@canonical/pragma-cli 0.18.0 → 0.21.0

package/src/testing/integration/parity.test.ts

@@ -3,28 +3,68 @@
  *
  * Each test calls the same query through both the operation layer
  * (what CLI uses) and the MCP tool (what agents use), then asserts
- * data equality.
+ * data equality. Condensed-mode tests verify that the MCP condensed
+ * text matches what the LLM formatter produces for the same data.
  */
 
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { listFormatters as blockListFmt } from "../../domains/block/formatters/index.js";
+// ---- Shared utilities ----
+import { VERSION } from "#constants";
+import { detectInstallSource } from "#package-manager";
+// ---- Formatters ----
+import {
+  listFormatters as blockListFmt,
+  lookupFormatters as blockLookupFmt,
+} from "../../domains/block/formatters/index.js";
+// ---- Operations ----
 import {
   listBlocks,
   lookupBlock,
 } from "../../domains/block/operations/index.js";
+import { showFormatters as configShowFmt } from "../../domains/config/formatters/index.js";
+import { resolveConfigShow } from "../../domains/config/operations/index.js";
+import { renderInfoLlm } from "../../domains/info/formatters/index.js";
+import { collectStoreSummary } from "../../domains/info/operations/index.js";
+import type { InfoData } from "../../domains/info/types.js";
+import {
+  listFormatters as modifierListFmt,
+  lookupFormatters as modifierLookupFmt,
+} from "../../domains/modifier/formatters/index.js";
 import {
   listModifiers,
   lookupModifier,
 } from "../../domains/modifier/operations/index.js";
-import { listOntologies } from "../../domains/ontology/operations/index.js";
+import {
+  listOntologies,
+  showOntology,
+} from "../../domains/ontology/operations/index.js";
+import { CHANNEL_RELEASES } from "../../domains/shared/filters/buildChannelFilter.js";
+import { resolveTierChain } from "../../domains/shared/filters/buildTierFilter.js";
 import type { PragmaRuntime } from "../../domains/shared/runtime.js";
-import { listStandards } from "../../domains/standard/operations/index.js";
+import {
+  type StandardListOutput,
+  categoriesFormatters as standardCatFmt,
+  listFormatters as standardListFmt,
+  lookupFormatters as standardLookupFmt,
+} from "../../domains/standard/formatters/index.js";
+import {
+  listCategories,
+  listStandards,
+  lookupStandard,
+} from "../../domains/standard/operations/index.js";
+import { listFormatters as tierListFmt } from "../../domains/tier/formatters/index.js";
 import { listTiers } from "../../domains/tier/operations/index.js";
+import {
+  createLookupFormatters as createTokenLookupFmt,
+  listFormatters as tokenListFmt,
+} from "../../domains/token/formatters/index.js";
 import {
   listTokens,
   lookupToken,
 } from "../../domains/token/operations/index.js";
+
+// ---- Test helpers ----
 import assertParity from "../helpers/assertParity.js";
 import createTestMcpClient from "../helpers/createTestMcpClient.js";
 import createTestRuntime from "../helpers/createTestRuntime.js";
@@ -45,6 +85,30 @@ afterAll(async () => {
   rt.dispose();
 });
 
+/** Parse condensed MCP response envelope. */
+function parseCondensed(mcpResponse: Record<string, unknown>): {
+  text: string;
+  condensed: boolean;
+  tokens: string;
+} {
+  const content = mcpResponse.content as unknown[];
+  const first = content[0] as { text: string };
+  return JSON.parse(first.text) as {
+    text: string;
+    condensed: boolean;
+    tokens: string;
+  };
+}
+
+/** Parse MCP response envelope. */
+function parseEnvelope(
+  mcpResponse: Record<string, unknown>,
+): Record<string, unknown> {
+  const content = mcpResponse.content as unknown[];
+  const first = content[0] as { text: string };
+  return JSON.parse(first.text) as Record<string, unknown>;
+}
+
 // ---------------------------------------------------------------------------
 // Block parity
 // ---------------------------------------------------------------------------
@@ -67,24 +131,43 @@ describe("block parity", () => {
       name: "block_list",
       arguments: { condensed: true },
     });
-    const content = mcpRes.content as unknown[];
-    const first = content[0] as { text: string };
-    const body = JSON.parse(first.text) as { text: string };
+    const body = parseCondensed(mcpRes);
     expect(body.text).toBe(expectedText);
   });
 
-  it("block_lookup: detailed fields match", async () => {
-    const opResult = await lookupBlock(rt.store, "Button", rt.config);
+  it("block_lookup: detailed result matches", async () => {
+    const opResults = await lookupBlock(rt.store, "Button", rt.config);
+    expect(opResults.length).toBeGreaterThan(0);
+    const opResult = opResults[0];
     const mcpRes = await client.callTool({
       name: "block_lookup",
       arguments: { names: ["Button"] },
     });
-    const content = mcpRes.content as unknown[];
-    const first = content[0] as { text: string };
-    const body = JSON.parse(first.text) as {
-      data: { results: unknown[] };
-    };
-    expect(body.data.results[0]).toEqual(opResult);
+    const body = parseEnvelope(mcpRes);
+    expect(body.data).toEqual({ results: [opResult], errors: [] });
+  });
+
+  it("block_lookup condensed: matches llm formatter", async () => {
+    const opResults = await lookupBlock(rt.store, "Button", rt.config);
+    expect(opResults.length).toBeGreaterThan(0);
+    const opResult = opResults[0];
+    const expectedText = blockLookupFmt.llm({
+      block: opResult,
+      detailed: true,
+      aspects: {
+        anatomy: true,
+        modifiers: true,
+        tokens: true,
+        implementations: true,
+      },
+    });
+
+    const mcpRes = await client.callTool({
+      name: "block_lookup",
+      arguments: { names: ["Button"], condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
   });
 });
 
@@ -101,6 +184,80 @@ describe("standard parity", () => {
     });
     assertParity(opResult, mcpRes);
   });
+
+  it("standard_list condensed: matches llm formatter", async () => {
+    const opResult = await listStandards(rt.store);
+    const output: StandardListOutput = {
+      items: opResult,
+      details: undefined,
+      disclosure: { level: "summary" },
+    };
+    const expectedText = standardListFmt.llm(output);
+
+    const mcpRes = await client.callTool({
+      name: "standard_list",
+      arguments: { condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
+  });
+
+  it("standard_lookup: detailed fields match", async () => {
+    const opResult = await lookupStandard(
+      rt.store,
+      "react/component/folder-structure",
+    );
+    const mcpRes = await client.callTool({
+      name: "standard_lookup",
+      arguments: { names: ["react/component/folder-structure"] },
+    });
+    const body = parseEnvelope(mcpRes);
+    const data = body.data as { results: unknown[]; errors: unknown[] };
+    expect(data.results[0]).toEqual(opResult);
+    expect(data.errors).toEqual([]);
+  });
+
+  it("standard_lookup condensed: matches llm formatter", async () => {
+    const opResult = await lookupStandard(
+      rt.store,
+      "react/component/folder-structure",
+    );
+    const expectedText = standardLookupFmt.llm({
+      standard: opResult,
+      detailed: true,
+    });
+
+    const mcpRes = await client.callTool({
+      name: "standard_lookup",
+      arguments: {
+        names: ["react/component/folder-structure"],
+        condensed: true,
+      },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
+  });
+
+  it("standard_categories: data matches", async () => {
+    const opResult = await listCategories(rt.store);
+    const mcpRes = await client.callTool({
+      name: "standard_categories",
+      arguments: {},
+    });
+    assertParity(opResult, mcpRes);
+  });
+
+  it("standard_categories condensed: matches llm formatter", async () => {
+    const opResult = await listCategories(rt.store);
+    const expectedText = standardCatFmt.llm(opResult);
+
+    const mcpRes = await client.callTool({
+      name: "standard_categories",
+      arguments: { condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -116,6 +273,18 @@ describe("tier parity", () => {
     });
     assertParity(opResult, mcpRes);
   });
+
+  it("tier_list condensed: matches llm formatter", async () => {
+    const opResult = await listTiers(rt.store);
+    const expectedText = tierListFmt.llm(opResult);
+
+    const mcpRes = await client.callTool({
+      name: "tier_list",
+      arguments: { condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -132,18 +301,39 @@ describe("modifier parity", () => {
     assertParity(opResult, mcpRes);
   });
 
+  it("modifier_list condensed: matches llm formatter", async () => {
+    const opResult = await listModifiers(rt.store);
+    const expectedText = modifierListFmt.llm([...opResult]);
+
+    const mcpRes = await client.callTool({
+      name: "modifier_list",
+      arguments: { condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
+  });
+
   it("modifier_lookup: values match", async () => {
     const opResult = await lookupModifier(rt.store, "importance");
     const mcpRes = await client.callTool({
       name: "modifier_lookup",
       arguments: { names: ["importance"] },
     });
-    const content = mcpRes.content as unknown[];
-    const first = content[0] as { text: string };
-    const body = JSON.parse(first.text) as {
-      data: { results: unknown[] };
-    };
-    expect(body.data.results[0]).toEqual(opResult);
+    const body = parseEnvelope(mcpRes);
+    const data = body.data as { results: unknown[]; errors: unknown[] };
+    expect(data.results[0]).toEqual(opResult);
+  });
+
+  it("modifier_lookup condensed: matches llm formatter", async () => {
+    const opResult = await lookupModifier(rt.store, "importance");
+    const expectedText = modifierLookupFmt.llm(opResult);
+
+    const mcpRes = await client.callTool({
+      name: "modifier_lookup",
+      arguments: { names: ["importance"], condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
   });
 });
 
@@ -161,18 +351,40 @@ describe("token parity", () => {
     assertParity(opResult, mcpRes);
   });
 
+  it("token_list condensed: matches llm formatter", async () => {
+    const opResult = await listTokens(rt.store);
+    const expectedText = tokenListFmt.llm([...opResult]);
+
+    const mcpRes = await client.callTool({
+      name: "token_list",
+      arguments: { condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
+  });
+
   it("token_lookup: values match", async () => {
     const opResult = await lookupToken(rt.store, "color.primary");
     const mcpRes = await client.callTool({
       name: "token_lookup",
       arguments: { names: ["color.primary"] },
     });
-    const content = mcpRes.content as unknown[];
-    const first = content[0] as { text: string };
-    const body = JSON.parse(first.text) as {
-      data: { results: unknown[] };
-    };
-    expect(body.data.results[0]).toEqual(opResult);
+    const body = parseEnvelope(mcpRes);
+    const data = body.data as { results: unknown[]; errors: unknown[] };
+    expect(data.results[0]).toEqual(opResult);
+  });
+
+  it("token_lookup condensed: matches llm formatter", async () => {
+    const opResult = await lookupToken(rt.store, "color.primary");
+    const fmt = createTokenLookupFmt({ detailed: true });
+    const expectedText = fmt.llm(opResult);
+
+    const mcpRes = await client.callTool({
+      name: "token_lookup",
+      arguments: { names: ["color.primary"], condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
   });
 });
 
@@ -189,4 +401,142 @@ describe("ontology parity", () => {
     });
     assertParity(opResult, mcpRes);
   });
+
+  it("ontology_list condensed: text contains ontology data", async () => {
+    const mcpRes = await client.callTool({
+      name: "ontology_list",
+      arguments: { condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.condensed).toBe(true);
+    expect(body.text).toContain("Ontologies");
+    expect(body.text).toContain("ds:");
+  });
+
+  it("ontology_show: data matches operation", async () => {
+    const opResult = await showOntology(rt.store, "ds");
+    const mcpRes = await client.callTool({
+      name: "ontology_show",
+      arguments: { prefix: "ds" },
+    });
+    const body = parseEnvelope(mcpRes);
+    expect(body.data).toEqual(opResult);
+  });
+
+  it("ontology_show condensed: text contains schema data", async () => {
+    const mcpRes = await client.callTool({
+      name: "ontology_show",
+      arguments: { prefix: "ds", condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.condensed).toBe(true);
+    expect(body.text).toContain("ds:");
+    expect(body.text).toContain("Classes");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Config parity
+// ---------------------------------------------------------------------------
+
+describe("config parity", () => {
+  it("config_show: data matches resolveConfigShow", async () => {
+    const install = detectInstallSource();
+    const opResult = resolveConfigShow(rt.config, {
+      packageManager: install.packageManager,
+      installSource: install.label,
+      configFilePath: "pragma.config.json",
+      configFileExists: true,
+    });
+
+    const mcpRes = await client.callTool({
+      name: "config_show",
+      arguments: {},
+    });
+    const body = parseEnvelope(mcpRes);
+    expect(body.data).toEqual(opResult);
+  });
+
+  it("config_show condensed: matches llm formatter", async () => {
+    const install = detectInstallSource();
+    const opResult = resolveConfigShow(rt.config, {
+      packageManager: install.packageManager,
+      installSource: install.label,
+      configFilePath: "pragma.config.json",
+      configFileExists: true,
+    });
+    const expectedText = configShowFmt.llm(opResult);
+
+    const mcpRes = await client.callTool({
+      name: "config_show",
+      arguments: { condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Info parity
+// ---------------------------------------------------------------------------
+
+describe("info parity", () => {
+  it("info: data matches shared operations", async () => {
+    const install = detectInstallSource();
+    const tierChain =
+      rt.config.tier !== undefined ? resolveTierChain(rt.config.tier) : [];
+    const channelReleases = CHANNEL_RELEASES[rt.config.channel];
+    const storeSummary = await collectStoreSummary(rt.store);
+
+    const expected: InfoData = {
+      version: VERSION,
+      pm: install.packageManager,
+      installSource: install.label,
+      configPath: "pragma.config.json",
+      tier: rt.config.tier,
+      tierChain,
+      channel: rt.config.channel,
+      channelReleases: [...channelReleases],
+      update: undefined,
+      updateSkipped: true,
+      store: storeSummary,
+    };
+
+    const mcpRes = await client.callTool({
+      name: "info",
+      arguments: {},
+    });
+    const body = parseEnvelope(mcpRes);
+    expect(body.data).toEqual(expected);
+  });
+
+  it("info condensed: matches llm formatter", async () => {
+    const install = detectInstallSource();
+    const tierChain =
+      rt.config.tier !== undefined ? resolveTierChain(rt.config.tier) : [];
+    const channelReleases = CHANNEL_RELEASES[rt.config.channel];
+    const storeSummary = await collectStoreSummary(rt.store);
+
+    const data: InfoData = {
+      version: VERSION,
+      pm: install.packageManager,
+      installSource: install.label,
+      configPath: "pragma.config.json",
+      tier: rt.config.tier,
+      tierChain,
+      channel: rt.config.channel,
+      channelReleases: [...channelReleases],
+      update: undefined,
+      updateSkipped: true,
+      store: storeSummary,
+    };
+    const expectedText = renderInfoLlm(data);
+
+    const mcpRes = await client.callTool({
+      name: "info",
+      arguments: { condensed: true },
+    });
+    const body = parseCondensed(mcpRes);
+    expect(body.text).toBe(expectedText);
+  });
 });

package/src/testing/store.ts

@@ -35,5 +35,5 @@ async function createTestStore(
   });
 }
 
-export { createTestStore };
 export type { PragmaTestStoreOptions };
+export { createTestStore };

package/src/tui/components/BulletList/BulletList.tsx

@@ -0,0 +1,46 @@
+import { Box, Text } from "ink";
+import compactUri from "../../../domains/shared/compactUri.js";
+import { PREFIX_MAP } from "../../../domains/shared/prefixes.js";
+import type { BulletListProps } from "./types.js";
+
+/**
+ * A simple bulleted list with `•` prefix.
+ *
+ * Formats each item as a string, compacting URIs when detected.
+ */
+export default function BulletList({ items, prefixes }: BulletListProps) {
+  const prefixMap = prefixes ?? PREFIX_MAP;
+
+  return (
+    <Box flexDirection="column" paddingLeft={2}>
+      {items.map((item) => {
+        const text = formatItem(item, prefixMap);
+        return <Text key={text}>• {text}</Text>;
+      })}
+    </Box>
+  );
+}
+
+function formatItem(
+  value: unknown,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") {
+    if (
+      value.startsWith("http://") ||
+      value.startsWith("https://") ||
+      /^[a-z][a-z0-9+.-]*:/i.test(value)
+    ) {
+      return compactUri(value, prefixes);
+    }
+    return value;
+  }
+  if (typeof value === "object" && !Array.isArray(value)) {
+    return Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== null && v !== undefined)
+      .map(([k, v]) => `${k}: ${String(v)}`)
+      .join(" | ");
+  }
+  return String(value);
+}

package/src/tui/components/BulletList/index.ts

@@ -0,0 +1,2 @@
+export { default as BulletList } from "./BulletList.js";
+export type * from "./types.js";

package/src/tui/components/BulletList/types.ts

@@ -0,0 +1,6 @@
+export interface BulletListProps {
+  /** Items to render as a bulleted list. */
+  readonly items: readonly unknown[];
+  /** URI prefix map for compacting IRIs. */
+  readonly prefixes?: Readonly<Record<string, string>>;
+}

package/src/tui/components/Card/Card.tsx

@@ -0,0 +1,73 @@
+import chalk from "chalk";
+import { BOX, DOMAIN_COLORS } from "../../constants.js";
+import { truncateText } from "../../helpers/index.js";
+
+/**
+ * Build a bordered card string for a single lookup result.
+ *
+ * Uses double-line box-drawing characters for the border. The title
+ * renders in the domain's instance color. When a badge is present
+ * (e.g., "[1 of 2]"), it appears right-aligned in the header.
+ * Every body line is wrapped with `║` side borders.
+ *
+ * @param title - Card title for the header bar.
+ * @param domain - Domain name for color lookup.
+ * @param bodyLines - Pre-formatted body lines to wrap with borders.
+ * @param termWidth - Terminal width in columns.
+ * @param badge - Optional right-aligned badge text (e.g., "[1 of 2]").
+ * @returns A fully bordered card as a single string.
+ */
+export default function buildCard(
+  title: string,
+  domain: string,
+  bodyLines: readonly string[],
+  termWidth: number,
+  badge?: string,
+): string {
+  const innerWidth = Math.max(termWidth - 4, 20);
+  const colors = DOMAIN_COLORS[domain];
+  const colorFn = resolveChalkColor(colors?.instanceFg);
+
+  const badgeText = badge ? ` ${badge}` : "";
+  const maxTitleWidth = innerWidth - badgeText.length;
+  const displayTitle = truncateText(title, maxTitleWidth);
+  const titlePad = innerWidth - displayTitle.length - badgeText.length;
+
+  const topBorder = `${BOX.topLeft}${BOX.horizontal.repeat(innerWidth + 2)}${BOX.topRight}`;
+  const badgePart = badge ? chalk.dim(badgeText) : "";
+  const titleLine = `${BOX.vertical} ${chalk.bold(colorFn(displayTitle))}${" ".repeat(Math.max(titlePad, 0))}${badgePart} ${BOX.vertical}`;
+  const divider = `${BOX.dividerLeft}${BOX.dividerHorizontal.repeat(innerWidth + 2)}${BOX.dividerRight}`;
+  const bottomBorder = `${BOX.bottomLeft}${BOX.horizontal.repeat(innerWidth + 2)}${BOX.bottomRight}`;
+
+  const expandedLines = bodyLines.flatMap((line) => line.split("\n"));
+  const borderedBody = expandedLines.map((line) => {
+    const visibleWidth = stripAnsi(line).length;
+    const pad = Math.max(innerWidth - visibleWidth, 0);
+    return `${BOX.vertical} ${line}${" ".repeat(pad)} ${BOX.vertical}`;
+  });
+
+  return [topBorder, titleLine, divider, ...borderedBody, bottomBorder].join(
+    "\n",
+  );
+}
+
+function resolveChalkColor(
+  colorName: string | undefined,
+): (text: string) => string {
+  if (!colorName) return (text) => text;
+  const fn = chalk[colorName as keyof typeof chalk];
+  return typeof fn === "function"
+    ? (fn as (text: string) => string)
+    : (text) => text;
+}
+
+/**
+ * Strip ANSI escape codes from a string to measure visible width.
+ */
+function stripAnsi(text: string): string {
+  return text.replace(
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping ANSI escapes
+    /\x1b\[[0-9;]*m/g,
+    "",
+  );
+}

package/src/tui/components/Card/index.ts

@@ -0,0 +1 @@
+export { default as buildCard } from "./Card.js";

package/src/tui/components/Card/types.ts

@@ -0,0 +1,12 @@
+import type React from "react";
+
+export interface CardProps {
+  /** Card title displayed in the header bar. */
+  readonly title: string;
+  /** Domain name — indexes into DOMAIN_COLORS for the title color. */
+  readonly domain: string;
+  /** Optional badge text displayed right-aligned in the header (e.g., "[1 of 2]"). */
+  readonly badge?: string;
+  /** Card body content. */
+  readonly children: React.ReactNode;
+}

package/src/tui/components/CodeBlock/CodeBlock.tsx

@@ -0,0 +1,37 @@
+import { Box, Text } from "ink";
+import { BOX } from "../../constants.js";
+import { syntaxColor } from "../../helpers/index.js";
+import { useTerminalSize } from "../../hooks/index.js";
+import type { CodeBlockProps } from "./types.js";
+
+/**
+ * A bordered code block with lightweight syntax coloring.
+ *
+ * Renders code inside a single-line bordered sub-box using thin
+ * box-drawing characters. Applies keyword-level colorization via
+ * the syntaxColor helper.
+ */
+export default function CodeBlock({ code, language }: CodeBlockProps) {
+  const { columns: termWidth } = useTerminalSize();
+  const innerWidth = Math.max(termWidth - 8, 20);
+
+  const colored = syntaxColor(code, language);
+  const lines = colored.split("\n");
+
+  const topBorder = `  ${BOX.thinVertical === "│" ? "┌" : BOX.thinVertical}${"─".repeat(innerWidth)}${"┐"}`;
+  const bottomBorder = `  ${"└"}${"─".repeat(innerWidth)}${"┘"}`;
+
+  return (
+    <Box flexDirection="column">
+      <Text dimColor>{topBorder}</Text>
+      {lines.map((line, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: static code lines
+        <Text key={i}>
+          {"  │ "}
+          {line}
+        </Text>
+      ))}
+      <Text dimColor>{bottomBorder}</Text>
+    </Box>
+  );
+}

package/src/tui/components/CodeBlock/index.ts

@@ -0,0 +1,2 @@
+export { default as CodeBlock } from "./CodeBlock.js";
+export type * from "./types.js";