visualproof 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/README.md +2 -2
  2. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  3. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  4. package/dist/assets/tips/tour-agent.webp +0 -0
  5. package/dist/assets/tips/tour-arrange.webp +0 -0
  6. package/dist/assets/tips/tour-artwork.webp +0 -0
  7. package/dist/assets/tips/tour-checks.webp +0 -0
  8. package/dist/assets/tips/tour-keys.webp +0 -0
  9. package/dist/assets/tips/tour-library.webp +0 -0
  10. package/dist/assets/tips/tour-project.webp +0 -0
  11. package/dist/assets/tips/tour-review.webp +0 -0
  12. package/dist/assets/tips/tour-share.webp +0 -0
  13. package/dist/assets/tips/tour-source.webp +0 -0
  14. package/dist/assets/tips/tour-target.webp +0 -0
  15. package/dist/assets/tips/tour-view.webp +0 -0
  16. package/dist/assets/tips/tour.json +125 -115
  17. package/dist/assets/tips/tour.webp +0 -0
  18. package/dist/extractor/Extract.lean +13 -3
  19. package/dist/mcp/visualproof-mcp.mjs +20 -9
  20. package/dist/server/access.js +28 -0
  21. package/dist/server/agent.js +130 -2819
  22. package/dist/server/agentactivity.js +72 -0
  23. package/dist/server/agentadvice.js +115 -0
  24. package/dist/server/agentdocs.js +1 -1
  25. package/dist/server/agententry.js +180 -0
  26. package/dist/server/agentexport.js +469 -0
  27. package/dist/server/agentfollow.js +384 -0
  28. package/dist/server/agentgraph.js +128 -0
  29. package/dist/server/agentlean.js +144 -0
  30. package/dist/server/agentlibrary.js +1 -1
  31. package/dist/server/agentplaces.js +242 -0
  32. package/dist/server/agentread.js +569 -0
  33. package/dist/server/agenttalk.js +282 -0
  34. package/dist/server/agenttcb.js +378 -0
  35. package/dist/server/agentviews.js +2 -2
  36. package/dist/server/app.js +377 -0
  37. package/dist/server/appaccess.js +127 -0
  38. package/dist/server/appagent.js +110 -0
  39. package/dist/server/appgraph.js +176 -0
  40. package/dist/server/appshare.js +179 -0
  41. package/dist/server/appsite.js +120 -0
  42. package/dist/server/apptalk.js +178 -0
  43. package/dist/server/artcmd.js +1 -1
  44. package/dist/server/askfollow.js +1 -1
  45. package/dist/server/deploy.js +204 -53
  46. package/dist/server/events.js +1 -1
  47. package/dist/server/history.js +51 -3
  48. package/dist/server/historyapi.js +34 -2
  49. package/dist/server/hover.js +11 -7
  50. package/dist/server/identity.js +1 -1
  51. package/dist/server/invites.js +113 -20
  52. package/dist/server/libraryroute.js +3 -3
  53. package/dist/server/live.js +186 -30
  54. package/dist/server/main.js +31 -1613
  55. package/dist/server/mcptools.js +33 -20
  56. package/dist/server/options.js +350 -0
  57. package/dist/server/outside.js +311 -0
  58. package/dist/server/pastdoc.js +22 -3
  59. package/dist/server/presence.js +3 -3
  60. package/dist/server/project.js +28 -4
  61. package/dist/server/prompt.js +8 -3
  62. package/dist/server/readonlygate.js +4 -4
  63. package/dist/server/reviewapi.js +51 -17
  64. package/dist/server/send.js +259 -0
  65. package/dist/server/talk.js +238 -116
  66. package/dist/server/tokens.js +13 -5
  67. package/dist/server/view.js +3 -1
  68. package/dist/server/views.js +1 -1
  69. package/dist/shared/artrecipe.js +3 -3
  70. package/dist/shared/build.js +35 -1
  71. package/dist/shared/collab.js +9 -1
  72. package/dist/shared/comment.js +1 -1
  73. package/dist/shared/doc/build.js +30 -14
  74. package/dist/shared/doc/latex.js +7 -2
  75. package/dist/shared/doc/model.js +4 -2
  76. package/dist/shared/doc/sections.js +21 -4
  77. package/dist/shared/keys.js +66 -37
  78. package/dist/shared/lostfound.js +1 -0
  79. package/dist/shared/mentions.js +83 -0
  80. package/dist/shared/outside.js +16 -0
  81. package/dist/shared/pastgraph.js +11 -2
  82. package/dist/shared/query.js +13 -4
  83. package/dist/shared/review.js +91 -21
  84. package/dist/shared/reviewqueue.js +6 -1
  85. package/dist/shared/scope.js +1 -1
  86. package/dist/web/bundle/app.js +51289 -49853
  87. package/dist/web/index.html +45 -9
  88. package/dist/web/src/reviewqueue.js +52 -19
  89. package/dist/web/src/selection.js +1 -1
  90. package/dist/web/src/theme.js +1 -1
  91. package/dist/web/src/trust.js +271 -0
  92. package/dist/web/src/visitors.js +1 -1
  93. package/dist/web/style.css +181 -70
  94. package/docs/agent-api/README.md +13 -11
  95. package/docs/agent-api/advice.md +8 -2
  96. package/docs/agent-api/export.md +9 -6
  97. package/docs/agent-api/following.md +11 -12
  98. package/docs/agent-api/history.md +6 -3
  99. package/docs/agent-api/mcp.md +15 -15
  100. package/docs/agent-api/notes.md +1 -1
  101. package/docs/agent-api/reading.md +10 -4
  102. package/docs/agent-api/requests.md +12 -15
  103. package/docs/agent-api/talking.md +60 -55
  104. package/docs/agent-api/tcb.md +21 -21
  105. package/docs/agent-api/views.md +3 -4
  106. package/docs/agent-api/words.md +8 -8
  107. package/package.json +2 -1
@@ -0,0 +1,176 @@
1
+ // The project as pages read it (the routes of server/app.ts): the server's status, the graph on show
2
+ // in its parts, a module's source, what Lean says at a place of it or of a name (server/hover.ts),
3
+ // and the project's git as git says it now. Only the graph's modules are read, or reach Lean: no
4
+ // path a client sends reaches the disk.
5
+ import { gitSource } from "./history.js";
6
+ import { readFileSync } from "node:fs";
7
+ import { join } from "node:path";
8
+ import { isDeclName } from "./hover.js";
9
+ import { outsideSource } from "./outside.js";
10
+ import { lakeTextHash } from "./status.js";
11
+ import { finalAnswer } from "./readonlygate.js";
12
+ import { slimDeploy } from "../shared/deploy.js";
13
+ import { packedGz, sendGz, sendJson } from "./send.js";
14
+ /** with Lean's language server as it is (server/hover.ts): what is open, what crashed
15
+ * a read-only reader is told how the server is, not its log nor where its review is kept
16
+ * `?brief`: the build status without its files, which the page reads by GET /api/build */
17
+ export function status(app, req, res, url) {
18
+ const live = app.live;
19
+ const st = { ...live.status(url.searchParams.has("brief")), lean: app.hover.state() };
20
+ // the address people reach the server at (--public-url): links of it are this site's, and the
21
+ // page makes its own with it (CollabSpec, "Copied links")
22
+ if (app.publicUrl)
23
+ st.publicUrl = app.publicUrl;
24
+ if (app.readOnlyOf.get(req) !== undefined) {
25
+ delete st.log;
26
+ st.review = { ...st.review, folder: undefined };
27
+ // a branch's build log is not a read-only reader's (DeploySpec decision 11)
28
+ if (st.deploy)
29
+ st.deploy = slimDeploy(st.deploy);
30
+ }
31
+ return sendJson(res, st);
32
+ }
33
+ /** GET /api/meta and GET /api/edges: the graph on show, its declarations and its edges, as prepared. */
34
+ export function graphParts(app, req, res, url) {
35
+ const live = app.live;
36
+ const path = url.pathname;
37
+ const g = live.graph;
38
+ if (!g)
39
+ return sendJson(res, { error: "not ready" }, 503);
40
+ // a page asks for the version it was told about; an older one is gone
41
+ const want = url.searchParams.get("v");
42
+ // of this server's: one restarted since counts its versions again (UpdateSpec decision 8)
43
+ const of = url.searchParams.get("i");
44
+ if ((want && Number(want) !== g.version) || (of && of !== live.instance))
45
+ return sendJson(res, { error: "superseded", version: g.version, instance: live.instance }, 409);
46
+ // a page asks for the edges packed (shared/edgecodec.ts; `pack=2` with the grammar site, a
47
+ // page from before it `pack=1`, which takes grammar for a proof); an agent gets them as they
48
+ // are
49
+ const pack = url.searchParams.get("pack");
50
+ return path === "/api/meta"
51
+ ? sendGz(req, res, g.prep.metaGz, "application/json")
52
+ : sendGz(req, res, pack === "1" || pack === "2" ? packedGz(g.prep.edgesGz, pack === "1" ? 1 : 2) : g.prep.edgesGz, "application/octet-stream");
53
+ }
54
+ /** GET /api/source?module=: a module's text, as the source windows read it. */
55
+ export function source(app, res, url) {
56
+ const live = app.live;
57
+ // only the graph's modules, from the file the graph was read from: no path from the client
58
+ // ever reaches the disk, and no file outside the graph is served
59
+ if (!live.graph)
60
+ return sendJson(res, { error: "not ready" }, 503);
61
+ const mod = url.searchParams.get("module") ?? "";
62
+ const rel = live.moduleFile(mod);
63
+ if (!rel) {
64
+ // outside the project: a module an outside declaration of the graph is in, its file in its
65
+ // package or in Lean's core (server/outside.ts; the owner's decision of 2026-10-20)
66
+ const out = rel === undefined ? live.outsideFile(mod) : undefined;
67
+ const src = out ? outsideSource(out.file, out.changed) : null;
68
+ if (src)
69
+ return sendJson(res, src);
70
+ return sendJson(res, { error: `no source for ${mod.slice(0, 300)}: ${out === null || (out && !src) ? "its file is not found outside the project" : "it is not a module of the graph"}` }, 404);
71
+ }
72
+ const text = readFileSync(join(live.project.root, rel), "utf8");
73
+ const hash = lakeTextHash(text);
74
+ // the usage pass's contexts of the module (shared/context.ts), when this is the text it
75
+ // elaborated
76
+ const contexts = live.contextsOf(mod);
77
+ // the hash says whether this is the text the graph was read from (meta.modules[].compiled)
78
+ return sendJson(res, { module: mod, file: rel, text, hash, ...(contexts && contexts.hash === hash ? { contexts } : {}) });
79
+ }
80
+ /** /api/hover and under it: Lean's language server asked about a module of the graph. */
81
+ export async function hover(app, req, res, url, reader) {
82
+ const live = app.live;
83
+ const path = url.pathname;
84
+ // what Lean says is at a position of a project file (server/hover.ts). Only the graph's
85
+ // modules (meta.modules) reach Lean: the module names the file the graph was read from, so
86
+ // no path from the client reaches the disk, and no other file in the project's folder — an
87
+ // old copy, a CI script — is ever elaborated or imported. Outside the project, only a
88
+ // module an outside declaration of the graph is in, its file found in its package
89
+ // (server/outside.ts; the owner's decision of 2026-10-20)
90
+ if (!live.graph)
91
+ return sendJson(res, { error: "not ready" }, 503);
92
+ const mod = url.searchParams.get("module") ?? "";
93
+ const rel = live.moduleFile(mod);
94
+ const out = rel === undefined ? live.outsideFile(mod) : undefined;
95
+ if (rel === undefined && out === undefined)
96
+ return sendJson(res, { error: `${mod.slice(0, 300)} is not a module of the graph` }, 404);
97
+ // a read-only reader (CollabSpec decision 11) is answered what Lean already said of this
98
+ // build, else asks it within bounds, per address and in all
99
+ const keyOf = reader !== undefined && req.method === "GET" ? `${live.graph.fingerprint}\0${path}\0${url.search}` : null;
100
+ const kept = keyOf ? app.bounds.answer(keyOf) : undefined;
101
+ if (kept !== undefined)
102
+ return sendJson(res, kept);
103
+ if (reader !== undefined) {
104
+ const wait = app.bounds.leanWait(req.socket.remoteAddress ?? "");
105
+ if (wait)
106
+ return sendJson(res, { error: "Lean is asked too often from here: try again in a moment.", retryAfter: wait }, 429, { "retry-after": String(wait) });
107
+ }
108
+ const reply = (body) => {
109
+ if (keyOf && finalAnswer(body))
110
+ app.bounds.keep(keyOf, body);
111
+ return sendJson(res, body);
112
+ };
113
+ if (path === "/api/hover/describe") {
114
+ // a declaration by name, where the module on show is imported: what a name in a hover card
115
+ // shows. The name is checked to be a name before it is written into Lean source.
116
+ const name = url.searchParams.get("name") ?? "";
117
+ if (!isDeclName(name))
118
+ return sendJson(res, { error: "not a name" }, 400);
119
+ return reply(await app.hover.describe(mod, name, 6000));
120
+ }
121
+ if (path === "/api/hover/print") {
122
+ // what Lean's #print says of a declaration it generated from a command, which has no text
123
+ // of its own (the source window, under the command that made it, when asked)
124
+ const name = url.searchParams.get("name") ?? "";
125
+ if (!isDeclName(name))
126
+ return sendJson(res, { error: "not a name" }, 400);
127
+ return reply(await app.hover.print(mod, name, false, 6000));
128
+ }
129
+ if (rel === null || out === null || (rel === undefined && !out))
130
+ return sendJson(res, { error: `no source for ${mod.slice(0, 300)}` }, 404);
131
+ // an outside file is opened by its resolved path, under its package's name
132
+ const file = out ? { name: `${out.file.package.name}: ${out.file.file}`, path: out.file.path } : rel;
133
+ const text = readFileSync(out ? out.file.path : join(live.project.root, rel), "utf8");
134
+ const hash = lakeTextHash(text);
135
+ if (path === "/api/hover/open") {
136
+ try {
137
+ await app.hover.open(file, text, hash);
138
+ return sendJson(res, { ok: true });
139
+ }
140
+ catch (e) {
141
+ return sendJson(res, { error: app.hover.failure ?? (e instanceof Error ? e.message : String(e)) });
142
+ }
143
+ }
144
+ // the page shows another text than there is now: it reads the source again first
145
+ const want = url.searchParams.get("hash");
146
+ if (want && want !== hash)
147
+ return sendJson(res, { stale: true });
148
+ if (path === "/api/hover/names") {
149
+ // the positions of the names in a declaration's source, as JSON [[line, character], …]
150
+ const r = await app.json(req, 1 << 20);
151
+ if (r.error !== undefined)
152
+ return sendJson(res, { error: r.error }, 400);
153
+ const ps = r.body;
154
+ 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));
155
+ if (!ok)
156
+ return sendJson(res, { error: "positions" }, 400);
157
+ return sendJson(res, await app.hover.names(file, text, hash, ps, 8000));
158
+ }
159
+ const line = Number(url.searchParams.get("line")), character = Number(url.searchParams.get("character"));
160
+ if (!Number.isInteger(line) || !Number.isInteger(character) || line < 0 || character < 0)
161
+ return sendJson(res, { error: "position" }, 400);
162
+ return reply(await app.hover.hover(file, text, hash, line, character, 6000));
163
+ }
164
+ /** the project's git source and commit as git says them now, not as the build was read (an
165
+ * artwork's foot, ExportSpec decision 19; the owner's decision of 2026-10-15) */
166
+ export function git(app, res) {
167
+ const live = app.live;
168
+ // following a branch, the commit of the build on show, on that branch: what is checked out
169
+ // meanwhile is the build going on (DeploySpec decision 12)
170
+ const shown = live.shownCommit();
171
+ if (shown !== undefined)
172
+ return sendJson(res, { git: shown && { source: live.deploy.status(false).source, commit: shown.hash, branch: shown.branch } });
173
+ if (!app.gitRead || Date.now() - app.gitRead.at >= app.gitFreshMs)
174
+ app.gitRead = { git: gitSource(live.project.root), at: Date.now() };
175
+ return sendJson(res, { git: app.gitRead.git });
176
+ }
@@ -0,0 +1,179 @@
1
+ // Share, for people (the routes of server/app.ts): a token for an AI agent and its prompt (AgentSpec
2
+ // decision 7), a personal link for a person (CollabSpec decision 9) and the one a page came by, and
3
+ // read-only links (decision 11) — each listed, made, shown again or revoked. Agents are refused all
4
+ // of it, at every level: what lets someone in stays with people.
5
+ import { defaultAgentName, madeBy } from "../shared/collab.js";
6
+ import { INVITE_PATH, invalidPersonName, Invites } from "./invites.js";
7
+ import { AGENT_LEVELS, lower } from "./agent.js";
8
+ import { AgentTokens, DEFAULT_DAYS, invalidAgentName, TOKEN_DAYS } from "./tokens.js";
9
+ import { agentPrompt } from "./prompt.js";
10
+ import { reachedAt, sendJson } from "./send.js";
11
+ /** Sharing with an AI agent (AgentSpec decision 7), for people: the tokens in force (GET), a new
12
+ * one with its prompt (POST), a token's prompt shown again (POST …/prompt), and revoking one
13
+ * (POST …/revoke). All but the list need a name: a token is made under it, and its prompt holds
14
+ * the token. The prompt is asked for by POST, as making one is, so that the browser sends its
15
+ * Origin and the prompt names the server as the page reached it, the same both times. */
16
+ export async function shareAgents(app, req, res, url) {
17
+ // agent tokens stay with people, at every level (the owner's decision, AgentSpec decision 9):
18
+ // an agent that could make, show or revoke tokens could outlive its own revocation. A token
19
+ // never gets here (it reaches the agents' API alone), and a request that says it is an agent's
20
+ // is refused
21
+ if (app.ids.kind(req) === "agent")
22
+ return sendJson(res, { error: "Agent tokens are for people: an agent cannot make, show or revoke them, at any level." }, 403);
23
+ const tokens = app.live.tokens;
24
+ const top = app.agents.level;
25
+ const me = app.ids.who(req);
26
+ const path = url.pathname.replace(/\/+$/, "");
27
+ if (path === "/api/share/agents" && req.method === "GET")
28
+ 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) });
29
+ if (req.method !== "POST")
30
+ return sendJson(res, { error: `${path} answers POST.` }, 405);
31
+ if (!me)
32
+ return sendJson(res, { error: "Say who you are first: a token is made, shown or revoked under your name.", who: true }, 401);
33
+ const r = await app.json(req, 1 << 16);
34
+ if (r.error !== undefined)
35
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
36
+ const b = (r.body ?? {});
37
+ if (path === "/api/share/agents/revoke") {
38
+ if (typeof b.id !== "string" || !tokens.revoke(b.id, me))
39
+ return sendJson(res, { error: "There is no such token in force." }, 404);
40
+ return sendJson(res, { ok: true, tokens: tokens.inForce().map(AgentTokens.info) });
41
+ }
42
+ // the server as the prompt names it
43
+ const address = app.publicUrl ?? reachedAt(req);
44
+ if (path === "/api/share/agents/prompt") {
45
+ // a token that ended has no prompt: it lets nothing in. Its maker alone is shown it again (the
46
+ // owner's decision of 2026-10-19): whoever holds the token reads its private channel
47
+ const t = typeof b.id === "string" ? tokens.token(b.id) : null;
48
+ if (!t)
49
+ return sendJson(res, { error: "There is no such token in force." }, 404);
50
+ if (!madeBy(t.record, { name: me, person: app.ids.person(req)?.id ?? null }))
51
+ 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);
52
+ return sendJson(res, { token: AgentTokens.info(t.record), prompt: agentPrompt({ url: address, token: t.token, record: t.record }) });
53
+ }
54
+ if (path !== "/api/share/agents")
55
+ return sendJson(res, { error: "not found" }, 404);
56
+ // the name given is the agent's as it is; none, the person's AI ("Alice's AI")
57
+ const name = b.name === undefined || b.name === null || (typeof b.name === "string" && !b.name.trim()) ? defaultAgentName(me) : b.name;
58
+ const bad = invalidAgentName(name);
59
+ if (bad)
60
+ return sendJson(res, { error: bad }, 400);
61
+ const level = (b.level ?? lower("advise", top));
62
+ if (!AGENT_LEVELS.includes(level))
63
+ return sendJson(res, { error: "level is read, advise or full." }, 400);
64
+ if (AGENT_LEVELS.indexOf(level) > AGENT_LEVELS.indexOf(top))
65
+ return sendJson(res, { error: `This server lets agents do at most ${top} (--agents ${top}): a token cannot give more.` }, 400);
66
+ const days = b.days ?? DEFAULT_DAYS;
67
+ if (!TOKEN_DAYS.includes(days))
68
+ return sendJson(res, { error: `days is one of ${TOKEN_DAYS.join(", ")}.` }, 400);
69
+ const made = tokens.create({ name: name.trim(), by: me, person: app.ids.person(req)?.id ?? null, level, days: days });
70
+ const prompt = agentPrompt({ url: address, token: made.token, record: made.record });
71
+ return sendJson(res, { token: AgentTokens.info(made.record), prompt, tokens: tokens.inForce().map(AgentTokens.info) });
72
+ }
73
+ /** Inviting a person (CollabSpec decision 9), for people: the personal links in force (GET), a new
74
+ * one for a person named in the body (POST), and revoking one (POST …/revoke). Making and
75
+ * revoking need a name: who made a link, and who revoked it, is said in Share. The link itself
76
+ * is answered once to whoever made it, and again to its holder alone (`mine`). */
77
+ export async function sharePeople(app, req, res, url) {
78
+ if (app.ids.kind(req) === "agent")
79
+ return sendJson(res, { error: "Personal links are for people: an agent cannot make, list, show or revoke them." }, 403);
80
+ if (app.ids.header)
81
+ return sendJson(res, { error: "Names come from the sign-in in front of this server: it has no personal links." }, 404);
82
+ const invites = app.live.invites;
83
+ const path = url.pathname.replace(/\/+$/, "");
84
+ if (path === "/api/share/people/mine" || path === "/api/share/people/mine/renew")
85
+ return myLink(app, req, res, path);
86
+ const list = () => invites.inForce().map(Invites.info);
87
+ if (path === "/api/share/people" && req.method === "GET")
88
+ return sendJson(res, { invites: list() });
89
+ if (req.method !== "POST")
90
+ return sendJson(res, { error: `${path} answers POST.` }, 405);
91
+ const me = app.ids.who(req);
92
+ if (!me)
93
+ return sendJson(res, app.nameless(req, "a personal link is made or revoked under your name"), 401);
94
+ const r = await app.json(req, 4096);
95
+ if (r.error !== undefined)
96
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
97
+ const b = (r.body ?? {});
98
+ if (path === "/api/share/people/revoke") {
99
+ if (typeof b.id !== "string" || !invites.revoke(b.id, me))
100
+ return sendJson(res, { error: "There is no such personal link in force." }, 404);
101
+ return sendJson(res, { ok: true, invites: list() });
102
+ }
103
+ if (path !== "/api/share/people")
104
+ return sendJson(res, { error: "not found" }, 404);
105
+ const bad = invalidPersonName(b.name);
106
+ if (bad)
107
+ return sendJson(res, { error: bad }, 400);
108
+ const made = invites.create({ name: b.name, by: me });
109
+ if (typeof made === "string")
110
+ return sendJson(res, { error: made, taken: true }, 409);
111
+ // the link as the person will open it: the server's address as this page reached it
112
+ const link = `${app.publicUrl ?? reachedAt(req)}${INVITE_PATH}${made.token}`;
113
+ return sendJson(res, { invite: Invites.info(made.record), link, invites: list() });
114
+ }
115
+ /** The personal link a page came by, for its holder alone (CollabSpec decision 9, the owner's
116
+ * decision of 2026-10-19): shown again (POST /api/share/people/mine; `link` null for a link made
117
+ * before 0.6.0, of which the server kept only the digest), or made anew (POST …/mine/renew,
118
+ * `{stream}` the event stream of the page asking, which stays open) — the same id under a new
119
+ * secret, the old link and the browsers it let in cut off, this browser given the new cookie.
120
+ * Whoever else asks is refused: its maker, a guest, an agent; a read-only reader's page posts
121
+ * nothing here (server/readonlygate.ts). Asked for by POST, as an agent's prompt is, so that the
122
+ * browser sends its Origin and the link names the server as the page reached it. */
123
+ async function myLink(app, req, res, path) {
124
+ const p = app.ids.person(req);
125
+ if (!p)
126
+ 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);
127
+ if (req.method !== "POST")
128
+ return sendJson(res, { error: `${path} answers POST.` }, 405);
129
+ const invites = app.live.invites;
130
+ const address = app.publicUrl ?? reachedAt(req);
131
+ if (path === "/api/share/people/mine") {
132
+ const token = invites.tokenOf(p.id);
133
+ return sendJson(res, { invite: Invites.info(p), link: token ? `${address}${INVITE_PATH}${token}` : null });
134
+ }
135
+ const r = await app.json(req, 4096);
136
+ if (r.error !== undefined)
137
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
138
+ const keep = r.body?.stream;
139
+ const made = invites.renew(p.id, { keep: typeof keep === "string" ? keep : undefined });
140
+ if (!made)
141
+ return sendJson(res, { error: "There is no such personal link in force." }, 404);
142
+ // this browser stays in: the cookie of the new link, beside what the request was given already
143
+ const set = res.getHeader("set-cookie");
144
+ res.setHeader("set-cookie", [...(Array.isArray(set) ? set : set === undefined ? [] : [String(set)]), invites.cookie(made.record)]);
145
+ return sendJson(res, { invite: Invites.info(made.record), link: `${address}${INVITE_PATH}${made.token}` });
146
+ }
147
+ /** Read-only links (CollabSpec decision 11), for people: every link (GET), a new one (POST), and
148
+ * revoking one (POST …/revoke). Anyone let in may make one; revoking needs a name, which Share
149
+ * says beside the link. A server open to all, or behind a sign-in, has none. */
150
+ export async function shareReadOnly(app, req, res, url) {
151
+ if (app.ids.kind(req) === "agent")
152
+ return sendJson(res, { error: "Read-only links are for people: an agent cannot make, list or revoke them." }, 403);
153
+ if (!app.access || app.ids.header)
154
+ return sendJson(res, { error: app.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);
155
+ const links = app.live.readOnly;
156
+ const path = url.pathname.replace(/\/+$/, "");
157
+ const address = app.publicUrl ?? reachedAt(req);
158
+ const list = () => links.list().map((l) => ({ ...l, link: `${address}${l.path}` }));
159
+ if (path === "/api/share/readonly" && req.method === "GET")
160
+ return sendJson(res, { links: list() });
161
+ if (req.method !== "POST")
162
+ return sendJson(res, { error: `${path} answers POST.` }, 405);
163
+ const me = app.ids.who(req);
164
+ if (path === "/api/share/readonly/revoke") {
165
+ if (!me)
166
+ return sendJson(res, app.nameless(req, "a read-only link is revoked under your name"), 401);
167
+ const r = await app.json(req, 4096);
168
+ if (r.error !== undefined)
169
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
170
+ const id = r.body?.id;
171
+ if (typeof id !== "string" || !links.revoke(id, me))
172
+ return sendJson(res, { error: "There is no such read-only link in force." }, 404);
173
+ return sendJson(res, { ok: true, links: list() });
174
+ }
175
+ if (path !== "/api/share/readonly")
176
+ return sendJson(res, { error: "not found" }, 404);
177
+ const made = links.create(me);
178
+ return sendJson(res, { made: { ...made, link: `${address}${made.path}` }, links: list() });
179
+ }
@@ -0,0 +1,120 @@
1
+ // What pages record in the site (the routes of server/app.ts): the review (ReviewSpec.md), the views
2
+ // and their layouts (ViewSpec.md) and a layout batch undone, the history's moves and the
3
+ // lost-and-found (HistorySpec.md), the library (AttachmentSpec.md). Each is recorded under who asks,
4
+ // as the agents' API records it; an agent here is held to its level as there.
5
+ import { historyAnswer } from "./historyapi.js";
6
+ import { layoutAuthor } from "./identity.js";
7
+ import { MAX_MEMORY_BYTES } from "./views.js";
8
+ import { needOf, refusal } from "./agent.js";
9
+ import { libraryApiOf } from "./library.js";
10
+ import { libraryRoute } from "./libraryroute.js";
11
+ import { sendGz, sendJson } from "./send.js";
12
+ import { undo } from "./agentplaces.js";
13
+ /** POST /api/review: what a page records in the review, `{op, …}` (server/reviewapi.ts). */
14
+ export function reviewPost(app, req, res, agent) {
15
+ // an opinion, a target, a trusted prefix or a key declaration is recorded under the
16
+ // reader's name (CollabSpec decision 3), not one in the body; what it is about is
17
+ // bound by the server (server/reviewapi.ts)
18
+ const me = app.ids.who(req);
19
+ if (!me)
20
+ return sendJson(res, app.nameless(req, "what you record in the review is recorded under your name"), 401);
21
+ const person = app.ids.person(req)?.id ?? null;
22
+ return app.json(req, 1 << 20).then(({ body, error }) => {
23
+ if (error)
24
+ return sendJson(res, { error: `The body is ${error}.` }, 400);
25
+ // an agent records here what its level allows, as through its own API (AgentSpec decision
26
+ // 9): an opinion as advice, the rest at full; in its own log, marked as an agent's
27
+ const no = agent ? refusal(app.agents.level, needOf(body)) : null;
28
+ if (no)
29
+ return sendJson(res, no.body, no.status);
30
+ // someone invited by a personal link writes to the log of their link (shared/review.ts)
31
+ const a = app.agents.reviews.post(body, { name: me, agent, person });
32
+ sendJson(res, a.body, a.status);
33
+ });
34
+ }
35
+ /** A request about views (server/views.ts): read here, answered there. A private page's is
36
+ * answered as its, recorded without its name (CollabSpec decision 8). */
37
+ export async function views(app, req, res, url) {
38
+ const priv = app.ids.privateOf(req);
39
+ const person = app.ids.person(req);
40
+ const caller = { name: app.ids.who(req), kind: app.ids.kind(req), ...(person ? { person: person.id } : {}), ...(priv !== null ? { private: { session: priv || null } } : {}) };
41
+ let body = null;
42
+ if (req.method === "POST") {
43
+ // a board's layout memory is as large as the board; nothing else about views is
44
+ const r = await app.json(req, url.pathname.replace(/\/+$/, "") === "/api/views/memory" ? MAX_MEMORY_BYTES : 1 << 20);
45
+ if (r.error !== undefined)
46
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
47
+ body = r.body;
48
+ }
49
+ const a = app.live.views.handle({ method: req.method ?? "GET", path: url.pathname, query: url.searchParams, body, caller }, app.agents.level);
50
+ sendJson(res, a.body, a.status, a.headers);
51
+ }
52
+ /** a layout batch an agent made, undone (AgentSpec decision 4): from a page's Activity, by anyone;
53
+ * by a private reader, without their name (CollabSpec decision 8) */
54
+ export async function layoutUndo(app, req, res, agent) {
55
+ const priv = app.ids.privateOf(req) !== null;
56
+ const me = layoutAuthor({ name: app.ids.who(req), private: priv });
57
+ if (!me && !priv)
58
+ return sendJson(res, { error: "Say who you are first.", who: true }, 401);
59
+ const no = agent ? refusal(app.agents.level, "full") : null;
60
+ if (no)
61
+ return sendJson(res, no.body, no.status);
62
+ const r = await app.json(req, 4096);
63
+ if (r.error !== undefined)
64
+ return sendJson(res, { error: r.error }, 400);
65
+ const a = undo(app.agents, me, agent, r.body?.id);
66
+ return sendJson(res, a.body, a.status);
67
+ }
68
+ /** the snapshots of the graph, one per build (HistorySpec.md): the Time Machine reads them; the
69
+ * moves, the lost-and-found and its archive */
70
+ export async function history(app, req, res, url) {
71
+ const live = app.live;
72
+ const path = url.pathname;
73
+ let body = null;
74
+ if (req.method === "POST") {
75
+ // a name's every entry archived at once is a few hundred keys at most
76
+ const r = await app.json(req, 1 << 20);
77
+ if (r.error !== undefined)
78
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
79
+ body = r.body;
80
+ }
81
+ // a move, an archiving or a putting back is recorded as the review is: under the reader's
82
+ // name — a private reader's too (CollabSpec decision 8) — with the personal link of someone
83
+ // invited by one, whose moves go to their link's log (decision 9); by an agent at level full
84
+ const person = app.ids.person(req)?.id;
85
+ const a = await historyAnswer(live, { method: req.method ?? "GET", path, query: url.searchParams, body, caller: { name: app.ids.who(req), kind: app.ids.kind(req), ...(person ? { person } : {}) } }, (q) => q.caller.kind === "agent" ? refusal(app.agents.level, "full") : null);
86
+ // a snapshot's graph in parts, as the Time Machine takes it: compressed once, and tagged
87
+ if (a.gz)
88
+ return sendGz(req, res, a.gz.body, a.gz.type);
89
+ return sendJson(res, a.body, a.status, a.headers);
90
+ }
91
+ /** The library's operations (server/library.ts), shared with the agents' API. */
92
+ function library(app) {
93
+ return libraryApiOf(app.live, () => ({
94
+ review: app.live.review,
95
+ project: app.live.project,
96
+ library: app.live.library,
97
+ graph: () => {
98
+ const v = app.agents.reviews.graph();
99
+ return "status" in v ? null : v;
100
+ },
101
+ // every file the library takes shows on the Project: a note carries it, on the ring
102
+ fileAdded: (f, who, note) => void app.live.views.fileAdded(f, { by: who.name, agent: who.agent, person: who.person ?? null }, note),
103
+ }));
104
+ }
105
+ /** the library of papers and images, and the links into them (AttachmentSpec.md,
106
+ * server/libraryroute.ts) */
107
+ export function libraryRequest(app, req, res, url, reader) {
108
+ const live = app.live;
109
+ const path = url.pathname;
110
+ // a read-only reader (CollabSpec decision 11) is drawn what the notes show of a PDF, kept in
111
+ // the cache as it is drawn, and no other page or region of one: each would be drawn by
112
+ // Poppler and kept anew, whoever comes asking
113
+ if (reader !== undefined && (path === "/api/library/page" || path === "/api/library/clip")) {
114
+ const q = url.searchParams;
115
+ const region = path === "/api/library/clip" ? (q.get("region") ?? "").split(",").map(Number) : null;
116
+ if (!live.views.shows(q.get("sha") ?? "", Number(q.get("page")), region))
117
+ return sendJson(res, { error: "A read-only page is drawn what the notes show of the library: open the file itself.", readOnly: true }, 403);
118
+ }
119
+ return libraryRoute({ ids: app.ids, level: app.agents.level, api: library(app) }, req, res, url);
120
+ }