visualproof 0.5.0 → 0.6.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 (58) hide show
  1. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  2. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  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 +125 -115
  16. package/dist/assets/tips/tour.webp +0 -0
  17. package/dist/mcp/visualproof-mcp.mjs +20 -9
  18. package/dist/server/access.js +28 -0
  19. package/dist/server/agent.js +137 -49
  20. package/dist/server/askfollow.js +1 -1
  21. package/dist/server/deploy.js +204 -53
  22. package/dist/server/invites.js +113 -20
  23. package/dist/server/live.js +125 -28
  24. package/dist/server/main.js +216 -69
  25. package/dist/server/mcptools.js +33 -20
  26. package/dist/server/presence.js +3 -3
  27. package/dist/server/prompt.js +8 -3
  28. package/dist/server/readonlygate.js +4 -4
  29. package/dist/server/reviewapi.js +51 -17
  30. package/dist/server/talk.js +231 -115
  31. package/dist/server/tokens.js +10 -2
  32. package/dist/shared/build.js +35 -1
  33. package/dist/shared/collab.js +8 -0
  34. package/dist/shared/keys.js +66 -37
  35. package/dist/shared/lostfound.js +1 -0
  36. package/dist/shared/mentions.js +83 -0
  37. package/dist/shared/query.js +13 -4
  38. package/dist/shared/review.js +91 -21
  39. package/dist/shared/reviewqueue.js +6 -1
  40. package/dist/web/bundle/app.js +3068 -1928
  41. package/dist/web/index.html +45 -9
  42. package/dist/web/src/reviewqueue.js +52 -19
  43. package/dist/web/src/trust.js +271 -0
  44. package/dist/web/style.css +181 -70
  45. package/docs/agent-api/README.md +13 -11
  46. package/docs/agent-api/advice.md +8 -2
  47. package/docs/agent-api/export.md +1 -1
  48. package/docs/agent-api/following.md +11 -12
  49. package/docs/agent-api/history.md +3 -2
  50. package/docs/agent-api/mcp.md +15 -15
  51. package/docs/agent-api/notes.md +1 -1
  52. package/docs/agent-api/reading.md +2 -2
  53. package/docs/agent-api/requests.md +12 -15
  54. package/docs/agent-api/talking.md +60 -55
  55. package/docs/agent-api/tcb.md +21 -21
  56. package/docs/agent-api/views.md +3 -4
  57. package/docs/agent-api/words.md +8 -8
  58. package/package.json +2 -1
@@ -8,10 +8,11 @@
8
8
  // changes the tree, nothing is read from it, and the board on show stays the last build's.
9
9
  //
10
10
  // What is kept, in the deployment's folder of the cache (`<cache>/deploy/<repo>-<hash>/`): the
11
- // clone, `state.json` (the commit the tree's outputs are of, the build going on, the last one
12
- // that ended, the newest head seen), each build's log (`logs/`), and `.lock`: one server follows a
13
- // branch with a cache at a time. A build cut short (a restart into a patch, a stop) is done again
14
- // by the next server, Lake keeping what it finished.
11
+ // clone (`clone/<repo>/`, whatever the repository is called), `state.json` (the commit the tree's
12
+ // outputs are of, the one checked out, the build going on, the last one that ended, the newest head
13
+ // seen), each build's log (`logs/`), and `.lock`: one server follows a branch with a cache at a
14
+ // time. A build cut short (a restart into a patch, a stop) is done again by the next server, Lake
15
+ // keeping what it finished.
15
16
  //
16
17
  // Git and Lake are run with argument arrays, never a shell; the address is checked against the
17
18
  // schemes followed, the branch by git (`check-ref-format --branch`); nothing that git or Lake starts
@@ -21,11 +22,11 @@ import { spawn, spawnSync } from "node:child_process";
21
22
  import { createHash } from "node:crypto";
22
23
  import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
23
24
  import { homedir, tmpdir } from "node:os";
24
- import { join } from "node:path";
25
+ import { basename, dirname, join, relative } from "node:path";
25
26
  import { shortCommit, slimDeploy } from "../shared/deploy.js";
26
27
  import { childEnv, DETACH, end, grouped } from "./children.js";
27
28
  import { dataHome, lockSite, SiteBusy } from "./dirs.js";
28
- import { sourceAddress } from "./history.js";
29
+ import { buildTime, sourceAddress } from "./history.js";
29
30
  import { openProject, ProjectError } from "./project.js";
30
31
  /** How often the remote is asked by default (DeploySpec decision 3). */
31
32
  export const DEFAULT_POLL_MINUTES = 2;
@@ -37,8 +38,11 @@ const ASK_MS = 60_000;
37
38
  const GIT_MS = 10 * 60_000;
38
39
  /** Mathlib's cache (`lake exe cache get`): it compiles the cache program first */
39
40
  const CACHE_MS = 30 * 60_000;
40
- /** `lake build`, past which the build is stopped and failed (proposed: DeploySpec decision 14) */
41
- export const BUILD_MS = 6 * 3600_000;
41
+ /** `--build-timeout`: the hours of `lake build` past which the build is stopped and failed
42
+ * (DeploySpec decision 14), by default and the least and most it takes: fractions of an hour too */
43
+ export const DEFAULT_BUILD_HOURS = 6;
44
+ export const MIN_BUILD_HOURS = 0.05;
45
+ export const MAX_BUILD_HOURS = 168;
42
46
  /** the most of a build's log kept for the pages, in lines and characters */
43
47
  const TAIL_LINES = 60;
44
48
  const TAIL_CHARS = 8000;
@@ -137,15 +141,42 @@ export function branchProblem(name) {
137
141
  return `git could not be run (${r.error.message}): following a branch needs git`;
138
142
  return r.status === 0 && r.stdout.trim() === name ? null : no;
139
143
  }
144
+ // ---------------------------------------------------------------- how long a build may take
145
+ /** `--build-timeout <hours>` read (DeploySpec decision 14): the hours, or why they are refused. */
146
+ export function parseBuildHours(v) {
147
+ const h = Number(v);
148
+ if (/^\d+(\.\d+)?$/.test(v) && h >= MIN_BUILD_HOURS && h <= MAX_BUILD_HOURS)
149
+ return h;
150
+ return { error: `--build-timeout ${v.slice(0, 40)}: say after how many hours a build is stopped, from ${MIN_BUILD_HOURS} (3 min) to ${MAX_BUILD_HOURS} (a week); 1.5 is an hour and a half` };
151
+ }
152
+ /** A build's limit as it is said: `6 hours`, `1 hour`, `1 h 30 min`, `3 min`, `4 min 12 s`. */
153
+ export function limitInWords(ms) {
154
+ if (ms < 60_000)
155
+ return `${Number((ms / 1000).toFixed(1))} s`;
156
+ const s = Math.round(ms / 1000);
157
+ if (s % 3600 === 0)
158
+ return s === 3600 ? "1 hour" : `${s / 3600} hours`;
159
+ const h = Math.floor(s / 3600), m = Math.floor((s % 3600) / 60), r = s % 60;
160
+ return [h ? `${h} h` : "", m ? `${m} min` : "", r ? `${r} s` : ""].filter(Boolean).join(" ");
161
+ }
140
162
  // ---------------------------------------------------------------- where it is kept
141
163
  /** A deployment's name among the others: the repository's name and a hash of the address and the
142
164
  * branch. */
143
165
  export function deployKey(remote, branch) {
144
166
  return `${remote.name}-${createHash("sha1").update(`${remote.url}\0${branch}`).digest("hex").slice(0, 8)}`;
145
167
  }
168
+ /** What the deployment's folder keeps of its own beside the clone of 0.5.0, which was named after
169
+ * its repository there (DeploySpec decision 2): a repository named so is moved out of their way. */
170
+ const OWN = /^(?:logs|mathlib-cache|state\.json(?:\.tmp-\d+)?)$/;
171
+ /** The deployment's folder: the clone in `clone/<repo>/`, apart from what the folder keeps of its
172
+ * own, whatever the repository is called (DeploySpec decision 2); a clone made by 0.5.0, named
173
+ * after its repository beside them, is kept where it is — never cloned again — unless its name is
174
+ * one of theirs (ensureClone moves it). */
146
175
  export function deployFolder(cacheRoot, remote, branch) {
147
176
  const dir = join(cacheRoot, "deploy", deployKey(remote, branch));
148
- return { dir, checkout: join(dir, remote.name), state: join(dir, "state.json"), logs: join(dir, "logs") };
177
+ const was = join(dir, remote.name);
178
+ const checkout = !OWN.test(remote.name) && existsSync(join(was, ".git")) ? was : join(dir, "clone", remote.name);
179
+ return { dir, checkout, state: join(dir, "state.json"), logs: join(dir, "logs"), mathlib: join(dir, "mathlib-cache") };
149
180
  }
150
181
  /** The site of a deployment, without `--site`: under the data home by the address and the branch,
151
182
  * so that the review stays where it is whatever `--cache` says. */
@@ -227,10 +258,23 @@ export function noPrompts(env, ssh = configuredSsh()) {
227
258
  export function gitEnv(remote) {
228
259
  return { ...noPrompts(gitBase()), GIT_ALLOW_PROTOCOL: remote.kind };
229
260
  }
261
+ export const MATHLIB_CACHES = ["shared", "own"];
262
+ /** Mathlib's cache as the user's builds find it, as Mathlib's cache program reads it
263
+ * (`Cache/IO.lean`, `CACHEDIR`): `MATHLIB_CACHE_DIR`, else `$XDG_CACHE_HOME/mathlib`, else
264
+ * `~/.cache/mathlib`. */
265
+ export function sharedMathlibCache(env = process.env, home = homedir()) {
266
+ return env.MATHLIB_CACHE_DIR || join(env.XDG_CACHE_HOME || join(home, ".cache"), "mathlib");
267
+ }
230
268
  /** Lake's environment for a build: the server's without what is its own — no access key or token
231
- * of VisualProof's is in it — and no prompts for the git it runs for the dependencies. */
232
- export function buildEnv() {
233
- return noPrompts(gitBase());
269
+ * of VisualProof's is in it — and no prompts for the git it runs for the dependencies. With
270
+ * `mathlib`, Mathlib's cache is that folder (`MATHLIB_CACHE_DIR`, which every Mathlib since
271
+ * February 2025, Lean v4.17, reads: every supported toolchain's); `XDG_CACHE_HOME`, which an older
272
+ * one read, is left as it is, since Lake's cache and git's credential cache are found by it too. */
273
+ export function buildEnv(mathlib = null) {
274
+ const env = noPrompts(gitBase());
275
+ if (mathlib)
276
+ env.MATHLIB_CACHE_DIR = mathlib;
277
+ return env;
234
278
  }
235
279
  /** Run `cmd` with `args` — an array, never through a shell — as a group of its own (what it starts
236
280
  * ends with it: server/children.ts), stopped past `timeoutMs`; what it writes goes to `onText` as
@@ -320,6 +364,14 @@ export async function branchToFollow(remote, given, cacheRoot) {
320
364
  * nothing half made. The commit checked out, or why there is none. */
321
365
  export async function ensureClone(remote, branch, folder, log) {
322
366
  const env = gitEnv(remote);
367
+ // a clone of 0.5.0 named as what its folder keeps of its own (a repository called logs): moved
368
+ // into the clone's place, what it built with it
369
+ const was = join(folder.dir, remote.name);
370
+ if (was !== folder.checkout && OWN.test(remote.name) && existsSync(join(was, ".git")) && !existsSync(folder.checkout)) {
371
+ mkdirSync(dirname(folder.checkout), { recursive: true });
372
+ renameSync(was, folder.checkout);
373
+ log(`the clone moved to ${folder.checkout}: its folder keeps a ${remote.name} of its own`);
374
+ }
323
375
  if (existsSync(join(folder.checkout, ".git"))) {
324
376
  const r = await git(["-C", folder.checkout, "rev-parse", "--verify", "HEAD^{commit}"], env);
325
377
  const c = r.stdout.trim();
@@ -327,12 +379,13 @@ export async function ensureClone(remote, branch, folder, log) {
327
379
  return { commit: c, made: false };
328
380
  return { error: `the clone ${folder.checkout} cannot be read (${gitWhy(r)}): remove it, and it is made again` };
329
381
  }
330
- mkdirSync(folder.dir, { recursive: true });
382
+ const place = dirname(folder.checkout);
383
+ mkdirSync(place, { recursive: true });
331
384
  // what a start that died midway left
332
- for (const f of readdirSync(folder.dir)) {
333
- const m = new RegExp(`^${remote.name.replace(/[.]/g, "\\.")}\\.tmp-(\\d+)$`).exec(f);
385
+ for (const f of readdirSync(place)) {
386
+ const m = new RegExp(`^${basename(folder.checkout).replace(/[.]/g, "\\.")}\\.tmp-(\\d+)$`).exec(f);
334
387
  if (m && !alive(Number(m[1])))
335
- rmSync(join(folder.dir, f), { recursive: true, force: true });
388
+ rmSync(join(place, f), { recursive: true, force: true });
336
389
  }
337
390
  const tmp = `${folder.checkout}.tmp-${process.pid}`;
338
391
  rmSync(tmp, { recursive: true, force: true });
@@ -395,29 +448,91 @@ export function onMathlib(root) {
395
448
  return false;
396
449
  }
397
450
  }
451
+ /** Whether the Mathlib checked out in the project reads `MATHLIB_CACHE_DIR` (since February 2025,
452
+ * #21480; every supported toolchain's does): its cache program's source says so (`Cache/IO.lean`,
453
+ * `CACHEDIR`). One before keeps its cache by `XDG_CACHE_HOME` alone: the user's. */
454
+ export function mathlibReadsCacheDir(root) {
455
+ let packages = join(".lake", "packages");
456
+ try {
457
+ const m = JSON.parse(readFileSync(join(root, "lake-manifest.json"), "utf8"));
458
+ if (typeof m.packagesDir === "string" && m.packagesDir)
459
+ packages = m.packagesDir;
460
+ }
461
+ catch {
462
+ // Lake's default
463
+ }
464
+ try {
465
+ return readFileSync(join(root, packages, "mathlib", "Cache", "IO.lean"), "utf8").includes('"MATHLIB_CACHE_DIR"');
466
+ }
467
+ catch {
468
+ return false;
469
+ }
470
+ }
398
471
  // ---------------------------------------------------------------- a build's log
472
+ /** What a build's log names more briefly for the pages (DeploySpec decision 11, SECURITY.md), the
473
+ * longest path first: the clone's folder `.`, the deployment's folder that holds it (its logs, its
474
+ * own Mathlib cache) from it (`../..`), and the home `~` — each as given and as resolved, since Lean
475
+ * prints paths resolved (macOS's /var is /private/var), git and Lake the ones given. A home reached
476
+ * through a symlink, or a folder under it that is one, prints resolved too: the folders elan and
477
+ * Lake use under it — `~/.elan` (or `$ELAN_HOME`), `~/.cache` (or `$XDG_CACHE_HOME`; Lake's cache,
478
+ * Mathlib's), `$MATHLIB_CACHE_DIR` where it is set — read by the path given, under `~`, whatever
479
+ * they resolve to (here `~/.elan` → `/data/.elan`: `/data/.elan/toolchains/…/bin/lean` reads
480
+ * `~/.elan/toolchains/…/bin/lean`). A folder outside the home keeps the path given. */
481
+ export function logNames(root, o = {}) {
482
+ const home = o.home ?? homedir();
483
+ const env = o.env ?? process.env;
484
+ // a folder not there yet (the clone before the first build's) as its nearest folder resolves
485
+ const resolved = (p) => {
486
+ try {
487
+ return realpathSync(p);
488
+ }
489
+ catch {
490
+ const up = dirname(p);
491
+ return up === p ? p : join(resolved(up), basename(p));
492
+ }
493
+ };
494
+ const names = new Map();
495
+ const name = (path, as) => {
496
+ for (const from of [path, resolved(path)])
497
+ if (from.length > 1 && !names.has(from))
498
+ names.set(from, as);
499
+ };
500
+ name(root, ".");
501
+ if (o.folder)
502
+ name(o.folder, relative(root, o.folder) || ".");
503
+ if (home && home.length > 1) {
504
+ const brief = (p) => (p === home ? "~" : p.startsWith(`${home}/`) ? `~${p.slice(home.length)}` : p);
505
+ for (const d of [env.ELAN_HOME || join(home, ".elan"), env.XDG_CACHE_HOME || join(home, ".cache"), env.MATHLIB_CACHE_DIR])
506
+ if (d)
507
+ name(d, brief(d));
508
+ name(home, "~");
509
+ }
510
+ return [...names].sort((a, b) => b[0].length - a[0].length);
511
+ }
512
+ /** What names a text's paths as `names` (the longest first) says, each where it is a whole path or
513
+ * begins one (not `/home/ann` in `/home/anne`, nor in `/mnt/home/ann`), once: what is put in stays. */
514
+ export function pathNamer(names) {
515
+ if (!names.length)
516
+ return (text) => text;
517
+ const to = new Map(names);
518
+ const any = names.map(([from]) => from.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&")).join("|");
519
+ const re = new RegExp(`(?<![\\w.~+@-])(?:${any})(?![\\w.~+@-])`, "g");
520
+ return (text) => text.replace(re, (m) => to.get(m) ?? m);
521
+ }
399
522
  /** A build's log: everything its programs wrote, in `logs/<commit>.log` of the deployment (a build
400
- * done again writes it again), and its end for the pages, where the clone's folder reads `.` and the
401
- * home `~`, colours and redrawn lines taken out. */
523
+ * done again writes it again), and its end for the pages, its paths named briefly (`logNames`: the
524
+ * clone's folder `.`, the home `~`), colours and redrawn lines taken out. */
402
525
  export class BuildLog {
403
526
  file;
404
527
  fd = null;
405
528
  lines = [];
406
529
  partial = "";
407
- /** the clone's path as the log may write it, the longest first: Lean prints the path resolved
408
- * (macOS's /var is /private/var), git and Lake the one given */
409
- roots;
410
- constructor(dir, commit, root) {
530
+ /** the paths the pages are given by another name (logNames) */
531
+ named;
532
+ constructor(dir, commit, root, o = {}) {
411
533
  mkdirSync(dir, { recursive: true });
412
534
  this.file = join(dir, `${commit}.log`);
413
- let real = root;
414
- try {
415
- real = realpathSync(root);
416
- }
417
- catch {
418
- // not there yet: the path as given
419
- }
420
- this.roots = [...new Set([real, root])].sort((a, b) => b.length - a.length);
535
+ this.named = pathNamer(logNames(root, o));
421
536
  try {
422
537
  this.fd = openSync(this.file, "w", 0o600);
423
538
  }
@@ -456,12 +571,7 @@ export class BuildLog {
456
571
  /** its end, as the pages are given it: its last `n` lines, the one being written included */
457
572
  tail(n = TAIL_LINES) {
458
573
  const last = this.partial.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").split("\r").pop().trimEnd();
459
- const home = homedir();
460
- let t = [...this.lines, ...(last ? [last] : [])].slice(-n).join("\n");
461
- for (const r of this.roots)
462
- t = t.split(r).join(".");
463
- if (home && home.length > 1)
464
- t = t.split(home).join("~");
574
+ const t = this.named([...this.lines, ...(last ? [last] : [])].slice(-n).join("\n"));
465
575
  return t.length > TAIL_CHARS ? `…${t.slice(-TAIL_CHARS)}` : t;
466
576
  }
467
577
  close() {
@@ -510,6 +620,8 @@ export class Deployment {
510
620
  running = null;
511
621
  env;
512
622
  lakeEnv;
623
+ /** `lake build` past which a build is stopped (DeploySpec decision 14) */
624
+ buildMs;
513
625
  /** every build tried since the start, in order: what the tests read */
514
626
  tried = [];
515
627
  /** the log of the build going on */
@@ -520,22 +632,24 @@ export class Deployment {
520
632
  this.branch = o.branch;
521
633
  this.folder = o.folder;
522
634
  this.env = gitEnv(o.remote);
523
- this.lakeEnv = buildEnv();
635
+ this.lakeEnv = buildEnv(o.mathlibCache === "own" ? o.folder.mathlib : null);
636
+ this.buildMs = o.buildMs ?? DEFAULT_BUILD_HOURS * 3600_000;
524
637
  this.state = this.read();
525
638
  const head = this.headNow();
526
- // the tree is one build's only where the outputs are of the commit checked out and no build
527
- // was going on
528
- this.interrupted = this.state.building !== null || (this.state.outputs !== null && head !== null && head !== this.state.outputs.commit);
639
+ // the tree is one build's only where the commit checked out is the one whose build last ran in
640
+ // it and no build was going on
641
+ this.interrupted = this.state.building !== null || (this.state.ran !== null && head !== null && head !== this.state.ran);
529
642
  this.want = this.state.head?.commit ?? this.state.building?.commit ?? o.head ?? head;
530
643
  this.done = this.interrupted ? null : this.state.done;
531
644
  if (this.state.building)
532
645
  o.hooks.log(`build: the build of ${shortCommit(this.state.building.commit)} was cut short (a restart, a stop): it is done again`);
533
646
  }
534
647
  read() {
535
- const fresh = { version: 1, url: this.remote.url, branch: this.branch, outputs: null, building: null, done: null, last: null, head: null };
648
+ const fresh = { version: 1, url: this.remote.url, branch: this.branch, outputs: null, ran: null, building: null, done: null, last: null, head: null };
536
649
  try {
537
650
  const s = JSON.parse(readFileSync(this.folder.state, "utf8"));
538
- return { ...fresh, ...s, version: 1, url: this.remote.url, branch: this.branch };
651
+ // 0.5.0's: the commit whose build last ran is the one its outputs were said to be of
652
+ return { ...fresh, ...s, ran: s.ran ?? s.outputs?.commit ?? null, version: 1, url: this.remote.url, branch: this.branch };
539
653
  }
540
654
  catch {
541
655
  return fresh;
@@ -582,8 +696,9 @@ export class Deployment {
582
696
  get busy() {
583
697
  return this.running !== null;
584
698
  }
585
- /** The commit what the tree holds was built from, and the branch: the history's for each build it
586
- * reads (HistorySpec decision 4). */
699
+ /** The commit what the tree's outputs were built from, and the branch: the history's for each
700
+ * build it reads (HistorySpec decision 4) — the last whose build wrote outputs, not a failed one
701
+ * that wrote none (DeploySpec decision 6). */
587
702
  commit() {
588
703
  return this.state.outputs ? { hash: this.state.outputs.commit, branch: this.branch } : null;
589
704
  }
@@ -663,6 +778,11 @@ export class Deployment {
663
778
  this.kick();
664
779
  });
665
780
  }
781
+ /** The commit built next where none is going on: the newest head seen, where it was not tried
782
+ * (the server's first lines say it). */
783
+ toBuild() {
784
+ return this.want && this.want !== this.done && this.want !== this.later ? this.want : null;
785
+ }
666
786
  /** Until the build going on and those waiting are done: what the tests wait for. */
667
787
  async settled() {
668
788
  while (this.running || this.asking || this.retry)
@@ -685,7 +805,7 @@ export class Deployment {
685
805
  this.o.hooks.changed();
686
806
  const short = shortCommit(commit);
687
807
  const say = this.o.hooks.log;
688
- const log = (this.log = new BuildLog(this.folder.logs, commit, this.folder.checkout));
808
+ const log = (this.log = new BuildLog(this.folder.logs, commit, this.folder.checkout, { folder: this.folder.dir }));
689
809
  const g = (args, ms = GIT_MS) => {
690
810
  log.say(`$ git ${args.join(" ")}`);
691
811
  return git(["-C", this.folder.checkout, ...args], this.env, ms, (t) => log.text(t));
@@ -736,10 +856,13 @@ export class Deployment {
736
856
  this.step("cache");
737
857
  say(`build: ${short}: getting Mathlib's cache`);
738
858
  for (let n = 1; n <= 2 && !this.stopped; n++) {
739
- log.say(`$ lake exe cache get`);
859
+ // the deployment's own cache, beside the clone in its folder (DeploySpec decision 2)
860
+ log.say(`$ ${this.o.mathlibCache === "own" ? `MATHLIB_CACHE_DIR=${relative(this.folder.checkout, this.folder.mathlib)} ` : ""}lake exe cache get`);
740
861
  const c = await run(lake, ["exe", "cache", "get"], { cwd: this.folder.checkout, env: this.lakeEnv, timeoutMs: CACHE_MS, onText: (t) => log.text(t) });
741
- if (c.code === 0)
862
+ if (c.code === 0) {
863
+ await this.cleanMathlibCache(lake, log);
742
864
  break;
865
+ }
743
866
  // Lake builds what the cache did not give
744
867
  log.say(`Mathlib's cache could not be had (${c.error ?? (c.timedOut ? "it took too long" : `exit ${c.code}`)})${n === 1 ? ": trying again" : ": lake build builds what it lacks"}`);
745
868
  }
@@ -749,7 +872,10 @@ export class Deployment {
749
872
  this.step("build");
750
873
  say(`build: ${short}: lake build${this.o.roots.length ? ` ${this.o.roots.join(" ")}` : ""}`);
751
874
  log.say(`$ lake build${this.o.roots.length ? ` ${this.o.roots.join(" ")}` : ""}`);
752
- const b = await run(lake, ["build", ...this.o.roots], { cwd: this.folder.checkout, env: this.lakeEnv, timeoutMs: BUILD_MS, onText: (t) => log.text(t) });
875
+ // the project's newest `.olean` before the build: whether it wrote any (as the history tells a
876
+ // new build: HistorySpec decision 4)
877
+ const before = buildTime(this.o.project);
878
+ const b = await run(lake, ["build", ...this.o.roots], { cwd: this.folder.checkout, env: this.lakeEnv, timeoutMs: this.buildMs, onText: (t) => log.text(t) });
753
879
  // cut short by the server's stop: done again at the next start
754
880
  if (this.stopped)
755
881
  return;
@@ -757,8 +883,14 @@ export class Deployment {
757
883
  await this.restore(log);
758
884
  return ended({ ok: false, retry: true, error: `lake could not be run: ${b.error}` });
759
885
  }
760
- // the tree is this build's, whatever came of it
761
- this.state.outputs = { commit, at: new Date().toISOString() };
886
+ const ok = b.code === 0 && !b.timedOut;
887
+ // the tree is this build's, whatever came of it: checked out at its commit, its failed files
888
+ // shown as such; its outputs are, where it built the commit or wrote any. A failed build that
889
+ // wrote none leaves the board on the last build that did, which is what is said built (the
890
+ // owner's decision of 2026-10-19)
891
+ this.state.ran = commit;
892
+ if (ok || buildTime(this.o.project) > before)
893
+ this.state.outputs = { commit, at: new Date().toISOString() };
762
894
  this.state.building = null;
763
895
  this.interrupted = false;
764
896
  // the modules a library's globs give, now that they are built
@@ -768,8 +900,10 @@ export class Deployment {
768
900
  catch {
769
901
  // read as it was after the checkout
770
902
  }
771
- const ok = b.code === 0 && !b.timedOut;
772
- return ended({ ok, exit: b.code, ...(b.timedOut ? { error: `it took longer than ${BUILD_MS / 3600_000} hours: stopped` } : {}) });
903
+ // stopped past the limit: failed, and not tried again (DeploySpec decision 14)
904
+ if (b.timedOut)
905
+ log.say(`lake build took longer than ${limitInWords(this.buildMs)} (--build-timeout): stopped`);
906
+ return ended({ ok, exit: b.code, ...(b.timedOut ? { error: `it took longer than ${limitInWords(this.buildMs)} (--build-timeout): stopped` } : {}) });
773
907
  }
774
908
  catch (e) {
775
909
  if (this.stopped)
@@ -783,6 +917,23 @@ export class Deployment {
783
917
  this.log = null;
784
918
  }
785
919
  }
920
+ /** The deployment's own Mathlib cache keeps the version checked out alone (DeploySpec decision 2,
921
+ * the owner's decision of 2026-10-19): after each `lake exe cache get` that succeeded, `lake exe
922
+ * cache clean` deletes the files (`<hash>.ltar`) the Mathlib checked out does not link, which
923
+ * are what `get` fetches. Never the user's cache: only where the deployment has its own, and the
924
+ * Mathlib checked out reads it (one before February 2025 would clean the user's). */
925
+ async cleanMathlibCache(lake, log) {
926
+ if (this.o.mathlibCache !== "own" || this.lakeEnv.MATHLIB_CACHE_DIR !== this.folder.mathlib)
927
+ return;
928
+ if (!mathlibReadsCacheDir(this.folder.checkout)) {
929
+ log.say("Mathlib's cache is not cleaned: this Mathlib does not read MATHLIB_CACHE_DIR (it is older than February 2025), and keeps its cache with the user's");
930
+ return;
931
+ }
932
+ log.say(`$ MATHLIB_CACHE_DIR=${relative(this.folder.checkout, this.folder.mathlib)} lake exe cache clean`);
933
+ const k = await run(lake, ["exe", "cache", "clean"], { cwd: this.folder.checkout, env: this.lakeEnv, timeoutMs: CACHE_MS, onText: (t) => log.text(t) });
934
+ if (k.code !== 0)
935
+ log.say(`Mathlib's cache could not be cleaned (${k.error ?? (k.timedOut ? "it took too long" : `exit ${k.code}`)}): what it holds of other versions stays until the next build`);
936
+ }
786
937
  /** Whether the clone has `commit`. */
787
938
  async has(commit) {
788
939
  const r = await git(["-C", this.folder.checkout, "cat-file", "-e", `${commit}^{commit}`], this.env, ASK_MS);
@@ -792,7 +943,7 @@ export class Deployment {
792
943
  * out at that build's commit again, so that what is read of it, and a restart, are that build's.
793
944
  * Where that cannot be done, the tree stays held until a build ends. */
794
945
  async restore(log) {
795
- const was = this.state.outputs?.commit;
946
+ const was = this.state.ran;
796
947
  if (was) {
797
948
  log.say(`back to ${shortCommit(was)}, the last build's commit`);
798
949
  const co = await git(["-C", this.folder.checkout, "-c", "advice.detachedHead=false", "checkout", "--quiet", "--force", "--detach", was], this.env);
@@ -20,11 +20,22 @@
20
20
  // Share lists every link in force with when it was last used, so that one nobody uses any more is
21
21
  // seen and revoked, which cuts it off at once — its pages' event streams too.
22
22
  //
23
- // The token is shown once, to whoever made it, for them to send: the server keeps only its digest,
24
- // in `<site>/person-invites.json` (readable by its owner alone, as the access key and the agents'
25
- // tokens are). Showing it again would let anyone on the server be that person. Revoked links are
26
- // kept, with every name their holders went by, so that what they did keeps its name; they never let
27
- // anyone in again. When a link was last used is written at most once a minute, as an agent token's.
23
+ // The token is shown once to whoever made it, for them to send, and again to its holder alone (the
24
+ // owner's decision of 2026-10-19): someone who wants to open the site as themselves in another
25
+ // browser, on another device, finds it in the menu under their name. So the server keeps it in
26
+ // full, in `<site>/person-invites.json` (readable by its owner alone, as the access key, the agents'
27
+ // tokens and the read-only links are), beside its digest — what a link opened is compared with, what
28
+ // its cookie is made from, and all that a server before 0.6.0 kept: such a link cannot be shown, and
29
+ // its holder is offered to make it anew. Shown to anyone else, it would let them be that person.
30
+ //
31
+ // Made anew, a link keeps its id — the same person, log and names — under a new secret: the old
32
+ // link, and every cookie made from it, let nobody in from now on, and its pages' event streams end
33
+ // but the one of the page that made it anew, whose browser is given the new cookie. The old digests
34
+ // are kept (the last few), so that a browser the old link let in is told that it no longer does, as
35
+ // a revoked link's is, rather than its page trying again as if the server were down. Revoked links
36
+ // are kept, with every name their holders went by, so that what they did keeps its name; they never
37
+ // let anyone in again. When a link was last used is written at most once a minute, as an agent
38
+ // token's.
28
39
  import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
29
40
  import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
30
41
  import { join } from "node:path";
@@ -41,10 +52,14 @@ const COOKIE = "visualproof_person";
41
52
  const MAX_AGE = 400 * 24 * 3600;
42
53
  const FLUSH_MS = 60_000;
43
54
  const SECRET = /^[A-Za-z0-9_-]{43}$/;
55
+ /** how many of a link's old digests are kept once it was made anew: the browsers they let in are
56
+ * told the link no longer does */
57
+ const REPLACED_KEPT = 16;
44
58
  const sha = (s) => createHash("sha256").update(s).digest();
45
59
  const digestOf = (token) => sha(`visualproof person link\0${token}`).toString("base64url");
46
- /** the cookie's value for a link: its id, and a digest of what is kept of its token */
47
- const cookieValue = (r) => `${r.id}.${sha(`visualproof person cookie\0${r.digest}`).toString("base64url")}`;
60
+ /** the cookie's value for a link: its id, and a digest of the digest of its token (`digest`: an
61
+ * old one of a link made anew) */
62
+ const cookieValue = (r, digest = r.digest) => `${r.id}.${sha(`visualproof person cookie\0${digest}`).toString("base64url")}`;
48
63
  /** Whether `a` and `b` are the same, in constant time whatever they are. */
49
64
  function same(a, b) {
50
65
  return timingSafeEqual(sha(a), sha(b));
@@ -56,7 +71,8 @@ export class Invites {
56
71
  cookieName;
57
72
  dirty = false;
58
73
  timer = null;
59
- /** told when a link is revoked: its pages' event streams end (server/live.ts) */
74
+ /** told when a link no longer lets in the browsers it let in — revoked, or made anew: its pages'
75
+ * event streams end (server/live.ts), but `keep`, the one of the page that made it anew */
60
76
  onEnded = () => { };
61
77
  /** told when a link was made, renamed or revoked: every page is told the names (`people`) */
62
78
  onChanged = () => { };
@@ -70,7 +86,7 @@ export class Invites {
70
86
  if (typeof data.cookie === "string" && /^[0-9a-f]{12}$/.test(data.cookie))
71
87
  own = data.cookie;
72
88
  if (Array.isArray(data.invites))
73
- this.records = data.invites.filter(isRecord);
89
+ this.records = data.invites.filter(isRecord).map(kept);
74
90
  }
75
91
  catch {
76
92
  // a file that cannot be read lets nobody in by a link; it is kept aside, not overwritten
@@ -99,32 +115,46 @@ export class Invites {
99
115
  do
100
116
  id = randomBytes(5).toString("hex");
101
117
  while (this.records.some((r) => r.id === id));
102
- const token = `${INVITE_PREFIX}${id}_${randomBytes(32).toString("base64url")}`;
103
- const record = { id, digest: digestOf(token), name, names: [{ name, at: now }], by: o.by, created: now, revoked: null, revokedBy: null, lastUsed: null };
118
+ const token = newToken(id);
119
+ const record = { id, digest: digestOf(token), token, name, names: [{ name, at: now }], by: o.by, created: now, revoked: null, revokedBy: null, lastUsed: null };
104
120
  this.records.push(record);
105
121
  this.save();
106
122
  this.onChanged();
107
123
  return { token, record };
108
124
  }
109
125
  /** What a link's token is. Compared in constant time, by digests of one length whatever was sent,
110
- * whether or not its id is known. */
126
+ * whether or not its id is known; then with the link's old ones, if it was made anew. */
111
127
  check(token, now = Date.now()) {
112
128
  if (!token.startsWith(INVITE_PREFIX))
113
129
  return null;
114
130
  const id = token.slice(INVITE_PREFIX.length, INVITE_PREFIX.length + 10);
115
131
  const r = validPersonId(id) && token[INVITE_PREFIX.length + 10] === "_" && SECRET.test(token.slice(INVITE_PREFIX.length + 11)) ? this.get(id) : undefined;
116
- const ok = same(digestOf(token), r?.digest ?? "no such link");
117
- return r && ok ? this.seen(r, now) : null;
132
+ const given = digestOf(token);
133
+ const ok = same(given, r?.digest ?? "no such link");
134
+ if (r && ok)
135
+ return this.seen(r, now);
136
+ return r ? this.old(r, (d) => same(given, d)) : null;
118
137
  }
119
- /** What the cookie a request carries says (its `Cookie` header): a link in force, one revoked
120
- * (whose cookie the browser should forget), or none. */
138
+ /** What the cookie a request carries says (its `Cookie` header): a link in force, one revoked or
139
+ * made anew since the cookie was given (which the browser should forget), or none. */
121
140
  ofCookie(header, now = Date.now()) {
122
141
  const given = cookieOf(header, this.cookieName);
123
142
  if (given === null)
124
143
  return null;
125
144
  const r = given.indexOf(".") === 10 ? this.get(given.slice(0, 10)) : undefined;
126
145
  const ok = same(given, r ? cookieValue(r) : "no such link");
127
- return r && ok ? this.seen(r, now) : null;
146
+ if (r && ok)
147
+ return this.seen(r, now);
148
+ return r ? this.old(r, (d) => same(given, cookieValue(r, d))) : null;
149
+ }
150
+ /** A link's old token or cookie, by `is`, which says whether it is the one of an old digest: the
151
+ * link revoked since, or made anew (when, the latest such); null when it is none of them. */
152
+ old(r, is) {
153
+ // every old digest compared, whichever matches
154
+ const at = (r.replaced ?? []).reduce((found, d) => (is(d.digest) ? d.at : found), null);
155
+ if (at === null)
156
+ return null;
157
+ return r.revoked ? { ended: "revoked", record: r } : { ended: "replaced", record: r, at };
128
158
  }
129
159
  seen(r, now) {
130
160
  if (r.revoked)
@@ -184,6 +214,45 @@ export class Invites {
184
214
  this.onChanged();
185
215
  return true;
186
216
  }
217
+ /** The link of the holder of `id` in force, to show them again (the owner's decision of
218
+ * 2026-10-19): its token; null for a link made before 0.6.0, of which only the digest was kept;
219
+ * undefined for no such link in force. */
220
+ tokenOf(id) {
221
+ const r = this.get(id);
222
+ if (!r || r.revoked)
223
+ return undefined;
224
+ return r.token ?? null;
225
+ }
226
+ /** Make the link in force `id` anew, for its holder (the owner's decision of 2026-10-19): a new
227
+ * secret under the same id, so the same person, log and names. The old link and every cookie it
228
+ * gave let nobody in from now on, and are told so; its pages' event streams end, but `keep` (the
229
+ * page that made it anew, whose browser is given the new cookie). The new token and the record,
230
+ * or null for no such link in force. */
231
+ renew(id, o = {}) {
232
+ const r = this.get(id);
233
+ if (!r || r.revoked)
234
+ return null;
235
+ const token = newToken(r.id);
236
+ const was = { digest: r.digest, token: r.token, replaced: r.replaced };
237
+ r.replaced = [...(r.replaced ?? []), { digest: r.digest, at: new Date(o.now ?? Date.now()).toISOString() }].slice(-REPLACED_KEPT);
238
+ r.digest = digestOf(token);
239
+ r.token = token;
240
+ try {
241
+ this.save();
242
+ }
243
+ catch (e) {
244
+ // not written: the link stays as it was, its browsers in, rather than made anew until the
245
+ // server restarts and reads the old one again
246
+ Object.assign(r, was);
247
+ if (was.token === undefined)
248
+ delete r.token;
249
+ if (was.replaced === undefined)
250
+ delete r.replaced;
251
+ throw e;
252
+ }
253
+ this.onEnded(r, o.keep);
254
+ return { token, record: r };
255
+ }
187
256
  /** Every holder of a link, revoked ones too, as every page is told them (`Invited`). */
188
257
  people() {
189
258
  return this.records.map((r) => ({ id: r.id, name: r.name, was: [...new Set(r.names.map((n) => n.name).filter((n) => n !== r.name))], ...(r.revoked ? { revoked: true } : {}) }));
@@ -200,9 +269,9 @@ export class Invites {
200
269
  this.timer = null;
201
270
  this.flush();
202
271
  }
203
- /** A link as Share shows it: no digest. */
272
+ /** A link as Share shows it: nothing of its token. */
204
273
  static info(r) {
205
- const { digest: _, ...rest } = r;
274
+ const { digest: _d, token: _t, replaced: _r, ...rest } = r;
206
275
  return { ...rest, names: rest.names.map((n) => ({ ...n })) };
207
276
  }
208
277
  save() {
@@ -214,6 +283,10 @@ export class Invites {
214
283
  renameSync(tmp, this.file);
215
284
  }
216
285
  }
286
+ /** A new token for the link of id `id`: its prefix, its id, and 32 random bytes. */
287
+ function newToken(id) {
288
+ return `${INVITE_PREFIX}${id}_${randomBytes(32).toString("base64url")}`;
289
+ }
217
290
  /** Why a name is not to be had: someone with a personal link goes by it. */
218
291
  export function taken(r) {
219
292
  return `“${r.name}” is the name of someone invited with a personal link: choose another.`;
@@ -233,9 +306,29 @@ export function cookieOf(header, name) {
233
306
  }
234
307
  return null;
235
308
  }
236
- /** A record as this server keeps it; anything else is dropped when the file is read. */
309
+ /** A record as this server keeps it; anything else is dropped when the file is read. A record of
310
+ * a server before 0.6.0 has no token. */
237
311
  function isRecord(x) {
238
312
  const r = x;
239
313
  return (!!r && typeof r === "object" && validPersonId(r.id) && typeof r.digest === "string" && typeof r.name === "string" && validName(r.name) &&
240
314
  Array.isArray(r.names) && r.names.every((n) => n && typeof n.name === "string" && typeof n.at === "string") && typeof r.by === "string" && typeof r.created === "string");
241
315
  }
316
+ /** A record as it is kept from now on: its token only where it is this link's own — of its id, and
317
+ * of the digest the link is compared with; one that is not (written in by hand, a copy mended
318
+ * wrongly) is never shown, and the link is as one made before 0.6.0, which its holder may make
319
+ * anew. Its old digests only where they are digests. */
320
+ function kept(r) {
321
+ const out = { ...r };
322
+ const t = r.token;
323
+ const own = typeof t === "string" && t.startsWith(`${INVITE_PREFIX}${r.id}_`) && SECRET.test(t.slice(INVITE_PREFIX.length + 11)) && digestOf(t) === r.digest;
324
+ if (!own)
325
+ delete out.token;
326
+ if (r.replaced !== undefined) {
327
+ const ds = Array.isArray(r.replaced) ? r.replaced.filter((d) => d && typeof d.digest === "string" && typeof d.at === "string") : [];
328
+ if (ds.length)
329
+ out.replaced = ds.slice(-REPLACED_KEPT);
330
+ else
331
+ delete out.replaced;
332
+ }
333
+ return out;
334
+ }