@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/src/domains/modifier/orchestration/modifierEmptyError.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import modifierEmptyError from "./modifierEmptyError.js";
+
+describe("modifierEmptyError", () => {
+  it("recovers via a runnable install command (store-empty is its only scenario)", () => {
+    const err = modifierEmptyError();
+
+    // `modifier list` takes no filters, so an empty result is always
+    // store-empty: the recovery is the install, not a widen.
+    expect(err.recovery).toEqual({
+      message: "Install the design system packages that provide modifiers.",
+      cli: "bun add -D @canonical/design-system",
+    });
+  });
+
+  it("cites a real default package, not @canonical/ds-global", () => {
+    const err = modifierEmptyError();
+    expect(err.recovery?.cli).toContain("@canonical/design-system");
+    expect(err.recovery?.cli).not.toContain("ds-global");
+  });
+
+  it("has no mcp retry for store-empty (re-listing would return empty again)", () => {
+    const err = modifierEmptyError();
+    expect(err.recovery?.mcp).toBeUndefined();
+  });
+});

package/src/domains/modifier/orchestration/modifierEmptyError.ts

@@ -1,10 +1,15 @@
 import { PragmaError } from "#error";
 
 export default function modifierEmptyError(): PragmaError {
+  // `modifier list` takes no filters, so an empty result always means the
+  // design system packages that supply modifier triples are absent. The
+  // recovery is the runnable install command, not a (non-existent) widen.
   return PragmaError.emptyResults("modifier", {
     recovery: {
-      message:
-        "Ensure design system packages are installed: bun add -D @canonical/ds-global",
+      // The base error already states "No modifiers found"; the recovery adds
+      // only the cause + the runnable fix (the cli line is what renders on CLI).
+      message: "Install the design system packages that provide modifiers.",
+      cli: "bun add -D @canonical/design-system",
     },
   });
 }

package/src/domains/modifier/orchestration/resolveModifierLookup.ts

@@ -1,6 +1,7 @@
 import type { LookupContract, LookupResult } from "../../shared/contracts.js";
 import lookupMany from "../../shared/lookupMany.js";
 import type { PragmaRuntime } from "../../shared/runtime.js";
+import { expandLookupQueries } from "../../shared/suggestions/index.js";
 import type { ModifierFamily } from "../../shared/types/index.js";
 import { lookupModifier } from "../operations/index.js";
 
@@ -8,11 +9,23 @@ export default async function resolveModifierLookup(
   store: Pick<PragmaRuntime, "store">["store"],
   queries: readonly string[],
 ): Promise<LookupContract<ModifierFamily>> {
-  const result: LookupResult<ModifierFamily> = await lookupMany(
+  const { names, globErrors } = await expandLookupQueries(
     queries,
-    (query) => lookupModifier(store, query),
+    store,
+    "modifier",
   );
 
+  const lookupResult: LookupResult<ModifierFamily> =
+    names.length > 0
+      ? await lookupMany(names, (query) => lookupModifier(store, query))
+      : { results: [], errors: [], meta: { internalErrorCount: 0 } };
+
+  const result: LookupResult<ModifierFamily> = {
+    results: lookupResult.results,
+    errors: [...lookupResult.errors, ...globErrors],
+    meta: lookupResult.meta ?? { internalErrorCount: 0 },
+  };
+
   return {
     params: { names: queries },
     result,

package/src/domains/modifier/stories.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { modifierListStory, modifierLookupStory } from "./stories.js";
+
+describe("modifierListStory", () => {
+  it("renders the ink list view", () => {
+    const view = modifierListStory.renderInk?.([]);
+    expect(typeof view).toBe("string");
+    expect(view).toContain("Modifiers");
+  });
+});
+
+describe("modifierLookupStory", () => {
+  it("renders the ink lookup view", () => {
+    const view = modifierLookupStory.renderInk?.(
+      { results: [], errors: [] },
+      { surface: "cli", detailed: false, params: {} },
+    );
+    expect(typeof view).toBe("string");
+  });
+});

package/src/domains/modifier/stories.ts

@@ -0,0 +1,77 @@
+/**
+ * Modifier read stories — the single declaration of `modifier list` and
+ * `modifier lookup` for both surfaces.
+ *
+ * The story kernel compiles these into the CLI commands and MCP tools,
+ * so descriptions, parameters, resolution, and rendering live here once.
+ */
+
+import { createListView, createLookupView } from "#tui";
+import type { LookupStory, ReadStory } from "../shared/stories/index.js";
+import type { ModifierFamily } from "../shared/types/index.js";
+import {
+  createInkLookupOptions,
+  listFormatters,
+  lookupFormatters,
+} from "./formatters/index.js";
+import { modifierConfig } from "./modifierConfig.js";
+import {
+  resolveModifierList,
+  resolveModifierLookup,
+} from "./orchestration/index.js";
+import type { ModifierListResolution } from "./types.js";
+
+/** The `modifier list` / `modifier_list` read story. */
+export const modifierListStory: ReadStory<
+  ModifierListResolution,
+  ModifierFamily[]
+> = {
+  noun: "modifier",
+  verb: "list",
+  description: "List all modifier families",
+  toolDescription: "List all modifier families with their values.",
+  params: [],
+  examples: ["pragma modifier list", "pragma modifier list --llm"],
+  resolve: (rt) => resolveModifierList(rt),
+  toOutput: (resolution) => [...resolution.items],
+  formatters: listFormatters,
+  toEnvelope: (resolution) => ({
+    data: resolution.items,
+    meta: { count: resolution.items.length },
+  }),
+  renderInk: (items) =>
+    createListView({
+      heading: "Modifiers",
+      domain: "modifier",
+      items,
+      columns: modifierConfig.listColumns,
+    }),
+};
+
+/** The `modifier lookup` / `modifier_lookup` read story. */
+export const modifierLookupStory: LookupStory<ModifierFamily, ModifierFamily> =
+  {
+    noun: "modifier",
+    description: "Look up a modifier family and its values",
+    toolDescription: "Get one or more modifier families and their values.",
+    namesDescription: "Modifier family names or IRIs",
+    namesToolDescription: "Modifier family names or IRIs to look up",
+    examples: [
+      "pragma modifier lookup importance",
+      "pragma modifier lookup importance density",
+      "pragma modifier lookup importance --llm",
+    ],
+    resolve: async (rt, names) => {
+      const contract = await resolveModifierLookup(rt.store, names);
+      return contract.result;
+    },
+    toFmtInput: (family) => family,
+    formatters: lookupFormatters,
+    renderInk: (result) =>
+      createLookupView({
+        results: result.results,
+        errors: result.errors,
+        domain: "modifier",
+        options: createInkLookupOptions(),
+      }),
+  };

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

@@ -1,64 +1,11 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
-import { createListView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 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";
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { ontologyListStory } from "../stories.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.
- *
- * Lists all loaded ontology namespaces with class and property counts.
- *
- * @param ctx - Pragma runtime context providing the ke store and config.
- * @returns A command definition for `ontology list`.
- */
+/** Wire the `pragma ontology list` CLI command from the ontology list story. */
 export default function buildListCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["ontology", "list"],
-    description: "List loaded ontologies",
-    parameters: [],
-    meta: {
-      examples: ["pragma ontology list", "pragma ontology list --llm"],
-    },
-    execute: async (): Promise<CommandResult> => {
-      const ontologies = await listOntologies(ctx.store);
-
-      if (ontologies.length === 0) {
-        throw PragmaError.emptyResults("ontology", {
-          recovery: {
-            message: "Ensure design system packages are installed.",
-          },
-        });
-      }
-
-      return createOutputResult(ontologies, {
-        plain: selectFormatter(ctx, listFormatters),
-        ink: (data) =>
-          createListView({
-            heading: "Ontologies",
-            domain: "ontology",
-            items: data,
-            columns: ontologyListColumns,
-          }),
-      });
-    },
-  };
+  return compileReadCommand(ctx, ontologyListStory);
 }

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

@@ -1,66 +1,14 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import { selectFormatter } from "../../shared/formatters.js";
-import { showFormatters } from "../formatters/index.js";
-import { listOntologies, showOntology } from "../operations/index.js";
+import { compileReadCommand } from "../../shared/stories/index.js";
+import { ontologyShowStory } from "../stories.js";
 
 /**
- * Builds the `pragma ontology show` command definition.
- *
- * Displays detailed schema (classes and properties) for a given ontology
- * prefix. Provides tab-completion for the prefix parameter.
- *
- * @param ctx - Pragma runtime context providing the ke store and config.
- * @returns A command definition for `ontology show`.
+ * Wire the `pragma ontology show <prefix>` CLI command from the ontology
+ * show story.
  */
 export default function buildShowCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["ontology", "show"],
-    description: "Show ontology schema details",
-    parameters: [
-      {
-        name: "prefix",
-        description: "Ontology prefix (e.g. 'ds', 'cs')",
-        type: "string",
-        positional: true,
-        required: true,
-        complete: async (partial: string) => {
-          const all = await listOntologies(ctx.store);
-          return all
-            .map((o) => o.prefix)
-            .filter((p) => p.toLowerCase().startsWith(partial.toLowerCase()));
-        },
-      },
-    ],
-    meta: {
-      examples: ["pragma ontology show ds", "pragma ontology show cs --llm"],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-    ): Promise<CommandResult> => {
-      const prefix = params.prefix as string;
-      if (!prefix) {
-        throw PragmaError.invalidInput("prefix", "(empty)", {
-          recovery: {
-            message: "List loaded ontologies to find valid prefixes.",
-            cli: "pragma ontology list",
-            mcp: { tool: "ontology_list" },
-          },
-        });
-      }
-
-      const result = await showOntology(ctx.store, prefix);
-
-      return createOutputResult(result, {
-        plain: selectFormatter(ctx, showFormatters),
-      });
-    },
-  };
+  return compileReadCommand(ctx, ontologyShowStory);
 }

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

@@ -1,5 +1,11 @@
 import chalk from "chalk";
-import { formatHeading, formatSection } from "#pipeline";
+// Deep import, not #pipeline: the barrel re-exports collectCommands, which
+// imports every domain barrel — including this one — so #pipeline here forms
+// a module cycle that evaluates this domain's stories as undefined at load.
+import {
+  formatHeading,
+  formatSection,
+} from "../../../pipeline/formatTerminal.js";
 import compactUri from "../../shared/compactUri.js";
 import type { Formatters } from "../../shared/formatters.js";
 import { PREFIX_MAP } from "../../shared/prefixes.js";

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

@@ -1,93 +1,16 @@
 /**
- * MCP tool specs for the ontology domain.
+ * MCP tool specs for the ontology domain — ontology_list and
+ * ontology_show, compiled from the ontology read stories in
+ * `../stories.ts` so both surfaces share formatters and resolution.
  */
 
+import { compileReadTool } from "../../shared/stories/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { listOntologies, showOntology } from "../operations/index.js";
+import { ontologyListStory, ontologyShowStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
-  {
-    name: "ontology_list",
-    description:
-      "List all ontologies loaded in the knowledge graph with class and property counts.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const result = await listOntologies(rt.store);
-
-      if (condensed) {
-        const lines = ["## Ontologies", ""];
-        for (const o of result) {
-          lines.push(
-            `- **${o.prefix}:** (${o.namespace}) | classes: ${o.classCount} | properties: ${o.propertyCount}`,
-          );
-        }
-        const text = lines.join("\n");
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: result, meta: { count: result.length } };
-    },
-  },
-  {
-    name: "ontology_show",
-    description:
-      "Show detailed schema for an ontology including classes and properties.",
-    params: {
-      prefix: {
-        type: "string",
-        description: "Ontology prefix (e.g. 'ds', 'cs')",
-        optional: false,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { prefix, condensed }) {
-      const result = await showOntology(rt.store, prefix as string);
-
-      if (condensed) {
-        const lines = [`## ${result.prefix}: (${result.namespace})`, ""];
-        if (result.classes.length > 0) {
-          lines.push("### Classes");
-          for (const c of result.classes) {
-            const sup = c.superclass ? ` extends ${c.superclass}` : "";
-            lines.push(`- **${c.label}**${sup}`);
-          }
-          lines.push("");
-        }
-        if (result.properties.length > 0) {
-          lines.push("### Properties");
-          for (const p of result.properties) {
-            const domain = p.domain ? ` domain: ${p.domain}` : "";
-            const range = p.range ? ` range: ${p.range}` : "";
-            lines.push(`- **${p.label}** (${p.type})${domain}${range}`);
-          }
-        }
-        const text = lines.join("\n");
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: result };
-    },
-  },
+  compileReadTool(ontologyListStory),
+  compileReadTool(ontologyShowStory),
 ];
 
 export default specs;

package/src/domains/ontology/stories.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { ontologyListStory, ontologyShowStory } from "./stories.js";
+
+describe("ontologyListStory", () => {
+  it("renders the ink list view", () => {
+    const view = ontologyListStory.renderInk?.([]);
+    expect(typeof view).toBe("string");
+    expect(view).toContain("Ontologies");
+  });
+
+  it("rejects only empty results", () => {
+    expect(ontologyListStory.emptyError?.([], {})).toBeDefined();
+    expect(
+      ontologyListStory.emptyError?.(
+        [
+          {
+            prefix: "ds",
+            namespace: "https://ds.example/",
+            classCount: 1,
+            propertyCount: 1,
+            anatomyCount: 0,
+          },
+        ],
+        {},
+      ),
+    ).toBeUndefined();
+  });
+});
+
+describe("ontologyShowStory", () => {
+  it("guards against a missing prefix", () => {
+    expect(ontologyShowStory.guardParams?.({})).toBeDefined();
+    expect(ontologyShowStory.guardParams?.({ prefix: "" })).toBeDefined();
+    expect(ontologyShowStory.guardParams?.({ prefix: "ds" })).toBeUndefined();
+  });
+});

package/src/domains/ontology/stories.ts

@@ -0,0 +1,108 @@
+/**
+ * Ontology read stories — the single declaration of `ontology list` and
+ * `ontology show` for both surfaces.
+ *
+ * The story kernel compiles these into the CLI commands and MCP tools.
+ * Both surfaces now render through the same formatters, so MCP condensed
+ * output matches CLI `--llm` output by construction (previously the MCP
+ * specs re-implemented the Markdown inline and had drifted).
+ */
+
+import { PragmaError } from "#error";
+import { createListView } from "#tui";
+import type { ColumnDef } from "../shared/contracts.js";
+import {
+  type ReadStory,
+  requirePragmaContext,
+} from "../shared/stories/index.js";
+import type {
+  OntologyDetailed,
+  OntologySummary,
+} from "../shared/types/index.js";
+import { listFormatters, showFormatters } from "./formatters/index.js";
+import { listOntologies, showOntology } 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" },
+];
+
+/** The `ontology list` / `ontology_list` read story. */
+export const ontologyListStory: ReadStory<
+  OntologySummary[],
+  readonly OntologySummary[]
+> = {
+  noun: "ontology",
+  verb: "list",
+  description: "List loaded ontologies",
+  toolDescription:
+    "List all ontologies loaded in the knowledge graph with class and property counts.",
+  params: [],
+  examples: ["pragma ontology list", "pragma ontology list --llm"],
+  resolve: (rt) => listOntologies(rt.store),
+  toOutput: (ontologies) => ontologies,
+  formatters: listFormatters,
+  toEnvelope: (ontologies) => ({
+    data: ontologies,
+    meta: { count: ontologies.length },
+  }),
+  emptyError: (ontologies) =>
+    ontologies.length === 0
+      ? PragmaError.emptyResults("ontology", {
+          recovery: {
+            message: "Ensure design system packages are installed.",
+          },
+        })
+      : undefined,
+  renderInk: (ontologies) =>
+    createListView({
+      heading: "Ontologies",
+      domain: "ontology",
+      items: ontologies,
+      columns: ontologyListColumns,
+    }),
+};
+
+/** The `ontology show <prefix>` / `ontology_show` read story. */
+export const ontologyShowStory: ReadStory<OntologyDetailed, OntologyDetailed> =
+  {
+    noun: "ontology",
+    verb: "show",
+    description: "Show ontology schema details",
+    toolDescription:
+      "Show detailed schema for an ontology including classes and properties.",
+    params: [
+      {
+        name: "prefix",
+        type: "string",
+        description: "Ontology prefix (e.g. 'ds', 'cs')",
+        positional: true,
+        required: true,
+        complete: async (partial, cmdCtx) => {
+          const ctx = requirePragmaContext(cmdCtx);
+          const all = await listOntologies(ctx.store);
+          return all
+            .map((o) => o.prefix)
+            .filter((p) => p.toLowerCase().startsWith(partial.toLowerCase()));
+        },
+      },
+    ],
+    examples: ["pragma ontology show ds", "pragma ontology show cs --llm"],
+    resolve: (rt, params) => showOntology(rt.store, params.prefix as string),
+    toOutput: (ontology) => ontology,
+    formatters: showFormatters,
+    toEnvelope: (ontology) => ({ data: ontology }),
+    guardParams: (params) =>
+      typeof params.prefix === "string" && params.prefix.length > 0
+        ? undefined
+        : PragmaError.invalidInput("prefix", "(empty)", {
+            recovery: {
+              message: "List loaded ontologies to find valid prefixes.",
+              cli: "pragma ontology list",
+              mcp: { tool: "ontology_list" },
+            },
+          }),
+  };

package/src/domains/refs/operations/index.ts

@@ -3,7 +3,7 @@
 export { cloneRef, fetchRef, isSha, pruneCache } from "./gitOps.js";
 export type { PackageRef, RawPackageEntry } from "./parseRef.js";
 export { parsePackageEntry } from "./parseRef.js";
-export { cacheRoot, gitCacheDir, globalConfigDir } from "./paths.js";
+export { cacheRoot, dataRoot, gitCacheDir, globalConfigDir } from "./paths.js";
 export { default as readGlobalRefs } from "./readGlobalRefs.js";
 
 export type { UpdateRefsOptions, UpdateResult } from "./updateRefs.js";

package/src/domains/refs/operations/paths.ts

@@ -1,9 +1,10 @@
 /**
- * Cross-platform path resolution for pragma cache and global config.
+ * Cross-platform path resolution for pragma cache, config, and data.
  *
  * Respects XDG Base Directory Specification:
  * - XDG_CACHE_HOME for cache (default: ~/.cache)
  * - XDG_CONFIG_HOME for global config (default: ~/.config)
+ * - XDG_DATA_HOME for persistent data (default: ~/.local/share)
  *
  * Override via PRAGMA_CACHE_DIR for CI and testing.
  * Uses os.homedir() for macOS/WSL/Linux portability.
@@ -42,6 +43,19 @@ export function globalConfigDir(): string {
   return join(base, "pragma");
 }
 
+/**
+ * Root directory for pragma persistent data (extracted skills, etc.).
+ *
+ * Resolution order:
+ * 1. XDG_DATA_HOME/pragma (XDG spec)
+ * 2. ~/.local/share/pragma (default)
+ */
+export function dataRoot(): string {
+  const xdg = process.env.XDG_DATA_HOME;
+  const base = xdg ?? join(homedir(), ".local", "share");
+  return join(base, "pragma");
+}
+
 /**
  * Cache directory for a specific git-ref-resolved package.
  *
@@ -54,6 +68,20 @@ export function gitCacheDir(pkg: string, ref: string): string {
   return join(cacheRoot(), "refs", pkg, sanitizedRef);
 }
 
+/**
+ * Root directory for query trace logs.
+ *
+ * Resolution order:
+ * 1. PRAGMA_TRACE_DIR environment variable (CI/testing override)
+ * 2. XDG_DATA_HOME/pragma/traces (default)
+ */
+export function traceDir(): string {
+  if (process.env.PRAGMA_TRACE_DIR) {
+    return process.env.PRAGMA_TRACE_DIR;
+  }
+  return join(dataRoot(), "traces");
+}
+
 /**
  * Sanitize a git ref for use as a directory name.
  * Replaces characters that are invalid or confusing in path segments.

package/src/domains/refs/operations/updateRefs.test.ts

@@ -157,8 +157,11 @@ describe("updateRefs", () => {
 
   it("uses defaults when no config exists", async () => {
     const results = await updateRefs({ cwd: projectDir });
-    // All 4 defaults are npm, so all skipped
-    expect(results.every((r) => r.kind === "skipped")).toBe(true);
-    expect(results).toHaveLength(4);
+    // All 3 defaults are git refs
+    expect(results).toHaveLength(3);
+    for (const r of results) {
+      // Each result is either cloned, up-to-date, or error (network)
+      expect(["cloned", "updated", "up-to-date", "error"]).toContain(r.kind);
+    }
   });
 });