visualproof 0.4.3 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/README.md +16 -7
  2. package/dist/assets/latex/visualproof.sty +19 -9
  3. package/dist/assets/tips/tour-agent.webp +0 -0
  4. package/dist/assets/tips/tour-arrange.webp +0 -0
  5. package/dist/assets/tips/tour-artwork.webp +0 -0
  6. package/dist/assets/tips/tour-checks.webp +0 -0
  7. package/dist/assets/tips/tour-keys.webp +0 -0
  8. package/dist/assets/tips/tour-library.webp +0 -0
  9. package/dist/assets/tips/tour-project.webp +0 -0
  10. package/dist/assets/tips/tour-review.webp +0 -0
  11. package/dist/assets/tips/tour-share.webp +0 -0
  12. package/dist/assets/tips/tour-source.webp +0 -0
  13. package/dist/assets/tips/tour-target.webp +0 -0
  14. package/dist/assets/tips/tour-view.webp +0 -0
  15. package/dist/assets/tips/tour.json +117 -112
  16. package/dist/assets/tips/tour.webp +0 -0
  17. package/dist/mcp/visualproof-mcp.mjs +7 -3
  18. package/dist/server/access.js +37 -1
  19. package/dist/server/accesspage.js +130 -0
  20. package/dist/server/agent.js +11 -5
  21. package/dist/server/agentlibrary.js +1 -1
  22. package/dist/server/agentviews.js +1 -1
  23. package/dist/server/artcmd.js +1 -1
  24. package/dist/server/askfollow.js +1 -4
  25. package/dist/server/buildwatch.js +133 -0
  26. package/dist/server/deploy.js +844 -0
  27. package/dist/server/doctor.js +15 -3
  28. package/dist/server/events.js +20 -5
  29. package/dist/server/export.js +17 -4
  30. package/dist/server/fetchurl.js +30 -13
  31. package/dist/server/film.js +1 -1
  32. package/dist/server/history.js +3 -1
  33. package/dist/server/historyapi.js +100 -50
  34. package/dist/server/historythread.js +206 -0
  35. package/dist/server/hover.js +8 -0
  36. package/dist/server/identity.js +25 -1
  37. package/dist/server/library.js +10 -3
  38. package/dist/server/live.js +206 -28
  39. package/dist/server/lostfound.js +3 -2
  40. package/dist/server/main.js +361 -50
  41. package/dist/server/poppler.js +48 -10
  42. package/dist/server/renames.js +10 -5
  43. package/dist/server/review.js +32 -2
  44. package/dist/server/reviewapi.js +1 -1
  45. package/dist/server/status.js +144 -50
  46. package/dist/server/talk.js +7 -2
  47. package/dist/server/usage.js +51 -0
  48. package/dist/server/views.js +21 -7
  49. package/dist/shared/board.js +2 -1
  50. package/dist/shared/collab.js +14 -8
  51. package/dist/shared/deploy.js +35 -0
  52. package/dist/shared/doc/latex.js +5 -3
  53. package/dist/shared/doc/outline.js +6 -3
  54. package/dist/shared/layout.js +297 -70
  55. package/dist/shared/libm.js +366 -0
  56. package/dist/shared/library.js +11 -6
  57. package/dist/shared/palette.js +1 -1
  58. package/dist/shared/review.js +7 -5
  59. package/dist/shared/search.js +7 -3
  60. package/dist/shared/separate.js +556 -32
  61. package/dist/shared/views.js +8 -1
  62. package/dist/web/bundle/app.js +3595 -1520
  63. package/dist/web/bundle/edges.js +44 -16
  64. package/dist/web/bundle/layout.js +1026 -80
  65. package/dist/web/index.html +2 -2
  66. package/dist/web/src/artwork.js +25 -4
  67. package/dist/web/src/axiomring.js +42 -0
  68. package/dist/web/src/bundles.js +52 -16
  69. package/dist/web/src/canvas.js +109 -54
  70. package/dist/web/src/overview.js +4 -1
  71. package/dist/web/src/past.js +28 -0
  72. package/dist/web/src/scene.js +13 -12
  73. package/dist/web/src/selection.js +47 -4
  74. package/dist/web/src/status.js +32 -2
  75. package/dist/web/src/theme.js +108 -0
  76. package/dist/web/style.css +181 -45
  77. package/docs/agent-api/following.md +1 -1
  78. package/docs/agent-api/history.md +3 -0
  79. package/docs/agent-api/library.md +1 -1
  80. package/docs/agent-api/requests.md +4 -1
  81. package/docs/agent-api/views.md +1 -1
  82. package/package.json +1 -1
@@ -7,8 +7,8 @@ import { createHash } from "node:crypto";
7
7
  import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
8
8
  import { createServer } from "node:http";
9
9
  import { basename, dirname, extname, join, resolve } from "node:path";
10
- import { tmpdir } from "node:os";
11
- import { gunzipSync, gzipSync } from "node:zlib";
10
+ import { freemem, tmpdir } from "node:os";
11
+ import { gunzip, gunzipSync, gzip, gzipSync } from "node:zlib";
12
12
  import { WEB, WEBFONTS, bundleDir, bundleDirIn, ensureBundle, prepare, useBundleDir } from "./pipeline.js";
13
13
  import { makeArtwork, pngOf, projectView } from "./artcmd.js";
14
14
  import { SiteBusy, cacheHome, dataHome, lockSite, openSite, projectDirs } from "./dirs.js";
@@ -19,18 +19,19 @@ import { isDeclName, LeanHover } from "./hover.js";
19
19
  import { Identities, layoutAuthor } from "./identity.js";
20
20
  import { LAYOUT_VERSION } from "../shared/graph.js";
21
21
  import { MAX_MEMORY_BYTES, readProjectView, Views } from "./views.js";
22
- import { cleanView, defaultAgentName, validSession, withoutArtwork } from "../shared/collab.js";
22
+ import { cleanView, defaultAgentName, nameKey, validSession, withoutArtwork } from "../shared/collab.js";
23
23
  import { writeSnapshot } from "./snapshot.js";
24
24
  import { lakeTextHash } from "./status.js";
25
25
  import { invalidTemplate } from "../shared/editor.js";
26
26
  import { packEdges } from "../shared/edgecodec.js";
27
- import { Access, KEY_PATH, loadKey } from "./access.js";
27
+ import { Access, hostAllowed, KEY_PATH, loadKey, urlHost } from "./access.js";
28
+ import { asksForPage, sendAccessPage } from "./accesspage.js";
28
29
  import { INVITE_PATH, invalidPersonName, Invites, taken } from "./invites.js";
29
30
  import { AGENT_LEVELS, AgentApi, lower, needOf, refusal } from "./agent.js";
30
31
  import { AgentTokens, bearerOf, DEFAULT_DAYS, invalidAgentName, looksLikeToken, TOKEN_DAYS } from "./tokens.js";
31
32
  import { agentPrompt } from "./prompt.js";
32
33
  import { MAX_PERSON } from "./talk.js";
33
- import { DEFAULT_JOBS, UsagePass, mergeUsage, saveMerged } from "./usage.js";
34
+ import { DEFAULT_JOBS, inGB, jobsAdvice, memoryFloor, onMathlib, UsagePass, mergeUsage, saveMerged, WORKER_PEAK } from "./usage.js";
34
35
  import { extract } from "./extract.js";
35
36
  import { Exporter } from "./export.js";
36
37
  import { Library, libraryApiOf } from "./library.js";
@@ -46,14 +47,17 @@ import { RESTART_STATUS, supervise } from "./supervise.js";
46
47
  import { stopChildren } from "./children.js";
47
48
  import { filmStatus, serveFilm, useFilm } from "./film.js";
48
49
  import { finalAnswer, readOnlyAllows, ReadOnlyBounds } from "./readonlygate.js";
50
+ import { branchProblem, branchToFollow, DEFAULT_POLL_MINUTES, DeployBusy, deployFolder, Deployment, deploySite, ensureClone, isGitAddress, lockDeployment, MIN_POLL_MINUTES, parseRemote, recordedDefault } from "./deploy.js";
51
+ import { shortCommit, slimDeploy } from "../shared/deploy.js";
49
52
  /** The usage, to stderr with status 2 for a command line it cannot read; asked for (`--help`),
50
53
  * to stdout with status 0. */
51
54
  function usage(code = 2) {
52
- (code === 0 ? console.log : console.error)(`usage: visualproof serve <lean-project> [--root Name]... [--port 4173] [--host 127.0.0.1]
55
+ (code === 0 ? console.log : console.error)(`usage: visualproof serve <lean-project | git URL> [--branch name] [--poll ${DEFAULT_POLL_MINUTES}] [--root Name]... [--port 4173] [--host 127.0.0.1]
53
56
  [--site dir] [--cache dir] [--graph saved.json]
54
57
  [--identity-header X-Forwarded-User] [--editor URL-template]
55
58
  [--agents read|advise|full] [--access-key-file file] [--public] [--jobs ${DEFAULT_JOBS}]
56
- [--public-url https://host] [--library-limit GB] [--updates auto|notify|off]
59
+ [--public-url https://host] [--allowed-host name]... [--library-limit GB]
60
+ [--updates auto|notify|off]
57
61
  visualproof purge-file <lean-project> <sha256> [--site dir] [--cache dir]
58
62
  visualproof export <lean-project> -o page.html [--label text] [--root Name]... [--graph saved.json]
59
63
  [--jobs ${DEFAULT_JOBS}] [--site dir] [--cache dir]
@@ -65,6 +69,18 @@ function usage(code = 2) {
65
69
  Reads what \`lake build\` left in <lean-project>/.lake. It never builds the project, and writes
66
70
  nothing into it.
67
71
 
72
+ A git URL where the project goes (https://github.com/owner/repo, ssh://…, git@host:owner/repo, or
73
+ file:///path for a repository on this machine): the server follows that branch of the repository
74
+ in a clone of its own in the cache, never a workspace, and builds each new commit itself —
75
+ \`lake exe cache get\` where the project is on Mathlib, then \`lake build\` — one at a time, the
76
+ newest commit pushed meanwhile the only one built after it; the board shows the last build
77
+ meanwhile. Git's own credentials (an SSH key, a deploy key, a credential helper): VisualProof keeps
78
+ none, and nothing waits on a prompt. Whoever can push to the branch runs code on this machine, as
79
+ the server's user (SECURITY.md): run it as a user of its own, and protect the branch.
80
+ --branch the branch followed (default: the remote's default branch); never a pull request's or
81
+ a fork's
82
+ --poll how often the remote is asked for the branch's head, in minutes (default ${DEFAULT_POLL_MINUTES})
83
+
68
84
  --root what to read: a library of the lakefile (the modules Lake builds of it) or a module;
69
85
  repeatable. By default the lakefile's default targets.
70
86
  --site the site's folder: the review's logs and what this running site accumulates — the
@@ -116,26 +132,37 @@ function usage(code = 2) {
116
132
  --jobs how many modules the usage pass elaborates at once (default ${DEFAULT_JOBS}; 0: no pass). The
117
133
  pass finds which notation each declaration is written in and the exact context it is
118
134
  written in (TCBSpec.md, decisions 2 and 4); its findings follow the extractor's graph
119
- as its next version. Each worker takes about 400 MB of its own and the import of a
120
- module is bound by memory bandwidth: past about a quarter of the cores it gains little.
135
+ as its next version. Each worker takes about 400 MB of its own, several GB on a large
136
+ project on Mathlib (serve and doctor say which --jobs the memory fits); with memory
137
+ short, fewer run at a time. The import of a module is bound by memory bandwidth: past
138
+ about a quarter of the cores it gains little.
121
139
 
122
140
  --access-key-file let in only those given the link http://<host>:<port>/k/<key>, the key being
123
141
  what the file holds (one is made there, readable by its owner alone, if there is none).
124
142
  The link leaves a cookie in the browser; agents send Authorization: Bearer <key>.
125
- Anything else is answered 404. Over plain HTTP the key crosses the network in the
126
- clear: it keeps out who was not given the link, not who can watch the traffic.
143
+ Anything else is answered 404, but a browser asking for a page, which is shown one
144
+ that says the site is private and nothing of it. Over plain HTTP the key crosses the
145
+ network in the clear: it keeps out who was not given the link, not who can watch the
146
+ traffic.
127
147
  Share also gives an AI agent a token of its own (vpa_…), which reaches /api/agent only,
128
148
  and a person a link of their own (/i/vpp_…), which lets them in and says who they are,
129
149
  and anyone a read-only link (/r/vpr_…), which lets them see and change nothing shared.
130
150
 
131
151
  --public with --access-key-file: whoever comes without the key or a link of their own is let
132
- in read-only, rather than answered 404: they see the project, its review and its
152
+ in read-only, rather than turned away: they see the project, its review and its
133
153
  history, change nothing that is shared, and are seen by nobody. For a project anyone
134
154
  may read (a showcase); never for a private one.
135
155
 
136
156
  --public-url the address people reach this server at, when it is not the one their browser
137
157
  sends (a proxy in front): the prompt Share makes for an agent tells it this address.
138
158
 
159
+ --allowed-host without --access-key-file, a name this server is reached by; repeatable. A
160
+ server without a key answers only requests for an IP address, localhost (and the names
161
+ under it), --public-url's host and these: any other name is answered 403, so that a web
162
+ page that makes its own name resolve to this machine (DNS rebinding) cannot use it. Give
163
+ the names people reach it by: a proxy's in front of it, this machine's own. With a key,
164
+ the key keeps everyone else out, whatever the name.
165
+
139
166
  --updates what the server does with VisualProof's own releases, asked of the npm registry
140
167
  (through npm) at start and once a day: auto (the default) — a patch of the version it
141
168
  runs (0.4.x) is downloaded into the cache and taken at a quiet moment, nobody on a page,
@@ -173,7 +200,7 @@ function parseArgs(argv) {
173
200
  console.error(`visualproof: VISUALPROOF_UPDATES=${fromEnv}: say auto, notify or off`);
174
201
  process.exit(2);
175
202
  }
176
- 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" };
203
+ 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, allowedHosts: [], 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", remote: null, branch: null, poll: null };
177
204
  for (let i = 0; i < rest.length; i++) {
178
205
  const a = rest[i];
179
206
  const val = () => rest[++i] ?? usage();
@@ -208,9 +235,13 @@ function parseArgs(argv) {
208
235
  else if (a === "--svg" && cmd === "artwork")
209
236
  o.svg = true;
210
237
  else if (a === "--screen" && cmd === "artwork") {
211
- const m = /^(\d+)x(\d+)$/.exec(val());
212
- if (!m || +m[1] < 640 || +m[2] < 480 || +m[1] > 10000 || +m[2] > 10000)
213
- usage();
238
+ const v = val();
239
+ const m = /^(\d+)x(\d+)$/.exec(v);
240
+ // said in a line, as --public-url is, rather than the whole usage
241
+ if (!m || +m[1] < 640 || +m[2] < 480 || +m[1] > 10000 || +m[2] > 10000) {
242
+ console.error(`visualproof artwork: --screen ${v}: give the screen's width and height in pixels, e.g. 1920x1200, from 640x480 to 10000x10000`);
243
+ process.exit(2);
244
+ }
214
245
  o.screen = { w: +m[1], h: +m[2] };
215
246
  }
216
247
  else if (a === "--public-url") {
@@ -221,12 +252,33 @@ function parseArgs(argv) {
221
252
  }
222
253
  o.publicUrl = u.replace(/\/+$/, "");
223
254
  }
255
+ else if (a === "--allowed-host" && cmd === "serve") {
256
+ const h = val();
257
+ // a name, as a Host header gives it without its port (CollabSpec decision 12)
258
+ if (!/^[A-Za-z0-9]([A-Za-z0-9_-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9_-]*[A-Za-z0-9])?)*\.?$/.test(h)) {
259
+ console.error(`visualproof: --allowed-host ${h}: give a name this server is reached by, without a scheme or a port, e.g. vp.example.org`);
260
+ process.exit(2);
261
+ }
262
+ o.allowedHosts.push(h);
263
+ }
224
264
  else if (a === "--jobs") {
225
265
  const n = Number(val());
226
266
  if (!Number.isInteger(n) || n < 0 || n > 256)
227
267
  usage();
228
268
  o.jobs = n;
229
269
  }
270
+ else if (a === "--branch" && cmd === "serve")
271
+ o.branch = val();
272
+ else if (a === "--poll" && cmd === "serve") {
273
+ const v = val();
274
+ const m = Number(v);
275
+ // said in a line, as --screen is
276
+ if (!/^\d+(\.\d+)?$/.test(v) || m < MIN_POLL_MINUTES || m > 1440) {
277
+ console.error(`visualproof: --poll ${v}: say how often the remote is asked, in minutes, from ${MIN_POLL_MINUTES} to 1440 (a day)`);
278
+ process.exit(2);
279
+ }
280
+ o.poll = m;
281
+ }
230
282
  else if (a === "--updates" && cmd === "serve") {
231
283
  const mode = val();
232
284
  if (!UPDATE_MODES.includes(mode))
@@ -256,12 +308,43 @@ function parseArgs(argv) {
256
308
  }
257
309
  if ((!o.path && cmd !== "doctor") || (cmd === "export" && !o.out) || (cmd === "artwork" && !o.recipe))
258
310
  usage();
311
+ // a git address where the project goes: the branch followed and built (DeploySpec decisions 1,
312
+ // 10 and 11), its address and branch checked before anything is run
313
+ if (o.path && isGitAddress(o.path)) {
314
+ if (cmd !== "serve") {
315
+ console.error(`visualproof ${cmd}: ${o.path.slice(0, 200)} is a git address: only serve follows a branch. Give the folder of its clone, which serve names as it starts (its "clone:" line).`);
316
+ process.exit(2);
317
+ }
318
+ const r = parseRemote(o.path);
319
+ if ("error" in r) {
320
+ console.error(`visualproof: ${r.error}`);
321
+ process.exit(2);
322
+ }
323
+ if (o.graph) {
324
+ console.error("visualproof: --graph does not go with a git address: the server builds what it shows");
325
+ process.exit(2);
326
+ }
327
+ const why = o.branch === null ? null : branchProblem(o.branch);
328
+ if (why) {
329
+ console.error(`visualproof: --branch ${why}`);
330
+ process.exit(2);
331
+ }
332
+ o.remote = r;
333
+ }
334
+ else if (o.branch !== null || o.poll !== null) {
335
+ console.error("visualproof: --branch and --poll go with a git address (serve https://github.com/owner/repo): a folder is read as its owner's builds leave it");
336
+ process.exit(2);
337
+ }
259
338
  // read-only for whoever comes, beside those the key or a link lets in: without a key, everyone is in
260
339
  // already; behind a sign-in, there is nobody else
261
340
  if (o.publicRead && (!o.accessKeyFile || o.identityHeader)) {
262
341
  console.error("visualproof: --public lets in read-only whoever has no key: it needs --access-key-file, and does not go with --identity-header");
263
342
  process.exit(2);
264
343
  }
344
+ // the names a server without a key answers: with one, the key keeps everyone else out whatever
345
+ // the name (CollabSpec decision 12)
346
+ if (o.allowedHosts.length && o.accessKeyFile)
347
+ console.warn("visualproof: --allowed-host changes nothing with --access-key-file: the key lets in whoever has it, by any name");
265
348
  if (cmd === "purge-file" && !validSha(o.sha)) {
266
349
  console.error("visualproof purge-file: give the file's SHA-256, 64 hex digits, as the page's library shows it.");
267
350
  process.exit(2);
@@ -296,6 +379,13 @@ export class App {
296
379
  /** --public: whoever comes without the key or a link of their own reads only (CollabSpec
297
380
  * decision 11) */
298
381
  publicRead;
382
+ /** without a key, the names this server answers besides its addresses and localhost
383
+ * (server/access.ts, hostAllowed): --public-url's host and every --allowed-host; null: every
384
+ * name, the key keeping everyone else out */
385
+ hostNames;
386
+ /** the names refused as Host, said once each in the server's console (a few: whoever asks
387
+ * chooses them) */
388
+ refusedHosts = new Set();
299
389
  /** the read-only readers' requests, by the read-only link they came by, or "public" */
300
390
  readOnlyOf = new WeakMap();
301
391
  /** what read-only readers may cost the server: Lean's answers, their documents */
@@ -303,7 +393,7 @@ export class App {
303
393
  /** VisualProof's own releases as this server follows them (server/updates.ts); null: the
304
394
  * version alone is told (a test's server) */
305
395
  updates = null;
306
- constructor(live, hover, ids, agents, access, exporter = null, publicUrl = null, publicRead = false) {
396
+ constructor(live, hover, ids, agents, access, exporter = null, publicUrl = null, publicRead = false, allowedHosts = []) {
307
397
  this.live = live;
308
398
  this.hover = hover;
309
399
  this.ids = ids;
@@ -317,6 +407,7 @@ export class App {
317
407
  agents.exporter = exporter;
318
408
  this.publicUrl = publicUrl;
319
409
  this.publicRead = publicRead && access !== null;
410
+ this.hostNames = access ? null : [...(publicUrl ? [urlHost(publicUrl)] : []), ...allowedHosts];
320
411
  this.bounds = new ReadOnlyBounds((id) => this.exporter?.job(id)?.state === "running");
321
412
  }
322
413
  /** Whether a request is told all of the server's own releases (UpdateSpec decision 11): someone
@@ -531,7 +622,7 @@ export class App {
531
622
  return sendJson(res, { error: "to is a reader's id, as presence lists them; left out, everyone." }, 400);
532
623
  const person = this.ids.person(req);
533
624
  // one request every 30 s per person — their personal link, else their name — and per page
534
- const key = person ? `p:${person.id}` : `n:${me.trim().normalize("NFKC").toLowerCase()}`;
625
+ const key = person ? `p:${person.id}` : `n:${nameKey(me)}`;
535
626
  const a = live.asks.ask({ name: me, verified: !!person, agent: false, from: page.id, stream: b.token, rate: [key, `s:${b.token}`] }, typeof b.to === "string" ? { page: b.to } : { everyone: true });
536
627
  if ("ok" in a) {
537
628
  const { report: _, ...sent } = a.ok;
@@ -674,35 +765,43 @@ export class App {
674
765
  /** A personal link opened (CollabSpec decision 9): the browser is given the cookie that lets its
675
766
  * holder in, as who the link says, and goes on to the page — the token leaves the address, and a
676
767
  * place after it (a fragment) comes along. A revoked link says so; anything else is answered as
677
- * any address nobody was given. */
678
- enter(req, res, token) {
768
+ * any address nobody was given. On a server with a key, a browser is shown the page of a link
769
+ * that does not open the site instead (CollabSpec decision 7), which says neither which it was
770
+ * nor who revoked it — unless the key or a link of its own lets it in, and it may be told. */
771
+ enter(req, res, token, path) {
679
772
  const c = this.ids.header ? null : this.live.invites.check(token);
680
773
  if (c && "ok" in c) {
681
774
  res.writeHead(303, { location: "/", "set-cookie": this.live.invites.cookie(c.ok), "cache-control": "no-store", "referrer-policy": "no-referrer" });
682
775
  return void res.end();
683
776
  }
684
- if (c) {
685
- const r = c.record;
686
- return sendText(req, res, `This personal link was revoked by ${r.revokedBy} on ${r.revoked.slice(0, 10)}. Ask whoever invited you for a new one.\n`, "text/plain; charset=utf-8", 410);
687
- }
777
+ if (this.access && asksForPage(req, path) && (!c || !this.letIn(req)))
778
+ return sendAccessPage(res, "link", this.publicRead);
779
+ if (c)
780
+ return sendText(req, res, revokedWords(c.record, "personal") + "\n", "text/plain; charset=utf-8", 410);
688
781
  sendJson(res, { error: "not found" }, 404);
689
782
  }
690
783
  /** A read-only link opened (CollabSpec decision 11): the browser is given the cookie that lets
691
784
  * its holder read, and goes on to the page — the token leaves the address, and a place after it
692
785
  * (a fragment) comes along. A revoked link says so; anything else, and any link on a server
693
- * open to all or behind a sign-in, which have none, is answered as an address nobody was given. */
694
- enterReadOnly(req, res, token) {
786
+ * open to all or behind a sign-in, which have none, is answered as an address nobody was given;
787
+ * to a browser, on a server with a key, as a personal link's (enter). */
788
+ enterReadOnly(req, res, token, path) {
695
789
  const c = this.access && !this.ids.header ? this.live.readOnly.check(token) : null;
696
790
  if (c && "ok" in c) {
697
791
  res.writeHead(303, { location: "/", "set-cookie": this.live.readOnly.cookie(c.ok.id), "cache-control": "no-store", "referrer-policy": "no-referrer" });
698
792
  return void res.end();
699
793
  }
700
- if (c) {
701
- const l = c.link;
702
- return sendText(req, res, `This read-only link was revoked by ${l.revokedBy} on ${l.revoked.slice(0, 10)}. Ask whoever gave it to you for a new one.\n`, "text/plain; charset=utf-8", 410);
703
- }
794
+ if (this.access && asksForPage(req, path) && (!c || !this.letIn(req)))
795
+ return sendAccessPage(res, "link", this.publicRead);
796
+ if (c)
797
+ return sendText(req, res, revokedWords(c.link, "read-only") + "\n", "text/plain; charset=utf-8", 410);
704
798
  sendJson(res, { error: "not found" }, 404);
705
799
  }
800
+ /** Whether the key's cookie or a personal link in force lets a request in: someone who sees the
801
+ * site's people, and may be told who revoked a link. */
802
+ letIn(req) {
803
+ return !!this.ids.person(req) || this.access?.admit(req, "/") === "in";
804
+ }
706
805
  /** Who the reader is (POST /api/identity {name}): the name someone invited by a personal link goes
707
806
  * by from now on — kept with their link, and said in their review log, so that what they wrote
708
807
  * shows under it — or, for a guest, whether a name is theirs to take: one a link's holder goes
@@ -736,6 +835,23 @@ export class App {
736
835
  this.live.review.named(p.id, done.name);
737
836
  return sendJson(res, { ok: true, name: done.name, person: Invites.info(done) });
738
837
  }
838
+ /** A request for a name this server without a key does not answer (CollabSpec decision 12): 403,
839
+ * saying which option lets the name in; and, once per name, the server's console says it too,
840
+ * for whoever runs it behind a proxy that forwards the name people reach it by. A browser asking
841
+ * for a page is shown a page that says so (the owner's decision of 2026-10-18), which does not
842
+ * repeat the name: it is the requester's, any text at all. */
843
+ refuseHost(req, res, path) {
844
+ const raw = req.headers.host ?? "";
845
+ const name = /^\[/.test(raw) ? raw : raw.replace(/:\d{1,5}$/, "");
846
+ const shown = /^[A-Za-z0-9._\-[\]:]{1,253}$/.test(name) ? name : null;
847
+ if (shown && this.refusedHosts.size < 20 && !this.refusedHosts.has(shown.toLowerCase())) {
848
+ this.refusedHosts.add(shown.toLowerCase());
849
+ console.error(`refused a request for ${shown}: without an access key this server answers only its addresses, localhost, --public-url's host and the --allowed-host names; --allowed-host ${shown} lets this one in`);
850
+ }
851
+ if (asksForPage(req, path))
852
+ return sendAccessPage(res, "host");
853
+ sendText(req, res, `This server answers only the names it is meant to be reached by${shown ? `, and ${shown} is not one of them` : ""}. Whoever runs it can let a name in with --allowed-host${shown ? ` ${shown}` : " <name>"}.\n`, "text/plain; charset=utf-8", 403);
854
+ }
739
855
  /** The answer to a request that needs a name and has none: the page asks for one (`who`). Where
740
856
  * the name the page gives is a personal link holder's, it says so, and the page asks for
741
857
  * another. */
@@ -818,6 +934,12 @@ export class App {
818
934
  const url = new URL(req.url ?? "/", "http://localhost");
819
935
  const path = url.pathname;
820
936
  const live = this.live;
937
+ // without a key, only the names this server is reached at (CollabSpec decision 12, the owner's
938
+ // decision of 2026-10-18): a page whose own name was made to resolve to this machine (DNS
939
+ // rebinding) is refused whatever it asks — the page, its data, the event stream, the agents'
940
+ // API, the MCP server's file
941
+ if (this.hostNames && !hostAllowed(req.headers.host, this.hostNames))
942
+ return this.refuseHost(req, res, path);
821
943
  // every route; whatever one throws, handle() answers
822
944
  {
823
945
  // an agent's own token (server/tokens.ts) lets it into its API alone: the page and the page's
@@ -840,11 +962,11 @@ export class App {
840
962
  // it says, and its cookie does from then on; a revoked one's cookie is forgotten, and lets
841
963
  // nobody in
842
964
  if (path.startsWith(INVITE_PATH))
843
- return this.enter(req, res, path.slice(INVITE_PATH.length));
965
+ return this.enter(req, res, path.slice(INVITE_PATH.length), path);
844
966
  // a read-only link (CollabSpec decision 11, server/readonly.ts): its cookie lets its holder
845
967
  // read, where nothing else lets them in
846
968
  if (path.startsWith(READONLY_PATH))
847
- return this.enterReadOnly(req, res, path.slice(READONLY_PATH.length));
969
+ return this.enterReadOnly(req, res, path.slice(READONLY_PATH.length), path);
848
970
  const link = this.ids.link(req);
849
971
  const cookies = link && "ended" in link ? [live.invites.forget()] : [];
850
972
  const ro = this.access && !this.ids.header ? live.readOnly.ofCookie(req.headers.cookie) : null;
@@ -855,11 +977,41 @@ export class App {
855
977
  if (a === "out") {
856
978
  // nothing lets them in to write: their read-only link does, or --public, to read
857
979
  const reader = ro && "ok" in ro ? ro.ok.id : this.publicRead && !this.ids.header ? "public" : null;
980
+ // a page whose link was revoked, which nothing else lets in, is told so (CollabSpec
981
+ // decisions 9 and 11): its requests are answered 410 with who revoked it and when, and the
982
+ // page, reloaded, says the link no longer opens the site (decision 7: to a browser, the
983
+ // page of a link that does not, which names nobody); the cookie is forgotten there, once
984
+ // it has been said
985
+ const revoked = reader === null && this.ids.kind(req) !== "agent" ? (link && "ended" in link ? revokedWords(link.record, "personal") : ro && "ended" in ro ? revokedWords(ro.link, "read-only") : null) : null;
986
+ if (revoked) {
987
+ if (asksForPage(req, path)) {
988
+ res.setHeader("set-cookie", cookies);
989
+ return sendAccessPage(res, "link");
990
+ }
991
+ if (path === "/" || path === "/index.html") {
992
+ res.setHeader("set-cookie", cookies);
993
+ return sendText(req, res, revoked + "\n", "text/plain; charset=utf-8", 410);
994
+ }
995
+ return sendJson(res, { error: revoked, revoked: true }, 410);
996
+ }
997
+ // nothing lets them in: a browser asking for a page is told the site is private, or that
998
+ // its link (`/k/…`, a key replaced) does not open it (CollabSpec decision 7, the owner's
999
+ // decision of 2026-10-18); anything else is answered as if there were nothing here
858
1000
  if (reader === null || this.ids.kind(req) === "agent") {
859
1001
  if (cookies.length)
860
1002
  res.setHeader("set-cookie", cookies);
1003
+ if (asksForPage(req, path))
1004
+ return sendAccessPage(res, path.startsWith(KEY_PATH) ? "link" : "private");
861
1005
  return sendJson(res, { error: "not found" }, 404);
862
1006
  }
1007
+ // a link of the key's that is not the key, opened where the address, or a read-only link,
1008
+ // lets them read: the page of a link that does not open the site, which says whether the
1009
+ // address alone does (--public)
1010
+ if (path.startsWith(KEY_PATH) && asksForPage(req, path)) {
1011
+ if (cookies.length)
1012
+ res.setHeader("set-cookie", cookies);
1013
+ return sendAccessPage(res, "link", this.publicRead);
1014
+ }
863
1015
  this.readOnlyOf.set(req, reader);
864
1016
  // the page renews a read-only link's cookie, as a personal link's
865
1017
  if (reader !== "public" && (path === "/" || path === "/index.html"))
@@ -927,6 +1079,9 @@ export class App {
927
1079
  if (this.readOnlyOf.get(req) !== undefined) {
928
1080
  delete st.log;
929
1081
  st.review = { ...st.review, folder: undefined };
1082
+ // a branch's build log is not a read-only reader's (DeploySpec decision 11)
1083
+ if (st.deploy)
1084
+ st.deploy = slimDeploy(st.deploy);
930
1085
  }
931
1086
  return sendJson(res, st);
932
1087
  }
@@ -975,7 +1130,7 @@ export class App {
975
1130
  // name — a private reader's too (CollabSpec decision 8) — with the personal link of someone
976
1131
  // invited by one, whose moves go to their link's log (decision 9); by an agent at level full
977
1132
  const person = this.ids.person(req)?.id;
978
- const a = historyAnswer(live, { method: req.method ?? "GET", path, query: url.searchParams, body, caller: { name: this.ids.who(req), kind: this.ids.kind(req), ...(person ? { person } : {}) } }, (q) => q.caller.kind === "agent" ? refusal(this.agents.level, "full") : null);
1133
+ const a = await historyAnswer(live, { method: req.method ?? "GET", path, query: url.searchParams, body, caller: { name: this.ids.who(req), kind: this.ids.kind(req), ...(person ? { person } : {}) } }, (q) => q.caller.kind === "agent" ? refusal(this.agents.level, "full") : null);
979
1134
  // a snapshot's graph in parts, as the Time Machine takes it: compressed once, and tagged
980
1135
  if (a.gz)
981
1136
  return sendGz(req, res, a.gz.body, a.gz.type);
@@ -983,14 +1138,24 @@ export class App {
983
1138
  }
984
1139
  // the library of papers and images, and the links into them (AttachmentSpec.md,
985
1140
  // server/libraryroute.ts)
986
- if (path === "/api/library" || path.startsWith("/api/library/"))
1141
+ if (path === "/api/library" || path.startsWith("/api/library/")) {
1142
+ // a read-only reader (CollabSpec decision 11) is drawn what the notes show of a PDF, kept in
1143
+ // the cache as it is drawn, and no other page or region of one: each would be drawn by
1144
+ // Poppler and kept anew, whoever comes asking
1145
+ if (reader !== undefined && (path === "/api/library/page" || path === "/api/library/clip")) {
1146
+ const q = url.searchParams;
1147
+ const region = path === "/api/library/clip" ? (q.get("region") ?? "").split(",").map(Number) : null;
1148
+ if (!live.views.shows(q.get("sha") ?? "", Number(q.get("page")), region))
1149
+ return sendJson(res, { error: "A read-only page is drawn what the notes show of the library: open the file itself.", readOnly: true }, 403);
1150
+ }
987
1151
  return libraryRoute({ ids: this.ids, level: this.agents.level, api: this.library() }, req, res, url);
1152
+ }
988
1153
  // an agent may use the page's own endpoints too: the same rules hold there (AgentSpec)
989
1154
  const agent = this.ids.kind(req) === "agent";
990
1155
  // the review (ReviewSpec.md): the whole of it, as a page takes it on, with the lines of its
991
- // logs that cannot be read
1156
+ // logs that cannot be read; tagged with its revision, compressed once a revision
992
1157
  if (path === "/api/review" && req.method === "GET")
993
- return sendJson(res, live.review.whole());
1158
+ return sendReview(req, res, live.review);
994
1159
  if (path === "/api/review" && req.method === "POST") {
995
1160
  // an opinion, a target, a trusted prefix or a key declaration is recorded under the
996
1161
  // reader's name (CollabSpec decision 3), not one in the body; what it is about is
@@ -1080,6 +1245,11 @@ export class App {
1080
1245
  // the project's git source and commit as git says them now, not as the build was read (an
1081
1246
  // artwork's foot, ExportSpec decision 19; the owner's decision of 2026-10-15)
1082
1247
  if (path === "/api/git") {
1248
+ // following a branch, the commit of the build on show, on that branch: what is checked out
1249
+ // meanwhile is the build going on (DeploySpec decision 12)
1250
+ const shown = live.shownCommit();
1251
+ if (shown !== undefined)
1252
+ return sendJson(res, { git: shown && { source: live.deploy.status(false).source, commit: shown.hash, branch: shown.branch } });
1083
1253
  if (!this.gitRead || Date.now() - this.gitRead.at >= this.gitFreshMs)
1084
1254
  this.gitRead = { git: gitSource(live.project.root), at: Date.now() };
1085
1255
  return sendJson(res, { git: this.gitRead.git });
@@ -1199,6 +1369,10 @@ export class App {
1199
1369
  }
1200
1370
  }
1201
1371
  }
1372
+ /** What a revoked link's holder is told, opening it or on a page it had opened. */
1373
+ function revokedWords(r, kind) {
1374
+ return `This ${kind} link was revoked by ${r.revokedBy} on ${(r.revoked ?? "").slice(0, 10)}. Ask whoever ${kind === "personal" ? "invited you" : "gave it to you"} for a new one.`;
1375
+ }
1202
1376
  /** an artwork's font file (assets/webfonts/) */
1203
1377
  const FONT_PATH = /^\/fonts\/(source-sans-3|source-serif-4|jost)-[a-z-]+\.woff2$/;
1204
1378
  const TYPES = {
@@ -1310,18 +1484,60 @@ function tooLarge(req, res, body) {
1310
1484
  }
1311
1485
  /** Send a JSON answer, once: a handler that answers after something else already did (a body too
1312
1486
  * large, answered as it was read) is not heard. */
1313
- function sendJson(res, body, code = 200, headers = {}) {
1487
+ export function sendJson(res, body, code = 200, headers = {}) {
1488
+ if (res.headersSent || res.writableEnded || refused.has(res))
1489
+ return;
1490
+ sendJsonText(res, JSON.stringify(body), code, headers);
1491
+ }
1492
+ /** The same, of an answer written as JSON already. */
1493
+ function sendJsonText(res, text, code = 200, headers = {}) {
1314
1494
  if (res.headersSent || res.writableEnded || refused.has(res))
1315
1495
  return;
1316
- const text = JSON.stringify(body);
1317
- // a small answer is not worth compressing; a status with its build log, a source file, are
1496
+ // a small answer is not worth compressing; a status with its build log, a source file, are; a
1497
+ // large one is compressed off the server's thread, which meanwhile answers others
1318
1498
  if (text.length > JSON_GZIP_FROM && acceptsGzip(res.req)) {
1319
1499
  res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store", "content-encoding": "gzip", vary: "accept-encoding", ...headers });
1320
- return void res.end(gzipSync(text));
1500
+ if (text.length < JSON_GZIP_AWAY_FROM)
1501
+ return void res.end(gzipSync(text));
1502
+ return void gzip(text, (e, gz) => (e ? res.destroy(e) : res.end(gz)));
1321
1503
  }
1322
1504
  res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store", ...headers });
1323
1505
  res.end(text);
1324
1506
  }
1507
+ /** the whole review compressed, under the tag of the revision it is of, per review */
1508
+ const reviewGz = new WeakMap();
1509
+ /** The whole review (GET /api/review), tagged with its run and its revision (server/review.ts): a
1510
+ * page that has it is answered 304, which a reload is, and one whose review fell behind is sent it
1511
+ * compressed — once a revision, off the server's thread when it is large, the same bytes for every
1512
+ * page (a review of 5,000 opinions on Sphere-Packing-Lean: 8.5 MB of JSON, 1.1 MB sent). */
1513
+ function sendReview(req, res, review) {
1514
+ if (res.headersSent || res.writableEnded || refused.has(res))
1515
+ return;
1516
+ const tag = review.tag();
1517
+ const head = { "content-type": "application/json", "cache-control": "private, no-cache", etag: tag, vary: "accept-encoding" };
1518
+ if (fresh(req, tag)) {
1519
+ res.writeHead(304, head);
1520
+ return void res.end();
1521
+ }
1522
+ const text = review.wholeText();
1523
+ if (text.length <= JSON_GZIP_FROM || !acceptsGzip(req)) {
1524
+ res.writeHead(200, head);
1525
+ return void res.end(text);
1526
+ }
1527
+ let c = reviewGz.get(review);
1528
+ if (c?.tag !== tag) {
1529
+ const gz = text.length < JSON_GZIP_AWAY_FROM ? Promise.resolve(gzipSync(text)) : new Promise((ok, fail) => gzip(text, (e, b) => (e ? fail(e) : ok(b))));
1530
+ reviewGz.set(review, (c = { tag, gz }));
1531
+ // a compression that failed is tried again by the next page that asks
1532
+ gz.catch(() => reviewGz.get(review)?.gz === gz && reviewGz.delete(review));
1533
+ }
1534
+ c.gz.then((gz) => {
1535
+ if (res.headersSent || res.destroyed)
1536
+ return;
1537
+ res.writeHead(200, { ...head, "content-encoding": "gzip" });
1538
+ res.end(gz);
1539
+ }, (e) => res.destroy(e));
1540
+ }
1325
1541
  /** Send a text that is not JSON (the agents' documentation, the MCP server's file), compressed
1326
1542
  * where the client takes it. */
1327
1543
  function sendText(req, res, text, type, code = 200) {
@@ -1362,20 +1578,32 @@ export function reachedAt(req) {
1362
1578
  }
1363
1579
  /** characters from which a JSON answer is sent compressed */
1364
1580
  const JSON_GZIP_FROM = 2048;
1581
+ /** characters from which a JSON answer is compressed off the server's thread: a snapshot's whole
1582
+ * graph on NavierStokesAndEuler (GET /api/agent/history/graph, 105 MB of JSON) was 2 to 3 s of
1583
+ * compressing, every page and agent waiting meanwhile */
1584
+ export const JSON_GZIP_AWAY_FROM = 1 << 20;
1365
1585
  /** the graph's parts as sent, each tagged once (a graph's buffers live as long as it does) */
1366
1586
  const gzTags = new WeakMap();
1367
- /** A part of the graph, gzipped already: tagged, so that a page that has it gets 304. */
1587
+ /** A part of the graph, gzipped already: tagged, so that a page that has it gets 304; a client that
1588
+ * does not take gzip (an agent's) is sent it as it is, made so off the server's thread. */
1368
1589
  function sendGz(req, res, gz, type) {
1369
1590
  if (refused.has(res))
1370
1591
  return;
1371
1592
  let etag = gzTags.get(gz);
1372
1593
  if (!etag)
1373
1594
  gzTags.set(gz, (etag = tagOf(gz)));
1374
- const head = { "content-type": type, "cache-control": "private, no-cache", etag };
1595
+ const head = { "content-type": type, "cache-control": "private, no-cache", etag, vary: "accept-encoding" };
1375
1596
  if (fresh(req, etag)) {
1376
1597
  res.writeHead(304, head);
1377
1598
  return void res.end();
1378
1599
  }
1600
+ if (!acceptsGzip(req))
1601
+ return void gunzip(gz, (e, plain) => {
1602
+ if (e)
1603
+ return res.destroy(e);
1604
+ res.writeHead(200, head);
1605
+ res.end(plain);
1606
+ });
1379
1607
  res.writeHead(200, { ...head, "content-encoding": "gzip" });
1380
1608
  res.end(gz);
1381
1609
  }
@@ -1404,7 +1632,7 @@ async function main() {
1404
1632
  // an installed package's server runs under the supervisor, which stays while it restarts into
1405
1633
  // another version (UpdateSpec decision 5); `--updates off`, and a checkout, run it as they are
1406
1634
  if (o.cmd === "serve" && FROM_PACKAGE && o.updates !== "off" && process.env.VISUALPROOF_SUPERVISED !== "1") {
1407
- const site = projectDirs(resolve(o.path), o.site, o.cache).site;
1635
+ const site = o.remote ? deploySiteOf(o) : projectDirs(resolve(o.path), o.site, o.cache).site;
1408
1636
  process.exit(await supervise({ installedRoot: PACKAGE_ROOT, cacheRoot: o.cache ? resolve(o.cache) : cacheHome(), argv: process.argv.slice(2), site, mode: o.updates }));
1409
1637
  }
1410
1638
  // a stop asked before the server can stop gracefully (it reads the project, takes the site) ends
@@ -1421,13 +1649,18 @@ async function main() {
1421
1649
  // whatever fails ends it, with status 1)
1422
1650
  if (o.cmd !== "artwork")
1423
1651
  process.on("unhandledRejection", (e) => console.error("unhandled:", e instanceof Error ? e.message : e));
1652
+ // following a branch (DeploySpec): its clone in the cache, made at the first start, is the project
1653
+ const deploy = o.remote ? await openDeployment(o) : null;
1654
+ if (o.remote && !deploy)
1655
+ return;
1424
1656
  let project;
1425
1657
  try {
1426
- project = openProject(o.path, o.roots, o.graph === null);
1658
+ // a branch's clone is read before its build: the server builds it
1659
+ project = openProject(deploy ? deploy.folder.checkout : o.path, o.roots, !deploy && o.graph === null);
1427
1660
  }
1428
1661
  catch (e) {
1429
1662
  if (e instanceof ProjectError) {
1430
- console.error(`visualproof: ${e.message}`);
1663
+ console.error(`visualproof: ${deploy ? `${deploy.branch} of ${deploy.remote.source ?? deploy.remote.url}, at ${shortCommit(deploy.head)}: ` : ""}${e.message}`);
1431
1664
  return endNotTheCode(1);
1432
1665
  }
1433
1666
  throw e;
@@ -1435,7 +1668,8 @@ async function main() {
1435
1668
  // a picture: the site read, never made, locked or written (ExportSpec decision 21)
1436
1669
  if (o.cmd === "artwork")
1437
1670
  return artworkCommand(project, o);
1438
- const dirs = projectDirs(project.root, o.site, o.cache);
1671
+ // a branch's site is the address's and the branch's, wherever the cache is
1672
+ const dirs = { ...projectDirs(project.root, o.site, o.cache), ...(deploy && o.site === null ? { site: deploySite(deploy.remote, deploy.branch) } : {}) };
1439
1673
  openSite(dirs.site);
1440
1674
  mkdirSync(dirs.cache, { recursive: true });
1441
1675
  // one server at a time writes a site; an export only reads it
@@ -1512,8 +1746,31 @@ async function main() {
1512
1746
  live.invites.close();
1513
1747
  live.readOnly.close();
1514
1748
  });
1749
+ // the branch followed: asked every --poll minutes, each new head built in turn (DeploySpec)
1750
+ const deployment = deploy
1751
+ ? new Deployment({
1752
+ remote: deploy.remote,
1753
+ branch: deploy.branch,
1754
+ folder: deploy.folder,
1755
+ project,
1756
+ roots: o.roots,
1757
+ everyMs: (o.poll ?? DEFAULT_POLL_MINUTES) * 60_000,
1758
+ head: deploy.head,
1759
+ hooks: {
1760
+ reading: () => live.reading,
1761
+ // the usage pass of the build before is cut short: what it finished is kept
1762
+ starting: () => live.usage.cancel(),
1763
+ toolchainChanged: () => hover.toolchainChanged(),
1764
+ // the pages are told at the live loop's next look, within a second
1765
+ changed: () => live.lookSoon(),
1766
+ log: (l) => live.say(l),
1767
+ ended: () => live.reread(),
1768
+ },
1769
+ })
1770
+ : null;
1771
+ live.deploy = deployment;
1515
1772
  const exporter = new Exporter(dirs.cache);
1516
- const app = new App(live, hover, ids, new AgentApi(live, hover, o.agents), key ? new Access(key.key) : null, exporter, o.publicUrl, o.publicRead);
1773
+ const app = new App(live, hover, ids, new AgentApi(live, hover, o.agents), key ? new Access(key.key) : null, exporter, o.publicUrl, o.publicRead, o.allowedHosts);
1517
1774
  const server = createServer((req, res) => app.handle(req, res));
1518
1775
  const version = packageVersion();
1519
1776
  // run by the supervisor, which starts it again in another version (UpdateSpec decision 5)
@@ -1535,6 +1792,8 @@ async function main() {
1535
1792
  stopping = true;
1536
1793
  exitStatus = status;
1537
1794
  updates.stop();
1795
+ // a build going on is stopped with the programs, and done again at the next start
1796
+ deployment?.stop();
1538
1797
  server.close();
1539
1798
  live.end(why);
1540
1799
  hover.stop();
@@ -1592,13 +1851,65 @@ async function main() {
1592
1851
  console.log(` editor: ${o.editor ?? "no link unless a reader sets one"}`);
1593
1852
  console.log(` agents: ${o.agents} — their API is http://${o.host}:${o.port}/api/agent`);
1594
1853
  console.log(` usage pass: ${o.graph ? "none for a saved graph" : o.jobs > 0 ? `${o.jobs} module(s) at a time` : "off (--jobs 0)"}`);
1595
- 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"}`);
1854
+ // what the pass's workers may hold on a project on Mathlib, against what the machine has
1855
+ const memory = o.graph || o.jobs <= 0 ? null : jobsAdvice(o.jobs, onMathlib(project.root));
1856
+ if (memory)
1857
+ console.log(` memory: ${inGB(freemem())} available; on Mathlib the pass's workers may hold up to ${inGB(WORKER_PEAK)} each, ${inGB(memory.need)} at ${o.jobs}: ` +
1858
+ `--jobs ${memory.fits} if memory runs short (it starts fewer while less than ${inGB(memoryFloor())} is available)`);
1859
+ 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, by its address, localhost${[...(o.publicUrl ? [urlHost(o.publicUrl)] : []), ...o.allowedHosts].map((n) => `, ${n}`).join("")} (other names are refused: --allowed-host)`}`);
1596
1860
  console.log(` version: ${version}; updates ${updatesInWords(o.updates, version, supervised)}`);
1861
+ if (deployment) {
1862
+ const d = deployment.status(true);
1863
+ console.log(` following: ${d.branch} of ${d.source ?? deployment.remote.url}, asked every ${o.poll ?? DEFAULT_POLL_MINUTES} min`);
1864
+ console.log(` clone: ${deployment.folder.checkout}`);
1865
+ console.log(` builds: ${d.built ? `the tree holds the build of ${shortCommit(d.built)}${deployment.holds() ? ", cut short: it is done again" : ""}` : `none yet: the first, of ${shortCommit(deploy.head)}, starts now, and the page says so until it is done`}; their logs in ${deployment.folder.logs}`);
1866
+ }
1597
1867
  recordVersion(live, version, supervised);
1598
1868
  process.send?.({ vp: "listening", version });
1599
1869
  updates.start();
1600
1870
  });
1601
1871
  live.start();
1872
+ deployment?.start();
1873
+ }
1874
+ /** The site a branch's server keeps, as the supervisor finds it (UpdateSpec decision 7): `--site`,
1875
+ * else the address's and the branch's — the default branch as it was last asked, without the network;
1876
+ * null at a first start without --branch, which the server alone resolves. */
1877
+ function deploySiteOf(o) {
1878
+ if (o.site !== null)
1879
+ return resolve(o.site);
1880
+ const branch = o.branch ?? recordedDefault(o.cache ? resolve(o.cache) : cacheHome(), o.remote.url);
1881
+ return branch ? deploySite(o.remote, branch) : null;
1882
+ }
1883
+ /** A branch's deployment as the server starts (DeploySpec decisions 1–2): the branch (the remote's
1884
+ * default where none is given), its folder in the cache taken for this server, its clone made at
1885
+ * the first start. Null where it cannot be had: said, and the server ends, which is not its code. */
1886
+ async function openDeployment(o) {
1887
+ const remote = o.remote;
1888
+ const cacheRoot = o.cache ? resolve(o.cache) : cacheHome();
1889
+ const branch = await branchToFollow(remote, o.branch, cacheRoot);
1890
+ if (typeof branch !== "string") {
1891
+ console.error(`visualproof: ${remote.source ?? remote.url}: ${branch.error}`);
1892
+ endNotTheCode(1);
1893
+ return null;
1894
+ }
1895
+ const folder = deployFolder(cacheRoot, remote, branch);
1896
+ try {
1897
+ process.on("exit", lockDeployment(folder, remote, branch));
1898
+ }
1899
+ catch (e) {
1900
+ if (!(e instanceof DeployBusy))
1901
+ throw e;
1902
+ console.error(`visualproof: ${e.message}`);
1903
+ endNotTheCode(1);
1904
+ return null;
1905
+ }
1906
+ const c = await ensureClone(remote, branch, folder, (l) => console.log(l));
1907
+ if ("error" in c) {
1908
+ console.error(`visualproof: ${c.error}`);
1909
+ endNotTheCode(1);
1910
+ return null;
1911
+ }
1912
+ return { remote, branch, folder, head: c.commit };
1602
1913
  }
1603
1914
  /** What the server does with its releases, for its first lines (UpdateSpec decisions 2–4, 13). */
1604
1915
  function updatesInWords(mode, version, supervised) {
@@ -1696,11 +2007,11 @@ async function artwork(project, o, fail) {
1696
2007
  // the site's layout memory read and never written, nor the views laid out written to the cache;
1697
2008
  // without a site, none read: the board as a new site lays it out
1698
2009
  const prep = await prepare(project, dirs, o.graph, log, { ...(ex ? { extraction: ex } : {}), readOnlySite: true, ...(site ? {} : { freshLayout: true }) });
1699
- const kept = site ? readProjectView(site, LAYOUT_VERSION) : { view: null };
2010
+ const kept = site ? readProjectView(site, LAYOUT_VERSION) : { view: null, notes: 0 };
1700
2011
  if (kept.why)
1701
2012
  console.error(`visualproof artwork: the site's views cannot be read (${kept.why}): the Project view as a new site has it`);
1702
2013
  const review = site ? new ReviewStore(project.root, site).data : null;
1703
- const a = makeArtwork(prep, review, projectView(kept.view), { recipe, screen: o.screen, name: outBase ? basename(outBase) : null, root: project.root });
2014
+ const a = makeArtwork(prep, review, projectView(kept.view), { recipe, screen: o.screen, name: outBase ? basename(outBase) : null, root: project.root, projectNotes: kept.notes });
1704
2015
  if (!("svg" in a)) {
1705
2016
  for (const p of a.problems)
1706
2017
  console.error(`visualproof artwork: ${p}`);