banger/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• cmd/banger and cmd/bangerd are the primary user-facing entrypoints.
• internal/ contains the daemon, CLI, RPC, storage, Firecracker, and system integration code.
• The VM lifecycle is now organized around daemon capabilities plus a structured guest-config builder. New host-integrated VM features should plug into that Go path instead of adding more one-off branches through internal/daemon/vm.go.
• customize.sh, make-rootfs.sh, and interactive.sh remain as manual rootfs/customization helpers; normal VM lifecycle, NAT, .vm DNS, and daemon-driven image builds are handled by the Go control plane.
• Source checkouts use a generated ./runtime/ bundle for Firecracker, kernels, modules, rootfs images, and helper copies. Bundle defaults come from ./runtime/bundle.json when present. Those runtime artifacts are not meant to be tracked directly in Git.
• The daemon keeps state under XDG directories rather than the old repo-local state/ layout.

Build, Test, and Development Commands

• make build builds ./banger, ./bangerd, and the bundled ./runtime/banger-vsock-agent guest helper.
• make bench-create benchmarks vm create and first-SSH readiness on the current host.
• make runtime-bundle bootstraps ./runtime/ from the archive referenced by RUNTIME_MANIFEST; the checked-in runtime-bundle.toml is only a template.
• make rootfs-void builds an experimental local-only x86_64-glibc Void rootfs plus work-seed under ./runtime/; it does not replace the default Debian path or teach banger image build about Void.
• make verify-void registers void-exp and runs the normal smoke test against that image.
• banger validates required host tools per command and reports actionable missing-tool errors; do not assume one workstation's package set.
• ./banger vm create --name testbox creates and starts a VM.
• ./banger vm ssh testbox connects to a running guest using the runtime bundle SSH key and reminds the user if the VM is still running when the session exits.
• ./banger vm stop testbox stops a VM while preserving its disks.
• ./banger vm stop vm-a vm-b vm-c and ./banger vm set --nat web-1 web-2 are supported; multi-VM lifecycle and set actions fan out concurrently through the CLI.
• ./banger doctor reports runtime bundle, host tool, feature, and image-build readiness from the same Go checks used by the daemon.
• ./banger image register --name local --rootfs /abs/path/rootfs.ext4 creates or updates an unmanaged image record without changing the default image config; use it for experimental guest iteration paths such as Void.
• ./banger tui launches the terminal UI.
• make test runs go test ./....
• ./verify.sh runs the smoke test for the Go VM workflow.

Coding Style & Naming Conventions

• Go code should stay small, direct, and standard-library-first unless there is a clear reason otherwise.
• Shell helpers use Bash with set -euo pipefail; keep remaining shell scripts strict and explicit.
• Prefer lowercase filenames with short descriptive names.
• Use gofmt for Go formatting; no extra formatter is configured for shell files.

Testing Guidelines

• Primary automated coverage is go test ./....
• Manual verification for VM lifecycle changes: ./banger vm create, confirm SSH access, then stop/delete the VM.
• For host-integration changes, run ./banger doctor as a quick readiness check before the live VM smoke.
• Rebuilt images now include mise, opencode, tmux-resurrect/tmux-continuum defaults for root, and the banger-vsock-agent service used by the SSH reminder and guest health-check path; if you change guest provisioning, document whether users need to rebuild ./runtime/rootfs-docker.ext4 or another base image to pick it up.
• The experimental Void rootfs path is intentionally lean: keep it limited to boot, SSH, the vsock HTTP health agent, a bash root shell while leaving /bin/sh alone, and the /root work-seed unless the user explicitly wants more baked in.
• Rebuilt images also emit a work-seed.ext4 sidecar used to speed up future VM creates. If you touch /root provisioning, verify both the rootfs and the work-seed output.
• The daemon may keep idle TAP devices in a pool for faster creates. Smoke tests should treat tap-pool-* devices as reusable capacity, not cleanup leaks.
• If you add a new operational workflow, document how to exercise it in README.md.
• For NAT changes, verify both guest outbound access and host rule cleanup, for example with ./verify.sh --nat.

Commit & Pull Request Guidelines

• Git history uses short, imperative subjects.
• Prefer a real commit body when the change affects lifecycle behavior, storage semantics, or host integration.
• PRs should call out runtime requirements, migration impact, and any host-side verification performed.

Security & Configuration Tips

• The VM workflow requires sudo and /dev/kvm access; do not commit secrets.
• id_ed25519 lives inside the runtime bundle; rotate or replace it before publishing a shared bundle.