box/docs/plans/2026-07-18-versioned-install.md

Versioned installs, and a real uninstall (0.7.0 core)

Status: implemented and tested. 154/154 in test/cli.sh (which now drives real installer runs, not greps of them), shellcheck clean, and CI's rehearsal job installs via install.sh itself and ends with a zero-residue uninstall drill on a live Incus. This doc records the design and why each decision fell where it did.

What was asked

Two maintainer requests, one PR:

1. Install should be versioned — each box version goes to its own folder and a tracked default names the one you run, like plenty of CLIs manage theirs. Before this, install.sh refused to touch an existing install at all: changing versions meant uninstalling by hand (rm -rf two paths from the README) and re-running the installer.
2. Uninstall is flaky — there was no uninstall verb at all, only prose; teardown-host.sh deliberately leaves the install tree; and nothing encoded the safe full-removal order (revoke users → teardown-host → remove trees/symlinks). Add thorough tests for uninstall, and for grant/revoke that they are clean.

The layout

<root>/                       /opt/box (root) or ~/.local/share/box (user);
                              BOX_HOME overrides — both unchanged from #71
  versions/<version>/         one full tree per version, each with its own
                              VERSION + INSTALLED_FROM
  current -> versions/<v>     the tracked default (a relative symlink, so the
                              root can move as a unit)
$BINDIR/box -> <root>/current/bin/box

The version key is the tree's own VERSION file — the identity of what was installed, and the name box versions lists. bin/box needed no change to run from here: line 8 already derives $root via readlink -f, which resolves the whole $BINDIR/box → current → versions/<v> chain, so VERSION, templates/, host/ and drill/ all resolve inside the version tree that is actually running. That same fact is how the new verbs detect their world: a versioned install always runs from .../versions/<v>; a git checkout does not, and the verbs refuse instead of uninstalling somebody's working copy.

Install semantics (#66's stance, kept — at the flip)

#66 established: a stray installer re-run must never clobber a working install or rebuild the stack under existing boxes. The old enforcement was a blanket "refuse if anything is installed", which also blocked upgrades. The versioned layout splits the two concerns:

• Same version present → converging no-op ("already installed", exit 0); BOX_REINSTALL=1 replaces that version's tree via two renames (never a partial overlay). A converge/reinstall of a non-current version never moves the default — switching is box use, a deliberate act.
• Different version → installs side-by-side, then flips current only when no boxes exist. With boxes present (both tag generations, checked at the caller's tier via a shared existing_boxes() — byte-identical in install.sh and bin/box, diffed by the tests so the two #66 stances cannot drift), the flip is refused loudly, the boxes are named, and the operator is pointed at the remedy: down/copy-out/rm, then box use <v>. A daemon that is absent or not answering has no boxes to protect — the stance guards boxes, not daemons.
• Pre-0.7.0 flat tree → migrated before anything else: mv the root aside, mkdir versions/, mv it to versions/<its-VERSION>, link current and $BINDIR/box. Two renames inside one parent directory — no copy, no window with no install, the operator's tree preserved bit for bit (the tests assert the migrated tree's own INSTALLED_FROM survives).
• Wedged symlinks → healed, never trusted. The old no-op check keyed off $BINDIR/box or $DEST/bin/box existing, so a stale symlink (or a half-removed tree) faked "already installed" forever. Installed-ness is now judged from versions/<v> itself; ln -sfn converges the links.
• Tier coexistence → a root and a per-user install shadow each other by PATH order alone; the installer warns when it sees the other tier's tree.
• Host setup is offered on fresh hosts only — an upgraded host has made that decision (and may have live boxes the stack must not be rebuilt under); box setup-host re-applies stack changes deliberately.

BOX_INSTALL_SOURCE=<dir-or-tarball> bypasses the download (a directory is tar-copied with --exclude=.git). This exists for CI and the drill — the code under review is what lands — and it is what turned the test suite's install coverage from greps into real runs.

The new verbs

Table rows like every other verb (the CMDS table stays the single source of truth); uninstall joins the host-verb flag passthrough so --all / --purge-host reach it.

• box versions — lists versions/*, marking the current default and the tree answering the command (they differ when another install shadows yours on PATH).
• box use <version> — same existing-boxes refusal as the installer's flip (shared helper, boxes named), then repoints current, converges every PATH symlink that resolves into this install root (never one that is somebody else's), and asserts the effective result: current must resolve to the asked-for version and current/bin/box --version must answer it. A flip that "worked" while the operator still runs the old tree is exactly the flakiness this verb exists to end.
• box uninstall [<version>] [--all] [--purge-host] —
  • one version: refuses the current one; removes the dir; re-checks it.
  • full: the safe order — refuse while boxes exist (naming them) unless --purge-host runs teardown-host.sh first (its own confirmation; a note names granted users' surviving projects and revoke --purge as the clean path); confirm (--force / BOX_YES=1 — installer-family consent, deliberately not the lifecycle confirm(), which must never auto-accept from the environment); gather the removal set (root, every PATH symlink pointing into it, claudebox crumbs of both name generations); remove; then the absence assert: every path re-checked for file/dir/symlink existence, any survivor → exit 1 uninstall INCOMPLETE naming the leftovers. rm's exit code is not the verdict — the re-check is (a half-removed tree is INCOMPLETE, not a crash).

Grant/revoke cleanliness

Reading revoke-user.sh against its own absence assert found the gap: the purge removes /var/lib/incus/users/<uid> but never re-checks it — and the stat was a bare [ -d ], which lies for a non-root admin (/var/lib/incus is not traversable, so the directory reads as absent while it is there). Both fixed: the check rides $SUDO test -d, and the absence block now covers the state dir. Grepped-and-guarded in test/cli.sh; drilled live in CI.

Tests (the heart of this PR)

test/cli.sh stays dependency-free, non-root, daemon-free. New machinery: a fake incus on PATH whose list prints $FAKE_BOXES, throwaway BOX_HOME/BOX_BIN roots, and fabricated second/third sources with different VERSIONs. Driven end to end: fresh layout + chain (box --version through both symlinks), no-op/canary, BOX_REINSTALL, side-by-side + no-boxes flip, all three #66 refusals (install flip, use, uninstall — boxes named, remedies named), versions markers, use flip-and-assert, flat-tree migration (alone, and combined with an upgrade), dangling- and stale-symlink healing, single-version uninstall (current refused), full uninstall with planted legacy crumbs and a zero-residue assert (files and symlinks and legacy names), the INCOMPLETE scream (a chmod-pinned survivor), and refusals from a working tree. The existing DEST/BINDIR-branch tests are kept unchanged (the branch itself is unchanged).

CI's rehearsal job now installs via install.sh (BOX_INSTALL_SOURCE=$GITHUB_WORKSPACE), asserts the layout it left, runs the stack from /opt/box/current/..., and appends the uninstall drill: grant + revoke --purge a throwaway user (asserting the incus-user state dir is gone), teardown-host (new --yes/BOX_YES support), box uninstall --all, then zero residue — networks, profiles, ACLs, nft tables, systemd units, files, symlinks, both name generations.

What this is not

• Not #67: boxes still do not migrate across versions — this PR delivers the version-agnostic upgrade path (side-by-side installs, an explicit flip); data migration remains #67.
• Not a release: VERSION is untouched (a release PR bumps it).