@awebai/oats 0.59.0 → 0.60.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 (35) hide show
  1. package/docs/desktop-cli-api.md +12 -5
  2. package/docs/execution-targets.md +7 -2
  3. package/docs/implementation.md +1 -0
  4. package/docs/integrations.md +1 -1
  5. package/docs/official-catalog.md +2 -2
  6. package/docs/packages.md +7 -7
  7. package/docs/release-notes/v0.60.0.md +104 -0
  8. package/docs/tui.md +123 -15
  9. package/docs/workspaces.md +1 -1
  10. package/lib/core.mjs +42 -15
  11. package/lib/session-input.mjs +45 -28
  12. package/package-catalog.json +2 -2
  13. package/package.json +1 -1
  14. package/packages/client/capability-catalog.mjs +93 -0
  15. package/packages/client/capability-facts.mjs +59 -0
  16. package/packages/client/capability-rows.mjs +121 -0
  17. package/packages/client/catalog-messages.mjs +12 -0
  18. package/packages/client/cli-locator.mjs +2 -2
  19. package/packages/client/soul-catalog.mjs +8 -0
  20. package/packages/client/soul-facts.mjs +7 -0
  21. package/packages/client/spawn-messages.mjs +8 -0
  22. package/packages/client/subsequence-score.mjs +15 -0
  23. package/packages/tui/README.md +1 -1
  24. package/packages/tui/lib/actions.mjs +1 -1
  25. package/packages/tui/lib/client.mjs +7 -2
  26. package/packages/tui/lib/main.mjs +58 -9
  27. package/packages/tui/lib/model.mjs +136 -46
  28. package/packages/tui/lib/store.mjs +133 -16
  29. package/packages/tui/lib/views/capabilities.mjs +239 -0
  30. package/packages/tui/lib/views/frame.mjs +55 -20
  31. package/packages/tui/lib/views/help.mjs +9 -4
  32. package/packages/tui/lib/views/palette.mjs +9 -4
  33. package/packages/tui/lib/views/souls.mjs +6 -4
  34. package/packages/tui/lib/views/spawn.mjs +5 -3
  35. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -12,7 +12,7 @@
12
12
  import { ACTIONS, LEADER_KEYS, bindings } from "./actions.mjs";
13
13
  import { collapseKey, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
14
14
  import { DETACH_KEY } from "./config.mjs";
15
- import { BUTTON_ORDER, SPAWN_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, disclosure, openDecision, paletteItems, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher } from "./model.mjs";
15
+ import { BUTTON_ORDER, SPAWN_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher } from "./model.mjs";
16
16
  import { backKeyId } from "./term/through.mjs";
17
17
  import { windowOf } from "./views/scroll.mjs";
18
18
  import { SPLIT_MIN, splitFits } from "./views/split.mjs";
@@ -32,6 +32,13 @@ const NO_FILTER = Object.freeze({ editing: false, query: "" });
32
32
  * and whether a read of it is in flight), and the selection (a soul's name), the scroll, the focus
33
33
  * and the filter of the view, kept when it is left and found again, for the run. */
34
34
  const NO_SOULS = Object.freeze({ wanted: false, held: new Map(), selected: null, top: 0, loose: false, focus: "list", detailTop: 0, filter: Object.freeze({ editing: false, query: "" }) });
35
+ /** The Capabilities view's own (docs/tui.md, "The Capabilities view"; Spec 7), as the Souls view's:
36
+ * whether its catalog was ever wanted, what the loop holds of each workspace's (`held`), and the
37
+ * selection (a capability's key, lib/model.mjs capabilityKey), the list's scroll (`top`, `loose` as
38
+ * the switcher's), the focus, the filter, and in the detail its scroll (`detailTop`, the row it was
39
+ * last drawn from) and the mark on a soul of "Used by" (`mark`, an index of the listed souls;
40
+ * `detailLoose` while the detail was scrolled away from it on purpose). Kept for the run. */
41
+ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected: null, top: 0, loose: false, focus: "list", detailTop: 0, detailLoose: false, mark: 0, filter: Object.freeze({ editing: false, query: "" }) });
35
42
 
36
43
  /** The state before the first answer. `deployment` is the one `oats tui` was started in or was
37
44
  * told of, with its shared pending entry (lib/main.mjs makes it); null for a run started outside
@@ -97,7 +104,7 @@ export function initialState({ deployment = null, cli, home, entry = null, actio
97
104
  switcher: Object.freeze({ editing: false, query: "", selected: null, top: 0, loose: false, line: null, refused: null }),
98
105
  offered: Object.freeze({ offered: Object.freeze([]), limited: false }),
99
106
  helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(),
100
- leaderKey: backKeyId(detachKey), leader: null, palette: null, recent: Object.freeze([]), souls: NO_SOULS,
107
+ leaderKey: backKeyId(detachKey), leader: null, palette: null, recent: Object.freeze([]), souls: NO_SOULS, capabilities: NO_CAPABILITIES,
101
108
  spawn: null, spawning: null, spawnCheck: null, arriving: null, previews: 0, tabs: Object.freeze([]), split: null, group: 0, aside: null,
102
109
  });
103
110
  }
@@ -258,6 +265,11 @@ const FIELDS = Object.freeze({
258
265
  put: (state, query) => (query === state.souls.filter.query ? state : soulsWith(state, { filter: Object.freeze({ ...state.souls.filter, query }), top: 0, loose: false, detailTop: 0 })),
259
266
  close: (state, query) => soulsWith(state, { filter: Object.freeze({ editing: false, query }), top: 0, loose: false }),
260
267
  }),
268
+ capabilities: Object.freeze({
269
+ query: (state) => state.capabilities.filter.query,
270
+ put: (state, query) => (query === state.capabilities.filter.query ? state : capabilitiesWith(state, { filter: Object.freeze({ ...state.capabilities.filter, query }), top: 0, loose: false, detailTop: 0, mark: 0 })),
271
+ close: (state, query) => capabilitiesWith(state, { filter: Object.freeze({ editing: false, query }), top: 0, loose: false }),
272
+ }),
261
273
  switcher: Object.freeze({
262
274
  query: (state) => state.switcher.query,
263
275
  put: (state, query) => (query === state.switcher.query ? state : next(state, { switcher: Object.freeze({ ...state.switcher, query, top: 0, loose: false }) })),
@@ -267,7 +279,8 @@ const FIELDS = Object.freeze({
267
279
  /** The filter field that is open now, or null. */
268
280
  const fieldOf = (state) => (state.view === "instances" && state.filter.editing ? FIELDS.instances
269
281
  : state.view === "switcher" && state.switcher.editing ? FIELDS.switcher
270
- : state.view === "souls" && state.souls.filter.editing ? FIELDS.souls : null);
282
+ : state.view === "souls" && state.souls.filter.editing ? FIELDS.souls
283
+ : state.view === "capabilities" && state.capabilities.filter.editing ? FIELDS.capabilities : null);
271
284
 
272
285
  /** A key while a filter field is open. A key that is text is text, whatever the action table
273
286
  * says, so `q` and `j` can be typed; Backspace removes one grapheme, Enter keeps the filter and
@@ -346,6 +359,100 @@ function inSouls(state, action, event, page, scrolled) {
346
359
  }
347
360
  }
348
361
 
362
+ /** The Souls view with the soul named `name` selected, as the palette's soul row and the Capabilities
363
+ * view's "Used by" show it. A kept filter of the view that hides it is cleared: the soul chosen is
364
+ * the one shown, and the one `i` acts on. */
365
+ function soulChosen(state, name) {
366
+ const step = soulsShown(state), chosen = soulsWith(step.state, { selected: name, loose: false, detailTop: 0 });
367
+ const shown = soulsOf(chosen).selected?.name === name ? chosen : soulsWith(chosen, { filter: Object.freeze({ editing: false, query: "" }), top: 0 });
368
+ return { state: shown, effect: step.effect };
369
+ }
370
+
371
+ /** The Capabilities view's own state with what changes of it. */
372
+ const capabilitiesWith = (state, changes) => next(state, { capabilities: Object.freeze({ ...state.capabilities, ...changes }) });
373
+
374
+ /** The Capabilities view shown (docs/tui.md, "The Capabilities view"): from now on its catalog is
375
+ * wanted, and so is the souls catalog its "Used by" reads, the same flag the Souls view and a spawn
376
+ * set; the loop settles both for the open workspace (`capabilities: "settle"`, `souls: "settle"`),
377
+ * each read only when nothing is held for the workspace as it is now (each its own key). */
378
+ function capabilitiesShown(state) {
379
+ // Come back to from another view, it shows its list: what was selected and filtered stays.
380
+ const shown = state.view === "capabilities" ? state : next(state, { view: "capabilities", back: "capabilities", capabilities: Object.freeze({ ...state.capabilities, focus: "list" }) });
381
+ return { state: soulsWith(capabilitiesWith(shown, { wanted: true }), { wanted: true }), effect: { souls: "settle", capabilities: "settle" } };
382
+ }
383
+
384
+ /** What the loop holds of a workspace's capabilities catalog, told: `{ id, entry, reading }`, as
385
+ * soulsHeard. Only a served workspace's is kept. */
386
+ function capabilitiesHeard(state, { id, entry, reading }) {
387
+ if (!state.ctxs.includes(id)) return { state, effect: null };
388
+ return { state: capabilitiesWith(state, { held: new Map(state.capabilities.held).set(id, Object.freeze({ entry: entry ?? null, reading: reading === true })) }), effect: null };
389
+ }
390
+
391
+ /** The row the capability detail was drawn from, told by the loop once the frame is written (the
392
+ * view keeps the marked soul in sight, so the store's `detailTop` may not be what was drawn): the
393
+ * detail scrolls on from there. */
394
+ function capabilitiesTop(state, top) {
395
+ if (state.view !== "capabilities" || !Number.isInteger(top) || top < 0 || state.capabilities.detailTop === top) return { state, effect: null };
396
+ return { state: capabilitiesWith(state, { detailTop: top }), effect: null };
397
+ }
398
+
399
+ /** A key in the Capabilities view (docs/tui.md, "The Capabilities view"). The list's keys move among
400
+ * the capabilities the filter keeps, passing over the headings of the sections and the groups (the
401
+ * switcher's way: what stands above the first comes into the pane with it, and with nothing further
402
+ * to go to the list scrolls). Enter gives the detail the focus, its mark on the first soul of "Used
403
+ * by"; there Up and Down move that mark among the listed souls, and Enter shows the marked soul in
404
+ * the Souls view. Past the first or the last soul, with none listed, and for the other movement
405
+ * keys, the detail scrolls. `/`
406
+ * opens the view's own filter field; `r` reads the catalog again (`capabilities: "reread"`, which
407
+ * starts nothing while a read is in flight); Esc closes the detail, then clears a kept filter, then
408
+ * goes back to the instances (to the switcher when no workspace is open), as `1` does. */
409
+ function inCapabilities(state, action, event, page, scrolled) {
410
+ const stay = { state, effect: null }, v = state.capabilities;
411
+ const c = capabilitiesOf(state), at = c.selected === null ? -1 : c.keys.indexOf(c.selected);
412
+ const back = () => ({ state: state.open === null ? toSwitcher(next(state, { back: "switcher" })) : next(state, { view: "instances", back: "instances" }), effect: null });
413
+ const put = (changes) => ({ state: capabilitiesWith(state, changes), effect: null });
414
+ const toDetail = { focus: "detail", mark: 0, detailTop: 0, detailLoose: false };
415
+ switch (action) {
416
+ case "instances": return back();
417
+ case "close":
418
+ if (v.focus === "detail") return put({ focus: "list" });
419
+ if (v.filter.query !== "") return put({ filter: Object.freeze({ editing: false, query: "" }), top: 0, loose: false });
420
+ return back();
421
+ case "filter": return c.local ? put({ focus: "list", filter: Object.freeze({ ...v.filter, editing: true }) }) : stay;
422
+ case "refresh": return c.local ? { state, effect: { capabilities: "reread" } } : stay;
423
+ case "open": {
424
+ if (at < 0) return stay;
425
+ if (v.focus !== "detail") return put(toDetail);
426
+ const listed = capabilityUsersOf(state, undefined, c.row).shown;
427
+ const soul = listed[Math.min(v.mark, listed.length - 1)]?.soul ?? null;
428
+ return soul === null ? stay : soulChosen(state, soul);
429
+ }
430
+ case "detail": return at < 0 ? stay : put(v.focus === "detail" ? { focus: "list" } : toDetail);
431
+ case "up": case "down": case "top": case "bottom": case "page-up": case "page-down": {
432
+ if (v.focus === "detail") {
433
+ const listed = at < 0 ? 0 : capabilityUsersOf(state, undefined, c.row).shown.length;
434
+ // The mark moves while it has a soul to go to; past the first or the last, the detail scrolls.
435
+ const to = Math.min(v.mark, listed - 1) + (action === "up" ? -1 : 1);
436
+ if (listed && (action === "up" || action === "down") && to >= 0 && to < listed) return put({ mark: to, detailLoose: false });
437
+ return put({ detailTop: scrolled(v.detailTop), detailLoose: true });
438
+ }
439
+ const count = c.items.length, height = capabilitiesHeight(c, page);
440
+ const drawn = windowOf({ top: v.top, count, height, keep: v.loose ? -1 : c.items.findIndex((item) => item.key !== undefined && item.key === c.selected) }).top;
441
+ const key = c.keys.length ? c.keys[Math.min(Math.max(0, moved(action, Math.max(0, at), c.keys.length, page)), c.keys.length - 1)] : null;
442
+ // No capability to go to in that direction: the rows scroll instead.
443
+ if (key === null || key === c.selected) {
444
+ const top = windowOf({ top: moved(action, drawn, count, height), count, height }).top;
445
+ return top === drawn ? stay : put({ top, loose: true });
446
+ }
447
+ const index = c.items.findIndex((item) => item.key === key);
448
+ // The headings above the first capability come into the pane with it, and what stands under the last one.
449
+ const top = windowOf({ top: key === c.keys[0] ? 0 : key === c.keys.at(-1) ? count : drawn, count, height, keep: index }).top;
450
+ return put({ selected: key, top, loose: false, detailTop: 0, mark: 0, detailLoose: false });
451
+ }
452
+ default: return stay;
453
+ }
454
+ }
455
+
349
456
  const MOVES = Object.freeze(["up", "down", "top", "bottom", "page-up", "page-down"]);
350
457
  /** Where a movement key takes a position `from` among `count` rows, a page being `page` rows. */
351
458
  function moved(action, from, count, page) {
@@ -1003,11 +1110,12 @@ function ranFromPalette(state, item, event, keymap) {
1003
1110
  const from = state.palette.from;
1004
1111
  const settled = item.kind === "instance" || item.kind === "act" ? toInstances(state) : toList(state), shut = settled.state;
1005
1112
  const then = (step) => ({ state: step.state, effect: both(settled.effect, step.effect) });
1006
- // A soul: the Souls view, with it selected. A kept filter of the view that hides it is cleared:
1007
- // the soul chosen is the one shown, and the one `i` acts on.
1008
- if (item.kind === "soul") {
1009
- const step = soulsShown(shut), chosen = soulsWith(step.state, { selected: item.name, loose: false, detailTop: 0 });
1010
- const shown = soulsOf(chosen).selected?.name === item.name ? chosen : soulsWith(chosen, { filter: Object.freeze({ editing: false, query: "" }), top: 0 });
1113
+ // A soul: the Souls view, with it selected (soulChosen).
1114
+ if (item.kind === "soul") return then(soulChosen(shut, item.name));
1115
+ // A capability: the Capabilities view, with it selected, as a soul is shown.
1116
+ if (item.kind === "capability") {
1117
+ const step = capabilitiesShown(shut), chosen = capabilitiesWith(step.state, { selected: item.capability, loose: false, detailTop: 0, mark: 0, detailLoose: false });
1118
+ const shown = capabilitiesOf(chosen).selected === item.capability ? chosen : capabilitiesWith(chosen, { filter: Object.freeze({ editing: false, query: "" }), top: 0 });
1011
1119
  return then({ state: shown, effect: step.effect });
1012
1120
  }
1013
1121
  if (item.kind === "instance" || item.kind === "act") {
@@ -1045,8 +1153,11 @@ function reduced(state, event, keymap) {
1045
1153
  if (event.admitted !== undefined) return { state: admitted(state, event), effect: { refresh: { live: true } } };
1046
1154
  if (event.refused !== undefined) return { state: next(state, { switcher: Object.freeze({ ...state.switcher, refused: event.refused }) }), effect: null };
1047
1155
  if (event.souls !== undefined) return soulsHeard(state, event.souls);
1156
+ if (event.capabilities !== undefined) return capabilitiesHeard(state, event.capabilities);
1157
+ if (event.capabilitiesTop !== undefined) return capabilitiesTop(state, event.capabilitiesTop);
1048
1158
  if (event.spawnRead !== undefined) return spawnRead(state, event.spawnRead);
1049
1159
  if (event.spawnDrawn !== undefined) return spawnDrawn(state, event.spawnDrawn);
1160
+ if (event.spawnTop !== undefined) return spawnTop(state, event.spawnTop);
1050
1161
  if (event.spawnProgress !== undefined) return { state: state.spawning?.phase === "submitting" ? next(state, { spawning: Object.freeze({ ...state.spawning, phase: "spawning" }) }) : state, effect: null };
1051
1162
  if (event.spawnDone !== undefined) return spawnDone(state, event.spawnDone);
1052
1163
  // An action the leader or the palette runs comes as `{ action }`, with no key: whatever field or
@@ -1073,25 +1184,21 @@ function reduced(state, event, keymap) {
1073
1184
  switch (action) {
1074
1185
  case "quit": case "suspend": case "redraw": return { state, effect: action };
1075
1186
  // In the switcher the folders of ~/Agents are listed again too.
1076
- // In the Souls view it reads the souls again, and nothing else.
1077
- case "refresh": return state.view === "souls" ? inSouls(state, action, event, page, scrolled) : { state, effect: { refresh: { live: true }, ...((state.view === "help" ? state.back : state.view) === "switcher" ? { offer: true } : {}) } };
1187
+ // In the Souls view it reads the souls again, and nothing else; in the Capabilities view, the capabilities.
1188
+ case "refresh": return state.view === "souls" ? inSouls(state, action, event, page, scrolled) : state.view === "capabilities" ? inCapabilities(state, action, event, page, scrolled) : { state, effect: { refresh: { live: true }, ...((state.view === "help" ? state.back : state.view) === "switcher" ? { offer: true } : {}) } };
1078
1189
  case "help": return { state: next(state, state.view === "help" ? { view: state.back } : { view: "help", back: state.view, helpTop: 0 }), effect: null };
1079
1190
  case "workspaces": return state.view === "switcher" ? stay : { state: toSwitcher(next(state, { back: "switcher" })), effect: { offer: true } };
1080
1191
  case "palette": return { state: paletteOpened(state, event, "list"), effect: null };
1081
1192
  // Souls and Capabilities are views of this machine, whatever workspace is open, or none.
1082
1193
  case "souls": return soulsShown(state);
1083
- case "capabilities": return { state: state.view === action ? state : next(state, { view: action, back: action }), effect: null };
1194
+ case "capabilities": return capabilitiesShown(state);
1084
1195
  // A spawn starts from the list of instances or the Souls view (the leader reaches them from anywhere).
1085
1196
  case "spawn": case "spawn-another": return state.view === "instances" || state.view === "souls" ? spawnAsked(state, event, action, spawnTarget(state)) : stay;
1086
1197
  case "spawn-check": return spawnChecked(state);
1087
1198
  default:
1088
1199
  }
1089
1200
  if (state.view === "souls") return inSouls(state, action, event, page, scrolled);
1090
- if (state.view === "capabilities") {
1091
- // Esc and 1 go back to the instances, or to the switcher when no workspace is open.
1092
- if (action !== "close" && action !== "instances") return stay;
1093
- return { state: state.open === null ? toSwitcher(next(state, { back: "switcher" })) : next(state, { view: "instances", back: "instances" }), effect: null };
1094
- }
1201
+ if (state.view === "capabilities") return inCapabilities(state, action, event, page, scrolled);
1095
1202
  if (state.view === "help") {
1096
1203
  if (action === "close") return { state: next(state, { view: state.back }), effect: null };
1097
1204
  if (action === "instances") return state.open === null ? stay : { state: next(state, { view: "instances", back: "instances" }), effect: null };
@@ -1250,6 +1357,16 @@ function spawnDrawn(state, { n, read }) {
1250
1357
  return { state: spawnWith(state, { shownIn: read }), effect: null };
1251
1358
  }
1252
1359
 
1360
+ /** The preview's window as a frame painted it (`{ n, top }`): it keeps the fold with the focus in
1361
+ * sight, so it may stand where `top` does not. Taken once for each frame painted, `top` is then
1362
+ * that window, and the movement keys go on from it, each from where the one before left it,
1363
+ * painted or not (round 1 of the polish's review). */
1364
+ function spawnTop(state, { n, top }) {
1365
+ const p = state.spawn;
1366
+ if (p === null || p.step !== "preview" || p.n !== n || !Number.isInteger(top) || top < 0 || p.top === top) return { state, effect: null };
1367
+ return { state: spawnWith(state, { top }), effect: null };
1368
+ }
1369
+
1253
1370
  /** The name field's text left as it is now: when it is not what the preview was read with, the
1254
1371
  * preview is read again. A changed choice puts away what an earlier spawn's outcome said. */
1255
1372
  function nameKept(state) {
@@ -0,0 +1,239 @@
1
+ // The Capabilities view: (model, pane) -> rows of spans, the list of the open workspace's
2
+ // capabilities in their sections and groups, and the selected capability's detail. Pure: no IO, no
3
+ // clock, no escape byte. A capability's name, its description, a group's name and note, the facts
4
+ // of where it comes from and what it provides, the names of the souls that use it, the shared words
5
+ // of the detail (lib/model.mjs passes CAPABILITY_COPY's) and a failed read's sentence are text the
6
+ // TUI did not write and go through shown(); the section titles, the separators and the few lines
7
+ // of CAPABILITIES_TEXT are the TUI's own. Nothing is told by colour alone: the selected row and the
8
+ // marked soul carry `>` as well as reverse video, a soul's colour is drawn on a mark that is there
9
+ // without it, and the souls on an older version are said so in words before their warning style.
10
+ import { lit, shown, shownLines } from "../term/text.mjs";
11
+ import { COLORS, style } from "../term/style.mjs";
12
+ import { keyLabel } from "../actions.mjs";
13
+ import { cutNote, headingRow, marksOf, measured } from "./instances.mjs";
14
+ import { windowOf } from "./scroll.mjs";
15
+ import { COUNT_SIGN, SOUL_MARK, flowed, ownLines } from "./souls.mjs";
16
+
17
+ /** The TUI's own lines in the Capabilities view. The section titles are the Desktop's own
18
+ * (renderer/workspace-catalog.mjs), word for word: the shared home holds none (Spec 7, Settled 6).
19
+ * `retry` stands after the key that reads again (tui.json may rebind it). `reading` and
20
+ * `readingSouls` end in an ellipsis, drawn `...` in ASCII. */
21
+ export const CAPABILITIES_TEXT = Object.freeze({
22
+ reading: "Reading capabilities…",
23
+ none: "This workspace offers no capabilities. `oats capabilities` says why.",
24
+ nomatch: "No capability matches the filter.",
25
+ retry: "reads them again.",
26
+ noWorkspace: "Open a workspace of this machine to see its capabilities.",
27
+ readingSouls: "Reading souls…",
28
+ sections: Object.freeze({ workspace: "Workspace owned", repo: "Repo owned", packages: "Packages" }),
29
+ });
30
+
31
+ /** The columns of the list: the selection mark, a section's title, a group's heading, a capability's name. */
32
+ const SECTION = 1, GROUP = 2, NAME = 4;
33
+ /** Where a line of the TUI's own and a failed read's sentence start in the list (views/souls.mjs). */
34
+ const SENTENCE_INDENT = 3;
35
+ /** The detail's title and headings start here: the first cell holds the mark of the pane with the
36
+ * focus (views/detail.mjs). Each section's lines are set in to INNER. */
37
+ const LEFT = 2, INNER = LEFT + 2;
38
+ /** The fewest cells a fact's value keeps beside its label: under them it goes on the row under it. */
39
+ const VALUE_MIN = 16;
40
+ /** The most rows a wrapped value or sentence takes, and the description. */
41
+ const WRAP_ROWS = 6, DESCRIPTION_ROWS = 8;
42
+
43
+ const PLAIN = style();
44
+ const BOLD = style({ bold: true });
45
+ const DIM = style({ dim: true });
46
+ const SELECTED = style({ reverse: true });
47
+ /** The warning style: what it marks says so in words too. */
48
+ const WARN = style({ bold: true, fg: "yellow" });
49
+
50
+ /** The mark between a group's name and its note, and before the instances on an older version. */
51
+ const dotOf = (ascii) => (ascii ? "-" : "·");
52
+ /** A line of the TUI's own as the screen draws it: the ellipsis is `...` in ASCII. */
53
+ const ownText = (text, ascii) => (ascii ? text.replace(/…/g, "...") : text);
54
+
55
+ /** The first key of the action `id` as the user has it, `{ text, width }`, or null when it has none. */
56
+ function keyOf(m, id) {
57
+ const action = (m.actions ?? []).find((a) => a.id === id && a.keys.length);
58
+ return action ? measured(keyLabel(action.keys[0])) : null;
59
+ }
60
+
61
+ /** Whether the list stands, beside the detail on a wide terminal: once the catalog was read (its
62
+ * rows, or none of them matching the filter), and over the rows a failed re-read kept. A body of
63
+ * one sentence (reading, a failed first read, an empty catalog, no workspace here) has the whole
64
+ * width instead. */
65
+ export function capabilitiesListed(c) {
66
+ return Boolean(c) && c.local !== false && (c.heading != null || c.state === "rows" || c.state === "nomatch" || (c.list?.length ?? 0) > 0);
67
+ }
68
+
69
+ /** Text from outside, then `after` (parts `{ text, style }` of the TUI's own or shown already, each
70
+ * `width` cells) one cell after it, from column `col` in a row ending at `end`: the text is cut
71
+ * before what follows it is, which stands whole beside what is left of it, or not at all when no
72
+ * cell of the text would be left. */
73
+ function nameThen(name, after, col, end, look) {
74
+ const afterWidth = after.reduce((sum, part) => sum + 1 + part.width, 0);
75
+ const kept = end - col > afterWidth ? after : [];
76
+ const room = end - col - (kept.length ? afterWidth : 0);
77
+ if (room <= 0) return [];
78
+ const nameWidth = Math.min(name.width, room);
79
+ const spans = [{ col, text: name.text, style: look(PLAIN), width: kept.length ? nameWidth : room }];
80
+ let at = col + nameWidth;
81
+ for (const part of kept) { at += 1; spans.push({ col: at, text: part.text, style: look(part.style), width: part.width }); at += part.width; }
82
+ return spans;
83
+ }
84
+
85
+ /** One item of the list in a pane `cols` wide: a section's title (bold), a group's heading (dim,
86
+ * `name · note`), or a capability: the selection mark, its name, and its layer's label dim when it
87
+ * has one. One cell is kept at the right edge. */
88
+ function itemRow(item, cols, ascii) {
89
+ const end = cols - 1;
90
+ if (item.section !== undefined) {
91
+ const title = CAPABILITIES_TEXT.sections[item.section];
92
+ return [{ col: SECTION, text: lit(title), style: BOLD, width: Math.max(0, Math.min(title.length, end - SECTION)) }];
93
+ }
94
+ if (item.group !== undefined) {
95
+ const name = measured(item.group), note = item.note ? measured(item.note) : null;
96
+ const spans = [{ col: GROUP, text: name.text, style: DIM, width: Math.max(0, Math.min(name.width, end - GROUP)) }];
97
+ const at = GROUP + name.width;
98
+ if (note && at + 3 < end) spans.push({ col: at + 1, text: lit(dotOf(ascii)), style: DIM, width: 1 }, { col: at + 3, text: note.text, style: DIM, width: Math.max(0, end - at - 3) });
99
+ return spans.filter((span) => span.width > 0);
100
+ }
101
+ const look = (own) => (item.selected ? SELECTED : own);
102
+ const spans = item.selected ? [{ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(marksOf(ascii).selected), style: SELECTED, width: 1 }] : [];
103
+ const layer = item.layer ? measured(item.layer) : null;
104
+ return [...spans, ...nameThen(measured(item.name), layer ? [{ text: layer.text, width: layer.width, style: DIM }] : [], NAME, end, look)];
105
+ }
106
+
107
+ /** `size.rows` rows for the list pane, `size.cols` wide: the model's window of the sections, the
108
+ * groups and the capabilities (after the heading of a failed re-read, when there is one) and on
109
+ * the last row what is cut off; or the one body the catalog's state gives: reading, a failed first
110
+ * read (its sentence, then the key that reads again), an empty catalog, nothing matching the
111
+ * filter, no workspace of this machine. */
112
+ export function capabilitiesList(m, size) {
113
+ const c = m.capabilities, ascii = m.ascii;
114
+ const rows = Array.from({ length: size.rows }, () => []);
115
+ if (size.rows < 1 || !c) return rows;
116
+ const width = Math.max(0, size.cols - SENTENCE_INDENT - 1);
117
+ /** A line of the TUI's own, dim, from row `at` on: the rows it took. */
118
+ const own = (text, at) => {
119
+ const lines = ownLines(ownText(text, ascii), width).slice(0, Math.max(0, size.rows - at));
120
+ lines.forEach((line, i) => { rows[at + i] = [{ col: SENTENCE_INDENT, text: lit(line), style: DIM, width }]; });
121
+ return lines.length;
122
+ };
123
+ if (c.local === false) { own(CAPABILITIES_TEXT.noWorkspace, 0); return rows; }
124
+ if (!capabilitiesListed(c)) {
125
+ if (c.state === "failed") {
126
+ // The sentence from outside, whole where the rows allow, and under it the key that reads again.
127
+ const retry = keyOf(m, "refresh");
128
+ const lines = shownLines(c.failure, width, Math.max(1, size.rows - (retry ? 1 : 0)), { ascii });
129
+ lines.forEach((line, i) => { rows[i] = [{ col: SENTENCE_INDENT, text: line, width }]; });
130
+ if (retry && lines.length < size.rows) {
131
+ const at = lines.length, words = SENTENCE_INDENT + retry.width + 1;
132
+ rows[at] = [{ col: SENTENCE_INDENT, text: retry.text, style: BOLD, width: Math.min(retry.width, width) },
133
+ ...(words < size.cols - 1 ? [{ col: words, text: lit(CAPABILITIES_TEXT.retry), style: DIM, width: size.cols - 1 - words }] : [])];
134
+ }
135
+ } else own(c.state === "none" ? CAPABILITIES_TEXT.none : CAPABILITIES_TEXT.reading, 0);
136
+ return rows;
137
+ }
138
+ let at = 0;
139
+ if (c.heading) rows[at++] = headingRow(c.heading, size.cols, ascii);
140
+ if (c.state === "none" || c.state === "nomatch") own(CAPABILITIES_TEXT[c.state], at);
141
+ else c.list.forEach((item, i) => { if (at + i < size.rows) rows[at + i] = itemRow(item, size.cols, ascii); });
142
+ const note = cutNote(c.above ?? 0, c.below ?? 0);
143
+ if (note) rows[size.rows - 1] = [{ col: SENTENCE_INDENT, text: lit(note), style: DIM, width: Math.max(0, size.cols - SENTENCE_INDENT) }];
144
+ return rows;
145
+ }
146
+
147
+ /** `{ rows, mark }`: every row of the selected capability's detail for a pane `cols` wide, before it
148
+ * is scrolled, and the row of the marked soul of "Used by" (-1 when none is marked). Top to bottom:
149
+ * the name and its layer's label, a failed re-read's sentence (in the warning style; it says so in
150
+ * words), the description; where it comes from (each fact `label value`); what it provides (each
151
+ * kind its names, flowed, or the shared word for none or not listable); and the souls that use it,
152
+ * eight at most and then `+n`, each its colour mark, its name, a dim count of its instances that
153
+ * carry it and how many of those are on an older version. A section with nothing to say is left out. */
154
+ export function capabilityDetailRows(m, cols) {
155
+ const d = m.capabilities?.detail;
156
+ if (!d) return { rows: [], mark: -1 };
157
+ const ascii = m.ascii, wide = Math.max(0, cols - LEFT), inner = Math.max(0, cols - INNER);
158
+ const label = (text, col = LEFT) => { const t = measured(text); return { col, text: t.text, style: DIM, width: Math.max(0, Math.min(t.width, cols - col)) }; };
159
+ const layer = d.layer ? measured(d.layer) : null;
160
+ const rows = [nameThen(measured(d.name), layer ? [{ text: layer.text, width: layer.width, style: DIM }] : [], LEFT, cols, (own) => (own === PLAIN ? BOLD : own))];
161
+ /** Safe lines placed at `col`, each `width` cells, the first beside `first` when given. */
162
+ const lines = (list, col, width, look, first = null) => list.forEach((line, i) => rows.push([...(i === 0 && first ? [first] : []), { col, text: line, width, ...(look ? { style: look } : {}) }]));
163
+ /** Facts `{ label, value }` under a section's heading: the labels in a column of their own, and
164
+ * each value beside its label, wrapped, or under it when the column leaves too few cells (and
165
+ * none at all in a pane with no cell for it). */
166
+ const facts = (list, value) => {
167
+ const names = list.map((fact) => measured(fact.label));
168
+ const column = Math.max(0, ...names.map((name) => name.width));
169
+ const beside = inner - column - 2 >= VALUE_MIN;
170
+ list.forEach((fact, i) => {
171
+ const name = { col: INNER, text: names[i].text, style: DIM, width: Math.min(names[i].width, inner) };
172
+ if (beside) value(fact, INNER + column + 2, inner - column - 2, name);
173
+ else { rows.push([name]); if (inner - 2 >= 1) value(fact, INNER + 2, inner - 2, null); }
174
+ });
175
+ };
176
+ const blank = () => rows.push([]);
177
+
178
+ if (d.failure) lines(shownLines(d.failure, wide, WRAP_ROWS, { ascii }), LEFT, wide, WARN);
179
+ lines(shownLines(d.description, wide, DESCRIPTION_ROWS, { ascii }), LEFT, wide);
180
+
181
+ if (d.comesFrom.length) {
182
+ blank();
183
+ rows.push([label(d.words.comesFrom)]);
184
+ facts(d.comesFrom, (fact, col, width, name) => lines(shownLines(fact.value, width, WRAP_ROWS, { ascii }), col, width, null, name));
185
+ }
186
+
187
+ if (d.provides.length) {
188
+ blank();
189
+ rows.push([label(d.words.provides)]);
190
+ const comma = { text: lit(","), width: 1, glue: true };
191
+ facts(d.provides, (kind, col, width, name) => {
192
+ if (kind.said) { lines(shownLines(kind.said, width, WRAP_ROWS, { ascii }), col, width, DIM, name); return; }
193
+ const set = width < 1 ? [] : flowed(kind.names.map((each, i, all) => [measured(each), ...(i < all.length - 1 ? [comma] : [])]), width);
194
+ if (!set.length) { if (name) rows.push([name]); return; }
195
+ set.forEach((spans, i) => rows.push([...(i === 0 && name ? [name] : []), ...spans.map((span) => ({ ...span, col: span.col + col }))]));
196
+ });
197
+ }
198
+
199
+ const u = d.used;
200
+ blank();
201
+ const count = u.count ? measured(u.count) : null, heading = label(d.words.usedBy);
202
+ rows.push([heading, ...(count && LEFT + heading.width + 2 < cols ? [{ col: LEFT + heading.width + 2, text: count.text, style: DIM, width: Math.max(0, Math.min(count.width, cols - LEFT - heading.width - 2)) }] : [])]);
203
+ let mark = -1;
204
+ if (u.state === "reading") lines([lit(ownText(CAPABILITIES_TEXT.readingSouls, ascii))], INNER, inner, DIM);
205
+ else if (u.state === "failed") lines(shownLines(u.failure, inner, WRAP_ROWS, { ascii }), INNER, inner, WARN);
206
+ else if (u.empty) lines(shownLines(u.empty, inner, WRAP_ROWS, { ascii }), INNER, inner, DIM);
207
+ const sign = ascii ? COUNT_SIGN.ascii : COUNT_SIGN.utf8, soulMark = ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8, end = cols - 1;
208
+ u.shown.forEach((user, i) => {
209
+ const marked = i === m.capabilities.mark;
210
+ if (marked) mark = rows.length;
211
+ const look = (own) => (marked ? SELECTED : own);
212
+ const colour = typeof user.color === "string" && COLORS.includes(user.color) ? user.color : null;
213
+ const spans = marked ? [{ col: LEFT, width: Math.max(0, cols - LEFT), style: SELECTED }, { col: LEFT, text: lit(">"), style: SELECTED, width: 1 }] : [];
214
+ spans.push({ col: INNER, text: lit(soulMark), style: look(colour ? style({ fg: colour }) : PLAIN), width: 1 });
215
+ const counted = `${sign}${user.count}`;
216
+ const after = [{ text: lit(counted), width: counted.length, style: DIM }];
217
+ if (user.behind) { const behind = measured(user.behind); after.push({ text: lit(dotOf(ascii)), width: 1, style: DIM }, { text: behind.text, width: behind.width, style: WARN }); }
218
+ rows.push([...spans, ...nameThen(measured(user.name), after, INNER + 2, end, look)]);
219
+ });
220
+ if (u.more > 0) rows.push([{ col: INNER, text: lit(`+${u.more}`), style: DIM, width: `+${u.more}`.length }]);
221
+ return { rows, mark };
222
+ }
223
+
224
+ /** `{ rows, extent, top }`: `size.rows` rows of the detail for a pane `size.cols` wide, scrolled to
225
+ * the model's `detailTop`, or the least from there that shows the marked soul while the detail was
226
+ * not scrolled away from it (`keep`); how many rows the whole detail has; and the row it was drawn
227
+ * from, which the loop gives the store. The pane with the focus says so with `>` beside the title,
228
+ * never by an attribute alone (views/detail.mjs). */
229
+ export function capabilityDetail(m, size) {
230
+ const { rows: all, mark } = capabilityDetailRows(m, size.cols);
231
+ const rows = Array.from({ length: size.rows }, () => []);
232
+ const c = m.capabilities;
233
+ const win = windowOf({ top: c?.detailTop ?? 0, count: all.length, height: size.rows, keep: c?.keep && mark >= 0 ? mark : -1 });
234
+ all.slice(win.top, win.top + win.size).forEach((spans, i) => { rows[i] = spans; });
235
+ const note = cutNote(win.above, win.below);
236
+ if (note && size.rows > 0) rows[size.rows - 1] = [{ col: LEFT, text: lit(note), style: DIM, width: Math.max(0, size.cols - LEFT) }];
237
+ if (c?.focus === "detail" && size.rows > 0 && all.length) rows[0] = [{ col: 0, text: lit(">"), style: BOLD, width: 1 }, ...rows[0]];
238
+ return { rows, extent: all.length, top: win.top };
239
+ }