@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -0,0 +1,241 @@
+/**
+ * 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 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 {
+  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;
+
+/**
+ * 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.
+ */
+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;
+}
+
+/**
+ * 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.
+ *
+ * @param style - The shared styler.
+ * @returns The styler plus `red`.
+ */
+const withRed = (style: RenderStyle): PlanStyle => ({
+  ...style,
+  red: style.enabled ? (text) => chalk.red(text) : (text) => text,
+});
+
+/** 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 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.
+ */
+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})`;
+}
+
+/** 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})`;
+
+/** 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.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 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),
+    ])
+    .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 = byBand(plan);
+  for (const [band, rows] of groups) {
+    if (plan.scope === "both") lines.push(style.bold(BAND_LABELS[band]));
+    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");
+}
+
+/**
+ * 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 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`)}`;
+  }
+
+  const glyph = GLYPHS[outcome.status];
+  const tinted =
+    outcome.status === "failed"
+      ? painted.red(glyph)
+      : outcome.status === "skipped" || outcome.status === "kept"
+        ? painted.yellow(glyph)
+        : painted.green(glyph);
+  const note = outcome.note;
+  const body =
+    outcome.status === "skipped"
+      ? `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 [band, rows] of byBand(plan)) {
+    if (plan.scope === "both") lines.push(style.bold(`  ${BAND_LABELS[band]}`));
+    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`));
+  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 : GLYPHS[status];
+    const state = status ?? row.action;
+    lines.push(
+      `- ${glyph} **${row.target}** (${row.band}): ${state} — ${detailCell(row)}`,
+    );
+    for (const child of row.children ?? []) {
+      lines.push(`  - ${childCell(child)}`);
+    }
+    if (row.outcome?.remedy) lines.push(`  - _fix:_ ${row.outcome.remedy}`);
+  }
+  return lines.join("\n");
+}

package/src/capabilities/setup/plan.ts

@@ -0,0 +1,236 @@
+/**
+ * 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 { ScopeBand, 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. `skipped` is NOT a failure — see {@link planExitFailed}. */
+export type OutcomeStatus =
+  | "done"
+  | "noop"
+  | "skipped"
+  | "failed"
+  | "removed"
+  | "kept";
+
+/** 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, e.g. `~/.claude.json — Claude Code`. */
+  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 band. */
+export interface PlanRow {
+  readonly target: TargetId;
+  readonly band: ScopeBand;
+  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 });