@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -0,0 +1,127 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`error render matrix (× plain/llm/json) > renders each error across the three formats 1`] = `
+{
+  "empty": {
+    "json": "{"ok":false,"error":{"code":"EMPTY_RESULTS","message":"No tokens found.","validOptions":["stable","beta"],"filters":{"channel":"stable","tier":"core"}}}",
+    "llm": "## Error: EMPTY_RESULTS
+No tokens found.
+Filters: channel=stable, tier=core
+Valid options: stable, beta",
+    "plain": "Error: No tokens found.
+
+Active filters:
+  channel: stable
+  tier: core
+
+Valid options: stable, beta",
+  },
+  "notFound": {
+    "json": "{"ok":false,"error":{"code":"ENTITY_NOT_FOUND","message":"block \\"Buton\\" not found.","suggestions":["Button"],"recovery":{"message":"List available blocks.","cli":"pragma block list"}}}",
+    "llm": "## Error: ENTITY_NOT_FOUND
+block "Buton" not found.
+Suggestions: Button
+Recovery: List available blocks. \`pragma block list\`",
+    "plain": "Error: block "Buton" not found.
+
+Did you mean?
+  - Button
+
+List available blocks. Run \`pragma block list\`",
+  },
+}
+`;
+
+exports[`render matrix (list/lookup/empty × plain/llm/json × detail) > renders every scenario/format/detail combination 1`] = `
+{
+  "detailed": {
+    "empty": {
+      "json": "[]",
+      "llm": "## Widgets (0)
+",
+      "plain": "",
+    },
+    "list": {
+      "json": "[{"uri":"https://ds.canonical.com/Button","name":"Button","kind":"component","note":"Primary action"},{"uri":"https://ds.canonical.com/Card","name":"Card","kind":"pattern","note":""}]",
+      "llm": "## Widgets (2)
+
+- \`ds:Button\` — **Button** component | Primary action
+- \`ds:Card\` — **Card** pattern",
+      "plain": "ds:Button  Button  component  Primary action
+ds:Card    Card    pattern",
+    },
+    "lookup": {
+      "json": "{"uri":"https://ds.canonical.com/Button","name":"Button","kind":"component","note":"Primary action"}",
+      "llm": "## Button
+
+- Kind: component
+- URI: ds:Button
+
+### Note
+Primary action",
+      "plain": "Button
+════════════════════════
+
+  Kind: component
+  URI: ds:Button
+
+Note:
+  Primary action",
+    },
+  },
+  "standard": {
+    "empty": {
+      "json": "[]",
+      "llm": "## Widgets (0)
+",
+      "plain": "",
+    },
+    "list": {
+      "json": "[{"name":"Button","kind":"component"},{"name":"Card","kind":"pattern"}]",
+      "llm": "## Widgets (2)
+
+- **Button** component
+- **Card** pattern",
+      "plain": "Button  component
+Card    pattern",
+    },
+    "lookup": {
+      "json": "{"uri":"https://ds.canonical.com/Button","name":"Button","kind":"component","note":"Primary action"}",
+      "llm": "## Button
+
+- Kind: component",
+      "plain": "Button
+════════════════════════
+
+  Kind: component",
+    },
+  },
+  "summary": {
+    "empty": {
+      "json": "[]",
+      "llm": "## Widgets (0)
+",
+      "plain": "",
+    },
+    "list": {
+      "json": "[{"name":"Button"},{"name":"Card"}]",
+      "llm": "## Widgets (2)
+
+- **Button**
+- **Card**",
+      "plain": "Button
+Card",
+    },
+    "lookup": {
+      "json": "{"uri":"https://ds.canonical.com/Button","name":"Button","kind":"component","note":"Primary action"}",
+      "llm": "## Button
+
+- Kind: component",
+      "plain": "Button
+════════════════════════
+
+  Kind: component",
+    },
+  },
+}
+`;

package/src/kernel/render/compactUri.ts

@@ -0,0 +1,25 @@
+/**
+ * Compact a full URI to its prefixed form using the longest matching
+ * namespace. When two registered namespaces both prefix the URI (a base
+ * namespace and a sub-namespace), the longer — more specific — one wins.
+ * Falls back to the original URI when no namespace matches.
+ *
+ * @param fullUri - The absolute URI to compact.
+ * @param prefixes - A map of prefix to namespace IRI.
+ * @returns The `prefix:local` form, or `fullUri` unchanged when none matches.
+ */
+export function compactUri(
+  fullUri: string,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  let best: { prefix: string; namespace: string } | undefined;
+  for (const [prefix, namespace] of Object.entries(prefixes)) {
+    if (!fullUri.startsWith(namespace)) continue;
+    if (best === undefined || namespace.length > best.namespace.length) {
+      best = { prefix, namespace };
+    }
+  }
+
+  if (best === undefined) return fullUri;
+  return `${best.prefix}:${fullUri.slice(best.namespace.length)}`;
+}

package/src/kernel/render/contracts.ts

@@ -0,0 +1,72 @@
+/**
+ * Layout contracts for the generic list and lookup renderers.
+ *
+ * These describe *how* a domain's data is projected to text — which columns a
+ * list shows, which fields and sections a lookup renders — with no coupling to
+ * store shapes, filters, or effects. Domain formatters (PR2+) build these
+ * option bags and hand them to {@link renderers}.
+ */
+
+/** A single column in a list rendering. */
+export interface ColumnDef<T> {
+  readonly key: keyof T & string;
+  readonly label: string;
+  readonly format?: (value: unknown) => string;
+  readonly showWhenEmpty?: boolean;
+}
+
+/** The kinds of section a lookup can render. */
+export type SectionKind =
+  | "field"
+  | "code"
+  | "list"
+  | "table"
+  | "nested-table"
+  | "tree";
+
+/** A single section in a lookup rendering. */
+export interface SectionDef<T> {
+  readonly key: keyof T & string;
+  readonly heading: string;
+  readonly kind: SectionKind;
+  readonly showWhenEmpty?: boolean;
+}
+
+/** A single inline field rendered in a lookup heading block. */
+export interface LookupField<T> {
+  readonly label: string;
+  readonly value: (entity: T) => unknown;
+}
+
+/** Per-mode override callbacks for a lookup section. */
+export interface LookupSectionOverride<T> {
+  readonly plain?: (entity: T, section: SectionDef<T>) => string | null;
+  readonly llm?: (entity: T, section: SectionDef<T>) => string | null;
+}
+
+/** Options controlling the generic list renderer. */
+export interface RenderListOptions<T> {
+  readonly heading: string;
+  readonly columns: readonly ColumnDef<T>[];
+  readonly prefixes?: Readonly<Record<string, string>>;
+  /**
+   * The message shown when the list is empty, so zero results read as a calm,
+   * non-blank success (exit 0) rather than an empty screen. Omit to keep the
+   * bare-empty behavior (plain renders "", llm renders the `(0)` heading only).
+   */
+  readonly emptyMessage?: string;
+  /** An optional second line under {@link emptyMessage} — how to get results. */
+  readonly emptyHint?: string;
+}
+
+/** Options controlling the generic lookup renderer. */
+export interface RenderLookupOptions<T> {
+  readonly title: (entity: T) => string;
+  readonly fields: readonly LookupField<T>[];
+  readonly sections: readonly SectionDef<T>[];
+  readonly prefixes?: Readonly<Record<string, string>>;
+  readonly sectionOverrides?: Partial<
+    Record<keyof T & string, LookupSectionOverride<T>>
+  >;
+  readonly codeLanguage?: (section: SectionDef<T>, value: unknown) => string;
+}

package/src/kernel/render/disclosure.ts

@@ -0,0 +1,44 @@
+/**
+ * Progressive-disclosure resolution.
+ *
+ * A verb renders at one of {@link DETAIL_LEVELS}. The effective level is chosen
+ * from four sources, most specific first: the `--detail` flag, the resolved
+ * config's `detail`, the verb's own `disclosure.default`, and finally the
+ * built-in `"standard"`. Unknown values (a stale config, a typo) fall back to
+ * the default rather than erroring, so output never fails on disclosure.
+ */
+
+import {
+  DEFAULT_DETAIL_LEVEL,
+  DETAIL_LEVELS,
+  type DetailLevel,
+} from "../../constants.js";
+
+export { DETAIL_LEVELS };
+
+/** Type guard: is a string one of the recognized detail levels? */
+function isDetailLevel(value: string): value is DetailLevel {
+  return (DETAIL_LEVELS as readonly string[]).includes(value);
+}
+
+/**
+ * Resolve the effective disclosure level from its ordered sources.
+ *
+ * @param sources - Candidate levels, applied most-specific first.
+ * @param sources.flag - The explicit `--detail` value, if any.
+ * @param sources.config - The resolved config's `detail`, if any.
+ * @param sources.specDefault - The verb's `disclosure.default`, if any.
+ * @returns The first recognized level, or `"standard"` when none matches.
+ */
+export function resolveDetail(sources: {
+  flag?: string | undefined;
+  config?: string | undefined;
+  specDefault?: string | undefined;
+}): DetailLevel {
+  const candidate =
+    sources.flag ??
+    sources.config ??
+    sources.specDefault ??
+    DEFAULT_DETAIL_LEVEL;
+  return isDetailLevel(candidate) ? candidate : DEFAULT_DETAIL_LEVEL;
+}

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,31 @@
+/**
+ * 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 the llm mode
+ * (`--format llm` or auto-detected on a non-interactive stdout), 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 (`--format llm` / auto-detected) > 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,205 @@
+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";
+import { type RenderStyle, styleFor } from "./style.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("lookup beautify (TTY style seam)", () => {
+  const lookupOpts = {
+    title: (w: Widget) => w.name,
+    fields: fieldsFor("standard"),
+    sections: sectionsFor("standard"),
+  };
+
+  it("bolds the title, dims the rule, and cyans field labels on a TTY", () => {
+    const tagged: RenderStyle = {
+      enabled: true,
+      bold: (t) => `B(${t})`,
+      dim: (t) => `D(${t})`,
+      cyan: (t) => `C(${t})`,
+      green: (t) => t,
+      yellow: (t) => t,
+    };
+    const lines = renderLookupPlain(
+      widgets[0] as Widget,
+      lookupOpts,
+      tagged,
+    ).split("\n");
+    expect(lines.at(0)).toBe("B(Button)");
+    expect(lines.at(1)).toBe(`D(${"═".repeat(24)})`);
+    expect(lines).toContain("  C(Kind): component");
+  });
+
+  it("is byte-identical to the plain lookup when the styler is disabled", () => {
+    expect(
+      renderLookupPlain(widgets[0] as Widget, lookupOpts, styleFor(false)),
+    ).toBe(`Button\n${"═".repeat(24)}\n\n  Kind: component`);
+  });
+});
+
+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();
+  });
+});