visualproof 0.2.0 → 0.4.0

package/dist/server/artcmd.js

@@ -0,0 +1,335 @@
+// The artwork command (ExportSpec decision 21): `visualproof artwork <lean-project> --recipe <file>`
+// makes the picture a recipe says (decision 20) without a browser — the same picture as the page's,
+// by the page's own code. The build is read as `visualproof export` reads it; the board is the
+// Project's, laid out as the site keeps it (or as a new site would); the recipe is resolved as the
+// page resolves it; the board is drawn by the page's canvas without a graphics card (its renderer
+// kept to its data, the names measured from the fonts the package ships) on a screen of the given
+// size, the frame placed and fitted as the artwork mode places and fits it; the SVG is written as
+// the page's Save SVG writes it, and the PNG is that SVG drawn by resvg with the same fonts.
+// Nothing is written but the files: the site is read, never written (pipeline `readOnlySite`), and
+// without --site none is read.
+import { readFileSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { createDeflate, crc32, gunzipSync } from "node:zlib";
+import { readRecipe, resolveRecipe } from "../shared/artrecipe.js";
+import { textMeasurer } from "../shared/artfonts.js";
+import { boardSet, lightUp, wholeLayout } from "../shared/board.js";
+import { declAt, guessNames } from "../shared/declfind.js";
+import { litKeyEdges } from "../shared/keys.js";
+import { emptyReview } from "../shared/review.js";
+import { SearchIndex } from "../shared/search.js";
+import { Graph } from "../shared/viewgraph.js";
+import { PROJECT } from "../shared/views.js";
+import { artName, artSvg, borderInset, cleanSettings, cssTheme, drawBackdrop, frameRect, sourceLine, SvgContext, themeBackground, titleOf, titleRoom, writeOver } from "../web/src/artwork.js";
+import { GraphCanvas, themeOf } from "../web/src/canvas.js";
+import { ART_SANS } from "../web/src/halo.js";
+import { ReviewFlow } from "../web/src/reviewqueue.js";
+import { declPick, edgeMode, selectionQuery } from "../web/src/selection.js";
+import { statusCodes } from "../web/src/status.js";
+import { gitSource } from "./history.js";
+import { WEB, WEBFONTS } from "./pipeline.js";
+/** the faces of a picture's names, from the package's own TrueType files (scripts/artfonts.py) */
+const TTF = join(WEBFONTS, "ttf");
+let metrics = null;
+/** How wide text is in a font, as the package's faces draw it. */
+function measurer() {
+    metrics ??= JSON.parse(readFileSync(join(WEBFONTS, "metrics.json"), "utf8"));
+    return textMeasurer(metrics);
+}
+/** The page's font faces, each its WOFF2 written in, as the page's Save SVG writes them (web/src/
+ *  artframe.ts, faces): from the style sheet's rules, the files beside it. */
+export function facesOf(css) {
+    const out = [];
+    for (const m of css.matchAll(/@font-face\s*\{([^}]*)\}/g)) {
+        const body = m[1];
+        const get = (k) => new RegExp(`${k}\\s*:\\s*([^;]+)`).exec(body)?.[1].trim();
+        const family = get("font-family")?.replace(/["']/g, "").trim() ?? "";
+        if (family !== "Source Sans 3" && family !== "Source Serif 4" && family !== "Jost")
+            continue;
+        const file = /url\(["']?\/fonts\/([a-z0-9-]+\.woff2)["']?\)/.exec(body)?.[1];
+        if (!file)
+            continue;
+        const b64 = readFileSync(join(WEBFONTS, file)).toString("base64");
+        out.push(`@font-face{font-family:"${family}";font-style:${get("font-style") || "normal"};font-weight:${get("font-weight") || "400"};src:url(data:font/woff2;base64,${b64}) format("woff2");unicode-range:${get("unicode-range") || "U+0-10FFFF"}}`);
+    }
+    return out.join("");
+}
+/** The Project view as a site keeps it (its pins, folds, hidden levels and clustering: server/views.ts,
+ *  readProjectView), or as a new site has it. */
+export function projectView(kept) {
+    const empty = () => ({ namespace: [], module: [] });
+    return (kept ?? {
+        id: PROJECT,
+        name: null,
+        scope: { op: "all" },
+        clustering: "namespace",
+        pins: { namespace: { clusters: {}, nodes: {} }, module: { clusters: {}, nodes: {} } },
+        folds: empty(),
+        hidden: empty(),
+        by: null,
+        at: new Date(0).toISOString(),
+        kept: true,
+    });
+}
+/** The picture a recipe says, of the build `prep` — its graph and layouts — with the review and the
+ *  Project view a site keeps (or none). */
+export function makeArtwork(prep, review, project, ask) {
+    const read = readRecipe(ask.recipe);
+    if ("error" in read)
+        return { problems: [`${read.error} ${read.hint}`] };
+    const r = read.recipe;
+    if (r.view && r.view !== PROJECT)
+        return { problems: [`the command draws the Project view: the recipe names the view ${r.view}`] };
+    const meta = JSON.parse(gunzipSync(prep.metaGz).toString("utf8"));
+    const raw = gunzipSync(prep.edgesGz);
+    const g = new Graph(meta, new Int32Array(raw.buffer, raw.byteOffset, raw.byteLength / 4));
+    const data = review ?? emptyReview();
+    // the board: the Project's, on the server's layout under the levels it hides
+    const mode = project.clustering;
+    const bs = boardSet(g, data, project.scope);
+    const L = wholeLayout(meta.layouts[mode], g.nodes, mode, project.hidden[mode]);
+    // the targets: the review's with a site, those the recipe names without one
+    const onGraph = (n) => g.byName.has(n);
+    const targets = review ? Object.keys(data.targets) : Array.isArray(r.targets) ? r.targets.filter(onGraph) : [];
+    const problems = [];
+    let sel = null;
+    if (r.selection) {
+        // as the agents' API finds a declaration (shared/declfind.ts): a name it folds is the declaration
+        // it is folded into; none, what was likely meant
+        const i = declAt(g, r.selection.name);
+        if (i !== undefined)
+            sel = { name: g.nodes[i].name, mode: r.selection.mode ?? "tcb" };
+        else {
+            const meant = guessNames(g, new SearchIndex(meta.nodes, meta.projectCount), r.selection.name.trim());
+            problems.push(`no declaration ${r.selection.name} in the graph${meant.length ? ` (did you mean ${meant[0]}?)` : ""}`);
+        }
+    }
+    const res = resolveRecipe(r, {
+        clusters: L.clusters,
+        clusterOf: (name) => {
+            const i = g.byName.get(name);
+            return i === undefined ? undefined : L.cluster[i];
+        },
+        targets,
+        projectCount: g.projectCount,
+    });
+    problems.push(...res.problems);
+    if (problems.length)
+        return { problems };
+    const s = cleanSettings(res.look, { scheme: "kind", theme: "light" });
+    // the theme as the mode sets it (web/src/main.ts, drawLook): the board's style in the artwork's,
+    // the cells and the starfield in the dark one
+    const css = readFileSync(join(WEB, "style.css"), "utf8");
+    const v = cssTheme(css, s.style === "board" ? s.theme === "dark" : true);
+    const measure = measurer();
+    // the board, drawn without a browser on a screen of the size asked
+    const scratch = new SvgContext(measure, ART_SANS);
+    const none = () => { };
+    const C = new GraphCanvas(null, null, null, g, { nodeClick: none, clusterClick: none, backgroundClick: none, hover: none, pinsChanged: none, foldChanged: none }, { w: ask.screen.w, h: ask.screen.h, theme: themeOf(v), ctx: scratch });
+    C.setGraph(g);
+    C.setLayout(L, project.pins[mode], project.folds[mode], mode);
+    C.setShowExternals(bs.whole ? bs.outside : true);
+    // the review on it, as the page's syncStatus puts it (no build's file states: none is known here)
+    const idx = targets.map((n) => g.byName.get(n)).filter((j) => j !== undefined);
+    C.setStatus(statusCodes(data, g, new Map()));
+    C.setTargets(idx);
+    const flow = new ReviewFlow({ graph: () => g, review: () => data, reader: () => null });
+    const keys = new Map();
+    for (const t of idx)
+        for (const k of flow.keys(t).keys)
+            if (k !== t)
+                keys.set(k, [...(keys.get(k) ?? []), t]);
+    C.setKeys([...keys.keys()], [...keys.values()]);
+    // the artwork's look, as drawLook gives it
+    C.setScheme(s.scheme);
+    C.setEdges(s.edges !== "none");
+    C.setArt({ labels: s.labels, namesFrom: s.namesFrom, hidden: new Set(s.hiddenNames), shown: new Set(s.shownNames), ruled: new Set(s.ruledNames), edges: s.edges, targets: s.targets, shownTargets: new Set(s.shownTargets), keys: s.keys, style: s.style });
+    // the selection, as the page's apply makes it
+    const picks = sel ? [declPick(sel.mode, sel.name)] : [];
+    const q = selectionQuery(picks);
+    const lit = q && lightUp(g, data, bs, q);
+    const keyEdges = sel?.mode === "keys" && lit && lit.count ? litKeyEdges(idx.map((t) => flow.keys(t)), (i) => lit.set[i] === 1).flat() : null;
+    if (s.targets === "highlight") {
+        const alone = new Uint8Array(g.n);
+        for (const i of idx)
+            alone[i] = 1;
+        C.setActivation(edgeMode(picks), [], alone, [], null);
+    }
+    else if (!s.selection)
+        C.setActivation(edgeMode(picks), [], null, [], null);
+    else
+        C.setActivation(edgeMode(picks), sel ? [g.byName.get(sel.name)] : [], lit?.set ?? null, [], keyEdges);
+    // the frame, placed and fitted as the mode places and fits it (web/src/artframe.ts, place, open)
+    const rect = frameRect(ask.screen, s);
+    // the title's line counts the targets marked: the review's, or the recipe's where there is no site
+    const own = titleOf(meta.project.name, meta.projectCount, review ? Object.keys(data.targets).length : targets.length);
+    const below = titleRoom(rect.h, s, own);
+    const cam = C.fitCam({ x: rect.x, y: rect.y + below, w: rect.w, h: rect.h - below });
+    if (cam)
+        C.jumpTo(cam);
+    C.settle();
+    // what the names are: those written, and those a rule chose that would have covered another
+    const written = C.writtenNames();
+    const name = (id) => id.slice(2).replace("⟨external⟩", "External");
+    const git = s.source ? gitSource(ask.root) : null;
+    const source = git ? sourceLine(git) : null;
+    // the SVG, as the page's Save SVG writes it (artframe saveFile); notes are not drawn here
+    const ground = s.background !== "transparent";
+    const bg = ground && s.style === "board" ? themeBackground(v) : null;
+    const svg = artSvg(rect, s, bg, ART_SANS, measure, (pen) => {
+        const ctx = pen;
+        if (ground)
+            drawBackdrop(ctx, s.style, rect);
+        if (s.border) {
+            const i = borderInset(rect);
+            pen.clipRect("inside", rect.x + i, rect.y + i, rect.w - 2 * i, rect.h - 2 * i);
+            pen.raw(`<g clip-path="url(#inside)">`);
+        }
+        for (const sh of C.artShapes(rect))
+            pen.shape(sh);
+        C.drawMarks(ctx);
+        if (s.border)
+            pen.raw(`</g>`);
+        writeOver(ctx, s, rect, own, source, v);
+    }, facesOf(css));
+    const title = ask.name ?? (s.title || meta.project.name);
+    return {
+        problems: [],
+        look: s,
+        names: {
+            written: [...written].map(name),
+            ruledSkipped: s.ruledNames.filter((id) => !written.has(id)).map(name),
+            left: res.left,
+        },
+        targets: s.targets === "chosen" ? s.shownTargets : s.targets === "plain" ? [] : idx.map((j) => g.nodes[j].name),
+        selection: sel,
+        notesLeftOut: s.notes ? (project.notes ?? []).length : 0,
+        svg,
+        file: (kind) => artName(title, kind),
+    };
+}
+let wasmReady = null;
+let ttfs = null;
+/** resvg's WebAssembly build, ready, with the package's TrueType faces and none of the system's
+ *  (decision 21: the PNG agrees with the SVG, and is the same on every machine) */
+async function renderer() {
+    const { initWasm, Resvg } = await import("@resvg/resvg-wasm");
+    wasmReady ??= initWasm(readFileSync(createRequire(import.meta.url).resolve("@resvg/resvg-wasm/index_bg.wasm")));
+    await wasmReady;
+    ttfs ??= readdirSync(TTF)
+        .filter((f) => f.endsWith(".ttf"))
+        .sort()
+        .map((f) => new Uint8Array(readFileSync(join(TTF, f))));
+    const opts = { font: { fontBuffers: ttfs, loadSystemFonts: false, defaultFontFamily: "Source Sans 3" } };
+    return (svg) => new Resvg(svg, opts);
+}
+/** The most pixels a PNG is drawn in at once. resvg holds a picture four times over and more (its
+ *  clipped groups' layers and their masks: 17 bytes a pixel) in WebAssembly's memory, which is at
+ *  most 4 GiB: a picture of 80 million pixels takes 1.9 GB, the largest (16384 × 16384) more than
+ *  there is. A larger one is drawn in bands of BAND_PIXELS (the largest: 2.0 GB). */
+export const PNG_PIXELS = 80_000_000;
+/** A band's pixels: resvg's layers reach up to twice the band's height beyond it, so that a band
+ *  costs 35 bytes a pixel, 0.7 GB, and the picture is drawn about three times as long. */
+const BAND_PIXELS = 20_000_000;
+/** An artwork's SVG (artSvg's: its root's viewBox the frame, its width and height the picture's) as
+ *  it draws rows `y0` to `y0 + rows` of the picture: its viewBox moved down, the background's
+ *  rectangle (its `100%`, which a moved viewBox would not move) in the frame's units, and the frame's
+ *  clip left out, as the band is within the frame. The border's clip is kept, and given a rectangle
+ *  as large as the frame that draws nothing: resvg 2.6 fails (WebAssembly's `unreachable`) on a
+ *  clipped group whose contents lie more than twice the band's height away from it. */
+export function bandSvg(svg, y0, rows) {
+    const root = /^<svg ([^>]*?)viewBox="0 0 ([\d.]+) ([\d.]+)" width="(\d+)" height="(\d+)"/.exec(svg);
+    const board = /<g clip-path="url\(#frame\)"><g transform="translate\(([-\d.]+) ([-\d.]+)\)">/.exec(svg);
+    if (!root || !board)
+        throw new Error("not an artwork's SVG");
+    const [W, H, PH] = [Number(root[2]), Number(root[3]), Number(root[5])];
+    const f = H / PH;
+    return svg
+        .replace(root[0], `<svg ${root[1]}viewBox="0 ${y0 * f} ${W} ${rows * f}" width="${root[4]}" height="${rows}"`)
+        .replace(`<rect width="100%" height="100%"`, `<rect width="${W}" height="${H}"`)
+        .replace(board[0], `<g><g transform="translate(${board[1]} ${board[2]})">`)
+        .replace(`<g clip-path="url(#inside)">`, `<g clip-path="url(#inside)"><rect x="${-Number(board[1])}" y="${-Number(board[2])}" width="${W}" height="${H}" fill="#000" fill-opacity="0"/>`);
+}
+/** An SVG drawn as a PNG at the size its root says, by resvg. A picture of more than `most` pixels
+ *  is drawn in bands of about `band` pixels (bandSvg) and written as one PNG, row by row: the same
+ *  picture, its pixels a few levels apart where translucent shapes overlap (resvg's layers round
+ *  otherwise than one drawing). */
+export async function pngOf(svg, most = PNG_PIXELS, band = BAND_PIXELS) {
+    const render = await renderer();
+    const m = /^<svg [^>]*?width="(\d+)" height="(\d+)"/.exec(svg);
+    const [w, h] = m ? [Number(m[1]), Number(m[2])] : [0, 0];
+    const failed = (e) => new Error(`the PNG${m ? `, ${w} × ${h},` : ""} could not be drawn (${e instanceof Error ? e.message : String(e)})`);
+    if (!m || w * h <= most) {
+        const r = render(svg);
+        let png;
+        try {
+            const image = r.render();
+            png = image.asPng();
+            image.free();
+        }
+        catch (e) {
+            // resvg is not called again once it has failed: the command ends
+            throw failed(e);
+        }
+        r.free();
+        return png;
+    }
+    // the rows, each its filter byte (none) and its pixels, demultiplied as resvg's own PNG has them
+    // (tiny-skia's `demultiply`)
+    const deflate = createDeflate({ level: 6 });
+    const out = [];
+    deflate.on("data", (b) => out.push(b));
+    const done = new Promise((ok, fail) => {
+        deflate.on("end", ok);
+        deflate.on("error", fail);
+    });
+    // bands of even heights, so that none is a sliver
+    const count = Math.ceil(h / Math.max(1, Math.floor(band / w)));
+    const rows = Math.ceil(h / count);
+    for (let y = 0; y < h; y += rows) {
+        const n = Math.min(rows, h - y);
+        const r = render(bandSvg(svg, y, n));
+        let px;
+        try {
+            const image = r.render();
+            px = image.pixels;
+            image.free();
+        }
+        catch (e) {
+            throw failed(e);
+        }
+        r.free();
+        const lines = Buffer.alloc(n * (w * 4 + 1));
+        for (let row = 0; row < n; row++) {
+            const o = row * (w * 4 + 1) + 1, from = row * w * 4;
+            for (let x = 0; x < w * 4; x += 4) {
+                const a = px[from + x + 3];
+                lines[o + x + 3] = a;
+                if (a === 255)
+                    for (let c = 0; c < 3; c++)
+                        lines[o + x + c] = px[from + x + c];
+                else if (a > 0)
+                    for (let c = 0; c < 3; c++)
+                        lines[o + x + c] = Math.min(255, Math.floor(px[from + x + c] / (a / 255) + 0.5));
+            }
+        }
+        if (!deflate.write(lines))
+            await new Promise((ok) => deflate.once("drain", ok));
+    }
+    deflate.end();
+    await done;
+    const chunk = (type, data) => {
+        const head = Buffer.alloc(8);
+        head.writeUInt32BE(data.length, 0);
+        head.write(type, 4, "latin1");
+        const crc = Buffer.alloc(4);
+        crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])) >>> 0, 0);
+        return Buffer.concat([head, data, crc]);
+    };
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(w, 0);
+    ihdr.writeUInt32BE(h, 4);
+    ihdr.set([8, 6, 0, 0, 0], 8);
+    return new Uint8Array(Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk("IHDR", ihdr), chunk("IDAT", Buffer.concat(out)), chunk("IEND", Buffer.alloc(0))]));
+}

package/dist/server/children.js

@@ -0,0 +1,85 @@
+// The programs the server runs and waits for — the extractor and the Lean programs' build, the
+// usage pass's `lake env`, Lean's language server, XeLaTeX, ImageMagick, Poppler, git, ps — kept
+// here while they run, so that a server stopping stops them (UpdateSpec decision 9) rather than
+// leave them working for nobody. Those that start programs of their own (Lake starts Lean, Lean's
+// server its workers, XeLaTeX kpathsea's, ImageMagick its delegates) run in a process group of
+// their own (`grouped`, spawn's `detached`), and are stopped with all they started; what is left
+// at the server's exit is ended at once. The usage pass's workers have a stop of their own
+// (server/usage.ts).
+const running = new Set();
+/** the children that lead a process group of their own */
+const groups = new WeakSet();
+/** spawn's `detached` for a program run as a group (`grouped`): its own process group, where the
+ *  platform has them */
+export const DETACH = process.platform !== "win32";
+/** Keep `child` as `tracked` does, as the leader of a process group of its own: spawned with
+ *  `detached: DETACH`, and stopped with every program it started. */
+export function grouped(child) {
+    if (DETACH)
+        groups.add(child);
+    return tracked(child);
+}
+/** End `child` with `signal`: where it leads a process group, the whole group. */
+export function end(child, signal = "SIGTERM") {
+    if (groups.has(child) && child.pid && child.exitCode === null) {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // the group is gone: the child alone, if it is not
+        }
+    }
+    child.kill(signal);
+}
+// what still runs as the server's process ends goes with it
+process.once("exit", () => {
+    for (const c of running)
+        end(c, "SIGKILL");
+});
+/** Keep `child` until it exits; the same child, for `spawn(…)` to be wrapped in place. */
+export function tracked(child) {
+    running.add(child);
+    const gone = () => running.delete(child);
+    child.once("exit", gone);
+    child.once("error", gone);
+    return child;
+}
+/** The environment a program the server runs is given: the server's own, without what is the
+ *  server's alone (`VISUALPROOF_*`: the supervisor's word to it, its test hooks; UpdateSpec decision
+ *  9), with `extra` over it. */
+export function childEnv(extra = {}) {
+    const env = {};
+    for (const [k, v] of Object.entries(process.env))
+        if (!k.startsWith("VISUALPROOF_"))
+            env[k] = v;
+    return { ...env, ...extra };
+}
+/** How many tracked programs run now. */
+export function childCount() {
+    return running.size;
+}
+/** Ask every tracked program to end (SIGTERM), and end those still there after `graceMs`
+ *  (SIGKILL). Resolves once none runs, or at the end of the grace; the process waits for it. */
+export function stopChildren(graceMs = 2000) {
+    if (!running.size)
+        return Promise.resolve();
+    for (const c of running)
+        end(c, "SIGTERM");
+    return new Promise((resolve) => {
+        const t0 = Date.now();
+        const tick = setInterval(() => {
+            if (!running.size) {
+                clearInterval(tick);
+                return resolve();
+            }
+            if (Date.now() - t0 >= graceMs) {
+                for (const c of running)
+                    end(c, "SIGKILL");
+                running.clear();
+                clearInterval(tick);
+                resolve();
+            }
+        }, 50);
+    });
+}

package/dist/server/doctor.js

@@ -1,52 +1,25 @@
 // `visualproof doctor [<lean-project>]`: what this machine, and a project, need for VisualProof to
-// run, each checked, with what to do where it falls short. It changes nothing: it runs no Lake (in a
-// project's folder that would install its toolchain, and Lake may build), and makes no folder.
+// run, each checked, with what to do where it falls short; and whether a newer VisualProof is out,
+// asked of the npm registry through npm (UpdateSpec decision 1). It changes nothing: it runs no Lake
+// (in a project's folder that would install its toolchain, and Lake may build), and makes no folder.
 import { spawnSync } from "node:child_process";
-import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
+import { filmPin } from "./film.js";
+import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
-import { projectDirs, siteHolder } from "./dirs.js";
+import { cacheHome, projectDirs, siteHolder } from "./dirs.js";
+import { cmp, packageVersion, parseVersion, satisfies } from "./version.js";
+import { choose, FROM_PACKAGE, installCommand, newerThan, newest, notesOf, npmCommand, PACKAGE_ROOT, readInfo, sameMinor, Versions } from "./updates.js";
+export { packageVersion, satisfies };
 import { ProjectError, openProject, targetsInWords } from "./project.js";
-export const run = (cmd, args) => {
-    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 30_000, stdio: ["ignore", "pipe", "pipe"] });
+export const run = (cmd, args, cwd) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 30_000, stdio: ["ignore", "pipe", "pipe"], ...(cwd ? { cwd } : {}) });
     return r.error || r.status !== 0 ? null : `${r.stdout}${r.stderr}`;
 };
 /** The package's own file, read where both a checkout and the installed package have it. */
 function packageFile(rel) {
     return join(import.meta.dirname, "..", "..", rel);
 }
-export function packageVersion() {
-    return JSON.parse(readFileSync(packageFile("package.json"), "utf8")).version;
-}
-function parseVersion(v) {
-    const m = /(\d+)\.(\d+)\.(\d+)/.exec(v);
-    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
-}
-function cmp(a, b) {
-    for (let i = 0; i < 3; i++)
-        if (a[i] !== b[i])
-            return a[i] - b[i];
-    return 0;
-}
-/** Whether a version meets a range of the forms package.json's `engines` uses: alternatives
- *  joined by `||`, each of `^x.y.z`, `>=x.y.z`, `<x.y.z`, joined by spaces. */
-export function satisfies(version, range) {
-    const v = parseVersion(version);
-    if (!v)
-        return false;
-    return range.split("||").some((alt) => alt.trim().split(/\s+/).every((part) => {
-        const m = /^(\^|>=|<|)(\d+\.\d+\.\d+)$/.exec(part);
-        if (!m)
-            return false;
-        const w = parseVersion(m[2]);
-        if (m[1] === "^")
-            return v[0] === w[0] && cmp(v, w) >= 0;
-        if (m[1] === ">=")
-            return cmp(v, w) >= 0;
-        if (m[1] === "<")
-            return cmp(v, w) < 0;
-        return cmp(v, w) === 0;
-    }));
-}
 /** A toolchain as elan names it: `leanprover/lean4:v4.33.1`, whether the project writes it so, or
  *  as a bare version, or elan lists it as its folder's name (`leanprover--lean4---v4.33.1`). */
 export function toolchainName(t) {
@@ -92,6 +65,93 @@ function install(what, platform) {
         return platform === "darwin" ? "brew install poppler" : "install poppler-utils (Debian, Ubuntu: sudo apt install poppler-utils)";
     return platform === "darwin" ? "install MacTeX, or brew install --cask mactex-no-gui" : "install TeX Live's XeLaTeX (Debian, Ubuntu: sudo apt install texlive-xetex texlive-latex-extra)";
 }
+/** What the registry says of the releases beyond this one, in a line (UpdateSpec decisions 1–4, 7):
+ *  asked through npm under this Node, unless updates are off (VISUALPROOF_UPDATES=off); with what
+ *  this machine's servers set aside. */
+function updatesLine(exec, node, fromPackage, cacheRoot, mode, site) {
+    const running = packageVersion();
+    if (!fromPackage)
+        return "a checkout: its updates are git's, not npm's";
+    if (mode === "off")
+        return "not asked (VISUALPROOF_UPDATES=off)";
+    // what is set aside now (for the project's site, where one is checked), and where its patches are paused
+    const kept = new Versions(cacheRoot);
+    const held = kept.reasons(Date.now(), site);
+    const paused = kept.paused(site);
+    const bad = new Map(held.map((h) => [h.version, h]));
+    const aside = (held.length ? `; set aside here: ${held.map((h) => `${h.version} (${h.why})`).join(", ")}` : "") +
+        (paused ? `; this site's patches up to ${paused.upTo} are not taken (${paused.why})` : "");
+    const { cmd, args } = npmCommand();
+    // run where no project's .npmrc applies: the caches' root, else the temporary folder
+    const cwd = existsSync(cacheRoot) ? cacheRoot : tmpdir();
+    const ask = (more) => exec(cmd, [...args, ...more, "--fetch-timeout=15000", "--fetch-retries=1"], cwd);
+    // npm's own warnings come after its answer: the answer alone is read
+    const json = (out, re) => {
+        const m = out === null ? null : re.exec(out)?.[0];
+        try {
+            return m ? JSON.parse(m) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const v = json(ask(["view", "visualproof", "versions", "--json"]), /\[[^\]]*\]|"[^"\n]*"/);
+    if (v === undefined)
+        return `the npm registry could not be asked (offline, or npm not found): not checked${aside}`;
+    const versions = (Array.isArray(v) ? v : [v]).filter((x) => typeof x === "string");
+    // the engines of the newest beyond this one: those the doctor would name
+    const engines = new Map();
+    const deprecated = new Set();
+    const first = choose(running, versions, { bad: new Set(bad.keys()) });
+    for (const c of [first.patch, first.release]) {
+        if (!c || engines.has(c))
+            continue;
+        const out = ask(["view", `visualproof@${c}`, "engines", "deprecated", "--json"]);
+        const info = out === null ? null : readInfo(/^[\s\S]*?(\{[\s\S]*\}|"[^"\n]*")/.exec(out)?.[1] ?? "");
+        if (!info)
+            continue;
+        engines.set(c, info.engines);
+        if (info.deprecated)
+            deprecated.add(c);
+    }
+    // only versions npm said the engines and deprecation of are named: one it could not say of is not
+    const { patch, release } = choose(running, versions.filter((x) => engines.has(x)), { node, bad: new Set(bad.keys()), engines: (x) => engines.get(x), deprecated });
+    const skipped = newest(versions.filter((x) => newerThan(x, running)));
+    const unsaid = [first.patch, first.release].find((c) => c && !engines.has(c));
+    if (release && !sameMinor(release, running))
+        return `${release} is out: ${installCommand(PACKAGE_ROOT, release)} (${notesOf(release)}); a server restarts into it by itself${aside}`;
+    // the pause is said in `aside`: no server here takes this one
+    if (patch && paused && !newerThan(patch, paused.upTo))
+        return `${patch} is out, not taken${aside}, for a day or until a newer patch`;
+    if (patch)
+        return `${patch} is out: a server takes it by itself (--updates auto), or ${installCommand(PACKAGE_ROOT, patch)}${aside}`;
+    if (unsaid)
+        return `${unsaid} is out, but npm could not say what it needs: not checked${aside}`;
+    if (skipped && deprecated.has(skipped))
+        return `${skipped} is out, but deprecated by its publisher${aside}`;
+    if (skipped && engines.has(skipped))
+        return `${skipped} is out, but needs Node ${engines.get(skipped)}; this is ${node}${aside}`;
+    return `the latest release${aside}`;
+}
+/** The tips' tour film, in a line: kept in the cache, or fetched on its first play, or never. */
+function filmLine(cacheRoot, mode) {
+    if (process.env.VISUALPROOF_TOUR_FILM)
+        return `the local file ${process.env.VISUALPROOF_TOUR_FILM} (VISUALPROOF_TOUR_FILM)`;
+    const pin = filmPin();
+    if (!pin)
+        return "none pinned in this package";
+    const kept = join(cacheRoot, "media", `${pin.sha256}.mp4`);
+    try {
+        if (statSync(kept).size === pin.size)
+            return `kept (${kept})`;
+    }
+    catch {
+        // not kept yet
+    }
+    if (mode === "off")
+        return "never fetched (VISUALPROOF_UPDATES=off): the tour shows its stills and captions";
+    return `fetched from the project's GitHub release on its first play (${(pin.size / 1e6).toFixed(0)} MB)`;
+}
 export function doctor(o) {
     const exec = o.run ?? run;
     const node = o.node ?? process.versions.node;
@@ -121,8 +181,10 @@ export function doctor(o) {
     if (exec("git", ["--version"]) === null) {
         checks.push({ level: "info", what: "git not found: builds are kept without their commit, and past sources only as the builds kept them" });
     }
+    const film = filmLine(o.cache ? resolve(o.cache) : cacheHome(), o.updates ?? process.env.VISUALPROOF_UPDATES);
+    const updates = updatesLine(exec, node, o.fromPackage ?? FROM_PACKAGE, o.cache ? resolve(o.cache) : cacheHome(), o.updates ?? process.env.VISUALPROOF_UPDATES, o.path === null ? null : projectDirs(resolve(o.path), o.site, o.cache).site);
     if (o.path === null)
-        return { checks, ready: null };
+        return { checks, updates, film, ready: null };
     let project;
     try {
         project = openProject(o.path, o.roots, false);
@@ -131,7 +193,7 @@ export function doctor(o) {
         if (!(e instanceof ProjectError))
             throw e;
         checks.push({ level: "fail", what: e.message });
-        return { checks, ready: null };
+        return { checks, updates, film, ready: null };
     }
     const { root, toolchain, roots, libDir } = project;
     const name = toolchainName(toolchain);
@@ -168,7 +230,7 @@ export function doctor(o) {
         : { level: "info", what: `site ${dirs.site}: a server (process ${holder}) is serving it; another needs a --site of its own` });
     const failed = checks.some((c) => c.level === "fail");
     const args = [o.path, ...o.roots.flatMap((r) => ["--root", r]), ...(o.site ? ["--site", o.site] : []), ...(o.cache ? ["--cache", o.cache] : [])];
-    return { checks, ready: failed ? null : `visualproof serve ${args.map((a) => (/^[\w./:@%+=-]+$/.test(a) ? a : JSON.stringify(a))).join(" ")}` };
+    return { checks, updates, film, ready: failed ? null : `visualproof serve ${args.map((a) => (/^[\w./:@%+=-]+$/.test(a) ? a : JSON.stringify(a))).join(" ")}` };
 }
 const MARK = { ok: "✓", fail: "✗", warn: "!", info: "·" };
 export function printReport(r, project) {
@@ -178,6 +240,7 @@ export function printReport(r, project) {
         if (c.fix && c.level !== "ok")
             lines.push(`      ${c.fix}`);
     }
+    lines.push(`  updates: ${r.updates}`, `  tour film: ${r.film}`);
     if (r.ready)
         lines.push("", `Ready: ${r.ready}`);
     else if (project === null && !r.checks.some((c) => c.level === "fail"))

package/dist/server/events.js

@@ -77,6 +77,16 @@ export class Timeline {
         renameSync(tmp, this.file);
     }
     /** Record an event, and tell every page. */
+    /** The VisualProof version the timeline last recorded as serving the site (UpdateSpec decision
+     *  10), or null where none is kept. */
+    lastVersion() {
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            const e = this.events[i];
+            if (e.kind === "tool")
+                return e.to;
+        }
+        return null;
+    }
     add(e) {
         const full = { ...e, id: (this.events[this.events.length - 1]?.id ?? 0) + 1, at: new Date().toISOString() };
         this.events.push(full);