thaloco/banger
1
Fork 0
Code Pull requests Releases Packages Activity Actions
banger/AGENTS.md
Thales Maciel 238bb8a020
Switch to fetched runtime bundles 
Stop treating Firecracker, kernels, modules, and guest images as tracked source files. Source checkouts now resolve runtime assets from ./runtime, while installed binaries keep using ../lib/banger.

Add a small runtimebundle helper plus runtime-bundle.toml so make can bootstrap, package, and install a runtime bundle with checksum validation. Update the shell helpers and daemon path hints to fail clearly when the bundle is missing instead of assuming repo-root artifacts.

This removes the tracked runtime blobs from HEAD in favor of an ignored local runtime/ tree. Verified with go test ./..., make build, bash -n on the shell helpers, make -n install, and a temporary package/fetch smoke test. The manifest URL/SHA still need a published bundle before fresh clones can bootstrap, and history rewrite remains a separate rollout step.
2026-03-16 15:05:10 -03:00

2.4 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. 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 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.