@canonical/pragma-cli 0.20.0 → 0.21.0

package/src/domains/shared/types/ontology.ts

@@ -0,0 +1,50 @@
+/** Ontology inspection return types. */
+
+/** Summary of a loaded ontology namespace from `ontology list`. */
+export interface OntologySummary {
+  /** Short prefix alias (e.g., `"ds"`, `"cs"`). */
+  readonly prefix: string;
+  /** Full namespace URI the prefix expands to. */
+  readonly namespace: string;
+  /** Number of OWL/RDFS classes defined in this namespace. */
+  readonly classCount: number;
+  /** Number of properties (object + datatype) defined in this namespace. */
+  readonly propertyCount: number;
+  readonly anatomyCount: number;
+}
+
+/** A class in an ontology's class hierarchy. */
+export interface OntologyClass {
+  /** Full URI of the class. */
+  readonly uri: string;
+  /** Human-readable label (rdfs:label). */
+  readonly label: string;
+  /** URI of the direct superclass, if declared. */
+  readonly superclass?: string;
+}
+
+/** A property in an ontology namespace. */
+export interface OntologyProperty {
+  /** Full URI of the property. */
+  readonly uri: string;
+  /** Human-readable label (rdfs:label). */
+  readonly label: string;
+  /** URI of the domain class this property applies to, if declared. */
+  readonly domain?: string;
+  /** URI of the range class or datatype, if declared. */
+  readonly range?: string;
+  /** Whether this is an object property (links classes) or datatype property (links to literals). */
+  readonly type: "object" | "datatype";
+}
+
+/** Detailed view of a single ontology namespace from `ontology show`. */
+export interface OntologyDetailed {
+  /** Short prefix alias (e.g., `"ds"`). */
+  readonly prefix: string;
+  /** Full namespace URI the prefix expands to. */
+  readonly namespace: string;
+  /** All classes defined in this namespace. */
+  readonly classes: readonly OntologyClass[];
+  /** All properties defined in this namespace. */
+  readonly properties: readonly OntologyProperty[];
+}

package/src/domains/shared/types/runtime.ts

@@ -0,0 +1,21 @@
+/** Boot-time state shared by CLI, MCP, and completions server. */
+
+import type { Store } from "@canonical/ke";
+import type { PragmaConfig } from "#config";
+
+/**
+ * Boot-time state shared by CLI, MCP, and completions server.
+ *
+ * Four members:
+ * - `store` — the ke triple store, loaded and ready for SPARQL queries.
+ * - `config` — resolved pragma config (tier, channel).
+ * - `cwd` — working directory used for config and source resolution.
+ * - `dispose()` — tears down the store and frees WASM memory. Must be
+ *   called exactly once; calling operations after dispose is undefined.
+ */
+export interface PragmaRuntime {
+  readonly store: Store;
+  readonly config: PragmaConfig;
+  readonly cwd: string;
+  dispose(): void;
+}

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

@@ -0,0 +1,64 @@
+/** Standard domain return types. */
+
+import type { URI } from "@canonical/ke";
+
+/** Summary view of a design-system standard (guideline or rule). */
+export interface StandardSummary {
+  /** Full RDF URI identifying this standard in the ke store. */
+  readonly uri: URI;
+  /** Human-readable name of the standard. */
+  readonly name: string;
+  /** Category grouping (e.g., `"accessibility"`, `"layout"`). */
+  readonly category: string;
+  /** Brief prose description of what the standard prescribes. */
+  readonly description: string;
+  /** URI of the parent standard this one extends, if any. */
+  readonly extends?: string;
+}
+
+/** Digest view of a standard for generic list contracts. */
+export type StandardDigest = StandardSummary;
+
+/** Fenced code block used in standard do/don't examples. */
+export interface CodeBlock {
+  /** Programming language identifier for syntax highlighting. */
+  readonly language: string;
+  /** Source code content of the example. */
+  readonly code: string;
+  /** Optional explanatory caption displayed alongside the code. */
+  readonly caption?: string;
+}
+
+/** Detailed view of a standard, extending the summary with code examples. */
+export interface StandardDetailed extends StandardSummary {
+  /** Positive examples demonstrating correct usage. */
+  readonly dos: readonly CodeBlock[];
+  /** Negative examples demonstrating incorrect usage. */
+  readonly donts: readonly CodeBlock[];
+}
+
+/** Summary of a standards category with its member count. */
+export interface CategorySummary {
+  /** Category name (e.g., `"accessibility"`, `"layout"`). */
+  readonly name: string;
+  /** Number of standards belonging to this category. */
+  readonly standardCount: number;
+}
+
+/** Optional filters for narrowing the standards list. */
+export interface StandardListFilters {
+  /** Restrict results to a single category name. */
+  readonly category?: string;
+  /** Free-text search term matched against standard names and descriptions. */
+  readonly search?: string;
+}
+
+/** Lightweight reference to a standard, used in block cross-references. */
+export interface StandardRef {
+  /** Human-readable standard name. */
+  readonly name: string;
+  /** Full RDF URI of the referenced standard. */
+  readonly uri: URI;
+  /** Category the referenced standard belongs to. */
+  readonly category: string;
+}

package/src/domains/shared/types/tier.ts

@@ -0,0 +1,15 @@
+/** Tier hierarchy return types. */
+
+import type { URI } from "@canonical/ke";
+
+/** A single entry in the tier hierarchy (e.g., `global`, `apps`, `apps/lxd`). */
+export interface TierEntry {
+  /** Full RDF URI identifying this tier in the ke store. */
+  readonly uri: URI;
+  /** Slash-separated tier path (e.g., `"apps/lxd"`). */
+  readonly path: string;
+  /** Path of the parent tier, if this is not the root. */
+  readonly parent?: string;
+  /** Nesting depth in the tier hierarchy (0 = root). */
+  readonly depth: number;
+}

package/src/domains/shared/types/token.ts

@@ -0,0 +1,30 @@
+/** Token domain return types. */
+
+import type { URI } from "@canonical/ke";
+
+/** Summary view of a design token. */
+export interface TokenSummary {
+  /** Full RDF URI identifying this token in the ke store. */
+  readonly uri: URI;
+  /** Human-readable token name (e.g., `"color-primary"`). */
+  readonly name: string;
+  /** Token category (e.g., `"color"`, `"spacing"`, `"typography"`). */
+  readonly category: string;
+}
+
+/** Digest view of a token for generic list contracts. */
+export type TokenDigest = TokenSummary;
+
+/** Detailed view of a token, extending the summary with per-theme resolved values. */
+export interface TokenDetailed extends TokenSummary {
+  /** Resolved values keyed by theme (e.g., `{ theme: "dark", value: "#fff" }`). */
+  readonly values: readonly { theme: string; value: string }[];
+}
+
+/** Lightweight reference to a token (name + URI), used in cross-references. */
+export interface TokenRef {
+  /** Human-readable token name. */
+  readonly name: string;
+  /** Full RDF URI of the referenced token. */
+  readonly uri: URI;
+}

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

@@ -11,11 +11,13 @@ import {
   type CommandResult,
   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 type { StandardListOutput } from "../formatters/types.js";
 import { resolveStandardList } from "../orchestration/index.js";
+import { standardConfig } from "../standardConfig.js";
 
 export default function buildListCommand(
   ctx: PragmaContext,
@@ -75,6 +77,13 @@ export default function buildListCommand(
 
       return createOutputResult(output, {
         plain: selectFormatter(ctx, listFormatters),
+        ink: (data) =>
+          createListView({
+            heading: "Standards",
+            domain: "standard",
+            items: data.items,
+            columns: standardConfig.listColumns,
+          }),
       });
     },
   };

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

@@ -10,9 +10,14 @@ import {
   type CommandResult,
   createOutputResult,
 } from "@canonical/cli-core";
+import { createLookupView } from "#tui";
 import type { PragmaContext } from "../../shared/context.js";
 import type { LookupResult } from "../../shared/contracts.js";
-import { lookupFormatters } from "../formatters/index.js";
+import { renderLookupResults } from "../../shared/formatters.js";
+import {
+  createInkLookupOptions,
+  lookupFormatters,
+} from "../formatters/index.js";
 import type { lookupStandard } from "../operations/index.js";
 import { resolveStandardLookup } from "../orchestration/index.js";
 
@@ -60,7 +65,22 @@ export default function buildLookupCommand(
 
       return createOutputResult<StandardLookupOutput>(
         { result: contract.result, detailed },
-        { plain: renderStandardLookupOutput(ctx) },
+        {
+          plain: ({ result, detailed: isDetailed }) =>
+            renderLookupResults({
+              ctx,
+              result,
+              formatters: lookupFormatters,
+              mapResult: (standard) => ({ standard, detailed: isDetailed }),
+            }),
+          ink: ({ result, detailed: isDetailed }) =>
+            createLookupView({
+              results: result.results,
+              errors: result.errors,
+              domain: "standard",
+              options: createInkLookupOptions(isDetailed),
+            }),
+        },
       );
     },
   };
@@ -77,51 +97,3 @@ function normalizeNames(names: unknown, legacyName?: unknown): string[] {
   }
   return [];
 }
-
-function renderStandardLookupOutput(
-  ctx: PragmaContext,
-): (data: StandardLookupOutput) => string {
-  return ({ result, detailed }) => {
-    const formatOne =
-      ctx.globalFlags.format === "json"
-        ? lookupFormatters.json
-        : ctx.globalFlags.llm
-          ? lookupFormatters.llm
-          : lookupFormatters.plain;
-
-    if (ctx.globalFlags.format === "json") {
-      if (result.results.length === 1 && result.errors.length === 0) {
-        const only = result.results[0];
-        return only
-          ? lookupFormatters.json({ standard: only, detailed })
-          : JSON.stringify({ results: [], errors: result.errors }, null, 2);
-      }
-
-      return JSON.stringify(
-        {
-          results: result.results.map((standard) =>
-            JSON.parse(lookupFormatters.json({ standard, detailed })),
-          ),
-          errors: result.errors,
-        },
-        null,
-        2,
-      );
-    }
-
-    const parts = result.results.map((standard) =>
-      formatOne({ standard, detailed }),
-    );
-
-    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/standard/formatters/categories.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import type { CategorySummary } from "../../shared/types.js";
+import type { CategorySummary } from "../../shared/types/index.js";
 import formatters from "./categories.js";
 
 const CATEGORIES: CategorySummary[] = [

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

@@ -8,7 +8,7 @@
  */
 
 import type { Formatters } from "../../shared/formatters.js";
-import type { CategorySummary } from "../../shared/types.js";
+import type { CategorySummary } from "../../shared/types/index.js";
 
 const formatters: Formatters<readonly CategorySummary[]> = {
   plain(categories) {

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

@@ -2,5 +2,8 @@
 
 export { default as categoriesFormatters } from "./categories.js";
 export { default as listFormatters } from "./list.js";
-export { default as lookupFormatters } from "./lookup.js";
+export {
+  createInkLookupOptions,
+  default as lookupFormatters,
+} from "./lookup.js";
 export type { StandardListOutput, StandardLookupInput } from "./types.js";

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

@@ -1,6 +1,9 @@
 import type { URI } from "@canonical/ke";
 import { describe, expect, it } from "vitest";
-import type { StandardDetailed, StandardSummary } from "../../shared/types.js";
+import type {
+  StandardDetailed,
+  StandardSummary,
+} from "../../shared/types/index.js";
 import formatters from "./list.js";
 import type { StandardListOutput } from "./types.js";
 

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

@@ -1,19 +1,5 @@
-/**
- * Three-mode formatter for `pragma standard list` output.
- *
- * - **plain** — terminal text with progressive disclosure.
- * - **llm** — condensed Markdown consumed by LLM agents and reused
- *   by the MCP adapter when `condensed: true`.
- * - **json** — structured JSON; enrichment varies by disclosure level.
- *
- * Disclosure levels:
- *   - summary  — name + category + description (default)
- *   - digest   — summary + first do example (truncated)
- *   - detailed — summary + full dos/donts
- */
-
 import type { Formatters } from "../../shared/formatters.js";
-import type { CodeBlock, StandardDetailed } from "../../shared/types.js";
+import type { CodeBlock, StandardDetailed } from "../../shared/types/index.js";
 import type { StandardListOutput } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -22,6 +8,17 @@ import type { StandardListOutput } from "./types.js";
 
 const DEFAULT_MAX_EXAMPLE_LENGTH = 120;
 
+interface StandardListRow {
+  readonly uri: StandardDetailed["uri"];
+  readonly name: StandardDetailed["name"];
+  readonly category: StandardDetailed["category"];
+  readonly description: StandardDetailed["description"];
+  readonly extends?: StandardDetailed["extends"];
+  readonly example?: string;
+  readonly dos?: StandardDetailed["dos"];
+  readonly donts?: StandardDetailed["donts"];
+}
+
 function truncate(text: string, max: number): string {
   const oneLine = text.replace(/\n/g, " ").trim();
   return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
@@ -40,82 +37,21 @@ function firstDoExample(
 // Plain
 // ---------------------------------------------------------------------------
 
-function plain({ items, details, disclosure }: StandardListOutput): string {
-  const lines: string[] = [];
-
-  for (const [i, s] of items.entries()) {
-    const cat = s.category ? ` [${s.category}]` : "";
-    lines.push(`${s.name}${cat}`);
-    lines.push(`  ${s.description}`);
-
-    if (disclosure.level === "digest") {
-      const maxLen = disclosure.maxExampleLength ?? DEFAULT_MAX_EXAMPLE_LENGTH;
-      const example = firstDoExample(details?.[i], maxLen);
-      if (example) {
-        lines.push(`  Example: ${example}`);
-      }
-    }
-
-    if (disclosure.level === "detailed") {
-      const detail = details?.[i];
-      if (detail) {
-        if (detail.dos.length > 0) {
-          lines.push("  Do:");
-          for (const d of detail.dos) {
-            lines.push(`    ${d.code}`);
-          }
-        }
-        if (detail.donts.length > 0) {
-          lines.push("  Don't:");
-          for (const d of detail.donts) {
-            lines.push(`    ${d.code}`);
-          }
-        }
-      }
-    }
-  }
-
-  return lines.join("\n");
+function plain(output: StandardListOutput): string {
+  return buildRows(output)
+    .map((row) => formatPlainRow(row, output.disclosure.level))
+    .join("\n\n");
 }
 
 // ---------------------------------------------------------------------------
 // LLM
 // ---------------------------------------------------------------------------
 
-function llm({ items, details, disclosure }: StandardListOutput): string {
-  const lines: string[] = [];
-  lines.push("## Standards");
-  lines.push("");
-
-  for (const [i, s] of items.entries()) {
-    const cat = s.category ? ` [${s.category}]` : "";
-    lines.push(`- **${s.name}**${cat}: ${s.description}`);
-
-    if (disclosure.level === "digest") {
-      const maxLen = disclosure.maxExampleLength ?? DEFAULT_MAX_EXAMPLE_LENGTH;
-      const example = firstDoExample(details?.[i], maxLen);
-      if (example) {
-        lines.push(`  - Example: \`${example}\``);
-      }
-    }
+function llm(output: StandardListOutput): string {
+  const lines = ["## Standards", ""];
 
-    if (disclosure.level === "detailed") {
-      const detail = details?.[i];
-      if (detail) {
-        if (detail.dos.length > 0) {
-          lines.push("  - **Do**:");
-          for (const d of detail.dos) {
-            lines.push(`    - ${d.code}`);
-          }
-        }
-        if (detail.donts.length > 0) {
-          lines.push("  - **Don't**:");
-          for (const d of detail.donts) {
-            lines.push(`    - ${d.code}`);
-          }
-        }
-      }
-    }
+  for (const row of buildRows(output)) {
+    lines.push(formatLlmRow(row, output.disclosure.level));
   }
 
   return lines.join("\n");
@@ -151,6 +87,98 @@ function json({ items, details, disclosure }: StandardListOutput): string {
 // Export
 // ---------------------------------------------------------------------------
 
+/** Three-mode formatter for `pragma standard list` output. */
 const formatters: Formatters<StandardListOutput> = { plain, llm, json };
 
 export default formatters;
+
+function buildRows({
+  items,
+  details,
+  disclosure,
+}: StandardListOutput): readonly StandardListRow[] {
+  if (disclosure.level === "summary") {
+    return items;
+  }
+
+  if (disclosure.level === "digest") {
+    const maxLen = disclosure.maxExampleLength ?? DEFAULT_MAX_EXAMPLE_LENGTH;
+    return items.map((item, index) => ({
+      ...item,
+      extends: details?.[index]?.extends,
+      example: firstDoExample(details?.[index], maxLen),
+    }));
+  }
+
+  return items.map((item, index) => ({
+    ...item,
+    extends: details?.[index]?.extends,
+    dos: details?.[index]?.dos,
+    donts: details?.[index]?.donts,
+  }));
+}
+
+function formatPlainRow(
+  row: StandardListRow,
+  level: StandardListOutput["disclosure"]["level"],
+): string {
+  const lines = [formatHeading(row), `  ${row.description}`];
+
+  if (row.extends) {
+    lines.push(`  Extends: ${row.extends}`);
+  }
+
+  if (level === "digest" && row.example) {
+    lines.push(`  Example: ${row.example}`);
+  }
+
+  if (level === "detailed") {
+    if (row.dos && row.dos.length > 0) {
+      lines.push("  Do:");
+      lines.push(...row.dos.map((item) => `    ${item.code}`));
+    }
+
+    if (row.donts && row.donts.length > 0) {
+      lines.push("  Don't:");
+      lines.push(...row.donts.map((item) => `    ${item.code}`));
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatLlmRow(
+  row: StandardListRow,
+  level: StandardListOutput["disclosure"]["level"],
+): string {
+  const lines = [
+    `- **${row.name}**${row.category ? ` [${row.category}]` : ""}`,
+  ];
+  lines.push(`  ${row.description}`);
+
+  if (row.extends) {
+    lines.push(`  Extends: ${row.extends}`);
+  }
+
+  if (level === "digest" && row.example) {
+    lines.push(`  Example: \`${row.example}\``);
+  }
+
+  if (level === "detailed") {
+    if (row.dos && row.dos.length > 0) {
+      lines.push("  **Do**:");
+      lines.push(...row.dos.map((item) => `  - ${item.code}`));
+    }
+
+    if (row.donts && row.donts.length > 0) {
+      lines.push("  **Don't**:");
+      lines.push(...row.donts.map((item) => `  - ${item.code}`));
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatHeading(row: StandardListRow): string {
+  return row.category ? `${row.name} [${row.category}]` : row.name;
+}

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

@@ -1,6 +1,6 @@
 import type { URI } from "@canonical/ke";
 import { describe, expect, it } from "vitest";
-import type { StandardDetailed } from "../../shared/types.js";
+import type { StandardDetailed } from "../../shared/types/index.js";
 import formatters from "./lookup.js";
 
 const DETAILED: StandardDetailed = {