Files
marqdo-cli/docs/adr/0006-cli-contract.md
T
cflmy 509bdb1bf6 fix(runtime): resolve runtime errors against their logical module (B-08)
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.
2026-11-20 12:57:44 +08:00

228 lines
11 KiB
Markdown

# 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`:
```json
{"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`:
```json
{"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):
```json
{"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`:
```json
{"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. Runtime errors
from a non-entry module are covered by
`runtime_error_in_imported_module_reports_that_module` (ADR-0017).
## 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.