@canonical/pragma-cli 0.35.0 → 0.36.0

package/src/capabilities/setup/buildPlan.ts

@@ -19,16 +19,16 @@ import {
 } from "./plan.js";
 import {
   type AnyTarget,
-  supportsBand,
+  supportsScope,
   TARGETS,
   type TargetDraft,
 } from "./targets.js";
-import type { ScopeBand, ScopeSelection } from "./types.js";
+import type { Scope, ScopeSelection } from "./types.js";
 
 /** One detection, kept beside the row that produced it (and can read it back). */
 export interface DetectedRow {
   readonly target: AnyTarget;
-  readonly band: ScopeBand;
+  readonly scope: Scope;
   readonly detection: never;
   /**
    * Why this row's detection did not settle, when it threw. `detection` is then
@@ -48,8 +48,8 @@ export interface DetectedPlan {
   readonly detected: readonly DetectedRow[];
 }
 
-/** The bands a `--scope` selection runs, global before project. */
-export const bandsForScope = (scope: ScopeSelection): readonly ScopeBand[] =>
+/** The scopes a `--scope` selection runs, global before project. */
+export const scopesForSelection = (scope: ScopeSelection): readonly Scope[] =>
   scope === "both" ? ["global", "project"] : [scope];
 
 /**
@@ -72,7 +72,7 @@ const messageOf = (reason: unknown): string =>
   reason instanceof Error ? reason.message : String(reason);
 
 /**
- * Detect every requested target in every band the scope runs.
+ * Detect every requested target in every scope the scope runs.
  *
  * Detections are started together and SETTLED INDEPENDENTLY: they are
  * independent reads, and a run-all that probed five targets serially paid for
@@ -82,13 +82,13 @@ const messageOf = (reason: unknown): string =>
  * unreadable config, a permission-denied directory — takes only its own row
  * down. Awaiting them as one `Promise.all` meant the first rejection prevented
  * a run from being built at all: none of the other targets ran, and doctor
- * rendered no banded rows whatsoever. The failed row carries its cause and is
+ * rendered no scoped rows whatsoever. The failed row carries its cause and is
  * reported as a row, which is the same shape a failed COMPOSE already has.
  *
  * @param rt - The per-invocation runtime.
  * @param ids - The targets to plan (all five for the run-all).
- * @param scope - The resolved band selection.
- * @returns One entry per (target, band) the scope actually runs.
+ * @param scope - The resolved scope selection.
+ * @returns One entry per (target, scope) the scope actually runs.
  * @note Impure — every target's `detect` reads the real filesystem.
  */
 export async function detectTargets(
@@ -97,25 +97,25 @@ export async function detectTargets(
   scope: ScopeSelection,
 ): Promise<DetectedRow[]> {
   const wanted = TARGETS.filter((target) => ids.includes(target.id));
-  const pairs = bandsForScope(scope).flatMap((band) =>
+  const pairs = scopesForSelection(scope).flatMap((scope) =>
     wanted
-      .filter((target) => supportsBand(target, band))
+      .filter((target) => supportsScope(target, scope))
       .map((target) => ({
         target,
-        band,
+        scope,
       })),
   );
   const settled = await Promise.allSettled(
-    pairs.map(({ target, band }) => target.detect(rt, band)),
+    pairs.map(({ target, scope }) => target.detect(rt, scope)),
   );
-  return pairs.map(({ target, band }, index) => {
+  return pairs.map(({ target, scope }, index) => {
     const outcome = settled[index] as PromiseSettledResult<unknown>;
     if (outcome.status === "fulfilled") {
-      return { target, band, detection: outcome.value as never };
+      return { target, scope, detection: outcome.value as never };
     }
     return {
       target,
-      band,
+      scope,
       detection: undefined as never,
       failure: messageOf(outcome.reason),
     };
@@ -123,22 +123,26 @@ export async function detectTargets(
 }
 
 /**
- * The dim row a target gets when the SELECTED band cannot hold it — `setup
- * --local` still shows `completions`, saying why it is not in this run. A band
- * merely filters the run-all: the user asked for a band, not for that target, so
+ * The dim row a target gets when the SELECTED scope cannot hold it — `setup
+ * --local` still shows `completions`, saying why it is not in this run. A scope
+ * merely filters the run-all: the user asked for a scope, not for that target, so
  * nothing errors, but nothing is silently absent either. (Asking for the
- * impossible band on the SUB-VERB is a different thing entirely — a typed
+ * impossible scope on the SUB-VERB is a different thing entirely — a typed
  * contradiction, and a usage error.)
+ *
+ * The reason names the flag that WOULD reach the target, so the row is not a
+ * dead end: a reader who wanted `completions` under `--local` is told in the
+ * same line that `--global` is where it lives.
  */
-const outOfBandRow = (target: AnyTarget, band: ScopeBand): PlanRow => ({
+const outOfScopeRow = (target: AnyTarget, scope: Scope): PlanRow => ({
   target: target.id,
-  band,
+  scope,
   action: "skip",
-  detail: "not in this band",
+  detail: "not part of this scope",
   reason:
-    band === "project"
-      ? "user-level only — it has no project band"
-      : "project-level only — it has no global band",
+    scope === "project"
+      ? "this one is global only — run it with `--global`"
+      : "this one is per-project only — run it with `--local`",
   selected: false,
 });
 
@@ -151,11 +155,11 @@ const outOfBandRow = (target: AnyTarget, band: ScopeBand): PlanRow => ({
  */
 const failedDetectionRow = (
   target: AnyTarget,
-  band: ScopeBand,
+  scope: Scope,
   failure: string,
 ): PlanRow => ({
   target: target.id,
-  band,
+  scope,
   action: "skip",
   detail: "detection did not complete",
   reason: failure,
@@ -179,51 +183,51 @@ export function draftFor(
   removal: boolean,
 ): TargetDraft {
   return removal
-    ? hit.target.removalPlan(hit.detection, hit.band, roots)
-    : hit.target.plan(hit.detection, hit.band, roots);
+    ? hit.target.removalPlan(hit.detection, hit.scope, roots)
+    : hit.target.plan(hit.detection, hit.scope, roots);
 }
 
 /**
  * Project detections into plan rows.
  *
- * @param scope - The resolved band selection (named in the header).
+ * @param selection - The resolved scope selection (named in the header).
  * @param roots - The two named roots every path renders relative to.
- * @param detected - The detections, in table order per band.
- * @param ids - The targets that were REQUESTED, so an out-of-band one still
+ * @param detected - The detections, in table order per scope.
+ * @param ids - The targets that were REQUESTED, so an out-of-scope one still
  *   gets a visible row.
  * @param removal - Build the removal plan (`--undo`) instead of the forward one.
  * @returns The plan.
  */
 export function buildPlan(
-  scope: ScopeSelection,
+  selection: ScopeSelection,
   roots: SetupPlan["roots"],
   detected: readonly DetectedRow[],
   ids: readonly TargetId[],
   removal = false,
 ): SetupPlan {
   const rows: PlanRow[] = [];
-  for (const band of bandsForScope(scope)) {
+  for (const scope of scopesForSelection(selection)) {
     for (const target of TARGETS) {
       if (!ids.includes(target.id)) continue;
       const hit = detected.find(
-        (d) => d.target.id === target.id && d.band === band,
+        (d) => d.target.id === target.id && d.scope === scope,
       );
       if (hit === undefined) {
-        // Only worth a line when the target has no row in ANY selected band —
+        // Only worth a line when the target has no row in ANY selected scope —
         // under `--scope both` a global-only target already appears above.
         const elsewhere = detected.some((d) => d.target.id === target.id);
-        if (!elsewhere) rows.push(outOfBandRow(target, band));
+        if (!elsewhere) rows.push(outOfScopeRow(target, scope));
         continue;
       }
       const failure = detectionFailure(hit);
       if (failure !== undefined) {
-        rows.push(failedDetectionRow(target, band, failure));
+        rows.push(failedDetectionRow(target, scope, failure));
         continue;
       }
       const draft = draftFor(hit, roots, removal);
       rows.push({
         target: target.id,
-        band,
+        scope,
         action: draft.action,
         detail: draft.detail,
         ...(draft.reason === undefined ? {} : { reason: draft.reason }),
@@ -232,5 +236,5 @@ export function buildPlan(
       });
     }
   }
-  return { scope, roots, rows };
+  return { scope: selection, roots, rows };
 }

package/src/capabilities/setup/index.ts

@@ -9,4 +9,4 @@ export type {
   TargetId,
 } from "./plan.js";
 export { setupModule } from "./setup.verb.js";
-export type { ScopeBand, ScopeSelection } from "./types.js";
+export type { Scope, ScopeSelection } from "./types.js";

package/src/capabilities/setup/mode.ts

@@ -20,8 +20,8 @@
  * who forgot `--yes` reads the hint on the very output they are capturing.
  *
  * An MCP tool call is programmatic consent: `transport === "mcp"` resolves as if
- * `--yes` were passed. The band default applies there too — the tool writes the
- * global band unless told otherwise.
+ * `--yes` were passed. The scope default applies there too — the tool writes the
+ * global scope unless told otherwise.
  */
 
 import type { InteractionMode } from "@canonical/summon-core/projection";

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

@@ -13,7 +13,7 @@
  *
  * The detection types are part of the surface, not an implementation leak: a
  * detection is the value passed from the read half to the compose half and on
- * to the plan rows, so `doctor`'s banded checks name the same records `setup`
+ * to the plan rows, so `doctor`'s scoped checks name the same records `setup`
  * acts on. The presentation helpers travel with them for the same reason — a
  * skip reason or an uninstall remedy is derived from one detection, and
  * deriving it twice is how the two surfaces start disagreeing about the same
@@ -54,6 +54,7 @@ export {
   lspEditorNames,
   lspSkipReason,
   lspUninstallRemedy,
+  ownedLspEditors,
 } from "./setupLsp.js";
 export type { McpDetection } from "./setupMcp.js";
 export {
@@ -61,6 +62,7 @@ export {
   composeMcpRemoval,
   detectMcp,
   mcpGroupState,
+  mcpWriteState,
   ownedMcpGroups,
   selectedGroups,
 } from "./setupMcp.js";
@@ -71,4 +73,7 @@ export {
   detectSkills,
   ownedSkillLinks,
   skillsSkipReason,
+  skillsSkipRemedy,
+  staleSkillLinks,
+  withinRoot,
 } from "./setupSkills.js";

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.
@@ -55,7 +55,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 +72,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 +103,15 @@ 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;
+  /**
+   * 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 +170,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 +249,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 +258,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 +302,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 +319,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 +371,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 +401,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(
@@ -399,9 +466,21 @@ export async function buildSetupRun(
         const task = removal
           ? hit.target.composeRemoval(hit.detection)
           : 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));
     },
   };
 
@@ -432,7 +511,7 @@ export async function buildSetupRun(
     // 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.band, row.target));
+    const error = sink.get(rowKey(row.scope, row.target));
     if (error !== undefined) {
       const pragma = rowPragmaError(error);
       return {
@@ -444,15 +523,7 @@ 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 }),
@@ -462,6 +533,9 @@ export async function buildSetupRun(
   return {
     plan,
     generator,
+    setRowListener: (listener) => {
+      rowListener = listener;
+    },
     applied: (answers) => {
       const chosen = readList(answers, ROWS_ANSWER);
       return withRows(