Manifest-driven deploy with dry-run, backup-on-conflict and audit [find-inspiration:manifest-deploy]

[nonrational]

Kind: foundation
Effort: M · Risk: med
Source: priors/known-candidates (run 2026-07-04)
Decision: spike

Problem

Deploy logic is implicit: link-dotfiles.sh links every root dotfile by convention, OS/host variance lives in .Darwin/.Linux suffixes and per-host .bashrc. sprawl, and there is no way to preview or audit what a run will do.

Current state (this repo)

Bespoke Makefile + link-dotfiles.sh with interactive diff/merge; filename-suffix OS branching.

Their approach

A manifest declares source→target mappings with per-entry OS/host conditions; deploy supports --dry-run, backs up conflicting files, and an audit subcommand reports drift.

Difference that matters

Reviewability and safety: a declared plan you can diff, preview and audit vs a convention you have to re-read shell to understand. Replaces suffix/per-host sprawl with explicit conditions.

Translation into this repo

Steal the design, not anyone's unreviewed engine: a manifest file + a small bash driver alongside link-dotfiles.sh, migrating a few files at a time.

Pilot slice

Manifest covering only bin.Darwin/bin.Linux and one per-host file, run in --dry-run against current state; link-dotfiles.sh keeps handling the rest until parity.

Spike question

Can a manifest + small bash driver reach parity with link-dotfiles.sh for bin.* and one per-host file — with --dry-run, backup-on-conflict and an audit mode — without adopting an external engine?

[nonrational]

Spike findings

Answer: yes. A 162-line bash driver plus a 3-entry manifest reaches parity with link-dotfiles.sh for the pilot slice (bin.*, .bashrc.nyx) with --dry-run, backup-on-conflict and audit — bash + coreutils only, no external engine.

Evidence

• ./test_deploy.sh: 23 passed, 0 failed — sandboxed fault injection covering missing target, wrong symlink, regular-file and directory conflicts, pre-existing .bak refusal, malformed/relative manifest entries, and a checksum proof that --dry-run changes nothing.

• Against the live $HOME on nyx (Darwin), run from the main checkout:

  ok: /Users/norton/bin -> /Users/norton/.dotfiles/bin.Darwin
  skip: ~/bin (os=Linux)
  ok: /Users/norton/.bashrc.nyx -> /Users/norton/.dotfiles/.bashrc.nyx
  dry-run exit=0
  ok: /Users/norton/bin
  skip: ~/bin (os=Linux)
  ok: /Users/norton/.bashrc.nyx
  audit exit=0
  

Deliberate differences from link-dotfiles.sh

• Backup-on-conflict is non-interactive — no diff/merge menu. It refuses to clobber an existing .bak (skip + non-zero exit).
• Entries whose condition doesn't match are skipped, never removed, so .bashrc.nyx already linked on another host is left alone.

Caveats

• Symlink targets are absolute paths, so deploy.sh is sensitive to which checkout it runs from. Running it from the worktree showed spurious drift — both real targets reported would: relink: because the worktree's copy resolved sources under the worktree path instead of the main checkout the live symlinks point at. Not a defect, but a practical constraint: audit and apply need to run from the checkout the links actually target, not from whatever branch happens to be checked out elsewhere.

Next step if adopted

Merge the branch, then migrate remaining dotfiles into the manifest a few at a time; drop the bin.$(uname) special case from link-dotfiles.sh once the manifest covers it.