@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/render/renderers.ts

@@ -0,0 +1,429 @@
+/**
+ * Generic list and lookup renderers for the plain and llm output modes.
+ *
+ * Domain formatters delegate to these pure, layout-only functions: each takes
+ * a typed options bag (see {@link contracts}) and returns a fully formatted
+ * string — no I/O, no side effects. The single-field record collapse and
+ * URI-compaction behaviour are ported verbatim from the v1 renderers.
+ */
+
+import { compactUri } from "./compactUri.js";
+import type {
+  ColumnDef,
+  RenderListOptions,
+  RenderLookupOptions,
+  SectionDef,
+} from "./contracts.js";
+import { DEFAULT_PREFIX_MAP } from "./prefixes.js";
+
+type RenderMode = "plain" | "llm";
+
+/**
+ * The empty-state body — the message plus its optional hint on a second line,
+ * or "" when the caller declared no message (bare-empty behavior preserved).
+ */
+function emptyBody<T>(options: RenderListOptions<T>): string {
+  if (!options.emptyMessage) return "";
+  return options.emptyHint
+    ? `${options.emptyMessage}\n${options.emptyHint}`
+    : options.emptyMessage;
+}
+
+export function renderListPlain<T>(
+  items: readonly T[],
+  options: RenderListOptions<T>,
+): string {
+  if (items.length === 0) return emptyBody(options);
+
+  const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
+  const rows = items.map((item) =>
+    options.columns
+      .map((column) => ({
+        column,
+        value: formatColumnValue(item, column, prefixes),
+      }))
+      .filter(({ column, value }) => shouldRenderColumn(column, value))
+      .map(({ value }) => value),
+  );
+
+  const widths = rows.reduce<number[]>(
+    (acc, row) =>
+      row.map((value, index) => Math.max(acc[index] ?? 0, value.length)),
+    [],
+  );
+
+  return rows
+    .map((row) =>
+      row
+        .map((value, index) => value.padEnd(widths[index] ?? value.length))
+        .join("  ")
+        .trimEnd(),
+    )
+    .join("\n");
+}
+
+export function renderListLlm<T>(
+  items: readonly T[],
+  options: RenderListOptions<T>,
+): string {
+  const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
+  const lines = [`## ${options.heading} (${items.length})`, ""];
+
+  if (items.length === 0) {
+    const body = emptyBody(options);
+    return body ? `${lines[0]}\n\n${body}` : lines.join("\n");
+  }
+
+  for (const item of items) {
+    const values = options.columns
+      .map((column) => ({
+        column,
+        value: formatColumnValue(item, column, prefixes),
+      }))
+      .filter(({ column, value }) => shouldRenderColumn(column, value));
+
+    const iri = values.find(({ column }) => column.key === "uri")?.value;
+    const name = values.find(({ column }) => column.key === "name")?.value;
+    const rest = values
+      .filter(({ column }) => column.key !== "uri" && column.key !== "name")
+      .map(({ value }) => value)
+      .filter(Boolean);
+
+    const parts: string[] = [];
+    if (iri) parts.push(`\`${iri}\``);
+    if (name) {
+      parts.push(iri ? `— **${name}**` : `**${name}**`);
+    }
+    if (rest.length > 0) {
+      parts.push(rest.join(" | "));
+    }
+
+    lines.push(`- ${parts.join(" ")}`.trimEnd());
+  }
+
+  return lines.join("\n");
+}
+
+export function renderLookupPlain<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+): string {
+  return renderLookup(entity, options, "plain");
+}
+
+export function renderLookupLlm<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+): string {
+  return renderLookup(entity, options, "llm");
+}
+
+function renderLookup<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string {
+  const title = options.title(entity);
+  const fields = renderLookupFields(entity, options, mode);
+  const sections = renderLookupSections(entity, options, mode);
+
+  if (mode === "llm") {
+    return [`## ${title}`, "", ...fields, ...sections].join("\n").trimEnd();
+  }
+
+  const headingRule = "═".repeat(Math.max(title.length, 24));
+  return [title, headingRule, "", ...fields, ...sections].join("\n").trimEnd();
+}
+
+function renderLookupFields<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string[] {
+  const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
+  return options.fields.flatMap((field) => {
+    const value = field.value(entity);
+    if (isEmptyValue(value)) {
+      return [];
+    }
+
+    const formatted = formatInlineValue(value, prefixes);
+    return mode === "llm"
+      ? [`- ${field.label}: ${formatted}`]
+      : [`  ${field.label}: ${formatted}`];
+  });
+}
+
+function renderLookupSections<T>(
+  entity: T,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string[] {
+  const sections: string[] = [];
+
+  for (const section of options.sections) {
+    const value = entity[section.key];
+    if (!section.showWhenEmpty && isEmptyValue(value)) {
+      continue;
+    }
+
+    const override = options.sectionOverrides?.[section.key]?.[mode];
+    const body = override
+      ? override(entity, section)
+      : renderSectionValue(value, section, options, mode);
+
+    if (!body) {
+      continue;
+    }
+
+    sections.push("");
+    sections.push(
+      mode === "llm" ? `### ${section.heading}` : `${section.heading}:`,
+    );
+    sections.push(body);
+  }
+
+  return sections;
+}
+
+function renderSectionValue<T>(
+  value: unknown,
+  section: SectionDef<T>,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string | null {
+  const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
+
+  switch (section.kind) {
+    case "field":
+      return renderFieldValue(value, prefixes, mode);
+    case "code":
+      return renderCodeValue(value, section, options, mode);
+    case "list":
+    case "table":
+    case "nested-table":
+      return renderCollectionValue(value, prefixes, mode);
+    case "tree":
+      return renderTreeValue(value, prefixes, mode);
+    default:
+      return null;
+  }
+}
+
+function renderFieldValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+  mode: RenderMode,
+): string | null {
+  if (isEmptyValue(value)) {
+    return null;
+  }
+
+  const text = formatScalarValue(value, prefixes);
+  return mode === "llm" ? text : indentBlock(text);
+}
+
+function renderCodeValue<T>(
+  value: unknown,
+  section: SectionDef<T>,
+  options: RenderLookupOptions<T>,
+  mode: RenderMode,
+): string | null {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    return null;
+  }
+
+  const language =
+    options.codeLanguage?.(section, value) ?? inferCodeLanguage(value);
+  if (mode === "llm") {
+    return [`\`\`\`${language}`, value, "```"].join("\n");
+  }
+
+  const header = language === "text" ? "" : `[${language}]\n`;
+  return indentBlock(`${header}${value}`.trimEnd());
+}
+
+function renderCollectionValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+  mode: RenderMode,
+): string | null {
+  if (!Array.isArray(value) || value.length === 0) {
+    return null;
+  }
+
+  const lines = value.map(
+    (entry) => `- ${formatCollectionEntry(entry, prefixes)}`,
+  );
+  return mode === "llm" ? lines.join("\n") : indentBlock(lines.join("\n"));
+}
+
+function renderTreeValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+  mode: RenderMode,
+): string | null {
+  const lines = buildTreeLines(value, prefixes);
+  if (lines.length === 0) {
+    return null;
+  }
+
+  return mode === "llm" ? lines.join("\n") : indentBlock(lines.join("\n"));
+}
+
+function buildTreeLines(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+  depth = 0,
+): string[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => buildTreeLines(entry, prefixes, depth));
+  }
+
+  if (!value || typeof value !== "object") {
+    return typeof value === "string" && value.length > 0
+      ? [`${"  ".repeat(depth)}- ${formatScalarValue(value, prefixes)}`]
+      : [];
+  }
+
+  const rootedTree = value as { root?: unknown };
+  if (rootedTree.root) {
+    return buildTreeLines(rootedTree.root, prefixes, depth);
+  }
+
+  const treeNode = value as {
+    name?: unknown;
+    uri?: unknown;
+    children?: unknown;
+  };
+  const label =
+    typeof treeNode.name === "string" && treeNode.name.length > 0
+      ? treeNode.name
+      : typeof treeNode.uri === "string"
+        ? compactUri(treeNode.uri, prefixes)
+        : "item";
+
+  const lines = [`${"  ".repeat(depth)}- ${label}`];
+  if (Array.isArray(treeNode.children)) {
+    lines.push(...buildTreeLines(treeNode.children, prefixes, depth + 1));
+  }
+  return lines;
+}
+
+function formatCollectionEntry(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (!value || typeof value !== "object") {
+    return formatScalarValue(value, prefixes);
+  }
+
+  const object = value as Record<string, unknown>;
+  return Object.entries(object)
+    .filter(([, entryValue]) => !isEmptyValue(entryValue))
+    .map(
+      ([key, entryValue]) =>
+        `${key}: ${formatInlineValue(entryValue, prefixes)}`,
+    )
+    .join(" | ");
+}
+
+function formatColumnValue<T>(
+  item: T,
+  column: ColumnDef<T>,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  const raw = item[column.key];
+  if (column.format) {
+    return column.format(raw);
+  }
+
+  return formatInlineValue(raw, prefixes);
+}
+
+function formatInlineValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (Array.isArray(value)) {
+    return value.map((entry) => formatInlineValue(entry, prefixes)).join(", ");
+  }
+
+  if (value && typeof value === "object") {
+    return Object.entries(value as Record<string, unknown>)
+      .filter(([, entryValue]) => !isEmptyValue(entryValue))
+      .map(
+        ([key, entryValue]) =>
+          `${key}=${formatInlineValue(entryValue, prefixes)}`,
+      )
+      .join("; ");
+  }
+
+  return formatScalarValue(value, prefixes);
+}
+
+function formatScalarValue(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    return looksLikeUri(value) ? compactUri(value, prefixes) : value;
+  }
+
+  return String(value);
+}
+
+function shouldRenderColumn<T>(column: ColumnDef<T>, value: string): boolean {
+  if (value.length > 0) {
+    return true;
+  }
+
+  return column.showWhenEmpty === true;
+}
+
+function inferCodeLanguage(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("@prefix") || trimmed.includes(" a ")) {
+    return "ttl";
+  }
+  if (trimmed.includes(":") && trimmed.includes("\n")) {
+    return "yaml";
+  }
+  return "text";
+}
+
+function looksLikeUri(value: string): boolean {
+  return (
+    value.startsWith("http://") ||
+    value.startsWith("https://") ||
+    /^[a-z][a-z0-9+.-]*:/i.test(value)
+  );
+}
+
+function isEmptyValue(value: unknown): boolean {
+  if (value === null || value === undefined) {
+    return true;
+  }
+
+  if (typeof value === "string") {
+    return value.trim().length === 0;
+  }
+
+  if (Array.isArray(value)) {
+    return value.length === 0;
+  }
+
+  return false;
+}
+
+function indentBlock(value: string, spaces = 2): string {
+  const indent = " ".repeat(spaces);
+  return value
+    .split("\n")
+    .map((line) => `${indent}${line}`)
+    .join("\n");
+}

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { writeChunked } from "./writeStdout.js";
+
+/** Collect everything {@link writeChunked} writes into one buffer. */
+function collect(text: string): Buffer {
+  const chunks: Buffer[] = [];
+  const stream = {
+    write(chunk: string | Uint8Array): boolean {
+      chunks.push(Buffer.from(chunk as Uint8Array));
+      return true;
+    },
+  } as unknown as NodeJS.WritableStream;
+  writeChunked(stream, text);
+  return Buffer.concat(chunks);
+}
+
+describe("writeChunked", () => {
+  it("round-trips a short string with an astral char", () => {
+    const text = "hello 😀 world";
+    expect(collect(text).toString("utf8")).toBe(text);
+  });
+
+  it("preserves an astral char that straddles the 4 KiB boundary", () => {
+    // Place a 4-byte emoji so its UTF-8 bytes span the 4096-byte chunk edge —
+    // a UTF-16 string slice there would emit a lone surrogate (U+FFFD).
+    const text = `${"a".repeat(4094)}😀${"z".repeat(16)}`;
+    const out = collect(text).toString("utf8");
+    expect(out).toBe(text);
+    expect(out).not.toContain("�");
+  });
+
+  it("splits large input into multiple writes", () => {
+    let writes = 0;
+    const stream = {
+      write(): boolean {
+        writes++;
+        return true;
+      },
+    } as unknown as NodeJS.WritableStream;
+    writeChunked(stream, "x".repeat(10_000));
+    expect(writes).toBeGreaterThan(1);
+  });
+});

package/src/kernel/render/writeStdout.ts

@@ -0,0 +1,49 @@
+/**
+ * Chunked stdout writer.
+ *
+ * Bun's runtime can segfault when a single very large string is written to
+ * stdout in one call; writing in ≤4 KiB pieces avoids it. Every command's final
+ * output goes through {@link writeStdout} so large list/graph payloads stay safe.
+ * Ported from the v1 `writeChunked` guard.
+ *
+ * The text is encoded to a UTF-8 `Buffer` first and sliced on byte boundaries.
+ * Slicing the *string* by UTF-16 unit could split an astral character's
+ * surrogate pair, leaving a lone surrogate that encodes to U+FFFD and corrupts
+ * the output; splitting raw UTF-8 bytes across writes is lossless — the
+ * consumer concatenates them.
+ */
+
+/** Maximum bytes written per `stream.write` call. */
+const CHUNK_SIZE = 4096;
+
+/**
+ * Write a string to a writable stream in ≤{@link CHUNK_SIZE}-byte slices.
+ *
+ * @param stream - The destination writable stream.
+ * @param text - The full string to write.
+ * @note Impure — writes to the stream.
+ */
+export function writeChunked(
+  stream: NodeJS.WritableStream,
+  text: string,
+): void {
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.length <= CHUNK_SIZE) {
+    stream.write(buffer);
+    return;
+  }
+
+  for (let offset = 0; offset < buffer.length; offset += CHUNK_SIZE) {
+    stream.write(buffer.subarray(offset, offset + CHUNK_SIZE));
+  }
+}
+
+/**
+ * Write a string to stdout, chunked, appending no newline.
+ *
+ * @param text - The string to write.
+ * @note Impure — writes to `process.stdout`.
+ */
+export function writeStdout(text: string): void {
+  writeChunked(process.stdout, text);
+}

package/src/kernel/runtime/boot.test.ts

@@ -0,0 +1,69 @@
+/**
+ * C2 (config visibility) at the runtime seam.
+ *
+ * `bootRuntime` memoizes the layered-config read (`configPromise`) for the
+ * invocation. On a long-lived MCP server that memo would strand a stale config
+ * after a `config_set` write — subsequent reads keep serving the old value. The
+ * fix couples the two server-lifetime memos: `store.invalidate()` also clears
+ * the config memo (via the `onInvalidate` hook boot.ts wires), so the next
+ * `loadConfig()` re-reads disk. This drives that mechanism directly against the
+ * real config reader and an isolated global config file.
+ */
+
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { bootRuntime } from "./boot.js";
+import type { GlobalFlags } from "./types.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+
+describe("bootRuntime config memo — invalidate() re-reads config from disk (C2)", () => {
+  let priorXdgConfig: string | undefined;
+  let configPath: string;
+
+  beforeEach(() => {
+    // Isolate the global config to this test so writes never bleed across tests.
+    priorXdgConfig = process.env.XDG_CONFIG_HOME;
+    const xdg = mkdtempSync(join(tmpdir(), "pragma-c2-cfg-"));
+    process.env.XDG_CONFIG_HOME = xdg;
+    mkdirSync(join(xdg, "pragma"), { recursive: true });
+    configPath = join(xdg, "pragma", "config.json");
+  });
+
+  afterEach(() => {
+    if (priorXdgConfig === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = priorXdgConfig;
+  });
+
+  it("serves the memoized config until store.invalidate() clears it, then re-reads disk", async () => {
+    writeFileSync(configPath, JSON.stringify({ tier: "apps/lxd" }));
+    // An empty project dir: only the global layer contributes `tier`.
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-c2-proj-"));
+    const runtime = bootRuntime(FLAGS, cwd);
+
+    const first = await runtime.loadConfig();
+    expect(first.config.tier).toBe("apps/lxd");
+
+    // A mutation changes config on disk...
+    writeFileSync(configPath, JSON.stringify({ tier: "apps/vm" }));
+
+    // ...but the per-invocation memo still serves the STALE value (the bug the
+    // fix targets on a long-lived server).
+    const stale = await runtime.loadConfig();
+    expect(stale.config.tier).toBe("apps/lxd");
+
+    // Invalidating the store drops the coupled config memo (onInvalidate)...
+    runtime.store.invalidate();
+
+    // ...so the next read re-reads disk and sees the new value.
+    const fresh = await runtime.loadConfig();
+    expect(fresh.config.tier).toBe("apps/vm");
+  });
+});

package/src/kernel/runtime/boot.ts

@@ -0,0 +1,59 @@
+/**
+ * Build the per-invocation {@link PragmaRuntime}.
+ *
+ * The runtime stays cheap and storeless to construct: `store` is a lazy handle
+ * (nothing boots until a `needsStore` verb calls `store.get()`), `query` is the
+ * facade over it, and `loadConfig` memoizes the layered-config read behind a
+ * dynamic import so the config reader (and its zod) never lands on the
+ * `--help`/`__complete` fast path. No eager I/O happens here — a storeless verb
+ * that only reads `globalFlags`/`cwd` touches neither the store nor config.
+ *
+ * The store's boot reads config through `loadConfig`, so the two memos are
+ * coupled: `store.invalidate()` (called by the MCP projector after a real
+ * mutation) also clears `configPromise` via the `onInvalidate` hook, so a
+ * re-boot re-reads config from disk instead of reusing a stale layer. On a
+ * long-lived MCP server that is what makes a `config_set` visible to the next
+ * read tool; on a one-shot CLI nothing calls `invalidate`, so it never fires.
+ */
+
+import { VERSION } from "../../constants.js";
+import type { ConfigLayers } from "../config/types.js";
+import { createQueryFacade } from "./facade.js";
+import { createLazyStore } from "./store.js";
+import type { GlobalFlags, PragmaRuntime } from "./types.js";
+
+/**
+ * Assemble a runtime for one CLI or MCP invocation.
+ *
+ * @param globalFlags - The parsed global flags for this invocation.
+ * @param cwd - The directory to resolve project state against (defaults to the
+ *   process working directory).
+ * @returns The runtime handed to every verb `run`.
+ * @note Impure by default — reads `process.cwd()` unless `cwd` is provided; the
+ *   store/config handles it exposes do their own I/O only when used.
+ */
+export function bootRuntime(
+  globalFlags: GlobalFlags,
+  cwd: string = process.cwd(),
+): PragmaRuntime {
+  let configPromise: Promise<ConfigLayers> | undefined;
+  const loadConfig = (): Promise<ConfigLayers> => {
+    configPromise ??= import("../config/readConfig.js").then((module) =>
+      module.readConfig(cwd),
+    );
+    return configPromise;
+  };
+
+  const store = createLazyStore({
+    cwd,
+    loadConfig,
+    // Invalidating the store must also drop the config memo its boot depends on,
+    // so a re-boot after a mutation re-reads config from disk (never stale).
+    onInvalidate: () => {
+      configPromise = undefined;
+    },
+  });
+  const query = createQueryFacade(store);
+
+  return { cwd, version: VERSION, globalFlags, loadConfig, store, query };
+}