Copilot instructions

1# 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