|
| 1 | +# CLAUDE.md — arazzo-cli |
| 2 | + |
| 3 | +Standalone Arazzo 1.0 workflow executor (Rust-only on `main`). |
| 4 | + |
| 5 | +## Build & Test |
| 6 | + |
| 7 | +```bash |
| 8 | +cargo fmt --all -- --check |
| 9 | +cargo clippy --workspace --all-targets --all-features -- -D warnings |
| 10 | +cargo test --workspace |
| 11 | +cargo audit |
| 12 | +``` |
| 13 | + |
| 14 | +## Workspace Structure |
| 15 | + |
| 16 | +```text |
| 17 | +crates/ |
| 18 | + arazzo-spec Typed Arazzo model |
| 19 | + arazzo-validate YAML parse + validation |
| 20 | + arazzo-expr Expression parser/evaluator |
| 21 | + arazzo-runtime Engine, HTTP execution, control flow |
| 22 | + arazzo-cli CLI commands |
| 23 | + arazzo-mcp MCP server (Model Context Protocol) for AI agents |
| 24 | + arazzo-debug-protocol Internal JSON-line debug protocol types |
| 25 | + arazzo-debug-adapter Full DAP (Debug Adapter Protocol) implementation |
| 26 | +vscode-arazzo-debug/ VS Code extension for Arazzo debugging |
| 27 | + src/ TypeScript extension source |
| 28 | + bin/ Bundled debug adapter binary (copied from target/release) |
| 29 | + dist/ Compiled extension JS |
| 30 | + package.json Extension manifest + debugger contribution |
| 31 | +examples/ Sample Arazzo specs |
| 32 | +testdata/ Fixtures used by tests |
| 33 | +``` |
| 34 | + |
| 35 | +## VS Code Extension |
| 36 | + |
| 37 | +The debugger extension lives at `vscode-arazzo-debug/`. To rebuild and install: |
| 38 | + |
| 39 | +```bash |
| 40 | +cargo build --release -p arazzo-debug-adapter # Build the adapter binary |
| 41 | +cd vscode-arazzo-debug && npm run build # Compile TypeScript |
| 42 | +npx @vscode/vsce package --no-dependencies # Package VSIX (copies binary automatically) |
| 43 | +code --install-extension arazzo-debug-0.0.1.vsix --force # Install into VS Code |
| 44 | +``` |
| 45 | + |
| 46 | +After installing, reload VS Code. The extension registers the `arazzo` debug type. |
| 47 | +Debug adapter diagnostics go to stderr (visible in VS Code's Output > Arazzo Debug panel). |
| 48 | + |
| 49 | +## Architecture Notes |
| 50 | + |
| 51 | +- Runtime interpretation only (no codegen) |
| 52 | +- Typed expression evaluation across `$inputs`, `$steps`, and response context |
| 53 | +- Spec-driven control flow via `onSuccess` / `onFailure` |
| 54 | +- Optional dry-run request planning and trace hooks |
| 55 | +- Unsafe code is forbidden across the workspace |
| 56 | + |
| 57 | +## CLI Principles |
| 58 | + |
| 59 | +- Every command supports `--json` |
| 60 | +- Human-readable output stays available by default |
| 61 | +- Structured error JSON when `--json` is set |
| 62 | +- Commands: `run`, `replay`, `validate`, `list`, `steps`, `catalog`, `show`, `generate`, `schema`, `serve` |
| 63 | + |
| 64 | +## Conventions |
| 65 | + |
| 66 | +- Keep behavior generic (no app-specific logic) |
| 67 | +- Keep tests hermetic and deterministic |
| 68 | +- Prefer compile-time checks and explicit types over dynamic behavior |
| 69 | + |
| 70 | +## Expression Surface |
| 71 | + |
| 72 | +- `$inputs.name` |
| 73 | +- `$steps.<id>.outputs.<name>` |
| 74 | +- `$env.VAR_NAME` |
| 75 | +- `$statusCode` |
| 76 | +- `$method` |
| 77 | +- `$response.header.Name` |
| 78 | +- `$response.body.path` |
| 79 | +- `$response.body#/json/pointer` (RFC 6901) |
| 80 | +- `$outputs.name` (workflow outputs map, inside `workflow.outputs` only) |
| 81 | +- `$outputs.name#/json/pointer` |
| 82 | +- `$url` |
| 83 | +- `$request.header.Name` |
| 84 | +- `$request.query.Name` |
| 85 | +- `$request.path.Name` |
| 86 | +- `$request.body` / `$request.body.path` / `$request.body#/pointer` |
| 87 | +- `$sourceDescriptions.{name}.url` |
| 88 | +- `{$expr}` interpolation in string values |
| 89 | +- `{sourceName}./path` operationPath routing (multiple source descriptions) |
| 90 | +- `//xpath` |
| 91 | + |
| 92 | +## Quick Smoke |
| 93 | + |
| 94 | +```bash |
| 95 | +cargo run -p arazzo-cli -- validate examples/httpbin-get.arazzo.yaml |
| 96 | +cargo run -p arazzo-cli -- run examples/httpbin-get.arazzo.yaml get-origin |
| 97 | +cargo run -p arazzo-cli -- --json catalog examples |
| 98 | +``` |
0 commit comments