refactor: migrate nix-darwin config to a flake-parts dendritic layout

README.md

@@ -7,9 +7,9 @@ Declarative macOS setup with `nix-darwin`, `home-manager`, `nix-homebrew`, and
 
 ## What This Repo Manages
 
-- System-level macOS configuration in `hosts/`
-- User-level tooling, shell, terminal, and editor config in `home/`
-- Declarative Homebrew taps/apps/casks in `hosts/apps.nix`
+- Flake orchestration and host assembly in `modules/flake/`
+- Auto-discovered Darwin and Home Manager aspects in `modules/aspects/`
+- Auto-discovered host declarations in `hosts/`
 - Encrypted secrets via SOPS (`secrets/` + `.sops.yaml`)
 
 ## Prerequisites
@@ -25,16 +25,15 @@ Declarative macOS setup with `nix-darwin`, `home-manager`, `nix-homebrew`, and
 
 ## Repository Layout
 
-- `flake.nix`: flake inputs/outputs and `darwinConfigurations`
+- `flake.nix`: `flake-parts` entrypoint and flake inputs
 - `Justfile`: day-to-day commands (`darwin`, `darwin-debug`, `fmt`, `up`, `gc`)
-- `hosts/`: system modules
-  - `default.nix`
-  - `nix-core.nix`
-  - `system.nix`
-  - `apps.nix`
-  - `host-users.nix`
-- `home/`: Home Manager modules (`git.nix`, `zsh.nix`, `nvf/`, `aerospace.nix`,
-  etc.)
+- `modules/flake/`: repo options, Darwin assembly, and shared context modules
+- `modules/aspects/`: auto-discovered aspect entry modules such as `base`,
+  `homebrew`, `shell`, `editor`, and `desktop`
+- `modules/aspects/_*/`: ignored internal implementation trees that back the
+  public aspect entry modules
+- `hosts/`: auto-discovered host declarations that register `system` and a flat
+  `features` list
 - `secrets/`: encrypted secret files (`poby.yaml`)
 
 ## Common Commands
@@ -56,11 +55,14 @@ just fmt .
 just up
 
 # Update one flake input
-just upp nixpkgs-darwin
+just upp nixpkgs
 
 # Validate build without switching (example host: fenrir)
 nix build .#darwinConfigurations.fenrir.system --extra-experimental-features 'nix-command flakes'
 
+# Validate without realizing a full build
+nix build .#darwinConfigurations.fenrir.system --dry-run --extra-experimental-features 'nix-command flakes'
+
 # Inspect profile history / cleanup old generations
 just history
 just clean
@@ -69,19 +71,36 @@ just gc
 
 ## Configuration Notes
 
-- `flake.nix` currently defines one `darwinConfigurations` entry from
-  `hostname`, and imports system modules through `./hosts`.
-- `home/default.nix` composes user modules (shell, git, nvf, aerospace, sops,
-  ssh).
-- Aerospace multi-monitor workspace assignment lives in `home/aerospace.nix`.
-- Homebrew-first app management (for frequently updated apps) is in
-  `hosts/apps.nix`.
+- `flake.nix` now uses `flake-parts`, keeps `./modules/flake` explicit, and
+  auto-discovers `./modules/aspects` and `./hosts` through `import-tree`.
+- `hosts/fenrir.nix` is the current host declaration and maps `fenrir` to one
+  flat feature list.
+- `modules/flake/darwin-configurations.nix` assembles each host’s
+  `darwinConfigurations.<host>` output and embeds Home Manager for user `poby`.
+- `modules/aspects/` is the feature vocabulary for hosts. The current feature
+  set is `base`, `nix-core`, `system-packages`, `homebrew`,
+  `macos-defaults`, `activation`, `fonts`, `sudo-auth`, `shell`, `cli-tools`,
+  `git`, `ssh`, `secrets`, `terminal`, `editor`, `desktop`, and `fenrir`.
+- The `cli-tools` aspect owns the CLI user tool set, including `zoxide`.
+- `modules/aspects/_*/` contains implementation files that are intentionally not
+  auto-loaded. `import-tree` skips paths containing `/_`, which is the repo’s
+  convention for internal helpers and subtrees like the NVF source.
+- Home Manager is Darwin-integrated only in this phase; no standalone
+  `homeConfigurations` output is exposed.
+
+## Adding A Host
+
+- Create `hosts/<hostname>.nix`.
+- Register `repo.hosts.<hostname>.system`.
+- Register `repo.hosts.<hostname>.features` with the desired aspect names.
+- Add any host-specific behavior as a new aspect in `modules/aspects/` instead
+  of modifying shared features.
 
 ## Secrets
 
 - Keep secrets encrypted in `secrets/*.yaml`.
 - `.sops.yaml` enforces encryption rules for `secrets/.*\.yaml`.
-- Home Manager reads from `secrets/poby.yaml` via `home/sops.nix`:
+- Home Manager reads from `secrets/poby.yaml` via the `secrets` aspect:
   - `github_ssh_key`
   - `github_cli_token`
 
@@ -89,10 +108,8 @@ just gc
 
 - Use `just darwin-debug <hostname>` for detailed evaluation/build output.
 - If evaluation fails for a host, verify it exists under `darwinConfigurations`.
+- Dry-run evaluation with
+  `nix build .#darwinConfigurations.<host>.system --dry-run` before a full
+  switch when you only want to confirm the dependency graph.
 - If settings look stale after a successful build, run switch again and verify
   active hostname/config values.
-
-## Milestone
-
-- [ ] `multi-host implementation`
-- [ ] Dentritic Pattern - using flake-parts