@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/modifier/stories.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { PragmaError } from "../../error/index.js";
+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,
+    emptyNamesError: () =>
+      PragmaError.invalidInput("names", "(empty)", {
+        recovery: {
+          message: "List available modifier families.",
+          cli: "pragma modifier list",
+          mcp: { tool: "modifier_list" },
+        },
+      }),
+    renderInk: (result) =>
+      createLookupView({
+        results: result.results,
+        errors: result.errors,
+        domain: "modifier",
+        options: createInkLookupOptions(),
+      }),
+  };

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

@@ -52,8 +52,10 @@ describe("ontology list command", () => {
     const { text } = await executeOutput(cmd, {}, ctx);
 
     expect(text).toContain("ds");
-    expect(text).toContain("classes:");
-    expect(text).toContain("anatomy:");
+    expect(text).toContain("classes");
+    expect(text).toContain("relations");
+    expect(text).toContain("attributes");
+    expect(text).toContain("Next: pragma ontology show <prefix>");
   });
 
   it("renders llm output", async () => {
@@ -65,7 +67,7 @@ describe("ontology list command", () => {
 
     expect(text).toContain("## Ontologies");
     expect(text).toContain("**ds:**");
-    expect(text).toContain("anatomy:");
+    expect(text).toContain("relations");
   });
 
   it("renders json output", async () => {

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.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/index.js";
+import type { OntologyShowInput } from "../formatters/index.js";
 import buildShowCommand from "./show.js";
 
 let runtime: PragmaRuntime;
@@ -41,10 +41,69 @@ describe("ontology show command", () => {
     const cmd = buildShowCommand(ctx);
     const { value } = await executeOutput(cmd, { prefix: "ds" }, ctx);
 
-    const result = value as OntologyDetailed;
-    expect(result.prefix).toBe("ds");
-    expect(result.classes.length).toBeGreaterThan(0);
-    expect(result.properties.length).toBeGreaterThan(0);
+    const { ontology } = value as OntologyShowInput;
+    expect(ontology.prefix).toBe("ds");
+    expect(ontology.classes.length).toBeGreaterThan(0);
+    const propertyCount =
+      ontology.classes.reduce((n, c) => n + c.properties.length, 0) +
+      ontology.unattached.length;
+    expect(propertyCount).toBeGreaterThan(0);
+  });
+
+  it("deep-dives into a class via the class param", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+    const { value, text } = await executeOutput(
+      cmd,
+      { prefix: "ds", class: "Component" },
+      ctx,
+    );
+
+    const { ontology } = value as OntologyShowInput;
+    expect(ontology.focus?.iri).toBe("ds:Component");
+    expect(text).toContain("Component");
+    expect(text).toContain("extends:");
+    // Follow-up querying: the deep dive hands over runnable SPARQL.
+    expect(text).toContain(
+      "SELECT ?instance WHERE { ?instance a ds:Component }",
+    );
+  });
+
+  it("hides attributes by default and shows them with --properties", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+
+    const bare = await executeOutput(cmd, { prefix: "ds" }, ctx);
+    // Attributes render as `label: range` — absent by default.
+    expect(bare.text).not.toContain(": xsd:");
+    // hasModifierFamily is an object property (relation) — always shown.
+    expect(bare.text).toContain("hasModifierFamily");
+
+    const withProps = await executeOutput(
+      cmd,
+      { prefix: "ds", properties: true },
+      ctx,
+    );
+    expect(withProps.text).toContain(": xsd:");
+  });
+
+  it("expands IRIs with --full-uris", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const cmd = buildShowCommand(ctx);
+    const { value, text } = await executeOutput(
+      cmd,
+      { prefix: "ds", fullUris: true },
+      ctx,
+    );
+
+    const { ontology } = value as OntologyShowInput;
+    const component = ontology.classes.find((c) => c.label === "Component");
+    expect(component?.iri).toBe("https://ds.canonical.com/Component");
+    expect(text).toContain("https://ds.canonical.com/Component");
+    // The seeded footer query must stay valid SPARQL: full URIs need <...>.
+    expect(text).toMatch(/\?s a <https:\/\/ds\.canonical\.com\//);
   });
 
   it("completes ontology prefixes", async () => {
@@ -57,13 +116,30 @@ describe("ontology show command", () => {
     expect(matches).toContain("ds");
   });
 
+  it("completes class names for --class", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+    const classParam = cmd.parameters.find((p) => p.name === "class");
+    const complete = classParam?.complete;
+
+    expect(complete).toBeTypeOf("function");
+    const matches = await complete?.("comp", ctx);
+    expect(matches).toContain("Component");
+    // Case-insensitive prefix match, sorted, no non-matches.
+    expect(matches?.every((m) => m.toLowerCase().startsWith("comp"))).toBe(
+      true,
+    );
+  });
+
   it("renders plain output", async () => {
     const ctx = makeCtx();
     const cmd = buildShowCommand(ctx);
     const { text } = await executeOutput(cmd, { prefix: "ds" }, ctx);
 
-    expect(text).toContain("Classes");
-    expect(text).toContain("Properties");
+    expect(text).toContain("Ontology ds:");
+    expect(text).toContain("classes");
+    // Hierarchy: children render beneath their parent with tree branches.
+    expect(text).toContain("└─");
   });
 
   it("renders llm output", async () => {
@@ -73,7 +149,7 @@ describe("ontology show command", () => {
     const cmd = buildShowCommand(ctx);
     const { text } = await executeOutput(cmd, { prefix: "ds" }, ctx);
 
-    expect(text).toContain("## ds:");
+    expect(text).toContain("## Ontology ds:");
     expect(text).toContain("### Classes");
   });
 
@@ -84,7 +160,7 @@ describe("ontology show command", () => {
     const cmd = buildShowCommand(ctx);
     const { text } = await executeOutput(cmd, { prefix: "ds" }, ctx);
 
-    const parsed = JSON.parse(text) as OntologyDetailed;
+    const parsed = JSON.parse(text) as { prefix: string };
     expect(parsed.prefix).toBe("ds");
   });
 

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/index.ts

@@ -1,4 +1,5 @@
 /** @module Barrel for ontology formatters. */
 
 export { default as listFormatters } from "./list.js";
+export type { OntologyShowInput } from "./show.js";
 export { default as showFormatters } from "./show.js";

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

@@ -1,33 +1,39 @@
 import chalk from "chalk";
-import compactUri from "../../shared/compactUri.js";
 import type { Formatters } from "../../shared/formatters.js";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
 import type { OntologySummary } from "../../shared/types/index.js";
 
 /**
  * Formatters for `pragma ontology list` output.
  *
- * - **plain**: one line per ontology with chalk-styled prefix, namespace, and counts.
- * - **llm**: condensed Markdown bullet list under an `## Ontologies` heading.
- * - **json**: serialized ontology summary array as indented JSON.
+ * One line per namespace mirroring the `ontology show` summary line —
+ * name, metadata, and split counts — plus a next-command footer, so the
+ * list is the entry point of the same drill-down path
+ * (`list → show <prefix> → show <prefix> --class <Class>`).
+ *
+ * - **plain**: chalk-styled lines with counts and a dimmed footer.
+ * - **llm**: the same content as condensed Markdown bullets.
+ * - **json**: the {@link OntologySummary} array itself.
  */
 const formatters: Formatters<readonly OntologySummary[]> = {
   plain(ontologies) {
-    return ontologies
-      .map(
-        (o) =>
-          `${chalk.bold(`${o.prefix}:`)} ${compactUri(o.namespace, PREFIX_MAP)} classes: ${o.classCount} properties: ${o.propertyCount} anatomy: ${o.anatomyCount}`,
-      )
-      .join("\n");
+    const lines = ontologies.map(
+      (o) =>
+        `${chalk.bold(prefixLabel(o))} ${o.namespace} ${chalk.dim(`— ${summaryLine(o)}`)}`,
+    );
+    lines.push("");
+    lines.push(chalk.dim("Next: pragma ontology show <prefix>"));
+    return lines.join("\n");
   },
 
   llm(ontologies) {
     const lines = ["## Ontologies", ""];
     for (const o of ontologies) {
       lines.push(
-        `- **${o.prefix}:** \`${compactUri(o.namespace, PREFIX_MAP)}\` | classes: ${o.classCount} | properties: ${o.propertyCount} | anatomy: ${o.anatomyCount}`,
+        `- **${prefixLabel(o)}** \`${o.namespace}\` — ${summaryLine(o)}`,
       );
     }
+    lines.push("");
+    lines.push("Next: `ontology show <prefix>` for the class hierarchy.");
     return lines.join("\n");
   },
 
@@ -37,3 +43,22 @@ const formatters: Formatters<readonly OntologySummary[]> = {
 };
 
 export default formatters;
+
+/** `ds:` for prefixed namespaces, a placeholder for unprefixed ones. */
+function prefixLabel(o: OntologySummary): string {
+  return o.prefix ? `${o.prefix}:` : "(no prefix)";
+}
+
+/** The same counts-and-metadata line `ontology show` leads with. */
+function summaryLine(o: OntologySummary): string {
+  const parts = [
+    `${o.classCount} classes`,
+    `${o.relationCount} relations`,
+    `${o.attributeCount} attributes`,
+  ];
+  if (o.shapeCount > 0) parts.push(`${o.shapeCount} shapes`);
+  if (o.anatomyCount > 0) parts.push(`${o.anatomyCount} anatomies`);
+  if (o.version) parts.push(`v${o.version}`);
+  if (o.title) parts.push(o.title);
+  return parts.join(" · ");
+}