Complete the documentation set for the M0.5 toolchain, grounded in the code: - spec/references.md: import/reference/call edges, identities, loader rules, anchors, `ref` resolution/ambiguity, `check --refs` validation. - spec/value-wire.md: exact wire_version 1 typed encoding, integer-as-decimal string rule, special floats, limits and exact float round-trip. - spec/security.md: modes (strict refuses without OS isolation), capabilities, path rules, budgets, tracing, foreign process caveats, plugin trust. - spec/package-format.md: marqdo.yaml/lock formats, validation, lock/sync, unsupported registry/git/environment work. - spec/plugin-abi.md: ABI v1 layout/ownership/negotiation, manifest/artifact rules, wire envelopes, loader lifecycle, trust boundary, SDK/C demo, and the implemented CLI plugin-invocation flow with its limitations. - spec/math.md and spec/foreign.md: the implemented math subset and the foreign request/response/timeout/capability contract. - docs/adr/0001..0007: accepted decisions for the span foundation, inert executables outside function bodies, ref ambiguity (S-07), strict refusal, AST normalization, CLI contract and BigInt/typed wire (S-08). - docs/contributor-guide.md: repo map, workflow, fixture/golden updates, quality gate, ADR/commit policy. - docs/STATUS.md: P0-P7 matrix with evidence, open items and the blueprint §18 Alpha checklist (conclusion: not yet Alpha-complete), including known divergences rather than overclaims. - README.md rewritten from "design-only starter" to the working implementation with quickstart, implemented phases, deliberate limits and doc index. - AGENTS.md: updated pointers/workflow only; architectural rules unchanged. - Consistency fixes in spec/mapping.md/evaluation.md (inert emph outside functions, unsupported math.simplify/differentiate).
10 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":"...","message":"...","span":{"line":..,"column":..,"file":..}, "frames":[...]},"trace":[...]}. Runtime error spans are currently resolved
against the entry file only, even when the error came from an imported
module; frames carry function names, not module ids. This is a known precision
limitation.
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, and runtime error span from a non-entry module before calling the schema "final".
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.