@canonical/pragma-cli 0.20.0 → 0.21.0

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

@@ -1,65 +1,80 @@
-/**
- * Three-mode formatter factory for `pragma token lookup` output.
- *
- * - **plain** — terminal text showing token name, category, and optional
- *   per-theme values when detailed.
- * - **llm** — condensed Markdown consumed by LLM agents and reused
- *   by the MCP adapter when `condensed: true`.
- * - **json** — structured JSON; omits values unless detailed.
- */
-
+import type { RenderLookupOptions } from "../../shared/contracts.js";
 import type { Formatters } from "../../shared/formatters.js";
-import type { TokenDetailed } from "../../shared/types.js";
+import { renderLookupLlm, renderLookupPlain } from "../../shared/renderers.js";
+import type { TokenDetailed } from "../../shared/types/index.js";
+import { tokenConfig } from "../tokenConfig.js";
 
 /** Options controlling detail level for the token-lookup formatter. */
-export interface TokenLookupFormatterOptions {
+interface TokenLookupFormatterOptions {
   readonly detailed: boolean;
 }
 
 /**
- * Creates a three-mode formatter set for a single token, capturing the
- * detail level in the closure so callers only pass the token data.
+ * Create a three-mode formatter set for a single token.
+ *
+ * Captures the detail level in the closure so callers only pass the token data.
  *
  * @param options - detail-level options
  * @returns plain/llm/json formatters for {@link TokenDetailed}
  */
-export function createLookupFormatters(
+export default function createLookupFormatters(
   options: TokenLookupFormatterOptions,
 ): Formatters<TokenDetailed> {
   const { detailed } = options;
+  const sections = detailed ? tokenConfig.lookupSections : [];
 
   return {
-    plain: (token) => {
-      const lines: string[] = [];
-      lines.push(token.name);
-      lines.push(`Category: ${token.category || "—"}`);
-
-      if (detailed && token.values.length > 0) {
-        lines.push("");
-        lines.push("Values:");
-        for (const v of token.values) {
-          lines.push(`  ${v.theme}: ${v.value}`);
-        }
-      }
-
-      return lines.join("\n");
-    },
-
-    llm: (token) => {
-      const lines: string[] = [];
-      lines.push(`## ${token.name}`);
-      lines.push(`Category: ${token.category || "—"}`);
-
-      if (detailed && token.values.length > 0) {
-        lines.push("");
-        lines.push("### Values");
-        for (const v of token.values) {
-          lines.push(`- ${v.theme}: \`${v.value}\``);
-        }
-      }
+    plain: (token) =>
+      renderLookupPlain(token, {
+        title: (entry) => entry.name,
+        fields: [
+          { label: "URI", value: (entry) => entry.uri },
+          { label: "Category", value: (entry) => entry.category || "—" },
+        ],
+        sections,
+        sectionOverrides: {
+          values: {
+            plain: (entry) =>
+              entry.values.length > 0
+                ? entry.values
+                    .map((value) => `  ${value.theme}: ${value.value}`)
+                    .join("\n")
+                : null,
+            llm: (entry) =>
+              entry.values.length > 0
+                ? entry.values
+                    .map((value) => `- ${value.theme}: \`${value.value}\``)
+                    .join("\n")
+                : null,
+          },
+        },
+      }),
 
-      return lines.join("\n");
-    },
+    llm: (token) =>
+      renderLookupLlm(token, {
+        title: (entry) => entry.name,
+        fields: [
+          { label: "URI", value: (entry) => entry.uri },
+          { label: "Category", value: (entry) => entry.category || "—" },
+        ],
+        sections,
+        sectionOverrides: {
+          values: {
+            plain: (entry) =>
+              entry.values.length > 0
+                ? entry.values
+                    .map((value) => `  ${value.theme}: ${value.value}`)
+                    .join("\n")
+                : null,
+            llm: (entry) =>
+              entry.values.length > 0
+                ? entry.values
+                    .map((value) => `- ${value.theme}: \`${value.value}\``)
+                    .join("\n")
+                : null,
+          },
+        },
+      }),
 
     json: (token) => {
       if (detailed) {
@@ -70,3 +85,23 @@ export function createLookupFormatters(
     },
   };
 }
+
+/**
+ * Build lookup rendering options for the Ink TUI view.
+ *
+ * @param options - detail-level options
+ * @returns Options compatible with the LookupView component.
+ */
+export function createInkLookupOptions(
+  options: TokenLookupFormatterOptions,
+): RenderLookupOptions<TokenDetailed> {
+  const sections = options.detailed ? tokenConfig.lookupSections : [];
+  return {
+    title: (entry) => entry.name,
+    fields: [
+      { label: "URI", value: (entry) => entry.uri },
+      { label: "Category", value: (entry) => entry.category || "—" },
+    ],
+    sections,
+  };
+}

package/src/domains/token/index.ts

@@ -30,3 +30,4 @@ export {
   resolveTokenLookup,
   tokenEmptyError,
 } from "./orchestration/index.js";
+export { tokenConfig } from "./tokenConfig.js";

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

@@ -11,7 +11,7 @@ import type { Store, URI } from "@canonical/ke";
 import { escapeSparqlValue } from "@canonical/ke";
 import { buildQuery } from "../../shared/buildQuery.js";
 import { P } from "../../shared/prefixes.js";
-import type { TokenSummary } from "../../shared/types.js";
+import type { TokenSummary } from "../../shared/types/index.js";
 
 /** Optional filters for the token list operation. */
 export interface TokenListFilters {

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

@@ -15,7 +15,7 @@ import { escapeSparqlValue } from "@canonical/ke";
 import { PragmaError } from "#error";
 import { buildQuery } from "../../shared/buildQuery.js";
 import { P } from "../../shared/prefixes.js";
-import type { TokenDetailed } from "../../shared/types.js";
+import type { TokenDetailed } from "../../shared/types/index.js";
 
 export default async function lookupToken(
   store: Store,

package/src/domains/token/orchestration/resolveTokenLookup.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 { TokenDetailed } from "../../shared/types.js";
+import type { TokenDetailed } from "../../shared/types/index.js";
 import { lookupToken } from "../operations/index.js";
 
 export default async function resolveTokenLookup(

package/src/domains/token/tokenConfig.ts

@@ -0,0 +1,38 @@
+import type { EntityDisplayConfig } from "../shared/contracts.js";
+import { P } from "../shared/prefixes.js";
+import type {
+  FilterConfig,
+  TokenDetailed,
+  TokenDigest,
+  TokenSummary,
+} from "../shared/types/index.js";
+
+/** Display-contract configuration for design-token entities. */
+export const tokenConfig: EntityDisplayConfig<
+  TokenSummary,
+  TokenDigest,
+  TokenDetailed
+> = {
+  domain: "token",
+  entityName: "token",
+  rdfTypes: [`${P.ds}Token`],
+  listColumns: [
+    { key: "uri", label: "IRI" },
+    { key: "name", label: "Name" },
+    { key: "category", label: "Category" },
+  ],
+  digestColumns: [],
+  lookupSections: [
+    { key: "values", heading: "Values", kind: "table", showWhenEmpty: false },
+  ],
+  emptyRecovery: (_filters: FilterConfig) => ({
+    message: "List available tokens.",
+    cli: "pragma token list",
+    mcp: { tool: "token_list" },
+  }),
+  notFoundRecovery: (_query: string) => ({
+    message: "List available tokens.",
+    cli: "pragma token list",
+    mcp: { tool: "token_list" },
+  }),
+};

package/src/domains/token/types.ts

@@ -1,4 +1,4 @@
-import type { TokenSummary } from "../shared/types.js";
+import type { TokenSummary } from "../shared/types/index.js";
 
 export interface TokenListResolution {
   readonly params: { category?: string };

package/src/index.ts

@@ -62,7 +62,7 @@ export type {
   TokenDetailed,
   TokenRef,
   TokenSummary,
-} from "./domains/shared/types.js";
+} from "./domains/shared/types/index.js";
 
 // — Domain Operations —————————————————————————————————————————————————————————
 

package/src/mcp/runMcpServer.test.ts

@@ -53,7 +53,7 @@ describe("runMcpServer", () => {
     const result = spawnSync("bun", ["run", binPath, "mcp"], {
       input: "",
       encoding: "utf-8",
-      timeout: 10_000,
+      timeout: 20_000,
     });
 
     expect(result.error).toBeUndefined();
@@ -62,5 +62,5 @@ describe("runMcpServer", () => {
       console.error("pragma mcp stderr:", result.stderr);
     }
     expect(result.status).toBe(0);
-  });
+  }, 20_000);
 });

package/src/mcp/tools/index.ts

@@ -13,6 +13,7 @@ import { specs as configSpecs } from "../../domains/config/mcp/index.js";
 import { specs as createSpecs } from "../../domains/create/mcp/index.js";
 import { specs as diagnosticSpecs } from "../../domains/doctor/mcp/index.js";
 import { specs as graphSpecs } from "../../domains/graph/mcp/index.js";
+import { specs as infoSpecs } from "../../domains/info/mcp/index.js";
 import { specs as orientationSpecs } from "../../domains/llm/mcp/index.js";
 import { specs as modifierSpecs } from "../../domains/modifier/mcp/index.js";
 import { specs as ontologySpecs } from "../../domains/ontology/mcp/index.js";
@@ -35,6 +36,7 @@ const allSpecs: readonly ToolSpec[] = [
   ...graphSpecs,
   ...skillSpecs,
   ...diagnosticSpecs,
+  ...infoSpecs,
   ...orientationSpecs,
   ...createSpecs,
 ];

package/src/mcp/tools/registerTools.test.ts

@@ -476,11 +476,15 @@ describe("config_show", () => {
       arguments: {},
     });
     const data = parseData(result) as {
-      tier: string | null;
+      tier: string | undefined;
       channel: string;
+      tierChain: string[];
+      includedReleases: string[];
     };
     expect(data.channel).toBe("normal");
-    expect(data.tier).toBeNull();
+    expect(data.tier).toBeUndefined();
+    expect(data.tierChain).toEqual([]);
+    expect(data.includedReleases).toContain("stable");
   });
 
   it("returns condensed config text", async () => {
@@ -491,7 +495,8 @@ describe("config_show", () => {
     const envelope = parseEnvelope(result);
     expect(envelope.ok).toBe(true);
     expect(envelope.condensed).toBe(true);
-    expect(envelope.text).toBe("Config: tier=(none) channel=normal");
+    expect(typeof envelope.text).toBe("string");
+    expect(envelope.text as string).toContain("Configuration");
   });
 });
 

package/src/package-manager/types.ts

@@ -7,6 +7,4 @@ interface InstallSource {
   readonly label: string;
 }
 
-export type { PackageManager };
-
-export type { InstallSource };
+export type { InstallSource, PackageManager };

package/src/pipeline/createProgram.ts

@@ -1,7 +1,9 @@
 import {
   type CommandDefinition,
+  detectRenderMode,
   formatHelp,
   formatLlmHelp,
+  type HandleResultOptions,
   registerAll,
 } from "@canonical/cli-core";
 import { Command } from "commander";
@@ -35,6 +37,9 @@ export default function createProgram(
     writeErr: (str) => process.stderr.write(str),
   });
 
+  // Global flags (--llm, --format, --verbose) are pre-parsed by
+  // parseGlobalFlags() and stripped from argv before Commander sees it.
+  // Declaring them here keeps them visible in --help output.
   program.option(
     "--llm",
     "Condensed Markdown output for LLM consumption",
@@ -42,6 +47,8 @@ export default function createProgram(
   );
   program.option("--format <type>", "Output format (text or json)", "text");
   program.option("--verbose", "Diagnostic output to stderr", false);
+  // Commander will never see these flags in argv (they're stripped),
+  // so enablePositionalOptions() scoping can't reject them.
 
   program.addHelpText("beforeAll", (_ctx) => {
     // Only show root-level help when the help is for the root program itself.
@@ -64,7 +71,19 @@ export default function createProgram(
       await runMcpServer();
     });
 
-  registerAll(program, commands, ctx);
+  const mode = detectRenderMode(ctx.globalFlags);
+  const resultOptions: HandleResultOptions = {
+    mode,
+    renderInk:
+      mode === "ink"
+        ? async (element: unknown) => {
+            const { renderInk } = await import("#tui");
+            await renderInk(element as import("react").ReactElement);
+          }
+        : undefined,
+  };
+
+  registerAll(program, commands, ctx, resultOptions);
 
   return program;
 }

package/src/pipeline/index.ts

@@ -8,7 +8,10 @@ export {
   formatSection,
 } from "./formatTerminal.js";
 export { default as mapExitCode } from "./mapExitCode.js";
-export { default as parseGlobalFlags } from "./parseGlobalFlags.js";
+export {
+  default as parseGlobalFlags,
+  stripGlobalFlags,
+} from "./parseGlobalFlags.js";
 export {
   renderErrorJson,
   renderErrorLlm,

package/src/pipeline/parseGlobalFlags.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import parseGlobalFlags, { stripGlobalFlags } from "./parseGlobalFlags.js";
+
+describe("parseGlobalFlags", () => {
+  it("extracts --llm", () => {
+    const flags = parseGlobalFlags([
+      "node",
+      "pragma",
+      "block",
+      "list",
+      "--llm",
+    ]);
+    expect(flags.llm).toBe(true);
+  });
+
+  it("extracts --format json", () => {
+    const flags = parseGlobalFlags([
+      "node",
+      "pragma",
+      "--format",
+      "json",
+      "info",
+    ]);
+    expect(flags.format).toBe("json");
+  });
+
+  it("defaults to text when --format is absent", () => {
+    const flags = parseGlobalFlags(["node", "pragma", "info"]);
+    expect(flags.format).toBe("text");
+  });
+
+  it("extracts --verbose", () => {
+    const flags = parseGlobalFlags([
+      "node",
+      "pragma",
+      "--verbose",
+      "block",
+      "list",
+    ]);
+    expect(flags.verbose).toBe(true);
+  });
+});
+
+describe("stripGlobalFlags", () => {
+  it("removes --llm from any position", () => {
+    expect(
+      stripGlobalFlags(["node", "pragma", "--llm", "tier", "list"]),
+    ).toEqual(["node", "pragma", "tier", "list"]);
+    expect(
+      stripGlobalFlags(["node", "pragma", "tier", "list", "--llm"]),
+    ).toEqual(["node", "pragma", "tier", "list"]);
+  });
+
+  it("removes --format and its value", () => {
+    expect(
+      stripGlobalFlags(["node", "pragma", "--format", "json", "info"]),
+    ).toEqual(["node", "pragma", "info"]);
+    expect(
+      stripGlobalFlags(["node", "pragma", "info", "--format", "json"]),
+    ).toEqual(["node", "pragma", "info"]);
+  });
+
+  it("removes --verbose from any position", () => {
+    expect(
+      stripGlobalFlags(["node", "pragma", "block", "list", "--verbose"]),
+    ).toEqual(["node", "pragma", "block", "list"]);
+  });
+
+  it("removes all global flags at once", () => {
+    expect(
+      stripGlobalFlags([
+        "node",
+        "pragma",
+        "--llm",
+        "--verbose",
+        "--format",
+        "json",
+        "block",
+        "list",
+      ]),
+    ).toEqual(["node", "pragma", "block", "list"]);
+  });
+
+  it("preserves argv when no global flags present", () => {
+    expect(stripGlobalFlags(["node", "pragma", "block", "list"])).toEqual([
+      "node",
+      "pragma",
+      "block",
+      "list",
+    ]);
+  });
+});

package/src/pipeline/parseGlobalFlags.ts

@@ -19,3 +19,28 @@ export default function parseGlobalFlags(argv: readonly string[]): GlobalFlags {
     verbose: argv.includes("--verbose"),
   };
 }
+
+/**
+ * Return a copy of argv with global flags stripped out.
+ *
+ * Since {@link parseGlobalFlags} pre-parses these flags before Commander
+ * runs, we remove them so they don't collide with Commander's
+ * `enablePositionalOptions()` scoping. This lets users place `--llm`,
+ * `--format`, and `--verbose` anywhere in the command line.
+ *
+ * @param argv - Raw process.argv array.
+ * @returns New array with global flags removed.
+ */
+export function stripGlobalFlags(argv: readonly string[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--llm" || arg === "--verbose") continue;
+    if (arg === "--format") {
+      i += 1; // skip the value too
+      continue;
+    }
+    result.push(arg as string);
+  }
+  return result;
+}

package/src/pipeline/runCli.orchestration.test.ts

@@ -32,6 +32,7 @@ vi.mock("./mapExitCode.js", () => ({
 
 vi.mock("./parseGlobalFlags.js", () => ({
   default: parseGlobalFlagsMock,
+  stripGlobalFlags: (argv: readonly string[]) => [...argv],
 }));
 
 vi.mock("./resolveCommandKind.js", () => ({

package/src/pipeline/runCli.ts

@@ -8,13 +8,14 @@ import { PragmaError } from "../error/index.js";
 import collectCommands from "./collectCommands.js";
 import createProgram from "./createProgram.js";
 import mapExitCode from "./mapExitCode.js";
-import parseGlobalFlags from "./parseGlobalFlags.js";
+import parseGlobalFlags, { stripGlobalFlags } from "./parseGlobalFlags.js";
 import {
   renderErrorJson,
   renderErrorLlm,
   renderErrorPlain,
 } from "./renderError.js";
 import resolveCommandKind from "./resolveCommandKind.js";
+import runInteractiveCommand from "./runInteractiveCommand.js";
 
 function hasCommandArg(argv: readonly string[]): boolean {
   const args = argv.slice(2);
@@ -78,6 +79,7 @@ async function handleRootHelp(globalFlags: GlobalFlags): Promise<void> {
     cwd: process.cwd(),
     dispose: () => {},
     globalFlags,
+    interactive: runInteractiveCommand,
   };
   const commands = collectCommands(stubCtx);
   const program = createProgram(commands, stubCtx);
@@ -111,10 +113,14 @@ async function bootAndRun(
   }
 
   try {
-    const ctx: PragmaContext = { ...runtime, globalFlags };
+    const ctx: PragmaContext = {
+      ...runtime,
+      globalFlags,
+      interactive: runInteractiveCommand,
+    };
     const commands = collectCommands(ctx);
     const program = createProgram(commands, ctx);
-    await program.parseAsync(argv);
+    await program.parseAsync(stripGlobalFlags(argv));
   } catch (err) {
     handleProgramError(err, globalFlags);
   } finally {
@@ -132,12 +138,13 @@ async function runStoreSkip(
     cwd: process.cwd(),
     dispose: () => {},
     globalFlags,
+    interactive: runInteractiveCommand,
   };
   const commands = [...setupCommands()];
   const program = createProgram(commands, stubCtx);
 
   try {
-    await program.parseAsync(argv);
+    await program.parseAsync(stripGlobalFlags(argv));
   } catch (err) {
     handleProgramError(err, globalFlags);
   }