copilot-instructions.md in darkmatter/nixmac runs 1,326 words across 20 headings.
Home manager and nix-darwin that understands plain English
RustCovers
12 of the 20 section tags
In the order a file is read inHeadings
20 headings, in the order the file writes them
01Copilot Cloud Agent Instructions
02What this repository is
03Organization-wide agent guidance
04Repository layout
05Tech stack
06⚠️ macOS-only constraints for the cloud agent
07Building and testing (what works on Linux)
08Install JS/TS dependencies
09Rust unit tests (no macOS SDK required for most)
10TypeScript unit tests
11Storybook component tests (needs Playwright + Chromium installed)
12TS/JS lint
13Type-check frontend
14expands to: cargo test --manifest-path src-tauri/Cargo.toml && bun run test:unit
15Code conventions
16Rust
17TypeScript / React
18AI provider abstraction
19Key domain concepts
20Common pitfalls
Commands
11 commands this file writes down
Extracted from the file, verbatimbun install
cargo test --manifest-path apps/native/src-tauri/Cargo.toml
bun run check
npm install
yarn
bun run desktop:build
cargo build
bun run test:unit
bun run …
npm
biome.json
The file
.github/copilot-instructions.md
157 lines1# Copilot Cloud Agent Instructions
2
3## What this repository is
4
5**nixmac** is a native macOS application (Tauri 2 + Rust backend, React 19 frontend) that puts an AI agent in front of a [nix-darwin](https://github.com/LnL7/nix-darwin) configuration. Users describe what they want in plain English and the app edits their Nix config files, builds the system, and applies it — including one-click rollback via git history.
6
7## Organization-wide agent guidance
8
9- Organization-wide Copilot instructions are maintained in the `darkmatter/skills` repository.
10- When reviewing pull requests for this repository, also apply and follow the PR review guidelines documented there.
11
12## Repository layout
13
14```
15nixmac/
16├── apps/native/ # The main deliverable: Tauri desktop app
17│ ├── src/ # React/TypeScript frontend (Vite)
18│ │ ├── components/widget/ # UI widgets (badges, controls, feedback, history,
19│ │ │ # layout, notifications, overlays, promptinput,
20│ │ │ # settings, steps)
21│ │ ├── hooks/ # React hooks (use-evolve.ts, use-apply.ts, …)
22│ │ ├── ipc/ # Tauri IPC bindings (api.ts, sqlite.ts, types.ts)
23│ │ ├── stores/ # Zustand state (widget-store.ts)
24│ │ └── stories/ # Storybook stories
25│ └── src-tauri/ # Rust backend
26│ └── src/
27│ ├── main.rs # App entry point; declares top-level modules only
28│ ├── ai/ # ChatCompletionProvider trait + provider impls
29│ │ └── providers/ # openai.rs, ollama.rs, cli.rs
30│ ├── evolve/ # The AI evolution loop (tool use, file edits, git)
31│ │ ├── mod.rs # Core agent loop
32│ │ ├── tools.rs # Tool definitions (think/read_file/edit_file/…)
33│ │ ├── file_ops.rs # Path-safe file helpers (join_in_dir, resolve_*)
34│ │ ├── edit_nix_file.rs # Semantic Nix AST editing (rnix/rowan)
35│ │ └── …
36│ ├── rebuild/ # darwin-rebuild build/apply/rollback wrappers
37│ ├── summarize/ # AI summarization pipeline
38│ ├── commands/ # Tauri command handlers
39│ ├── shared_types/ # Types shared between Rust and TypeScript via specta
40│ ├── storage/ # Tauri store + keyring credential storage
41│ ├── git/ # Git operations (exec, changes_from_diff)
42│ ├── state/ # App state (build state, watcher, evolve state)
43│ └── …
44├── packages/ui/ # Shared Radix UI + Tailwind component library
45├── nix/ # devenv modules and Nix helper files
46└── ops/ # Release scripts (scripts/) and SOPS-encrypted secrets (secrets/)
47```
48
49## Tech stack
50
51| Layer | Technologies |
52| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
53| Rust backend | Tauri 2, tokio, serde/serde_json, anyhow, thiserror, rusqlite + rusqlite_migration, specta (type export), rnix + rowan (Nix AST), clap (CLI), async-openai, tiktoken-rs |
54| TypeScript frontend | React 19, Vite 7, Zustand, Radix UI, TailwindCSS 3, Monaco Editor, Shiki, Sonner, motion |
55| Package manager | **Bun** (1.3.x) — use `bun install`, never `npm install` or `yarn` |
56| Linting | **oxlint** (TS/JS), **biome** (formatting) |
57| Testing | Vitest (unit + Storybook browser tests), Playwright (e2e web), WebdriverIO (e2e Tauri app) |
58| Build system | `bun run desktop:build` (Tauri) wraps `cargo build` + Vite |
59| CI | GitHub Actions — `.github/workflows/build.yaml` runs on `macos-latest` |
60| Secrets | SOPS + age (`ops/secrets/secrets.sops.json`) — never commit plaintext secrets |
61
62## ⚠️ macOS-only constraints for the cloud agent
63
64nixmac targets macOS exclusively. The cloud agent runs on Ubuntu Linux; keep the following in mind:
65
66- **The app cannot be fully built on Linux.** `tauri build` / `bun run desktop:build` requires macOS (Cocoa APIs, Apple signing). Do not attempt a production build in the agent environment.
67- **Most Rust unit tests can run on Linux** via `cargo test --manifest-path apps/native/src-tauri/Cargo.toml`. Tests that invoke `darwin-rebuild` or macOS system APIs are guarded by `#[cfg(target_os = "macos")]` or the `e2e_mock_system` flag and will be skipped.
68- **Frontend-only tests work fine** — `bun run test:unit` (Vitest/jsdom) runs on Linux.
69- `devenv up` and `nix` commands require a Nix installation; do not rely on them in the agent.
70
71## Building and testing (what works on Linux)
72
73```bash
74# Install JS/TS dependencies
75bun install
76
77# Rust unit tests (no macOS SDK required for most)
78cargo test --manifest-path apps/native/src-tauri/Cargo.toml
79
80# TypeScript unit tests
81cd apps/native && bun run test:unit
82
83# Storybook component tests (needs Playwright + Chromium installed)
84cd apps/native && bun run test:storybook
85
86# TS/JS lint
87bun run check # runs oxlint across the whole repo
88cd apps/native && bun run lint
89
90# Type-check frontend
91cd apps/native && bun run build # tsc + vite build (no macOS deps)
92```
93
94The canonical "full desktop test" command is:
95
96```bash
97cd apps/native && bun run desktop:test
98# expands to: cargo test --manifest-path src-tauri/Cargo.toml && bun run test:unit
99```
100
101## Code conventions
102
103### Rust
104
105- Top-level module declarations belong in `main.rs` only. Leaf modules are declared by their parent `mod.rs` files so rust-analyzer resolves them via Cargo.
106- All public `serde` structs use `#[serde(rename_all = "camelCase")]` to match JS/TS consumers.
107- Prefer `anyhow::Result` for fallible functions; define domain errors with `thiserror`.
108- Unused items are **denied** (`[lints.rust] unused = "deny"`); add `#[allow(dead_code)]` sparingly and only when the item is intentionally reserved.
109- **Path safety**: always use `file_ops::join_in_dir` or `file_ops::resolve_*_path_in_dir*` when constructing paths inside the user's config dir. Never concatenate strings or use `Path::new(user_input)` directly — this prevents path-traversal out of `config_dir`.
110- **External commands in the GUI app**: set `PATH` via `nix::get_nix_path()` (includes `/usr/local/bin` and `/opt/homebrew/bin`) so commands work when launched from Finder.
111- **Rust tests that mutate environment variables**: use `crate::test_support::e2e_env_lock()` and `EnvVarRestore::capture(keys)` to serialize env state and restore it after the test.
112- **Debug logs**: written under `dirs::data_local_dir()/nixmac/logs`. darwin-rebuild logs go to `~/Library/Logs/nixmac/`.
113
114### TypeScript / React
115
116- Use **Bun** for all package operations (`bun install`, `bun run …`).
117- Components live under `apps/native/src/components/widget/{subfolder}/` — subfolders include `badges`, `controls`, `feedback`, `history`, `layout`, `notifications`, `overlays`, `promptinput`, `settings`, `steps`.
118- The shared UI library is at `packages/ui/src`; import as `@nixmac/ui` or `@/components/ui`.
119- State management uses **Zustand** (`apps/native/src/stores/widget-store.ts`).
120- IPC with the Rust backend uses Tauri's `invoke` wrapped in `apps/native/src/ipc/api.ts`.
121- TypeScript types shared with Rust are generated by **specta** (`specta-typescript`); regenerate with the specta export command after changing `#[specta::Type]`-annotated structs.
122- Linting: **oxlint** + **biome** (extends `ultracite/core` + `ultracite/react`). Run `bun run check` from repo root.
123
124### AI provider abstraction
125
126The `ChatCompletionProvider` trait (`apps/native/src-tauri/src/ai/providers/mod.rs`) has two core methods:
127
128```rust
129async fn completion(&self, system_prompt, user_prompt, max_tokens, context_window_tokens, temperature, request_id) -> Result<(String, TokenUsage)>
130async fn json_completion(&self, ...) -> Result<(String, TokenUsage)>
131```
132
133- `max_tokens` — maximum output tokens (all providers).
134- `context_window_tokens` — optional override for the total context window. For **Ollama** this maps to `num_ctx`; OpenAI-compatible providers ignore it.
135- Supported providers: `openrouter` (default), `openai`, `ollama`, `openai_compatible`, `claude` (CLI), `codex` (CLI), `opencode` (CLI).
136
137## Key domain concepts
138
139| Concept | Description |
140| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
141| **Evolution** | One AI-driven config change cycle: prompt → tool use → file edits → `darwin-rebuild build` → `darwin-rebuild switch` → git commit |
142| **EvolutionState** | Enum: `Pending`, `Running`, `Complete`, `Failed`, `Cancelled` |
143| **SemanticFileEdit** | Structured Nix AST edit (`Add`, `Remove`, `Set`, `SetAttrs`) applied by `edit_nix_file.rs` via rnix/rowan |
144| **Tools available to the agent** | `think`, `read_file`, `write_file`, `edit_file`, `edit_nix_file`, `list_files`, `search_packages`, `search_docs`, `search_code`, `build_check`, `ask_user`, `ensure_secret`, `done` |
145| **Config dir** | The user's nix-darwin flake repo (default `~/.darwin`), always accessed through `file_ops` helpers |
146| **Summarization pipeline** | Batched AI calls that generate commit messages and UI labels; token-budgeted via `tiktoken-rs` |
147
148## Common pitfalls
149
1501. **Do not run `bun run desktop:build` or `tauri build`** in the agent — they require macOS.
1511. **Do not modify `ops/secrets/`** without sops; the files are encrypted with age.
1521. **Do not use `npm` or `yarn`** — this project uses Bun exclusively.
1531. **Do not add `unused` imports** — they are compile errors (`unused = "deny"`).
1541. When adding a new Rust source file, declare it with `mod` in its **parent `mod.rs`**, not in `main.rs` (unless it is a new top-level domain module).
1551. When adding or changing a Tauri command, update the corresponding TypeScript types in `apps/native/src/ipc/types.ts` (or regenerate via specta).
1561. The `biome.json` `files.includes` list is explicit — new `apps/**` and `packages/**` files are covered automatically, but files outside those paths need to be added manually.
157
The rest of the repository
darkmatter/nixmac ships 5 other instruction files
.cursor/rules/native-env.mdc.cursor/rules/native-errors.mdc.cursor/rules/native-state-package.mdc.cursor/rules/native-config-tiers.mdc.cursor/rules/native-orpc.mdc
A row that is not a link is a file this repository ships that this app did not freeze a sheet for. It is listed because the corpus knows it exists, and it is not linked because there is nothing here to open.
This listing
Whoever runs darkmatter/nixmac can claim it
This is yours? Claim this config and we will write to you when the measurement moves. The check is one token placed where only you can place it, and there is no account and no password.