visualproof 0.2.0 → 0.4.0

package/dist/server/media.js

@@ -0,0 +1,114 @@
+// What the sheet's tips play (GuideSpec decision 6): the tour film's data, assets/tips/tour.json (the
+// film pinned by its sha256, its chapters, its captions), its poster tour.webp and each chapter's
+// still tour-<chapter>.webp; its captions as WebVTT, made from tour.json; the film itself,
+// /tips/tour.mp4, which is not in the package (server/film.ts fetches it); and the phone's gestures
+// (phone-fingers.light.mp4). Served as they are (they are compressed already) and with byte
+// ranges, which Safari needs to play a video at all; and which clips there are.
+import { closeSync, createReadStream, fstatSync, openSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream";
+import { WEBFONTS } from "./pipeline.js";
+/** where the clips are: beside the artworks' fonts, in the checkout's src/assets or the package's dist/assets */
+export const TIPS_DIR = join(dirname(WEBFONTS), "tips");
+/** a clip's or its key frame's address, the film's data, poster and stills */
+export const TIP_PATH = /^\/tips\/(?:[a-z0-9]+(?:-[a-z0-9]+)*\.(?:light|dark)\.(?:mp4|webp)|tour(?:-[a-z0-9]+)?\.webp|tour\.json)$/;
+/** A time of a WebVTT cue: hh:mm:ss.mmm. */
+function vttTime(t) {
+    const ms = Math.max(0, Math.round(t * 1000));
+    const p = (n, w = 2) => String(n).padStart(w, "0");
+    return `${p(Math.floor(ms / 3_600_000))}:${p(Math.floor(ms / 60_000) % 60)}:${p(Math.floor(ms / 1000) % 60)}.${p(ms % 1000, 3)}`;
+}
+/** The film's captions as WebVTT, for assistive technology (the page draws its own from
+ *  tour.json): each cue in order, its text on one line, nothing in it read as markup. Null where
+ *  tour.json says none. */
+export function tourVtt(raw) {
+    const caps = raw?.captions;
+    if (!Array.isArray(caps))
+        return null;
+    const cues = caps.filter((c) => !!c && typeof c.start === "number" && typeof c.end === "number" && c.end > c.start && typeof c.text === "string");
+    const text = (t) => t.replace(/[\r\n]+/g, " ").replace(/-->/g, "→").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    return "WEBVTT\n\n" + cues.map((c) => `${vttTime(c.start)} --> ${vttTime(c.end)}\n${text(c.text)}\n`).join("\n");
+}
+/** tour.json as the package holds it; null where there is none. */
+export function tourData(dir = TIPS_DIR) {
+    try {
+        return JSON.parse(readFileSync(join(dir, "tour.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+const TYPES = { mp4: "video/mp4", webp: "image/webp", json: "application/json" };
+/** The clips there are: those recorded in the light theme (the film is light only). */
+export function tipClips(dir = TIPS_DIR) {
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return files.flatMap((f) => {
+        const m = /^([a-z0-9]+(?:-[a-z0-9]+)*)\.light\.mp4$/.exec(f);
+        return m ? [m[1]] : [];
+    });
+}
+/** Whether the request already has the content `etag` names. */
+function fresh(req, etag) {
+    const have = req.headers["if-none-match"];
+    return !!have && have.split(",").some((t) => t.trim().replace(/^W\//, "") === etag);
+}
+function answer(res, code, headers = {}) {
+    res.writeHead(code, headers);
+    res.end();
+}
+/** A clip or a key frame: the whole file, or the range asked for (206), or what cannot be given
+ *  (416). The file is opened before anything is answered, so that one that cannot be read is a
+ *  404 rather than a cut connection; it is closed however the answer ends — sent, refused, or the
+ *  reader gone in the middle of it. */
+export function sendMedia(req, res, file) {
+    let fd;
+    try {
+        fd = openSync(file, "r");
+    }
+    catch {
+        return answer(res, 404, { "content-type": "application/json", "cache-control": "no-store" });
+    }
+    let size, mtime;
+    try {
+        ({ size, mtimeMs: mtime } = fstatSync(fd));
+    }
+    catch {
+        closeSync(fd);
+        return answer(res, 404);
+    }
+    const etag = `"${size.toString(36)}-${Math.round(mtime).toString(36)}"`;
+    const head = { "content-type": TYPES[file.slice(file.lastIndexOf(".") + 1)] ?? "application/octet-stream", "cache-control": "no-cache", etag, "accept-ranges": "bytes" };
+    const done = (code, headers) => {
+        closeSync(fd);
+        answer(res, code, headers);
+    };
+    if (fresh(req, etag))
+        return done(304, head);
+    const m = /^bytes=(\d*)-(\d*)$/.exec(String(req.headers.range ?? "").trim());
+    let start = 0, end = size - 1;
+    if (m && (m[1] || m[2])) {
+        // from a byte to another (or to the end), or the last so many
+        if (m[1])
+            [start, end] = [Number(m[1]), m[2] ? Math.min(Number(m[2]), size - 1) : size - 1];
+        else
+            start = Math.max(0, size - Number(m[2]));
+        if (start > end)
+            return done(416, { "content-range": `bytes */${size}` });
+        res.writeHead(206, { ...head, "content-range": `bytes ${start}-${end}/${size}`, "content-length": end - start + 1 });
+    }
+    else
+        res.writeHead(200, { ...head, "content-length": size });
+    if (req.method === "HEAD" || size === 0) {
+        closeSync(fd);
+        return void res.end();
+    }
+    // the stream owns the descriptor from here: pipeline destroys it, and so closes the file, when
+    // the answer is sent, fails, or the reader goes away
+    pipeline(createReadStream(file, { fd, start, end, autoClose: true }), res, () => { });
+}

package/dist/server/pipeline.js

@@ -11,6 +11,7 @@ import { cachedExtraction, extract, loadSaved, prune } from "./extract.js";
 import { memoryOf } from "../shared/layout.js";
 import { buildViewOffThread } from "./view.js";
 import { cacheHome } from "./dirs.js";
+import { packageVersion } from "./version.js";
 /** the tool's own folder, `src/`; the repository is above it */
 export const SRC = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 /** the fonts the page draws an artwork's names and title in (ExportSpec decision 19): Source Sans 3
@@ -41,8 +42,9 @@ export function bundleDir() {
  *  views from an older server are rebuilt rather than served. 7: a notation unit's statement is
  *  its command's text. 8: notation units carry their Lean constant, display form, what they
  *  interpret and their rules. 9: a node's hash is its version, beside the kernel's
- *  (server/versions.ts). 10: the project's git source and commit (server/history.ts, gitSource). */
-const VIEW_VERSION = 10;
+ *  (server/versions.ts). 10: the project's git source and commit (server/history.ts, gitSource). 11:
+ *  not them any more: they are asked when wanted (GET /api/git), not kept with the view. */
+const VIEW_VERSION = 11;
 function loadMemory(siteDir) {
     try {
         const mem = JSON.parse(readFileSync(join(siteDir, "layout-memory.json"), "utf8"));
@@ -63,7 +65,9 @@ export async function prepare(project, dirs, saved, log, opts = {}) {
     // `reuse`: lay out an extraction already held, without reading the build (which may be
     // half-written right now); `extraction`: one in hand (the usage pass's, merged); `provisional`:
     // the graph waits for its usage pass; `completes`: the fingerprint of the build's extraction that
-    // this graph, the usage pass's merged, completes
+    // this graph, the usage pass's merged, completes; `readOnlySite`: the site's layout memory read,
+    // never written, and the view laid out not kept in the cache either, which a server would take for
+    // its site's (the artwork command, ExportSpec decision 21)
     const held = opts.extraction ?? (opts.reuse ? cachedExtraction(dirs.cache, opts.reuse) : null);
     if (opts.reuse && !held)
         throw new Error("the graph on screen is no longer cached; it is laid out afresh at the next build");
@@ -72,7 +76,6 @@ export async function prepare(project, dirs, saved, log, opts = {}) {
         log(ex.cached ? `extraction ${ex.fingerprint} reused` : `extraction ${ex.fingerprint} done`);
     const usage = ex.graph.usage ?? null;
     const viewDir = join(dirs.cache, "view");
-    mkdirSync(viewDir, { recursive: true });
     const metaFile = join(viewDir, `${ex.fingerprint}-v${VIEW_VERSION}.meta.json.gz`);
     const edgeFile = join(viewDir, `${ex.fingerprint}-v${VIEW_VERSION}.edges.bin.gz`);
     const memory = opts.freshLayout ? null : loadMemory(dirs.site);
@@ -87,13 +90,17 @@ export async function prepare(project, dirs, saved, log, opts = {}) {
     const completing = memory !== null && opts.completes !== undefined && memory.fingerprint === opts.completes && memory.before !== undefined;
     const against = completing ? (memory.before ?? null) : (memory?.layouts ?? null);
     const view = await buildViewOffThread(project, ex, log, against);
-    saveMemory(dirs.site, ex.fingerprint, view.meta, opts.provisional ? against : undefined);
+    if (!opts.readOnlySite)
+        saveMemory(dirs.site, ex.fingerprint, view.meta, opts.provisional ? against : undefined);
     const metaGz = gzipSync(JSON.stringify(view.meta));
     const edgesGz = gzipSync(Buffer.from(view.edges.buffer, view.edges.byteOffset, view.edges.byteLength));
-    writeFileSync(metaFile, metaGz);
-    writeFileSync(edgeFile, edgesGz);
-    prune(viewDir, /\.meta\.json\.gz$/, 3);
-    prune(viewDir, /\.edges\.bin\.gz$/, 3);
+    if (!opts.readOnlySite) {
+        mkdirSync(viewDir, { recursive: true });
+        writeFileSync(metaFile, metaGz);
+        writeFileSync(edgeFile, edgesGz);
+        prune(viewDir, /\.meta\.json\.gz$/, 3);
+        prune(viewDir, /\.edges\.bin\.gz$/, 3);
+    }
     return { fingerprint: ex.fingerprint, cached: ex.cached, metaGz, edgesGz, usage };
 }
 function readdirRec(dir) {
@@ -118,7 +125,9 @@ export async function ensureBundle() {
     const dist = bundleDir();
     const out = join(dist, "app.js");
     let newest = 0;
-    for (const f of [...readdirRec(join(WEB, "src")), ...readdirRec(join(SRC, "shared"))])
+    // package.json too: the page is bundled with its version (UpdateSpec decision 8), which a page
+    // compares with its server's — a bundle of another version would have every new tab reload
+    for (const f of [...readdirRec(join(WEB, "src")), ...readdirRec(join(SRC, "shared")), join(REPO, "package.json")])
         newest = Math.max(newest, statSync(f).mtimeMs);
     const beside = ["layout.js", "edges.js", "pdfworker.js"].every((f) => existsSync(join(dist, f)));
     if (existsSync(out) && beside && statSync(out).mtimeMs >= newest)
@@ -152,6 +161,8 @@ export async function bundlePage(outdir, sourcemap = true) {
         // the owner reads in Safari: what Safari 16 lacks of the syntax (pdf.js's class static blocks; a
         // regular expression's lookbehind, read at run time instead) is lowered
         target: ["es2022", "safari16"],
+        // the version the page is of, which it compares with its server's (UpdateSpec decision 8)
+        define: { __VP_VERSION__: JSON.stringify(packageVersion()) },
         sourcemap,
         outdir,
         logLevel: "warning",

package/dist/server/poppler.js

@@ -10,6 +10,7 @@
 // input: the tools are run without a shell, on a path of the server's own, with a time limit, and at
 // most two at once.
 import { execFile } from "node:child_process";
+import { tracked } from "./children.js";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
@@ -31,12 +32,12 @@ async function run(cmd, args, ms) {
     running++;
     try {
         return await new Promise((ok, no) => {
-            execFile(cmd, args, { timeout: ms, maxBuffer: MAX_OUT, encoding: "buffer", windowsHide: true }, (err, out, errOut) => {
+            tracked(execFile(cmd, args, { timeout: ms, maxBuffer: MAX_OUT, encoding: "buffer", windowsHide: true }, (err, out, errOut) => {
                 if (err)
                     no(new Error(`${cmd} failed: ${(errOut?.toString("utf8").trim().split("\n").pop() ?? "") || err.message}`));
                 else
                     ok(out);
-            });
+            }));
         });
     }
     finally {

package/dist/server/readonlygate.js

@@ -6,13 +6,13 @@
 export function readOnlyAllows(method, path) {
     const read = method === "GET" || method === "HEAD";
     if (read) {
-        // the page and its files
-        if (path === "/" || path === "/index.html" || path === "/style.css" || /^\/(app|layout|edges|pdfworker)\.js(\.map)?$/.test(path) || path.startsWith("/pdfjs/") || path.startsWith("/fonts/"))
+        // the page and its files: its fonts, the tips' clips (GuideSpec decision 6)
+        if (path === "/" || path === "/index.html" || path === "/style.css" || /^\/(app|layout|edges|pdfworker)\.js(\.map)?$/.test(path) || path.startsWith("/pdfjs/") || path.startsWith("/fonts/") || path.startsWith("/tips/"))
             return true;
         // the graph, its sources and Lean's answers, the review, what happened, the views, the history,
         // the library, the printed document's state and files, who the reader is and the link they
-        // came by, and the event stream every change comes by
-        if (["/api/status", "/api/meta", "/api/edges", "/api/source", "/api/review", "/api/activity", "/api/identity", "/api/share"].includes(path))
+        // came by, VisualProof's version, and the event stream every change comes by
+        if (["/api/status", "/api/updates", "/api/meta", "/api/edges", "/api/git", "/api/source", "/api/review", "/api/activity", "/api/identity", "/api/share"].includes(path))
             return true;
         // a stream is opened by GET alone: a HEAD would take one of their places for nothing
         if (path === "/api/events")

package/dist/server/review.js

@@ -263,7 +263,10 @@ export class ReviewStore {
         this.refresh();
         const file = logFileName(name, false, person);
         const now = Object.hasOwn(this.data.people, person) ? this.data.people[person].name : null;
-        if (!this.files.has(file) || now === name.trim())
+        // one who has no log yet, but whom opinions were recorded for (ReviewSpec decision 8), is
+        // given one by the rename, so that those follow it
+        const spokenFor = Object.values(this.data.opinions).some((ops) => ops.some((o) => o.person === person && o.recordedBy));
+        if ((!this.files.has(file) && !spokenFor) || now === name.trim())
             return { change: null, unchanged: true };
         return this.write(file, () => nameEvent(person, name, this.nextTime()));
     }

package/dist/server/reviewapi.js

@@ -17,6 +17,7 @@
 // Every refusal is an answer: a status, and words that say what to do instead.
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { MAX_NAME, sameName, validName } from "../shared/collab.js";
 import { exactContext, judgedText } from "../shared/context.js";
 import { MAX_TEXT, STANDARD_AXIOMS, validPrefix } from "../shared/review.js";
 import { reviewSet } from "../shared/reviewqueue.js";
@@ -102,6 +103,9 @@ export class ReviewApi {
                     return answer(refuse(400, "The comment is longer than 10,000 characters.", "Say it shorter."));
                 if (b.verdict === "comment" && !comment)
                     return answer(refuse(400, "A comment needs text.", "Write it in the box, then Comment."));
+                const voice = this.voice(b.for, who);
+                if ("status" in voice)
+                    return answer(voice);
                 const v = this.graph();
                 if ("status" in v)
                     return answer(v);
@@ -109,7 +113,7 @@ export class ReviewApi {
                 if ("status" in x)
                     return answer(x);
                 // an agent's opinion is advice, whatever its level (AgentSpec decision 2)
-                return this.record({ op: "opinion", name: x.name, by, verdict: b.verdict, ...(comment ? { comment } : {}), ...(x.hash ? { hash: x.hash } : {}), ...(x.text !== undefined ? { text: x.text } : x.statement !== undefined ? { statement: x.statement } : {}), ...agent }, who);
+                return this.record({ op: "opinion", name: x.name, by, verdict: b.verdict, ...(comment ? { comment } : {}), ...(x.hash ? { hash: x.hash } : {}), ...(x.text !== undefined ? { text: x.text } : x.statement !== undefined ? { statement: x.statement } : {}), ...voice, ...agent }, who);
             }
             case "target": {
                 if (typeof b.on !== "boolean")
@@ -173,6 +177,36 @@ export class ReviewApi {
                 return answer(refuse(400, "op is opinion, target, trust or key.", "Send {op, …}."));
         }
     }
+    /** Whose an opinion is to be (ReviewSpec decision 8): the asker's own where `asked` is absent or
+     *  names them; else another person's, recorded for them — by their link's id where `asked` is an
+     *  invited person's name, a guest's as the logs write it — and never an agent's, nor by an agent. */
+    voice(asked, who) {
+        if (asked === undefined)
+            return {};
+        if (who.agent)
+            return refuse(403, "An agent records no opinion for anyone else.", "Leave out for: your opinion is your own, and advice.");
+        if (typeof asked !== "string" || !validName(asked.trim()))
+            return refuse(400, `for is the name of the person the opinion is recorded for: 1–${MAX_NAME} characters, no line breaks.`, "Send {op: \"opinion\", name, verdict, for: \"<their name>\"}.");
+        const name = asked.trim();
+        const held = this.world.invited?.(name);
+        // one's own name, or one's own link: one's own opinion
+        if (held ? held.id === who.person : sameName(name, who.name.trim()))
+            return {};
+        // the writers the logs name, people's and agents', in any case
+        const d = this.world.review.data;
+        const writers = [
+            ...Object.values(d.opinions).flatMap((ops) => ops.map((o) => ({ by: o.by, agent: !!o.agent, person: !!o.person }))),
+            ...Object.values(d.targets).map((t) => ({ by: t.by, agent: !!t.agent, person: !!t.person })),
+            ...Object.values(d.keys).flatMap((marks) => Object.values(marks).map((m) => ({ by: m.by, agent: !!m.agent, person: !!m.person }))),
+        ];
+        if (writers.some((w) => w.agent && sameName(w.by, name)))
+            return refuse(400, `${name} is an agent: nobody records an opinion for an agent.`, "Record it for a person, or as your own.");
+        if (held)
+            return { for: held.name, forPerson: held.id };
+        // a guest already in the logs, as they write their name: "bob" is Bob
+        const guest = writers.find((w) => !w.agent && !w.person && sameName(w.by, name));
+        return { for: guest?.by ?? name };
+    }
     /** Append a writer's event to their log; the answer carries the change, which the page applies
      *  at once, and the event as written. */
     record(op, who) {

package/dist/server/snapshot.js

@@ -4,11 +4,19 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
 import { WEB, WEBFONTS, bundleDir } from "./pipeline.js";
+import { gitSource } from "./history.js";
 import { lakeTextHash } from "./status.js";
 /** Text that sits inside a <script> element must not close it. */
 function scriptSafe(s) {
     return s.replace(/<\/script/gi, "<\\/script");
 }
+/** A snapshot's graph: the view's, with the project's git source and commit as the snapshot is
+ *  taken, since a snapshot has no server to ask (GET /api/git); as it was where the project is no
+ *  git repository. */
+export function withGit(root, meta, metaGz) {
+    const git = gitSource(root);
+    return git ? gzipSync(JSON.stringify({ ...meta, project: { ...meta.project, git } })) : metaGz;
+}
 export function writeSnapshot(project, prep, out, label, review, views) {
     const meta = JSON.parse(gunzipSync(prep.metaGz).toString("utf8"));
     // the sources a card can show: every project module's file, with the usage pass's contexts where
@@ -28,6 +36,7 @@ export function writeSnapshot(project, prep, out, label, review, views) {
         }
     }
     const b64 = (buf) => buf.toString("base64");
+    const metaGz = withGit(project.root, meta, prep.metaGz);
     // the artwork's fonts within the page, which has no server to ask for them
     const css = readFileSync(join(WEB, "style.css"), "utf8").replace(/url\("\/fonts\/([a-z0-9-]+\.woff2)"\)/g, (_, f) => `url("data:font/woff2;base64,${b64(readFileSync(join(WEBFONTS, f)))}")`);
     const js = readFileSync(join(bundleDir(), "app.js"), "utf8").replace(/\n\/\/# sourceMappingURL=.*$/m, "");
@@ -35,7 +44,7 @@ export function writeSnapshot(project, prep, out, label, review, views) {
     const html = readFileSync(join(WEB, "index.html"), "utf8")
         .replace(`<link rel="stylesheet" href="/style.css">`, () => `<style>\n${css}\n</style>`)
         .replace(`<script type="module" src="/app.js"></script>`, () => `<script id="vp-static" type="application/json">${scriptSafe(JSON.stringify(info))}</script>\n` +
-        `<script id="vp-meta" type="application/octet-stream">${b64(prep.metaGz)}</script>\n` +
+        `<script id="vp-meta" type="application/octet-stream">${b64(metaGz)}</script>\n` +
         `<script id="vp-edges" type="application/octet-stream">${b64(prep.edgesGz)}</script>\n` +
         `<script id="vp-sources" type="application/octet-stream">${b64(gzipSync(JSON.stringify(sources)))}</script>\n` +
         // the review as it stood: shown, not changed (ReviewSpec decision 7)

package/dist/server/sourcestore.js

@@ -24,6 +24,7 @@
 // read-only: the build's commit, the commits made on top of it, the working tree and the blobs kept
 // already. Nothing is ever written into the project or its `.git`.
 import { spawn, spawnSync } from "node:child_process";
+import { childEnv, tracked } from "./children.js";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -156,13 +157,13 @@ const DECLARES = /^\s*(?:@\[[^\]]*\]\s*)*(?:(?:private|protected|noncomputable|p
 // ------------------------------------------------------------------------------------------- git
 /** Git, read-only and taking no lock, run from the project's folder: its output, or null. */
 function gitSync(root, args) {
-    const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 10_000, maxBuffer: 256 << 20, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, stdio: ["ignore", "pipe", "ignore"] });
+    const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 10_000, maxBuffer: 256 << 20, env: childEnv({ GIT_OPTIONAL_LOCKS: "0" }), stdio: ["ignore", "pipe", "ignore"] });
     return r.status === 0 ? r.stdout : null;
 }
 /** The same, off the event loop, with `input` on its standard input: its output as bytes, or null. */
 function git(root, args, input) {
     return new Promise((ok) => {
-        const p = spawn("git", ["-C", root, ...args], { env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, stdio: ["pipe", "pipe", "ignore"] });
+        const p = tracked(spawn("git", ["-C", root, ...args], { env: childEnv({ GIT_OPTIONAL_LOCKS: "0" }), stdio: ["pipe", "pipe", "ignore"] }));
         const out = [];
         p.stdout.on("data", (b) => out.push(b));
         p.on("error", () => ok(null));

package/dist/server/status.js

@@ -10,6 +10,7 @@
 //   - the trace records the hash of the source it was built from. Lake rebuilds when that hash
 //     changes, not when the mtime does, so "stale" here compares the same hash (`lakeTextHash`).
 import { execFile } from "node:child_process";
+import { tracked } from "./children.js";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 const IMPORT_RE = /^\s*(?:public\s+|private\s+)?(?:meta\s+)?import\s+(?:all\s+)?([^\s-]+)/;
@@ -84,7 +85,7 @@ export function scanModules(p) {
 /** Modules a lean process is compiling right now, for this project's build directory. */
 export function compiling(p) {
     return new Promise((resolve) => {
-        execFile("ps", ["axo", "command"], { maxBuffer: 16 << 20 }, (err, stdout) => {
+        tracked(execFile("ps", ["axo", "command"], { maxBuffer: 16 << 20 }, (err, stdout) => {
             const out = new Set();
             if (err)
                 return resolve(out);
@@ -99,7 +100,7 @@ export function compiling(p) {
                     out.add(path.split("/").join("."));
             }
             resolve(out);
-        });
+        }));
     });
 }
 const M = 0xc6a4a7935bd1e995n;

package/dist/server/supervise.js

@@ -0,0 +1,219 @@
+// The supervisor (UpdateSpec decision 5): `visualproof serve` from an installed package runs the
+// server as a child of this small process, which stays while the server restarts into another
+// version. It runs the newest of the installed package and the patches of its minor downloaded
+// into the cache (server/updates.ts, codeToRun), passes signals on, and ends with the server's
+// status — except where the server asks to be started again (status 75, a restart into another
+// version) or where a version downloaded fails as it starts: that one is set aside, and the one
+// before it started again (decision 7).
+//
+// The child is told, by its environment, that it runs supervised (VISUALPROOF_SUPERVISED), where the
+// installed package is (VISUALPROOF_INSTALLED: the one it watches for an `npm install`), and what was
+// set aside before it started (VISUALPROOF_SET_ASIDE), which it records in the timeline. It says over
+// IPC when it listens (`{vp: "listening", version}`), so that a version which stops before then is
+// known to have failed, and when what ends it is not its code (`{vp: "environment"}`: the site is
+// busy, the port taken).
+import { spawn } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { codeToRun, Versions } from "./updates.js";
+/** the status a server ends with to be started again, in another version */
+export const RESTART_STATUS = 75;
+/** a version downloaded that ends within this long of starting is set aside */
+export const FAILS_WITHIN = 10 * 60_000;
+/** more starts than this in RESTART_WINDOW, and the supervisor gives up */
+const MAX_STARTS = 6;
+const RESTART_WINDOW = 10 * 60_000;
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const defaultRun = (main, argv, env) => spawn(process.execPath, [main, ...argv], { stdio: ["inherit", "inherit", "inherit", "ipc"], env });
+/** The status a process ended by `signal` is said to end with, as shells say it: 128 + its number. */
+export function signalStatus(signal) {
+    return 128 + (osConstants.signals[signal] ?? 0);
+}
+/** How a version's failure counts (UpdateSpec decision 7): a SIGKILL never (the kernel's when
+ *  memory runs out, an operator's kill -9); a SIGABRT — V8's when the heap reaches its limit — only
+ *  before the version served: a version that runs out of memory as it starts, where the one before
+ *  it did not, is the version's fault; one that runs out once it serves may be a reader's request.
+ *  Either way it is started again (a version killed at every start ends in the too-many-starts stop
+ *  below, which pauses it). */
+function resource(signal, listened) {
+    return signal === "SIGKILL" || (signal === "SIGABRT" && listened);
+}
+/** failures soon after it served are counted for a day after the last one */
+const STRIKES_FOR = 24 * 3600_000;
+/** Run the server until it ends for good; the status it ended with — 0 once a stop was asked,
+ *  whatever the server does meanwhile. A version from the cache is set aside (UpdateSpec decision 7)
+ *  where it fails before it serves (for every site: it is about the version), or twice soon after it
+ *  served (for this site: it may be about its project; a second site's sets it aside for all);
+ *  where the version started after one was set aside fails as soon, the fault was not the first
+ *  one's: it is taken back (what was recorded kept), this site's patches up to it are paused — it
+ *  runs the installed package until a newer patch is out — and the supervisor ends. So does it
+ *  after too many starts, pausing the patch it was starting. */
+export function supervise(o) {
+    const log = o.log ?? ((l) => console.error(`visualproof: ${l}`));
+    const run = o.run ?? defaultRun;
+    const now = o.now ?? Date.now;
+    const site = o.site ?? null;
+    const versions = new Versions(o.cacheRoot);
+    const starts = [];
+    const backoff = o.backoff ?? ((n) => Math.min(300_000, 5000 * 2 ** (n - 1)));
+    /** kills in a row that do not count (out of memory): each start after one waits longer, and is
+     *  not one of the starts that make the supervisor give up */
+    let kills = 0;
+    /** failures soon after it served, by version, and when the last one was */
+    const strikes = new Map();
+    /** versions set aside whose record could not be written (a full disk): set aside all the same */
+    const unrecorded = new Set();
+    let child = null;
+    let stopping = false;
+    /** the version set aside last, which the next child is told of */
+    let setAside = null;
+    const forward = (sig) => {
+        stopping = true;
+        child?.kill(sig);
+    };
+    for (const s of SIGNALS)
+        process.on(s, forward);
+    return new Promise((resolve) => {
+        let ended = false;
+        const done = (status) => {
+            if (ended)
+                return;
+            ended = true;
+            for (const s of SIGNALS)
+                process.off(s, forward);
+            // a stop was asked: whatever the server did meanwhile (a restart, a signal before its own
+            // handlers), the stop is what happened
+            resolve(stopping ? 0 : status);
+        };
+        const pause = (v, why) => {
+            if (!site)
+                return;
+            if (versions.pause(site, v, why))
+                log(`this site's patches up to ${v} are not taken until a newer one is out (${why}): the installed package runs`);
+            else
+                log(`this site's patches could not be paused (${versions.root} cannot be written): ${why}`);
+        };
+        const start = (uncounted = false) => {
+            if (stopping)
+                return done(0);
+            const t = now();
+            if (!uncounted)
+                starts.push(t);
+            while (starts.length && t - starts[0] > RESTART_WINDOW)
+                starts.shift();
+            let code = codeToRun(o.installedRoot, versions, { mode: o.mode, site, also: unrecorded });
+            // marked before it is started, so that no prune removes it meanwhile; chosen again where one
+            // did just before the mark
+            if (code.cached) {
+                versions.markRunning(code.version, process.pid);
+                if (!versions.ready().includes(code.version)) {
+                    versions.unmarkRunning(code.version, process.pid);
+                    code = codeToRun(o.installedRoot, versions, { mode: o.mode, site, also: unrecorded });
+                    if (code.cached)
+                        versions.markRunning(code.version, process.pid);
+                }
+            }
+            if (starts.length > MAX_STARTS) {
+                log(`the server was started ${starts.length} times in ten minutes: giving up`);
+                if (code.cached) {
+                    versions.unmarkRunning(code.version, process.pid);
+                    pause(code.version, `VisualProof ${code.version} was started ${starts.length} times in ten minutes`);
+                }
+                return done(1);
+            }
+            const env = { ...process.env, VISUALPROOF_SUPERVISED: "1", VISUALPROOF_INSTALLED: o.installedRoot };
+            // what it set aside without a record (a full disk): the server never restarts into it
+            if (unrecorded.size)
+                env.VISUALPROOF_UNRECORDED = JSON.stringify([...unrecorded]);
+            else
+                delete env.VISUALPROOF_UNRECORDED;
+            // the version set aside just before this one started: told to it (the timeline), and taken
+            // back if this one fails as soon
+            const after = setAside;
+            if (after)
+                env.VISUALPROOF_SET_ASIDE = JSON.stringify(after);
+            else
+                delete env.VISUALPROOF_SET_ASIDE;
+            setAside = null;
+            let listened = null;
+            // what ended it is not its code (the site busy, the port taken): never set aside for that
+            let environment = false;
+            const c = run(code.main, o.argv, env);
+            child = c;
+            // a version of the cache's, which no other server removes while this one runs it: marked as
+            // it starts, by its process
+            const pid = c.pid;
+            if (code.cached) {
+                if (pid)
+                    versions.markRunning(code.version, pid);
+                versions.unmarkRunning(code.version, process.pid);
+            }
+            c.on("message", (m) => {
+                const said = m && typeof m === "object" ? m.vp : null;
+                if (said === "listening") {
+                    listened = now();
+                    kills = 0;
+                }
+                else if (said === "environment")
+                    environment = true;
+            });
+            c.once("error", (e) => {
+                log(`the server could not be started: ${e.message}`);
+                done(1);
+            });
+            c.once("exit", (status, signal) => {
+                child = null;
+                if (code.cached && pid)
+                    versions.unmarkRunning(code.version, pid);
+                const ends = status ?? (signal ? signalStatus(signal) : 1);
+                if (stopping)
+                    return done(0);
+                if (status === RESTART_STATUS)
+                    return start();
+                if (status === 0 || environment)
+                    return done(ends);
+                const how = signal ? `was ended by ${signal}` : `exited with status ${status}`;
+                const soon = listened === null || now() - listened < FAILS_WITHIN;
+                const counts = !resource(signal, listened !== null);
+                if (after && soon && counts) {
+                    // the version before it fails as soon: the fault was not the one set aside's
+                    versions.unmarkBad(after.version);
+                    unrecorded.delete(after.version);
+                    log(`VisualProof ${code.version} ${how} as well: ${after.version} is taken back from those set aside (the fault is not its); stopping`);
+                    pause(after.version, `${after.version}, and the version before it, failed as they started`);
+                    return done(ends);
+                }
+                if (!code.cached || !soon)
+                    return done(ends);
+                const aside = (why, where) => {
+                    if (!versions.markBad(code.version, why, where)) {
+                        unrecorded.add(code.version);
+                        log(`VisualProof ${code.version} ${why}: set aside, though ${versions.root} could not record it (a full disk?)`);
+                    }
+                    else
+                        log(`VisualProof ${code.version} ${why}: set aside${where ? " for this site" : ""}; starting the version before it`);
+                    setAside = { version: code.version, why };
+                    start();
+                };
+                if (!counts) {
+                    kills++;
+                    const wait = backoff(kills);
+                    log(`VisualProof ${code.version} ${how}${listened === null ? " as it started" : " soon after it started"} (out of memory?): started again${wait ? ` in ${Math.round(wait / 1000)} s` : ""}`);
+                    if (!wait)
+                        return start(true);
+                    setTimeout(() => start(true), wait);
+                    return;
+                }
+                if (listened === null)
+                    return aside(`${how} before it served`, null);
+                const was = strikes.get(code.version);
+                const n = was && now() - was.at < STRIKES_FOR ? was.n + 1 : 1;
+                strikes.set(code.version, { n, at: now() });
+                if (n >= 2)
+                    return aside(`${how} twice soon after it started`, site ?? "");
+                log(`VisualProof ${code.version} ${how} soon after it started: started again`);
+                start();
+            });
+        };
+        start();
+    });
+}