@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -1,49 +0,0 @@
-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

@@ -1,119 +0,0 @@
-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/setup.ts

@@ -1,70 +0,0 @@
-/**
- * Wires the top-level `pragma setup` command.
- *
- * `setup` is one level more general than `create <thing>`: it configures the
- * whole local environment (completions, LSP, MCP). Unlike `create`, its steps
- * perform *read* effects whose results drive control flow — detecting AI
- * harnesses, checking what is already installed — so it must run for real and
- * report the real outcome. It therefore executes through {@link runSetupTask}
- * (real execution, streamed output) rather than the generator preview-then-
- * execute path, which would render a dry-run preview whose stubbed reads report
- * the wrong state (e.g. "no harnesses detected").
- */
-
-import type { CommandDefinition, CommandResult } from "@canonical/cli-core";
-import runSetupTask from "../helpers/runSetupTask.js";
-import setupAll from "../operations/setupAll.js";
-
-/**
- * Build the top-level `pragma setup` command definition.
- *
- * @returns The command definition for `pragma setup`.
- * @note Impure
- */
-export default function buildSetupCommand(): CommandDefinition {
-  return {
-    path: ["setup"],
-    description:
-      "Configure this project's environment: completions, LSP, and MCP",
-    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 all confirmation prompts",
-        type: "boolean",
-        default: false,
-      },
-    ],
-    meta: {
-      examples: [
-        "pragma setup",
-        "pragma setup --yes",
-        "pragma setup --dry-run",
-        "pragma setup --undo",
-      ],
-    },
-    execute: async (
-      params: Record<string, unknown>,
-      ctx,
-    ): Promise<CommandResult> =>
-      runSetupTask(setupAll(ctx.cwd), {
-        dryRun: params.dryRun === true,
-        undo: params.undo === true,
-        yes: params.yes === true,
-        verbose: ctx.globalFlags.verbose,
-        llm: ctx.globalFlags.llm,
-        format: ctx.globalFlags.format,
-      }),
-  };
-}

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

@@ -1,68 +0,0 @@
-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()}`);
-
-/** One source per skill directory, matching the loader granularity. */
-const TEST_SOURCES = [
-  {
-    dir: join(
-      TMP_ROOT,
-      "node_modules/@canonical/design-system/skills/design-audit",
-    ),
-    packageName: "@canonical/design-system",
-  },
-];
-
-vi.mock("../../skill/helpers/resolveSkillSources.js", () => ({
-  default: () => TEST_SOURCES,
-}));
-
-beforeAll(() => {
-  mkdirSync(TMP_ROOT, { recursive: true });
-
-  const dir = TEST_SOURCES.at(0)?.dir ?? "";
-  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

@@ -1,110 +0,0 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-  runGeneratorTask,
-} from "@canonical/cli-core";
-import { detectHarnesses } from "@canonical/harnesses";
-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";
-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),
-        });
-      }
-
-      // 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 };
-
-      return createOutputResult(output, {
-        plain: selectFormatter(ctx as PragmaContext, skillsFormatters),
-      });
-    },
-  };
-}

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

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

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

@@ -1,103 +0,0 @@
-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);
-    });
-  });
-});

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

@@ -1,112 +0,0 @@
-import chalk from "chalk";
-import type { Formatters } from "../../shared/formatters.js";
-import type { SetupSkillsOutput } from "./types.js";
-
-/**
- * Formatters for `pragma setup skills` output.
- *
- * - **plain** renders symlink actions grouped by harness with chalk styling.
- * - **llm** renders a markdown summary with bullet lists.
- * - **json** serializes the raw SetupSkillsResult.
- */
-const formatters: Formatters<SetupSkillsOutput> = {
-  plain({ result, dryRun }) {
-    const lines: string[] = [];
-    const prefix = dryRun ? "Would create" : "Created";
-
-    const created = result.actions.filter((a) => a.action === "created");
-    const skipped = result.actions.filter((a) => a.action === "skipped");
-    const replaced = result.actions.filter((a) => a.action === "replaced");
-
-    if (created.length > 0) {
-      const byHarness = groupByHarness(created.map((a) => a));
-      for (const [harness, actions] of byHarness) {
-        const count = actions.length;
-        lines.push(
-          `${chalk.green("✓")} ${prefix} ${count} symlink${count === 1 ? "" : "s"} for ${harness}`,
-        );
-      }
-    }
-
-    if (skipped.length > 0) {
-      lines.push(
-        chalk.dim(
-          `  ${skipped.length} existing symlink${skipped.length === 1 ? "" : "s"} unchanged`,
-        ),
-      );
-    }
-
-    if (replaced.length > 0) {
-      for (const action of replaced) {
-        lines.push(
-          chalk.yellow(
-            `  ⚠ Replaced symlink for ${action.skillName} in ${action.harnessName}`,
-          ),
-        );
-      }
-    }
-
-    for (const warning of result.warnings) {
-      lines.push(chalk.yellow(`  ⚠ ${warning}`));
-    }
-
-    return lines.join("\n");
-  },
-
-  llm({ result, dryRun }) {
-    const lines: string[] = [];
-    const verb = dryRun ? "Would symlink" : "Symlinked";
-
-    lines.push(`## Setup Skills`);
-    lines.push("");
-
-    const created = result.actions.filter((a) => a.action === "created");
-    const skipped = result.actions.filter((a) => a.action === "skipped");
-
-    if (created.length > 0) {
-      lines.push(`${verb} ${created.length} skill(s):`);
-      for (const action of created) {
-        lines.push(`- **${action.skillName}** → ${action.harnessName}`);
-      }
-    }
-
-    if (skipped.length > 0) {
-      lines.push("");
-      lines.push(`${skipped.length} already up to date.`);
-    }
-
-    if (result.warnings.length > 0) {
-      lines.push("");
-      lines.push("### Warnings");
-      for (const w of result.warnings) {
-        lines.push(`- ${w}`);
-      }
-    }
-
-    return lines.join("\n");
-  },
-
-  json({ result }) {
-    return JSON.stringify(result, null, 2);
-  },
-};
-
-/**
- * Group actions by their harness name for display.
- *
- * @param actions - Symlink actions to group.
- * @returns A Map keyed by harness name.
- */
-function groupByHarness(
-  actions: readonly { harnessName: string }[],
-): Map<string, typeof actions> {
-  const groups = new Map<string, (typeof actions)[number][]>();
-  for (const action of actions) {
-    const group = groups.get(action.harnessName) ?? [];
-    group.push(action);
-    groups.set(action.harnessName, group);
-  }
-  return groups;
-}
-
-export default formatters;

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

@@ -1,7 +0,0 @@
-import type { SetupSkillsResult } from "../types.js";
-
-/** Formatter input for `pragma setup skills`, pairing the result with a dry-run flag. */
-export interface SetupSkillsOutput {
-  readonly result: SetupSkillsResult;
-  readonly dryRun: boolean;
-}