@protoboardai/cli 0.0.0-stage → 0.2.0

package/src/setup.ts

@@ -0,0 +1,298 @@
+/**
+ * `protoboard setup` (first builds review, D4 and item 8; PB-1047): the npm
+ * package sets up the rest of the machine. It finds the command-line launchers
+ * of VS Code, Cursor, Windsurf and VSCodium, installs the Protoboard extension
+ * into each with the user's yes (`<editor> --install-extension
+ * deltarobotics.vscode-protoboard --force`: VS Code installs it from the
+ * Marketplace, the others from Open VSX), offers to put the `protoboard`
+ * command on PATH, and then offers the agents' set-up (`agents setup`). None
+ * of it needs a sign-in.
+ *
+ * `--vsix <file>` installs that package instead, for a machine offline. An
+ * editor whose gallery does not have the extension (not published yet) is said
+ * in one line, and the PATH and the agents are still set up.
+ *
+ * It is a command a person (or their agent, with their yes) runs. It is never
+ * run from an npm install script: an install must not change an editor.
+ *
+ * The platform, the environment, the file system, the network and the
+ * programs it starts are arguments, so Windows and macOS are tested from Linux.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { applyPathPlan, describePathPlan, lastingPath, onPathValue, pathPlan, stackHome, type PathPlan } from "@protoboardai/core";
+
+export type EditorId = "code" | "cursor" | "windsurf" | "codium";
+
+export interface Editor {
+  id: EditorId;
+  name: string;
+  /** Its command-line launcher, as a full path. */
+  launcher: string;
+  /** `path`: found on PATH. `known`: found where its installer puts it. */
+  from: "path" | "known";
+}
+
+export const EDITORS: readonly { id: EditorId; name: string }[] = [
+  { id: "code", name: "VS Code" },
+  { id: "cursor", name: "Cursor" },
+  { id: "windsurf", name: "Windsurf" },
+  { id: "codium", name: "VSCodium" },
+];
+
+export interface Look {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  exists?: (file: string) => boolean;
+}
+
+/** Where each editor's installer puts its launcher, when it is not on PATH. */
+function knownLaunchers(id: EditorId, platform: NodeJS.Platform, env: NodeJS.ProcessEnv, home: string): string[] {
+  if (platform === "darwin") {
+    const app = { code: "Visual Studio Code.app", cursor: "Cursor.app", windsurf: "Windsurf.app", codium: "VSCodium.app" }[id];
+    return [`/Applications/${app}/Contents/Resources/app/bin/${id}`, `${home}/Applications/${app}/Contents/Resources/app/bin/${id}`];
+  }
+  if (platform === "win32") {
+    const local = env.LOCALAPPDATA ?? `${home}\\AppData\\Local`;
+    const files = env.ProgramFiles ?? "C:\\Program Files";
+    return {
+      code: [`${local}\\Programs\\Microsoft VS Code\\bin\\code.cmd`, `${files}\\Microsoft VS Code\\bin\\code.cmd`],
+      cursor: [`${local}\\Programs\\cursor\\resources\\app\\bin\\cursor.cmd`, `${files}\\cursor\\resources\\app\\bin\\cursor.cmd`],
+      windsurf: [`${local}\\Programs\\Windsurf\\bin\\windsurf.cmd`, `${files}\\Windsurf\\bin\\windsurf.cmd`],
+      codium: [`${local}\\Programs\\VSCodium\\bin\\codium.cmd`, `${files}\\VSCodium\\bin\\codium.cmd`],
+    }[id];
+  }
+  return {
+    code: ["/usr/bin/code", "/snap/bin/code", "/usr/share/code/bin/code", "/var/lib/flatpak/exports/bin/com.visualstudio.code"],
+    cursor: ["/usr/bin/cursor", `${home}/.local/bin/cursor`, "/opt/cursor/bin/cursor"],
+    windsurf: ["/usr/bin/windsurf", `${home}/.local/bin/windsurf`, "/opt/windsurf/bin/windsurf"],
+    codium: ["/usr/bin/codium", "/snap/bin/codium", "/usr/share/codium/bin/codium", "/var/lib/flatpak/exports/bin/com.vscodium.codium"],
+  }[id];
+}
+
+/** The editors whose command-line launcher is on this machine: on PATH first, else where the installer puts it. */
+export function findEditors(look: Look = {}): Editor[] {
+  const platform = look.platform ?? process.platform;
+  const env = look.env ?? process.env;
+  const home = look.home ?? homedir();
+  const exists = look.exists ?? existsSync;
+  const win = platform === "win32";
+  const dirs = (env.PATH ?? env.Path ?? "")
+    .split(win ? ";" : ":")
+    .filter(Boolean)
+    .map((d) => d.replace(win ? /[\\/]+$/ : /\/+$/, ""));
+  const found: Editor[] = [];
+  for (const e of EDITORS) {
+    const names = win ? [`${e.id}.cmd`, `${e.id}.exe`] : [e.id];
+    let launcher: string | undefined;
+    for (const d of dirs) {
+      launcher = names.map((n) => (win ? `${d}\\${n}` : `${d}/${n}`)).find(exists);
+      if (launcher) break;
+    }
+    if (launcher) found.push({ ...e, launcher, from: "path" });
+    else {
+      const known = knownLaunchers(e.id, platform, env, home).find(exists);
+      if (known) found.push({ ...e, launcher: known, from: "known" });
+    }
+  }
+  return found;
+}
+
+export interface Command {
+  command: string;
+  args: string[];
+  /** Windows: the arguments are the command line as written (no quoting added). */
+  verbatim?: boolean;
+}
+
+/**
+ * `<editor> --install-extension <id | file> --force`, started without a shell
+ * where the launcher is a program or a script. On Windows the launcher is a
+ * `.cmd`, which only cmd runs: the line is given to cmd whole, each argument in
+ * double quotes (inside them cmd reads `&` and spaces as text).
+ */
+export function installCommand(editor: Pick<Editor, "launcher">, extension: string, platform: NodeJS.Platform = process.platform, env: NodeJS.ProcessEnv = process.env): Command {
+  const args = ["--install-extension", extension, "--force"];
+  if (platform === "win32" && /\.(cmd|bat)$/i.test(editor.launcher)) {
+    for (const p of [editor.launcher, extension]) if (/["%]/.test(p)) throw new Error(`${p} has a " or a % in its path, which cmd would read as its own: move the file to a folder without one`);
+    return { command: env.ComSpec ?? `${env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`, args: ["/d", "/s", "/c", `""${editor.launcher}" --install-extension "${extension}" --force"`], verbatim: true };
+  }
+  return { command: editor.launcher, args };
+}
+
+export type Run = (c: Command) => { status: number | null; stdout: string; stderr: string; error?: Error };
+
+const defaultRun: Run = (c) => {
+  // an editor's launcher started from VS Code's own runtime must not inherit "run as Node"
+  const { ELECTRON_RUN_AS_NODE: _e, ...env } = process.env;
+  const r = spawnSync(c.command, c.args, { encoding: "utf8", env, windowsHide: true, timeout: 5 * 60_000, ...(c.verbatim ? { windowsVerbatimArguments: true } : {}) });
+  return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", ...(r.error ? { error: r.error } : {}) };
+};
+
+// ---------------------------------------------------------------- the extension
+
+/** The extension's id on the Visual Studio Marketplace and on Open VSX (`<publisher>.<name>` of its manifest). */
+export const EXTENSION_ID = "deltarobotics.vscode-protoboard";
+
+/**
+ * What is installed: the extension by its id, from the editor's own gallery
+ * (VS Code's is the Marketplace; Cursor's, Windsurf's and VSCodium's is Open
+ * VSX), or a `.vsix` file given with `--vsix` (offline).
+ */
+export type ExtensionSource = { from: "gallery"; id: string } | { from: "file"; file: string };
+
+/** An editor's answer that its gallery has no extension of that id: not published there (yet). */
+export const notPublished = (output: string) => /\bnot found\b|\b404\b/i.test(output);
+
+// ---------------------------------------------------------------- the command
+
+export interface SetupFlags {
+  vsix?: string;
+  yes?: boolean;
+  editor?: string[];
+  /** false: leave the agents alone (`--no-agents`). */
+  agents?: boolean;
+}
+
+export interface SetupIo {
+  json: boolean;
+  cwd: string;
+  out(data: unknown, text: () => string): void;
+  log(line: string): void;
+  /** Ask a yes/no question at the terminal; undefined when there is no terminal to ask at. */
+  confirm?: (question: string) => Promise<boolean>;
+  /** The agents' set-up, offered last (`protoboard agents setup`). */
+  agents?: () => Promise<void>;
+}
+
+export interface SetupDeps extends Look {
+  run?: Run;
+  /** The user's Protoboard folder (its `bin` holds the command). */
+  stackHome?: string;
+  /** Appends to a shell start file (PATH set-up). */
+  append?: (file: string, text: string) => void;
+  read?: (file: string) => string;
+}
+
+export interface EditorResult {
+  id: EditorId;
+  name: string;
+  launcher: string;
+  /** `unpublished`: the editor's gallery has no extension of that id yet (not a failure of the set-up). */
+  action: "installed" | "declined" | "failed" | "unpublished";
+  command: string;
+  message?: string;
+}
+
+export interface SetupResult {
+  editors: EditorResult[];
+  notFound: string[];
+  /** What was installed into the editors: the id from their galleries, or a `--vsix` file. */
+  extension?: ExtensionSource;
+  path?: { dir: string; action: "added" | "already" | "declined" | "failed" | "not-needed"; message: string };
+  agents: "offered" | "skipped" | "not-run";
+}
+
+const show = (c: Command) => (c.verbatim ? `${c.command} ${c.args.join(" ")}` : [c.command, ...c.args].map((a) => (/^[\w@%+=:,./\\-]+$/.test(a) ? a : JSON.stringify(a))).join(" "));
+
+export async function setupCommand(flags: SetupFlags, io: SetupIo, deps: SetupDeps = {}): Promise<SetupResult> {
+  const env = deps.env ?? process.env;
+  const platform = deps.platform ?? process.platform;
+  // an install must not change an editor or a shell's start file: only a person's own command does
+  const lifecycle = env.npm_lifecycle_event;
+  if (lifecycle) throw new Error(`protoboard setup does not run from an npm script of an install (${lifecycle}): it changes editors and asks before each change. Run \`protoboard setup\` yourself, in a terminal.`);
+  if (!flags.yes && !io.confirm) throw new Error("there is no terminal to ask at, and protoboard setup changes nothing without a yes: run it in a terminal, or with --yes (installs the extension into every editor found; --editor <id> names one)");
+  const run = deps.run ?? defaultRun;
+  const wanted = flags.editor ?? [];
+  for (const id of wanted) if (!EDITORS.some((e) => e.id === id)) throw new Error(`no editor "${id}"; known: ${EDITORS.map((e) => e.id).join(", ")}`);
+  const all = findEditors(deps);
+  const editors = wanted.length ? all.filter((e) => wanted.includes(e.id)) : all;
+  const notFound = EDITORS.filter((e) => (wanted.length ? wanted.includes(e.id) : true) && !all.some((a) => a.id === e.id)).map((e) => e.name);
+  const result: SetupResult = { editors: [], notFound, agents: "not-run" };
+
+  // ---- the extension, into each editor found
+  if (editors.length) {
+    let source: ExtensionSource;
+    if (flags.vsix) {
+      const file = resolve(io.cwd, flags.vsix);
+      if (!(deps.exists ?? existsSync)(file)) throw new Error(`--vsix: there is no file ${file}`);
+      if (!/\.vsix$/i.test(file)) throw new Error(`--vsix: ${file} is not a .vsix file`);
+      source = { from: "file", file };
+    } else source = { from: "gallery", id: EXTENSION_ID };
+    result.extension = source;
+    const what = source.from === "file" ? source.file : source.id;
+    for (const e of editors) {
+      const c = installCommand(e, what, platform, env);
+      const shown = show(c);
+      if (!flags.yes && !(await io.confirm!(`Install the Protoboard extension into ${e.name}? This runs: ${e.launcher} --install-extension ${what} --force`))) {
+        result.editors.push({ id: e.id, name: e.name, launcher: e.launcher, action: "declined", command: shown });
+        continue;
+      }
+      io.log(`${e.name}: ${e.launcher} --install-extension ${source.from === "file" ? basename(source.file) : source.id} --force`);
+      const r = run(c);
+      const ok = !r.error && r.status === 0;
+      const said = `${r.stderr}\n${r.stdout}`;
+      // the gallery has no such extension: said once below, and the set-up goes on (PATH, agents)
+      const action = ok ? "installed" : !r.error && source.from === "gallery" && notPublished(said) ? "unpublished" : "failed";
+      result.editors.push({ id: e.id, name: e.name, launcher: e.launcher, action, command: shown, ...(action === "failed" ? { message: (r.error?.message ?? (r.stderr.trim() || r.stdout.trim()).split("\n").slice(-3).join(" ")) || `exit ${r.status}` } : {}) });
+    }
+  }
+
+  // ---- the command for terminals outside the editor: only when the extension put one in ~/.protoboard/bin and no `protoboard` is on PATH
+  const bin = join(deps.stackHome ?? stackHome(env), "bin");
+  const exists = deps.exists ?? existsSync;
+  const win = platform === "win32";
+  // what a terminal outside the editor has: in an editor's terminal the extension's own entry for `bin` lasts only there (PB-1037)
+  const lasting = lastingPath(bin, env, platform);
+  const hasCommand = (lasting ?? "")
+    .split(win ? ";" : ":")
+    .filter(Boolean)
+    .some((d) => (win ? ["protoboard.cmd", "protoboard.exe"] : ["protoboard"]).some((n) => exists(win ? `${d.replace(/[\\/]+$/, "")}\\${n}` : `${d.replace(/\/+$/, "")}/${n}`)));
+  if (!exists(join(bin, win ? "protoboard.cmd" : "protoboard"))) {
+    result.path = { dir: bin, action: "not-needed", message: hasCommand ? "The protoboard command is on PATH." : `The Protoboard extension writes the protoboard command into ${bin} the first time it starts; run \`protoboard setup\` again then to put it on PATH.` };
+  } else if (hasCommand || onPathValue(bin, lasting, platform)) {
+    result.path = { dir: bin, action: "already", message: "The protoboard command is on PATH." };
+  } else {
+    const plan: PathPlan = pathPlan(bin, { platform, env, ...(deps.home ? { home: deps.home } : {}), ...(deps.exists ? { exists: deps.exists } : {}), ...(deps.read ? { read: deps.read } : {}) });
+    if (plan.kind === "already") result.path = { dir: bin, action: "already", message: describePathPlan(plan) };
+    else if (!flags.yes && !(await io.confirm!(`Put the protoboard command on your PATH, for terminals outside the editor? ${describePathPlan(plan)}`))) result.path = { dir: bin, action: "declined", message: `Left as it is. The command is ${join(bin, win ? "protoboard.cmd" : "protoboard")}; the editor's own terminals have it.` };
+    else {
+      try {
+        const applied = applyPathPlan(plan, { ...(deps.append ? { append: deps.append } : {}), ...(deps.run ? { run: (command: string, args: string[]) => deps.run!({ command, args }) } : {}) });
+        result.path = { dir: bin, action: applied.changed ? "added" : "already", message: applied.message };
+      } catch (e) {
+        result.path = { dir: bin, action: "failed", message: (e as Error).message };
+      }
+    }
+  }
+
+  // ---- report, then the agents (their own questions, their own report)
+  const agentsNext = flags.agents === false ? "skipped" : io.agents && !io.json && io.confirm ? "offered" : "not-run";
+  result.agents = agentsNext;
+  const mark = { installed: "✓", declined: "·", failed: "✗", unpublished: "·" } as const;
+  const unpublished = result.editors.filter((e) => e.action === "unpublished").map((e) => e.name);
+  const gallery = (id: EditorId) => (id === "code" ? "the Marketplace" : "Open VSX");
+  io.out(result, () =>
+    [
+      ...(result.editors.length || result.notFound.length ? ["The Protoboard extension"] : []),
+      ...result.editors.map((e) => `  ${mark[e.action]} ${e.name}: ${e.action === "installed" ? `installed (${e.launcher})` : e.action === "declined" ? "left alone" : e.action === "unpublished" ? "not installed" : `not installed: ${e.message}`}${e.action === "installed" ? "\n      Reload its windows (or restart it) to start the extension." : ""}`),
+      ...(unpublished.length ? [`  ${EXTENSION_ID} is not published yet on ${[...new Set(result.editors.filter((e) => e.action === "unpublished").map((e) => gallery(e.id)))].join(" or ")}: install a .vsix with \`protoboard setup --vsix <file>\`.`] : []),
+      ...(result.notFound.length ? [`  Not found here: ${result.notFound.join(", ")}${editors.length ? "" : `. In ${result.notFound[0]}, install it from the Extensions view: search for Protoboard (${EXTENSION_ID})${platform === "darwin" ? '; its command comes with "Shell Command: Install \'code\' command in PATH" from the Command Palette' : ""}.`}`] : []),
+      ...(result.extension?.from === "file" ? [`  from ${result.extension.file}`] : result.extension && result.editors.some((e) => e.action === "installed") ? [`  ${EXTENSION_ID}, from ${[...new Set(result.editors.filter((e) => e.action === "installed").map((e) => gallery(e.id)))].join(" and ")}`] : []),
+      ...(result.path && result.path.action !== "not-needed" ? ["", "The protoboard command", `  ${result.path.action === "failed" ? "✗" : result.path.action === "declined" ? "·" : "✓"} ${result.path.message}`] : result.path ? ["", result.path.message] : []),
+      ...(agentsNext === "not-run" ? ["", "Agents: `protoboard agents setup` connects your agents to Protoboard (it asks about each)."] : []),
+    ].join("\n"),
+  );
+  if (agentsNext === "offered") {
+    io.log("");
+    io.log("Agents");
+    await io.agents!();
+  }
+  return result;
+}
+
+/** The exit code of a set-up: 1 when an install that was agreed to failed. */
+export const setupExitCode = (r: SetupResult) => (r.editors.some((e) => e.action === "failed") || r.path?.action === "failed" ? 1 : 0);

package/src/stack-messages.ts

@@ -0,0 +1,53 @@
+/**
+ * What `protoboard stack link` says beyond the link summary (F04).
+ */
+import { readdirSync, readFileSync, type Dirent } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * What `stack link` says of the packages package.json names that no stack copy
+ * provides (F04): which the project's own files import, and which nothing
+ * imports (leftovers, such as a tool's dependencies from before the project
+ * was a Protoboard one). Never "npm install": AGENTS.md tells agents not to
+ * run npm in a stack-linked project.
+ */
+export function notProvidedLines(root: string, names: string[]): string[] {
+  if (!names.length) return [];
+  // the TypeScript pin (catalog parts' sources are checked against it) and type packages are kept on purpose
+  const tooling = names.filter((n) => n === "typescript" || n.startsWith("@types/"));
+  const rest = names.filter((n) => !tooling.includes(n));
+  const used = importedPackages(root, rest);
+  const unused = rest.filter((n) => !used.has(n));
+  return [
+    ...(tooling.length ? [`kept in package.json for type checking, not linked: ${tooling.join(", ")}`] : []),
+    ...(used.size ? [`not provided by the Protoboard stack, and imported by the project's files: ${[...used].sort().join(", ")}. Ask the person how the project should get them; do not run npm in a stack-linked project`] : []),
+    ...(unused.length ? [`not provided by the Protoboard stack, and imported by none of the project's files: ${unused.join(", ")}. Probably leftovers: remove them from package.json`] : []),
+  ];
+}
+
+/** Which of `names` a source file of the project imports or requires (node_modules, .protoboard, operations and release left out). */
+export function importedPackages(root: string, names: string[]): Set<string> {
+  const found = new Set<string>();
+  const skip = new Set(["node_modules", ".protoboard", "operations", "release", ".git"]);
+  const walk = (dir: string) => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (found.size === names.length) return;
+      const p = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!skip.has(e.name) && !e.name.startsWith(".")) walk(p);
+      } else if (/\.(c|m)?(t|j)sx?$/.test(e.name)) {
+        const text = readFileSync(p, "utf8");
+        for (const n of names) if (!found.has(n) && new RegExp(`(from|import|require)\\s*\\(?\\s*["'\`]${n.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")}(/[^"'\`]*)?["'\`]`).test(text)) found.add(n);
+      }
+    }
+  };
+  walk(root);
+  return found;
+}
+

package/src/views-check.ts

@@ -0,0 +1,267 @@
+/**
+ * `protoboard views check [--module <path or id>] [--out <dir>] [--no-render]`
+ * (PB-1030): which tabs each level of the project gets in the viewer, and
+ * whether each one draws. The tabs come from the same rules the shells use
+ * (@protoboardai/views/tabs); each is then opened once in the web viewer
+ * `protoboard dev` serves, in a headless browser, as a person would open it:
+ * the level by the URL, the tab by its button. A tab fails when the page
+ * throws or logs an error while it is shown, or when nothing is drawn
+ * (an empty state, or a blank view). `--out` keeps a PNG of every tab, so an
+ * agent can look at the board without the editor (F13).
+ *
+ * The levels are the root and every module with modules inside it (the
+ * levels a person drills into: a board, an enclosure, an assembly);
+ * `--module` picks one (an instance path, or a module id: its first
+ * instance), parts included.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ModuleDef } from "@deltarobotics/uhd";
+import { findProjectRoot, loadProject, resolveViews, uhdBundle } from "@protoboardai/core";
+import { tabsFor } from "@protoboardai/views/tabs";
+
+export type TabStatus = "ok" | "empty" | "error" | "not-rendered";
+
+export interface TabResult {
+  id: string;
+  title: string;
+  status: TabStatus;
+  /** Why it failed, or what was seen. */
+  detail?: string;
+  /** Share of the view's pixels that differ from its background (0–1). */
+  ink?: number;
+  /** The PNG written for it (`--out`). */
+  shot?: string;
+}
+
+export interface LevelResult {
+  /** Instance path ("" is the root). */
+  path: string;
+  module: string;
+  name: string;
+  tabs: TabResult[];
+  /** Tabs the viewer showed that the rules did not list, or the other way round (should be none). */
+  mismatch?: string;
+}
+
+export interface ViewsCheckReport {
+  root: string;
+  levels: LevelResult[];
+  rendered: boolean;
+  /** Why nothing was rendered (no browser, --no-render). */
+  reason?: string;
+  failed: number;
+}
+
+export interface ViewsCheckOptions {
+  cwd: string;
+  module?: string;
+  /** Folder for one PNG per tab. */
+  out?: string;
+  render?: boolean;
+  /** Seconds to wait for a tab to draw (default 45: a board's GLB in a software renderer takes a while). */
+  timeout?: number;
+  log?: (line: string) => void;
+}
+
+const W = 1440;
+const H = 900;
+/** The floating header the shell draws over the top of the view. */
+const HEADER = 52;
+/**
+ * Where ink is measured: the middle of the view, clear of the floating cards
+ * every view has (the title card top left, the toolbar at the bottom, an
+ * inspector on the right), which would count as ink on a blank view.
+ */
+const MIDDLE = { x: Math.round(W * 0.16), y: HEADER + 70, width: Math.round(W * 0.56), height: H - HEADER - 170, scale: 0.5 };
+/** Below this share of differing pixels, a view counts as blank. */
+const MIN_INK = 0.002;
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+const slug = (s: string) => s.replace(/[^A-Za-z0-9_.-]+/g, "_") || "root";
+
+/** The levels to check: the root and every module with modules inside it, or the one `--module` names. */
+function levels(p: Awaited<ReturnType<typeof loadProject>>, module?: string): { path: string; def: ModuleDef }[] {
+  const at = (path: string, id: string) => ({ path, def: p.lookup(id)! });
+  if (module !== undefined) {
+    const byPath = p.instances.find((i) => i.path === module);
+    const byId = p.instances.find((i) => i.definition === module);
+    const hit = byPath ?? byId;
+    if (!hit) throw new Error(`no instance path or module "${module}" (paths look like board or cap/board; see \`protoboard inspect\`)`);
+    return [at(hit.path, hit.definition)];
+  }
+  const seen = new Set<string>();
+  const out: { path: string; def: ModuleDef }[] = [];
+  for (const i of p.instances) {
+    const def = p.lookup(i.definition);
+    if (!def) continue;
+    if (i.path !== "" && !(def.children ?? []).length) continue;
+    // a module used several times is checked once, at its first instance
+    if (i.path !== "" && seen.has(def.id)) continue;
+    seen.add(def.id);
+    out.push({ path: i.path, def });
+  }
+  return out;
+}
+
+/** In the page: a tab button's view title (its tooltip is "<title>[ · planned][: description]"). */
+const TITLE = `(b.getAttribute('data-tooltip') || '').split(/ · |: /)[0].trim()`;
+const TABS = `[...document.querySelectorAll('[role=tablist] [role=tab]')].map((b) => ${TITLE})`;
+
+/** In the page: the share of a PNG's pixels that differ from its most common colour. */
+const INK = `async (b64) => {
+  const img = new Image();
+  img.src = "data:image/png;base64," + b64;
+  await img.decode();
+  const c = document.createElement("canvas");
+  c.width = img.width; c.height = img.height;
+  const g = c.getContext("2d");
+  g.drawImage(img, 0, 0);
+  const d = g.getImageData(0, 0, c.width, c.height).data;
+  const counts = new Map();
+  for (let i = 0; i < d.length; i += 4) { const k = (d[i] >> 3) << 10 | (d[i + 1] >> 3) << 5 | (d[i + 2] >> 3); counts.set(k, (counts.get(k) || 0) + 1); }
+  let bg = 0, most = -1;
+  for (const [k, n] of counts) if (n > most) { most = n; bg = k; }
+  const br = (bg >> 10) << 3, bgG = ((bg >> 5) & 31) << 3, bb = (bg & 31) << 3;
+  let ink = 0;
+  for (let i = 0; i < d.length; i += 4) if (Math.abs(d[i] - br) > 24 || Math.abs(d[i + 1] - bgG) > 24 || Math.abs(d[i + 2] - bb) > 24) ink++;
+  return ink / (d.length / 4);
+}`;
+
+/**
+ * In the page: what the active tab's panel holds. An empty state is the
+ * viewer's EmptyState (a centred column with an upper-case title) standing
+ * alone: no drawing (an SVG or a canvas of some size) beside it.
+ */
+const PANEL = `(() => {
+  const panel = document.querySelector('[role=tabpanel]');
+  if (!panel) return { panel: false };
+  const big = (el) => { const r = el.getBoundingClientRect(); return r.width > 200 && r.height > 150; };
+  const drawings = panel.querySelectorAll('.react-flow__node').length + [...panel.querySelectorAll('svg')].filter((s) => big(s) && s.querySelectorAll('*').length > 20).length
+    + [...panel.querySelectorAll('canvas')].filter(big).length;
+  const rows = panel.querySelectorAll('[role=row], tr, [data-line]').length;
+  const empties = [...panel.querySelectorAll('div.flex.flex-col.items-center.justify-center.text-center')]
+    .filter((e) => e.offsetParent !== null && e.querySelector('.uppercase'))
+    .map((e) => e.querySelector('.uppercase').textContent.trim());
+  return { panel: true, drawings, rows, empties, text: panel.innerText.slice(0, 160) };
+})()`;
+
+export async function viewsCheck(options: ViewsCheckOptions): Promise<ViewsCheckReport> {
+  const log = options.log ?? (() => {});
+  const root = findProjectRoot(options.cwd);
+  if (!root) throw new Error(`no protoboard.config.ts in ${options.cwd} or its parents (run \`protoboard init\`)`);
+  const p = await loadProject(root, { checks: false });
+  const bundle = await uhdBundle(p);
+  const { views } = resolveViews(p.extensions);
+  const result: LevelResult[] = levels(p, options.module).map(({ path, def }) => ({
+    path,
+    module: def.id,
+    name: def.name ?? def.id,
+    tabs: tabsFor(bundle.definitions.find((d) => d.id === def.id) ?? def, bundle, path, views).map((v) => ({ id: v.id, title: v.title, status: "not-rendered" as TabStatus })),
+  }));
+  const report: ViewsCheckReport = { root, levels: result, rendered: false, failed: 0 };
+  if (options.render === false) return { ...report, reason: "not rendered (--no-render)" };
+
+  const { launchBrowser } = await import("@protoboardai/core/cdp");
+  const { startDev } = await import("./dev/server.js");
+  let browser: Awaited<ReturnType<typeof launchBrowser>>;
+  try {
+    browser = await launchBrowser({ purpose: "`protoboard views check` opens each tab in a headless Chromium-family browser", echoErrors: false });
+  } catch (e) {
+    return { ...report, reason: (e as Error).message.split("\n")[0], failed: result.reduce((n, l) => n + l.tabs.length, 0) };
+  }
+  const dev = await startDev({ root, port: 0, watch: false, record: false });
+  const out = options.out ? resolve(options.cwd, options.out) : undefined;
+  if (out) mkdirSync(out, { recursive: true });
+  const timeout = (options.timeout ?? 45) * 1000;
+  try {
+    await browser.setViewport(W, H);
+    for (const level of result) {
+      const url = `${dev.url}?theme=protoboard-dark${level.path ? `&drill=${encodeURIComponent(level.path.split("/").join(","))}` : ""}`;
+      log(`${level.path || "(root)"} ${level.module}: ${level.tabs.map((t) => t.title).join(", ")}`);
+      await browser.navigate(url);
+      // the shell's tabs, once it has mounted the level
+      // the shell's tabs, once it has mounted the level (the same as the rules', or settled for 3 s)
+      const expected = level.tabs.map((t) => t.title);
+      let shown: string[] = [];
+      let first = 0;
+      for (const t0 = Date.now(); Date.now() - t0 < timeout; await sleep(250)) {
+        shown = await browser.evaluate<string[]>(TABS);
+        if (!shown.length) continue;
+        first ||= Date.now();
+        if ((shown.length === expected.length && shown.every((t) => expected.includes(t))) || Date.now() - first > 3000) break;
+      }
+      const extra = shown.filter((t) => !expected.includes(t));
+      const missing = expected.filter((t) => !shown.includes(t));
+      if (extra.length || missing.length) level.mismatch = `${missing.length ? `not shown: ${missing.join(", ")}` : ""}${extra.length && missing.length ? "; " : ""}${extra.length ? `shown besides: ${extra.join(", ")}` : ""}`;
+      browser.takeErrors();
+      for (const tab of level.tabs) {
+        if (!shown.includes(tab.title)) {
+          tab.status = "error";
+          tab.detail = "the viewer does not offer this tab here";
+          continue;
+        }
+        await browser.evaluate(`[...document.querySelectorAll('[role=tablist] [role=tab]')].find((b) => ${TITLE} === ${JSON.stringify(tab.title)}).click()`);
+        // wait for it to draw: something inked and a drawing or rows in the panel, or until the time is up
+        // wait for it to draw: inked and unchanged across two looks (a model still loading changes), or an
+        // empty state that stays, or until the time is up
+        let panel: { panel: boolean; drawings?: number; rows?: number; empties?: string[]; text?: string } = { panel: false };
+        let ink = 0;
+        let before = -1;
+        for (const t0 = Date.now(); Date.now() - t0 < timeout; await sleep(600)) {
+          panel = await browser.evaluate(PANEL);
+          const png = await browser.screenshot(MIDDLE);
+          ink = await browser.evaluate<number>(`(${INK})(${JSON.stringify(png.toString("base64"))})`);
+          const settled = Math.abs(ink - before) < 0.0005;
+          before = ink;
+          if ((panel.empties ?? []).length && !(panel.drawings ?? 0) && Date.now() - t0 > 3000) break;
+          if (ink >= MIN_INK && settled && ((panel.drawings ?? 0) > 0 || (panel.rows ?? 0) > 0 || Date.now() - t0 > 4000)) break;
+        }
+        await sleep(600);
+        const errors = browser.takeErrors().filter((e) => !/favicon|ERR_ABORTED|EventSource/i.test(e));
+        tab.ink = Math.round(ink * 10000) / 10000;
+        if (errors.length) {
+          tab.status = "error";
+          tab.detail = errors[0].split("\n")[0].slice(0, 300);
+        } else if (!panel.panel) {
+          tab.status = "error";
+          tab.detail = "no view panel";
+        } else if ((panel.empties ?? []).length && !(panel.drawings ?? 0)) {
+          tab.status = "empty";
+          tab.detail = `shows "${panel.empties![0]}"`;
+        } else if (ink < MIN_INK) {
+          tab.status = "empty";
+          tab.detail = "blank: nothing is drawn";
+        } else if (!(panel.drawings ?? 0) && !(panel.rows ?? 0)) {
+          tab.status = "ok";
+          tab.detail = `no drawing or table; shows "${(panel.text ?? "").split("\n")[0]}"`;
+        } else tab.status = "ok";
+        if (out) {
+          const file = join(out, `${slug(level.path)}__${tab.id}.png`);
+          writeFileSync(file, await browser.screenshot());
+          tab.shot = file;
+        }
+        log(`  ${tab.status.padEnd(5)} ${tab.title}${tab.detail ? `: ${tab.detail}` : ""}`);
+      }
+    }
+  } finally {
+    await browser.close();
+    await dev.close();
+  }
+  const failed = result.reduce((n, l) => n + l.tabs.filter((t) => t.status === "empty" || t.status === "error").length, 0);
+  return { ...report, rendered: true, failed };
+}
+
+/** The report for people. */
+export function formatViewsCheck(r: ViewsCheckReport): string {
+  const lines: string[] = [];
+  for (const l of r.levels) {
+    lines.push(`${l.path || "(root)"}  ${l.module}`);
+    for (const t of l.tabs) lines.push(`  ${t.status === "ok" ? "✓" : t.status === "not-rendered" ? "·" : "✗"} ${t.title.padEnd(10)} ${t.status === "ok" || t.status === "not-rendered" ? "" : t.status}${t.detail ? `${t.status === "ok" ? "" : ": "}${t.detail}` : ""}${t.shot ? `  ${t.shot}` : ""}`.trimEnd());
+    if (l.mismatch) lines.push(`  ! the viewer's tabs differ from the rules: ${l.mismatch}`);
+  }
+  const tabs = r.levels.reduce((n, l) => n + l.tabs.length, 0);
+  lines.push("");
+  lines.push(r.rendered ? `${tabs} tab(s) on ${r.levels.length} level(s): ${r.failed ? `${r.failed} failed` : "every one draws"}` : `${tabs} tab(s) on ${r.levels.length} level(s), not rendered: ${r.reason}`);
+  return lines.join("\n");
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.