@canonical/pragma-cli 0.18.0

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

@@ -0,0 +1,170 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const runSetupTaskMock = vi.fn();
+const setupAllMock = vi.fn(() => ({ task: "all" }));
+const setupCompletionsMock = vi.fn((shell?: string) => ({
+  task: "completions",
+  shell,
+}));
+const setupLspMock = vi.fn((cwd: string) => ({ task: "lsp", cwd }));
+const setupMcpMock = vi.fn((cwd: string, harness?: string) => ({
+  task: "mcp",
+  cwd,
+  harness,
+}));
+
+vi.mock("../helpers/runSetupTask.js", () => ({
+  default: runSetupTaskMock,
+}));
+
+vi.mock("../operations/setupAll.js", () => ({
+  default: setupAllMock,
+}));
+
+vi.mock("../operations/setupCompletions.js", () => ({
+  default: setupCompletionsMock,
+}));
+
+vi.mock("../operations/setupLsp.js", () => ({
+  default: setupLspMock,
+}));
+
+vi.mock("../operations/setupMcp.js", () => ({
+  default: setupMcpMock,
+}));
+
+describe("setup command entrypoints", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    runSetupTaskMock.mockResolvedValue({ tag: "exit", code: 0 });
+  });
+
+  it("maps setup all flags into runSetupTask", async () => {
+    const { default: allCommand } = await import("./all.js");
+
+    await allCommand.execute(
+      { dryRun: true, undo: true, yes: true },
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: true, format: "json", verbose: true },
+      },
+    );
+
+    expect(setupAllMock).toHaveBeenCalledWith("/workspace");
+    expect(runSetupTaskMock).toHaveBeenCalledWith(
+      { task: "all" },
+      {
+        dryRun: true,
+        undo: true,
+        yes: true,
+        verbose: true,
+        llm: true,
+        format: "json",
+      },
+    );
+  });
+
+  it("resolves zsh, bash, fish, and default completion targets", async () => {
+    const { default: completionsCommand } = await import("./completions.js");
+
+    await completionsCommand.execute(
+      { zsh: true },
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      },
+    );
+    await completionsCommand.execute(
+      { bash: true },
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      },
+    );
+    await completionsCommand.execute(
+      { fish: true },
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      },
+    );
+    await completionsCommand.execute(
+      {},
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      },
+    );
+
+    expect(setupCompletionsMock).toHaveBeenNthCalledWith(1, "zsh");
+    expect(setupCompletionsMock).toHaveBeenNthCalledWith(2, "bash");
+    expect(setupCompletionsMock).toHaveBeenNthCalledWith(3, "fish");
+    expect(setupCompletionsMock).toHaveBeenNthCalledWith(4, undefined);
+  });
+
+  it("resolves harness-specific and default mcp setup", async () => {
+    const { default: mcpCommand } = await import("./mcp.js");
+
+    await mcpCommand.execute(
+      { claudeCode: true, yes: true },
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      },
+    );
+    await mcpCommand.execute(
+      { cursor: true },
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      },
+    );
+    await mcpCommand.execute(
+      { windsurf: true },
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      },
+    );
+    await mcpCommand.execute(
+      {},
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      },
+    );
+
+    expect(setupMcpMock).toHaveBeenNthCalledWith(
+      1,
+      "/workspace",
+      "claude-code",
+    );
+    expect(setupMcpMock).toHaveBeenNthCalledWith(2, "/workspace", "cursor");
+    expect(setupMcpMock).toHaveBeenNthCalledWith(3, "/workspace", "windsurf");
+    expect(setupMcpMock).toHaveBeenNthCalledWith(4, "/workspace", undefined);
+  });
+
+  it("passes cwd and flags through setup lsp", async () => {
+    const { default: lspCommand } = await import("./lsp.js");
+
+    await lspCommand.execute(
+      { dryRun: true, undo: true },
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: true, format: "json", verbose: true },
+      },
+    );
+
+    expect(setupLspMock).toHaveBeenCalledWith("/workspace");
+    expect(runSetupTaskMock).toHaveBeenCalledWith(
+      { task: "lsp", cwd: "/workspace" },
+      {
+        dryRun: true,
+        undo: true,
+        verbose: true,
+        llm: true,
+        format: "json",
+      },
+    );
+  });
+});

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

@@ -0,0 +1,6 @@
+/** @module Setup command definitions for `pragma setup`. */
+export { default as allCommand } from "./all.js";
+export { default as completionsCommand } from "./completions.js";
+export { default as lspCommand } from "./lsp.js";
+export { default as mcpCommand } from "./mcp.js";
+export { default as skillsCommand } from "./skills.js";

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

@@ -0,0 +1,49 @@
+import type { CommandDefinition, CommandResult } from "@canonical/cli-core";
+import runSetupTask from "../helpers/runSetupTask.js";
+import setupLsp from "../operations/setupLsp.js";
+
+/**
+ * `pragma setup lsp` command definition.
+ *
+ * Installs the Terrazzo LSP VS Code extension.
+ *
+ * @note Impure
+ */
+const lspCommand: CommandDefinition = {
+  path: ["setup", "lsp"],
+  description: "Install the Terrazzo LSP VS Code extension",
+  parameters: [
+    {
+      name: "dryRun",
+      description: "Preview changes without writing",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "undo",
+      description: "Reverse a previous setup",
+      type: "boolean",
+      default: false,
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma setup lsp",
+      "pragma setup lsp --dry-run",
+      "pragma setup lsp --undo",
+    ],
+  },
+  execute: async (
+    params: Record<string, unknown>,
+    ctx,
+  ): Promise<CommandResult> =>
+    runSetupTask(setupLsp(ctx.cwd), {
+      dryRun: params.dryRun === true,
+      undo: params.undo === true,
+      verbose: ctx.globalFlags.verbose,
+      llm: ctx.globalFlags.llm,
+      format: ctx.globalFlags.format,
+    }),
+};
+
+export default lspCommand;

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

@@ -0,0 +1,119 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import runSetupTask from "../helpers/runSetupTask.js";
+import setupMcp from "../operations/setupMcp.js";
+
+/**
+ * Map boolean harness flags to a harness ID string.
+ *
+ * @param params - Command parameters containing optional harness flags.
+ * @returns The forced harness ID, or undefined to auto-detect.
+ */
+function resolveForceHarness(
+  params: Record<string, unknown>,
+): string | undefined {
+  if (params.claudeCode === true) return "claude-code";
+  if (params.cursor === true) return "cursor";
+  if (params.windsurf === true) return "windsurf";
+  return undefined;
+}
+
+function buildSuccessMessage(forceHarnessId: string | undefined): string {
+  if (forceHarnessId) {
+    return `✓ MCP configured for ${forceHarnessId}.`;
+  }
+
+  return "✓ MCP configured for detected harnesses.";
+}
+
+/**
+ * `pragma setup mcp` command definition.
+ *
+ * Configures the pragma MCP server for detected AI harnesses.
+ * Auto-detects harnesses unless overridden with --claude-code, --cursor,
+ * or --windsurf.
+ *
+ * @note Impure
+ */
+const mcpCommand: CommandDefinition = {
+  path: ["setup", "mcp"],
+  description: "Configure pragma MCP server for AI harnesses",
+  parameters: [
+    {
+      name: "dryRun",
+      description: "Preview changes without writing",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "undo",
+      description: "Reverse a previous setup",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "yes",
+      description: "Skip confirmation prompts",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "claudeCode",
+      description: "Configure for Claude Code only",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "cursor",
+      description: "Configure for Cursor only",
+      type: "boolean",
+      default: false,
+    },
+    {
+      name: "windsurf",
+      description: "Configure for Windsurf only",
+      type: "boolean",
+      default: false,
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma setup mcp",
+      "pragma setup mcp --claude-code",
+      "pragma setup mcp --dry-run",
+      "pragma setup mcp --undo",
+    ],
+  },
+  execute: async (
+    params: Record<string, unknown>,
+    ctx,
+  ): Promise<CommandResult> => {
+    const forceHarnessId = resolveForceHarness(params);
+    const result = await runSetupTask(setupMcp(ctx.cwd, forceHarnessId), {
+      dryRun: params.dryRun === true,
+      undo: params.undo === true,
+      yes: params.yes === true,
+      verbose: ctx.globalFlags.verbose,
+      llm: ctx.globalFlags.llm,
+      format: ctx.globalFlags.format,
+    });
+
+    if (
+      params.dryRun !== true &&
+      params.undo !== true &&
+      result.tag === "exit" &&
+      result.code === 0
+    ) {
+      return createOutputResult(buildSuccessMessage(forceHarnessId), {
+        plain: (text) => text,
+      });
+    }
+
+    return result;
+  },
+};
+
+export default mcpCommand;

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

@@ -0,0 +1,64 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import type { PragmaContext } from "../../shared/context.js";
+import buildSkillsCommand from "./skills.js";
+
+const TMP_ROOT = join(tmpdir(), `pragma-setup-cmd-${Date.now()}`);
+
+const TEST_SOURCES = [
+  {
+    dir: join(TMP_ROOT, "node_modules/@canonical/design-system/skills"),
+    packageName: "@canonical/design-system",
+  },
+];
+
+vi.mock("../../skill/helpers/resolveSkillSources.js", () => ({
+  default: () => TEST_SOURCES,
+}));
+
+beforeAll(() => {
+  mkdirSync(TMP_ROOT, { recursive: true });
+
+  const dir = join(TEST_SOURCES[0].dir, "design-audit");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "SKILL.md"),
+    `---
+name: design-audit
+description: Audit a component against DS specs
+---
+`,
+  );
+});
+
+afterAll(() => {
+  rmSync(TMP_ROOT, { recursive: true, force: true });
+});
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    cwd: TMP_ROOT,
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    store: {} as PragmaContext["store"],
+    config: { tier: undefined, channel: "normal" },
+    ...overrides,
+  } as PragmaContext;
+}
+
+describe("buildSkillsCommand", () => {
+  it("has correct path and parameters", () => {
+    const cmd = buildSkillsCommand();
+    expect(cmd.path).toEqual(["setup", "skills"]);
+    expect(cmd.parameters.map((p) => p.name)).toContain("dryRun");
+    expect(cmd.parameters.map((p) => p.name)).toContain("yes");
+  });
+
+  it("returns output result for found skills", async () => {
+    const cmd = buildSkillsCommand();
+    const ctx = makeCtx();
+    const result = await cmd.execute({ dryRun: true }, ctx);
+    expect(result.tag).toBe("output");
+  });
+});

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

@@ -0,0 +1,106 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { detectHarnesses } from "@canonical/harnesses";
+import { collectEffects, runTask } from "@canonical/task";
+import { PragmaError } from "#error";
+import type { PragmaContext } from "../../shared/context.js";
+import { selectFormatter } from "../../shared/formatters.js";
+import { discoverSkills } from "../../skill/operations/index.js";
+import { skillsFormatters } from "../formatters/index.js";
+import type { SetupSkillsOutput } from "../formatters/types.js";
+import { setupSkills } from "../operations/index.js";
+
+/**
+ * Build the `pragma setup skills` command definition.
+ *
+ * Discovers skills from installed packages, detects AI harnesses,
+ * and symlinks skill folders into each harness directory. Supports
+ * dry-run mode via effect collection.
+ *
+ * @returns The command definition for `pragma setup skills`.
+ * @note Impure
+ */
+export default function buildSkillsCommand(): CommandDefinition {
+  return {
+    path: ["setup", "skills"],
+    description:
+      "Symlink agent skills from design system packages into AI harness directories",
+    parameters: [
+      {
+        name: "yes",
+        description: "Skip confirmation prompts",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "dryRun",
+        description: "Preview symlinks without creating them",
+        type: "boolean",
+        default: false,
+      },
+    ],
+    meta: {
+      examples: [
+        "pragma setup skills",
+        "pragma setup skills --dry-run",
+        "pragma setup skills --yes",
+      ],
+    },
+    execute: async (
+      params: Record<string, unknown>,
+      ctx,
+    ): Promise<CommandResult> => {
+      const dryRun = params.dryRun === true;
+      const cwd = (ctx as PragmaContext).cwd;
+
+      const skills = await discoverSkills(cwd);
+      if (skills.length === 0) {
+        throw PragmaError.emptyResults("skill", {
+          recovery: {
+            message:
+              "Install @canonical packages first, then run pragma setup skills.",
+            cli: "pragma setup skills",
+          },
+        });
+      }
+
+      const harnesses = await runTask(detectHarnesses(cwd));
+
+      const task = setupSkills(skills, harnesses, cwd);
+
+      if (dryRun) {
+        const effects = collectEffects(task);
+        const symlinkCount = effects.filter((e) => e._tag === "Symlink").length;
+
+        const output: SetupSkillsOutput = {
+          result: {
+            actions: [],
+            harnessCount: harnesses.length,
+            skillCount: skills.length,
+            warnings: [],
+          },
+          dryRun: true,
+        };
+
+        process.stdout.write(
+          `Would create ${symlinkCount} symlink(s) for ${skills.length} skill(s) across ${harnesses.length} harness(es)\n`,
+        );
+
+        return createOutputResult(output, {
+          plain: selectFormatter(ctx as PragmaContext, skillsFormatters),
+        });
+      }
+
+      const result = await runTask(task);
+
+      const output: SetupSkillsOutput = { result, dryRun: false };
+
+      return createOutputResult(output, {
+        plain: selectFormatter(ctx as PragmaContext, skillsFormatters),
+      });
+    },
+  };
+}

package/src/domains/setup/formatters/index.ts

@@ -0,0 +1,2 @@
+/** @module Formatter sets for setup domain output. */
+export { default as skillsFormatters } from "./skills.js";

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

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+import type { SetupSkillsResult } from "../types.js";
+import formatters from "./skills.js";
+
+const MOCK_RESULT: SetupSkillsResult = {
+  actions: [
+    {
+      skillName: "design-audit",
+      target: "/project/node_modules/@canonical/ds-global/skills/design-audit",
+      linkPath: "/project/.claude/skills/design-audit",
+      action: "created",
+      harnessName: "Claude Code",
+    },
+    {
+      skillName: "scaffold-story",
+      target:
+        "/project/node_modules/@canonical/pragma-cli/skills/scaffold-story",
+      linkPath: "/project/.claude/skills/scaffold-story",
+      action: "created",
+      harnessName: "Claude Code",
+    },
+    {
+      skillName: "design-audit",
+      target: "/project/node_modules/@canonical/ds-global/skills/design-audit",
+      linkPath: "/project/.cursor/skills/design-audit",
+      action: "skipped",
+      harnessName: "Cursor",
+    },
+  ],
+  harnessCount: 2,
+  skillCount: 2,
+  warnings: [],
+};
+
+describe("setup skills formatters", () => {
+  describe("plain", () => {
+    it("shows created symlinks grouped by harness", () => {
+      const output = formatters.plain({
+        result: MOCK_RESULT,
+        dryRun: false,
+      });
+      expect(output).toContain("Created 2 symlinks for Claude Code");
+      expect(output).toContain("1 existing symlink unchanged");
+    });
+
+    it("uses dry-run prefix", () => {
+      const output = formatters.plain({
+        result: MOCK_RESULT,
+        dryRun: true,
+      });
+      expect(output).toContain("Would create 2 symlinks");
+    });
+
+    it("shows replacement warnings", () => {
+      const result: SetupSkillsResult = {
+        ...MOCK_RESULT,
+        actions: [
+          {
+            skillName: "design-audit",
+            target: "/new/target",
+            linkPath: "/project/.claude/skills/design-audit",
+            action: "replaced",
+            harnessName: "Claude Code",
+          },
+        ],
+        warnings: ["Replaced existing symlink for design-audit in Claude Code"],
+      };
+      const output = formatters.plain({ result, dryRun: false });
+      expect(output).toContain("Replaced symlink for design-audit");
+    });
+  });
+
+  describe("llm", () => {
+    it("renders markdown", () => {
+      const output = formatters.llm({
+        result: MOCK_RESULT,
+        dryRun: false,
+      });
+      expect(output).toContain("## Setup Skills");
+      expect(output).toContain("**design-audit**");
+    });
+
+    it("uses dry-run verb", () => {
+      const output = formatters.llm({
+        result: MOCK_RESULT,
+        dryRun: true,
+      });
+      expect(output).toContain("Would symlink");
+    });
+  });
+
+  describe("json", () => {
+    it("produces valid JSON", () => {
+      const output = formatters.json({
+        result: MOCK_RESULT,
+        dryRun: false,
+      });
+      const parsed = JSON.parse(output);
+      expect(parsed.harnessCount).toBe(2);
+      expect(parsed.actions).toHaveLength(3);
+    });
+  });
+});