@canonical/pragma-cli 0.29.0 → 0.30.0

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

@@ -8,12 +8,11 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { readConfig } from "#config";
-import { DEFAULT_PACKAGES } from "../../shared/packages.js";
+import { mergeAndParseRefs } from "../../shared/mergeAndParseRefs.js";
 import { cloneRef, fetchRef, pruneCache } from "./gitOps.js";
 import type { PackageRef, RawPackageEntry } from "./parseRef.js";
 import { parsePackageEntry } from "./parseRef.js";
 import { cacheRoot, gitCacheDir } from "./paths.js";
-import readGlobalRefs from "./readGlobalRefs.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -56,7 +55,7 @@ export default async function updateRefs(
   options: UpdateRefsOptions,
 ): Promise<UpdateResult[]> {
   const config = readConfig(options.cwd);
-  const refs = mergeEntries(config.packages);
+  const refs = mergeAndParseRefs(config.packages);
   const results: UpdateResult[] = [];
 
   for (const ref of refs) {
@@ -137,40 +136,6 @@ export default async function updateRefs(
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Merge global + project entries, parse into PackageRef[]. */
-function mergeEntries(
-  projectPackages?: ReadonlyArray<RawPackageEntry>,
-): PackageRef[] {
-  const globalEntries = readGlobalRefs();
-
-  if (
-    (!projectPackages || projectPackages.length === 0) &&
-    globalEntries.length === 0
-  ) {
-    return DEFAULT_PACKAGES.map((pkg) => parsePackageEntry(pkg));
-  }
-
-  const merged = new Map<string, RawPackageEntry>();
-
-  for (const entry of DEFAULT_PACKAGES) {
-    const name = typeof entry === "string" ? entry : entry.name;
-    merged.set(name, entry);
-  }
-  for (const entry of globalEntries) {
-    const name = typeof entry === "string" ? entry : entry.name;
-    merged.set(name, entry);
-  }
-  if (projectPackages) {
-    merged.clear();
-    for (const entry of projectPackages) {
-      const name = typeof entry === "string" ? entry : entry.name;
-      merged.set(name, entry);
-    }
-  }
-
-  return [...merged.values()].map(parsePackageEntry);
-}
-
 /**
  * Remove cache directories that don't match any configured git ref.
  * Returns list of removed directories.

package/src/domains/setup/commands/skills.test.ts

@@ -7,9 +7,13 @@ import buildSkillsCommand from "./skills.js";
 
 const TMP_ROOT = join(tmpdir(), `pragma-setup-cmd-${Date.now()}`);
 
+/** One source per skill directory, matching the loader granularity. */
 const TEST_SOURCES = [
   {
-    dir: join(TMP_ROOT, "node_modules/@canonical/design-system/skills"),
+    dir: join(
+      TMP_ROOT,
+      "node_modules/@canonical/design-system/skills/design-audit",
+    ),
     packageName: "@canonical/design-system",
   },
 ];
@@ -21,7 +25,7 @@ vi.mock("../../skill/helpers/resolveSkillSources.js", () => ({
 beforeAll(() => {
   mkdirSync(TMP_ROOT, { recursive: true });
 
-  const dir = join(TEST_SOURCES[0].dir, "design-audit");
+  const dir = TEST_SOURCES.at(0)?.dir ?? "";
   mkdirSync(dir, { recursive: true });
   writeFileSync(
     join(dir, "SKILL.md"),

package/src/domains/setup/commands/skills.ts

@@ -2,9 +2,11 @@ import {
   type CommandDefinition,
   type CommandResult,
   createOutputResult,
+  runGeneratorTask,
 } from "@canonical/cli-core";
 import { detectHarnesses } from "@canonical/harnesses";
-import { collectEffects, runTask } from "@canonical/task";
+import { collectEffects } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
 import { PragmaError } from "#error";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
@@ -94,7 +96,9 @@ export default function buildSkillsCommand(): CommandDefinition {
         });
       }
 
-      const result = await runTask(task);
+      // Run the symlink task through the shared execution core, like the
+      // other setup commands.
+      const result = await runGeneratorTask(task);
 
       const output: SetupSkillsOutput = { result, dryRun: false };
 

package/src/domains/setup/helpers/runSetupTask.test.ts

@@ -1,33 +1,44 @@
-import { info, pure, writeFile } from "@canonical/task";
+import { answerPromptWithDefaults } from "@canonical/cli-core";
+import { pure, type Task, writeFile } from "@canonical/task";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-const { createInterfaceMock, dryRunMock, runTaskMock, runUndoMock } =
-  vi.hoisted(() => ({
-    createInterfaceMock: vi.fn(),
-    dryRunMock: vi.fn(() => ({ effects: [] })),
-    runTaskMock: vi.fn(),
-    runUndoMock: vi.fn(),
-  }));
-
-async function loadRunSetupTask() {
-  vi.resetModules();
-  vi.doMock("node:readline", () => ({
-    createInterface: createInterfaceMock,
-  }));
-  vi.doMock("@canonical/task", async (importOriginal) => {
-    const actual = await importOriginal<typeof import("@canonical/task")>();
-    return {
-      ...actual,
-      dryRun: dryRunMock,
-      runTask: runTaskMock,
-      runUndo: runUndoMock,
-    };
-  });
-  return (await import("./runSetupTask.js")).default;
-}
-
 import runSetupTask from "./runSetupTask.js";
 
+const {
+  runGeneratorTaskMock,
+  runUndoMock,
+  sessionAnswerMock,
+  sessionDisposeMock,
+} = vi.hoisted(() => ({
+  runGeneratorTaskMock: vi.fn(),
+  runUndoMock: vi.fn(),
+  sessionAnswerMock: vi.fn(),
+  sessionDisposeMock: vi.fn(),
+}));
+
+// runSetupTask orchestrates: dry-run/undo use real formatting and runUndo,
+// while production runs through the shared execution core. Mock the core,
+// runUndo, and the interactive prompt session, so the wiring and lifecycle
+// stay under test with real effect formatting.
+vi.mock("@canonical/cli-core", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@canonical/cli-core")>()),
+  runGeneratorTask: runGeneratorTaskMock,
+}));
+
+vi.mock("@canonical/task/node", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@canonical/task/node")>()),
+  runUndo: runUndoMock,
+}));
+
+vi.mock("../../shared/createInteractivePromptSession.js", () => ({
+  default: () => ({
+    answerPrompt: sessionAnswerMock,
+    wasInterrupted: () => false,
+    dispose: sessionDisposeMock,
+  }),
+}));
+
+const succeed = async (): Promise<undefined> => undefined;
+
 describe("runSetupTask", () => {
   let stderrSpy: ReturnType<typeof vi.spyOn>;
 
@@ -40,13 +51,16 @@ describe("runSetupTask", () => {
 
   afterEach(() => {
     stderrSpy.mockRestore();
-    vi.doUnmock("node:readline");
-    vi.doUnmock("@canonical/task");
   });
 
+  // ===========================================================================
+  // Dry-run mode
+  // ===========================================================================
+
   it("returns output result in dry-run mode", async () => {
-    const task = writeFile("/tmp/test.txt", "hello");
-    const result = await runSetupTask(task, { dryRun: true });
+    const result = await runSetupTask(writeFile("/tmp/test.txt", "hello"), {
+      dryRun: true,
+    });
 
     expect(result.tag).toBe("output");
     if (result.tag === "output") {
@@ -54,176 +68,152 @@ describe("runSetupTask", () => {
       expect(text).toContain("Dry run");
       expect(text).toContain("/tmp/test.txt");
     }
+    expect(runGeneratorTaskMock).not.toHaveBeenCalled();
   });
 
   it("returns json output in dry-run + json mode", async () => {
-    const task = writeFile("/tmp/test.txt", "hello");
-    const result = await runSetupTask(task, {
+    const result = await runSetupTask(writeFile("/tmp/test.txt", "hello"), {
       dryRun: true,
       format: "json",
     });
 
     expect(result.tag).toBe("output");
     if (result.tag === "output") {
-      const text = result.render.plain(result.value);
-      const parsed = JSON.parse(text);
+      const parsed = JSON.parse(result.render.plain(result.value));
       expect(Array.isArray(parsed)).toBe(true);
       expect(parsed[0].action).toBe("WriteFile");
     }
   });
 
   it("returns llm markdown in dry-run + llm mode", async () => {
-    const task = writeFile("/tmp/test.txt", "hello");
-    const result = await runSetupTask(task, { dryRun: true, llm: true });
+    const result = await runSetupTask(writeFile("/tmp/test.txt", "hello"), {
+      dryRun: true,
+      llm: true,
+    });
 
     expect(result.tag).toBe("output");
     if (result.tag === "output") {
-      const text = result.render.plain(result.value);
-      expect(text).toContain("## Dry Run");
-      expect(text).toContain("WriteFile");
+      expect(result.render.plain(result.value)).toContain("Dry Run");
     }
   });
 
-  it("returns exit 0 on successful execution with --yes", async () => {
-    const task = info("test message");
-    const result = await runSetupTask(task, { yes: true });
+  it("shows the no-visible-effects message when a dry-run collects none", async () => {
+    const result = await runSetupTask(pure(undefined) as Task<void>, {
+      dryRun: true,
+      verbose: false,
+    });
 
-    expect(result.tag).toBe("exit");
-    if (result.tag === "exit") {
-      expect(result.code).toBe(0);
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toContain("no visible effects");
     }
   });
 
-  it("returns exit 0 for pure task", async () => {
-    const task = pure(undefined);
-    const result = await runSetupTask(task, { yes: true });
+  // ===========================================================================
+  // Production execution — through the shared execution core
+  // ===========================================================================
+
+  it("runs production through the shared execution core and returns exit 0", async () => {
+    runGeneratorTaskMock.mockImplementation(succeed);
 
+    const result = await runSetupTask(writeFile("/tmp/x", "y"), { yes: true });
+
+    expect(runGeneratorTaskMock).toHaveBeenCalledTimes(1);
     expect(result.tag).toBe("exit");
-    if (result.tag === "exit") {
-      expect(result.code).toBe(0);
-    }
+    if (result.tag === "exit") expect(result.code).toBe(0);
   });
 
-  it("shows no visible effects message for pure dry-run", async () => {
-    const task = pure(undefined);
-    const result = await runSetupTask(task, { dryRun: true });
+  it("wires the auto-confirm handler in yes mode", async () => {
+    runGeneratorTaskMock.mockImplementation(async (_task, options) => {
+      expect(options.promptHandler).toBe(answerPromptWithDefaults);
+      return succeed();
+    });
 
-    expect(result.tag).toBe("output");
-    if (result.tag === "output") {
-      const text = result.render.plain(result.value);
-      expect(text).toContain("no visible effects");
-    }
+    await runSetupTask(writeFile("/tmp/x", "y"), { yes: true });
+    expect(runGeneratorTaskMock).toHaveBeenCalledTimes(1);
   });
 
-  it("returns exit 0 in undo mode for a pure task", async () => {
-    const task = pure(undefined);
-    const result = await runSetupTask(task, { undo: true, yes: true });
+  it("wires an interactive prompt session when not in yes mode and disposes it", async () => {
+    runGeneratorTaskMock.mockImplementation(async (_task, options) => {
+      expect(options.promptHandler).toBe(sessionAnswerMock);
+      expect(sessionDisposeMock).not.toHaveBeenCalled();
+      return succeed();
+    });
 
-    expect(result.tag).toBe("exit");
-    if (result.tag === "exit") {
-      expect(result.code).toBe(0);
-    }
-    expect(stderrSpy).toHaveBeenCalledWith("Nothing to undo.\n");
+    await runSetupTask(writeFile("/tmp/x", "y"), {});
+    expect(runGeneratorTaskMock).toHaveBeenCalledTimes(1);
+    expect(sessionDisposeMock).toHaveBeenCalledTimes(1);
   });
 
-  it("auto-confirms select, multiselect, confirm, and text prompts in yes mode", async () => {
-    runTaskMock.mockImplementation(async (_task, options) => {
-      expect(
-        await options.promptHandler({
-          _tag: "Prompt",
-          question: { type: "confirm", default: false, message: "Continue?" },
-        }),
-      ).toBe(false);
-      expect(
-        await options.promptHandler({
-          _tag: "Prompt",
-          question: {
-            type: "select",
-            choices: [{ value: "zsh" }],
-            message: "Shell?",
-          },
-        }),
-      ).toBe("zsh");
-      expect(
-        await options.promptHandler({
-          _tag: "Prompt",
-          question: { type: "multiselect", message: "Pick many" },
-        }),
-      ).toEqual([]);
-      expect(
-        await options.promptHandler({
-          _tag: "Prompt",
-          question: { type: "input", message: "Name?" },
-        }),
-      ).toBe("");
-    });
+  it("disposes the prompt session even when production execution fails", async () => {
+    runGeneratorTaskMock.mockRejectedValue(new Error("boom"));
 
-    const runSetupTaskWithMocks = await loadRunSetupTask();
-    const result = await runSetupTaskWithMocks({} as never, { yes: true });
+    const result = await runSetupTask(writeFile("/tmp/x", "y"), {});
 
     expect(result.tag).toBe("exit");
-    if (result.tag === "exit") {
-      expect(result.code).toBe(0);
-    }
+    expect(sessionDisposeMock).toHaveBeenCalledTimes(1);
   });
 
-  it("uses interactive confirm defaults and suppresses debug logs unless verbose", async () => {
-    createInterfaceMock.mockReturnValue({
-      question: (_prompt: string, cb: (answer: string) => void) => cb(""),
-      close: vi.fn(),
-    });
-    runTaskMock.mockImplementation(async (_task, options) => {
-      expect(
-        await options.promptHandler({
-          _tag: "Prompt",
-          question: { type: "confirm", default: true, message: "Continue?" },
-        }),
-      ).toBe(true);
+  it("suppresses debug logs unless verbose during production", async () => {
+    runGeneratorTaskMock.mockImplementation(async (_task, options) => {
       options.onLog("debug", "hidden");
       options.onLog("info", "shown");
+      return succeed();
     });
 
-    const runSetupTaskWithMocks = await loadRunSetupTask();
-    const result = await runSetupTaskWithMocks({} as never, {});
+    await runSetupTask(writeFile("/tmp/x", "y"), { yes: true });
 
-    expect(result.tag).toBe("exit");
     expect(stderrSpy).toHaveBeenCalledWith("shown\n");
     expect(stderrSpy).not.toHaveBeenCalledWith("hidden\n");
   });
 
-  it("returns false for explicit negative interactive confirmation", async () => {
-    createInterfaceMock.mockReturnValue({
-      question: (_prompt: string, cb: (answer: string) => void) => cb("n"),
-      close: vi.fn(),
+  it("emits debug logs when verbose during production", async () => {
+    runGeneratorTaskMock.mockImplementation(async (_task, options) => {
+      options.onLog("debug", "shown-debug");
+      return succeed();
     });
-    runTaskMock.mockImplementation(async (_task, options) => {
-      expect(
-        await options.promptHandler({
-          _tag: "Prompt",
-          question: { type: "confirm", default: false, message: "Continue?" },
-        }),
-      ).toBe(false);
-    });
-
-    const runSetupTaskWithMocks = await loadRunSetupTask();
-    const result = await runSetupTaskWithMocks({} as never, {});
 
-    expect(result.tag).toBe("exit");
+    await runSetupTask(writeFile("/tmp/x", "y"), { yes: true, verbose: true });
+    expect(stderrSpy).toHaveBeenCalledWith("shown-debug\n");
   });
 
   it("returns exit 1 when production execution fails", async () => {
-    runTaskMock.mockRejectedValue(new Error("permission denied"));
+    runGeneratorTaskMock.mockRejectedValue(new Error("permission denied"));
 
-    const runSetupTaskWithMocks = await loadRunSetupTask();
-    const result = await runSetupTaskWithMocks({} as never, { yes: true });
+    const result = await runSetupTask(writeFile("/tmp/x", "y"), { yes: true });
 
     expect(result.tag).toBe("exit");
-    if (result.tag === "exit") {
-      expect(result.code).toBe(1);
-    }
+    if (result.tag === "exit") expect(result.code).toBe(1);
     expect(stderrSpy).toHaveBeenCalledWith("Setup failed: permission denied\n");
   });
 
+  it("stringifies a non-Error production rejection", async () => {
+    runGeneratorTaskMock.mockRejectedValue("raw failure");
+
+    const result = await runSetupTask(writeFile("/tmp/x", "y"), { yes: true });
+
+    expect(result.tag).toBe("exit");
+    if (result.tag === "exit") expect(result.code).toBe(1);
+    expect(stderrSpy).toHaveBeenCalledWith("Setup failed: raw failure\n");
+  });
+
+  // ===========================================================================
+  // Undo mode
+  // ===========================================================================
+
+  it("reports nothing to undo when no undos are collected", async () => {
+    runUndoMock.mockResolvedValue({ undoCount: 0 });
+
+    const result = await runSetupTask(writeFile("/tmp/x", "y"), {
+      undo: true,
+      yes: true,
+    });
+
+    expect(result.tag).toBe("exit");
+    if (result.tag === "exit") expect(result.code).toBe(0);
+    expect(stderrSpy).toHaveBeenCalledWith("Nothing to undo.\n");
+  });
+
   it("writes verbose undo logs and the singular completion message", async () => {
     runUndoMock.mockImplementation(async (_task, options) => {
       options.onLog("debug", "debug line");
@@ -231,8 +221,7 @@ describe("runSetupTask", () => {
       return { undoCount: 1 };
     });
 
-    const runSetupTaskWithMocks = await loadRunSetupTask();
-    const result = await runSetupTaskWithMocks({} as never, {
+    const result = await runSetupTask(writeFile("/tmp/x", "y"), {
       undo: true,
       yes: true,
       verbose: true,
@@ -249,8 +238,7 @@ describe("runSetupTask", () => {
   it("writes the plural undo completion message", async () => {
     runUndoMock.mockResolvedValue({ undoCount: 2 });
 
-    const runSetupTaskWithMocks = await loadRunSetupTask();
-    const result = await runSetupTaskWithMocks({} as never, {
+    const result = await runSetupTask(writeFile("/tmp/x", "y"), {
       undo: true,
       yes: true,
     });
@@ -264,16 +252,26 @@ describe("runSetupTask", () => {
   it("returns exit 1 when undo fails", async () => {
     runUndoMock.mockRejectedValue(new Error("cannot undo"));
 
-    const runSetupTaskWithMocks = await loadRunSetupTask();
-    const result = await runSetupTaskWithMocks({} as never, {
+    const result = await runSetupTask(writeFile("/tmp/x", "y"), {
       undo: true,
       yes: true,
     });
 
     expect(result.tag).toBe("exit");
-    if (result.tag === "exit") {
-      expect(result.code).toBe(1);
-    }
+    if (result.tag === "exit") expect(result.code).toBe(1);
     expect(stderrSpy).toHaveBeenCalledWith("Undo failed: cannot undo\n");
   });
+
+  it("stringifies a non-Error undo rejection", async () => {
+    runUndoMock.mockRejectedValue("raw undo failure");
+
+    const result = await runSetupTask(writeFile("/tmp/x", "y"), {
+      undo: true,
+      yes: true,
+    });
+
+    expect(result.tag).toBe("exit");
+    if (result.tag === "exit") expect(result.code).toBe(1);
+    expect(stderrSpy).toHaveBeenCalledWith("Undo failed: raw undo failure\n");
+  });
 });