Thales Maciel
ca4865447c
internal/daemon/doc.go and ARCHITECTURE.md were written before the subpackage extractions and still referenced old structure (in-progress phrasing, missing opstate/dmsnap/fcproc/imagemgr/session/workspace, mentions of opRegistry by its old name). Both now describe the current shape: composition root + six leaf subpackages, lock ordering rooted at vmLocks[id], and the one intra-package dependency (workspace → session for ShellQuote + FormatStepError). README.md and AGENTS.md mark the local web UI as experimental. It is still enabled by default at 127.0.0.1:7777, but the docs now state plainly that its surface is not stable or hardened and not intended for anything beyond single-user localhost use. AGENTS.md also points at ARCHITECTURE.md for the subpackage layout. No code changes; tests still green. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
56 lines
2.8 KiB
Markdown
56 lines
2.8 KiB
Markdown
# 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`.
|
|
- `scripts/` contains explicit manual helper workflows for rootfs and kernel 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 ./...`.
|
|
- `./build/bin/banger doctor` checks host readiness.
|
|
- `./build/bin/banger image build --from-image <image>` builds a managed image from an existing registered image.
|
|
- `./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.
|
|
- `make void-kernel`, `make rootfs-void`, and `make void-register` drive the experimental Void flow under `./build/manual`.
|
|
|
|
## Image Model
|
|
|
|
- Managed images own the full boot set: rootfs, optional work-seed, kernel, optional initrd, and optional modules.
|
|
- There is no runtime bundle and no auto-registered default image from disk paths.
|
|
- `default_image_name` selects a registered image only.
|
|
|
|
## 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 create`, `vm ssh`, `vm stop`, and `vm delete`.
|
|
- 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.
|