Thales Maciel
671723a0ef
Capture the repository preference that shell facing tools should consume files when they support them instead of large inline strings. Add explicit guidance for prompt files, temporary files, and git commit message files so future automation avoids quoting bugs and stays aligned with the vm run harness and commit workflows.
53 lines
2.6 KiB
Markdown
53 lines
2.6 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure
|
|
|
|
- `cmd/banger` and `cmd/bangerd` are the main user entrypoints.
|
|
- `internal/` contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and web UI.
|
|
- `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.
|