Thales Maciel
da4a6bf45b
Three small operational improvements. 1. Makefile build dependencies now cover everything under cmd/ and internal/, not just *.go. The previous GO_SOURCES find pattern missed embedded assets (catalog.json today, anything else added later), so editing a JSON manifest didn't trigger a rebuild and left the binary stale. New BUILD_INPUTS covers all files; go's own build cache absorbs any redundant invocations. GO_SOURCES is kept for fmt/lint targets which still want only Go files. 2. New `make lint` (default + lint-go + lint-shell): - lint-go: gofmt -l (fail if any output) and go vet ./... - lint-shell: shellcheck --severity=error on scripts/*.sh The shell floor is set at error-level for now; the legacy make-rootfs-*.sh / make-*-kernel.sh / customize.sh scripts have warning-level findings (sudo-cat redirects, heredoc quoting) that would block landing this if we tightened immediately. Documented as tech debt in docs/kernel-catalog.md alongside a note about eventually replacing the per-distro bash with a uniform Go tool. 3. gofmt drift fixed in internal/daemon/imagemgr/build.go, session/session.go, and vm_create_ops.go (trailing newline + gofmt's preferred function-definition wrapping). Now `make lint` passes cleanly; future drift will fail CI/local lint instead of accumulating. AGENTS.md gains a one-line note on make lint. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
58 lines
3 KiB
Markdown
58 lines
3 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 ./...`.
|
|
- `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 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`.
|
|
- `scripts/publish-kernel.sh <name>` packages a locally-imported kernel and uploads it to the catalog; see `docs/kernel-catalog.md`.
|
|
|
|
## 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.
|