fascicle 0.14.0 → 0.16.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 (67) hide show
  1. package/CHANGELOG.md +150 -0
  2. package/README.md +8 -8
  3. package/dist/acp.d.ts +16 -2
  4. package/dist/acp.js +1406 -1307
  5. package/dist/acp.js.map +1 -1
  6. package/dist/{adapters-DNnzeLxr.js → adapters-CDUzZlby.js} +35 -13
  7. package/dist/adapters-CDUzZlby.js.map +1 -0
  8. package/dist/adapters.d.ts +8 -1
  9. package/dist/adapters.js +1 -1
  10. package/dist/agents.d.ts +1 -1
  11. package/dist/agents.js +15 -8
  12. package/dist/agents.js.map +1 -1
  13. package/dist/bin/fascicle-viewer.js +4 -1
  14. package/dist/console-CdB4pcFO.js +37 -0
  15. package/dist/console-CdB4pcFO.js.map +1 -0
  16. package/dist/{core-CDrz0NM1.js → core-CErsxGF6.js} +246 -147
  17. package/dist/core-CErsxGF6.js.map +1 -0
  18. package/dist/diagram_bin.js +2 -2
  19. package/dist/diagram_bin.js.map +1 -1
  20. package/dist/{engine-BDWB2jdn.js → engine-CR8q2IqV.js} +683 -511
  21. package/dist/engine-CR8q2IqV.js.map +1 -0
  22. package/dist/index.d.ts +529 -73
  23. package/dist/index.js +440 -137
  24. package/dist/index.js.map +1 -1
  25. package/dist/{invoke-tjTjZLHj.js → invoke-COaeZ-vy.js} +98 -26
  26. package/dist/invoke-COaeZ-vy.js.map +1 -0
  27. package/dist/{json_schema_to_standard-r21kW2LI.js → json_schema_to_standard-C4F4lXHE.js} +11 -32
  28. package/dist/json_schema_to_standard-C4F4lXHE.js.map +1 -0
  29. package/dist/{leading_system-BQe_405V.js → leading_system-PoHzNHuV.js} +277 -3
  30. package/dist/leading_system-PoHzNHuV.js.map +1 -0
  31. package/dist/mcp.d.ts +6 -5
  32. package/dist/mcp.js +11 -6
  33. package/dist/mcp.js.map +1 -1
  34. package/dist/otel.js +10 -10
  35. package/dist/otel.js.map +1 -1
  36. package/dist/records-1HU7mWXf.js +22 -0
  37. package/dist/records-1HU7mWXf.js.map +1 -0
  38. package/dist/{search-CqH5hmuF.js → search-CpCJYMUm.js} +73 -10
  39. package/dist/search-CpCJYMUm.js.map +1 -0
  40. package/dist/search_worker.js +1 -1
  41. package/dist/stdio.js +7 -3
  42. package/dist/stdio.js.map +1 -1
  43. package/dist/testing.d.ts +1 -1
  44. package/dist/testing.js +3 -3
  45. package/dist/testing.js.map +1 -1
  46. package/dist/{trajectory-Bm-mOtqw.d.ts → trajectory-BKGNxi7u.d.ts} +10 -9
  47. package/dist/{trajectory-BI-mrVFT.js → trajectory-DeURWIhj.js} +6 -5
  48. package/dist/trajectory-DeURWIhj.js.map +1 -0
  49. package/dist/{types-C_Rmcgck.d.ts → types-Sw0oHW-_.d.ts} +47 -9
  50. package/dist/ui.d.ts +2 -1
  51. package/dist/ui.js +8 -1
  52. package/dist/ui.js.map +1 -1
  53. package/dist/viewer-app/assets/index-BYF5Dp7d.js +2 -0
  54. package/dist/viewer-app/index.html +2 -1
  55. package/dist/viewer.d.ts +26 -12
  56. package/dist/viewer.js +282 -63
  57. package/dist/viewer.js.map +1 -1
  58. package/package.json +4 -4
  59. package/dist/adapters-DNnzeLxr.js.map +0 -1
  60. package/dist/core-CDrz0NM1.js.map +0 -1
  61. package/dist/engine-BDWB2jdn.js.map +0 -1
  62. package/dist/invoke-tjTjZLHj.js.map +0 -1
  63. package/dist/json_schema_to_standard-r21kW2LI.js.map +0 -1
  64. package/dist/leading_system-BQe_405V.js.map +0 -1
  65. package/dist/search-CqH5hmuF.js.map +0 -1
  66. package/dist/trajectory-BI-mrVFT.js.map +0 -1
  67. package/dist/viewer-app/assets/index-Fnh5HKSU.js +0 -2
package/dist/viewer.js CHANGED
@@ -1,11 +1,13 @@
1
- import "./core-CDrz0NM1.js";
2
- import { l as parse_trajectory_event } from "./trajectory-BI-mrVFT.js";
1
+ import "./core-CErsxGF6.js";
2
+ import { l as parse_trajectory_event } from "./trajectory-DeURWIhj.js";
3
3
  import { open, stat } from "node:fs/promises";
4
- import { dirname, extname, resolve, sep } from "node:path";
4
+ import { basename, dirname, extname, resolve, sep } from "node:path";
5
5
  import { createReadStream, existsSync, statSync, watch } from "node:fs";
6
6
  import { spawn } from "node:child_process";
7
+ import { pipeline } from "node:stream";
7
8
  import { fileURLToPath } from "node:url";
8
9
  import { createServer } from "node:http";
10
+ import { isIPv6 } from "node:net";
9
11
  import { parseArgs } from "node:util";
10
12
  //#region src/viewer/broadcast.ts
11
13
  /**
@@ -72,7 +74,12 @@ function create_broadcaster(config) {
72
74
  * on disk. A client folds `/api/trajectory` for the whole run and then follows
73
75
  * `/api/events`, which replays anything past the cursor it names and streams
74
76
  * new events live. The ring is bounded memory by design, so history older than
75
- * it is served from the file the tail already reads (D7).
77
+ * it is served from the file the tail already reads.
78
+ *
79
+ * A server bound to a loopback name answers only requests whose `Host` names
80
+ * loopback too, so a web page can't reach it by rebinding a domain of its own
81
+ * to 127.0.0.1. Ingest is mounted unless the config turns it off, reads only
82
+ * `application/x-ndjson`, and refuses a body past 8 MB.
76
83
  */
77
84
  const SSE_HEARTBEAT_MS = 15e3;
78
85
  const HERE = dirname(fileURLToPath(import.meta.url));
@@ -100,16 +107,37 @@ const CONTENT_TYPES = {
100
107
  };
101
108
  const FALLBACK_CONTENT_TYPE = "application/octet-stream";
102
109
  /**
110
+ * The names that keep the viewer on this machine. A server bound to one of
111
+ * them answers only a request whose `Host` names one of them as well.
112
+ */
113
+ const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
114
+ "localhost",
115
+ "127.0.0.1",
116
+ "::1"
117
+ ]);
118
+ /** The one content type `/api/ingest` reads, which is what `http_logger` sends. */
119
+ const NDJSON = "application/x-ndjson";
120
+ /**
121
+ * The most bytes one ingest body may carry. `http_logger` posts a single
122
+ * event per request, so only a runaway or hostile client comes near it.
123
+ */
124
+ const INGEST_LIMIT_BYTES = 8e6;
125
+ /**
103
126
  * Starts the HTTP server and resolves once it is listening.
104
127
  *
105
- * Wires the four API routes (health, snapshot, SSE, ingest) plus the compiled
106
- * app's static files to a single request handler, and resolves with the bound
107
- * URL and a `close` that shuts the socket down. The API routes are matched
128
+ * Wires the five API routes (health, snapshot, trajectory, SSE, ingest) plus
129
+ * the compiled app's static files to a single request handler, and resolves
130
+ * with the bound URL and port and a `close` that shuts the socket down. The
131
+ * `Host` check runs before anything else, then the API routes are matched
108
132
  * first and exactly, so no file the canvas ships can ever shadow one.
109
133
  */
110
134
  function start_server(config) {
111
- const { broadcaster, host, port, app_dir, trajectory_path, on_parse_error } = config;
135
+ const { broadcaster, host, port, app_dir, trajectory_path, ingest = true, on_parse_error } = config;
112
136
  const handler = (req, res) => {
137
+ if (!host_allowed(host, req.headers.host)) {
138
+ send_forbidden_host(res, host);
139
+ return;
140
+ }
113
141
  const route = resolve_route(req, host, port);
114
142
  if (route === "GET /api/health") {
115
143
  send_json(res, 200, { ok: true });
@@ -127,7 +155,7 @@ function start_server(config) {
127
155
  handle_sse(req, res, broadcaster);
128
156
  return;
129
157
  }
130
- if (route === "POST /api/ingest") {
158
+ if (ingest && route === "POST /api/ingest") {
131
159
  handle_ingest(req, res, broadcaster, on_parse_error);
132
160
  return;
133
161
  }
@@ -142,8 +170,10 @@ function start_server(config) {
142
170
  http_server.once("error", res_err);
143
171
  http_server.listen(port, host, () => {
144
172
  http_server.removeListener("error", res_err);
173
+ const bound_port = bound_port_of(http_server.address(), port);
145
174
  res_ok({
146
- url: `http://${host}:${bound_port_of(http_server.address(), port)}`,
175
+ url: `http://${format_authority(host, bound_port)}`,
176
+ port: bound_port,
147
177
  close: () => close_server(http_server)
148
178
  });
149
179
  });
@@ -161,6 +191,57 @@ function bound_port_of(addr, fallback) {
161
191
  return addr !== null && typeof addr === "object" && "port" in addr ? addr.port : fallback;
162
192
  }
163
193
  /**
194
+ * Joins a host and port into a URL authority, bracketing an IPv6 literal.
195
+ *
196
+ * `http://::1:4242` is not a URL; `http://[::1]:4242` is. A hostname or IPv4
197
+ * address passes through untouched.
198
+ */
199
+ function format_authority(host, port) {
200
+ return `${isIPv6(host) ? `[${host}]` : host}:${port}`;
201
+ }
202
+ /**
203
+ * Whether `host` is a loopback name, which keeps a server bound to it on this
204
+ * machine.
205
+ */
206
+ function is_loopback_host(host) {
207
+ return LOOPBACK_HOSTS.has(host);
208
+ }
209
+ /**
210
+ * The hostname a `Host` header names, lowercased, with an IPv6 literal's
211
+ * brackets and any port taken off.
212
+ */
213
+ function host_name(header) {
214
+ const host = header.toLowerCase();
215
+ if (host.startsWith("[")) return host.slice(1, host.indexOf("]"));
216
+ const colon = host.indexOf(":");
217
+ return colon === -1 ? host : host.slice(0, colon);
218
+ }
219
+ /**
220
+ * Whether a server bound to `bound` answers a request whose `Host` header is
221
+ * `header`.
222
+ *
223
+ * Bound to a loopback name, it answers only a `Host` that names loopback too,
224
+ * whatever the port, because a page that rebinds a domain of its own to
225
+ * 127.0.0.1 still sends that domain, and would otherwise read every prompt and
226
+ * output in the trajectory. A request with no `Host` is refused as well. Bound
227
+ * anywhere else, it checks nothing: whoever can reach it can read it, which
228
+ * is what the CLI warns about before it binds.
229
+ */
230
+ function host_allowed(bound, header) {
231
+ if (!is_loopback_host(bound)) return true;
232
+ return header !== void 0 && is_loopback_host(host_name(header));
233
+ }
234
+ /**
235
+ * Writes the 403 for a request whose `Host` a loopback-bound server won't
236
+ * answer, naming the names it will.
237
+ */
238
+ function send_forbidden_host(res, bound) {
239
+ send_json(res, 403, {
240
+ error: "forbidden_host",
241
+ message: `this viewer is bound to ${bound} and answers only a Host of localhost, 127.0.0.1, or ::1; open it by one of those names`
242
+ });
243
+ }
244
+ /**
164
245
  * Builds a `"METHOD /path"` route key from a request.
165
246
  *
166
247
  * Resolves the path against the client's `Host` header when it parses, and
@@ -177,7 +258,7 @@ function resolve_route(req, host, port) {
177
258
  if (header !== void 0) try {
178
259
  return `${method} ${new URL(path, `http://${header}`).pathname}`;
179
260
  } catch {}
180
- return `${method} ${new URL(path, `http://${host}:${port}`).pathname}`;
261
+ return `${method} ${new URL(path, `http://${format_authority(host, port)}`).pathname}`;
181
262
  }
182
263
  /**
183
264
  * Closes the HTTP server and resolves once every connection is torn down.
@@ -211,7 +292,7 @@ function send_not_found(res, route) {
211
292
  /**
212
293
  * Handles `GET /api/trajectory` by streaming the whole run history as NDJSON,
213
294
  * one event per line, so the client folds the full run before it follows the
214
- * live tail (D7).
295
+ * live tail.
215
296
  *
216
297
  * The tailed file is the source of truth: its bytes stream straight through,
217
298
  * which keeps memory bounded no matter how long the run grew, and a finished
@@ -230,7 +311,7 @@ function serve_trajectory(res, broadcaster, trajectory_path) {
230
311
  res.setHeader(CURSOR_HEADER, String(ring.at(-1)?.id ?? 0));
231
312
  if (trajectory_path !== void 0) {
232
313
  if (stat_file(trajectory_path) !== null) {
233
- createReadStream(trajectory_path).pipe(res);
314
+ stream_file(res, trajectory_path);
234
315
  return;
235
316
  }
236
317
  }
@@ -311,7 +392,20 @@ function serve_app_asset(res, route, override) {
311
392
  res.setHeader("content-type", CONTENT_TYPES[extname(file)] ?? FALLBACK_CONTENT_TYPE);
312
393
  res.setHeader("cache-control", "no-store");
313
394
  res.setHeader("content-length", String(stats.size));
314
- createReadStream(file).pipe(res);
395
+ stream_file(res, file);
396
+ }
397
+ /**
398
+ * Streams a file as the response body, dropping the connection if the read
399
+ * fails.
400
+ *
401
+ * A file can pass `stat_file` and still refuse to open (mode 000 answers
402
+ * EACCES), and a bare `pipe` leaves that stream error unhandled, which ends the
403
+ * process. `pipeline` handles it by destroying both ends, so the client sees a
404
+ * dropped connection and the server keeps serving. It also closes the file when
405
+ * a client leaves mid-stream.
406
+ */
407
+ function stream_file(res, path) {
408
+ pipeline(createReadStream(path), res, () => {});
315
409
  }
316
410
  /**
317
411
  * Handles `GET /api/events` by turning the connection into an SSE stream.
@@ -383,15 +477,62 @@ function write_event(res, id, event) {
383
477
  res.write(`id: ${id}\nevent: trajectory\ndata: ${JSON.stringify(event)}\n\n`);
384
478
  }
385
479
  /**
480
+ * Whether a `content-type` header names NDJSON, whatever its case and its
481
+ * parameters, so `application/x-ndjson; charset=utf-8` counts.
482
+ */
483
+ function is_ndjson(header) {
484
+ if (header === void 0) return false;
485
+ const semicolon = header.indexOf(";");
486
+ return (semicolon === -1 ? header : header.slice(0, semicolon)).trim().toLowerCase() === NDJSON;
487
+ }
488
+ /**
489
+ * Writes the 413 for an ingest body past the limit, closing the connection so
490
+ * the rest of the body is never read.
491
+ */
492
+ function send_too_large(res) {
493
+ res.setHeader("connection", "close");
494
+ send_json(res, 413, {
495
+ error: "payload_too_large",
496
+ message: `an ingest body holds at most ${INGEST_LIMIT_BYTES} bytes; post the events in smaller batches`
497
+ });
498
+ }
499
+ /**
500
+ * Answers an ingest request that won't be read, before any of its body is:
501
+ * a 415 for a body that isn't NDJSON, and a 413 for one whose declared length
502
+ * runs past the limit. Returns whether it answered.
503
+ *
504
+ * Requiring the content type is what keeps a web page out: a page can post a
505
+ * `text/plain` body to any origin without a preflight, but not an NDJSON one.
506
+ */
507
+ function refuse_ingest(req, res) {
508
+ if (!is_ndjson(req.headers["content-type"])) {
509
+ send_json(res, 415, {
510
+ error: "unsupported_media_type",
511
+ message: `post trajectory events as ${NDJSON}, one JSON event to a line`
512
+ });
513
+ return true;
514
+ }
515
+ if (Number(req.headers["content-length"]) > INGEST_LIMIT_BYTES) {
516
+ send_too_large(res);
517
+ return true;
518
+ }
519
+ return false;
520
+ }
521
+ /**
386
522
  * Handles `POST /api/ingest`: parses newline-delimited trajectory events
387
523
  * from the request body and feeds valid ones into the broadcaster.
388
524
  *
389
525
  * Reports how many lines were accepted vs rejected in the response body;
390
526
  * a malformed line is skipped and reported via `on_parse_error`, not
391
- * treated as a fatal request error.
527
+ * treated as a fatal request error. A body sent without a length is counted
528
+ * as it streams, and one that runs past the limit gets its 413 there, after
529
+ * the lines before that point have gone out. Once a request is answered,
530
+ * nothing more it sends is read or reported.
392
531
  */
393
532
  function handle_ingest(req, res, broadcaster, on_parse_error) {
533
+ if (refuse_ingest(req, res)) return;
394
534
  let buf = "";
535
+ let received = 0;
395
536
  let accepted = 0;
396
537
  let rejected = 0;
397
538
  const consume_line = (line) => {
@@ -415,6 +556,12 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
415
556
  };
416
557
  req.setEncoding("utf8");
417
558
  req.on("data", (chunk) => {
559
+ if (res.writableEnded) return;
560
+ received += Buffer.byteLength(chunk);
561
+ if (received > INGEST_LIMIT_BYTES) {
562
+ send_too_large(res);
563
+ return;
564
+ }
418
565
  buf += chunk;
419
566
  let nl = buf.indexOf("\n");
420
567
  while (nl !== -1) {
@@ -424,6 +571,7 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
424
571
  }
425
572
  });
426
573
  req.on("end", () => {
574
+ if (res.writableEnded) return;
427
575
  if (buf.length > 0) consume_line(buf);
428
576
  send_json(res, 200, {
429
577
  accepted,
@@ -431,6 +579,7 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
431
579
  });
432
580
  });
433
581
  req.on("error", (err) => {
582
+ if (res.writableEnded) return;
434
583
  if (on_parse_error) on_parse_error(err, "");
435
584
  send_json(res, 400, { error: "bad_request" });
436
585
  });
@@ -440,41 +589,70 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
440
589
  /**
441
590
  * JSONL file tailer.
442
591
  *
443
- * Watches a file for appends and emits one parsed trajectory event per
444
- * complete line. Handles three pathological cases:
592
+ * Follows a path for appends and emits one parsed trajectory event per
593
+ * complete line. Handles these pathological cases:
445
594
  *
446
- * - Truncation / rotation: a watcher event whose stat is shorter than the
447
- * current offset means the file shrunk. Reset offset to 0 and re-stream.
595
+ * - A file that doesn't exist yet: a missing file is a wait, not an
596
+ * error. The tail reads it from its first line once it appears.
597
+ * - Rotation: a file renamed away and recreated under the same name is a
598
+ * new inode, so the tail starts the new file from its first line rather
599
+ * than at the old file's offset.
600
+ * - Truncation: a stat shorter than the current offset means the file
601
+ * shrank in place. Reset offset to 0 and re-stream.
448
602
  * - Partial last line: if the trailing chunk has no `\n`, buffer it and
449
603
  * wait. Never parse a half-written line.
450
604
  * - Schema failures: a line that fails `parse_trajectory_event` is
451
605
  * dropped and surfaced to `on_parse_error`. The stream keeps going.
452
606
  *
453
- * The watcher is fs.watch-based; reads are serialized and change events
454
- * that arrive mid-read are coalesced into one extra pass rather than
455
- * dropped, so a burst of appends never starts overlapping reads. Each pass
456
- * re-stats and re-reads from the saved offset, which also covers platforms
457
- * where fs.watch misses some append notifications: the next successful
458
- * change event catches the file up regardless.
607
+ * Two fs.watch watchers drive the reads. A watch on the file itself carries
608
+ * every append, but it follows the file's inode, so it can't see a file
609
+ * appear and after a rename it reports on the old one. So while the file is
610
+ * missing, and from the moment that watch reports a rename, a second watch
611
+ * on the parent directory waits for the file's name, and the first pass that
612
+ * finds a file there moves the file watch onto it and drops the directory
613
+ * watch. Appends never ride the directory watch, because macOS serves a
614
+ * directory through FSEvents, whose stream starts asynchronously and drops
615
+ * what happens before it is live, while a file watch is kqueue's and holds
616
+ * from the moment it is made. Reads are serialized, and change events that arrive mid-read are coalesced
617
+ * into one extra pass rather than dropped, so a burst of appends never starts
618
+ * overlapping reads. Each pass re-stats and re-reads from the saved offset,
619
+ * which also covers platforms where fs.watch misses some append
620
+ * notifications: the next successful change event catches the file up
621
+ * regardless.
459
622
  */
460
623
  /**
624
+ * True for the error a stat or an open throws when nothing is at the path,
625
+ * which the tail reads as waiting for the file rather than as a failure.
626
+ */
627
+ function is_missing(err) {
628
+ return Reflect.get(Object(err), "code") === "ENOENT";
629
+ }
630
+ /**
461
631
  * Starts tailing `path` and returns a handle to stop or drain it.
462
632
  *
463
633
  * Watches the file with `fs.watch` and re-reads from the last known offset
464
634
  * on every change, buffering an incomplete trailing line until the rest
465
- * arrives. Overlapping change events are coalesced: a read already in
466
- * flight absorbs any events that fire while it runs instead of starting a
467
- * second concurrent read.
635
+ * arrives. A missing file is waited for through a watch on its directory,
636
+ * and a new file at the path (a different inode) is read from its first
637
+ * line. Overlapping change events are coalesced: a read already in flight
638
+ * absorbs any events that fire while it runs instead of starting a second
639
+ * concurrent read.
468
640
  */
469
641
  function start_tail(config) {
470
642
  const { path, on_event, on_parse_error, on_io_error } = config;
643
+ const name = basename(path);
644
+ let inode = null;
471
645
  let offset = 0;
472
646
  let buffer = "";
473
647
  let busy = false;
474
648
  let pending = false;
475
649
  let closed = false;
476
- let watcher = null;
650
+ let file_watcher = null;
651
+ let dir_watcher = null;
477
652
  let last_drain = Promise.resolve();
653
+ const report = (err) => {
654
+ if (on_io_error && !is_missing(err)) on_io_error(err);
655
+ };
478
656
  const handle_line = (line) => {
479
657
  if (line.length === 0) return;
480
658
  let parsed;
@@ -491,30 +669,70 @@ function start_tail(config) {
491
669
  }
492
670
  on_event(result.data);
493
671
  };
494
- const read_more = async () => {
672
+ const watch$1 = (target, listener) => {
673
+ if (closed) return null;
674
+ try {
675
+ return watch(target, { persistent: true }, listener);
676
+ } catch (err) {
677
+ if (on_io_error) on_io_error(err);
678
+ return null;
679
+ }
680
+ };
681
+ const await_file = () => {
682
+ if (dir_watcher !== null) return;
683
+ dir_watcher = watch$1(dirname(path), (_event, filename) => {
684
+ if (filename === null || filename === name) schedule();
685
+ });
686
+ if (dir_watcher !== null) schedule();
687
+ };
688
+ const adopt = (ino) => {
689
+ inode = ino;
690
+ offset = 0;
691
+ buffer = "";
692
+ file_watcher?.close();
693
+ file_watcher = watch$1(path, (event) => {
694
+ if (event === "rename") await_file();
695
+ schedule();
696
+ });
697
+ dir_watcher?.close();
698
+ dir_watcher = null;
699
+ };
700
+ const locate = async () => {
495
701
  let st;
496
702
  try {
497
703
  st = await stat(path);
498
704
  } catch (err) {
499
- if (on_io_error) on_io_error(err);
500
- return;
705
+ if (is_missing(err)) {
706
+ inode = null;
707
+ await_file();
708
+ }
709
+ report(err);
710
+ return null;
501
711
  }
502
- if (st.size < offset) {
712
+ if (st.ino !== inode) adopt(st.ino);
713
+ else if (st.size < offset) {
503
714
  offset = 0;
504
715
  buffer = "";
505
716
  }
506
- if (st.size === offset) return;
717
+ return st.size;
718
+ };
719
+ const read_more = async () => {
720
+ const size = await locate();
721
+ if (size === null || size === offset) return;
507
722
  const fh = await open(path, "r").catch((err) => {
508
- if (on_io_error) on_io_error(err);
723
+ report(err);
509
724
  return null;
510
725
  });
511
726
  if (!fh) return;
512
727
  try {
513
- const length = st.size - offset;
728
+ const length = size - offset;
514
729
  const buf = Buffer.alloc(length);
515
730
  const { bytesRead } = await fh.read(buf, 0, length, offset);
516
731
  offset += bytesRead;
517
732
  buffer += buf.subarray(0, bytesRead).toString("utf8");
733
+ } catch (err) {
734
+ report(err);
735
+ return;
518
736
  } finally {
519
737
  await fh.close();
520
738
  }
@@ -547,19 +765,12 @@ function start_tail(config) {
547
765
  })();
548
766
  };
549
767
  schedule();
550
- try {
551
- watcher = watch(path, { persistent: true }, () => {
552
- schedule();
553
- });
554
- } catch (err) {
555
- if (on_io_error) on_io_error(err);
556
- }
557
768
  const stop = () => {
558
769
  closed = true;
559
- if (watcher) {
560
- watcher.close();
561
- watcher = null;
562
- }
770
+ file_watcher?.close();
771
+ file_watcher = null;
772
+ dir_watcher?.close();
773
+ dir_watcher = null;
563
774
  };
564
775
  const drain = async () => {
565
776
  schedule();
@@ -583,8 +794,9 @@ function start_tail(config) {
583
794
  * Starts the viewer: brings up the HTTP/SSE server and, if `options.path`
584
795
  * is set, a file tail that feeds the same broadcaster.
585
796
  *
586
- * Defaults to `127.0.0.1:4242` with a 1000-event ring buffer. HTTP ingest
587
- * and SSE are always available; tailing is opt-in via `path`.
797
+ * Defaults to `127.0.0.1:4242` with a 1000-event ring buffer. SSE is always
798
+ * available, HTTP ingest is on unless `ingest` is false, and tailing is opt-in
799
+ * via `path`.
588
800
  */
589
801
  async function start_viewer(options = {}) {
590
802
  const host = options.host ?? "127.0.0.1";
@@ -597,6 +809,7 @@ async function start_viewer(options = {}) {
597
809
  broadcaster,
598
810
  host,
599
811
  port,
812
+ ingest: options.ingest,
600
813
  ...options.path !== void 0 ? { trajectory_path: options.path } : {},
601
814
  ...options.on_parse_error ? { on_parse_error: options.on_parse_error } : {}
602
815
  });
@@ -615,15 +828,15 @@ async function start_viewer(options = {}) {
615
828
  * Combines the server and optional tail into a single `ViewerHandle`.
616
829
  *
617
830
  * `close` stops the tail first, then closes the server, mirroring the
618
- * startup order (server first, tail second) in reverse. The port is read
619
- * back from `server.url` rather than the requested `port` option, since
831
+ * startup order (server first, tail second) in reverse. The port is the one
832
+ * the server reports binding rather than the requested `port` option, since
620
833
  * a caller that passes `0` gets whatever port the OS actually bound.
621
834
  */
622
835
  function wrap_handle(server, tail, host) {
623
836
  return {
624
837
  url: server.url,
625
838
  host,
626
- port: Number(new URL(server.url).port),
839
+ port: server.port,
627
840
  close: async () => {
628
841
  if (tail) tail.stop();
629
842
  await server.close();
@@ -641,9 +854,13 @@ function wrap_handle(server, tail, host) {
641
854
  *
642
855
  * Flags: --port <n> --host <h> --buffer <n> --no-open --help
643
856
  *
857
+ * `POST /api/ingest` is mounted only under `--listen`, so a viewer that only
858
+ * tails a file takes no posts from anything.
859
+ *
644
860
  * Defaults bind 127.0.0.1:4242 and open the user's default browser. SIGINT
645
861
  * shuts everything down cleanly. The CLI body is exposed as `run_viewer_cli`
646
- * so the umbrella's bin shim can drive it from a bundled `dist/index.js`.
862
+ * so the `fascicle-viewer` bin shim can drive it from the bundled
863
+ * `dist/viewer.js`.
647
864
  */
648
865
  const HELP = `\
649
866
  fascicle-viewer — minimal in-repo dashboard for fascicle trajectory streams.
@@ -654,8 +871,9 @@ Usage:
654
871
  fascicle-viewer <path> --listen both producers feed the same broadcaster
655
872
 
656
873
  Options:
874
+ --listen accept HTTP push on /api/ingest (off unless set)
657
875
  --port <n> port (default 4242)
658
- --host <h> bind host (default 127.0.0.1; --host 0.0.0.0 warns)
876
+ --host <h> bind host (default 127.0.0.1; a non-loopback host warns)
659
877
  --buffer <n> ring-buffer size (default 1000)
660
878
  --no-open do not open the browser
661
879
  --help show this message
@@ -705,8 +923,8 @@ function parse(argv) {
705
923
  process.stdout.write(HELP);
706
924
  process.exit(0);
707
925
  }
708
- const port_raw = values.port ?? "4242";
709
- const buffer_raw = values.buffer ?? "1000";
926
+ const port_raw = values.port;
927
+ const buffer_raw = values.buffer;
710
928
  const port = Number.parseInt(port_raw, 10);
711
929
  const buffer = Number.parseInt(buffer_raw, 10);
712
930
  if (!Number.isFinite(port) || port <= 0) {
@@ -718,7 +936,7 @@ function parse(argv) {
718
936
  process.exit(2);
719
937
  }
720
938
  const path = positionals[0];
721
- const listen = values.listen ?? false;
939
+ const listen = values.listen;
722
940
  if (path === void 0 && !listen) {
723
941
  process.stderr.write("fascicle-viewer: a <path> is required unless --listen is set\n");
724
942
  process.stderr.write(HELP);
@@ -726,11 +944,11 @@ function parse(argv) {
726
944
  }
727
945
  return {
728
946
  ...path !== void 0 ? { path } : {},
729
- host: values.host ?? "127.0.0.1",
947
+ host: values.host,
730
948
  port,
731
949
  buffer,
732
950
  listen,
733
- open: !values["no-open"] && (values.open ?? true)
951
+ open: !values["no-open"] && values.open
734
952
  };
735
953
  }
736
954
  /**
@@ -761,19 +979,20 @@ function open_browser(url) {
761
979
  * CLI entry point: parses argv, starts the viewer, and wires shutdown.
762
980
  *
763
981
  * Warns but proceeds when the tailed path does not exist yet or when the
764
- * bind host is 0.0.0.0 (the dashboard has no auth). Optionally opens the
982
+ * bind host is not loopback (the dashboard has no auth). Optionally opens the
765
983
  * browser, then installs SIGINT/SIGTERM handlers that close the viewer
766
984
  * before exiting.
767
985
  */
768
986
  async function run_viewer_cli(argv) {
769
987
  const args = parse(argv);
770
- if (args.path !== void 0 && !existsSync(args.path)) process.stderr.write(`fascicle-viewer: warning: ${args.path} does not exist yet — will pick up events once it is created\n`);
771
- if (args.host === "0.0.0.0") process.stderr.write("fascicle-viewer: warning: binding 0.0.0.0 — this dashboard has no auth and exposes whatever is in your trajectory stream\n");
988
+ if (args.path !== void 0 && !existsSync(args.path)) process.stderr.write(`fascicle-viewer: warning: ${args.path} does not exist yet, so the viewer will read it from its first line once it is created\n`);
989
+ if (!is_loopback_host(args.host)) process.stderr.write(`fascicle-viewer: warning: binding ${args.host} reaches beyond this machine, and the dashboard has no auth, so anyone who can reach it reads your trajectory stream; pass --host 127.0.0.1 to keep it local\n`);
772
990
  const handle = await start_viewer({
773
991
  ...args.path !== void 0 ? { path: args.path } : {},
774
992
  host: args.host,
775
993
  port: args.port,
776
994
  buffer: args.buffer,
995
+ ingest: args.listen,
777
996
  on_parse_error: (err, line) => {
778
997
  const preview = line.length > 120 ? `${line.slice(0, 120)}…` : line;
779
998
  process.stderr.write(`fascicle-viewer: skipped malformed line: ${preview}\n ${describe_error(err)}\n`);
@@ -783,7 +1002,7 @@ async function run_viewer_cli(argv) {
783
1002
  }
784
1003
  });
785
1004
  if (args.path !== void 0) process.stderr.write(`fascicle-viewer: watching ${args.path}\n`);
786
- if (args.listen || args.path === void 0) process.stderr.write(`fascicle-viewer: listening for HTTP push on ${handle.url}/api/ingest\n`);
1005
+ if (args.listen) process.stderr.write(`fascicle-viewer: listening for HTTP push on ${handle.url}/api/ingest\n`);
787
1006
  process.stderr.write(`fascicle-viewer: viewer at ${handle.url}\n`);
788
1007
  if (args.open) open_browser(handle.url);
789
1008
  const shutdown = async () => {