# Repository Guidelines

## Project Structure & Module Organization

This repository is a declarative macOS setup built with Nix flakes, `flake-parts`,
and a dendritic aspect layout.

- `flake.nix` and `flake.lock`: flake entrypoint and pinned inputs.
- `modules/flake/`: flake assembly, repo options, shared context modules, and
  `darwinConfigurations` generation.
- `modules/aspects/`: public aspect entry modules auto-discovered with
  `import-tree`. Each aspect may expose `flake.modules.darwin.<feature>` and/or
  `repo.homeModules.<feature>`.
- `modules/aspects/_*/`: private implementation trees intentionally excluded
  from `import-tree`. Import these manually from the owning aspect to keep each
  feature plug-and-play and in control of its own composition surface.
- `hosts/`: auto-discovered host declarations that register
  `repo.hosts.<hostname>.system` and a flat `features` list.
- `secrets/` and `.sops.yaml`: encrypted SOPS files and path rules.
- `Justfile`: day-to-day contributor commands.

Prefer adding a new focused aspect in `modules/aspects/` and keeping host files
thin. Put reusable internals under a sibling `_/` tree and wire them in
explicitly from the public aspect entry module.

## Build, Test, and Development Commands

Use `just` as the primary interface:

- `just darwin <hostname>`: build and switch to the current host (ex: `fenrir`).
- `just darwin-debug <hostname>`: same as above with verbose trace output.
- `just fmt .`: format Nix files from the repository root via `nix fmt`
  (Alejandra).
- `just up`: update all flake inputs.
- `just upp <input>`: update one input (example: `just upp nixpkgs`).
- `just history`, `just clean`, `just gc`: inspect and prune Nix
  generations/store.

For validation without switching, run:
`nix build .#darwinConfigurations.fenrir.system --extra-experimental-features 'nix-command flakes'`.

For dependency-graph validation without realizing a full build, run:
`nix build .#darwinConfigurations.fenrir.system --dry-run --extra-experimental-features 'nix-command flakes'`.

## Coding Style & Naming Conventions

- Use 2-space indentation in `.nix` files and keep attribute sets readable.
- Run `just fmt .` before committing; formatter is defined in `flake.nix`
  (`alejandra`).
- Name aspect and helper files in lowercase kebab-case.
- Keep public aspect filenames aligned with the feature names referenced from
  `repo.hosts.<hostname>.features`.
- Keep host files declarative and small: they should select features, not carry
  large implementation blocks.
- Use `imports` inside private `_*/` trees to compose internals, but expose the
  aspect itself through one public entry module in `modules/aspects/`.

## Testing Guidelines

There is no dedicated unit-test suite in this repo. Treat evaluation/build as
the test gate:

- Run `just fmt .`.
- Run `nix build .#darwinConfigurations.fenrir.system`.
- Use `nix build .#darwinConfigurations.fenrir.system --dry-run` for a quick
  validation pass when you only need evaluation and dependency resolution.
- Use `just darwin-debug <hostname>` when diagnosing evaluation/runtime issues.

Document manual verification for user-facing changes (shell, terminal, window
manager, app defaults, Homebrew behavior).

## Commit & Pull Request Guidelines

Commit history follows Conventional Commit style: `feat:`, `fix:`, `refactor:`,
`style:`.

- Keep subject lines imperative and concise.
- Scope each commit to one logical change.
- In PRs, include: summary, affected modules/paths, command output used for
  validation, and any relevant screenshots for UI changes (for example
  WezTerm/AeroSpace behavior).

## Security & Configuration Tips

- Never commit plaintext secrets.
- Store secrets only in `secrets/*.yaml` and manage keys/rules in `.sops.yaml`.
- `.sops.yaml` currently matches `secrets/.*\.yaml$`; keep new secret files
  within that pattern or update the rule before committing.
- If adding new secret-backed modules, continue reading from encrypted files via
  the `secrets` aspect rather than hardcoding credentials into aspect modules.