Repository navigation
Add a versioned machine-readable CLI contract for agents #5
Description
Activity
This was generated by AI during triage.
Agent Brief
Category: enhancement
Summary: Provide a versioned JSON command contract for agent-facing mdcode operations.Current behavior:
List can emit newline-delimited JSON metadata only. It omits block content, locations, and stable names. Other commands expose human-oriented console output, binary data, or process exits rather than a consistent structured outcome.Desired behavior:
Every block-oriented CLI command supports one versioned JSON document per invocation. The envelope is consistent across commands: version, command, ok, result, and errors. Human-readable behavior remains available when JSON is not selected. JSON output is free of terminal formatting and progress prose.Key interfaces:
- JSON response envelope — version is the numeric contract version; command identifies the invoked command; ok indicates success; result holds command-specific data; errors is a structured array for failures.
- List result — return each block name, language, metadata, content, and source location. Names use the stable identifier semantics established by issue Add stable block identities and robust metadata syntax #16.
- Extract, update, and run results — return structured per-block actions, changes, outputs, and failures rather than requiring terminal parsing.
- Dump result — with JSON selected, require an explicit archive output path, write the tar archive there, and return a JSON manifest/outcome on stdout. Preserve binary stdout only for the existing non-JSON mode.
- CLI presentation adapter — serialize structured outcomes for JSON or format them for humans without allowing presentation/process behavior to contaminate JSON results.
Acceptance criteria:
- List produces one valid versioned JSON document containing named blocks, language, metadata, code, and source locations.
- Extract, update, run, and dump produce the common JSON envelope with command-specific result data and structured errors.
- JSON output contains no colors, progress messages, or other terminal prose.
- JSON dump writes the archive to an explicit output path and reports its manifest/outcome without encoding the archive into JSON.
- Existing non-JSON command behavior remains available.
- The response schema and representative examples are documented.
- CLI integration tests cover JSON success and failure cases for every command.
Out of scope:
- Defining or implementing block names and quoted metadata syntax; that is issue Add stable block identities and robust metadata syntax #16 and is a prerequisite.
- Position-derived identifiers.
- Editor integrations, TypeScript type-checking, or configuration workflows.
Verification status:
Confirmed: only list has partial JSON support; other commands use inconsistent presentation/output paths. This issue remains blocked by #16 until stable names are available.
What to build
Provide a consistent, versioned machine-readable output contract for mdcode commands so an LLM agent can inspect blocks and results without parsing terminal prose.
Acceptance criteria
Blocked by