thaloco/banger
1
Fork 0
Code Pull requests Releases Packages Activity Actions
banger/AGENTS.md
Thales Maciel fcedacba5c
Make runtime defaults portable 
Stop assuming one workstation layout for runtime artifacts, mapdns, and host tooling. The daemon and shell helpers now use portable mapdns configuration, and runtime bundles can carry bundle.json metadata for their default kernel, initrd, modules, rootfs, and helper paths.

Load bundle metadata through config with a legacy layout fallback, thread mapdns_bin/mapdns_data_file through the Go and shell paths, and add command-scoped preflight checks for VM start, NAT, image build, work-disk resize, and SSH so missing tools or artifacts fail with actionable errors.

Update the runtime-bundle manifest, docs, and tests to match the new model. Verified with go test ./..., make build, and bash -n customize.sh interactive.sh dns.sh make-rootfs.sh verify.sh.
2026-03-16 15:30:08 -03:00

2.6 KiB
Raw Blame History

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.
  • customize.sh, make-rootfs.sh, and interactive.sh remain as image-build/customization helpers; normal VM lifecycle and NAT management 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 and ./bangerd.
  • make runtime-bundle bootstraps ./runtime/ from runtime-bundle.toml.
  • 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.
  • ./banger vm stop testbox stops a VM while preserving its disks.
  • ./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.
  • 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.