@protoboardai/cli 0.0.0-stage → 0.2.0

package/src/dev/page.ts

@@ -0,0 +1,284 @@
+/**
+ * The page `protoboard dev` serves: Protoboard's web viewer
+ * (`@protoboardai/web-viewer`, `mountWebViewer`: the browser shell over the
+ * viewer stack, docs/specs/viewer-stack.md) in a page of its own, with the
+ * Protoboard adapter around it:
+ *
+ * - the bundle and its artifacts come from the viewer's own handler
+ *   (`/uhd-bundle.json`, `/artifacts/...`);
+ * - the dev session's findings (a failed rebuild, an unsaved layout) are the
+ *   host diagnostics, next to the project's aggregate in the bundle;
+ * - layout edits go to the server, which writes them to display.json;
+ * - server-sent events push rebuilt bundles and display changes into the
+ *   running viewer (`update`), so the view, drill level and selection stay;
+ * - in a frame (the VS Code extension's webview), the page relays the
+ *   viewer's host messages between its parent and the viewer (relay.js),
+ *   and answers `openSource` with the file and line from the build's source
+ *   index (`/__protoboard/source`, ./sources.ts);
+ * - the views the project's extensions contribute become tabs (`views` in the
+ *   state route); `?theme=` picks the theme (protoboard-dark, protoboard-light,
+ *   vscode, …; default: the viewer's last choice, else Protoboard dark).
+ */
+
+/** Routes of the dev session, apart from the viewer handler's own. */
+export const DEV_ROUTES = {
+  page: "/",
+  script: "/__protoboard/dev.js",
+  events: "/__protoboard/events",
+  state: "/__protoboard/state",
+  layout: "/__protoboard/layout",
+  relay: "/__protoboard/relay.js",
+  source: "/__protoboard/source",
+  parts: "/__protoboard/parts/",
+  viewerJs: "/__protoboard/viewer/web-viewer.js",
+  viewerCss: "/__protoboard/viewer/web-viewer.css",
+} as const;
+
+/**
+ * A route as the page refers to it: relative to the page, so the page also
+ * works behind a proxy that serves it under a path (code-server's
+ * `/proxy/<port>/`, PB-861). The page is always served at the root of the
+ * server.
+ */
+const rel = (route: string) => `.${route}`;
+/** A route as dev.js imports it: relative to dev.js itself (`/__protoboard/dev.js`). */
+const fromScript = (route: string) => `./${route.slice("/__protoboard/".length)}`;
+
+/**
+ * The Protoboard mark (as in the VS Code extension's media/protoboard.svg) as
+ * the tab's icon, in a neutral grey: no brand colour is hard-coded (PB-900).
+ * Once mounted, the web viewer redraws it in the theme's accent.
+ */
+export const FAVICON_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24">' +
+  '<path fill="#8a8a8a" d="M8.529 13.629 15.272 6.885C15.348 6.81 15.385 6.715 15.385 6.6C15.385 6.486 15.348 6.39 15.272 6.315L13.815 4.886C13.624 4.695 13.386 4.6 13.101 4.6H10.9C10.614 4.6 10.376 4.695 10.186 4.886L8.529 6.543C8.338 6.733 8.243 6.972 8.243 7.257V13.486C8.243 13.638 8.281 13.714 8.357 13.714C8.414 13.714 8.472 13.686 8.529 13.629ZM10.9 19.4H13.101C13.386 19.4 13.624 19.305 13.815 19.114L15.472 17.457C15.662 17.267 15.757 17.029 15.757 16.743V10.514C15.757 10.362 15.719 10.286 15.643 10.286C15.586 10.286 15.529 10.315 15.472 10.372L8.729 17.115C8.634 17.209 8.586 17.305 8.586 17.4C8.586 17.496 8.634 17.591 8.729 17.685L10.186 19.114C10.376 19.305 10.614 19.4 10.9 19.4ZM6.015 5.372 9.015 2.4C9.243 2.133 9.548 2 9.929 2H14.072C14.433 2 14.738 2.124 14.986 2.372L17.958 5.372C18.224 5.6 18.357 5.905 18.357 6.286V17.714C18.357 18.076 18.224 18.391 17.958 18.657L14.986 21.628C14.738 21.876 14.433 22 14.072 22H9.929C9.548 22 9.243 21.867 9.015 21.6L6.015 18.628C5.767 18.381 5.643 18.076 5.643 17.714V6.286C5.643 5.924 5.767 5.619 6.015 5.372Z"/></svg>';
+/** The page's icon, inline: the browser then never asks for /favicon.ico (PB-873). */
+const FAVICON_DATA_URL = `data:image/svg+xml,${encodeURIComponent(FAVICON_SVG)}`;
+
+/** Header carrying the session token on writes (a page on another origin cannot set it without a preflight, which is refused). */
+export const TOKEN_HEADER = "x-protoboard-dev";
+
+const escapeHtml = (s: string) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]!);
+
+export function devPage(config: { name: string; token: string; session: string; hostOrigins?: string[] }): string {
+  const json = JSON.stringify(config).replace(/</g, "\\u003c");
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(config.name)} · Protoboard dev</title>
+    <link rel="icon" href="${FAVICON_DATA_URL}" />
+    <link rel="stylesheet" href="${rel(DEV_ROUTES.viewerCss)}" />
+    <style>
+      /* until the web viewer mounts and puts its theme on the document, the system canvas in the
+         theme's scheme (no dark flash under a light theme) */
+      html { background: Canvas; color-scheme: dark; }
+      html[data-pb-scheme="light"] { color-scheme: light; }
+      html, body { margin: 0; height: 100%; }
+      #viewer { height: 100vh; }
+      #pb-dev {
+        --pb-surface: #262626; --pb-text: #e5e5e5; --pb-text-muted: #a3a3a3; --pb-border: #3a3a3a; --pb-accent: currentColor;
+        --pb-ok: #22c55e; --pb-warning: #eed202; --pb-error: #ef4444; --pb-shadow: 0 6px 24px rgb(0 0 0 / 0.35); --pb-font: ui-monospace, monospace;
+        /* above the viewer's bottom toolbar, and only while it has something to say: once a build or a
+           save is done it fades out, so it never sits over the diagram (PB-861); errors stay */
+        position: fixed; bottom: 60px; left: 50%; transform: translateX(-50%); z-index: 50; pointer-events: none;
+        max-width: min(640px, calc(100vw - 32px)); white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+        display: flex; align-items: center; gap: 8px; padding: 6px 10px;
+        /* the viewer's tokens (the theme is applied on the viewer's root, so read them from there) */
+        background: var(--pb-surface); color: var(--pb-text-muted);
+        border: 1px solid var(--pb-border); border-radius: 8px;
+        box-shadow: var(--pb-shadow);
+        font: 500 11px/1.4 var(--pb-font); letter-spacing: 0.04em; text-transform: uppercase;
+        transition: opacity 0.3s;
+      }
+      #pb-dev .dot { width: 7px; height: 7px; border-radius: 50%; background: var(--pb-ok); flex: none; }
+      #pb-dev[data-state="busy"] .dot { background: var(--pb-warning); }
+      #pb-dev[data-state="error"] .dot { background: var(--pb-error); }
+      #pb-dev[data-state="error"] { color: var(--pb-text); }
+      #pb-dev[data-quiet="1"] { opacity: 0; }
+      #pb-dev .sep { width: 1px; align-self: stretch; background: var(--pb-border); }
+      #pb-dev .brand { color: var(--pb-accent); }
+    </style>
+    <script>
+      try {
+        const t = new URLSearchParams(location.search).get("theme") ?? localStorage.getItem("protoboard-web:theme") ?? "";
+        if (t.endsWith("light") || (t.endsWith("system") && matchMedia("(prefers-color-scheme: light)").matches)) document.documentElement.dataset.pbScheme = "light";
+      } catch {}
+    </script>
+    <script type="application/json" id="protoboard-dev">${json}</script>
+  </head>
+  <body>
+    <div id="viewer"></div>
+    <div id="pb-dev" data-state="busy"><span class="dot"></span><span class="brand">Protoboard dev</span><span class="sep"></span><span id="pb-dev-text">loading</span></div>
+    <script type="module" src="${rel(DEV_ROUTES.script)}"></script>
+  </body>
+</html>
+`;
+}
+
+/** The page's script: mounts the viewer and connects it to the dev server. */
+export const DEV_SCRIPT = `import { createDevPartsData, mountWebViewer } from "${fromScript(DEV_ROUTES.viewerJs)}";
+import { createRelay } from "${fromScript(DEV_ROUTES.relay)}";
+
+const config = JSON.parse(document.getElementById("protoboard-dev").textContent);
+const client = crypto.randomUUID();
+const empty = () => ({ positions: {}, links: {} });
+const badge = document.getElementById("pb-dev");
+const text = document.getElementById("pb-dev-text");
+let quiet;
+function status(state, message) {
+  badge.dataset.state = state;
+  badge.dataset.quiet = "0";
+  text.textContent = message;
+  clearTimeout(quiet);
+  if (state === "ok") quiet = setTimeout(() => (badge.dataset.quiet = "1"), 4000);
+}
+const counts = (c) => (c ? c.error + " errors · " + c.warning + " warnings" : "");
+
+// the badge sits outside the viewer: it takes the viewer's theme tokens from the viewer's root whenever they change
+const BADGE_TOKENS = { surface: "surface", text: "text", "text-muted": "text-muted", border: "border", accent: "accent", ok: "severity-ok", warning: "severity-warning", error: "severity-error", shadow: "shadow-lg", font: "font-ui" };
+let themed;
+function syncBadge() {
+  const style = getComputedStyle(themed);
+  for (const [k, t] of Object.entries(BADGE_TOKENS)) {
+    const v = style.getPropertyValue("--uhd-" + t).trim();
+    if (v) badge.style.setProperty("--pb-" + k, v);
+  }
+}
+new MutationObserver(() => {
+  const root = document.querySelector("#viewer > .uhd-root");
+  if (!root || root === themed) return;
+  themed = root;
+  new MutationObserver(syncBadge).observe(root, { attributes: true, attributeFilter: ["style", "data-uhd-theme"] });
+  syncBadge();
+}).observe(document.getElementById("viewer"), { childList: true });
+
+// every URL relative to the page, so it works behind a path-prefixing proxy (a browser-hosted VS Code)
+const here = (path) => new URL(path, document.baseURI).href;
+const bundleUrl = here("uhd-bundle.json");
+
+async function fetchBundle() {
+  const res = await fetch(bundleUrl, { cache: "no-store" });
+  if (!res.ok) throw new Error("bundle: " + res.status);
+  const bundle = await res.json();
+  // the server names artifact bases by the host it was asked on (http://host/artifacts/…); a proxy in
+  // front of it (another scheme, host or path) reaches them relative to this page instead
+  for (const [id, base] of Object.entries(bundle.artifactBases ?? {})) {
+    const m = /^https?:\\/\\/[^/]+\\/(artifacts\\/.*)$/.exec(base);
+    if (m) bundle.artifactBases[id] = here(m[1]);
+  }
+  return bundle;
+}
+
+/** Where every node and edge of the diagram on screen is drawn (absolute canvas coordinates). */
+function snapshot() {
+  const flow = document.querySelector(".react-flow");
+  if (!flow) return undefined;
+  const nodes = {};
+  for (const el of flow.querySelectorAll(".react-flow__node[data-id]")) {
+    const m = /translate\\((-?[\\d.]+)px,\\s*(-?[\\d.]+)px\\)/.exec(el.style.transform);
+    if (m) nodes[el.dataset.id] = { x: Number(m[1]), y: Number(m[2]) };
+  }
+  const edges = [...flow.querySelectorAll(".react-flow__edge[data-id]")].map((el) => el.dataset.id);
+  return { nodes, edges };
+}
+
+async function save(layout) {
+  status("busy", "saving layout");
+  try {
+    const res = await fetch("${rel(DEV_ROUTES.layout)}", {
+      method: "POST",
+      headers: { "content-type": "application/json", "${TOKEN_HEADER}": config.token },
+      body: JSON.stringify({ client, layout, snapshot: snapshot() }),
+    });
+    const body = await res.json();
+    if (!res.ok) throw new Error(body.error ?? res.status);
+    if (body.skipped?.length) status("error", "layout not saved: " + body.skipped[0].reason);
+    else status("ok", body.levels.length ? "layout saved · " + body.file : "layout unchanged");
+  } catch (e) {
+    status("error", "layout not saved: " + e.message);
+  }
+}
+
+// a framing host (the VS Code extension) talks to the viewer through this page
+const relay = createRelay({
+  window,
+  origins: config.hostOrigins,
+  async resolveSource(request) {
+    const query = new URLSearchParams({ defId: request.defId, ...(request.instancePath ? { instancePath: request.instancePath } : {}) });
+    const res = await fetch("${rel(DEV_ROUTES.source)}?" + query, { cache: "no-store" });
+    return res.ok ? res.json() : undefined;
+  },
+  onLocal(event) {
+    const at = event.source ?? event.instanceSource;
+    status("ok", at ? "source · " + at.file + (at.line ? ":" + at.line : "") : "no source found for " + event.defId);
+  },
+});
+
+const state = await (await fetch("${rel(DEV_ROUTES.state)}", { cache: "no-store" })).json();
+const themeChoice = new URLSearchParams(location.search).get("theme") ?? undefined;
+const viewer = mountWebViewer(document.getElementById("viewer"), {
+  bundle: await fetchBundle(),
+  bundleUrl,
+  themeChoice,
+  views: state.views ?? [],
+  // every definition's part status (PB-932): the shell marks the modules with it
+  partStatus: state.partStatus,
+  // the library and bom tabs ask the server (writes carry the session token)
+  partsData: createDevPartsData({ base: here("${DEV_ROUTES.parts.slice(1)}"), token: config.token, tokenHeader: "${TOKEN_HEADER}" }),
+  diagnostics: state.diagnostics,
+  layout: empty(),
+  onLayoutChange: save,
+  ...relay.callbacks,
+});
+relay.attach(viewer);
+window.protoboardDev = { viewer, relay, client, version: state.version, updates: 0 };
+status(state.building ? "busy" : state.failed ? "error" : "ok", state.message);
+
+const events = new EventSource("${rel(DEV_ROUTES.events)}");
+events.addEventListener("hello", (e) => {
+  // a restarted server: its bundle and session are new
+  if (JSON.parse(e.data).session !== config.session) location.reload();
+});
+events.addEventListener("status", (e) => {
+  const s = JSON.parse(e.data);
+  status(s.state, s.message);
+});
+events.addEventListener("bundle", async (e) => {
+  const msg = JSON.parse(e.data);
+  try {
+    const bundle = await fetchBundle();
+    // the layout on disk changed under the viewer (an edit, a checkout, another tab): show it as saved
+    const reset = msg.reason === "display" || (msg.reason === "layout" && msg.client !== client);
+    viewer.update({ bundle, diagnostics: msg.diagnostics, ...(reset ? { layout: empty() } : {}), ...(msg.partStatus ? { partStatus: msg.partStatus } : {}) });
+    window.protoboardDev.version = msg.version;
+    window.protoboardDev.updates++;
+    status(msg.failed ? "error" : "ok", msg.message);
+  } catch (err) {
+    status("error", err.message);
+  }
+});
+// a dropped stream reconnects by itself (a laptop that slept, a network that changed): say so only while it is down
+let lost = false;
+events.onerror = () => {
+  lost = true;
+  status("error", "dev server unreachable; retrying");
+};
+events.onopen = async () => {
+  if (!lost) return;
+  lost = false;
+  try {
+    const now = await (await fetch("${rel(DEV_ROUTES.state)}", { cache: "no-store" })).json();
+    if (now.session !== config.session) return location.reload();
+    if (now.version !== window.protoboardDev.version) {
+      viewer.update({ bundle: await fetchBundle(), diagnostics: now.diagnostics });
+      window.protoboardDev.version = now.version;
+      window.protoboardDev.updates++;
+    }
+    status(now.building ? "busy" : now.failed ? "error" : "ok", now.message);
+  } catch (err) {
+    status("error", err.message);
+  }
+};
+`;

package/src/dev/parts.ts

@@ -0,0 +1,356 @@
+/**
+ * The parts routes of `protoboard dev` (PB-912): what the web viewer's
+ * `library` and `bom` tabs show, computed the way the VS Code extension
+ * computes them (@protoboardai/views/parts-data, the CLI's own commands).
+ *
+ * - `GET  parts/library?text&category&domain&protocol&sort&cursor`: a search over
+ *   the project's libraries (the list from `protoboard libraries`, the
+ *   client and the merging from @protoboardai/core/library-client), as the
+ *   Library's model; thumbnails by `parts/blob`.
+ * - `GET  parts/part?key=<library>/<id>&revision`: a part's detail, with its pages.
+ * - `GET  parts/pages?key=<library>/<id>&revision`: a part's pages, for the
+ *   cards' text carousel (PB-918): asked for when a card first shows one.
+ * - `GET  parts/prices?key=<library>/<id>`: the part's prices by source, as
+ *   its library serves them to the signed-in user (`partPrices`).
+ * - `GET  parts/blob?library&sha&size&type`: a thumbnail or model, verified
+ *   against its address by the library client, cached under
+ *   .protoboard/cache/library.
+ * - `GET  parts/project[?check=1]`: `protoboard parts list [--check]`, each
+ *   library part with its picture (the library's thumbnail, by `parts/blob`).
+ * - `GET  parts/bom`: `protoboard bom`.
+ * - `POST parts/offers`: `protoboard parts offers`: the library's current
+ *   offers for the project's parts into parts/offers.json; the page's
+ *   session token, like every write. The answer says how many came back.
+ * - `POST parts/bom`: keep the units to build (`{ units }`) or a line's
+ *   chosen offer (`{ line, offer }`, `offer: null` for the best one) in
+ *   parts/bom.json; the page's session token, like every write.
+ * - `POST parts/vendor {key, kind, revision}` (the session token): `protoboard
+ *   parts add|update`, as in a terminal.
+ *
+ * The CLI runs in a child process for anything that loads the project, as
+ * the build does; only the library client runs here.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readOrigins } from "@protoboardai/core";
+import { accountTokensFor } from "@protoboardai/core/account";
+import { connectLibrary, explainCloudError, libraryTaxonomy, markShadowed, partPrices, searchLibraries, type LibrariesTaxonomy, type LibraryConnection } from "@protoboardai/core/library-client";
+import { categoryNamer, detailModel, drillDown, itemModel, libraryViewModel, pageImages, parseLibraryQuery, partPages, previewModel, previewTrust, type LibraryQuery, type Usage } from "@protoboardai/views/parts-data";
+import { parseVerificationRecord } from "@protoboardai/core/part-trust";
+
+export const PARTS_PREFIX = "/__protoboard/parts/";
+const CLI = fileURLToPath(new URL("../../bin/protoboard.mjs", import.meta.url));
+const PAGE = 30;
+const SHA = /^[0-9a-f]{64}$/;
+
+/** `protoboard <args> --format json` in the project, its JSON or its error. */
+export function runCliJson<T>(root: string, args: string[], timeoutMs = 180_000): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [CLI, ...args, "--format", "json"], { cwd: root, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    let out = "";
+    let err = "";
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      try {
+        const json = JSON.parse(out) as T & { error?: string };
+        if (code !== 0 && json && typeof json === "object" && "error" in json && json.error) return reject(new Error(json.error));
+        resolve(json);
+      } catch {
+        reject(new Error((err || out).trim().split("\n").pop() || `protoboard ${args[0]} exited ${code}`));
+      }
+    });
+  });
+}
+
+interface LibraryInfo {
+  id: string;
+  url: string;
+  authEnv?: string;
+}
+
+export interface PartsRoutes {
+  handle(req: IncomingMessage, res: ServerResponse, url: URL, write: { authorised: boolean }): Promise<void>;
+  /** The project's files changed (a rebuild): forget what was read from them. */
+  changed(): void;
+}
+
+export function partsRoutes(root: string): PartsRoutes {
+  let libs: Promise<LibraryConnection[]> | undefined;
+  let taxonomy: { key: string; value: Promise<LibrariesTaxonomy | undefined> } | undefined;
+  const cacheDir = join(root, ".protoboard", "cache", "library");
+
+  const connections = () =>
+    (libs ??= (async () => {
+      const out = await runCliJson<{ libraries: LibraryInfo[] }>(root, ["libraries"]);
+      const signedIn = await accountTokensFor(out.libraries.map((l) => l.url)).catch(() => ({ tokens: new Map<string, string>(), problems: [] }));
+      return out.libraries.map((l) => connectLibrary(l, { accountTokens: signedIn.tokens }));
+    })().catch((e) => {
+      libs = undefined;
+      throw e;
+    }));
+
+  const usage = (): Map<string, Usage> => {
+    const out = new Map<string, Usage>();
+    try {
+      for (const [id, rec] of Object.entries(readOrigins(root).definitions)) {
+        const library = rec.library ?? (rec.provider === "protoboard-cloud" ? "protoboard" : undefined);
+        out.set(id, { ...(typeof rec.revision === "number" ? { revision: rec.revision } : {}), ...(library ? { library } : {}), ...(rec.tier ? { tier: rec.tier } : {}), file: rec.file });
+      }
+    } catch {
+      // no origins yet
+    }
+    return out;
+  };
+
+  const blobUrl = (library: string, b: { sha256: string; size: number; mediaType: string }) => `${PARTS_PREFIX.slice(1)}blob?${new URLSearchParams({ library, sha: b.sha256, size: String(b.size), type: b.mediaType })}`;
+
+  const json = (res: ServerResponse, status: number, body: unknown) => {
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+  };
+
+  async function library(url: URL) {
+    const conns = await connections();
+    const p = url.searchParams;
+    const q: LibraryQuery = parseLibraryQuery({ text: p.get("text") ?? "", category: p.get("category") ?? "", domain: p.get("domain") ?? "", protocol: p.get("protocol") ?? "", sort: p.get("sort") ?? undefined });
+    const key = JSON.stringify([q.text, q.domain, q.protocol]);
+    if (taxonomy?.key !== key) taxonomy = { key, value: libraryTaxonomy(conns, { q: q.text || undefined, domain: q.domain || undefined, protocol: q.protocol || undefined }).catch(() => undefined) };
+    const cursor = p.get("cursor");
+    const [r, tax] = await Promise.all([
+      searchLibraries(conns, { q: q.text || undefined, taxonomy: q.category || undefined, domain: q.domain || undefined, protocol: q.protocol || undefined, sort: q.sort, limit: PAGE, facets: !cursor, ...(cursor ? { cursor } : {}) }),
+      taxonomy.value,
+    ]);
+    const used = usage();
+    const hits = markShadowed(r.parts, conns.map((c) => c.id));
+    const thumbs = Object.fromEntries(hits.filter((h) => h.thumbnail).map((h) => [h.thumbnail!.sha256, blobUrl(h.library, h.thumbnail!)]));
+    const model = libraryViewModel({
+      query: q,
+      ...(tax ? { drill: drillDown(tax.nodes, q.category, { facets: r.facets?.taxonomy, total: tax.total }), top: tax.nodes } : {}),
+      items: hits.map((h) => itemModel(h, used)),
+      total: r.total,
+      // the taxonomy counts each part once; it is the whole catalog while no text, domain or protocol narrows it
+      ...(tax && !q.text && !q.domain && !q.protocol ? { catalogTotal: tax.total } : {}),
+      more: !!r.nextCursor,
+      sources: r.libraries.map((l) => ({ id: l.id, ...(l.total !== undefined ? { total: l.total } : {}), ...(l.error ? { error: l.error } : {}) })),
+      thumbs,
+      loading: false,
+      ...(tax ? { categoryName: categoryNamer(tax.nodes) } : {}),
+      sorts: r.sorts,
+    });
+    const { loading: _l, loadingMore: _m, ...rest } = model;
+    return { model: rest, ...(r.nextCursor ? { cursor: r.nextCursor } : {}) };
+  }
+
+  /** The library and part id of a `<library>/<id>` key. */
+  async function keyed(url: URL) {
+    const key = url.searchParams.get("key") ?? "";
+    const [libraryId, ...rest] = key.split("/");
+    const partId = rest.join("/");
+    const conn = (await connections()).find((c) => c.id === libraryId);
+    if (!conn || !partId) throw new Error(`no part ${key} in the project's libraries`);
+    return { conn, partId };
+  }
+
+  /** A revision's pictures as this server's URLs (verified and cached by `parts/blob`). */
+  const pictureUrls = (library: string, env: Parameters<typeof pageImages>[0]) => Object.fromEntries(pageImages(env).map((i) => [i.sha256, blobUrl(library, i)]));
+
+  /** A part's pages: its revision's specifications, dimensions, interfaces, CAD and artifacts (a revision never changes, so the client keeps them). */
+  async function pages(url: URL) {
+    const { conn, partId } = await keyed(url);
+    try {
+      const asked = Number(url.searchParams.get("revision"));
+      const revision = Number.isInteger(asked) && asked > 0 ? asked : await conn.client.getPart(partId).then((r) => r.part.recommendedRevision ?? r.part.latestRevision);
+      const envelope = await conn.client.getRevision(partId, revision);
+      return partPages(envelope, { urls: pictureUrls(conn.id, envelope) });
+    } catch (e) {
+      throw explainCloudError(e, conn, partId);
+    }
+  }
+
+  /** The part's prices by source: what its library serves, nothing else. A refusal comes back in `unavailable`, with what to do. */
+  async function prices(url: URL) {
+    const { conn, partId } = await keyed(url);
+    return partPrices(conn, partId);
+  }
+
+  async function part(url: URL) {
+    const { conn, partId } = await keyed(url);
+    try {
+      const { part, revisions } = await conn.client.getPart(partId);
+      const asked = Number(url.searchParams.get("revision"));
+      const revision = Number.isInteger(asked) && asked > 0 ? asked : (part.recommendedRevision ?? part.latestRevision);
+      const envelope = await conn.client.getRevision(partId, revision);
+      const tax = await taxonomy?.value;
+      const preview = previewModel({ part, revisions, envelope, library: { id: conn.id, url: conn.url }, usage: usage().get(partId), ...(tax ? { categoryName: categoryNamer(tax.nodes) } : {}) });
+      // the verification record among the evidence says the part's status (PB-932); one that cannot be read reads as unverified
+      const record = preview.verification
+        ? await conn.client.downloadBlob(preview.verification.sha256, { size: preview.verification.size }).then(
+            (bytes) => parseVerificationRecord(Buffer.from(bytes).toString("utf8")),
+            () => null,
+          )
+        : undefined;
+      return detailModel(preview, {
+        pages: partPages(envelope, { urls: pictureUrls(conn.id, envelope) }),
+        hasPrices: true,
+        ...previewTrust(preview, record),
+        ...(part.thumbnail ? { thumb: blobUrl(conn.id, part.thumbnail) } : {}),
+        ...(preview.glb ? { model: blobUrl(conn.id, { sha256: preview.glb.sha256, size: preview.glb.size, mediaType: "model/gltf-binary" }) } : {}),
+      });
+    } catch (e) {
+      throw explainCloudError(e, conn, partId);
+    }
+  }
+
+  /** Library parts' thumbnails by `library/id` (null: the library has none), kept until the project changes. */
+  const pictures = new Map<string, Promise<string | null>>();
+
+  /** `parts list`, each library part with its picture from its library, as the Project Parts page shows it. */
+  async function project(check: boolean) {
+    const report = await runCliJson<{ parts: { id: string; tier: string; library?: string; thumbnail?: string }[] }>(root, ["parts", "list", ...(check ? ["--check"] : [])]);
+    const conns = await connections().catch(() => [] as LibraryConnection[]);
+    await Promise.all(
+      report.parts.map(async (p) => {
+        const conn = p.tier === "catalog" && p.library ? conns.find((c) => c.id === p.library) : undefined;
+        if (!conn) return;
+        const key = `${conn.id}/${p.id}`;
+        if (!pictures.has(key)) {
+          pictures.set(
+            key,
+            conn.client.getPart(p.id).then(
+              (r) => (r.part.thumbnail ? blobUrl(conn.id, r.part.thumbnail) : null),
+              () => {
+                pictures.delete(key); // the library did not answer: ask again next time
+                return null;
+              },
+            ),
+          );
+        }
+        const url = await pictures.get(key);
+        if (url) p.thumbnail = url;
+      }),
+    );
+    return report;
+  }
+
+  async function blob(url: URL, res: ServerResponse) {
+    const p = url.searchParams;
+    const sha = p.get("sha") ?? "";
+    const type = p.get("type") ?? "application/octet-stream";
+    if (!SHA.test(sha) || !/^(image\/(png|jpeg|webp|svg\+xml)|model\/gltf-binary)$/.test(type)) return json(res, 400, { error: "not a part file" });
+    const file = join(cacheDir, sha);
+    if (!existsSync(file)) {
+      const conn = (await connections()).find((c) => c.id === p.get("library"));
+      if (!conn) return json(res, 404, { error: `no library ${p.get("library")}` });
+      const size = Number(p.get("size"));
+      const bytes = await conn.client.downloadBlob(sha, Number.isInteger(size) && size > 0 ? { size } : {});
+      mkdirSync(cacheDir, { recursive: true });
+      const tmp = `${file}.${process.pid}.part`;
+      writeFileSync(tmp, bytes);
+      renameSync(tmp, file);
+    }
+    // an SVG from a library is shown as an image only, never as a page
+    res.writeHead(200, { "content-type": type, "cache-control": "max-age=31536000, immutable", "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'", "x-content-type-options": "nosniff" });
+    res.end(readFileSync(file));
+  }
+
+  async function body(req: IncomingMessage): Promise<unknown> {
+    let text = "";
+    for await (const chunk of req) {
+      text += chunk;
+      if (text.length > 64 << 10) throw new Error("request too large");
+    }
+    return JSON.parse(text);
+  }
+
+  async function vendor(req: IncomingMessage) {
+    const m = (await body(req)) as { key?: unknown; kind?: unknown; revision?: unknown };
+    const key = typeof m.key === "string" ? m.key : "";
+    const [library, ...rest] = key.split("/");
+    const partId = rest.join("/");
+    const revision = Number(m.revision);
+    if (!library || !/^[a-z0-9][a-z0-9._-]*$/i.test(partId) || !Number.isInteger(revision) || revision < 1) throw new Error("give a part key and a revision");
+    const args = m.kind === "add" ? ["parts", "add", `${partId}@${revision}`, "--library", library] : ["parts", "update", partId, "--to", String(revision), "--library", library];
+    const out = await runCliJson<{ results: { id: string; status: string; revision?: number; message?: string }[] }>(root, args);
+    taxonomy = undefined;
+    const self = out.results.find((x) => x.id === partId);
+    const conflict = out.results.find((x) => x.status === "conflict");
+    if (conflict) throw new Error(`${conflict.id}: ${conflict.message ?? "conflict"}`);
+    return { message: `${partId}@${self?.revision ?? revision} ${self?.status ?? "added"} from ${library}` };
+  }
+
+  /** Keep the units to build, or a line's chosen offer, in the project (parts/bom.json), through the CLI. */
+  async function saveBom(req: IncomingMessage) {
+    const m = (await body(req)) as { units?: unknown; line?: unknown; offer?: unknown };
+    if (typeof m.units === "number") {
+      if (!Number.isInteger(m.units) || m.units < 1 || m.units > 1_000_000) throw new Error("units is a whole number from 1 to 1,000,000");
+      return runCliJson(root, ["bom", "units", String(m.units)]);
+    }
+    // a line key is a part id, with an ordering code after "#"; an offer id never starts with a dash
+    if (typeof m.line !== "string" || !m.line || m.line.startsWith("-") || m.line.length > 300) throw new Error("give units, or a line and an offer");
+    if (m.offer !== null && (typeof m.offer !== "string" || !m.offer || m.offer.startsWith("-") || m.offer === "auto" || m.offer.length > 300)) throw new Error("give the offer's id, or null for the best offer");
+    return runCliJson(root, ["bom", "choose", m.line, m.offer ?? "auto"]);
+  }
+
+  /** Ask the library for its current offers for the project's parts (parts/offers.json), through the CLI. Says what came back, not how. */
+  async function refreshOffers() {
+    const r = await runCliJson<{ id: string; status: string; offers?: number }[]>(root, ["parts", "offers"]);
+    const got = r.filter((x) => x.status === "vendored");
+    const offers = got.reduce((n, x) => n + (x.offers ?? 0), 0);
+    return { message: got.length ? `The library gave ${offers} offer${offers === 1 ? "" : "s"} for ${got.length} part${got.length === 1 ? "" : "s"}.` : "The library holds no offers for this project's parts." };
+  }
+
+  return {
+    changed() {
+      libs = undefined;
+      taxonomy = undefined;
+      pictures.clear();
+    },
+    async handle(req, res, url, write) {
+      const route = url.pathname.slice(PARTS_PREFIX.length);
+      try {
+        if (route === "vendor") {
+          if (req.method !== "POST") return json(res, 405, { error: "POST only" });
+          if (!write.authorised) return json(res, 403, { error: "not this page's session" });
+          return json(res, 200, await vendor(req));
+        }
+        if (route === "bom" && req.method === "POST") {
+          if (!write.authorised) return json(res, 403, { error: "not this page's session" });
+          return json(res, 200, await saveBom(req));
+        }
+        if (route === "offers") {
+          if (req.method !== "POST") return json(res, 405, { error: "POST only" });
+          if (!write.authorised) return json(res, 403, { error: "not this page's session" });
+          return json(res, 200, await refreshOffers());
+        }
+        if (req.method !== "GET" && req.method !== "HEAD") return json(res, 405, { error: "GET only" });
+        switch (route) {
+          case "library":
+            return json(res, 200, await library(url));
+          case "part":
+            return json(res, 200, await part(url));
+          case "pages":
+            return json(res, 200, await pages(url));
+          case "prices":
+            return json(res, 200, await prices(url));
+          case "blob":
+            return await blob(url, res);
+          case "project":
+            return json(res, 200, await project(!!url.searchParams.get("check")));
+          case "bom":
+            return json(res, 200, await runCliJson(root, ["bom"]));
+          default:
+            return json(res, 404, { error: `no parts route ${route}` });
+        }
+      } catch (e) {
+        if (!res.headersSent) json(res, 502, { error: (e as Error).message });
+        else res.end();
+      }
+    },
+  };
+}