@canonical/pragma-cli 0.20.0 → 0.21.0

package/src/domains/info/mcp/specs.ts

@@ -0,0 +1,65 @@
+/**
+ * MCP tool spec for the info domain.
+ *
+ * Uses shared operations (collectStoreSummary, resolveTierChain) instead of
+ * inlining data assembly. Skips the npm registry check to avoid network
+ * latency in MCP tool calls — sets `updateSkipped: true`.
+ */
+
+import { VERSION } from "#constants";
+import { detectInstallSource } from "#package-manager";
+import { CHANNEL_RELEASES } from "../../shared/filters/buildChannelFilter.js";
+import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { renderInfoLlm } from "../formatters/index.js";
+import { collectStoreSummary } from "../operations/index.js";
+import type { InfoData } from "../types.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "info",
+    description: "Show pragma version, configuration, and store summary.",
+    params: {
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, params) {
+      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,
+      };
+
+      if (params.condensed) {
+        const text = renderInfoLlm(data);
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data };
+    },
+  },
+];
+
+export default specs;

package/src/domains/llm/data/commandReference.ts

@@ -7,14 +7,14 @@ import type { CommandRefEntry } from "../types.js";
  */
 export const COMMAND_REFERENCE: readonly CommandRefEntry[] = [
   { command: "block list", tokens: "~200" },
-  { command: "block lookup <name> --detailed", tokens: "~500" },
+  { command: "block lookup <name-or-iri...> --detailed", tokens: "~500" },
   { command: "standard list --category <cat>", tokens: "~100" },
-  { command: "standard lookup <name> --detailed", tokens: "~400" },
+  { command: "standard lookup <name-or-iri...> --detailed", tokens: "~400" },
   { command: "standard categories", tokens: "~50" },
   { command: "modifier list", tokens: "~100" },
-  { command: "modifier lookup <name>", tokens: "~80" },
+  { command: "modifier lookup <name-or-iri...>", tokens: "~80" },
   { command: "token list", tokens: "~400" },
-  { command: "token lookup <name> --detailed", tokens: "~150" },
+  { command: "token lookup <name-or-iri...> --detailed", tokens: "~150" },
   { command: "tier list", tokens: "~50" },
   { command: "ontology list", tokens: "~80" },
   { command: "ontology show <prefix>", tokens: "~300" },

package/src/domains/llm/data/decisionTrees.ts

@@ -9,31 +9,33 @@ import type { DecisionTree } from "../types.js";
 export const DECISION_TREES: readonly DecisionTree[] = [
   {
     intent: "Build a block",
-    tree: `? Know name?
-  yes → block lookup <name> --detailed  [~500]
-  no  → block list [~200] → pick → lookup`,
+    tree: `? Know IRI or name?
+  yes → block lookup <name-or-iri...> --detailed  [~500]
+        e.g. block lookup ds:global.component.button
+  no  → block list [~200] → pick compact IRI → lookup`,
   },
   {
     intent: "Audit standards",
-    tree: `? Know standard?
-  yes → standard lookup <name> --detailed [~400]
-  no  → ? Know block?
-      yes → block lookup <name> --detailed [~500]
+    tree: `? Know standard IRI or name?
+  yes → standard lookup <name-or-iri...> --detailed [~400]
+        e.g. standard lookup react/component/props
+  no  → ? Know block IRI or name?
+      yes → block lookup <name-or-iri...> --detailed [~500]
         → inspect related guidance manually Σ500
         no  → standard list --category <cat> [~100]
-              → standard lookup <std> --detailed [~400] Σ500`,
+              → standard lookup <std-iri...> --detailed [~400] Σ500`,
   },
   {
     intent: "Find a token",
-    tree: `? Know name?
-  yes → token lookup <name> --detailed [~150]
+    tree: `? Know token IRI or name?
+  yes → token lookup <name-or-iri...> --detailed [~150]
   no  → token list --category <cat> [~100]
-        → token lookup <name> --detailed [~150] Σ250`,
+        → token lookup <name-or-iri...> --detailed [~150] Σ250`,
   },
   {
     intent: "Explore the design system",
     tree: `high-level → ontology list [~80] → ontology show <ns> [~300]
-modifiers  → modifier list [~100] → modifier lookup <name> [~80]
+modifiers  → modifier list [~100] → modifier lookup <name-or-iri...> [~80]
 tiers      → tier list [~50]
 raw        → graph query "SELECT ..." → graph inspect <uri> [~200]`,
   },

package/src/domains/llm/operations/collectContext.ts

@@ -3,7 +3,7 @@ import { listBlocks } from "../../block/operations/index.js";
 import { listModifiers } from "../../modifier/operations/index.js";
 import { listOntologies } from "../../ontology/operations/index.js";
 import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
-import type { FilterConfig } from "../../shared/types.js";
+import type { FilterConfig } from "../../shared/types/index.js";
 import { listStandards } from "../../standard/operations/index.js";
 import { listTokens } from "../../token/operations/index.js";
 import type { LlmContext } from "../types.js";

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

@@ -9,9 +9,11 @@ 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 { modifierConfig } from "../modifierConfig.js";
 import { resolveModifierList } from "../orchestration/index.js";
 
 export default function listCommand(ctx: PragmaContext): CommandDefinition {
@@ -27,6 +29,13 @@ export default function listCommand(ctx: PragmaContext): CommandDefinition {
 
       return createOutputResult([...resolution.items], {
         plain: selectFormatter(ctx, listFormatters),
+        ink: (data) =>
+          createListView({
+            heading: "Modifiers",
+            domain: "modifier",
+            items: data,
+            columns: modifierConfig.listColumns,
+          }),
       });
     },
   };

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

@@ -8,9 +8,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 { lookupFormatters } from "../formatters/index.js";
+import { renderLookupResults } from "../../shared/formatters.js";
+import {
+  createInkLookupOptions,
+  lookupFormatters,
+} from "../formatters/index.js";
 import type { lookupModifier } from "../operations/index.js";
 import { resolveModifierLookup } from "../orchestration/index.js";
 
@@ -46,7 +51,22 @@ export default function buildLookupCommand(
 
       return createOutputResult<ModifierLookupOutput>(
         { result: contract.result },
-        { plain: renderModifierLookupOutput(ctx) },
+        {
+          plain: ({ result }) =>
+            renderLookupResults({
+              ctx,
+              result,
+              formatters: lookupFormatters,
+              mapResult: (family) => family,
+            }),
+          ink: ({ result }) =>
+            createLookupView({
+              results: result.results,
+              errors: result.errors,
+              domain: "modifier",
+              options: createInkLookupOptions(),
+            }),
+        },
       );
     },
   };
@@ -63,43 +83,3 @@ function normalizeNames(names: unknown, legacyName?: unknown): string[] {
   }
   return [];
 }
-
-function renderModifierLookupOutput(
-  ctx: PragmaContext,
-): (data: ModifierLookupOutput) => string {
-  return ({ result }) => {
-    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(only)
-          : JSON.stringify({ results: [], errors: result.errors }, null, 2);
-      }
-
-      return JSON.stringify(
-        { results: result.results, errors: result.errors },
-        null,
-        2,
-      );
-    }
-
-    const parts = result.results.map((family) => formatOne(family));
-    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/modifier/formatters/index.ts

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

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

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

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

@@ -1,33 +1,20 @@
-/**
- * Three-mode formatter for `pragma modifier list` output.
- *
- * - **plain** — one line per family showing name and comma-separated values.
- * - **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 { ModifierFamily } from "../../shared/types.js";
+import { renderListLlm } from "../../shared/renderers.js";
+import type { ModifierFamily } from "../../shared/types/index.js";
+import { modifierConfig } from "../modifierConfig.js";
 
+/** Three-mode formatter for `pragma modifier list` output. */
 const formatters: Formatters<ModifierFamily[]> = {
-  plain: (families) => {
-    const lines: string[] = [];
-    for (const f of families) {
-      lines.push(`${f.name}: ${f.values.join(", ")}`);
-    }
-    return lines.join("\n");
-  },
+  plain: (families) =>
+    families
+      .map((family) => `${family.name}: ${family.values.join(", ")}`)
+      .join("\n"),
 
-  llm: (families) => {
-    const lines: string[] = [];
-    lines.push("## Modifier Families");
-    lines.push("");
-    for (const f of families) {
-      lines.push(`- **${f.name}**: ${f.values.join(", ")}`);
-    }
-    return lines.join("\n");
-  },
+  llm: (families) =>
+    renderListLlm(families, {
+      heading: "Modifier Families",
+      columns: modifierConfig.listColumns,
+    }),
 
   json: (families) => JSON.stringify(families, null, 2),
 };

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

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

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

@@ -1,38 +1,50 @@
-/**
- * Three-mode formatter for `pragma modifier lookup` output.
- *
- * - **plain** — terminal text showing the family name and its values.
- * - **llm** — condensed Markdown consumed by LLM agents and reused
- *   by the MCP adapter when `condensed: true`.
- * - **json** — structured JSON for programmatic consumption.
- */
-
+import type { RenderLookupOptions } from "../../shared/contracts.js";
 import type { Formatters } from "../../shared/formatters.js";
-import type { ModifierFamily } from "../../shared/types.js";
+import { renderLookupLlm, renderLookupPlain } from "../../shared/renderers.js";
+import type {
+  ModifierDetailed,
+  ModifierFamily,
+} from "../../shared/types/index.js";
+import { modifierConfig } from "../modifierConfig.js";
 
+/** Three-mode formatter for `pragma modifier lookup` output. */
 const formatters: Formatters<ModifierFamily> = {
-  plain: (family) => {
-    const lines: string[] = [];
-    lines.push(family.name);
-    lines.push("");
-    lines.push("Values:");
-    for (const v of family.values) {
-      lines.push(`  ${v}`);
-    }
-    return lines.join("\n");
-  },
+  plain: (family) =>
+    renderLookupPlain(family, {
+      title: (entry) => entry.name,
+      fields: [{ label: "IRI", value: (entry) => entry.uri }],
+      sections: modifierConfig.lookupSections,
+      sectionOverrides: {
+        values: {
+          plain: (entry) =>
+            entry.values.length > 0
+              ? entry.values.map((value) => `  ${value}`).join("\n")
+              : null,
+        },
+      },
+    }),
 
-  llm: (family) => {
-    const lines: string[] = [];
-    lines.push(`## ${family.name}`);
-    lines.push("");
-    for (const v of family.values) {
-      lines.push(`- ${v}`);
-    }
-    return lines.join("\n");
-  },
+  llm: (family) =>
+    renderLookupLlm(family, {
+      title: (entry) => entry.name,
+      fields: [{ label: "IRI", value: (entry) => entry.uri }],
+      sections: modifierConfig.lookupSections,
+    }),
 
   json: (family) => JSON.stringify(family, null, 2),
 };
 
 export default formatters;
+
+/**
+ * Build lookup rendering options for the Ink TUI view.
+ *
+ * @returns Options compatible with the LookupView component.
+ */
+export function createInkLookupOptions(): RenderLookupOptions<ModifierDetailed> {
+  return {
+    title: (entry) => entry.name,
+    fields: [{ label: "IRI", value: (entry) => entry.uri }],
+    sections: modifierConfig.lookupSections,
+  };
+}

package/src/domains/modifier/index.ts

@@ -14,6 +14,7 @@ export function commands(ctx: PragmaContext): CommandDefinition[] {
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";
+export { modifierConfig } from "./modifierConfig.js";
 export { listModifiers, lookupModifier } from "./operations/index.js";
 export {
   modifierEmptyError,

package/src/domains/modifier/modifierConfig.ts

@@ -0,0 +1,36 @@
+import type { EntityDisplayConfig } from "../shared/contracts.js";
+import { P } from "../shared/prefixes.js";
+import type {
+  FilterConfig,
+  ModifierDetailed,
+  ModifierDigest,
+  ModifierSummary,
+} from "../shared/types/index.js";
+
+/** Display-contract configuration for modifier-family entities. */
+export const modifierConfig: EntityDisplayConfig<
+  ModifierSummary,
+  ModifierDigest,
+  ModifierDetailed
+> = {
+  domain: "modifier",
+  entityName: "modifier",
+  rdfTypes: [`${P.ds}ModifierFamily`],
+  listColumns: [
+    { key: "uri", label: "IRI" },
+    { key: "name", label: "Name" },
+    { key: "values", label: "Values", showWhenEmpty: false },
+  ],
+  digestColumns: [],
+  lookupSections: [{ key: "values", heading: "Values", kind: "list" }],
+  emptyRecovery: (_filters: FilterConfig) => ({
+    message: "List available modifier families.",
+    cli: "pragma modifier list",
+    mcp: { tool: "modifier_list" },
+  }),
+  notFoundRecovery: (_query: string) => ({
+    message: "List available modifier families.",
+    cli: "pragma modifier list",
+    mcp: { tool: "modifier_list" },
+  }),
+};

package/src/domains/modifier/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 { ModifierFamily } from "../../shared/types.js";
+import type { ModifierFamily } from "../../shared/types/index.js";
 
 export default async function listModifiers(
   store: Store,

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

@@ -13,20 +13,21 @@ import { escapeSparqlValue } from "@canonical/ke";
 import { PragmaError } from "#error";
 import { buildQuery } from "../../shared/buildQuery.js";
 import { P } from "../../shared/prefixes.js";
-import type { ModifierFamily } from "../../shared/types.js";
+import type { ModifierFamily } from "../../shared/types/index.js";
 
 export default async function lookupModifier(
   store: Store,
   name: string,
 ): Promise<ModifierFamily> {
-  const escaped = escapeSparqlValue(name);
+  const escaped = escapeSparqlValue(name.toLowerCase());
 
   const result = await store.query(
     buildQuery(`
       SELECT ?family (GROUP_CONCAT(DISTINCT ?valueName; separator="|") AS ?values)
       WHERE {
         ?family a ${P.ds}ModifierFamily ;
-                ${P.ds}name ${escaped} .
+                ${P.ds}name ?familyName .
+        FILTER(LCASE(STR(?familyName)) = ${escaped})
         OPTIONAL {
           ?mod a ${P.ds}Modifier ;
                ${P.ds}modifierFamily ?family ;

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

package/src/domains/modifier/types.ts

@@ -1,4 +1,4 @@
-import type { ModifierFamily } from "../shared/types.js";
+import type { ModifierFamily } from "../shared/types/index.js";
 
 export interface ModifierListResolution {
   readonly items: readonly ModifierFamily[];

package/src/domains/ontology/commands/list.test.ts

@@ -3,7 +3,7 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import createTestRuntime from "../../../testing/helpers/createTestRuntime.js";
 import type { PragmaContext } from "../../shared/context.js";
 import type { PragmaRuntime } from "../../shared/runtime.js";
-import type { OntologySummary } from "../../shared/types.js";
+import type { OntologySummary } from "../../shared/types/index.js";
 import buildListCommand from "./list.js";
 
 let runtime: PragmaRuntime;

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

@@ -4,11 +4,22 @@ 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 { OntologySummary } from "../../shared/types/ontology.js";
 import { listFormatters } from "../formatters/index.js";
 import { listOntologies } from "../operations/index.js";
 
+const ontologyListColumns: readonly ColumnDef<OntologySummary>[] = [
+  { key: "prefix", label: "Prefix" },
+  { key: "namespace", label: "Namespace" },
+  { key: "classCount", label: "Classes" },
+  { key: "propertyCount", label: "Properties" },
+  { key: "anatomyCount", label: "Anatomies" },
+];
+
 /**
  * Builds the `pragma ontology list` command definition.
  *
@@ -40,6 +51,13 @@ export default function buildListCommand(
 
       return createOutputResult(ontologies, {
         plain: selectFormatter(ctx, listFormatters),
+        ink: (data) =>
+          createListView({
+            heading: "Ontologies",
+            domain: "ontology",
+            items: data,
+            columns: ontologyListColumns,
+          }),
       });
     },
   };

package/src/domains/ontology/commands/show.test.ts

@@ -3,7 +3,7 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import createTestRuntime from "../../../testing/helpers/createTestRuntime.js";
 import type { PragmaContext } from "../../shared/context.js";
 import type { PragmaRuntime } from "../../shared/runtime.js";
-import type { OntologyDetailed } from "../../shared/types.js";
+import type { OntologyDetailed } from "../../shared/types/index.js";
 import buildShowCommand from "./show.js";
 
 let runtime: PragmaRuntime;

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

@@ -1,6 +1,8 @@
 import chalk from "chalk";
+import compactUri from "../../shared/compactUri.js";
 import type { Formatters } from "../../shared/formatters.js";
-import type { OntologySummary } from "../../shared/types.js";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+import type { OntologySummary } from "../../shared/types/index.js";
 
 /**
  * Formatters for `pragma ontology list` output.
@@ -14,7 +16,7 @@ const formatters: Formatters<readonly OntologySummary[]> = {
     return ontologies
       .map(
         (o) =>
-          `${chalk.bold(o.prefix)} ${chalk.dim(`(${o.namespace})`)} classes: ${o.classCount} properties: ${o.propertyCount} anatomy: ${o.anatomyCount}`,
+          `${chalk.bold(`${o.prefix}:`)} ${compactUri(o.namespace, PREFIX_MAP)} classes: ${o.classCount} properties: ${o.propertyCount} anatomy: ${o.anatomyCount}`,
       )
       .join("\n");
   },
@@ -23,7 +25,7 @@ const formatters: Formatters<readonly OntologySummary[]> = {
     const lines = ["## Ontologies", ""];
     for (const o of ontologies) {
       lines.push(
-        `- **${o.prefix}:** (${o.namespace}) | classes: ${o.classCount} | properties: ${o.propertyCount} | anatomy: ${o.anatomyCount}`,
+        `- **${o.prefix}:** \`${compactUri(o.namespace, PREFIX_MAP)}\` | classes: ${o.classCount} | properties: ${o.propertyCount} | anatomy: ${o.anatomyCount}`,
       );
     }
     return lines.join("\n");