@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/setup/operations/setupGenerator.ts

@@ -0,0 +1,307 @@
+/**
+ * Synthesize `setup` (and each sub-verb) as a summon `GeneratorDefinition`, so
+ * they all flow through the SAME `execute` seam `create` uses — inheriting the
+ * Ink wizard, the recap/confirm gate, live progress, colours, and the shared
+ * cancel fixes (H1/H2/H3/M1) by construction. Replaces the old readline
+ * `promptStrategy` + `setupAll`.
+ *
+ * The shape mirrors `create`: detection runs FOR REAL up front (in each
+ * `detectX`), then a PURE `generate` composes only the effects for the SELECTED
+ * steps. `generate` must stay side-effect-free — `execute` and the wizard invoke
+ * it more than once (the confirm-gate preview + the build), so all real reads
+ * belong in detection, never in `generate`.
+ *
+ * This module carries NO static import of `@canonical/summon-core` VALUES or of
+ * React/Ink — it only `import type`s the generator shape and builds plain object
+ * literals over `@canonical/task`. It is itself reached only through the verb's
+ * lazy dynamic import, so the fast paths stay free of it.
+ */
+
+import type {
+  GeneratorDefinition,
+  PromptDefinition,
+} from "@canonical/summon-core";
+import { sequence_, type Task, when } from "@canonical/task";
+import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import { guardMissingBinary } from "../../shared/assertExecOk.js";
+import type { SetupMode, SetupResult } from "../types.js";
+import {
+  type CompletionsDetection,
+  composeCompletions,
+  detectCompletions,
+} from "./setupCompletions.js";
+import { composeLsp } from "./setupLsp.js";
+import {
+  composeMcp,
+  detectMcp,
+  type McpDetection,
+  mcpConfigured,
+} from "./setupMcp.js";
+import {
+  composeSkills,
+  detectSkills,
+  type SkillsDetection,
+  skillsEmptyError,
+  toSkillsResult,
+} from "./setupSkills.js";
+
+/** The run-all steps, in composition (and display) order. */
+type StepId = "completions" | "lsp" | "mcp" | "skills";
+
+/**
+ * A ready-to-run setup plan: the synthesized generator (fed to `inkPrompt` /
+ * `execute`) plus a mapper from the completed answers back onto setup's tagged
+ * {@link SetupResult} output union (its `--format json` shape is frozen).
+ */
+export interface SetupPlan {
+  readonly generator: GeneratorDefinition;
+  readonly toResult: (answers: Record<string, unknown>) => SetupResult;
+}
+
+/** The union of every step's detection, gathered up front for the run-all. */
+interface SetupDetection {
+  readonly completions: CompletionsDetection;
+  readonly mcp: McpDetection;
+  readonly skills: SkillsDetection;
+}
+
+/** Read `answers.steps` (the run-all multiselect) as a string array. */
+const stepsOf = (answers: Record<string, unknown>): string[] =>
+  Array.isArray(answers.steps) ? (answers.steps as string[]) : [];
+
+/** Read `answers.mcpHarnesses`, falling back to ALL detected ids. */
+const mcpSelection = (
+  d: McpDetection,
+  answers: Record<string, unknown>,
+): string[] =>
+  Array.isArray(answers.mcpHarnesses)
+    ? (answers.mcpHarnesses as string[])
+    : d.harnesses.map((h) => h.harness.id);
+
+/**
+ * The LSP-install step, guarded at its use site. An absent `bunx` (no Bun on
+ * PATH) REJECTS the exec with ENOENT, which would otherwise collapse to
+ * INTERNAL_ERROR ("please report this issue") at the CLI/MCP boundary;
+ * `guardMissingBinary` names it a UNSUPPORTED "`bunx` not found on PATH" with an
+ * actionable install recovery instead. Preview-transparent — a dry-run mocks the
+ * exec (no spawn) — and re-runnable (the guard is a `recover`, and `composeLsp`
+ * is combinator-built), so it survives `execute`'s double interpretation.
+ */
+const composeGuardedLsp = (rt: PragmaRuntime): Task<void> =>
+  guardMissingBinary(
+    "bunx",
+    {
+      message:
+        "Install Bun (https://bun.sh) to provide `bunx`, then run this again.",
+    },
+    composeLsp(rt.cwd),
+  );
+
+/** Build a generator's `meta` (no stamping — the version is just header text). */
+const metaFor = (
+  rt: PragmaRuntime,
+  title: string,
+): GeneratorDefinition["meta"] => ({
+  name: title,
+  displayName: title,
+  description: "Configure pragma for this project",
+  version: rt.version,
+});
+
+/** The MCP-harness multiselect follow-up (offered only when harnesses exist). */
+const mcpHarnessesPrompt = (
+  d: McpDetection,
+  when?: PromptDefinition["when"],
+): PromptDefinition => ({
+  name: "mcpHarnesses",
+  type: "multiselect",
+  message: "Configure MCP for which harnesses?",
+  when,
+  choices: d.harnesses.map((h) => ({
+    label: h.harness.name,
+    value: h.harness.id,
+  })),
+  default: d.harnesses.map((h) => h.harness.id),
+});
+
+// =============================================================================
+// Detection
+// =============================================================================
+
+/** Gather EVERY step's detection up front (real reads), for the run-all. */
+async function gatherDetection(rt: PragmaRuntime): Promise<SetupDetection> {
+  const [completions, mcp, skills] = await Promise.all([
+    detectCompletions(rt.cwd),
+    detectMcp(rt),
+    detectSkills(rt),
+  ]);
+  return { completions, mcp, skills };
+}
+
+/**
+ * The steps worth OFFERING, given detection — undetectable steps are omitted so
+ * the run-all degrades gracefully instead of throwing a mid-wizard
+ * EMPTY_RESULTS (skills with no skills, mcp with no harnesses, completions with
+ * no shell). LSP is always offered (its install is a self-contained exec).
+ */
+function availableSteps(
+  detected: SetupDetection,
+): { label: string; value: StepId }[] {
+  const choices: { label: string; value: StepId }[] = [];
+  if (detected.completions.shell) {
+    choices.push({
+      label: `Shell completions (${detected.completions.shell})`,
+      value: "completions",
+    });
+  }
+  choices.push({ label: "Terrazzo LSP extension", value: "lsp" });
+  if (detected.mcp.harnesses.length > 0) {
+    choices.push({
+      label: `MCP config (${detected.mcp.harnesses.length} harness(es))`,
+      value: "mcp",
+    });
+  }
+  if (detected.skills.available) {
+    choices.push({
+      label: `Link skills (${detected.skills.skillCount})`,
+      value: "skills",
+    });
+  }
+  return choices;
+}
+
+// =============================================================================
+// Plan builders
+// =============================================================================
+
+/** The run-all self-verb: a step multiselect + per-step composition. */
+function runAllPlan(rt: PragmaRuntime, detected: SetupDetection): SetupPlan {
+  const steps = availableSteps(detected);
+  const prompts: PromptDefinition[] = [
+    {
+      name: "steps",
+      type: "multiselect",
+      message: "Which steps would you like to run?",
+      choices: steps,
+      default: steps.map((c) => c.value), // --yes / non-TTY ⇒ every step
+    },
+  ];
+  if (detected.mcp.harnesses.length > 0) {
+    prompts.push(
+      mcpHarnessesPrompt(
+        detected.mcp,
+        (a) => stepsOf(a).includes("mcp"), // only when mcp is chosen
+      ),
+    );
+  }
+
+  // `generate` MUST be pure and re-runnable — `execute` interprets it twice (the
+  // confirm-gate preview + the build) — so it composes with `when`/`sequence_`
+  // (immutable) rather than a single-use `gen`, and does NO detection (all real
+  // reads already happened up front). Composing an unchosen step is harmless:
+  // `when(false, …)` discards the (side-effect-free) task it was handed.
+  const generator: GeneratorDefinition = {
+    meta: metaFor(rt, "pragma setup"),
+    prompts,
+    generate: (answers) => {
+      const chosen = stepsOf(answers);
+      return sequence_([
+        when(
+          chosen.includes("completions"),
+          composeCompletions(detected.completions),
+        ),
+        when(chosen.includes("lsp"), composeGuardedLsp(rt)),
+        when(
+          chosen.includes("mcp"),
+          composeMcp(detected.mcp, mcpSelection(detected.mcp, answers)),
+        ),
+        when(chosen.includes("skills"), composeSkills(detected.skills)),
+      ]);
+    },
+  };
+
+  return {
+    generator,
+    toResult: (answers) => ({ kind: "all", steps: stepsOf(answers) }),
+  };
+}
+
+/** A single-step generator (no run-all multiselect) for one sub-verb. */
+function singleStep(
+  rt: PragmaRuntime,
+  title: string,
+  prompts: PromptDefinition[],
+  generate: (answers: Record<string, unknown>) => Task<void>,
+): GeneratorDefinition {
+  return { meta: metaFor(rt, title), prompts, generate };
+}
+
+/**
+ * Build the plan for an entry point. Detection runs here (up front); the
+ * returned generator's `generate` is pure. The `skills` sub-verb throws
+ * EMPTY_RESULTS before returning a plan when nothing is discoverable (its direct
+ * contract), whereas the run-all simply omits an undetectable step.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param mode - The entry point (`all` or one sub-verb).
+ * @returns The generator + result mapper.
+ * @throws PragmaError EMPTY_RESULTS for a direct `setup skills` with no skills.
+ * @note Impure — performs each step's real detection.
+ */
+export async function buildSetupPlan(
+  rt: PragmaRuntime,
+  mode: SetupMode,
+): Promise<SetupPlan> {
+  switch (mode) {
+    case "all":
+      return runAllPlan(rt, await gatherDetection(rt));
+
+    case "completions": {
+      const d = await detectCompletions(rt.cwd);
+      return {
+        generator: singleStep(rt, "pragma setup completions", [], () =>
+          composeCompletions(d),
+        ),
+        toResult: () => ({
+          kind: "completions",
+          shell: d.shell,
+          path: d.path,
+          installed: d.shell !== null,
+        }),
+      };
+    }
+
+    case "lsp":
+      return {
+        generator: singleStep(rt, "pragma setup lsp", [], () =>
+          composeGuardedLsp(rt),
+        ),
+        toResult: () => ({ kind: "lsp" }),
+      };
+
+    case "mcp": {
+      const d = await detectMcp(rt);
+      const prompts = d.harnesses.length > 0 ? [mcpHarnessesPrompt(d)] : [];
+      return {
+        generator: singleStep(rt, "pragma setup mcp", prompts, (answers) =>
+          composeMcp(d, mcpSelection(d, answers)),
+        ),
+        toResult: (answers) => ({
+          kind: "mcp",
+          configured: mcpConfigured(d, mcpSelection(d, answers)),
+        }),
+      };
+    }
+
+    case "skills": {
+      const d = await detectSkills(rt);
+      if (!d.available) throw skillsEmptyError();
+      return {
+        generator: singleStep(rt, "pragma setup skills", [], () =>
+          composeSkills(d),
+        ),
+        toResult: () => ({ kind: "skills", result: toSkillsResult(d) }),
+      };
+    }
+  }
+}

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

@@ -0,0 +1,61 @@
+/**
+ * `setup lsp` — ensure the Terrazzo LSP VS Code extension is installed.
+ *
+ * There is nothing to detect (the installer is a single idempotent `exec`), so
+ * `detectLsp` is a trivial marker and `composeLsp` holds the sole mutation —
+ * mocked under `--dry-run`, run for real otherwise. A successful run reports it
+ * installed (up to date), not a fresh install.
+ */
+
+import {
+  type ExecResult,
+  exec,
+  flatMap,
+  info,
+  pure,
+  sequence_,
+  type Task,
+} from "@canonical/task";
+import { assertExecOk } from "../../shared/assertExecOk.js";
+
+/** LSP has no real detection — the install is one idempotent subprocess. */
+export interface LspDetection {
+  readonly available: true;
+}
+
+/**
+ * "Detect" the LSP step. Always available — kept for symmetry with the other
+ * steps' detect phase (so the run-all can gather every step uniformly).
+ */
+export function detectLsp(): LspDetection {
+  return { available: true };
+}
+
+/**
+ * Compose the LSP-install exec.
+ *
+ * Built from re-runnable combinators (NOT a single-use `gen`) because `execute`
+ * interprets the task twice (preview + perform). Under the dry-run preview the
+ * `exec` is MOCKED to `exitCode 0`, so `assertExecOk` passes there; a real run's
+ * nonzero exit still fails loudly.
+ *
+ * @param cwd - The directory to run the installer in.
+ * @returns A Task that execs the extension installer, failing loudly on nonzero.
+ */
+export function composeLsp(cwd: string): Task<void> {
+  return sequence_([
+    info("Ensuring the Terrazzo LSP VS Code extension is installed..."),
+    // The interpreter RESOLVES on a nonzero exit — a failed installer must fail
+    // loudly (surfacing its stderr), not report a false success.
+    flatMap(
+      exec("bunx", ["@canonical/terrazzo-lsp-extension"], cwd),
+      (result) => {
+        assertExecOk(
+          "bunx @canonical/terrazzo-lsp-extension",
+          result as ExecResult,
+        );
+        return pure(undefined);
+      },
+    ),
+  ]);
+}

package/src/capabilities/setup/operations/setupMcp.ts

@@ -0,0 +1,85 @@
+/**
+ * `setup mcp` — register the pragma MCP server in detected AI harnesses.
+ *
+ * Split into `detectMcp` (harness detection runs FOR REAL up front, via
+ * `runTask` over safe reads, so the wizard recap and a `--dry-run` describe
+ * writes against the TRUE harness set) and `composeMcp` (a pure, re-runnable
+ * write body driven by the harnesses the user SELECTED — the per-harness confirm
+ * is gone; selection now comes from the wizard's multiselect). The covenant
+ * sub-verb carries no force-flags, so harness selection is detection-only.
+ */
+
+import type { DetectedHarness } from "@canonical/harnesses";
+import { info, sequence_, type Task, warn } from "@canonical/task";
+import { MCP_SERVER_NAME } from "../../../constants.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+
+/** The `writeMcpConfig` Task-builder, captured from the dynamic harness import. */
+type WriteMcpConfig = typeof import("@canonical/harnesses").writeMcpConfig;
+
+/**
+ * The detected MCP state: the harnesses found, the project root the config is
+ * written against, and the (dynamically imported) config-writer the pure
+ * `composeMcp` needs synchronously.
+ */
+export interface McpDetection {
+  readonly harnesses: readonly DetectedHarness[];
+  readonly cwd: string;
+  readonly writeMcpConfig: WriteMcpConfig;
+}
+
+/**
+ * Detect the AI harnesses present in the project (real reads, up front).
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns The detected harnesses + the writer used to compose config writes.
+ * @note Impure — reads the filesystem via `detectHarnesses`.
+ */
+export async function detectMcp(rt: PragmaRuntime): Promise<McpDetection> {
+  const cwd = rt.cwd;
+  const [{ detectHarnesses, writeMcpConfig }, { runTask }] = await Promise.all([
+    import("@canonical/harnesses"),
+    import("@canonical/task/node"),
+  ]);
+  const harnesses = await runTask(detectHarnesses(cwd));
+  return { harnesses, cwd, writeMcpConfig };
+}
+
+/**
+ * Compose the per-harness config writes for the SELECTED harnesses (pure —
+ * re-runnable; builds ABSOLUTE config paths itself).
+ *
+ * @param d - The detection gathered up front.
+ * @param selectedIds - Harness ids the user chose (a subset of `d.harnesses`).
+ * @returns A Task that writes the pragma MCP config into each chosen harness.
+ */
+export function composeMcp(
+  d: McpDetection,
+  selectedIds: readonly string[],
+): Task<void> {
+  const chosen = d.harnesses.filter((h) => selectedIds.includes(h.harness.id));
+  if (chosen.length === 0) {
+    return warn("No AI harnesses selected — nothing to configure.");
+  }
+  const pragmaMcpConfig = { command: "pragma", args: ["mcp"], cwd: d.cwd };
+  // Re-runnable combinators (NOT a single-use `gen`): `execute` interprets the
+  // task twice (preview + perform).
+  const tasks: Task<unknown>[] = [];
+  for (const h of chosen) {
+    tasks.push(
+      d.writeMcpConfig(h.harness, d.cwd, MCP_SERVER_NAME, pragmaMcpConfig),
+    );
+    tasks.push(info(`✓ pragma MCP server added to ${h.configPath}`));
+  }
+  return sequence_(tasks);
+}
+
+/** The harness names configured for a given selection (for the result shape). */
+export function mcpConfigured(
+  d: McpDetection,
+  selectedIds: readonly string[],
+): string[] {
+  return d.harnesses
+    .filter((h) => selectedIds.includes(h.harness.id))
+    .map((h) => h.harness.name);
+}

package/src/capabilities/setup/operations/setupSkills.ts

@@ -0,0 +1,199 @@
+/**
+ * `setup skills` — symlink discovered skills into each harness skill directory
+ * and the cross-client `.agents/skills`.
+ *
+ * Split into `detectSkills` (skill discovery, harness detection, and the
+ * per-link create/skip/replace DECISION all run against REAL fs up front, so the
+ * wizard recap and a `--dry-run` plan reflect true state) and `composeSkills` (a
+ * pure, re-runnable body performing only the symlink/delete effects the dry-run
+ * interpreter mocks). Idempotent by construction.
+ */
+
+import { existsSync, readlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  deleteFile,
+  info,
+  mkdir,
+  sequence_,
+  symlink,
+  type Task,
+} from "@canonical/task";
+import { RECOVERY_CLI_PREFIX } from "../../../constants.js";
+import { PragmaError } from "../../../kernel/error/PragmaError.js";
+import { cliRecovery } from "../../../kernel/error/recovery.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import type { SetupSkillsResult, SymlinkAction } from "../types.js";
+
+/** Cross-client skill directory, shared across all harnesses. */
+const CROSS_CLIENT_DIR = ".agents/skills";
+
+/**
+ * The detected skill-linking plan: the target directories, the decided per-link
+ * actions, and the counts/warnings the result surface reports. `available` is
+ * false when no skills were discovered.
+ */
+export interface SkillsDetection {
+  readonly available: boolean;
+  readonly targets: readonly { readonly dir: string; readonly name: string }[];
+  readonly actions: readonly SymlinkAction[];
+  readonly skillCount: number;
+  readonly harnessCount: number;
+  readonly warnings: readonly string[];
+}
+
+/** The current target of a symlink, or `null` when absent / not a symlink. */
+function currentLink(linkPath: string): string | null {
+  if (!existsSync(linkPath)) return null;
+  try {
+    return readlinkSync(linkPath);
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Discover skills, detect harnesses, and decide each link action (real fs, up
+ * front). Returns `available: false` (empty plan) when no skills exist — the
+ * run-all omits the step; the direct sub-verb turns it into {@link skillsEmptyError}.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns The link plan.
+ * @note Impure — reads the filesystem (skills + harnesses + existing links).
+ */
+export async function detectSkills(
+  rt: PragmaRuntime,
+): Promise<SkillsDetection> {
+  const cwd = rt.cwd;
+  const [{ discoverSkills }, { detectHarnesses }, { runTask }] =
+    await Promise.all([
+      import("../../skill/discover.js"),
+      import("@canonical/harnesses"),
+      import("@canonical/task/node"),
+    ]);
+
+  const skills = discoverSkills(cwd);
+  if (skills.length === 0) {
+    return {
+      available: false,
+      targets: [],
+      actions: [],
+      skillCount: 0,
+      harnessCount: 0,
+      warnings: [],
+    };
+  }
+
+  const detected = await runTask(detectHarnesses(cwd));
+
+  // Target dirs (harness skill dirs + the cross-client dir), first-seen wins.
+  const seen = new Set<string>();
+  const targets: { dir: string; name: string }[] = [];
+  for (const d of detected) {
+    const dir = d.harness.skillsPath(cwd);
+    if (!seen.has(dir)) {
+      seen.add(dir);
+      targets.push({ dir, name: d.harness.name });
+    }
+  }
+  const crossDir = resolve(cwd, CROSS_CLIENT_DIR);
+  if (!seen.has(crossDir)) {
+    seen.add(crossDir);
+    targets.push({ dir: crossDir, name: CROSS_CLIENT_DIR });
+  }
+
+  // Decide each action against REAL fs (so the preview is accurate).
+  const actions: SymlinkAction[] = [];
+  for (const { dir, name } of targets) {
+    for (const skill of skills) {
+      const linkPath = resolve(dir, skill.folderName);
+      const current = currentLink(linkPath);
+      const action: SymlinkAction["action"] =
+        current === null
+          ? "created"
+          : current === skill.sourcePath
+            ? "skipped"
+            : "replaced";
+      actions.push({
+        skillName: skill.name,
+        target: skill.sourcePath,
+        linkPath,
+        action,
+        harnessName: name,
+      });
+    }
+  }
+
+  const warnings = actions
+    .filter((a) => a.action === "replaced")
+    .map(
+      (a) => `Replaced stale symlink for ${a.skillName} in ${a.harnessName}`,
+    );
+
+  return {
+    available: true,
+    targets,
+    actions,
+    skillCount: skills.length,
+    harnessCount: detected.length,
+    warnings,
+  };
+}
+
+/**
+ * Compose the (re)link effects from a detection (builds ABSOLUTE link paths
+ * itself).
+ *
+ * Built from re-runnable combinators (NOT a single-use `gen`) because `execute`
+ * interprets the task twice (preview + perform). `created` links carry an undo;
+ * a `replaced` link is delete-then-relink (idempotent); `skipped` is a no-op.
+ *
+ * @param d - The detection gathered up front.
+ * @returns A Task that mkdirs each target and creates/replaces each symlink.
+ */
+export function composeSkills(d: SkillsDetection): Task<void> {
+  if (!d.available) return sequence_([]);
+  const tasks: Task<unknown>[] = [];
+  for (const { dir } of d.targets) {
+    tasks.push(mkdir(dir, true));
+  }
+  for (const a of d.actions) {
+    if (a.action === "created") {
+      tasks.push(
+        symlink(a.target, a.linkPath, { undo: deleteFile(a.linkPath) }),
+      );
+    } else if (a.action === "replaced") {
+      tasks.push(deleteFile(a.linkPath));
+      tasks.push(symlink(a.target, a.linkPath));
+    }
+  }
+  tasks.push(
+    info(`Linked ${d.skillCount} skill(s) into ${d.targets.length} dir(s).`),
+  );
+  return sequence_(tasks);
+}
+
+/** Project a detection onto the {@link SetupSkillsResult} output shape. */
+export function toSkillsResult(d: SkillsDetection): SetupSkillsResult {
+  return {
+    actions: d.actions,
+    harnessCount: d.harnessCount,
+    skillCount: d.skillCount,
+    warnings: d.warnings,
+  };
+}
+
+/**
+ * The EMPTY_RESULTS error the DIRECT `setup skills` sub-verb raises when no
+ * skills are discoverable (the run-all instead omits the step). Recovery points
+ * at where skills COME FROM (U8): package skills install on `sources update`.
+ */
+export function skillsEmptyError(): PragmaError {
+  return PragmaError.emptyResults("skill", {
+    message: "No skills found to link.",
+    recovery: cliRecovery(
+      `${RECOVERY_CLI_PREFIX}sources update`,
+      "Add a design-system package that ships skills to your config, then run `pragma sources update` to install them.",
+    ),
+  });
+}

package/src/capabilities/setup/setup.render.ts

@@ -0,0 +1,49 @@
+/**
+ * Formatters for `pragma setup` and its sub-verbs — one shared formatter over
+ * the tagged {@link SetupResult} union (plain, llm, json).
+ */
+
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { SetupResult, SetupSkillsResult } from "./types.js";
+
+/** Summarize a skills result: created / skipped / replaced counts. */
+function skillsSummary(result: SetupSkillsResult): string {
+  const created = result.actions.filter((a) => a.action === "created").length;
+  const skipped = result.actions.filter((a) => a.action === "skipped").length;
+  const replaced = result.actions.filter((a) => a.action === "replaced").length;
+  return `${created} created, ${replaced} replaced, ${skipped} unchanged across ${result.harnessCount} harness(es)`;
+}
+
+/** Render a setup result to a single human line (shared by plain/llm). */
+function line(data: SetupResult): string {
+  switch (data.kind) {
+    case "completions":
+      return data.installed
+        ? `Installed ${data.shell} completions at ${data.path}.`
+        : "No shell detected — completions were not installed.";
+    case "lsp":
+      return "Terrazzo LSP extension is installed (up to date).";
+    case "mcp":
+      return data.configured.length > 0
+        ? `Configured MCP for: ${data.configured.join(", ")}.`
+        : "No harnesses configured.";
+    case "skills":
+      return `Skills: ${skillsSummary(data.result)}.`;
+    case "all":
+      return data.steps.length > 0
+        ? `Setup complete — ran: ${data.steps.join(", ")}.`
+        : "Setup complete — no steps selected.";
+  }
+}
+
+export const setupFormatters: Formatters<SetupResult> = {
+  plain(data) {
+    return line(data);
+  },
+  llm(data) {
+    return `- ${line(data)}`;
+  },
+  json(data) {
+    return JSON.stringify(data);
+  },
+};