@canonical/pragma-cli 0.29.0 → 0.30.0

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

@@ -1,85 +1,14 @@
-/**
- * Wires the `pragma modifier lookup <name...>` CLI command.
- *
- * Retrieves a single modifier family by name and renders its values.
- */
-
-import {
-  type CommandDefinition,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { createLookupView } from "#tui";
+import type { CommandDefinition } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
-import type { LookupResult } from "../../shared/contracts.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";
-
-interface ModifierLookupOutput {
-  readonly result: LookupResult<Awaited<ReturnType<typeof lookupModifier>>>;
-}
+import { compileLookupCommand } from "../../shared/stories/index.js";
+import { modifierLookupStory } from "../stories.js";
 
+/**
+ * Wire the `pragma modifier lookup <name...>` CLI command from the
+ * modifier lookup story.
+ */
 export default function buildLookupCommand(
   ctx: PragmaContext,
 ): CommandDefinition {
-  return {
-    path: ["modifier", "lookup"],
-    description: "Look up a modifier family and its values",
-    parameters: [
-      {
-        name: "names",
-        description: "Modifier family names or IRIs",
-        type: "multiselect",
-        positional: true,
-        required: true,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma modifier lookup importance",
-        "pragma modifier lookup importance density",
-        "pragma modifier lookup importance --llm",
-      ],
-    },
-    async execute(params: Record<string, unknown>) {
-      const names = normalizeNames(params.names, params.name);
-      const contract = await resolveModifierLookup(ctx.store, names);
-
-      return createOutputResult<ModifierLookupOutput>(
-        { result: contract.result },
-        {
-          plain: ({ result }) =>
-            renderLookupResults({
-              ctx,
-              result,
-              formatters: lookupFormatters,
-              mapResult: (family) => family,
-            }),
-          ink: ({ result }) =>
-            createLookupView({
-              results: result.results,
-              errors: result.errors,
-              domain: "modifier",
-              options: createInkLookupOptions(),
-            }),
-        },
-      );
-    },
-  };
-}
-
-function normalizeNames(names: unknown, legacyName?: unknown): string[] {
-  if (Array.isArray(names)) {
-    return names.filter(
-      (name): name is string => typeof name === "string" && name.length > 0,
-    );
-  }
-  if (typeof legacyName === "string" && legacyName.length > 0) {
-    return [legacyName];
-  }
-  return [];
+  return compileLookupCommand(ctx, modifierLookupStory);
 }

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

@@ -1,99 +1,25 @@
 /**
- * MCP tool specs for the modifier domain.
+ * MCP tool specs for the modifier domain — modifier_list, modifier_lookup,
+ * modifier_sample.
  *
- * Declarative definitions — no MCP imports. The adapter layer
- * converts these into registered MCP tools via `registerFromSpec()`.
+ * The list and lookup tools are compiled from the modifier read stories in
+ * `../stories.ts`; only the sample tool is spec'd by hand. The adapter
+ * layer converts these into registered MCP tools via `registerFromSpec()`.
  */
 
-import type { ToolSpec } from "../../shared/ToolSpec.js";
 import {
-  listFormatters as modifierListFmt,
-  lookupFormatters as modifierLookupFmt,
-  sampleFormatters as modifierSampleFmt,
-} from "../formatters/index.js";
+  compileLookupTool,
+  compileReadTool,
+  condense,
+} from "../../shared/stories/index.js";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { sampleFormatters as modifierSampleFmt } from "../formatters/index.js";
 import { sampleModifiers } from "../operations/index.js";
-import {
-  resolveModifierList,
-  resolveModifierLookup,
-} from "../orchestration/index.js";
+import { modifierListStory, modifierLookupStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
-  {
-    name: "modifier_list",
-    description: "List all modifier families with their values.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const resolution = await resolveModifierList(rt);
-
-      if (condensed) {
-        const text = modifierListFmt.llm([...resolution.items]);
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return {
-        data: resolution.items,
-        meta: { count: resolution.items.length },
-      };
-    },
-  },
-
-  {
-    name: "modifier_lookup",
-    description: "Get one or more modifier families and their values.",
-    params: {
-      names: {
-        type: "string[]",
-        description: "Modifier family names or IRIs to look up",
-        optional: false,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { names, condensed }) {
-      const contract = await resolveModifierLookup(rt.store, names as string[]);
-      const result = contract.result;
-
-      if (condensed) {
-        const textParts = result.results.map((family) =>
-          modifierLookupFmt.llm(family),
-        );
-
-        if (result.errors.length > 0) {
-          textParts.push(
-            [
-              "### Errors",
-              ...result.errors.map(
-                (error) => `- ${error.query}: ${error.message}`,
-              ),
-            ].join("\n"),
-          );
-        }
-
-        return {
-          condensed: true,
-          text: textParts.join("\n\n"),
-          tokens: `~${Math.ceil(textParts.join("\n\n").length / 4)}`,
-        };
-      }
-
-      return { data: result, meta: { count: result.results.length } };
-    },
-  },
+  compileReadTool(modifierListStory),
+  compileLookupTool(modifierLookupStory),
   {
     name: "modifier_sample",
     description:
@@ -121,12 +47,7 @@ const specs: readonly ToolSpec[] = [
       ];
 
       if (condensed) {
-        const text = modifierSampleFmt.llm({ ...result, nextSteps });
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
+        return condense(modifierSampleFmt.llm({ ...result, nextSteps }));
       }
 
       return {

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

@@ -18,11 +18,12 @@ export default async function resolveModifierLookup(
   const lookupResult: LookupResult<ModifierFamily> =
     names.length > 0
       ? await lookupMany(names, (query) => lookupModifier(store, query))
-      : { results: [], errors: [] };
+      : { results: [], errors: [], meta: { internalErrorCount: 0 } };
 
   const result: LookupResult<ModifierFamily> = {
     results: lookupResult.results,
     errors: [...lookupResult.errors, ...globErrors],
+    meta: lookupResult.meta ?? { internalErrorCount: 0 },
   };
 
   return {

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();
+  });
+});