visualproof 0.4.4 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/README.md +16 -7
  2. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  3. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  4. package/dist/assets/tips/tour-agent.webp +0 -0
  5. package/dist/assets/tips/tour-arrange.webp +0 -0
  6. package/dist/assets/tips/tour-artwork.webp +0 -0
  7. package/dist/assets/tips/tour-checks.webp +0 -0
  8. package/dist/assets/tips/tour-keys.webp +0 -0
  9. package/dist/assets/tips/tour-library.webp +0 -0
  10. package/dist/assets/tips/tour-project.webp +0 -0
  11. package/dist/assets/tips/tour-review.webp +0 -0
  12. package/dist/assets/tips/tour-share.webp +0 -0
  13. package/dist/assets/tips/tour-source.webp +0 -0
  14. package/dist/assets/tips/tour-target.webp +0 -0
  15. package/dist/assets/tips/tour-view.webp +0 -0
  16. package/dist/assets/tips/tour.json +132 -117
  17. package/dist/assets/tips/tour.webp +0 -0
  18. package/dist/mcp/visualproof-mcp.mjs +20 -9
  19. package/dist/server/access.js +31 -1
  20. package/dist/server/accesspage.js +130 -0
  21. package/dist/server/agent.js +143 -50
  22. package/dist/server/askfollow.js +1 -1
  23. package/dist/server/buildwatch.js +133 -0
  24. package/dist/server/deploy.js +995 -0
  25. package/dist/server/doctor.js +15 -3
  26. package/dist/server/film.js +1 -1
  27. package/dist/server/historyapi.js +100 -50
  28. package/dist/server/historythread.js +206 -0
  29. package/dist/server/hover.js +8 -0
  30. package/dist/server/invites.js +113 -20
  31. package/dist/server/live.js +308 -60
  32. package/dist/server/main.js +450 -77
  33. package/dist/server/mcptools.js +33 -20
  34. package/dist/server/presence.js +3 -3
  35. package/dist/server/prompt.js +8 -3
  36. package/dist/server/readonlygate.js +4 -4
  37. package/dist/server/review.js +27 -7
  38. package/dist/server/reviewapi.js +51 -17
  39. package/dist/server/status.js +119 -46
  40. package/dist/server/talk.js +231 -115
  41. package/dist/server/tokens.js +10 -2
  42. package/dist/server/usage.js +51 -0
  43. package/dist/shared/board.js +2 -1
  44. package/dist/shared/build.js +35 -1
  45. package/dist/shared/collab.js +8 -0
  46. package/dist/shared/deploy.js +35 -0
  47. package/dist/shared/keys.js +66 -37
  48. package/dist/shared/layout.js +297 -70
  49. package/dist/shared/libm.js +366 -0
  50. package/dist/shared/lostfound.js +1 -0
  51. package/dist/shared/mentions.js +83 -0
  52. package/dist/shared/palette.js +1 -1
  53. package/dist/shared/query.js +13 -4
  54. package/dist/shared/review.js +91 -21
  55. package/dist/shared/reviewqueue.js +6 -1
  56. package/dist/shared/separate.js +556 -32
  57. package/dist/web/bundle/app.js +5022 -2736
  58. package/dist/web/bundle/edges.js +2 -1
  59. package/dist/web/bundle/layout.js +1026 -80
  60. package/dist/web/index.html +45 -9
  61. package/dist/web/src/canvas.js +47 -34
  62. package/dist/web/src/overview.js +4 -1
  63. package/dist/web/src/reviewqueue.js +52 -19
  64. package/dist/web/src/scene.js +13 -12
  65. package/dist/web/src/status.js +28 -0
  66. package/dist/web/src/theme.js +108 -0
  67. package/dist/web/src/trust.js +271 -0
  68. package/dist/web/style.css +283 -105
  69. package/docs/agent-api/README.md +13 -11
  70. package/docs/agent-api/advice.md +8 -2
  71. package/docs/agent-api/export.md +1 -1
  72. package/docs/agent-api/following.md +11 -12
  73. package/docs/agent-api/history.md +6 -2
  74. package/docs/agent-api/mcp.md +15 -15
  75. package/docs/agent-api/notes.md +1 -1
  76. package/docs/agent-api/reading.md +2 -2
  77. package/docs/agent-api/requests.md +16 -18
  78. package/docs/agent-api/talking.md +60 -55
  79. package/docs/agent-api/tcb.md +21 -21
  80. package/docs/agent-api/views.md +3 -4
  81. package/docs/agent-api/words.md +8 -8
  82. package/package.json +2 -1
@@ -4,14 +4,16 @@
4
4
  // Two speeds, on purpose. Build status is cheap (a few stats and hashes) and goes out every
5
5
  // second it changes, so a page shows "building 12 / 40" while Lean works. The graph is expensive
6
6
  // and only meaningful between builds, so it is re-extracted once the outputs stop moving; until
7
- // then the page keeps the last good graph and says how old it is.
7
+ // then the page keeps the last good graph and says how old it is. With nothing happening, the
8
+ // loop asks which compiles run, and looks at the files only when a watch says something moved
9
+ // (server/buildwatch.ts): a server at rest costs next to nothing.
8
10
  //
9
11
  // The extractor's graph is served as soon as it is ready; the usage pass (server/usage.ts) then
10
12
  // elaborates the modules whose result is not cached, and its findings — the notation each unit is
11
13
  // written in, the exact contexts — come as the next version of the graph. Where every module's
12
14
  // result is cached, the merged graph is the first one served.
13
15
  import { randomBytes } from "node:crypto";
14
- import { sameName } from "../shared/collab.js";
16
+ import { madeBy, nameKey, sameName } from "../shared/collab.js";
15
17
  import { prepare } from "./pipeline.js";
16
18
  import { extract, loadSaved } from "./extract.js";
17
19
  import { DEFAULT_JOBS, UsagePass, mergeUsage, saveMerged } from "./usage.js";
@@ -23,9 +25,11 @@ import { agentKey, Presence } from "./presence.js";
23
25
  import { AgentTokens } from "./tokens.js";
24
26
  import { Invites } from "./invites.js";
25
27
  import { ReadOnlyLinks } from "./readonly.js";
26
- import { Talk } from "./talk.js";
28
+ import { forPages, PUBLIC, Talk } from "./talk.js";
27
29
  import { Asks } from "./askfollow.js";
28
- import { BuildTracker, importable, outputStamp, scanModules, sourceStamp } from "./status.js";
30
+ import { BuildTracker, compiling, importable, outputsOf, probeAll, scanModules, stampOf } from "./status.js";
31
+ import { BuildWatch, moduleDirs, shouldLook } from "./buildwatch.js";
32
+ import { buildChanges } from "../shared/build.js";
29
33
  import { Views } from "./views.js";
30
34
  import { graphOf, memoryProblem, titleContext } from "./agentviews.js";
31
35
  import { ownName, rebinder, versionBase, versions, withVersions } from "./versions.js";
@@ -45,6 +49,9 @@ import { withoutReasons } from "../shared/timeline.js";
45
49
  const TICK = 1000;
46
50
  /** outputs quiet this long, and no compile running: the build is over */
47
51
  const SETTLE = 2500;
52
+ /** how long a watch's news of a change a look found may take before the look counts as one it
53
+ * missed (server/buildwatch.ts) */
54
+ const MISS_GRACE_MS = 500;
48
55
  const PING = 15000;
49
56
  /** Event streams, which every change goes to: at most this many open at once, and this many per
50
57
  * page (`session`: a reload, a lost connection coming back), its oldest closed for a new one. */
@@ -59,6 +66,13 @@ export const MAX_STREAMS_PER_SESSION = 4;
59
66
  export const MAX_BUFFERED = 4 << 20;
60
67
  /** the list of who is here goes out at most this often: a burst of heartbeats is one event */
61
68
  const PRESENCE_EVERY = 500;
69
+ /** A change of the build status larger than this, and than this part of the whole (about what the
70
+ * whole takes compressed: 42 KB of NavierStokesAndEuler's 362), goes out as its revision alone
71
+ * (`build-rev`), which every page reads compressed (GET /api/build) rather than take it uncompressed
72
+ * on its stream: the first look, an edit or a build that starts or fails under much of a large
73
+ * project. A smaller one is no saving worth a request. */
74
+ export const BUILD_DELTA_MAX = 64 << 10;
75
+ export const BUILD_DELTA_PART = 1 / 8;
62
76
  /** The graph's modules and their files (meta.modules), per graph read (agentviews.ts, graphOf). */
63
77
  const moduleFiles = new WeakMap();
64
78
  export class Live {
@@ -70,7 +84,21 @@ export class Live {
70
84
  mods = new Map();
71
85
  lastStamp = "";
72
86
  extractedStamp = "";
87
+ /** what the last look would read: the stamp, or a followed branch's outputs alone */
88
+ lastRead = "";
73
89
  quietSince = 0;
90
+ /** what tells the loop to look at the files (server/buildwatch.ts) */
91
+ buildWatch = new BuildWatch((l) => this.say(l));
92
+ /** when the files were last looked at, the compiles that ran then, and the status as last sent */
93
+ lastLook = 0;
94
+ lastRunning = "";
95
+ buildText = "";
96
+ /** the build status's revision (`build-rev`, `build-delta`), counted from 0, before the first look,
97
+ * in this server's process; each file's status as last sent, as JSON, by module; and the whole as
98
+ * GET /api/build answers it, made when first asked */
99
+ buildRev = 0;
100
+ buildFiles = new Map();
101
+ buildWholeText = null;
74
102
  build = null;
75
103
  graph = null;
76
104
  extracting = false;
@@ -86,6 +114,11 @@ export class Live {
86
114
  /** review changes not yet sent: those made in one turn of the event loop go out as one */
87
115
  reviewPending = [];
88
116
  version = 0;
117
+ /** the branch followed (DeploySpec), where the server builds what it shows; null for a workspace,
118
+ * whose builds are its owner's */
119
+ deploy = null;
120
+ /** graphs being made ready to serve (install): the tree is read meanwhile */
121
+ installing = 0;
89
122
  /** this server's process, as its pages know it (UpdateSpec decision 8): the graph's versions are
90
123
  * counted again by another */
91
124
  instance = randomBytes(6).toString("base64url");
@@ -155,11 +188,13 @@ export class Live {
155
188
  this.invites = new Invites(dirs.site);
156
189
  // every page knows the names the people invited by a link go by, so that what each did shows
157
190
  // under the name they go by now; a link revoked cuts its pages off at once, as it does its
158
- // requests: their streams end, and come back only if the key lets them in
191
+ // requests: their streams end, and come back only if the key lets them in. A link made anew
192
+ // does the same, but to the page that made it anew (`keep`): the other pages of its browser,
193
+ // given the new cookie, come back as they were
159
194
  this.invites.onChanged = () => this.send("people", this.invites.people());
160
- this.invites.onEnded = (r) => {
195
+ this.invites.onEnded = (r, keep) => {
161
196
  for (const st of [...this.streams.values()])
162
- if (st.person === r.id)
197
+ if (st.person === r.id && (keep === undefined || st.token !== keep))
163
198
  this.close(st);
164
199
  };
165
200
  this.readOnly = new ReadOnlyLinks(dirs.site);
@@ -231,12 +266,8 @@ export class Live {
231
266
  this.tokens.onEnded = (r) => this.talk.close(r.id, r.revoked ? "revoked" : "expired");
232
267
  this.talk.inForce = (id) => this.tokens.inForce().some((r) => r.id === id);
233
268
  this.talk.onState = (id, talk) => this.presence.setTalk(id, talk);
234
- // a new message goes to every page, named by the agent's entry in presence
235
- this.talk.onMessage = (id, message) => {
236
- const r = this.tokens.get(id);
237
- if (r)
238
- this.send("chat", { agent: agentKey({ name: r.name, token: r.id }), message });
239
- };
269
+ // a new message goes to the pages that may read its channel (CollabSpec decision 13)
270
+ this.talk.onMessage = (channel, message) => this.sendChat(channel, message);
240
271
  this.views.pageOf = (token) => (typeof token === "string" ? this.byToken.get(token)?.id ?? null : null);
241
272
  // the views a private page holds live while a page of its session is open
242
273
  this.views.sessionOpen = (session) => [...this.streams.values()].some((st) => st.session === session);
@@ -287,10 +318,14 @@ export class Live {
287
318
  * stream that closed, a guess), and nothing changes. A private page's (`priv`, CollabSpec
288
319
  * decision 8) is counted and nothing more is kept of it: not its name, not where it is.
289
320
  * `verified`: the page of someone invited by a personal link (decision 9). */
290
- beat(token, name, view, idle, priv = false, verified = false) {
321
+ beat(token, name, view, idle, priv = false, verified = false, who = name) {
291
322
  const s = typeof token === "string" ? this.byToken.get(token) : undefined;
292
323
  if (!s)
293
324
  return false;
325
+ // the name the page goes by, said by its heartbeat's request, a private page's too (`who`): what
326
+ // of the channels its stream is sent (CollabSpec decision 13)
327
+ if (s.readOnly === null)
328
+ s.name = who;
294
329
  if (s.private !== priv)
295
330
  this.rename(s, priv, name, view, idle, verified);
296
331
  else if (priv)
@@ -344,7 +379,11 @@ export class Live {
344
379
  }
345
380
  /** The review changed (server/review.ts tells it): every open page gets what changed — the new
346
381
  * events, which it applies to the review it holds (`review-delta`), or, where events came in
347
- * between, the whole review (`review`). Changes made in one turn (an agent's batch of advice)
382
+ * between, the revision alone (`review-rev`), at which the page reads the whole review (GET
383
+ * /api/review, compressed and tagged). The stream never carries the whole review: with thousands
384
+ * of opinions it is megabytes, and it went uncompressed to every page, which read it again from
385
+ * GET /api/review besides (5.4 MB to each page of a review of 5,000 opinions on
386
+ * NavierStokesAndEuler, 0.7 MB compressed). Changes made in one turn (an agent's batch of advice)
348
387
  * go out as one. A new target's TCB is where its timeline starts; it has no view until a click
349
388
  * gives it one (ViewSpec decision 29). */
350
389
  reviewChanged(c) {
@@ -362,7 +401,7 @@ export class Live {
362
401
  if (deltas)
363
402
  this.send("review-delta", { epoch: last.epoch, base: cs[0].base, rev: last.rev, events: cs.flatMap((c) => c.events), problems: last.problems, error: this.review.error });
364
403
  else
365
- this.send("review", this.review.whole());
404
+ this.send("review-rev", this.reviewRev());
366
405
  this.timeline.reviewChanged(this.review.data);
367
406
  // a target a move brought from another name takes that name's view over; a target unmarked is
368
407
  // unlinked from its view
@@ -374,6 +413,41 @@ export class Live {
374
413
  this.reversion();
375
414
  this.lostChanged();
376
415
  }
416
+ /** The build status a look found (the live loop's tick): where it changed, every page is told the
417
+ * files whose status changed, with the new revision (`build-delta`), which it applies to the
418
+ * status it holds; a large change (BUILD_DELTA_MAX) goes out as the revision alone (`build-rev`),
419
+ * at which each page reads the whole (GET /api/build). A page from before 0.6.0 is sent the
420
+ * whole (`build`), as it was. */
421
+ buildFound(build) {
422
+ const text = JSON.stringify(build);
423
+ this.build = build;
424
+ if (text === this.buildText)
425
+ return;
426
+ this.buildText = text;
427
+ this.buildWholeText = null;
428
+ const base = this.buildRev++;
429
+ const { files, gone, texts } = buildChanges(this.buildFiles, build);
430
+ this.buildFiles = texts;
431
+ if (this.streams.size) {
432
+ const delta = { epoch: this.instance, base, rev: this.buildRev, active: build.active, progress: build.progress, counts: build.counts, files, gone };
433
+ const d = JSON.stringify(delta);
434
+ const news = d.length > Math.max(BUILD_DELTA_MAX, text.length * BUILD_DELTA_PART) ? `event: build-rev\ndata: ${JSON.stringify(this.buildRevNow())}\n\n` : `event: build-delta\ndata: ${d}\n\n`;
435
+ let whole = null;
436
+ for (const st of [...this.streams.values()])
437
+ this.push(st, st.buildDeltas ? news : (whole ??= `event: build\ndata: ${text}\n\n`));
438
+ }
439
+ this.timeline.buildStatus(build);
440
+ }
441
+ /** Which build status the server holds (`build-rev`): its process and its revision. */
442
+ buildRevNow() {
443
+ return { epoch: this.instance, rev: this.buildRev };
444
+ }
445
+ /** The whole build status as GET /api/build answers it, with its revision, and the tag of that
446
+ * revision: written once a revision, whoever asks. */
447
+ buildWhole() {
448
+ this.buildWholeText ??= `{"epoch":${JSON.stringify(this.instance)},"rev":${this.buildRev},"status":${this.buildText || "null"}}`;
449
+ return { tag: `"b${this.instance}.${this.buildRev}"`, text: this.buildWholeText };
450
+ }
377
451
  say(line) {
378
452
  this.log.push(line);
379
453
  if (this.log.length > 200)
@@ -397,27 +471,43 @@ export class Live {
397
471
  if (this.history)
398
472
  void backfillSources(this.history, this.project, this.dirs.cache, (l) => this.say(l)).catch((e) => this.say(`history: the source texts could not be backfilled: ${e instanceof Error ? e.message : String(e)}`));
399
473
  // the review's logs are watched whatever the graph comes from: they may change on disk any time
400
- setInterval(() => this.checkReview(), TICK);
401
- setInterval(() => {
474
+ this.timers.push(setInterval(() => this.checkReview(), TICK));
475
+ this.timers.push(setInterval(() => {
402
476
  for (const st of [...this.streams.values()])
403
477
  this.push(st, ": ping\n\n");
404
- }, PING);
478
+ }, PING));
405
479
  if (this.saved) {
406
480
  // a saved extraction does not change: no watching of the build
407
481
  void this.extract(null);
408
482
  return;
409
483
  }
410
484
  const loop = async () => {
485
+ if (this.stopped)
486
+ return;
411
487
  try {
412
488
  await this.tick();
413
489
  }
414
490
  catch (e) {
415
491
  this.say(`watch: ${e instanceof Error ? e.message : String(e)}`);
416
492
  }
417
- setTimeout(loop, TICK);
493
+ if (!this.stopped)
494
+ this.next = setTimeout(loop, TICK);
418
495
  };
419
496
  void loop();
420
497
  }
498
+ /** the loop's timers, which `stop` clears */
499
+ timers = [];
500
+ next = null;
501
+ stopped = false;
502
+ /** Nothing more is watched (a test that ran the loop, at its end). */
503
+ stop() {
504
+ this.stopped = true;
505
+ for (const t of this.timers)
506
+ clearInterval(t);
507
+ if (this.next)
508
+ clearTimeout(this.next);
509
+ this.timers = [];
510
+ }
421
511
  /** The review's logs changed on disk (by hand, a backup restored): what changed is read, and the
422
512
  * store tells the pages. */
423
513
  checkReview() {
@@ -429,30 +519,70 @@ export class Live {
429
519
  }
430
520
  }
431
521
  async tick() {
522
+ const running = await compiling(this.project);
432
523
  const now = Date.now();
433
- const stampOf = () => `${outputStamp(this.project, this.mods)}#${sourceStamp(this.project, this.mods)}`;
434
- let st = stampOf();
524
+ const runs = [...running].sort().join(" ");
525
+ // the files are looked at only when something says to (server/buildwatch.ts)
526
+ const heard = this.buildWatch.dirty;
527
+ const look = shouldLook({
528
+ heard,
529
+ polling: this.buildWatch.polling !== null,
530
+ running: running.size,
531
+ runsChanged: runs !== this.lastRunning,
532
+ active: !!this.build?.active,
533
+ sinceMove: now - this.quietSince,
534
+ sinceLook: now - this.lastLook,
535
+ unread: this.lastRead !== this.extractedStamp,
536
+ settle: SETTLE,
537
+ tick: TICK,
538
+ });
539
+ if (!look)
540
+ return;
541
+ this.buildWatch.dirty = false;
542
+ this.lastLook = now;
543
+ this.lastRunning = runs;
544
+ let probes = probeAll(this.project, this.mods);
545
+ let st = stampOf(probes);
546
+ // the first look is not a change: a project at rest is read at once
547
+ const moved = st !== this.lastStamp && this.lastStamp !== "";
548
+ // a change no watch told of, unless its news is on its way still (through the event loop; after
549
+ // a moment, on macOS): one more and the watches are given up
550
+ if (moved && !heard && this.buildWatch.polling === null)
551
+ setTimeout(() => this.buildWatch.dirty || this.buildWatch.missed(), MISS_GRACE_MS).unref();
435
552
  if (st !== this.lastStamp || this.mods.size === 0) {
436
553
  // sources or outputs moved: files may have appeared, and the import graph changed
437
554
  this.project.files = indexSources(this.project.root);
438
555
  this.mods = scanModules(this.project);
439
- st = stampOf();
556
+ probes = probeAll(this.project, this.mods);
557
+ st = stampOf(probes);
440
558
  }
441
- // the first look is not a change: a project at rest is read at once
442
- const moved = st !== this.lastStamp && this.lastStamp !== "";
559
+ this.buildWatch.watch(moduleDirs(this.project, this.mods), this.project.root);
443
560
  this.lastStamp = st;
444
561
  if (moved)
445
562
  this.quietSince = now;
446
- const build = await this.tracker.status(this.mods);
447
- const before = this.build && JSON.stringify(this.build);
448
- this.build = build;
449
- if (JSON.stringify(build) !== before) {
450
- this.send("build", build);
451
- this.timeline.buildStatus(build);
563
+ // the status as JSON once a look, compared with what went out last
564
+ let build = await this.tracker.status(this.mods, probes, running);
565
+ // following a branch, the build going on is the server's own: active from its fetch to its end
566
+ // (DeploySpec decision 6)
567
+ const d = this.deploy;
568
+ if (d && d.busy && !build.active)
569
+ build = { ...build, active: true };
570
+ this.buildFound(build);
571
+ // and its builds, beside the files: the one going on, the newest commit waiting, the last
572
+ if (d) {
573
+ const now = JSON.stringify(d.status(true));
574
+ if (now !== this.deploySent) {
575
+ this.deploySent = now;
576
+ this.sendDeploy();
577
+ }
452
578
  }
579
+ // a branch's tree is read only between its builds, and only where a build wrote something:
580
+ // its sources change only with a checkout, which a build follows (DeploySpec decision 5)
581
+ const read = d ? outputsOf(probes) : st;
582
+ this.lastRead = read;
453
583
  const settled = !build.active && now - this.quietSince >= SETTLE;
454
- if (settled && !this.extracting && st !== this.extractedStamp) {
455
- this.extractedStamp = st;
584
+ if (settled && !this.extracting && read !== this.extractedStamp && !d?.holds()) {
585
+ this.extractedStamp = read;
456
586
  const ok = importable(this.project, this.mods);
457
587
  const okSet = new Set(ok);
458
588
  const missing = [...this.mods.keys()].filter((m) => !okSet.has(m)).sort();
@@ -517,6 +647,17 @@ export class Live {
517
647
  * provisional: the usage pass's graph, which `completes` that build's extraction, is laid out as
518
648
  * the build's own (server/pipeline.ts, prepare). */
519
649
  async install(ex, missing, usage, completes) {
650
+ // the tree is read until it is served (the source texts the snapshot keeps): a branch's build
651
+ // waits (DeploySpec decision 5)
652
+ this.installing++;
653
+ try {
654
+ await this.installNow(ex, missing, usage, completes);
655
+ }
656
+ finally {
657
+ this.installing--;
658
+ }
659
+ }
660
+ async installNow(ex, missing, usage, completes) {
520
661
  const laid = await prepare(this.project, this.dirs, null, (l) => this.say(l), { extraction: ex, provisional: usage === "pending", completes });
521
662
  if (this.graph && this.graph.fingerprint === laid.fingerprint)
522
663
  return;
@@ -528,7 +669,8 @@ export class Live {
528
669
  // versions served are made under them (HistorySpec.md)
529
670
  const renamed = this.snapshot(ex, missing);
530
671
  const prep = this.versioned(laid);
531
- this.graph = { version: ++this.version, fingerprint: prep.fingerprint, at: new Date().toISOString(), missing, usage: { state: usage, failed }, prep };
672
+ const commit = this.deploy?.commit()?.hash;
673
+ this.graph = { version: ++this.version, fingerprint: prep.fingerprint, at: new Date().toISOString(), missing, usage: { state: usage, failed }, ...(commit ? { commit } : {}), prep };
532
674
  this.send("graph", this.graphInfo());
533
675
  this.lostChanged();
534
676
  // opinions recorded under the kernel's hash are bound to the versions of this graph
@@ -615,7 +757,8 @@ export class Live {
615
757
  // a re-layout going on is let finish; a newer build supersedes the pass
616
758
  while (this.extracting && this.passFor === ex.fingerprint)
617
759
  await new Promise((ok) => setTimeout(ok, 200));
618
- if (!merged || this.passFor !== ex.fingerprint)
760
+ // a branch's build that started meanwhile changes the tree: its graph is read once it ends
761
+ if (!merged || this.passFor !== ex.fingerprint || this.deploy?.holds())
619
762
  return;
620
763
  this.passFor = null;
621
764
  await this.install(merged, missing, "done", ex.fingerprint);
@@ -651,6 +794,12 @@ export class Live {
651
794
  const renamed = this.review.data.renamed;
652
795
  return renamed ? (u) => identityIn(renamed, u) : ownName;
653
796
  }
797
+ /** The renames in force (to → from), which `identity` follows: what the history's worker makes it
798
+ * again from (server/historythread.ts). */
799
+ renamed() {
800
+ const renamed = this.review.data.renamed;
801
+ return renamed ? Object.entries(renamed) : null;
802
+ }
654
803
  /** Keep a snapshot of the graph just read (server/history.ts): a new build's, or its own again;
655
804
  * then pair what vanished since the build before with what appeared (server/renames.ts), and
656
805
  * migrate the renames of high confidence. The pages are told of a snapshot made or changed
@@ -661,7 +810,10 @@ export class Live {
661
810
  return renamed;
662
811
  try {
663
812
  const t0 = Date.now();
664
- const commit = commitNow(this.project.root);
813
+ // a branch's build is of the commit its build checked out, on the branch followed; a
814
+ // workspace's, of the commit checked out as it is read
815
+ const d = this.deploy?.commit();
816
+ const commit = this.deploy ? (d ? { hash: d.hash, branch: d.branch } : null) : commitNow(this.project.root);
665
817
  // the texts the build was compiled from, while its files are most likely still those
666
818
  // (HistorySpec decision 21): only the files that changed since any build are written
667
819
  let written = 0;
@@ -986,7 +1138,51 @@ export class Live {
986
1138
  /** Whether the server is working on the build (an extraction, a re-layout, the usage pass):
987
1139
  * no moment to restart in (UpdateSpec decision 6). */
988
1140
  get busy() {
989
- return this.extracting || this.usage.status.state === "running";
1141
+ return this.extracting || this.usage.status.state === "running" || !!this.deploy?.busy;
1142
+ }
1143
+ /** Whether the tree is being read: an extraction, a re-layout, a graph made ready to serve. A
1144
+ * branch's build changes the tree only after (DeploySpec decision 5). */
1145
+ get reading() {
1146
+ return this.extracting || this.installing > 0;
1147
+ }
1148
+ /** Following a branch, the commit of the graph on show and the branch (an exported document's
1149
+ * build, GET /api/git): null before a build was read; undefined for a workspace, whose commit git
1150
+ * says as it is now. */
1151
+ shownCommit() {
1152
+ const d = this.deploy;
1153
+ if (!d)
1154
+ return undefined;
1155
+ const c = this.graph?.commit ?? d.commit()?.hash;
1156
+ return c ? { hash: c, branch: d.status(false).branch } : null;
1157
+ }
1158
+ /** The branch followed and its builds, as agents are told them (GET /api/agent/history); null
1159
+ * for a workspace. */
1160
+ following() {
1161
+ return this.deploy?.status(true) ?? null;
1162
+ }
1163
+ /** A branch's build ended (DeploySpec decision 5): the tree is read again once it settles,
1164
+ * whatever the build wrote — a usage pass it cut short is done then, from what it finished. */
1165
+ reread() {
1166
+ this.extractedStamp = "";
1167
+ }
1168
+ /** A branch's builds changed (one started, a step, a newer commit waiting): the loop looks at its
1169
+ * next turn, as it does when a watch tells of a change (server/buildwatch.ts), and the pages are
1170
+ * told then. */
1171
+ lookSoon() {
1172
+ this.buildWatch.dirty = true;
1173
+ }
1174
+ /** The branch's builds as the pages were last told them (`deploy`). */
1175
+ deploySent = "";
1176
+ /** The branch's builds, to every page (`deploy`): a read-only reader's without the build's log
1177
+ * (DeploySpec decision 11). */
1178
+ sendDeploy() {
1179
+ const d = this.deploy;
1180
+ if (!d || !this.streams.size)
1181
+ return;
1182
+ const full = `event: deploy\ndata: ${JSON.stringify(d.status(true))}\n\n`;
1183
+ const slim = `event: deploy\ndata: ${JSON.stringify(d.status(false))}\n\n`;
1184
+ for (const st of [...this.streams.values()])
1185
+ this.push(st, st.readOnly === null ? full : slim);
990
1186
  }
991
1187
  /** What happened, to every page: a version set aside, without why, to those not told all
992
1188
  * (UpdateSpec decision 11). */
@@ -1020,8 +1216,10 @@ export class Live {
1020
1216
  st.res.end(text);
1021
1217
  }
1022
1218
  }
1023
- /** What /api/status says: enough for the loader and for a page that just connected. */
1024
- status() {
1219
+ /** What /api/status says: enough for the loader and for a page that just connected. `brief`: the
1220
+ * build status without its files (the page's loader, which reads them by GET /api/build). */
1221
+ status(brief = false) {
1222
+ const b = this.build;
1025
1223
  return {
1026
1224
  state: this.graph ? "ready" : this.extractError ? "error" : "extracting",
1027
1225
  error: this.graph ? undefined : this.extractError ?? undefined,
@@ -1031,7 +1229,9 @@ export class Live {
1031
1229
  graph: this.graphInfo(),
1032
1230
  // the usage pass: how far it is, and the modules it could not elaborate
1033
1231
  usage: this.usage.status,
1034
- build: this.build,
1232
+ build: brief && b ? { active: b.active, progress: b.progress, counts: b.counts } : b,
1233
+ // the branch followed, where the server builds what it shows (DeploySpec)
1234
+ ...(this.deploy ? { deploy: this.deploy.status(true) } : {}),
1035
1235
  live: !this.saved,
1036
1236
  editor: this.editor,
1037
1237
  streams: { open: this.streams.size, max: MAX_STREAMS, readOnly: this.readOnlyStreams(), maxReadOnly: MAX_READONLY_STREAMS, closedForNotReading: this.dropped, agentsListening: this.talk.count },
@@ -1040,10 +1240,11 @@ export class Live {
1040
1240
  };
1041
1241
  }
1042
1242
  /** A page's event stream; `session` is what the page calls itself (its streams are kept few by
1043
- * it), `person` the personal link it came by. The stream is named by the server: the page is
1044
- * told its id, which everyone sees, and a secret for its heartbeats (`hello`); it is gone from
1045
- * presence when its stream closes. */
1046
- subscribe(res, session = null, person = null, readOnly = null, toldAll = readOnly === null) {
1243
+ * it), `person` the personal link it came by, `buildDeltas` whether it takes the build status as
1244
+ * changes (a page of 0.6.0 or later), `name` the name it gives (the conversations it is sent).
1245
+ * The stream is named by the server: the page is told its id, which everyone sees, and a secret
1246
+ * for its heartbeats (`hello`); it is gone from presence when its stream closes. */
1247
+ subscribe(res, session = null, person = null, readOnly = null, toldAll = readOnly === null, buildDeltas = false, name = null) {
1047
1248
  if (session) {
1048
1249
  // a page that opens one more than a page needs (a reload whose old stream lingers) loses
1049
1250
  // its oldest
@@ -1063,7 +1264,7 @@ export class Live {
1063
1264
  connection: "keep-alive",
1064
1265
  });
1065
1266
  res.write("retry: 2000\n\n");
1066
- const st = { res, id: randomBytes(9).toString("base64url"), token: randomBytes(24).toString("base64url"), session, private: false, person, readOnly, toldAll, room: Infinity, after: 0 };
1267
+ const st = { res, id: randomBytes(9).toString("base64url"), token: randomBytes(24).toString("base64url"), session, private: false, person, readOnly, name: readOnly === null ? name : null, toldAll, room: Infinity, after: 0, buildDeltas };
1067
1268
  this.streams.set(res, st);
1068
1269
  this.byToken.set(st.token, st);
1069
1270
  this.presence.open(st.id);
@@ -1077,10 +1278,17 @@ export class Live {
1077
1278
  // the views as they are: a page that was away (a restart, a lost connection) catches up, and
1078
1279
  // reads again the boards it has open
1079
1280
  this.write(res, "views", { views: this.views.list(), changes: [], all: true });
1080
- if (this.build)
1281
+ // the build status's revision: a page that holds another reads the whole (GET /api/build); what
1282
+ // changes after comes as deltas. A page from before 0.6.0 is sent it whole.
1283
+ if (buildDeltas)
1284
+ this.write(res, "build-rev", this.buildRevNow());
1285
+ else if (this.build)
1081
1286
  this.write(res, "build", this.build);
1082
- // the whole review once; what changes after comes as deltas
1083
- this.push(st, this.reviewHello());
1287
+ if (this.deploy)
1288
+ this.write(res, "deploy", this.deploy.status(readOnly === null));
1289
+ // the review's revision: a page that holds another reads the whole review (GET /api/review);
1290
+ // what changes after comes as deltas
1291
+ this.write(res, "review-rev", this.reviewRev());
1084
1292
  const g = this.graphInfo();
1085
1293
  if (g)
1086
1294
  this.write(res, "graph", g);
@@ -1095,15 +1303,9 @@ export class Live {
1095
1303
  st.room = MAX_BUFFERED + res.writableLength;
1096
1304
  st.after = 0;
1097
1305
  }
1098
- /** the whole review as a stream's hello says it, in bytes, and the text it was made from */
1099
- reviewBytes = null;
1100
- /** The whole review as every stream's hello says it: made into bytes once a revision, not once a
1101
- * stream (a hundred pages opening at once, a review of 7.6 MB, had the server 5 s encoding it). */
1102
- reviewHello() {
1103
- const text = this.review.wholeText();
1104
- if (this.reviewBytes?.text !== text)
1105
- this.reviewBytes = { text, bytes: Buffer.from(`event: review\ndata: ${text}\n\n`) };
1106
- return this.reviewBytes.bytes;
1306
+ /** Which review the server holds (`review-rev`): its run and its revision. */
1307
+ reviewRev() {
1308
+ return { epoch: this.review.epoch, rev: this.review.rev };
1107
1309
  }
1108
1310
  write(res, event, data) {
1109
1311
  const st = this.streams.get(res);
@@ -1119,10 +1321,46 @@ export class Live {
1119
1321
  for (const st of [...this.streams.values()])
1120
1322
  this.push(st, text);
1121
1323
  }
1324
+ /** A message of a channel, sent to the pages that read it (CollabSpec decision 13): a public one to
1325
+ * every page with a name, private readers' too; a private one only to the pages of the person
1326
+ * who made its agent's token (shared/collab.ts, madeBy), named by the agent's entry in presence;
1327
+ * nothing to a read-only reader's page, nor to a page without a name. */
1328
+ sendChat(channel, message) {
1329
+ if (!this.streams.size)
1330
+ return;
1331
+ const t = channel === PUBLIC ? null : (this.tokens.get(channel) ?? null);
1332
+ if (channel !== PUBLIC && !t)
1333
+ return;
1334
+ const text = `event: chat\ndata: ${JSON.stringify({ channel: t ? agentKey({ name: t.name, token: t.id }) : PUBLIC, message: forPages(message) })}\n\n`;
1335
+ for (const st of [...this.streams.values()])
1336
+ if (mayRead(st, t))
1337
+ this.push(st, text);
1338
+ }
1339
+ /** Who a message may mention (CollabSpec decision 13): the agents listed with a token in force, by
1340
+ * their tokens, and the people — with a page open, invited by a link, or who wrote in the public
1341
+ * channel lately — by the names they go by. */
1342
+ mentionable() {
1343
+ const agents = new Map();
1344
+ const names = [];
1345
+ for (const r of this.tokens.inForce()) {
1346
+ agents.set(nameKey(r.name), r.id);
1347
+ names.push(r.name);
1348
+ }
1349
+ for (const p of this.presence.list())
1350
+ if (!p.agent && p.name)
1351
+ names.push(p.name);
1352
+ for (const r of this.invites.inForce())
1353
+ names.push(r.name);
1354
+ for (const m of this.talk.thread(PUBLIC))
1355
+ if (m.kind === "person")
1356
+ names.push(m.from);
1357
+ return { names, agents };
1358
+ }
1122
1359
  /** Write to a stream, unless what it has not read yet passed MAX_BUFFERED beyond its hello (`room`):
1123
- * then it is closed instead, and its page reconnects to the present state. A review of 5,000
1124
- * opinions on Sphere-Packing-Lean is 7 MB: counted against MAX_BUFFERED, it closed every page's
1125
- * stream as it opened, and the pages reconnected every two seconds, never live. */
1360
+ * then it is closed instead, and its page reconnects to the present state. A hello counted against
1361
+ * MAX_BUFFERED (in 0.4.3 it carried the whole review, 7 MB for 5,000 opinions on
1362
+ * Sphere-Packing-Lean) closed every page's stream as it opened, and the pages reconnected every two
1363
+ * seconds, never live. */
1126
1364
  push(st, text) {
1127
1365
  const waiting = st.res.writableLength;
1128
1366
  // all that waits was written since the hello: the hello is read
@@ -1189,3 +1427,13 @@ function viewsCarried(views) {
1189
1427
  }
1190
1428
  return { notes, pins, scopes, reviewViews: 0 };
1191
1429
  }
1430
+ /** Whether a page's stream is sent a channel's messages (CollabSpec decision 13): the public channel
1431
+ * (`t` null) where it has a name, a private one where its reader made the agent's token; never a
1432
+ * read-only reader's. */
1433
+ function mayRead(st, t) {
1434
+ if (st.readOnly !== null)
1435
+ return false;
1436
+ if (!t)
1437
+ return st.name !== null || st.person !== null;
1438
+ return madeBy(t, { name: st.name, person: st.person });
1439
+ }