visualproof 0.2.0 → 0.4.0

package/dist/server/main.js

@@ -2,12 +2,15 @@
 // visualproof serve <path>   — read a built Lean project and serve its declaration graph
 // visualproof export <path>  — the same page, frozen into one HTML file
 import { historyAnswer } from "./historyapi.js";
+import { gitSource } from "./history.js";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
-import { extname, join, resolve } from "node:path";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
 import { gunzipSync, gzipSync } from "node:zlib";
 import { WEB, WEBFONTS, bundleDir, bundleDirIn, ensureBundle, prepare, useBundleDir } from "./pipeline.js";
+import { makeArtwork, pngOf, projectView } from "./artcmd.js";
 import { SiteBusy, cacheHome, dataHome, lockSite, openSite, projectDirs } from "./dirs.js";
 import { ProjectError, openProject, targetsInWords } from "./project.js";
 import { Live } from "./live.js";
@@ -15,7 +18,7 @@ import { ReviewStore } from "./review.js";
 import { isDeclName, LeanHover } from "./hover.js";
 import { Identities, layoutAuthor } from "./identity.js";
 import { LAYOUT_VERSION } from "../shared/graph.js";
-import { MAX_MEMORY_BYTES, Views } from "./views.js";
+import { MAX_MEMORY_BYTES, readProjectView, Views } from "./views.js";
 import { cleanView, defaultAgentName, validSession, withoutArtwork } from "../shared/collab.js";
 import { writeSnapshot } from "./snapshot.js";
 import { lakeTextHash } from "./status.js";
@@ -36,6 +39,12 @@ import { UPLOAD_PATH } from "./agentlibrary.js";
 import { DEFAULT_LIBRARY_LIMIT, validSha } from "../shared/library.js";
 import { doctor, packageVersion, printReport } from "./doctor.js";
 import { READONLY_PATH } from "./readonly.js";
+import { sendMedia, TIP_PATH, TIPS_DIR, tipClips, tourData, tourVtt } from "./media.js";
+import { withoutReasons } from "../shared/timeline.js";
+import { FROM_PACKAGE, PACKAGE_ROOT, UPDATE_MODES, Updates } from "./updates.js";
+import { RESTART_STATUS, supervise } from "./supervise.js";
+import { stopChildren } from "./children.js";
+import { filmStatus, serveFilm, useFilm } from "./film.js";
 import { finalAnswer, readOnlyAllows, ReadOnlyBounds } from "./readonlygate.js";
 /** The usage, to stderr with status 2 for a command line it cannot read; asked for (`--help`),
  *  to stdout with status 0. */
@@ -44,10 +53,12 @@ function usage(code = 2) {
                                          [--site dir] [--cache dir] [--graph saved.json]
                                          [--identity-header X-Forwarded-User] [--editor URL-template]
                                          [--agents read|advise|full] [--access-key-file file] [--public] [--jobs ${DEFAULT_JOBS}]
-                                         [--public-url https://host] [--library-limit GB]
+                                         [--public-url https://host] [--library-limit GB] [--updates auto|notify|off]
        visualproof purge-file <lean-project> <sha256> [--site dir] [--cache dir]
        visualproof export <lean-project> -o page.html [--label text] [--root Name]... [--graph saved.json]
                                          [--jobs ${DEFAULT_JOBS}] [--site dir] [--cache dir]
+       visualproof artwork <lean-project> --recipe recipe.json [-o name] [--png] [--svg] [--root Name]...
+                                         [--site dir] [--cache dir] [--jobs ${DEFAULT_JOBS}] [--screen 1920x1200] [--graph saved.json]
        visualproof doctor [<lean-project>] [--root Name]... [--site dir] [--cache dir]
        visualproof --version
 
@@ -65,13 +76,27 @@ function usage(code = 2) {
   --cache  the root of the caches, which a rebuild makes again: the project's (extractions, the
            usage pass's results, prepared views, typeset documents, Lean's language server's
            folder) in projects/<project>-<hash>/, the Lean programs compiled per toolchain in
-           lean/, the page's bundle in web/. Default: ${cacheHome()}
+           lean/, the page's bundle in web/, VisualProof's own releases in updates.json and the
+           patches downloaded in versions/ (code the servers run: keep the root yours alone),
+           and the tips' tour film in media/.
+           Default: ${cacheHome()}
            (XDG_DATA_HOME and XDG_CACHE_HOME move both homes, on any platform)
 
   --graph  use a saved extraction (a projects/*/extract/*.json of the cache) instead of reading
            the build; the project path still supplies the sources
   export   writes one self-contained HTML file: the page, its data and the sources, frozen
 
+  artwork  makes the picture an artwork recipe says (the agents' API's, docs/agent-api/export.md:
+           the size, the look, names by a rule, the targets, the selection), as the page's
+           artwork mode makes it, without a browser: an SVG and a PNG (--png or --svg for one),
+           named by -o (a name, or a path without its extension), else the recipe's title, else
+           the project. With --site, the board as that site keeps it (its layout, pins and folds)
+           and its review's targets; without, the board as a new site would lay it out, and the
+           targets the recipe names. --screen: the screen the board is drawn on, as a reader's
+           (default 1920x1200, at least 640x480): how large names are in the picture. It reads
+           the site, never writes it; it writes the files and the cache's extraction. Anything
+           that fails ends it with status 1. Notes are not drawn yet.
+
   --identity-header  behind a proxy that authenticates (Tailscale, oauth2-proxy, …): take each
            reader's name from this header instead of the name the page gives. Only use it when
            the proxy is the only way to reach the server: the header is believed as it comes.
@@ -111,6 +136,16 @@ function usage(code = 2) {
   --public-url  the address people reach this server at, when it is not the one their browser
            sends (a proxy in front): the prompt Share makes for an agent tells it this address.
 
+  --updates  what the server does with VisualProof's own releases, asked of the npm registry
+           (through npm) at start and once a day: auto (the default) — a patch of the version it
+           runs (0.4.x) is downloaded into the cache and taken at a quiet moment, nobody on a page,
+           open pages reloading where they were; a newer version (0.5.0) is told of, in the log
+           and the help, with the command that installs it, after which the server restarts into
+           it by itself; notify — told of, never downloaded; off — never asked (and no
+           supervisor process), and the tips' tour film never fetched: the server reaches the
+           network for nothing of its own. VISUALPROOF_UPDATES says the same. From a checkout,
+           never asked.
+
   --library-limit  the most the project's library of papers and images may take, in GB (default
            ${DEFAULT_LIBRARY_LIMIT / 1024 ** 3}); its files are kept in the site directory, by their hash.
 
@@ -131,9 +166,14 @@ function parseArgs(argv) {
         console.log(packageVersion());
         process.exit(0);
     }
-    if (cmd !== "serve" && cmd !== "export" && cmd !== "purge-file" && cmd !== "doctor")
+    if (cmd !== "serve" && cmd !== "export" && cmd !== "purge-file" && cmd !== "doctor" && cmd !== "artwork")
         usage();
-    const o = { cmd, path: "", roots: [], port: 4173, host: "127.0.0.1", site: null, cache: null, graph: null, out: null, label: "VisualProof", identityHeader: null, editor: null, agents: "full", accessKeyFile: null, jobs: DEFAULT_JOBS, publicUrl: null, libraryLimit: DEFAULT_LIBRARY_LIMIT, sha: null, publicRead: false };
+    const fromEnv = process.env.VISUALPROOF_UPDATES;
+    if (cmd === "serve" && fromEnv !== undefined && !UPDATE_MODES.includes(fromEnv)) {
+        console.error(`visualproof: VISUALPROOF_UPDATES=${fromEnv}: say auto, notify or off`);
+        process.exit(2);
+    }
+    const o = { cmd, path: "", roots: [], port: 4173, host: "127.0.0.1", site: null, cache: null, graph: null, out: null, label: "VisualProof", identityHeader: null, editor: null, agents: "full", accessKeyFile: null, jobs: DEFAULT_JOBS, publicUrl: null, libraryLimit: DEFAULT_LIBRARY_LIMIT, sha: null, publicRead: false, recipe: null, png: false, svg: false, screen: { w: 1920, h: 1200 }, updates: UPDATE_MODES.includes(fromEnv) ? fromEnv : "auto" };
     for (let i = 0; i < rest.length; i++) {
         const a = rest[i];
         const val = () => rest[++i] ?? usage();
@@ -161,6 +201,18 @@ function parseArgs(argv) {
             o.accessKeyFile = resolve(val());
         else if (a === "--public")
             o.publicRead = true;
+        else if (a === "--recipe" && cmd === "artwork")
+            o.recipe = resolve(val());
+        else if (a === "--png" && cmd === "artwork")
+            o.png = true;
+        else if (a === "--svg" && cmd === "artwork")
+            o.svg = true;
+        else if (a === "--screen" && cmd === "artwork") {
+            const m = /^(\d+)x(\d+)$/.exec(val());
+            if (!m || +m[1] < 640 || +m[2] < 480 || +m[1] > 10000 || +m[2] > 10000)
+                usage();
+            o.screen = { w: +m[1], h: +m[2] };
+        }
         else if (a === "--public-url") {
             const u = val();
             if (!/^https?:\/\/[^\s/?#]+\/?$/.test(u)) {
@@ -175,6 +227,12 @@ function parseArgs(argv) {
                 usage();
             o.jobs = n;
         }
+        else if (a === "--updates" && cmd === "serve") {
+            const mode = val();
+            if (!UPDATE_MODES.includes(mode))
+                usage();
+            o.updates = mode;
+        }
         else if (a === "--agents") {
             const level = val();
             if (!AGENT_LEVELS.includes(level))
@@ -196,7 +254,7 @@ function parseArgs(argv) {
         else
             usage();
     }
-    if ((!o.path && cmd !== "doctor") || (cmd === "export" && !o.out))
+    if ((!o.path && cmd !== "doctor") || (cmd === "export" && !o.out) || (cmd === "artwork" && !o.recipe))
         usage();
     // read-only for whoever comes, beside those the key or a link lets in: without a key, everyone is in
     // already; behind a sign-in, there is nobody else
@@ -221,6 +279,11 @@ export class App {
     live;
     hover;
     ids;
+    /** how long a read of the project's git (GET /api/git) is kept, whoever asks: git is run at most
+     *  once in that time, so what readers cost the server is bounded (CollabSpec decision 11); 0 in
+     *  the tests */
+    gitFreshMs = 3000;
+    gitRead = null;
     /** the agents' API (server/agent.ts), and what agents may change */
     agents;
     /** who may come in at all (server/access.ts); null: anyone who reaches the port */
@@ -237,6 +300,9 @@ export class App {
     readOnlyOf = new WeakMap();
     /** what read-only readers may cost the server: Lean's answers, their documents */
     bounds;
+    /** VisualProof's own releases as this server follows them (server/updates.ts); null: the
+     *  version alone is told (a test's server) */
+    updates = null;
     constructor(live, hover, ids, agents, access, exporter = null, publicUrl = null, publicRead = false) {
         this.live = live;
         this.hover = hover;
@@ -253,6 +319,11 @@ export class App {
         this.publicRead = publicRead && access !== null;
         this.bounds = new ReadOnlyBounds((id) => this.exporter?.job(id)?.state === "running");
     }
+    /** Whether a request is told all of the server's own releases (UpdateSpec decision 11): someone
+     *  let in fully; not a read-only reader, nor an agent. */
+    toldAll(req) {
+        return this.readOnlyOf.get(req) === undefined && this.ids.kind(req) !== "agent";
+    }
     /** The exported document (ExportSpec decisions 5–16): POST /api/export starts typesetting the
      *  document of a view, `{view, settings, version?}` (a build the Time Machine shows the view at;
      *  left out, the view's own), and answers with its job at once; the page asks how the
@@ -825,6 +896,23 @@ export class App {
             // the fonts an artwork is drawn in (ExportSpec decision 19)
             if (FONT_PATH.test(path))
                 return sendFile(req, res, join(WEBFONTS, path.slice("/fonts/".length)));
+            // the tips' clips and their key frames (GuideSpec decision 6), and which there are
+            if (path === "/tips/index.json")
+                return sendJson(res, { clips: tipClips() });
+            // the tour film, fetched by this server on its first play and kept checked in the cache
+            // (server/film.ts, UpdateSpec decision 14): else 503 while it comes, or 404, and the page shows
+            // its stills and captions; and its captions as WebVTT, for assistive technology
+            if (path === "/tips/tour.mp4" && !refused.has(res))
+                return void serveFilm(req, res, sendMedia);
+            if (path === "/tips/tour.en.vtt") {
+                const vtt = tourVtt(tourData());
+                if (vtt === null)
+                    return sendJson(res, { error: "no captions" }, 404);
+                res.writeHead(200, { "content-type": "text/vtt; charset=utf-8", "cache-control": "no-cache" });
+                return void res.end(vtt);
+            }
+            if (TIP_PATH.test(path) && !refused.has(res))
+                return sendMedia(req, res, join(TIPS_DIR, path.slice("/tips/".length)));
             // the page, and its workers: the one that lays out the Time Machine's past graphs
             // (web/src/layoutworker.ts), the one that chooses the overview's edges (web/src/edgeworker.ts),
             // and pdf.js's, which reads the library's PDFs for the reference window (AttachmentSpec decision 11)
@@ -833,8 +921,19 @@ export class App {
             if (path.startsWith("/pdfjs/"))
                 return pdfjsAsset(res, path);
             // with Lean's language server as it is (server/hover.ts): what is open, what crashed
-            if (path === "/api/status")
-                return sendJson(res, { ...live.status(), lean: this.hover.state() });
+            // a read-only reader is told how the server is, not its log nor where its review is kept
+            if (path === "/api/status") {
+                const st = { ...live.status(), lean: this.hover.state() };
+                if (this.readOnlyOf.get(req) !== undefined) {
+                    delete st.log;
+                    st.review = { ...st.review, folder: undefined };
+                }
+                return sendJson(res, st);
+            }
+            // VisualProof's own version, and what of its releases those let in fully are told (UpdateSpec
+            // decision 11): a read-only reader and an agent are told the version alone
+            if (path === "/api/updates")
+                return sendJson(res, this.updates?.status(this.toldAll(req)) ?? { running: packageVersion() });
             // the link that lets someone in, for a page that shares where it is (web/src/share.ts); a
             // request gets here only once it is in
             // a read-only reader shares the link they came by, or the address alone (--public)
@@ -954,12 +1053,14 @@ export class App {
             }
             if (path === "/api/events") {
                 const session = url.searchParams.get("session");
-                return live.subscribe(res, validSession(session) ? session : null, this.ids.person(req)?.id ?? null, reader ?? null);
+                return live.subscribe(res, validSession(session) ? session : null, this.ids.person(req)?.id ?? null, reader ?? null, this.toldAll(req));
             }
             // what happened (CollabSpec decision 5): what the server stored; the review's own history the
             // page reads from the review
-            if (path === "/api/activity")
-                return sendJson(res, { events: live.timeline.events.slice(-2000) });
+            if (path === "/api/activity") {
+                const events = live.timeline.events.slice(-2000);
+                return sendJson(res, { events: this.toldAll(req) ? events : events.map(withoutReasons) });
+            }
             // a layout batch an agent made, undone (AgentSpec decision 4): from a page's Activity, by anyone;
             // by a private reader, without their name (CollabSpec decision 8)
             if (path === "/api/layout/undo" && req.method === "POST") {
@@ -976,14 +1077,23 @@ export class App {
                 const a = this.agents.undo(me, agent, r.body?.id);
                 return sendJson(res, a.body, a.status);
             }
+            // the project's git source and commit as git says them now, not as the build was read (an
+            // artwork's foot, ExportSpec decision 19; the owner's decision of 2026-10-15)
+            if (path === "/api/git") {
+                if (!this.gitRead || Date.now() - this.gitRead.at >= this.gitFreshMs)
+                    this.gitRead = { git: gitSource(live.project.root), at: Date.now() };
+                return sendJson(res, { git: this.gitRead.git });
+            }
             if (path === "/api/meta" || path === "/api/edges") {
                 const g = live.graph;
                 if (!g)
                     return sendJson(res, { error: "not ready" }, 503);
                 // a page asks for the version it was told about; an older one is gone
                 const want = url.searchParams.get("v");
-                if (want && Number(want) !== g.version)
-                    return sendJson(res, { error: "superseded", version: g.version }, 409);
+                // of this server's: one restarted since counts its versions again (UpdateSpec decision 8)
+                const of = url.searchParams.get("i");
+                if ((want && Number(want) !== g.version) || (of && of !== live.instance))
+                    return sendJson(res, { error: "superseded", version: g.version, instance: live.instance }, 409);
                 // a page asks for the edges packed (shared/edgecodec.ts; `pack=2` with the grammar site, a
                 // page from before it `pack=1`, which takes grammar for a proof); an agent gets them as they
                 // are
@@ -1287,15 +1397,30 @@ function packedGz(edgesGz, format) {
     }
     return p;
 }
+/** What a stop signal does to a server: end it at once, until it can stop gracefully (serve). */
+let stopNow = () => process.exit(0);
 async function main() {
     const o = parseArgs(process.argv.slice(2));
+    // an installed package's server runs under the supervisor, which stays while it restarts into
+    // another version (UpdateSpec decision 5); `--updates off`, and a checkout, run it as they are
+    if (o.cmd === "serve" && FROM_PACKAGE && o.updates !== "off" && process.env.VISUALPROOF_SUPERVISED !== "1") {
+        const site = projectDirs(resolve(o.path), o.site, o.cache).site;
+        process.exit(await supervise({ installedRoot: PACKAGE_ROOT, cacheRoot: o.cache ? resolve(o.cache) : cacheHome(), argv: process.argv.slice(2), site, mode: o.updates }));
+    }
+    // a stop asked before the server can stop gracefully (it reads the project, takes the site) ends
+    // it at once, with status 0; once it can, the graceful stop does (`stopNow`, below)
+    if (o.cmd === "serve")
+        for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+            process.on(sig, () => stopNow());
     if (o.cmd === "doctor") {
         const report = doctor({ path: o.path || null, roots: o.roots, site: o.site, cache: o.cache });
         console.log(printReport(report, o.path || null));
         process.exit(report.checks.some((c) => c.level === "fail") ? 1 : 0);
     }
-    // a live server outlives any one failed task: log it and keep serving
-    process.on("unhandledRejection", (e) => console.error("unhandled:", e instanceof Error ? e.message : e));
+    // a live server outlives any one failed task: log it and keep serving (a picture is no server:
+    // whatever fails ends it, with status 1)
+    if (o.cmd !== "artwork")
+        process.on("unhandledRejection", (e) => console.error("unhandled:", e instanceof Error ? e.message : e));
     let project;
     try {
         project = openProject(o.path, o.roots, o.graph === null);
@@ -1303,10 +1428,13 @@ async function main() {
     catch (e) {
         if (e instanceof ProjectError) {
             console.error(`visualproof: ${e.message}`);
-            process.exit(1);
+            return endNotTheCode(1);
         }
         throw e;
     }
+    // a picture: the site read, never made, locked or written (ExportSpec decision 21)
+    if (o.cmd === "artwork")
+        return artworkCommand(project, o);
     const dirs = projectDirs(project.root, o.site, o.cache);
     openSite(dirs.site);
     mkdirSync(dirs.cache, { recursive: true });
@@ -1320,7 +1448,7 @@ async function main() {
             if (!(e instanceof SiteBusy))
                 throw e;
             console.error(`visualproof: ${e.message}`);
-            process.exit(1);
+            return endNotTheCode(1);
         }
     }
     useBundleDir(bundleDirIn(o.cache ? resolve(o.cache) : cacheHome()));
@@ -1373,7 +1501,7 @@ async function main() {
     }
     catch (e) {
         console.error(`visualproof: --access-key-file: ${e instanceof Error ? e.message : String(e)}`);
-        process.exit(2);
+        return endNotTheCode(2);
     }
     process.on("exit", () => {
         hover.stop();
@@ -1384,10 +1512,77 @@ async function main() {
         live.invites.close();
         live.readOnly.close();
     });
-    for (const sig of ["SIGINT", "SIGTERM"])
-        process.on(sig, () => process.exit(0));
-    const app = new App(live, hover, ids, new AgentApi(live, hover, o.agents), key ? new Access(key.key) : null, new Exporter(dirs.cache), o.publicUrl, o.publicRead);
+    const exporter = new Exporter(dirs.cache);
+    const app = new App(live, hover, ids, new AgentApi(live, hover, o.agents), key ? new Access(key.key) : null, exporter, o.publicUrl, o.publicRead);
     const server = createServer((req, res) => app.handle(req, res));
+    const version = packageVersion();
+    // run by the supervisor, which starts it again in another version (UpdateSpec decision 5)
+    const supervised = typeof process.send === "function" && process.env.VISUALPROOF_SUPERVISED === "1";
+    /** Stop (UpdateSpec decision 9): no new requests, the pages told why and their streams ended, the
+     *  programs the server runs stopped, then the process ends: status 0, or RESTART_STATUS for the
+     *  supervisor to start it again in another version. A second signal meanwhile changes nothing;
+     *  whatever still waits, it ends within 5 s. */
+    let stopping = false;
+    /** the status the process ends with: a stop asked during a restart makes it a stop (0), so that
+     *  the supervisor does not start it again */
+    let exitStatus = 0;
+    const stop = (status, why) => {
+        if (stopping) {
+            if ("stopped" in why)
+                exitStatus = 0;
+            return;
+        }
+        stopping = true;
+        exitStatus = status;
+        updates.stop();
+        server.close();
+        live.end(why);
+        hover.stop();
+        live.usage.cancel();
+        server.closeIdleConnections();
+        setTimeout(() => process.exit(exitStatus), 5000);
+        void stopChildren(2000).then(() => {
+            server.closeAllConnections();
+            process.exit(exitStatus);
+        });
+    };
+    const cacheRoot = o.cache ? resolve(o.cache) : cacheHome();
+    const updates = new Updates({
+        mode: o.updates,
+        cacheRoot,
+        canRestart: supervised && FROM_PACKAGE,
+        check: FROM_PACKAGE,
+        checkout: !FROM_PACKAGE,
+        // nobody on a page, nothing running that a restart would cut short (UpdateSpec decision 6)
+        quiet: () => live.pages === 0 && !live.busy && !exporter.busy,
+        restart: (to) => {
+            process.send?.({ vp: "restart", to });
+            stop(RESTART_STATUS, { update: { from: version, to } });
+        },
+        // the server's console alone: the log pages read (GET /api/status) is no place for paths and
+        // commands of this machine
+        log: (l) => console.log(l),
+        changed: () => live.updatesChanged(),
+        running: version,
+        // the supervisor's word, believed only from it
+        installedRoot: (supervised && process.env.VISUALPROOF_INSTALLED) || PACKAGE_ROOT,
+        site: dirs.site,
+        // what the supervisor set aside without a record of it (a full disk), believed only from it
+        also: new Set(supervised ? unrecordedOf(process.env.VISUALPROOF_UNRECORDED) : []),
+        film: () => filmStatus(),
+    });
+    // the tips' tour film, fetched on its first play (UpdateSpec decision 14; never under --updates off)
+    useFilm({ cacheRoot, mode: o.updates, log: (l) => console.log(l) });
+    live.updateStatus = (full) => updates.status(full);
+    app.updates = updates;
+    stopNow = () => stop(0, { stopped: true });
+    // the supervisor went: this server goes with it rather than serve on alone
+    if (supervised)
+        process.on("disconnect", () => stop(0, { stopped: true }));
+    server.on("error", (e) => {
+        console.error(`visualproof: ${e.code === "EADDRINUSE" ? `${o.host}:${o.port} is in use already: give --port another` : e.message}`);
+        return endNotTheCode(1);
+    });
     server.listen(o.port, o.host, () => {
         console.log(`VisualProof — ${project.name} (${targetsInWords(project)})`);
         console.log(`  http://${o.host}:${o.port}/`);
@@ -1398,9 +1593,143 @@ async function main() {
         console.log(`  agents: ${o.agents} — their API is http://${o.host}:${o.port}/api/agent`);
         console.log(`  usage pass: ${o.graph ? "none for a saved graph" : o.jobs > 0 ? `${o.jobs} module(s) at a time` : "off (--jobs 0)"}`);
         console.log(`  access: ${key ? `by its link only, /k/<the key in ${o.accessKeyFile}>${key.made ? " (a new key was made there)" : ""}${o.publicRead ? "; anyone else read-only (--public)" : ""}` : "anyone who reaches the port"}`);
+        console.log(`  version: ${version}; updates ${updatesInWords(o.updates, version, supervised)}`);
+        recordVersion(live, version, supervised);
+        process.send?.({ vp: "listening", version });
+        updates.start();
     });
     live.start();
 }
+/** What the server does with its releases, for its first lines (UpdateSpec decisions 2–4, 13). */
+function updatesInWords(mode, version, supervised) {
+    if (mode === "off")
+        return "off (--updates off): the registry is never asked";
+    if (!FROM_PACKAGE)
+        return "none from a checkout";
+    const minor = version.split(".").slice(0, 2).join(".");
+    if (mode === "notify")
+        return `notify — newer versions told of, never downloaded${supervised ? "; one installed meanwhile is restarted into" : ""}`;
+    return supervised ? `auto — a patch of ${minor} taken by itself at a quiet moment; a newer version told of` : "auto, but without the supervisor: newer versions told of";
+}
+/** The versions the supervisor says it set aside without a record (VISUALPROOF_UNRECORDED). */
+function unrecordedOf(text) {
+    try {
+        const v = JSON.parse(text ?? "[]");
+        return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** The version that serves the site, recorded in the timeline where it is another than the last one
+ *  recorded (UpdateSpec decision 10), with what the supervisor set aside before this one started. */
+function recordVersion(live, version, supervised) {
+    let setAside;
+    try {
+        const raw = JSON.parse((supervised && process.env.VISUALPROOF_SET_ASIDE) || "null");
+        if (raw && typeof raw.version === "string" && typeof raw.why === "string")
+            setAside = { version: raw.version, why: raw.why };
+    }
+    catch {
+        // nothing set aside that can be read
+    }
+    const was = live.timeline.lastVersion() ?? live.history?.lastVersion() ?? null;
+    if (was !== version || setAside)
+        live.timeline.add({ kind: "tool", from: was, to: version, ...(setAside ? { setAside } : {}) });
+}
+/** End the server with `status`, the supervisor told first that what ends it is not its code (the
+ *  site is busy, the port is taken, the project cannot be read): a patch that ends so is not set
+ *  aside (UpdateSpec decision 7). The message is sent before the process ends, not lost with it. */
+function endNotTheCode(status) {
+    process.exitCode = status;
+    if (process.send)
+        process.send({ vp: "environment" }, () => process.exit(status));
+    else
+        process.exit(status);
+}
+/** The artwork command (ExportSpec decision 21): the build read as an export reads it, the picture a
+ *  recipe says made of it (server/artcmd.ts), its files written; what it named said as the agents'
+ *  API says it; problems said, and exit status 1. */
+async function artworkCommand(project, o) {
+    const fail = (why) => {
+        console.error(`visualproof artwork: ${why}`);
+        process.exit(1);
+    };
+    try {
+        await artwork(project, o, fail);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+}
+async function artwork(project, o, fail) {
+    const dirs = projectDirs(project.root, o.site, o.cache);
+    const site = o.site ? dirs.site : null;
+    if (site && !existsSync(site))
+        fail(`there is no site at ${site}`);
+    let recipe;
+    try {
+        recipe = JSON.parse(readFileSync(o.recipe, "utf8"));
+    }
+    catch (e) {
+        fail(`the recipe ${o.recipe} cannot be read: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // -o: a name, or a path without its extension, in a folder that is there
+    const outBase = o.out ? o.out.replace(/\.(png|svg)$/i, "") : null;
+    const dir = outBase ? dirname(outBase) : process.cwd();
+    if (!existsSync(dir))
+        fail(`there is no folder ${dir} to write the files in`);
+    mkdirSync(dirs.cache, { recursive: true });
+    const log = (l) => console.log(l);
+    let ex = o.graph ? undefined : await extract(project, dirs, log);
+    if (ex && o.jobs > 0) {
+        const pass = new UsagePass(project, dirs, o.jobs, log);
+        const plan = pass.plan(ex.graph);
+        if (plan.todo.length)
+            log(`usage pass: elaborating ${plan.todo.length} of ${plan.modules.length} modules, ${o.jobs} at a time`);
+        const results = await pass.run(plan);
+        if (results) {
+            ex = mergeUsage(ex, plan, results, pass.status.failed, pass.status.ms ?? 0);
+            saveMerged(dirs.cache, ex);
+        }
+    }
+    // the site's layout memory read and never written, nor the views laid out written to the cache;
+    // without a site, none read: the board as a new site lays it out
+    const prep = await prepare(project, dirs, o.graph, log, { ...(ex ? { extraction: ex } : {}), readOnlySite: true, ...(site ? {} : { freshLayout: true }) });
+    const kept = site ? readProjectView(site, LAYOUT_VERSION) : { view: null };
+    if (kept.why)
+        console.error(`visualproof artwork: the site's views cannot be read (${kept.why}): the Project view as a new site has it`);
+    const review = site ? new ReviewStore(project.root, site).data : null;
+    const a = makeArtwork(prep, review, projectView(kept.view), { recipe, screen: o.screen, name: outBase ? basename(outBase) : null, root: project.root });
+    if (!("svg" in a)) {
+        for (const p of a.problems)
+            console.error(`visualproof artwork: ${p}`);
+        process.exit(1);
+    }
+    const list = (xs) => (xs.length ? xs.join(", ") : "none");
+    console.log(`names written: ${list(a.names.written)}`);
+    if (a.names.ruledSkipped.length)
+        console.log(`names a rule chose, left out where they would cover another: ${list(a.names.ruledSkipped)}`);
+    if (a.names.left)
+        console.log(`names or targets left out for room: ${a.names.left}`);
+    console.log(`targets marked: ${list(a.targets)}`);
+    console.log(`selection: ${a.selection ? `${a.selection.mode} of ${a.selection.name}` : "none"}`);
+    if (a.notesLeftOut)
+        console.log(`notes: ${a.notesLeftOut} on the board, not drawn (the command draws no notes yet)`);
+    const both = !o.png && !o.svg;
+    const mb = (n) => `${(n / 1e6).toFixed(1)} MB`;
+    if (both || o.svg) {
+        const file = join(dir, a.file("svg"));
+        writeFileSync(file, a.svg);
+        console.log(`wrote ${file} (${mb(Buffer.byteLength(a.svg))})`);
+    }
+    if (both || o.png) {
+        const png = await pngOf(a.svg);
+        const file = join(dir, a.file("png"));
+        writeFileSync(file, png);
+        console.log(`wrote ${file} (${mb(png.length)}, ${a.look.w} × ${a.look.h})`);
+    }
+}
 // run as the command (`node src/server/main.ts`, the `visualproof` bin), not when a test imports App
 if (import.meta.main)
     void main();

package/dist/server/mcptools.js

@@ -373,12 +373,13 @@ export const TOOLS = [
     },
     {
         name: "export",
-        about: "A view's document — every declaration of the project its board holds, in its sections and order: its model as JSON, or typeset as a PDF and saved on your machine.",
+        about: "A view's document — every declaration of the project its board holds, in its sections and order: its model as JSON, or typeset as a PDF and saved on your machine. Or a picture of the board: a link that opens it in the artwork mode as a recipe says.",
         actions: {
             model: { method: "GET", path: "/api/agent/export", says: "the document's model", args: ["view", "settings", "version"] },
             typeset: { method: "POST", path: "/api/agent/export", says: "start typesetting: a job", args: ["view", "settings", "version"] },
             job: { method: "GET", path: "/api/agent/export/job", says: "how the job is doing", args: ["id"] },
             file: { method: "GET", path: "/api/agent/export/file", saves: true, says: "a file of it saved on your machine", args: ["id", "what", "saveTo"] },
+            artwork: { method: "POST", path: "/api/agent/artwork", says: "a link to a picture of the board, as a recipe says", args: ["recipe", "save"] },
         },
         args: {
             view: str("the view's id: a target's Key view is open on key(<target>)"),
@@ -387,6 +388,8 @@ export const TOOLS = [
             id: str("the job's id"),
             what: str("pdf (default), tex, sty or zip", ["pdf", "tex", "sty", "zip"]),
             saveTo: SAVE_TO,
+            recipe: { type: "object", description: "the picture: size, orientation, style, theme, names (e.g. {clusters: 1}), targets, selection {name, mode}, title, subtitle, edges… (docs: export)" },
+            save: str("png, svg or png,svg: saved by the page once ready"),
         },
     },
 ];