Consolidate the public library interface and CLI adapter #19

Activity

1. adrianbrowning

   marked this as blocked by 2 issues on Aug 8, 2026

   • Add a versioned machine-readable CLI contract for agents #5
   • Add plan, diff, apply, and check workflows for agent-driven sync #6
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: Consolidate mdcode library operations around structured outcomes and make the CLI a presentation/exit-code adapter.

   Current behavior:
   Public command functions mix operation logic with console output. The exported Execute function calls process.exit in command error paths. The default library helper returns only transformed Markdown, and its documentation uses an outdated package identity and transformer signature.

   Desired behavior:
   Programmatic callers receive structured success values, changes, diagnostics, and errors without terminal formatting or process termination. The CLI renders the same outcomes for humans or JSON and chooses its exit code at the outermost adapter. Callers may observe progress through an explicit callback instead of global console state.

   Key interfaces:

   • Result — a shared discriminated outcome: successful value plus diagnostics, or structured errors. Reuse the semantics underlying the versioned JSON contract from issue Add a versioned machine-readable CLI contract for agents #5.
   • Library operations — list, extract, update/plan/apply/check, run, dump, and transforms return Result; they never call console or process.exit.
   • Reporter callback — optional caller-provided event/diagnostic callback for observable progress without requiring global console state.
   • CLI adapter — converts Result into human text or versioned JSON and sets the process exit code after all operation work completes. Do not call process.exit from library code.
   • Public migration — replace or deprecate the default transform helper in favor of the structured operation interface; update examples to @gcmdev/mdcode and the object-form transformer signature ({ tag, meta, code }) => ... .

   Acceptance criteria:

   • Public library operations return structured success values, changes, diagnostics, and errors.
   • No library operation writes to global console or terminates the process.
   • Callers can supply a reporter callback to observe operation events or diagnostics.
   • The CLI is a thin adapter that renders human/JSON output and assigns exit codes.
   • CLI behavior preserves the documented command contract from issues Add a versioned machine-readable CLI contract for agents #5 and Add plan, diff, apply, and check workflows for agent-driven sync #6.
   • Public library documentation and examples use @gcmdev/mdcode and accurate transformer signatures.
   • Focused library tests and CLI integration tests cover success, failure, reporter, JSON, and exit-code paths.

   Out of scope:

   • Defining the JSON envelope or safe update semantics; those are Add a versioned machine-readable CLI contract for agents #5 and Add plan, diff, apply, and check workflows for agent-driven sync #6.
   • Changing package publication/ownership decisions from Define the canonical npm package identity and align metadata #3.
   • A logging framework or globally configured output mechanism.

   Verification status:
   Confirmed: commands call console, CLI paths call process.exit, and the current default library example uses an outdated package identity/signature. This issue is blocked by #5 and #6.
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

   self-assigned this

   on Oct 6, 2026
5. adrianbrowning commented on Oct 6, 2026

   

   adrianbrowning

   on Oct 6, 2026

   OwnerAuthor

   More actions

   Scope check against main (c50021e) before starting. Most of the brief was written before #5/#6 landed and is already done:

   Criterion	State on main
   Operations return structured results	list, extract, update, validate, watch, run, dump all return typed results; failures throw MetadataError / BlockFailure / CommandError, which errorsFrom() maps onto contract codes.
   No global console / process exit in library code	Only commands/transform.ts still does it: transform() reads process.stdin and both it and transformWithFunction() print every block with console.log. main.ts sets process.exitCode; nothing calls process.exit.
   Reporter callback	run({ onBlock }) and watch({ onEvent }) already exist and are tested. The other operations are one-shot and return every diagnostic in their result.
   CLI is a thin adapter	Execute() renders via format*() and returns the exit code.
   Docs use the package identity and object-form transformer	Already mdcode-ts and ({ tag, meta, code }). @gcmdev/mdcode belongs to #3 and stays out of scope.

   Remaining work, which is all this issue now covers:

   1. Remove transform() and transformWithFunction(). No CLI command uses them. transformWithFunction(source, fn, filter) is update({ source, transformer: fn, filter }) without the file= reads, plus console noise. Callers move to update(), or to walk() to skip file= reads. Breaking, but the package is 0.0.x.
   2. extract({ updateSource, ignoreAnonymous }) throws a plain Error, which maps to unexpected_error. Make it a CommandError("invalid_usage") as the CLI already does.
   3. Keep the mdcode() default export: it already wraps update() and is documented as the simple string API.
6. adrianbrowning

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

   feat!: drop console-printing transform API; add update onBlock; extra…

   ...

   b18bd63
7. adrianbrowning

   closed this as completedin #47on Oct 6, 2026
8. adrianbrowning

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

   chore: guardrails from the #19 retro (#48)

   ...

   af8ae9d