@canonical/pragma-cli 0.34.0 → 0.36.0

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

@@ -1,109 +1,331 @@
 /**
- * Render goldens for `pragma setup` — the MCP recap grouped by band.
+ * Render goldens for `pragma setup` — the plan, the progress lines, the recap.
  *
- * `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.
+ * These three used to be three unrelated renderers over a tagged result union
+ * with one member per sub-verb, and the run-all's member carried only a list of
+ * step NAMES: a run could report "Setup complete — ran: completions, lsp, mcp"
+ * while silently having dropped a target it could not offer. The goldens below
+ * pin the property that replaces that — the preview, the progress stream and
+ * the recap are the SAME rows — by rendering ONE plan three ways and asserting
+ * every byte of each.
+ *
+ * The formatters take an injected style, and `defaultStyle()` is the identity
+ * styler off a TTY, so no chalk-level dance is needed.
  */
 
+import { join, sep } from "node:path";
 import { describe, expect, it } from "vitest";
-import { setupFormatters } from "./setup.render.js";
-import type { SetupResult } from "./types.js";
+import { type PlanRow, type SetupPlan, shortenPath } from "./plan.js";
+import {
+  renderPlanTable,
+  renderProgressLine,
+  renderRecap,
+} from "./plan.render.js";
+import { PREVIEW_HINT, renderDryRun, setupFormatters } from "./setup.render.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",
-    },
-  ],
+const ROOTS = { global: "/home/u", project: "/home/u/src/app" };
+
+/** The five rows a first global run produces on a machine with no editor. */
+const ROWS: PlanRow[] = [
+  {
+    target: "config",
+    scope: "global",
+    action: "none",
+    detail: "~/.config/pragma/config.json — present",
+    selected: false,
+  },
+  {
+    target: "completions",
+    scope: "global",
+    action: "install",
+    detail: "bash → ~/.local/share/bash-completion/completions/pragma",
+    selected: true,
+  },
+  {
+    target: "lsp",
+    scope: "global",
+    action: "skip",
+    detail:
+      "no VS Code-family editor CLI on PATH (code, codium, cursor, windsurf)",
+    reason:
+      "no VS Code-family editor CLI on PATH (code, codium, cursor, windsurf)",
+    selected: false,
+  },
+  {
+    target: "mcp",
+    scope: "global",
+    action: "update",
+    detail: "2 config files",
+    children: [
+      { key: "/home/u/.claude.json", label: "~/.claude.json", action: "add" },
+      {
+        key: "/home/u/.codeium/windsurf/mcp_config.json",
+        label: "~/.codeium/windsurf/mcp_config.json",
+        action: "add",
+      },
+    ],
+    selected: true,
+  },
+  {
+    target: "skills",
+    scope: "global",
+    action: "link",
+    detail: "2 skills → 2 folders (~/.claude/skills, ~/.agents/skills)",
+    selected: true,
+  },
+];
+
+const PLAN: SetupPlan = { scope: "global", roots: ROOTS, rows: ROWS };
+
+/** The same plan after a run: outcomes filled in, nothing else changed. */
+const APPLIED: SetupPlan = {
+  ...PLAN,
+  rows: ROWS.map((row): PlanRow => {
+    if (row.target === "lsp") {
+      return {
+        ...row,
+        outcome: {
+          status: "skipped",
+          remedy:
+            "no action is possible on this machine yet — install VS Code or VSCodium, then run this again",
+        },
+      };
+    }
+    if (row.target === "config") return { ...row, outcome: { status: "noop" } };
+    if (row.target === "mcp") {
+      return { ...row, outcome: { status: "done", note: "2 added" } };
+    }
+    if (row.target === "completions") {
+      return { ...row, outcome: { status: "done", note: "installed" } };
+    }
+    return { ...row, outcome: { status: "done", note: "linked" } };
+  }),
 };
 
-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.",
+describe("the setup plan renders as one table", () => {
+  it("names the scope and both roots once, then one row per target", () => {
+    // The header carries the roots so no row repeats an absolute prefix, and
+    // EVERY target is a row — including the one that will skip, which is the
+    // whole point: a target that cannot be offered is named, not omitted.
+    //
+    // The middle column is a column of VERBS. Three things are pinned here that
+    // it used to get wrong: `mcp` reads `install` rather than `2 files` (a count
+    // is not an action, and the row-level token `update` disagreed with every
+    // one of its own `(add)` children); a row whose children all do the same
+    // thing prints their labels bare, because the verb has already said what
+    // happens to them; and the two quiet outcomes are told apart in words —
+    // `no change` for something already correct, `nothing to do` for something
+    // there is nothing to act on — with the reason beside each.
+    expect(renderPlanTable(PLAN, { lead: "Setup plan" })).toBe(
+      [
+        "Setup plan — global (home: ~ · project: ~/src/app)",
+        "",
+        "  config       no change      ~/.config/pragma/config.json — present",
+        "  completions  install        bash → ~/.local/share/bash-completion/completions/pragma",
+        "  lsp          nothing to do  no VS Code-family editor CLI on PATH (code, codium, cursor, windsurf)",
+        "  mcp          install        ~/.claude.json · ~/.codeium/windsurf/mcp_config.json",
+        "  skills       link           2 skills → 2 folders (~/.claude/skills, ~/.agents/skills)",
+      ].join("\n"),
     );
   });
 
-  it("llm is the same banded recap prefixed with a bullet", () => {
-    expect(setupFormatters.llm(BOTH_BANDS)).toBe(
-      "- Configured MCP — Global: Windsurf · Project: Cursor.",
+  it("an explicit dry run names itself, not the consent it was not asked for", () => {
+    // Two previews, two last lines. `--dry-run` was asked for and answered, so
+    // telling the user to "run again with --yes" would be advice for a question
+    // they did not ask; the run that was DENIED consent is the one where that
+    // is the useful next step.
+    expect(renderDryRun({ ...PLAN, preview: true })).toContain(
+      "Dry run — nothing applied.",
     );
+    expect(renderDryRun({ ...PLAN, preview: true })).not.toContain("--yes");
   });
 
-  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 non-interactive run without consent previews and says so", () => {
+    const preview = setupFormatters.plain({ ...PLAN, preview: true });
+    expect(preview).toContain("Setup plan — global");
+    expect(preview.endsWith(`\n\n${PREVIEW_HINT}`)).toBe(true);
   });
 
-  it("a single-band selection lists only that band", () => {
-    const projectOnly: SetupResult = {
-      kind: "mcp",
-      configured: ["Cursor"],
-      targets: [
+  it("groups the rows under scope headings when a run covers both", () => {
+    const both: SetupPlan = {
+      scope: "both",
+      roots: ROOTS,
+      rows: [
+        ROWS[3] as PlanRow,
         {
-          name: "Cursor",
-          band: "project",
-          path: "/p/.cursor/mcp.json",
-          state: "absent",
+          target: "mcp",
+          scope: "project",
+          action: "skip",
+          detail: "no AI harness in this project keeps a per-project config",
+          reason: "no AI harness in this project keeps a per-project config",
+          selected: false,
         },
       ],
     };
-    expect(setupFormatters.plain(projectOnly)).toBe(
-      "Configured MCP — Project: Cursor.",
+    const out = renderPlanTable(both, { lead: "Setup plan" });
+    expect(out).toContain("Global");
+    expect(out).toContain("Local project");
+    expect(out).toContain("global and local project");
+    // "band" was the type layer's word for this partition; the vocabulary
+    // retired it, and it may not return through any of the three renders.
+    expect(out).not.toMatch(/\bbands?\b/);
+  });
+});
+
+describe("the recap is the plan replayed", () => {
+  it("counts the rows it took responsibility for and carries each row's outcome", () => {
+    expect(renderRecap(APPLIED)).toBe(
+      [
+        "Setup: 4 of 4 targets configured — global",
+        "  ✓ config       ~/.config/pragma/config.json — present",
+        "  ✓ completions  bash → ~/.local/share/bash-completion/completions/pragma — installed",
+        "  ○ lsp          skipped: no VS Code-family editor CLI on PATH (code, codium, cursor, windsurf)",
+        "      no action is possible on this machine yet — install VS Code or VSCodium, then run this again",
+        "  ✓ mcp          2 config files — 2 added",
+        "  ✓ skills       2 skills → 2 folders (~/.claude/skills, ~/.agents/skills) — linked",
+        "",
+        "Check this again any time with `pragma doctor`.",
+      ].join("\n"),
     );
   });
 
-  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",
-        },
+  it("a skip carries its reason and never counts as a failure", () => {
+    const lsp = APPLIED.rows.find((row) => row.target === "lsp") as PlanRow;
+    expect(renderProgressLine(lsp, 11)).toBe(
+      "○ lsp          skipped: no VS Code-family editor CLI on PATH (code, codium, cursor, windsurf)",
+    );
+  });
+
+  it("the plain formatter picks the recap once a run has happened", () => {
+    expect(setupFormatters.plain(APPLIED)).toBe(renderRecap(APPLIED));
+    expect(setupFormatters.plain(PLAN)).toBe(
+      renderPlanTable(PLAN, { lead: "Setup plan" }),
+    );
+  });
+});
+
+describe("a row that did not run never renders as one that did", () => {
+  it("an unselected row gets a neutral marker, not a green check", () => {
+    // The row was offered and left unselected: neither done nor skipped for a
+    // reason. A ✓ here is the same claim the old recap made when it reported
+    // "Setup complete" over a target it had quietly dropped.
+    const row: PlanRow = {
+      target: "mcp",
+      scope: "global",
+      action: "update",
+      detail: "1 file",
+      selected: false,
+    };
+    expect(renderProgressLine(row, 3)).toBe("· mcp  1 file — not selected");
+  });
+
+  it("a converged run recaps its noop rows instead of printing a plan", () => {
+    // Every row already current: nothing is selected, because there is nothing
+    // to do. That is a RESULT, and gating the recap on `selected` made the one
+    // command that had just verified the machine report itself as a preview.
+    const converged: SetupPlan = {
+      scope: "global",
+      roots: ROOTS,
+      rows: [
         {
-          name: "Cursor",
-          band: "project",
-          path: "/proj/.cursor/mcp.json",
-          state: "drifted",
+          target: "config",
+          scope: "global",
+          action: "none",
+          detail: "~/.config/pragma/config.json — present",
+          selected: false,
+          outcome: { status: "noop", note: "unchanged" },
         },
       ],
     };
-    expect(setupFormatters.plain(rerun)).toBe(
-      "Configured MCP — Global: Windsurf · Project: Cursor (0 added, 1 updated, 1 unchanged).",
+    expect(setupFormatters.plain(converged)).toBe(renderRecap(converged));
+    expect(setupFormatters.plain(converged)).toContain(
+      "✓ config  ~/.config/pragma/config.json — present — unchanged",
+    );
+  });
+
+  it("a failed row carries the failure glyph and its remedy", () => {
+    const failed: PlanRow = {
+      target: "lsp",
+      scope: "global",
+      action: "install",
+      detail: "via code",
+      selected: true,
+      outcome: {
+        status: "failed",
+        note: "VS Code refused the VSIX",
+        remedy:
+          "install manually: code --install-extension ~/.local/share/pragma/lsp/terrazzo-lsp.vsix",
+      },
+    };
+    expect(renderProgressLine(failed, 3)).toBe(
+      "✗ lsp  via code — VS Code refused the VSIX",
     );
   });
 
-  it("no targets → a plain 'nothing configured' line", () => {
-    const none: SetupResult = { kind: "mcp", configured: [], targets: [] };
-    expect(setupFormatters.plain(none)).toBe("No harnesses configured.");
+  it("an unapplied plan does not paint every llm row with a check", () => {
+    // `GLYPHS[status ?? "noop"]` gave a plan with no outcomes a green ✓ on
+    // every row, skips included.
+    const out = setupFormatters.llm(PLAN);
+    expect(out).not.toContain("✓");
+    expect(out).toContain("· **lsp** (global): skip");
+  });
+});
+
+describe("the machine-readable projections carry the same rows", () => {
+  it("json is the plan round-tripped, scope and all", () => {
+    expect(JSON.parse(setupFormatters.json(APPLIED))).toEqual(APPLIED);
+    // The type-layer rename reaches the machine surface too: the model is
+    // emitted verbatim, so the retired word cannot survive as a JSON key.
+    expect(setupFormatters.json(APPLIED)).not.toMatch(/\bbands?\b/);
+  });
+
+  it("llm names every row with its scope and state", () => {
+    const out = setupFormatters.llm(APPLIED);
+    for (const row of APPLIED.rows) {
+      expect(out).toContain(`**${row.target}** (${row.scope})`);
+    }
+  });
+});
+
+describe("shortenPath — containment, on the host's own separator", () => {
+  // The rule is `node:path`'s: a root contains a path when the relative route
+  // between them walks only downwards. Hard-coding `/` answered no for every
+  // Windows path `node:path` produces, so a plan that had just named both roots
+  // in its header printed 120-character absolute rows underneath them. The
+  // win32 arm follows from `relative`/`sep` rather than from a second rule, so
+  // what is pinned here are the invariants the host separator makes visible.
+  const roots = {
+    global: join(sep, "home", "u"),
+    project: join(sep, "home", "u", "src", "app"),
+  };
+
+  it("renders under the project root first — the more specific one", () => {
+    expect(shortenPath(join(roots.project, "a", "b.json"), roots)).toBe(
+      `.${sep}${join("a", "b.json")}`,
+    );
+    expect(shortenPath(roots.project, roots)).toBe(".");
+  });
+
+  it("renders a global-scope path under `~`", () => {
+    expect(shortenPath(join(roots.global, ".config", "x.json"), roots)).toBe(
+      `~${sep}${join(".config", "x.json")}`,
+    );
+    expect(shortenPath(roots.global, roots)).toBe("~");
+  });
+
+  it("does not take a sibling that merely EXTENDS a root's name as inside it", () => {
+    // `<project>-backup` is not under `<project>`; it is under the home root,
+    // and that is the root it must be rendered against.
+    expect(shortenPath(join(`${roots.project}-backup`, "a.json"), roots)).toBe(
+      `~${sep}${join("src", "app-backup", "a.json")}`,
+    );
+    // A sibling of the OUTERMOST root is under neither, so it stays absolute.
+    const outside = join(`${roots.global}-backup`, "a.json");
+    expect(shortenPath(outside, roots)).toBe(outside);
   });
 
-  it("json is the exact SetupResult round-trip", () => {
-    expect(JSON.parse(setupFormatters.json(BOTH_BANDS))).toEqual(BOTH_BANDS);
+  it("leaves a path under neither root absolute", () => {
+    const outside = join(sep, "etc", "pragma", "config.json");
+    expect(shortenPath(outside, roots)).toBe(outside);
   });
 });

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

@@ -1,94 +1,62 @@
 /**
  * Formatters for `pragma setup` and its sub-verbs — one shared formatter over
- * the tagged {@link SetupResult} union (plain, llm, json).
+ * the {@link SetupPlan} (plain, llm, json).
+ *
+ * The plan REPLACED a tagged result union with one member per sub-verb, each
+ * rendering its own sentence in its own vocabulary. That union could not
+ * describe a run that touched several targets in two scopes, so the run-all
+ * reported a list of step names and nothing about what any of them did. One
+ * structure with one renderer is what makes the preview, the progress lines and
+ * the recap agree by construction rather than by review.
  */
 
-import type { Formatters } from "../../kernel/spec/types.js";
-import { BAND_LABELS } from "../shared/bands.js";
-import type {
-  ConfiguredTarget,
-  SetupResult,
-  SetupSkillsResult,
-} from "./types.js";
+import type { Formatters } from "../../kernel/spec/index.js";
+import type { SetupPlan } from "./plan.js";
+import { renderPlanLlm, renderPlanTable, renderRecap } from "./plan.render.js";
+
+/** The trailing line a non-applied plan carries. */
+export const PREVIEW_HINT =
+  "Nothing was applied. Run again with --yes to apply.";
 
-/** Summarize a skills result: created / skipped / replaced counts. */
-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)`;
-}
+/** The trailing line an explicit dry run carries. */
+export const DRY_RUN_HINT = "Dry run — nothing applied.";
 
 /**
- * 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}).
+ * Whether any row carries an outcome, i.e. whether a run actually happened.
  *
- * 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).
+ * Selection is deliberately NOT part of this test. An all-current re-run selects
+ * nothing — every row is already converged — and gating on `selected` made that
+ * run render as an unapplied PLAN, so the one command that had just confirmed
+ * the machine was fully set up reported itself as a preview.
  */
-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).`;
-}
+const wasApplied = (plan: SetupPlan): boolean =>
+  plan.rows.some((row) => row.outcome !== undefined);
 
-/** Render a setup result to a single human line (shared by plain/llm). */
-function renderSetupLine(data: SetupResult): string {
-  switch (data.kind) {
-    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 data.state === "installed"
-        ? "Terrazzo LSP extension already installed (up to date)."
-        : "Terrazzo LSP extension is installed (up to date).";
-    case "mcp":
-      return summarizeMcpTargets(data.targets);
-    case "skills":
-      return `Skills: ${summarizeSkills(data.result)}.`;
-    case "all":
-      return data.steps.length > 0
-        ? `Setup complete — ran: ${data.steps.join(", ")}.`
-        : "Setup complete — no steps selected.";
-  }
-}
+/**
+ * The dry-run render. Reached ONLY through the verb's `formatPlan` seam, which
+ * the kernel calls on the `--dry-run` branch — so it can name that path
+ * outright. The identical body under {@link setupFormatters} serves the OTHER
+ * preview, the non-interactive run that was given no consent, whose useful last
+ * line is how to grant it.
+ *
+ * @param plan - The plan to render.
+ * @returns The plan table, ended with the dry-run's own line.
+ */
+export const renderDryRun = (plan: SetupPlan): string =>
+  renderPlanTable(plan, { lead: "Setup plan", hint: DRY_RUN_HINT });
 
-export const setupFormatters: Formatters<SetupResult> = {
+export const setupFormatters: Formatters<SetupPlan> = {
   plain(data) {
-    return renderSetupLine(data);
+    if (data.preview === true) {
+      return renderPlanTable(data, { lead: "Setup plan", hint: PREVIEW_HINT });
+    }
+    if (!wasApplied(data)) {
+      return renderPlanTable(data, { lead: "Setup plan" });
+    }
+    return renderRecap(data);
   },
   llm(data) {
-    return `- ${renderSetupLine(data)}`;
+    return renderPlanLlm(data, data.preview === true ? "Setup plan" : "Setup");
   },
   json(data) {
     return JSON.stringify(data);