RuntimeError and CallFrame now carry a logical ModuleId and an origin (source/callsite). Errors are attributed at function/body boundaries so the innermost callee module wins; argument-binding errors and host/plugin/foreign boundaries are attributed to the caller callsite without fabricating a foreign stack. The CLI resolves (module_id, span) through LoadedProject::locate instead of indexing every span against the entry file. Unknown modules and out-of-range spans keep the module id and byte span but emit null line/file. Human output and frames now point at the correct file. Record the decision in ADR-0017 and supersede the ADR-0006 limitation. Add an end-to-end imported-module division-by-zero test.
11 KiB
ADR-0006: CLI output, exit-code and JSON contract
Status: Accepted Date: 2026-11-20
Context
CI, scripts and coding agents need a stable CLI contract, not just human
output. The blueprint (§12) requires: all commands available with --json,
non-zero error exit codes, program stdout kept separate from diagnostics, and
machine-readable error codes. The implemented CLI must be documented precisely
because scripts will depend on stream separation and exit status.
Implementation: crates/cli/src/main.rs (clap definitions, process exit),
crates/cli/src/commands.rs (behavior), crates/cli/src/output.rs
(diagnostic/JSON rendering), crates/cli/src/args.rs (--arg constants).
Decision
1. Commands and flags (implemented surface)
| Command | Arguments / flags | What it does |
|---|---|---|
init [dir] |
— | create marqdo.yaml, index.mq.md, .gitignore; refuses an existing manifest |
run [file] |
--mode, --allow-read, --allow-write, --allow-foreign, --allow-plugin, --fuel, --stack, --max-output, --timeout, --plugin, --trust-native-plugin, --json, --trace |
execute main (or default index.mq.md) |
call <file> <function> |
--arg NAME=VALUE (repeatable) plus all run flags |
execute one named function |
check [file] |
--json |
static check; never executes |
inspect [file] |
--ast, --units, --signature, --ir, --refs, --platform, --json |
static inspection; never executes |
fmt [file] |
--check |
normalize CRLF and trailing newlines |
plugin inspect <dir-or-yaml> |
--json |
validate manifest + verify artifact hash; never loads code |
add <name> |
--path, --git, --rev, --json |
edit marqdo.yaml |
remove <name> |
--json |
edit marqdo.yaml (and prune a stale lock entry) |
lock |
--json |
write deterministic marqdo.lock |
sync |
--locked, --json |
verify the lock is current |
There is no test, tree, update, vendor, add for plugins, kernel
command or --project/--offline flag in this build. run defaults the
file to index.mq.md; check/inspect/fmt do too. call requires an
explicit file path plus a function name.
--mode is only on run/call and accepts pure|project|strict
(default project). --trust-native-plugin/--plugin are only meaningful on
run/call. inspect --platform still requires a document argument (or
defaults to index.mq.md), because project loading happens first.
2. Exit codes
| Code | Meaning |
|---|---|
0 |
success (for check: no error diagnostics; warnings do not fail) |
1 |
a checked document has errors; a runtime/security failure; strict refusal; plugin load/inspect failure; lock/sync mismatch; fmt --check would reformat; init found an existing manifest; add duplicate; remove missing dependency; sync stale lock |
2 |
usage error (clap), unreadable entry file, invalid --mode name, invalid capability combination (e.g. --allow-read in pure), invalid --arg value, unreadable manifest for project commands, unreadable file for fmt |
Codes are stable contract. Diagnostic codes (for example
markdown.invalid_construct, expr.parse, symbol.unknown,
permission.denied, ref.ambiguous) are stable; message wording is not.
3. Stream separation
- Program output (
打印/print) goes to stdout in text mode. In JSON mode it is embedded as thestdoutstring; it is never interleaved with JSON. - Diagnostics and effect traces go to stderr in text mode.
runin text mode writes only program output to stdout (no implicit return value).callin text mode additionally prints the returned value (usingValue::display) when it is notUnit.checktext mode: diagnostics to stderr;checked N module(s): okto stdout on success; acheck failed: ...summary to stderr on failure.inspectprints pretty JSON-ish structures to stdout; load errors to stderr.- JSON mode prints exactly one pretty JSON object to stdout per invocation.
add/remove/lock/syncstill print errors as plainerror: ...on stderr even with--json(JSON success envelope only) — an inconsistency to fix before the contract is declared final.
4. JSON output shapes
check:
{"command":"check","success":true,"errors":0,
"diagnostics":[{"file":"index.mq.md","module":"index.mq.md",
"line":3,"column":5,"severity":"error","code":"expr.parse",
"message":"...","hints":["..."]}]}
inspect:
{"command":"inspect","module":"index.mq.md",
"ast":{...},"units":[...],"signatures":[...],"ir":[...],
"refs":[...],"platform":{...}}
Only the requested sections are present. With no section flags, a summary
with modules, functions, units, resources is emitted instead.
run/call (success):
{"command":"run","success":true,
"value":{"type":"text","value":"..."},
"stdout":"program stdout text",
"trace":[{"op":"print","module":"index.mq.md",
"span":{"start":43,"end":57},"duration_micros":3,"result":"ok"}]}
Note: call --json also emits "command":"run" in this build (shared
implementation). Consumers should accept both names or key on the presence of
diagnostics/value; this is a known quirk.
run/call (failure): {"command":"run","success":false,"stdout":..., "error":{"code":"...","origin":"source|callsite","module_id":"...", "span":{"start":..,"end":..},"line":..,"column":..,"file":.., "frames":[...]},"trace":[...]}. Runtime locations are resolved against the
logical module that produced the error (ADR-0017); there is no entry-file
fallback. Unknown modules or invalid spans leave line/column/file null while
keeping the module id and byte span.
plugin inspect:
{"command":"plugin.inspect","success":true,"plugin":"demo.solver",
"version":"0.1.0","abi":"^1.0","abi_compatibility":"compatible",
"target":"x86_64-unknown-linux-gnu",
"artifact":{"file":"solver.so","path":"...","sha256":"...","verified":true},
"exports":[{"name":"solver.add","signature":"($a: Int, $b: Int) -> Int"}],
"loaded":false}
load_project failures with --json print {"success":false,"error":"..."}
without a command field.
There is no json_schema_version field yet. The blueprint asks for a
versioned JSON schema; until it exists, treat these keys as the stable subset
and ignore unknown keys. Adding keys is not considered breaking; renaming or
removing one is.
5. --arg values
--arg NAME=VALUE parses VALUE with the expression grammar restricted to
constants (crates/cli/src/args.rs): integers, floats, double-quoted text
(escapes supported), true/false/None, lists, records, and unary -/+
over constants. Calls and identifiers are rejected ("must be a literal
constant"). Text must be double-quoted; there is no bare-word fallback.
6. Determinism and safety of read-only commands
check/inspectnever execute project code (ADR context; seespec/security.md§7).plugin inspectnever loads plugin code.fmtonly rewrites the file when not--check; exit 1 when--checkdetects a difference.
Alternatives
- Use exit code 1 for all failures. Rejected: scripts need to distinguish usage errors (2) from document/runtime failures (1); it also mirrors common CLI conventions and clap's own usage exit code.
- Print JSON even for usage errors. Rejected for now: clap owns usage output before our code runs; wrapping it would mean intercepting clap errors. Documented as a limitation.
- Interleave program output and JSON. Rejected: it makes JSON unparseable. Program stdout is embedded as a string instead.
- Return values from
runon stdout in text mode. Rejected:runis the batch entry; implicit value printing would pollute program output.callprints the return value exactly when non-Unit. - Human-only messages with numeric exit codes only. Rejected: diagnostics and runtime errors have stable machine codes in both text and JSON.
Markdown AST shape
The CLI itself does not change the AST. What it exposes:
inspect --ast= canonicalMdNodetree (see ADR-0005);inspect --units=UnitInfo[](marqdo-ir);inspect --signature={name, local_name, signature: explicit|inferred, params:[{name,type,has_default}]};inspect --ir=Function[]withStmt/Exprand spans;inspect --refs= link edge array (spec/references.md§4);inspect --platform=PlatformCapabilitiesJSON.
Compatibility
- Exit codes, stream separation and the documented JSON keys are the public CLI contract. Changing them requires this ADR to be superseded and a changelog entry.
- The old "design-only starter" README listed planned commands (
add,lock && sync,plugin inspect); all listed commands except a versioned JSON schema are now implemented as described here. - Diagnostic code renames are breaking for CI; message changes are not.
- No package/ABI/wire changes.
Security
--json/--traceenable effect tracing; traces contain op/module/span/ duration/result summary, never argument values (no secrets) — seespec/security.md§4.- JSON mode embeds program stdout, which is program-controlled data; consumers must not treat it as trusted.
- Refusing to run with compile errors happens before host creation, so JSON failure output cannot leak effects.
- Strict-mode refusal and capability denials produce stable codes for CI.
Testing
- CLI behavior is currently covered by manual smoke checks and library-level
tests; the fixtures workstream is adding CLI integration tests under
crates/cli/tests(goldens/negative cases) andtests/. crates/cli/src/args.rsunit tests cover typed--argparsing and rejection of non-constant values.crates/cli/src/output.rshas no unit tests; diagnostic JSON is exercised through check/run smoke tests.- Add contract tests for: exit codes per failure class, stdout/stderr
separation, JSON key presence,
call --jsoncommand naming. Runtime errors from a non-entry module are covered byruntime_error_in_imported_module_reports_that_module(ADR-0017).
Migration & rollout
- Keep the current shapes stable while adding tests.
- Add a
schema_versionto JSON envelopes and document the versioned schema; then document that unknown keys may be added (forward compatible) while existing keys are frozen. - Fix the
call --json"command":"run"quirk and JSON errors inadd/remove/lock/sync; both are additive/corrective and should be announced in the changelog. - If a command is renamed or an exit code changes, update this ADR, the
README quickstart,
docs/STATUS.mdand CI scripts in the same change.