|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +Nix flake managing macOS (nix-darwin) and Home Manager configs. Built on |
| 4 | +`flake-parts` + `haumea` (directory-tree-as-attrset auto-loading). Pinned to the |
| 5 | +`26.05` release channels. |
| 6 | + |
| 7 | +## Commands |
| 8 | + |
| 9 | +All workflows go through `just` (see `Justfile`). Run inside `nix develop` (auto |
| 10 | +via `.envrc`/direnv). |
| 11 | + |
| 12 | +- `just build` — build current host (`nh darwin build`) |
| 13 | +- `just build-system <name>` — build a named host (`eMac`, `mercury`) |
| 14 | +- `just build-home <name>` — build a home config (`ethan`, `et`) |
| 15 | +- `just switch` — activate current host |
| 16 | +- `just check` — `nix flake check --impure --all-systems` (note `--impure` is required) |
| 17 | +- `just format` / `treefmt` — format everything |
| 18 | +- `just repl` — Nix REPL with this flake loaded |
| 19 | +- `just render-workflows` — regenerate `.github/workflows/*.yml` (see Gotchas) |
| 20 | + |
| 21 | +There is no test suite; `just check` + a successful build is the verification. |
| 22 | + |
| 23 | +## Architecture |
| 24 | + |
| 25 | +Everything is wired through `flake.nix`'s `imports`. Three building blocks: |
| 26 | + |
| 27 | +1. **Modules** (`modules/{darwin,home}/src/`, `modules/profiles/`) — auto-loaded |
| 28 | + by `haumea` into `flake.darwinModules` / `flake.homeModules` and |
| 29 | + `flake.profiles.{darwin,home}`. A file's directory path becomes its attr path |
| 30 | + (e.g. `profiles/home/git/common.nix` → `profiles.home.git.common`). Adding a |
| 31 | + file is enough to register it; no central import list. |
| 32 | +2. **Suites** (`modules/suites/{system,home}.nix`) — named bundles of profiles |
| 33 | + (`base`, `development`, `work`, `identity`, `minimal`, `fonts`). This is where |
| 34 | + you opt a profile into the default set. Defined as plain lists referencing |
| 35 | + `profiles`. |
| 36 | +3. **Configurations** — `hosts/` defines `darwinConfigurations`, `users/` defines |
| 37 | + `homeConfigurations`, both built via helpers in `lib/src/{darwin,hm}.nix` |
| 38 | + (`mkDarwinConfiguration` / `mkHomeManagerConfiguration`). |
| 39 | + |
| 40 | +Data flow: profile files are pure HM/darwin modules → grouped into suites → |
| 41 | +hosts/users import suites + extra profiles. Hosts inject the standalone home |
| 42 | +configs via `modules/profiles/system/users/*.nix` (e.g. `home-manager.users.et = |
| 43 | +import ../../../../users/et/home.nix`), so a user's `home.nix` is shared between |
| 44 | +the standalone `homeConfigurations` and the darwin host. |
| 45 | + |
| 46 | +`specialArgs`/`extraSpecialArgs` expose `flake`, `inputs`, `secrets`, `suites`, |
| 47 | +`profiles` to every module — that's why profiles take `{ suites, profiles, ... }`. |
| 48 | + |
| 49 | +## Conventions |
| 50 | + |
| 51 | +- **nixfmt-classic** style, 2-space indent (`.editorconfig`); Justfile uses |
| 52 | + 4-space. `treefmt` runs deadnix + statix + nixfmt + prettier + actionlint. |
| 53 | +- Profiles are thin: one tool/concern per file, typically `programs.<x>.enable = |
| 54 | + true` plus config. Match neighbors in `modules/profiles/home/`. |
| 55 | +- Custom HM modules with full options live in `modules/home/src/programs/` |
| 56 | + (see `rippkgs/default.nix` for the option pattern). |
| 57 | +- Custom options namespaced under `tilde.*` (`modules/darwin/src/tilde/options.nix`). |
| 58 | +- Packages defined in `modules/packages/` via `callPackage`, exposed through both |
| 59 | + `packages` and the overlay (`modules/overlays/default.nix`, `easyOverlay`). |
| 60 | +- nixpkgs is overlaid (`self.overlays.default`, pragmatapro, emacs-overlay) with |
| 61 | + `allowUnfree = true` in `flake.nix` `perSystem`. |
| 62 | + |
| 63 | +## Gotchas |
| 64 | + |
| 65 | +- **`--impure` is required** for `flake check` and the devShell build (secrets + |
| 66 | + `tilde-secrets` private input). |
| 67 | +- **Secrets** use sops-nix; the `tilde-secrets` / `pragmatapro` inputs are |
| 68 | + private SSH git repos. Builds need SSH agent access. Edit secrets via |
| 69 | + `just edit-secret <file>`; after key changes run `just update-secret-files`. |
| 70 | +- **GitHub workflows are generated** from `modules/development/ci.nix` via |
| 71 | + `actions-nix`. Never hand-edit `.github/workflows/*.yml` — change `ci.nix` and |
| 72 | + run `just render-workflows`. |
| 73 | +- `secrets.json` / `secrets.yml` are excluded from prettier; don't reformat them. |
| 74 | +- Hosts are all `aarch64-darwin`; flake `systems` also lists `x86_64-linux` for |
| 75 | + the linux builder. |
| 76 | +- Binary caches (cachix `tilde`, attic at `cache.e10.camp`) are configured in |
| 77 | + `nixConfig`; push results with `just push-result-to-cache`. |
0 commit comments