@canonical/pragma-cli 0.18.0 → 0.21.0

package/src/domains/standard/formatters/lookup.ts

@@ -1,78 +1,45 @@
-/**
- * Three-mode formatter for `pragma standard lookup` output.
- *
- * - **plain** — terminal text showing name, category, description, and
- *   optional dos/donts when detailed.
- * - **llm** — condensed Markdown consumed by LLM agents and reused
- *   by the MCP adapter when `condensed: true`.
- * - **json** — structured JSON; omits dos/donts unless detailed.
- */
-
+import type { RenderLookupOptions } from "../../shared/contracts.js";
 import type { Formatters } from "../../shared/formatters.js";
+import { renderLookupLlm, renderLookupPlain } from "../../shared/renderers.js";
+import type { StandardDetailed } from "../../shared/types/index.js";
+import { standardConfig } from "../standardConfig.js";
 import type { StandardLookupInput } from "./types.js";
 
+/** Three-mode formatter for `pragma standard lookup` output. */
 const formatters: Formatters<StandardLookupInput> = {
-  plain({ standard, detailed }) {
-    const lines: string[] = [];
-    lines.push(standard.name);
-    lines.push(`URI: ${standard.uri}`);
-    lines.push(`Category: ${standard.category || "—"}`);
-    lines.push(`Description: ${standard.description}`);
-    if (standard.extends) {
-      lines.push(`Extends: ${standard.extends}`);
-    }
-
-    if (detailed) {
-      if (standard.dos.length > 0) {
-        lines.push("");
-        lines.push("Do:");
-        for (const d of standard.dos) {
-          lines.push(`  ${d.code}`);
-        }
-      }
-
-      if (standard.donts.length > 0) {
-        lines.push("");
-        lines.push("Don't:");
-        for (const d of standard.donts) {
-          lines.push(`  ${d.code}`);
-        }
-      }
-    }
-
-    return lines.join("\n");
-  },
-
-  llm({ standard, detailed }) {
-    const lines: string[] = [];
-    lines.push(`## ${standard.name}`);
-    lines.push(`URI: ${standard.uri}`);
-    lines.push(`Category: ${standard.category || "—"}`);
-    if (standard.extends) {
-      lines.push(`Extends: ${standard.extends}`);
-    }
-    lines.push(standard.description);
+  plain: ({ standard, detailed }) =>
+    renderLookupPlain(standard, {
+      title: (entry) => entry.name,
+      fields: [
+        { label: "URI", value: (entry) => entry.uri },
+        { label: "Category", value: (entry) => entry.category || "—" },
+        { label: "Description", value: (entry) => entry.description },
+        { label: "Extends", value: (entry) => entry.extends },
+      ],
+      sections: detailed
+        ? standardConfig.lookupSections.filter(
+            (section) => section.key === "dos" || section.key === "donts",
+          )
+        : [],
+      sectionOverrides: standardSectionOverrides,
+    }),
 
-    if (detailed) {
-      if (standard.dos.length > 0) {
-        lines.push("");
-        lines.push("### Do");
-        for (const d of standard.dos) {
-          lines.push(`- ${d.code}`);
-        }
-      }
-
-      if (standard.donts.length > 0) {
-        lines.push("");
-        lines.push("### Don't");
-        for (const d of standard.donts) {
-          lines.push(`- ${d.code}`);
-        }
-      }
-    }
-
-    return lines.join("\n");
-  },
+  llm: ({ standard, detailed }) =>
+    renderLookupLlm(standard, {
+      title: (entry) => entry.name,
+      fields: [
+        { label: "URI", value: (entry) => entry.uri },
+        { label: "Category", value: (entry) => entry.category || "—" },
+        { label: "Description", value: (entry) => entry.description },
+        { label: "Extends", value: (entry) => entry.extends },
+      ],
+      sections: detailed
+        ? standardConfig.lookupSections.filter(
+            (section) => section.key === "dos" || section.key === "donts",
+          )
+        : [],
+      sectionOverrides: standardSectionOverrides,
+    }),
 
   json({ standard, detailed }) {
     if (detailed) {
@@ -84,3 +51,51 @@ const formatters: Formatters<StandardLookupInput> = {
 };
 
 export default formatters;
+
+/**
+ * Build lookup rendering options for the Ink TUI view.
+ *
+ * @param detailed - whether to include dos/donts sections
+ * @returns Options compatible with the LookupView component.
+ */
+export function createInkLookupOptions(
+  detailed: boolean,
+): RenderLookupOptions<StandardDetailed> {
+  return {
+    title: (entry) => entry.name,
+    fields: [
+      { label: "URI", value: (entry) => entry.uri },
+      { label: "Category", value: (entry) => entry.category || "—" },
+      { label: "Description", value: (entry) => entry.description },
+      { label: "Extends", value: (entry) => entry.extends },
+    ],
+    sections: detailed
+      ? standardConfig.lookupSections.filter(
+          (section) => section.key === "dos" || section.key === "donts",
+        )
+      : [],
+  };
+}
+
+const standardSectionOverrides = {
+  dos: {
+    plain: (entry: StandardLookupInput["standard"]) =>
+      entry.dos.length > 0
+        ? entry.dos.map((item) => `  ${item.code}`).join("\n")
+        : null,
+    llm: (entry: StandardLookupInput["standard"]) =>
+      entry.dos.length > 0
+        ? entry.dos.map((item) => `- ${item.code}`).join("\n")
+        : null,
+  },
+  donts: {
+    plain: (entry: StandardLookupInput["standard"]) =>
+      entry.donts.length > 0
+        ? entry.donts.map((item) => `  ${item.code}`).join("\n")
+        : null,
+    llm: (entry: StandardLookupInput["standard"]) =>
+      entry.donts.length > 0
+        ? entry.donts.map((item) => `- ${item.code}`).join("\n")
+        : null,
+  },
+};

package/src/domains/standard/formatters/types.ts

@@ -9,7 +9,7 @@ import type {
   Disclosure,
   StandardDetailed,
   StandardSummary,
-} from "../../shared/types.js";
+} from "../../shared/types/index.js";
 
 /** Input payload for the standard-lookup formatter, pairing data with a detail flag. */
 export interface StandardLookupInput {

package/src/domains/standard/index.ts

@@ -30,3 +30,4 @@ export {
   resolveStandardLookup,
   standardEmptyError,
 } from "./orchestration/index.js";
+export { standardConfig } from "./standardConfig.js";

package/src/domains/standard/operations/categories.ts

@@ -9,7 +9,7 @@
 import type { Store } from "@canonical/ke";
 import { buildQuery } from "../../shared/buildQuery.js";
 import { P } from "../../shared/prefixes.js";
-import type { CategorySummary } from "../../shared/types.js";
+import type { CategorySummary } from "../../shared/types/index.js";
 
 export default async function listCategories(
   store: Store,

package/src/domains/standard/operations/list.ts

@@ -14,7 +14,7 @@ import { P } from "../../shared/prefixes.js";
 import type {
   StandardListFilters,
   StandardSummary,
-} from "../../shared/types.js";
+} from "../../shared/types/index.js";
 
 export default async function listStandards(
   store: Store,

package/src/domains/standard/operations/lookup.ts

@@ -18,7 +18,7 @@ import resolveUri from "../../graph/helpers/resolveUri.js";
 import { buildQuery } from "../../shared/buildQuery.js";
 import compactUri from "../../shared/compactUri.js";
 import { P } from "../../shared/prefixes.js";
-import type { CodeBlock, StandardDetailed } from "../../shared/types.js";
+import type { CodeBlock, StandardDetailed } from "../../shared/types/index.js";
 
 export default async function lookupStandard(
   store: Store,

package/src/domains/standard/orchestration/buildStandardFilters.ts

@@ -1,4 +1,4 @@
-import type { StandardListFilters } from "../../shared/types.js";
+import type { StandardListFilters } from "../../shared/types/index.js";
 
 export default function buildStandardFilters(params: {
   category?: string;

package/src/domains/standard/orchestration/resolveStandardList.ts

@@ -1,6 +1,9 @@
 import type { ListParams } from "../../shared/contracts.js";
 import type { PragmaRuntime } from "../../shared/runtime.js";
-import type { Disclosure, StandardListFilters } from "../../shared/types.js";
+import type {
+  Disclosure,
+  StandardListFilters,
+} from "../../shared/types/index.js";
 import { listStandards, lookupStandard } from "../operations/index.js";
 import type { StandardListResolution } from "../types.js";
 import buildStandardFilters from "./buildStandardFilters.js";

package/src/domains/standard/orchestration/resolveStandardLookup.ts

@@ -1,7 +1,7 @@
 import type { LookupContract, LookupResult } from "../../shared/contracts.js";
 import lookupMany from "../../shared/lookupMany.js";
 import type { PragmaRuntime } from "../../shared/runtime.js";
-import type { StandardDetailed } from "../../shared/types.js";
+import type { StandardDetailed } from "../../shared/types/index.js";
 import { lookupStandard } from "../operations/index.js";
 
 export default async function resolveStandardLookup(

package/src/domains/standard/orchestration/standardEmptyError.ts

@@ -1,5 +1,5 @@
 import { PragmaError } from "#error";
-import type { StandardListFilters } from "../../shared/types.js";
+import type { StandardListFilters } from "../../shared/types/index.js";
 
 export default function standardEmptyError(
   filters: StandardListFilters,

package/src/domains/standard/standardConfig.ts

@@ -0,0 +1,42 @@
+import type { EntityDisplayConfig } from "../shared/contracts.js";
+import { P } from "../shared/prefixes.js";
+import type {
+  FilterConfig,
+  StandardDetailed,
+  StandardDigest,
+  StandardSummary,
+} from "../shared/types/index.js";
+
+/** Display-contract configuration for code-standard entities. */
+export const standardConfig: EntityDisplayConfig<
+  StandardSummary,
+  StandardDigest,
+  StandardDetailed
+> = {
+  domain: "standard",
+  entityName: "standard",
+  rdfTypes: [`${P.cs}CodeStandard`],
+  listColumns: [
+    { key: "uri", label: "IRI" },
+    { key: "name", label: "Name" },
+    { key: "category", label: "Category" },
+    { key: "description", label: "Description" },
+  ],
+  digestColumns: [{ key: "extends", label: "Extends", showWhenEmpty: false }],
+  lookupSections: [
+    { key: "description", heading: "Description", kind: "field" },
+    { key: "extends", heading: "Extends", kind: "field", showWhenEmpty: false },
+    { key: "dos", heading: "Do", kind: "table", showWhenEmpty: false },
+    { key: "donts", heading: "Don't", kind: "table", showWhenEmpty: false },
+  ],
+  emptyRecovery: (_filters: FilterConfig) => ({
+    message: "List available standards.",
+    cli: "pragma standard list",
+    mcp: { tool: "standard_list" },
+  }),
+  notFoundRecovery: (_query: string) => ({
+    message: "List available standards.",
+    cli: "pragma standard list",
+    mcp: { tool: "standard_list" },
+  }),
+};

package/src/domains/standard/types.ts

@@ -4,7 +4,7 @@ import type {
   StandardDetailed,
   StandardListFilters,
   StandardSummary,
-} from "../shared/types.js";
+} from "../shared/types/index.js";
 
 export interface StandardListResolution {
   readonly params: ListParams & StandardListFilters;

package/src/domains/tier/commands/list.ts

@@ -10,11 +10,20 @@ import {
   createOutputResult,
 } from "@canonical/cli-core";
 import { PragmaError } from "#error";
+import { createListView } from "#tui";
 import type { PragmaContext } from "../../shared/context.js";
+import type { ColumnDef } from "../../shared/contracts.js";
 import { selectFormatter } from "../../shared/formatters.js";
+import type { TierEntry } from "../../shared/types/tier.js";
 import { listFormatters } from "../formatters/index.js";
 import { listTiers } from "../operations/index.js";
 
+const tierListColumns: readonly ColumnDef<TierEntry>[] = [
+  { key: "uri", label: "IRI" },
+  { key: "path", label: "Path" },
+  { key: "parent", label: "Parent" },
+];
+
 export default function listCommand(ctx: PragmaContext): CommandDefinition {
   return {
     path: ["tier", "list"],
@@ -37,6 +46,13 @@ export default function listCommand(ctx: PragmaContext): CommandDefinition {
 
       return createOutputResult(tiers, {
         plain: selectFormatter(ctx, listFormatters),
+        ink: (data) =>
+          createListView({
+            heading: "Tiers",
+            domain: "tier",
+            items: data,
+            columns: tierListColumns,
+          }),
       });
     },
   };

package/src/domains/tier/formatters/list.test.ts

@@ -1,6 +1,6 @@
 import type { URI } from "@canonical/ke";
 import { describe, expect, it } from "vitest";
-import type { TierEntry } from "../../shared/types.js";
+import type { TierEntry } from "../../shared/types/index.js";
 import formatters from "./list.js";
 
 const TIERS: TierEntry[] = [

package/src/domains/tier/formatters/list.ts

@@ -1,3 +1,8 @@
+import compactUri from "../../shared/compactUri.js";
+import type { Formatters } from "../../shared/formatters.js";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+import type { TierEntry } from "../../shared/types/index.js";
+
 /**
  * Three-mode formatter for `pragma tier list` output.
  *
@@ -7,17 +12,15 @@
  *   by the MCP adapter when `condensed: true`.
  * - **json** — structured JSON array for programmatic consumption.
  */
-
-import type { Formatters } from "../../shared/formatters.js";
-import type { TierEntry } from "../../shared/types.js";
-
 const formatters: Formatters<TierEntry[]> = {
   plain: (tiers) => {
     const lines: string[] = [];
     for (const t of tiers) {
       const indent = "  ".repeat(t.depth);
       const parent = t.parent ? ` (parent: ${t.parent})` : "";
-      lines.push(`${indent}${t.path}${parent}`);
+      lines.push(
+        `${compactUri(t.uri, PREFIX_MAP)}  ${indent}${t.path}${parent}`,
+      );
     }
     return lines.join("\n");
   },
@@ -29,7 +32,9 @@ const formatters: Formatters<TierEntry[]> = {
     for (const t of tiers) {
       const indent = "  ".repeat(t.depth);
       const parent = t.parent ? ` (parent: ${t.parent})` : "";
-      lines.push(`${indent}- **${t.path}**${parent}`);
+      lines.push(
+        `${indent}- **${t.path}** \`${compactUri(t.uri, PREFIX_MAP)}\`${parent}`,
+      );
     }
     return lines.join("\n");
   },

package/src/domains/tier/operations/list.ts

@@ -9,7 +9,7 @@
 import type { Store, URI } from "@canonical/ke";
 import { buildQuery } from "../../shared/buildQuery.js";
 import { P } from "../../shared/prefixes.js";
-import type { TierEntry } from "../../shared/types.js";
+import type { TierEntry } from "../../shared/types/index.js";
 
 export default async function listTiers(store: Store): Promise<TierEntry[]> {
   const result = await store.query(

package/src/domains/token/commands/list.ts

@@ -9,10 +9,12 @@ import {
   type CommandDefinition,
   createOutputResult,
 } from "@canonical/cli-core";
+import { createListView } from "#tui";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
 import { listFormatters } from "../formatters/index.js";
 import { resolveTokenList } from "../orchestration/index.js";
+import { tokenConfig } from "../tokenConfig.js";
 
 export default function listCommand(ctx: PragmaContext): CommandDefinition {
   return {
@@ -39,6 +41,13 @@ export default function listCommand(ctx: PragmaContext): CommandDefinition {
 
       return createOutputResult([...resolution.items], {
         plain: selectFormatter(ctx, listFormatters),
+        ink: (data) =>
+          createListView({
+            heading: "Tokens",
+            domain: "token",
+            items: data,
+            columns: tokenConfig.listColumns,
+          }),
       });
     },
   };

package/src/domains/token/commands/lookup.ts

@@ -9,9 +9,14 @@ import {
   type CommandDefinition,
   createOutputResult,
 } from "@canonical/cli-core";
+import { createLookupView } from "#tui";
 import type { PragmaContext } from "../../shared/context.js";
 import type { LookupResult } from "../../shared/contracts.js";
-import { createLookupFormatters } from "../formatters/index.js";
+import { renderLookupResults } from "../../shared/formatters.js";
+import {
+  createLookupFormatters,
+  createTokenInkLookupOptions,
+} from "../formatters/index.js";
 import type { lookupToken } from "../operations/index.js";
 import { resolveTokenLookup } from "../orchestration/index.js";
 
@@ -56,7 +61,22 @@ export default function buildLookupCommand(
 
       return createOutputResult<TokenLookupOutput>(
         { result: contract.result, detailed },
-        { plain: renderTokenLookupOutput(ctx) },
+        {
+          plain: ({ result, detailed: isDetailed }) =>
+            renderLookupResults({
+              ctx,
+              result,
+              formatters: createLookupFormatters({ detailed: isDetailed }),
+              mapResult: (token) => token,
+            }),
+          ink: ({ result, detailed: isDetailed }) =>
+            createLookupView({
+              results: result.results,
+              errors: result.errors,
+              domain: "token",
+              options: createTokenInkLookupOptions({ detailed: isDetailed }),
+            }),
+        },
       );
     },
   };
@@ -73,49 +93,3 @@ function normalizeNames(names: unknown, legacyName?: unknown): string[] {
   }
   return [];
 }
-
-function renderTokenLookupOutput(
-  ctx: PragmaContext,
-): (data: TokenLookupOutput) => string {
-  return ({ result, detailed }) => {
-    const formatters = createLookupFormatters({ detailed });
-    const formatOne =
-      ctx.globalFlags.format === "json"
-        ? formatters.json
-        : ctx.globalFlags.llm
-          ? formatters.llm
-          : formatters.plain;
-
-    if (ctx.globalFlags.format === "json") {
-      if (result.results.length === 1 && result.errors.length === 0) {
-        const only = result.results[0];
-        return only
-          ? formatters.json(only)
-          : JSON.stringify({ results: [], errors: result.errors }, null, 2);
-      }
-
-      return JSON.stringify(
-        {
-          results: result.results.map((token) =>
-            JSON.parse(formatters.json(token)),
-          ),
-          errors: result.errors,
-        },
-        null,
-        2,
-      );
-    }
-
-    const parts = result.results.map((token) => formatOne(token));
-    if (result.errors.length > 0) {
-      parts.push(
-        [
-          "Errors:",
-          ...result.errors.map((error) => `- ${error.query}: ${error.message}`),
-        ].join("\n"),
-      );
-    }
-
-    return parts.join("\n\n");
-  };
-}

package/src/domains/token/formatters/index.ts

@@ -1,4 +1,7 @@
 /** @module Re-exports token formatters (`createLookupFormatters`, `listFormatters`). */
 
 export { default as listFormatters } from "./list.js";
-export { createLookupFormatters } from "./lookup.js";
+export {
+  createInkLookupOptions as createTokenInkLookupOptions,
+  default as createLookupFormatters,
+} from "./lookup.js";

package/src/domains/token/formatters/list.test.ts

@@ -1,6 +1,6 @@
 import type { URI } from "@canonical/ke";
 import { describe, expect, it } from "vitest";
-import type { TokenSummary } from "../../shared/types.js";
+import type { TokenSummary } from "../../shared/types/index.js";
 import formatters from "./list.js";
 
 const TOKENS: TokenSummary[] = [

package/src/domains/token/formatters/list.ts

@@ -1,35 +1,22 @@
-/**
- * Three-mode formatter for `pragma token list` output.
- *
- * - **plain** — one line per token showing name and optional category.
- * - **llm** — condensed Markdown consumed by LLM agents and reused
- *   by the MCP adapter when `condensed: true`.
- * - **json** — structured JSON array for programmatic consumption.
- */
-
 import type { Formatters } from "../../shared/formatters.js";
-import type { TokenSummary } from "../../shared/types.js";
+import { renderListLlm } from "../../shared/renderers.js";
+import type { TokenSummary } from "../../shared/types/index.js";
+import { tokenConfig } from "../tokenConfig.js";
 
+/** Three-mode formatter for `pragma token list` output. */
 const formatters: Formatters<TokenSummary[]> = {
-  plain: (tokens) => {
-    const lines: string[] = [];
-    for (const t of tokens) {
-      const cat = t.category ? ` [${t.category}]` : "";
-      lines.push(`${t.name}${cat}`);
-    }
-    return lines.join("\n");
-  },
+  plain: (tokens) =>
+    tokens
+      .map((token) =>
+        token.category ? `${token.name} [${token.category}]` : token.name,
+      )
+      .join("\n"),
 
-  llm: (tokens) => {
-    const lines: string[] = [];
-    lines.push("## Design Tokens");
-    lines.push("");
-    for (const t of tokens) {
-      const cat = t.category ? ` [${t.category}]` : "";
-      lines.push(`- **${t.name}**${cat}`);
-    }
-    return lines.join("\n");
-  },
+  llm: (tokens) =>
+    renderListLlm(tokens, {
+      heading: "Design Tokens",
+      columns: tokenConfig.listColumns,
+    }),
 
   json: (tokens) => JSON.stringify(tokens, null, 2),
 };

package/src/domains/token/formatters/lookup.test.ts

@@ -1,7 +1,7 @@
 import type { URI } from "@canonical/ke";
 import { describe, expect, it } from "vitest";
-import type { TokenDetailed } from "../../shared/types.js";
-import { createLookupFormatters } from "./lookup.js";
+import type { TokenDetailed } from "../../shared/types/index.js";
+import createLookupFormatters from "./lookup.js";
 
 const DETAILED: TokenDetailed = {
   uri: "http://example.com/t1" as URI,