Installer copy catalog (byte-exact golden of what a user sees)

[LukasWodka]

Summary

Adds a copy catalog for the installer — a byte-exact golden of every stable piece of user-facing copy, so wording + layout can be reviewed without running an install. Mirrors the CLI's golden catalog (cli repo, internal/cli/testdata/golden/).

scripts/tests/copy-catalog.bats renders the copy colour-off (NO_COLOR) into two files under scripts/testdata/golden/, ordered like the run:

• 00-install.golden — the banner (versioned + direct-run variants), the "2. Installing" roadmap, the six running step headers (a–f; titles read live from install-k8s.sh so they can't drift), and --help.
• 01-outcomes.golden — print_summary's five end states (connected / starting / bad creds / image pull / crash) + the reboot footer, including the macOS/Windows variant.

Why

So we stop the "change copy → deploy → see it in prod → fix" loop: the catalog is reviewable on any PR that touches installer copy, and the test fails on drift.

Determinism

• Colour off → text is byte-exact.
• The one live read (_chart_version) is stubbed; $HOME collapses to ~ in the summary, so the goldens are stable across machines/CI.
• The step titles are extracted from install-k8s.sh at test time, so they track the real installer.

Test plan

• TB_UPDATE_GOLDEN=1 bats scripts/tests/copy-catalog.bats regenerates; plain bats scripts/tests/copy-catalog.bats verifies (drift guard). Both green locally.
• Not in the R8 manifest (tests/ + testdata/ aren't installer scripts). CI already globs scripts/tests/*.bats and excludes .bats from shellcheck, so it runs with no wiring changes.

🤖 Generated with Claude Code

---

Note

Low Risk
Test-only additions (BATS + golden fixtures); installer runtime behavior is unchanged.

Overview
Adds an installer copy catalog: BATS tests render stable, user-facing installer text (with NO_COLOR) into golden files under scripts/testdata/golden/, mirroring the CLI’s golden pattern.

copy-catalog.bats drives print_banner, print_roadmap, step headers (titles parsed live from install-k8s.sh), print_help, and print_summary for each end state. Output is compared byte-for-byte to 00-install.golden and 01-outcomes.golden; drift fails CI unless you regenerate with TB_UPDATE_GOLDEN=1.

Determinism comes from stubbing _chart_version, clearing TRACEBLOC_BANNER_SHOWN, and fixed env vars—no full install required for copy review on PRs.

^{Reviewed by Cursor Bugbot for commit 65b9e8a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f5bfebf. Configure here.}

[shujaatTracebloc]

Review — installer copy catalog

Nice addition — a byte-exact copy golden is exactly the right guard against the "change copy → deploy → see it in prod → fix" loop, and the determinism work holds up: I traced it and confirmed _reboot_note keys off $OS (not uname), $HOME→~ collapse in print_summary, the _chart_version stub ordering (sourced then overridden), the 5 driven states match summary.sh's case labels, and CI genuinely globs scripts/tests/*.bats so it wires up with no changes. No CLAUDE.md or reuse issues (summary.bats covers state detection, this covers rendered copy — complementary).

Four things in the harness, ranked. Test-only, so none is a runtime risk — but #1 undercuts the catalog's own promise.

1. Step-header scrape silently drops steps + mishandles titles (blocking-ish)

sed -nE 's/.*step_header ([a-f]) "([^"]*)".*/\1 \2/p'"${SCRIPTS_DIR}/install-k8s.sh"

The PR's selling point is "titles read live so they can't drift." This regex only partly delivers:

• Hard-coded [a-f] — a future step_header g "Finishing up" is silently omitted. The catalog still looks complete, so a reviewer gets false "all steps covered" confidence — the exact drift this is meant to catch.
• "([^"]*)" truncates a title containing a ", and a title passed as a variable (step_header a "$FOO") is captured as the literal $FOO, not the rendered text the user sees.

Deeper fix: instead of scraping source text, have install-k8s.sh expose its step titles (a function or array) the test can invoke — then the catalog can't diverge from the real steps regardless of count or quoting.

2. Missing golden → cryptic failure instead of the documented hint

check_golden does diff -u "$golden" "$actual" with no existence check. A new catalog file (or a deleted golden) fails with diff: …/XX.golden: No such file or directory (exit 2) rather than the run TB_UPDATE_GOLDEN=1 … guidance the header advertises — reads as a tooling error, not "generate the golden". A one-line [ -f "$golden" ] || { echo "missing golden — run TB_UPDATE_GOLDEN=1"; return 1; } fixes it.

3. print_summary 2>&1 folds stderr into the byte-exact golden

Safe today (summary is pure stdout; log() is sunk to /dev/null), but if any end-state — or a lib it sources — ever writes to stderr, that text lands in the golden, and because piped stdout is block-buffered while stderr is unbuffered, the two can interleave in a machine-dependent order → a "byte-exact" golden that flakes. Capturing only stdout (drop 2>&1) unless you specifically want to pin stderr copy.

4. Determinism leans on override ordering in setup()

Goldens are machine-independent only because setup() reassigns OS/ARCHafterload_lib sources common.sh (whose top-level OS=$(uname -s) / ARCH=$(uname -m) would otherwise capture the runner). Correct as written, but load-bearing and unremarked — a reorder, or a newly-cataloged function that reads $OS before the override, reintroduces Darwin/arm64 leakage on a Mac. Worth a one-line comment pinning why the order matters.

🤖 Reviewed with Claude Code

[shujaatTracebloc]

Approving — this is a well-built, byte-exact copy catalog and the determinism holds up (verified: _reboot_note keys off $OS, $HOME→~ collapse, _chart_version stub ordering, CI globs *.bats). Details in my earlier review comment above.

Non-blocking, in priority order:

1. Worth a fast-follow: the sed … step_header ([a-f]) "…" scrape hard-codes [a-f] (silently drops a future 7th step) and mis-handles quoted/variable titles — which softens the PR's own "titles can't drift" guarantee. Ideally install-k8s.sh exposes its step titles rather than being scraped. Fine to land as-is and tighten later.
   2–4. Optional polish: missing-golden should hint TB_UPDATE_GOLDEN=1 rather than a raw diff error; consider dropping 2>&1 on print_summary to keep the golden stdout-only; and a one-line comment on why setup() must override OS/ARCH after load_lib.

None block merge. 🚀

🤖 Reviewed with Claude Code