@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/setup/setup.test.ts

@@ -0,0 +1,351 @@
+/**
+ * `pragma setup` + its sub-verbs — now synthesized as summon generators routed
+ * through the shared `execute` seam (accumulate → recap → execute-with-progress),
+ * exactly like `create`.
+ *
+ * Never spawns the real LSP installer (bunx) — every LSP path is exercised only
+ * under `--dry-run` / plan-first, which MOCK the exec — and never writes outside
+ * isolated HOME/cwd temps. Covers: completions (exact emitScripts output /
+ * preview-accurate dry-run / undo reversal / no-shell warn), the MCP recap gate
+ * (auto-confirm writes, decline writes nothing), skills (empty → EMPTY_RESULTS,
+ * symlink effect carries an undo), the run-all wizard previewing every detected
+ * step, the lazy-React guard (a `--yes` run mounts no Ink), the mixed-noun
+ * routing, and MCP plan-first with the sub-verbs absent from the catalog.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execute } from "@canonical/summon-core";
+import { dryRun, type Effect, type Task } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { emitScripts } from "../../kernel/completion/emitScripts.js";
+import { asPragmaError } from "../../kernel/error/fromTaskError.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { projectCli } from "../../testing/helpers/projectCli.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { capabilities } from "../index.js";
+import { buildSetupPlan } from "./operations/setupGenerator.js";
+import { composeSkills, detectSkills } from "./operations/setupSkills.js";
+import { setupModule } from "./setup.verb.js";
+import { completionScriptPath } from "./shell.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const YES = { dryRun: false, undo: false, yes: true };
+const DRY = { dryRun: true, undo: false, yes: false };
+const UNDO = { dryRun: false, undo: true, yes: false };
+
+const verbOf = (v: string): VerbSpec =>
+  setupModule.verbs.find((s) => (s.path[1] ?? s.path[0]) === v) as VerbSpec;
+const setupSelfVerb = verbOf("setup");
+const completionsVerb = verbOf("completions");
+
+const roots: string[] = [];
+const tmp = (prefix: string): string => {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  roots.push(dir);
+  return dir;
+};
+
+let prevHome: string | undefined;
+let prevShell: string | undefined;
+beforeEach(() => {
+  prevHome = process.env.HOME;
+  prevShell = process.env.SHELL;
+  process.env.HOME = tmp("pragma-setup-home-");
+  process.env.SHELL = "/usr/bin/zsh";
+});
+afterEach(() => {
+  process.env.HOME = prevHome;
+  process.env.SHELL = prevShell;
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+describe("setup completions", () => {
+  it("writes exactly emitScripts(capabilities)[shell]", async () => {
+    const path = completionScriptPath("zsh");
+    const outcome = await executeVerb(
+      completionsVerb,
+      {},
+      YES,
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(existsSync(path)).toBe(true);
+    expect(readFileSync(path, "utf-8")).toBe(emitScripts(capabilities).zsh);
+  });
+
+  it("bakes the completion config (minChars + per-family opt-out) into the emitted script", async () => {
+    // Proves the reconciled `detectCompletions(cwd)` reads `completion` config
+    // and threads {minChars, disabledFamilies} into `emitScripts` — a silent
+    // regression if the fold had dropped autocomplete's config-threading for
+    // setup's argument-free detect.
+    const cwd = tmp("pragma-setup-proj-");
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      "export default { completion: { minChars: 5, families: { block: false } } };\n",
+    );
+    const path = completionScriptPath("zsh");
+    const outcome = await executeVerb(
+      completionsVerb,
+      {},
+      YES,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    const written = readFileSync(path, "utf-8");
+    // The installed script is EXACTLY the config-baked emit (minChars 5, the
+    // `block` family scrubbed) — the config was threaded end to end.
+    expect(written).toBe(
+      emitScripts(capabilities, {
+        minChars: 5,
+        disabledFamilies: ["block"],
+      }).zsh,
+    );
+    // Both knobs actually moved the output: it differs from the default emit
+    // (minChars), and from the minChars-only emit (the family opt-out).
+    expect(written).not.toBe(emitScripts(capabilities).zsh);
+    expect(written).not.toBe(emitScripts(capabilities, { minChars: 5 }).zsh);
+  });
+
+  it("--dry-run previews the write against the detected shell, writing nothing", async () => {
+    const path = completionScriptPath("zsh");
+    const outcome = await executeVerb(
+      completionsVerb,
+      {},
+      DRY,
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+    );
+    expect(outcome.stdout).toContain("Write file");
+    expect(outcome.stdout).toContain(path);
+    // The confirm gate / answer prompts are never part of a plan.
+    expect(outcome.stdout).not.toContain("Prompt");
+    expect(existsSync(path)).toBe(false);
+  });
+
+  it("warns and writes nothing when no shell is detected", async () => {
+    process.env.SHELL = "";
+    const outcome = await executeVerb(
+      completionsVerb,
+      {},
+      YES,
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(existsSync(completionScriptPath("zsh"))).toBe(false);
+  });
+
+  it("--undo reverses the write", async () => {
+    const path = completionScriptPath("zsh");
+    const cwd = tmp("pragma-setup-proj-");
+    await executeVerb(completionsVerb, {}, YES, bootRuntime(FLAGS, cwd));
+    expect(existsSync(path)).toBe(true);
+    await executeVerb(completionsVerb, {}, UNDO, bootRuntime(FLAGS, cwd));
+    expect(existsSync(path)).toBe(false);
+  });
+});
+
+describe("setup mcp — recap gate", () => {
+  it("auto-confirms the detected harness under --yes (writes the pragma server)", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // makes Cursor detected
+    const configPath = join(cwd, ".cursor", "mcp.json");
+
+    const outcome = await executeVerb(
+      verbOf("mcp"),
+      {},
+      YES,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(existsSync(configPath)).toBe(true);
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    expect(config.mcpServers?.pragma?.command).toBe("pragma");
+  });
+
+  it("a declined recap gate writes nothing (clean GENERATOR_CANCELLED)", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    const configPath = join(cwd, ".cursor", "mcp.json");
+
+    const { generator } = await buildSetupPlan(bootRuntime(FLAGS, cwd), "mcp");
+    // A handler that declines EVERYTHING (incl. execute's "Proceed?" gate) must
+    // fail the run cleanly — the GENERATOR_CANCELLED code the boundary renders
+    // as a plain "Cancelled." — and write nothing.
+    const task = execute(generator, { prompt: async () => false, params: {} });
+    await expect(
+      runTask(task as Task<unknown>, { promptHandler: async () => false }),
+    ).rejects.toMatchObject({ code: "GENERATOR_CANCELLED" });
+    expect(existsSync(configPath)).toBe(false);
+  });
+});
+
+describe("setup skills", () => {
+  it("empty skills raise EMPTY_RESULTS on the direct sub-verb", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    await expect(
+      executeVerb(verbOf("skills"), {}, YES, bootRuntime(FLAGS, cwd)),
+    ).rejects.toMatchObject({ code: "EMPTY_RESULTS" });
+  });
+
+  it("detects a created action and composes a symlink carrying an undo", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const skillDir = join(cwd, ".pragma", "skills", "my-skill");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(skillDir, "SKILL.md"),
+      "---\nname: my-skill\ndescription: A test skill.\n---\n",
+    );
+
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd));
+    expect(detected.available).toBe(true);
+    expect(detected.skillCount).toBe(1);
+    expect(detected.actions.some((a) => a.action === "created")).toBe(true);
+
+    const { effects } = dryRun(composeSkills(detected));
+    const symlinkEffect = effects.find((e) => e._tag === "Symlink") as
+      | (Effect & { _tag: "Symlink"; undo?: unknown })
+      | undefined;
+    expect(symlinkEffect).toBeDefined();
+    expect(symlinkEffect?.undo).toBeDefined();
+    expect(existsSync(join(cwd, ".agents", "skills", "my-skill"))).toBe(false);
+  });
+});
+
+describe("setup lsp — missing-binary guard (bunx absent)", () => {
+  it("surfaces a NAMED UNSUPPORTED (not INTERNAL_ERROR) when bunx is off PATH", async () => {
+    // Drives the REAL composeLsp exec (YES — not a dry-run mock) with `bunx`
+    // removed from PATH, so the spawn REJECTS with ENOENT. The reconciled guard
+    // at composeLsp's use site names it; without the guard the raw reject
+    // collapses to INTERNAL_ERROR ("please report this issue") at the boundary.
+    const prevPath = process.env.PATH;
+    process.env.PATH = tmp("pragma-empty-path-"); // empty dir ⇒ bunx unresolvable
+    let thrown: unknown;
+    try {
+      await executeVerb(
+        verbOf("lsp"),
+        {},
+        YES,
+        bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      );
+    } catch (error) {
+      thrown = error;
+    } finally {
+      process.env.PATH = prevPath;
+    }
+    expect(thrown).toBeDefined();
+    const err = asPragmaError(thrown);
+    expect(err.code).toBe("UNSUPPORTED");
+    expect(err.code).not.toBe("INTERNAL_ERROR");
+    expect(err.message).toContain("bunx");
+    expect(err.message).toMatch(/not found on your PATH/i);
+    // The recovery is the actionable install hint, not "report this issue".
+    expect(err.recovery?.message ?? "").not.toMatch(/report this issue/i);
+  });
+});
+
+describe("setup (run-all wizard)", () => {
+  it("--dry-run previews every DETECTED step (completions + lsp + mcp), writing nothing", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // harness detected
+    const outcome = await executeVerb(
+      setupSelfVerb,
+      {},
+      DRY,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    const plan = outcome.stdout ?? "";
+    expect(plan).toContain(completionScriptPath("zsh")); // completions step
+    expect(plan).toContain("terrazzo-lsp-extension"); // lsp step (exec, mocked)
+    expect(plan).toContain("mcp.json"); // mcp step
+    expect(plan).not.toContain("Prompt"); // recap gate / multiselects filtered
+    // Nothing is written by a preview.
+    expect(existsSync(completionScriptPath("zsh"))).toBe(false);
+    expect(existsSync(join(cwd, ".cursor", "mcp.json"))).toBe(false);
+  });
+
+  it("omits skills gracefully when none are discovered (no mid-wizard EMPTY_RESULTS)", async () => {
+    // A run-all in a project with no skills must NOT throw — it just doesn't
+    // offer the skills step. Reaching a clean plan proves the graceful degrade.
+    const outcome = await executeVerb(
+      setupSelfVerb,
+      {},
+      DRY,
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("terrazzo-lsp-extension"); // lsp still there
+  });
+});
+
+describe("lazy-React discipline (PROTECTED)", () => {
+  it("running a --yes setup never loads React or Ink", async () => {
+    // A real run through the seam (autoPrompt, no wizard) must not mount Ink.
+    await executeVerb(
+      completionsVerb,
+      {},
+      YES,
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+    );
+    const isReactPkg = (k: string) =>
+      /[\\/](react|react-dom|ink|ink-select-input|ink-text-input|ink-spinner)@\d/.test(
+        k,
+      ) ||
+      /[\\/]node_modules[\\/](react|react-dom|ink|ink-select-input|ink-text-input|ink-spinner)[\\/]/.test(
+        k,
+      );
+    const loaded = Object.keys(require.cache ?? {});
+    expect(loaded.filter(isReactPkg)).toEqual([]);
+  });
+});
+
+describe("setup — mixed-noun wiring & MCP surface", () => {
+  it("registers a single `setup` command with an action and four sub-verbs", () => {
+    const program = projectCli([setupModule]);
+    const setups = program.commands.filter((c) => c.name() === "setup");
+    expect(setups).toHaveLength(1);
+    const setup = setups[0];
+    // Self-verb mutation flags land on the parent.
+    expect(setup?.options.map((o) => o.long)).toEqual(
+      expect.arrayContaining(["--dry-run", "--undo", "--yes"]),
+    );
+    // The four CLI-only sub-verbs hang under it.
+    expect(setup?.commands.map((c) => c.name()).sort()).toEqual([
+      "completions",
+      "lsp",
+      "mcp",
+      "skills",
+    ]);
+  });
+
+  it("exposes only the `setup` tool over MCP; plan-first without confirm", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const mcp = await projectMcp([setupModule], cwd);
+    const tools = (await mcp.listTools()).map((t) => t.name);
+    expect(tools).toEqual(["setup"]); // sub-verbs are mcp:false
+
+    const plan = await mcp.callTool("setup"); // no confirm → plan-first
+    await mcp.cleanup();
+    expect(plan.ok).toBe(true);
+    expect(plan.meta).toMatchObject({ planOnly: true, confirmRequired: true });
+    expect(Array.isArray((plan.data as { plan: unknown }).plan)).toBe(true);
+  });
+});

package/src/capabilities/setup/setup.verb.ts

@@ -0,0 +1,209 @@
+/**
+ * The `setup` verbs — the run-all self-verb plus the four CLI-only sub-verbs
+ * (`mcp`/`completions`/`skills`/`lsp`).
+ *
+ * `setup` is the ONE covenant noun that is BOTH directly runnable and has
+ * sub-verbs (see the buildProgram mixed-noun change). All five are storeless,
+ * interactive mutations. The sub-verbs are `mcp: false` (the covenant marks
+ * them so — `buildServer` skips them, `buildProgram` still registers them); only
+ * the self-verb `setup` is an MCP tool. `destructive: false` (D4) keeps MCP from
+ * advertising the `setup` tool as destructive.
+ *
+ * ALL FIVE now flow through the SAME summon `execute` seam `create` uses: each
+ * `run` synthesizes a `GeneratorDefinition` (detection up front, a pure
+ * `generate`), picks the Ink wizard / auto / MCP strategy off `rt.interaction`,
+ * and returns `execute` — so setup inherits the recap, live progress, colours,
+ * and the shared cancel fixes. summon-core + the generator ops stay behind a
+ * LAZY dynamic import (mirroring `create`'s `loadCreateRuntime`), so building the
+ * command tree / `--help` / `__complete` — and `setup --yes` — load no
+ * React/Ink. `params: []` on every verb keeps the command surface frozen.
+ */
+
+import type { GeneratorResult } from "@canonical/summon-core";
+import { $, gen, type Task } from "@canonical/task";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import { setupFormatters } from "./setup.render.js";
+import type { SetupMode, SetupResult } from "./types.js";
+
+/** The exposed-to-MCP capability the run-all self-verb declares. */
+const SELF_CAPABILITY = {
+  needsStore: false,
+  mutates: true,
+  interactive: true,
+  destructive: false,
+  mcp: {
+    expose: true as const,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: false,
+    },
+  },
+};
+
+/** The CLI-only capability every sub-verb declares (not an MCP tool). */
+const SUB_CAPABILITY = {
+  needsStore: false,
+  mutates: true,
+  interactive: true,
+  destructive: false,
+  mcp: {
+    expose: false as const,
+    reason: "CLI-only environment installer",
+  },
+};
+
+/**
+ * The one summon↔pragma seam per setup invocation: lazily load summon-core + the
+ * generator ops, build the plan (detection up front), pick the prompt strategy
+ * off `rt.interaction`, wire `rt.exec`, and return `execute` mapped back onto
+ * {@link SetupResult}.
+ *
+ * NOTE: `rt.exec` carries NO per-call `cwd`. Unlike `create` (whose generator
+ * emits RELATIVE paths jailed to `rt.cwd`), setup's ops build ABSOLUTE effect
+ * paths themselves ($HOME/…, resolve(cwd,…)); the interpreter leaves absolute
+ * paths unchanged, so no per-call write root is threaded. No stamping either —
+ * setup writes symlinks / config / scripts, not generated source.
+ *
+ * @param mode - Which entry point (`all` or one sub-verb).
+ * @param rt - The per-invocation runtime (mutated: `rt.exec` is set).
+ * @returns The `Task<SetupResult>` the dispatcher/MCP handler interprets.
+ * @note Impure — runs each step's real detection; may throw EMPTY_RESULTS
+ *   (direct `setup skills` with no skills) before returning a Task.
+ */
+async function runSetup(
+  mode: SetupMode,
+  rt: PragmaRuntime,
+): Promise<Task<SetupResult>> {
+  // Lazy dynamic imports (R1 lazy-React discipline): summon-core's barrel is
+  // React-free, and the non-TTY branch picks autoPrompt/mcpPrompt (never mounts
+  // Ink), so `setup --yes` loads no React — the guard test enforces this.
+  const [summon, ops] = await Promise.all([
+    import("@canonical/summon-core"),
+    import("./operations/setupGenerator.js"),
+  ]);
+
+  const { generator, toResult } = await ops.buildSetupPlan(rt, mode);
+
+  const { isTTY, transport, yes, signal, abort } = rt.interaction ?? {
+    isTTY: false,
+    transport: "cli" as const,
+    yes: true,
+  };
+
+  // TTY without --yes → the Ink wizard (recap + live progress). Its callbacks
+  // ride rt.exec; `onCancel` threads the run's abort in so an in-Ink Ctrl-C
+  // during execution actually stops the writes (H2). No stamping (A5).
+  let task: Task<GeneratorResult>;
+  if (isTTY && !yes) {
+    const session = summon.inkPrompt(generator, { signal, onCancel: abort });
+    rt.exec = {
+      promptHandler: session.promptHandler,
+      onEffectStart: session.onEffectStart,
+      onEffectComplete: session.onEffectComplete,
+      onLog: session.onLog,
+      dispose: session.dispose,
+      signal,
+    };
+    task = summon.execute(generator, {
+      prompt: session.promptHandler,
+      params: {},
+      signal,
+    });
+  } else {
+    // Non-interactive: MCP → params-or-error; CLI/--yes/CI → defaults.
+    const prompt =
+      transport === "mcp" ? summon.mcpPrompt({}) : summon.autoPrompt({});
+    rt.exec = {
+      promptHandler: prompt,
+      onLog: (_level, message) => process.stderr.write(`${message}\n`),
+      signal,
+    };
+    task = summon.execute(generator, { prompt, params: {}, signal });
+  }
+
+  // execute yields a GeneratorResult; map it back onto setup's tagged result
+  // union (its --format json shape is frozen). The completion view is driven by
+  // controller phase, not this value, so mapping after execute is invisible to
+  // the wizard.
+  return gen(function* () {
+    const result = yield* $(task);
+    return toResult(result.answers);
+  });
+}
+
+/** Build a setup verb bound to its {@link SetupMode}. */
+function setupVerb(
+  path: VerbSpec<Record<string, unknown>, SetupResult>["path"],
+  summary: string,
+  mode: SetupMode,
+  capability: typeof SELF_CAPABILITY | typeof SUB_CAPABILITY,
+  extras: Partial<VerbSpec<Record<string, unknown>, SetupResult>> = {},
+): VerbSpec<Record<string, unknown>, SetupResult> {
+  return {
+    path,
+    summary,
+    params: [],
+    output: { formatters: setupFormatters },
+    capability,
+    ...extras,
+    run: (_params, rt) => runSetup(mode, rt) as unknown as Task<SetupResult>,
+  };
+}
+
+const setupAllVerb = setupVerb(
+  ["setup"],
+  "Configure MCP, completions, skills, and the LSP for this project.",
+  "all",
+  SELF_CAPABILITY,
+  {
+    doc: "Runs the shell-completions, LSP, MCP, and skills installers as a single wizard: pick the steps, review the recap, then apply.",
+    examples: [
+      { cmd: "pragma setup" },
+      { cmd: "pragma setup --dry-run", note: "preview every step's effects" },
+      { cmd: "pragma setup mcp", note: "just the MCP server registration" },
+    ],
+  },
+);
+
+const mcpVerb = setupVerb(
+  ["setup", "mcp"],
+  "Register the pragma MCP server in detected AI harnesses.",
+  "mcp",
+  SUB_CAPABILITY,
+);
+
+const completionsVerb = setupVerb(
+  ["setup", "completions"],
+  "Install the shell-completion script for your shell.",
+  "completions",
+  SUB_CAPABILITY,
+);
+
+const skillsVerb = setupVerb(
+  ["setup", "skills"],
+  "Symlink discovered skills into each AI harness.",
+  "skills",
+  SUB_CAPABILITY,
+);
+
+const lspVerb = setupVerb(
+  ["setup", "lsp"],
+  "Ensure the Terrazzo LSP VS Code extension is installed.",
+  "lsp",
+  SUB_CAPABILITY,
+);
+
+/** The `setup` capability module (run-all self-verb + four CLI-only sub-verbs). */
+export const setupModule: CapabilityModule = {
+  name: "setup",
+  verbs: [
+    asVerb(setupAllVerb),
+    asVerb(mcpVerb),
+    asVerb(completionsVerb),
+    asVerb(skillsVerb),
+    asVerb(lspVerb),
+  ],
+};

package/src/capabilities/setup/shell.ts

@@ -0,0 +1,85 @@
+/**
+ * Shell detection + completion-script install paths (ported from the old
+ * shell's `setup/helpers/detectShell` + `completionScripts` path helpers).
+ *
+ * The covenant `setup completions` sub-verb carries NO flags, so shell selection
+ * is detection-only (the old `--zsh`/`--bash`/`--fish` force-flags are dropped).
+ * `$HOME` is read at call time so tests can isolate it.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** The shells `setup completions` can install for. */
+export type ShellId = "zsh" | "bash" | "fish";
+
+const SHELL_MAP: Record<string, ShellId> = {
+  zsh: "zsh",
+  bash: "bash",
+  fish: "fish",
+};
+
+/**
+ * Detect the user's shell from `$SHELL`.
+ *
+ * @returns The detected shell, or `null` when `$SHELL` is unset/unrecognized.
+ * @note Impure — reads `process.env.SHELL`.
+ */
+export function detectShell(): ShellId | null {
+  const shell = process.env.SHELL ?? "";
+  const basename = shell.split("/").pop() ?? "";
+  return SHELL_MAP[basename] ?? null;
+}
+
+/**
+ * The standard install path for a shell's completion script.
+ *
+ * @param shell - The target shell.
+ * @returns The absolute path the completion script is written to.
+ * @note Impure — reads the home directory.
+ */
+export function completionScriptPath(shell: ShellId): string {
+  const home = homedir();
+  switch (shell) {
+    case "zsh":
+      return join(home, ".zfunc", "_pragma");
+    case "bash":
+      return join(
+        home,
+        ".local",
+        "share",
+        "bash-completion",
+        "completions",
+        "pragma",
+      );
+    case "fish":
+      return join(home, ".config", "fish", "completions", "pragma.fish");
+  }
+}
+
+/**
+ * The post-install activation hint for a shell.
+ *
+ * bash and fish install into directories their completion systems auto-load, so
+ * the only step left is a fresh shell. zsh's `~/.zfunc` is NOT auto-loaded: the
+ * script never loads unless `~/.zfunc` is on `$fpath` BEFORE `compinit` runs —
+ * the single trap every zsh user hits, so we spell out the exact `.zshrc` lines.
+ *
+ * @param shell - The shell the script was installed for.
+ * @returns A one-or-more-line activation instruction.
+ */
+export function activationHint(shell: ShellId): string {
+  switch (shell) {
+    case "zsh":
+      return (
+        "To activate, ensure ~/.zfunc is on your fpath BEFORE compinit. Add to ~/.zshrc:\n" +
+        "    fpath=(~/.zfunc $fpath)\n" +
+        "    autoload -Uz compinit && compinit\n" +
+        "Then restart your shell (or run `exec zsh`)."
+      );
+    case "bash":
+      return "To activate, restart your shell (bash-completion auto-loads the script).";
+    case "fish":
+      return "To activate, restart your shell (fish auto-loads the script).";
+  }
+}

package/src/capabilities/setup/types.ts

@@ -0,0 +1,42 @@
+/**
+ * Data shapes for `pragma setup` and its sub-verbs.
+ */
+
+import type { ShellId } from "./shell.js";
+
+/**
+ * Which setup entry point is running: the run-all self-verb or one sub-verb.
+ * Lives here (a leaf type module) so `setup.verb.ts` can name it WITHOUT a
+ * static import of the generator ops — keeping them dynamic-only (lazy-React).
+ */
+export type SetupMode = "all" | "completions" | "lsp" | "mcp" | "skills";
+
+/** One symlink create/skip/replace action performed during skill setup. */
+export interface SymlinkAction {
+  readonly skillName: string;
+  readonly target: string;
+  readonly linkPath: string;
+  readonly action: "created" | "skipped" | "replaced";
+  readonly harnessName: string;
+}
+
+/** Aggregate result of `pragma setup skills`. */
+export interface SetupSkillsResult {
+  readonly actions: readonly SymlinkAction[];
+  readonly harnessCount: number;
+  readonly skillCount: number;
+  readonly warnings: readonly string[];
+}
+
+/** The result of one setup verb, tagged by which verb produced it. */
+export type SetupResult =
+  | {
+      readonly kind: "completions";
+      readonly shell: ShellId | null;
+      readonly path: string | null;
+      readonly installed: boolean;
+    }
+  | { readonly kind: "lsp" }
+  | { readonly kind: "mcp"; readonly configured: readonly string[] }
+  | { readonly kind: "skills"; readonly result: SetupSkillsResult }
+  | { readonly kind: "all"; readonly steps: readonly string[] };