40 lines
2.8 KiB
Markdown
40 lines
2.8 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
This repository is a Den-based NixOS flake. `flake.nix` evaluates `./modules` through `import-tree`, so normal `.nix` files under `modules/` are auto-imported.
|
|
|
|
- `modules/hosts/` contains host-specific composition and hardware data for `polaris` and `orion`.
|
|
- `modules/features/` contains aspects such as desktop, shell, services, and Neovim.
|
|
- `modules/profiles/` holds higher-level bundles such as `workstation.nix`.
|
|
- `modules/users/` defines user metadata and per-user behavior.
|
|
- `modules/secrets/` wires `sops-nix` and stores the encrypted `secrets.yaml`.
|
|
- `.agents/den/` is a local checkout of Den with source, docs, and examples.
|
|
|
|
Keep host files thin. Shared behavior belongs in `modules/features/` or `modules/profiles/`.
|
|
When Den behavior is unclear, read `.agents/den/docs/`, `.agents/den/modules/`, and `.agents/den/templates/ci/` before guessing.
|
|
|
|
## Build, Test, and Development Commands
|
|
Run commands from the repository root.
|
|
|
|
- `nix build .#nixosConfigurations.polaris.config.system.build.toplevel --show-trace`: evaluate and build the Polaris system.
|
|
- `nix build .#nixosConfigurations.orion.config.system.build.toplevel --show-trace`: evaluate and build the Orion system.
|
|
- `nixos-rebuild build --flake .#<host>`: use the standard rebuild path without activating it.
|
|
- `nix fmt`: format Nix files using the flake-provided formatter.
|
|
- `nix eval .#nixosConfigurations.<host>.config.<option>`: inspect a single option while iterating.
|
|
|
|
`nix flake check` is useful for evaluation, but this repo does not define an automated test suite.
|
|
|
|
## Coding Style & Naming Conventions
|
|
Use two-space indentation and standard Nix attrset formatting. Prefer small `let` bindings, lowerCamelCase local names, and lowercase file names such as `sops-password.nix`. Match the surrounding module style instead of reformatting unrelated code.
|
|
|
|
Prefer Den composition through `includes`; avoid host-specific duplication when a reusable aspect is clearer.
|
|
|
|
## Testing Guidelines
|
|
There are no first-party unit tests. Treat evaluation and build-only checks as the baseline. For scoped changes, run the matching `nix build` target first, or `nixos-rebuild build --flake .#<host>` when you want the standard rebuild path without activation. Activation and switching are manual steps and should not be performed by contributors or agents.
|
|
|
|
## Commit
|
|
Follow the history style: short imperative subjects, optionally with a conventional prefix, for example `refactor: restructure openssh config`. Keep each commit focused on one concern.
|
|
|
|
## Security & Configuration Tips
|
|
Never commit plaintext secrets. Add or update secrets through `modules/secrets/secrets.yaml` and reference them via `config.sops.secrets.<name>.path`. Be explicit about firewall, SSH, disk, or boot changes; those are the highest-risk edits here.
|