Compile one hand-written WIT contract into the runtime-independent artifacts its consumers need.
witforge checks a deliberately portable WIT subset, locks protobuf field and method numbers, and generates stable Rust, protobuf, JSON Schema, glue, compatibility reports, and adapters between contract versions.
Current release: 0.5.0. The 1.0 release remains intentionally gated on successful independent consumer validation.
| Output | Purpose |
|---|---|
| Plain Rust | Owned structs, enums, interface traits, world metadata, and optional Serde derives |
| Protobuf | Messages and method IDs with append-only numbers from wire.lock |
| JSON Schema | Draft 7 definitions for WIT-shaped values |
| Rust glue | Checked conversion between plain Rust and prost-generated protobuf types |
| Version adapters | Old-to-new and new-to-old conversion between adjacent contract versions |
| Diff and diagnostics | Human, JSON, and SARIF compatibility/change reports |
Use witforge when:
- hand-written WIT is the source of truth;
- the callable contract is pure, synchronous, and value-oriented;
- native Rust and out-of-process implementations share the same values;
- protobuf identity must remain stable across releases;
- generated output is committed and checked in CI;
- contract changes need explicit compatibility review.
Use wit-bindgen and a Component Model runtime directly when you only need guest and host Component Model bindings.
witforge does not load components, generate protobuf services, own process framing, or define callbacks, retries, capabilities, resource limits, discovery, or failure policy. Direct Go source generation is not available yet; non-Rust consumers use the emitted protobuf schema, their normal language toolchain, and the documented WIT decode profile.
cargo install witforge-cli --version 0.5.0 --locked
witforge --versionPrebuilt checksum files and archives are also published for Linux x86_64, macOS Intel and Apple silicon, and Windows x86_64.
Create wit/v0.1/contract.wit:
package example:checker@0.1.0;
interface api {
record request {
text: string,
}
record diagnostic {
start: u32,
end: u32,
message: string,
}
check: func(input: request) -> list<diagnostic>;
}
world plugin {
export api;
}Lock and validate the first version:
witforge lock wit/v0.1 --first
witforge check wit/v0.1Generate the projections:
witforge rust wit --out generated/rust
witforge proto wit --out generated/proto
witforge schema wit --out generated/schema
witforge glue wit --out generated/glue \
--plain-root crate::plain \
--proto-root crate::protoEvery generator supports --check, which writes nothing and fails when committed output differs.
For the WIT above, the generated Rust module contains ordinary owned values and a trait:
pub mod api {
#[derive(Debug, Clone, PartialEq)]
pub struct Request {
pub text: ::std::string::String,
}
#[derive(Debug, Clone, PartialEq)]
pub struct Diagnostic {
pub start: u32,
pub end: u32,
pub message: ::std::string::String,
}
pub trait Api {
fn check(&self, input: Request) -> ::std::vec::Vec<Diagnostic>;
}
}The same contract becomes protobuf messages and a locked method ID:
message ApiRequest {
optional string text = 1;
}
message ApiDiagnostic {
optional uint32 start = 1;
optional uint32 end = 2;
optional string message = 3;
}
message ApiCheckRequest {
ApiRequest input = 1;
}
message ApiCheckResponse {
repeated ApiDiagnostic result = 1;
}
enum ApiMethod {
API_METHOD_UNSPECIFIED = 0;
API_METHOD_CHECK = 1;
}These excerpts are checked against current emitter output by the test suite, not hand-designed target APIs. The generated-output guide shows complete Rust, protobuf, JSON Schema, glue, and version-adapter examples with links to committed generated files.
For configuration, dependencies, evolution, and complete command sequences, continue with the documentation or the repository quickstart.
Keep each contract version in its own directory. Start a new minor as a copy of the previous version, lockfile included:
mkdir wit/v0.2
cp wit/v0.1/contract.wit wit/v0.1/wire.lock wit/v0.2/
# Edit wit/v0.2/contract.wit: set the package version to 0.2.0, then change the contract.
witforge lock wit/v0.2 --against wit/v0.1/wire.lock
witforge check wit/v0.2 --against wit/v0.1/wire.lock
witforge diff wit/v0.1 wit/v0.2Released WIT, lockfiles, dependency packages, and generated per-version Rust modules are immutable. Create a new version directory instead of editing a released one.
Add --check when CI must reject source- or generated-API-breaking changes. The evolved repository
example intentionally adds defaultable fields, so its adapters can convert old values even though
diff --check reports the source/API change.
Pin the Action to the same release used locally:
- uses: asamarts/witforge@v0.5.0
with:
check: wit/v0.2
config: witforge.toml
generators: rust,proto,schema,glue
- run: witforge diff wit/v0.1 wit/v0.2The Action downloads the matching checksum-verified release binary, leaves witforge on PATH,
and runs the configured generators with --check. The second step prints the contract diff. Add
--check to it to fail the job on a wire-, source-, or generated-API-breaking change, which
includes an added record field. The Action also has diff-old, diff-new, and diff-check
inputs; releases up to v0.5.0 ignore them. See the
CI guide.
Rust Serde and JSON Schema project the same WIT values, but they do not define one identical JSON
wire format. Rust fields are snake_case; JSON Schema preserves WIT spelling, normally kebab-case.
WIT option<T> permits null but does not make a schema property omittable.
Read JSON projections before choosing a JSON boundary.
- Documentation site
- API documentation
- Quickstart
- Single-version example
- Evolved-contract example
- Design overview
- Public API policy
- Release criteria
The first consumer is the alint plugin contract. Task-level
planning and closure evidence live under aplan/; ROADMAP.md
is the narrative sequence.
Report vulnerabilities through
GitHub private vulnerability reporting,
not a public issue. See SECURITY.md.
Licensed under either Apache-2.0 or MIT, at your option.