# Forge Gen — Unified Code Generator from OpenAPI Specs
> **★★★ CSE / Knowable Construction.** This repo operates under **Constructive Substrate Engineering** — canonical specification at [`pleme-io/theory/CONSTRUCTIVE-SUBSTRATE-ENGINEERING.md`](https://github.com/pleme-io/theory/blob/main/CONSTRUCTIVE-SUBSTRATE-ENGINEERING.md). The Compounding Directive (operational rules: solve once, load-bearing fixes only, idiom-first, models stay current, direction beats velocity) is in the org-level pleme-io/CLAUDE.md ★★★ section. Read both before non-trivial changes.
<!-- Blackmatter alignment: pillars 3, 12 -->
<!-- See ~/code/github/pleme-io/BLACKMATTER.md for pillar definitions. -->
## Blackmatter pillars upheld
- **Pillar 3** (API generation): Forge Gen IS Pillar 3. One OpenAPI spec → SDKs (Rust/Go/Python/JS/Java/Swift) + gRPC proto + GraphQL schema + REST server + MCP server + IaC (Pangea/Terraform/Pulumi/Crossplane/Ansible) + completions + docs. Never hand-write two copies of the same schema.
- **Pillar 12** (Generation over composition): the unified `--iac`, `--sdks`, `--servers`, `--mcp`, `--completions`, `--schemas`, `--docs` flags make "can this be generated?" the first question for every API surface.
## Build & Test
```bash
cargo build
cargo test # 257 tests
cargo run -- generate --spec openapi.yaml --sdks rust,go --mcp mcp-rust
cargo run -- list # show all registered generators
cargo run -- list --category completion # filter by category
```
## Architecture
Unified CLI orchestrating multiple code generation backends from a single OpenAPI spec.
Invokes external tools (openapi-generator-cli, iac-forge, mcp-forge, completion-forge) in parallel.
### Generator Categories
| Category | Backend Tool | Generators |
|----------|-------------|------------|
| **SDK** | openapi-generator-cli | go, python, javascript, typescript (+4 variants), java, ruby, csharp, rust, kotlin, swift, dart, php, perl, elixir, scala, haskell, c, cpp, lua, r, ocaml, clojure, elm, powershell, bash (28 targets) |
| **Server** | openapi-generator-cli | go-server, python-fastapi, rust-axum, spring, kotlin-spring (5 targets) |
| **Schema** | openapi-generator-cli | graphql-schema, protobuf-schema, mysql-schema, postgresql-schema (4 targets) |
| **Doc** | openapi-generator-cli | markdown, html, asciidoc, plantuml (4 targets) |
| **IaC** | iac-forge | terraform, pulumi, crossplane, ansible, pangea, steampipe (6 targets) |
| **Helm** | iac-forge | helm (1 target) |
| **MCP** | mcp-forge | mcp-rust (Rust MCP server with rmcp 0.15) |
| **Completion** | completion-forge | skim-tab (YAML), fish (shell completions) |
### Modules
| Module | Purpose |
|--------|---------|
| `commands/generate.rs` | `TaskRunner` trait + `execute_task()`, parallel/sequential dispatch via `JoinSet` |
| `commands/list.rs` | List all registered generators with categories |
| `commands/init.rs` | Create starter `forge-gen.toml` manifest |
| `commands/validate.rs` | Parse and summarize OpenAPI spec |
| `manifest.rs` | `forge-gen.toml` manifest loading + CLI merge, `HasTargets` trait for generic CSV parsing |
| `registry.rs` | Static generator registry (51 generators across 8 categories), `Category` with `FromStr + Display` |
### CLI Flags
```
--spec <path> OpenAPI spec (YAML or JSON)
--output <dir> Output directory (default: ./generated)
--sdks <list> Comma-separated SDK targets or "all"
--servers <list> Comma-separated server targets or "all"
--iac <list> Comma-separated IaC backends or "all"
--helm <list> Comma-separated Helm targets or "all"
--mcp <list> Comma-separated MCP targets or "all"
--mcp-name <name> Project name for MCP generation
--completions <list> Comma-separated completion formats or "all"
--completion-name <name> CLI command name for completion generation
--schemas <list> Comma-separated schema targets or "all"
--docs <list> Comma-separated doc targets or "all"
--manifest <path> Path to forge-gen.toml (default: ./forge-gen.toml)
--parallel Run generators in parallel (default: true)
```
### Manifest (`forge-gen.toml`)
```toml
[spec]
path = "openapi.yaml"
[output]
dir = "./generated"
[sdks]
targets = ["go", "rust", "typescript"]
[mcp]
targets = ["mcp-rust"]
name = "my-api"
[iac]
backends = ["terraform", "pulumi"]
[completions]
targets = ["skim-tab", "fish"]
name = "my-tool"
icon = "☁"
grouping = "auto" # auto, tag, path, or operation-id
aliases = ["mt"]
```
## Design Decisions
- **External tool dispatch** — does NOT embed generators; invokes `openapi-generator-cli`, `iac-forge`, `mcp-forge`, `completion-forge` as subprocesses
- **Parallel by default** — JoinSet-based concurrent execution
- **TaskRunner trait** — single `execute_task()` eliminates boilerplate across 5 generator types
- **HasTargets trait** — generic `parse_csv_or<T>()` replaces 5 duplicated CSV parsers
- **Registry is static** — all generators known at compile time (51 total across 8 categories)
- **Nix build** — substrate `rust-tool-release-flake.nix` pattern