@canonical/pragma-cli 0.34.0 → 0.36.0

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

@@ -0,0 +1,336 @@
+/**
+ * The plan's four renders: the preview table, one progress line per row, the
+ * recap, and the JSON projection.
+ *
+ * All four read the SAME {@link SetupPlan}. That is the whole design: a preview
+ * that shows one thing, a progress stream that shows another, and a recap that
+ * counts a third is how "Setup complete — ran: completions, lsp, mcp" came to
+ * be printed on a run that had silently dropped a target. Here the recap is the
+ * preview with outcomes filled in, so the two cannot describe different runs.
+ *
+ * Column widths are computed from the rows being rendered, so the block stays
+ * aligned whether it holds one row or seven. Colour rides the shared TTY seam —
+ * a piped run renders byte-for-byte plain.
+ */
+
+import { BIN_NAME } from "../../constants.js";
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.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 { 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 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.
+ */
+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})`;
+}
+
+/**
+ * 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.
+ *
+ * `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 ACTION_WORDS: Record<PlanAction, string> = {
+  install: "install",
+  update: "update",
+  link: "link",
+  remove: "remove",
+  none: "no change",
+  skip: "nothing to do",
+};
+
+/** 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 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 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];
+}
+
+/**
+ * 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((child) => childCell(row, child)).join(" · ")
+    : row.action === "skip"
+      ? (row.reason ?? row.detail)
+      : row.detail;
+
+/** Pad every id to the widest, so the three columns line up. */
+const widthOf = (rows: readonly PlanRow[], pick: (row: PlanRow) => string) =>
+  Math.max(0, ...rows.map((row) => pick(row).length));
+
+/** 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);
+}
+
+/**
+ * Render the plan as the preview table.
+ *
+ * @param plan - The plan to render.
+ * @param options - `lead` heads the block; `hint` is the trailing line (the
+ *   non-interactive preview's "nothing was applied", or the dry-run's own).
+ * @param style - Injected for tests; defaults to the shared TTY seam.
+ * @returns The rendered block.
+ */
+export function renderPlanTable(
+  plan: SetupPlan,
+  options: { lead: string; hint?: string } = { lead: "Setup plan" },
+  style: RenderStyle = defaultStyle(),
+): string {
+  const idWidth = widthOf(plan.rows, (row) => row.target);
+  const actionWidth = widthOf(plan.rows, actionCell);
+  const lines = [style.bold(header(plan, options.lead)), ""];
+  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))}`,
+      );
+    }
+  }
+  if (options.hint) lines.push("", options.hint);
+  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
+ * see the same sentence about the same row.
+ *
+ * @param row - The row, with its outcome filled in.
+ * @param idWidth - The shared id column width.
+ * @param style - Injected for tests.
+ * @returns The line.
+ */
+export function renderProgressLine(
+  row: PlanRow,
+  idWidth: number,
+  style: RenderStyle = defaultStyle(),
+): string {
+  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 `${style.dim(NOT_RUN_GLYPH)} ${row.target.padEnd(idWidth)}  ${style.dim(`${row.detail} — not selected`)}`;
+  }
+
+  const glyph = OUTCOME_GLYPHS[outcome.status];
+  const tinted =
+    outcome.status === "failed"
+      ? style.red(glyph)
+      : outcome.status === "skipped" || outcome.status === "kept"
+        ? style.yellow(glyph)
+        : style.green(glyph);
+  const note = outcome.note;
+  const body =
+    outcome.status === "skipped"
+      ? // 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;
+  return `${tinted} ${row.target.padEnd(idWidth)}  ${body}`;
+}
+
+/**
+ * The recap: the plan replayed with outcomes.
+ *
+ * The headline counts SELECTED rows, never "steps that ran", so a target that
+ * was selected and then skipped is visible in the denominator instead of
+ * vanishing from a sentence that claims completeness.
+ *
+ * @param plan - The plan, with outcomes filled in.
+ * @param lead - The headline's first word (`Setup` / `Removed`).
+ * @param style - Injected for tests.
+ * @returns The rendered recap.
+ */
+export function renderRecap(
+  plan: SetupPlan,
+  lead = "Setup",
+  style: RenderStyle = defaultStyle(),
+): string {
+  const { configured, accountable } = planTally(plan);
+  const idWidth = widthOf(plan.rows, (row) => row.target);
+  const lines = [
+    style.bold(
+      `${lead}: ${configured} of ${accountable} targets configured — ${scopePhrase(plan.scope)}`,
+    ),
+  ];
+  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(`Check this again any time with \`${BIN_NAME} doctor\`.`),
+  );
+  return lines.join("\n");
+}
+
+/** The condensed Markdown form — the same rows, one bullet each. */
+export function renderPlanLlm(plan: SetupPlan, lead = "Setup"): string {
+  const lines = [`## ${lead} — ${scopePhrase(plan.scope)}`, ""];
+  for (const row of plan.rows) {
+    const status = row.outcome?.status;
+    // 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 : OUTCOME_GLYPHS[status];
+    const state = status ?? row.action;
+    lines.push(
+      `- ${glyph} **${row.target}** (${row.scope}): ${state} — ${detailCell(row)}`,
+    );
+    for (const child of row.children ?? []) {
+      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}`,
+      );
+    }
+  }
+  return lines.join("\n");
+}

package/src/capabilities/setup/plan.ts

@@ -0,0 +1,241 @@
+/**
+ * The setup plan — ONE structure with four readers.
+ *
+ * `--dry-run` prints it, the wizard edits its `selected` flags, progress reports
+ * one line per row as its outcome lands, and the recap is the same rows with
+ * `outcome` filled. `--format json` emits `{ scope, roots, rows }` verbatim.
+ * Doctor reads the same target table (see {@link ./targets.js}) so the two
+ * surfaces cannot disagree about what they looked at.
+ *
+ * The shape is deliberately flat and JSON-ready: no class, no live handle, no
+ * task. A row is a fact about what a run WOULD do (or, once `outcome` is set,
+ * what it did), which is why the plan can be rendered before, during, and after
+ * the run without any reader having to know which phase produced it.
+ *
+ * This module is pure data + pure derivations. It carries no import of the
+ * operations, the harnesses runtime, or React — so the renderers, the doctor
+ * checks, and the verb can all reach it without dragging anything heavy along.
+ */
+
+import { isAbsolute, relative, sep } from "node:path";
+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 = [
+  "config",
+  "completions",
+  "lsp",
+  "mcp",
+  "skills",
+] as const;
+
+/** One target id — the `setup <target>` argument AND the doctor row name. */
+export type TargetId = (typeof TARGET_IDS)[number];
+
+/**
+ * What a run would do to one row. `none` is "already current" (a converged
+ * re-run performs zero filesystem mutations); `skip` is "cannot or should not
+ * act here", and always carries a {@link PlanRow.reason}.
+ */
+export type PlanAction =
+  | "install"
+  | "update"
+  | "link"
+  | "remove"
+  | "none"
+  | "skip";
+
+// 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 {
+  /**
+   * The stable identifier the wizard's per-file selection and `--format json`
+   * key on — an absolute path for both MCP files and skill link dirs. Distinct
+   * from {@link label}, which is display text and may be re-worded freely.
+   */
+  readonly key: string;
+  /**
+   * 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. */
+  readonly reason?: string;
+}
+
+/** How one row ended, filled in after (or during) apply; absent in a pure plan. */
+export interface PlanOutcome {
+  readonly status: OutcomeStatus;
+  /** `2 added, 1 updated`, or the failure line. */
+  readonly note?: string;
+  /**
+   * An action that works on THIS machine NOW — probed, not hoped — or absent.
+   * Never a generic cause, never a command for a binary this machine lacks,
+   * never an ephemeral path.
+   */
+  readonly remedy?: string;
+}
+
+/** One row of the plan: one target in one scope. */
+export interface PlanRow {
+  readonly target: TargetId;
+  readonly scope: Scope;
+  readonly action: PlanAction;
+  /** Right-hand column: what and where, rendered root-relative. */
+  readonly detail: string;
+  /** REQUIRED when the action is `skip` — the named reason. */
+  readonly reason?: string;
+  readonly children?: readonly PlanChildRow[];
+  /** The wizard edits this; `--yes` takes it as-is. Skips are never selectable. */
+  readonly selected: boolean;
+  readonly outcome?: PlanOutcome;
+}
+
+/** Built once per invocation from the target table's detections. */
+export interface SetupPlan {
+  readonly scope: ScopeSelection;
+  /**
+   * True when this plan was rendered INSTEAD of being applied — an explicit
+   * `--dry-run`, or a non-interactive run that was not given `--yes`. The
+   * renderer turns it into the trailing "nothing was applied" line; readers of
+   * `--format json` get the same fact without parsing prose.
+   */
+  readonly preview?: boolean;
+  /** Named once in the header; every row path renders relative to one of these. */
+  readonly roots: { readonly global: string; readonly project: string };
+  readonly rows: readonly PlanRow[];
+}
+
+/**
+ * Whether a plan action would touch the filesystem. `none` and `skip` are the
+ * two quiet outcomes: a converged re-run composes no effects at all, so mtimes
+ * stay untouched and a second `--yes` writes nothing.
+ */
+export const isActionable = (action: PlanAction): boolean =>
+  action === "install" ||
+  action === "update" ||
+  action === "link" ||
+  action === "remove";
+
+/**
+ * Default selection for a freshly built row: actionable rows are pre-selected,
+ * already-current rows are shown de-selected, and a skip is never selectable.
+ */
+export const defaultSelected = (action: PlanAction): boolean =>
+  isActionable(action);
+
+/** The rows a run acts on: selected, and not a skip. */
+export const selectedRows = (plan: SetupPlan): readonly PlanRow[] =>
+  plan.rows.filter((row) => row.selected && row.action !== "skip");
+
+/**
+ * THE exit rule (and the reason it is stated once, here): a run fails only when
+ * a selected row was attempted and did not happen. Every selected row ending
+ * `done`, `noop` or `skipped` exits 0 — including a headless box where nothing
+ * is installable, because a skip is "nothing to do here, honestly named", the
+ * same semantics doctor gives its skip glyph. Punishing a converged or benignly
+ * empty state with a non-zero exit makes a dotfiles script fail on a machine
+ * with an exotic shell, which teaches people to ignore the exit code.
+ *
+ * @param plan - The plan, with outcomes filled in.
+ * @returns Whether any selected row ended `failed`.
+ */
+export const planExitFailed = (plan: SetupPlan): boolean =>
+  plan.rows.some((row) => row.outcome?.status === "failed");
+
+/**
+ * `N of M targets` — the recap headline's counts.
+ *
+ * M is the rows this run took RESPONSIBILITY for: every row that reached an
+ * outcome other than `skipped`. That is deliberately not "rows with the checkbox
+ * ticked". An already-current row is offered de-selected because there is
+ * nothing to do to it, so counting ticks reported a fully converged machine as
+ * `0 of 0 configured` — a sentence that describes a machine where nothing
+ * worked exactly as it describes one where everything already did.
+ *
+ * Skips stay out of both counts: a target that cannot act on this machine is
+ * neither a success nor a shortfall, and it is already named on its own row.
+ * A row the user deselected has no outcome at all and is likewise absent.
+ *
+ * @param plan - The plan, with outcomes filled in.
+ * @returns The headline's numerator and denominator.
+ */
+export function planTally(plan: SetupPlan): {
+  configured: number;
+  accountable: number;
+} {
+  const accountable = plan.rows.filter(
+    (row) => row.outcome !== undefined && row.outcome.status !== "skipped",
+  );
+  const configured = accountable.filter(
+    (row) =>
+      row.outcome?.status === "done" ||
+      row.outcome?.status === "noop" ||
+      row.outcome?.status === "removed" ||
+      row.outcome?.status === "kept",
+  );
+  return { configured: configured.length, accountable: accountable.length };
+}
+
+/**
+ * Render one absolute path relative to whichever root contains it — the header
+ * names both roots once, so a row never repeats a 120-character prefix. The
+ * global root prints as `~`; the project root prints as `.`. A path under
+ * neither root stays absolute, because shortening it would be a guess — and a
+ * sibling directory whose name merely EXTENDS a root's is under neither.
+ *
+ * The project root is tried FIRST: a project checked out inside the home
+ * directory sits under both, and the more specific root is the informative one.
+ *
+ * @param path - An absolute path.
+ * @param roots - The plan's two named roots.
+ * @returns The root-relative rendering.
+ */
+export function shortenPath(path: string, roots: SetupPlan["roots"]): string {
+  for (const [root, marker] of [
+    [roots.project, "."],
+    [roots.global, "~"],
+  ] as const) {
+    if (!root) continue;
+    if (path === root) return marker;
+    // Containment is a question about path SEGMENTS, and the separator is the
+    // host's. Testing `startsWith(root + "/")` answered no for every Windows
+    // path `node:path` produces, so the plan printed absolute paths where it
+    // had just named the root they sit under — and it answered YES for a
+    // sibling whose name merely extends the root's.
+    const rel = relative(root, path);
+    if (
+      rel.length === 0 ||
+      rel === ".." ||
+      rel.startsWith(`..${sep}`) ||
+      isAbsolute(rel)
+    ) {
+      continue;
+    }
+    return `${marker}${sep}${rel}`;
+  }
+  return path;
+}
+
+/** Replace a row's outcome, leaving every other field untouched. */
+export const withOutcome = (row: PlanRow, outcome: PlanOutcome): PlanRow => ({
+  ...row,
+  outcome,
+});
+
+/** Replace a plan's rows (the wizard's edit, and the apply phase's fill-in). */
+export const withRows = (
+  plan: SetupPlan,
+  rows: readonly PlanRow[],
+): SetupPlan => ({ ...plan, rows });