@canonical/pragma-cli 0.35.0 → 0.37.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/setupCompletions.ts

@@ -204,11 +204,18 @@ export function composeCompletions(d: CompletionsDetection): Task<void> {
  * machine that never installed one reverses zero steps and says so.
  *
  * @param d - The detection gathered up front.
+ * @param undoKey - Correlation key stamped on the reversal(s), echoed on
+ *   their undo outcomes so the caller can read results back per row.
  * @returns A Task whose undo deletes the installed script.
  */
-export function composeCompletionsRemoval(d: CompletionsDetection): Task<void> {
+export function composeCompletionsRemoval(
+  d: CompletionsDetection,
+  undoKey?: string,
+): Task<void> {
   if (d.path === null || d.script === null || d.state === "absent") {
     return sequence_([]);
   }
-  return sequence_([writeFile(d.path, d.script, { undo: deleteFile(d.path) })]);
+  return sequence_([
+    writeFile(d.path, d.script, { undo: deleteFile(d.path), undoKey }),
+  ]);
 }

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

@@ -110,12 +110,17 @@ export function composeConfigFile(d: ConfigDetection): Task<void> {
  * delete as its `undo`, which is what the undo interpreter executes.
  *
  * @param d - The detection gathered up front.
+ * @param undoKey - Correlation key stamped on the reversal(s), echoed on
+ *   their undo outcomes so the caller can read results back per row.
  * @returns A Task whose undo removes a seed-only config, or an empty Task.
  */
-export function composeConfigRemoval(d: ConfigDetection): Task<void> {
+export function composeConfigRemoval(
+  d: ConfigDetection,
+  undoKey?: string,
+): Task<void> {
   if (!d.exists || !d.isSeed) return sequence_([]);
   return sequence_([
-    writeFile(d.path, SEED_CONFIG, { undo: deleteFile(d.path) }),
+    writeFile(d.path, SEED_CONFIG, { undo: deleteFile(d.path), undoKey }),
   ]);
 }