@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/render/envelope.ts

@@ -0,0 +1,50 @@
+/**
+ * The machine-output envelope (D3, D4).
+ *
+ * Both projectors emit the same two shapes: `{ ok: true, data, meta }` for a
+ * success and `{ ok: false, error }` for a failure. The CLI writes them to
+ * stdout under `--format json`; the MCP projector returns them as tool
+ * content. Building both here — from one `successEnvelope` / `errorEnvelope`
+ * pair — is what makes CLI-JSON and MCP output provably identical.
+ */
+
+import type { PragmaError } from "../error/PragmaError.js";
+import { serializeError } from "../error/serialize.js";
+import type { ErrorPayload } from "../error/types.js";
+
+/** The success envelope: an agent branches on `ok` before reading `data`. */
+export interface SuccessEnvelope {
+  readonly ok: true;
+  readonly data: unknown;
+  readonly meta: Record<string, unknown>;
+}
+
+/** The failure envelope: the serialized error under `error`. */
+export interface ErrorEnvelope {
+  readonly ok: false;
+  readonly error: ErrorPayload;
+}
+
+/**
+ * Wrap already-JSON-safe data in the success envelope.
+ *
+ * @param data - The verb's data projection (JSON-safe).
+ * @param meta - Envelope metadata (e.g. plan-first flags); defaults to `{}`.
+ * @returns The `{ ok: true, data, meta }` envelope.
+ */
+export function successEnvelope(
+  data: unknown,
+  meta: Record<string, unknown> = {},
+): SuccessEnvelope {
+  return { ok: true, data, meta };
+}
+
+/**
+ * Wrap a {@link PragmaError} in the failure envelope.
+ *
+ * @param error - The structured error to serialize.
+ * @returns The `{ ok: false, error }` envelope.
+ */
+export function errorEnvelope(error: PragmaError): ErrorEnvelope {
+  return { ok: false, error: serializeError(error) };
+}

package/src/kernel/render/formatters.ts

@@ -0,0 +1,30 @@
+/**
+ * Formatter selection for the CLI projector.
+ *
+ * The grammar's {@link Formatters} (plain / llm / json — no ink field) is the
+ * per-verb output contract. {@link selectFormatter} picks one by the parsed
+ * global flags with a fixed precedence: `--format json` wins, then `--llm`,
+ * then the plain terminal default. The dispatcher uses the plain/llm branches
+ * directly and wraps the json branch in the machine envelope (D3).
+ */
+
+import type { GlobalFlags } from "../runtime/types.js";
+import type { Formatters } from "../spec/types.js";
+
+/**
+ * Pick the formatter for the active output mode.
+ *
+ * Precedence: `--format json` > `--llm` > plain.
+ *
+ * @param flags - The parsed global flags for this invocation.
+ * @param formatters - The verb's three-mode formatter set.
+ * @returns The single formatter matching the active mode.
+ */
+export function selectFormatter<T>(
+  flags: GlobalFlags,
+  formatters: Formatters<T>,
+): (data: T) => string {
+  if (flags.format === "json") return formatters.json;
+  if (flags.llm) return formatters.llm;
+  return formatters.plain;
+}

package/src/kernel/render/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Render kernel barrel — the pure, layout-only output layer.
+ *
+ * The projectors compose these: the generic renderers and formatter selector
+ * for text output, the disclosure resolver for progressive detail, the machine
+ * envelope for `--format json` / MCP, and the chunked stdout writer.
+ */
+
+export { compactUri } from "./compactUri.js";
+export type {
+  ColumnDef,
+  LookupField,
+  LookupSectionOverride,
+  RenderListOptions,
+  RenderLookupOptions,
+  SectionDef,
+  SectionKind,
+} from "./contracts.js";
+export { DETAIL_LEVELS, resolveDetail } from "./disclosure.js";
+export type { ErrorEnvelope, SuccessEnvelope } from "./envelope.js";
+export { errorEnvelope, successEnvelope } from "./envelope.js";
+export { selectFormatter } from "./formatters.js";
+export { DEFAULT_PREFIX_MAP } from "./prefixes.js";
+export {
+  renderListLlm,
+  renderListPlain,
+  renderLookupLlm,
+  renderLookupPlain,
+} from "./renderers.js";
+export { writeChunked, writeStdout } from "./writeStdout.js";

package/src/kernel/render/prefixes.ts

@@ -0,0 +1,21 @@
+/**
+ * The default display-compaction prefix set.
+ *
+ * A minimal port of the v1 prefix map: only the namespaces the renderers use
+ * to compact IRIs in output. The store's query prefix map (which layers in
+ * package- and config-declared prefixes) is a store concern and joins when the
+ * first store-backed capability lands — this display set is intentionally
+ * small and static so the render layer stays store-free.
+ */
+
+/**
+ * Namespaces compacted in list/lookup output. Keys are the prefixes shown to
+ * the user (`ds:Button`); values are the absolute namespace IRIs matched.
+ */
+export const DEFAULT_PREFIX_MAP: Readonly<Record<string, string>> = {
+  ds: "https://ds.canonical.com/",
+  cs: "http://pragma.canonical.com/codestandards#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  owl: "http://www.w3.org/2002/07/owl#",
+  skos: "http://www.w3.org/2004/02/skos/core#",
+};

package/src/kernel/render/renderers.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "../error/PragmaError.js";
+import { cliRecovery } from "../error/recovery.js";
+import {
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+} from "../error/renderError.js";
+import type { ColumnDef, LookupField, SectionDef } from "./contracts.js";
+import { resolveDetail } from "./disclosure.js";
+import {
+  renderListLlm,
+  renderListPlain,
+  renderLookupLlm,
+  renderLookupPlain,
+} from "./renderers.js";
+
+interface Widget {
+  readonly uri: string;
+  readonly name: string;
+  readonly kind: string;
+  readonly note: string;
+}
+
+const widgets: readonly Widget[] = [
+  {
+    uri: "https://ds.canonical.com/Button",
+    name: "Button",
+    kind: "component",
+    note: "Primary action",
+  },
+  {
+    uri: "https://ds.canonical.com/Card",
+    name: "Card",
+    kind: "pattern",
+    note: "",
+  },
+];
+
+/** Columns shown at each disclosure level — mirrors what a domain formatter does. */
+function columnsFor(detail: string): ColumnDef<Widget>[] {
+  if (detail === "summary") return [{ key: "name", label: "Name" }];
+  if (detail === "detailed") {
+    return [
+      { key: "uri", label: "URI" },
+      { key: "name", label: "Name" },
+      { key: "kind", label: "Kind" },
+      { key: "note", label: "Note" },
+    ];
+  }
+  return [
+    { key: "name", label: "Name" },
+    { key: "kind", label: "Kind" },
+  ];
+}
+
+function fieldsFor(detail: string): LookupField<Widget>[] {
+  const fields: LookupField<Widget>[] = [
+    { label: "Kind", value: (w) => w.kind },
+  ];
+  if (detail === "detailed") {
+    fields.push({ label: "URI", value: (w) => w.uri });
+  }
+  return fields;
+}
+
+function sectionsFor(detail: string): SectionDef<Widget>[] {
+  return detail === "detailed"
+    ? [{ key: "note", heading: "Note", kind: "field" }]
+    : [];
+}
+
+const DETAILS = ["summary", "standard", "detailed"] as const;
+
+describe("render matrix (list/lookup/empty × plain/llm/json × detail)", () => {
+  it("renders every scenario/format/detail combination", () => {
+    const matrix: Record<string, Record<string, Record<string, string>>> = {};
+
+    for (const detail of DETAILS) {
+      const columns = columnsFor(detail);
+      const listOpts = { heading: "Widgets", columns };
+      const lookupOpts = {
+        title: (w: Widget) => w.name,
+        fields: fieldsFor(detail),
+        sections: sectionsFor(detail),
+      };
+      const projected = widgets.map((w) =>
+        Object.fromEntries(columns.map((c) => [c.key, w[c.key]])),
+      );
+
+      matrix[detail] = {
+        list: {
+          plain: renderListPlain(widgets, listOpts),
+          llm: renderListLlm(widgets, listOpts),
+          json: JSON.stringify(projected),
+        },
+        lookup: {
+          plain: renderLookupPlain(widgets[0] as Widget, lookupOpts),
+          llm: renderLookupLlm(widgets[0] as Widget, lookupOpts),
+          json: JSON.stringify(widgets[0]),
+        },
+        empty: {
+          plain: renderListPlain([], listOpts),
+          llm: renderListLlm([], listOpts),
+          json: "[]",
+        },
+      };
+    }
+
+    expect(matrix).toMatchSnapshot();
+  });
+
+  it("renders an empty-state message (+ hint) when items are empty", () => {
+    const options = {
+      heading: "Widgets",
+      columns: columnsFor("summary"),
+      emptyMessage: "No widget entries found.",
+      emptyHint: "Run `pragma sources update`.",
+    };
+    // Plain: message then hint on the next line — a non-blank exit-0 body.
+    expect(renderListPlain([], options)).toBe(
+      "No widget entries found.\nRun `pragma sources update`.",
+    );
+    // Llm: the `(0)` heading, then the same message + hint.
+    expect(renderListLlm([], options)).toBe(
+      "## Widgets (0)\n\nNo widget entries found.\nRun `pragma sources update`.",
+    );
+  });
+
+  it("keeps the bare-empty behavior when no emptyMessage is declared", () => {
+    const options = { heading: "Widgets", columns: columnsFor("summary") };
+    expect(renderListPlain([], options)).toBe("");
+    expect(renderListLlm([], options)).toBe("## Widgets (0)\n");
+  });
+
+  it("resolves disclosure level from ordered sources", () => {
+    expect(resolveDetail({ flag: "detailed", config: "summary" })).toBe(
+      "detailed",
+    );
+    expect(resolveDetail({ config: "summary" })).toBe("summary");
+    expect(resolveDetail({ specDefault: "detailed" })).toBe("detailed");
+    expect(resolveDetail({})).toBe("standard");
+    expect(resolveDetail({ flag: "bogus" })).toBe("standard");
+  });
+});
+
+describe("error render matrix (× plain/llm/json)", () => {
+  it("renders each error across the three formats", () => {
+    const notFound = PragmaError.notFound("block", "Buton", {
+      suggestions: ["Button"],
+      recovery: cliRecovery("pragma block list", "List available blocks."),
+    });
+    const empty = PragmaError.emptyResults("token", {
+      filters: { channel: "stable", tier: "core" },
+      validOptions: ["stable", "beta"],
+    });
+
+    expect({
+      notFound: {
+        plain: renderErrorPlain(notFound),
+        llm: renderErrorLlm(notFound),
+        json: renderErrorJson(notFound),
+      },
+      empty: {
+        plain: renderErrorPlain(empty),
+        llm: renderErrorLlm(empty),
+        json: renderErrorJson(empty),
+      },
+    }).toMatchSnapshot();
+  });
+});