visualproof 0.3.0 → 0.4.1

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);

package/dist/server/export.js

@@ -19,6 +19,7 @@
 // with it in the cache and in the sources' zip; their names say what they are drawn from, so the
 // .tex names them too.
 import { spawn, spawnSync } from "node:child_process";
+import { childEnv, DETACH, end, grouped } from "./children.js";
 import { createHash } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
@@ -58,6 +59,11 @@ export class Exporter {
         this.maxCached = o.maxCached ?? 20;
         this.concurrent = o.concurrent ?? 2;
     }
+    /** Whether a document is being typeset, or waits its turn: no moment to restart in (UpdateSpec
+     *  decision 6). */
+    get busy() {
+        return this.running > 0 || this.queue.length > 0;
+    }
     /** Whether XeLaTeX can be run here: asked once. */
     available() {
         if (this.found === null) {
@@ -260,16 +266,17 @@ export class Exporter {
         return new Promise((ok) => {
             if (timeoutMs <= 0)
                 return ok("timeout");
-            const p = spawn(this.xelatex, ["-no-shell-escape", "-halt-on-error", "-interaction=nonstopmode", "doc.tex"], {
+            const p = grouped(spawn(this.xelatex, ["-no-shell-escape", "-halt-on-error", "-interaction=nonstopmode", "doc.tex"], {
                 cwd,
                 // TeX's paranoid file access; and a log whose lines are not wrapped, so that it reads back
-                env: { ...process.env, openin_any: "p", openout_any: "p", shell_escape: "f", max_print_line: "10000" },
+                env: childEnv({ openin_any: "p", openout_any: "p", shell_escape: "f", max_print_line: "10000" }),
                 stdio: ["ignore", "ignore", "ignore"],
-            });
+                detached: DETACH,
+            }));
             let killed = false;
             const timer = setTimeout(() => {
                 killed = true;
-                p.kill("SIGKILL");
+                end(p, "SIGKILL");
             }, timeoutMs);
             p.on("error", () => {
                 clearTimeout(timer);

package/dist/server/extract.js

@@ -1,6 +1,7 @@
 // Run the Lean extractor against a project, or reuse its last result when nothing it reads has
 // changed.
 import { spawn } from "node:child_process";
+import { childEnv, DETACH, grouped } from "./children.js";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
@@ -70,7 +71,7 @@ export function leanProgram(prog, toolchain, leanRoot, log) {
         writeFileSync(join(work, "lean-toolchain"), toolchain + "\n");
         writeFileSync(join(work, "lakefile.toml"), `name = "${prog.exe.replace(/-/g, "")}"\n\n[[lean_exe]]\nname = "${prog.exe}"\nroot = "${prog.root}"\nsupportInterpreter = true\n`);
         log(`building ${prog.exe} for ${toolchain}…`);
-        const child = spawn("lake", ["build", prog.exe], { cwd: work, stdio: ["ignore", "pipe", "pipe"] });
+        const child = grouped(spawn("lake", ["build", prog.exe], { cwd: work, stdio: ["ignore", "pipe", "pipe"], detached: DETACH, env: childEnv() }));
         let tail = "";
         child.stdout.on("data", (b) => (tail = (tail + b).slice(-2000)));
         child.stderr.on("data", (b) => (tail = (tail + b).slice(-2000)));
@@ -111,7 +112,7 @@ function runExtractor(p, out, opts, log) {
         const args = opts.bin
             ? ["env", opts.bin, out, p.libDir, ...p.roots, ...tail_]
             : ["env", "lean", "--run", EXTRACTOR, out, p.libDir, ...p.roots, ...tail_];
-        const child = spawn("lake", args, { cwd: p.root, stdio: ["ignore", "pipe", "pipe"] });
+        const child = grouped(spawn("lake", args, { cwd: p.root, stdio: ["ignore", "pipe", "pipe"], detached: DETACH, env: childEnv() }));
         let tail = "";
         const onData = (buf) => {
             const text = buf.toString();

package/dist/server/figures.js

@@ -8,6 +8,7 @@
 // server lacks, an image no tool here can turn into a PNG — prints as a reference instead, and the
 // export's notes say so.
 import { spawn, spawnSync } from "node:child_process";
+import { childEnv, DETACH, end, grouped } from "./children.js";
 import { closeSync, mkdtempSync, openSync, readFileSync, readSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -112,8 +113,8 @@ async function toPng(path, type) {
     const out = join(dir, "out.png");
     try {
         await new Promise((ok, no) => {
-            const p = spawn(t, ["-limit", "memory", "256MiB", "-limit", "disk", "1GiB", `${type}:${path}[0]`, "-depth", "8", `png:${out}`], { stdio: ["ignore", "ignore", "ignore"] });
-            const timer = setTimeout(() => p.kill("SIGKILL"), CONVERT_MS);
+            const p = grouped(spawn(t, ["-limit", "memory", "256MiB", "-limit", "disk", "1GiB", `${type}:${path}[0]`, "-depth", "8", `png:${out}`], { stdio: ["ignore", "ignore", "ignore"], detached: DETACH, env: childEnv() }));
+            const timer = setTimeout(() => end(p, "SIGKILL"), CONVERT_MS);
             p.on("error", (e) => {
                 clearTimeout(timer);
                 no(e);