Add stable block identities and robust metadata syntax #16

Activity

1. adrianbrowning

   marked this as blocked on Aug 8, 2026

   • Add a versioned machine-readable CLI contract for agents #5
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: Add stable per-document block names and robust quoted metadata values.

   Current behavior:
   Code-block metadata is parsed by splitting the info string on whitespace. Values therefore cannot contain spaces, malformed input is mostly ignored, identifiers are not validated for uniqueness, and only the run command offers partial name-based selection.

   Desired behavior:
   A Markdown code block can declare a stable name using name=. Names are unique within one Markdown document; a cross-document reference is the document path plus the name. Every block-oriented CLI command can select by that name. Metadata continues to support existing unquoted key=value values and adds double-quoted values with spaces, backslash escapes, and quote escapes.

   Key interfaces:

   • Fence metadata grammar — preserve existing unquoted values; accept name="quick start" and file="examples/getting started.ts". Inside quoted values, " represents a quote and \ represents a backslash.
   • Metadata validation — reject unterminated quoted values, invalid escape sequences, duplicate keys in a fence, and duplicate names in the same document with actionable errors.
   • Command filtering — make --name available consistently across list, extract, update, run, and dump.
   • Listing — display the declared name as block identity in human-readable output and expose it structurally for machine-readable output.

   Acceptance criteria:

   • Blocks accept an optional name metadata value as their stable identifier.
   • Every block-oriented command supports selecting by --name.
   • Duplicate names within one Markdown document fail before the selected operation runs and identify the conflicting names/locations.
   • Existing unquoted key=value metadata remains compatible.
   • Double-quoted values support spaces, escaped quotes, and escaped backslashes.
   • Unterminated quotes, invalid escapes, and duplicate metadata keys produce actionable errors.
   • Listing and documentation show the block name and selection examples.
   • Parser, command, and CLI integration tests cover successful and failing cases.

   Out of scope:

   • Requiring every block to have a name.
   • Global uniqueness across multiple Markdown documents.
   • Position-derived identifiers or automatic naming.
   • Defining the versioned JSON response envelope; that follows in issue Add a versioned machine-readable CLI contract for agents #5.

   Verification status:
   Confirmed: metadata is currently whitespace-split, names are not validated, and --name exists only for run.
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 blocked on Oct 4, 2026

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

   marked this as blocking on Oct 4, 2026

   • Add a versioned machine-readable CLI contract for agents #5
6. adrianbrowning

   added a commit that references this issue on Oct 4, 2026

   feat: stable block names and quoted metadata values

   ...

   This issue will close once commit 9748cf3 is merged into the 'main' branch.

   9748cf3
7. adrianbrowning

   closed this as completedin #31on Oct 4, 2026