# Rust Foundry
Opinionated Rust bootstrapper for production-minded project setup.
`foundry` generates archetypes, applies layered config policy, and runs validation checks so new projects start with consistent defaults instead of ad-hoc scaffolding.
## v0.1 Scope
- Archetypes: `web`, `tui`, `tooling`
- Interfaces:
- `foundry` (CLI)
- `foundry-tui` (interactive)
- Commands: `plan`, `doctor`, `apply`, `explain`
- JSON contract: stable `api_version = "v1"`
Desktop/Tauri archetypes are planned for v0.2.
## Install
From crates.io (after publish):
```bash
cargo install foundry
```
From source:
```bash
git clone https://github.com/logando-al/rust-foundry.git
cd rust-foundry
cargo install --path crates/foundry --force
```
## Quick Start (CLI)
Plan files without writing:
```bash
foundry --json plan --archetype web
```
Run environment and schema checks:
```bash
foundry --json doctor --archetype web
```
Generate project (gated by `plan` + `doctor`, unless `--force`):
```bash
foundry --json apply --archetype web --force
```
Explain resolved policy and decision trace:
```bash
foundry --json explain --archetype web
```
## Quick Start (TUI)
```bash
foundry-tui
```
The TUI prompts for:
- archetype
- project name (optional explicit override)
- template engine (`handlebars` / `mini_jinja`)
- profile
- post-generation checks toggle
Then it runs `plan -> doctor -> apply`.
## Configuration
Config files:
- `foundry.toml` (project policy)
- `companion.toml` (AI/user companion policy)
Optional user-level companion path:
- `FOUNDRY_COMPANION_PATH=/path/to/companion.toml`
Profiles:
- `profiles/<profile>.toml`
### Precedence
Lowest to highest:
1. built-in defaults
2. profile defaults
3. project `foundry.toml`
4. companion config
5. explicit CLI/TUI inputs
### Example `foundry.toml`
```toml
project_name = "my-service"
archetype = "web"
template_engine = "mini_jinja"
profile = "default"
run_post_gen_checks = true
```
## Output Artifacts
`apply` writes:
- generated files (`README.md`, `Cargo.toml`, `src/main.rs`)
- `foundry.lock.json` (resolved config + artifacts)
- `audit.log` (structured JSON: config, artifacts, decision_trace)
For identical inputs, `foundry.lock.json` and `audit.log` are deterministic.
## JSON Envelope (`--json`)
All commands return:
- `api_version`
- `command`
- `status`
- `errors[]`
- `warnings[]`
- `artifacts[]`
- `checks[]`
- `resolved_config`
- `decision_trace[]`
## Validation Model
- `doctor` includes executable capability checks and schema health checks.
- `apply` post-generation checks run where feasible:
- `cargo fmt --check`
- `cargo clippy`
- `cargo check`
## Development
Run tests:
```bash
cargo test -p foundry
```
The project follows Trial Rite (TDD-first): tests first, then implementation.
## License
MIT