@canonical/pragma-cli 0.35.0 → 0.37.0

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

@@ -5,7 +5,7 @@
  * gate, live progress, colours, and the shared cancel fixes by construction.
  *
  * The shape mirrors `create`: detection runs FOR REAL up front (once per
- * target/band, in `detectTargets`), then a PURE `generate` composes only the
+ * 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.
@@ -34,6 +34,7 @@ import {
   type TaskError,
   warn,
 } from "@canonical/task";
+import type { UndoOutcome } from "@canonical/task/node";
 import { BIN_NAME } from "../../../constants.js";
 import { PragmaError } from "../../../kernel/error/index.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
@@ -55,7 +56,7 @@ import {
   type TargetId,
   withRows,
 } from "../plan.js";
-import type { ScopeBand, ScopeSelection, SetupMode } from "../types.js";
+import type { Scope, ScopeSelection, SetupMode } from "../types.js";
 
 /** The answer key the run-all's row multiselect writes. */
 const ROWS_ANSWER = "targets";
@@ -72,9 +73,26 @@ const CHILD_ANSWER: Partial<Record<TargetId, string>> = {
   lsp: LSP_EDITORS_ANSWER,
 };
 
-/** A row's identity in an answer bag: band-qualified, so `both` stays unambiguous. */
-const rowKey = (band: ScopeBand, target: TargetId): string =>
-  `${band}:${target}`;
+/** A row's identity in an answer bag: scope-qualified, so `both` stays unambiguous. */
+const rowKey = (scope: Scope, target: TargetId): string => `${scope}:${target}`;
+
+/**
+ * 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 RowEvent {
+  /** The row's stable identity — `scope:target`. */
+  readonly key: string;
+  readonly label: string;
+  readonly status: "start" | "done" | "failed";
+}
 
 /**
  * A ready-to-run setup invocation: the plan as detected, the synthesized
@@ -86,6 +104,29 @@ export interface SetupRun {
   readonly generator: GeneratorDefinition;
   /** The plan with the wizard's selection and the run's outcomes applied. */
   applied(answers: Record<string, unknown>): SetupPlan;
+  /**
+   * The plan graded by the EXECUTED reversals — `--undo`'s own `applied`.
+   *
+   * A real `--undo` never interprets the composed task for real: the undo
+   * interpreter walks it with every effect mocked (to collect the
+   * reversals), so the {@link OutcomeSink} the forward run fills stays
+   * empty, and only the interpreter's per-undo outcomes — correlated by the
+   * `undoKey` each reversal was stamped with in `generate` — say what
+   * actually happened. This projection writes those outcomes onto the SAME
+   * sink and reads the plan back through the SAME `outcomeFor` the forward
+   * run uses: one outcome model, both directions. An actionable row none of
+   * whose reversals reported back is a failure, never a quiet `removed`.
+   */
+  appliedUndo(outcomes: readonly UndoOutcome[]): 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;
 }
 
 /**
@@ -144,25 +185,50 @@ const rowPragmaError = (error: TaskError): PragmaError =>
  * 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 runRowsIsolated = (
   sink: OutcomeSink,
-  rows: readonly { key: string; task: Task<void> }[],
+  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, task }) =>
-        recover(task, (error) =>
-          flatMap(
-            warn(
-              `The ${key.split(":")[1]} step did not complete — continuing with the remaining targets.`,
-            ),
-            () => {
-              sink.record(key, error);
+      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);
+              },
+            ),
         ),
       ),
     );
@@ -198,7 +264,7 @@ const buildRowsPrompt = (plan: SetupPlan): PromptDefinition => {
     .filter((row) => row.action !== "skip")
     .map((row) => ({
       label: `${row.target} — ${row.detail}${row.action === "none" ? " (already configured)" : ""}`,
-      value: rowKey(row.band, row.target),
+      value: rowKey(row.scope, row.target),
     }));
   return {
     name: ROWS_ANSWER,
@@ -207,27 +273,27 @@ const buildRowsPrompt = (plan: SetupPlan): PromptDefinition => {
     choices,
     default: plan.rows
       .filter((row) => row.selected)
-      .map((row) => rowKey(row.band, row.target)),
+      .map((row) => rowKey(row.scope, row.target)),
   };
 };
 
-/** The opt-in "customize which files" gate — defaults to false. */
-const buildCustomizePrompt = (
-  when?: PromptDefinition["when"],
-): PromptDefinition => ({
-  name: "customize",
-  type: "confirm",
-  message: `Customize which files ${BIN_NAME} configures?`,
-  default: false,
-  when,
-});
-
 /**
  * The per-file MCP multiselect — one row per deduplicated config file, across
- * every band the run covers. An already-current file is DEFAULT-DESELECTED; a
- * file that is absent or drifted stays selected. Retained unchanged from the
- * landed opt-in narrowing: it is row-level CHILD selection, which is exactly
- * what the plan's child rows are.
+ * 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 buildChildPrompt = (
   plan: SetupPlan,
@@ -251,7 +317,7 @@ const buildChildPrompt = (
   };
 };
 
-/** Every child row a target contributes, across the bands in the plan. */
+/** Every child row a target contributes, across the scopes in the plan. */
 const childrenOf = (
   plan: SetupPlan,
   target: TargetId,
@@ -268,7 +334,7 @@ const isChosen = (
   row.action !== "skip" &&
   (chosen === undefined
     ? row.selected
-    : chosen.includes(rowKey(row.band, row.target)));
+    : chosen.includes(rowKey(row.scope, row.target)));
 
 /**
  * What a row DID, as a past-tense word. The row's detail says what and where;
@@ -320,7 +386,7 @@ function childNote(
  *
  * @param rt - The per-invocation runtime.
  * @param mode - The entry point: the run-all, or one target.
- * @param scope - The resolved band selection.
+ * @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.
@@ -350,35 +416,51 @@ export async function buildSetupRun(
     ] as const
   ).filter(([target]) => !removal && childrenOf(plan, target).length > 1);
 
-  if (narrowable.length > 0) {
-    const anyChosen = (answers: Record<string, unknown>): boolean => {
+  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 narrowable.some(([target]) =>
-        plan.rows.some((row) => row.target === target && isChosen(row, chosen)),
+      return plan.rows.some(
+        (row) => row.target === target && isChosen(row, chosen),
       );
     };
-    prompts.push(buildCustomizePrompt(anyChosen));
-    for (const [target, message] of narrowable) {
-      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,
-          (answers) => answers.customize === true && rowChosen(answers),
-        ),
-      );
-    }
+    prompts.push(buildChildPrompt(plan, target, message, rowChosen));
   }
 
   /** 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.band === row.band);
+    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(
@@ -396,12 +478,31 @@ export async function buildSetupRun(
         // MCP file paths to every other target's compose.
         const key = CHILD_ANSWER[row.target];
         const children = key === undefined ? undefined : readList(answers, key);
+        // A removal stamps the row's identity on every reversal it composes:
+        // `--undo` executes those reversals in a LATER phase (the undo
+        // interpreter's), whose outcomes come back correlated by this key —
+        // see `appliedUndo`.
         const task = removal
-          ? hit.target.composeRemoval(hit.detection)
+          ? hit.target.composeRemoval(
+              hit.detection,
+              rowKey(row.scope, row.target),
+            )
           : hit.target.compose(hit.detection, children);
-        return [{ key: rowKey(row.band, row.target), task }];
+        // 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);
+      return runRowsIsolated(sink, tasks, (event) => rowListener?.(event));
     },
   };
 
@@ -430,9 +531,19 @@ export async function buildSetupRun(
     // 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" };
+    //
+    // On a REMOVAL the same state is `kept`, not `noop`: the run owned
+    // nothing here and deliberately left the machine's state standing (the
+    // config the user edited, the editor with no extension copy). That is
+    // standing aside, which the vocabulary marks inert (○), where `noop`'s
+    // green ✓ would claim removal work that never existed.
+    if (row.action === "none") {
+      return removal
+        ? { status: "kept" }
+        : { status: "noop", note: "unchanged" };
+    }
     if (!isChosen(row, chosen)) return undefined;
-    const error = sink.get(rowKey(row.band, row.target));
+    const error = sink.get(rowKey(row.scope, row.target));
     if (error !== undefined) {
       const pragma = rowPragmaError(error);
       return {
@@ -444,37 +555,69 @@ export async function buildSetupRun(
       };
     }
     if (!isActionable(row.action)) return { status: "noop" };
-    // 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 childKey = CHILD_ANSWER[row.target];
-    const kept =
-      childKey === undefined ? undefined : readList(answers, childKey);
-    const note = removal
-      ? ACTION_NOTES[row.action]
-      : (childNote(row, kept) ?? ACTION_NOTES[row.action]);
+    const note = noteFor(row, answers);
     return {
       status: removal ? "removed" : "done",
       ...(note === undefined ? {} : { note }),
     };
   };
 
+  /** The one answers→plan projection both `applied` faces share. */
+  const project = (answers: Record<string, unknown>): SetupPlan => {
+    const chosen = readList(answers, ROWS_ANSWER);
+    return withRows(
+      plan,
+      plan.rows.map((row): PlanRow => {
+        const outcome = outcomeFor(row, chosen, answers);
+        return {
+          ...row,
+          selected: isChosen(row, chosen),
+          ...(outcome === undefined ? {} : { outcome }),
+        };
+      }),
+    );
+  };
+
   return {
     plan,
     generator,
-    applied: (answers) => {
-      const chosen = readList(answers, ROWS_ANSWER);
-      return withRows(
-        plan,
-        plan.rows.map((row): PlanRow => {
-          const outcome = outcomeFor(row, chosen, answers);
-          return {
-            ...row,
-            selected: isChosen(row, chosen),
-            ...(outcome === undefined ? {} : { outcome }),
-          };
-        }),
+    setRowListener: (listener) => {
+      rowListener = listener;
+    },
+    applied: project,
+    appliedUndo: (outcomes) => {
+      // The undo path's sink fill. The forward run's recover frames write the
+      // sink WHILE the task is interpreted; a real `--undo` interprets the
+      // task only as the mocked collection walk, so the executed reversals'
+      // outcomes land here instead — same sink, same reader (`outcomeFor`),
+      // other direction. The first failure per row wins: it is the earliest
+      // cause, and the row's note should name it, not the knock-on.
+      sink.clear();
+      for (const outcome of outcomes) {
+        if (outcome.status !== "failed" || outcome.key === undefined) continue;
+        if (sink.get(outcome.key) !== undefined) continue;
+        sink.record(outcome.key, outcome.error);
+      }
+      // A row that owed reversals and heard back from NONE of them cannot
+      // report `removed` — nothing proved anything happened. Structurally
+      // every actionable removal row composes at least one keyed reversal,
+      // so this is a guard against a future target breaking that invariant,
+      // not a path any current target takes.
+      const reported = new Set(
+        outcomes.flatMap((o) => (o.key === undefined ? [] : [o.key])),
       );
+      for (const row of plan.rows) {
+        const id = rowKey(row.scope, row.target);
+        if (!isActionable(row.action) || !row.selected) continue;
+        if (reported.has(id) || sink.get(id) !== undefined) continue;
+        sink.record(id, {
+          code: "UNSUPPORTED",
+          message: "no reversal was executed for this target",
+        });
+      }
+      // No answers: `--undo` asks nothing, so every row falls back to its
+      // own default selection — exactly the set `generate` composed from.
+      return project({});
     },
   };
 }