@canonical/pragma-cli 0.18.0

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

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

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

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import {
+  completionScriptContent,
+  completionScriptPath,
+  postInstallHint,
+} from "./completionScripts.js";
+
+describe("completionScriptContent", () => {
+  it("produces zsh completion with compdef", () => {
+    const script = completionScriptContent("zsh");
+    expect(script).toContain("#compdef pragma");
+    expect(script).toContain("pragma completions zsh");
+  });
+
+  it("produces bash completion with complete -F", () => {
+    const script = completionScriptContent("bash");
+    expect(script).toContain("complete -F _pragma pragma");
+    expect(script).toContain("pragma completions bash");
+  });
+
+  it("produces fish completion with complete -c", () => {
+    const script = completionScriptContent("fish");
+    expect(script).toContain("complete -c pragma");
+    expect(script).toContain("pragma completions fish");
+  });
+});
+
+describe("completionScriptPath", () => {
+  it("returns zsh path under ~/.zfunc", () => {
+    expect(completionScriptPath("zsh")).toContain(".zfunc/_pragma");
+  });
+
+  it("returns bash path under ~/.local/share/bash-completion", () => {
+    expect(completionScriptPath("bash")).toContain(
+      "bash-completion/completions/pragma",
+    );
+  });
+
+  it("returns fish path under ~/.config/fish/completions", () => {
+    expect(completionScriptPath("fish")).toContain(
+      "fish/completions/pragma.fish",
+    );
+  });
+});
+
+describe("postInstallHint", () => {
+  it("hints source for zsh", () => {
+    expect(postInstallHint("zsh")).toContain("source ~/.zshrc");
+  });
+
+  it("hints source for bash", () => {
+    expect(postInstallHint("bash")).toContain("source ~/.bashrc");
+  });
+
+  it("hints new shell for fish", () => {
+    expect(postInstallHint("fish")).toContain("new shell");
+  });
+});

package/src/domains/setup/helpers/completionScripts.ts

@@ -0,0 +1,92 @@
+import type { ShellId } from "./detectShell.js";
+
+const HOME = process.env.HOME ?? "";
+
+/**
+ * Generate the shell-specific completion script content.
+ *
+ * Each script delegates to `pragma completions <shell>` at runtime
+ * so the completion logic stays in the CLI, not in the shell script.
+ *
+ * @param shell - Target shell identifier.
+ * @returns The completion script content as a string.
+ */
+export function completionScriptContent(shell: ShellId): string {
+  switch (shell) {
+    case "zsh":
+      return [
+        "#compdef pragma",
+        "# Generated by `pragma setup completions`",
+        "",
+        "_pragma() {",
+        "  local -a completions",
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: shell syntax, not JS template
+        '  completions=("${(@f)$(pragma completions zsh -- "${words[@]}" 2>/dev/null)}")',
+        "  compadd -- $completions",
+        "}",
+        "",
+        "compdef _pragma pragma",
+        "",
+      ].join("\n");
+
+    case "bash":
+      return [
+        "# Generated by `pragma setup completions`",
+        "",
+        "_pragma() {",
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: shell syntax, not JS template
+        '  local cur="${COMP_WORDS[COMP_CWORD]}"',
+        "  local completions",
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: shell syntax, not JS template
+        '  completions=$(pragma completions bash -- "${COMP_WORDS[@]}" 2>/dev/null)',
+        "  # shellcheck disable=SC2207",
+        '  COMPREPLY=($(compgen -W "$completions" -- "$cur"))',
+        "}",
+        "",
+        "complete -F _pragma pragma",
+        "",
+      ].join("\n");
+
+    case "fish":
+      return [
+        "# Generated by `pragma setup completions`",
+        "",
+        "complete -c pragma -f -a '(pragma completions fish -- (commandline -cop) 2>/dev/null)'",
+        "",
+      ].join("\n");
+  }
+}
+
+/**
+ * Return the standard filesystem path where the completion script should be installed.
+ *
+ * @param shell - Target shell identifier.
+ * @returns Absolute path to the completion script location.
+ */
+export function completionScriptPath(shell: ShellId): string {
+  switch (shell) {
+    case "zsh":
+      return `${HOME}/.zfunc/_pragma`;
+    case "bash":
+      return `${HOME}/.local/share/bash-completion/completions/pragma`;
+    case "fish":
+      return `${HOME}/.config/fish/completions/pragma.fish`;
+  }
+}
+
+/**
+ * Return a post-install hint instructing the user how to activate completions.
+ *
+ * @param shell - Target shell identifier.
+ * @returns A human-readable activation hint.
+ */
+export function postInstallHint(shell: ShellId): string {
+  switch (shell) {
+    case "zsh":
+      return "Run `source ~/.zshrc` or start a new shell to activate.";
+    case "bash":
+      return "Run `source ~/.bashrc` or start a new shell to activate.";
+    case "fish":
+      return "Start a new shell to activate.";
+  }
+}

package/src/domains/setup/helpers/constants.ts

@@ -0,0 +1,2 @@
+/** MCP server name written into harness config files. */
+export const MCP_SERVER_NAME = "pragma";

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

@@ -0,0 +1,48 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import detectShell from "./detectShell.js";
+
+describe("detectShell", () => {
+  let original: string | undefined;
+
+  beforeEach(() => {
+    original = process.env.SHELL;
+  });
+
+  afterEach(() => {
+    if (original !== undefined) {
+      process.env.SHELL = original;
+    } else {
+      delete process.env.SHELL;
+    }
+  });
+
+  it("detects zsh from /bin/zsh", () => {
+    process.env.SHELL = "/bin/zsh";
+    expect(detectShell()).toBe("zsh");
+  });
+
+  it("detects zsh from /usr/bin/zsh", () => {
+    process.env.SHELL = "/usr/bin/zsh";
+    expect(detectShell()).toBe("zsh");
+  });
+
+  it("detects bash from /bin/bash", () => {
+    process.env.SHELL = "/bin/bash";
+    expect(detectShell()).toBe("bash");
+  });
+
+  it("detects fish from /usr/bin/fish", () => {
+    process.env.SHELL = "/usr/bin/fish";
+    expect(detectShell()).toBe("fish");
+  });
+
+  it("returns null for unknown shell", () => {
+    process.env.SHELL = "/bin/tcsh";
+    expect(detectShell()).toBeNull();
+  });
+
+  it("returns null when SHELL is unset", () => {
+    delete process.env.SHELL;
+    expect(detectShell()).toBeNull();
+  });
+});

package/src/domains/setup/helpers/detectShell.ts

@@ -0,0 +1,20 @@
+/** Union of supported shell identifiers. */
+export type ShellId = "zsh" | "bash" | "fish";
+
+const SHELL_MAP: Record<string, ShellId> = {
+  zsh: "zsh",
+  bash: "bash",
+  fish: "fish",
+};
+
+/**
+ * Detect the user's shell from the `$SHELL` environment variable.
+ *
+ * @returns The detected ShellId, or null if `$SHELL` is unset or unrecognized.
+ * @note Impure
+ */
+export default function detectShell(): ShellId | null {
+  const shell = process.env.SHELL ?? "";
+  const basename = shell.split("/").pop() ?? "";
+  return SHELL_MAP[basename] ?? null;
+}

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

@@ -0,0 +1,12 @@
+/** @module Shared helpers for setup commands: shell detection, completion scripts, and task execution. */
+export {
+  completionScriptContent,
+  completionScriptPath,
+  postInstallHint,
+} from "./completionScripts.js";
+export { MCP_SERVER_NAME } from "./constants.js";
+export { default as detectShell, type ShellId } from "./detectShell.js";
+export {
+  default as runSetupTask,
+  type SetupTaskOptions,
+} from "./runSetupTask.js";

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

@@ -0,0 +1,279 @@
+import { info, pure, 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";
+
+describe("runSetupTask", () => {
+  let stderrSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    stderrSpy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stderrSpy.mockRestore();
+    vi.doUnmock("node:readline");
+    vi.doUnmock("@canonical/task");
+  });
+
+  it("returns output result in dry-run mode", async () => {
+    const task = writeFile("/tmp/test.txt", "hello");
+    const result = await runSetupTask(task, { dryRun: 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("/tmp/test.txt");
+    }
+  });
+
+  it("returns json output in dry-run + json mode", async () => {
+    const task = writeFile("/tmp/test.txt", "hello");
+    const result = await runSetupTask(task, {
+      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);
+      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 });
+
+    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");
+    }
+  });
+
+  it("returns exit 0 on successful execution with --yes", async () => {
+    const task = info("test message");
+    const result = await runSetupTask(task, { yes: true });
+
+    expect(result.tag).toBe("exit");
+    if (result.tag === "exit") {
+      expect(result.code).toBe(0);
+    }
+  });
+
+  it("returns exit 0 for pure task", async () => {
+    const task = pure(undefined);
+    const result = await runSetupTask(task, { yes: true });
+
+    expect(result.tag).toBe("exit");
+    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 });
+
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      const text = result.render.plain(result.value);
+      expect(text).toContain("no visible effects");
+    }
+  });
+
+  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 });
+
+    expect(result.tag).toBe("exit");
+    if (result.tag === "exit") {
+      expect(result.code).toBe(0);
+    }
+    expect(stderrSpy).toHaveBeenCalledWith("Nothing to undo.\n");
+  });
+
+  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("");
+    });
+
+    const runSetupTaskWithMocks = await loadRunSetupTask();
+    const result = await runSetupTaskWithMocks({} as never, { yes: true });
+
+    expect(result.tag).toBe("exit");
+    if (result.tag === "exit") {
+      expect(result.code).toBe(0);
+    }
+  });
+
+  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);
+      options.onLog("debug", "hidden");
+      options.onLog("info", "shown");
+    });
+
+    const runSetupTaskWithMocks = await loadRunSetupTask();
+    const result = await runSetupTaskWithMocks({} as never, {});
+
+    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(),
+    });
+    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");
+  });
+
+  it("returns exit 1 when production execution fails", async () => {
+    runTaskMock.mockRejectedValue(new Error("permission denied"));
+
+    const runSetupTaskWithMocks = await loadRunSetupTask();
+    const result = await runSetupTaskWithMocks({} as never, { yes: true });
+
+    expect(result.tag).toBe("exit");
+    if (result.tag === "exit") {
+      expect(result.code).toBe(1);
+    }
+    expect(stderrSpy).toHaveBeenCalledWith("Setup failed: permission denied\n");
+  });
+
+  it("writes verbose undo logs and the singular completion message", async () => {
+    runUndoMock.mockImplementation(async (_task, options) => {
+      options.onLog("debug", "debug line");
+      options.onLog("info", "undoing");
+      return { undoCount: 1 };
+    });
+
+    const runSetupTaskWithMocks = await loadRunSetupTask();
+    const result = await runSetupTaskWithMocks({} as never, {
+      undo: true,
+      yes: true,
+      verbose: true,
+    });
+
+    expect(result.tag).toBe("exit");
+    expect(stderrSpy).toHaveBeenCalledWith("debug line\n");
+    expect(stderrSpy).toHaveBeenCalledWith("undoing\n");
+    expect(stderrSpy).toHaveBeenCalledWith(
+      "Undo complete (1 step reversed).\n",
+    );
+  });
+
+  it("writes the plural undo completion message", async () => {
+    runUndoMock.mockResolvedValue({ undoCount: 2 });
+
+    const runSetupTaskWithMocks = await loadRunSetupTask();
+    const result = await runSetupTaskWithMocks({} as never, {
+      undo: true,
+      yes: true,
+    });
+
+    expect(result.tag).toBe("exit");
+    expect(stderrSpy).toHaveBeenCalledWith(
+      "Undo complete (2 steps reversed).\n",
+    );
+  });
+
+  it("returns exit 1 when undo fails", async () => {
+    runUndoMock.mockRejectedValue(new Error("cannot undo"));
+
+    const runSetupTaskWithMocks = await loadRunSetupTask();
+    const result = await runSetupTaskWithMocks({} as never, {
+      undo: true,
+      yes: true,
+    });
+
+    expect(result.tag).toBe("exit");
+    if (result.tag === "exit") {
+      expect(result.code).toBe(1);
+    }
+    expect(stderrSpy).toHaveBeenCalledWith("Undo failed: cannot undo\n");
+  });
+});