@canonical/pragma-cli 0.32.0 → 0.33.0

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

@@ -2,84 +2,261 @@
  * `setup mcp` — register the pragma MCP server in detected AI harnesses.
  *
  * Split into `detectMcp` (harness detection runs FOR REAL up front, via
- * `runTask` over safe reads, so the wizard recap and a `--dry-run` describe
- * writes against the TRUE harness set) and `composeMcp` (a pure, re-runnable
- * write body driven by the harnesses the user SELECTED — the per-harness confirm
- * is gone; selection now comes from the wizard's multiselect). The covenant
- * sub-verb carries no force-flags, so harness selection is detection-only.
+ * `runTask` over safe reads, and the resolved config targets are deduplicated
+ * into per-file {@link TargetGroup}s for the chosen `--scope`) and `composeMcp`
+ * (a pure, re-runnable write body driven by the SELECTED groups). Each write is
+ * a distinct `(path, mcpKey)` so two harnesses sharing a file (VS Code + Cline)
+ * each preserve the other; every group emits a band-prefixed `info()` manifest
+ * line, so the recap and a `--dry-run` show which band each file belongs to.
+ *
+ * Detection ALSO reads each group's existing config (via `readMcpConfigFrom`,
+ * FOR REAL up front) and classifies every group as `absent` (no pragma entry
+ * yet), `configured` (the pragma entry already matches what we'd write), or
+ * `drifted` (a pragma entry exists but differs). The wizard shows that prior
+ * state in each row and DEFAULT-DESELECTS the already-`configured` files; the
+ * write itself stays idempotent (a re-merge of the identical entry is
+ * byte-for-byte), so a re-run is a no-op the recap reports as "unchanged" — the
+ * same state-awareness `setup skills` has always had.
  */
 
-import type { DetectedHarness } from "@canonical/harnesses";
+import type {
+  McpServerConfig,
+  PlatformEnv,
+  TargetGroup,
+} from "@canonical/harnesses";
 import { info, sequence_, type Task, warn } from "@canonical/task";
 import { MCP_SERVER_NAME } from "../../../constants.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import type {
+  ConfiguredTarget,
+  McpTargetState,
+  ScopeSelection,
+} from "../types.js";
 
-/** The `writeMcpConfig` Task-builder, captured from the dynamic harness import. */
-type WriteMcpConfig = typeof import("@canonical/harnesses").writeMcpConfig;
+/** The `writeMcpConfigTargets` builder, captured from the dynamic harness import. */
+type WriteMcpConfigTargets =
+  typeof import("@canonical/harnesses").writeMcpConfigTargets;
 
 /**
- * The detected MCP state: the harnesses found, the project root the config is
- * written against, and the (dynamically imported) config-writer the pure
- * `composeMcp` needs synchronously.
+ * The detected MCP state: the per-file target groups (already scoped to the
+ * requested `--scope`), a by-path map of each group's prior
+ * {@link McpTargetState} (read up front), the project root, and the
+ * (dynamically imported) target-based writer the pure `composeMcp` needs
+ * synchronously. Keeping `groups` a plain {@link TargetGroup}[] leaves every
+ * existing `.groups` consumer (path/harnessNames/scope) unchanged; the state
+ * rides alongside, keyed by the group's `path`.
  */
 export interface McpDetection {
-  readonly harnesses: readonly DetectedHarness[];
+  readonly groups: readonly TargetGroup[];
+  readonly stateByPath: ReadonlyMap<string, McpTargetState>;
   readonly cwd: string;
-  readonly writeMcpConfig: WriteMcpConfig;
+  readonly platform: PlatformEnv;
+  readonly writeMcpConfigTargets: WriteMcpConfigTargets;
+}
+
+/**
+ * The pragma MCP server entry we register — the SINGLE source of truth both the
+ * classifier (does the existing entry match this?) and the writer (`composeMcp`)
+ * consume, so "already configured" means byte-for-byte what a write would emit.
+ *
+ * @param cwd - The project root recorded on the entry.
+ * @returns The pragma {@link McpServerConfig}.
+ */
+export function pragmaMcpEntry(cwd: string): McpServerConfig {
+  return { command: "pragma", args: ["mcp"], cwd };
+}
+
+/**
+ * Whether an existing MCP entry equals the pragma entry we would write, over the
+ * fields we control (`command`/`args`/`cwd`). A shallow structural compare — a
+ * harness that carries extra keys (e.g. `env`) still reads as `configured` as
+ * long as our three fields match, so we never churn a file we did not author.
+ */
+function entryMatches(
+  existing: McpServerConfig,
+  want: McpServerConfig,
+): boolean {
+  const sameArgs =
+    (existing.args ?? []).length === (want.args ?? []).length &&
+    (want.args ?? []).every((a, i) => existing.args?.[i] === a);
+  return (
+    existing.command === want.command && existing.cwd === want.cwd && sameArgs
+  );
+}
+
+/**
+ * Classify one target group against its on-disk config: `absent` when no pragma
+ * entry exists in ANY of the group's writes, `configured` when EVERY write
+ * already carries a matching pragma entry, `drifted` otherwise (present in at
+ * least one write but not matching everywhere). Reads each write's file for real
+ * via `readMcpConfigFrom`.
+ *
+ * @param group - The target group whose writes to inspect.
+ * @param want - The pragma entry a write would emit.
+ * @param readMcpConfigFrom - The harness reader (dynamically imported).
+ * @param runTask - The node Task interpreter.
+ * @returns The group's {@link McpTargetState}.
+ * @note Impure — reads each write's config file.
+ */
+async function classifyGroup(
+  group: TargetGroup,
+  want: McpServerConfig,
+  readMcpConfigFrom: typeof import("@canonical/harnesses").readMcpConfigFrom,
+  runTask: typeof import("@canonical/task/node").runTask,
+): Promise<McpTargetState> {
+  let present = 0;
+  let matching = 0;
+  for (const write of group.writes) {
+    const servers = await runTask(readMcpConfigFrom(write));
+    const existing = servers[MCP_SERVER_NAME];
+    if (existing === undefined) continue;
+    present += 1;
+    if (entryMatches(existing, want)) matching += 1;
+  }
+  if (present === 0) return "absent";
+  if (matching === group.writes.length) return "configured";
+  return "drifted";
 }
 
 /**
- * Detect the AI harnesses present in the project (real reads, up front).
+ * Detect the AI harnesses present in the project (real reads, up front),
+ * resolve+dedup their config targets for the chosen scope, AND read each
+ * group's existing config to classify it `absent`/`configured`/`drifted` — so
+ * the wizard can show prior state and default-deselect already-`configured`
+ * files.
  *
  * @param rt - The per-invocation runtime.
- * @returns The detected harnesses + the writer used to compose config writes.
- * @note Impure — reads the filesystem via `detectHarnesses`.
+ * @param scope - The resolved `--scope` selection.
+ * @returns The scoped target groups, their prior states, + the config writer.
+ * @note Impure — reads the filesystem via `detectHarnesses` + `readMcpConfigFrom`.
  */
-export async function detectMcp(rt: PragmaRuntime): Promise<McpDetection> {
+export async function detectMcp(
+  rt: PragmaRuntime,
+  scope: ScopeSelection,
+): Promise<McpDetection> {
   const cwd = rt.cwd;
-  const [{ detectHarnesses, writeMcpConfig }, { runTask }] = await Promise.all([
+  const [
+    {
+      detectHarnesses,
+      groupTargetsForScope,
+      readMcpConfigFrom,
+      readPlatformEnv,
+      writeMcpConfigTargets,
+    },
+    { runTask },
+  ] = await Promise.all([
     import("@canonical/harnesses"),
     import("@canonical/task/node"),
   ]);
-  const harnesses = await runTask(detectHarnesses(cwd));
-  return { harnesses, cwd, writeMcpConfig };
+  const platform = readPlatformEnv();
+  const detected = await runTask(detectHarnesses(cwd, platform));
+  const groups = groupTargetsForScope(detected, cwd, scope, platform);
+
+  // Read each group's existing config (for real, up front) so the recap/preview
+  // and the default selection reflect true prior state — the same discipline
+  // `detectSkills` uses for its per-link create/skip/replace decision.
+  const want = pragmaMcpEntry(cwd);
+  const stateByPath = new Map<string, McpTargetState>();
+  await Promise.all(
+    groups.map(async (group) => {
+      const state = await classifyGroup(
+        group,
+        want,
+        readMcpConfigFrom,
+        runTask,
+      );
+      stateByPath.set(group.path, state);
+    }),
+  );
+
+  return { groups, stateByPath, cwd, platform, writeMcpConfigTargets };
+}
+
+/**
+ * The prior state of a group, defaulting to `absent` for an unknown path (so a
+ * caller never has to guard the map lookup).
+ */
+export function mcpGroupState(d: McpDetection, path: string): McpTargetState {
+  return d.stateByPath.get(path) ?? "absent";
+}
+
+/** The target groups the user selected (by path), or all when none recorded. */
+export function selectedGroups(
+  d: McpDetection,
+  selectedPaths: readonly string[],
+): TargetGroup[] {
+  return d.groups.filter((g) => selectedPaths.includes(g.path));
 }
 
 /**
- * Compose the per-harness config writes for the SELECTED harnesses (pure —
- * re-runnable; builds ABSOLUTE config paths itself).
+ * Compose the per-target config writes for the SELECTED groups (pure —
+ * re-runnable; builds ABSOLUTE config paths itself). The prior
+ * {@link McpTargetState} drives the manifest MESSAGE (already-configured /
+ * updated / added) but NOT whether the write runs: the idempotent
+ * read-modify-write is always composed so it carries its `undo` and a re-run is
+ * byte-identical when already `configured`. The wizard already default-DESELECTS
+ * `configured` files (so they are usually not in `groups` at all); a `configured`
+ * file that IS selected is still rewritten idempotently.
  *
  * @param d - The detection gathered up front.
- * @param selectedIds - Harness ids the user chose (a subset of `d.harnesses`).
- * @returns A Task that writes the pragma MCP config into each chosen harness.
+ * @param groups - The target groups the user chose (a subset of `d.groups`).
+ * @returns A Task that writes the pragma MCP config into each chosen file.
  */
 export function composeMcp(
   d: McpDetection,
-  selectedIds: readonly string[],
+  groups: readonly TargetGroup[],
 ): Task<void> {
-  const chosen = d.harnesses.filter((h) => selectedIds.includes(h.harness.id));
-  if (chosen.length === 0) {
+  if (groups.length === 0) {
     return warn("No AI harnesses selected — nothing to configure.");
   }
-  const pragmaMcpConfig = { command: "pragma", args: ["mcp"], cwd: d.cwd };
+  const pragmaMcpConfig = pragmaMcpEntry(d.cwd);
   // Re-runnable combinators (NOT a single-use `gen`): `execute` interprets the
-  // task twice (preview + perform).
+  // task twice (preview + perform). One combined write per file keeps a shared
+  // file (VS Code + Cline) a single read-modify-write — dry-run safe.
   const tasks: Task<unknown>[] = [];
-  for (const h of chosen) {
+  for (const group of groups) {
+    const state = mcpGroupState(d, group.path);
+    const names = group.harnessNames.join(", ");
+    tasks.push(
+      d.writeMcpConfigTargets(group.writes, MCP_SERVER_NAME, pragmaMcpConfig),
+    );
+    const verb =
+      state === "configured"
+        ? "already configured →"
+        : state === "drifted"
+          ? "updated →"
+          : "→";
     tasks.push(
-      d.writeMcpConfig(h.harness, d.cwd, MCP_SERVER_NAME, pragmaMcpConfig),
+      info(
+        `[${group.scope}] pragma MCP server ${verb} ${group.path} (${names})`,
+      ),
     );
-    tasks.push(info(`✓ pragma MCP server added to ${h.configPath}`));
   }
   return sequence_(tasks);
 }
 
-/** The harness names configured for a given selection (for the result shape). */
-export function mcpConfigured(
+/** The harness names configured across a selection (for the result summary). */
+export function mcpConfigured(groups: readonly TargetGroup[]): string[] {
+  const names = new Set<string>();
+  for (const group of groups) {
+    for (const name of group.harnessNames) names.add(name);
+  }
+  return [...names].sort();
+}
+
+/**
+ * The per-file {@link ConfiguredTarget}s for a selection (for the result), each
+ * carrying its prior {@link McpTargetState} so the recap distinguishes newly
+ * added, updated, and already-configured targets.
+ */
+export function mcpTargets(
   d: McpDetection,
-  selectedIds: readonly string[],
-): string[] {
-  return d.harnesses
-    .filter((h) => selectedIds.includes(h.harness.id))
-    .map((h) => h.harness.name);
+  groups: readonly TargetGroup[],
+): ConfiguredTarget[] {
+  return groups.map((group) => ({
+    name: group.harnessNames.join(", "),
+    band: group.scope,
+    path: group.path,
+    state: mcpGroupState(d, group.path),
+  }));
 }

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

@@ -148,6 +148,10 @@ export async function detectSkills(
  * interprets the task twice (preview + perform). `created` links carry an undo;
  * a `replaced` link is delete-then-relink (idempotent); `skipped` is a no-op.
  *
+ * FOLLOW-UP(AV-284): global-band skills — skills only link into per-project
+ * harness dirs today; a `--scope global` machine-band skills location is
+ * deferred. The manifest line is `[project]`-prefixed to make that explicit.
+ *
  * @param d - The detection gathered up front.
  * @returns A Task that mkdirs each target and creates/replaces each symlink.
  */
@@ -168,7 +172,9 @@ export function composeSkills(d: SkillsDetection): Task<void> {
     }
   }
   tasks.push(
-    info(`Linked ${d.skillCount} skill(s) into ${d.targets.length} dir(s).`),
+    info(
+      `[project] Linked ${d.skillCount} skill(s) into ${d.targets.length} dir(s).`,
+    ),
   );
   return sequence_(tasks);
 }

package/src/capabilities/setup/setup.render.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Render goldens for `pragma setup` — the MCP recap grouped by band.
+ *
+ * `summarizeMcpTargets` (the recap's band grouping) previously shipped
+ * executed-but-never-asserted; this pins the ACTUAL banded recap text for BOTH
+ * the plain and llm formatters, and locks the unified Global/Project vocabulary
+ * (the recap no longer says MACHINE/PROJECT). The setup formatters use no
+ * colour, so no chalk level dance is needed.
+ */
+
+import { describe, expect, it } from "vitest";
+import { setupFormatters } from "./setup.render.js";
+import type { SetupResult } from "./types.js";
+
+/**
+ * A two-band MCP result: a global (Windsurf) and a project (Cursor) target,
+ * both newly `absent`→added — the clean first-run recap (no state tally).
+ */
+const BOTH_BANDS: SetupResult = {
+  kind: "mcp",
+  configured: ["Cursor", "Windsurf"],
+  targets: [
+    {
+      name: "Windsurf",
+      band: "global",
+      path: "/home/u/.codeium/windsurf/mcp_config.json",
+      state: "absent",
+    },
+    {
+      name: "Cursor",
+      band: "project",
+      path: "/proj/.cursor/mcp.json",
+      state: "absent",
+    },
+  ],
+};
+
+describe("setup render — MCP recap banded by Global/Project", () => {
+  it("plain lists the global band before the project band", () => {
+    expect(setupFormatters.plain(BOTH_BANDS)).toBe(
+      "Configured MCP — Global: Windsurf · Project: Cursor.",
+    );
+  });
+
+  it("llm is the same banded recap prefixed with a bullet", () => {
+    expect(setupFormatters.llm(BOTH_BANDS)).toBe(
+      "- Configured MCP — Global: Windsurf · Project: Cursor.",
+    );
+  });
+
+  it("uses the unified labels, never MACHINE/PROJECT", () => {
+    const out = setupFormatters.plain(BOTH_BANDS);
+    expect(out).not.toContain("MACHINE");
+    expect(out).not.toContain("PROJECT");
+  });
+
+  it("a single-band selection lists only that band", () => {
+    const projectOnly: SetupResult = {
+      kind: "mcp",
+      configured: ["Cursor"],
+      targets: [
+        {
+          name: "Cursor",
+          band: "project",
+          path: "/p/.cursor/mcp.json",
+          state: "absent",
+        },
+      ],
+    };
+    expect(setupFormatters.plain(projectOnly)).toBe(
+      "Configured MCP — Project: Cursor.",
+    );
+  });
+
+  it("appends the state tally when a target was already present (re-run)", () => {
+    // A mix of already-configured + drifted + newly-added surfaces the
+    // idempotency breakdown, so a re-run reads as a no-op rather than a rewrite.
+    const rerun: SetupResult = {
+      kind: "mcp",
+      configured: ["Cursor", "Windsurf"],
+      targets: [
+        {
+          name: "Windsurf",
+          band: "global",
+          path: "/home/u/.codeium/windsurf/mcp_config.json",
+          state: "configured",
+        },
+        {
+          name: "Cursor",
+          band: "project",
+          path: "/proj/.cursor/mcp.json",
+          state: "drifted",
+        },
+      ],
+    };
+    expect(setupFormatters.plain(rerun)).toBe(
+      "Configured MCP — Global: Windsurf · Project: Cursor (0 added, 1 updated, 1 unchanged).",
+    );
+  });
+
+  it("no targets → a plain 'nothing configured' line", () => {
+    const none: SetupResult = { kind: "mcp", configured: [], targets: [] };
+    expect(setupFormatters.plain(none)).toBe("No harnesses configured.");
+  });
+
+  it("json is the exact SetupResult round-trip", () => {
+    expect(JSON.parse(setupFormatters.json(BOTH_BANDS))).toEqual(BOTH_BANDS);
+  });
+});

package/src/capabilities/setup/setup.render.ts

@@ -4,31 +4,78 @@
  */
 
 import type { Formatters } from "../../kernel/spec/types.js";
-import type { SetupResult, SetupSkillsResult } from "./types.js";
+import { BAND_LABELS } from "../shared/bands.js";
+import type {
+  ConfiguredTarget,
+  SetupResult,
+  SetupSkillsResult,
+} from "./types.js";
 
 /** Summarize a skills result: created / skipped / replaced counts. */
-function skillsSummary(result: SetupSkillsResult): string {
+function summarizeSkills(result: SetupSkillsResult): string {
   const created = result.actions.filter((a) => a.action === "created").length;
   const skipped = result.actions.filter((a) => a.action === "skipped").length;
   const replaced = result.actions.filter((a) => a.action === "replaced").length;
   return `${created} created, ${replaced} replaced, ${skipped} unchanged across ${result.harnessCount} harness(es)`;
 }
 
+/**
+ * Summarize the MCP targets grouped by band — the global (user/home) band
+ * before the project (per-repo) band — so the recap shows which files at which
+ * level got the pragma server. The Global/Project labels match the doctor
+ * report and the CLI's `--global`/`--local` grammar (see {@link BAND_LABELS}).
+ *
+ * A trailing state tally is appended ONLY when something was already present
+ * (an `updated` or `unchanged` target) — a clean first run (every target newly
+ * `added`) keeps the plain `Configured MCP — …` line, so the idempotency detail
+ * surfaces exactly when it is informative (a re-run made clear it was a no-op).
+ */
+function summarizeMcpTargets(targets: readonly ConfiguredTarget[]): string {
+  if (targets.length === 0) return "No harnesses configured.";
+  const section = (band: ConfiguredTarget["band"], label: string): string => {
+    const names = targets.filter((t) => t.band === band).map((t) => t.name);
+    return names.length > 0 ? `${label}: ${names.join(", ")}` : "";
+  };
+  const parts = [
+    section("global", BAND_LABELS.global),
+    section("project", BAND_LABELS.project),
+  ]
+    .filter((p) => p.length > 0)
+    .join(" · ");
+  const updated = targets.filter((t) => t.state === "drifted").length;
+  const unchanged = targets.filter((t) => t.state === "configured").length;
+  if (updated === 0 && unchanged === 0) {
+    // Clean first run — every target newly added; keep the original recap line.
+    return `Configured MCP — ${parts}.`;
+  }
+  const added = targets.filter((t) => t.state === "absent").length;
+  return `Configured MCP — ${parts} (${added} added, ${updated} updated, ${unchanged} unchanged).`;
+}
+
 /** Render a setup result to a single human line (shared by plain/llm). */
-function line(data: SetupResult): string {
+function renderSetupLine(data: SetupResult): string {
   switch (data.kind) {
-    case "completions":
-      return data.installed
-        ? `Installed ${data.shell} completions at ${data.path}.`
-        : "No shell detected — completions were not installed.";
+    case "completions": {
+      if (!data.installed) {
+        return "No shell detected — completions were not installed.";
+      }
+      switch (data.state) {
+        case "installed":
+          return `${data.shell} completions already up to date at ${data.path}.`;
+        case "stale":
+          return `Updated ${data.shell} completions at ${data.path}.`;
+        default:
+          return `Installed ${data.shell} completions at ${data.path}.`;
+      }
+    }
     case "lsp":
-      return "Terrazzo LSP extension is installed (up to date).";
+      return data.state === "installed"
+        ? "Terrazzo LSP extension already installed (up to date)."
+        : "Terrazzo LSP extension is installed (up to date).";
     case "mcp":
-      return data.configured.length > 0
-        ? `Configured MCP for: ${data.configured.join(", ")}.`
-        : "No harnesses configured.";
+      return summarizeMcpTargets(data.targets);
     case "skills":
-      return `Skills: ${skillsSummary(data.result)}.`;
+      return `Skills: ${summarizeSkills(data.result)}.`;
     case "all":
       return data.steps.length > 0
         ? `Setup complete — ran: ${data.steps.join(", ")}.`
@@ -38,10 +85,10 @@ function line(data: SetupResult): string {
 
 export const setupFormatters: Formatters<SetupResult> = {
   plain(data) {
-    return line(data);
+    return renderSetupLine(data);
   },
   llm(data) {
-    return `- ${line(data)}`;
+    return `- ${renderSetupLine(data)}`;
   },
   json(data) {
     return JSON.stringify(data);