# dsl-kit
An engine kit for building small, AI-native DSLs in Rust.
Write your AST as a Rust enum and derive the rest: from a few derives,
the kit supplies a schema, a text parser, a JSON front-end, a typed
builder, lints, a debugger-grade interpreter that executes the enum
directly, and an MCP surface an AI can drive. The Rust type is the
single source of truth — everything user-facing (grammar, examples,
diagnostics, tool schemas, execution) is generated from it, so none of
it can drift.
```rust
use dsl_kit::{IdGen, NodeId};
use dsl_kit_macros::{DslBuild, DslExec, DslNode, DslSchema};
#[derive(Debug, DslNode, DslSchema, DslBuild, DslExec)]
enum Expr {
#[dsl_exec(value)]
Lit { id: NodeId, value: i64 },
#[dsl_exec(apply = "add")]
Add { id: NodeId, lhs: Box<Expr>, rhs: Box<Expr> },
#[dsl_exec(branch)]
If { id: NodeId, cond: Box<Expr>, then_branch: Box<Expr>, else_branch: Box<Expr> },
}
```
That single declaration already gives you:
```rust
use dsl_kit_parse::{DslBuild as _, schema_gen};
use dsl_kit_schema::DslSchema as _;
// A grammar for a canonical text syntax, generated from the schema —
// left-recursion-free by construction and verified by static checks.
let grammar = schema_gen::checked_grammar_from_schema(&Expr::schema(), &IdGen::new())?;
// Parse canonical text, then build the typed AST back out of it.
let tree = grammar.parse("Add(lhs: Lit(value: 40), rhs: Lit(value: 2))")?;
let expr = Expr::from_parse_tree(&tree, &IdGen::new())?;
// Machine-derived examples that parse by construction — few-shot
// material for an AI writing your DSL.
let examples = dsl_kit_parse::example_gen::examples_from_grammar(&grammar)?;
```
A JSON front-end (`{"type": "Add", "lhs": ...}`) targets the same
`ParseTree`, so both surfaces share one conformance check and one typed
builder. Payload types the canonical syntax cannot spell get per-field
hooks on both sides: `schema_gen::SyntaxOverrides` for the grammar,
`#[dsl_build(with = ...)]` for the builder.
## The engine
`dsl-kit-core` interprets effect-oriented, value-bearing programs —
`Seq` / `Par` / `Call` / `Scope` / `Maybe` for orchestration, `Apply` /
`Branch` / `Bind` / `Read` / `Loop` / `Lit` for computation — with the
runtime mechanics a real host needs:
- **Structured fan-out**: `Par` with join policies (`All` / `Any` /
`FirstK`, fail-fast or collect-all) folded by pluggable reducers.
- **Suspend / resume**: every `Call` yields a suspension the host
resolves with `Ok(value)` or `Err(effect_error)`; cancellation is
cooperative and observable.
- **Debugger-grade breakpoints**: every spawn passes through one
schedule, so a breakpoint halts *before* the matched frame spawns —
at any depth, including mid-`Par`-cascade — and the frame tree
faithfully exposes the partially spawned state.
- **Sans-io drive layer**: `drive` (sync) and `drive_async` (any
executor; the core has zero runtime dependencies) run the
resolve loop for you when you don't want to hand-roll it.
- **Value semantics, interpreted**: `Apply` folds evaluated children
through a registered op, `Branch` selects on a value (the untaken
side never spawns), `Bind` / `Read` carry a lexical env chain,
`Loop` respawns its body per iteration — all inside the same frame
machinery, so breakpoints halt on branch selection and on every
loop iteration, and an unbound `Read` suspends like any other
effect. You register what `"add"` *means*; the engine does the
rest. No hand-written eval loop — `expr-example` runs entirely on
the engine.
## MCP: let an AI debug your DSL
`dsl-kit-mcp` wraps any `DslHost` in a stdio MCP server with a
debugger-style tool surface: `load`, `ast`, `step` (one / to-yield /
to-done), `breakpoint add/list/remove`, `state`, `pending`, `resolve`,
`schema`, `lint`, `explain`. The `custom-mcp-example` shows how to ship
your own DSL as its own MCP server binary.
## Crates
| `dsl-kit` | facade — re-exports the kit surface |
| `dsl-kit-core` | engine: frames, fan-out, cancellation, events, breakpoints, drive |
| `dsl-kit-macros` | `#[derive(DslNode)]` / `#[derive(DslSchema)]` / `#[derive(DslBuild)]` / `#[derive(DslExec)]` |
| `dsl-kit-schema` | type-level schema consumed by parsers, editors, AI clients |
| `dsl-kit-parse` | `ParseTree`, conformance, JSON bridge, PEG interpreter, grammar generation, example synthesis |
| `dsl-kit-lint` | walk-driven, schema-aware, author-extensible lints |
| `dsl-kit-mcp` | stdio MCP framework over any `DslHost` |
## Examples
```sh
cargo run -p expr-example # expression DSL: text + JSON round trips, schema-generated grammar
cargo run -p flow-example # orchestration DSL: fan-out, value-gated Branch, breakpoints, drive layer, text round trip
```
The examples double as reference implementations: `flow-dsl` shows the
per-field hooks on a DSL with exotic payload types, `expr-dsl` shows
the plain derive-only path end to end.
## Documentation
API documentation is the source of truth and is written to be read:
```sh
cargo doc --open
```
## Status
`0.1.0` — the kit is young and the API is still moving. The engine
semantics (fan-out, cancellation, halt-before-spawn breakpoints) and
the derive contracts are test-pinned; surface ergonomics may change
between minor versions.
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option.
Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the
Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.