@canonical/pragma-cli 0.35.0 → 0.36.0

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

@@ -13,85 +13,107 @@
  * a piped run renders byte-for-byte plain.
  */
 
-import chalk from "chalk";
 import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
-import { BAND_LABELS } from "../shared/index.js";
 import {
+  NOT_RUN_GLYPH,
+  OUTCOME_GLYPHS,
+  outcomeRemedyWord,
+  SCOPE_LABELS,
+  SCOPE_PHRASES,
+} from "../../kernel/render/vocabulary.js";
+import {
+  type PlanAction,
   type PlanChildRow,
   type PlanRow,
   planTally,
   type SetupPlan,
   shortenPath,
 } from "./plan.js";
-import type { ScopeBand } from "./types.js";
-
-/** The glyph for a row's outcome. */
-const GLYPHS = {
-  done: "✓",
-  noop: "✓",
-  removed: "✓",
-  kept: "○",
-  skipped: "○",
-  failed: "✗",
-} as const;
+import type { Scope } from "./types.js";
+
+/** The header's scope phrase: `global`, `local project`, or both of them. */
+const scopePhrase = (scope: SetupPlan["scope"]): string => SCOPE_PHRASES[scope];
 
 /**
- * The marker for a row that carries NO outcome — one the user deselected, so it
- * was neither done nor skipped-for-cause. It must not be a ✓: a green check
- * against work that never ran is the same lie the old recap told when it
- * reported "Setup complete" over a target it had dropped.
+ * The header line. It names the scope and BOTH roots exactly once, which is what
+ * frees every row below to render its paths root-relative instead of repeating
+ * a 120-character prefix per line. The roots are LABELLED (`home:`, `project:`)
+ * because the `~` and `.` markers the rows use are only legible once something
+ * has said what they stand for.
  */
-const NOT_RUN_GLYPH = "·";
-
-/** The TTY styler plus `red` — the one tint {@link RenderStyle} does not carry. */
-interface PlanStyle extends RenderStyle {
-  red(text: string): string;
+function header(plan: SetupPlan, lead: string): string {
+  const project = shortenPath(plan.roots.project, {
+    global: plan.roots.global,
+    project: "",
+  });
+  return `${lead} — ${scopePhrase(plan.scope)} (home: ~ · project: ${project})`;
 }
 
 /**
- * Widen a {@link RenderStyle} with a `red` gated on the SAME colour decision, so
- * a failure tint appears only on a colour-capable TTY. Mirrors `doctor`'s own
- * styler, which is deliberate: a failed setup row and a failed doctor row are
- * the same finding seen twice, and they are tinted alike.
+ * The plain verb each action reads as. The middle column is a column of VERBS:
+ * what this row will do. It used to render the raw {@link PlanAction} token, so
+ * it read as a column of status codes — and `none` was the worst of them,
+ * standing equally for "already correct" and "nothing found here". The two are
+ * now told apart by the pair: the word says nothing will happen, the detail
+ * beside it says what was found.
  *
- * @param style - The shared styler.
- * @returns The styler plus `red`.
+ * `none` and `skip` are worded direction-neutrally on purpose. The SAME renderer
+ * draws the `--undo` plan, where a target-specific negation ("nothing to create"
+ * on the `config` row) would be plainly false — there the row is not creating
+ * anything, it is declining to delete.
+ *
+ * The token itself is untouched: `action` is the machine field `--format json`
+ * publishes, and this is the display layer over it.
  */
-const withRed = (style: RenderStyle): PlanStyle => ({
-  ...style,
-  red: style.enabled ? (text) => chalk.red(text) : (text) => text,
-});
+const ACTION_WORDS: Record<PlanAction, string> = {
+  install: "install",
+  update: "update",
+  link: "link",
+  remove: "remove",
+  none: "no change",
+  skip: "nothing to do",
+};
 
-/** The header's band phrase: `global band`, `project band`, or `both bands`. */
-const scopePhrase = (scope: SetupPlan["scope"]): string =>
-  scope === "both" ? "both bands" : `${scope} band`;
+/** The distinct actions a row's children carry (empty when it has none). */
+const childActions = (row: PlanRow): Set<PlanChildRow["action"]> =>
+  new Set((row.children ?? []).map((child) => child.action));
 
 /**
- * The header line. It names the band and BOTH roots exactly once, which is what
- * frees every row below to render its paths root-relative instead of repeating
- * a 120-character prefix per line.
+ * The middle column.
+ *
+ * A row with children takes its word from THEM when they agree, because the
+ * row-level token can disagree with every one of its own files: registering the
+ * MCP server in three files that have never held it plans as `update` (the
+ * table's word for "this row has work that is not a fresh install"), and
+ * printing `update` over three `(add)` children described the opposite of what
+ * the run would do. Before this the cell held the row's DETAIL instead — `3
+ * files`, which is a count, not an action, and left the plan with no column
+ * that said what would happen.
  */
-function header(plan: SetupPlan, lead: string): string {
-  const project = shortenPath(plan.roots.project, {
-    global: plan.roots.global,
-    project: "",
-  });
-  return `${lead} — ${scopePhrase(plan.scope)} (~ · project: ${project})`;
+function actionCell(row: PlanRow): string {
+  const kinds = childActions(row);
+  if (row.action === "update" && kinds.size === 1 && kinds.has("add")) {
+    return ACTION_WORDS.install;
+  }
+  return ACTION_WORDS[row.action];
 }
 
-/** The middle column: the per-file count when a row has children, else its action. */
-const actionCell = (row: PlanRow): string =>
-  row.children && row.children.length > 0 ? row.detail : row.action;
-
-/** One child rendered inline: `~/.claude.json (add)`. */
-const childCell = (child: PlanChildRow): string =>
-  `${child.label} (${child.action})`;
+/**
+ * One child rendered inline. The per-child action is printed only when the
+ * children DISAGREE — when they all do the same thing the row's own verb has
+ * just said it, and `lsp  no change  codium — VSCodium (unchanged)` said
+ * "nothing happens here" twice in two columns.
+ */
+const childCell = (row: PlanRow, child: PlanChildRow): string =>
+  childActions(row).size === 1
+    ? child.label
+    : `${child.label} (${child.action})`;
 
 /** The right column: the children joined, or the row's own detail. */
 const detailCell = (row: PlanRow): string =>
   row.children && row.children.length > 0
-    ? row.children.map(childCell).join(" · ")
+    ? row.children.map((child) => childCell(row, child)).join(" · ")
     : row.action === "skip"
       ? (row.reason ?? row.detail)
       : row.detail;
@@ -100,13 +122,13 @@ const detailCell = (row: PlanRow): string =>
 const widthOf = (rows: readonly PlanRow[], pick: (row: PlanRow) => string) =>
   Math.max(0, ...rows.map((row) => pick(row).length));
 
-/** Group rows by band, in the plan's own band order. */
-function byBand(plan: SetupPlan): [ScopeBand, PlanRow[]][] {
-  const bands: ScopeBand[] = ["global", "project"];
-  return bands
-    .map((band): [ScopeBand, PlanRow[]] => [
-      band,
-      plan.rows.filter((row) => row.band === band),
+/** Group rows by scope, in the plan's own scope order. */
+function byScope(plan: SetupPlan): [Scope, PlanRow[]][] {
+  const scopes: Scope[] = ["global", "project"];
+  return scopes
+    .map((scope): [Scope, PlanRow[]] => [
+      scope,
+      plan.rows.filter((row) => row.scope === scope),
     ])
     .filter(([, rows]) => rows.length > 0);
 }
@@ -128,9 +150,9 @@ export function renderPlanTable(
   const idWidth = widthOf(plan.rows, (row) => row.target);
   const actionWidth = widthOf(plan.rows, actionCell);
   const lines = [style.bold(header(plan, options.lead)), ""];
-  const groups = byBand(plan);
-  for (const [band, rows] of groups) {
-    if (plan.scope === "both") lines.push(style.bold(BAND_LABELS[band]));
+  const groups = byScope(plan);
+  for (const [scope, rows] of groups) {
+    if (plan.scope === "both") lines.push(style.bold(SCOPE_LABELS[scope]));
     for (const row of rows) {
       lines.push(
         `  ${row.target.padEnd(idWidth)}  ${actionCell(row).padEnd(actionWidth)}  ${style.dim(detailCell(row))}`,
@@ -141,6 +163,65 @@ export function renderPlanTable(
   return lines.join("\n");
 }
 
+/**
+ * What was DETECTED, rendered before anything is asked.
+ *
+ * The gap this closes is a rendering one, not an ordering one: detection is
+ * complete before the prompt array is even constructed (`buildSetupRun` does
+ * resolveRoots → detectTargets → buildPlan, and only then builds `prompts`), and
+ * the Ink view mounts no React until the FIRST prompt effect. So the facts were
+ * sitting in `run.plan` the whole time with nothing rendering them — the wizard
+ * leaked detection only through prompt-label suffixes, and `renderPlanTable` is
+ * reached only by `--dry-run` or the non-interactive preview. A wizard run
+ * never rendered it at all, and the confirm gate shows an EFFECTS summary, not
+ * a detection one.
+ *
+ * It is a plain-string formatter on purpose. It rides `rt.report` — the non-Ink
+ * stderr seam, `--quiet`-aware and a no-op over MCP — because pragma contains no
+ * React and no Ink, and three PROTECTED tests exist to keep it that way.
+ *
+ * The default lists DETECTED rows only; `--verbose` lists everything. "Detected"
+ * is `action !== "skip"`, which is not a new partition: it is exactly the
+ * predicate the row multiselect already uses to build its choices, so the
+ * summary and the question that follows it describe the same set.
+ *
+ * @param plan - The plan as detected (no outcomes yet).
+ * @param options - `verbose` widens detected-only to the whole table.
+ * @param style - Injected for tests; defaults to the shared TTY seam.
+ * @returns The rendered block, or `undefined` when there is nothing to say.
+ */
+export function renderDetectionSummary(
+  plan: SetupPlan,
+  options: { verbose?: boolean } = {},
+  style: RenderStyle = defaultStyle(),
+): string | undefined {
+  const shown = options.verbose
+    ? plan.rows
+    : plan.rows.filter((row) => row.action !== "skip");
+  if (shown.length === 0) return undefined;
+  const hidden = plan.rows.length - shown.length;
+  const idWidth = widthOf(shown, (row) => row.target);
+  const actionWidth = widthOf(shown, actionCell);
+  const lines = [style.bold(header(plan, "Detected")), ""];
+  for (const [scope, rows] of byScope({ ...plan, rows: shown })) {
+    if (plan.scope === "both") lines.push(style.bold(SCOPE_LABELS[scope]));
+    for (const row of rows) {
+      lines.push(
+        `  ${row.target.padEnd(idWidth)}  ${actionCell(row).padEnd(actionWidth)}  ${style.dim(detailCell(row))}`,
+      );
+    }
+  }
+  if (hidden > 0) {
+    lines.push(
+      "",
+      style.dim(
+        `${hidden} target${hidden === 1 ? "" : "s"} not detected here — --verbose lists them`,
+      ),
+    );
+  }
+  return lines.join("\n");
+}
+
 /**
  * One progress line, emitted as a row's outcome lands. Same columns as the
  * recap, so a reader watching the run and a reader reading the recap afterwards
@@ -156,27 +237,30 @@ export function renderProgressLine(
   idWidth: number,
   style: RenderStyle = defaultStyle(),
 ): string {
-  const painted = withRed(style);
   const outcome = row.outcome;
 
   // No outcome at all: the row was offered and left unselected. It is neither a
   // success nor a skip-for-cause, and painting it green would claim work that
   // never happened, so it gets a neutral marker and says plainly what it is.
   if (outcome === undefined) {
-    return `${painted.dim(NOT_RUN_GLYPH)} ${row.target.padEnd(idWidth)}  ${painted.dim(`${row.detail} — not selected`)}`;
+    return `${style.dim(NOT_RUN_GLYPH)} ${row.target.padEnd(idWidth)}  ${style.dim(`${row.detail} — not selected`)}`;
   }
 
-  const glyph = GLYPHS[outcome.status];
+  const glyph = OUTCOME_GLYPHS[outcome.status];
   const tinted =
     outcome.status === "failed"
-      ? painted.red(glyph)
+      ? style.red(glyph)
       : outcome.status === "skipped" || outcome.status === "kept"
-        ? painted.yellow(glyph)
-        : painted.green(glyph);
+        ? style.yellow(glyph)
+        : style.green(glyph);
   const note = outcome.note;
   const body =
     outcome.status === "skipped"
-      ? `skipped — ${row.reason ?? row.detail}`
+      ? // A colon, not a dash: the reasons carry their own em-dash clause
+        // ("no skills installed yet — pack skills arrive with …"), and two
+        // dashes in one line read as one run-on sentence rather than a label
+        // in front of a reason.
+        `skipped: ${row.reason ?? row.detail}`
       : note
         ? `${row.detail} — ${note}`
         : row.detail;
@@ -207,15 +291,19 @@ export function renderRecap(
       `${lead}: ${configured} of ${accountable} targets configured — ${scopePhrase(plan.scope)}`,
     ),
   ];
-  for (const [band, rows] of byBand(plan)) {
-    if (plan.scope === "both") lines.push(style.bold(`  ${BAND_LABELS[band]}`));
+  for (const [scope, rows] of byScope(plan)) {
+    if (plan.scope === "both")
+      lines.push(style.bold(`  ${SCOPE_LABELS[scope]}`));
     for (const row of rows) {
       lines.push(`  ${renderProgressLine(row, idWidth, style)}`);
       const remedy = row.outcome?.remedy;
       if (remedy) lines.push(`      ${style.dim(remedy)}`);
     }
   }
-  lines.push("", style.dim(`verify anytime: ${BIN_NAME} doctor`));
+  lines.push(
+    "",
+    style.dim(`Check this again any time with \`${BIN_NAME} doctor\`.`),
+  );
   return lines.join("\n");
 }
 
@@ -227,15 +315,22 @@ export function renderPlanLlm(plan: SetupPlan, lead = "Setup"): string {
     // Before a run there is no outcome to report, so the row shows its ACTION
     // behind a neutral marker. Reusing the `noop` glyph here painted every row
     // of an unapplied plan — skips included — with a green check.
-    const glyph = status === undefined ? NOT_RUN_GLYPH : GLYPHS[status];
+    const glyph = status === undefined ? NOT_RUN_GLYPH : OUTCOME_GLYPHS[status];
     const state = status ?? row.action;
     lines.push(
-      `- ${glyph} **${row.target}** (${row.band}): ${state} — ${detailCell(row)}`,
+      `- ${glyph} **${row.target}** (${row.scope}): ${state} — ${detailCell(row)}`,
     );
     for (const child of row.children ?? []) {
-      lines.push(`  - ${childCell(child)}`);
+      lines.push(`  - ${childCell(row, child)}`);
+    }
+    // `fix:` for a row that failed, `next:` for one that skipped — a skip is
+    // not a fault, and labelling its instruction as a repair is what teaches a
+    // reader to treat skips as failures.
+    if (row.outcome?.remedy) {
+      lines.push(
+        `  - _${outcomeRemedyWord(row.outcome.status)}:_ ${row.outcome.remedy}`,
+      );
     }
-    if (row.outcome?.remedy) lines.push(`  - _fix:_ ${row.outcome.remedy}`);
   }
   return lines.join("\n");
 }

package/src/capabilities/setup/plan.ts

@@ -18,7 +18,8 @@
  */
 
 import { isAbsolute, relative, sep } from "node:path";
-import type { ScopeBand, ScopeSelection } from "./types.js";
+import type { OutcomeStatus } from "../../kernel/render/vocabulary.js";
+import type { Scope, ScopeSelection } from "./types.js";
 
 /** The five setup targets, in table (and therefore display) order. */
 export const TARGET_IDS = [
@@ -45,14 +46,11 @@ export type PlanAction =
   | "none"
   | "skip";
 
-/** How one row ended. `skipped` is NOT a failure — see {@link planExitFailed}. */
-export type OutcomeStatus =
-  | "done"
-  | "noop"
-  | "skipped"
-  | "failed"
-  | "removed"
-  | "kept";
+// How one row ended. Defined with the rendering vocabulary (one module owns
+// the states and their glyphs); re-exported here because the plan is where
+// every other consumer meets it. `skipped` is NOT a failure — see
+// {@link planExitFailed}.
+export type { OutcomeStatus } from "../../kernel/render/vocabulary.js";
 
 /** Per-file / per-link detail under a row (MCP files; skill link dirs). */
 export interface PlanChildRow {
@@ -62,7 +60,14 @@ export interface PlanChildRow {
    * from {@link label}, which is display text and may be re-worded freely.
    */
   readonly key: string;
-  /** Display text, e.g. `~/.claude.json — Claude Code`. */
+  /**
+   * Display text as the producers actually emit it: the MCP row's children
+   * carry the file's shortened path alone (`~/.claude.json`), the LSP row's
+   * carry `cli — Editor Name` (`codium — VSCodium`). This doc once promised
+   * a path-plus-harness pairing (`~/.claude.json — Claude Code`) that no
+   * producer ever emitted; the harness names sharing an MCP file are the
+   * doctor inventory row's to report, not this label's.
+   */
   readonly label: string;
   readonly action: "add" | "update" | "unchanged" | "skip";
   /** REQUIRED when the action is `skip` — the named reason. */
@@ -82,10 +87,10 @@ export interface PlanOutcome {
   readonly remedy?: string;
 }
 
-/** One row of the plan: one target in one band. */
+/** One row of the plan: one target in one scope. */
 export interface PlanRow {
   readonly target: TargetId;
-  readonly band: ScopeBand;
+  readonly scope: Scope;
   readonly action: PlanAction;
   /** Right-hand column: what and where, rendered root-relative. */
   readonly detail: string;

package/src/capabilities/setup/setup.mcp.correctness.test.ts

@@ -74,7 +74,7 @@ afterEach(() => {
   roots.length = 0;
 });
 
-/** A project with Cursor detected — one project-band file, `.cursor/mcp.json`. */
+/** A project with Cursor detected — one project-scope file, `.cursor/mcp.json`. */
 const cursorProject = (): { cwd: string; config: string } => {
   const cwd = tmp("pragma-mcpc-proj-");
   mkdirSync(join(cwd, ".cursor"), { recursive: true });
@@ -122,7 +122,7 @@ describe("installing twice never produces a second entry", () => {
     const { cwd, config } = cursorProject();
     await install(cwd);
     const detection = await detectMcp(bootRuntime(FLAGS, cwd), "project");
-    expect(mcpGroupState(detection, config)).toBe("configured");
+    expect(mcpGroupState(detection, config)).toBe("registered");
   });
 });
 
@@ -278,7 +278,7 @@ describe("every drift shape converges in one write, then stays converged", () =>
     const repaired = readFileSync(config, "utf-8");
 
     const after = await detectMcp(bootRuntime(FLAGS, cwd), "project");
-    expect(mcpGroupState(after, config)).toBe("configured");
+    expect(mcpGroupState(after, config)).toBe("registered");
 
     // A second run after the repair changes nothing.
     await install(cwd);
@@ -341,7 +341,7 @@ describe("every drift shape converges in one write, then stays converged", () =>
     expect(entry).toEqual({ command: "pragma", args: ["mcp", "serve"] });
     expect(entry).not.toHaveProperty("cwd");
     const after = await detectMcp(bootRuntime(FLAGS, cwd), "global");
-    expect(mcpGroupState(after, config)).toBe("configured");
+    expect(mcpGroupState(after, config)).toBe("registered");
   });
 
   it("leaves extra keys on OUR entry alone — they are not ours to drop", async () => {
@@ -355,7 +355,7 @@ describe("every drift shape converges in one write, then stays converged", () =>
     writeFileSync(config, `${JSON.stringify(parsed, null, 2)}\n`);
 
     const detection = await detectMcp(bootRuntime(FLAGS, cwd), "project");
-    expect(mcpGroupState(detection, config)).toBe("configured");
+    expect(mcpGroupState(detection, config)).toBe("registered");
 
     await install(cwd);
     expect(
@@ -363,8 +363,8 @@ describe("every drift shape converges in one write, then stays converged", () =>
     ).toBe(5000);
   });
 
-  it("keeps the two bands of one harness independent", async () => {
-    // Cursor has both a project file and a home file. Writing one band must
+  it("keeps the two scopes of one harness independent", async () => {
+    // Cursor has both a project file and a home file. Writing one scope must
     // not touch the other, and each converges on its own terms — the project
     // entry records a cwd, the global entry omits it.
     const cwd = tmp("pragma-mcpc-proj-");
@@ -380,13 +380,13 @@ describe("every drift shape converges in one write, then stays converged", () =>
     const projectBytes = readFileSync(projectConfig, "utf-8");
     expect(existsSync(globalConfig)).toBe(true);
 
-    // Each band carries its own shape.
+    // Each scope carries its own shape.
     expect(JSON.parse(projectBytes).mcpServers.pragma.cwd).toBe(cwd);
     expect(
       JSON.parse(readFileSync(globalConfig, "utf-8")).mcpServers.pragma,
     ).not.toHaveProperty("cwd");
 
-    // Undoing one band leaves the other intact.
+    // Undoing one scope leaves the other intact.
     await undo(cwd, GLOBAL);
     expect(readFileSync(projectConfig, "utf-8")).toBe(projectBytes);
   });