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

226 lines
10 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":"...","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`:
```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, 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.