visualproof 0.5.0 → 0.7.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 (107) hide show
  1. package/README.md +2 -2
  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 +125 -115
  17. package/dist/assets/tips/tour.webp +0 -0
  18. package/dist/extractor/Extract.lean +13 -3
  19. package/dist/mcp/visualproof-mcp.mjs +20 -9
  20. package/dist/server/access.js +28 -0
  21. package/dist/server/agent.js +130 -2819
  22. package/dist/server/agentactivity.js +72 -0
  23. package/dist/server/agentadvice.js +115 -0
  24. package/dist/server/agentdocs.js +1 -1
  25. package/dist/server/agententry.js +180 -0
  26. package/dist/server/agentexport.js +469 -0
  27. package/dist/server/agentfollow.js +384 -0
  28. package/dist/server/agentgraph.js +128 -0
  29. package/dist/server/agentlean.js +144 -0
  30. package/dist/server/agentlibrary.js +1 -1
  31. package/dist/server/agentplaces.js +242 -0
  32. package/dist/server/agentread.js +569 -0
  33. package/dist/server/agenttalk.js +282 -0
  34. package/dist/server/agenttcb.js +378 -0
  35. package/dist/server/agentviews.js +2 -2
  36. package/dist/server/app.js +377 -0
  37. package/dist/server/appaccess.js +127 -0
  38. package/dist/server/appagent.js +110 -0
  39. package/dist/server/appgraph.js +176 -0
  40. package/dist/server/appshare.js +179 -0
  41. package/dist/server/appsite.js +120 -0
  42. package/dist/server/apptalk.js +178 -0
  43. package/dist/server/artcmd.js +1 -1
  44. package/dist/server/askfollow.js +1 -1
  45. package/dist/server/deploy.js +204 -53
  46. package/dist/server/events.js +1 -1
  47. package/dist/server/history.js +51 -3
  48. package/dist/server/historyapi.js +34 -2
  49. package/dist/server/hover.js +11 -7
  50. package/dist/server/identity.js +1 -1
  51. package/dist/server/invites.js +113 -20
  52. package/dist/server/libraryroute.js +3 -3
  53. package/dist/server/live.js +186 -30
  54. package/dist/server/main.js +31 -1613
  55. package/dist/server/mcptools.js +33 -20
  56. package/dist/server/options.js +350 -0
  57. package/dist/server/outside.js +311 -0
  58. package/dist/server/pastdoc.js +22 -3
  59. package/dist/server/presence.js +3 -3
  60. package/dist/server/project.js +28 -4
  61. package/dist/server/prompt.js +8 -3
  62. package/dist/server/readonlygate.js +4 -4
  63. package/dist/server/reviewapi.js +51 -17
  64. package/dist/server/send.js +259 -0
  65. package/dist/server/talk.js +238 -116
  66. package/dist/server/tokens.js +13 -5
  67. package/dist/server/view.js +3 -1
  68. package/dist/server/views.js +1 -1
  69. package/dist/shared/artrecipe.js +3 -3
  70. package/dist/shared/build.js +35 -1
  71. package/dist/shared/collab.js +9 -1
  72. package/dist/shared/comment.js +1 -1
  73. package/dist/shared/doc/build.js +30 -14
  74. package/dist/shared/doc/latex.js +7 -2
  75. package/dist/shared/doc/model.js +4 -2
  76. package/dist/shared/doc/sections.js +21 -4
  77. package/dist/shared/keys.js +66 -37
  78. package/dist/shared/lostfound.js +1 -0
  79. package/dist/shared/mentions.js +83 -0
  80. package/dist/shared/outside.js +16 -0
  81. package/dist/shared/pastgraph.js +11 -2
  82. package/dist/shared/query.js +13 -4
  83. package/dist/shared/review.js +91 -21
  84. package/dist/shared/reviewqueue.js +6 -1
  85. package/dist/shared/scope.js +1 -1
  86. package/dist/web/bundle/app.js +51289 -49853
  87. package/dist/web/index.html +45 -9
  88. package/dist/web/src/reviewqueue.js +52 -19
  89. package/dist/web/src/selection.js +1 -1
  90. package/dist/web/src/theme.js +1 -1
  91. package/dist/web/src/trust.js +271 -0
  92. package/dist/web/src/visitors.js +1 -1
  93. package/dist/web/style.css +181 -70
  94. package/docs/agent-api/README.md +13 -11
  95. package/docs/agent-api/advice.md +8 -2
  96. package/docs/agent-api/export.md +9 -6
  97. package/docs/agent-api/following.md +11 -12
  98. package/docs/agent-api/history.md +6 -3
  99. package/docs/agent-api/mcp.md +15 -15
  100. package/docs/agent-api/notes.md +1 -1
  101. package/docs/agent-api/reading.md +10 -4
  102. package/docs/agent-api/requests.md +12 -15
  103. package/docs/agent-api/talking.md +60 -55
  104. package/docs/agent-api/tcb.md +21 -21
  105. package/docs/agent-api/views.md +3 -4
  106. package/docs/agent-api/words.md +8 -8
  107. package/package.json +2 -1
@@ -1,1630 +1,36 @@
1
1
  #!/usr/bin/env node
2
2
  // visualproof serve <path> — read a built Lean project and serve its declaration graph
3
3
  // visualproof export <path> — the same page, frozen into one HTML file
4
- import { historyAnswer } from "./historyapi.js";
5
- import { gitSource } from "./history.js";
6
- import { createHash } from "node:crypto";
7
- import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
4
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
8
5
  import { createServer } from "node:http";
9
- import { basename, dirname, extname, join, resolve } from "node:path";
6
+ import { basename, dirname, join, resolve } from "node:path";
10
7
  import { freemem, tmpdir } from "node:os";
11
- import { gunzip, gunzipSync, gzip, gzipSync } from "node:zlib";
12
- import { WEB, WEBFONTS, bundleDir, bundleDirIn, ensureBundle, prepare, useBundleDir } from "./pipeline.js";
8
+ import { bundleDirIn, ensureBundle, prepare, useBundleDir } from "./pipeline.js";
13
9
  import { makeArtwork, pngOf, projectView } from "./artcmd.js";
14
- import { SiteBusy, cacheHome, dataHome, lockSite, openSite, projectDirs } from "./dirs.js";
10
+ import { SiteBusy, cacheHome, lockSite, openSite, projectDirs } from "./dirs.js";
15
11
  import { ProjectError, openProject, targetsInWords } from "./project.js";
16
12
  import { Live } from "./live.js";
17
13
  import { ReviewStore } from "./review.js";
18
- import { isDeclName, LeanHover } from "./hover.js";
19
- import { Identities, layoutAuthor } from "./identity.js";
14
+ import { LeanHover } from "./hover.js";
15
+ import { Identities } from "./identity.js";
20
16
  import { LAYOUT_VERSION } from "../shared/graph.js";
21
- import { MAX_MEMORY_BYTES, readProjectView, Views } from "./views.js";
22
- import { cleanView, defaultAgentName, nameKey, validSession, withoutArtwork } from "../shared/collab.js";
17
+ import { readProjectView, Views } from "./views.js";
23
18
  import { writeSnapshot } from "./snapshot.js";
24
- import { lakeTextHash } from "./status.js";
25
- import { invalidTemplate } from "../shared/editor.js";
26
- import { packEdges } from "../shared/edgecodec.js";
27
- import { Access, hostAllowed, KEY_PATH, loadKey, urlHost } from "./access.js";
28
- import { asksForPage, sendAccessPage } from "./accesspage.js";
29
- import { INVITE_PATH, invalidPersonName, Invites, taken } from "./invites.js";
30
- import { AGENT_LEVELS, AgentApi, lower, needOf, refusal } from "./agent.js";
31
- import { AgentTokens, bearerOf, DEFAULT_DAYS, invalidAgentName, looksLikeToken, TOKEN_DAYS } from "./tokens.js";
32
- import { agentPrompt } from "./prompt.js";
33
- import { MAX_PERSON } from "./talk.js";
34
- import { DEFAULT_JOBS, inGB, jobsAdvice, memoryFloor, onMathlib, UsagePass, mergeUsage, saveMerged, WORKER_PEAK } from "./usage.js";
19
+ import { Access, loadKey, urlHost } from "./access.js";
20
+ import { AgentApi } from "./agent.js";
21
+ import { inGB, jobsAdvice, memoryFloor, onMathlib, UsagePass, mergeUsage, saveMerged, WORKER_PEAK } from "./usage.js";
35
22
  import { extract } from "./extract.js";
36
23
  import { Exporter } from "./export.js";
37
- import { Library, libraryApiOf } from "./library.js";
38
- import { libraryRoute, pdfjsAsset, readUpload } from "./libraryroute.js";
39
- import { UPLOAD_PATH } from "./agentlibrary.js";
40
- import { DEFAULT_LIBRARY_LIMIT, validSha } from "../shared/library.js";
24
+ import { Library } from "./library.js";
41
25
  import { doctor, packageVersion, printReport } from "./doctor.js";
42
- import { READONLY_PATH } from "./readonly.js";
43
- import { sendMedia, TIP_PATH, TIPS_DIR, tipClips, tourData, tourVtt } from "./media.js";
44
- import { withoutReasons } from "../shared/timeline.js";
45
- import { FROM_PACKAGE, PACKAGE_ROOT, UPDATE_MODES, Updates } from "./updates.js";
26
+ import { FROM_PACKAGE, PACKAGE_ROOT, Updates } from "./updates.js";
46
27
  import { RESTART_STATUS, supervise } from "./supervise.js";
47
28
  import { stopChildren } from "./children.js";
48
- import { filmStatus, serveFilm, useFilm } from "./film.js";
49
- import { finalAnswer, readOnlyAllows, ReadOnlyBounds } from "./readonlygate.js";
50
- import { branchProblem, branchToFollow, DEFAULT_POLL_MINUTES, DeployBusy, deployFolder, Deployment, deploySite, ensureClone, isGitAddress, lockDeployment, MIN_POLL_MINUTES, parseRemote, recordedDefault } from "./deploy.js";
51
- import { shortCommit, slimDeploy } from "../shared/deploy.js";
52
- /** The usage, to stderr with status 2 for a command line it cannot read; asked for (`--help`),
53
- * to stdout with status 0. */
54
- function usage(code = 2) {
55
- (code === 0 ? console.log : console.error)(`usage: visualproof serve <lean-project | git URL> [--branch name] [--poll ${DEFAULT_POLL_MINUTES}] [--root Name]... [--port 4173] [--host 127.0.0.1]
56
- [--site dir] [--cache dir] [--graph saved.json]
57
- [--identity-header X-Forwarded-User] [--editor URL-template]
58
- [--agents read|advise|full] [--access-key-file file] [--public] [--jobs ${DEFAULT_JOBS}]
59
- [--public-url https://host] [--allowed-host name]... [--library-limit GB]
60
- [--updates auto|notify|off]
61
- visualproof purge-file <lean-project> <sha256> [--site dir] [--cache dir]
62
- visualproof export <lean-project> -o page.html [--label text] [--root Name]... [--graph saved.json]
63
- [--jobs ${DEFAULT_JOBS}] [--site dir] [--cache dir]
64
- visualproof artwork <lean-project> --recipe recipe.json [-o name] [--png] [--svg] [--root Name]...
65
- [--site dir] [--cache dir] [--jobs ${DEFAULT_JOBS}] [--screen 1920x1200] [--graph saved.json]
66
- visualproof doctor [<lean-project>] [--root Name]... [--site dir] [--cache dir]
67
- visualproof --version
68
-
69
- Reads what \`lake build\` left in <lean-project>/.lake. It never builds the project, and writes
70
- nothing into it.
71
-
72
- A git URL where the project goes (https://github.com/owner/repo, ssh://…, git@host:owner/repo, or
73
- file:///path for a repository on this machine): the server follows that branch of the repository
74
- in a clone of its own in the cache, never a workspace, and builds each new commit itself —
75
- \`lake exe cache get\` where the project is on Mathlib, then \`lake build\` — one at a time, the
76
- newest commit pushed meanwhile the only one built after it; the board shows the last build
77
- meanwhile. Git's own credentials (an SSH key, a deploy key, a credential helper): VisualProof keeps
78
- none, and nothing waits on a prompt. Whoever can push to the branch runs code on this machine, as
79
- the server's user (SECURITY.md): run it as a user of its own, and protect the branch.
80
- --branch the branch followed (default: the remote's default branch); never a pull request's or
81
- a fork's
82
- --poll how often the remote is asked for the branch's head, in minutes (default ${DEFAULT_POLL_MINUTES})
83
-
84
- --root what to read: a library of the lakefile (the modules Lake builds of it) or a module;
85
- repeatable. By default the lakefile's default targets.
86
- --site the site's folder: the review's logs and what this running site accumulates — the
87
- history of builds, the library's files, the views and their layouts, the timeline,
88
- conversations with agents, agents' tokens and personal links. It cannot be derived
89
- again and holds secrets: back it up, never commit it. One server at a time uses a
90
- site. Relative to the current directory, or absolute; default:
91
- ${join(dataHome(), "sites", "<project>-<hash>")}
92
- --cache the root of the caches, which a rebuild makes again: the project's (extractions, the
93
- usage pass's results, prepared views, typeset documents, Lean's language server's
94
- folder) in projects/<project>-<hash>/, the Lean programs compiled per toolchain in
95
- lean/, the page's bundle in web/, VisualProof's own releases in updates.json and the
96
- patches downloaded in versions/ (code the servers run: keep the root yours alone),
97
- and the tips' tour film in media/.
98
- Default: ${cacheHome()}
99
- (XDG_DATA_HOME and XDG_CACHE_HOME move both homes, on any platform)
100
-
101
- --graph use a saved extraction (a projects/*/extract/*.json of the cache) instead of reading
102
- the build; the project path still supplies the sources
103
- export writes one self-contained HTML file: the page, its data and the sources, frozen
104
-
105
- artwork makes the picture an artwork recipe says (the agents' API's, docs/agent-api/export.md:
106
- the size, the look, names by a rule, the targets, the selection), as the page's
107
- artwork mode makes it, without a browser: an SVG and a PNG (--png or --svg for one),
108
- named by -o (a name, or a path without its extension), else the recipe's title, else
109
- the project. With --site, the board as that site keeps it (its layout, pins and folds)
110
- and its review's targets; without, the board as a new site would lay it out, and the
111
- targets the recipe names. --screen: the screen the board is drawn on, as a reader's
112
- (default 1920x1200, at least 640x480): how large names are in the picture. It reads
113
- the site, never writes it; it writes the files and the cache's extraction. Anything
114
- that fails ends it with status 1. Notes are not drawn yet.
115
-
116
- --identity-header behind a proxy that authenticates (Tailscale, oauth2-proxy, …): take each
117
- reader's name from this header instead of the name the page gives. Only use it when
118
- the proxy is the only way to reach the server: the header is believed as it comes.
119
-
120
- --editor link each declaration to its place in an editor, through a URL template:
121
- "vscode://file/{path}:{line}:{col}" for VS Code on this machine, or
122
- "vscode://vscode-remote/ssh-remote+HOST{path}:{line}" for VS Code over SSH to it.
123
- {path} is the file on this machine, {rel} the file in the project, {line} and {col}
124
- where the declaration starts. Each reader can set their own in the page (?).
125
-
126
- --agents what AI agents (requests with X-VisualProof-Kind: agent; their API is /api/agent) may
127
- change: read — nothing; advise — give advice and leave notes; full (the default) — also
128
- whatever a person can do through the page (targets, key declarations, trust, views,
129
- pins), each recorded as the agent's. An agent's opinion is advice whatever the level:
130
- shown apart, never counted; agent tokens stay with people.
131
-
132
- --jobs how many modules the usage pass elaborates at once (default ${DEFAULT_JOBS}; 0: no pass). The
133
- pass finds which notation each declaration is written in and the exact context it is
134
- written in (TCBSpec.md, decisions 2 and 4); its findings follow the extractor's graph
135
- as its next version. Each worker takes about 400 MB of its own, several GB on a large
136
- project on Mathlib (serve and doctor say which --jobs the memory fits); with memory
137
- short, fewer run at a time. The import of a module is bound by memory bandwidth: past
138
- about a quarter of the cores it gains little.
139
-
140
- --access-key-file let in only those given the link http://<host>:<port>/k/<key>, the key being
141
- what the file holds (one is made there, readable by its owner alone, if there is none).
142
- The link leaves a cookie in the browser; agents send Authorization: Bearer <key>.
143
- Anything else is answered 404, but a browser asking for a page, which is shown one
144
- that says the site is private and nothing of it. Over plain HTTP the key crosses the
145
- network in the clear: it keeps out who was not given the link, not who can watch the
146
- traffic.
147
- Share also gives an AI agent a token of its own (vpa_…), which reaches /api/agent only,
148
- and a person a link of their own (/i/vpp_…), which lets them in and says who they are,
149
- and anyone a read-only link (/r/vpr_…), which lets them see and change nothing shared.
150
-
151
- --public with --access-key-file: whoever comes without the key or a link of their own is let
152
- in read-only, rather than turned away: they see the project, its review and its
153
- history, change nothing that is shared, and are seen by nobody. For a project anyone
154
- may read (a showcase); never for a private one.
155
-
156
- --public-url the address people reach this server at, when it is not the one their browser
157
- sends (a proxy in front): the prompt Share makes for an agent tells it this address.
158
-
159
- --allowed-host without --access-key-file, a name this server is reached by; repeatable. A
160
- server without a key answers only requests for an IP address, localhost (and the names
161
- under it), --public-url's host and these: any other name is answered 403, so that a web
162
- page that makes its own name resolve to this machine (DNS rebinding) cannot use it. Give
163
- the names people reach it by: a proxy's in front of it, this machine's own. With a key,
164
- the key keeps everyone else out, whatever the name.
165
-
166
- --updates what the server does with VisualProof's own releases, asked of the npm registry
167
- (through npm) at start and once a day: auto (the default) — a patch of the version it
168
- runs (0.4.x) is downloaded into the cache and taken at a quiet moment, nobody on a page,
169
- open pages reloading where they were; a newer version (0.5.0) is told of, in the log
170
- and the help, with the command that installs it, after which the server restarts into
171
- it by itself; notify — told of, never downloaded; off — never asked (and no
172
- supervisor process), and the tips' tour film never fetched: the server reaches the
173
- network for nothing of its own. VISUALPROOF_UPDATES says the same. From a checkout,
174
- never asked.
175
-
176
- --library-limit the most the project's library of papers and images may take, in GB (default
177
- ${DEFAULT_LIBRARY_LIMIT / 1024 ** 3}); its files are kept in the site directory, by their hash.
178
-
179
- purge-file deletes a file's bytes from the library for good (a file added by mistake), and what
180
- was read of it; its record and its links stay in the review, saying this server lacks it.
181
- Nothing else deletes a file: removing one from the page archives it.
182
-
183
- doctor checks what VisualProof needs on this machine (Node, elan, Poppler, XeLaTeX) and, given
184
- a project, its toolchain, its build and its site, and says what to do; it changes
185
- nothing.`);
186
- process.exit(code);
187
- }
188
- function parseArgs(argv) {
189
- const [cmd, ...rest] = argv;
190
- if (cmd === "--help" || cmd === "-h" || cmd === "help")
191
- usage(0);
192
- if (cmd === "--version" || cmd === "-v") {
193
- console.log(packageVersion());
194
- process.exit(0);
195
- }
196
- if (cmd !== "serve" && cmd !== "export" && cmd !== "purge-file" && cmd !== "doctor" && cmd !== "artwork")
197
- usage();
198
- const fromEnv = process.env.VISUALPROOF_UPDATES;
199
- if (cmd === "serve" && fromEnv !== undefined && !UPDATE_MODES.includes(fromEnv)) {
200
- console.error(`visualproof: VISUALPROOF_UPDATES=${fromEnv}: say auto, notify or off`);
201
- process.exit(2);
202
- }
203
- const o = { cmd, path: "", roots: [], port: 4173, host: "127.0.0.1", site: null, cache: null, graph: null, out: null, label: "VisualProof", identityHeader: null, editor: null, agents: "full", accessKeyFile: null, jobs: DEFAULT_JOBS, publicUrl: null, allowedHosts: [], libraryLimit: DEFAULT_LIBRARY_LIMIT, sha: null, publicRead: false, recipe: null, png: false, svg: false, screen: { w: 1920, h: 1200 }, updates: UPDATE_MODES.includes(fromEnv) ? fromEnv : "auto", remote: null, branch: null, poll: null };
204
- for (let i = 0; i < rest.length; i++) {
205
- const a = rest[i];
206
- const val = () => rest[++i] ?? usage();
207
- if (a === "--root")
208
- o.roots.push(val());
209
- else if (a === "--port")
210
- o.port = Number(val());
211
- else if (a === "--host")
212
- o.host = val();
213
- else if (a === "--site")
214
- o.site = val();
215
- else if (a === "--cache")
216
- o.cache = val();
217
- else if (a === "--graph")
218
- o.graph = resolve(val());
219
- else if (a === "-o" || a === "--out")
220
- o.out = resolve(val());
221
- else if (a === "--label")
222
- o.label = val();
223
- else if (a === "--identity-header")
224
- o.identityHeader = val();
225
- else if (a === "--editor")
226
- o.editor = val();
227
- else if (a === "--access-key-file")
228
- o.accessKeyFile = resolve(val());
229
- else if (a === "--public")
230
- o.publicRead = true;
231
- else if (a === "--recipe" && cmd === "artwork")
232
- o.recipe = resolve(val());
233
- else if (a === "--png" && cmd === "artwork")
234
- o.png = true;
235
- else if (a === "--svg" && cmd === "artwork")
236
- o.svg = true;
237
- else if (a === "--screen" && cmd === "artwork") {
238
- const v = val();
239
- const m = /^(\d+)x(\d+)$/.exec(v);
240
- // said in a line, as --public-url is, rather than the whole usage
241
- if (!m || +m[1] < 640 || +m[2] < 480 || +m[1] > 10000 || +m[2] > 10000) {
242
- console.error(`visualproof artwork: --screen ${v}: give the screen's width and height in pixels, e.g. 1920x1200, from 640x480 to 10000x10000`);
243
- process.exit(2);
244
- }
245
- o.screen = { w: +m[1], h: +m[2] };
246
- }
247
- else if (a === "--public-url") {
248
- const u = val();
249
- if (!/^https?:\/\/[^\s/?#]+\/?$/.test(u)) {
250
- console.error(`visualproof: --public-url ${u}: give the scheme and the host (and port), e.g. https://example.org`);
251
- process.exit(2);
252
- }
253
- o.publicUrl = u.replace(/\/+$/, "");
254
- }
255
- else if (a === "--allowed-host" && cmd === "serve") {
256
- const h = val();
257
- // a name, as a Host header gives it without its port (CollabSpec decision 12)
258
- if (!/^[A-Za-z0-9]([A-Za-z0-9_-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9_-]*[A-Za-z0-9])?)*\.?$/.test(h)) {
259
- console.error(`visualproof: --allowed-host ${h}: give a name this server is reached by, without a scheme or a port, e.g. vp.example.org`);
260
- process.exit(2);
261
- }
262
- o.allowedHosts.push(h);
263
- }
264
- else if (a === "--jobs") {
265
- const n = Number(val());
266
- if (!Number.isInteger(n) || n < 0 || n > 256)
267
- usage();
268
- o.jobs = n;
269
- }
270
- else if (a === "--branch" && cmd === "serve")
271
- o.branch = val();
272
- else if (a === "--poll" && cmd === "serve") {
273
- const v = val();
274
- const m = Number(v);
275
- // said in a line, as --screen is
276
- if (!/^\d+(\.\d+)?$/.test(v) || m < MIN_POLL_MINUTES || m > 1440) {
277
- console.error(`visualproof: --poll ${v}: say how often the remote is asked, in minutes, from ${MIN_POLL_MINUTES} to 1440 (a day)`);
278
- process.exit(2);
279
- }
280
- o.poll = m;
281
- }
282
- else if (a === "--updates" && cmd === "serve") {
283
- const mode = val();
284
- if (!UPDATE_MODES.includes(mode))
285
- usage();
286
- o.updates = mode;
287
- }
288
- else if (a === "--agents") {
289
- const level = val();
290
- if (!AGENT_LEVELS.includes(level))
291
- usage();
292
- o.agents = level;
293
- }
294
- else if (a === "--library-limit") {
295
- const gb = Number(val());
296
- if (!Number.isFinite(gb) || gb <= 0 || gb > 10000)
297
- usage();
298
- o.libraryLimit = Math.round(gb * 1024 ** 3);
299
- }
300
- else if (a.startsWith("-"))
301
- usage();
302
- else if (!o.path)
303
- o.path = a;
304
- else if (cmd === "purge-file" && !o.sha)
305
- o.sha = a;
306
- else
307
- usage();
308
- }
309
- if ((!o.path && cmd !== "doctor") || (cmd === "export" && !o.out) || (cmd === "artwork" && !o.recipe))
310
- usage();
311
- // a git address where the project goes: the branch followed and built (DeploySpec decisions 1,
312
- // 10 and 11), its address and branch checked before anything is run
313
- if (o.path && isGitAddress(o.path)) {
314
- if (cmd !== "serve") {
315
- console.error(`visualproof ${cmd}: ${o.path.slice(0, 200)} is a git address: only serve follows a branch. Give the folder of its clone, which serve names as it starts (its "clone:" line).`);
316
- process.exit(2);
317
- }
318
- const r = parseRemote(o.path);
319
- if ("error" in r) {
320
- console.error(`visualproof: ${r.error}`);
321
- process.exit(2);
322
- }
323
- if (o.graph) {
324
- console.error("visualproof: --graph does not go with a git address: the server builds what it shows");
325
- process.exit(2);
326
- }
327
- const why = o.branch === null ? null : branchProblem(o.branch);
328
- if (why) {
329
- console.error(`visualproof: --branch ${why}`);
330
- process.exit(2);
331
- }
332
- o.remote = r;
333
- }
334
- else if (o.branch !== null || o.poll !== null) {
335
- console.error("visualproof: --branch and --poll go with a git address (serve https://github.com/owner/repo): a folder is read as its owner's builds leave it");
336
- process.exit(2);
337
- }
338
- // read-only for whoever comes, beside those the key or a link lets in: without a key, everyone is in
339
- // already; behind a sign-in, there is nobody else
340
- if (o.publicRead && (!o.accessKeyFile || o.identityHeader)) {
341
- console.error("visualproof: --public lets in read-only whoever has no key: it needs --access-key-file, and does not go with --identity-header");
342
- process.exit(2);
343
- }
344
- // the names a server without a key answers: with one, the key keeps everyone else out whatever
345
- // the name (CollabSpec decision 12)
346
- if (o.allowedHosts.length && o.accessKeyFile)
347
- console.warn("visualproof: --allowed-host changes nothing with --access-key-file: the key lets in whoever has it, by any name");
348
- if (cmd === "purge-file" && !validSha(o.sha)) {
349
- console.error("visualproof purge-file: give the file's SHA-256, 64 hex digits, as the page's library shows it.");
350
- process.exit(2);
351
- }
352
- // a template that cannot make a link is said at the start, not found out by a reader's click
353
- const why = o.editor === null ? null : invalidTemplate(o.editor);
354
- if (why) {
355
- console.error(`visualproof: --editor ${o.editor}: ${why}`);
356
- process.exit(2);
357
- }
358
- return o;
359
- }
360
- /** The server's answers to requests: exported so that the tests serve them as the server does. */
361
- export class App {
362
- live;
363
- hover;
364
- ids;
365
- /** how long a read of the project's git (GET /api/git) is kept, whoever asks: git is run at most
366
- * once in that time, so what readers cost the server is bounded (CollabSpec decision 11); 0 in
367
- * the tests */
368
- gitFreshMs = 3000;
369
- gitRead = null;
370
- /** the agents' API (server/agent.ts), and what agents may change */
371
- agents;
372
- /** who may come in at all (server/access.ts); null: anyone who reaches the port */
373
- access;
374
- /** the exported document's typesetting (server/export.ts, ExportSpec.md); null: no export here */
375
- exporter;
376
- /** the address people reach the server at, for the prompt Share makes (--public-url); null: the
377
- * one the person's browser used */
378
- publicUrl;
379
- /** --public: whoever comes without the key or a link of their own reads only (CollabSpec
380
- * decision 11) */
381
- publicRead;
382
- /** without a key, the names this server answers besides its addresses and localhost
383
- * (server/access.ts, hostAllowed): --public-url's host and every --allowed-host; null: every
384
- * name, the key keeping everyone else out */
385
- hostNames;
386
- /** the names refused as Host, said once each in the server's console (a few: whoever asks
387
- * chooses them) */
388
- refusedHosts = new Set();
389
- /** the read-only readers' requests, by the read-only link they came by, or "public" */
390
- readOnlyOf = new WeakMap();
391
- /** what read-only readers may cost the server: Lean's answers, their documents */
392
- bounds;
393
- /** VisualProof's own releases as this server follows them (server/updates.ts); null: the
394
- * version alone is told (a test's server) */
395
- updates = null;
396
- constructor(live, hover, ids, agents, access, exporter = null, publicUrl = null, publicRead = false, allowedHosts = []) {
397
- this.live = live;
398
- this.hover = hover;
399
- this.ids = ids;
400
- this.agents = agents;
401
- this.access = access;
402
- // a personal link says who its holder is (CollabSpec decision 9); behind a proxy that signs
403
- // people in, the proxy does, and there are no personal links
404
- ids.invites = ids.header ? null : live.invites;
405
- this.exporter = exporter;
406
- // agents typeset as people do (ExportSpec decision 11), through their API
407
- agents.exporter = exporter;
408
- this.publicUrl = publicUrl;
409
- this.publicRead = publicRead && access !== null;
410
- this.hostNames = access ? null : [...(publicUrl ? [urlHost(publicUrl)] : []), ...allowedHosts];
411
- this.bounds = new ReadOnlyBounds((id) => this.exporter?.job(id)?.state === "running");
412
- }
413
- /** Whether a request is told all of the server's own releases (UpdateSpec decision 11): someone
414
- * let in fully; not a read-only reader, nor an agent. */
415
- toldAll(req) {
416
- return this.readOnlyOf.get(req) === undefined && this.ids.kind(req) !== "agent";
417
- }
418
- /** The exported document (ExportSpec decisions 5–16): POST /api/export starts typesetting the
419
- * document of a view, `{view, settings, version?}` (a build the Time Machine shows the view at;
420
- * left out, the view's own), and answers with its job at once; the page asks how the
421
- * job is doing (GET /api/export/job) and fetches the PDF and the LaTeX sources once it is done
422
- * (GET /api/export/file). The answers are the agents' API's (server/agent.ts), which has the same
423
- * routes under /api/agent/; an agent that comes here is held to its one job at a time there too.
424
- * The window shows the title and the author line the document will have (GET /api/export/head
425
- * ?view=&version=: ExportSpec decisions 14 and 15), which only the server can tell: who dropped
426
- * each pin is never sent to pages. */
427
- async export(req, res, url, agent, readOnly = false) {
428
- const path = url.pathname;
429
- const api = this.agents;
430
- // the document's outline, which the linear form draws: nothing is typeset for it
431
- if (path === "/api/export/outline") {
432
- const o = api.exportOutline(url.searchParams.get("view") ?? "", url.searchParams.get("version") ?? undefined);
433
- return sendJson(res, o.body, o.status, o.headers);
434
- }
435
- if (!this.exporter)
436
- return sendJson(res, { error: "This server does not export documents." }, 404);
437
- let a;
438
- if (path === "/api/export" && req.method === "POST") {
439
- const caller = agent ? { name: this.ids.who(req), kind: "agent" } : null;
440
- if (caller && !caller.name)
441
- return sendJson(res, { error: "Say who you are first.", who: true }, 401);
442
- const r = await this.json(req, 1 << 20);
443
- if (r.error !== undefined)
444
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
445
- // read-only readers typeset one document at a time among them (CollabSpec decision 11): while
446
- // one is being typeset, the others wait, even one the export's cache holds. The place is
447
- // taken before the job starts, so that two requests at once cannot both start one.
448
- if (readOnly) {
449
- if (!this.bounds.mayExport())
450
- return sendJson(res, { error: "Another document is being typeset for readers of this page: try again in a little while." }, 429, { "retry-after": "5" });
451
- this.bounds.reserveExport();
452
- }
453
- let started;
454
- try {
455
- started = await api.exportStart(r.body, caller);
456
- }
457
- finally {
458
- if (readOnly)
459
- this.bounds.exportStarted(started?.body);
460
- }
461
- a = started;
462
- }
463
- else if (path === "/api/export/head")
464
- a = api.exportHead(url.searchParams.get("view") ?? "", url.searchParams.get("version") ?? undefined);
465
- else if (path === "/api/export/job")
466
- a = api.exportJob(url.searchParams.get("id") ?? "", false);
467
- else if (path === "/api/export/file")
468
- a = api.exportFile(url.searchParams.get("id") ?? "", url.searchParams.get("what"));
469
- else
470
- return sendJson(res, { error: "not found" }, 404);
471
- if (a.file)
472
- return sendDownload(res, a.file);
473
- // the agents' answer as it is: the page shows its error, and an agent that asked here its hint
474
- sendJson(res, a.body, a.status, a.headers);
475
- }
476
- /** A request to the agents' API: read here, answered there. An agent with a token of its own is
477
- * who its token says, whatever its headers say (server/tokens.ts). */
478
- async agent(req, res, url, token = null) {
479
- const said = this.ids.who(req);
480
- const caller = token
481
- ? { name: token.name, kind: "agent", token: { id: token.id, by: token.by, level: token.level, expires: token.expires }, ...(said && said !== token.name ? { ignoredName: said } : {}) }
482
- : { name: said, kind: this.ids.kind(req) };
483
- let body = null;
484
- if (req.method === "POST" && url.pathname.replace(/\/+$/, "") === UPLOAD_PATH) {
485
- // a file for the library: its bytes as they come (server/agentlibrary.ts)
486
- const bytes = await readUpload(req, res);
487
- if (!bytes)
488
- return;
489
- body = { bytes };
490
- }
491
- else if (req.method === "POST") {
492
- const r = await this.json(req, AGENT_BODY);
493
- if (r.error !== undefined)
494
- return sendJson(res, { error: `The body is ${r.error}.`, hint: "Send a JSON object, with content-type: application/json." }, 400);
495
- body = r.body;
496
- }
497
- // a request that waits (the inbox, the companion) learns that its asker went away: an agent's
498
- // wait for messages ends with its connection, so that none is handed to nobody
499
- const away = new AbortController();
500
- res.on("close", () => {
501
- if (!res.writableFinished)
502
- away.abort();
503
- });
504
- // the session an MCP server says it is (since 0.4.0): a wait from another is a new session's
505
- const session = req.headers["x-visualproof-session"];
506
- const a = await this.agents.handle({ method: req.method ?? "GET", path: url.pathname, query: url.searchParams, body, caller, base: this.publicUrl ?? `http://${hostOf(req)}`, signal: away.signal, ...(validSession(session) ? { session } : {}) });
507
- if (away.signal.aborted)
508
- return;
509
- if (a.text)
510
- return sendText(req, res, a.text.body, a.text.type, a.status);
511
- if (a.file)
512
- return sendDownload(res, a.file);
513
- if (a.gz)
514
- return sendGz(req, res, a.gz.body, a.gz.type);
515
- sendJson(res, a.body, a.status, a.headers);
516
- }
517
- /** Talking with an agent (AgentSpec decision 8), for pages: an agent's conversation (GET), and a
518
- * message to it (POST) — from a person with a name, to an agent that is not offline (409
519
- * otherwise: one listening has it at once, one thinking or working at its next wait), at most so
520
- * many a minute. The agent is named as presence names it. */
521
- async chat(req, res, url) {
522
- const live = this.live;
523
- if (req.method === "GET") {
524
- const id = url.searchParams.get("agent") ?? "";
525
- const tok = live.presence.tokenOf(id);
526
- if (!tok)
527
- return sendJson(res, { error: "There is no such agent: only an agent with a token of its own can be talked to." }, 404);
528
- return sendJson(res, { agent: { id, name: live.tokens.get(tok)?.name ?? null, talk: live.talk.talk(tok) }, messages: live.talk.thread(tok) });
529
- }
530
- if (req.method !== "POST")
531
- return sendJson(res, { error: "/api/chat answers GET and POST." }, 405);
532
- if (this.ids.kind(req) === "agent")
533
- return sendJson(res, { error: "Agents answer through their API.", hint: "POST /api/agent/reply." }, 403);
534
- const me = this.ids.who(req);
535
- if (!me)
536
- return sendJson(res, { error: "Say who you are first: a message is sent under your name.", who: true }, 401);
537
- const r = await this.json(req, 1 << 16);
538
- if (r.error !== undefined)
539
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
540
- const b = (r.body ?? {});
541
- const tok = typeof b.agent === "string" ? live.presence.tokenOf(b.agent) : null;
542
- if (!tok)
543
- return sendJson(res, { error: "There is no such agent: only an agent with a token of its own can be talked to." }, 404);
544
- const name = live.tokens.get(tok)?.name ?? "The agent";
545
- if (live.talk.state(tok) === "offline")
546
- return sendJson(res, { error: "offline", message: `${name} is offline: it can be written to once it listens again.` }, 409);
547
- const text = typeof b.text === "string" ? b.text.trim() : "";
548
- if (!text)
549
- return sendJson(res, { error: "The message is empty." }, 400);
550
- if (text.length > MAX_PERSON)
551
- return sendJson(res, { error: `A message is at most ${MAX_PERSON.toLocaleString("en")} characters.` }, 400);
552
- const wait = live.talk.allow("person", me);
553
- if (wait)
554
- return sendJson(res, { error: `Too many messages at once: wait ${wait} s.`, retryAfter: wait }, 429, { "retry-after": String(wait) });
555
- // where the writer was, as the page says it, bounded: a selection can be a long query; a private
556
- // reader's message says nothing of where they are (CollabSpec decision 8), only who wrote it
557
- const view = this.ids.privateOf(req) === null ? cleanView(b.place) : null;
558
- const at = view ? this.agents.placeOf(view) : null;
559
- const clip = (x, n) => (x !== null && x.length > n ? x.slice(0, n - 1) + "…" : x);
560
- const where = at ? { inWords: clip(at.inWords, 600), view: at.view, declaration: clip(at.declaration, 300), selection: clip(at.selection, 300) } : null;
561
- const message = live.talk.post(tok, { from: me, kind: "person", text, where });
562
- return sendJson(res, { ok: true, message });
563
- }
564
- /** A new conversation with an agent (AgentSpec decision 8, the owner's decision of 2026-10-11):
565
- * a divider, from anyone who may write to it — a person with a name — and held to the rate of
566
- * their messages; an offline agent's too, so that its next session starts clean. One right after
567
- * another divides nothing: it is answered `unchanged`, and neither written nor counted. */
568
- async chatNew(req, res) {
569
- const live = this.live;
570
- if (req.method !== "POST")
571
- return sendJson(res, { error: "/api/chat/new answers POST." }, 405);
572
- if (this.ids.kind(req) === "agent")
573
- return sendJson(res, { error: "A new conversation is for people to start." }, 403);
574
- const me = this.ids.who(req);
575
- if (!me)
576
- return sendJson(res, { error: "Say who you are first: a new conversation is started under your name.", who: true }, 401);
577
- const r = await this.json(req, 1 << 12);
578
- if (r.error !== undefined)
579
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
580
- const b = (r.body ?? {});
581
- const tok = typeof b.agent === "string" ? live.presence.tokenOf(b.agent) : null;
582
- if (!tok)
583
- return sendJson(res, { error: "There is no such agent: only an agent with a token of its own can be talked to." }, 404);
584
- if (live.talk.fresh(tok))
585
- return sendJson(res, { ok: true, unchanged: true, divider: null, message: "Nothing was said since the conversation began: it is new already." });
586
- const wait = live.talk.allow("person", me);
587
- if (wait)
588
- return sendJson(res, { error: `Too many at once: wait ${wait} s.`, retryAfter: wait }, 429, { "retry-after": String(wait) });
589
- return sendJson(res, { ok: true, divider: live.talk.restart(tok, me) });
590
- }
591
- /** Asking others to follow (CollabSpec decision 10, the owner's decision of 2026-10-12), for pages:
592
- * POST /api/ask {token, to?} — the page whose event stream holds `token` asks everyone on the
593
- * server, or the person whose page is listed as `to`, to follow its reader, who has a name and is
594
- * visible: a private reader cannot be followed; POST /api/ask/answer {token, id, answer} — a page
595
- * asked answers, whoever its reader is. The server relays both (server/askfollow.ts); agents ask
596
- * through their API (POST /api/agent/ask-follow). */
597
- async ask(req, res, url) {
598
- const live = this.live;
599
- if (req.method !== "POST")
600
- return sendJson(res, { error: `${url.pathname} answers POST.` }, 405);
601
- if (this.ids.kind(req) === "agent")
602
- return sendJson(res, { error: "Agents ask through their API.", hint: "POST /api/agent/ask-follow." }, 403);
603
- const r = await this.json(req, 4096);
604
- if (r.error !== undefined)
605
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
606
- const b = (r.body ?? {});
607
- const page = live.pageStream(b.token);
608
- if (!page)
609
- return sendJson(res, { error: "This request is not from an open event stream of this page's: it is sent with the token the stream says hello with.", stream: false }, 403);
610
- if (url.pathname === "/api/ask/answer") {
611
- const a = live.asks.answer(b.token, b.id, b.answer);
612
- return sendJson(res, a.body, a.status);
613
- }
614
- if (url.pathname !== "/api/ask")
615
- return sendJson(res, { error: "not found" }, 404);
616
- const me = this.ids.who(req);
617
- if (!me)
618
- return sendJson(res, this.nameless(req, "a request to follow you says who asks"), 401);
619
- if (page.private || this.ids.privateOf(req) !== null)
620
- return sendJson(res, { error: "You are private: nobody can follow you. Go visible (the menu under your name) to ask." }, 409);
621
- if (b.to !== undefined && b.to !== null && typeof b.to !== "string")
622
- return sendJson(res, { error: "to is a reader's id, as presence lists them; left out, everyone." }, 400);
623
- const person = this.ids.person(req);
624
- // one request every 30 s per person — their personal link, else their name — and per page
625
- const key = person ? `p:${person.id}` : `n:${nameKey(me)}`;
626
- const a = live.asks.ask({ name: me, verified: !!person, agent: false, from: page.id, stream: b.token, rate: [key, `s:${b.token}`] }, typeof b.to === "string" ? { page: b.to } : { everyone: true });
627
- if ("ok" in a) {
628
- const { report: _, ...sent } = a.ok;
629
- return sendJson(res, { ok: true, ...sent });
630
- }
631
- return sendJson(res, { error: a.error, ...(a.retryAfter ? { retryAfter: a.retryAfter } : {}) }, a.status, a.retryAfter ? { "retry-after": String(a.retryAfter) } : undefined);
632
- }
633
- /** Sharing with an AI agent (AgentSpec decision 7), for people: the tokens in force (GET), a new
634
- * one with its prompt (POST), a token's prompt shown again (POST …/prompt), and revoking one
635
- * (POST …/revoke). All but the list need a name: a token is made under it, and its prompt holds
636
- * the token. The prompt is asked for by POST, as making one is, so that the browser sends its
637
- * Origin and the prompt names the server as the page reached it, the same both times. */
638
- async shareAgents(req, res, url) {
639
- // agent tokens stay with people, at every level (the owner's decision, AgentSpec decision 9):
640
- // an agent that could make, show or revoke tokens could outlive its own revocation. A token
641
- // never gets here (it reaches the agents' API alone), and a request that says it is an agent's
642
- // is refused
643
- if (this.ids.kind(req) === "agent")
644
- return sendJson(res, { error: "Agent tokens are for people: an agent cannot make, show or revoke them, at any level." }, 403);
645
- const tokens = this.live.tokens;
646
- const top = this.agents.level;
647
- const me = this.ids.who(req);
648
- const path = url.pathname.replace(/\/+$/, "");
649
- if (path === "/api/share/agents" && req.method === "GET")
650
- return sendJson(res, { level: top, levels: AGENT_LEVELS.slice(0, AGENT_LEVELS.indexOf(top) + 1), defaultLevel: lower("advise", top), days: TOKEN_DAYS, defaultDays: DEFAULT_DAYS, tokens: tokens.inForce().map(AgentTokens.info) });
651
- if (req.method !== "POST")
652
- return sendJson(res, { error: `${path} answers POST.` }, 405);
653
- if (!me)
654
- return sendJson(res, { error: "Say who you are first: a token is made, shown or revoked under your name.", who: true }, 401);
655
- const r = await this.json(req, 1 << 16);
656
- if (r.error !== undefined)
657
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
658
- const b = (r.body ?? {});
659
- if (path === "/api/share/agents/revoke") {
660
- if (typeof b.id !== "string" || !tokens.revoke(b.id, me))
661
- return sendJson(res, { error: "There is no such token in force." }, 404);
662
- return sendJson(res, { ok: true, tokens: tokens.inForce().map(AgentTokens.info) });
663
- }
664
- // the server as the prompt names it
665
- const address = this.publicUrl ?? reachedAt(req);
666
- if (path === "/api/share/agents/prompt") {
667
- // a token that ended has no prompt: it lets nothing in
668
- const t = typeof b.id === "string" ? tokens.token(b.id) : null;
669
- if (!t)
670
- return sendJson(res, { error: "There is no such token in force." }, 404);
671
- return sendJson(res, { token: AgentTokens.info(t.record), prompt: agentPrompt({ url: address, token: t.token, record: t.record }) });
672
- }
673
- if (path !== "/api/share/agents")
674
- return sendJson(res, { error: "not found" }, 404);
675
- // the name given is the agent's as it is; none, the person's AI ("Alice's AI")
676
- const name = b.name === undefined || b.name === null || (typeof b.name === "string" && !b.name.trim()) ? defaultAgentName(me) : b.name;
677
- const bad = invalidAgentName(name);
678
- if (bad)
679
- return sendJson(res, { error: bad }, 400);
680
- const level = (b.level ?? lower("advise", top));
681
- if (!AGENT_LEVELS.includes(level))
682
- return sendJson(res, { error: "level is read, advise or full." }, 400);
683
- if (AGENT_LEVELS.indexOf(level) > AGENT_LEVELS.indexOf(top))
684
- return sendJson(res, { error: `This server lets agents do at most ${top} (--agents ${top}): a token cannot give more.` }, 400);
685
- const days = b.days ?? DEFAULT_DAYS;
686
- if (!TOKEN_DAYS.includes(days))
687
- return sendJson(res, { error: `days is one of ${TOKEN_DAYS.join(", ")}.` }, 400);
688
- const made = tokens.create({ name: name.trim(), by: me, level, days: days });
689
- const prompt = agentPrompt({ url: address, token: made.token, record: made.record });
690
- return sendJson(res, { token: AgentTokens.info(made.record), prompt, tokens: tokens.inForce().map(AgentTokens.info) });
691
- }
692
- /** Inviting a person (CollabSpec decision 9), for people: the personal links in force (GET), a new
693
- * one for a person named in the body (POST), and revoking one (POST …/revoke). Making and
694
- * revoking need a name: who made a link, and who revoked it, is said in Share. The link itself
695
- * is answered once, to whoever made it: the server keeps only its digest (server/invites.ts). */
696
- async sharePeople(req, res, url) {
697
- if (this.ids.kind(req) === "agent")
698
- return sendJson(res, { error: "Personal links are for people: an agent cannot make, list or revoke them." }, 403);
699
- if (this.ids.header)
700
- return sendJson(res, { error: "Names come from the sign-in in front of this server: it has no personal links." }, 404);
701
- const invites = this.live.invites;
702
- const path = url.pathname.replace(/\/+$/, "");
703
- const list = () => invites.inForce().map(Invites.info);
704
- if (path === "/api/share/people" && req.method === "GET")
705
- return sendJson(res, { invites: list() });
706
- if (req.method !== "POST")
707
- return sendJson(res, { error: `${path} answers POST.` }, 405);
708
- const me = this.ids.who(req);
709
- if (!me)
710
- return sendJson(res, this.nameless(req, "a personal link is made or revoked under your name"), 401);
711
- const r = await this.json(req, 4096);
712
- if (r.error !== undefined)
713
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
714
- const b = (r.body ?? {});
715
- if (path === "/api/share/people/revoke") {
716
- if (typeof b.id !== "string" || !invites.revoke(b.id, me))
717
- return sendJson(res, { error: "There is no such personal link in force." }, 404);
718
- return sendJson(res, { ok: true, invites: list() });
719
- }
720
- if (path !== "/api/share/people")
721
- return sendJson(res, { error: "not found" }, 404);
722
- const bad = invalidPersonName(b.name);
723
- if (bad)
724
- return sendJson(res, { error: bad }, 400);
725
- const made = invites.create({ name: b.name, by: me });
726
- if (typeof made === "string")
727
- return sendJson(res, { error: made, taken: true }, 409);
728
- // the link as the person will open it: the server's address as this page reached it
729
- const link = `${this.publicUrl ?? reachedAt(req)}${INVITE_PATH}${made.token}`;
730
- return sendJson(res, { invite: Invites.info(made.record), link, invites: list() });
731
- }
732
- /** Read-only links (CollabSpec decision 11), for people: every link (GET), a new one (POST), and
733
- * revoking one (POST …/revoke). Anyone let in may make one; revoking needs a name, which Share
734
- * says beside the link. A server open to all, or behind a sign-in, has none. */
735
- async shareReadOnly(req, res, url) {
736
- if (this.ids.kind(req) === "agent")
737
- return sendJson(res, { error: "Read-only links are for people: an agent cannot make, list or revoke them." }, 403);
738
- if (!this.access || this.ids.header)
739
- return sendJson(res, { error: this.ids.header ? "Who comes in is the sign-in's, in front of this server: it has no read-only links." : "This server lets in whoever reaches it: a read-only link would let in no one more." }, 404);
740
- const links = this.live.readOnly;
741
- const path = url.pathname.replace(/\/+$/, "");
742
- const address = this.publicUrl ?? reachedAt(req);
743
- const list = () => links.list().map((l) => ({ ...l, link: `${address}${l.path}` }));
744
- if (path === "/api/share/readonly" && req.method === "GET")
745
- return sendJson(res, { links: list() });
746
- if (req.method !== "POST")
747
- return sendJson(res, { error: `${path} answers POST.` }, 405);
748
- const me = this.ids.who(req);
749
- if (path === "/api/share/readonly/revoke") {
750
- if (!me)
751
- return sendJson(res, this.nameless(req, "a read-only link is revoked under your name"), 401);
752
- const r = await this.json(req, 4096);
753
- if (r.error !== undefined)
754
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
755
- const id = r.body?.id;
756
- if (typeof id !== "string" || !links.revoke(id, me))
757
- return sendJson(res, { error: "There is no such read-only link in force." }, 404);
758
- return sendJson(res, { ok: true, links: list() });
759
- }
760
- if (path !== "/api/share/readonly")
761
- return sendJson(res, { error: "not found" }, 404);
762
- const made = links.create(me);
763
- return sendJson(res, { made: { ...made, link: `${address}${made.path}` }, links: list() });
764
- }
765
- /** A personal link opened (CollabSpec decision 9): the browser is given the cookie that lets its
766
- * holder in, as who the link says, and goes on to the page — the token leaves the address, and a
767
- * place after it (a fragment) comes along. A revoked link says so; anything else is answered as
768
- * any address nobody was given. On a server with a key, a browser is shown the page of a link
769
- * that does not open the site instead (CollabSpec decision 7), which says neither which it was
770
- * nor who revoked it — unless the key or a link of its own lets it in, and it may be told. */
771
- enter(req, res, token, path) {
772
- const c = this.ids.header ? null : this.live.invites.check(token);
773
- if (c && "ok" in c) {
774
- res.writeHead(303, { location: "/", "set-cookie": this.live.invites.cookie(c.ok), "cache-control": "no-store", "referrer-policy": "no-referrer" });
775
- return void res.end();
776
- }
777
- if (this.access && asksForPage(req, path) && (!c || !this.letIn(req)))
778
- return sendAccessPage(res, "link", this.publicRead);
779
- if (c)
780
- return sendText(req, res, revokedWords(c.record, "personal") + "\n", "text/plain; charset=utf-8", 410);
781
- sendJson(res, { error: "not found" }, 404);
782
- }
783
- /** A read-only link opened (CollabSpec decision 11): the browser is given the cookie that lets
784
- * its holder read, and goes on to the page — the token leaves the address, and a place after it
785
- * (a fragment) comes along. A revoked link says so; anything else, and any link on a server
786
- * open to all or behind a sign-in, which have none, is answered as an address nobody was given;
787
- * to a browser, on a server with a key, as a personal link's (enter). */
788
- enterReadOnly(req, res, token, path) {
789
- const c = this.access && !this.ids.header ? this.live.readOnly.check(token) : null;
790
- if (c && "ok" in c) {
791
- res.writeHead(303, { location: "/", "set-cookie": this.live.readOnly.cookie(c.ok.id), "cache-control": "no-store", "referrer-policy": "no-referrer" });
792
- return void res.end();
793
- }
794
- if (this.access && asksForPage(req, path) && (!c || !this.letIn(req)))
795
- return sendAccessPage(res, "link", this.publicRead);
796
- if (c)
797
- return sendText(req, res, revokedWords(c.link, "read-only") + "\n", "text/plain; charset=utf-8", 410);
798
- sendJson(res, { error: "not found" }, 404);
799
- }
800
- /** Whether the key's cookie or a personal link in force lets a request in: someone who sees the
801
- * site's people, and may be told who revoked a link. */
802
- letIn(req) {
803
- return !!this.ids.person(req) || this.access?.admit(req, "/") === "in";
804
- }
805
- /** Who the reader is (POST /api/identity {name}): the name someone invited by a personal link goes
806
- * by from now on — kept with their link, and said in their review log, so that what they wrote
807
- * shows under it — or, for a guest, whether a name is theirs to take: one a link's holder goes
808
- * by is not (409). A guest's name is their page's own; nothing of it is kept here. */
809
- async identity(req, res) {
810
- if (this.ids.kind(req) === "agent")
811
- return sendJson(res, { error: "An agent's name is its own: its token's, or the one it sends." }, 403);
812
- if (this.ids.header)
813
- return sendJson(res, { error: "Your name is the sign-in's, in front of this server: it cannot be changed here." }, 403);
814
- const r = await this.json(req, 4096);
815
- if (r.error !== undefined)
816
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
817
- const name = r.body?.name;
818
- const bad = invalidPersonName(name);
819
- if (bad)
820
- return sendJson(res, { error: bad }, 400);
821
- const n = name.trim();
822
- const p = this.ids.person(req);
823
- if (!p) {
824
- const holder = this.live.invites.holder(n);
825
- return holder ? sendJson(res, { error: taken(holder), taken: true }, 409) : sendJson(res, { ok: true, name: n });
826
- }
827
- const was = p.name;
828
- const done = this.live.invites.rename(p.id, n);
829
- if (typeof done === "string")
830
- return sendJson(res, { error: done, taken: true }, 409);
831
- // their log says so, where they have one: what they wrote shows under the new name everywhere.
832
- // A log that cannot be written to now (a line to mend by hand) says it with their next line,
833
- // which carries the name it is written under
834
- if (done.name !== was)
835
- this.live.review.named(p.id, done.name);
836
- return sendJson(res, { ok: true, name: done.name, person: Invites.info(done) });
837
- }
838
- /** A request for a name this server without a key does not answer (CollabSpec decision 12): 403,
839
- * saying which option lets the name in; and, once per name, the server's console says it too,
840
- * for whoever runs it behind a proxy that forwards the name people reach it by. A browser asking
841
- * for a page is shown a page that says so (the owner's decision of 2026-10-18), which does not
842
- * repeat the name: it is the requester's, any text at all. */
843
- refuseHost(req, res, path) {
844
- const raw = req.headers.host ?? "";
845
- const name = /^\[/.test(raw) ? raw : raw.replace(/:\d{1,5}$/, "");
846
- const shown = /^[A-Za-z0-9._\-[\]:]{1,253}$/.test(name) ? name : null;
847
- if (shown && this.refusedHosts.size < 20 && !this.refusedHosts.has(shown.toLowerCase())) {
848
- this.refusedHosts.add(shown.toLowerCase());
849
- console.error(`refused a request for ${shown}: without an access key this server answers only its addresses, localhost, --public-url's host and the --allowed-host names; --allowed-host ${shown} lets this one in`);
850
- }
851
- if (asksForPage(req, path))
852
- return sendAccessPage(res, "host");
853
- sendText(req, res, `This server answers only the names it is meant to be reached by${shown ? `, and ${shown} is not one of them` : ""}. Whoever runs it can let a name in with --allowed-host${shown ? ` ${shown}` : " <name>"}.\n`, "text/plain; charset=utf-8", 403);
854
- }
855
- /** The answer to a request that needs a name and has none: the page asks for one (`who`). Where
856
- * the name the page gives is a personal link holder's, it says so, and the page asks for
857
- * another. */
858
- nameless(req, what) {
859
- const holder = this.ids.taken(req);
860
- return { error: holder ? `${taken(holder)} (Click your name.)` : `Say who you are first: ${what}.`, who: true };
861
- }
862
- /** The library's operations (server/library.ts), shared with the agents' API. */
863
- library() {
864
- return libraryApiOf(this.live, () => ({
865
- review: this.live.review,
866
- project: this.live.project,
867
- library: this.live.library,
868
- graph: () => {
869
- const v = this.agents.reviews.graph();
870
- return "status" in v ? null : v;
871
- },
872
- // every file the library takes shows on the Project: a note carries it, on the ring
873
- fileAdded: (f, who, note) => void this.live.views.fileAdded(f, { by: who.name, agent: who.agent, person: who.person ?? null }, note),
874
- }));
875
- }
876
- /** A request about views (server/views.ts): read here, answered there. A private page's is
877
- * answered as its, recorded without its name (CollabSpec decision 8). */
878
- async views(req, res, url) {
879
- const priv = this.ids.privateOf(req);
880
- const person = this.ids.person(req);
881
- const caller = { name: this.ids.who(req), kind: this.ids.kind(req), ...(person ? { person: person.id } : {}), ...(priv !== null ? { private: { session: priv || null } } : {}) };
882
- let body = null;
883
- if (req.method === "POST") {
884
- // a board's layout memory is as large as the board; nothing else about views is
885
- const r = await this.json(req, url.pathname.replace(/\/+$/, "") === "/api/views/memory" ? MAX_MEMORY_BYTES : 1 << 20);
886
- if (r.error !== undefined)
887
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
888
- body = r.body;
889
- }
890
- const a = this.live.views.handle({ method: req.method ?? "GET", path: url.pathname, query: url.searchParams, body, caller }, this.agents.level);
891
- sendJson(res, a.body, a.status, a.headers);
892
- }
893
- /** A request's JSON body, or why it has none. A body larger than `limit` is answered here and
894
- * now, 413 (as the agents' API words its errors under /api/agent), and the connection closed
895
- * after it, without reading the rest; whoever asked for the body is told `too large`, and what
896
- * it answers after is not sent (sendJson). */
897
- async json(req, limit) {
898
- let text;
899
- try {
900
- text = await readBody(req, limit);
901
- }
902
- catch (e) {
903
- const res = this.responses.get(req);
904
- if (!(e instanceof TooLarge) || !res)
905
- return { error: e instanceof Error ? e.message : String(e) };
906
- const size = limit >= 1 << 20 ? `${Math.round(limit / (1 << 20))} MB` : `${Math.round(limit / 1024)} KB`;
907
- const agent = (req.url ?? "").startsWith("/api/agent");
908
- tooLarge(req, res, { error: `The body is larger than ${size}, as much as this request takes.`, ...(agent ? { hint: "Send less at once: fewer items per request (POST /api/agent/opinions takes 100 at most), or split the request." } : {}) });
909
- return { error: "too large" };
910
- }
911
- try {
912
- return { body: JSON.parse(text) };
913
- }
914
- catch {
915
- return { error: "not JSON" };
916
- }
917
- }
918
- /** each request's response, for what answers a request while reading it (a body too large) */
919
- responses = new WeakMap();
920
- /** Answer a request; whatever goes wrong in answering it is answered too, 500 with what it was,
921
- * rather than left hanging or taking the server down. */
922
- handle(req, res) {
923
- this.responses.set(req, res);
924
- this.route(req, res).catch((e) => {
925
- console.error(`${req.method} ${req.url?.slice(0, 200)}: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`);
926
- const agent = (req.url ?? "").startsWith("/api/agent");
927
- if (!res.headersSent)
928
- sendJson(res, { error: e instanceof Error ? e.message : String(e), ...(agent ? { hint: "This is the server's fault; the request may work again." } : {}) }, 500);
929
- else
930
- res.destroy();
931
- });
932
- }
933
- async route(req, res) {
934
- const url = new URL(req.url ?? "/", "http://localhost");
935
- const path = url.pathname;
936
- const live = this.live;
937
- // without a key, only the names this server is reached at (CollabSpec decision 12, the owner's
938
- // decision of 2026-10-18): a page whose own name was made to resolve to this machine (DNS
939
- // rebinding) is refused whatever it asks — the page, its data, the event stream, the agents'
940
- // API, the MCP server's file
941
- if (this.hostNames && !hostAllowed(req.headers.host, this.hostNames))
942
- return this.refuseHost(req, res, path);
943
- // every route; whatever one throws, handle() answers
944
- {
945
- // an agent's own token (server/tokens.ts) lets it into its API alone: the page and the page's
946
- // API answer it as they answer an outsider. A token that ended says so, to whoever held it.
947
- const bearer = bearerOf(req.headers.authorization);
948
- if (bearer && looksLikeToken(bearer)) {
949
- const t = live.tokens.check(bearer);
950
- if (!t)
951
- return sendJson(res, this.access ? { error: "not found" } : { error: "This token is not one of this server's.", hint: "Check that it was copied whole (vpa_…), or ask the person who shared with you for a new one." }, this.access ? 404 : 401);
952
- if ("ended" in t)
953
- return sendJson(res, {
954
- error: t.ended === "revoked" ? `This token was revoked by ${t.record.revokedBy} at ${t.record.revoked}.` : `This token expired at ${t.record.expires}.`,
955
- hint: "Ask the person who shared with you for a new one (Share, then AI agent, in the page).",
956
- }, 401);
957
- if (path !== "/api/agent" && !path.startsWith("/api/agent/"))
958
- return sendJson(res, { error: "not found" }, 404);
959
- return this.agent(req, res, url, t.ok);
960
- }
961
- // a personal link (CollabSpec decision 9, server/invites.ts): it lets its holder in, as who
962
- // it says, and its cookie does from then on; a revoked one's cookie is forgotten, and lets
963
- // nobody in
964
- if (path.startsWith(INVITE_PATH))
965
- return this.enter(req, res, path.slice(INVITE_PATH.length), path);
966
- // a read-only link (CollabSpec decision 11, server/readonly.ts): its cookie lets its holder
967
- // read, where nothing else lets them in
968
- if (path.startsWith(READONLY_PATH))
969
- return this.enterReadOnly(req, res, path.slice(READONLY_PATH.length), path);
970
- const link = this.ids.link(req);
971
- const cookies = link && "ended" in link ? [live.invites.forget()] : [];
972
- const ro = this.access && !this.ids.header ? live.readOnly.ofCookie(req.headers.cookie) : null;
973
- if (ro && "ended" in ro)
974
- cookies.push(live.readOnly.forget());
975
- if (this.access) {
976
- const a = link && "ok" in link && !path.startsWith(KEY_PATH) ? "in" : this.access.admit(req, path);
977
- if (a === "out") {
978
- // nothing lets them in to write: their read-only link does, or --public, to read
979
- const reader = ro && "ok" in ro ? ro.ok.id : this.publicRead && !this.ids.header ? "public" : null;
980
- // a page whose link was revoked, which nothing else lets in, is told so (CollabSpec
981
- // decisions 9 and 11): its requests are answered 410 with who revoked it and when, and the
982
- // page, reloaded, says the link no longer opens the site (decision 7: to a browser, the
983
- // page of a link that does not, which names nobody); the cookie is forgotten there, once
984
- // it has been said
985
- const revoked = reader === null && this.ids.kind(req) !== "agent" ? (link && "ended" in link ? revokedWords(link.record, "personal") : ro && "ended" in ro ? revokedWords(ro.link, "read-only") : null) : null;
986
- if (revoked) {
987
- if (asksForPage(req, path)) {
988
- res.setHeader("set-cookie", cookies);
989
- return sendAccessPage(res, "link");
990
- }
991
- if (path === "/" || path === "/index.html") {
992
- res.setHeader("set-cookie", cookies);
993
- return sendText(req, res, revoked + "\n", "text/plain; charset=utf-8", 410);
994
- }
995
- return sendJson(res, { error: revoked, revoked: true }, 410);
996
- }
997
- // nothing lets them in: a browser asking for a page is told the site is private, or that
998
- // its link (`/k/…`, a key replaced) does not open it (CollabSpec decision 7, the owner's
999
- // decision of 2026-10-18); anything else is answered as if there were nothing here
1000
- if (reader === null || this.ids.kind(req) === "agent") {
1001
- if (cookies.length)
1002
- res.setHeader("set-cookie", cookies);
1003
- if (asksForPage(req, path))
1004
- return sendAccessPage(res, path.startsWith(KEY_PATH) ? "link" : "private");
1005
- return sendJson(res, { error: "not found" }, 404);
1006
- }
1007
- // a link of the key's that is not the key, opened where the address, or a read-only link,
1008
- // lets them read: the page of a link that does not open the site, which says whether the
1009
- // address alone does (--public)
1010
- if (path.startsWith(KEY_PATH) && asksForPage(req, path)) {
1011
- if (cookies.length)
1012
- res.setHeader("set-cookie", cookies);
1013
- return sendAccessPage(res, "link", this.publicRead);
1014
- }
1015
- this.readOnlyOf.set(req, reader);
1016
- // the page renews a read-only link's cookie, as a personal link's
1017
- if (reader !== "public" && (path === "/" || path === "/index.html"))
1018
- cookies.push(live.readOnly.cookie(reader));
1019
- // what a read-only reader may ask; the rest is refused, whatever the page sends
1020
- if (!readOnlyAllows(req.method ?? "GET", path)) {
1021
- if (cookies.length)
1022
- res.setHeader("set-cookie", cookies);
1023
- return sendJson(res, { error: "This page is read-only: it changes nothing that is shared.", readOnly: true }, 403);
1024
- }
1025
- }
1026
- else if (a !== "in") {
1027
- // the link: the browser keeps the cookie, and the key leaves the address (a fragment
1028
- // after the key, a place in the page, comes along to "/")
1029
- res.writeHead(303, { location: "/", "set-cookie": [a.enter, ...cookies], "cache-control": "no-store", "referrer-policy": "no-referrer" });
1030
- return void res.end();
1031
- }
1032
- else {
1033
- // let in by the cookie every server used to share: the browser is given this one's own
1034
- const renew = this.access.renewal(req);
1035
- if (renew)
1036
- cookies.push(renew);
1037
- }
1038
- }
1039
- // the page renews a personal link's cookie: its holder stays in as long as they come back
1040
- if (link && "ok" in link && (path === "/" || path === "/index.html"))
1041
- cookies.push(live.invites.cookie(link.ok));
1042
- if (cookies.length)
1043
- res.setHeader("set-cookie", cookies);
1044
- if (path === "/" || path === "/index.html")
1045
- return sendFile(req, res, join(WEB, "index.html"));
1046
- if (path === "/style.css")
1047
- return sendFile(req, res, join(WEB, "style.css"));
1048
- // the fonts an artwork is drawn in (ExportSpec decision 19)
1049
- if (FONT_PATH.test(path))
1050
- return sendFile(req, res, join(WEBFONTS, path.slice("/fonts/".length)));
1051
- // the tips' clips and their key frames (GuideSpec decision 6), and which there are
1052
- if (path === "/tips/index.json")
1053
- return sendJson(res, { clips: tipClips() });
1054
- // the tour film, fetched by this server on its first play and kept checked in the cache
1055
- // (server/film.ts, UpdateSpec decision 14): else 503 while it comes, or 404, and the page shows
1056
- // its stills and captions; and its captions as WebVTT, for assistive technology
1057
- if (path === "/tips/tour.mp4" && !refused.has(res))
1058
- return void serveFilm(req, res, sendMedia);
1059
- if (path === "/tips/tour.en.vtt") {
1060
- const vtt = tourVtt(tourData());
1061
- if (vtt === null)
1062
- return sendJson(res, { error: "no captions" }, 404);
1063
- res.writeHead(200, { "content-type": "text/vtt; charset=utf-8", "cache-control": "no-cache" });
1064
- return void res.end(vtt);
1065
- }
1066
- if (TIP_PATH.test(path) && !refused.has(res))
1067
- return sendMedia(req, res, join(TIPS_DIR, path.slice("/tips/".length)));
1068
- // the page, and its workers: the one that lays out the Time Machine's past graphs
1069
- // (web/src/layoutworker.ts), the one that chooses the overview's edges (web/src/edgeworker.ts),
1070
- // and pdf.js's, which reads the library's PDFs for the reference window (AttachmentSpec decision 11)
1071
- if (/^\/(app|layout|edges|pdfworker)\.js(\.map)?$/.test(path))
1072
- return sendFile(req, res, join(bundleDir(), path.slice(1)));
1073
- if (path.startsWith("/pdfjs/"))
1074
- return pdfjsAsset(res, path);
1075
- // with Lean's language server as it is (server/hover.ts): what is open, what crashed
1076
- // a read-only reader is told how the server is, not its log nor where its review is kept
1077
- if (path === "/api/status") {
1078
- const st = { ...live.status(), lean: this.hover.state() };
1079
- if (this.readOnlyOf.get(req) !== undefined) {
1080
- delete st.log;
1081
- st.review = { ...st.review, folder: undefined };
1082
- // a branch's build log is not a read-only reader's (DeploySpec decision 11)
1083
- if (st.deploy)
1084
- st.deploy = slimDeploy(st.deploy);
1085
- }
1086
- return sendJson(res, st);
1087
- }
1088
- // VisualProof's own version, and what of its releases those let in fully are told (UpdateSpec
1089
- // decision 11): a read-only reader and an agent are told the version alone
1090
- if (path === "/api/updates")
1091
- return sendJson(res, this.updates?.status(this.toldAll(req)) ?? { running: packageVersion() });
1092
- // the link that lets someone in, for a page that shares where it is (web/src/share.ts); a
1093
- // request gets here only once it is in
1094
- // a read-only reader shares the link they came by, or the address alone (--public)
1095
- const reader = this.readOnlyOf.get(req);
1096
- if (path === "/api/share") {
1097
- if (reader !== undefined)
1098
- return sendJson(res, { path: reader === "public" ? "/" : (live.readOnly.get(reader)?.path ?? null), readOnly: true });
1099
- return sendJson(res, { path: this.access?.link ?? null, readOnlyLinks: !!this.access && !this.ids.header, public: this.publicRead });
1100
- }
1101
- if (path === "/api/share/readonly" || path.startsWith("/api/share/readonly/"))
1102
- return this.shareReadOnly(req, res, url);
1103
- if (path.startsWith("/api/share/agents"))
1104
- return this.shareAgents(req, res, url);
1105
- if (path === "/api/share/people" || path.startsWith("/api/share/people/"))
1106
- return this.sharePeople(req, res, url);
1107
- if (path === "/api/chat")
1108
- return this.chat(req, res, url);
1109
- if (path === "/api/chat/new")
1110
- return this.chatNew(req, res);
1111
- if (path === "/api/ask" || path === "/api/ask/answer")
1112
- return this.ask(req, res, url);
1113
- if (path === "/api/agent" || path.startsWith("/api/agent/"))
1114
- return this.agent(req, res, url);
1115
- // the views, each a shared board (ViewSpec.md)
1116
- if (path === "/api/views" || path.startsWith("/api/views/"))
1117
- return this.views(req, res, url);
1118
- // the snapshots of the graph, one per build (HistorySpec.md): the Time Machine reads them; the
1119
- // moves, the lost-and-found and its archive
1120
- if (path === "/api/history" || path.startsWith("/api/history/")) {
1121
- let body = null;
1122
- if (req.method === "POST") {
1123
- // a name's every entry archived at once is a few hundred keys at most
1124
- const r = await this.json(req, 1 << 20);
1125
- if (r.error !== undefined)
1126
- return sendJson(res, { error: `The body is ${r.error}.` }, 400);
1127
- body = r.body;
1128
- }
1129
- // a move, an archiving or a putting back is recorded as the review is: under the reader's
1130
- // name — a private reader's too (CollabSpec decision 8) — with the personal link of someone
1131
- // invited by one, whose moves go to their link's log (decision 9); by an agent at level full
1132
- const person = this.ids.person(req)?.id;
1133
- const a = await historyAnswer(live, { method: req.method ?? "GET", path, query: url.searchParams, body, caller: { name: this.ids.who(req), kind: this.ids.kind(req), ...(person ? { person } : {}) } }, (q) => q.caller.kind === "agent" ? refusal(this.agents.level, "full") : null);
1134
- // a snapshot's graph in parts, as the Time Machine takes it: compressed once, and tagged
1135
- if (a.gz)
1136
- return sendGz(req, res, a.gz.body, a.gz.type);
1137
- return sendJson(res, a.body, a.status, a.headers);
1138
- }
1139
- // the library of papers and images, and the links into them (AttachmentSpec.md,
1140
- // server/libraryroute.ts)
1141
- if (path === "/api/library" || path.startsWith("/api/library/")) {
1142
- // a read-only reader (CollabSpec decision 11) is drawn what the notes show of a PDF, kept in
1143
- // the cache as it is drawn, and no other page or region of one: each would be drawn by
1144
- // Poppler and kept anew, whoever comes asking
1145
- if (reader !== undefined && (path === "/api/library/page" || path === "/api/library/clip")) {
1146
- const q = url.searchParams;
1147
- const region = path === "/api/library/clip" ? (q.get("region") ?? "").split(",").map(Number) : null;
1148
- if (!live.views.shows(q.get("sha") ?? "", Number(q.get("page")), region))
1149
- return sendJson(res, { error: "A read-only page is drawn what the notes show of the library: open the file itself.", readOnly: true }, 403);
1150
- }
1151
- return libraryRoute({ ids: this.ids, level: this.agents.level, api: this.library() }, req, res, url);
1152
- }
1153
- // an agent may use the page's own endpoints too: the same rules hold there (AgentSpec)
1154
- const agent = this.ids.kind(req) === "agent";
1155
- // the review (ReviewSpec.md): the whole of it, as a page takes it on, with the lines of its
1156
- // logs that cannot be read; tagged with its revision, compressed once a revision
1157
- if (path === "/api/review" && req.method === "GET")
1158
- return sendReview(req, res, live.review);
1159
- if (path === "/api/review" && req.method === "POST") {
1160
- // an opinion, a target, a trusted prefix or a key declaration is recorded under the
1161
- // reader's name (CollabSpec decision 3), not one in the body; what it is about is
1162
- // bound by the server (server/reviewapi.ts)
1163
- const me = this.ids.who(req);
1164
- if (!me)
1165
- return sendJson(res, this.nameless(req, "what you record in the review is recorded under your name"), 401);
1166
- const person = this.ids.person(req)?.id ?? null;
1167
- return this.json(req, 1 << 20).then(({ body, error }) => {
1168
- if (error)
1169
- return sendJson(res, { error: `The body is ${error}.` }, 400);
1170
- // an agent records here what its level allows, as through its own API (AgentSpec decision
1171
- // 9): an opinion as advice, the rest at full; in its own log, marked as an agent's
1172
- const no = agent ? refusal(this.agents.level, needOf(body)) : null;
1173
- if (no)
1174
- return sendJson(res, no.body, no.status);
1175
- // someone invited by a personal link writes to the log of their link (shared/review.ts)
1176
- const a = this.agents.reviews.post(body, { name: me, agent, person });
1177
- sendJson(res, a.body, a.status);
1178
- });
1179
- }
1180
- if (path === "/api/export" || path.startsWith("/api/export/"))
1181
- return this.export(req, res, url, agent, reader !== undefined);
1182
- // who the reader is (CollabSpec decisions 3 and 9): the name their page gives, the proxy's, or
1183
- // their personal link's — with the link, and whether the page's own name is a link holder's
1184
- // and not theirs; a link revoked says by whom
1185
- if (path === "/api/identity" && req.method === "GET") {
1186
- const person = this.ids.person(req);
1187
- const holder = this.ids.taken(req);
1188
- const ended = link && "ended" in link ? link.record : null;
1189
- if (reader !== undefined)
1190
- return sendJson(res, { mode: this.ids.mode, name: null, readOnly: { by: reader === "public" ? "public" : "link" } });
1191
- return sendJson(res, {
1192
- mode: this.ids.mode,
1193
- name: this.ids.who(req),
1194
- ...(person ? { person: Invites.info(person) } : {}),
1195
- ...(holder ? { taken: taken(holder) } : {}),
1196
- ...(ended ? { revoked: { by: ended.revokedBy, at: ended.revoked, name: ended.name } } : {}),
1197
- });
1198
- }
1199
- if (path === "/api/identity" && req.method === "POST")
1200
- return this.identity(req, res);
1201
- // where a reader is: the others see it (CollabSpec decision 4); of a private reader, only that
1202
- // they are here (decision 8)
1203
- if (path === "/api/presence" && req.method === "POST") {
1204
- const r = await this.json(req, 16384);
1205
- if (r.error !== undefined)
1206
- return sendJson(res, { error: r.error }, 400);
1207
- const b = (r.body ?? {});
1208
- // an agent is one entry by its name (server/presence.ts), never private; a page speaks for
1209
- // its own event stream only, by the secret the stream was given (`hello`)
1210
- const name = this.ids.who(req);
1211
- const priv = !agent && b.private === true;
1212
- // agents have no artwork (ExportSpec decision 19): the page draws it
1213
- if (agent && name)
1214
- live.presence.agentBeat(name, withoutArtwork(cleanView(b.view)));
1215
- else if (!live.beat(b.token, priv ? null : name, priv ? null : cleanView(b.view), !priv && b.idle === true, priv, !!this.ids.person(req)))
1216
- return sendJson(res, { error: "This heartbeat is not from an open event stream of this page's: it is sent with the token the stream says hello with.", stream: false }, 403);
1217
- return sendJson(res, { ok: true });
1218
- }
1219
- if (path === "/api/events") {
1220
- const session = url.searchParams.get("session");
1221
- return live.subscribe(res, validSession(session) ? session : null, this.ids.person(req)?.id ?? null, reader ?? null, this.toldAll(req));
1222
- }
1223
- // what happened (CollabSpec decision 5): what the server stored; the review's own history the
1224
- // page reads from the review
1225
- if (path === "/api/activity") {
1226
- const events = live.timeline.events.slice(-2000);
1227
- return sendJson(res, { events: this.toldAll(req) ? events : events.map(withoutReasons) });
1228
- }
1229
- // a layout batch an agent made, undone (AgentSpec decision 4): from a page's Activity, by anyone;
1230
- // by a private reader, without their name (CollabSpec decision 8)
1231
- if (path === "/api/layout/undo" && req.method === "POST") {
1232
- const priv = this.ids.privateOf(req) !== null;
1233
- const me = layoutAuthor({ name: this.ids.who(req), private: priv });
1234
- if (!me && !priv)
1235
- return sendJson(res, { error: "Say who you are first.", who: true }, 401);
1236
- const no = agent ? refusal(this.agents.level, "full") : null;
1237
- if (no)
1238
- return sendJson(res, no.body, no.status);
1239
- const r = await this.json(req, 4096);
1240
- if (r.error !== undefined)
1241
- return sendJson(res, { error: r.error }, 400);
1242
- const a = this.agents.undo(me, agent, r.body?.id);
1243
- return sendJson(res, a.body, a.status);
1244
- }
1245
- // the project's git source and commit as git says them now, not as the build was read (an
1246
- // artwork's foot, ExportSpec decision 19; the owner's decision of 2026-10-15)
1247
- if (path === "/api/git") {
1248
- // following a branch, the commit of the build on show, on that branch: what is checked out
1249
- // meanwhile is the build going on (DeploySpec decision 12)
1250
- const shown = live.shownCommit();
1251
- if (shown !== undefined)
1252
- return sendJson(res, { git: shown && { source: live.deploy.status(false).source, commit: shown.hash, branch: shown.branch } });
1253
- if (!this.gitRead || Date.now() - this.gitRead.at >= this.gitFreshMs)
1254
- this.gitRead = { git: gitSource(live.project.root), at: Date.now() };
1255
- return sendJson(res, { git: this.gitRead.git });
1256
- }
1257
- if (path === "/api/meta" || path === "/api/edges") {
1258
- const g = live.graph;
1259
- if (!g)
1260
- return sendJson(res, { error: "not ready" }, 503);
1261
- // a page asks for the version it was told about; an older one is gone
1262
- const want = url.searchParams.get("v");
1263
- // of this server's: one restarted since counts its versions again (UpdateSpec decision 8)
1264
- const of = url.searchParams.get("i");
1265
- if ((want && Number(want) !== g.version) || (of && of !== live.instance))
1266
- return sendJson(res, { error: "superseded", version: g.version, instance: live.instance }, 409);
1267
- // a page asks for the edges packed (shared/edgecodec.ts; `pack=2` with the grammar site, a
1268
- // page from before it `pack=1`, which takes grammar for a proof); an agent gets them as they
1269
- // are
1270
- const pack = url.searchParams.get("pack");
1271
- return path === "/api/meta"
1272
- ? sendGz(req, res, g.prep.metaGz, "application/json")
1273
- : sendGz(req, res, pack === "1" || pack === "2" ? packedGz(g.prep.edgesGz, pack === "1" ? 1 : 2) : g.prep.edgesGz, "application/octet-stream");
1274
- }
1275
- if (path === "/api/hover" || path === "/api/hover/open" || path === "/api/hover/names" || path === "/api/hover/describe" || path === "/api/hover/print") {
1276
- // what Lean says is at a position of a project file (server/hover.ts). Only the graph's
1277
- // modules (meta.modules) reach Lean: the module names the file the graph was read from, so
1278
- // no path from the client reaches the disk, and no other file in the project's folder — an
1279
- // old copy, a CI script — is ever elaborated or imported
1280
- if (!live.graph)
1281
- return sendJson(res, { error: "not ready" }, 503);
1282
- const mod = url.searchParams.get("module") ?? "";
1283
- const rel = live.moduleFile(mod);
1284
- if (rel === undefined)
1285
- return sendJson(res, { error: `${mod.slice(0, 300)} is not a module of the graph` }, 404);
1286
- // a read-only reader (CollabSpec decision 11) is answered what Lean already said of this
1287
- // build, else asks it within bounds, per address and in all
1288
- const keyOf = reader !== undefined && req.method === "GET" ? `${live.graph.fingerprint}\0${path}\0${url.search}` : null;
1289
- const kept = keyOf ? this.bounds.answer(keyOf) : undefined;
1290
- if (kept !== undefined)
1291
- return sendJson(res, kept);
1292
- if (reader !== undefined) {
1293
- const wait = this.bounds.leanWait(req.socket.remoteAddress ?? "");
1294
- if (wait)
1295
- return sendJson(res, { error: "Lean is asked too often from here: try again in a moment.", retryAfter: wait }, 429, { "retry-after": String(wait) });
1296
- }
1297
- const reply = (body) => {
1298
- if (keyOf && finalAnswer(body))
1299
- this.bounds.keep(keyOf, body);
1300
- return sendJson(res, body);
1301
- };
1302
- if (path === "/api/hover/describe") {
1303
- // a declaration by name, where the module on show is imported: what a name in a hover card
1304
- // shows. The name is checked to be a name before it is written into Lean source.
1305
- const name = url.searchParams.get("name") ?? "";
1306
- if (!isDeclName(name))
1307
- return sendJson(res, { error: "not a name" }, 400);
1308
- return reply(await this.hover.describe(mod, name, 6000));
1309
- }
1310
- if (path === "/api/hover/print") {
1311
- // what Lean's #print says of a declaration it generated from a command, which has no text
1312
- // of its own (the source window, under the command that made it, when asked)
1313
- const name = url.searchParams.get("name") ?? "";
1314
- if (!isDeclName(name))
1315
- return sendJson(res, { error: "not a name" }, 400);
1316
- return reply(await this.hover.print(mod, name, false, 6000));
1317
- }
1318
- if (rel === null)
1319
- return sendJson(res, { error: `no source for ${mod}` }, 404);
1320
- const text = readFileSync(join(live.project.root, rel), "utf8");
1321
- const hash = lakeTextHash(text);
1322
- if (path === "/api/hover/open") {
1323
- try {
1324
- await this.hover.open(rel, text, hash);
1325
- return sendJson(res, { ok: true });
1326
- }
1327
- catch (e) {
1328
- return sendJson(res, { error: this.hover.failure ?? (e instanceof Error ? e.message : String(e)) });
1329
- }
1330
- }
1331
- // the page shows another text than there is now: it reads the source again first
1332
- const want = url.searchParams.get("hash");
1333
- if (want && want !== hash)
1334
- return sendJson(res, { stale: true });
1335
- if (path === "/api/hover/names") {
1336
- // the positions of the names in a declaration's source, as JSON [[line, character], …]
1337
- const r = await this.json(req, 1 << 20);
1338
- if (r.error !== undefined)
1339
- return sendJson(res, { error: r.error }, 400);
1340
- const ps = r.body;
1341
- const ok = Array.isArray(ps) && ps.length <= 5000 && ps.every((p) => Array.isArray(p) && p.length === 2 && p.every((x) => Number.isInteger(x) && x >= 0));
1342
- if (!ok)
1343
- return sendJson(res, { error: "positions" }, 400);
1344
- return sendJson(res, await this.hover.names(rel, text, hash, ps, 8000));
1345
- }
1346
- const line = Number(url.searchParams.get("line")), character = Number(url.searchParams.get("character"));
1347
- if (!Number.isInteger(line) || !Number.isInteger(character) || line < 0 || character < 0)
1348
- return sendJson(res, { error: "position" }, 400);
1349
- return reply(await this.hover.hover(rel, text, hash, line, character, 6000));
1350
- }
1351
- if (path === "/api/source") {
1352
- // only the graph's modules, from the file the graph was read from: no path from the client
1353
- // ever reaches the disk, and no file outside the graph is served
1354
- if (!live.graph)
1355
- return sendJson(res, { error: "not ready" }, 503);
1356
- const mod = url.searchParams.get("module") ?? "";
1357
- const rel = live.moduleFile(mod);
1358
- if (!rel)
1359
- return sendJson(res, { error: `no source for ${mod.slice(0, 300)}: it is not a module of the graph` }, 404);
1360
- const text = readFileSync(join(live.project.root, rel), "utf8");
1361
- const hash = lakeTextHash(text);
1362
- // the usage pass's contexts of the module (shared/context.ts), when this is the text it
1363
- // elaborated
1364
- const contexts = live.contextsOf(mod);
1365
- // the hash says whether this is the text the graph was read from (meta.modules[].compiled)
1366
- return sendJson(res, { module: mod, file: rel, text, hash, ...(contexts && contexts.hash === hash ? { contexts } : {}) });
1367
- }
1368
- sendJson(res, { error: "not found" }, 404);
1369
- }
1370
- }
1371
- }
1372
- /** What a revoked link's holder is told, opening it or on a page it had opened. */
1373
- function revokedWords(r, kind) {
1374
- return `This ${kind} link was revoked by ${r.revokedBy} on ${(r.revoked ?? "").slice(0, 10)}. Ask whoever ${kind === "personal" ? "invited you" : "gave it to you"} for a new one.`;
1375
- }
1376
- /** an artwork's font file (assets/webfonts/) */
1377
- const FONT_PATH = /^\/fonts\/(source-sans-3|source-serif-4|jost)-[a-z-]+\.woff2$/;
1378
- const TYPES = {
1379
- ".woff2": "font/woff2",
1380
- ".html": "text/html; charset=utf-8",
1381
- ".css": "text/css; charset=utf-8",
1382
- ".js": "text/javascript; charset=utf-8",
1383
- ".map": "application/json",
1384
- };
1385
- // Pages are often far from the server (CollabSpec, "Far pages"): every byte counts, and what a
1386
- // browser has it should not fetch again. The page's files and the graph are sent compressed, with
1387
- // a tag naming their content; a browser that has that content already is told so (304) and sends
1388
- // nothing more. Everything else in JSON is compressed when it is large.
1389
- /** The tag naming a content. */
1390
- function tagOf(body) {
1391
- return `"${createHash("sha256").update(body).digest("base64url").slice(0, 27)}"`;
1392
- }
1393
- /** Whether the request already has the content `etag` names. */
1394
- function fresh(req, etag) {
1395
- const have = req.headers["if-none-match"];
1396
- return !!have && have.split(",").some((t) => t.trim().replace(/^W\//, "") === etag);
1397
- }
1398
- function acceptsGzip(req) {
1399
- return /\bgzip\b/.test(String(req?.headers["accept-encoding"] ?? ""));
1400
- }
1401
- /** the page's files as last read: compressed and tagged once per change on disk */
1402
- const files = new Map();
1403
- function sendFile(req, res, file) {
1404
- if (refused.has(res))
1405
- return;
1406
- if (!existsSync(file))
1407
- return sendJson(res, { error: "not found" }, 404);
1408
- const st = statSync(file);
1409
- let f = files.get(file);
1410
- if (!f || f.mtime !== st.mtimeMs || f.size !== st.size) {
1411
- const body = readFileSync(file);
1412
- f = { mtime: st.mtimeMs, size: st.size, body, gz: null, etag: tagOf(body) };
1413
- files.set(file, f);
1414
- }
1415
- const head = { "content-type": TYPES[extname(file)] ?? "application/octet-stream", "cache-control": "no-cache", etag: f.etag, vary: "accept-encoding" };
1416
- if (fresh(req, f.etag)) {
1417
- res.writeHead(304, head);
1418
- return void res.end();
1419
- }
1420
- if (!acceptsGzip(req)) {
1421
- res.writeHead(200, head);
1422
- return void res.end(f.body);
1423
- }
1424
- f.gz ??= gzipSync(f.body, { level: 9 });
1425
- res.writeHead(200, { ...head, "content-encoding": "gzip" });
1426
- res.end(f.gz);
1427
- }
1428
- /** the most an agent's request body may be (docs/agent-api/requests.md: 1 MB) */
1429
- const AGENT_BODY = 1 << 20;
1430
- /** how long the rest of a body refused as too large is read before it is answered all the same,
1431
- * and the connection cut: long enough for a client to finish sending what it began, not for an
1432
- * endless body */
1433
- const TOO_LARGE_GRACE_MS = 2000;
1434
- class TooLarge extends Error {
1435
- }
1436
- /** A request's body, refused (TooLarge) once it passes `limit` bytes: what comes after is not kept. */
1437
- function readBody(req, limit) {
1438
- return new Promise((ok, fail) => {
1439
- const parts = [];
1440
- let size = 0;
1441
- if (Number(req.headers["content-length"]) > limit)
1442
- return fail(new TooLarge());
1443
- req.on("data", (b) => {
1444
- if (size > limit)
1445
- return;
1446
- size += b.length;
1447
- if (size > limit) {
1448
- parts.length = 0;
1449
- fail(new TooLarge());
1450
- }
1451
- else
1452
- parts.push(b);
1453
- });
1454
- req.on("end", () => ok(Buffer.concat(parts).toString("utf8")));
1455
- req.on("error", fail);
1456
- });
1457
- }
1458
- /** Responses refused as too large and not answered yet (tooLarge): what the handler that asked for
1459
- * the body answers meanwhile is not sent. */
1460
- const refused = new WeakSet();
1461
- /** Answer 413 to a body too large and close the connection. The rest of the body is read and thrown
1462
- * away first, and the answer goes once it has all come: a connection closed while the client is
1463
- * still sending is reset on some systems (macOS), and the client never reads the answer. A client
1464
- * still sending after a short grace is answered all the same, and cut off. */
1465
- function tooLarge(req, res, body) {
1466
- refused.add(res);
1467
- let done = false;
1468
- const answer = () => {
1469
- if (done)
1470
- return;
1471
- done = true;
1472
- refused.delete(res);
1473
- sendJson(res, body, 413, { connection: "close" });
1474
- };
1475
- req.on("data", () => { });
1476
- req.on("end", answer);
1477
- req.resume();
1478
- if (req.readableEnded)
1479
- answer();
1480
- setTimeout(() => {
1481
- answer();
1482
- setTimeout(() => req.socket.destroy(), 500).unref();
1483
- }, TOO_LARGE_GRACE_MS).unref();
1484
- }
1485
- /** Send a JSON answer, once: a handler that answers after something else already did (a body too
1486
- * large, answered as it was read) is not heard. */
1487
- export function sendJson(res, body, code = 200, headers = {}) {
1488
- if (res.headersSent || res.writableEnded || refused.has(res))
1489
- return;
1490
- sendJsonText(res, JSON.stringify(body), code, headers);
1491
- }
1492
- /** The same, of an answer written as JSON already. */
1493
- function sendJsonText(res, text, code = 200, headers = {}) {
1494
- if (res.headersSent || res.writableEnded || refused.has(res))
1495
- return;
1496
- // a small answer is not worth compressing; a status with its build log, a source file, are; a
1497
- // large one is compressed off the server's thread, which meanwhile answers others
1498
- if (text.length > JSON_GZIP_FROM && acceptsGzip(res.req)) {
1499
- res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store", "content-encoding": "gzip", vary: "accept-encoding", ...headers });
1500
- if (text.length < JSON_GZIP_AWAY_FROM)
1501
- return void res.end(gzipSync(text));
1502
- return void gzip(text, (e, gz) => (e ? res.destroy(e) : res.end(gz)));
1503
- }
1504
- res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store", ...headers });
1505
- res.end(text);
1506
- }
1507
- /** the whole review compressed, under the tag of the revision it is of, per review */
1508
- const reviewGz = new WeakMap();
1509
- /** The whole review (GET /api/review), tagged with its run and its revision (server/review.ts): a
1510
- * page that has it is answered 304, which a reload is, and one whose review fell behind is sent it
1511
- * compressed — once a revision, off the server's thread when it is large, the same bytes for every
1512
- * page (a review of 5,000 opinions on Sphere-Packing-Lean: 8.5 MB of JSON, 1.1 MB sent). */
1513
- function sendReview(req, res, review) {
1514
- if (res.headersSent || res.writableEnded || refused.has(res))
1515
- return;
1516
- const tag = review.tag();
1517
- const head = { "content-type": "application/json", "cache-control": "private, no-cache", etag: tag, vary: "accept-encoding" };
1518
- if (fresh(req, tag)) {
1519
- res.writeHead(304, head);
1520
- return void res.end();
1521
- }
1522
- const text = review.wholeText();
1523
- if (text.length <= JSON_GZIP_FROM || !acceptsGzip(req)) {
1524
- res.writeHead(200, head);
1525
- return void res.end(text);
1526
- }
1527
- let c = reviewGz.get(review);
1528
- if (c?.tag !== tag) {
1529
- const gz = text.length < JSON_GZIP_AWAY_FROM ? Promise.resolve(gzipSync(text)) : new Promise((ok, fail) => gzip(text, (e, b) => (e ? fail(e) : ok(b))));
1530
- reviewGz.set(review, (c = { tag, gz }));
1531
- // a compression that failed is tried again by the next page that asks
1532
- gz.catch(() => reviewGz.get(review)?.gz === gz && reviewGz.delete(review));
1533
- }
1534
- c.gz.then((gz) => {
1535
- if (res.headersSent || res.destroyed)
1536
- return;
1537
- res.writeHead(200, { ...head, "content-encoding": "gzip" });
1538
- res.end(gz);
1539
- }, (e) => res.destroy(e));
1540
- }
1541
- /** Send a text that is not JSON (the agents' documentation, the MCP server's file), compressed
1542
- * where the client takes it. */
1543
- function sendText(req, res, text, type, code = 200) {
1544
- if (res.headersSent || res.writableEnded || refused.has(res))
1545
- return;
1546
- const head = { "content-type": type, "cache-control": "no-store", vary: "accept-encoding" };
1547
- if (text.length > JSON_GZIP_FROM && acceptsGzip(req)) {
1548
- res.writeHead(code, { ...head, "content-encoding": "gzip" });
1549
- return void res.end(gzipSync(text));
1550
- }
1551
- res.writeHead(code, head);
1552
- res.end(text);
1553
- }
1554
- /** Send a file to download (a typeset document): as it is, never cached, named for the disk. */
1555
- function sendDownload(res, f) {
1556
- if (res.headersSent || res.writableEnded || refused.has(res))
1557
- return;
1558
- res.writeHead(200, { "content-type": f.type, "content-length": String(f.body.length), "content-disposition": `attachment; filename="${f.name.replace(/[^A-Za-z0-9._-]/g, "_")}"`, "cache-control": "no-store" });
1559
- res.end(f.body);
1560
- }
1561
- /** The Host a request was sent to, when it looks like one. */
1562
- function hostOf(req) {
1563
- return /^[A-Za-z0-9.:[\]-]{1,300}$/.test(req.headers.host ?? "") ? req.headers.host : "127.0.0.1";
1564
- }
1565
- /** The server's address as the request's browser reached it: its Origin where it names the host
1566
- * the request was sent to (a page's POST carries it, with the scheme), else http:// and the Host. */
1567
- export function reachedAt(req) {
1568
- const host = hostOf(req);
1569
- try {
1570
- const o = new URL(String(req.headers.origin ?? ""));
1571
- if (o.host === host && (o.protocol === "http:" || o.protocol === "https:"))
1572
- return o.origin;
1573
- }
1574
- catch {
1575
- // no Origin, or not an address: the Host
1576
- }
1577
- return `http://${host}`;
1578
- }
1579
- /** characters from which a JSON answer is sent compressed */
1580
- const JSON_GZIP_FROM = 2048;
1581
- /** characters from which a JSON answer is compressed off the server's thread: a snapshot's whole
1582
- * graph on NavierStokesAndEuler (GET /api/agent/history/graph, 105 MB of JSON) was 2 to 3 s of
1583
- * compressing, every page and agent waiting meanwhile */
1584
- export const JSON_GZIP_AWAY_FROM = 1 << 20;
1585
- /** the graph's parts as sent, each tagged once (a graph's buffers live as long as it does) */
1586
- const gzTags = new WeakMap();
1587
- /** A part of the graph, gzipped already: tagged, so that a page that has it gets 304; a client that
1588
- * does not take gzip (an agent's) is sent it as it is, made so off the server's thread. */
1589
- function sendGz(req, res, gz, type) {
1590
- if (refused.has(res))
1591
- return;
1592
- let etag = gzTags.get(gz);
1593
- if (!etag)
1594
- gzTags.set(gz, (etag = tagOf(gz)));
1595
- const head = { "content-type": type, "cache-control": "private, no-cache", etag, vary: "accept-encoding" };
1596
- if (fresh(req, etag)) {
1597
- res.writeHead(304, head);
1598
- return void res.end();
1599
- }
1600
- if (!acceptsGzip(req))
1601
- return void gunzip(gz, (e, plain) => {
1602
- if (e)
1603
- return res.destroy(e);
1604
- res.writeHead(200, head);
1605
- res.end(plain);
1606
- });
1607
- res.writeHead(200, { ...head, "content-encoding": "gzip" });
1608
- res.end(gz);
1609
- }
1610
- /** the edges packed for pages (shared/edgecodec.ts), once per graph and format */
1611
- const packedEdges = new WeakMap();
1612
- function packedGz(edgesGz, format) {
1613
- let byFormat = packedEdges.get(edgesGz);
1614
- if (!byFormat)
1615
- packedEdges.set(edgesGz, (byFormat = new Map()));
1616
- let p = byFormat.get(format);
1617
- if (!p) {
1618
- const raw = gunzipSync(edgesGz);
1619
- const edges = new Int32Array(raw.buffer, raw.byteOffset, raw.byteLength / 4);
1620
- let n = 0;
1621
- for (let k = 0; k < edges.length; k += 3)
1622
- n = Math.max(n, edges[k] + 1, edges[k + 1] + 1);
1623
- p = gzipSync(packEdges(edges, n, format), { level: 9 });
1624
- byFormat.set(format, p);
1625
- }
1626
- return p;
1627
- }
29
+ import { filmStatus, useFilm } from "./film.js";
30
+ import { branchToFollow, DEFAULT_BUILD_HOURS, DEFAULT_POLL_MINUTES, DeployBusy, deployFolder, Deployment, deploySite, ensureClone, limitInWords, lockDeployment, recordedDefault, sharedMathlibCache } from "./deploy.js";
31
+ import { shortCommit } from "../shared/deploy.js";
32
+ import { parseArgs } from "./options.js";
33
+ import { App } from "./app.js";
1628
34
  /** What a stop signal does to a server: end it at once, until it can stop gracefully (serve). */
1629
35
  let stopNow = () => process.exit(0);
1630
36
  async function main() {
@@ -1755,6 +161,8 @@ async function main() {
1755
161
  project,
1756
162
  roots: o.roots,
1757
163
  everyMs: (o.poll ?? DEFAULT_POLL_MINUTES) * 60_000,
164
+ buildMs: (o.buildHours ?? DEFAULT_BUILD_HOURS) * 3600_000,
165
+ mathlibCache: o.mathlibCache ?? "shared",
1758
166
  head: deploy.head,
1759
167
  hooks: {
1760
168
  reading: () => live.reading,
@@ -1860,9 +268,19 @@ async function main() {
1860
268
  console.log(` version: ${version}; updates ${updatesInWords(o.updates, version, supervised)}`);
1861
269
  if (deployment) {
1862
270
  const d = deployment.status(true);
1863
- console.log(` following: ${d.branch} of ${d.source ?? deployment.remote.url}, asked every ${o.poll ?? DEFAULT_POLL_MINUTES} min`);
271
+ console.log(` following: ${d.branch} of ${d.source ?? deployment.remote.url}, asked every ${o.poll ?? DEFAULT_POLL_MINUTES} min; a build stopped past ${limitInWords(deployment.buildMs)}`);
1864
272
  console.log(` clone: ${deployment.folder.checkout}`);
1865
- console.log(` builds: ${d.built ? `the tree holds the build of ${shortCommit(d.built)}${deployment.holds() ? ", cut short: it is done again" : ""}` : `none yet: the first, of ${shortCommit(deploy.head)}, starts now, and the page says so until it is done`}; their logs in ${deployment.folder.logs}`);
273
+ // a failed build that wrote nothing is not built (DeploySpec decision 6): before any that did,
274
+ // none is, and the next is the next commit pushed
275
+ const next = deployment.toBuild();
276
+ const l = d.last;
277
+ const why = l ? (l.error ?? (l.exit === null ? "lake build was stopped" : l.exit !== undefined ? `lake build exited with ${l.exit}` : null)) : null;
278
+ const none = next
279
+ ? `none yet: the first, of ${shortCommit(next)}, starts now, and the page says so until it is done`
280
+ : `none yet: that of ${shortCommit(l?.commit ?? deploy.head)} failed${why ? ` (${why})` : ""}, and the next commit pushed is built`;
281
+ console.log(` builds: ${d.built ? `the tree holds the build of ${shortCommit(d.built)}${deployment.holds() ? ", cut short: it is done again" : ""}` : none}; their logs in ${deployment.folder.logs}`);
282
+ // where the project is on Mathlib, its cache: the user's, or the deployment's own (DeploySpec decision 2)
283
+ console.log(` Mathlib's cache: ${o.mathlibCache === "own" ? `${deployment.folder.mathlib}, the deployment's own` : `${sharedMathlibCache()}, the user's, shared by their builds`}`);
1866
284
  }
1867
285
  recordVersion(live, version, supervised);
1868
286
  process.send?.({ vp: "listening", version });