[quality] test: BATS coverage for files/bin/system-container (start/stop/enter/reset dispatch)

[kubestellar-hive]

Claimed ground: projectbluefin/server, one new file tests/unit/system-container_test.bats. Script under test: files/bin/system-container — the root privilege gate and the start / stop / enter / reset case dispatch. Tracker cluster: quality/test-coverage for the server repo.

Disjointness: no other open server PR touches files/bin/system-container or tests/unit/system-container_test.bats. #30 adds tests/unit/conftest.py + tests/unit/test_docs_checks.py and a Justfile test-unit recipe — different files; this PR touches no Justfile and no Python. #37 changes files/os/justfile, #36 the sysupdate keyring, #29 the sshd drop-in, #34 project.conf/Justfile/.github/scripts/check-release-version.py, #22/#25/#26/#27 the installer .bst elements and docs — all disjoint.

Why

files/bin/system-container is the user-facing entry point for machine management on Bluefin Server. It re-execs itself under sudo, then hands arguments straight to machinectl. Every branch runs as root, and three of the four subcommands are destructive or disruptive (poweroff, remove). It had zero test coverage, so a typo in the case table (for example machinectl stop instead of machinectl poweroff, or a dropped [ -n "$name" ] guard) would ship silently.

What

tests/unit/system-container_test.bats — 25 cases. id, sudo and machinectl are replaced with logging stubs prepended to PATH, so no privilege escalation and no container operation ever happens; each test asserts on the recorded argv.

• Privilege gate: non-root re-execs via sudo "$0" "$@" and does not reach machinectl; the re-exec still fires for a bare no-argument invocation; root invocation never calls sudo.
• Dispatch: start → machinectl start, stop → machinectl poweroff (explicitly asserted as not machinectl stop), enter → machinectl shell, reset → machinectl remove.
• Argument guards: each subcommand with a missing name, and with an explicitly empty name, exits 1 with its own usage: system-container <cmd> <name> message and invokes nothing.
• Exit-code propagation: machinectl failures (7, 3, 5) surface unchanged rather than being swallowed by the case block.
• Fallthrough: no arguments, the help default, an unknown subcommand, and a wrong-case START all exit 1 with the four-way usage banner and touch nothing.
• Contract details: usage text goes to stderr and not stdout; a machine name containing spaces stays a single argv element; extra trailing arguments are ignored; a leading -- is taken as the machine name (the script does no option parsing).
• Two structural assertions: the script is executable and declares set -euo pipefail.

Verification

$ bats tests/unit/system-container_test.bats
1..25
... 25 ok, 0 failures

Related

Refs #33 — no CI workflow runs tests/unit yet. This PR deliberately adds no workflow file (the bot token lacks the workflows permission) and no Justfile recipe (to stay textually disjoint from #30 and #34). Run locally with the command above.

Tests only — no production code, no workflow, no docs changed.

---

Filed by quality agent (hold-gated mode) — do not merge, do not remove the hold label.

— hive: agent=quality backend=copilot model=claude-opus-5

[hanthor]

Fetched the real files/bin/system-container script and confirmed all 25 BATS cases (dispatch, usage messages, exit codes, privilege gate) match actual behavior exactly. CI green.

---

Generated by Claude Code

[castrojo]

Approved by @castrojo for Hive auto-merge on green CI.