@mrclrchtr/supi-installer 0.0.0-stage → 9.1.0

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @mrclrchtr/supi-installer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Select direct SuPi package declarations in Project and Global scopes. This is a standalone Node CLI, not a PI extension.
+
+## Start
+
+1. Install [PI](https://pi.dev) and its required Node runtime. Make sure `pi` is on `PATH`.
+2. Open PI in the target project directory. Use `/trust` to save approval for that directory or an ancestor.
+3. Run the installer in a terminal:
+
+```sh
+npx @mrclrchtr/supi-installer@latest
+```
+
+To select another exact project directory:
+
+```sh
+npx @mrclrchtr/supi-installer@latest --project /path/to/project
+```
+
+The installer does not find a Git root, install PI, or grant project trust. Without saved project approval, it exits even for global-only changes. `PI_CODING_AGENT_DIR` selects a different PI agent directory when set.
+
+## Installation Matrix
+
+```text
+Package                         Project   Global
+supi-code-intelligence           [ ]       [x]
+supi-web                         [x]       [ ]
+```
+
+- A checkbox represents a direct declaration in that scope, not effective capability availability.
+- Project uses `<project>/.pi/settings.json`. Global uses PI's agent settings.
+- The matrix starts from current declarations, not a preset.
+- Clearing Project does not disable a global declaration. Filters and bundled extensions can also affect which capabilities load.
+- Existing pins and resource filters remain unchanged unless their declaration is removed.
+- New declarations use unpinned official npm sources. Use PI for later updates.
+
+| Key | Action |
+| --- | --- |
+| Up / Down | Select a package |
+| Left / Right | Select Project or Global |
+| Space | Change the focused checkbox |
+| `r` | Replace the focused column with Recommended |
+| `a` | Replace the focused column with All current packages |
+| `c` | Clear editable declarations in the focused column |
+| Enter | Review exact scoped changes |
+| `y` in review | Confirm and apply |
+| `e` in review | Return to editing |
+| Escape / Ctrl-C | Cancel |
+
+Use a terminal with at least 60 columns and 12 rows. Rows and the review scroll. Bracketed paste cannot edit or confirm a draft.
+
+Recommended contains the eight release-stack packages. All also includes beta packages, DevTools, Consulting, and Prompt Improver. Presets replace the draft for one column only; review can therefore include removals.
+
+## Removal and failures
+
+- Normal removal uses `pi remove` in the selected scope. It does not purge SuPi configuration, credentials, sessions, reports, or local checkouts.
+- Known obsolete standalone declarations have removal-only cells. They cannot be added to a new scope.
+- Recognized Git/local SuPi installations and legacy root installations block their scope. Remove the conflicting source with PI before using the matrix. The installer does not migrate it.
+- Unknown and unrelated declarations remain unmanaged and unchanged.
+- Settings and trust are checked again before and between commands. An observed external edit stops new commands and requires a new review.
+- Additions run before removals. A failed command does not stop independent changes, including a removal in the other scope of the same row.
+- **A failed destination install can still be followed by source removal, leaving neither declaration.** There is no automatic rollback.
+- Cancellation stops new commands and stops the active child where possible. The final report lists successes, failures, unattempted operations, and observed declarations.
+
+Run `/reload` or restart PI after package changes.
+
+## Read-only inventory
+
+```sh
+npx @mrclrchtr/supi-installer@latest --dry-run
+```
+
+This prints current declarations and scope restrictions without a terminal or package changes. It still requires PI and saved project trust. It is not a scripted target selection or an update/repair command.
+
+Use `--help` or `--version` without a trust requirement. Unattended package changes are not supported.
+
+## Development
+
+```sh
+node packages/supi-installer/bin/supi-installer.mjs --help
+pnpm vitest run packages/supi-installer/ --reporter=agent
+pnpm exec tsc -b packages/supi-installer/tsconfig.json packages/supi-installer/__tests__/tsconfig.json
+```
+
+The CLI uses checked JavaScript and has no build step. Tests use temporary settings, trust stores, and a fake PI executable. See the [installer contract](../../docs/conventions/installer.md) for the full design and verification requirements.

package/bin/supi-installer.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.mjs";
+
+const controller = new AbortController();
+const cancel = () => controller.abort();
+process.on("SIGINT", cancel);
+process.on("SIGTERM", cancel);
+try {
+  process.exitCode = await runCli(process.argv.slice(2), { signal: controller.signal });
+} finally {
+  process.removeListener("SIGINT", cancel);
+  process.removeListener("SIGTERM", cancel);
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@mrclrchtr/supi-installer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "9.1.0",
+  "description": "Select SuPi packages in project and global PI scopes",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git",
+    "directory": "packages/supi-installer"
+  },
+  "bin": {
+    "supi-installer": "bin/supi-installer.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "cross-spawn": "^7.0.6",
+    "string-width": "^8.3.0"
+  }
+}

package/src/catalog.mjs

@@ -0,0 +1,29 @@
+/** @param {string} name @param {string} description @param {string[]} labels @param {boolean} [recommended] @returns {import('./types.ts').CatalogItem} */
+function item(name, description, labels, recommended = false) {
+  return { name: `supi-${name}`, description, labels, recommended };
+}
+
+/** The only installable package catalog. Preset membership is explicit. */
+export const catalog = [
+  item("agent", "Profile-based foreground Agent Runs", ["Beta", "Agent"]),
+  item("ask-user", "Structured choice and text forms", ["Agent"], true),
+  item("bash-timeout", "Default shell timeouts", ["Beta"]),
+  item("cache", "Prompt-cache history and analysis", ["Beta"]),
+  item("claude-md", "Skills for project instructions", ["Beta"]),
+  item("code-intelligence", "Code navigation, diagnostics, and refactoring", ["Agent"], true),
+  item("consulting", "Bounded external agent consultations", ["Beta", "Opt-in", "Agent"]),
+  item("context", "Context pressure and token-use reports", ["Human"], true),
+  item("debug", "Debug events and tool feedback", ["DevTool"]),
+  item("extras", "Session controls and workflow shortcuts", ["Human"], true),
+  item("insights", "Historical session reports", ["Beta", "Human"]),
+  item("prompt-improver", "User-approved prompt improvement", ["Human"]),
+  item("prompt-suggestions", "Optional model-powered ghost text", ["Human"], true),
+  item("review", "Inspection-only reviews of Git targets", ["Beta", "Agent"]),
+  item("settings", "Shared project and global settings UI", ["Human"], true),
+  item("skills", "Scoped skill controls and shortcuts", ["Human"], true),
+  item("web", "Public web pages, search, and library docs", ["Agent"], true),
+  ...["agents", "rtk", "lsp", "tree-sitter"].map((name) => ({
+    ...item(name, "Obsolete direct installation; removal only", ["Removal only"]),
+    obsolete: true,
+  })),
+];

package/src/cli.mjs

@@ -0,0 +1,108 @@
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { executePlan } from "./execution.mjs";
+import { cleanLine, formatInventory, formatReport } from "./format.mjs";
+import { createContext, readInventory } from "./inventory.mjs";
+import { createMatrix } from "./matrix.mjs";
+import { createPiRunner, requirePi } from "./process.mjs";
+import { runTerminal } from "./ui/terminal.mjs";
+
+const HELP = `Usage: supi-installer [--project <path>] [--dry-run]
+
+Select direct SuPi package declarations in Project and Global scopes.
+
+  --project <path>  Use this exact directory; do not infer a Git root
+  --dry-run         Print current declarations; do not change packages
+  --help, -h        Show help
+  --version, -v     Show the installer version
+
+Requires PI on PATH and saved PI trust for the project, even for global work.
+Open PI in that directory and use /trust before starting the installer.
+
+Arrows: select row/scope. Space: toggle. r/a/c: Recommended/All/Clear column.
+Enter: review. y: confirm in review. Escape: cancel.
+No unattended package changes are supported.
+`;
+
+/** CLI boundary shared by the executable and terminal tests. @param {string[]} args @param {{input?: NodeJS.ReadStream, output?: NodeJS.WriteStream, error?: NodeJS.WriteStream, runner?: import('./types.ts').Runner, signal?: AbortSignal}} [options] */
+export async function runCli(args, options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const errorOutput = options.error ?? process.stderr;
+  try {
+    const { values } = parseArgs({
+      args,
+      strict: true,
+      allowPositionals: false,
+      options: {
+        project: { type: "string" },
+        "dry-run": { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+      },
+    });
+    if (values.help) {
+      output.write(HELP);
+      return 0;
+    }
+    if (values.version) {
+      output.write(
+        `${JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version}\n`,
+      );
+      return 0;
+    }
+    if (!values["dry-run"] && (!input.isTTY || !output.isTTY))
+      throw new Error(
+        "An interactive terminal is required. Use --dry-run to print current declarations.",
+      );
+    const context = createContext({ project: values.project });
+    const inventory = readInventory(context);
+    const runner =
+      options.runner ??
+      createPiRunner({ env: { ...process.env, PI_CODING_AGENT_DIR: context.agentDir } });
+    await requirePi(runner, context.project, options.signal);
+    if (values["dry-run"]) {
+      output.write(`${formatInventory(inventory).join("\n")}\n`);
+      return 0;
+    }
+    return await runInteractive(inventory, { input, output, runner, signal: options.signal });
+  } catch (error) {
+    if (options.signal?.aborted) {
+      errorOutput.write("Cancelled. No more commands will start.\n");
+      return 130;
+    }
+    errorOutput.write(
+      `Error: ${cleanLine(error instanceof Error ? error.message : String(error))}\n`,
+    );
+    return 1;
+  }
+}
+
+/** @param {import('./types.ts').Inventory} inventory @param {{input: NodeJS.ReadStream, output: NodeJS.WriteStream, runner: import('./types.ts').Runner, signal?: AbortSignal}} options */
+async function runInteractive(inventory, options) {
+  const { input, output, runner } = options;
+  const plan = await runTerminal(createMatrix(inventory), {
+    input,
+    output,
+    signal: options.signal,
+  });
+  if (plan === null) {
+    output.write("Cancelled. No package commands ran.\n");
+    return options.signal?.aborted ? 130 : 0;
+  }
+  if (plan.length === 0) {
+    output.write("No changes. No package commands ran.\n");
+    return 0;
+  }
+  const report = await executePlan(inventory, plan, {
+    runner,
+    signal: options.signal,
+    onProgress: (operation) => {
+      output.write(
+        `${cleanLine(`${operation.action.toUpperCase()} ${operation.scope}: ${operation.source}`)}\n`,
+      );
+    },
+  });
+  output.write(`${formatReport(report)}\n`);
+  return report.cancelled ? 130 : report.ok ? 0 : 1;
+}

package/src/execution.mjs

@@ -0,0 +1,115 @@
+import { isRecord } from "./files.mjs";
+import { readInventory } from "./inventory.mjs";
+import { npmName } from "./sources.mjs";
+
+/** @typedef {import('./types.ts').Inventory} Inventory */
+/** @typedef {import('./types.ts').Operation} Operation */
+
+/** Ignore JSON formatting, but not object values or package order. @param {unknown} value */
+function canonical(value) {
+  return JSON.stringify(value, (_key, item) =>
+    isRecord(item)
+      ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)))
+      : item,
+  );
+}
+
+/** @param {Inventory} inventory @param {Operation} operation */
+function expectedEntries(inventory, operation) {
+  const entries = inventory.entries[operation.scope];
+  return operation.action === "install"
+    ? [...entries, operation.source]
+    : entries.filter(
+        (entry) =>
+          npmName(typeof entry === "string" ? entry : entry.source) !==
+          `@mrclrchtr/${operation.name}`,
+      );
+}
+
+/** A child may change its own declaration, not unrelated state. This detects observed edits, not an atomic filesystem transaction. @param {Inventory} before @param {Inventory} after @param {Operation} operation */
+function isAllowedChange(before, after, operation) {
+  const path = before.context.settingsPaths[operation.scope];
+  const paths = new Set([...Object.keys(before.files), ...Object.keys(after.files)]);
+  for (const file of paths) {
+    if (file !== path && before.files[file] !== after.files[file]) return false;
+  }
+  const otherFields = /** @param {Inventory} inventory */ (inventory) => {
+    const data = JSON.parse((inventory.files[path] ?? "{}").replace(/^\uFEFF/, ""));
+    delete data.packages;
+    return canonical(data);
+  };
+  if (otherFields(before) !== otherFields(after)) return false;
+  const actual = canonical(after.entries[operation.scope]);
+  return (
+    actual === canonical(before.entries[operation.scope]) ||
+    actual === canonical(expectedEntries(before, operation))
+  );
+}
+
+/** Run one command and check that only its declaration changed. @param {Inventory} before @param {import('./types.ts').OperationResult} result @param {{runner: import('./types.ts').Runner, signal: AbortSignal, onProgress?: (operation: Operation) => void}} options */
+async function attemptOperation(before, result, options) {
+  const operation = result.operation;
+  options.onProgress?.(operation);
+  const args = [
+    operation.action,
+    operation.source,
+    ...(operation.scope === "project" ? ["--local"] : []),
+  ];
+  let outcome;
+  try {
+    outcome = await options.runner(args, { cwd: before.context.project, signal: options.signal });
+  } catch (error) {
+    outcome = { code: 1, output: error instanceof Error ? error.message : String(error) };
+  }
+  result.output = outcome.output;
+  result.status = outcome.code === 0 ? "success" : "failed";
+  const after = readInventory(before.context);
+  if (!isAllowedChange(before, after, operation))
+    throw new Error(
+      "Settings changed outside the selected operation. Remaining commands were not started; review a new plan.",
+    );
+  if (
+    outcome.code === 0 &&
+    canonical(after.entries[operation.scope]) !== canonical(expectedEntries(before, operation))
+  ) {
+    result.status = "failed";
+    result.output += "\nPI reported success, but the expected declaration change was not found.";
+  }
+  return after;
+}
+
+/** Execute a confirmed plan. Failures do not guard scope moves or roll back successful changes. @param {Inventory} initial @param {Operation[]} operations @param {{runner: import('./types.ts').Runner, signal?: AbortSignal, onProgress?: (operation: Operation) => void}} options @returns {Promise<import('./types.ts').ExecutionReport>} */
+export async function executePlan(initial, operations, options) {
+  const signal = options.signal ?? new AbortController().signal;
+  const results = operations.map((operation) => ({
+    operation,
+    status: /** @type {'success' | 'failed' | 'unattempted'} */ ("unattempted"),
+    output: "",
+  }));
+  /** @type {import('./types.ts').ExecutionReport} */
+  const report = { results, ok: true, cancelled: false };
+  let expected = initial;
+  try {
+    for (const result of results) {
+      if (signal.aborted) break;
+      const before = readInventory(initial.context);
+      if (before.fingerprint !== expected.fingerprint)
+        throw new Error(
+          "Settings or trust changed after review. Open the installer and review a new plan.",
+        );
+      expected = await attemptOperation(before, result, { ...options, signal });
+    }
+  } catch (error) {
+    report.error = error instanceof Error ? error.message : String(error);
+  }
+  report.cancelled = signal.aborted;
+  try {
+    report.inventory = readInventory(initial.context);
+  } catch (error) {
+    delete report.inventory;
+    report.error = error instanceof Error ? error.message : String(error);
+  }
+  report.ok =
+    !report.error && !report.cancelled && results.every((result) => result.status === "success");
+  return report;
+}

package/src/files.mjs

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+export function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Read without creating files. Only absence means an empty document. @param {string} path */
+export function readOptional(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+    throw new Error(`Cannot read ${path}`, { cause: error });
+  }
+}
+
+/** @param {string} path @param {Record<string, string | null>} files */
+export function readObject(path, files) {
+  const text = readOptional(path);
+  files[path] = text;
+  if (text === null) return {};
+  try {
+    const value = JSON.parse(text.replace(/^\uFEFF/, ""));
+    if (!isRecord(value)) throw new Error("Expected a JSON object");
+    return value;
+  } catch (error) {
+    throw new Error(`Invalid JSON object in ${path}`, { cause: error });
+  }
+}
+
+/** Include raw text so external edits cannot silently reuse an old plan. @param {Record<string, string | null>} files */
+export function fingerprint(files) {
+  return createHash("sha256")
+    .update(JSON.stringify(Object.entries(files).sort(([a], [b]) => a.localeCompare(b))))
+    .digest("hex");
+}

package/src/format.mjs

@@ -0,0 +1,80 @@
+import { sourceOf } from "./sources.mjs";
+
+/** Keep settings and child output from sending terminal control sequences. @param {string} text */
+export function cleanLine(text) {
+  return text.replace(/[\p{Cc}\p{Cf}]/gu, " ");
+}
+
+/** Read-only declarations, not a claim about loaded resources. @param {import('./types.ts').Inventory} inventory */
+export function formatInventory(inventory) {
+  const lines = [
+    "Direct package declarations",
+    `Project: ${inventory.context.project}`,
+    `Global: ${inventory.context.settingsPaths.global}`,
+  ];
+  if (inventory.context.project === inventory.context.home)
+    lines.push("Warning: Project is your home directory.");
+  for (const scope of /** @type {const} */ (["project", "global"]))
+    lines.push(...formatScope(inventory, scope));
+  return lines.map(cleanLine);
+}
+
+/** @param {import('./types.ts').Inventory} inventory @param {import('./types.ts').Scope} scope */
+function formatScope(inventory, scope) {
+  const lines = ["", `${scope.toUpperCase()} (${inventory.context.settingsPaths[scope]})`];
+  if (inventory.entries[scope].length === 0) lines.push("  No package declarations.");
+  for (const entry of inventory.entries[scope])
+    lines.push(
+      `  ${sourceOf(entry)}${typeof entry === "string" ? "" : ` (filtered/object entry: ${JSON.stringify(entry)})`}`,
+    );
+  for (const source of inventory.blocked[scope]) {
+    lines.push(
+      `  BLOCKED: ${source}`,
+      `  Remove this source with PI before changing this scope: pi remove <source>${scope === "project" ? " --local" : ""}`,
+    );
+  }
+  for (const source of inventory.unmanaged[scope]) lines.push(`  Unmanaged; retained: ${source}`);
+  return lines;
+}
+
+/** Show exact scoped sources and the accepted independent-failure policy. @param {import('./matrix.mjs').Matrix} matrix @param {import('./types.ts').Operation[]} operations */
+export function formatReview(matrix, operations) {
+  return [
+    ...formatInventory(matrix.inventory),
+    "",
+    "Planned changes:",
+    ...operations.map(
+      (operation) => `${operation.action.toUpperCase()} ${operation.scope}: ${operation.source}`,
+    ),
+    ...(operations.length === 0 ? ["No changes. No package commands will run."] : []),
+    "",
+    "Clearing Project can expose a global declaration.",
+    "Removal retains user data. Bundled behavior can remain available.",
+    "Commands are independent. A failed destination install does NOT prevent source removal.",
+    "A failed scope move can leave neither declaration. There is no automatic rollback.",
+  ].map(cleanLine);
+}
+
+/** @param {import('./types.ts').ExecutionReport} report */
+export function formatReport(report) {
+  const lines = [report.ok ? "Changes complete." : "Changes did not complete successfully."];
+  for (const { operation, status, output } of report.results) {
+    lines.push(
+      `${status.toUpperCase()}: ${operation.action} ${operation.scope}: ${operation.source}`,
+    );
+    if (output.trim())
+      lines.push(
+        ...output
+          .trim()
+          .split(/\r?\n/)
+          .map((line) => `  ${line}`),
+      );
+  }
+  if (report.cancelled) lines.push("Cancelled. No more commands will start.");
+  if (report.error) lines.push(`Error: ${report.error}`);
+  if (report.inventory) lines.push("", ...formatInventory(report.inventory));
+  else lines.push("Final declarations could not be read. Inspect them with PI before retrying.");
+  if (report.results.some((result) => result.status !== "unattempted"))
+    lines.push("", "Run /reload or restart PI after package changes.");
+  return lines.map(cleanLine).join("\n");
+}

package/src/inventory.mjs

@@ -0,0 +1,95 @@
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fingerprint, isRecord, readObject } from "./files.mjs";
+import { canonicalPath, expandPath } from "./paths.mjs";
+import { classifySources } from "./sources.mjs";
+
+/** @typedef {import('./types.ts').Context} Context */
+/** @typedef {import('./types.ts').PackageEntry} PackageEntry */
+
+/** Resolve a project directory without selecting a Git root. @param {{project?: string, cwd?: string, agentDir?: string, home?: string}} [options] @returns {Context} */
+export function createContext(options = {}) {
+  const home = options.home ?? homedir();
+  const cwd = options.cwd ?? process.cwd();
+  const project = realpathSync(resolve(cwd, expandPath(options.project ?? cwd, home)));
+  if (!statSync(project).isDirectory()) throw new Error(`Not a project directory: ${project}`);
+  const agentDir = resolve(
+    cwd,
+    expandPath(
+      options.agentDir ?? (process.env.PI_CODING_AGENT_DIR || join(home, ".pi/agent")),
+      home,
+    ),
+  );
+  const settingsPaths = {
+    project: join(project, ".pi/settings.json"),
+    global: join(agentDir, "settings.json"),
+  };
+  if (canonicalPath(settingsPaths.project) === canonicalPath(settingsPaths.global))
+    throw new Error(
+      "Global and project settings resolve to the same file. Select separate scopes before using the installer.",
+    );
+  return { project, agentDir, home, settingsPaths };
+}
+
+/** @param {Context} context @param {Record<string, string | null>} files */
+function requireTrust(context, files) {
+  const path = join(context.agentDir, "trust.json");
+  const data = readObject(path, files);
+  if (Object.values(data).some((value) => value !== true && value !== false && value !== null))
+    throw new Error(`Invalid decision in ${path}`);
+  let current = context.project;
+  while (true) {
+    const decision = Object.hasOwn(data, current) ? data[current] : null;
+    if (decision === true) return;
+    if (decision === false || dirname(current) === current) break;
+    current = dirname(current);
+  }
+  throw new Error(
+    `A saved PI trust approval is required for ${context.project}. Open PI in that directory, use /trust, then rerun the installer.`,
+  );
+}
+
+/** Validate only the package fields that this CLI must interpret. @param {unknown} entry @param {string} path @returns {PackageEntry} */
+function validateEntry(entry, path) {
+  if (typeof entry === "string" && entry.trim()) return entry;
+  if (!isRecord(entry) || typeof entry.source !== "string" || !entry.source.trim())
+    throw new Error(`Invalid package source in ${path}`);
+  for (const key of ["extensions", "skills", "prompts", "themes"]) {
+    if (
+      entry[key] !== undefined &&
+      (!Array.isArray(entry[key]) || !entry[key].every((value) => typeof value === "string"))
+    )
+      throw new Error(`Invalid ${key} in ${path}`);
+  }
+  if (entry.autoload !== undefined && typeof entry.autoload !== "boolean")
+    throw new Error(`Invalid autoload in ${path}`);
+  return /** @type {PackageEntry} */ (entry);
+}
+
+/** Observe both scopes without starting PI or changing settings or trust. @param {Context} context @returns {import('./types.ts').Inventory} */
+export function readInventory(context) {
+  /** @type {Record<string, string | null>} */
+  const files = {};
+  requireTrust(context, files);
+  /** @type {Record<import('./types.ts').Scope, PackageEntry[]>} */
+  const entries = { project: [], global: [] };
+  for (const scope of /** @type {const} */ (["project", "global"])) {
+    const path = context.settingsPaths[scope];
+    const data = readObject(path, files);
+    if (data.packages !== undefined && !Array.isArray(data.packages))
+      throw new Error(`Invalid packages in ${path}`);
+    entries[scope] = (data.packages ?? []).map((entry) => validateEntry(entry, path));
+  }
+  const inventory = {
+    context,
+    entries,
+    blocked: { project: [], global: [] },
+    unmanaged: { project: [], global: [] },
+    files,
+    fingerprint: "",
+  };
+  classifySources(inventory);
+  inventory.fingerprint = fingerprint(files);
+  return inventory;
+}

package/src/matrix.mjs

@@ -0,0 +1,75 @@
+import { catalog } from "./catalog.mjs";
+import { npmName, sourceOf } from "./sources.mjs";
+
+/** @typedef {{ inventory: import('./types.ts').Inventory, rows: import('./types.ts').MatrixRow[] }} Matrix */
+/** @typedef {import('./types.ts').Scope} Scope */
+
+/** Initialize from declarations, never from a preset. @param {import('./types.ts').Inventory} inventory @returns {Matrix} */
+export function createMatrix(inventory) {
+  const rows = catalog.map((item) => {
+    const find = /** @param {Scope} scope */ (scope) =>
+      inventory.entries[scope].find(
+        (entry) => npmName(sourceOf(entry)) === `@mrclrchtr/${item.name}`,
+      );
+    const initial = { project: find("project"), global: find("global") };
+    return {
+      item,
+      initial,
+      selected: { project: Boolean(initial.project), global: Boolean(initial.global) },
+    };
+  });
+  return {
+    inventory,
+    rows: rows.filter((row) => !row.item.obsolete || row.initial.project || row.initial.global),
+  };
+}
+
+/** @param {Matrix} matrix @param {number} index @param {Scope} scope */
+export function canEdit(matrix, index, scope) {
+  const row = matrix.rows[index];
+  return Boolean(
+    row &&
+      matrix.inventory.blocked[scope].length === 0 &&
+      (!row.item.obsolete || row.initial[scope]),
+  );
+}
+
+/** Removal-only rows permit undo but not new declarations. @param {Matrix} matrix @param {number} index @param {Scope} scope */
+export function toggleCell(matrix, index, scope) {
+  if (!canEdit(matrix, index, scope)) return false;
+  const row = matrix.rows[index];
+  row.selected[scope] = !row.selected[scope];
+  return true;
+}
+
+/** Replace only the focused scope's draft. @param {Matrix} matrix @param {Scope} scope @param {'recommended' | 'all' | 'clear'} preset */
+export function applyPreset(matrix, scope, preset) {
+  for (const [index, row] of matrix.rows.entries()) {
+    if (canEdit(matrix, index, scope))
+      row.selected[scope] =
+        !row.item.obsolete &&
+        (preset === "all" || (preset === "recommended" && row.item.recommended));
+  }
+}
+
+/** Create a plan with additions before removals, without scope-move guards. @param {Matrix} matrix @returns {import('./types.ts').Operation[]} */
+export function getPlan(matrix) {
+  /** @type {import('./types.ts').Operation[]} */
+  const operations = [];
+  for (const [index, row] of matrix.rows.entries()) {
+    for (const scope of /** @type {const} */ (["project", "global"])) {
+      const entry = row.initial[scope];
+      if (!canEdit(matrix, index, scope) || row.selected[scope] === Boolean(entry)) continue;
+      operations.push({
+        action: row.selected[scope] ? "install" : "remove",
+        scope,
+        name: row.item.name,
+        source: entry ? sourceOf(entry) : `npm:@mrclrchtr/${row.item.name}`,
+      });
+    }
+  }
+  return [
+    ...operations.filter((op) => op.action === "install"),
+    ...operations.filter((op) => op.action === "remove"),
+  ];
+}

package/src/paths.mjs

@@ -0,0 +1,22 @@
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Resolve existing file aliases; a missing file keeps its absolute path. @param {string} path */
+export function canonicalPath(path) {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return path;
+    throw error;
+  }
+}
+
+/** Match PI's tilde and file URL path forms. @param {string} path @param {string} [home] */
+export function expandPath(path, home = homedir()) {
+  if (path === "~") return home;
+  if (path.startsWith("~/") || (process.platform === "win32" && path.startsWith("~\\")))
+    return join(home, path.slice(2));
+  return path.startsWith("file://") ? fileURLToPath(path) : path;
+}

package/src/process-tree.mjs

@@ -0,0 +1,29 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+
+/** Stop the owned command group on Unix, or the npm shim and its descendants on Windows. @param {number | undefined} pid @param {boolean} force */
+export async function terminateTree(pid, force) {
+  if (pid === undefined) return;
+  if (process.platform === "win32") {
+    await new Promise((resolve, reject) => {
+      const command = join(process.env.SystemRoot || "C:\\Windows", "System32", "taskkill.exe");
+      const child = spawn(command, ["/PID", String(pid), "/T", "/F"], {
+        windowsHide: true,
+        shell: false,
+        stdio: "ignore",
+      });
+      child.once("error", reject);
+      child.once("close", (code) => {
+        // A second stop can find that the root process has already exited.
+        if (code === 0 || code === 128) resolve(undefined);
+        else reject(new Error(`Could not stop the PI process tree (taskkill status ${code}).`));
+      });
+    });
+    return;
+  }
+  try {
+    process.kill(-pid, force ? "SIGKILL" : "SIGTERM");
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) throw error;
+  }
+}

package/src/process.mjs

@@ -0,0 +1,72 @@
+import spawn from "cross-spawn";
+import { terminateTree } from "./process-tree.mjs";
+
+/** Portable PI command boundary. cross-spawn handles Windows npm shims and escaping. @param {{command?: string, prefix?: string[], env?: NodeJS.ProcessEnv}} [options] @returns {import('./types.ts').Runner} */
+export function createPiRunner(options = {}) {
+  return (args, { cwd, signal }) =>
+    new Promise((resolve) => {
+      if (signal.aborted) {
+        resolve({ code: 130, output: "Cancelled" });
+        return;
+      }
+      const child = spawn(options.command ?? "pi", [...(options.prefix ?? []), ...args], {
+        cwd,
+        env: options.env ?? process.env,
+        detached: process.platform !== "win32",
+        shell: false,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      let output = "";
+      const append = /** @param {Buffer} chunk */ (chunk) => {
+        output = `${output}${chunk.toString()}`.slice(-65_536);
+      };
+      child.stdout?.on("data", append);
+      child.stderr?.on("data", append);
+      let failed = false;
+      /** @type {NodeJS.Timeout | undefined} */
+      let killTimer;
+      let termination = Promise.resolve();
+      const stopError = /** @param {unknown} error */ (error) => {
+        output += `\n${error instanceof Error ? error.message : String(error)}`;
+      };
+      const stop = () => {
+        termination = terminateTree(child.pid, false).catch(stopError);
+        killTimer = setTimeout(() => {
+          void terminateTree(child.pid, true).catch(stopError);
+        }, 2_000);
+        killTimer.unref();
+      };
+      signal.addEventListener("abort", stop, { once: true });
+      child.once("error", (error) => {
+        failed = true;
+        output += `\n${error.message}`;
+      });
+      /** @param {number | null} code */
+      async function finish(code) {
+        signal.removeEventListener("abort", stop);
+        clearTimeout(killTimer);
+        if (signal.aborted) {
+          await termination;
+          await terminateTree(child.pid, true).catch(stopError);
+        }
+        resolve({ code: signal.aborted ? 130 : failed ? 1 : (code ?? 1), output });
+      }
+      child.once("close", (code) => {
+        void finish(code);
+      });
+    });
+}
+
+/** Check the executable without starting an agent session. The caller can cancel; a stalled version check also has a time limit. @param {import('./types.ts').Runner} runner @param {string} cwd @param {AbortSignal} [signal] */
+export async function requirePi(runner, cwd, signal = new AbortController().signal) {
+  if (signal.aborted) throw new Error("Cancelled while checking PI.");
+  const timeout = AbortSignal.timeout(10_000);
+  const result = await runner(["--version"], { cwd, signal: AbortSignal.any([signal, timeout]) });
+  if (signal.aborted) throw new Error("Cancelled while checking PI.");
+  if (timeout.aborted) throw new Error("PI did not respond to --version within 10 seconds.");
+  if (result.code !== 0)
+    throw new Error(
+      "PI is not available on PATH. Install PI from https://pi.dev, then rerun the installer.",
+    );
+}

package/src/sources.mjs

@@ -0,0 +1,88 @@
+import { statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { catalog } from "./catalog.mjs";
+import { readObject, readOptional } from "./files.mjs";
+import { expandPath } from "./paths.mjs";
+
+/** @param {import('./types.ts').PackageEntry} entry */
+export function sourceOf(entry) {
+  return typeof entry === "string" ? entry : entry.source;
+}
+
+/** Pins do not change the npm package identity. @param {string} source */
+export function npmName(source) {
+  if (!source.startsWith("npm:")) return undefined;
+  return /^(@[^/\s]+\/[^@\s]+|[^@\s]+)(?:@.+)?$/.exec(source.slice(4).trim())?.[1];
+}
+
+/** @param {string} source */
+function isRootGit(source) {
+  if (!/^(git:|github:|https?:|ssh:|git@)/.test(source)) return false;
+  const normalized = source
+    .replace(/^(git:(?!\/\/)|github:)/, "")
+    .replace(/^[a-z]+:\/\//, "")
+    .replace(/^git@/, "")
+    .replace(/^github\.com:/, "github.com/");
+  return /^(?:github\.com\/)?mrclrchtr\/supi(?:\.git)?\/?(?:[@#][^\s]+)?$/i.test(normalized);
+}
+
+/** Inspect local manifests as data, never as executable modules. @param {string} source @param {string} base @param {import('./types.ts').Inventory} inventory */
+function localPackageName(source, base, inventory) {
+  let path = resolve(base, expandPath(source, inventory.context.home));
+  try {
+    if (!statSync(path).isDirectory()) path = dirname(path);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+  while (true) {
+    const manifest = join(path, "package.json");
+    const text = readOptional(manifest);
+    inventory.files[manifest] = text;
+    if (text !== null) return readObject(manifest, inventory.files).name;
+    if (dirname(path) === path) return undefined;
+    path = dirname(path);
+  }
+}
+
+const managedNames = new Set(catalog.map((item) => `@mrclrchtr/${item.name}`));
+
+/** @param {unknown} name */
+function isSuPiName(name) {
+  return (
+    typeof name === "string" &&
+    (managedNames.has(name) || name === "@mrclrchtr/supi" || name === "@mrclrchtr/supi-workspace")
+  );
+}
+
+/** @param {string} source @param {import('./types.ts').Scope} scope @param {import('./types.ts').Inventory} inventory */
+function isBlocked(source, scope, inventory) {
+  const name = npmName(source);
+  if (name === "@mrclrchtr/supi" || name === "@mrclrchtr/supi-workspace" || isRootGit(source))
+    return true;
+  if (/^(npm:|git:|github:|https?:|ssh:|git@|builtin:)/.test(source)) return false;
+  return isSuPiName(
+    localPackageName(source, dirname(inventory.context.settingsPaths[scope]), inventory),
+  );
+}
+
+/** Classify sources without changing declarations. @param {import('./types.ts').Inventory} inventory */
+export function classifySources(inventory) {
+  for (const scope of /** @type {const} */ (["project", "global"])) {
+    const seen = new Set();
+    for (const entry of inventory.entries[scope]) {
+      const source = sourceOf(entry);
+      const name = npmName(source);
+      if (name && managedNames.has(name)) {
+        if (seen.has(name))
+          throw new Error(
+            `Duplicate managed package ${name} in ${inventory.context.settingsPaths[scope]}`,
+          );
+        seen.add(name);
+        continue;
+      }
+      if (isBlocked(source, scope, inventory)) inventory.blocked[scope].push(source);
+      else inventory.unmanaged[scope].push(source);
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,65 @@
+/** Installer scope names match the two matrix columns. */
+export type Scope = "project" | "global";
+/** Preserve object entries, including fields not owned by the installer. */
+export type PackageEntry = string | { source: string; [key: string]: unknown };
+/** Paths used by inventory reads and PI child commands. */
+export interface Context {
+  project: string;
+  agentDir: string;
+  home: string;
+  settingsPaths: Record<Scope, string>;
+}
+/** One read-only observation of declarations and source restrictions. */
+export interface Inventory {
+  context: Context;
+  entries: Record<Scope, PackageEntry[]>;
+  blocked: Record<Scope, string[]>;
+  unmanaged: Record<Scope, string[]>;
+  files: Record<string, string | null>;
+  fingerprint: string;
+}
+/** Catalog metadata is shipped with the CLI. */
+export interface CatalogItem {
+  name: string;
+  description: string;
+  labels: string[];
+  recommended: boolean;
+  obsolete?: boolean;
+}
+/** A row retains the source entry separately from the draft selections. */
+export interface MatrixRow {
+  item: CatalogItem;
+  initial: Record<Scope, PackageEntry | undefined>;
+  selected: Record<Scope, boolean>;
+}
+/** A reviewed change to one direct declaration. */
+export interface Operation {
+  action: "install" | "remove";
+  scope: Scope;
+  name: string;
+  source: string;
+}
+/** Child outcome includes errors that can occur before a process starts. */
+export interface CommandResult {
+  code: number;
+  output: string;
+}
+/** The process boundary can use a fake PI executable in tests. */
+export type Runner = (
+  args: string[],
+  options: { cwd: string; signal: AbortSignal },
+) => Promise<CommandResult>;
+/** Report all planned operations, including those not attempted. */
+export interface OperationResult {
+  operation: Operation;
+  status: "success" | "failed" | "unattempted";
+  output: string;
+}
+/** Execution never promises rollback or a complete filesystem inventory. */
+export interface ExecutionReport {
+  results: OperationResult[];
+  inventory?: Inventory;
+  error?: string;
+  cancelled: boolean;
+  ok: boolean;
+}

package/src/ui/controls.mjs

@@ -0,0 +1,90 @@
+import { applyPreset, toggleCell } from "../matrix.mjs";
+
+/** Ignore bracketed paste; only key input can edit or confirm a draft. @param {import('./view.mjs').View} view @param {import('node:readline').Key} key @param {{pasting: boolean, width: number, height: number}} input */
+export function handleKey(view, key, input) {
+  if (key.sequence === "\u001b[200~") {
+    input.pasting = true;
+    return "ignore";
+  }
+  if (key.sequence === "\u001b[201~") {
+    input.pasting = false;
+    return "ignore";
+  }
+  if (input.pasting) return "ignore";
+  if (key.name === "escape" || (key.ctrl && key.name === "c")) return "cancel";
+  if (input.width < 60 || input.height < 12) return "ignore";
+  if (view.review) return editReview(view, key.name) ? "apply" : "draw";
+  editMatrix(view, key.name);
+  return "draw";
+}
+
+/** Set the alternate screen, cursor, and bracketed-paste modes. @param {NodeJS.WriteStream} output @param {boolean} enabled */
+export function screenMode(output, enabled) {
+  const prefix = "\u001b[?";
+  output.write(`${prefix}1049${enabled ? "h" : "l"}`);
+  output.write(`${prefix}25${enabled ? "l" : "h"}`);
+  output.write(`${prefix}2004${enabled ? "h" : "l"}`);
+}
+
+/** @param {{input: NodeJS.ReadStream, output: NodeJS.WriteStream, wasRaw: boolean, wasFlowing: boolean | null}} state */
+export function restoreTerminal({ input, output, wasRaw, wasFlowing }) {
+  input.setRawMode(wasRaw);
+  if (wasFlowing !== true) input.pause();
+  if (!output.destroyed) screenMode(output, false);
+}
+
+/** @param {import('./view.mjs').View} view @param {string | undefined} name */
+export function editMatrix(view, name) {
+  switch (name) {
+    case "up":
+      view.index = Math.max(0, view.index - 1);
+      break;
+    case "down":
+      view.index = Math.min(view.matrix.rows.length - 1, view.index + 1);
+      break;
+    case "left":
+      view.scope = "project";
+      break;
+    case "right":
+      view.scope = "global";
+      break;
+    case "space":
+      toggleCell(view.matrix, view.index, view.scope);
+      break;
+    case "r":
+      applyPreset(view.matrix, view.scope, "recommended");
+      break;
+    case "a":
+      applyPreset(view.matrix, view.scope, "all");
+      break;
+    case "c":
+      applyPreset(view.matrix, view.scope, "clear");
+      break;
+    case "return":
+      view.review = true;
+      view.offset = 0;
+      break;
+    default:
+      break;
+  }
+}
+
+/** @param {import('./view.mjs').View} view @param {string | undefined} name */
+export function editReview(view, name) {
+  switch (name) {
+    case "y":
+      return true;
+    case "e":
+      view.review = false;
+      break;
+    case "up":
+      view.offset--;
+      break;
+    case "down":
+      view.offset++;
+      break;
+    default:
+      break;
+  }
+  return false;
+}

package/src/ui/terminal.mjs

@@ -0,0 +1,90 @@
+import { emitKeypressEvents } from "node:readline";
+import { getPlan } from "../matrix.mjs";
+import { handleKey, restoreTerminal, screenMode } from "./controls.mjs";
+import { renderView } from "./view.mjs";
+
+/** Own raw mode and screen state only while editing. Confirmation returns a plan; it never executes commands. @param {import('../matrix.mjs').Matrix} matrix @param {{input: NodeJS.ReadStream, output: NodeJS.WriteStream, signal?: AbortSignal}} options @returns {Promise<import('../types.ts').Operation[] | null>} */
+export function runTerminal(matrix, { input, output, signal }) {
+  return new Promise((resolve, reject) => {
+    /** @type {import('./view.mjs').View} */
+    const view = { matrix, index: 0, scope: "project", review: false, offset: 0 };
+    const wasRaw = Boolean(input.isRaw);
+    const wasFlowing = input.readableFlowing;
+    let settled = false;
+    const keyState = { pasting: false, width: 80, height: 24 };
+    const size = () => ({ width: output.columns ?? 80, height: output.rows ?? 24 });
+    const draw = () => {
+      output.write(`\u001b[H\u001b[2J${renderView(view, size())}`);
+    };
+    /** @param {import('../types.ts').Operation[] | null} value @param {Error} [error] */
+    function finish(value, error) {
+      if (settled) return;
+      settled = true;
+      input.removeListener("keypress", onKey);
+      input.removeListener("end", cancel);
+      input.removeListener("close", cancel);
+      input.removeListener("error", fail);
+      output.removeListener("resize", draw);
+      output.removeListener("error", fail);
+      signal?.removeEventListener("abort", cancel);
+      try {
+        restoreTerminal({ input, output, wasRaw, wasFlowing });
+      } catch (cleanupError) {
+        reject(cleanupError);
+        return;
+      }
+      if (error) reject(error);
+      else resolve(value);
+    }
+    function cancel() {
+      finish(null);
+    }
+    /** @param {Error} error */
+    function fail(error) {
+      finish(null, error);
+    }
+    /** @param {string} _text @param {import('node:readline').Key} key */
+    function onKey(_text, key) {
+      try {
+        Object.assign(keyState, size());
+        switch (handleKey(view, key, keyState)) {
+          case "cancel":
+            cancel();
+            break;
+          case "apply":
+            finish(getPlan(matrix));
+            break;
+          case "draw":
+            draw();
+            break;
+          case "ignore":
+            break;
+          default:
+            break;
+        }
+      } catch (error) {
+        fail(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+    try {
+      emitKeypressEvents(input);
+      input.on("keypress", onKey);
+      input.once("end", cancel);
+      input.once("close", cancel);
+      input.once("error", fail);
+      output.on("resize", draw);
+      output.once("error", fail);
+      signal?.addEventListener("abort", cancel, { once: true });
+      if (signal?.aborted) {
+        cancel();
+        return;
+      }
+      input.setRawMode(true);
+      input.resume();
+      screenMode(output, true);
+      draw();
+    } catch (error) {
+      fail(error instanceof Error ? error : new Error(String(error)));
+    }
+  });
+}

package/src/ui/view.mjs

@@ -0,0 +1,105 @@
+import stringWidth from "string-width";
+import { cleanLine, formatReview } from "../format.mjs";
+import { getPlan } from "../matrix.mjs";
+import { sourceOf } from "../sources.mjs";
+
+/** @typedef {{matrix: import('../matrix.mjs').Matrix, index: number, scope: import('../types.ts').Scope, review: boolean, offset: number}} View */
+
+/** Clip by terminal cells, not UTF-16 units. @param {string} line @param {number} width */
+function clipLine(line, width) {
+  let result = "";
+  let size = 0;
+  for (const char of cleanLine(line)) {
+    size += stringWidth(char);
+    if (size > width) break;
+    result += char;
+  }
+  return result;
+}
+
+/** Keep every source character available in the scrollable review. @param {string} line @param {number} width */
+function wrapLine(line, width) {
+  const lines = [];
+  let part = "";
+  let size = 0;
+  for (const char of cleanLine(line)) {
+    const cells = stringWidth(char);
+    if (size + cells > width) {
+      lines.push(part);
+      part = "";
+      size = 0;
+    }
+    part += char;
+    size += cells;
+  }
+  return [...lines, part];
+}
+
+/** @param {View} view @param {number} index @param {import('../types.ts').Scope} scope */
+function cell(view, index, scope) {
+  const row = view.matrix.rows[index];
+  const locked =
+    view.matrix.inventory.blocked[scope].length > 0 || (row.item.obsolete && !row.initial[scope]);
+  const value = row.selected[scope] ? "x" : " ";
+  return `${view.index === index && view.scope === scope ? ">" : " "}${locked ? `(${value})` : `[${value}]`}`;
+}
+
+/** @param {View} view @param {number} height */
+function matrixLines(view, height) {
+  const { matrix, index, scope } = view;
+  const { context, blocked, unmanaged } = matrix.inventory;
+  const count = Math.max(1, height - 10);
+  const start = Math.max(0, Math.min(index - Math.floor(count / 2), matrix.rows.length - count));
+  const row = matrix.rows[index];
+  const source = row.initial[scope];
+  const status = blocked[scope].length
+    ? `BLOCKED ${scope}: ${blocked[scope][0]}`
+    : source
+      ? sourceOf(source)
+      : scope === "project" && row.selected.global
+        ? "No project declaration; available from global."
+        : "No direct declaration.";
+  return [
+    "SuPi installer | checked = direct declaration",
+    `Project: ${context.project}${context.project === context.home ? " [HOME WARNING]" : ""}`,
+    `Global: ${context.settingsPaths.global}`,
+    `${"Package".padEnd(31)}Project   Global`,
+    ...matrix.rows.slice(start, start + count).map((item, offset) => {
+      const position = start + offset;
+      return `${position === index ? ">" : " "} ${item.item.name.padEnd(29)}${cell(view, position, "project").padEnd(10)}${cell(view, position, "global")}`;
+    }),
+    `${index + 1}/${matrix.rows.length} | Focus: ${scope} | Unmanaged: ${unmanaged.project.length + unmanaged.global.length}`,
+    `${row.item.description} [${row.item.labels.join(", ")}]`,
+    `${status}${typeof source === "object" ? " [filtered]" : ""}`,
+    "Up/Down: row  Left/Right: scope  Space: toggle",
+    "r: Recommended  a: All  c: Clear (focused column)",
+    "Enter: review sources and changes  Esc: cancel",
+  ];
+}
+
+/** Render a bounded frame. Review content scrolls separately from the matrix. @param {View} view @param {{width: number, height: number}} size */
+export function renderView(view, { width, height }) {
+  let lines;
+  if (width < 60 || height < 12)
+    lines = ["Resize terminal to at least 60 columns and 12 rows.", "Esc: cancel"];
+  else if (view.review) {
+    const operations = getPlan(view.matrix);
+    const content = formatReview(view.matrix, operations).flatMap((line) =>
+      wrapLine(line, width - 1),
+    );
+    const count = height - 5;
+    view.offset = Math.max(0, Math.min(view.offset, Math.max(0, content.length - count)));
+    lines = [
+      "Review | failed installs do not block removals",
+      "A failed move can leave neither declaration. No rollback.",
+      `${operations.length} changes | lines ${view.offset + 1}-${Math.min(content.length, view.offset + count)}/${content.length}`,
+      ...content.slice(view.offset, view.offset + count),
+      "",
+      "y: Apply  e: Edit  Up/Down: scroll  Esc: cancel",
+    ];
+  } else lines = matrixLines(view, height);
+  return lines
+    .slice(0, height)
+    .map((line) => clipLine(line, Math.max(1, width - 1)))
+    .join("\r\n");
+}