@jjanczur/tyran 0.1.40 → 0.1.42

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.
@@ -134,6 +134,22 @@ h3{font-family:var(--font);color:var(--heading);font-size:.85rem;margin:1.1rem 0
134
134
  .file{display:flex;gap:.5rem;align-items:baseline;flex-wrap:wrap;font-size:.76rem}
135
135
  .file .fname{color:var(--steel-bright);font-family:var(--mono);font-weight:600;min-width:6rem}
136
136
  .file code{color:var(--muted);font-size:.72rem;word-break:break-all}
137
+ /* On an initiative the name is a button that opens the file; on a ticket it is
138
+ still a plain span. Underlined rather than boxed: it sits in a list of paths
139
+ and a row of buttons there would read as a toolbar. */
140
+ .file button.fname{background:transparent;border:0;padding:0;font-size:inherit;cursor:pointer;
141
+ text-align:left;text-decoration:underline;text-underline-offset:.18em}
142
+ .file button.fname:hover{color:var(--brass-bright)}
143
+ .file button.fname:focus-visible{outline:2px solid var(--steel);outline-offset:2px}
144
+ .docview{margin-top:.5rem}
145
+ .dochead{display:flex;gap:.6rem;align-items:baseline;flex-wrap:wrap;margin-bottom:.3rem}
146
+ /* The document, as TEXT. It is agent-written markdown rendered by nothing —
147
+ pre-wrap so a long line folds instead of pushing the page sideways, and a
148
+ ceiling so a 2000-line NOTES.md scrolls inside the panel rather than
149
+ burying the board under it. */
150
+ pre.doc{background:var(--bg-sunken);border:1px solid var(--hairline);border-radius:.45rem;
151
+ padding:.7rem .85rem;font-family:var(--mono);font-size:.74rem;line-height:1.5;color:var(--text);
152
+ white-space:pre-wrap;word-break:break-word;max-height:32rem;overflow:auto;margin:0}
137
153
 
138
154
  /* ---- what actually ran on a ticket ---- */
139
155
  .runs{width:100%;border-collapse:collapse;margin-top:.3rem;font-size:.74rem;display:block;overflow-x:auto}
@@ -184,6 +200,20 @@ h3{font-family:var(--font);color:var(--heading);font-size:.85rem;margin:1.1rem 0
184
200
  .reply textarea:disabled{opacity:.55;cursor:not-allowed}
185
201
  .reply .acts{display:flex;flex-wrap:wrap;gap:.4rem;align-items:center;margin-top:.4rem}
186
202
  .reply .hint{font-size:.75rem;color:var(--muted);margin-top:.3rem}
203
+ /* Folded shut on a board that can answer in the page, opened by the settings
204
+ fetch on one that cannot. The summary is a sentence, not a chevron with a
205
+ noun: what is behind it is a route, not a section. */
206
+ .howbox{margin:.3rem 0 .8rem}
207
+ .howbox>summary{cursor:pointer;font-size:.76rem;color:var(--muted);list-style:none;padding:.2rem 0}
208
+ .howbox>summary::-webkit-details-marker{display:none}
209
+ /* The marker is written as a CHARACTER, not a CSS escape: this whole
210
+ stylesheet lives inside a template literal, where a backslash-2 escape is
211
+ read by JavaScript first and rejected as an octal one, taking the module
212
+ down before any CSS exists. */
213
+ .howbox>summary::before{content:"▸ ";color:var(--steel)}
214
+ .howbox[open]>summary::before{content:"▾ "}
215
+ .howbox>summary:hover{color:var(--text)}
216
+ .howbox>summary:focus-visible{outline:2px solid var(--steel);outline-offset:2px}
187
217
  pre.how{background:var(--bg-sunken);border:1px solid var(--hairline);border-radius:.45rem;padding:.7rem .85rem;font-family:var(--mono);font-size:.76rem;color:var(--text);overflow-x:auto;margin:.4rem 0 .7rem}
188
218
  pre.how .c{color:var(--muted)}
189
219
 
@@ -203,11 +233,23 @@ pre.how .c{color:var(--muted)}
203
233
  .comp .s-cache_write_1h{background:var(--ink)}
204
234
  /* ---- initiatives ---- */
205
235
  .inits{display:flex;flex-direction:column;gap:.3rem;margin:.5rem 0}
236
+ /* A button, because selecting one opens its detail — the same interaction the
237
+ lane cards have. The reset is the whole point of the first three
238
+ declarations: a button inherits neither the page font nor its colour. */
206
239
  .initrow{display:grid;grid-template-columns:minmax(0,1.6fr) 5rem auto minmax(0,1fr);
207
- gap:.6rem;align-items:center;padding:.35rem .5rem;border-radius:4px}
240
+ gap:.6rem;align-items:center;padding:.35rem .5rem;border-radius:4px;
241
+ font:inherit;color:inherit;background:transparent;border:1px solid transparent;
242
+ width:100%;text-align:left;cursor:pointer}
243
+ .initrow:hover{border-color:var(--hairline);background:var(--bg-raised)}
244
+ .initrow:focus-visible{outline:2px solid var(--steel);outline-offset:2px}
245
+ .initrow[aria-pressed="true"]{border-color:var(--brass-edge);background:var(--brass-low)}
208
246
  /* An initiative nobody can move without the operator is the one thing on this
209
247
  section worth catching an eye. */
210
248
  .initrow.waiting{background:color-mix(in srgb,var(--brass) 12%,transparent)}
249
+ /* Finished work is CONTEXT, not news: it keeps its row and its numbers and
250
+ stops competing for attention with the initiatives that are still running. */
251
+ .initrow.finished .il,.initrow.finished .iv{color:var(--muted)}
252
+ .initrow .iw.done{color:var(--sage);font-weight:600}
211
253
  .initrow .il{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
212
254
  .initrow .islug{color:var(--muted);margin-left:.4rem;font-size:.85em}
213
255
  .initrow .ib{height:6px;background:var(--line);border-radius:3px;overflow:hidden}
@@ -404,6 +446,14 @@ if (data.schema !== 1) {
404
446
  ['spend', 'Spend', null],
405
447
  ['settings', 'Settings', null],
406
448
  ];
449
+ // The open tab lives in the URL fragment, and that is not cosmetic. Tab
450
+ // state was a local variable while this page reloads itself every 30
451
+ // seconds, so an operator reading Spend was thrown back to Overview twice a
452
+ // minute — the page contradicting its own reason to be left open.
453
+ //
454
+ // replaceState, never an assignment to location.hash: assigning pushes a
455
+ // history entry, and one entry per reload means the Back button walks
456
+ // backwards through half an hour of refreshes instead of leaving the page.
407
457
  var select = function (key) {
408
458
  for (var i = 0; i < TABS.length; i += 1) {
409
459
  var k = TABS[i][0];
@@ -411,6 +461,9 @@ if (data.schema !== 1) {
411
461
  buttons[k].setAttribute('aria-selected', on ? 'true' : 'false');
412
462
  panels[k].hidden = !on;
413
463
  }
464
+ try {
465
+ history.replaceState(null, '', '#' + key);
466
+ } catch (e) { /* a restorable tab is a nicety; never let it take the page down */ }
414
467
  };
415
468
  TABS.forEach(function (spec) {
416
469
  var b = el('button', null, spec[1]);
@@ -614,21 +667,141 @@ if (data.schema !== 1) {
614
667
  // "Waiting" is the initiative's own count of open operator questions. The
615
668
  // idle time is computed HERE, from last_ts, because the payload is
616
669
  // byte-compared and reads no clock — the same split the agent strip uses.
670
+ // Reading an initiative's own documents, which were paths you copied into an
671
+ // editor and nothing else. SERVED, never embedded, for the same reason spend
672
+ // is: one NOTES.md runs to tens of kilobytes and board.json is a committed,
673
+ // byte-compared artefact.
674
+ //
675
+ // The request names an initiative and a FILE NAME, never a path - the server
676
+ // matches that name against its own fixed list (see board.mjs), so no URL
677
+ // this page can build reaches a file Tyran did not already agree to show.
678
+ // The markdown is rendered as TEXT in a pre, deliberately not parsed: these
679
+ // documents are written by agents, and the rule this whole page keeps is
680
+ // that nothing from that side ever becomes markup.
681
+ var loadDoc = function (init, file, view) {
682
+ clear(view);
683
+ view.appendChild(el('div', 'hint', 'reading ' + file.name + '…'));
684
+ fetch('doc.json?init=' + encodeURIComponent(init) + '&name=' + encodeURIComponent(file.name),
685
+ { headers: { accept: 'application/json' } })
686
+ .then(function (r) { return r.json().then(function (p) { return { ok: r.ok, payload: p }; }); })
687
+ .then(function (res) {
688
+ clear(view);
689
+ var payload = res.payload || {};
690
+ if (!res.ok) {
691
+ view.appendChild(el('div', 'setnote bad', String(payload.error || 'this file could not be read')));
692
+ return;
693
+ }
694
+ var head = el('div', 'dochead');
695
+ head.appendChild(el('span', 'fname', file.name));
696
+ head.appendChild(el('code', null, payload.path));
697
+ var close = el('button', 'sbtn', 'Close');
698
+ close.setAttribute('type', 'button');
699
+ close.addEventListener('click', function () { clear(view); });
700
+ head.appendChild(close);
701
+ view.appendChild(head);
702
+ var pre = el('pre', 'doc');
703
+ pre.textContent = payload.text;
704
+ view.appendChild(pre);
705
+ if (payload.truncated === true) {
706
+ view.appendChild(el('div', 'hint',
707
+ 'Shown to ' + payload.bytes + ' bytes and cut there — open ' + payload.path + ' for the rest.'));
708
+ }
709
+ })
710
+ .catch(function () {
711
+ clear(view);
712
+ view.appendChild(el('div', 'setnote bad',
713
+ 'This board is not being served, so it cannot read files. Start one with: npx @jjanczur/tyran board --dir .tyran --serve'));
714
+ });
715
+ };
716
+
617
717
  var inits = Array.isArray(data.initiatives) ? data.initiatives : [];
618
718
  if (inits.length > 0) {
619
- var stalled = inits.filter(function (i) { return i.waiting > 0; }).sort(function (a, b) {
719
+ // Finished is a fact the journal STATES, never one inferred from a
720
+ // percentage: a checkpoint whose phase is the reserved word closed. See
721
+ // board.mjs for why that event and no other.
722
+ var isClosed = function (i) { return typeof i.closed === 'string' && i.closed !== ''; };
723
+ // A finished initiative blocks nobody, so its leftover questions are moot
724
+ // and it stays out of the nag. Its own row still reports them.
725
+ var stalled = inits.filter(function (i) { return i.waiting > 0 && !isClosed(i); }).sort(function (a, b) {
620
726
  return (ageMsOf(b.last_ts) || 0) - (ageMsOf(a.last_ts) || 0);
621
727
  });
728
+ var finished = inits.filter(isClosed);
622
729
  ov.appendChild(el('h2', null, 'Initiatives'));
623
730
  if (stalled.length > 0) {
624
731
  ov.appendChild(el('div', 'hint',
625
732
  stalled.length + ' of ' + inits.length + ' are waiting on an answer from you. ' +
626
733
  'Longest-waiting first — an initiative with an open question does not move until it is answered.'));
627
734
  }
735
+ if (finished.length > 0) {
736
+ ov.appendChild(el('div', 'hint',
737
+ finished.length + ' finished, sorted last. Finished means a checkpoint declared the initiative closed; it ' +
738
+ 'is not a claim that anything was deployed, which no journal event records. An initiative sitting at 100% ' +
739
+ 'without that checkpoint is work that stopped, not work that ended.'));
740
+ }
741
+ // Selecting an initiative, which was the one thing on this page you could
742
+ // read and not open. Deliberately the ticket detail's shape and place:
743
+ // same interaction, same corner of the screen, nothing new to learn.
744
+ var initDetail = el('div');
745
+ var initSelected = null;
746
+ var showInit = function (i, button) {
747
+ if (initSelected) initSelected.setAttribute('aria-pressed', 'false');
748
+ initSelected = button;
749
+ button.setAttribute('aria-pressed', 'true');
750
+ clear(initDetail);
751
+ var box = el('div', 'detail');
752
+ box.appendChild(el('div', 'dt', i.title || i.name));
753
+ var dl = el('dl');
754
+ var irow = function (k, v) {
755
+ if (v === null || v === undefined || v === '') return;
756
+ dl.appendChild(el('dt', null, k));
757
+ dl.appendChild(el('dd', null, v));
758
+ };
759
+ irow('directory', i.name);
760
+ irow('state', isClosed(i)
761
+ ? 'finished — a checkpoint closed it ' + ago(i.closed) + ' (' + i.closed + ')'
762
+ : 'open' + (i.phase ? ' · phase ' + i.phase : ' · no phase recorded'));
763
+ irow('tickets', i.merged + ' of ' + i.tickets + ' merged ('
764
+ + (typeof i.percent === 'number' ? i.percent : 0) + '%)');
765
+ irow('waiting on you', i.waiting > 0
766
+ ? i.waiting + ' question(s) — the "Waiting on you" tab answers them' : null);
767
+ irow('findings', i.findings > 0 ? i.findings + ' — STATE.md carries the table' : null);
768
+ irow('last event', i.last_ts ? ago(i.last_ts) + ' (' + i.last_ts + ')' : null);
769
+ box.appendChild(dl);
770
+ // The documents this initiative ACTUALLY has, listed by the server after
771
+ // an existsSync - never a fixed list of what a well-run initiative ought
772
+ // to contain. A named file that is not there is the same lie as a
773
+ // missing one, in the other direction.
774
+ var docs = (data.files || {})[i.name] || [];
775
+ if (docs.length === 0) {
776
+ box.appendChild(el('div', 'hint',
777
+ 'No PLAN.md, NOTES.md, RETRO.md, STATE.md or PROGRESS.md beside this journal — those five are what the board can open.'));
778
+ } else {
779
+ box.appendChild(el('div', 'dt', 'Files'));
780
+ var view = el('div', 'docview');
781
+ var list = el('div', 'files');
782
+ docs.forEach(function (f) {
783
+ var line = el('div', 'file');
784
+ var open = el('button', 'fname', f.name);
785
+ open.setAttribute('type', 'button');
786
+ open.addEventListener('click', function () { loadDoc(i.name, f, view); });
787
+ line.appendChild(open);
788
+ line.appendChild(el('code', null, f.path));
789
+ list.appendChild(line);
790
+ });
791
+ box.appendChild(list);
792
+ box.appendChild(view);
793
+ }
794
+ initDetail.appendChild(box);
795
+ };
628
796
  var table = el('div', 'inits');
629
- var ordered = stalled.concat(inits.filter(function (i) { return !(i.waiting > 0); }));
797
+ var ordered = stalled
798
+ .concat(inits.filter(function (i) { return !(i.waiting > 0) && !isClosed(i); }))
799
+ .concat(finished);
630
800
  ordered.forEach(function (i) {
631
- var row = el('div', i.waiting > 0 ? 'initrow waiting' : 'initrow');
801
+ var row = el('button', 'initrow'
802
+ + (isClosed(i) ? ' finished' : i.waiting > 0 ? ' waiting' : ''));
803
+ row.setAttribute('type', 'button');
804
+ row.setAttribute('aria-pressed', 'false');
632
805
  // The TITLE, which the journal has carried all along while this page
633
806
  // showed a directory slug.
634
807
  var label = el('div', 'il');
@@ -643,16 +816,20 @@ if (data.schema !== 1) {
643
816
  var counts = i.merged + '/' + i.tickets + ' merged';
644
817
  // Named only when there is something to name. A findings count of zero
645
818
  // on every row is noise that teaches the eye to skip the column.
646
- if (i.findings > 0) counts += ' \u00b7 ' + i.findings + ' finding' + (i.findings === 1 ? '' : 's');
819
+ if (i.findings > 0) counts += ' · ' + i.findings + ' finding' + (i.findings === 1 ? '' : 's');
647
820
  row.appendChild(el('div', 'iv', counts));
648
821
  var age = ageMsOf(i.last_ts);
649
- row.appendChild(el('div', i.waiting > 0 ? 'iw warn' : 'iw',
650
- i.waiting > 0
651
- ? i.waiting + ' waiting on you \u00b7 quiet ' + ago(i.last_ts)
652
- : (age === null ? '' : 'last moved ' + ago(i.last_ts))));
822
+ row.appendChild(el('div', isClosed(i) ? 'iw done' : i.waiting > 0 ? 'iw warn' : 'iw',
823
+ isClosed(i)
824
+ ? 'FINISHED · closed ' + ago(i.closed)
825
+ : i.waiting > 0
826
+ ? i.waiting + ' waiting on you · quiet ' + ago(i.last_ts)
827
+ : (age === null ? '' : 'last moved ' + ago(i.last_ts))));
828
+ row.addEventListener('click', function () { showInit(i, row); });
653
829
  table.appendChild(row);
654
830
  });
655
831
  ov.appendChild(table);
832
+ ov.appendChild(initDetail);
656
833
  }
657
834
 
658
835
  ov.appendChild(el('h2', null, 'Agents'));
@@ -902,19 +1079,37 @@ if (data.schema !== 1) {
902
1079
  [].forEach.call(lanesWrap.children, function (box) { shown += box.tyranApply(q); });
903
1080
  filterCount.textContent = q === '' ? '' : shown + ' of ' + allCards.length + ' ticket(s)';
904
1081
  };
905
- filterInput.addEventListener('input', applyFilter);
1082
+ filterInput.addEventListener('input', function () {
1083
+ applyFilter();
1084
+ // The same rule every other input on this page follows: a reload must not
1085
+ // eat what you are in the middle of typing. Re-armed the moment the box is
1086
+ // empty again, because the Board is one of the two views that has to stay
1087
+ // live — a filter left holding the timer would freeze it for the night.
1088
+ // Wrapped, not passed: both helpers are defined further down, and
1089
+ // addEventListener with undefined is a silent no-op rather than an error.
1090
+ if (filterInput.value.trim() === '') armRefresh(); else holdRefresh();
1091
+ });
906
1092
  bd.appendChild(lanesWrap);
907
1093
  bd.appendChild(detail);
908
1094
 
909
1095
  // ---- questions --------------------------------------------------------
910
1096
  var qs = panels.questions;
911
1097
  qs.appendChild(el('div', 'hint', 'Every question here is a gate in the journal, and it stays open until you close it. Blank takes the recorded default and is still written down as your decision; a single dash leaves it for next time.'));
1098
+ // The terminal route, folded shut. It is the ONLY way to answer on a board
1099
+ // opened over file:// or served without --write, so it can never be removed
1100
+ // — but on a writable board it is three commands the operator does not need,
1101
+ // printed above the questions, which is where the eye lands first. So it
1102
+ // opens itself exactly when it is the answer: the settings fetch below finds
1103
+ // out whether this board can write, and a board that cannot gets it open.
1104
+ var howBox = el('details', 'howbox');
1105
+ howBox.appendChild(el('summary', null, 'Answer from the terminal instead'));
912
1106
  var how = el('pre', 'how');
913
1107
  how.textContent =
914
1108
  'npx @jjanczur/tyran answer render --dir .tyran # writes .tyran/state/ANSWERS.md\\n' +
915
1109
  '$EDITOR .tyran/state/ANSWERS.md # fill the answer: lines\\n' +
916
1110
  'npx @jjanczur/tyran answer apply --dir .tyran # closes what you answered';
917
- qs.appendChild(how);
1111
+ howBox.appendChild(how);
1112
+ qs.appendChild(howBox);
918
1113
  if (asks.length === 0) qs.appendChild(el('div', 'empty', 'nothing — the agents have what they need'));
919
1114
 
920
1115
  // Answering from the page. The three commands above still work and stay
@@ -928,9 +1123,14 @@ if (data.schema !== 1) {
928
1123
  var replyBox = function (a, hasDefault) {
929
1124
  var box = el('div', 'reply');
930
1125
  var input = el('textarea');
931
- input.placeholder = hasDefault
1126
+ // The shortcut is named where the cursor already is. "Answer" IS the send
1127
+ // button and always was, but a labelled verb beside a text box reads as a
1128
+ // mode switch rather than as send, and an operator who types an answer and
1129
+ // presses Enter gets a newline with nothing to say why.
1130
+ input.placeholder = (hasDefault
932
1131
  ? 'Your answer, in your own words \\u2014 or use the default button.'
933
- : 'Your answer, in your own words. There is no recorded default for this one.';
1132
+ : 'Your answer, in your own words. There is no recorded default for this one.')
1133
+ + ' \\u2318/Ctrl+Enter sends.';
934
1134
  var acts = el('div', 'acts');
935
1135
  var send = el('button', 'sbtn', 'Answer');
936
1136
  send.setAttribute('type', 'button');
@@ -969,7 +1169,8 @@ if (data.schema !== 1) {
969
1169
  + ': ' + p.recorded + ' \\u00b7 decision ' + p.decision + ' \\u2014 reload to refresh the board';
970
1170
  });
971
1171
  };
972
- send.addEventListener('click', function () {
1172
+ var attempt = function () {
1173
+ if (input.disabled) return;
973
1174
  if (input.value.trim() === '') {
974
1175
  status.className = 'sstat bad';
975
1176
  status.textContent = hasDefault
@@ -978,6 +1179,20 @@ if (data.schema !== 1) {
978
1179
  return;
979
1180
  }
980
1181
  submit(input.value);
1182
+ };
1183
+ send.addEventListener('click', attempt);
1184
+ // Enter ALONE must not send, and the modifier is not decoration. This is a
1185
+ // textarea because an operator explaining a decision writes sentences, and
1186
+ // what it sends is appended to a journal that can never take it back — a
1187
+ // question closed by a stray keystroke is a decision nobody made. The
1188
+ // keyCode fallback is for a browser that reports no key on a dead-key
1189
+ // layout; a duplicate hit is harmless because the handler is idempotent
1190
+ // once the field disables itself.
1191
+ input.addEventListener('keydown', function (e) {
1192
+ if ((e.metaKey || e.ctrlKey) && (e.key === 'Enter' || e.keyCode === 13)) {
1193
+ e.preventDefault();
1194
+ attempt();
1195
+ }
981
1196
  });
982
1197
  if (useDefault) useDefault.addEventListener('click', function () { submit(''); });
983
1198
 
@@ -1629,13 +1844,20 @@ if (data.schema !== 1) {
1629
1844
  stBody.appendChild(pol);
1630
1845
  };
1631
1846
 
1632
- // Leaving this tab re-arms the refresh, entering it stops it. A page that
1847
+ // Leaving these tabs re-arms the refresh, entering one stops it. A page that
1633
1848
  // reloads under an open select is a page that loses the change you were
1634
- // halfway through making, and the board has three other tabs that want to
1635
- // stay live.
1849
+ // halfway through making.
1850
+ //
1851
+ // Spend joined Settings for a different reason: nothing on it is live. It is
1852
+ // one fetch of a report over transcripts, and reloading the page under a
1853
+ // reader who is comparing two rows of a cost table re-runs that scan to
1854
+ // redraw numbers that did not move. Overview and Board are the two views
1855
+ // that must NOT be held — a stale board overnight is the failure this page
1856
+ // exists to prevent.
1857
+ var HELD_TABS = { settings: true, spend: true };
1636
1858
  Object.keys(buttons).forEach(function (key) {
1637
1859
  buttons[key].addEventListener('click', function () {
1638
- if (key === 'settings') holdRefresh(); else armRefresh();
1860
+ if (HELD_TABS[key] === true) holdRefresh(); else armRefresh();
1639
1861
  });
1640
1862
  });
1641
1863
 
@@ -1672,6 +1894,11 @@ if (data.schema !== 1) {
1672
1894
  fetch('settings.json', { headers: { accept: 'application/json' } })
1673
1895
  .then(function (r) { return r.ok ? r.json() : Promise.reject(new Error(String(r.status))); })
1674
1896
  .then(function (payload) {
1897
+ // A read-only board cannot post an answer, so the terminal commands stop
1898
+ // being a footnote and become the instruction — opened here rather than
1899
+ // guessed at render time, because whether this board may write is a fact
1900
+ // only the server has.
1901
+ if (payload.writable !== true) howBox.open = true;
1675
1902
  if (payload.schema !== 1) {
1676
1903
  clear(stBody);
1677
1904
  stBody.appendChild(el('div', 'setnote bad', 'Settings were served in a format this page does not know (schema ' +
@@ -1692,13 +1919,31 @@ if (data.schema !== 1) {
1692
1919
  }
1693
1920
  })
1694
1921
  .catch(function () {
1922
+ // No server at all — file://, or a copy on a docs site. Nothing on this
1923
+ // page can write, so the terminal route is the only one there is. Set
1924
+ // BEFORE the file:// return, which is silent on purpose.
1925
+ howBox.open = true;
1695
1926
  if (String(location.protocol) === 'file:') return;
1696
1927
  clear(stBody);
1697
1928
  stBody.appendChild(el('div', 'setnote bad',
1698
1929
  'Settings could not be read: the board server did not answer. They are served, never embedded \\u2014 start it with: npx @jjanczur/tyran board --dir .tyran --serve --write'));
1699
1930
  });
1700
1931
 
1701
- select('overview');
1932
+ // An unknown fragment is not worth a message: someone hand-edited the URL,
1933
+ // or a later Tyran renamed a tab. hasOwnProperty rather than a truth test on
1934
+ // the lookup, so a fragment spelling "constructor" cannot select a prototype.
1935
+ var tabFromHash = function () {
1936
+ var wanted = String(location.hash || '').replace(/^#/, '');
1937
+ return Object.prototype.hasOwnProperty.call(panels, wanted) ? wanted : 'overview';
1938
+ };
1939
+ select(tabFromHash());
1940
+ // Changing only the fragment of a URL is a SAME-DOCUMENT navigation: the
1941
+ // browser fires this and reloads nothing, so without it a link to #board —
1942
+ // or an operator editing the address bar on the page they already have open
1943
+ // — moved the URL and left the page on whatever tab it was showing.
1944
+ // Measured in a real browser; it is the half of fragment routing that is
1945
+ // invisible until someone tries it.
1946
+ window.addEventListener('hashchange', function () { select(tabFromHash()); });
1702
1947
 
1703
1948
  var foot = el('footer');
1704
1949
  foot.appendChild(el('div', null, 'GENERATED by tyran scripts/board.mjs — do not edit. Reloads itself every 30 s unless you are editing; ages are computed in this browser.'));
package/scripts/board.mjs CHANGED
@@ -35,7 +35,7 @@ import { spawn as spawnProcess } from 'node:child_process';
35
35
  import { basename, join, resolve } from 'node:path';
36
36
  import { realpathSync } from 'node:fs';
37
37
  import { fileURLToPath } from 'node:url';
38
- import { readJournal } from './journal.mjs';
38
+ import { isClosingPhase, readJournal } from './journal.mjs';
39
39
  import {
40
40
  BOARD_FILE,
41
41
  BOARD_JSON_FILE,
@@ -48,7 +48,7 @@ import {
48
48
  writeAllAtomic,
49
49
  writeAtomic,
50
50
  } from './project.mjs';
51
- import { jsonEscapeInvisible } from './invisible.mjs';
51
+ import { escapeInvisible, jsonEscapeInvisible } from './invisible.mjs';
52
52
  import { renderBoardError, renderBoardHtml } from './board-html.mjs';
53
53
  import { COST_SCHEMA, WINDOWS, costJson, costReport } from './cost.mjs';
54
54
  import { SettingsError, applyPolicyClass, applySetting, readSettings } from './settings.mjs';
@@ -225,10 +225,12 @@ export function readInitiativeBoards(tyranDir) {
225
225
  * rather than embedded. Relative is also the more useful form — it is what
226
226
  * the reader pastes, from the repo root, into an editor.
227
227
  *
228
- * Nothing is served from here: `--serve` derives a filesystem path from no
229
- * URL at all, which is worth more than a clickable link. The one route that
230
- * writes — Settings, behind `--write` — reaches two fixed files named in
231
- * `settings.mjs` and takes a KEY from the request, never a path.
228
+ * These five ARE served, since 0.1.42, by `readInitiativeDoc` below — and the
229
+ * promise this comment has always made survives it intact: `--serve` still
230
+ * derives a filesystem path from no URL at all. The route takes a NAME and
231
+ * matches it against the list above, exactly as the one route that writes —
232
+ * Settings, behind `--write` — reaches two fixed files named in `settings.mjs`
233
+ * by taking a KEY from the request and never a path.
232
234
  */
233
235
  export const INITIATIVE_FILES = Object.freeze(['PLAN.md', 'NOTES.md', 'RETRO.md', 'STATE.md', 'PROGRESS.md']);
234
236
 
@@ -241,6 +243,89 @@ export function initiativeFiles(tyranDir, name) {
241
243
  }));
242
244
  }
243
245
 
246
+ /**
247
+ * How much of one document travels to the page, in CODEPOINTS.
248
+ *
249
+ * Codepoints and not bytes because the cut is applied to a decoded string:
250
+ * slicing a UTF-8 buffer at a fixed offset lands inside a character often
251
+ * enough, and hands the reader a replacement mark that was never in the file.
252
+ *
253
+ * A cap at all because this route reads whatever grew beside a journal, and a
254
+ * NOTES.md three weeks into an initiative is not a thing to push through one
255
+ * response. The panel says it was cut and names the path holding the rest.
256
+ */
257
+ export const MAX_DOC_CHARS = 200_000;
258
+
259
+ /**
260
+ * One initiative document, for the page's file viewer.
261
+ *
262
+ * TWO CLOSED SETS AND NO PATH ARITHMETIC — that is the whole security story,
263
+ * and it is why the comment on `initiativeFiles` above ("nothing is served
264
+ * from here") could be revisited rather than merely broken. `name` must equal
265
+ * a member of `INITIATIVE_FILES`, and `init` must equal a directory that
266
+ * `state/` actually contains, compared against the very listing the board
267
+ * folds. Nothing from the request is joined into a path until it has matched
268
+ * one of those two lists, so `..`, an absolute path, a NUL and a name that
269
+ * differs only by case are all rejected by never becoming candidates — not by
270
+ * a filter someone has to keep ahead of the next trick.
271
+ *
272
+ * The text is invisible-ESCAPED, like every other journal-side value that
273
+ * reaches a human (invisible.mjs): these documents are written by agents out
274
+ * of reports about foreign repositories, and the reader is looking at them on
275
+ * a page instead of in the editor that would have shown the same bytes.
276
+ *
277
+ * Nothing is echoed back on a refusal. A message naming what was asked for is
278
+ * a message carrying attacker-chosen text into the operator's browser, and
279
+ * naming the five files it DOES serve is more useful anyway.
280
+ */
281
+ export function readInitiativeDoc(tyranDir, init, name) {
282
+ if (!INITIATIVE_FILES.includes(name)) {
283
+ return { ok: false, status: 400, error: `this board serves only: ${INITIATIVE_FILES.join(', ')}` };
284
+ }
285
+ const stateDir = join(tyranDir, 'state');
286
+ let names;
287
+ try {
288
+ names = readdirSync(stateDir);
289
+ } catch (err) {
290
+ return { ok: false, status: 503, error: `${err?.code ?? 'unreadable'} reading the state directory` };
291
+ }
292
+ if (!names.includes(init)) {
293
+ return { ok: false, status: 404, error: 'no initiative by that name in this board' };
294
+ }
295
+ const file = join(stateDir, init, name);
296
+ let raw;
297
+ try {
298
+ raw = readFileSync(file, 'utf8');
299
+ } catch (err) {
300
+ // ENOENT here is ordinary: `initiativeFiles` listed what existed when the
301
+ // page was rendered, and an initiative that has since been archived is a
302
+ // fact to report rather than a failure.
303
+ return {
304
+ ok: false,
305
+ status: err?.code === 'ENOENT' ? 404 : 503,
306
+ error: err?.code === 'ENOENT'
307
+ ? `${name} is not beside that journal — the board lists what exists when it renders, so reload it`
308
+ : `${err?.code ?? 'unreadable'} reading ${name}`,
309
+ };
310
+ }
311
+ const chars = [...raw];
312
+ const truncated = chars.length > MAX_DOC_CHARS;
313
+ return {
314
+ ok: true,
315
+ status: 200,
316
+ schema: 1,
317
+ init,
318
+ name,
319
+ // Repo-relative, the same form `initiativeFiles` records and for the same
320
+ // reason: it is what the reader pastes into an editor, and it names no
321
+ // home directory.
322
+ path: join(basename(resolve(tyranDir)), 'state', init, name),
323
+ truncated,
324
+ chars: truncated ? MAX_DOC_CHARS : chars.length,
325
+ text: escapeInvisible(truncated ? chars.slice(0, MAX_DOC_CHARS).join('') : raw),
326
+ };
327
+ }
328
+
244
329
  /** Pure merge of per-initiative boards into the one payload. */
245
330
  /**
246
331
  * How many logged errors travel in the payload.
@@ -297,6 +382,28 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
297
382
  // caller assembling one by hand need not have every collection. A
298
383
  // missing array must read as "none", never take the board down.
299
384
  findings: (state.findings ?? []).length,
385
+ // FINISHED and ABANDONED read identically on a percentage bar, and they
386
+ // are the opposite situation: one is work that ended, the other is work
387
+ // that stopped. The board had no way to tell them apart — measured, it
388
+ // is the same 63 journals where 43 sat on an unanswered question and 6
389
+ // were genuinely done.
390
+ //
391
+ // A checkpoint whose phase is the reserved word `closed` is the ONLY
392
+ // event that declares an initiative over (journal.mjs), which is already
393
+ // what closes its still-open spawns — so this hangs on that same fact
394
+ // rather than inventing a second rule for "finished" (ADR-21). The
395
+ // TIMESTAMP, not a boolean: "closed 9 days ago" is the reading, and the
396
+ // page ages it in the reader's browser like every other time here.
397
+ //
398
+ // `phase` travels beside it because an initiative that is NOT closed
399
+ // still has its own word for where it is, and the per-initiative
400
+ // board.json has carried that word all along while the cross board
401
+ // showed a percentage and nothing else.
402
+ //
403
+ // NOT deployment: nothing in the closed event set records a deploy, so
404
+ // the board must not imply one. This says the initiative was wound up.
405
+ phase: state.checkpoint?.phase ?? null,
406
+ closed: isClosingPhase(state.checkpoint?.phase) ? state.checkpoint.ts : null,
300
407
  last_ts: state.lastTs,
301
408
  });
302
409
  if (state.lastTs !== null && (asOf === null || state.lastTs > asOf)) asOf = state.lastTs;
@@ -897,6 +1004,27 @@ function main() {
897
1004
  sendJson(res, 200, { ...readSettings(dir), writable: flags.write });
898
1005
  return;
899
1006
  }
1007
+ // An initiative's own documents, which the board could name and not
1008
+ // open. A GET behind the same Host pin as everything else, and NOT
1009
+ // behind `--write`: reading a PLAN.md is what this whole page does,
1010
+ // and the flag draws its line at changing the repository.
1011
+ //
1012
+ // The route takes an initiative and a FILE NAME. It takes no path,
1013
+ // because a route that takes a path is a route whose safety is a
1014
+ // filter — see readInitiativeDoc for the two closed sets that replace
1015
+ // one. The old comment on `initiativeFiles` said this board derives a
1016
+ // filesystem path from no URL at all; it still does not.
1017
+ if (req.url.startsWith('/doc.json?') || req.url === '/doc.json') {
1018
+ const q = new URLSearchParams(req.url.slice(req.url.indexOf('?') + 1));
1019
+ const doc = readInitiativeDoc(dir, String(q.get('init') ?? ''), String(q.get('name') ?? ''));
1020
+ if (doc.ok !== true) {
1021
+ sendJson(res, doc.status, { ok: false, error: doc.error });
1022
+ return;
1023
+ }
1024
+ const { ok, status, ...payload } = doc;
1025
+ sendJson(res, 200, payload);
1026
+ return;
1027
+ }
900
1028
  if (req.url === '/settings/config' || req.url === '/settings/policy' || req.url === '/answer') {
901
1029
  const route = req.url === '/answer' ? 'answer' : req.url.slice('/settings/'.length);
902
1030
  if (req.method !== 'POST') {