Consolidate the public library interface and CLI adapter

[adrianbrowning]

What to build

Consolidate the public mdcode library interface so programmatic callers receive structured results and errors without inheriting CLI process exits or terminal formatting behavior.

Acceptance criteria

• The public library interface returns structured results, changes, and errors for supported operations.
• CLI presentation and process-exit behavior are implemented in a thin adapter rather than in library operations.
• Documentation and examples use the current package identity and accurate transformer signatures.
• Library callers can provide or observe output without relying on global console state.
• The migrated interface is covered by focused library and CLI integration tests.

Blocked by

• Add a versioned machine-readable CLI contract for agents #5
• Add plan, diff, apply, and check workflows for agent-driven sync #6

[adrianbrowning]

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.