Provide a CI example for validating runnable Markdown snippets #12

Activity

1. adrianbrowning

   added a parent issue on Aug 8, 2026

   • Add reusable CI/CD workflows for synchronized documentation #10
2. adrianbrowning

   marked this as blocking on Aug 8, 2026

   • Gate package releases on mdcode documentation and example checks #13
3. 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 copyable CI recipe for extracting intentionally runnable snippets into an isolated workspace and validating them.

   Current behavior:
   The run command writes one temporary file per block and invokes a caller-provided shell command, but it does not supply a reusable extracted-workspace CI example. No public metadata convention identifies which Markdown snippets are intended to be runnable.

   Desired behavior:
   Consumers can mark intentionally runnable code fences with runnable=true, extract only those fences into a newly created isolated workspace, and invoke a trusted, configurable validation command against that workspace. Validation failures fail CI and identify the affected snippets or generated files. Temporary output is reliably cleaned up.

   Key interfaces:

   • Runnable metadata convention — runnable=true selects only code blocks intended for execution or validation.
   • Isolated workspace — create a fresh temporary output directory outside source files, extract selected blocks there, and clean it up on success or failure.
   • Validation command — accept a consumer-supplied command as trusted CI configuration; Markdown metadata must not provide a command to run.
   • Diagnostics — report generated file paths and validation failures so a consumer can trace failures back to the source Markdown blocks.
   • CI examples — provide local-shell and GitHub Actions recipes that can be adapted to language-specific lint or test commands.

   Acceptance criteria:

   • A documented example selects only runnable=true blocks.
   • It extracts selected blocks into a newly created isolated workspace.
   • It runs a configurable, trusted validation command against the extracted files.
   • Validation failures return a non-zero status and identify the failing generated file or block.
   • The temporary workspace is cleaned up safely after success and failure.
   • Documentation explains the runnable=true convention and trust boundary.
   • Tests cover selection, successful validation, validation failure, and cleanup.

   Out of scope:

   • Treating all code fences as independently runnable by default.
   • Type-checking arbitrary snippets or providing editor diagnostics.
   • Executing a command specified by Markdown metadata.
   • Release gating, which is issue Gate package releases on mdcode documentation and example checks #13.

   Verification status:
   Confirmed: current run behavior is per-block and console-oriented; no extracted-workspace CI example or runnable metadata convention exists. This issue is blocked by #7.
4. 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
5. adrianbrowning

   marked this as blocked on Oct 4, 2026

   • Harden mdcode operations for untrusted Markdown and agent execution #7
6. adrianbrowning

   marked this as blocking on Oct 4, 2026

   • Add reusable CI/CD workflows for synchronized documentation #10
7. adrianbrowning

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

   feat(ci): ready-to-copy script to validate runnable=true snippets (#12)…

   ...

   729820a
8. adrianbrowning

   closed this as completedin #40on Oct 4, 2026