@jjanczur/tyran 0.1.31 → 0.1.33

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.
package/scripts/board.mjs CHANGED
@@ -21,11 +21,12 @@
21
21
  *
22
22
  * CLI:
23
23
  * node board.mjs [--dir <.tyran>] [--check]
24
- * [--serve [--port <n>] [--write] [--transcripts <dir>]...]
24
+ * [--serve [--port <n>] [--write] [--open] [--transcripts <dir>]...]
25
25
  * Exit: 0 ok · 1 drift (--check) · 2 usage/IO
26
26
  */
27
27
  import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
28
28
  import { createServer } from 'node:http';
29
+ import { spawn as spawnProcess } from 'node:child_process';
29
30
  import { basename, join, resolve } from 'node:path';
30
31
  import { realpathSync } from 'node:fs';
31
32
  import { fileURLToPath } from 'node:url';
@@ -44,7 +45,7 @@ import {
44
45
  } from './project.mjs';
45
46
  import { jsonEscapeInvisible } from './invisible.mjs';
46
47
  import { renderBoardError, renderBoardHtml } from './board-html.mjs';
47
- import { COST_SCHEMA, costJson, costReport } from './cost.mjs';
48
+ import { COST_SCHEMA, WINDOWS, costJson, costReport } from './cost.mjs';
48
49
  import { SettingsError, applyPolicyClass, applySetting, readSettings } from './settings.mjs';
49
50
  import { checkStopAt } from './stop-check.mjs';
50
51
  import { runState } from './overnight.mjs';
@@ -52,6 +53,42 @@ import { answerOne, answerProblem, classify, openAsks, partitionAsks, reRender,
52
53
 
53
54
  export const BOARD_HTML_FILE = 'board.html';
54
55
 
56
+ /**
57
+ * Open the served board in the operator's browser.
58
+ *
59
+ * The board was a URL printed to a terminal that nothing ever opened, and for
60
+ * the people this matters most to that is several steps — keep this window
61
+ * running, now type that address somewhere else — each one a place to stop.
62
+ * The dashboard is where Tyran becomes legible, and it was the one thing
63
+ * installation never actually reached.
64
+ *
65
+ * Best-effort and never fatal: a failure here leaves the server running and
66
+ * the URL printed, which is exactly where things were before. Headless
67
+ * machines, SSH sessions and locked-down desktops all land in that branch and
68
+ * none of them is an error worth taking a working server down for.
69
+ *
70
+ * The argument vector is fixed and the URL is the only variable — it is built
71
+ * from a port this process is already listening on, never from user text —
72
+ * and `shell: false` (the default) means nothing here reaches a shell.
73
+ */
74
+ export function openInBrowser(url, { platform = process.platform, spawn = spawnProcess } = {}) {
75
+ const [command, args] =
76
+ platform === 'darwin' ? ['open', [url]]
77
+ : platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
78
+ : ['xdg-open', [url]];
79
+ try {
80
+ const child = spawn(command, args, { stdio: 'ignore', detached: true });
81
+ // A missing `open`/`xdg-open` arrives as an async error event, not a
82
+ // throw, so the catch below would never see it — and an unhandled one
83
+ // would take the server down, which is the opposite of best-effort.
84
+ child.on?.('error', () => { /* no browser here; the printed URL still works */ });
85
+ child.unref?.();
86
+ return true;
87
+ } catch {
88
+ return false;
89
+ }
90
+ }
91
+
55
92
  /** Same ceiling as the evidence gate's journal locator — a deliberate
56
93
  * duplicate: scripts must not import from hook files (direction is
57
94
  * hooks -> scripts), and the constant is one number with one meaning. */
@@ -197,6 +234,7 @@ export const MAX_LOGGED_ERRORS = 20;
197
234
 
198
235
  export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
199
236
  const asks = [];
237
+ const summaries = [];
200
238
  const agents = [];
201
239
  const paused = [];
202
240
  const logged = [];
@@ -209,6 +247,39 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
209
247
  for (const { name, state, board, files: docs } of initiatives) {
210
248
  merged += state.merged;
211
249
  tickets += state.ticketList.length;
250
+ // Per-initiative, because one blended percentage over every initiative is
251
+ // not a fact about any of them: an operator reading "50%" across four
252
+ // slugs cannot tell which is nearly done from which has not started.
253
+ //
254
+ // The TITLE is the point of the row. `init.created` has carried a written
255
+ // sentence all along — "Settings on the board: edit config and the
256
+ // autonomy policy from the page" — and the board showed the directory
257
+ // slug. `waiting` and `last_ts` are here rather than a computed idle time
258
+ // because this payload is byte-compared under `--check` and reads no
259
+ // clock; the page ages them, exactly as it already ages agents.
260
+ summaries.push({
261
+ name,
262
+ title: typeof state.created?.data?.title === 'string' ? state.created.data.title : null,
263
+ tickets: state.ticketList.length,
264
+ merged: state.merged,
265
+ percent: state.percent,
266
+ waiting: board.asks.length,
267
+ // A COUNT, and deliberately not the findings themselves. Measured across
268
+ // 63 distinct real journals: 3 carry any finding at all, 49 in total,
269
+ // and NOT ONE names a ticket — so they cannot enrich a card, which is
270
+ // where a richer board would have put them. Their median claim is 429
271
+ // characters, a paragraph rather than a label, and STATE.md already
272
+ // renders the full seven-column table.
273
+ //
274
+ // So this is a pointer, not a copy: the research exists and the reader
275
+ // is told where. Duplicating the prose here would be ADR-21's defect
276
+ // and would cost ~600 B per finding in a byte-compared payload.
277
+ // Guarded: `crossBoard` is exported and takes any folded state, and a
278
+ // caller assembling one by hand need not have every collection. A
279
+ // missing array must read as "none", never take the board down.
280
+ findings: (state.findings ?? []).length,
281
+ last_ts: state.lastTs,
282
+ });
212
283
  if (state.lastTs !== null && (asOf === null || state.lastTs > asOf)) asOf = state.lastTs;
213
284
  for (const a of board.asks) asks.push({ ...a, init: name });
214
285
  for (const a of board.agents) agents.push({ ...a, init: name });
@@ -292,6 +363,10 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
292
363
  stop: stop === null ? null : { stopped: stop.stopped, reason: stop.reason },
293
364
  paused,
294
365
  asks,
366
+ // Ordered by directory name, like everything else here, so two renders of
367
+ // one journal set are byte-identical. `totals.percent` blends these; the
368
+ // rows are what let a reader see WHICH initiative it blends.
369
+ initiatives: summaries,
295
370
  agents,
296
371
  files,
297
372
  lanes,
@@ -570,14 +645,14 @@ function handleSettingsWrite(dir, route, body) {
570
645
 
571
646
  // ------------------------------------------------------------------- CLI
572
647
 
573
- const BOOLEAN_FLAGS = ['check', 'serve', 'write'];
648
+ const BOOLEAN_FLAGS = ['check', 'serve', 'write', 'open'];
574
649
  const VALUE_FLAGS = ['dir', 'port'];
575
650
  // Repeatable, unlike VALUE_FLAGS: sources are the union over every directory
576
651
  // given, exactly like cost.mjs's own `--transcripts`.
577
652
  const REPEATABLE_FLAGS = ['transcripts'];
578
653
 
579
654
  function parseArgs(argv) {
580
- const flags = { dir: '.tyran', port: 4173, check: false, serve: false, write: false, transcripts: [] };
655
+ const flags = { dir: '.tyran', port: 4173, check: false, serve: false, write: false, open: false, transcripts: [] };
581
656
  for (let i = 0; i < argv.length; i += 1) {
582
657
  const arg = argv[i];
583
658
  if (!arg.startsWith('--')) throw new UsageError(`unexpected argument "${arg}"`);
@@ -618,6 +693,13 @@ function main() {
618
693
  console.error('board: --write only means anything with --serve (it is what the served page may edit)');
619
694
  process.exit(2);
620
695
  }
696
+ if (flags.open && !flags.serve) {
697
+ // Same refusal as --write and --transcripts, for the same reason: there is
698
+ // no URL to open without a server, and a flag that silently does nothing
699
+ // reads as configuration.
700
+ console.error('board: --open only means anything with --serve (there is no URL to open without it)');
701
+ process.exit(2);
702
+ }
621
703
  if (flags.transcripts.length > 0 && !flags.serve) {
622
704
  console.error(
623
705
  'board: --transcripts only means anything with --serve (it is what /cost.json reads instead of ' +
@@ -743,14 +825,20 @@ function main() {
743
825
  // journal disagree and break the byte-exact `--check` contract. The
744
826
  // page fetches this route and simply omits the section when the fetch
745
827
  // fails, which is what happens over file://.
746
- if (req.url === '/cost.json') {
828
+ if (req.url === '/cost.json' || req.url.startsWith('/cost.json?')) {
747
829
  let body;
748
830
  try {
831
+ // The window is the ONLY query parameter, and it is validated
832
+ // against a closed list rather than passed through — an unknown
833
+ // value falls back to `all` instead of reaching the report, so a
834
+ // hand-typed URL cannot produce a window nobody defined.
835
+ const asked = new URLSearchParams(req.url.slice(req.url.indexOf('?') + 1)).get('window');
836
+ const window = WINDOWS.includes(asked) ? asked : 'all';
749
837
  // `flags.transcripts` is [] unless the operator started this
750
838
  // server with `--transcripts`; costReport falls through to
751
839
  // `spend.transcript_dirs` and then the derived directory on its
752
840
  // own, so an empty array here changes nothing for the common case.
753
- body = costJson(costReport({ tyranDir: dir, transcriptDirs: flags.transcripts }));
841
+ body = costJson(costReport({ tyranDir: dir, transcriptDirs: flags.transcripts, window }));
754
842
  } catch (err) {
755
843
  // A cost failure must never take the board down with it: the
756
844
  // board answers "what is going on", and that answer does not
@@ -796,10 +884,12 @@ function main() {
796
884
  process.exitCode = 2;
797
885
  });
798
886
  server.listen(flags.port, '127.0.0.1', () => {
887
+ const url = `http://127.0.0.1:${flags.port}/`;
799
888
  console.log(
800
- `board: serving http://127.0.0.1:${flags.port}/ ` +
889
+ `board: serving ${url} ` +
801
890
  `(${flags.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'}; Ctrl-C to stop)`,
802
891
  );
892
+ if (flags.open) openInBrowser(url);
803
893
  });
804
894
  return;
805
895
  }