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