# Development

> Build, test, and extend the Exploitmatic runtime.

## Layout

```
crates/exploitmatic-core/   the library: model, parse, validate, lint,
                            assert, transport, engine, oob, crypto
crates/exploitmatic/        the GUI (Tauri desktop app) and the CLI binary
                            (run / lint / check / mcp)
crates/exploitmatic-grammar/ generated ANTLR Rust parser (ExploitmaticLex.g4,
                            Exploitmatic.g4)
crates/exploitmatic/assets/workbench/
                            the workbench SPA the desktop app loads
                            (Vite + shadcn/ui, built to assets/workbench/dist)
grammar/                    the ANTLR grammar + generate.ps1 (Rust target)
examples/                   examples and demos (host scope + protocol demos)
```

## Build and test

From the `cli` directory:

```sh
cargo build --release                # the exploitmatic binary (CLI)
cargo build --release --features desktop --bin exploitmatic   # the GUI (Tauri)
cargo test --workspace               # unit + integration + corpus tests
cargo clippy -- -- -D warnings
cargo fmt --all -- --check
```

## The grammar and check

`grammar/Exploitmatic.g4` and `grammar/ExploitmaticLex.g4` are the formal
ANTLR grammar for the `.txt` language. The grammar validates structure and
line-start keyword recognition; the English directive sentences are parsed by
the runtime and re-parsed by the semantic pass in `exploitmatic check`, which
runs the same rules the engine enforces. Regenerate the generated parser from
`cli/grammar`:

```sh
cargo install antlr-rust-codegen   # provides antlr4-rust-gen
.\generate.ps1                     # regenerates crates/exploitmatic-grammar/src
```

Validate any solution file on the command line:

```sh
cargo run -p exploitmatic -- check <solution.txt>
```

The desktop GUI (`cargo run -p exploitmatic --features desktop`) and the MCP
server (`cargo run -p exploitmatic -- mcp`) expose the same public runtime API
(parse, validate, run) to other tools. The GUI hosts the workbench SPA in a
native window and runs an MCP server in-app; the CLI reaches the same API with
`run`, `lint`, `check`, and `mcp` subcommands.

## Design constraints

- Solutions are data, never code. The corpus has no arbitrary-code supply chain: no template engine, no injected interpreter.
- Rust is the runtime language: one static musl binary, a small audited crate set.
- Plain text solutions, no YAML: the format is line-based, validated at load, and there are no YAML aliases, anchors, or YAML CVEs.
- The runtime prints the request and response and the test that ran, but never stores a result: the result always comes from the tests.
- LLM-friendly by design: a closed eighteen-protocol grammar, a deterministic runtime, parse errors with line numbers, and stable result lines. Natural language is an authoring aid in front of the tool, never an input to the runtime.

## Roadmap

- M2: incident-derived corpus entries.
- M3: replay-all(scope): run the whole corpus against a target, return only verified findings.
- M4: model-agnostic surface (tool/MCP) so any agent calls replay().
- M5: incident-ingestion pipeline: published timelines become verified corpus entries.