Install fleet-diff on the host PATH #38

Merged

vnprc merged 1 commit from agent/fleet-diff-host-path into master

2026-09-04 00:44:21 +01:00

allod-agent commented

2026-09-03 23:28:14 +01:00

Member

Do not merge this yet, and expect nothing to change on the machine until you do. It adds fleet-diff to the host's installed tools, next to flake-status and flake-update-cascade, but the script it installs does not exist in the tools repo the host builds from, so merging today would break the next host rebuild. It becomes safe once allod/tools PR 136 merges and allod/archetypes advances its allod-tools lock; nothing here advances a lock. When that has happened, one host rebuild puts fleet-diff on your PATH and changes nothing else — I built the other four workspace tools before and after and they come out at byte-identical store paths. I did not rebuild the host, because that is a command for a human at the terminal. What proves the wiring is that I built fleet-diff itself, against a copy of the tools branch that carries the script, and ran the result. If it turns out wrong, revert the single commit and rebuild; nothing else in this repo reads it.

What changed

nix/home.nix, one file, 15 insertions and 2 deletions:

Lines 65-71: a new workspaceTool entry for fleet-diff, path = "flake/fleet-diff", runtimeInputs = [ pkgs.jq pkgs.git ], placed directly after flake-update-cascade so the three flake/ tools stay together. nix is deliberately not a runtime input: writeShellApplication prefixes rather than replaces PATH, and flake-update-cascade already calls nix fourteen times with the same set.
Lines 12-23: workspaceTool gains a useWorkspaceLib argument, default true, that controls whether lib/workspace.sh is prepended to the script. This is not cosmetic — see below.

Why the helper needed an argument

The issue's sketch, wired verbatim, does not build. workspaceTool prepends lib/workspace.sh to every script, and fleet-diff is the first tool that calls none of its four helpers, so shellcheck reports SC2329 ("this function is never invoked") four times and writeShellApplication fails the build on it. I reproduced that failure before changing anything and have the log. The four existing tools each call at least one helper, which is why the problem has not surfaced until now.

useWorkspaceLib = false for fleet-diff is the narrow fix: the tool genuinely does not need the library, and the alternative — adding SC2329 to the shared excludeShellChecks — would silence a real check for every tool here. The coupling to watch is that if fleet-diff later starts calling a workspace_* helper, this flag has to flip back; that fails loudly at build time as an undefined command, not silently.

Risk

R2 for the repo, higher for timing. The composition change is additive and touches no existing package, but the shared workspaceTool helper is edited, so all five tools are in scope for review rather than just the new one. I measured that directly: flake-status, flake-update-cascade, work-diff, and pull-all produce the same four .drv paths before and after the helper change, so the default path through workspaceTool is provably unchanged.

The real risk is merge order. Merged before allod/tools PR 136 lands and the lock advances, this makes the host un-rebuildable: builtins.readFile on a missing flake/fleet-diff is an evaluation error, so the failure is immediate and total rather than partial. That is loud, not silent, and reverting one commit restores the previous state.

Validation

Everything below ran against a read-only export of allod/tools at origin/agent/fleet-diff (commit 1608d3f), extracted with git archive into a scratch directory and passed as the allod-tools argument. Nexus does not pin allod-tools itself — allod/archetypes does, at 9d029a7, and hands it to nexus.homeModules.host through home-manager.extraSpecialArgs — so this stands in for the lock advance that has not happened.

nix-instantiate --parse nix/home.nix — passes.
Evaluated nix/home.nix directly as a function, with pkgs from this flake's own locked nixpkgs, and listed home.packages: nexus-provisioning-scripts, forge-0.1.0, work-diff, flake-status, flake-update-cascade, fleet-diff, pull-all, allod-0.1.0. The new entry is present and in the intended position.
Built the fleet-diff derivation. Before the useWorkspaceLib change it failed with four SC2329 findings on workspace_is_repo_root, workspace_collect_repos, workspace_collect_worktrees, and workspace_repo_default_branch. After the change it builds, and the built bin/fleet-diff --help exits 0 and prints the usage block.
Built flake-status, flake-update-cascade, work-diff, and pull-all both before and after the helper change. All four build, and all four .drv paths are identical across the two runs: ppqh5g5y…-flake-status.drv, 3dpfvzj6…-flake-update-cascade.drv, g11k03ib…-work-diff.drv, z1gpkb1d…-pull-all.drv.
nix build .#checks.x86_64-linux.no-hardcoded-arch — passes.

Not run, and why:

No host rebuild, and no nixos-rebuild of any kind. nexus is the host composition and host commands need a human at the terminal.
No full nix flake check. Its other checks (provisioning-contract, host-provisioning-env) cover scripts and modules this change does not touch, and provisioning-contract is the expensive one.
No flake.lock update in this repo, by instruction and because this repo has no allod-tools node to update.
The fleet-diff build above proves the composed script passes shellcheck and runs; it does not exercise the tool against a real fleet. allod/tools PR 136 carries that suite (83 assertions).

Linking

Refs, not Closes, per the multi-repo rule in git-workflow.md: this repo cannot put the tool on the PATH by itself, so the issue should close on the step that finishes the chain — the allod-tools lock advance in allod/archetypes — not here.

Refs allod/nexus#37

Depends on: allod/tools#136

Do not merge this yet, and expect nothing to change on the machine until you do. It adds `fleet-diff` to the host's installed tools, next to `flake-status` and `flake-update-cascade`, but the script it installs does not exist in the tools repo the host builds from, so merging today would break the next host rebuild. It becomes safe once allod/tools PR 136 merges and allod/archetypes advances its `allod-tools` lock; nothing here advances a lock. When that has happened, one host rebuild puts `fleet-diff` on your PATH and changes nothing else — I built the other four workspace tools before and after and they come out at byte-identical store paths. I did not rebuild the host, because that is a command for a human at the terminal. What proves the wiring is that I built `fleet-diff` itself, against a copy of the tools branch that carries the script, and ran the result. If it turns out wrong, revert the single commit and rebuild; nothing else in this repo reads it. ## What changed `nix/home.nix`, one file, 15 insertions and 2 deletions: - Lines 65-71: a new `workspaceTool` entry for `fleet-diff`, `path = "flake/fleet-diff"`, `runtimeInputs = [ pkgs.jq pkgs.git ]`, placed directly after `flake-update-cascade` so the three `flake/` tools stay together. `nix` is deliberately not a runtime input: `writeShellApplication` prefixes rather than replaces `PATH`, and `flake-update-cascade` already calls `nix` fourteen times with the same set. - Lines 12-23: `workspaceTool` gains a `useWorkspaceLib` argument, default `true`, that controls whether `lib/workspace.sh` is prepended to the script. This is not cosmetic — see below. ## Why the helper needed an argument The issue's sketch, wired verbatim, does not build. `workspaceTool` prepends `lib/workspace.sh` to every script, and `fleet-diff` is the first tool that calls none of its four helpers, so shellcheck reports `SC2329` ("this function is never invoked") four times and `writeShellApplication` fails the build on it. I reproduced that failure before changing anything and have the log. The four existing tools each call at least one helper, which is why the problem has not surfaced until now. `useWorkspaceLib = false` for `fleet-diff` is the narrow fix: the tool genuinely does not need the library, and the alternative — adding `SC2329` to the shared `excludeShellChecks` — would silence a real check for every tool here. The coupling to watch is that if `fleet-diff` later starts calling a `workspace_*` helper, this flag has to flip back; that fails loudly at build time as an undefined command, not silently. ## Risk R2 for the repo, higher for timing. The composition change is additive and touches no existing package, but the shared `workspaceTool` helper is edited, so all five tools are in scope for review rather than just the new one. I measured that directly: `flake-status`, `flake-update-cascade`, `work-diff`, and `pull-all` produce the same four `.drv` paths before and after the helper change, so the default path through `workspaceTool` is provably unchanged. The real risk is merge order. Merged before allod/tools PR 136 lands and the lock advances, this makes the host un-rebuildable: `builtins.readFile` on a missing `flake/fleet-diff` is an evaluation error, so the failure is immediate and total rather than partial. That is loud, not silent, and reverting one commit restores the previous state. ## Validation Everything below ran against a read-only export of `allod/tools` at `origin/agent/fleet-diff` (commit `1608d3f`), extracted with `git archive` into a scratch directory and passed as the `allod-tools` argument. Nexus does not pin `allod-tools` itself — `allod/archetypes` does, at `9d029a7`, and hands it to `nexus.homeModules.host` through `home-manager.extraSpecialArgs` — so this stands in for the lock advance that has not happened. - `nix-instantiate --parse nix/home.nix` — passes. - Evaluated `nix/home.nix` directly as a function, with `pkgs` from this flake's own locked nixpkgs, and listed `home.packages`: `nexus-provisioning-scripts`, `forge-0.1.0`, `work-diff`, `flake-status`, `flake-update-cascade`, `fleet-diff`, `pull-all`, `allod-0.1.0`. The new entry is present and in the intended position. - Built the `fleet-diff` derivation. Before the `useWorkspaceLib` change it failed with four `SC2329` findings on `workspace_is_repo_root`, `workspace_collect_repos`, `workspace_collect_worktrees`, and `workspace_repo_default_branch`. After the change it builds, and the built `bin/fleet-diff --help` exits 0 and prints the usage block. - Built `flake-status`, `flake-update-cascade`, `work-diff`, and `pull-all` both before and after the helper change. All four build, and all four `.drv` paths are identical across the two runs: `ppqh5g5y…-flake-status.drv`, `3dpfvzj6…-flake-update-cascade.drv`, `g11k03ib…-work-diff.drv`, `z1gpkb1d…-pull-all.drv`. - `nix build .#checks.x86_64-linux.no-hardcoded-arch` — passes. Not run, and why: - No host rebuild, and no `nixos-rebuild` of any kind. `nexus` is the host composition and host commands need a human at the terminal. - No full `nix flake check`. Its other checks (`provisioning-contract`, `host-provisioning-env`) cover scripts and modules this change does not touch, and `provisioning-contract` is the expensive one. - No `flake.lock` update in this repo, by instruction and because this repo has no `allod-tools` node to update. - The `fleet-diff` build above proves the composed script passes shellcheck and runs; it does not exercise the tool against a real fleet. `allod/tools` PR 136 carries that suite (83 assertions). ## Linking `Refs`, not `Closes`, per the multi-repo rule in `git-workflow.md`: this repo cannot put the tool on the PATH by itself, so the issue should close on the step that finishes the chain — the `allod-tools` lock advance in `allod/archetypes` — not here. Refs allod/nexus#37 Depends on: allod/tools#136

allod-agent added 1 commit

2026-09-03 23:28:14 +01:00

Install fleet-diff on the host PATH 4edff07c00

Wire flake/fleet-diff from the allod-tools input into the host home
composition, alongside flake-status and flake-update-cascade.

fleet-diff calls none of lib/workspace.sh's helpers, so prepending that
library unconditionally trips shellcheck SC2329 on all four unused
function definitions and writeShellApplication fails the build.
workspaceTool therefore gains a useWorkspaceLib argument, default true,
which fleet-diff sets to false. The other four tools' derivation paths
are unchanged.

flake/fleet-diff does not exist on allod/tools master yet, so this
cannot build until allod/tools PR 136 merges and the allod-tools lock
advances in allod/archetypes.

Refs allod/nexus#37

allod-agent referenced this pull request from allod/archetypes

2026-09-03 23:32:45 +01:00

Put fleet-diff on both PATHs and advance the pins that resolve it #68

allod-agent referenced this pull request from allod/tools

2026-09-03 23:40:46 +01:00

Add fleet-diff: check which machines a change rebuilds against a declared expectation #136