docs(plan): correct Task 2 scope — specialArgs needed for self in imports

The original plan claimed no flake-level changes were needed because
machines/configuration.nix:21 already passes `_module.args.self = self;`.
That's only true for `config`-time evaluation; `imports` are collected
before `config` is available, so referencing `self` in `imports` causes
infinite recursion. Fix: promote `self` to `specialArgs` on each
nixosSystem call. The implementer of Task 2 caught this on first
dispatch.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
marthsincemelee
2026-05-10 15:52:20 +02:00
parent 9ff3603d40
commit 311e358d88
@@ -21,9 +21,12 @@
| Action | File | Responsibility | | Action | File | Responsibility |
|--------|------|----------------| |--------|------|----------------|
| Modify | `modules/environments/home-assistant/default.nix` | Import unstable OTBR module; enable OTBR for the ZBT-2; add `otbr` + `thread` HA components | | Modify | `modules/environments/home-assistant/default.nix` | Import unstable OTBR module; enable OTBR for the ZBT-2; add `otbr` + `thread` HA components |
| Create (auto) | _(no new files)_ | All work fits in the one module | | Modify | `machines/configuration.nix` | Pass `self` via `specialArgs` so it's available during NixOS module **imports** evaluation (not just config) |
| Create (auto) | _(no new files)_ | All work fits in the two modules |
The `git revert` of `e8d09f4` automatically un-modifies the same file (drops `"zha"` and the `dialout` line). No host-level (`machines/jupiter/`) changes; no flake-level changes (the existing `_module.args.self = self;` in `machines/configuration.nix:21` already exposes `self.inputs.nixpkgs-unstable` to every module). The `git revert` of `e8d09f4` automatically un-modifies the home-assistant module (drops `"zha"` and the `dialout` line). No host-level (`machines/jupiter/`) changes.
**Why the flake-level edit is needed:** the existing `_module.args.self = self;` in `machines/configuration.nix:21` makes `self` available in module bodies (option definitions, `config` blocks). It does **not** make `self` available during `imports` evaluation — `_module.args` is resolved from `config`, but `imports` are collected **before** `config` is evaluated, so `self` in `imports` causes an infinite recursion error. Promoting `self` to `specialArgs` short-circuits that and is the conventional fix.
--- ---
@@ -95,6 +98,7 @@ Expected: revert commit on top of `dbeda27` on top of `e8d09f4`.
This task gets the module into scope so options become available, but leaves `services.openthread-border-router.enable = false` (the default). The point is to confirm the import path works before adding device-specific config. This task gets the module into scope so options become available, but leaves `services.openthread-border-router.enable = false` (the default). The point is to confirm the import path works before adding device-specific config.
**Files:** **Files:**
- Modify: `machines/configuration.nix` (add `specialArgs = { inherit self; };` to each `nixosSystem` call)
- Modify: `modules/environments/home-assistant/default.nix` - Modify: `modules/environments/home-assistant/default.nix`
- [ ] **Step 1: Write the failing eval check** - [ ] **Step 1: Write the failing eval check**
@@ -107,6 +111,50 @@ nix eval --json .#nixosConfigurations.jupiter.options.services.openthread-border
Expected: error containing `attribute 'openthread-border-router' missing` or similar — the option doesn't exist yet because the module isn't imported. Expected: error containing `attribute 'openthread-border-router' missing` or similar — the option doesn't exist yet because the module isn't imported.
- [ ] **Step 1a: Promote `self` to `specialArgs` in `machines/configuration.nix`**
`self` must be reachable during `imports` evaluation (not just `config` evaluation). The existing `_module.args.self = self;` only covers `config`-time access. Edit each `nixosSystem` call (`jupiter` and `mibook`) to add `specialArgs`.
Current shape (lines 5056 and 5763):
```nix
jupiter = nixosSystem {
system = "x86_64-linux";
modules = defaultModules ++ [
# nixos-hardware.nixosModules.bmax-b7-power
./jupiter/configuration.nix
];
};
mibook = nixosSystem {
system = "x86_64-linux";
modules = defaultModules ++ [
# nixos-hardware.nixosModules.mibook
./mibook/configuration.nix
];
};
```
Add `specialArgs = { inherit self; };` to each:
```nix
jupiter = nixosSystem {
system = "x86_64-linux";
specialArgs = { inherit self; };
modules = defaultModules ++ [
# nixos-hardware.nixosModules.bmax-b7-power
./jupiter/configuration.nix
];
};
mibook = nixosSystem {
system = "x86_64-linux";
specialArgs = { inherit self; };
modules = defaultModules ++ [
# nixos-hardware.nixosModules.mibook
./mibook/configuration.nix
];
};
```
- [ ] **Step 2: Add `self` to the module's argument list and add the `imports` block** - [ ] **Step 2: Add `self` to the module's argument list and add the `imports` block**
Current header (`modules/environments/home-assistant/default.nix` lines 111): Current header (`modules/environments/home-assistant/default.nix` lines 111):
@@ -180,7 +228,7 @@ Expected: a `/nix/store/...drv` path. Pre-existing trace warnings (the `*.servic
- [ ] **Step 6: Commit** - [ ] **Step 6: Commit**
```bash ```bash
git add modules/environments/home-assistant/default.nix git add machines/configuration.nix modules/environments/home-assistant/default.nix
git commit -m "$(cat <<'EOF' git commit -m "$(cat <<'EOF'
feat(home-assistant): import openthread-border-router module from unstable feat(home-assistant): import openthread-border-router module from unstable
@@ -188,6 +236,10 @@ Pulls the services.openthread-border-router NixOS module directly from
nixpkgs-unstable since it isn't in 25.11 yet. Service stays disabled nixpkgs-unstable since it isn't in 25.11 yet. Service stays disabled
in this commit; configuration follows. in this commit; configuration follows.
Also promotes `self` from `_module.args` to `specialArgs` in
machines/configuration.nix, since `imports` are evaluated before
`config` and so can't reach `_module.args.self`.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
EOF EOF
)" )"