# 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.
- **Scaffolding engine:** `cargo-generate` used as a library, driven by Rust-Bucket prompts.
- If we encounter consistent problems with cargo-generate as a library, create a bead to read the cargo-generate source code and summarize its programmatic API for future subagents in an `.md` file.
- **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 generated 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 an asset-embedding crate (e.g., `include_dir` or `rust-embed`).
At runtime:
- extract embedded templates to a temp directory
- feed that directory into the generator
Every 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)
### 4) Generator (render + apply)
Render strategy:
- Use `cargo-generate` programmatically with a local template path.
- Provide values via Rust-Bucket’s prompt layer (not cargo-generate’s prompts).
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.
### 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.