Files
marqdo-cli/docs/adr/0006-cli-contract.md
T
cflmy 0116160399 docs: formal specs, ADRs, STATUS matrix, contributor guide and honest README
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).
2026-11-20 10:56:26 +08:00

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 the stdout string; it is never interleaved with JSON.
  • Diagnostics and effect traces go to stderr in text mode.
  • run in text mode writes only program output to stdout (no implicit return value). call in text mode additionally prints the returned value (using Value::display) when it is not Unit.
  • check text mode: diagnostics to stderr; checked N module(s): ok to stdout on success; a check failed: ... summary to stderr on failure.
  • inspect prints 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/sync still print errors as plain error: ... 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/inspect never execute project code (ADR context; see spec/security.md §7).
  • plugin inspect never loads plugin code.
  • fmt only rewrites the file when not --check; exit 1 when --check detects a difference.

Alternatives

  1. 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.
  2. 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.
  3. Interleave program output and JSON. Rejected: it makes JSON unparseable. Program stdout is embedded as a string instead.
  4. Return values from run on stdout in text mode. Rejected: run is the batch entry; implicit value printing would pollute program output. call prints the return value exactly when non-Unit.
  5. 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 = canonical MdNode tree (see ADR-0005);
  • inspect --units = UnitInfo[] (marqdo-ir);
  • inspect --signature = {name, local_name, signature: explicit|inferred, params:[{name,type,has_default}]};
  • inspect --ir = Function[] with Stmt/Expr and spans;
  • inspect --refs = link edge array (spec/references.md §4);
  • inspect --platform = PlatformCapabilities JSON.

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/--trace enable effect tracing; traces contain op/module/span/ duration/result summary, never argument values (no secrets) — see spec/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) and tests/.
  • crates/cli/src/args.rs unit tests cover typed --arg parsing and rejection of non-constant values.
  • crates/cli/src/output.rs has 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 --json command naming, and runtime error span from a non-entry module before calling the schema "final".

Migration & rollout

  1. Keep the current shapes stable while adding tests.
  2. Add a schema_version to JSON envelopes and document the versioned schema; then document that unknown keys may be added (forward compatible) while existing keys are frozen.
  3. Fix the call --json "command":"run" quirk and JSON errors in add/remove/lock/sync; both are additive/corrective and should be announced in the changelog.
  4. If a command is renamed or an exit code changes, update this ADR, the README quickstart, docs/STATUS.md and CI scripts in the same change.