thaloco/banger
1
Fork 0
Code Pull requests Releases Packages Activity Actions
banger/AGENTS.md
Thales Maciel ac7974f5b9
Remove image build --from-image; doctor treats catalog images as OK 
The `image build` flow spun up a transient Firecracker VM, SSHed in,
and ran a large bash provisioning script to derive a new managed
image from an existing one. It overlapped heavily with the golden-
image Dockerfile flow (same mise/docker/tmux/opencode install logic
duplicated in Go as `imagemgr.BuildProvisionScript`) and had far more
machinery: async op state, RPC begin/status/cancel, webui form +
operation page, preflight checks, API types, tests. For custom
images, writing a Dockerfile is simpler and more reproducible.

Removed end-to-end:
- CLI `image build` subcommand + `absolutizeImageBuildPaths`.
- Daemon: BuildImage method, imagebuild.go (transient-VM orchestration),
  image_build_ops.go (async begin/status/cancel), imagemgr/build.go
  (the 247-line provisioning script generator and all its append*
  helpers), validateImageBuildPrereqs + addImageBuildPrereqs.
- RPC dispatches for image.build / .begin / .status / .cancel.
- opstate registry `imageBuildOps`, daemon seam `imageBuild`,
  background pruner call.
- API types: ImageBuildParams, ImageBuildOperation, ImageBuildBeginResult,
  ImageBuildStatusParams, ImageBuildStatusResult; model type
  ImageBuildRequest.
- Web UI: Backend interface methods, handlers, form, routes, template
  branches (images.html build form, operation.html build branch,
  dashboard.html Build button).
- Tests that directly exercised BuildImage.

Doctor polish (task C):
- Drop the "image build" preflight section entirely (its raison d'être
  is gone).
- Default-image check now accepts "not local but in imagecat" as OK:
  vm create auto-pulls on first use. Only flag when the image is
  neither locally registered nor in the catalog.

Net: 24 files touched, 1,373 lines deleted, 25 added.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-18 15:54:29 -03:00

3.7 KiB
Raw Blame History

Repository Guidelines

Always run make build before commit.

Project Structure

  • cmd/banger and cmd/bangerd are the main user entrypoints.
  • internal/ contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and the experimental web UI.
  • internal/daemon/ is the composition root; pure helpers live in its subpackages (opstate, dmsnap, fcproc, imagemgr, session, workspace). See internal/daemon/ARCHITECTURE.md.
  • internal/imagecat/ and internal/kernelcat/ embed the image + kernel catalogs.
  • images/golden/ is the Dockerfile for the debian-bookworm catalog entry.
  • scripts/ contains manual helper workflows for rootfs, kernel, and bundle preparation.
  • build/bin/ is the canonical source-checkout build output.
  • build/manual/ is the canonical source-checkout location for manual rootfs/kernel artifacts.

Build and Test

  • make build builds ./build/bin/banger, ./build/bin/bangerd, and ./build/bin/banger-vsock-agent.
  • make test runs go test ./....
  • make lint runs gofmt -l, go vet ./..., and shellcheck --severity=error on scripts/*.sh. Run before commits.
  • ./build/bin/banger doctor checks host readiness.
  • ./build/bin/banger vm run is the primary user-facing entry point — auto-pulls the default image + kernel from the catalogs if missing.
  • ./build/bin/banger image pull <name> uses the bundle catalog (fast) when <name> is a catalog entry, or falls through to the OCI path for arbitrary registry refs. See docs/image-catalog.md and docs/oci-import.md.
  • ./build/bin/banger image register ... registers an unmanaged host-side image stack.
  • ./build/bin/banger image promote <image> copies an unmanaged image into daemon-owned managed artifacts.
  • scripts/make-generic-kernel.sh builds a Firecracker-optimized vmlinux from upstream sources. scripts/publish-kernel.sh <name> publishes it to the kernel catalog.
  • scripts/publish-golden-image.sh rebuilds + publishes the golden image bundle and patches the image catalog.

Image Model

  • Managed images own the full boot set: rootfs, optional work-seed, kernel, optional initrd, and optional modules.
  • The image catalog ships pre-built bundles. vm run auto-pulls the default catalog entry; image pull <name> can be invoked explicitly.
  • default_image_name defaults to debian-bookworm. On miss, the daemon auto-pulls from imagecat before surfacing "not found".
  • Kernel references follow the same auto-pull pattern against kernelcat.

Config

  • Config lives at ~/.config/banger/config.toml.
  • Firecracker comes from PATH by default, or firecracker_bin.
  • SSH uses ssh_key_path or an auto-managed default key at ~/.config/banger/ssh/id_ed25519.

Coding Style

  • Prefer small, direct Go code and standard library solutions.
  • Keep shell scripts strict with set -euo pipefail.
  • Use gofmt for Go formatting.
  • When a CLI accepts either an inline string or a file input, always prefer the file-based form.
  • For shell commands and AI/LLM tooling, prefer passing files as input whenever the CLI allows it.
  • Create temporary files as needed to follow the file-first rule.
  • Examples: use git commit -F <file> instead of git commit -m <message>, and use prompt files instead of inline prompt strings when invoking LLM CLIs.

Testing Guidance

  • Primary automated coverage is go test ./....
  • For lifecycle changes, smoke-test with vm run end-to-end (covers create + start + boot + ssh).
  • If guest provisioning changes, document whether existing images must be rebuilt or recreated.

Security

  • Do not commit secrets.
  • VM workflows require sudo and /dev/kvm.
  • The default SSH key is local configuration, not a checked-in runtime artifact.