@awebai/oats 0.65.0 → 0.67.1

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 (75) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +74 -20
  3. package/docs/capabilities.md +4 -4
  4. package/docs/capability-manifest.schema.json +1 -1
  5. package/docs/desktop-cli-api.md +222 -10
  6. package/docs/desktop.md +101 -22
  7. package/docs/implementation.md +16 -6
  8. package/docs/integrations.md +1 -1
  9. package/docs/official-catalog.md +2 -2
  10. package/docs/packages.md +7 -7
  11. package/docs/release-lane.md +16 -0
  12. package/docs/release-notes/v0.66.0.md +183 -0
  13. package/docs/release-notes/v0.67.0.md +366 -0
  14. package/docs/release-notes/v0.67.1.md +64 -0
  15. package/docs/servers.md +5 -4
  16. package/docs/souls-and-instances.md +20 -3
  17. package/docs/tui.md +658 -143
  18. package/docs/upgrading.md +107 -25
  19. package/docs/workspaces.md +9 -2
  20. package/lib/capability-contract.mjs +2 -2
  21. package/lib/core.mjs +126 -54
  22. package/lib/deployments.mjs +21 -5
  23. package/lib/instance-color.mjs +58 -0
  24. package/lib/instance-inspect.mjs +107 -23
  25. package/lib/instance-lifecycle.mjs +21 -1
  26. package/lib/instance-naming.mjs +187 -0
  27. package/lib/instance-resolution.mjs +5 -1
  28. package/lib/materialize.mjs +62 -11
  29. package/lib/servers.mjs +15 -6
  30. package/lib/soul-composition.mjs +7 -3
  31. package/package-catalog.json +2 -2
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +37 -5
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/composed-gate.mjs +10 -2
  36. package/packages/client/deployment-data.mjs +5 -0
  37. package/packages/client/deployment-identity.mjs +40 -0
  38. package/packages/client/deployment-panel.mjs +3 -1
  39. package/packages/client/inspect-boundary.mjs +11 -7
  40. package/packages/client/inspect-cache.mjs +2 -2
  41. package/packages/client/instance-name.mjs +28 -0
  42. package/packages/client/instance-presentation.mjs +11 -0
  43. package/packages/client/keymap.mjs +99 -11
  44. package/packages/client/keys-file.mjs +122 -0
  45. package/packages/client/machine-contract.mjs +1 -5
  46. package/packages/client/own-codes.mjs +4 -2
  47. package/packages/client/panel-views.mjs +62 -9
  48. package/packages/client/spawn-naming.mjs +31 -0
  49. package/packages/client/spawn-preview-cli.mjs +22 -7
  50. package/packages/client/spawn-preview-contract.mjs +24 -0
  51. package/packages/client/spawn-preview-facts.mjs +8 -4
  52. package/packages/client/spawn-preview.mjs +47 -2
  53. package/packages/record/bin/setup.mjs +10 -2
  54. package/packages/record/docs/capture-service.md +45 -6
  55. package/packages/record/lib/capture-service-install.mjs +6 -95
  56. package/packages/record/lib/capture-setup-write.mjs +233 -0
  57. package/packages/tui/README.md +9 -8
  58. package/packages/tui/lib/actions.mjs +108 -64
  59. package/packages/tui/lib/client.mjs +8 -3
  60. package/packages/tui/lib/config.mjs +208 -26
  61. package/packages/tui/lib/main.mjs +91 -20
  62. package/packages/tui/lib/model.mjs +167 -61
  63. package/packages/tui/lib/read.mjs +53 -1
  64. package/packages/tui/lib/store.mjs +156 -47
  65. package/packages/tui/lib/term/keys.mjs +150 -34
  66. package/packages/tui/lib/term/kitty.mjs +223 -0
  67. package/packages/tui/lib/term/through.mjs +174 -27
  68. package/packages/tui/lib/term/tty.mjs +43 -12
  69. package/packages/tui/lib/views/frame.mjs +158 -79
  70. package/packages/tui/lib/views/help.mjs +143 -21
  71. package/packages/tui/lib/views/instances.mjs +59 -20
  72. package/packages/tui/lib/views/palette.mjs +14 -4
  73. package/packages/tui/lib/views/souls.mjs +2 -2
  74. package/packages/tui/lib/views/switcher.mjs +6 -1
  75. package/skills/oats-getting-started/SKILL.md +107 -34
@@ -2,10 +2,10 @@
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 { LEADER, backKeyLabel, keyLabel } from "../actions.mjs";
5
+ import { LEADER, backKeyLabel, keyLabel, keysTogether } from "../actions.mjs";
6
6
  import { lit, ownEllipsis } from "../term/text.mjs";
7
7
  import { style } from "../term/style.mjs";
8
- import { cutNote, marksOf, measured } from "./instances.mjs";
8
+ import { NEEDS_INPUT, belowText, cutNote, marksOf, measured } from "./instances.mjs";
9
9
  import { windowOf } from "./scroll.mjs";
10
10
  import { SOUL_MARK } from "./souls.mjs";
11
11
  import { OPEN_MARK } from "./switcher.mjs";
@@ -38,7 +38,7 @@ export const NOT_YET = Object.freeze([
38
38
  Object.freeze({ what: "see a capability's skills and files", command: "oats capabilities show <name>" }),
39
39
  Object.freeze({ what: "open an agent in its own tmux window", command: "oats session attach --home <home>" }),
40
40
  Object.freeze({ what: "start with another harness or model", command: "oats session start --home <home>" }),
41
- Object.freeze({ what: "add a machine to this workspace", command: "oats server connect <id> --ssh <alias>" }),
41
+ Object.freeze({ what: "add a machine to this workspace", command: "oats server connect <id> --ssh <alias> --dir <path on that machine>" }),
42
42
  Object.freeze({ what: "check a machine", command: "oats server check <id>" }),
43
43
  Object.freeze({ what: "remove a machine", command: "oats server remove <id>" }),
44
44
  // The switcher lists the deployments opened in this run and those on this computer's list, and no other.
@@ -68,10 +68,11 @@ const flow = (pieces, room) => pieces.reduce((lines, piece) => {
68
68
  return lines;
69
69
  }, []);
70
70
  /** A table: a left column as wide as its widest entry, then what each entry means, given as
71
- * pieces that are never broken (a word, or a whole command: a command cut in two cannot be
72
- * typed). What does not fit `cols` goes on in the same column on the next row. A table with a
73
- * piece wider than that column puts every meaning under its entry instead, so no row is cut at
74
- * the smallest width the frame draws at; a piece wider than even that starts further left. */
71
+ * pieces that are never cut (a word, or a whole command: a command cut short cannot be typed).
72
+ * What does not fit `cols` goes on in the same column on the next row. A table with a piece
73
+ * wider than that column puts every meaning under its entry instead, so no row is cut at the
74
+ * smallest width the frame draws at; a piece wider than even that starts further left, and a
75
+ * command wider than the whole area is broken before its flags (commandRows). */
75
76
  function table(pairs, cols, look) {
76
77
  // An entry is the TUI's own word, or text made elsewhere with its width (a key's label). A
77
78
  // third member makes rows of its own under the entry's meaning: given the meaning's column and
@@ -85,12 +86,27 @@ function table(pairs, cols, look) {
85
86
  return pairs.flatMap(([left, pieces]) => {
86
87
  // A row wider than its column (a whole command, in a narrow area) starts as far left as it
87
88
  // must to stand whole, down to the area's first column: a command cut short cannot be typed.
88
- const lines = flow(pieces, cols - at).map((text) => ({ col: Math.max(0, Math.min(at, cols - text.length)), text: lit(text) }));
89
+ const lines = flow(pieces, cols - at).flatMap((text) => (text.length <= cols ? [{ col: Math.max(0, Math.min(at, cols - text.length)), text: lit(text) }] : commandRows(text, at, cols)));
89
90
  const more = (under.get(pieces)?.(cols - at) ?? []).map((spans) => spans.map((span) => ({ ...span, col: span.col + at })));
90
91
  return [...(stacked ? [[entry(left)], ...lines.map((line) => [line])] : lines.map((line, i) => (i === 0 ? [entry(left), line] : [line]))), ...more];
91
92
  });
92
93
  }
93
94
 
95
+ /** A command wider than the whole area (`oats server connect`'s, at 80 columns and under), on as
96
+ * few rows as it needs: broken only before a flag (`--dir`), each flag with its value, the rows
97
+ * after the first 2 cells further in, so read in order they are the command, and every row
98
+ * stands whole inside the area, as far right as `at` when there is room. */
99
+ function commandRows(command, at, cols) {
100
+ const rows = command.split(/ (?=--)/).reduce((rows, part) => {
101
+ const last = rows.length - 1;
102
+ if (last >= 0 && rows[last].length + 1 + part.length <= (last === 0 ? cols : cols - 2)) rows[last] += ` ${part}`;
103
+ else rows.push(part);
104
+ return rows;
105
+ }, []);
106
+ const start = Math.max(0, Math.min(at, cols - Math.max(rows[0].length, ...rows.slice(1).map((row) => row.length + 2))));
107
+ return rows.map((row, i) => ({ col: start + (i === 0 ? 0 : 2), text: lit(row) }));
108
+ }
109
+
94
110
  /** The TUI's own sentences under the line of `open` in the list of instances: what the terminal
95
111
  * takes, what it does not do, and where the keys that can be the back key are listed (the help
96
112
  * does not restate the grammar). */
@@ -102,7 +118,7 @@ export const OPEN_RULES = Object.freeze([
102
118
  /** The rows under the line of `open`, in `room` cells: the leader then Esc, which takes the focus
103
119
  * from the open terminal, and the leader twice, which types it into the terminal (tui.json's
104
120
  * open.detachKey, text from outside), then OPEN_RULES, each sentence on as many rows as it needs. */
105
- function openRows(detachKey, room) {
121
+ function openRows(detachKey, room, chorded = false) {
106
122
  const label = backKeyLabel(detachKey), esc = keyLabel(LEADER.find((entry) => entry.does === "list").keys[0]);
107
123
  const pair = (keys, said) => {
108
124
  const key = keyText(keys), lines = flow(words(said), Math.max(1, room - key.width - 1));
@@ -111,9 +127,11 @@ function openRows(detachKey, room) {
111
127
  return [
112
128
  ...pair(`${label} ${esc}`, "takes the focus from the terminal back to the list; the agent keeps running."),
113
129
  ...pair(`${label} ${label}`, "types the leader into the terminal."),
114
- ...OPEN_RULES.flatMap((sentence) => flow(words(sentence), room).map((text) => [{ col: 0, text: lit(text) }])),
130
+ ...[...OPEN_RULES, ...(chorded ? [CHORD_OPEN_RULE] : [])].flatMap((sentence) => flow(words(sentence), room).map((text) => [{ col: 0, text: lit(text) }])),
115
131
  ];
116
132
  }
133
+ /** Under OPEN_RULES, while the chords are listed: they too are the TUI's in a terminal. */
134
+ export const CHORD_OPEN_RULE = "The chords are taken there too: they never reach the agent.";
117
135
  /** The TUI's own sentences under the line of the last act: how a confirmation is worked, and that
118
136
  * what it sent is never ended by the TUI. */
119
137
  export const ACT_RULES = Object.freeze([
@@ -132,6 +150,86 @@ const sentences = (list, cols) => list.flatMap((sentence) => {
132
150
  /** What the leader pressed again does, the last line of the leader's table. */
133
151
  export const LEADER_AGAIN = "the leader again: types it into the terminal that has the focus; with the list focused, closes the hint";
134
152
 
153
+ /** THE CHORDS (docs/tui.md, "Chords"): the chords read now, the extras of the leader, which is the
154
+ * key that always works. While the terminal confirms the kitty keyboard protocol they lead the
155
+ * help, first of all; without it only the Alt+Shift arrows are read, listed after the leader's
156
+ * section. What a
157
+ * terminal may take first is said, and where the table of terminals is, as sentences the help
158
+ * flows. */
159
+ export const CHORD_RULES = Object.freeze([
160
+ "Your terminal may take some first: Windows Terminal takes Ctrl+Alt+1 to Ctrl+Alt+9 for its own tabs, and the Alt+Shift arrows while its panes are split.",
161
+ "Terminals without the kitty keyboard protocol (GNOME Terminal and the other VTE terminals, Konsole before 26.08, WezTerm unless enable_kitty_keyboard is set) send only the Alt+Shift arrows.",
162
+ "On a keyboard layout where AltGr is Ctrl+Alt (Windows), a Ctrl+Alt key that types a character types it.",
163
+ "The leader works in every terminal.",
164
+ "docs/tui.md, \"Chords\", has the table of terminals.",
165
+ ]);
166
+ /** THE FAMILY (docs/tui.md, "Switch to Ctrl+Shift"): the sentences that lead the chords' section,
167
+ * for `keys`, the model's `{ family, label, note }` (keys.json as lib/config.mjs loadKeys read it, and
168
+ * the shared chordFamilyNote's line, or null), while the terminal confirms the kitty keyboard
169
+ * protocol (`confirmed`) or not. Which family is bound: Ctrl+Alt, with how to switch; Ctrl+Shift,
170
+ * from keys.json, and, without the protocol, that this terminal cannot send it, so the leader is
171
+ * the way (the Alt+Shift arrows still come). Then the note, when the file was there and not taken.
172
+ * No `keys` (a view drawn without a run): none. macOS has no chords, so no section and no line. */
173
+ export function chordFamilyLines(keys, confirmed) {
174
+ if (!keys) return [];
175
+ const shift = "Ctrl+Shift";
176
+ const said = keys.family !== "ctrl+shift"
177
+ ? `Shortcuts: ${keys.label}. For ${shift} (foot, Alacritty), set "chords": "ctrl+shift" in keys.json and restart.`
178
+ : confirmed ? `Shortcuts: ${shift}, from keys.json.`
179
+ : `Shortcuts: ${shift}, from keys.json, but this terminal does not confirm the kitty keyboard protocol: use the leader.`;
180
+ return typeof keys.note === "string" ? [said, keys.note] : [said];
181
+ }
182
+
183
+ /** The chords listed on one row of their own, both keys first, their modifiers said once
184
+ * (`Alt+Shift+Up/Down`, actions.mjs keysTogether, as the cheat sheet says them): the leader's Up
185
+ * and Down, its Left and Right. The table's left column stays narrow enough for the help beside
186
+ * the sidebar at 80 columns. */
187
+ const CHORD_PAIRS = Object.freeze([Object.freeze(["previous", "next"]), Object.freeze(["tab-previous", "tab-next"])]);
188
+ /** The chords' own (actions.mjs CHORD_OWN), the Nth tab: one row for the nine, as the TUI's words. */
189
+ const TAB_N = /^tab-([1-9])$/;
190
+ const TABS_SAID = "the focused group's first to eighth tab, 9 its last";
191
+ /** Two labels of the leader's table as one: `previous instance` and `next instance` are
192
+ * `previous and next instance`. */
193
+ function bothSaid(a, b) {
194
+ const [x, y] = [words(a), words(b)];
195
+ return x.length > 1 && x.at(-1) === y.at(-1) ? `${x.slice(0, -1).join(" ")} and ${y.join(" ")}` : `${a} and ${b}`;
196
+ }
197
+ /** The chords' rows: `chords` are `[key id, does]` in the table's order, each said as the leader's
198
+ * table says its `does`, then `or <the leader> then <its key>` (`detachKey`'s label, when one is
199
+ * given); a pair of CHORD_PAIRS on one row, and the nine tab-N on one, `Ctrl+Alt+1 … Ctrl+Alt+9`
200
+ * (`...` in ASCII), which no leader's key does. The family's lines lead them (chordFamilyLines:
201
+ * `keys`, under the protocol or not, `confirmed`). */
202
+ function chordRows(chords, cols, detachKey, ascii, keys = null, confirmed = false) {
203
+ const by = (does) => LEADER.find((entry) => entry.does === does);
204
+ const leader = typeof detachKey === "string" ? backKeyLabel(detachKey) : null;
205
+ const then = (list) => (leader === null || list.some((does) => !by(does)) ? "" : `, or ${leader} then ${list.map((does) => keyLabel(by(does).keys[0])).join(" and ")}`);
206
+ const keyOf = new Map(chords.map(([key, does]) => [does, key]));
207
+ const tabs = chords.filter(([, does]) => TAB_N.test(does));
208
+ const done = new Set(), rows = [];
209
+ for (const [key, does] of chords) {
210
+ if (done.has(does)) continue;
211
+ const pair = CHORD_PAIRS.find((each) => each.includes(does) && each.every((one) => keyOf.has(one)));
212
+ if (pair) {
213
+ pair.forEach((one) => done.add(one));
214
+ rows.push([keysTogether(pair.map((one) => keyOf.get(one))), `${bothSaid(by(pair[0]).label, by(pair[1]).label)}${then(pair)}`]);
215
+ } else if (TAB_N.test(does) && tabs.length === 9) {
216
+ tabs.forEach(([, one]) => done.add(one));
217
+ rows.push([ownEllipsis(`${keyLabel(tabs[0][0])} \u2026 ${keyLabel(tabs[8][0])}`, ascii), TABS_SAID]);
218
+ } else {
219
+ const n = TAB_N.exec(does)?.[1];
220
+ rows.push([keyLabel(key), n === undefined ? `${by(does)?.label ?? does}${then([does])}` : n === "9" ? "the focused group's last tab" : `the focused group's tab ${n}`]);
221
+ }
222
+ }
223
+ return [
224
+ heading("Chords"),
225
+ [],
226
+ ...sentences(chordFamilyLines(keys, confirmed), cols),
227
+ ...sentences(["One keypress each, from every focus, a terminal's too: none reaches the agent."], cols),
228
+ ...table(rows.map(([keys, said]) => [keyText(keys), words(said)]), cols, KEYS),
229
+ ...sentences(CHORD_RULES, cols),
230
+ ];
231
+ }
232
+
135
233
  /** The palette's keys (docs/tui.md, "The palette"): it reads its keys itself, so they are fixed
136
234
  * and the TUI's words. */
137
235
  export const PALETTE_KEYS = Object.freeze([
@@ -139,7 +237,24 @@ export const PALETTE_KEYS = Object.freeze([
139
237
  Object.freeze(["Enter", "run the selected row"]),
140
238
  Object.freeze(["Esc", "close the palette"]),
141
239
  ]);
142
- const paletteRows = (cols) => [heading("The palette"), [], ...table(PALETTE_KEYS.map(([keys, said]) => [keys, words(said)]), cols, KEYS)];
240
+ /** What the palette's own keys do (actions.mjs paletteKeys), said on a row of their own after its
241
+ * Up and Down, where the TUI has them (not on macOS). */
242
+ export const PALETTE_GROUP_WORDS = "the first row of the group before, or of the next; past either end it wraps";
243
+ /** The key ids of the palette's own keys (`paletteKeys`, `[key id, does]`, the model's), the
244
+ * group before's then the next's, as Up then Down; null unless it has both (none on macOS). The
245
+ * help and the cheat sheet (views/frame.mjs) name them so. */
246
+ export function paletteGroupKeys(paletteKeys) {
247
+ const keyOf = new Map((paletteKeys ?? []).map(([key, does]) => [does, key]));
248
+ const pair = ["palette-previous-group", "palette-next-group"].map((does) => keyOf.get(does));
249
+ return pair.every((key) => key !== undefined) ? pair : null;
250
+ }
251
+ /** The palette's section: PALETTE_KEYS, and after its Up and Down the row of its own keys
252
+ * (paletteGroupKeys), where it has them. */
253
+ function paletteRows(cols, paletteKeys) {
254
+ const pair = paletteGroupKeys(paletteKeys), rows = PALETTE_KEYS.map(([keys, said]) => [keys, words(said)]);
255
+ if (pair !== null) rows.splice(1, 0, [pair.map(keyLabel).join(", "), words(PALETTE_GROUP_WORDS)]);
256
+ return [heading("The palette"), [], ...table(rows, cols, KEYS)];
257
+ }
143
258
 
144
259
  /** The leader's rows (docs/tui.md, "The leader"): its key, then the table of what each key after
145
260
  * it does (actions.mjs LEADER), from every focus. */
@@ -180,23 +295,30 @@ const spawnRows = (cols) => [heading("The spawn prompt"), [], ...table(SPAWN_KEY
180
295
  * listed as such: the table can be changed by the user's tui.json, and the help says what is so
181
296
  * now. An action that does one thing in each view has a line per view, its key on each; under
182
297
  * the line of opening an agent stand the back key (`detachKey`, tui.json's `open.detachKey`) and
183
- * the rules of OPEN_RULES; under the line of the last act, ACT_RULES. After the leader's table,
184
- * the palette's keys (PALETTE_KEYS) and the spawn prompt's (SPAWN_KEYS, SPAWN_RULES). */
185
- export function helpRows(actions, ascii, cols = 100, detachKey = null) {
186
- const marks = marksOf(ascii);
298
+ * the rules of OPEN_RULES; under the line of the last act, ACT_RULES. The chords read now
299
+ * (`chords`, `[key id, does]`; none, or null, lists none) lead the whole help while the terminal
300
+ * confirms the kitty keyboard protocol (`chordsLead`), before this table; without it they come
301
+ * after the leader's table. Then the palette's keys (PALETTE_KEYS, and its own keys `paletteKeys`,
302
+ * `[key id, does]`, where there are any: paletteRows) and the spawn prompt's (SPAWN_KEYS,
303
+ * SPAWN_RULES). `keys` is the family the chords are bound in, `{ family, note }` (chordFamilyLines),
304
+ * said at the top of the chords' section; null says none. */
305
+ export function helpRows(actions, ascii, cols = 100, detachKey = null, chords = null, chordsLead = false, paletteKeys = null, keys = null) {
306
+ const marks = marksOf(ascii), chorded = chords !== null && chords.length > 0;
187
307
  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 "));
188
308
  return [
309
+ ...(chorded && chordsLead ? [...chordRows(chords, cols, detachKey, ascii, keys, true), []] : []),
189
310
  heading("Keys"),
190
311
  [],
191
312
  ...table(actions.flatMap((action) => {
192
313
  const left = action.keys.length ? keyText(keysLabel(action)) : "(no key)";
193
314
  if (!action.views) return [[left, words(action.label)]];
194
- return action.views.map(([view, said]) => [left, words(said), action.id === "open" && view === "instances" && detachKey !== null ? (room) => openRows(detachKey, room)
315
+ return action.views.map(([view, said]) => [left, words(said), action.id === "open" && view === "instances" && detachKey !== null ? (room) => openRows(detachKey, room, chorded)
195
316
  : action.id === "restart" ? actRows : undefined]);
196
317
  }), cols, KEYS),
197
318
  ...(detachKey !== null ? [[], ...leaderRows(detachKey, cols)] : []),
319
+ ...(chorded && !chordsLead ? [[], ...chordRows(chords, cols, detachKey, ascii, keys, false)] : []),
198
320
  [],
199
- ...paletteRows(cols),
321
+ ...paletteRows(cols, paletteKeys),
200
322
  [],
201
323
  ...spawnRows(cols),
202
324
  [],
@@ -209,8 +331,8 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null) {
209
331
  [marks.unknown, "state unknown"],
210
332
  [marks.held, ownEllipsis("held by a spawn or a retire: under way (Retiring\u2026), failed or not finished", ascii)],
211
333
  ["+N", "N instances folded away below it"],
212
- [marks.waiting, "needs input"],
213
- [`${marks.waiting}N`, "N instances folded away below it need input"],
334
+ [marks.waiting, `needs input, in reverse video: ${NEEDS_INPUT} where the whole name fits`],
335
+ ["N", `N instances folded away below it need input: ${belowText("N")} where the whole name fits`],
214
336
  [marks.selected, "the selected row, and the pane the movement keys act on"],
215
337
  [OPEN_MARK, "among the workspaces: the one that is open"],
216
338
  [ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8, "among the souls: a soul, in its colour"],
@@ -234,8 +356,8 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null) {
234
356
 
235
357
  /** `{ rows, extent }`: `size.rows` rows for an area `size.cols` wide, scrolled to `top`, and how
236
358
  * many rows the whole help has. The movement keys scroll it. */
237
- export function help(actions, size, { top = 0, ascii = false, detachKey = null } = {}) {
238
- const all = helpRows(actions, ascii, size.cols, detachKey);
359
+ export function help(actions, size, { top = 0, ascii = false, detachKey = null, chords = null, chordsLead = false, paletteKeys = null, keys = null } = {}) {
360
+ const all = helpRows(actions, ascii, size.cols, detachKey, chords, chordsLead, paletteKeys, keys);
239
361
  const rows = Array.from({ length: size.rows }, () => []);
240
362
  const win = windowOf({ top, count: all.length, height: size.rows });
241
363
  all.slice(win.top, win.top + win.size).forEach((spans, i) => { rows[i] = spans; });
@@ -2,11 +2,11 @@
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 `!`. 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.
5
+ // waiting row carries a tag in words, `Needs input`, in reverse video. A row is quiet: its mark
6
+ // and its name, and a word only where the mark can't say it. Children stand under their parent by
7
+ // indentation alone; a folded row says how many it folds away, `+n`, and how many of those wait,
8
+ // `N below`. In a view of two or more deployments the list also holds a heading per deployment
9
+ // and the sentences the model sets under one: a heading says in words what it is of.
10
10
  import { keyLabel } from "../actions.mjs";
11
11
  import { lit, shown, shownEnd, textOf } from "../term/text.mjs";
12
12
  import { style } from "../term/style.mjs";
@@ -23,8 +23,10 @@ export const marksOf = (ascii) => (ascii ? MARKS.ascii : MARKS.utf8);
23
23
 
24
24
  /** Two cells of indent per level, and no deeper than this many levels: a deeper row sits at the last. */
25
25
  const INDENT = 2, LEVELS = 6;
26
- /** The cells kept at the right edge for the waiting mark: `!`, `!N`, `!NN`, `!99+`. */
27
- const WAITING = 4;
26
+ /** The cells every row keeps at its right edge, so the word column stands in one place whether a
27
+ * row waits or not: they hold a needs-input tag in its short form, ` ! ` to ` 99+ `, whose
28
+ * padding is its gap. A tag in words takes more, and one cell of gap before it. */
29
+ const EDGE = 5;
28
30
  /** A row's cells before its name: the selection mark, a gap, the state mark, a gap. */
29
31
  const LEAD = 4;
30
32
  /** The column of the state mark, before a row's indent. */
@@ -51,8 +53,28 @@ const DIM = style({ dim: true });
51
53
  const SELECTED = style({ reverse: true });
52
54
  /** The look of each state mark: the Souls view draws an instance's mark in its detail as the list does. */
53
55
  export const LOOK = Object.freeze({ running: style({ fg: "green" }), stopped: DIM, shell: DIM, unknown: style({ fg: "yellow" }), held: style({ fg: "magenta" }) });
54
- const WAITS = style({ fg: "yellow", bold: true });
55
- const WAITS_SELECTED = style({ reverse: true, bold: true });
56
+ /** The marks an instance's colour (feature instance-color) draws: running in it, stopped and at its shell in
57
+ * it and dim. The shape still says the state; `unknown` and `held` keep their own look whatever the colour. */
58
+ const COLOURED = Object.freeze({ running: false, stopped: true, shell: true });
59
+ /** A state mark's look for a row of colour `colour` (a terminal colour name, or null for none). */
60
+ export function markLook(mark, colour) {
61
+ if (colour && Object.hasOwn(COLOURED, mark)) return style({ fg: colour, dim: COLOURED[mark] });
62
+ return LOOK[mark] ?? LOOK.unknown;
63
+ }
64
+ /** The needs-input tag: reverse video in the waiting colour, so the reverse video alone carries it
65
+ * under NO_COLOR. On the selected row, which is in reverse already, it is the other way round:
66
+ * not reversed, a gap in the selection's bar. */
67
+ const WAITS = style({ fg: "yellow", bold: true, reverse: true });
68
+ const WAITS_SELECTED = style({ fg: "yellow", bold: true });
69
+
70
+ /** The needs-input tag's words, the Desktop's (packages/desktop/renderer/shell.mjs, needsInputMark;
71
+ * a test pins them equal): `Needs input` on a waiting row, `N below` on a row that folds away N
72
+ * waiting rows, `99+ below` past 99. A row that is both says `Needs input`, as the Desktop's does:
73
+ * its own claim wins, and the detail's `below` line names the rest. */
74
+ export const NEEDS_INPUT = "Needs input";
75
+ /** A count of waiting rows as the tag says it, or the help's letter for one (`N`) as it is. */
76
+ const count = (n) => (typeof n === "number" && n > 99 ? "99+" : String(n));
77
+ export const belowText = (n) => `${count(n)} below`;
56
78
 
57
79
  export const EMPTY_TEXT = Object.freeze({
58
80
  reading: "Reading the deployment.",
@@ -70,30 +92,44 @@ export function measured(value) {
70
92
  return { text, width: textWidth(textOf(text)) };
71
93
  }
72
94
 
73
- const waitingText = (row) => (row.below > 99 ? "!99+" : row.below > 0 ? `!${row.below}` : row.waiting ? "!" : null);
95
+ /** A row's needs-input tag, in words and in its short form (`!`, or the count alone), or null when
96
+ * the row neither waits nor folds a waiting row away. Drawn with a cell of padding either side. */
97
+ function tagOf(row, marks) {
98
+ if (row.waiting) return { full: NEEDS_INPUT, short: marks.waiting };
99
+ return row.below > 0 ? { full: belowText(row.below), short: count(row.below) } : null;
100
+ }
74
101
 
75
102
  /** One instance's row in a pane `cols` wide: the state mark, the name cut to what is left, on a
76
103
  * folded row `+n` after the name, the row's word (when it has one) in the word column, and the
77
- * waiting mark at the edge. A row with no word gives its name the word column's cells too. The
104
+ * needs-input tag at the edge. A row with no word gives its name the word column's cells too. The
78
105
  * name wins over the word: it keeps NAME_LEAST cells (all of it when it is shorter), and when the
79
106
  * word column would leave it fewer, the word is cut to what the name leaves, after it, or given
80
107
  * up under WORD_LEAST cells; the mark and the detail still say it. The name is cut before `+n`
81
- * is: the count stays whole beside what is left of the name. Every span has its width, so no
82
- * text can pass its column whatever the terminal thinks a character takes. */
108
+ * is: the count stays whole beside what is left of the name. The tag is the first to give way:
109
+ * it is in words only where the whole name, its count and the word column all fit beside it
110
+ * (the word column then stands left of the tag), and else in its short form, inside the EDGE
111
+ * cells every row keeps, so it never takes a cell from the name, the word or the mark. Every
112
+ * span has its width, so no text can pass its column whatever the terminal thinks a character
113
+ * takes. */
83
114
  function instanceRow(row, cols, wordWidth, marks) {
84
115
  const look = (own) => (row.selected ? SELECTED : own);
85
116
  const at = Math.min(row.depth, LEVELS - 1) * INDENT;
86
117
  const fold = row.folded > 0 ? `+${row.folded}` : null;
87
- const nameCol = LEAD + at, room = cols - WAITING - 1 - nameCol;
118
+ const nameCol = LEAD + at;
88
119
  const name = measured(row.name), claim = Math.min(name.width + (fold ? fold.length + 1 : 0), NAME_LEAST);
120
+ // The tag, and where the name and the word end: before the tag in words and a gap, or the EDGE.
121
+ const hasWord = wordWidth > 0 && row.word !== null && row.word !== undefined;
122
+ const whole = name.width + (fold ? fold.length + 1 : 0) + (hasWord ? 2 + wordWidth : 0);
123
+ const tag = tagOf(row, marks), wide = tag !== null && cols - tag.full.length - 3 - nameCol >= whole;
124
+ const waits = tag && (wide ? tag.full : tag.short), end = wide ? cols - tag.full.length - 3 : cols - EDGE, room = end - nameCol;
89
125
  // The word's cells: its column's, or what the name's claim leaves of the row, or none.
90
126
  const left = room - claim - 2;
91
- const wordCells = wordWidth > 0 && row.word !== null && row.word !== undefined ? (left >= wordWidth ? wordWidth : left >= WORD_LEAST ? left : 0) : 0;
92
- const wordCol = left >= wordWidth ? cols - WAITING - 1 - wordWidth : nameCol + claim + 2;
93
- const nameEnd = wordCells ? wordCol - 2 : cols - WAITING - 1;
127
+ const wordCells = hasWord ? (left >= wordWidth ? wordWidth : left >= WORD_LEAST ? left : 0) : 0;
128
+ const wordCol = left >= wordWidth ? end - wordWidth : nameCol + claim + 2;
129
+ const nameEnd = wordCells ? wordCol - 2 : end;
94
130
  const spans = [];
95
131
  if (row.selected) spans.push({ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(marks.selected), style: SELECTED, width: 1 });
96
- spans.push({ col: MARK + at, text: lit(marks[row.mark] ?? marks.unknown), style: look(LOOK[row.mark] ?? LOOK.unknown), width: 1 });
132
+ spans.push({ col: MARK + at, text: lit(marks[row.mark] ?? marks.unknown), style: look(markLook(row.mark, row.color)), width: 1 });
97
133
  if (nameEnd > nameCol) {
98
134
  // The count and the gap before it, when there is room for them and for a cell of the name.
99
135
  const after = fold && nameEnd - nameCol > fold.length + 1 ? fold.length + 1 : 0;
@@ -102,8 +138,11 @@ function instanceRow(row, cols, wordWidth, marks) {
102
138
  if (after) spans.push({ col: nameCol + nameWidth + 1, text: lit(fold), style: look(DIM), width: fold.length });
103
139
  }
104
140
  if (wordCells) spans.push({ col: wordCol, text: shown(row.word), style: look(DIM), width: wordCells });
105
- const waits = waitingText(row);
106
- if (waits) spans.push({ col: cols - waits.length, text: lit(waits), style: row.selected ? WAITS_SELECTED : WAITS, width: waits.length });
141
+ // The tag: its padding a blank span in its style, the words over it.
142
+ const tagCol = waits ? cols - waits.length - 2 : 0, tagLook = row.selected ? WAITS_SELECTED : WAITS;
143
+ if (waits && tagCol > MARK + at) {
144
+ spans.push({ col: tagCol, width: waits.length + 2, style: tagLook }, { col: tagCol + 1, text: lit(waits), style: tagLook, width: waits.length });
145
+ }
107
146
  return spans;
108
147
  }
109
148
 
@@ -1,10 +1,12 @@
1
1
  // The palette (docs/tui.md, "The palette"): (model, area) -> rows of spans, over the whole body.
2
2
  // Pure: no IO, no clock, no escape byte. One input over a list: the query on the first row, then
3
3
  // the window of the rows lib/model.mjs paletteItems lists, the selected one in reverse with `>`.
4
- // An instance's, a soul's or a capability's name, a machine, an instance's siblings, where a
5
- // capability comes from and the query are text the TUI did not write and go through shown(); the
6
- // labels of the views, the acts and the commands are the TUI's own. Nothing is told by colour
7
- // alone: each row says in a word what kind it is.
4
+ // An instance's, a soul's or a capability's name, a machine, an instance's siblings, a group's
5
+ // label (a cluster's name, a machine's), where a capability comes from and the query are text the
6
+ // TUI did not write and go through shown(); the labels of the views, the acts and the commands are
7
+ // the TUI's own. Nothing is told by colour alone: each row says in a word what kind it is, and a
8
+ // group's label row, dim, which is never selected, stands where no row's mark stands, before the
9
+ // rows it names.
8
10
  import { lit, shown } from "../term/text.mjs";
9
11
  import { style } from "../term/style.mjs";
10
12
  import { cutNote, marksOf, measured } from "./instances.mjs";
@@ -23,8 +25,16 @@ const DIM = style({ dim: true });
23
25
  const SELECTED = style({ reverse: true });
24
26
  const PLAIN = style();
25
27
 
28
+ /** A group's label row in `cols` cells: its label, text from outside, dim at the rows' text
29
+ * column, with no kind word and no mark. */
30
+ function groupRow(item, cols) {
31
+ const label = measured(item.label), width = Math.min(label.width, Math.max(0, cols - LEAD));
32
+ return width > 0 ? [{ col: LEAD, text: label.text, style: DIM, width }] : [];
33
+ }
34
+
26
35
  /** One row of the palette in `cols` cells. */
27
36
  function itemRow(item, cols, marks) {
37
+ if (item.kind === "group") return groupRow(item, cols);
28
38
  const look = (own) => (item.selected ? SELECTED : own);
29
39
  const kind = KINDS[item.kind], kindCol = Math.max(LEAD, cols - kind.length);
30
40
  const spans = [];
@@ -9,7 +9,7 @@
9
9
  import { keyLabel } from "../actions.mjs";
10
10
  import { lit, shown, shownLines } from "../term/text.mjs";
11
11
  import { COLORS, style } from "../term/style.mjs";
12
- import { LOOK, cutNote, headingRow, marksOf, measured } from "./instances.mjs";
12
+ import { cutNote, headingRow, markLook, marksOf, measured } from "./instances.mjs";
13
13
  import { windowOf } from "./scroll.mjs";
14
14
 
15
15
  /** The TUI's own lines in the Souls view. `retry` and `toInstances` stand after the key that does
@@ -245,7 +245,7 @@ export function soulDetailRows(m, cols) {
245
245
  rows.push([label("instances here")]);
246
246
  const marks = marksOf(ascii);
247
247
  const units = [
248
- ...here.shown.map((each) => [{ text: lit(marks[each.mark] ?? marks.unknown), width: 1, style: LOOK[each.mark] ?? LOOK.unknown }, measured(each.name)]),
248
+ ...here.shown.map((each) => [{ text: lit(marks[each.mark] ?? marks.unknown), width: 1, style: markLook(each.mark, each.color) }, measured(each.name)]),
249
249
  ...(here.more > 0 ? [[{ text: lit(`+${here.more}`), width: `+${here.more}`.length, style: DIM }]] : []),
250
250
  ];
251
251
  flowed(units, inner, 2).forEach((spans) => rows.push(spans.map((span) => ({ ...span, col: span.col + INNER }))));
@@ -4,7 +4,8 @@
4
4
  // deployment's name and path and what the kernel said; the marks, the headings of its own and its
5
5
  // few sentences are the TUI's.
6
6
  // Nothing is told by colour alone: the selected row carries `>` as well as reverse video, and
7
- // the workspace that is open carries `*`.
7
+ // the workspace that is open carries `*`. Under a workspace, one dim line per deployment of it says
8
+ // where it is and, when it is not live, its state in words (lib/model.mjs switcher): never a colour.
8
9
  import { lit, shown, shownLines } from "../term/text.mjs";
9
10
  import { style } from "../term/style.mjs";
10
11
  import { cutNote, measured } from "./instances.mjs";
@@ -33,6 +34,8 @@ export const SWITCHER_TEXT = Object.freeze({
33
34
  /** The columns of a choice: the selection mark in the first cell, the open mark, then the label.
34
35
  * A heading and every line that is not a choice start two cells before the labels. */
35
36
  const OPEN = 2, LABEL = 4, ASIDE = LABEL - 2;
37
+ /** The column of a workspace's indicator lines: two cells in from its label. */
38
+ const INDICATOR = LABEL + 2;
36
39
  /** One cell of margin at the right edge, as the sidebar keeps. */
37
40
  const MARGIN = 1;
38
41
  /** The cells between two columns. */
@@ -134,6 +137,8 @@ export function switcher(m, size) {
134
137
  const at = lead.length + i;
135
138
  if (at >= size.rows) return;
136
139
  if (item.heading !== undefined) rows[at] = [{ col: ASIDE, text: item.shared ? shown(item.heading) : lit(item.heading), style: DIM, width: aside }];
140
+ // A deployment of the workspace above: the shared machine label and state word, cut at the edge.
141
+ else if (item.indicator !== undefined) rows[at] = cols - MARGIN > INDICATOR ? [{ col: INDICATOR, text: shown(item.indicator), style: DIM, width: cols - MARGIN - INDICATOR }] : [];
137
142
  else rows[at] = choiceRow(item, cols);
138
143
  });
139
144
  if (note) rows[size.rows - 1] = [{ col: ASIDE, text: lit(note), style: DIM, width: aside }];