akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/llm/usage-persist.js

@@ -23,12 +23,18 @@ import { appendEvent } from "../core/events.js";
 import { clearLlmUsageSink, hasLlmUsageSink, setLlmUsageSink } from "./usage-telemetry.js";
 /** Event type for persisted per-call LLM usage telemetry. */
 export const LLM_USAGE_EVENT = "llm_usage";
+/** Event type for the owning sink's terminal-record count marker. */
+export const LLM_USAGE_SUMMARY_EVENT = "llm_usage_summary";
 /**
  * Project a usage record into event metadata, dropping `undefined` token
  * fields so an absent-usage call records only `{stage, model, durationMs}`.
  */
 function toEventMetadata(record) {
-    const metadata = { durationMs: record.durationMs };
+    const metadata = {
+        durationMs: record.durationMs,
+        outcome: record.outcome,
+        modelSource: record.modelSource,
+    };
     if (record.stage !== undefined)
         metadata.stage = record.stage;
     if (record.engine !== undefined)
@@ -47,6 +53,8 @@ function toEventMetadata(record) {
         metadata.totalTokens = record.totalTokens;
     if (record.reasoningTokens !== undefined)
         metadata.reasoningTokens = record.reasoningTokens;
+    if (record.errorCode !== undefined)
+        metadata.errorCode = record.errorCode;
     return metadata;
 }
 /**
@@ -56,20 +64,33 @@ function toEventMetadata(record) {
  * test-isolation harness sees a clean sink between tests).
  *
  * `ctx` should carry the same long-lived `state.db` handle the caller already
- * opened for its other events; when omitted, `appendEvent` falls back to its
- * default open-insert-close path.
+ * opened for its other events. A getter is resolved for every append so a
+ * caller can replace its context binding without replacing this owning sink.
+ * When omitted, `appendEvent` falls back to its default open-insert-close path.
  */
 export function installLlmUsagePersistence(ctx) {
+    let expectedTerminalRecords = 0;
+    let disposed = false;
     setLlmUsageSink((record) => {
-        appendEvent({ eventType: LLM_USAGE_EVENT, metadata: toEventMetadata(record) }, ctx);
+        expectedTerminalRecords += 1;
+        appendEvent({ eventType: LLM_USAGE_EVENT, metadata: toEventMetadata(record) }, typeof ctx === "function" ? ctx() : ctx);
     });
     return () => {
+        if (disposed)
+            return;
+        disposed = true;
         clearLlmUsageSink();
+        try {
+            appendEvent({ eventType: LLM_USAGE_SUMMARY_EVENT, metadata: { expectedTerminalRecords } }, typeof ctx === "function" ? ctx() : ctx);
+        }
+        catch {
+            // Persistence remains best-effort even during run teardown.
+        }
     };
 }
 /**
  * Like {@link installLlmUsagePersistence}, but a no-op when a sink is already
- * installed — used by standalone entry points (`akm consolidate`, `akm drain`)
+ * installed — used by standalone entry points (`akm proposal drain`)
  * that may also run as a sub-step of `akm improve`. When invoked inside an
  * enclosing run the existing per-run sink keeps ownership; the returned
  * disposer then does nothing, so the enclosing run's `finally` still clears it.

package/dist/llm/usage-telemetry.js

@@ -5,7 +5,8 @@
  * Per-call LLM usage telemetry (#576).
  *
  * `chatCompletion` captures usage + model + finish_reason + wall-time for
- * EVERY OpenAI-compatible call and emits one {@link LlmUsageRecord} through a
+ * EVERY OpenAI-compatible HTTP attempt and emits one terminal
+ * {@link LlmUsageRecord} through a
  * module-level sink. The sink indirection keeps `client.ts` free of any
  * dependency on the events/db layer: the application wires the sink to
  * persistence at startup / per improve run, and tests can inspect records in
@@ -87,6 +88,20 @@ function asFiniteNonNegative(value) {
 function asNonEmptyString(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+function asLlmUsageErrorCode(value) {
+    switch (value) {
+        case "rate_limited":
+        case "provider_error":
+        case "provider_html_error":
+        case "network_error":
+        case "parse_error":
+        case "timeout":
+        case "unknown_error":
+            return value;
+        default:
+            return undefined;
+    }
+}
 /** Decode durable event metadata with the same validation used by health aggregation. */
 export function decodeLlmUsageRecord(value) {
     if (!value || typeof value !== "object")
@@ -95,7 +110,12 @@ export function decodeLlmUsageRecord(value) {
     const durationMs = asFiniteNonNegative(raw.durationMs);
     if (durationMs === undefined)
         return undefined;
-    const record = { durationMs };
+    // Historical rows predate terminal provenance. Keep health aggregation
+    // backward-compatible while conservatively treating their model as configured,
+    // never response-observed.
+    const outcome = raw.outcome === "success" || raw.outcome === "error" ? raw.outcome : "success";
+    const modelSource = raw.modelSource === "response" || raw.modelSource === "configured" ? raw.modelSource : "configured";
+    const record = { durationMs, outcome, modelSource };
     for (const key of ["stage", "engine", "process", "model", "finishReason"]) {
         const decoded = asNonEmptyString(raw[key]);
         if (decoded !== undefined)
@@ -106,6 +126,9 @@ export function decodeLlmUsageRecord(value) {
         if (decoded !== undefined)
             record[key] = decoded;
     }
+    const errorCode = asLlmUsageErrorCode(raw.errorCode);
+    if (errorCode !== undefined)
+        record.errorCode = errorCode;
     return record;
 }
 /**

package/dist/output/cli-hints.js

@@ -2,8 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Embedded "agent CLI hints" rendered by `akm hints` when no other source
- * is available.
+ * Embedded agent CLI guide rendered by `akm hints` and `akm help agents`.
  *
  * Extracted from `src/cli.ts` so it does not bloat the CLI module and so
  * docs/CI tooling can re-use the same constants. Two flavors:

package/dist/output/context.js

@@ -9,7 +9,9 @@
  * calls read from this in-memory singleton instead of re-scanning argv and
  * re-loading config on every call.
  *
- * Initialized from `cli.ts` before `runMain`.
+ * Initialized from `cli.ts` before `runCli` dispatches the command (`cli.ts`
+ * drives citty's `runCommand` directly rather than `runMain` — see the
+ * top-level driver comment there).
  */
 import { UsageError } from "../core/errors.js";
 const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md", "html"];
@@ -39,6 +41,8 @@ function parseShapeMode(value) {
 export function parseFlagValue(argv, flag) {
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        if (arg === "--")
+            break;
         if (arg === flag)
             return argv[i + 1];
         if (arg.startsWith(`${flag}=`))
@@ -47,15 +51,26 @@ export function parseFlagValue(argv, flag) {
     return undefined;
 }
 export function hasBooleanFlag(argv, flag) {
-    return argv.some((arg) => arg === flag || arg === `${flag}=true`);
+    for (const arg of argv) {
+        if (arg === "--")
+            return false;
+        if (arg === flag || arg === `${flag}=true`)
+            return true;
+    }
+    return false;
 }
 /**
  * Read a hyphenated arg out of citty's parsed `args` object.
  *
- * citty does not auto-camelise hyphenated arg keys (see `--max-pages`,
- * `--with-sources` for the existing convention), so command handlers end up
- * casting `args` to a string-indexed record at every read site. This helper
- * encapsulates the cast.
+ * Verified live: citty DOES auto-camelise a DECLARED hyphenated arg — for
+ * `"max-pages": { type: "string" }` in a command's `args`, citty's parsed
+ * object answers both `args["max-pages"]` and `args.maxPages` (a `Proxy`
+ * falls back through `camelCase`/`kebabCase`, and `--no-<flag>` negation is
+ * handled the same way for booleans). What citty's own TS types do NOT give
+ * callers is a statically-typed handle on that mapping, and command handlers
+ * here type `args` as `unknown` at the boundary — so every read site still
+ * needs a cast. This helper encapsulates that cast; it exists for typing
+ * convenience, not to work around a citty parsing limitation.
  */
 export function getHyphenatedArg(args, key) {
     if (typeof args !== "object" || args === null)
@@ -81,7 +96,7 @@ export function resolveOutputMode(argv, defaults = {}) {
     const detail = parseDetailLevel(rawDetail) ?? defaults?.detail ?? "brief";
     const shape = parseShapeMode(rawShape) ?? "human";
     const outputPath = parseFlagValue(argv, "--output");
-    return { format, detail, shape, forAgent: shape === "agent", ...(outputPath ? { outputPath } : {}) };
+    return { format, detail, shape, ...(outputPath ? { outputPath } : {}) };
 }
 let _mode;
 /**

package/dist/output/format-exempt.js

@@ -0,0 +1,80 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Commands whose output is not an envelope, and therefore not formattable (D7).
+ *
+ * D7 makes all six `--format` values work on every command that renders through
+ * `output()`. A small set does not render an envelope at all: they emit a shell
+ * script, drive an interactive prompt, hand stdout to a child process, or print
+ * a document that IS the payload. Passing `--format` to one of those cannot do
+ * anything useful.
+ *
+ * The point of declaring the set here is that the exemption stops being
+ * implicit. Before D7 you discovered it by getting JSON when you asked for
+ * Markdown, or an exit 2 when you asked for HTML. Now the list is one grep away,
+ * it is documented in `STABILITY.md`, and asking for a format on an exempt
+ * command warns instead of silently doing something else.
+ *
+ * Names are canonical command paths resolved from the Citty tree.
+ */
+/**
+ * Top-level command tokens whose entire surface is format-exempt.
+ */
+const EXEMPT_COMMANDS = new Set([
+    // Emits shell completion script source for eval.
+    "completions",
+    // `migrate status`/`apply` used to be exempt here too: `runMigrationTool`
+    // (src/commands/migration-tool.ts) spawns the standalone
+    // `scripts/akm-migrate.ts` tool, which always emitted its own fixed JSON
+    // shape and never consulted `--format`. `src/commands/migrate-cli.ts` now
+    // parses that child's final result line and renders it through the normal
+    // `output()` pipeline (registered shape: `src/output/shapes/migrate.ts`;
+    // text renderer: `src/output/text/migrate.ts`), so both subcommands honour
+    // `--format` like any other command and are no longer listed here. Any
+    // progress-event lines the child prints during a real `apply` still print
+    // verbatim ahead of the formatted result — those are operational logging,
+    // not part of the result envelope, the same way a progress spinner would be.
+    // Document payload group: bare `help` prints the sectioned overview,
+    // `help migrate <version>` prints release notes, and `help agents` prints
+    // the embedded CLI-reference guide (`src/output/cli-hints.ts`) — none of
+    // the three render a result envelope.
+    "help",
+    // Embedded agent guide document.
+    "hints",
+]);
+/**
+ * `<command> <subcommand>` pairs that are exempt while the rest of the group
+ * formats normally.
+ */
+const EXEMPT_SUBCOMMANDS = new Set([
+    // Child-process passthrough (the env/secret groups otherwise format fine).
+    "env run",
+    "secret run",
+    // B3/B4 (W1-F): a bare absolute filesystem path IS the payload — the
+    // documented shell-substitution primitive (`$(akm env path <ref>)`,
+    // Docker `_FILE` / `--env-file`) — not a field worth wrapping in an
+    // envelope. Wrapping it broke every existing substitution silently: the
+    // CLI's default format is `json`, so an un-flagged `akm env path <ref>`
+    // (exactly how the substitution is always written) started emitting
+    // `{"path":"..."}` instead of the raw path. Unlike `config path`, this
+    // command has no `--all`-style multi-field variant, so the whole surface
+    // can be exempt without wrongly warning on a real envelope case.
+    "env path",
+]);
+/**
+ * True when `--format` cannot meaningfully apply to this invocation.
+ *
+ * `commandPath` contains canonical Citty command names from the top-level
+ * command through the deepest resolved subcommand.
+ */
+export function isFormatExemptCommand(commandPath) {
+    const command = commandPath[0];
+    if (command === undefined)
+        return false;
+    return EXEMPT_COMMANDS.has(command) || EXEMPT_SUBCOMMANDS.has(commandPath.join(" "));
+}
+/** The declared exempt set, for docs generation and tests. */
+export function formatExemptSurfaces() {
+    return { commands: [...EXEMPT_COMMANDS], subcommands: [...EXEMPT_SUBCOMMANDS] };
+}

package/dist/output/generic-render.js

@@ -0,0 +1,259 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * True when `value` is a non-empty array of plain objects — the shape worth
+ * rendering as a table rather than as a nested list. Uniformity is judged on
+ * the union of keys, not on strict equality, so one row carrying an extra
+ * optional field still tabulates (its column is simply blank elsewhere).
+ */
+function isTabular(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return false;
+    return value.every((row) => row !== null && typeof row === "object" && !Array.isArray(row));
+}
+/** Column order for a table: first appearance across all rows, order-stable. */
+function tableColumns(rows) {
+    const columns = [];
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            if (!columns.includes(key))
+                columns.push(key);
+        }
+    }
+    return columns;
+}
+/**
+ * Render a leaf value for display. Objects and arrays that reach a cell are
+ * JSON-encoded rather than expanded — a table cell is not a place to nest.
+ */
+function displayScalar(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+/**
+ * Root-level envelope metadata the shape registry stamps on top of a
+ * command's actual result: `shape` (the discriminator) and `schemaVersion`
+ * (the envelope's own version), both added by the passthrough stamp in
+ * `src/output/shapes/passthrough.ts` and equivalent per-command shapers
+ * elsewhere. Transport bookkeeping, not a result anyone asked for — a `##
+ * shape` / `## schemaVersion` section (`renderGenericMarkdown`), an
+ * `<h2>shape</h2>` block (`renderGenericHtml`), or a `shape=…` line
+ * (`renderGenericText`) is noise in every command's output, so every generic
+ * renderer drops both. ONLY at the root, though: some shapes reuse
+ * `schemaVersion` as genuine per-entry content one level down (each event in
+ * `log list`'s `events[]` carries its own `schemaVersion`, see
+ * `shapeEventEntry` in `src/output/shapes/helpers.ts`), and that must
+ * survive untouched — every renderer below applies this filter only to the
+ * top-level `Object.entries` loop over the envelope, never recursively.
+ */
+const ENVELOPE_META_KEYS = new Set(["shape", "schemaVersion"]);
+// ── Markdown ─────────────────────────────────────────────────────────────────
+/** Escape the one character that can break a Markdown table row. */
+function escapeCell(text) {
+    return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function markdownTable(rows) {
+    const columns = tableColumns(rows);
+    if (columns.length === 0)
+        return [];
+    const lines = [
+        `| ${columns.join(" | ")} |`,
+        `| ${columns.map(() => "---").join(" | ")} |`,
+        ...rows.map((row) => `| ${columns.map((c) => escapeCell(displayScalar(row[c]))).join(" | ")} |`),
+    ];
+    return lines;
+}
+function markdownValue(value, depth) {
+    if (isTabular(value))
+        return markdownTable(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return ["_(none)_"];
+        return value.map((item) => `- ${escapeCell(displayScalar(item))}`);
+    }
+    if (value !== null && typeof value === "object") {
+        const lines = [];
+        for (const [key, nested] of Object.entries(value)) {
+            // Headings stop at h6; deeper nesting continues as bolded labels.
+            const heading = "#".repeat(Math.min(depth, 6));
+            lines.push(depth <= 6 ? `${heading} ${key}` : `**${key}**`, "", ...markdownValue(nested, depth + 1), "");
+        }
+        return lines;
+    }
+    return [displayScalar(value) === "" ? "_(empty)_" : displayScalar(value)];
+}
+/**
+ * Render a shaped envelope as Markdown. `command` titles the document so a
+ * rendered file identifies itself once detached from the invocation.
+ */
+export function renderGenericMarkdown(command, value) {
+    const body = value !== null && typeof value === "object" && !Array.isArray(value)
+        ? Object.entries(value)
+            .filter(([key]) => !ENVELOPE_META_KEYS.has(key)) // transport metadata, not a result
+            .flatMap(([key, nested]) => [`## ${key}`, "", ...markdownValue(nested, 3), ""])
+        : markdownValue(value, 2);
+    const lines = [`# ${command}`, "", ...body];
+    const rendered = lines
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd();
+    return `${rendered}\n`;
+}
+// ── HTML ─────────────────────────────────────────────────────────────────────
+const HTML_ESCAPES = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+/** Escape every value that reaches the document — this is untrusted content. */
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char] ?? char);
+}
+function htmlTable(rows) {
+    const columns = tableColumns(rows);
+    if (columns.length === 0)
+        return "";
+    const head = `<tr>${columns.map((c) => `<th scope="col">${escapeHtml(c)}</th>`).join("")}</tr>`;
+    const body = rows
+        .map((row) => `<tr>${columns.map((c) => `<td>${escapeHtml(displayScalar(row[c]))}</td>`).join("")}</tr>`)
+        .join("");
+    return `<table><thead>${head}</thead><tbody>${body}</tbody></table>`;
+}
+function htmlValue(value, depth) {
+    if (isTabular(value))
+        return htmlTable(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "<p><em>(none)</em></p>";
+        return `<ul>${value.map((item) => `<li>${escapeHtml(displayScalar(item))}</li>`).join("")}</ul>`;
+    }
+    if (value !== null && typeof value === "object") {
+        const level = Math.min(depth, 6);
+        return Object.entries(value)
+            .map(([key, nested]) => `<h${level}>${escapeHtml(key)}</h${level}>${htmlValue(nested, depth + 1)}`)
+            .join("");
+    }
+    const scalar = displayScalar(value);
+    return scalar === "" ? "<p><em>(empty)</em></p>" : `<p>${escapeHtml(scalar)}</p>`;
+}
+/**
+ * Render a shaped envelope as a self-contained HTML document.
+ *
+ * Self-contained matters: the output is routinely redirected to a file and
+ * opened directly, so it carries its own minimal styling and references
+ * nothing external.
+ */
+export function renderGenericHtml(command, value) {
+    const body = value !== null && typeof value === "object" && !Array.isArray(value)
+        ? Object.entries(value)
+            .filter(([key]) => !ENVELOPE_META_KEYS.has(key)) // transport metadata, not a result
+            .map(([key, nested]) => `<h2>${escapeHtml(key)}</h2>${htmlValue(nested, 3)}`)
+            .join("")
+        : htmlValue(value, 2);
+    return [
+        "<!doctype html>",
+        '<html lang="en">',
+        "<head>",
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        `<title>akm ${escapeHtml(command)}</title>`,
+        "<style>",
+        "body{font:16px/1.5 system-ui,sans-serif;margin:2rem auto;max-width:60rem;padding:0 1rem}",
+        "table{border-collapse:collapse;width:100%;margin:0 0 1rem}",
+        "th,td{border:1px solid #8884;padding:.35rem .6rem;text-align:left}",
+        "th{background:#8881}",
+        "h1{margin-bottom:1.5rem}",
+        "@media(prefers-color-scheme:dark){body{background:#111;color:#eee}}",
+        "</style>",
+        "</head>",
+        "<body>",
+        `<h1>akm ${escapeHtml(command)}</h1>`,
+        body === "" ? "<p><em>(no output)</em></p>" : body,
+        "</body>",
+        "</html>",
+        "",
+    ].join("\n");
+}
+// ── Text ─────────────────────────────────────────────────────────────────────
+/**
+ * Flatten `value` onto `lines` as `dotted.path=value` entries — the exact
+ * algorithm `formatConfigPlain` (`src/output/text/command-format.ts`)
+ * already established as this CLI's real plain-text house style for `akm
+ * config list`. Arrays serialize as one compact-JSON line rather than
+ * index-per-line (`items.0.name=…`), matching that same precedent instead of
+ * inventing a second convention: the arrays that reach this generic
+ * fallback are typically short id/tag lists, where one JSON-array line reads
+ * better than N extra `path.0=`, `path.1=`, … lines.
+ *
+ * Exported so command-specific text formatters (e.g. `formatHealthPlain` in
+ * `src/output/text/health-format.ts`) can reuse the SAME scalar-tree
+ * convention for the parts of their envelope that are plain nested
+ * scalars/objects, while overriding just the parts that need bespoke
+ * handling (arrays of status-bearing records, where this function's
+ * one-JSON-line-per-array behavior is the exact defect those formatters
+ * exist to fix). Reuse beats a second flattener.
+ */
+export function flattenForText(value, path, lines) {
+    if (value === null || value === undefined) {
+        lines.push(`${path}=`);
+    }
+    else if (Array.isArray(value)) {
+        lines.push(`${path}=${JSON.stringify(value)}`);
+    }
+    else if (typeof value === "object") {
+        const entries = Object.entries(value);
+        if (entries.length === 0) {
+            lines.push(`${path}={}`);
+            return;
+        }
+        for (const [key, nested] of entries) {
+            flattenForText(nested, `${path}.${key}`, lines);
+        }
+    }
+    else {
+        lines.push(`${path}=${String(value)}`);
+    }
+}
+/**
+ * Render a shaped envelope as flat `key=value` text — no markup characters.
+ *
+ * This is a DISTINCT function from `renderGenericMarkdown`, not a reuse of
+ * it, and that is a deliberate reversal of this fallback's first cut, which
+ * called `renderGenericMarkdown` directly for `text` on the reasoning that
+ * it emits no HTML and is therefore "plain-text-safe." That reasoning was
+ * wrong: `#` heading markers, `_..._` emphasis, and `| ... |` table syntax
+ * ARE markup — a terminal happens to print them as literal characters
+ * instead of throwing, but a user piping `--format text` into `grep` or a
+ * line-oriented script still sees literal `#`/`_`/`|` noise that plain JSON
+ * at least didn't have. That is the exact "one format wearing another
+ * format's flag" defect this whole fallback exists to close, with Markdown
+ * substituted for JSON instead of JSON itself.
+ *
+ * `akm config list --format text` and `akm info --format text` already
+ * establish this CLI's real plain-text convention — flat `dotted.path=value`
+ * lines, no markup — so the generic fallback now matches its registered
+ * siblings (what a command looks like once someone writes it a bespoke
+ * formatter) instead of matching `md`'s.
+ */
+export function renderGenericText(command, value) {
+    const lines = [];
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        for (const [key, nested] of Object.entries(value)) {
+            if (ENVELOPE_META_KEYS.has(key))
+                continue; // transport metadata, not a result
+            flattenForText(nested, key, lines);
+        }
+    }
+    else {
+        flattenForText(value, command, lines);
+    }
+    return lines.length === 0 ? `${command}: (empty)\n` : `${lines.join("\n")}\n`;
+}

package/dist/output/render-registry.js

@@ -0,0 +1,57 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Per-command `md` / `html` renderer registries (D7).
+ *
+ * Mirrors `src/output/text/registry.ts`: a command may register a bespoke
+ * renderer for a document format, and anything unregistered falls back to the
+ * generic rendering of its shaped envelope (`./generic-render`). The fallback
+ * is what makes all six `--format` values universal; the registry is what lets
+ * a command that has something better to say — `akm health` and its report
+ * templates — say it without the output pipeline knowing that command exists.
+ *
+ * Kept separate from the module that dispatches through it so per-command
+ * renderer modules can import `registerMdRenderer` / `registerHtmlRenderer`
+ * without a cycle back into the pipeline, exactly as the text registry does.
+ *
+ * Returning `null` from a handler means "I have nothing special for this
+ * payload" and falls through to the generic renderer — `akm health` uses that
+ * to keep its bespoke tables for the shapes that have them while still
+ * rendering everything else.
+ */
+import { createCommandRegistry } from "./command-registry.js";
+const MD_RENDERER_REGISTRY = createCommandRegistry();
+const HTML_RENDERER_REGISTRY = createCommandRegistry();
+/** Register a Markdown renderer for a command name. */
+export function registerMdRenderer(command, handler) {
+    MD_RENDERER_REGISTRY.register(command, handler);
+}
+/** Register a batch of Markdown renderers in iteration order. */
+export function registerMdRenderers(entries) {
+    MD_RENDERER_REGISTRY.registerAll(entries);
+}
+/** Look up a registered Markdown renderer, or `undefined` when unregistered. */
+export function getMdRendererHandler(command) {
+    return MD_RENDERER_REGISTRY.get(command);
+}
+/** Remove a previously-registered Markdown renderer. Test-only utility. */
+export function deregisterMdRenderer(command) {
+    MD_RENDERER_REGISTRY.deregister(command);
+}
+/** Register an HTML renderer for a command name. */
+export function registerHtmlRenderer(command, handler) {
+    HTML_RENDERER_REGISTRY.register(command, handler);
+}
+/** Register a batch of HTML renderers in iteration order. */
+export function registerHtmlRenderers(entries) {
+    HTML_RENDERER_REGISTRY.registerAll(entries);
+}
+/** Look up a registered HTML renderer, or `undefined` when unregistered. */
+export function getHtmlRendererHandler(command) {
+    return HTML_RENDERER_REGISTRY.get(command);
+}
+/** Remove a previously-registered HTML renderer. Test-only utility. */
+export function deregisterHtmlRenderer(command) {
+    HTML_RENDERER_REGISTRY.deregister(command);
+}