feat(installer): leftover-data guard — never silently adopt an earlier install's data (#376)

[saadqbal]

Closes#376. Implements the installer leftover-guard from RFC-0003 (cli#366, D3 — §4). Related: #367 (node-local storage), design: backend#1151.

Problem

A new install (one that creates a fresh cluster) did mkdir -p on its data dirs and adopted whatever already existed under HOST_DATA_DIR — data left by an earlier install (different layout, older version, custom dir) was silently picked up, so a "fresh" install wasn't guaranteed fresh.

What this does

Adds guard_leftover_data (scripts/lib/cluster.sh), called from create_clusteronly when creating a NEW cluster — an existing cluster is an in-place reuse/upgrade whose data stays by design (§3.3), so routine re-runs are unaffected. When it finds real client data it stops and forces a choice:

• Interactive:reuse / wipe / new dir / abort (abort is the default).
• Non-interactive:--reuse-data / --wipe-data / --data-dir=PATH (or TB_LEFTOVER_ACTION). No terminal + no choice → fail-safe abort, never adopt.
• Bypass:TRACEBLOC_SKIP_LEFTOVER_GUARD=1.

Detection (_leftover_data_dirs) covers both on-disk layouts — flat ($HOST_DATA_DIR/{mysql,data}) and per-release ($HOST_DATA_DIR/<rel>/…) — and keys on real data (MySQL/dataset files); empty dirs, values.yaml, and install logs are ignored.

Safety

• Scoped to HOST_DATA_DIR only. HOST_DATASET_DIR may be a shared network mount, so it is never scanned or wiped (a test asserts this).
• Wipe only removes paths under the already-validated HOST_DATA_DIR (validate_config guarantees it's under $HOME and not a system path).
• Doubles as the node-local migration prompt (Implement RFC-0003 local storage: node-local (Option C, single-node) + drop chmod 777 #367): existing ~/.tracebloc data is never silently stranded.

Tests / checks

• New scripts/tests/leftover-guard.bats — 13 tests (detection both layouts, reuse/wipe/new-dir, interactive + non-interactive, fail-safe abort, HOST_DATASET_DIR preserved).
• Full bats suite: 380/380 pass.
• shellcheck --severity=error (CI-equivalent) and check-style.sh: clean.
• manifest.sha256 regenerated (--check passes).

Docs

README "Reinstalling on a machine that still holds data" note + --help/env-var docs.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes first-run install behavior and can delete local MySQL/dataset dirs on wipe; mitigated by explicit choices, non-interactive abort by default, and extensive safety checks/tests.

Overview
New installs that create a fresh k3d cluster now run a leftover-data guard before provisioning: if HOST_DATA_DIR already has real MySQL/dataset files (flat or per-release layout), the installer stops instead of silently adopting it. Users choose reuse, wipe, another directory, or abort (interactive default is abort); non-interactive runs need --reuse-data, --wipe-data, or --data-dir=PATH, otherwise the install fails closed. Existing clusters are unchanged (in-place reuse/upgrades skip the guard).

The guard is scoped to HOST_DATA_DIR only—HOST_DATASET_DIR is never scanned or wiped—with symlink-safe detection, pipefail-safe non-empty checks, and wipe paths constrained under $HOME. validate_config now rejects empty HOST_DATA_DIR, expands leading ~, and blocks using $HOME itself as the data dir.

CLI/docs: new flags and env vars on install-k8s.sh, README reinstall note, --help/golden updates, refreshed manifest.sha256, plus leftover-guard.bats and HOST_DATA_DIR validation tests in common.bats.

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

[LukasWodka]

Reviewed the guard logic end-to-end — this is careful, well-tested work (default = abort, fail-closed on no-terminal, 18 bats cases, R8 manifest regenerated, HOST_DATASET_DIR correctly excluded from the wipe scope). One thing to confirm before merge, since it's destructive-capable:

Verify the HOST_DATA_DIR non-empty invariant guarding the wipe. The wipe loop removes $d only when it matches the "$HOST_DATA_DIR"/* case pattern. If HOST_DATA_DIR were ever empty/unset at the point guard_leftover_data runs, that pattern collapses to /* and the safety guard is defeated. The code comment states validate_config guarantees it is under $HOME — so the safety hinges entirely on guard_leftover_data always being called after validate_config has enforced a non-empty, under-$HOME HOST_DATA_DIR.

Could you confirm (or add a belt-and-suspenders assertion at the top of the wipe branch)?

[[ -n "$HOST_DATA_DIR" && "$HOST_DATA_DIR" == "$HOME"/* ]] || error "refusing to wipe: HOST_DATA_DIR unset/invalid"

That makes the wipe safe even if the call ordering ever changes. Everything else looks good to me.

(Claude-assisted review, run by @LukasWodka to keep the queue moving — flagging for a human eye on the wipe-safety invariant given this touches customer data.)

[saadqbal]

Added in c8b9f94. Put the assertion inside _wipe_leftover_data (rather than the wipe branch) so it guards the rm for any caller, not just the current path:

[[ -n"${HOST_DATA_DIR:-}"&&"$HOST_DATA_DIR"=="$HOME"/* ]] \
|| error "Refusing to wipe: HOST_DATA_DIR is unset or not under \$HOME (got '${HOST_DATA_DIR:-}')."

For completeness on the invariant you asked about: guard_leftover_data is only ever called from create_cluster, which runs after validate_config (main() → validate_config → … → create_cluster), and _leftover_data_dirs already returns nothing when HOST_DATA_DIR is unset — so the wipe can't run today with an empty value. The assertion is the belt-and-suspenders that keeps it safe if that ordering ever changes. Two tests cover it (empty + outside-$HOME both refuse). Suite is now 20 bats cases.

🤖 Addressed by Claude Code

[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 1c7c38c. Configure here.}

[shujaatTracebloc]

Approving — reviewed end-to-end, and Bugbot's re-review on e3f477b now concludes success with all 12 findings resolved.

Verified independently (not just trusting fix replies):

• Full leftover-guard suite green locally, shellcheck --severity=error clean, manifest.sha256 --check clean, branch current with develop (manifest conflict resolved by regenerating).
• The design is sound: a new-cluster-only guard that fails closed everywhere — no-TTY, unreadable/root-owned dirs, wipe survivors, symlink-escape, and now == $HOME all abort rather than silently adopt.

Findings, all confirmed genuinely fixed:

• Detection: pipefail-safe multi-file scan; unreadable dirs fail closed (no temp-file fail-open path); symlinked release dirs skipped; flat datadir's nested mysql schema no longer double-counted.
• Wipe: verifies removal (fails closed on survivors); refuses symlink-escape; asserts HOST_DATA_DIR non-empty & under $HOME.
• Input: paste/CSI sanitized + trimmed; TTY probed for openability (not just -r) so no-TTY runs get the actionable non-interactive guidance; ~/~/ expanded; empty --data-dir rejected; HOST_DATA_DIR == $HOME rejected.

Every fix carries a regression test. LGTM. 🚢

[LukasWodka]

Functional review \u2014 passed\n\nBasis: the behavioural suites that ran on this PR at merge against real environments, not mocks:\n\n- on multiple Ubuntu releases + \u2014 a real install exercised end-to-end on real distros, behind a TLS-inspecting proxy\n\nI could not reach the dev API (no dev credentials), so rather than rubber-stamp I used the strongest evidence available: these suites exercise the actual behaviour this change alters, on real infrastructure. Advancing \u2192 .\n\nIf the functional reviewer wants a manual pass on dev in addition, please move it back and say so.