On Unix, craft-ai-native creates its private files with mode 0600. On Windows they took their folder's access list, which is not private in a folder that CRAFT_AI_DIR names outside %LOCALAPPDATA%. - Private files and the folders this crate creates get an owner-only access list (the user's SID and SYSTEM) in the call that creates them, so no other account can open them in between. - Creation does not follow a link planted at the name, and handles paths past 260 characters. - A leftover temp file is removed and created again, never reused. This also fixes the Unix case. - The Win32 calls live in crates/ai-native/src/owner_only/win_acl.rs, the workspace's one named unsafe exception. The workspace lint moves from forbid to deny, and tests/unsafe_exception.rs fails if unsafe is allowed anywhere else. - Volumes without access lists (FAT, exFAT) still save, without one, as documented.
3.2 KiB
Contributing
Thanks for helping with the Craft AI layer. README.md says what
the crates are for and docs/LAYOUT.md says what lives where. Read both before a larger change.
Propose an integration
For a vetted built-in model, connection, engine or workflow suggestion, start with Propose an AI integration. It creates a checked suggestion and an issue draft without changing anyone's custom setup. The adoption guides cover the subsequent implementation.
Branches and pull requests
Changes reach main through a pull request. Nothing is pushed to it directly.
- Branch off
main. Keep the branch short-lived and focused on one change. - Open a pull request into
main. Explain what changed and why, and how you checked it. - Resolve every review conversation before merging.
- Merge by squash or rebase. History stays linear, so merge commits are off.
- The branch is deleted after merge. Delete your local copy too.
Review that matters happens at the boundaries: the shared contract goes to craft-libs, and each app
reviews its own adoption in its own repository. A change here should not quietly widen that contract.
Commit messages
Use a conventional prefix with the crate in brackets where one crate is affected:
feat(ai-client): resolve the selected local backend and model
fix(ai-openai): stop retrying on a 4xx
docs: add LAYOUT.md
Rules for every change
- Test first. Write the failing test, then the code. Ship tests with new logic, especially pure functions.
- Safety rules get a deliberate-bug check. Break the rule on purpose and confirm a test fails. No
surviving mutant is ignored. The harness and its case lists are in
tools/mutation/. - Small files. Under 500 lines each, 700 at the very most. A file near the limit is doing too much, so split it by responsibility.
- Keep
ai-coresmall. It uses serde only, with no I/O and no async runtime, and it must compile for wasm. Desktop-only code belongs inai-native. - No unsafe code. The workspace denies it. The one named exception is
crates/ai-native/src/owner_only/win_acl.rs: the Windows calls that make private files owner-only, which std cannot do.crates/ai-native/tests/unsafe_exception.rsfails ifunsafeis allowed anywhere else. - Time goes through
chrono(workspace dependency). Never hand-roll UTC/calendar conversion (days-to-date algorithms, leap-year math); a crate owns only its output format string. - No secrets in the repo or in logs. Keys go through the secret stores in
ai-native. - Do not claim more than was run. Say plainly what was tested live, what was tested against a scripted server, and what is only proposed.
Building and testing
Builds are heavy, so keep them targeted to the crate you changed. CI runs the whole workspace.
cargo test -p <crate> -j 8
cargo clippy -p <crate> -j 8
Tests that touch the real OS keychain are #[ignore]d and run on request, for example
cargo test -p craft-ai-native -- --ignored keychain_round_trip. egui widgets need Rust 1.95.
Licence
By contributing you agree that your work is licensed under MIT or Apache-2.0, at the option of the
user, matching LICENSE-MIT and LICENSE-APACHE.