@canonical/pragma-cli 0.34.0 → 0.36.0

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

@@ -1,21 +1,19 @@
 /**
- * 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`.
+ * Synthesize a setup invocation as a summon `GeneratorDefinition` driven by the
+ * TARGET TABLE, so the run-all and every sub-verb flow through the same
+ * `execute` seam `create` uses — inheriting the Ink wizard, the recap/confirm
+ * gate, live progress, colours, and the shared cancel fixes by construction.
  *
- * 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`.
+ * The shape mirrors `create`: detection runs FOR REAL up front (once per
+ * target/scope, in `detectTargets`), then a PURE `generate` composes only the
+ * effects for the SELECTED rows. `generate` must stay re-interpretable —
+ * `execute` invokes it more than once (the confirm-gate preview and the build) —
+ * so it is composed from combinators and does no reads of its own.
  *
- * The `--scope` selection is threaded through detection AND step-offering so
- * `listAvailableSteps` only offers steps whose band the scope runs, and the MCP
- * step targets exactly the deduped files for that scope. Per-file narrowing is
- * opt-in (Item 6): the "all" default never springs a per-file question — it
- * configures every deduped file.
+ * The wizard is the PLAN'S EDITOR, not a parallel path: its choices are the plan
+ * rows, and what it edits is each row's `selected` flag. There is exactly one
+ * list of things this command can do, and the preview, the wizard, the progress
+ * lines and the recap are four views of it.
  *
  * 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
@@ -27,97 +25,199 @@ import type {
   GeneratorDefinition,
   PromptDefinition,
 } from "@canonical/summon-core";
-import { sequence_, type Task, when } from "@canonical/task";
-import { BIN_NAME } from "../../../constants.js";
-import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
-import { guardMissingBinary } from "../../shared/assertExecOk.js";
-import type {
-  LspState,
-  ScopeSelection,
-  SetupMode,
-  SetupResult,
-} from "../types.js";
 import {
-  type CompletionsDetection,
-  composeCompletions,
-  detectCompletions,
-} from "./setupCompletions.js";
-import { composeLsp, detectLsp, type LspDetection } from "./setupLsp.js";
+  flatMap,
+  pure,
+  recover,
+  sequence_,
+  type Task,
+  type TaskError,
+  warn,
+} from "@canonical/task";
+import { BIN_NAME } from "../../../constants.js";
+import { PragmaError } from "../../../kernel/error/index.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
 import {
-  composeMcp,
-  detectMcp,
-  type McpDetection,
-  mcpConfigured,
-  mcpGroupState,
-  mcpTargets,
-  selectedGroups,
-} from "./setupMcp.js";
+  buildPlan,
+  type DetectedRow,
+  detectionFailure,
+  detectTargets,
+  draftFor,
+  resolveRoots,
+} from "../buildPlan.js";
 import {
-  composeSkills,
-  detectSkills,
-  type SkillsDetection,
-  skillsEmptyError,
-  toSkillsResult,
-} from "./setupSkills.js";
+  isActionable,
+  type PlanChildRow,
+  type PlanOutcome,
+  type PlanRow,
+  type SetupPlan,
+  TARGET_IDS,
+  type TargetId,
+  withRows,
+} from "../plan.js";
+import type { Scope, ScopeSelection, SetupMode } from "../types.js";
+
+/** The answer key the run-all's row multiselect writes. */
+const ROWS_ANSWER = "targets";
+
+/** The answer key the opt-in per-file MCP narrowing writes. */
+const MCP_FILES_ANSWER = "mcpTargets";
+
+/** The answer key the opt-in per-editor LSP narrowing writes. */
+const LSP_EDITORS_ANSWER = "lspEditors";
+
+/** Which answer key carries a target's per-child selection, if it has one. */
+const CHILD_ANSWER: Partial<Record<TargetId, string>> = {
+  mcp: MCP_FILES_ANSWER,
+  lsp: LSP_EDITORS_ANSWER,
+};
 
-/** The run-all steps, in composition (and display) order. */
-type StepId = "completions" | "lsp" | "mcp" | "skills";
+/** A row's identity in an answer bag: scope-qualified, so `both` stays unambiguous. */
+const rowKey = (scope: Scope, target: TargetId): string => `${scope}:${target}`;
 
 /**
- * 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).
+ * One live row-progress event: a plan row starting, finishing, or failing,
+ * reported WHILE the composed task is being interpreted. `label` is the row's
+ * progress sentence — the same `target  detail — note` shape
+ * `renderProgressLine` prints — so the listener (the Ink wizard's step view)
+ * shows the run in the plan's own vocabulary, not the effect transcript's.
+ *
+ * Structurally identical to summon-core's `StepReport` ON PURPOSE: the wizard
+ * branch forwards these events verbatim, and this module must not import
+ * summon-core values (it stays behind the verb's lazy import).
  */
-export interface SetupPlan {
-  readonly generator: GeneratorDefinition;
-  readonly toResult: (answers: Record<string, unknown>) => SetupResult;
+export interface RowEvent {
+  /** The row's stable identity — `scope:target`. */
+  readonly key: string;
+  readonly label: string;
+  readonly status: "start" | "done" | "failed";
 }
 
-/** The union of every step's detection, gathered up front for the run-all. */
-interface SetupDetection {
-  readonly completions: CompletionsDetection;
-  readonly lsp: LspDetection;
-  readonly mcp: McpDetection;
-  readonly skills: SkillsDetection;
+/**
+ * A ready-to-run setup invocation: the plan as detected, the synthesized
+ * generator, and a projection from the completed answers back onto the plan with
+ * outcomes filled in — the recap, and the `--format json` body.
+ */
+export interface SetupRun {
+  readonly plan: SetupPlan;
+  readonly generator: GeneratorDefinition;
+  /** The plan with the wizard's selection and the run's outcomes applied. */
+  applied(answers: Record<string, unknown>): SetupPlan;
+  /**
+   * Register THE live row listener (the Ink wizard's step adapter). The
+   * composed rows emit through it while they are interpreted — which means
+   * EVERY interpretation fires it, the confirm gate's honest preview included;
+   * the receiving session drops reports outside its executing phase, exactly
+   * as the {@link OutcomeSink} relies on last-drive-wins for its records. No
+   * listener registered (a `--yes` run, `--dry-run`, MCP) costs nothing.
+   */
+  setRowListener(listener: (event: RowEvent) => void): void;
 }
 
-/** Read `answers.steps` (the run-all multiselect) as a string array. */
-const readSteps = (answers: Record<string, unknown>): string[] =>
-  Array.isArray(answers.steps) ? (answers.steps as string[]) : [];
+/**
+ * Where a failed row's error lands during interpretation.
+ *
+ * Per-row failure isolation needs somewhere to put "row X failed with Y", and
+ * `execute` yields only the generator's answers and effects — the value of the
+ * composed task is discarded. So the recover handlers record here, and the head
+ * of the sequence CLEARS it: `generate` is invoked fresh per interpretation, so
+ * the clear runs first on every drive and the last drive (the real one, which
+ * follows `execute`'s mocked preview) is the one whose records survive. The
+ * composition itself stays pure and re-interpretable — nothing is captured in
+ * the task, only written while it runs.
+ */
+class OutcomeSink {
+  private readonly errors = new Map<string, TaskError>();
 
-/** Read `answers.mcpTargets` (selected file paths), falling back to ALL files. */
-const resolveMcpPaths = (
-  d: McpDetection,
-  answers: Record<string, unknown>,
-): string[] =>
-  Array.isArray(answers.mcpTargets)
-    ? (answers.mcpTargets as string[])
-    : d.groups.map((g) => g.path);
-
-/** The groups the user chose (or all, under the "all" default). */
-const selectChosenGroups = (
-  d: McpDetection,
-  answers: Record<string, unknown>,
-) => selectedGroups(d, resolveMcpPaths(d, answers));
+  /** Forget every recorded failure — run at the head of each interpretation. */
+  clear(): void {
+    this.errors.clear();
+  }
+
+  record(key: string, error: TaskError): void {
+    this.errors.set(key, error);
+  }
+
+  get(key: string): TaskError | undefined {
+    return this.errors.get(key);
+  }
+
+  get failureCount(): number {
+    return this.errors.size;
+  }
+}
+
+/** The {@link PragmaError} a row failure carries, or a wrapper around it. */
+const rowPragmaError = (error: TaskError): PragmaError =>
+  error.cause instanceof PragmaError
+    ? error.cause
+    : new PragmaError({ code: "UNSUPPORTED", message: error.message });
 
 /**
- * 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.
+ * Run the chosen rows with per-row failure isolation. The rows are independent
+ * installers, so one unsatisfiable prerequisite must not consume the others: a
+ * sequenced composition let a failing editor sideload abort the run before MCP
+ * or skills ever executed, so on every machine without a usable editor CLI the
+ * single advertised onboarding command configured nothing that mattered.
+ *
+ * Each row runs under a `recover` frame: the failure is reported inline (a
+ * `warn` right where it happened), recorded on the sink, and the remaining rows
+ * still run. The aggregate outcome is decided afterwards by the caller reading
+ * the sink — a run whose every failure is recorded does NOT rethrow, because the
+ * recap is the report and the exit code comes from the plan's own rule.
+ *
+ * Only failures travelling the task FAILURE CHANNEL are isolable — a synchronous
+ * throw bypasses the trampoline's recovery frames — which is why the row bodies
+ * raise via `checkExecOk`/`failPragma`, never a bare throw. Interruption bypasses
+ * recovery by interpreter invariant, so Ctrl-C still stops the whole run.
+ *
+ * Each row is also BRACKETED with {@link RowEvent}s — `start` as its body is
+ * entered, `done`/`failed` as it settles — emitted from the continuations,
+ * which run at interpretation time. Like the sink writes beside them, the
+ * emits capture nothing IN the task: the composition stays pure and
+ * re-interpretable, and each drive simply narrates itself as it runs.
  */
-const composeGuardedLsp = (rt: PragmaRuntime, state: LspState): Task<void> =>
-  guardMissingBinary(
-    "bunx",
-    {
-      message:
-        "Install Bun (https://bun.sh) to provide `bunx`, then run this again.",
-    },
-    composeLsp(rt.cwd, state),
-  );
+const runRowsIsolated = (
+  sink: OutcomeSink,
+  rows: readonly {
+    key: string;
+    label: string;
+    doneLabel: string;
+    task: Task<void>;
+  }[],
+  emit: (event: RowEvent) => void,
+): Task<void> =>
+  flatMap(pure(undefined), (): Task<void> => {
+    sink.clear();
+    return sequence_(
+      rows.map(({ key, label, doneLabel, task }) =>
+        recover(
+          flatMap(pure(undefined), () => {
+            emit({ key, label, status: "start" });
+            return flatMap(task, () => {
+              emit({ key, label: doneLabel, status: "done" });
+              return pure(undefined);
+            });
+          }),
+          (error) =>
+            flatMap(
+              warn(
+                `The ${key.split(":")[1]} step did not complete — continuing with the remaining targets.`,
+              ),
+              () => {
+                sink.record(key, error);
+                emit({
+                  key,
+                  label: `${label} — ${rowPragmaError(error).message}`,
+                  status: "failed",
+                });
+                return pure(undefined);
+              },
+            ),
+        ),
+      ),
+    );
+  });
 
 /** Build a generator's `meta` (no stamping — the version is just header text). */
 const buildMeta = (
@@ -126,285 +226,329 @@ const buildMeta = (
 ): GeneratorDefinition["meta"] => ({
   name: title,
   displayName: title,
-  description: `Configure ${BIN_NAME} for this project`,
+  description: `Configure ${BIN_NAME} on this machine`,
   version: rt.version,
 });
 
-/** The opt-in "customize which files" gate (Item 6) — defaults to false. */
-const buildCustomizePrompt = (
-  when?: PromptDefinition["when"],
-): PromptDefinition => ({
-  name: "customize",
-  type: "confirm",
-  message: `Customize which files ${BIN_NAME} configures?`,
-  default: false,
-  when,
-});
+/** Read a multiselect answer as a string array. */
+const readList = (
+  answers: Record<string, unknown>,
+  key: string,
+): string[] | undefined =>
+  Array.isArray(answers[key]) ? (answers[key] as string[]) : undefined;
 
-/** The suffix a group's prior state adds to its multiselect label. */
-const mcpStateSuffix = (d: McpDetection, path: string): string => {
-  switch (mcpGroupState(d, path)) {
-    case "configured":
-      return " — already configured";
-    case "drifted":
-      return " — needs update";
-    default:
-      return "";
-  }
+/**
+ * The wizard's row multiselect — its choices ARE the plan rows. Actionable rows
+ * are pre-selected; an already-current row is offered DE-selected, so a re-run
+ * never proposes to rewrite what is already correct. A skip row is not a choice
+ * at all (summon's choice shape has no disabled state) but stays a visible row
+ * in the plan and the recap, carrying its reason.
+ */
+const buildRowsPrompt = (plan: SetupPlan): PromptDefinition => {
+  const choices = plan.rows
+    .filter((row) => row.action !== "skip")
+    .map((row) => ({
+      label: `${row.target} — ${row.detail}${row.action === "none" ? " (already configured)" : ""}`,
+      value: rowKey(row.scope, row.target),
+    }));
+  return {
+    name: ROWS_ANSWER,
+    type: "multiselect",
+    message: "Which targets would you like to configure?",
+    choices,
+    default: plan.rows
+      .filter((row) => row.selected)
+      .map((row) => rowKey(row.scope, row.target)),
+  };
 };
 
 /**
- * The per-file MCP multiselect — one row per deduped {@link TargetGroup} file.
- * A row's label carries its prior state, and an already-`configured` file is
- * DEFAULT-DESELECTED (so a re-run does not re-offer to rewrite what is already
- * current); `absent`/`drifted` files stay selected by default.
+ * The per-file MCP multiselect — one row per deduplicated config file, across
+ * every scope the run covers. An already-current file is DEFAULT-DESELECTED; a
+ * file that is absent or drifted stays selected. It is row-level CHILD
+ * selection, which is exactly what the plan's child rows are.
+ *
+ * It used to sit behind a meta-question — "Customize which files pragma
+ * configures?", answered no by default. That gate was read in exactly ONE place
+ * in the repo (this prompt's `when`) and nowhere else: not by `generate`, not by
+ * `applied`, not by any plan, recap, renderer or JSON projection. Answering no
+ * meant the child prompt was never asked, its key was absent from the answer
+ * bag, `readList` returned `undefined`, and the compose bodies read that as
+ * "all" — so everything detected was configured anyway. A meta-question in front
+ * of a direct question is one more thing to answer and no more control; the
+ * choices below already carry the detected state per child (`— unchanged`,
+ * `— add`, `— update`), which is the answer the meta-question was standing in
+ * front of.
  */
-const buildMcpTargetsPrompt = (
-  d: McpDetection,
+const buildChildPrompt = (
+  plan: SetupPlan,
+  target: TargetId,
+  message: string,
   when?: PromptDefinition["when"],
-): PromptDefinition => ({
-  name: "mcpTargets",
-  type: "multiselect",
-  message: "Configure MCP for which files?",
-  when,
-  choices: d.groups.map((g) => ({
-    label: `${g.path} — ${g.harnessNames.join(", ")} [${g.scope}]${mcpStateSuffix(d, g.path)}`,
-    value: g.path,
-  })),
-  default: d.groups
-    .filter((g) => mcpGroupState(d, g.path) !== "configured")
-    .map((g) => g.path),
-});
+): PromptDefinition => {
+  const children = childrenOf(plan, target);
+  return {
+    name: CHILD_ANSWER[target] as string,
+    type: "multiselect",
+    message,
+    when,
+    choices: children.map((child) => ({
+      label: `${child.label} — ${child.action}`,
+      value: child.key,
+    })),
+    default: children
+      .filter((child) => child.action !== "unchanged")
+      .map((child) => child.key),
+  };
+};
 
-// =============================================================================
-// Detection
-// =============================================================================
+/** Every child row a target contributes, across the scopes in the plan. */
+const childrenOf = (
+  plan: SetupPlan,
+  target: TargetId,
+): readonly PlanChildRow[] =>
+  plan.rows
+    .filter((row) => row.target === target)
+    .flatMap((row) => row.children ?? []);
 
-/** Gather EVERY step's detection up front (real reads), for the run-all. */
-async function gatherDetection(
-  rt: PragmaRuntime,
-  scope: ScopeSelection,
-): Promise<SetupDetection> {
-  const [completions, lsp, mcp, skills] = await Promise.all([
-    detectCompletions(rt.cwd),
-    detectLsp(rt.cwd),
-    detectMcp(rt, scope),
-    detectSkills(rt),
-  ]);
-  return { completions, lsp, mcp, skills };
-}
+/** Whether a row was chosen: by the wizard's answer, else by its own default. */
+const isChosen = (
+  row: PlanRow,
+  chosen: readonly string[] | undefined,
+): boolean =>
+  row.action !== "skip" &&
+  (chosen === undefined
+    ? row.selected
+    : chosen.includes(rowKey(row.scope, row.target)));
 
 /**
- * The steps worth OFFERING, given detection AND the scope selection. An
- * undetectable step is omitted so the run-all degrades gracefully instead of
- * throwing a mid-wizard EMPTY_RESULTS; a step whose band the scope does not run
- * is omitted too (completions/lsp are global-band, skills are project-band, MCP
- * spans both via its resolved groups). Threading `scope` here is what makes
- * `setup --local` skip completions+lsp and `setup --global` skip skills — the
- * MCP groups are already scoped by {@link detectMcp}.
+ * What a row DID, as a past-tense word. The row's detail says what and where;
+ * the note says what happened to it, so a progress line and a recap line read
+ * as sentences rather than as two halves of one.
+ */
+const ACTION_NOTES: Record<string, string> = {
+  install: "installed",
+  update: "updated",
+  link: "linked",
+  remove: "removed",
+};
+
+/**
+ * The `2 added, 1 updated` note a row's children produce — counted over the
+ * children the run KEPT, not the ones it was offered.
  *
- * @param detected - Every step's up-front detection.
- * @param scope - The resolved `--scope` selection (project/global/both).
- * @returns The offerable steps, in composition/display order.
+ * `kept` is the row's own child answer: the MCP files, or the LSP editors, the
+ * wizard narrowed to. Counting the plan's children instead recapped `2 added`
+ * for a run the user had just narrowed to one file, so the plan and the result
+ * described different work. Absent (`undefined`) means the narrowing prompt was
+ * never answered, which is the same thing the compose bodies read as "all".
+ *
+ * @param row - The plan row.
+ * @param kept - The child keys the run retained, or `undefined` for all.
+ * @returns The counts note, or `undefined` when the row has no children.
  */
-function listAvailableSteps(
-  detected: SetupDetection,
-  scope: ScopeSelection,
-): { label: string; value: StepId }[] {
-  const hasProject = scope !== "global";
-  const hasGlobal = scope !== "project";
-  const choices: { label: string; value: StepId }[] = [];
-  if (detected.completions.shell && hasGlobal) {
-    choices.push({
-      label: `Shell completions (${detected.completions.shell})`,
-      value: "completions",
-    });
-  }
-  if (hasGlobal) {
-    choices.push({ label: "Terrazzo LSP extension", value: "lsp" });
-  }
-  if (detected.mcp.groups.length > 0) {
-    choices.push({
-      label: `MCP config (${detected.mcp.groups.length} file(s))`,
-      value: "mcp",
-    });
-  }
-  if (detected.skills.available && hasProject) {
-    choices.push({
-      label: `Link skills (${detected.skills.skillCount})`,
-      value: "skills",
-    });
-  }
-  return choices;
+function childNote(
+  row: PlanRow,
+  kept: readonly string[] | undefined,
+): string | undefined {
+  const children = (row.children ?? []).filter(
+    (child) => kept === undefined || kept.includes(child.key),
+  );
+  if (children.length === 0) return undefined;
+  const count = (action: string): number =>
+    children.filter((child) => child.action === action).length;
+  const parts = [
+    count("add") > 0 ? `${count("add")} added` : "",
+    count("update") > 0 ? `${count("update")} updated` : "",
+    count("unchanged") > 0 ? `${count("unchanged")} unchanged` : "",
+  ].filter((part) => part.length > 0);
+  return parts.length > 0 ? parts.join(", ") : undefined;
 }
 
-// =============================================================================
-// Plan builders
-// =============================================================================
-
 /**
- * The run-all self-verb: a step multiselect + per-step composition. The resolved
- * `scope` narrows BOTH the offered steps (via {@link listAvailableSteps}) and the
- * MCP target groups (already scoped by {@link detectMcp}), so `--local` omits the
- * global-band completions+lsp and `--global` omits the project-band skills.
+ * Build one invocation: detect, plan, synthesize the generator, and expose the
+ * projection back onto the plan.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param mode - The entry point: the run-all, or one target.
+ * @param scope - The resolved scope selection.
+ * @param removal - Compose the removal (`--undo`) instead of the install.
+ * @returns The plan, the generator, and the answers-to-plan projection.
+ * @note Impure — runs every selected target's real detection.
  */
-function buildRunAllPlan(
+export async function buildSetupRun(
   rt: PragmaRuntime,
-  detected: SetupDetection,
+  mode: SetupMode,
   scope: ScopeSelection,
-): SetupPlan {
-  const steps = listAvailableSteps(detected, scope);
-  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
-    },
-  ];
-  // Item 6: per-file narrowing is opt-in. The "customize?" gate (default false)
-  // only surfaces when MCP is chosen and there is more than one file; the
-  // per-file multiselect only surfaces after an explicit yes — so the "all"
-  // default configures every deduped file without an extra question.
-  if (detected.mcp.groups.length > 0) {
-    prompts.push(
-      buildCustomizePrompt((a) => readSteps(a).includes("mcp")),
-      buildMcpTargetsPrompt(
-        detected.mcp,
-        (a) => a.customize === true && readSteps(a).includes("mcp"),
-      ),
-    );
+  removal = false,
+): Promise<SetupRun> {
+  const ids: TargetId[] = mode === "all" ? [...TARGET_IDS] : [mode as TargetId];
+  const roots = await resolveRoots(rt);
+  const detected = await detectTargets(rt, ids, scope);
+  const plan = buildPlan(scope, roots, detected, ids, removal);
+  const sink = new OutcomeSink();
+
+  const prompts: PromptDefinition[] = [];
+  if (mode === "all") prompts.push(buildRowsPrompt(plan));
+  // A target is worth narrowing only when it has more than one child to choose
+  // between. `mcp` offers its config files; `lsp` offers the editors on PATH —
+  // a machine with several VS Code forks should not have the extension pushed
+  // into all of them just because they are installed.
+  const narrowable = (
+    [
+      ["mcp", "Configure MCP for which files?"],
+      ["lsp", "Install the extension into which editors?"],
+    ] as const
+  ).filter(([target]) => !removal && childrenOf(plan, target).length > 1);
+
+  for (const [target, message] of narrowable) {
+    // Asked whenever the row it narrows is in the run — one direct question,
+    // no meta-question in front of it. Removing a prompt cannot break the
+    // non-interactive paths: `autoPrompt`/`mcpPrompt` return each question's
+    // default, so a smaller prompt list means a smaller answer bag, and the
+    // compose bodies already read an absent child answer as "all". (The
+    // asymmetry is the reason this direction is safe: ADDING a defaultless
+    // prompt would hard-fail with MISSING_REQUIRED_ANSWER.)
+    const rowChosen = (answers: Record<string, unknown>): boolean => {
+      const chosen = readList(answers, ROWS_ANSWER);
+      return plan.rows.some(
+        (row) => row.target === target && isChosen(row, chosen),
+      );
+    };
+    prompts.push(buildChildPrompt(plan, target, message, rowChosen));
   }
 
-  // `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.
+  /** The detection behind a row, for composing and for re-reading its draft. */
+  const detectionFor = (row: PlanRow): DetectedRow | undefined =>
+    detected.find((d) => d.target.id === row.target && d.scope === row.scope);
+
+  /**
+   * The success note a row's completion carries — ONE derivation for the
+   * recap's outcome and the live row event's `done` label, so the sentence a
+   * watcher saw land is the sentence the recap repeats. A removal never
+   * borrows the forward child summary: its children are the files the entry is
+   * being taken OUT of, and counting them as `1 updated` described the
+   * opposite of what the run had just done.
+   */
+  const noteFor = (
+    row: PlanRow,
+    answers: Record<string, unknown>,
+  ): string | undefined => {
+    if (removal) return ACTION_NOTES[row.action];
+    const childKey = CHILD_ANSWER[row.target];
+    const kept =
+      childKey === undefined ? undefined : readList(answers, childKey);
+    return childNote(row, kept) ?? ACTION_NOTES[row.action];
+  };
+
+  /** The live row listener, when a wizard is watching. See {@link SetupRun}. */
+  let rowListener: ((event: RowEvent) => void) | undefined;
+
+  /** The id column width — the recap's own rule, so the columns agree. */
+  const idWidth = Math.max(...plan.rows.map((row) => row.target.length));
+
   const generator: GeneratorDefinition = {
-    meta: buildMeta(rt, `${BIN_NAME} setup`),
+    meta: buildMeta(
+      rt,
+      mode === "all" ? `${BIN_NAME} setup` : `${BIN_NAME} setup ${mode}`,
+    ),
     prompts,
     generate: (answers) => {
-      const chosen = readSteps(answers);
-      return sequence_([
-        when(
-          chosen.includes("completions"),
-          composeCompletions(detected.completions),
-        ),
-        when(chosen.includes("lsp"), composeGuardedLsp(rt, detected.lsp.state)),
-        when(
-          chosen.includes("mcp"),
-          composeMcp(detected.mcp, selectChosenGroups(detected.mcp, answers)),
-        ),
-        when(chosen.includes("skills"), composeSkills(detected.skills)),
-      ]);
+      const chosen = readList(answers, ROWS_ANSWER);
+      const tasks = plan.rows.flatMap((row) => {
+        if (!isChosen(row, chosen)) return [];
+        const hit = detectionFor(row);
+        if (hit === undefined) return [];
+        // Each target reads ITS OWN child answer. One shared list was handing
+        // MCP file paths to every other target's compose.
+        const key = CHILD_ANSWER[row.target];
+        const children = key === undefined ? undefined : readList(answers, key);
+        const task = removal
+          ? hit.target.composeRemoval(hit.detection)
+          : hit.target.compose(hit.detection, children);
+        // The row's progress sentence — the `target  detail — note` shape
+        // `renderProgressLine` prints — so the live view and the recap say the
+        // same thing about the same row.
+        const label = `${row.target.padEnd(idWidth)}  ${row.detail}`;
+        const note = noteFor(row, answers);
+        return [
+          {
+            key: rowKey(row.scope, row.target),
+            label,
+            doneLabel: note === undefined ? label : `${label} — ${note}`,
+            task,
+          },
+        ];
+      });
+      return runRowsIsolated(sink, tasks, (event) => rowListener?.(event));
     },
   };
 
-  return {
-    generator,
-    toResult: (answers) => ({ kind: "all", steps: readSteps(answers) }),
-  };
-}
-
-/** A single-step generator (no run-all multiselect) for one sub-verb. */
-function buildSingleStep(
-  rt: PragmaRuntime,
-  title: string,
-  prompts: PromptDefinition[],
-  generate: (answers: Record<string, unknown>) => Task<void>,
-): GeneratorDefinition {
-  return { meta: buildMeta(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).
- * @param scope - The resolved `--scope` selection (project/global/both).
- * @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,
-  scope: ScopeSelection,
-): Promise<SetupPlan> {
-  switch (mode) {
-    case "all":
-      return buildRunAllPlan(rt, await gatherDetection(rt, scope), scope);
-
-    case "completions": {
-      const d = await detectCompletions(rt.cwd);
+  /** The outcome one row ended in, read off the sink and its own draft. */
+  const outcomeFor = (
+    row: PlanRow,
+    chosen: readonly string[] | undefined,
+    answers: Record<string, unknown>,
+  ): PlanOutcome | undefined => {
+    const hit = detectionFor(row);
+    // A row whose DETECTION threw has no draft to read and nothing to compose,
+    // and it is not a skip: the target was requested and did not happen. It
+    // reports `failed` with its own cause, exactly as a failed compose does, so
+    // the run names it instead of reporting a clean sweep over its siblings.
+    const failure = hit === undefined ? undefined : detectionFailure(hit);
+    if (failure !== undefined) return { status: "failed", note: failure };
+    const draft = hit === undefined ? undefined : draftFor(hit, roots, removal);
+    if (row.action === "skip") {
       return {
-        generator: buildSingleStep(
-          rt,
-          `${BIN_NAME} setup completions`,
-          [],
-          () => composeCompletions(d),
-        ),
-        toResult: () => ({
-          kind: "completions",
-          shell: d.shell,
-          path: d.path,
-          installed: d.shell !== null,
-          state: d.state,
-        }),
+        status: "skipped",
+        ...(draft?.remedy === undefined ? {} : { remedy: draft.remedy }),
       };
     }
-
-    case "lsp": {
-      const d = await detectLsp(rt.cwd);
+    // An already-current row reports `noop` whether or not it was selected. It
+    // is offered DE-selected (there is nothing to do to it), and returning no
+    // outcome at all left a converged re-run with a plan-shaped output that
+    // claimed nothing had run — while the row still rendered a bare green ✓.
+    // Convergence is a real result: one quiet line per row, zero writes.
+    if (row.action === "none") return { status: "noop", note: "unchanged" };
+    if (!isChosen(row, chosen)) return undefined;
+    const error = sink.get(rowKey(row.scope, row.target));
+    if (error !== undefined) {
+      const pragma = rowPragmaError(error);
       return {
-        generator: buildSingleStep(rt, `${BIN_NAME} setup lsp`, [], () =>
-          composeGuardedLsp(rt, d.state),
-        ),
-        toResult: () => ({ kind: "lsp", state: d.state }),
+        status: "failed",
+        note: pragma.message,
+        ...(pragma.recovery?.message === undefined
+          ? {}
+          : { remedy: pragma.recovery.message }),
       };
     }
+    if (!isActionable(row.action)) return { status: "noop" };
+    const note = noteFor(row, answers);
+    return {
+      status: removal ? "removed" : "done",
+      ...(note === undefined ? {} : { note }),
+    };
+  };
 
-    case "mcp": {
-      const d = await detectMcp(rt, scope);
-      const prompts: PromptDefinition[] =
-        d.groups.length > 0
-          ? [
-              buildCustomizePrompt(),
-              buildMcpTargetsPrompt(d, (a) => a.customize === true),
-            ]
-          : [];
-      return {
-        generator: buildSingleStep(
-          rt,
-          `${BIN_NAME} setup mcp`,
-          prompts,
-          (answers) => composeMcp(d, selectChosenGroups(d, answers)),
-        ),
-        toResult: (answers) => {
-          const sel = selectChosenGroups(d, answers);
+  return {
+    plan,
+    generator,
+    setRowListener: (listener) => {
+      rowListener = listener;
+    },
+    applied: (answers) => {
+      const chosen = readList(answers, ROWS_ANSWER);
+      return withRows(
+        plan,
+        plan.rows.map((row): PlanRow => {
+          const outcome = outcomeFor(row, chosen, answers);
           return {
-            kind: "mcp",
-            configured: mcpConfigured(sel),
-            targets: mcpTargets(d, sel),
+            ...row,
+            selected: isChosen(row, chosen),
+            ...(outcome === undefined ? {} : { outcome }),
           };
-        },
-      };
-    }
-
-    case "skills": {
-      const d = await detectSkills(rt);
-      if (!d.available) throw skillsEmptyError();
-      return {
-        generator: buildSingleStep(rt, `${BIN_NAME} setup skills`, [], () =>
-          composeSkills(d),
-        ),
-        toResult: () => ({ kind: "skills", result: toSkillsResult(d) }),
-      };
-    }
-  }
+        }),
+      );
+    },
+  };
 }