@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,221 +0,0 @@
-import {
-  answerPromptWithDefaults,
-  type CommandResult,
-  createExitResult,
-  createOutputResult,
-  formatEffectLine,
-  isVisibleEffect,
-  runGeneratorTask,
-} from "@canonical/cli-core";
-import { dryRun, type Effect, type Task } from "@canonical/task";
-import { runUndo } from "@canonical/task/node";
-import createInteractivePromptSession, {
-  type InteractivePromptSession,
-} from "../../shared/createInteractivePromptSession.js";
-import type { LogLevel } from "../types.js";
-
-/** Options controlling how {@link runSetupTask} executes. */
-export interface SetupTaskOptions {
-  readonly dryRun?: boolean;
-  readonly undo?: boolean;
-  readonly yes?: boolean;
-  readonly verbose?: boolean;
-  readonly llm?: boolean;
-  readonly format?: "text" | "json";
-}
-
-/**
- * Pick the prompt handler for a run: auto-confirm defaults under `--yes`, else
- * an interactive readline session (whose lifetime the caller owns via the
- * returned `dispose`).
- */
-function selectPromptHandler(yes: boolean): {
-  handler: (effect: Effect & { _tag: "Prompt" }) => Promise<unknown>;
-  wasInterrupted: () => boolean;
-  dispose: () => void;
-} {
-  if (yes) {
-    return {
-      handler: answerPromptWithDefaults,
-      wasInterrupted: () => false,
-      dispose: () => {},
-    };
-  }
-  const session: InteractivePromptSession = createInteractivePromptSession();
-  return {
-    handler: session.answerPrompt,
-    wasInterrupted: session.wasInterrupted,
-    dispose: session.dispose,
-  };
-}
-
-/**
- * Build a task log sink that writes to stderr, hiding debug lines unless
- * verbose is set.
- */
-function createStderrLogger(
-  verbose: boolean,
-): (level: LogLevel, message: string) => void {
-  return (level, message) => {
-    if (level === "debug" && !verbose) return;
-    process.stderr.write(`${message}\n`);
-  };
-}
-
-/**
- * Format dry-run effects as plain terminal output with tree-style lines.
- *
- * @param effects - Collected effects from the dry-run.
- * @param verbose - Whether to include debug-level effects.
- * @returns Formatted multi-line string.
- */
-function formatDryRunPlain(
-  effects: readonly Effect[],
-  verbose: boolean,
-): string {
-  const visible = effects.filter((e) => isVisibleEffect(e, verbose));
-  if (visible.length === 0) return "Dry run: no visible effects.\n";
-
-  const lines = ["Dry run — the following operations would be performed:\n"];
-  for (const [i, effect] of visible.entries()) {
-    lines.push(formatEffectLine(effect, i === visible.length - 1));
-  }
-  lines.push("\nNo changes were made.");
-  return lines.join("\n");
-}
-
-/**
- * Format dry-run effects as a markdown table for LLM output.
- *
- * @param effects - Collected effects from the dry-run.
- * @param verbose - Whether to include debug-level effects.
- * @returns Markdown-formatted string.
- */
-function formatDryRunLlm(effects: readonly Effect[], verbose: boolean): string {
-  const visible = effects.filter((e) => isVisibleEffect(e, verbose));
-  if (visible.length === 0) return "## Dry Run\n\nNo visible effects.\n";
-
-  const lines = ["## Dry Run\n", "| Action | Detail |", "|--------|--------|"];
-  for (const effect of visible) {
-    const action = effect._tag;
-    const detail =
-      "path" in effect
-        ? (effect as { path: string }).path
-        : "message" in effect
-          ? (effect as { message: string }).message
-          : "";
-    lines.push(`| ${action} | ${detail} |`);
-  }
-  lines.push("\n---\nDry-run complete. No files were modified.");
-  return lines.join("\n");
-}
-
-/**
- * Format dry-run effects as a JSON array.
- *
- * @param effects - Collected effects from the dry-run.
- * @returns JSON string with effect summaries.
- */
-function formatDryRunJson(effects: readonly Effect[]): string {
-  const entries = effects
-    .filter((e) => isVisibleEffect(e, true))
-    .map((e) => ({
-      action: e._tag,
-      ...("path" in e ? { path: (e as { path: string }).path } : {}),
-      ...("message" in e
-        ? { message: (e as { message: string }).message }
-        : {}),
-    }));
-  return `${JSON.stringify(entries, null, 2)}\n`;
-}
-
-/**
- * Execute a setup Task and return a CommandResult.
- *
- * Supports three execution modes:
- * - `--dry-run`: collects effects without executing, formats for display.
- * - `--undo`: walks the task tree, collects undo operations, executes in reverse.
- * - default: execution through {@link runGeneratorTask}, with readline-based
- *   prompts on stderr.
- *
- * @param task - The setup Task to execute.
- * @param options - Execution options (dryRun, undo, yes, verbose, llm, format).
- * @returns A CommandResult with exit code or formatted output.
- * @note Impure
- */
-export default async function runSetupTask(
-  task: Task<void>,
-  options: SetupTaskOptions = {},
-): Promise<CommandResult> {
-  const verbose = options.verbose ?? false;
-
-  // Dry-run mode: collect effects without executing
-  if (options.dryRun) {
-    const result = dryRun(task);
-
-    if (options.format === "json") {
-      const json = formatDryRunJson(result.effects);
-      return createOutputResult(json, { plain: (s) => s });
-    }
-    if (options.llm) {
-      const md = formatDryRunLlm(result.effects, verbose);
-      return createOutputResult(md, { plain: (s) => s });
-    }
-
-    const text = formatDryRunPlain(result.effects, verbose);
-    return createOutputResult(text, { plain: (s) => s });
-  }
-
-  // Undo mode: walk the task tree, collect undos, execute in reverse
-  if (options.undo) {
-    const {
-      handler: promptHandler,
-      wasInterrupted,
-      dispose,
-    } = selectPromptHandler(options.yes ?? false);
-    const onLog = createStderrLogger(verbose);
-
-    try {
-      const result = await runUndo(task, { promptHandler, onLog });
-      if (result.undoCount === 0) {
-        process.stderr.write("Nothing to undo.\n");
-      } else {
-        process.stderr.write(
-          `Undo complete (${result.undoCount} step${result.undoCount === 1 ? "" : "s"} reversed).\n`,
-        );
-      }
-      return createExitResult(0);
-    } catch (err) {
-      if (wasInterrupted()) {
-        return createExitResult(130);
-      }
-      const message = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`Undo failed: ${message}\n`);
-      return createExitResult(1);
-    } finally {
-      dispose();
-    }
-  }
-
-  // Production execution
-  const {
-    handler: promptHandler,
-    wasInterrupted,
-    dispose,
-  } = selectPromptHandler(options.yes ?? false);
-  const onLog = createStderrLogger(verbose);
-
-  try {
-    await runGeneratorTask(task, { promptHandler, onLog });
-    return createExitResult(0);
-  } catch (err) {
-    if (wasInterrupted()) {
-      return createExitResult(130);
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`Setup failed: ${message}\n`);
-    return createExitResult(1);
-  } finally {
-    dispose();
-  }
-}

package/src/domains/setup/index.ts

@@ -1,37 +0,0 @@
-/** @module Setup domain -- commands for environment configuration (completions, LSP, MCP, skills). */
-
-import type { CommandDefinition } from "@canonical/cli-core";
-import {
-  completionsCommand,
-  lspCommand,
-  mcpCommand,
-  setupCommand,
-  skillsCommand,
-} from "./commands/index.js";
-
-/**
- * Return all setup command definitions.
- *
- * The top-level `pragma setup` is a summon-generator-backed command (replacing
- * the former `setup all`); the granular `setup <step>` verbs remain for
- * targeted, scriptable configuration of a single concern.
- *
- * @returns An array of CommandDefinitions for the setup command and its verbs.
- */
-export function commands(): CommandDefinition[] {
-  return [
-    setupCommand(),
-    lspCommand,
-    mcpCommand,
-    completionsCommand,
-    skillsCommand(),
-  ];
-}
-
-export {
-  setupAll,
-  setupCompletions,
-  setupLsp,
-  setupMcp,
-  setupSkills,
-} from "./operations/index.js";

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

@@ -1,6 +0,0 @@
-/** @module Setup operations that compose Task monads for filesystem effects. */
-export { default as setupAll } from "./setupAll.js";
-export { default as setupCompletions } from "./setupCompletions.js";
-export { default as setupLsp } from "./setupLsp.js";
-export { default as setupMcp } from "./setupMcp.js";
-export { default as setupSkills } from "./setupSkills.js";

package/src/domains/setup/operations/setupAll.test.ts

@@ -1,48 +0,0 @@
-import { collectEffects, dryRun } from "@canonical/task";
-import { describe, expect, it } from "vitest";
-import setupAll from "./setupAll.js";
-
-describe("setupAll", () => {
-  it("produces prompt effects for each step", () => {
-    const result = dryRun(setupAll("/project"));
-    const prompts = result.effects.filter((e) => e._tag === "Prompt");
-
-    // At least 3 top-level prompts: completions, lsp, mcp
-    expect(prompts.length).toBeGreaterThanOrEqual(3);
-  });
-
-  it("includes setup header in log output", () => {
-    const result = dryRun(setupAll("/project"));
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    expect(logs.some((l) => l.message.includes("Setting up pragma"))).toBe(
-      true,
-    );
-  });
-
-  it("includes completion message at end", () => {
-    const result = dryRun(setupAll("/project"));
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    expect(logs.some((l) => l.message.includes("Setup complete"))).toBe(true);
-  });
-
-  it("runs steps in sequence (completions, lsp, mcp)", () => {
-    const result = dryRun(setupAll("/project"));
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    const messages = logs.map((l) => l.message);
-
-    const completionsIdx = messages.findIndex((m) =>
-      m.includes("1. Shell completions"),
-    );
-    const lspIdx = messages.findIndex((m) => m.includes("2. LSP"));
-    const mcpIdx = messages.findIndex((m) => m.includes("3. MCP"));
-
-    expect(completionsIdx).toBeGreaterThanOrEqual(0);
-    expect(lspIdx).toBeGreaterThan(completionsIdx);
-    expect(mcpIdx).toBeGreaterThan(lspIdx);
-  });
-
-  it("collects effects without execution", () => {
-    const effects = collectEffects(setupAll("/project"));
-    expect(effects.length).toBeGreaterThan(0);
-  });
-});

package/src/domains/setup/operations/setupAll.ts

@@ -1,41 +0,0 @@
-import { $, gen, info, promptConfirm, type Task, when } from "@canonical/task";
-import setupCompletions from "./setupCompletions.js";
-import setupLsp from "./setupLsp.js";
-import setupMcp from "./setupMcp.js";
-
-/**
- * Compose a Task that runs completions, LSP, and MCP setup in sequence,
- * each guarded by a promptConfirm gate.
- *
- * @param root - Project root directory.
- * @returns A Task that yields void on completion.
- * @note Impure
- */
-export default function setupAll(root: string): Task<void> {
-  return gen(function* () {
-    yield* $(info("Setting up pragma for this project...\n"));
-
-    // Step 1: Shell completions
-    yield* $(info("1. Shell completions"));
-    const doCompletions = yield* $(
-      promptConfirm("setup-completions", "  Set up shell completions?", true),
-    );
-    yield* $(when(doCompletions, setupCompletions()));
-
-    // Step 2: LSP
-    yield* $(info("\n2. LSP"));
-    const doLsp = yield* $(
-      promptConfirm("setup-lsp", "  Install Terrazzo LSP extension?", true),
-    );
-    yield* $(when(doLsp, setupLsp(root)));
-
-    // Step 3: MCP
-    yield* $(info("\n3. MCP"));
-    const doMcp = yield* $(
-      promptConfirm("setup-mcp", "  Set up MCP for AI harnesses?", true),
-    );
-    yield* $(when(doMcp, setupMcp(root)));
-
-    yield* $(info("\nSetup complete. Run `pragma doctor` to verify."));
-  });
-}

package/src/domains/setup/operations/setupCompletions.test.ts

@@ -1,94 +0,0 @@
-import { dryRunWith, type Effect } from "@canonical/task";
-import { describe, expect, it } from "vitest";
-import setupCompletions from "./setupCompletions.js";
-
-const mockExists =
-  (predicate: (path: string) => boolean) =>
-  (effect: Effect): unknown =>
-    predicate((effect as Effect & { _tag: "Exists" }).path);
-
-function mocks(
-  existsPredicate: (path: string) => boolean,
-): Map<string, (effect: Effect) => unknown> {
-  return new Map([["Exists", mockExists(existsPredicate)]]);
-}
-
-describe("setupCompletions", () => {
-  it("writes zsh completion to ~/.zfunc/_pragma", () => {
-    const result = dryRunWith(
-      setupCompletions("zsh"),
-      mocks(() => true), // dir exists
-    );
-
-    const writes = result.effects.filter(
-      (e) => e._tag === "WriteFile",
-    ) as (Effect & { _tag: "WriteFile" })[];
-    expect(writes).toHaveLength(1);
-    expect(writes[0].path).toContain(".zfunc/_pragma");
-    expect(writes[0].content).toContain("#compdef pragma");
-  });
-
-  it("writes bash completion to standard path", () => {
-    const result = dryRunWith(
-      setupCompletions("bash"),
-      mocks(() => true),
-    );
-
-    const writes = result.effects.filter(
-      (e) => e._tag === "WriteFile",
-    ) as (Effect & { _tag: "WriteFile" })[];
-    expect(writes).toHaveLength(1);
-    expect(writes[0].path).toContain("bash-completion/completions/pragma");
-    expect(writes[0].content).toContain("complete -F _pragma pragma");
-  });
-
-  it("writes fish completion to standard path", () => {
-    const result = dryRunWith(
-      setupCompletions("fish"),
-      mocks(() => true),
-    );
-
-    const writes = result.effects.filter(
-      (e) => e._tag === "WriteFile",
-    ) as (Effect & { _tag: "WriteFile" })[];
-    expect(writes).toHaveLength(1);
-    expect(writes[0].path).toContain("fish/completions/pragma.fish");
-    expect(writes[0].content).toContain("complete -c pragma");
-  });
-
-  it("creates parent directory when missing", () => {
-    const result = dryRunWith(
-      setupCompletions("zsh"),
-      mocks(() => false), // dir does not exist
-    );
-
-    const mkdirs = result.effects.filter((e) => e._tag === "MakeDir");
-    expect(mkdirs.length).toBeGreaterThan(0);
-  });
-
-  it("warns when shell is undetected (no force)", () => {
-    // This test works because detectShell() reads process.env.SHELL.
-    // We pass undefined (no force) but mock nothing — detectShell() will
-    // use the real $SHELL. To test the null path, we'd need to unset $SHELL.
-    // Instead, just verify the forced-null scenario:
-    // Since we can't easily unset $SHELL in this test, we verify the
-    // happy path works and the warning path is tested separately.
-    const result = dryRunWith(
-      setupCompletions("zsh"),
-      mocks(() => true),
-    );
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    expect(
-      logs.some((l) => l.message.includes("✓ Completions installed")),
-    ).toBe(true);
-  });
-
-  it("includes post-install hint in output", () => {
-    const result = dryRunWith(
-      setupCompletions("zsh"),
-      mocks(() => true),
-    );
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    expect(logs.some((l) => l.message.includes("source ~/.zshrc"))).toBe(true);
-  });
-});

package/src/domains/setup/operations/setupCompletions.ts

@@ -1,54 +0,0 @@
-import { dirname } from "node:path";
-import {
-  $,
-  exists,
-  gen,
-  info,
-  mkdir,
-  type Task,
-  warn,
-  writeFile,
-} from "@canonical/task";
-import {
-  completionScriptContent,
-  completionScriptPath,
-  postInstallHint,
-} from "../helpers/completionScripts.js";
-import detectShell, { type ShellId } from "../helpers/detectShell.js";
-
-/**
- * Compose a Task that detects the user's shell and writes the
- * appropriate completion script to the standard install path.
- *
- * @param forceShell - If set, skip detection and use this shell.
- * @returns A Task that yields void on completion.
- * @note Impure
- */
-export default function setupCompletions(forceShell?: ShellId): Task<void> {
-  return gen(function* () {
-    const shell = forceShell ?? detectShell();
-
-    if (!shell) {
-      yield* $(
-        warn("Shell not detected. Use --zsh, --bash, or --fish to specify."),
-      );
-      return;
-    }
-
-    yield* $(info(`Setting up completions for ${shell}...`));
-
-    const path = completionScriptPath(shell);
-    const dir = dirname(path);
-
-    const dirExists = yield* $(exists(dir));
-    if (!dirExists) {
-      yield* $(mkdir(dir, true));
-    }
-
-    const script = completionScriptContent(shell);
-    yield* $(writeFile(path, script));
-
-    yield* $(info(`✓ Completions installed for ${shell}.`));
-    yield* $(info(`  ${postInstallHint(shell)}`));
-  });
-}

package/src/domains/setup/operations/setupLsp.test.ts

@@ -1,30 +0,0 @@
-import { collectEffects, dryRun } from "@canonical/task";
-import { describe, expect, it } from "vitest";
-import setupLsp from "./setupLsp.js";
-
-describe("setupLsp", () => {
-  it("produces an exec effect for bunx", () => {
-    const result = dryRun(setupLsp("/project"));
-    const execs = result.effects.filter((e) => e._tag === "Exec");
-    expect(execs).toHaveLength(1);
-    expect(execs[0]).toMatchObject({
-      _tag: "Exec",
-      command: "bunx",
-      args: ["@canonical/terrazzo-lsp-extension"],
-      cwd: "/project",
-    });
-  });
-
-  it("logs info messages before and after exec", () => {
-    const result = dryRun(setupLsp("/project"));
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    expect(logs.some((l) => l.message.includes("Ensuring"))).toBe(true);
-    // Reports an idempotent "up to date" outcome, not a fresh install claim.
-    expect(logs.some((l) => l.message.includes("up to date"))).toBe(true);
-  });
-
-  it("collects effects without execution", () => {
-    const effects = collectEffects(setupLsp("/project"));
-    expect(effects.length).toBeGreaterThan(0);
-  });
-});

package/src/domains/setup/operations/setupLsp.ts

@@ -1,22 +0,0 @@
-import { $, exec, gen, info, type Task } from "@canonical/task";
-
-/**
- * Compose a Task that installs the Terrazzo LSP VS Code extension
- * by running `bunx @canonical/terrazzo-lsp-extension`.
- *
- * @param root - Project root directory (used as cwd for the subprocess).
- * @returns A Task that yields void on completion.
- * @note Impure
- */
-export default function setupLsp(root: string): Task<void> {
-  return gen(function* () {
-    yield* $(
-      info("Ensuring the Terrazzo LSP VS Code extension is installed..."),
-    );
-    // The extension installer is idempotent — it installs if missing and is a
-    // no-op if already present — so this reports "ensured", not a fresh install
-    // (pragma does not inspect VS Code's extension state to tell them apart).
-    yield* $(exec("bunx", ["@canonical/terrazzo-lsp-extension"], root));
-    yield* $(info("✓ Terrazzo LSP extension is installed (up to date)."));
-  });
-}

package/src/domains/setup/operations/setupMcp.test.ts

@@ -1,120 +0,0 @@
-import { dryRunWith, type Effect } from "@canonical/task";
-import { describe, expect, it } from "vitest";
-import setupMcp from "./setupMcp.js";
-
-const mockExists =
-  (predicate: (path: string) => boolean) =>
-  (effect: Effect): unknown =>
-    predicate((effect as Effect & { _tag: "Exists" }).path);
-
-function mocks(
-  existsPredicate: (path: string) => boolean,
-): Map<string, (effect: Effect) => unknown> {
-  return new Map<string, (effect: Effect) => unknown>([
-    ["Exists", mockExists(existsPredicate)],
-    // An existing config reads back as an empty-but-valid JSON object, so a
-    // write merges into it rather than failing closed on the dry-run placeholder.
-    ["ReadFile", () => "{}"],
-  ]);
-}
-
-describe("setupMcp", () => {
-  it("warns when no harnesses are detected", () => {
-    const result = dryRunWith(
-      setupMcp("/project"),
-      mocks(() => false),
-    );
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    expect(logs.some((l) => l.message.includes("No AI harnesses"))).toBe(true);
-  });
-
-  it("does not write config when no harnesses detected", () => {
-    const result = dryRunWith(
-      setupMcp("/project"),
-      mocks(() => false),
-    );
-    const writes = result.effects.filter((e) => e._tag === "WriteFile");
-    expect(writes).toHaveLength(0);
-  });
-
-  it("detects Claude Code and writes config (dry-run defaults confirm)", () => {
-    const result = dryRunWith(
-      setupMcp("/project"),
-      mocks((p) => p.includes(".claude") || p === "/project/.mcp.json"),
-    );
-
-    const writes = result.effects.filter(
-      (e) => e._tag === "WriteFile",
-    ) as (Effect & { _tag: "WriteFile" })[];
-    expect(writes.length).toBeGreaterThan(0);
-
-    // At least one write should contain pragma MCP config
-    const mcpWrite = writes.find((w) => w.path.includes(".mcp.json"));
-    expect(mcpWrite).toBeDefined();
-    if (mcpWrite) {
-      const config = JSON.parse(mcpWrite.content);
-      expect(config.mcpServers?.pragma?.command).toBe("pragma");
-    }
-  });
-
-  it("force harness bypasses detection", () => {
-    const result = dryRunWith(
-      setupMcp("/project", "claude-code"),
-      mocks(() => false), // nothing exists, but force skips detection
-    );
-
-    const writes = result.effects.filter((e) => e._tag === "WriteFile");
-    expect(writes.length).toBeGreaterThan(0);
-
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    expect(logs.some((l) => l.message.includes("✓"))).toBe(true);
-  });
-
-  it("warns on unknown force harness", () => {
-    const result = dryRunWith(
-      setupMcp("/project", "nonexistent"),
-      mocks(() => false),
-    );
-
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    expect(logs.some((l) => l.message.includes("Unknown harness"))).toBe(true);
-
-    const writes = result.effects.filter((e) => e._tag === "WriteFile");
-    expect(writes).toHaveLength(0);
-  });
-
-  it("detects multiple harnesses", () => {
-    const result = dryRunWith(
-      setupMcp("/project"),
-      mocks(
-        (p) =>
-          p.includes(".claude") ||
-          p.includes(".mcp.json") ||
-          p.includes(".cursor"),
-      ),
-    );
-
-    const logs = result.effects.filter((e) => e._tag === "Log");
-    const detectedLog = logs.find((l) => l.message.includes("Detected"));
-    expect(detectedLog).toBeDefined();
-
-    // Multiple writes expected (one per confirmed harness)
-    const writes = result.effects.filter((e) => e._tag === "WriteFile");
-    expect(writes.length).toBeGreaterThanOrEqual(2);
-  });
-
-  it("includes prompt effects for each detected harness", () => {
-    const result = dryRunWith(
-      setupMcp("/project"),
-      mocks(
-        (p) =>
-          p.includes(".claude") ||
-          p.includes(".mcp.json") ||
-          p.includes(".cursor"),
-      ),
-    );
-
-    const prompts = result.effects.filter((e) => e._tag === "Prompt");
-    expect(prompts.length).toBeGreaterThanOrEqual(2);
-  });
-});