# Architecture
## Goals
- Provide a **cross-platform** CLI that scaffolds and updates an existing Rust crate.
- Maximize determinism by embedding templates in the Rust-Bucket binary.
- Make agentic coding reliable by generating strict conventions + automated checks.
- Support self-hosting: Rust-Bucket can update the Rust-Bucket repo itself.
## Non-goals (v1)
- No `.github/workflows` generation.
- No `.vscode` generation.
- No hook scripts (pre/post generation).
- No diff or dry-run mode.
- No workspace/multi-crate support (single crate root only).
## Key decisions
- **Template format:** Liquid.
- **Rendering engine:** the `liquid` crate used as a library, driven by values from Rust-Bucket's prompt layer.
- **Templates location:** embedded into the binary via `rust-embed`, extracted at runtime to a temp directory.
- **State file:** `rust-bucket.toml` written into the target repo.
- **Config contents (v1):** Only the test timeout value (and a version stamp comment). More fields will be added later.
- **Init overwrite policy:** refuse if any managed file exists; offer `--force` flag to override.
- **Update overwrite policy:** overwrite all managed files unconditionally.
- **Target README policy:** never touch `README.md` or `ARCHITECTURE.md` (just don't generate them).
- **Interactive prompts:** CLI-based (stdin/stdout).
- **Post-generation verification:** automatically run `cargo fmt --check`, `cargo clippy`, `cargo nextest run`.
- **Version stamping:** each managed file includes a comment at the top: `Generated by rust-bucket vX.Y.Z. DO NOT EDIT BY HAND.`
## High-level components
### 1) CLI
- `rust-bucket apply`
CLI is responsible for:
- Validating already `git init` and `cargo init`
- Collecting user choices (interactive by default)
- Loading/saving `rust-bucket.toml`
- Invoking the generator
### 2) Config (`rust-bucket.toml`)
Stores:
- persisted choices from previous `apply` runs
- template pack identifier/version
- the Rust-Bucket generator version that last updated the repo
### 3) Template Pack (embedded)
`templates/` directory in the Rust-Bucket repo is embedded at build time using `rust-embed`.
At runtime:
- extract embedded templates to a temp directory
- feed that directory into the generator
Every managed template that renders a file must stamp:
- “Generated by rust-bucket vX.Y.Z” (the running binary version)
- optionally the template pack version (if distinct)
Seed files are written without this header.
### 4) Generator (render + apply)
Render strategy:
- Use the `liquid` template engine programmatically over the extracted template directory.
- Provide values via Rust-Bucket’s prompt layer, passed to templates as Liquid globals.
Apply strategy:
- Maintain an explicit list of “managed files”.
- Ensure templates only generate that managed set.
- `init`: generate with overwrite disabled and fail fast on conflicts.
- `update`: generate with overwrite enabled to replace managed files.
#### Seed files vs managed files
Rust-Bucket distinguishes two categories of generated file, with different overwrite policies on every `apply`:
- **Managed files** (`templates::managed_files()`): owned by Rust-Bucket. They are re-rendered and **overwritten unconditionally on every apply**, so local edits to them do not survive an update.
- **Seed files** (`generator::seed_files`, registered in `templates::seed_files()`): written into the target **only if absent**, and **never overwritten on re-apply**. If a seed file already exists, it is left byte-for-byte untouched — unconditionally — so seeding is safe to repeat on every apply.
The current seed files are:
- `STYLE_GUIDE.md`
- `ratchets.toml`
`ratchets.toml` seeds the project's [`imbue-ai/ratchets`](https://github.com/imbue-ai/ratchets) configuration so the `ratchets check` gate (whose binary is installed via the devcontainer Dockerfile) has a config to read. Because it is seed-only, the project can then tune its ratchets without losing changes on the next apply.
### 5) Validation / verification
Post-generation verification should be “one command away”:
- `cargo fmt --check`
- `cargo clippy` (deny warnings)
- `cargo nextest run` with a strict global timeout
## Command flows
### `apply` first time flow
1. Assert we are in a Rust crate root (Cargo.toml present).
2. Check repo has `.git/` (or otherwise validate `git init` was done).
3. Refuse if any managed file already exists.
4. Prompt for choices.
5. Write `rust-bucket.toml`.
6. Render templates into the current directory (no overwrite).
7. Run verification commands (or print them as next steps).
### `apply` subsequent times flow
1. Load `rust-bucket.toml` and validate it.
2. Pre-answer any previous questions from the toml.
3. Ask any new questions that were not answered before.
4. Render the template pack into the current directory with overwrite enabled.
5. Refresh the generator/version stamps across managed files.
6. Run verification commands (or print them as next steps).
## Self-hosting
Self-hosting works automatically because the Rust-Bucket repo follows the same rules:
- It contains generated managed files.
- It contains templates in `templates/`.
- The CLI can run against the current crate root like any other.