Thales Maciel
fa95849f5a
Manual publish flow for the kernel catalog, designed for the current no-CI, private-repo state of banger. scripts/publish-kernel.sh <name>: - Reads $BANGER_KERNELS_DIR/<name>/ (the canonical layout produced by `banger kernel import`). - Pulls distro / arch / kernel_version from the local manifest. - Packages vmlinux + optional initrd.img + optional modules/ as <name>-<arch>.tar.zst with zstd -19. - Computes sha256 + size. - rclone copyto -> r2:banger-kernels/<file>. - HEAD-checks https://kernels.thaloco.com/<file> to catch public-access misconfig before declaring success. - jq-patches internal/kernelcat/catalog.json: replaces any prior entry with the same name, then sorts entries by name. - Prints next-step git+make commands; does not commit or rebuild automatically. Environment overrides RCLONE_REMOTE / RCLONE_BUCKET / BASE_URL / BANGER_KERNELS_DIR for non-default setups. docs/kernel-catalog.md covers the architecture (embedded JSON + external tarballs), end-user flow, the add/update/remove playbook, naming and tarball-layout conventions, the trust model (sha256 in embedded catalog catches transport/swap; no signing yet), and where the bucket lives. README.md gains a kernel-catalog example next to the existing image register example. AGENTS.md points at publish-kernel.sh and the docs. .gitignore now excludes .env so accidental drops of R2 credentials don't follow into commits. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
57 lines
2.9 KiB
Markdown
57 lines
2.9 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`.
|
|
- `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.
|