visualproof 0.4.4 → 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 (82) hide show
  1. package/README.md +16 -7
  2. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  3. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  4. package/dist/assets/tips/tour-agent.webp +0 -0
  5. package/dist/assets/tips/tour-arrange.webp +0 -0
  6. package/dist/assets/tips/tour-artwork.webp +0 -0
  7. package/dist/assets/tips/tour-checks.webp +0 -0
  8. package/dist/assets/tips/tour-keys.webp +0 -0
  9. package/dist/assets/tips/tour-library.webp +0 -0
  10. package/dist/assets/tips/tour-project.webp +0 -0
  11. package/dist/assets/tips/tour-review.webp +0 -0
  12. package/dist/assets/tips/tour-share.webp +0 -0
  13. package/dist/assets/tips/tour-source.webp +0 -0
  14. package/dist/assets/tips/tour-target.webp +0 -0
  15. package/dist/assets/tips/tour-view.webp +0 -0
  16. package/dist/assets/tips/tour.json +132 -117
  17. package/dist/assets/tips/tour.webp +0 -0
  18. package/dist/mcp/visualproof-mcp.mjs +20 -9
  19. package/dist/server/access.js +31 -1
  20. package/dist/server/accesspage.js +130 -0
  21. package/dist/server/agent.js +143 -50
  22. package/dist/server/askfollow.js +1 -1
  23. package/dist/server/buildwatch.js +133 -0
  24. package/dist/server/deploy.js +995 -0
  25. package/dist/server/doctor.js +15 -3
  26. package/dist/server/film.js +1 -1
  27. package/dist/server/historyapi.js +100 -50
  28. package/dist/server/historythread.js +206 -0
  29. package/dist/server/hover.js +8 -0
  30. package/dist/server/invites.js +113 -20
  31. package/dist/server/live.js +308 -60
  32. package/dist/server/main.js +450 -77
  33. package/dist/server/mcptools.js +33 -20
  34. package/dist/server/presence.js +3 -3
  35. package/dist/server/prompt.js +8 -3
  36. package/dist/server/readonlygate.js +4 -4
  37. package/dist/server/review.js +27 -7
  38. package/dist/server/reviewapi.js +51 -17
  39. package/dist/server/status.js +119 -46
  40. package/dist/server/talk.js +231 -115
  41. package/dist/server/tokens.js +10 -2
  42. package/dist/server/usage.js +51 -0
  43. package/dist/shared/board.js +2 -1
  44. package/dist/shared/build.js +35 -1
  45. package/dist/shared/collab.js +8 -0
  46. package/dist/shared/deploy.js +35 -0
  47. package/dist/shared/keys.js +66 -37
  48. package/dist/shared/layout.js +297 -70
  49. package/dist/shared/libm.js +366 -0
  50. package/dist/shared/lostfound.js +1 -0
  51. package/dist/shared/mentions.js +83 -0
  52. package/dist/shared/palette.js +1 -1
  53. package/dist/shared/query.js +13 -4
  54. package/dist/shared/review.js +91 -21
  55. package/dist/shared/reviewqueue.js +6 -1
  56. package/dist/shared/separate.js +556 -32
  57. package/dist/web/bundle/app.js +5022 -2736
  58. package/dist/web/bundle/edges.js +2 -1
  59. package/dist/web/bundle/layout.js +1026 -80
  60. package/dist/web/index.html +45 -9
  61. package/dist/web/src/canvas.js +47 -34
  62. package/dist/web/src/overview.js +4 -1
  63. package/dist/web/src/reviewqueue.js +52 -19
  64. package/dist/web/src/scene.js +13 -12
  65. package/dist/web/src/status.js +28 -0
  66. package/dist/web/src/theme.js +108 -0
  67. package/dist/web/src/trust.js +271 -0
  68. package/dist/web/style.css +283 -105
  69. package/docs/agent-api/README.md +13 -11
  70. package/docs/agent-api/advice.md +8 -2
  71. package/docs/agent-api/export.md +1 -1
  72. package/docs/agent-api/following.md +11 -12
  73. package/docs/agent-api/history.md +6 -2
  74. package/docs/agent-api/mcp.md +15 -15
  75. package/docs/agent-api/notes.md +1 -1
  76. package/docs/agent-api/reading.md +2 -2
  77. package/docs/agent-api/requests.md +16 -18
  78. package/docs/agent-api/talking.md +60 -55
  79. package/docs/agent-api/tcb.md +21 -21
  80. package/docs/agent-api/views.md +3 -4
  81. package/docs/agent-api/words.md +8 -8
  82. package/package.json +2 -1
@@ -0,0 +1,995 @@
1
+ // Following a branch of a git repository (SPEC/DeploySpec.md): `visualproof serve <git URL>`.
2
+ // The server keeps a clone of its own in the cache, one per URL and branch, never anyone's
3
+ // workspace; asks the remote for the branch's head every so often (`git ls-remote`); and builds
4
+ // each new head itself — fetched, checked out detached, Mathlib's cache got where the project is on
5
+ // Mathlib, `lake build` — one build at a time, in programs of their own (never the server's
6
+ // process), the newest head seen meanwhile the only one built after it. The live loop
7
+ // (server/live.ts) reads the build as it reads a workspace's, but only between builds: while one
8
+ // changes the tree, nothing is read from it, and the board on show stays the last build's.
9
+ //
10
+ // What is kept, in the deployment's folder of the cache (`<cache>/deploy/<repo>-<hash>/`): the
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.
16
+ //
17
+ // Git and Lake are run with argument arrays, never a shell; the address is checked against the
18
+ // schemes followed, the branch by git (`check-ref-format --branch`); nothing that git or Lake starts
19
+ // waits on a prompt; the credentials are git's own (an SSH key, a deploy key, a credential helper),
20
+ // and VisualProof keeps none.
21
+ import { spawn, spawnSync } from "node:child_process";
22
+ import { createHash } from "node:crypto";
23
+ import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
24
+ import { homedir, tmpdir } from "node:os";
25
+ import { basename, dirname, join, relative } from "node:path";
26
+ import { shortCommit, slimDeploy } from "../shared/deploy.js";
27
+ import { childEnv, DETACH, end, grouped } from "./children.js";
28
+ import { dataHome, lockSite, SiteBusy } from "./dirs.js";
29
+ import { buildTime, sourceAddress } from "./history.js";
30
+ import { openProject, ProjectError } from "./project.js";
31
+ /** How often the remote is asked by default (DeploySpec decision 3). */
32
+ export const DEFAULT_POLL_MINUTES = 2;
33
+ /** the least `--poll` takes, in minutes */
34
+ export const MIN_POLL_MINUTES = 0.05;
35
+ /** a question to the remote is given up after this long */
36
+ const ASK_MS = 60_000;
37
+ /** a fetch, a checkout */
38
+ const GIT_MS = 10 * 60_000;
39
+ /** Mathlib's cache (`lake exe cache get`): it compiles the cache program first */
40
+ const CACHE_MS = 30 * 60_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;
46
+ /** the most of a build's log kept for the pages, in lines and characters */
47
+ const TAIL_LINES = 60;
48
+ const TAIL_CHARS = 8000;
49
+ /** the lines of the build going on the pages are shown */
50
+ const LIVE_LINES = 6;
51
+ /** build logs kept, the newest */
52
+ const LOGS_KEPT = 30;
53
+ /** Whether a project's place on the command line is a git address rather than a folder: a URL
54
+ * (`scheme://…`), or git's scp-like `[user@]host:path` (a colon before any slash). Anything else is
55
+ * a folder; a folder whose name has a colon is written `./a:b`. */
56
+ export function isGitAddress(arg) {
57
+ if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(arg))
58
+ return true;
59
+ return /^[^/\\:\s]+:/.test(arg) && !/^[A-Za-z]:[\\/]/.test(arg);
60
+ }
61
+ const HOST = /^(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)*$/;
62
+ const PATH = /^[\w.~/@+-]+$/;
63
+ /** A git address checked against what is followed (DeploySpec decision 10): `https://` without a
64
+ * user name or password in it, `ssh://` and scp-like (`git@host:path`), and `file://` for a
65
+ * repository on this machine; never `http://` (nothing checks what comes), `git://`, `ext::` or any
66
+ * other. The address, or why it is refused. */
67
+ export function parseRemote(arg) {
68
+ const no = (why) => ({ error: `${arg.slice(0, 200)}: ${why}` });
69
+ if (!arg || arg.length > 2000 || /[\s\0-\x1f\x7f]/.test(arg))
70
+ return no("an address has no spaces or control characters");
71
+ if (arg.startsWith("-"))
72
+ return no("an address does not start with -");
73
+ if (/(^|[/:])\.\.?(\/|$)/.test(arg))
74
+ return no("not a repository's path: no . or .. in it");
75
+ const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(arg)?.[1].toLowerCase();
76
+ let kind;
77
+ let host = "";
78
+ let path;
79
+ if (scheme) {
80
+ if (scheme === "http")
81
+ return no("http:// is not followed: nothing checks what comes over it. Give the https:// address");
82
+ if (scheme !== "https" && scheme !== "ssh" && scheme !== "file")
83
+ return no(`${scheme}:// is not followed: give an https:// or ssh:// address, git's scp-like one (git@host:owner/repo.git), or file:// for a repository on this machine`);
84
+ let u;
85
+ try {
86
+ u = new URL(arg);
87
+ }
88
+ catch {
89
+ return no("not an address");
90
+ }
91
+ if (u.search || u.hash)
92
+ return no("an address has no query or fragment");
93
+ if (scheme === "file") {
94
+ if (u.host)
95
+ return no("file:// names a repository on this machine: file:///its/absolute/path");
96
+ kind = "file";
97
+ path = decodeURIComponent(u.pathname);
98
+ if (!path.startsWith("/") || path === "/")
99
+ return no("file:// takes the repository's absolute path");
100
+ }
101
+ else {
102
+ if (u.password || (scheme === "https" && u.username))
103
+ return no("no user name, password or token in the address: VisualProof keeps no credential. Let git find it (an SSH key, a deploy key, a credential helper)");
104
+ if (u.username && !/^[A-Za-z0-9._-]+$/.test(u.username))
105
+ return no("not a user name git takes");
106
+ host = u.hostname;
107
+ if (!HOST.test(host) && !/^\[[0-9A-Fa-f:.]+\]$/.test(host))
108
+ return no("not a host name");
109
+ kind = scheme === "https" ? "https" : "ssh";
110
+ path = decodeURIComponent(u.pathname);
111
+ }
112
+ }
113
+ else {
114
+ // scp-like, as git reads it: [user@]host:path
115
+ const m = /^(?:([A-Za-z0-9._][A-Za-z0-9._-]*)@)?([^@/:]+):(.+)$/.exec(arg);
116
+ if (!m)
117
+ return no("not a git address: give https://host/owner/repo, ssh://… or git@host:owner/repo");
118
+ if (!HOST.test(m[2]))
119
+ return no("not a host name");
120
+ host = m[2];
121
+ path = m[3];
122
+ if (path.startsWith("-"))
123
+ return no("a path does not start with -");
124
+ kind = "ssh";
125
+ }
126
+ const parts = path.replace(/\/+$/, "").split("/").filter(Boolean);
127
+ if (!parts.length || !PATH.test(path) || parts.some((p) => p === ".."))
128
+ return no("not a repository's path");
129
+ const name = (parts[parts.length - 1].replace(/\.git$/, "").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[.-]+/, "") || "repository").slice(0, 60);
130
+ const gh = kind !== "file" && /^(www\.)?github\.com$/i.test(host) && parts.length === 2 ? `${parts[0]}/${parts[1].replace(/\.git$/, "")}` : null;
131
+ return { url: arg, kind, source: kind === "file" ? null : sourceAddress(arg), github: gh, name };
132
+ }
133
+ /** Why `name` is no branch to follow, or null: git's own check (`git check-ref-format --branch`),
134
+ * after refusing what that check would read otherwise (`@{-1}`, the branch checked out before). */
135
+ export function branchProblem(name) {
136
+ const no = `${name.slice(0, 200)} is not a branch name git takes (git check-ref-format --branch)`;
137
+ if (!name || name.length > 255 || name.startsWith("-") || name.includes("@{") || /[\s\0-\x1f\x7f]/.test(name))
138
+ return no;
139
+ const r = spawnSync("git", ["check-ref-format", "--branch", name], { cwd: tmpdir(), encoding: "utf8", timeout: 10_000, env: gitBase() });
140
+ if (r.error)
141
+ return `git could not be run (${r.error.message}): following a branch needs git`;
142
+ return r.status === 0 && r.stdout.trim() === name ? null : no;
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
+ }
162
+ // ---------------------------------------------------------------- where it is kept
163
+ /** A deployment's name among the others: the repository's name and a hash of the address and the
164
+ * branch. */
165
+ export function deployKey(remote, branch) {
166
+ return `${remote.name}-${createHash("sha1").update(`${remote.url}\0${branch}`).digest("hex").slice(0, 8)}`;
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). */
175
+ export function deployFolder(cacheRoot, remote, branch) {
176
+ const dir = join(cacheRoot, "deploy", deployKey(remote, branch));
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") };
180
+ }
181
+ /** The site of a deployment, without `--site`: under the data home by the address and the branch,
182
+ * so that the review stays where it is whatever `--cache` says. */
183
+ export function deploySite(remote, branch, h) {
184
+ return join(dataHome(h), "sites", deployKey(remote, branch));
185
+ }
186
+ /** The remotes' default branches as last asked (`<cache>/deploy/remotes.json`): a server started
187
+ * without `--branch` and without the network follows the branch it followed. */
188
+ function remotesFile(cacheRoot) {
189
+ return join(cacheRoot, "deploy", "remotes.json");
190
+ }
191
+ export function recordedDefault(cacheRoot, url) {
192
+ try {
193
+ const all = JSON.parse(readFileSync(remotesFile(cacheRoot), "utf8"));
194
+ const b = Object.hasOwn(all, url) ? all[url].branch : null;
195
+ return typeof b === "string" && !branchProblem(b) ? b : null;
196
+ }
197
+ catch {
198
+ return null;
199
+ }
200
+ }
201
+ function recordDefault(cacheRoot, url, branch) {
202
+ const file = remotesFile(cacheRoot);
203
+ let all = {};
204
+ try {
205
+ all = JSON.parse(readFileSync(file, "utf8"));
206
+ }
207
+ catch {
208
+ // none yet
209
+ }
210
+ all[url] = { branch, at: new Date().toISOString() };
211
+ try {
212
+ mkdirSync(join(cacheRoot, "deploy"), { recursive: true });
213
+ writeFileSync(`${file}.tmp-${process.pid}`, JSON.stringify(all, null, 1) + "\n");
214
+ renameSync(`${file}.tmp-${process.pid}`, file);
215
+ }
216
+ catch {
217
+ // a record to spare the network at the next start; not a reason to fail
218
+ }
219
+ }
220
+ // ---------------------------------------------------------------- the programs' environment
221
+ /** What tells git which repository to work on, where the server's own environment has it (a hook's,
222
+ * a test's): never handed on, so that git works on the clone alone. */
223
+ const REPO_VARS = ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_NAMESPACE", "GIT_PREFIX", "GIT_QUARANTINE_PATH", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT"];
224
+ /** The server's environment without what is the server's alone (`VISUALPROOF_*`, server/children.ts)
225
+ * and without what would point git elsewhere. */
226
+ function gitBase() {
227
+ const env = childEnv();
228
+ for (const k of REPO_VARS)
229
+ delete env[k];
230
+ for (const k of Object.keys(env))
231
+ if (/^GIT_CONFIG_(KEY|VALUE)_\d+$/.test(k))
232
+ delete env[k];
233
+ return env;
234
+ }
235
+ let sshConfigured;
236
+ /** The ssh command git is configured with (`core.sshCommand`, the user's or the system's), read once. */
237
+ function configuredSsh() {
238
+ if (sshConfigured !== undefined)
239
+ return sshConfigured;
240
+ const r = spawnSync("git", ["config", "--get", "core.sshCommand"], { cwd: tmpdir(), encoding: "utf8", timeout: 10_000, env: gitBase() });
241
+ return (sshConfigured = r.status === 0 && r.stdout.trim() ? r.stdout.trim() : null);
242
+ }
243
+ /** No prompt is ever waited on (DeploySpec decision 9): git asks no terminal and runs no askpass
244
+ * (`GIT_TERMINAL_PROMPT=0`, an empty `GIT_ASKPASS`), the credential manager is not interactive, and
245
+ * ssh runs in batch mode — the ssh command git would run (`GIT_SSH_COMMAND`, else `core.sshCommand`,
246
+ * else `ssh`) with `-o BatchMode=yes` after it; a `GIT_SSH` program is left as it is. Credentials
247
+ * are git's own: helpers, keys and agents work as for any git. The programs run without a
248
+ * terminal of their own besides (server/children.ts, `grouped`). */
249
+ export function noPrompts(env, ssh = configuredSsh()) {
250
+ const out = { ...env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "", SSH_ASKPASS_REQUIRE: "never", GCM_INTERACTIVE: "never" };
251
+ const own = env.GIT_SSH_COMMAND || ssh || (env.GIT_SSH ? null : "ssh");
252
+ if (own)
253
+ out.GIT_SSH_COMMAND = `${own} -o BatchMode=yes`;
254
+ return out;
255
+ }
256
+ /** git's environment, for the remote `remote`: no prompts, and only its protocol allowed
257
+ * (`GIT_ALLOW_PROTOCOL`), whatever a redirect or a configuration says. */
258
+ export function gitEnv(remote) {
259
+ return { ...noPrompts(gitBase()), GIT_ALLOW_PROTOCOL: remote.kind };
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
+ }
268
+ /** Lake's environment for a build: the server's without what is its own — no access key or token
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;
278
+ }
279
+ /** Run `cmd` with `args` — an array, never through a shell — as a group of its own (what it starts
280
+ * ends with it: server/children.ts), stopped past `timeoutMs`; what it writes goes to `onText` as
281
+ * it comes. Never rejects. */
282
+ export function run(cmd, args, o) {
283
+ return new Promise((done) => {
284
+ const keep = o.keep ?? 20_000;
285
+ let stdout = "", out = "", timedOut = false, finished = false;
286
+ let child;
287
+ try {
288
+ child = grouped(spawn(cmd, args, { cwd: o.cwd, env: o.env, stdio: ["ignore", "pipe", "pipe"], detached: DETACH }));
289
+ }
290
+ catch (e) {
291
+ return done({ code: null, signal: null, stdout, out, timedOut, error: e instanceof Error ? e.message : String(e) });
292
+ }
293
+ const take = (b, own) => {
294
+ const t = b.toString();
295
+ if (own)
296
+ stdout = (stdout + t).slice(-keep);
297
+ out = (out + t).slice(-keep);
298
+ o.onText?.(t);
299
+ };
300
+ child.stdout.on("data", (b) => take(b, true));
301
+ child.stderr.on("data", (b) => take(b, false));
302
+ const timer = setTimeout(() => {
303
+ timedOut = true;
304
+ end(child);
305
+ setTimeout(() => end(child, "SIGKILL"), 5000).unref();
306
+ }, o.timeoutMs);
307
+ const finish = (r) => {
308
+ if (finished)
309
+ return;
310
+ finished = true;
311
+ clearTimeout(timer);
312
+ done(r);
313
+ };
314
+ child.on("error", (e) => finish({ code: null, signal: null, stdout, out, timedOut, error: e.message }));
315
+ child.on("close", (code, signal) => finish({ code, signal, stdout, out, timedOut }));
316
+ });
317
+ }
318
+ /** What git said went wrong, in a line: its last `fatal:` or `error:` line, else its last line. */
319
+ function gitWhy(r) {
320
+ if (r.error)
321
+ return `git could not be run: ${r.error}`;
322
+ if (r.timedOut)
323
+ return "git did not finish in time";
324
+ const lines = r.out.split("\n").map((l) => l.trim()).filter(Boolean);
325
+ const said = [...lines].reverse().find((l) => /^(fatal|error):/.test(l)) ?? lines[lines.length - 1] ?? `git exited with ${r.code}`;
326
+ return said.replace(/^(fatal|error):\s*/, "").slice(0, 400);
327
+ }
328
+ const git = (args, env, ms = GIT_MS, onText) => run("git", args, { env, timeoutMs: ms, cwd: tmpdir(), onText });
329
+ const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
330
+ /** The head of `branch` on the remote; without a branch, the remote's default branch and its head
331
+ * (`git ls-remote --symref HEAD`). Only that branch is ever asked of: never a pull request's ref, nor
332
+ * a fork's. */
333
+ export async function askRemote(remote, branch, env) {
334
+ const r = await git(branch ? ["ls-remote", "--", remote.url, `refs/heads/${branch}`] : ["ls-remote", "--symref", "--", remote.url, "HEAD"], env, ASK_MS);
335
+ if (r.code !== 0 || r.error || r.timedOut)
336
+ return { error: r.timedOut ? "the remote did not answer within a minute" : gitWhy(r) };
337
+ const lines = r.stdout.split("\n");
338
+ if (!branch) {
339
+ const ref = lines.map((l) => /^ref: refs\/heads\/(\S+)\tHEAD$/.exec(l)).find(Boolean)?.[1];
340
+ if (!ref || branchProblem(ref))
341
+ return { error: "the remote names no default branch: say which to follow, --branch <name>" };
342
+ const head = lines.map((l) => /^([0-9a-f]+)\tHEAD$/.exec(l)).find(Boolean)?.[1];
343
+ return head && SHA.test(head) ? { head, branch: ref } : { error: `the remote's ${ref} has no commit` };
344
+ }
345
+ // the pattern matches refs that end so: the branch's own ref alone
346
+ const head = lines.map((l) => l.split("\t")).find((p) => p[1] === `refs/heads/${branch}`)?.[0];
347
+ return head && SHA.test(head) ? { head, branch } : { error: `the remote has no branch ${branch}` };
348
+ }
349
+ /** The branch to follow: `given`, else the remote's default as it says it now, else as it said it
350
+ * last (the network may be away at a restart). */
351
+ export async function branchToFollow(remote, given, cacheRoot) {
352
+ if (given)
353
+ return given;
354
+ const a = await askRemote(remote, null, gitEnv(remote));
355
+ if ("head" in a) {
356
+ recordDefault(cacheRoot, remote.url, a.branch);
357
+ return a.branch;
358
+ }
359
+ return recordedDefault(cacheRoot, remote.url) ?? { error: `cannot learn the remote's default branch (${a.error}): give --branch <name>` };
360
+ }
361
+ /** The deployment's clone, made at the first start (DeploySpec decision 2): an empty repository
362
+ * whose `origin` is the address, the branch fetched alone, its head checked out detached. It is
363
+ * made in a folder of its own and moved into place once whole, so that a start cut short leaves
364
+ * nothing half made. The commit checked out, or why there is none. */
365
+ export async function ensureClone(remote, branch, folder, log) {
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
+ }
375
+ if (existsSync(join(folder.checkout, ".git"))) {
376
+ const r = await git(["-C", folder.checkout, "rev-parse", "--verify", "HEAD^{commit}"], env);
377
+ const c = r.stdout.trim();
378
+ if (r.code === 0 && SHA.test(c))
379
+ return { commit: c, made: false };
380
+ return { error: `the clone ${folder.checkout} cannot be read (${gitWhy(r)}): remove it, and it is made again` };
381
+ }
382
+ const place = dirname(folder.checkout);
383
+ mkdirSync(place, { recursive: true });
384
+ // what a start that died midway left
385
+ for (const f of readdirSync(place)) {
386
+ const m = new RegExp(`^${basename(folder.checkout).replace(/[.]/g, "\\.")}\\.tmp-(\\d+)$`).exec(f);
387
+ if (m && !alive(Number(m[1])))
388
+ rmSync(join(place, f), { recursive: true, force: true });
389
+ }
390
+ const tmp = `${folder.checkout}.tmp-${process.pid}`;
391
+ rmSync(tmp, { recursive: true, force: true });
392
+ const t0 = Date.now();
393
+ log(`cloning ${remote.source ?? remote.url} (${branch}) into ${folder.checkout}…`);
394
+ const steps = [
395
+ ["init", "--quiet", tmp],
396
+ ["-C", tmp, "remote", "add", "origin", "--", remote.url],
397
+ ["-C", tmp, "fetch", "--no-tags", "--no-recurse-submodules", "--quiet", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`],
398
+ ];
399
+ for (const s of steps) {
400
+ const r = await git(s, env);
401
+ if (r.code !== 0) {
402
+ rmSync(tmp, { recursive: true, force: true });
403
+ return { error: `cannot clone ${remote.source ?? remote.url} (${branch}): ${gitWhy(r)}` };
404
+ }
405
+ }
406
+ const rp = await git(["-C", tmp, "rev-parse", "--verify", `refs/remotes/origin/${branch}^{commit}`], env);
407
+ const commit = rp.stdout.trim();
408
+ const co = SHA.test(commit) ? await git(["-C", tmp, "-c", "advice.detachedHead=false", "checkout", "--quiet", "--force", "--detach", commit], env) : rp;
409
+ if (co.code !== 0 || !SHA.test(commit)) {
410
+ rmSync(tmp, { recursive: true, force: true });
411
+ return { error: `cannot check out ${branch} of ${remote.source ?? remote.url}: ${gitWhy(co)}` };
412
+ }
413
+ renameSync(tmp, folder.checkout);
414
+ log(`cloned in ${((Date.now() - t0) / 1000).toFixed(1)} s, at ${shortCommit(commit)}`);
415
+ return { commit, made: true };
416
+ }
417
+ function alive(pid) {
418
+ try {
419
+ process.kill(pid, 0);
420
+ return true;
421
+ }
422
+ catch (e) {
423
+ return e.code === "EPERM";
424
+ }
425
+ }
426
+ /** Another server follows the branch with this cache. */
427
+ export class DeployBusy extends Error {
428
+ }
429
+ /** Take the deployment for this process (`.lock`, as a site is taken: server/dirs.ts). */
430
+ export function lockDeployment(folder, remote, branch) {
431
+ mkdirSync(folder.dir, { recursive: true });
432
+ try {
433
+ return lockSite(folder.dir);
434
+ }
435
+ catch (e) {
436
+ if (e instanceof SiteBusy)
437
+ throw new DeployBusy(`another VisualProof server (process ${e.pid}) follows ${branch} of ${remote.source ?? remote.url} with this cache (${folder.dir}): stop it first, or give this one a --cache of its own`);
438
+ throw e;
439
+ }
440
+ }
441
+ /** Whether the project is on Mathlib: its manifest names it (DeploySpec decision 4). */
442
+ export function onMathlib(root) {
443
+ try {
444
+ const m = JSON.parse(readFileSync(join(root, "lake-manifest.json"), "utf8"));
445
+ return Array.isArray(m.packages) && m.packages.some((p) => typeof p?.name === "string" && p.name.toLowerCase() === "mathlib");
446
+ }
447
+ catch {
448
+ return false;
449
+ }
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
+ }
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
+ }
522
+ /** A build's log: everything its programs wrote, in `logs/<commit>.log` of the deployment (a build
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. */
525
+ export class BuildLog {
526
+ file;
527
+ fd = null;
528
+ lines = [];
529
+ partial = "";
530
+ /** the paths the pages are given by another name (logNames) */
531
+ named;
532
+ constructor(dir, commit, root, o = {}) {
533
+ mkdirSync(dir, { recursive: true });
534
+ this.file = join(dir, `${commit}.log`);
535
+ this.named = pathNamer(logNames(root, o));
536
+ try {
537
+ this.fd = openSync(this.file, "w", 0o600);
538
+ }
539
+ catch {
540
+ // a log that cannot be written: its end is still kept for the pages
541
+ }
542
+ prune(dir, LOGS_KEPT);
543
+ }
544
+ /** a line of VisualProof's own: the step, the command */
545
+ say(line) {
546
+ this.text(`${line}\n`);
547
+ }
548
+ text(t) {
549
+ if (this.fd !== null) {
550
+ try {
551
+ writeSync(this.fd, t);
552
+ }
553
+ catch {
554
+ this.fd = null;
555
+ }
556
+ }
557
+ const parts = (this.partial + t).split("\n");
558
+ this.partial = parts.pop() ?? "";
559
+ for (const p of parts)
560
+ this.push(p);
561
+ }
562
+ push(raw) {
563
+ // a line redrawn in place (a progress bar) is its last state
564
+ const line = raw.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").split("\r").pop().trimEnd();
565
+ if (!line)
566
+ return;
567
+ this.lines.push(line);
568
+ if (this.lines.length > TAIL_LINES * 2)
569
+ this.lines.splice(0, this.lines.length - TAIL_LINES);
570
+ }
571
+ /** its end, as the pages are given it: its last `n` lines, the one being written included */
572
+ tail(n = TAIL_LINES) {
573
+ const last = this.partial.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").split("\r").pop().trimEnd();
574
+ const t = this.named([...this.lines, ...(last ? [last] : [])].slice(-n).join("\n"));
575
+ return t.length > TAIL_CHARS ? `…${t.slice(-TAIL_CHARS)}` : t;
576
+ }
577
+ close() {
578
+ if (this.fd !== null)
579
+ closeSync(this.fd);
580
+ this.fd = null;
581
+ }
582
+ }
583
+ /** Keep the newest `keep` files of `dir`. */
584
+ function prune(dir, keep) {
585
+ try {
586
+ const files = readdirSync(dir)
587
+ .filter((f) => f.endsWith(".log"))
588
+ .map((f) => ({ f, t: statSync(join(dir, f)).mtimeMs }))
589
+ .sort((a, b) => b.t - a.t);
590
+ for (const { f } of files.slice(keep))
591
+ unlinkSync(join(dir, f));
592
+ }
593
+ catch {
594
+ // housekeeping
595
+ }
596
+ }
597
+ /** A branch followed and built (DeploySpec decisions 3–8): the remote asked every `everyMs`, each
598
+ * new head built in turn, the newest seen meanwhile the only one built after the build going on. */
599
+ export class Deployment {
600
+ remote;
601
+ branch;
602
+ folder;
603
+ o;
604
+ state;
605
+ /** the newest head seen: what is built next */
606
+ want;
607
+ /** the last commit tried */
608
+ done;
609
+ /** a commit whose try could not be made: tried again at the next look at the remote, not before */
610
+ later = null;
611
+ /** the tree is not one build's: a build was cut short, and nothing is read until one ends */
612
+ interrupted;
613
+ building = null;
614
+ asked = null;
615
+ timer = null;
616
+ retry = null;
617
+ stopped = false;
618
+ asking = null;
619
+ /** the build going on */
620
+ running = null;
621
+ env;
622
+ lakeEnv;
623
+ /** `lake build` past which a build is stopped (DeploySpec decision 14) */
624
+ buildMs;
625
+ /** every build tried since the start, in order: what the tests read */
626
+ tried = [];
627
+ /** the log of the build going on */
628
+ log = null;
629
+ constructor(o) {
630
+ this.o = o;
631
+ this.remote = o.remote;
632
+ this.branch = o.branch;
633
+ this.folder = o.folder;
634
+ this.env = gitEnv(o.remote);
635
+ this.lakeEnv = buildEnv(o.mathlibCache === "own" ? o.folder.mathlib : null);
636
+ this.buildMs = o.buildMs ?? DEFAULT_BUILD_HOURS * 3600_000;
637
+ this.state = this.read();
638
+ const head = this.headNow();
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);
642
+ this.want = this.state.head?.commit ?? this.state.building?.commit ?? o.head ?? head;
643
+ this.done = this.interrupted ? null : this.state.done;
644
+ if (this.state.building)
645
+ o.hooks.log(`build: the build of ${shortCommit(this.state.building.commit)} was cut short (a restart, a stop): it is done again`);
646
+ }
647
+ read() {
648
+ const fresh = { version: 1, url: this.remote.url, branch: this.branch, outputs: null, ran: null, building: null, done: null, last: null, head: null };
649
+ try {
650
+ const s = JSON.parse(readFileSync(this.folder.state, "utf8"));
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 };
653
+ }
654
+ catch {
655
+ return fresh;
656
+ }
657
+ }
658
+ save() {
659
+ const tmp = `${this.folder.state}.tmp-${process.pid}`;
660
+ try {
661
+ writeFileSync(tmp, JSON.stringify(this.state, null, 1) + "\n");
662
+ renameSync(tmp, this.folder.state);
663
+ }
664
+ catch (e) {
665
+ this.o.hooks.log(`build: ${this.folder.state} cannot be written: ${e instanceof Error ? e.message : String(e)}`);
666
+ }
667
+ }
668
+ /** the commit checked out in the clone */
669
+ headNow() {
670
+ const r = spawnSync("git", ["-C", this.folder.checkout, "rev-parse", "--verify", "HEAD^{commit}"], { encoding: "utf8", timeout: 10_000, env: this.env });
671
+ const c = r.status === 0 ? r.stdout.trim() : "";
672
+ return SHA.test(c) ? c : null;
673
+ }
674
+ /** Ask the remote at once, then every `everyMs`. */
675
+ start() {
676
+ void this.poll();
677
+ this.timer = setInterval(() => void this.poll(), this.o.everyMs);
678
+ this.timer.unref?.();
679
+ }
680
+ /** No more asking or building; a build going on is stopped with the server's programs
681
+ * (server/children.ts) and recorded as cut short, to be done again at the next start. */
682
+ stop() {
683
+ this.stopped = true;
684
+ if (this.timer)
685
+ clearInterval(this.timer);
686
+ if (this.retry)
687
+ clearTimeout(this.retry);
688
+ this.timer = this.retry = null;
689
+ }
690
+ /** Whether the tree is not to be read now: a build changes it, one was cut short, or none was ever
691
+ * made. */
692
+ holds() {
693
+ return this.building !== null || this.interrupted || this.state.outputs === null;
694
+ }
695
+ /** a build is going on, which a restart would cut short (UpdateSpec decision 6) */
696
+ get busy() {
697
+ return this.running !== null;
698
+ }
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). */
702
+ commit() {
703
+ return this.state.outputs ? { hash: this.state.outputs.commit, branch: this.branch } : null;
704
+ }
705
+ /** What the pages and agents are told; without the build's log for a read-only reader. */
706
+ status(full) {
707
+ const s = {
708
+ source: this.remote.source,
709
+ github: this.remote.github,
710
+ branch: this.branch,
711
+ every: Math.round(this.o.everyMs / 1000),
712
+ asked: this.asked,
713
+ // what the build going on says now (the cache's download, Lake's last lines)
714
+ building: this.building && { ...this.building, ...(this.log ? { tail: this.log.tail(LIVE_LINES) } : {}) },
715
+ // a commit waiting for its try to be made again is said by the last build's
716
+ next: this.building && this.want && this.want !== this.done && this.want !== this.building.commit ? this.want : null,
717
+ last: this.state.last,
718
+ built: this.state.outputs?.commit ?? null,
719
+ };
720
+ return full ? s : slimDeploy(s);
721
+ }
722
+ /** Ask the remote for the branch's head; a new one is built once the build going on ends. A
723
+ * question asked while one is on its way waits for it. */
724
+ poll() {
725
+ this.asking ??= (async () => {
726
+ try {
727
+ const a = this.o.ask ? await this.o.ask() : await askRemote(this.remote, this.branch, this.env);
728
+ const at = new Date().toISOString();
729
+ if (this.stopped)
730
+ return;
731
+ if ("error" in a) {
732
+ if (this.asked?.error !== a.error)
733
+ this.o.hooks.log(`build: the remote cannot be asked: ${a.error}`);
734
+ this.asked = { at, head: this.asked?.head ?? null, error: a.error };
735
+ }
736
+ else {
737
+ this.asked = { at, head: a.head };
738
+ if (a.head !== this.state.head?.commit) {
739
+ this.state.head = { commit: a.head, at };
740
+ this.save();
741
+ }
742
+ if (a.head !== this.want) {
743
+ if (this.want)
744
+ this.o.hooks.log(`build: ${this.branch} is at ${shortCommit(a.head)} now${this.running ? `: built once the build of ${shortCommit(this.building?.commit ?? "")} ends` : ""}`);
745
+ this.want = a.head;
746
+ }
747
+ }
748
+ this.later = null;
749
+ this.o.hooks.changed();
750
+ this.kick();
751
+ }
752
+ finally {
753
+ this.asking = null;
754
+ }
755
+ })();
756
+ return this.asking;
757
+ }
758
+ /** Start the build of the newest head where none is going on and it is not built yet; while the
759
+ * server reads the tree, a moment later. */
760
+ kick() {
761
+ if (this.stopped || this.running || !this.want || this.want === this.done || this.want === this.later)
762
+ return;
763
+ if (this.o.hooks.reading()) {
764
+ this.retry ??= setTimeout(() => {
765
+ this.retry = null;
766
+ this.kick();
767
+ }, 300);
768
+ return;
769
+ }
770
+ const commit = this.want;
771
+ this.tried.push(commit);
772
+ this.running = this.attempt(commit)
773
+ .catch((e) => this.o.hooks.log(`build: ${shortCommit(commit)}: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`))
774
+ .finally(() => {
775
+ this.running = null;
776
+ this.building = null;
777
+ this.o.hooks.changed();
778
+ this.kick();
779
+ });
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
+ }
786
+ /** Until the build going on and those waiting are done: what the tests wait for. */
787
+ async settled() {
788
+ while (this.running || this.asking || this.retry)
789
+ await (this.running ?? this.asking ?? new Promise((ok) => setTimeout(ok, 50)));
790
+ }
791
+ step(s) {
792
+ if (this.building)
793
+ this.building = { ...this.building, step: s };
794
+ this.o.hooks.changed();
795
+ }
796
+ /** The build of `commit` (DeploySpec decisions 4–7): fetched where the clone has it not, checked
797
+ * out detached and cleaned (the build outputs kept), the project read again as it says it,
798
+ * Mathlib's cache got where it is on Mathlib, `lake build`. A try that could not change or build
799
+ * the tree leaves it as the last build had it. */
800
+ async attempt(commit) {
801
+ const t0 = Date.now();
802
+ const since = new Date(t0).toISOString();
803
+ // before anything is awaited: from here the tree is not read (holds)
804
+ this.building = { commit, since, step: "fetch" };
805
+ this.o.hooks.changed();
806
+ const short = shortCommit(commit);
807
+ const say = this.o.hooks.log;
808
+ const log = (this.log = new BuildLog(this.folder.logs, commit, this.folder.checkout, { folder: this.folder.dir }));
809
+ const g = (args, ms = GIT_MS) => {
810
+ log.say(`$ git ${args.join(" ")}`);
811
+ return git(["-C", this.folder.checkout, ...args], this.env, ms, (t) => log.text(t));
812
+ };
813
+ const ended = (b) => this.ended(commit, t0, { ...b, tail: log.tail() }, log);
814
+ try {
815
+ say(`build: ${short}: ${this.state.outputs ? "" : "the first build: "}fetching`);
816
+ if (!(await this.has(commit))) {
817
+ const f = await g(["fetch", "--no-tags", "--no-recurse-submodules", "--quiet", "origin", `+refs/heads/${this.branch}:refs/remotes/origin/${this.branch}`]);
818
+ if (this.stopped)
819
+ return;
820
+ if (f.code !== 0)
821
+ return ended({ ok: false, retry: true, error: `it could not be fetched: ${gitWhy(f)}` });
822
+ if (!(await this.has(commit)))
823
+ return ended({ ok: false, retry: true, error: "the branch moved on before it could be fetched: its newest commit is built next" });
824
+ }
825
+ // a graph being made ready to serve as the fetch went on (the usage pass's) is let finish: the
826
+ // tree changes from here
827
+ while (this.o.hooks.reading() && !this.stopped)
828
+ await new Promise((ok) => setTimeout(ok, 100));
829
+ if (this.stopped)
830
+ return;
831
+ // the build is recorded as going on, so that one cut short is done again (DeploySpec
832
+ // decision 8)
833
+ this.step("checkout");
834
+ this.o.hooks.starting();
835
+ this.state.building = { commit, since };
836
+ this.save();
837
+ const co = await g(["-c", "advice.detachedHead=false", "checkout", "--quiet", "--force", "--detach", commit]);
838
+ const cl = co.code === 0 ? await g(["clean", "-ffdq", "-e", ".lake"]) : co;
839
+ if (this.stopped)
840
+ return;
841
+ if (cl.code !== 0) {
842
+ await this.restore(log);
843
+ return ended({ ok: false, retry: true, error: `it could not be checked out: ${gitWhy(cl)}` });
844
+ }
845
+ try {
846
+ this.adopt(openProject(this.folder.checkout, this.o.roots, false));
847
+ }
848
+ catch (e) {
849
+ if (!(e instanceof ProjectError))
850
+ throw e;
851
+ await this.restore(log);
852
+ return ended({ ok: false, error: `it is no Lean project VisualProof can read: ${e.message}` });
853
+ }
854
+ const lake = this.o.lake ?? "lake";
855
+ if (onMathlib(this.folder.checkout)) {
856
+ this.step("cache");
857
+ say(`build: ${short}: getting Mathlib's cache`);
858
+ for (let n = 1; n <= 2 && !this.stopped; n++) {
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`);
861
+ const c = await run(lake, ["exe", "cache", "get"], { cwd: this.folder.checkout, env: this.lakeEnv, timeoutMs: CACHE_MS, onText: (t) => log.text(t) });
862
+ if (c.code === 0) {
863
+ await this.cleanMathlibCache(lake, log);
864
+ break;
865
+ }
866
+ // Lake builds what the cache did not give
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"}`);
868
+ }
869
+ }
870
+ if (this.stopped)
871
+ return;
872
+ this.step("build");
873
+ say(`build: ${short}: lake build${this.o.roots.length ? ` ${this.o.roots.join(" ")}` : ""}`);
874
+ log.say(`$ lake build${this.o.roots.length ? ` ${this.o.roots.join(" ")}` : ""}`);
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) });
879
+ // cut short by the server's stop: done again at the next start
880
+ if (this.stopped)
881
+ return;
882
+ if (b.error) {
883
+ await this.restore(log);
884
+ return ended({ ok: false, retry: true, error: `lake could not be run: ${b.error}` });
885
+ }
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() };
894
+ this.state.building = null;
895
+ this.interrupted = false;
896
+ // the modules a library's globs give, now that they are built
897
+ try {
898
+ this.adopt(openProject(this.folder.checkout, this.o.roots, false));
899
+ }
900
+ catch {
901
+ // read as it was after the checkout
902
+ }
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` } : {}) });
907
+ }
908
+ catch (e) {
909
+ if (this.stopped)
910
+ return;
911
+ if (this.state.building)
912
+ await this.restore(log);
913
+ return ended({ ok: false, retry: true, error: e instanceof Error ? e.message : String(e) });
914
+ }
915
+ finally {
916
+ log.close();
917
+ this.log = null;
918
+ }
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
+ }
937
+ /** Whether the clone has `commit`. */
938
+ async has(commit) {
939
+ const r = await git(["-C", this.folder.checkout, "cat-file", "-e", `${commit}^{commit}`], this.env, ASK_MS);
940
+ return r.code === 0;
941
+ }
942
+ /** The tree as the last build left it, after a try that changed it and did not build it: checked
943
+ * out at that build's commit again, so that what is read of it, and a restart, are that build's.
944
+ * Where that cannot be done, the tree stays held until a build ends. */
945
+ async restore(log) {
946
+ const was = this.state.ran;
947
+ if (was) {
948
+ log.say(`back to ${shortCommit(was)}, the last build's commit`);
949
+ const co = await git(["-C", this.folder.checkout, "-c", "advice.detachedHead=false", "checkout", "--quiet", "--force", "--detach", was], this.env);
950
+ if (co.code !== 0) {
951
+ log.say(`it could not be checked out again: ${gitWhy(co)}`);
952
+ this.interrupted = true;
953
+ return;
954
+ }
955
+ try {
956
+ this.adopt(openProject(this.folder.checkout, this.o.roots, false));
957
+ }
958
+ catch {
959
+ // it was read at that build
960
+ }
961
+ }
962
+ // no build to go back to: nothing is read until one is made (holds)
963
+ this.state.building = null;
964
+ this.interrupted = false;
965
+ }
966
+ /** The project as the commit checked out says it, taken into the server's own in place: its
967
+ * toolchain, its name, its roots. */
968
+ adopt(fresh) {
969
+ const p = this.o.project;
970
+ const was = p.toolchain;
971
+ Object.assign(p, { ...fresh, root: p.root });
972
+ if (fresh.toolchain !== was) {
973
+ this.o.hooks.log(`build: the toolchain is ${fresh.toolchain} now (it was ${was})`);
974
+ this.o.hooks.toolchainChanged();
975
+ }
976
+ }
977
+ /** A try ended: recorded, said, and — unless it could not be made — not tried again. */
978
+ ended(commit, t0, b, log) {
979
+ const ms = Date.now() - t0;
980
+ const build = { commit, at: new Date().toISOString(), ms, ...b };
981
+ this.state.last = build;
982
+ if (!b.retry)
983
+ this.state.done = this.done = commit;
984
+ else
985
+ this.later = commit;
986
+ this.save();
987
+ this.o.hooks.ended?.();
988
+ const secs = ms < 60_000 ? `${(ms / 1000).toFixed(1)} s` : `${Math.round(ms / 60_000)} min`;
989
+ const short = shortCommit(commit);
990
+ if (b.ok)
991
+ this.o.hooks.log(`build: ${short} built in ${secs}`);
992
+ else
993
+ this.o.hooks.log(`build: ${short} failed after ${secs}: ${b.error ?? `lake build exited with ${b.exit}`}${b.retry ? "; tried again at the next look at the remote" : ""} (its log: ${log.file})`);
994
+ }
995
+ }