Problem
Keeping the machine in sync with the repo is a manual, multi-step chore today: I have to remember to run brew bundle, restow packages, prune broken symlinks, and re-install global language packages by hand, across separate tools. There's no single "is my machine still what the repo says it should be?" check, and no one command to fix it.
Goal
One command to report drift and one to reconcile it — reusing the tools we already have (brew bundle, stow, packages/packages.sh), not reinventing them.
Scope — three domains
- Homebrew — installed formulae/casks vs
packages/Brewfile (brew bundle check / dump / cleanup).
- Stow symlinks — missing links, un-stowed new files, and dead/broken symlinks pointing into the repo.
- Language globals — declared vs installed for node/bun/ruby/rust against the
packages/*_packages.txt manifests (delegates to packages.sh).
Proposed command surface (justfile)
just doctor — read-only report across all three domains; non-zero exit if drift is found (CI/scriptable).
just sync — safe apply: install missing (brew + language globals) and restow. Never uninstalls anything.
just prune — destructive, opt-in: remove installed packages not declared in the Brewfile (brew bundle cleanup --force).
just snapshot — update Brewfile from current state (brew bundle dump --force).
Acceptance criteria
just doctor on a clean machine exits 0 and reports "no drift".
- Introducing drift (uninstall a Brewfile formula, add an unstowed file, drop a manifest package) is surfaced by
just doctor.
just sync reconciles the safe cases and is idempotent (second run = no changes).
- No new bespoke lockfile; logic lives in a shellcheck-clean
scripts/drift.sh using the existing scripts/functions.sh helpers.
Priority: this is the next feature to build.
Problem
Keeping the machine in sync with the repo is a manual, multi-step chore today: I have to remember to run
brew bundle, restow packages, prune broken symlinks, and re-install global language packages by hand, across separate tools. There's no single "is my machine still what the repo says it should be?" check, and no one command to fix it.Goal
One command to report drift and one to reconcile it — reusing the tools we already have (
brew bundle,stow,packages/packages.sh), not reinventing them.Scope — three domains
packages/Brewfile(brew bundle check/dump/cleanup).packages/*_packages.txtmanifests (delegates topackages.sh).Proposed command surface (justfile)
just doctor— read-only report across all three domains; non-zero exit if drift is found (CI/scriptable).just sync— safe apply: install missing (brew + language globals) and restow. Never uninstalls anything.just prune— destructive, opt-in: remove installed packages not declared in the Brewfile (brew bundle cleanup --force).just snapshot— updateBrewfilefrom current state (brew bundle dump --force).Acceptance criteria
just doctoron a clean machine exits 0 and reports "no drift".just doctor.just syncreconciles the safe cases and is idempotent (second run = no changes).scripts/drift.shusing the existingscripts/functions.shhelpers.Priority: this is the next feature to build.