@canonical/pragma-cli 0.32.0 → 0.33.0

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

@@ -11,6 +11,12 @@
  * it more than once (the confirm-gate preview + the build), so all real reads
  * belong in detection, never in `generate`.
  *
+ * 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.
+ *
  * 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
  * literals over `@canonical/task`. It is itself reached only through the verb's
@@ -24,18 +30,26 @@ import type {
 import { sequence_, type Task, when } from "@canonical/task";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
 import { guardMissingBinary } from "../../shared/assertExecOk.js";
-import type { SetupMode, SetupResult } from "../types.js";
+import type {
+  LspState,
+  ScopeSelection,
+  SetupMode,
+  SetupResult,
+} from "../types.js";
 import {
   type CompletionsDetection,
   composeCompletions,
   detectCompletions,
 } from "./setupCompletions.js";
-import { composeLsp } from "./setupLsp.js";
+import { composeLsp, detectLsp, type LspDetection } from "./setupLsp.js";
 import {
   composeMcp,
   detectMcp,
   type McpDetection,
   mcpConfigured,
+  mcpGroupState,
+  mcpTargets,
+  selectedGroups,
 } from "./setupMcp.js";
 import {
   composeSkills,
@@ -61,22 +75,29 @@ export interface SetupPlan {
 /** 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;
 }
 
 /** Read `answers.steps` (the run-all multiselect) as a string array. */
-const stepsOf = (answers: Record<string, unknown>): string[] =>
+const readSteps = (answers: Record<string, unknown>): string[] =>
   Array.isArray(answers.steps) ? (answers.steps as string[]) : [];
 
-/** Read `answers.mcpHarnesses`, falling back to ALL detected ids. */
-const mcpSelection = (
+/** Read `answers.mcpTargets` (selected file paths), falling back to ALL files. */
+const resolveMcpPaths = (
   d: McpDetection,
   answers: Record<string, unknown>,
 ): string[] =>
-  Array.isArray(answers.mcpHarnesses)
-    ? (answers.mcpHarnesses as string[])
-    : d.harnesses.map((h) => h.harness.id);
+  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));
 
 /**
  * The LSP-install step, guarded at its use site. An absent `bunx` (no Bun on
@@ -87,18 +108,18 @@ const mcpSelection = (
  * exec (no spawn) — and re-runnable (the guard is a `recover`, and `composeLsp`
  * is combinator-built), so it survives `execute`'s double interpretation.
  */
-const composeGuardedLsp = (rt: PragmaRuntime): Task<void> =>
+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),
+    composeLsp(rt.cwd, state),
   );
 
 /** Build a generator's `meta` (no stamping — the version is just header text). */
-const metaFor = (
+const buildMeta = (
   rt: PragmaRuntime,
   title: string,
 ): GeneratorDefinition["meta"] => ({
@@ -108,20 +129,50 @@ const metaFor = (
   version: rt.version,
 });
 
-/** The MCP-harness multiselect follow-up (offered only when harnesses exist). */
-const mcpHarnessesPrompt = (
+/** 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 pragma configures?",
+  default: false,
+  when,
+});
+
+/** 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 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.
+ */
+const buildMcpTargetsPrompt = (
   d: McpDetection,
   when?: PromptDefinition["when"],
 ): PromptDefinition => ({
-  name: "mcpHarnesses",
+  name: "mcpTargets",
   type: "multiselect",
-  message: "Configure MCP for which harnesses?",
+  message: "Configure MCP for which files?",
   when,
-  choices: d.harnesses.map((h) => ({
-    label: h.harness.name,
-    value: h.harness.id,
+  choices: d.groups.map((g) => ({
+    label: `${g.path} — ${g.harnessNames.join(", ")} [${g.scope}]${mcpStateSuffix(d, g.path)}`,
+    value: g.path,
   })),
-  default: d.harnesses.map((h) => h.harness.id),
+  default: d.groups
+    .filter((g) => mcpGroupState(d, g.path) !== "configured")
+    .map((g) => g.path),
 });
 
 // =============================================================================
@@ -129,39 +180,55 @@ const mcpHarnessesPrompt = (
 // =============================================================================
 
 /** Gather EVERY step's detection up front (real reads), for the run-all. */
-async function gatherDetection(rt: PragmaRuntime): Promise<SetupDetection> {
-  const [completions, mcp, skills] = await Promise.all([
+async function gatherDetection(
+  rt: PragmaRuntime,
+  scope: ScopeSelection,
+): Promise<SetupDetection> {
+  const [completions, lsp, mcp, skills] = await Promise.all([
     detectCompletions(rt.cwd),
-    detectMcp(rt),
+    detectLsp(rt.cwd),
+    detectMcp(rt, scope),
     detectSkills(rt),
   ]);
-  return { completions, mcp, skills };
+  return { completions, lsp, mcp, skills };
 }
 
 /**
- * The steps worth OFFERING, given detection — undetectable steps are omitted so
- * the run-all degrades gracefully instead of throwing a mid-wizard
- * EMPTY_RESULTS (skills with no skills, mcp with no harnesses, completions with
- * no shell). LSP is always offered (its install is a self-contained exec).
+ * 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}.
+ *
+ * @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.
  */
-function availableSteps(
+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) {
+  if (detected.completions.shell && hasGlobal) {
     choices.push({
       label: `Shell completions (${detected.completions.shell})`,
       value: "completions",
     });
   }
-  choices.push({ label: "Terrazzo LSP extension", value: "lsp" });
-  if (detected.mcp.harnesses.length > 0) {
+  if (hasGlobal) {
+    choices.push({ label: "Terrazzo LSP extension", value: "lsp" });
+  }
+  if (detected.mcp.groups.length > 0) {
     choices.push({
-      label: `MCP config (${detected.mcp.harnesses.length} harness(es))`,
+      label: `MCP config (${detected.mcp.groups.length} file(s))`,
       value: "mcp",
     });
   }
-  if (detected.skills.available) {
+  if (detected.skills.available && hasProject) {
     choices.push({
       label: `Link skills (${detected.skills.skillCount})`,
       value: "skills",
@@ -174,9 +241,18 @@ function availableSteps(
 // Plan builders
 // =============================================================================
 
-/** The run-all self-verb: a step multiselect + per-step composition. */
-function runAllPlan(rt: PragmaRuntime, detected: SetupDetection): SetupPlan {
-  const steps = availableSteps(detected);
+/**
+ * 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.
+ */
+function buildRunAllPlan(
+  rt: PragmaRuntime,
+  detected: SetupDetection,
+  scope: ScopeSelection,
+): SetupPlan {
+  const steps = listAvailableSteps(detected, scope);
   const prompts: PromptDefinition[] = [
     {
       name: "steps",
@@ -186,11 +262,16 @@ function runAllPlan(rt: PragmaRuntime, detected: SetupDetection): SetupPlan {
       default: steps.map((c) => c.value), // --yes / non-TTY ⇒ every step
     },
   ];
-  if (detected.mcp.harnesses.length > 0) {
+  // 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(
-      mcpHarnessesPrompt(
+      buildCustomizePrompt((a) => readSteps(a).includes("mcp")),
+      buildMcpTargetsPrompt(
         detected.mcp,
-        (a) => stepsOf(a).includes("mcp"), // only when mcp is chosen
+        (a) => a.customize === true && readSteps(a).includes("mcp"),
       ),
     );
   }
@@ -201,19 +282,19 @@ function runAllPlan(rt: PragmaRuntime, detected: SetupDetection): SetupPlan {
   // reads already happened up front). Composing an unchosen step is harmless:
   // `when(false, …)` discards the (side-effect-free) task it was handed.
   const generator: GeneratorDefinition = {
-    meta: metaFor(rt, "pragma setup"),
+    meta: buildMeta(rt, "pragma setup"),
     prompts,
     generate: (answers) => {
-      const chosen = stepsOf(answers);
+      const chosen = readSteps(answers);
       return sequence_([
         when(
           chosen.includes("completions"),
           composeCompletions(detected.completions),
         ),
-        when(chosen.includes("lsp"), composeGuardedLsp(rt)),
+        when(chosen.includes("lsp"), composeGuardedLsp(rt, detected.lsp.state)),
         when(
           chosen.includes("mcp"),
-          composeMcp(detected.mcp, mcpSelection(detected.mcp, answers)),
+          composeMcp(detected.mcp, selectChosenGroups(detected.mcp, answers)),
         ),
         when(chosen.includes("skills"), composeSkills(detected.skills)),
       ]);
@@ -222,18 +303,18 @@ function runAllPlan(rt: PragmaRuntime, detected: SetupDetection): SetupPlan {
 
   return {
     generator,
-    toResult: (answers) => ({ kind: "all", steps: stepsOf(answers) }),
+    toResult: (answers) => ({ kind: "all", steps: readSteps(answers) }),
   };
 }
 
 /** A single-step generator (no run-all multiselect) for one sub-verb. */
-function singleStep(
+function buildSingleStep(
   rt: PragmaRuntime,
   title: string,
   prompts: PromptDefinition[],
   generate: (answers: Record<string, unknown>) => Task<void>,
 ): GeneratorDefinition {
-  return { meta: metaFor(rt, title), prompts, generate };
+  return { meta: buildMeta(rt, title), prompts, generate };
 }
 
 /**
@@ -244,6 +325,7 @@ function singleStep(
  *
  * @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.
@@ -251,15 +333,16 @@ function singleStep(
 export async function buildSetupPlan(
   rt: PragmaRuntime,
   mode: SetupMode,
+  scope: ScopeSelection,
 ): Promise<SetupPlan> {
   switch (mode) {
     case "all":
-      return runAllPlan(rt, await gatherDetection(rt));
+      return buildRunAllPlan(rt, await gatherDetection(rt, scope), scope);
 
     case "completions": {
       const d = await detectCompletions(rt.cwd);
       return {
-        generator: singleStep(rt, "pragma setup completions", [], () =>
+        generator: buildSingleStep(rt, "pragma setup completions", [], () =>
           composeCompletions(d),
         ),
         toResult: () => ({
@@ -267,29 +350,42 @@ export async function buildSetupPlan(
           shell: d.shell,
           path: d.path,
           installed: d.shell !== null,
+          state: d.state,
         }),
       };
     }
 
-    case "lsp":
+    case "lsp": {
+      const d = await detectLsp(rt.cwd);
       return {
-        generator: singleStep(rt, "pragma setup lsp", [], () =>
-          composeGuardedLsp(rt),
+        generator: buildSingleStep(rt, "pragma setup lsp", [], () =>
+          composeGuardedLsp(rt, d.state),
         ),
-        toResult: () => ({ kind: "lsp" }),
+        toResult: () => ({ kind: "lsp", state: d.state }),
       };
+    }
 
     case "mcp": {
-      const d = await detectMcp(rt);
-      const prompts = d.harnesses.length > 0 ? [mcpHarnessesPrompt(d)] : [];
+      const d = await detectMcp(rt, scope);
+      const prompts: PromptDefinition[] =
+        d.groups.length > 0
+          ? [
+              buildCustomizePrompt(),
+              buildMcpTargetsPrompt(d, (a) => a.customize === true),
+            ]
+          : [];
       return {
-        generator: singleStep(rt, "pragma setup mcp", prompts, (answers) =>
-          composeMcp(d, mcpSelection(d, answers)),
+        generator: buildSingleStep(rt, "pragma setup mcp", prompts, (answers) =>
+          composeMcp(d, selectChosenGroups(d, answers)),
         ),
-        toResult: (answers) => ({
-          kind: "mcp",
-          configured: mcpConfigured(d, mcpSelection(d, answers)),
-        }),
+        toResult: (answers) => {
+          const sel = selectChosenGroups(d, answers);
+          return {
+            kind: "mcp",
+            configured: mcpConfigured(sel),
+            targets: mcpTargets(d, sel),
+          };
+        },
       };
     }
 
@@ -297,7 +393,7 @@ export async function buildSetupPlan(
       const d = await detectSkills(rt);
       if (!d.available) throw skillsEmptyError();
       return {
-        generator: singleStep(rt, "pragma setup skills", [], () =>
+        generator: buildSingleStep(rt, "pragma setup skills", [], () =>
           composeSkills(d),
         ),
         toResult: () => ({ kind: "skills", result: toSkillsResult(d) }),

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

@@ -1,10 +1,13 @@
 /**
  * `setup lsp` — ensure the Terrazzo LSP VS Code extension is installed.
  *
- * There is nothing to detect (the installer is a single idempotent `exec`), so
- * `detectLsp` is a trivial marker and `composeLsp` holds the sole mutation —
- * mocked under `--dry-run`, run for real otherwise. A successful run reports it
- * installed (up to date), not a fresh install.
+ * `detectLsp` probes for the extension FOR REAL up front — it runs
+ * `code --list-extensions` (via the `exec` seam, over `runTask`) and matches the
+ * `terrazzo` extension id — so a re-run of an already-installed extension is a
+ * true no-op and the recap says so, rather than always shelling out. When the
+ * `code` CLI is absent from PATH the state is `unknown` (we cannot enumerate,
+ * so the installer still runs). `composeLsp` holds the sole mutation, mocked
+ * under `--dry-run` and skipped when detection already found the extension.
  */
 
 import {
@@ -17,18 +20,51 @@ import {
   type Task,
 } from "@canonical/task";
 import { assertExecOk } from "../../shared/assertExecOk.js";
+import type { LspState } from "../types.js";
 
-/** LSP has no real detection — the install is one idempotent subprocess. */
+/** The VS Code CLI queried for the installed-extensions list. */
+const VSCODE_CLI = "code";
+
+/** The substring an installed Terrazzo extension id contains (publisher-agnostic). */
+const TERRAZZO_EXTENSION_MATCH = "terrazzo";
+
+/**
+ * The detected LSP state: whether the Terrazzo extension is already `installed`,
+ * `absent`, or `unknown` (the `code` CLI is not on PATH, so we cannot enumerate).
+ */
 export interface LspDetection {
   readonly available: true;
+  readonly state: LspState;
 }
 
 /**
- * "Detect" the LSP step. Always available — kept for symmetry with the other
- * steps' detect phase (so the run-all can gather every step uniformly).
+ * Probe VS Code for the Terrazzo extension. Runs `code --list-extensions` and
+ * matches the `terrazzo` id; an absent `code` CLI (spawn ENOENT) or a nonzero
+ * exit yields `unknown` (we fall through to running the installer).
+ *
+ * @param cwd - The directory the probe runs in.
+ * @returns The detected {@link LspState}.
+ * @note Impure — spawns `code --list-extensions`.
  */
-export function detectLsp(): LspDetection {
-  return { available: true };
+export async function detectLsp(cwd: string): Promise<LspDetection> {
+  const { runTask } = await import("@canonical/task/node");
+  let state: LspState = "unknown";
+  try {
+    const result = (await runTask(
+      exec(VSCODE_CLI, ["--list-extensions"], cwd),
+    )) as ExecResult;
+    if (result.exitCode === 0) {
+      const installed = result.stdout
+        .toLowerCase()
+        .includes(TERRAZZO_EXTENSION_MATCH);
+      state = installed ? "installed" : "absent";
+    }
+  } catch {
+    // `code` absent from PATH (ENOENT) or any spawn failure → we cannot tell;
+    // leave `unknown` so the installer still runs.
+    state = "unknown";
+  }
+  return { available: true, state };
 }
 
 /**
@@ -37,12 +73,20 @@ export function detectLsp(): LspDetection {
  * Built from re-runnable combinators (NOT a single-use `gen`) because `execute`
  * interprets the task twice (preview + perform). Under the dry-run preview the
  * `exec` is MOCKED to `exitCode 0`, so `assertExecOk` passes there; a real run's
- * nonzero exit still fails loudly.
+ * nonzero exit still fails loudly. When detection already found the extension
+ * `installed`, the install is SKIPPED — a re-run is a true no-op.
  *
  * @param cwd - The directory to run the installer in.
- * @returns A Task that execs the extension installer, failing loudly on nonzero.
+ * @param state - The prior state from {@link detectLsp} (defaults to `unknown`).
+ * @returns A Task that execs the installer (or reports already-installed).
  */
-export function composeLsp(cwd: string): Task<void> {
+export function composeLsp(
+  cwd: string,
+  state: LspState = "unknown",
+): Task<void> {
+  if (state === "installed") {
+    return info("Terrazzo LSP VS Code extension already installed — skipped.");
+  }
   return sequence_([
     info("Ensuring the Terrazzo LSP VS Code extension is installed..."),
     // The interpreter RESOLVES on a nonzero exit — a failed installer must fail