@awebai/oats 0.57.1 → 0.59.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 (61) hide show
  1. package/bin/oats.mjs +24 -11
  2. package/docs/configuration.md +2 -1
  3. package/docs/desktop-cli-api.md +105 -17
  4. package/docs/desktop.md +30 -3
  5. package/docs/execution-targets.md +15 -0
  6. package/docs/implementation.md +2 -0
  7. package/docs/integrations.md +2 -2
  8. package/docs/knowledge.md +4 -4
  9. package/docs/official-catalog.md +4 -4
  10. package/docs/packages.md +14 -14
  11. package/docs/release-notes/v0.58.0.md +107 -0
  12. package/docs/release-notes/v0.59.0.md +288 -0
  13. package/docs/servers.md +4 -1
  14. package/docs/souls-and-instances.md +30 -0
  15. package/docs/tui.md +653 -117
  16. package/docs/workspaces.md +2 -2
  17. package/lib/core.mjs +227 -46
  18. package/lib/read-ahead-worker.mjs +119 -0
  19. package/lib/read-ahead.mjs +115 -0
  20. package/lib/retire-state.mjs +33 -0
  21. package/lib/servers.mjs +9 -1
  22. package/lib/session-input.mjs +14 -4
  23. package/package-catalog.json +3 -3
  24. package/package.json +1 -1
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/deployment-data.mjs +4 -0
  27. package/packages/client/deployment-panel.mjs +3 -0
  28. package/packages/client/instance-acts.mjs +23 -8
  29. package/packages/client/instance-presentation.mjs +3 -2
  30. package/packages/client/instance-tree.mjs +84 -39
  31. package/packages/client/lifecycle-confirmation.mjs +9 -3
  32. package/packages/client/panel-views.mjs +1 -1
  33. package/packages/client/remote-roster.mjs +4 -1
  34. package/packages/client/retire-in-flight.mjs +65 -0
  35. package/packages/client/retire-state.mjs +30 -0
  36. package/packages/client/spawn-apply-cli.mjs +8 -2
  37. package/packages/client/spawn-apply.mjs +20 -7
  38. package/packages/client/spawn-preview-cli.mjs +2 -1
  39. package/packages/client/spawn-preview.mjs +30 -18
  40. package/packages/record/lib/directory-identity.mjs +14 -0
  41. package/packages/record/lib/native-history.mjs +6 -5
  42. package/packages/tui/README.md +23 -10
  43. package/packages/tui/lib/actions.mjs +63 -5
  44. package/packages/tui/lib/client.mjs +12 -1
  45. package/packages/tui/lib/config.mjs +7 -2
  46. package/packages/tui/lib/main.mjs +315 -82
  47. package/packages/tui/lib/model.mjs +523 -56
  48. package/packages/tui/lib/panel.mjs +519 -144
  49. package/packages/tui/lib/read.mjs +52 -26
  50. package/packages/tui/lib/store.mjs +908 -65
  51. package/packages/tui/lib/term/keys.mjs +9 -2
  52. package/packages/tui/lib/term/text.mjs +4 -0
  53. package/packages/tui/lib/term/through.mjs +12 -1
  54. package/packages/tui/lib/views/frame.mjs +394 -95
  55. package/packages/tui/lib/views/help.mjs +54 -13
  56. package/packages/tui/lib/views/instances.mjs +43 -25
  57. package/packages/tui/lib/views/palette.mjs +61 -0
  58. package/packages/tui/lib/views/souls.mjs +268 -0
  59. package/packages/tui/lib/views/spawn.mjs +299 -0
  60. package/packages/tui/lib/views/split.mjs +29 -0
  61. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -2,8 +2,8 @@
2
2
  // text. Pure: no IO, no clock, no escape byte. The keys are generated from the table the reducer
3
3
  // acts on, so the help names every key that does something and no key that does not; the marks
4
4
  // are the ones the list and the switcher draw (views/instances.mjs, views/switcher.mjs).
5
- import { keyLabel } from "../actions.mjs";
6
- import { lit } from "../term/text.mjs";
5
+ import { LEADER, keyLabel } from "../actions.mjs";
6
+ import { lit, ownEllipsis } from "../term/text.mjs";
7
7
  import { style } from "../term/style.mjs";
8
8
  import { cutNote, marksOf, measured } from "./instances.mjs";
9
9
  import { windowOf } from "./scroll.mjs";
@@ -29,6 +29,10 @@ export function keyText(label) {
29
29
  * kernel's own usage, so the help cannot name a command that does not exist. A later version
30
30
  * removes a line when it adds the act. */
31
31
  export const NOT_YET = Object.freeze([
32
+ // The spawn prompt (n, N) spawns on this machine, with the launch the soul and this machine
33
+ // choose, and no task: the rest is the kernel's command's (run on that machine for another).
34
+ Object.freeze({ what: "spawn on another machine", command: "oats spawn <soul>" }),
35
+ Object.freeze({ what: "spawn with a harness, model or task", command: "oats spawn <soul>" }),
32
36
  Object.freeze({ what: "open an agent in its own tmux window", command: "oats session attach --home <home>" }),
33
37
  Object.freeze({ what: "start with another harness or model", command: "oats session start --home <home>" }),
34
38
  Object.freeze({ what: "add a machine to this workspace", command: "oats server connect <id> --ssh <alias>" }),
@@ -44,10 +48,11 @@ export const MACHINES = Object.freeze([
44
48
  "Nothing is kept on disk: a machine not reached in this run is listed by its own name.",
45
49
  "Souls and Capabilities, when they come, are this machine's.",
46
50
  ]);
47
- /** The views the frame names, and for the two that cannot be opened yet, what to run instead. */
51
+ /** The views the frame names, what each holds, and what to run for what a view does not do yet:
52
+ * Capabilities is not built. The Souls view spawns an agent of the selected soul (n, N). */
48
53
  export const VIEWS = Object.freeze([
49
54
  Object.freeze({ name: "1 Instances", what: "the instances of the open workspace", commands: Object.freeze([]) }),
50
- Object.freeze({ name: "2 Souls", what: "not in this version", commands: Object.freeze(["oats souls", "oats spawn <soul>"]) }),
55
+ Object.freeze({ name: "2 Souls", what: "the souls of the open workspace and their detail, i their instances, n an agent of the selected soul", commands: Object.freeze([]) }),
51
56
  Object.freeze({ name: "3 Capabilities", what: "not in this version", commands: Object.freeze(["oats capabilities"]) }),
52
57
  ]);
53
58
 
@@ -86,14 +91,14 @@ function table(pairs, cols, look) {
86
91
  * does not restate the grammar). */
87
92
  export const OPEN_RULES = Object.freeze([
88
93
  "While the terminal has the focus every other key goes to the agent, Ctrl+C and Ctrl+Z too.",
89
- "One terminal is open at a time. It has no scrollback but the viewer's own, and no mouse.",
90
- "docs/tui.md has the keys that can be the back key.",
94
+ "Up to 4 terminals are open at a time, each a tab. They have no scrollback but the viewer's own, and no mouse.",
95
+ "docs/tui.md has the keys that can be the leader.",
91
96
  ]);
92
- /** The rows under the line of `open`, in `room` cells: the back key, which takes the focus from the
93
- * open terminal (tui.json's open.detachKey, text from outside), then OPEN_RULES, each sentence on
94
- * as many rows as it needs. */
97
+ /** The rows under the line of `open`, in `room` cells: the leader pressed twice, which takes the
98
+ * focus from the open terminal (tui.json's open.detachKey, text from outside), then OPEN_RULES,
99
+ * each sentence on as many rows as it needs. */
95
100
  function openRows(detachKey, room) {
96
- const key = keyText(detachKey), said = "takes the focus from the terminal back to the list; the agent keeps running.";
101
+ const key = keyText(`${detachKey} ${detachKey}`), said = "takes the focus from the terminal back to the list; the agent keeps running.";
97
102
  const first = flow(words(said), Math.max(1, room - key.width - 1));
98
103
  return [
99
104
  [{ col: 0, text: key.text, width: key.width }, { col: key.width + 1, text: lit(first[0]) }],
@@ -116,11 +121,44 @@ const sentences = (list, cols) => list.flatMap((sentence) => {
116
121
  return [first, ...flow(rest.flatMap(words), cols - 2 * INDENT - 2)].map((text, i) => [{ col: INDENT + (i ? 2 : 0), text: lit(text) }]);
117
122
  });
118
123
 
124
+ /** The leader's rows (docs/tui.md, "The leader"): its key, then the table of what each key after
125
+ * it does (actions.mjs LEADER), from every focus. */
126
+ function leaderRows(detachKey, cols) {
127
+ const key = keyText(detachKey);
128
+ // The sentence after the key on as many rows as it needs, its later rows under its first.
129
+ const at = INDENT + key.width + 1;
130
+ const lead = flow(words("then one of these keys, from every focus; a terminal too:"), Math.max(1, cols - INDENT - at));
131
+ return [
132
+ [{ col: INDENT, text: lit("The leader"), style: TITLE }],
133
+ [],
134
+ [{ col: INDENT, text: key.text, width: key.width, style: KEYS }, { col: at, text: lit(lead[0]) }],
135
+ ...lead.slice(1).map((text) => [{ col: at, text: lit(text) }]),
136
+ ...table(LEADER.map((entry) => [entry.keys.map(keyLabel).join(", "),
137
+ words(entry.does === "list" ? `${entry.label}; the leader again does the same` : entry.terminal ? `${entry.label}, while a terminal is open` : entry.label)]), cols, KEYS),
138
+ ];
139
+ }
140
+
141
+ /** The spawn prompt's keys (docs/tui.md, "Spawning an agent"): the prompt reads its keys itself, as
142
+ * the palette does, so they are fixed and the TUI's words. Each step's keys, then the paste guard. */
143
+ export const SPAWN_KEYS = Object.freeze([
144
+ Object.freeze(["Up, Down", "move in the soul picker; typing narrows it"]),
145
+ Object.freeze(["Enter", "pick the selected soul; a soul marked ! would be refused here and cannot be picked"]),
146
+ Object.freeze(["Esc", "close the soul picker"]),
147
+ Object.freeze(["Tab, Shift+Tab", "move the focus in the preview: Spawn, name, child of, then each fold"]),
148
+ Object.freeze(["Enter", "do what the footer names: on Spawn spawn, on name keep the name and read the preview again, on child of switch it, on a fold open or close it"]),
149
+ Object.freeze(["Esc", "from a field back to Spawn; from Spawn back to the picker, or to the list"]),
150
+ ]);
151
+ export const SPAWN_RULES = Object.freeze([
152
+ "Enter spawns only once the preview on the screen is the one for the choices shown, read after it was first drawn: a paste cannot spawn.",
153
+ ]);
154
+ const spawnRows = (cols) => [heading("The spawn prompt"), [], ...table(SPAWN_KEYS.map(([keys, said]) => [keys, words(said)]), cols, KEYS), ...sentences(SPAWN_RULES, cols)];
155
+
119
156
  /** Every row of the help for an area `cols` wide, before it is scrolled. Unbound actions are
120
157
  * listed as such: the table can be changed by the user's tui.json, and the help says what is so
121
158
  * now. An action that does one thing in each view has a line per view, its key on each; under
122
159
  * the line of opening an agent stand the back key (`detachKey`, tui.json's `open.detachKey`) and
123
- * the rules of OPEN_RULES; under the line of the last act, ACT_RULES. */
160
+ * the rules of OPEN_RULES; under the line of the last act, ACT_RULES. After the leader's table,
161
+ * the spawn prompt's keys (SPAWN_KEYS, SPAWN_RULES). */
124
162
  export function helpRows(actions, ascii, cols = 100, detachKey = null) {
125
163
  const marks = marksOf(ascii);
126
164
  const closing = keyText(["close", "help"].map((id) => actions.find((action) => action.id === id)).filter((action) => action?.keys.length).map((action) => keyLabel(action.keys[0])).join(" or "));
@@ -133,6 +171,9 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null) {
133
171
  return action.views.map(([view, said]) => [left, words(said), action.id === "open" && view === "instances" && detachKey !== null ? (room) => openRows(detachKey, room)
134
172
  : action.id === "restart" ? actRows : undefined]);
135
173
  }), cols, KEYS),
174
+ ...(detachKey !== null ? [[], ...leaderRows(detachKey, cols)] : []),
175
+ [],
176
+ ...spawnRows(cols),
136
177
  [],
137
178
  heading("Marks"),
138
179
  [],
@@ -141,8 +182,8 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null) {
141
182
  [marks.stopped, "stopped"],
142
183
  [marks.shell, "stopped, with a shell left in its terminal"],
143
184
  [marks.unknown, "state unknown"],
144
- [marks.held, "held by a spawn or a retire that is not finished"],
145
- [`${marks.open} ${marks.closed}`, "has instances below it: shown, folded away"],
185
+ [marks.held, ownEllipsis("held by a spawn or a retire: under way (Retiring\u2026), failed or not finished", ascii)],
186
+ ["+N", "N instances folded away below it"],
146
187
  [marks.waiting, "needs input"],
147
188
  [`${marks.waiting}N`, "N instances folded away below it need input"],
148
189
  [marks.selected, "the selected row, and the pane the movement keys act on"],
@@ -2,18 +2,21 @@
2
2
  // Every name, word and reason in it is text the TUI did not write and goes through shown(); the
3
3
  // marks and the few words around them are the TUI's own. Nothing is told by colour alone: each
4
4
  // state has a mark of its own shape, the selected row carries `>` as well as reverse video, and a
5
- // waiting row carries `!`. In a view of two or more deployments the list also holds a heading per
6
- // deployment and the sentences the model sets under one: a heading says in words what it is of.
5
+ // waiting row carries `!`. A row is quiet: its mark and its name, and a word only where the mark
6
+ // can't say it. Children stand under their parent by indentation alone; a folded row says how
7
+ // many it folds away, `+n`. In a view of two or more deployments the list also holds a heading
8
+ // per deployment and the sentences the model sets under one: a heading says in words what it is
9
+ // of.
7
10
  import { lit, shown, shownEnd, textOf } from "../term/text.mjs";
8
11
  import { style } from "../term/style.mjs";
9
12
  import { textWidth } from "../term/width.mjs";
10
13
 
11
14
  /** The marks, in UTF-8 and in ASCII (docs/tui.md lists them; the help view draws them from here).
12
15
  * The state marks are keyed by the word the shared home gives a row's state, with `shell` and
13
- * `held` beside them (lib/model.mjs says when). */
16
+ * `held` beside them (lib/model.mjs says when). A fold has no mark: a folded row shows `+n`. */
14
17
  export const MARKS = Object.freeze({
15
- utf8: Object.freeze({ running: "●", stopped: "○", shell: "◌", unknown: "?", held: "◆", open: "▾", closed: "▸", selected: ">", waiting: "!" }),
16
- ascii: Object.freeze({ running: "*", stopped: "-", shell: "~", unknown: "?", held: "#", open: "v", closed: ">", selected: ">", waiting: "!" }),
18
+ utf8: Object.freeze({ running: "●", stopped: "○", shell: "◌", unknown: "?", held: "◆", selected: ">", waiting: "!" }),
19
+ ascii: Object.freeze({ running: "*", stopped: "-", shell: "~", unknown: "?", held: "#", selected: ">", waiting: "!" }),
17
20
  });
18
21
  export const marksOf = (ascii) => (ascii ? MARKS.ascii : MARKS.utf8);
19
22
 
@@ -21,9 +24,10 @@ export const marksOf = (ascii) => (ascii ? MARKS.ascii : MARKS.utf8);
21
24
  const INDENT = 2, LEVELS = 6;
22
25
  /** The cells kept at the right edge for the waiting mark: `!`, `!N`, `!NN`, `!99+`. */
23
26
  const WAITING = 4;
24
- /** A row's cells before its name: the selection mark, a gap, the disclosure mark, a gap, the
25
- * state mark, a gap. */
26
- const LEAD = 5;
27
+ /** A row's cells before its name: the selection mark, a gap, the state mark, a gap. */
28
+ const LEAD = 4;
29
+ /** The column of the state mark, before a row's indent. */
30
+ const MARK = 2;
27
31
 
28
32
  /** A heading starts here: at the margin the header and the footer keep, not at a row's indent. */
29
33
  const HEAD = 1;
@@ -32,15 +36,17 @@ const GAP = 2;
32
36
  /** The fewest cells a heading's short reason or its path is drawn in when it is cut: under them
33
37
  * it is left out, since a few cells of either say nothing. */
34
38
  const PART_MIN = 8;
35
- /** Where a sentence inside the list starts. The model wraps a sentence for a pane less this
36
- * indent and one cell (lib/model.mjs SENTENCE_INDENT, which a view cannot import): the same value. */
39
+ /** Where a sentence inside the list starts, and the line that says why no instance is listed or
40
+ * what is cut off. The model wraps a sentence for a pane less this indent and one cell
41
+ * (lib/model.mjs SENTENCE_INDENT, which a view cannot import): the same value. */
37
42
  const SENTENCE_INDENT = 3;
38
43
 
39
44
  const PLAIN = style();
40
45
  const BOLD = style({ bold: true });
41
46
  const DIM = style({ dim: true });
42
47
  const SELECTED = style({ reverse: true });
43
- const LOOK = Object.freeze({ running: style({ fg: "green" }), stopped: DIM, shell: DIM, unknown: style({ fg: "yellow" }), held: style({ fg: "magenta" }) });
48
+ /** The look of each state mark: the Souls view draws an instance's mark in its detail as the list does. */
49
+ export const LOOK = Object.freeze({ running: style({ fg: "green" }), stopped: DIM, shell: DIM, unknown: style({ fg: "yellow" }), held: style({ fg: "magenta" }) });
44
50
  const WAITS = style({ fg: "yellow", bold: true });
45
51
  const WAITS_SELECTED = style({ reverse: true, bold: true });
46
52
 
@@ -59,20 +65,30 @@ export function measured(value) {
59
65
 
60
66
  const waitingText = (row) => (row.below > 99 ? "!99+" : row.below > 0 ? `!${row.below}` : row.waiting ? "!" : null);
61
67
 
62
- /** One instance's row in a pane `cols` wide: the marks, the name cut to what is left, the state
63
- * word in its column and the waiting mark at the edge. Every span has its width, so no text can
64
- * pass its column whatever the terminal thinks a character takes. */
68
+ /** One instance's row in a pane `cols` wide: the state mark, the name cut to what is left, on a
69
+ * folded row `+n` after the name, the row's word (when it has one) in the word column, and the
70
+ * waiting mark at the edge. A row with no word gives its name the word column's cells too. The
71
+ * name is cut before `+n` is: the count stays whole beside what is left of the name. Every span
72
+ * has its width, so no text can pass its column whatever the terminal thinks a character takes. */
65
73
  function instanceRow(row, cols, wordWidth, marks) {
66
74
  const look = (own) => (row.selected ? SELECTED : own);
67
75
  const at = Math.min(row.depth, LEVELS - 1) * INDENT;
76
+ const worded = wordWidth > 0 && row.word !== null && row.word !== undefined;
68
77
  const wordCol = Math.max(0, cols - WAITING - 1 - wordWidth);
69
- const nameCol = LEAD + at;
78
+ const nameCol = LEAD + at, nameEnd = worded ? wordCol - 2 : cols - WAITING - 1;
79
+ const fold = row.folded > 0 ? `+${row.folded}` : null;
70
80
  const spans = [];
71
81
  if (row.selected) spans.push({ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(marks.selected), style: SELECTED, width: 1 });
72
- if (row.disclosure) spans.push({ col: 1 + at, text: lit(marks[row.disclosure]), style: look(PLAIN), width: 1 });
73
- spans.push({ col: 3 + at, text: lit(marks[row.mark] ?? marks.unknown), style: look(LOOK[row.mark] ?? LOOK.unknown), width: 1 });
74
- if (wordCol - 2 > nameCol) spans.push({ col: nameCol, text: shown(row.name), style: look(PLAIN), width: wordCol - 2 - nameCol });
75
- if (wordWidth > 0) spans.push({ col: wordCol, text: shown(row.word), style: look(DIM), width: wordWidth });
82
+ spans.push({ col: MARK + at, text: lit(marks[row.mark] ?? marks.unknown), style: look(LOOK[row.mark] ?? LOOK.unknown), width: 1 });
83
+ if (nameEnd > nameCol) {
84
+ const name = measured(row.name);
85
+ // The count and the gap before it, when there is room for them and for a cell of the name.
86
+ const after = fold && nameEnd - nameCol > fold.length + 1 ? fold.length + 1 : 0;
87
+ const nameWidth = Math.min(name.width, nameEnd - nameCol - after);
88
+ spans.push({ col: nameCol, text: name.text, style: look(PLAIN), width: after ? nameWidth : nameEnd - nameCol });
89
+ if (after) spans.push({ col: nameCol + nameWidth + 1, text: lit(fold), style: look(DIM), width: fold.length });
90
+ }
91
+ if (worded) spans.push({ col: wordCol, text: shown(row.word), style: look(DIM), width: wordWidth });
76
92
  const waits = waitingText(row);
77
93
  if (waits) spans.push({ col: cols - waits.length, text: lit(waits), style: row.selected ? WAITS_SELECTED : WAITS, width: waits.length });
78
94
  return spans;
@@ -82,8 +98,10 @@ function instanceRow(row, cols, wordWidth, marks) {
82
98
  * live, the shared word for its state and the short reason; at the right edge the time a machine
83
99
  * reported its rows at. The state and the time always stand. When the row is too narrow for the
84
100
  * rest, the path is given up first, then the short reason, and then the label is cut: the full
85
- * reason is in the detail of each of its rows, and under the heading when it has none. */
86
- function headingRow({ label, path, state, short, readAt }, cols, ascii) {
101
+ * reason is in the detail of each of its rows, and under the heading when it has none. A short
102
+ * reason with no state word is drawn too: the Souls view's heading of a failed re-read has a
103
+ * sentence and no shared word for a state (views/souls.mjs). */
104
+ export function headingRow({ label, path, state, short, readAt }, cols, ascii) {
87
105
  const spans = [], edge = cols - 1;
88
106
  let limit = edge;
89
107
  if (readAt) {
@@ -91,7 +109,7 @@ function headingRow({ label, path, state, short, readAt }, cols, ascii) {
91
109
  spans.push({ col, text: lit(read), style: DIM, width: Math.max(0, Math.min(read.length, edge - col)) });
92
110
  limit = col - GAP;
93
111
  }
94
- const name = measured(label), word = state ? measured(state) : null, why = state && short ? measured(short) : null, where = path ? measured(path) : null;
112
+ const name = measured(label), word = state ? measured(state) : null, why = short ? measured(short) : null, where = path ? measured(path) : null;
95
113
  let room = limit - HEAD - (word ? GAP + word.width : 0);
96
114
  const nameWidth = Math.max(0, Math.min(name.width, room));
97
115
  room -= nameWidth;
@@ -122,16 +140,16 @@ export function instances(m, size) {
122
140
  const rows = Array.from({ length: size.rows }, () => []);
123
141
  if (size.rows < 1) return rows;
124
142
  const marks = marksOf(m.ascii);
125
- const aside = Math.max(0, size.cols - LEAD + 2), sentence = Math.max(0, size.cols - SENTENCE_INDENT - 1);
143
+ const aside = Math.max(0, size.cols - SENTENCE_INDENT), sentence = Math.max(0, size.cols - SENTENCE_INDENT - 1);
126
144
  m.list.forEach((item, i) => {
127
145
  if (!item || i >= size.rows) return;
128
146
  if (item.heading) rows[i] = headingRow(item.heading, size.cols, m.ascii);
129
147
  else if (item.line) rows[i] = [{ col: SENTENCE_INDENT, text: item.line, width: sentence }];
130
148
  else if (item.own) rows[i] = [{ col: SENTENCE_INDENT, text: lit(item.own), style: DIM, width: sentence }];
131
- else if (item.empty) rows[i] = [{ col: LEAD - 2, text: lit(EMPTY_TEXT[item.empty]), style: DIM, width: aside }];
149
+ else if (item.empty) rows[i] = [{ col: SENTENCE_INDENT, text: lit(EMPTY_TEXT[item.empty]), style: DIM, width: aside }];
132
150
  else rows[i] = instanceRow(item, size.cols, m.wordWidth, marks);
133
151
  });
134
152
  const note = cutNote(m.above, m.below);
135
- if (note) rows[size.rows - 1] = [{ col: LEAD - 2, text: lit(note), style: DIM, width: aside }];
153
+ if (note) rows[size.rows - 1] = [{ col: SENTENCE_INDENT, text: lit(note), style: DIM, width: aside }];
136
154
  return rows;
137
155
  }
@@ -0,0 +1,61 @@
1
+ // The palette (docs/tui.md, "The palette"): (model, area) -> rows of spans, over the whole body.
2
+ // Pure: no IO, no clock, no escape byte. One input over a list: the query on the first row, then
3
+ // the window of the rows lib/model.mjs paletteItems lists, the selected one in reverse with `>`.
4
+ // An instance's or a soul's name, a machine and the query are text the TUI did not write and go
5
+ // through shown(); the labels of the views, the acts and the commands are the TUI's own. Nothing
6
+ // is told by colour alone: each row says in a word what kind it is.
7
+ import { lit, shown } from "../term/text.mjs";
8
+ import { style } from "../term/style.mjs";
9
+ import { cutNote, marksOf, measured } from "./instances.mjs";
10
+
11
+ /** The query's prompt, and the cells it takes with the gap after it. */
12
+ const PROMPT = ">", PROMPT_CELLS = 2;
13
+ /** The cells a row's text starts at: the selection mark, a gap, an instance's state mark, a gap. */
14
+ const LEAD = 4;
15
+ /** The word at a row's right edge that says what it is. */
16
+ const KINDS = Object.freeze({ instance: "instance", soul: "soul", view: "view", act: "act", command: "command" });
17
+ /** The TUI's word before another machine's name. */
18
+ const ON = "on";
19
+
20
+ const BOLD = style({ bold: true });
21
+ const DIM = style({ dim: true });
22
+ const SELECTED = style({ reverse: true });
23
+ const PLAIN = style();
24
+
25
+ /** One row of the palette in `cols` cells. */
26
+ function itemRow(item, cols, marks) {
27
+ const look = (own) => (item.selected ? SELECTED : own);
28
+ const kind = KINDS[item.kind], kindCol = Math.max(LEAD, cols - kind.length);
29
+ const spans = [];
30
+ if (item.selected) spans.push({ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(">"), style: SELECTED, width: 1 });
31
+ if (item.kind === "instance") spans.push({ col: 2, text: lit(marks[item.mark] ?? marks.unknown), style: look(PLAIN), width: 1 });
32
+ let col = LEAD;
33
+ const room = () => Math.max(0, kindCol - 2 - col);
34
+ const put = (text, width, own) => { const w = Math.min(width, room()); if (w > 0) spans.push({ col, text, style: look(own), width: w }); col += width + 1; };
35
+ if (item.kind === "instance" || item.kind === "soul") {
36
+ // A name is text from outside: an instance's or a soul's.
37
+ const name = measured(item.name);
38
+ put(name.text, name.width, PLAIN);
39
+ if (item.machine !== null && item.machine !== undefined) { put(lit(ON), ON.length, DIM); const where = measured(item.machine); put(where.text, where.width, DIM); }
40
+ } else {
41
+ put(lit(item.label), item.label.length, PLAIN);
42
+ if (item.kind === "act") { const name = measured(item.name); put(name.text, name.width, DIM); }
43
+ }
44
+ spans.push({ col: kindCol, text: lit(kind), style: look(DIM), width: Math.min(kind.length, cols - kindCol) });
45
+ return spans;
46
+ }
47
+
48
+ /** `{ rows, cursor }`: `size.rows` rows for an area `size.cols` wide, and the column the cursor
49
+ * stands at on the first row, after the query. The last row says what is cut off. */
50
+ export function palette(m, size) {
51
+ const rows = Array.from({ length: size.rows }, () => []);
52
+ const p = m.palette, query = measured(p.query);
53
+ const room = Math.max(0, size.cols - PROMPT_CELLS - 1);
54
+ if (size.rows > 0) rows[0] = [{ col: 0, text: lit(PROMPT), style: BOLD, width: PROMPT.length }, ...(query.width ? [{ col: PROMPT_CELLS, text: query.text, width: Math.min(query.width, room) }] : [])];
55
+ const marks = marksOf(m.ascii);
56
+ if (p.empty && size.rows > 1) rows[1] = [{ col: LEAD, text: lit("Nothing matches."), style: DIM, width: Math.max(0, size.cols - LEAD) }];
57
+ p.rows.forEach((item, i) => { if (1 + i < size.rows) rows[1 + i] = itemRow(item, size.cols, marks); });
58
+ const note = cutNote(p.above, p.below);
59
+ if (note && size.rows > 2) rows[size.rows - 1] = [{ col: LEAD, text: lit(note), style: DIM, width: Math.max(0, size.cols - LEAD) }];
60
+ return { rows, cursor: PROMPT_CELLS + Math.min(query.width, room) };
61
+ }
@@ -0,0 +1,268 @@
1
+ // The Souls view: (model, pane) -> rows of spans, the list of the open workspace's souls and the
2
+ // selected soul's detail. Pure: no IO, no clock, no escape byte. A soul's name, its description,
3
+ // where it comes from, its harness facts, its teams and capabilities, the names of its instances
4
+ // and a failed read's sentence are text the TUI did not write and go through shown(); the marks,
5
+ // the labels and the few lines of SOULS_TEXT are the TUI's own. Nothing is told by colour alone:
6
+ // a soul's colour is drawn on a mark that is there without it, the selected row carries `>` as
7
+ // well as reverse video, a soul a spawn here would refuse carries `!` as well as being dim, and
8
+ // the refusal in the detail says "Can't spawn here" in words before its warning style.
9
+ import { keyLabel } from "../actions.mjs";
10
+ import { lit, shown, shownLines } from "../term/text.mjs";
11
+ import { COLORS, style } from "../term/style.mjs";
12
+ import { LOOK, cutNote, headingRow, marksOf, measured } from "./instances.mjs";
13
+ import { windowOf } from "./scroll.mjs";
14
+
15
+ /** The TUI's own lines in the Souls view. `retry` and `toInstances` stand after the key that does
16
+ * what they say (tui.json may rebind it), so the line names the key the user has: `r reads them
17
+ * again.`. `reading` ends in an ellipsis, drawn `...` in ASCII. */
18
+ export const SOULS_TEXT = Object.freeze({
19
+ reading: "Reading souls…",
20
+ none: "This workspace offers no souls. `oats souls` says why.",
21
+ nomatch: "No soul matches the filter.",
22
+ retry: "reads them again.",
23
+ noWorkspace: "Open a workspace of this machine to see its souls.",
24
+ toInstances: "shows them in the Instances view.",
25
+ });
26
+
27
+ /** A soul's colour (soul-colors.mjs's palette name) as one of the terminal's sixteen: the model
28
+ * maps a row's colour with it, and a name not here leaves the soul uncoloured. */
29
+ export const SOUL_COLOURS = Object.freeze({ sand: "yellow", sage: "green", slate: "blue", mauve: "magenta", clay: "red", olive: "cyan" });
30
+
31
+ /** A soul's mark, in UTF-8 and in ASCII, and the sign before a count of its instances. */
32
+ export const SOUL_MARK = Object.freeze({ utf8: "■", ascii: "#" });
33
+ export const COUNT_SIGN = Object.freeze({ utf8: "·", ascii: "x" });
34
+
35
+ /** The columns of a soul's row, as an instance's: the selection mark, a gap, the soul's mark, a gap. */
36
+ const MARK = 2, NAME = 4;
37
+ /** Where a line of the TUI's own and a failed read's sentence start in the list, as in the list
38
+ * of instances (views/instances.mjs SENTENCE_INDENT). */
39
+ const SENTENCE_INDENT = 3;
40
+ /** The detail's title and labels start here: the first cell holds the mark of the pane with the
41
+ * focus (views/detail.mjs). */
42
+ const LEFT = 2;
43
+ /** The values start here, as in the instance detail (views/detail.mjs): a label is a short word.
44
+ * A part with a longer name (the harness, the capabilities, the instances here) has its name on
45
+ * a row of its own and its values under it. */
46
+ const VALUE = LEFT + 9;
47
+ /** The parts of a section (the harness, the instances) are set in this far under its label. */
48
+ const INNER = LEFT + 2;
49
+ /** The fewest cells a harness value keeps beside its label: under them each value goes on the
50
+ * row under its label, so a long label ("Launch configuration") never squeezes its value. */
51
+ const VALUE_MIN = 16;
52
+ /** The most rows a wrapped value or sentence takes, and the description. */
53
+ const WRAP_ROWS = 6, DESCRIPTION_ROWS = 8;
54
+
55
+ const PLAIN = style();
56
+ const BOLD = style({ bold: true });
57
+ const DIM = style({ dim: true });
58
+ const SELECTED = style({ reverse: true });
59
+ /** The refusal's warning style: it says "Can't spawn here" too, so the colour is not alone. */
60
+ const WARN = style({ bold: true, fg: "yellow" });
61
+
62
+ const markOf = (ascii) => (ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8);
63
+ const countText = (count, ascii) => `${ascii ? COUNT_SIGN.ascii : COUNT_SIGN.utf8}${count}`;
64
+ /** A line of the TUI's own as the screen draws it: the ellipsis is `...` in ASCII. */
65
+ const ownText = (text, ascii) => (ascii ? text.replace(/…/g, "...") : text);
66
+
67
+ /** The first key of the action `id` as the user has it, `{ text, width }`, or null when it has none. */
68
+ function keyOf(m, id) {
69
+ const action = (m.actions ?? []).find((a) => a.id === id && a.keys.length);
70
+ return action ? measured(keyLabel(action.keys[0])) : null;
71
+ }
72
+
73
+ /** Whether the list stands, beside the detail on a wide terminal: once the catalog was read (its
74
+ * rows, or none of them matching the filter), and over the rows a failed re-read kept. A body of
75
+ * one sentence (reading, a failed first read, an empty catalog, no workspace here) has the whole
76
+ * width instead. */
77
+ export function soulsListed(s) {
78
+ return Boolean(s) && s.local !== false && (s.heading != null || s.state === "rows" || s.state === "nomatch" || (s.list?.length ?? 0) > 0);
79
+ }
80
+
81
+ /** A line of the TUI's own on as many rows of `width` cells as it needs, broken at its spaces but
82
+ * never inside a command between backticks: a command cut in two cannot be typed. */
83
+ function ownLines(text, width) {
84
+ const words = text.match(/`[^`]*`[^\s`]*|\S+/g) ?? [];
85
+ return words.reduce((lines, word) => {
86
+ const last = lines.at(-1);
87
+ if (last !== undefined && last.length + 1 + word.length <= width) lines[lines.length - 1] = `${last} ${word}`;
88
+ else lines.push(word);
89
+ return lines;
90
+ }, []);
91
+ }
92
+
93
+ /** Units set on rows of `width` cells from column 0, `gap` cells between two: a unit is pieces
94
+ * (`{ text, width, style, glue }`) written together, one cell between two but before a glued one
95
+ * (a comma). A unit is never broken over two rows; one wider than a row is cut there. */
96
+ function flowed(units, width, gap = 1) {
97
+ const unitWidth = (unit) => unit.reduce((sum, piece, i) => sum + piece.width + (i > 0 && !piece.glue ? 1 : 0), 0);
98
+ const rows = [];
99
+ let row = [], used = 0;
100
+ for (const unit of units) {
101
+ const w = unitWidth(unit);
102
+ if (row.length && used + gap + w > width) { rows.push(row); row = []; used = 0; }
103
+ let col = row.length ? used + gap : 0;
104
+ unit.forEach((piece, i) => {
105
+ if (i > 0 && !piece.glue) col += 1;
106
+ if (col < width && piece.width > 0) row.push({ col, text: piece.text, width: Math.min(piece.width, width - col), ...(piece.style ? { style: piece.style } : {}) });
107
+ col += piece.width;
108
+ });
109
+ used = Math.min(width, col);
110
+ }
111
+ if (row.length) rows.push(row);
112
+ return rows;
113
+ }
114
+
115
+ /** One soul's row in a pane `cols` wide: the selection mark, the soul's mark in its colour, its
116
+ * name, `!` when a spawn of it here would be refused, and a dim count of its instances here when
117
+ * it has any. The name is cut before the `!` and the count are: they stay whole beside what is
118
+ * left of it. A refused soul's row is dim. One cell is kept at the right edge. */
119
+ function soulRow(row, cols, ascii) {
120
+ const look = (own) => (row.selected ? SELECTED : own);
121
+ const quiet = row.refused ? DIM : PLAIN;
122
+ const colour = typeof row.color === "string" && COLORS.includes(row.color) ? row.color : null;
123
+ const spans = [];
124
+ if (row.selected) spans.push({ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(marksOf(ascii).selected), style: SELECTED, width: 1 });
125
+ spans.push({ col: MARK, text: lit(markOf(ascii)), style: look(colour ? style({ fg: colour, dim: row.refused === true }) : quiet), width: 1 });
126
+ const end = cols - 1;
127
+ if (end <= NAME) return spans;
128
+ const after = [...(row.refused ? [{ text: "!", style: quiet }] : []), ...(row.count > 0 ? [{ text: countText(row.count, ascii), style: DIM }] : [])];
129
+ const afterWidth = after.reduce((sum, part) => sum + 1 + part.text.length, 0);
130
+ const name = measured(row.name);
131
+ // What follows the name stands only when a cell of the name is left beside it.
132
+ const kept = end - NAME > afterWidth ? after : [];
133
+ const room = end - NAME - (kept.length ? afterWidth : 0);
134
+ const nameWidth = Math.min(name.width, room);
135
+ spans.push({ col: NAME, text: name.text, style: look(quiet), width: kept.length ? nameWidth : room });
136
+ let col = NAME + nameWidth;
137
+ for (const part of kept) { col += 1; spans.push({ col, text: lit(part.text), style: look(part.style), width: part.text.length }); col += part.text.length; }
138
+ return spans;
139
+ }
140
+
141
+ /** `size.rows` rows for the list pane, `size.cols` wide: the model's window of the souls (after
142
+ * the heading of a failed re-read, when there is one) and on the last row what is cut off; or the
143
+ * one body the catalog's state gives: reading, a failed first read (its sentence, then the key
144
+ * that reads again), an empty catalog, no soul matching the filter, no workspace of this machine. */
145
+ export function soulsList(m, size) {
146
+ const s = m.souls, ascii = m.ascii;
147
+ const rows = Array.from({ length: size.rows }, () => []);
148
+ if (size.rows < 1 || !s) return rows;
149
+ const width = Math.max(0, size.cols - SENTENCE_INDENT - 1);
150
+ /** A line of the TUI's own, dim, from row `at` on: the rows it took. */
151
+ const own = (text, at) => {
152
+ const lines = ownLines(ownText(text, ascii), width).slice(0, Math.max(0, size.rows - at));
153
+ lines.forEach((line, i) => { rows[at + i] = [{ col: SENTENCE_INDENT, text: lit(line), style: DIM, width }]; });
154
+ return lines.length;
155
+ };
156
+ if (s.local === false) { own(SOULS_TEXT.noWorkspace, 0); return rows; }
157
+ if (!soulsListed(s)) {
158
+ if (s.state === "failed") {
159
+ // The sentence from outside, whole where the rows allow, and under it the key that reads again.
160
+ const retry = keyOf(m, "refresh");
161
+ const lines = shownLines(s.failure, width, Math.max(1, size.rows - (retry ? 1 : 0)), { ascii });
162
+ lines.forEach((line, i) => { rows[i] = [{ col: SENTENCE_INDENT, text: line, width }]; });
163
+ if (retry && lines.length < size.rows) {
164
+ const at = lines.length, words = SENTENCE_INDENT + retry.width + 1;
165
+ rows[at] = [{ col: SENTENCE_INDENT, text: retry.text, style: BOLD, width: Math.min(retry.width, width) },
166
+ ...(words < size.cols - 1 ? [{ col: words, text: lit(SOULS_TEXT.retry), style: DIM, width: size.cols - 1 - words }] : [])];
167
+ }
168
+ } else own(s.state === "none" ? SOULS_TEXT.none : SOULS_TEXT.reading, 0);
169
+ return rows;
170
+ }
171
+ let at = 0;
172
+ if (s.heading) rows[at++] = headingRow(s.heading, size.cols, ascii);
173
+ if (s.state === "none" || s.state === "nomatch") own(SOULS_TEXT[s.state], at);
174
+ else s.list.forEach((row, i) => { if (at + i < size.rows) rows[at + i] = soulRow(row, size.cols, ascii); });
175
+ const note = cutNote(s.above ?? 0, s.below ?? 0);
176
+ if (note) rows[size.rows - 1] = [{ col: SENTENCE_INDENT, text: lit(note), style: DIM, width: Math.max(0, size.cols - SENTENCE_INDENT) }];
177
+ return rows;
178
+ }
179
+
180
+ /** Every row of the selected soul's detail for a pane `cols` wide, before it is scrolled: the name,
181
+ * a failed re-read's sentence (in the warning style; it says so in words) and the description; `from` and `works`; the refusal; the harness (each fact `label value`,
182
+ * its notes, a launch problem); the teams; the capabilities (one line, wrapped); and the instances
183
+ * here, with the key that shows them. A section with nothing to say is left out. */
184
+ export function soulDetailRows(m, cols) {
185
+ const d = m.souls?.detail;
186
+ if (!d) return [];
187
+ const ascii = m.ascii, wide = Math.max(0, cols - LEFT), room = Math.max(0, cols - VALUE), inner = Math.max(0, cols - INNER);
188
+ const rows = [[{ col: LEFT, text: shown(d.name), style: BOLD, width: wide }]];
189
+ const label = (text, col = LEFT) => ({ col, text: lit(text), style: DIM, width: Math.max(0, Math.min(text.length, cols - col)) });
190
+ /** Safe lines placed at `col`, each `width` cells, the first beside `first` (a label) when given. */
191
+ 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 } : {}) }]));
192
+ /** A value from outside beside its label, wrapped under the value's column. */
193
+ const fact = (name, value) => {
194
+ if (room < 1) { rows.push([label(name)]); return; }
195
+ lines(shownLines(value, room, WRAP_ROWS, { ascii }), VALUE, room, null, label(name));
196
+ };
197
+ /** Units beside a label, flowed under the value's column. */
198
+ const flowFact = (name, units) => {
199
+ const set = room < 1 ? [] : flowed(units, room);
200
+ if (!set.length) { rows.push([label(name)]); return; }
201
+ set.forEach((spans, i) => rows.push([...(i === 0 ? [label(name)] : []), ...spans.map((span) => ({ ...span, col: span.col + VALUE }))]));
202
+ };
203
+
204
+ // A failed re-read's sentence, whole, under the name: the rows are the last read's.
205
+ if (d.failure) lines(shownLines(d.failure, wide, WRAP_ROWS, { ascii }), LEFT, wide, WARN);
206
+ lines(shownLines(d.description, wide, DESCRIPTION_ROWS, { ascii }), LEFT, wide);
207
+ if (d.from) fact("from", d.from);
208
+ if (d.works) fact("works", d.works);
209
+ if (d.refusal) lines(shownLines(d.refusal, wide, WRAP_ROWS, { ascii }), LEFT, wide, WARN);
210
+
211
+ const h = d.harness ?? { rows: [], notes: [], problem: null };
212
+ if (h.rows.length || h.notes.length || h.problem) {
213
+ rows.push([label("harness")]);
214
+ const names = h.rows.map(([name]) => measured(name));
215
+ const column = Math.max(0, ...names.map((name) => name.width));
216
+ const beside = inner - column - 2 >= VALUE_MIN;
217
+ h.rows.forEach(([, value], i) => {
218
+ const name = { col: INNER, text: names[i].text, style: DIM, width: Math.min(names[i].width, inner) };
219
+ if (beside) lines(shownLines(value, inner - column - 2, WRAP_ROWS, { ascii }), INNER + column + 2, inner - column - 2, null, name);
220
+ else { rows.push([name]); lines(shownLines(value, Math.max(0, inner - 2), WRAP_ROWS, { ascii }), INNER + 2, Math.max(0, inner - 2)); }
221
+ });
222
+ for (const note of h.notes) lines(shownLines(note, inner, WRAP_ROWS, { ascii }), INNER, inner, DIM);
223
+ if (h.problem) {
224
+ lines(shownLines(h.problem.lead, inner, WRAP_ROWS, { ascii }), INNER, inner, BOLD);
225
+ for (const line of h.problem.lines ?? []) lines(shownLines(line, inner, WRAP_ROWS, { ascii }), INNER, inner);
226
+ if (h.problem.code) {
227
+ const code = measured(h.problem.code);
228
+ rows.push([label("code", INNER), { col: INNER + 5, text: code.text, style: DIM, width: Math.max(0, Math.min(code.width, cols - INNER - 5)) }]);
229
+ }
230
+ }
231
+ }
232
+
233
+ // Each team its label, the default one marked so in the TUI's word; a comma after all but the last.
234
+ const comma = { text: lit(","), width: 1, glue: true };
235
+ if (d.teams?.length) flowFact("teams", d.teams.map((team, i, all) => [measured(team.label), ...(team.default ? [{ text: lit("(default)"), width: "(default)".length, style: DIM }] : []), ...(i < all.length - 1 ? [comma] : [])]));
236
+ if (d.capabilities?.length) {
237
+ rows.push([label("capabilities")]);
238
+ flowed(d.capabilities.map((id, i, all) => [measured(id), ...(i < all.length - 1 ? [comma] : [])]), inner).forEach((spans) => rows.push(spans.map((span) => ({ ...span, col: span.col + INNER }))));
239
+ }
240
+
241
+ const here = d.instances ?? { shown: [], more: 0 };
242
+ if (here.shown.length || here.more > 0) {
243
+ rows.push([label("instances here")]);
244
+ const marks = marksOf(ascii);
245
+ const units = [
246
+ ...here.shown.map((each) => [{ text: lit(marks[each.mark] ?? marks.unknown), width: 1, style: LOOK[each.mark] ?? LOOK.unknown }, measured(each.name)]),
247
+ ...(here.more > 0 ? [[{ text: lit(`+${here.more}`), width: `+${here.more}`.length, style: DIM }]] : []),
248
+ ];
249
+ flowed(units, inner, 2).forEach((spans) => rows.push(spans.map((span) => ({ ...span, col: span.col + INNER }))));
250
+ const key = keyOf(m, "soul-instances");
251
+ if (key && INNER + key.width + 1 < cols) rows.push([{ col: INNER, text: key.text, style: DIM, width: key.width }, { col: INNER + key.width + 1, text: lit(SOULS_TEXT.toInstances), style: DIM, width: cols - INNER - key.width - 1 }]);
252
+ }
253
+ return rows;
254
+ }
255
+
256
+ /** `{ rows, extent }`: `size.rows` rows of the detail for a pane `size.cols` wide, scrolled to the
257
+ * model's `detailTop`, and how many rows the whole detail has. The pane with the focus says so
258
+ * with `>` beside the title, never by an attribute alone (views/detail.mjs). */
259
+ export function soulDetail(m, size) {
260
+ const all = soulDetailRows(m, size.cols);
261
+ const rows = Array.from({ length: size.rows }, () => []);
262
+ const win = windowOf({ top: m.souls?.detailTop ?? 0, count: all.length, height: size.rows });
263
+ all.slice(win.top, win.top + win.size).forEach((spans, i) => { rows[i] = spans; });
264
+ const note = cutNote(win.above, win.below);
265
+ if (note && size.rows > 0) rows[size.rows - 1] = [{ col: LEFT, text: lit(note), style: DIM, width: Math.max(0, size.cols - LEFT) }];
266
+ if (m.souls?.focus === "detail" && size.rows > 0 && all.length) rows[0] = [{ col: 0, text: lit(">"), style: BOLD, width: 1 }, ...rows[0]];
267
+ return { rows, extent: all.length };
268
+ }