33 lines
2.3 KiB
Markdown
33 lines
2.3 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
- `flake.nix` / `flake.lock`: entry point for nix-darwin + Home Manager; defines overlays and the `macbook-pro` host.
|
||
- `modules/darwin/`: machine-level options (`system.nix`, `homebrew.nix`, `devtools.nix`). Extend these for hardware or OS-wide services only.
|
||
- `modules/home/rsydn/`: Home Manager profile composed of `programs/`, `shell/`, and `devtools/`. User-level bundles belong here, including AI tooling.
|
||
- `.cache/`: local build cache. Keep it out of Git.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `nix develop`: enter the flake’s dev shell (bundles `git`, `nixfmt-classic`, etc.).
|
||
- `nix fmt`: format all Nix sources using the flake’s formatter output.
|
||
- `XDG_CACHE_HOME=$PWD/.cache nix flake check`: type-checks modules, overlays, and packages without polluting global caches.
|
||
- `darwin-rebuild --dry-run --flake .#macbook-pro`: smoke-test activation scripts.
|
||
- `darwin-rebuild switch --flake .#macbook-pro`: apply the configuration once validation passes.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- Nix code: two-space indent, trailing commas, lower-kebab filenames (e.g., `shell/nushell.nix`).
|
||
- Custom options live under the `rsydn.*` namespace; keep logical groupings (`rsydn.aiTools`, `rsydn.devTools`).
|
||
- Run `nix fmt` before committing; avoid manual formatting tweaks that fight the formatter.
|
||
|
||
## Testing Guidelines
|
||
- `nix flake check` is mandatory before any PR; treat failures as regressions.
|
||
- For substantial module changes, add `darwin-rebuild --dry-run` output to the PR discussion.
|
||
- Pending automated tests should live beside the module they cover; name files after their option namespace (e.g., `rsydn-ai-tools.nix`).
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- Commits: short, imperative subjects (`replace zsh with nushell`), one logical change per commit.
|
||
- Include the exact validation commands run (`nix flake check`, dry-run output) in the PR body.
|
||
- Reference related issues or TODOs; attach logs/screenshots if they clarify UI-facing changes (e.g., Ghostty themes).
|
||
|
||
## AI Tooling & Shell Profile
|
||
- AI CLIs are toggled via `rsydn.aiTools`; adjust packages and enable flags there rather than invoking installers manually.
|
||
- Nushell is the default interactive shell. Any bootstrap scripts must be Nix-managed to avoid PATH drift.
|