@awebai/oats 0.52.0 → 0.53.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 (98) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +304 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/desktop-cli-api.md +673 -58
  6. package/docs/desktop-instance-start.md +25 -12
  7. package/docs/execution-targets.md +1 -0
  8. package/docs/implementation.md +175 -11
  9. package/docs/integrations.md +6 -3
  10. package/docs/knowledge.md +2 -2
  11. package/docs/macos-test-runs.md +246 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-lane.md +210 -6
  15. package/docs/release-notes/v0.53.0.md +1274 -0
  16. package/docs/schedules.md +7 -1
  17. package/docs/souls-and-instances.md +237 -15
  18. package/docs/tui.md +453 -21
  19. package/docs/upgrading.md +298 -0
  20. package/docs/workspaces.md +3 -3
  21. package/lib/automations.mjs +22 -22
  22. package/lib/claim.mjs +93 -4
  23. package/lib/config-data.mjs +4 -1
  24. package/lib/core.mjs +569 -121
  25. package/lib/instance-events.mjs +19 -1
  26. package/lib/instance-git.mjs +39 -3
  27. package/lib/instance-inspect.mjs +5 -6
  28. package/lib/instance-lifecycle.mjs +145 -18
  29. package/lib/instance-resolution.mjs +59 -6
  30. package/lib/launch-preference.mjs +226 -15
  31. package/lib/local-edit.mjs +118 -0
  32. package/lib/packages.mjs +13 -4
  33. package/lib/pi-bridge.mjs +308 -0
  34. package/lib/refused-text.mjs +11 -0
  35. package/lib/remote.mjs +190 -25
  36. package/lib/resolve.mjs +2 -1
  37. package/lib/retained-after-retire.mjs +2 -2
  38. package/lib/retire-output.mjs +12 -1
  39. package/lib/schedule-host.mjs +6 -35
  40. package/lib/shell-word.mjs +13 -0
  41. package/lib/soul-launch-verbs.mjs +153 -0
  42. package/lib/stable-node.mjs +62 -0
  43. package/lib/teams-verbs.mjs +18 -46
  44. package/lib/workspace.mjs +49 -19
  45. package/package-catalog.json +4 -4
  46. package/package.json +2 -1
  47. package/packages/client/attach-exit.mjs +25 -0
  48. package/packages/client/cli-adapter.mjs +16 -3
  49. package/packages/client/cli-locator.mjs +2 -2
  50. package/packages/client/deployment-contract.mjs +4 -0
  51. package/packages/client/deployment-facts.mjs +71 -10
  52. package/packages/client/deployment-panel.mjs +49 -11
  53. package/packages/client/deployment-read-cli.mjs +7 -3
  54. package/packages/client/display-text.mjs +8 -2
  55. package/packages/client/instance-acts.mjs +46 -10
  56. package/packages/client/instance-events-contract.mjs +4 -2
  57. package/packages/client/instance-presentation.mjs +66 -2
  58. package/packages/client/instance-tree.mjs +23 -14
  59. package/packages/client/kernel-lines.mjs +31 -0
  60. package/packages/client/kernel-made.mjs +23 -0
  61. package/packages/client/launch-prompt-outcome.mjs +51 -16
  62. package/packages/client/lifecycle-contract.mjs +45 -4
  63. package/packages/client/liveness.mjs +14 -1
  64. package/packages/client/own-codes.mjs +31 -0
  65. package/packages/client/panel-views.mjs +18 -11
  66. package/packages/client/readiness-contract.mjs +3 -1
  67. package/packages/client/remote-address.mjs +34 -9
  68. package/packages/client/remote-identity-memory.mjs +94 -0
  69. package/packages/client/remote-roster.mjs +92 -6
  70. package/packages/client/session-attach.mjs +175 -0
  71. package/packages/client/spawn-apply-contract.mjs +16 -4
  72. package/packages/client/spawn-messages.mjs +26 -3
  73. package/packages/client/spawn-preview-cli.mjs +8 -2
  74. package/packages/client/spawn-preview-contract.mjs +5 -1
  75. package/packages/client/terminal-exec.mjs +21 -0
  76. package/packages/client/workspace-choices.mjs +95 -0
  77. package/packages/client/workspace-views.mjs +39 -3
  78. package/packages/record/README.md +21 -0
  79. package/packages/record/bin/setup.mjs +108 -15
  80. package/packages/tui/README.md +30 -12
  81. package/packages/tui/lib/actions.mjs +16 -1
  82. package/packages/tui/lib/client.mjs +32 -1
  83. package/packages/tui/lib/config.mjs +151 -0
  84. package/packages/tui/lib/main.mjs +117 -46
  85. package/packages/tui/lib/model.mjs +392 -0
  86. package/packages/tui/lib/read.mjs +473 -0
  87. package/packages/tui/lib/store.mjs +364 -0
  88. package/packages/tui/lib/term/keys.mjs +44 -0
  89. package/packages/tui/lib/term/screen.mjs +16 -4
  90. package/packages/tui/lib/term/text.mjs +60 -0
  91. package/packages/tui/lib/term/tty.mjs +13 -3
  92. package/packages/tui/lib/views/detail.mjs +46 -0
  93. package/packages/tui/lib/views/frame.mjs +230 -36
  94. package/packages/tui/lib/views/help.mjs +125 -13
  95. package/packages/tui/lib/views/instances.mjs +137 -0
  96. package/packages/tui/lib/views/scroll.mjs +19 -0
  97. package/packages/tui/lib/views/switcher.mjs +97 -0
  98. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -1,31 +1,47 @@
1
- // The frame: (state, size) -> rows of safe text. Pure: no IO, no clock, no escape byte.
2
- // Every word here is the TUI's own, so every span is lit(). Meaning never rests on colour alone:
3
- // what is dim or bold also says what it is in words.
1
+ // The frame: (model, size) -> the rows of the whole screen. Pure: no IO, no clock, no escape
2
+ // byte. It places the views: the header, the list of instances and the detail beside it (or as a
3
+ // page of its own on a narrow terminal), the switcher of workspaces over the whole body, the
4
+ // help, and the footer. The TUI's own words are lit(); everything else is shown(). Meaning never
5
+ // rests on colour alone: what is dim or bold also says what it is in words or by a mark.
4
6
  import { keyLabel } from "../actions.mjs";
5
- import { lit } from "../term/text.mjs";
7
+ import { lit, shown, shownLines } from "../term/text.mjs";
6
8
  import { style } from "../term/style.mjs";
7
- import { help } from "./help.mjs";
9
+ import { detail } from "./detail.mjs";
10
+ import { help, keyText } from "./help.mjs";
11
+ import { instances, measured } from "./instances.mjs";
12
+ import { switcher } from "./switcher.mjs";
8
13
 
9
14
  /** The frame is drawn from this size up (docs/tui.md); the design size is 80x24. */
10
15
  export const MIN_SIZE = Object.freeze({ cols: 60, rows: 15 });
11
- /** The views to come, named so the frame already has its shape. Drawn dim: none can be opened yet. */
12
- const VIEWS = Object.freeze(["1 Instances", "2 Souls", "3 Capabilities"]);
13
- const BODY = Object.freeze(["This preview draws the frame only.", "Views arrive in later releases."]);
16
+ /** From this width up the detail stands beside the list; under it, it is a page of its own. */
17
+ export const WIDE = 80;
18
+ /** The views, named so the frame has its shape. Two are dim: they cannot be opened yet, and the
19
+ * help says what to run instead. */
20
+ const VIEWS = Object.freeze([Object.freeze({ name: "1 Instances", open: true }), Object.freeze({ name: "2 Souls", open: false }), Object.freeze({ name: "3 Capabilities", open: false })]);
14
21
  const GAP = 3;
22
+ /** One cell of margin on each side of the header and the footer. */
23
+ const MARGIN = 1;
15
24
  /** The longest run one lit() holds with room to spare: the display filter bounds a line, and a
16
25
  * terminal can be wider than that bound. */
17
26
  const RUN = 500;
27
+ /** The rows a reason may take above the list: a quarter of the body, at least one, at most this. */
28
+ const REASON_ROWS = 4;
29
+ /** The rows a deployment's note may take above the list. */
30
+ const NOTE_ROWS = 2;
31
+ /** The cells a kept filter takes in the footer. */
32
+ const FILTER_COLS = 24;
33
+ /** What the header holds in the workspace's place while the switcher is shown. */
34
+ const WORKSPACES = "workspaces";
35
+ /** The TUI's word before the one machine of a view that holds no deployment of this machine. */
36
+ const ON = "on";
37
+ /** The cells the workspace's name keeps (all of them, when it is shorter) before the header says
38
+ * how many other machines it is on: under that the name comes first. */
39
+ const NAME_MIN = 8;
18
40
 
19
41
  const BOLD = style({ bold: true });
20
42
  const DIM = style({ dim: true });
21
43
 
22
- /** Spans left to right from `col`, GAP cells apart. */
23
- function inline(col, texts, look) {
24
- const spans = [];
25
- for (const text of texts) { spans.push({ col, text: lit(text), ...(look ? { style: look } : {}) }); col += text.length + GAP; }
26
- return spans;
27
- }
28
- const centred = (text, cols, look) => ({ col: Math.max(0, Math.floor((cols - text.length) / 2)), text: lit(text), ...(look ? { style: look } : {}) });
44
+ const clamp = (n, low, high) => Math.min(Math.max(n, low), high);
29
45
  const tooSmall = (size) => size.cols < MIN_SIZE.cols || size.rows < MIN_SIZE.rows;
30
46
 
31
47
  /** One row saying so, with the size found and the size needed. Short, and the sizes early: on a
@@ -36,27 +52,205 @@ function tooSmallRows(size) {
36
52
  return rows;
37
53
  }
38
54
 
39
- /** The whole screen for a state: `{ view: "frame" | "help", actions, ascii }`. */
40
- export function frame(state, size) {
41
- if (tooSmall(size)) return tooSmallRows(size);
55
+ /** A horizontal rule over the whole width, with a joint where the panes' rule meets it. */
56
+ function rule(cols, ascii, joint = null) {
57
+ const spans = [], dash = ascii ? "-" : "─";
58
+ for (let col = 0; col < cols; col += RUN) spans.push({ col, text: lit(dash.repeat(Math.min(RUN, cols - col))), style: DIM });
59
+ if (joint) spans.push({ col: joint.col, text: lit(ascii ? "+" : joint.up ? "┴" : "┬"), style: DIM, width: 1 });
60
+ return spans;
61
+ }
62
+
63
+ /** Where everything stands for a size: the body under the header, the reason of a deployment
64
+ * that is not live and the note of the one deployment of a view without headings (both wrapped
65
+ * here, since their rows take room from the panes), and the panes. `notice` and `note` are the
66
+ * model's (lib/model.mjs): the main loop asks for the layout first, because the model's window
67
+ * is as tall, and the sentences in its list as wide, as the list pane this gives. The answer's
68
+ * `note` is the note's rows. */
69
+ export function layout(notice, size, { observed = true, note = null, ascii = false } = {}) {
70
+ const body = { top: 3, rows: Math.max(0, size.rows - 5) };
71
+ const wide = size.cols >= WIDE;
72
+ const listCols = wide ? clamp(Math.floor(size.cols * 0.48), 36, 60) : size.cols;
73
+ const across = Math.max(1, size.cols - 2 * MARGIN);
74
+ const reason = notice ? shownLines(notice.reason, across, clamp(Math.floor(body.rows / 4), 1, REASON_ROWS), { ascii }) : [];
75
+ const noted = note ? shownLines(note, across, NOTE_ROWS, { ascii }) : [];
76
+ // The state and its reason, then the note, stand above the panes, over the whole width; a rule
77
+ // closes them when instances follow.
78
+ const said = (notice ? 1 + reason.length : 0) + noted.length;
79
+ const above = said ? Math.min(body.rows, said + (observed ? 1 : 0)) : 0;
80
+ return { body, wide, listCols, reason, note: noted, above, panes: { top: body.top + above, rows: Math.max(0, body.rows - above) }, page: Math.max(0, body.rows - above) };
81
+ }
82
+
83
+ /** The header's middle, from `col` on in `room` cells: the workspace's name and, when the view
84
+ * holds other machines, what says so, in the TUI's words and dim:
85
+ * `+N machine(s)` beside a deployment of this machine;
86
+ * `on <machine>` the one machine of a view that holds no deployment of this machine (no
87
+ * heading names it there);
88
+ * `N machines` two or more of them and no deployment of this machine.
89
+ * Whether a deployment is this machine's is the shared entries' word (the model's `here`), and
90
+ * the machine's name is theirs. What stands after the name gives way before the name is cut
91
+ * short of NAME_MIN cells, and a machine's name is cut before the workspace's. While the
92
+ * switcher is shown no workspace is named: the header says what is listed instead. */
93
+ function nameSpans(m, col, room) {
94
+ if (room <= 0) return [];
95
+ if (m.under === "switcher") return [{ col, text: lit(WORKSPACES), width: room }];
96
+ const name = measured(m.workspace), alone = [{ col, text: name.text, width: room }];
97
+ if (!(m.machines > 0)) return alone;
98
+ const least = Math.min(name.width, NAME_MIN);
99
+ // Two cells between the name and what follows it, as everywhere in the header.
100
+ const after = (width) => col + width + (width ? 2 : 0);
101
+ if (!m.here && m.machine !== null) {
102
+ const where = measured(m.machine), left = room - 2 - ON.length - 1;
103
+ // The machine's name is cut first, down to the cells that still say something: the
104
+ // workspace's name has what that leaves.
105
+ const kept = Math.min(where.width, NAME_MIN);
106
+ if (left - least < kept) return alone;
107
+ const width = Math.min(name.width, left - kept), at = after(width);
108
+ return [...(width ? [{ col, text: name.text, width }] : []), { col: at, text: lit(ON), style: DIM, width: ON.length }, { col: at + ON.length + 1, text: where.text, style: DIM, width: Math.min(where.width, left - width) }];
109
+ }
110
+ const more = `${m.here ? "+" : ""}${m.machines} ${m.machines === 1 ? "machine" : "machines"}`;
111
+ const left = room - 2 - more.length;
112
+ if (left < least) return alone;
113
+ const width = Math.min(name.width, left);
114
+ return [...(width ? [{ col, text: name.text, width }] : []), { col: after(width), text: lit(more), style: DIM, width: more.length }];
115
+ }
116
+
117
+ /** The header's counts, right aligned, each a number and a word. When they do not all fit, the
118
+ * ones from the shared count are given up from the end, never the two the TUI adds. */
119
+ function countSpans(counts, cols) {
120
+ const texts = counts.map((count) => ({ ...count, text: `${count.n} ${count.word}` }));
121
+ const width = (list) => list.reduce((sum, c) => sum + c.text.length, 0) + Math.max(0, list.length - 1) * 2;
122
+ const room = cols - 2 * MARGIN - "oats".length - 2;
123
+ let kept = texts;
124
+ while (width(kept) > room && kept.some((c) => c.shared)) kept = kept.filter((c, i) => i !== kept.findLastIndex((k) => k.shared));
125
+ const spans = [];
126
+ let col = cols - MARGIN - width(kept);
127
+ for (const count of kept) { if (col >= 0) spans.push({ col, text: count.shared ? shown(count.text) : lit(count.text), width: count.text.length }); col += count.text.length + 2; }
128
+ return { spans, start: cols - MARGIN - width(kept) };
129
+ }
130
+
131
+ /** The footer: the filter field while it is open; else the actions that apply now, read from the
132
+ * effective table, as many as fit, `help` and `quit` last and always: their room is set aside
133
+ * first, and a kept filter and the other hints take what is left. A hint that does not fit ends
134
+ * the row's hints, so the order they are tried in is the order they are given up from the end:
135
+ * `workspaces` stands after `refresh`, and a row too narrow for both keeps `refresh`. The
136
+ * switcher has a filter of its own, drawn as the list's. A key's label is the user's
137
+ * (views/help.mjs keyText); everything is placed by cells. */
138
+ function footer(m, cols) {
139
+ const action = (id) => m.actions.find((a) => a.id === id && a.keys.length);
140
+ /** A hint: a key and what it does. */
141
+ const made = (key, word) => ({ key, word, width: key.width + 1 + word.length });
142
+ const hint = (id, label) => { const a = action(id); return a ? made(keyText(keyLabel(a.keys[0])), label ?? a.label) : null; };
143
+ const edge = cols - MARGIN; // nothing stands at or past it
144
+ /** A hint's spans at `col`, never past the edge. */
145
+ const put = (h, col, look) => [
146
+ { col, text: h.key.text, width: Math.max(0, Math.min(h.key.width, edge - col)), ...look },
147
+ { col: col + h.key.width + 1, text: lit(h.word), width: Math.max(0, Math.min(h.word.length, edge - col - h.key.width - 1)), ...look },
148
+ ].filter((span) => span.width > 0);
149
+ const span = (hints) => hints.reduce((sum, h) => sum + h.width, 0) + Math.max(0, hints.length - 1) * GAP;
150
+
151
+ if (m.view !== "help" && m.filter.editing) {
152
+ const hints = [made({ text: lit("Enter"), width: "Enter".length }, "keep"), hint("close", "clear")].filter(Boolean);
153
+ const spans = [{ col: MARGIN, text: lit("/"), style: BOLD, width: 1 }, { col: MARGIN + 1, text: shown(m.filter.query), width: Math.max(0, edge - span(hints) - GAP - MARGIN - 1) }];
154
+ let col = Math.max(MARGIN + 2, edge - span(hints));
155
+ for (const h of hints) { spans.push(...put(h, col, { style: DIM })); col += h.width + GAP; }
156
+ return spans;
157
+ }
158
+ const ids = m.view === "help" ? ["close"]
159
+ // Esc closes the switcher only onto a view, and there is none before a workspace is opened.
160
+ // A kept filter puts `close` before `refresh`, as in the list: the key that clears it is the hint to keep.
161
+ : m.view === "switcher" ? ["open-workspace", "filter", ...(m.filter.query ? ["close", "refresh"] : ["refresh", ...(m.open ? ["close"] : [])])]
162
+ : m.focus === "detail" ? ["detail", "close", "refresh"]
163
+ : ["filter", "detail", ...(m.filter.query ? ["close"] : []), "refresh", "workspaces"];
164
+ const last = ["help", "quit"].map((id) => hint(id)).filter(Boolean);
165
+ const spans = [];
166
+ let col = MARGIN;
167
+ if (m.view !== "help" && m.filter.query) {
168
+ // The kept filter has a place of its own width, so the hints stand where they always do;
169
+ // it gives way, down to nothing, before `help` and `quit` do.
170
+ const slot = Math.min(FILTER_COLS - GAP, edge - MARGIN - span(last) - (last.length ? GAP : 0));
171
+ if (slot >= 2) {
172
+ spans.push({ col, text: lit("/"), style: BOLD, width: 1 }, { col: col + 1, text: shown(m.filter.query), style: BOLD, width: slot - 1 });
173
+ col += slot + GAP;
174
+ }
175
+ }
176
+ for (const h of ids.map((id) => hint(id)).filter(Boolean)) {
177
+ if (col + h.width + GAP + span(last) > edge) break;
178
+ spans.push(...put(h, col));
179
+ col += h.width + GAP;
180
+ }
181
+ for (const h of last) { spans.push(...put(h, col)); col += h.width + GAP; }
182
+ return spans;
183
+ }
184
+
185
+ /** Shift a pane's rows to its place on the screen. */
186
+ const placed = (spans, col) => spans.map((span) => ({ ...span, col: span.col + col }));
187
+
188
+ /** The whole screen for a model: `{ rows, page, extent, room }`. `page` is the rows of the list
189
+ * pane (of the whole body, for the switcher); `extent` and `room` are how many rows the other
190
+ * scrolling pane (the help, else the detail) holds and shows. The main loop hands the three back
191
+ * with the next key, so the store scrolls by what is on the screen without holding a size. */
192
+ export function frame(m, size) {
193
+ if (tooSmall(size)) return { rows: tooSmallRows(size), page: 1, extent: 0, room: 1 };
42
194
  const rows = Array.from({ length: size.rows }, () => []);
43
- const rule = [];
44
- for (let col = 0; col < size.cols; col += RUN) rule.push({ col, text: lit((state.ascii ? "-" : "\u2500").repeat(Math.min(RUN, size.cols - col))), style: DIM });
45
- const key = (id) => { const action = state.actions.find((a) => a.id === id); return action ? `${keyLabel(action.keys[0])} ${action.label}` : null; };
46
-
47
- rows[0] = [{ col: 0, text: lit("oats"), style: BOLD }, { col: size.cols - "preview".length, text: lit("preview") }];
48
- rows[1] = inline(0, VIEWS, DIM);
49
- rows[2] = rule;
50
- rows[size.rows - 2] = rule;
51
- rows[size.rows - 1] = inline(0, [key(state.view === "help" ? "close" : "help"), key("quit")].filter(Boolean));
52
-
53
- const top = 3, height = size.rows - 5;
54
- if (state.view === "help") help(state.actions, { cols: size.cols, rows: height }).forEach((spans, i) => { rows[top + i] = spans; });
55
- else {
56
- // One line where it fits, else a line per sentence.
57
- const lines = BODY.join(" ").length <= size.cols ? [BODY.join(" ")] : BODY;
58
- const first = top + Math.max(0, Math.floor((height - lines.length) / 2));
59
- lines.forEach((line, i) => { rows[first + i] = [centred(line, size.cols)]; });
195
+ const g = layout(m.notice, size, { observed: m.observed, note: m.note, ascii: m.ascii });
196
+ const { cols } = size;
197
+ // The switcher is no view of the three: while it is shown, or is under the help, none is current.
198
+ const listing = m.under === "switcher";
199
+
200
+ const counts = countSpans(m.counts, cols);
201
+ const nameCol = MARGIN + "oats".length + 2;
202
+ rows[0] = [{ col: MARGIN, text: lit("oats"), style: BOLD }, ...nameSpans(m, nameCol, counts.start - 2 - nameCol), ...counts.spans];
203
+ let col = MARGIN;
204
+ for (const view of VIEWS) { rows[1].push({ col, text: lit(view.name), ...(view.open && !listing ? {} : { style: DIM }), width: view.name.length }); col += view.name.length + GAP; }
205
+ if (m.readAt) { const read = `read ${m.readAt}`; rows[1].push({ col: cols - MARGIN - read.length, text: lit(read), style: DIM, width: read.length }); }
206
+ rows[size.rows - 1] = footer(m, cols);
207
+
208
+ if (m.view === "help") {
209
+ rows[2] = rule(cols, m.ascii);
210
+ rows[size.rows - 2] = rule(cols, m.ascii);
211
+ const drawn = help(m.actions, { cols, rows: g.body.rows }, { top: m.helpTop, ascii: m.ascii });
212
+ drawn.rows.forEach((spans, i) => { rows[g.body.top + i] = spans; });
213
+ return { rows, page: Math.max(1, g.page), extent: drawn.extent, room: g.body.rows };
60
214
  }
61
- return rows;
215
+
216
+ // The switcher takes the whole body, over the whole width: one pane, so no joint in the rules.
217
+ // Nothing beside it scrolls on its own.
218
+ if (listing) {
219
+ rows[2] = rule(cols, m.ascii);
220
+ rows[size.rows - 2] = rule(cols, m.ascii);
221
+ switcher(m, { cols, rows: g.body.rows }).forEach((spans, i) => { rows[g.body.top + i] = spans; });
222
+ return { rows, page: Math.max(1, g.body.rows), extent: 0, room: 1 };
223
+ }
224
+
225
+ // The state of a deployment that is not live, and on rows of its own the reason, which is the
226
+ // shared home's sentence or the kernel's: nothing of the TUI's stands on a reason's row. Then
227
+ // the note of the one deployment of a view without headings, the shared home's sentence too.
228
+ const said = [];
229
+ if (m.notice) {
230
+ const since = m.notice.since ? `since ${m.notice.since}` : null;
231
+ said.push([{ col: MARGIN, text: shown(m.notice.text), style: BOLD, width: Math.max(0, cols - 2 * MARGIN - (since ? since.length + 2 : 0)) }, ...(since ? [{ col: cols - MARGIN - since.length, text: lit(since), style: DIM, width: since.length }] : [])]);
232
+ for (const line of g.reason) said.push([{ col: MARGIN, text: line, width: cols - 2 * MARGIN }]);
233
+ }
234
+ for (const line of g.note) said.push([{ col: MARGIN, text: line, width: cols - 2 * MARGIN }]);
235
+ said.slice(0, g.above).forEach((spans, i) => { rows[g.body.top + i] = spans; });
236
+ const paged = !g.wide && m.focus === "detail" && m.detail;
237
+ // Two panes only over an observed deployment: with no instance there is nothing to put beside the list.
238
+ const split = g.wide && g.panes.rows > 0 && m.observed;
239
+ const joint = split ? { col: g.listCols } : null;
240
+ // The rule that opens the panes: the one under the header, or the one under the reason and the note.
241
+ const opening = m.observed && g.above > 0 ? g.panes.top - 1 : 2;
242
+ rows[2] = rule(cols, m.ascii, opening === 2 ? joint : null);
243
+ if (opening !== 2 && opening < size.rows - 2) rows[opening] = rule(cols, m.ascii, joint);
244
+ rows[size.rows - 2] = rule(cols, m.ascii, joint && { ...joint, up: true });
245
+
246
+ const pane = { cols: g.wide ? g.listCols : cols, rows: g.panes.rows };
247
+ let extent = 0;
248
+ if (!paged) instances(m, pane).forEach((spans, i) => { rows[g.panes.top + i] = spans; });
249
+ if (split || paged) {
250
+ const at = paged ? MARGIN : g.listCols + 2;
251
+ const drawn = detail(m, { cols: Math.max(0, cols - at - MARGIN), rows: g.panes.rows });
252
+ extent = drawn.extent;
253
+ drawn.rows.forEach((spans, i) => { rows[g.panes.top + i] = [...rows[g.panes.top + i], ...(split ? [{ col: g.listCols, text: lit(m.ascii ? "|" : "│"), style: DIM, width: 1 }] : []), ...placed(spans, at)]; });
254
+ }
255
+ return { rows, page: Math.max(1, g.page), extent, room: Math.max(1, g.panes.rows) };
62
256
  }
@@ -1,9 +1,13 @@
1
- // The help view: the action table as rows of safe text. Pure: no IO, no clock, no escape byte.
2
- // It is generated from the table the reducer acts on, so it names every key that does something
3
- // and no key that does not.
1
+ // The help view: the action table, the marks and what this version does not do, as rows of safe
2
+ // text. Pure: no IO, no clock, no escape byte. The keys are generated from the table the reducer
3
+ // acts on, so the help names every key that does something and no key that does not; the marks
4
+ // are the ones the list and the switcher draw (views/instances.mjs, views/switcher.mjs).
4
5
  import { keyLabel } from "../actions.mjs";
5
6
  import { lit } from "../term/text.mjs";
6
7
  import { style } from "../term/style.mjs";
8
+ import { cutNote, marksOf, measured } from "./instances.mjs";
9
+ import { windowOf } from "./scroll.mjs";
10
+ import { OPEN_MARK } from "./switcher.mjs";
7
11
 
8
12
  const TITLE = style({ bold: true });
9
13
  const KEYS = style({ bold: true });
@@ -13,16 +17,124 @@ const GAP = 3;
13
17
 
14
18
  /** The keys of an action as a person reads them: `q, Ctrl+C`. */
15
19
  export const keysLabel = (action) => action.keys.map(keyLabel).join(", ");
20
+ /** A key's label for the screen: `{ text, width }`. A key is the user's once their tui.json names
21
+ * it, so its label is text the TUI did not write: it goes through shown(), and takes the cells
22
+ * its display takes (a key may be a wide character). */
23
+ export function keyText(label) {
24
+ return measured(label);
25
+ }
26
+
27
+ /** What this version does not do, each with the `oats` command that does it: an omission is
28
+ * stated where a user looks for it. test/tui-word.test.mjs holds every command here to the
29
+ * kernel's own usage, so the help cannot name a command that does not exist. A later version
30
+ * removes a line when it adds the act. */
31
+ export const NOT_YET = Object.freeze([
32
+ Object.freeze({ what: "open an agent's terminal", command: "oats session attach --home <home>" }),
33
+ Object.freeze({ what: "stop an agent", command: "oats instance stop <instance>" }),
34
+ Object.freeze({ what: "start or restart an agent", command: "oats session start --home <home>" }),
35
+ Object.freeze({ what: "retire an agent", command: "oats retire <instance>" }),
36
+ Object.freeze({ what: "add a machine to this workspace", command: "oats server connect <id> --ssh <alias>" }),
37
+ Object.freeze({ what: "check a machine", command: "oats server check <id>" }),
38
+ Object.freeze({ what: "remove a machine", command: "oats server remove <id>" }),
39
+ // The switcher lists the deployments opened in this run and those in ~/Agents, and no other.
40
+ Object.freeze({ what: "open a deployment outside ~/Agents", command: "oats tui --dir <path>" }),
41
+ ]);
42
+ /** What a user should know of the machines the list shows, each a sentence of the TUI's own: a
43
+ * limit that no command lifts is stated too. */
44
+ export const MACHINES = Object.freeze([
45
+ "A machine's rows are what it reported at the time on its heading (in a view of one machine, in the header).",
46
+ "Nothing is kept on disk: a machine not reached in this run is listed by its own name.",
47
+ "Souls and Capabilities, when they come, are this machine's.",
48
+ ]);
49
+ /** The views the frame names, and for the two that cannot be opened yet, what to run instead. */
50
+ export const VIEWS = Object.freeze([
51
+ Object.freeze({ name: "1 Instances", what: "the instances of the open workspace", commands: Object.freeze([]) }),
52
+ Object.freeze({ name: "2 Souls", what: "not in this version", commands: Object.freeze(["oats souls", "oats spawn <soul>"]) }),
53
+ Object.freeze({ name: "3 Capabilities", what: "not in this version", commands: Object.freeze(["oats capabilities"]) }),
54
+ ]);
55
+
56
+ const words = (text) => text.split(" ");
57
+ /** Pieces set on lines of at most `room` cells, a space between two; a piece is never broken. */
58
+ const flow = (pieces, room) => pieces.reduce((lines, piece) => {
59
+ const last = lines.at(-1);
60
+ if (last !== undefined && last.length + 1 + piece.length <= room) lines[lines.length - 1] = `${last} ${piece}`;
61
+ else lines.push(piece);
62
+ return lines;
63
+ }, []);
64
+ /** A table: a left column as wide as its widest entry, then what each entry means, given as
65
+ * pieces that are never broken (a word, or a whole command: a command cut in two cannot be
66
+ * typed). What does not fit `cols` goes on in the same column on the next row. A table with a
67
+ * piece wider than that column puts every meaning under its entry instead, so no row is cut at
68
+ * the smallest width the frame draws at. */
69
+ function table(pairs, cols, look) {
70
+ // An entry is the TUI's own word, or text made elsewhere with its width (a key's label).
71
+ pairs = pairs.map(([left, pieces]) => [typeof left === "string" ? { text: lit(left), width: left.length } : left, pieces]);
72
+ const entry = (left) => ({ col: INDENT, text: left.text, width: left.width, ...(look ? { style: look } : {}) });
73
+ const column = INDENT + Math.max(...pairs.map(([left]) => left.width)) + GAP;
74
+ const stacked = pairs.some(([, pieces]) => pieces.some((piece) => column + piece.length > cols));
75
+ const at = stacked ? INDENT + 2 : column;
76
+ return pairs.flatMap(([left, pieces]) => {
77
+ const lines = flow(pieces, cols - at).map((text) => ({ col: at, text: lit(text) }));
78
+ return stacked ? [[entry(left)], ...lines.map((line) => [line])] : lines.map((line, i) => (i === 0 ? [entry(left), line] : [line]));
79
+ });
80
+ }
81
+ const heading = (text) => [{ col: INDENT, text: lit(text), style: TITLE }];
82
+ /** Sentences, each from the left margin on as many rows as it needs, with that margin kept at
83
+ * the right too: its later rows are set in, so the next sentence is seen to start. */
84
+ const sentences = (list, cols) => list.flatMap((sentence) => {
85
+ const [first, ...rest] = flow(words(sentence), cols - 2 * INDENT);
86
+ return [first, ...flow(rest.flatMap(words), cols - 2 * INDENT - 2)].map((text, i) => [{ col: INDENT + (i ? 2 : 0), text: lit(text) }]);
87
+ });
88
+
89
+ /** Every row of the help for an area `cols` wide, before it is scrolled. Unbound actions are
90
+ * listed as such: the table can be changed by the user's tui.json, and the help says what is so
91
+ * now. */
92
+ export function helpRows(actions, ascii, cols = 100) {
93
+ const marks = marksOf(ascii);
94
+ 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 "));
95
+ return [
96
+ heading("Keys"),
97
+ [],
98
+ ...table(actions.map((action) => [action.keys.length ? keyText(keysLabel(action)) : "(no key)", words(action.label)]), cols, KEYS),
99
+ [],
100
+ heading("Marks"),
101
+ [],
102
+ ...table([
103
+ [marks.running, "running"],
104
+ [marks.stopped, "stopped"],
105
+ [marks.shell, "stopped, with a shell left in its terminal"],
106
+ [marks.unknown, "state unknown"],
107
+ [marks.held, "held by a spawn or a retire that is not finished"],
108
+ [`${marks.open} ${marks.closed}`, "has instances below it: shown, folded away"],
109
+ [marks.waiting, "needs input"],
110
+ [`${marks.waiting}N`, "N instances folded away below it need input"],
111
+ [marks.selected, "the selected row, and the pane the movement keys act on"],
112
+ [OPEN_MARK, "among the workspaces: the one that is open"],
113
+ ].map(([mark, meaning]) => [mark, words(meaning)]), cols),
114
+ [],
115
+ heading("Views"),
116
+ [],
117
+ ...table(VIEWS.map((view) => [view.name, view.commands.length ? [...words(`${view.what}:`), ...view.commands.map((command, i) => (i < view.commands.length - 1 ? `${command},` : command))] : words(view.what)]), cols),
118
+ [],
119
+ heading("Machines"),
120
+ [],
121
+ ...sentences(MACHINES, cols),
122
+ [],
123
+ heading("Not in this version"),
124
+ [],
125
+ ...table(NOT_YET.map(({ what, command }) => [what, [command]]), cols),
126
+ ...(closing.width ? [[], [{ col: INDENT, text: closing.text, width: closing.width, style: HINT }, { col: INDENT + closing.width + 1, text: lit("closes this help"), style: HINT }]] : []),
127
+ ];
128
+ }
16
129
 
17
- /** `size.rows` rows for an area `size.cols` wide: a title, one row per action (its keys, then
18
- * what it does), and how to close. */
19
- export function help(actions, size) {
130
+ /** `{ rows, extent }`: `size.rows` rows for an area `size.cols` wide, scrolled to `top`, and how
131
+ * many rows the whole help has. The movement keys scroll it. */
132
+ export function help(actions, size, { top = 0, ascii = false } = {}) {
133
+ const all = helpRows(actions, ascii, size.cols);
20
134
  const rows = Array.from({ length: size.rows }, () => []);
21
- const column = INDENT + Math.max(...actions.map((action) => keysLabel(action).length)) + GAP;
22
- const put = (r, ...spans) => { if (r < size.rows) rows[r] = spans; };
23
- put(1, { col: INDENT, text: lit("Keys"), style: TITLE });
24
- actions.forEach((action, i) => put(3 + i, { col: INDENT, text: lit(keysLabel(action)), style: KEYS }, { col: column, text: lit(action.label) }));
25
- const closing = ["close", "help"].map((id) => actions.find((action) => action.id === id)).filter(Boolean).map((action) => keyLabel(action.keys[0]));
26
- if (closing.length) put(4 + actions.length, { col: INDENT, text: lit(`${closing.join(" or ")} closes this help`), style: HINT });
27
- return rows;
135
+ const win = windowOf({ top, count: all.length, height: size.rows });
136
+ all.slice(win.top, win.top + win.size).forEach((spans, i) => { rows[i] = spans; });
137
+ const note = cutNote(win.above, win.below);
138
+ if (note && size.rows > 0) rows[size.rows - 1] = [{ col: INDENT, text: lit(note), style: HINT }];
139
+ return { rows, extent: all.length };
28
140
  }
@@ -0,0 +1,137 @@
1
+ // The list of instances: (model, pane) -> rows of spans. Pure: no IO, no clock, no escape byte.
2
+ // Every name, word and reason in it is text the TUI did not write and goes through shown(); the
3
+ // marks and the few words around them are the TUI's own. Nothing is told by colour alone: each
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.
7
+ import { lit, shown, shownEnd, textOf } from "../term/text.mjs";
8
+ import { style } from "../term/style.mjs";
9
+ import { textWidth } from "../term/width.mjs";
10
+
11
+ /** The marks, in UTF-8 and in ASCII (docs/tui.md lists them; the help view draws them from here).
12
+ * 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). */
14
+ 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: "!" }),
17
+ });
18
+ export const marksOf = (ascii) => (ascii ? MARKS.ascii : MARKS.utf8);
19
+
20
+ /** Two cells of indent per level, and no deeper than this many levels: a deeper row sits at the last. */
21
+ const INDENT = 2, LEVELS = 6;
22
+ /** The cells kept at the right edge for the waiting mark: `!`, `!N`, `!NN`, `!99+`. */
23
+ 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
+
28
+ /** A heading starts here: at the margin the header and the footer keep, not at a row's indent. */
29
+ const HEAD = 1;
30
+ /** The cells between two parts of a heading. */
31
+ const GAP = 2;
32
+ /** The fewest cells a heading's short reason or its path is drawn in when it is cut: under them
33
+ * it is left out, since a few cells of either say nothing. */
34
+ 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. */
37
+ const SENTENCE_INDENT = 3;
38
+
39
+ const PLAIN = style();
40
+ const BOLD = style({ bold: true });
41
+ const DIM = style({ dim: true });
42
+ 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" }) });
44
+ const WAITS = style({ fg: "yellow", bold: true });
45
+ const WAITS_SELECTED = style({ reverse: true, bold: true });
46
+
47
+ export const EMPTY_TEXT = Object.freeze({
48
+ reading: "Reading the deployment.",
49
+ none: "No instances in this deployment.",
50
+ nomatch: "No instance matches the filter.",
51
+ });
52
+
53
+ /** Text the TUI did not write, with the cells its display takes: `{ text, width }`. What stands
54
+ * after it on a row is placed by that width. */
55
+ export function measured(value) {
56
+ const text = shown(value);
57
+ return { text, width: textWidth(textOf(text)) };
58
+ }
59
+
60
+ const waitingText = (row) => (row.below > 99 ? "!99+" : row.below > 0 ? `!${row.below}` : row.waiting ? "!" : null);
61
+
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. */
65
+ function instanceRow(row, cols, wordWidth, marks) {
66
+ const look = (own) => (row.selected ? SELECTED : own);
67
+ const at = Math.min(row.depth, LEVELS - 1) * INDENT;
68
+ const wordCol = Math.max(0, cols - WAITING - 1 - wordWidth);
69
+ const nameCol = LEAD + at;
70
+ const spans = [];
71
+ 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 });
76
+ const waits = waitingText(row);
77
+ if (waits) spans.push({ col: cols - waits.length, text: lit(waits), style: row.selected ? WAITS_SELECTED : WAITS, width: waits.length });
78
+ return spans;
79
+ }
80
+
81
+ /** A deployment's heading in a pane `cols` wide: its label in bold, its path, and, when it is not
82
+ * live, the shared word for its state and the short reason; at the right edge the time a machine
83
+ * reported its rows at. The state and the time always stand. When the row is too narrow for the
84
+ * 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) {
87
+ const spans = [], edge = cols - 1;
88
+ let limit = edge;
89
+ if (readAt) {
90
+ const read = `read ${readAt}`, col = Math.max(HEAD, edge - read.length);
91
+ spans.push({ col, text: lit(read), style: DIM, width: Math.max(0, Math.min(read.length, edge - col)) });
92
+ limit = col - GAP;
93
+ }
94
+ const name = measured(label), word = state ? measured(state) : null, why = state && short ? measured(short) : null, where = path ? measured(path) : null;
95
+ let room = limit - HEAD - (word ? GAP + word.width : 0);
96
+ const nameWidth = Math.max(0, Math.min(name.width, room));
97
+ room -= nameWidth;
98
+ /** The cells a part after the label gets: its own, or what is left when that is enough to read. */
99
+ const taken = (part) => (part && part.width > 0 && room - GAP >= Math.min(part.width, PART_MIN) ? Math.min(part.width, room - GAP) : 0);
100
+ const whyWidth = taken(why);
101
+ if (whyWidth) room -= GAP + whyWidth;
102
+ const whereWidth = taken(where);
103
+ let col = HEAD;
104
+ if (nameWidth) { spans.push({ col, text: name.text, style: BOLD, width: nameWidth }); col += nameWidth + GAP; }
105
+ // A path is read from its end: cut, it keeps its last cells.
106
+ if (whereWidth) { spans.push({ col, text: whereWidth < where.width ? shownEnd(path, whereWidth, { ascii }) : where.text, style: DIM, width: whereWidth }); col += whereWidth + GAP; }
107
+ if (word) { spans.push({ col, text: word.text, style: PLAIN, width: Math.max(0, Math.min(word.width, edge - col)) }); col += word.width + GAP; }
108
+ if (whyWidth) spans.push({ col, text: why.text, style: DIM, width: whyWidth });
109
+ return spans.filter((span) => span.width > 0);
110
+ }
111
+
112
+ /** How many rows are cut off, in the TUI's words: `12 more below`. */
113
+ export function cutNote(above, below) {
114
+ return [above > 0 ? `${above} more above` : null, below > 0 ? `${below} more below` : null].filter(Boolean).join(", ");
115
+ }
116
+
117
+ /** `size.rows` rows for a pane `size.cols` wide: the model's window of the list, one item per row,
118
+ * and on the last row what is cut off above and below. An item is an instance, a deployment's
119
+ * heading, one row of a sentence the model wrapped (safe text already, placed as it is), a line
120
+ * of the TUI's own, the one line that says why no instance is listed, or nothing (an empty row). */
121
+ export function instances(m, size) {
122
+ const rows = Array.from({ length: size.rows }, () => []);
123
+ if (size.rows < 1) return rows;
124
+ const marks = marksOf(m.ascii);
125
+ const aside = Math.max(0, size.cols - LEAD + 2), sentence = Math.max(0, size.cols - SENTENCE_INDENT - 1);
126
+ m.list.forEach((item, i) => {
127
+ if (!item || i >= size.rows) return;
128
+ if (item.heading) rows[i] = headingRow(item.heading, size.cols, m.ascii);
129
+ else if (item.line) rows[i] = [{ col: SENTENCE_INDENT, text: item.line, width: sentence }];
130
+ 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 }];
132
+ else rows[i] = instanceRow(item, size.cols, m.wordWidth, marks);
133
+ });
134
+ const note = cutNote(m.above, m.below);
135
+ if (note) rows[size.rows - 1] = [{ col: LEAD - 2, text: lit(note), style: DIM, width: aside }];
136
+ return rows;
137
+ }
@@ -0,0 +1,19 @@
1
+ // The window of a scrolling pane: which of `count` rows a pane `height` rows tall shows. Pure
2
+ // arithmetic, shared by the store (which keeps `top`) and the views (which draw it), so the two
3
+ // can never disagree about what is on the screen.
4
+
5
+ /** `{ top, size, above, below }`: the first row shown, how many are shown, and how many are cut
6
+ * off on each side. When rows are cut off the pane's last row is given up to say so, hence
7
+ * `size` is one less than `height` then. `keep` is a row that must stay inside the window (the
8
+ * selection), or -1: `top` moves the least that keeps it there. */
9
+ export function windowOf({ top = 0, count, height, keep = -1 }) {
10
+ if (height < 1 || count < 1) return { top: 0, size: 0, above: 0, below: Math.max(0, count) };
11
+ if (count <= height) return { top: 0, size: count, above: 0, below: 0 };
12
+ const size = Math.max(1, height - 1);
13
+ let first = Math.min(Math.max(0, top), count - size);
14
+ if (keep >= 0 && keep < count) {
15
+ if (keep < first) first = keep;
16
+ else if (keep >= first + size) first = keep - size + 1;
17
+ }
18
+ return { top: first, size, above: first, below: count - first - size };
19
+ }