@canonical/pragma-cli 0.35.0 → 0.37.0

package/src/capabilities/setup/targets.ts

@@ -1,14 +1,14 @@
 /**
  * THE target table — the one list `setup` and `doctor` both read.
  *
- * Five rows, each with a band column. This table drives the `setup <target>`
+ * Five rows, each with a scope column. This table drives the `setup <target>`
  * sub-verbs, the wizard's choices, the `--dry-run` plan, the progress lines, the
  * recap, the doctor rows, and each doctor row's `fix:` line. Adding a sixth
  * target is one row here — not a new sub-verb, a new check, a new recap branch
  * and a new fix string that four separate files have to agree about.
  *
  * A row owns: its identity (`id` is BOTH the sub-verb argument and the doctor
- * row name, so `mcp` and `setup mcp` visibly share a token), which bands it can
+ * row name, so `mcp` and `setup mcp` visibly share a token), which scopes it can
  * be installed into, how to DETECT its current state, how to PLAN a run from
  * that detection, and how to COMPOSE the forward and removal effects. Detection
  * runs once per invocation and feeds every reader, so setup and doctor cannot
@@ -24,6 +24,7 @@
  * doctor's), so nothing here lands on the `--help`/`__complete` fast path.
  */
 
+import { dirname } from "node:path";
 import type { Task } from "@canonical/task";
 import { BIN_NAME } from "../../constants.js";
 import type { PragmaRuntime } from "../../kernel/runtime/index.js";
@@ -47,7 +48,7 @@ import {
   type LspDetection,
   lspEditorNames,
   lspSkipReason,
-  lspUninstallRemedy,
+  ownedLspEditors,
 } from "./operations/setupLsp.js";
 import {
   composeMcp,
@@ -65,6 +66,8 @@ import {
   ownedSkillLinks,
   type SkillsDetection,
   skillsSkipReason,
+  skillsSkipRemedy,
+  staleSkillLinks,
 } from "./operations/setupSkills.js";
 import {
   type PlanAction,
@@ -73,7 +76,7 @@ import {
   shortenPath,
   type TargetId,
 } from "./plan.js";
-import type { ScopeBand } from "./types.js";
+import type { Scope } from "./types.js";
 
 /** What a target contributes to one plan row, before selection is applied. */
 export interface TargetDraft {
@@ -98,20 +101,24 @@ export interface TargetDefinition<D> {
   readonly id: TargetId;
   /** Human title, used where a sentence needs one; the id is the row name. */
   readonly title: string;
-  readonly bands: readonly ScopeBand[];
-  /** Real reads, up front, once per (target, band) per invocation. */
-  detect(rt: PragmaRuntime, band: ScopeBand): Promise<D>;
+  readonly scopes: readonly Scope[];
+  /** Real reads, up front, once per (target, scope) per invocation. */
+  detect(rt: PragmaRuntime, scope: Scope): Promise<D>;
   /** What a forward run would do. */
-  plan(detection: D, band: ScopeBand, roots: Roots): TargetDraft;
+  plan(detection: D, scope: Scope, roots: Roots): TargetDraft;
   /** What a removal would do — composed from what detection says we own. */
-  removalPlan(detection: D, band: ScopeBand, roots: Roots): TargetDraft;
+  removalPlan(detection: D, scope: Scope, roots: Roots): TargetDraft;
   /**
    * The forward effects. `chosen` is the row's per-child selection (MCP file
    * paths); a row without children ignores it.
    */
   compose(detection: D, chosen?: readonly string[]): Task<void>;
-  /** The removal effects: forward re-assertion carrying the reversal as `undo`. */
-  composeRemoval(detection: D): Task<void>;
+  /**
+   * The removal effects: forward re-assertion carrying the reversal as
+   * `undo`. `undoKey` (the row's identity) is stamped on every reversal so
+   * the undo interpreter's outcomes can be read back per row.
+   */
+  composeRemoval(detection: D, undoKey?: string): Task<void>;
 }
 
 /** A table row with its detection type erased — how every consumer holds one. */
@@ -128,35 +135,35 @@ const defineTarget = <D>(target: TargetDefinition<D>): AnyTarget =>
 const configTarget = defineTarget<ConfigDetection>({
   id: "config",
   title: "Global configuration",
-  bands: ["global"],
+  scopes: ["global"],
   detect: () => detectConfigFile(),
-  plan: (d, _band, roots) => {
+  plan: (d, _scope, roots) => {
     const path = shortenPath(d.path, roots);
     if (!d.exists) return { action: "install", detail: path };
     return { action: "none", detail: `${path} — present` };
   },
-  removalPlan: (d, _band, roots) => {
+  removalPlan: (d, _scope, roots) => {
     const path = shortenPath(d.path, roots);
     if (!d.exists) return { action: "none", detail: `${path} — absent` };
     if (!d.isSeed) {
       return {
         action: "skip",
         detail: path,
-        reason: "kept — it holds your settings",
+        reason: `it holds your own settings, so ${path} stays`,
       };
     }
     return { action: "remove", detail: path };
   },
   compose: (d) => composeConfigFile(d),
-  composeRemoval: (d) => composeConfigRemoval(d),
+  composeRemoval: (d, undoKey) => composeConfigRemoval(d, undoKey),
 });
 
 const completionsTarget = defineTarget<CompletionsDetection>({
   id: "completions",
   title: "Shell completions",
-  bands: ["global"],
+  scopes: ["global"],
   detect: (rt) => detectCompletions(rt.cwd),
-  plan: (d, _band, roots) => {
+  plan: (d, _scope, roots) => {
     // Never guess a shell. Installing for the wrong one is invisible until the
     // user presses TAB and nothing happens, so an unresolved shell is a named
     // skip whose remedy is the one action that DOES settle it.
@@ -187,26 +194,31 @@ const completionsTarget = defineTarget<CompletionsDetection>({
       };
     }
     const where = `${d.shell} → ${shortenPath(d.path, roots)}`;
-    if (d.state === "installed") return { action: "none", detail: where };
+    // A no-op row says what it FOUND, not just where it looked: `no change`
+    // beside a bare path leaves the reader to guess whether the script is
+    // there and current or missing and unreachable.
+    if (d.state === "installed") {
+      return { action: "none", detail: `${where} — already up to date` };
+    }
     return {
       action: d.state === "stale" ? "update" : "install",
       detail: where,
     };
   },
-  removalPlan: (d, _band, roots) => {
+  removalPlan: (d, _scope, roots) => {
     if (d.path === null || d.state === "absent") {
       return { action: "none", detail: "no script installed" };
     }
     return { action: "remove", detail: shortenPath(d.path, roots) };
   },
   compose: (d) => composeCompletions(d),
-  composeRemoval: (d) => composeCompletionsRemoval(d),
+  composeRemoval: (d, undoKey) => composeCompletionsRemoval(d, undoKey),
 });
 
 const lspTarget = defineTarget<LspDetection>({
   id: "lsp",
   title: "Terrazzo LSP extension",
-  bands: ["global"],
+  scopes: ["global"],
   detect: (rt) => detectLsp(rt.cwd),
   plan: (d) => {
     if (d.state === "unknown") {
@@ -225,32 +237,71 @@ const lspTarget = defineTarget<LspDetection>({
       label: `${e.editor.cli} — ${e.editor.name}`,
       action: e.installed ? ("unchanged" as const) : ("add" as const),
     }));
+    // The detail names WHAT is being placed and WHERE — never the row's own
+    // state, which the action column already carries. `installed (VSCodium)`
+    // beside a child row reading `codium — VSCodium (unchanged)` said the
+    // editor's name twice and "nothing happens here" twice.
     if (d.state === "installed") {
       return {
         action: "none",
-        detail: `installed (${lspEditorNames(d).join(", ")})`,
+        detail: `Terrazzo extension in ${lspEditorNames(d).join(", ")}`,
         children,
       };
     }
     const pending = d.editors.filter((e) => !e.installed);
     return {
       action: "install",
-      detail: `${pending.length} ${pending.length === 1 ? "editor" : "editors"}`,
+      detail: `Terrazzo extension → ${pending
+        .map((e) => e.editor.name)
+        .join(", ")}`,
       children,
     };
   },
-  removalPlan: (d) => ({
-    action: "skip",
-    detail: "not removed",
-    reason: "an extension install cannot be reversed from here",
-    remedy:
-      lspUninstallRemedy(d) ??
-      "no editor CLI is on PATH — uninstall it from your editor",
-  }),
+  removalPlan: (d) => {
+    // No editor CLI on PATH is the SAME named skip the forward plan reports:
+    // there is nothing on this machine to run an uninstall with.
+    if (d.state === "unknown") {
+      return {
+        action: "skip",
+        detail: lspSkipReason(d),
+        reason: lspSkipReason(d),
+        remedy: LSP_SKIP_REMEDY,
+      };
+    }
+    // Removal is composed from what detection says we OWN — a copy that is
+    // present, whatever its version. The forward plan's version gate would let
+    // a dead pre-0.8.3 copy this command installed survive its own `--undo`.
+    const owned = ownedLspEditors(d);
+    if (owned.length === 0) {
+      return { action: "none", detail: "no editor carries the extension" };
+    }
+    return {
+      action: "remove",
+      detail: `Terrazzo extension from ${owned
+        .map((e) => e.editor.name)
+        .join(", ")}`,
+      children: owned.map((e) => ({
+        key: e.editor.cli,
+        label: `${e.editor.cli} — ${e.editor.name}`,
+        action: "update" as const,
+      })),
+    };
+  },
   compose: (d, chosen) => composeLsp(d, chosen),
-  composeRemoval: (d) => composeLspRemoval(d),
+  composeRemoval: (d, undoKey) => composeLspRemoval(d, undoKey),
 });
 
+/**
+ * Why the `mcp` row has nothing to write in a scope — authored once, because
+ * `setup`'s row and `doctor`'s row are the same finding and must not word it
+ * differently. Neither sentence says "scope": the two scopes are `global` and
+ * `local project`, after the `--global` / `--local` flags that select them.
+ */
+export const MCP_NO_LOCATION: Record<Scope, string> = {
+  global: "no AI harness on this machine keeps a global config",
+  project: "no AI harness in this project keeps a per-project config",
+};
+
 /** One MCP file as a plan child: its path, the harnesses sharing it, its state. */
 const mcpChild = (
   d: McpDetection,
@@ -262,7 +313,7 @@ const mcpChild = (
     key: group.path,
     label: shortenPath(group.path, roots),
     action:
-      state === "configured"
+      state === "registered"
         ? "unchanged"
         : state === "drifted"
           ? "update"
@@ -273,35 +324,34 @@ const mcpChild = (
 const mcpTarget = defineTarget<McpDetection>({
   id: "mcp",
   title: "MCP server registration",
-  bands: ["global", "project"],
-  detect: (rt, band) => detectMcp(rt, band),
-  plan: (d, band, roots) => {
+  scopes: ["global", "project"],
+  detect: (rt, scope) => detectMcp(rt, scope),
+  plan: (d, scope, roots) => {
     if (d.groups.length === 0) {
       return {
         action: "skip",
-        detail: "no harness config location in this band",
-        reason:
-          band === "project"
-            ? "no AI harness in this project writes a per-repository config"
-            : "no detected AI harness declares a user-level config location",
+        detail: MCP_NO_LOCATION[scope],
+        reason: MCP_NO_LOCATION[scope],
       };
     }
     const children = d.groups.map((group) => mcpChild(d, group, roots));
     const pending = children.filter((c) => c.action !== "unchanged");
     return {
       action: pending.length === 0 ? "none" : "update",
-      detail: `${d.groups.length} ${d.groups.length === 1 ? "file" : "files"}`,
+      detail: `${d.groups.length} ${
+        d.groups.length === 1 ? "config file" : "config files"
+      }`,
       children,
     };
   },
-  removalPlan: (d, _band, roots) => {
+  removalPlan: (d, _scope, roots) => {
     const owned = ownedMcpGroups(d);
     if (owned.length === 0) {
       return { action: "none", detail: "no entry to remove" };
     }
     return {
       action: "remove",
-      detail: `${owned.length} ${owned.length === 1 ? "file" : "files"}`,
+      detail: `${owned.length} ${owned.length === 1 ? "config file" : "config files"}`,
       children: owned.map((group) => ({
         key: group.path,
         label: shortenPath(group.path, roots),
@@ -311,30 +361,58 @@ const mcpTarget = defineTarget<McpDetection>({
   },
   compose: (d, chosen) =>
     composeMcp(d, chosen ? selectedGroups(d, chosen) : d.groups),
-  composeRemoval: (d) => composeMcpRemoval(d),
+  composeRemoval: (d, undoKey) => composeMcpRemoval(d, undoKey),
 });
 
 const skillsTarget = defineTarget<SkillsDetection>({
   id: "skills",
   title: "Skill symlinks",
-  bands: ["global", "project"],
-  detect: (rt, band) => detectSkills(rt, band),
-  plan: (d, band, roots) => {
-    if (!d.available) {
-      const reason = skillsSkipReason(shortenPath(d.sourceRoot, roots), band);
-      return { action: "skip", detail: reason, reason };
+  scopes: ["global", "project"],
+  detect: (rt, scope) => detectSkills(rt, scope),
+  plan: (d, scope, roots) => {
+    // A forward run RECONCILES: stale links this scope owns are its work too, so
+    // an orphan-only tree is actionable rather than a row that plans `none` and
+    // is then deselected into doing nothing. `staleSkillLinks` carries the
+    // absent-root safety gate, so a machine whose source root does not exist
+    // contributes no sweep and the row falls back to the honest skip.
+    const stale = staleSkillLinks(d);
+    if (!d.available && stale.length === 0) {
+      const short = shortenPath(d.sourceRoot, roots);
+      const reason = skillsSkipReason(short, scope, d.rootExists);
+      // A skip with no remedy is a dead end — this one names the command that
+      // fills the scope's source root, exactly as the completions and lsp skips
+      // beside it name theirs.
+      return {
+        action: "skip",
+        detail: reason,
+        reason,
+        remedy: skillsSkipRemedy(short, scope),
+      };
     }
     const dirs = d.targets.map((t) => shortenPath(t.dir, roots)).join(", ");
-    const where = `${d.skillCount} ${d.skillCount === 1 ? "skill" : "skills"} → ${d.targets.length} ${d.targets.length === 1 ? "dir" : "dirs"} (${dirs})`;
+    const where = `${d.skillCount} ${d.skillCount === 1 ? "skill" : "skills"} → ${d.targets.length} ${d.targets.length === 1 ? "folder" : "folders"} (${dirs})`;
+    const detail =
+      stale.length === 0
+        ? where
+        : `${where}, ${stale.length} stale ${stale.length === 1 ? "link" : "links"} to remove`;
     const pending = d.actions.filter((a) => a.action !== "skipped");
-    return { action: pending.length === 0 ? "none" : "link", detail: where };
+    if (pending.length > 0) return { action: "link", detail };
+    // Nothing to link, but something to retire: `update` is the table's word
+    // for "this row has work that is not a fresh install".
+    if (stale.length > 0) return { action: "update", detail };
+    return { action: "none", detail };
   },
-  removalPlan: (d, _band, roots) => {
+  removalPlan: (d, _scope, roots) => {
     const owned = ownedSkillLinks(d);
     if (owned.length === 0) {
       return { action: "none", detail: "no link to remove" };
     }
-    const dirs = [...new Set(owned.map((a) => shortenPath(a.linkPath, roots)))];
+    // Dedupe to the FOLDERS the links live in — `linkPath` itself is one path
+    // per link, so a Set over it deduped nothing and the removal preview
+    // printed an 18-path wall where the forward plan says `… → 2 folders`.
+    const dirs = [
+      ...new Set(owned.map((a) => shortenPath(dirname(a.linkPath), roots))),
+    ];
     return {
       action: "remove",
       detail: `${owned.length} ${owned.length === 1 ? "link" : "links"}`,
@@ -346,7 +424,7 @@ const skillsTarget = defineTarget<SkillsDetection>({
     };
   },
   compose: (d) => composeSkills(d),
-  composeRemoval: (d) => composeSkillsRemoval(d),
+  composeRemoval: (d, undoKey) => composeSkillsRemoval(d, undoKey),
 });
 
 /** THE table, in display order. */
@@ -362,6 +440,6 @@ export const TARGETS: readonly AnyTarget[] = [
 export const findTarget = (id: string): AnyTarget | undefined =>
   TARGETS.find((target) => target.id === id);
 
-/** Whether a target can be installed into a band. */
-export const supportsBand = (target: AnyTarget, band: ScopeBand): boolean =>
-  target.bands.includes(band);
+/** Whether a target can be installed into a scope. */
+export const supportsScope = (target: AnyTarget, scope: Scope): boolean =>
+  target.scopes.includes(scope);

package/src/capabilities/setup/types.ts

@@ -15,31 +15,23 @@ export type SetupMode =
   | "mcp"
   | "skills";
 
-/**
- * One of the two config bands: the per-user/home `global` band or the per-repo
- * `project` band. Mirrors `@canonical/harnesses`' `ScopeBand` structurally, but
- * is redeclared here so this statically-reachable type module never pulls the
- * harnesses runtime into the fast-path module graph (the lazy-dispatch invariant).
- */
-export type ScopeBand = "project" | "global";
-
-/**
- * The resolved `--scope` selection: which config band(s) a run touches.
- * `global` is the DEFAULT — the user/home band a machine-level installer
- * configures; `project` is the opt-in per-repository band; `both` is the
- * explicit "run each band in one invocation". Structurally mirrors the
- * harnesses `ScopeSelection`.
- */
-export type ScopeSelection = "project" | "global" | "both";
+// The scope types are part of the rendering vocabulary — the one module that
+// owns both the states and the words for them. Re-exported here so setup's
+// type surface stays complete; the definitions (and the structural pin against
+// `@canonical/harnesses`) live with the vocabulary.
+export type {
+  Scope,
+  ScopeSelection,
+} from "../../kernel/render/vocabulary.js";
 
 /**
  * The prior state of an MCP target file, read up front by `detectMcp`:
- * `absent` (no pragma entry yet), `configured` (a matching pragma entry already
+ * `absent` (no pragma entry yet), `registered` (a matching pragma entry already
  * present in every write — a re-run skips it), or `drifted` (a pragma entry
  * exists but differs, so a write updates it). Mirrors the skills step's
  * created/skipped/replaced idempotency at the file grain.
  */
-export type McpTargetState = "absent" | "configured" | "drifted";
+export type McpTargetState = "absent" | "registered" | "drifted";
 
 /**
  * The prior on-disk state of the shell-completion script, read up front by

package/src/capabilities/shared/index.ts

@@ -8,9 +8,11 @@
  * that capability, and the moment something here has a single consumer again
  * it should move back. What survives is the environment the CLI reports on but
  * does not own — how it was installed, what the registry says about it,
- * whether a subprocess it ran actually succeeded — plus the one piece of
- * vocabulary (`BAND_LABELS`) that keeps `setup` and `doctor` calling the two
- * config bands by the same names users meet in the flags.
+ * whether a subprocess it ran actually succeeded. (The scope labels that keep
+ * `setup` and `doctor` calling the two config scopes by the same names used
+ * to live here too; they are part of the rendering vocabulary now —
+ * `kernel/render/vocabulary.ts` — beside the statuses and glyphs they are
+ * printed with.)
  *
  * The exec guard is exported as the pair a caller needs together: `checkExecOk`
  * to classify a result inside a Task and `assertExecOk` to throw on one
@@ -23,10 +25,20 @@
 export {
   assertExecOk,
   checkExecOk,
+  failPragma,
   guardMissingBinary,
 } from "./assertExecOk.js";
-export { BAND_LABELS } from "./bands.js";
-export type { InstallSource } from "./packageManager.js";
-export { detectInstallSource, pmUpdateCommand } from "./packageManager.js";
+export type {
+  EphemeralRunner,
+  GlobalInstall,
+  InstallProbe,
+  InstallSource,
+  PackageManager,
+} from "./packageManager.js";
+export {
+  detectInstallSource,
+  pmUpdateCommand,
+  updateGuidance,
+} from "./packageManager.js";
 export type { RegistryCheckResult } from "./registry.js";
 export { checkRegistryVersion, PRAGMA_PACKAGE } from "./registry.js";