Add a versioned machine-readable CLI contract for agents #5

Activity

1. adrianbrowning

   marked this as blocking 5 issues on Aug 8, 2026

   • Add plan, diff, apply, and check workflows for agent-driven sync #6
   • Publish an agent integration guide and workflow examples #8
   • Expose mdcode as typed MCP tools for LLM agents #9
   • Add stable block identities and robust metadata syntax #16
   • Consolidate the public library interface and CLI adapter #19
2. adrianbrowning commented on Aug 8, 2026

   

   adrianbrowning

   on Aug 8, 2026

   OwnerAuthor

   More actions

   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.
3. adrianbrowning

   added

   enhancementNew feature or requestNew feature or request

   ready-for-agentFully specified and ready for an AFK agentFully specified and ready for an AFK agent

   on Aug 8, 2026
4. adrianbrowning

   unmarked this as blocking on Oct 4, 2026

   • Add stable block identities and robust metadata syntax #16
5. adrianbrowning

   marked this as blocked on Oct 4, 2026

   • Add stable block identities and robust metadata syntax #16
6. adrianbrowning

   marked this as blocking 2 issues on Oct 4, 2026

   • Harden mdcode operations for untrusted Markdown and agent execution #7
   • Add validation and duplicate-target protection before writes #15
7. adrianbrowning

   closed this as completedin ff056e4on Oct 4, 2026