@awebai/oats 0.66.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 (65) hide show
  1. package/bin/oats.mjs +66 -13
  2. package/docs/capabilities.md +4 -4
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/desktop-cli-api.md +217 -6
  5. package/docs/desktop.md +101 -22
  6. package/docs/implementation.md +6 -5
  7. package/docs/official-catalog.md +1 -1
  8. package/docs/packages.md +5 -5
  9. package/docs/release-lane.md +16 -0
  10. package/docs/release-notes/v0.67.0.md +366 -0
  11. package/docs/release-notes/v0.67.1.md +64 -0
  12. package/docs/servers.md +3 -2
  13. package/docs/souls-and-instances.md +20 -3
  14. package/docs/tui.md +570 -176
  15. package/docs/upgrading.md +107 -25
  16. package/docs/workspaces.md +1 -1
  17. package/lib/capability-contract.mjs +2 -2
  18. package/lib/core.mjs +126 -54
  19. package/lib/instance-color.mjs +58 -0
  20. package/lib/instance-inspect.mjs +107 -23
  21. package/lib/instance-lifecycle.mjs +21 -1
  22. package/lib/instance-naming.mjs +187 -0
  23. package/lib/instance-resolution.mjs +5 -1
  24. package/lib/materialize.mjs +62 -11
  25. package/lib/servers.mjs +15 -6
  26. package/lib/soul-composition.mjs +7 -3
  27. package/package-catalog.json +1 -1
  28. package/package.json +1 -1
  29. package/packages/client/cli-adapter.mjs +37 -5
  30. package/packages/client/cli-locator.mjs +2 -2
  31. package/packages/client/composed-gate.mjs +10 -2
  32. package/packages/client/deployment-data.mjs +5 -0
  33. package/packages/client/deployment-identity.mjs +40 -0
  34. package/packages/client/deployment-panel.mjs +3 -1
  35. package/packages/client/inspect-boundary.mjs +11 -7
  36. package/packages/client/inspect-cache.mjs +2 -2
  37. package/packages/client/instance-name.mjs +28 -0
  38. package/packages/client/instance-presentation.mjs +11 -0
  39. package/packages/client/keymap.mjs +85 -24
  40. package/packages/client/keys-file.mjs +122 -0
  41. package/packages/client/own-codes.mjs +4 -2
  42. package/packages/client/panel-views.mjs +62 -9
  43. package/packages/client/spawn-naming.mjs +31 -0
  44. package/packages/client/spawn-preview-cli.mjs +22 -7
  45. package/packages/client/spawn-preview-contract.mjs +24 -0
  46. package/packages/client/spawn-preview-facts.mjs +8 -4
  47. package/packages/client/spawn-preview.mjs +47 -2
  48. package/packages/tui/README.md +3 -3
  49. package/packages/tui/lib/actions.mjs +57 -14
  50. package/packages/tui/lib/client.mjs +8 -4
  51. package/packages/tui/lib/config.mjs +50 -9
  52. package/packages/tui/lib/main.mjs +40 -13
  53. package/packages/tui/lib/model.mjs +167 -63
  54. package/packages/tui/lib/read.mjs +53 -1
  55. package/packages/tui/lib/store.mjs +148 -54
  56. package/packages/tui/lib/term/keys.mjs +19 -5
  57. package/packages/tui/lib/term/kitty.mjs +36 -11
  58. package/packages/tui/lib/term/through.mjs +61 -28
  59. package/packages/tui/lib/views/frame.mjs +158 -79
  60. package/packages/tui/lib/views/help.mjs +109 -26
  61. package/packages/tui/lib/views/instances.mjs +59 -20
  62. package/packages/tui/lib/views/palette.mjs +14 -4
  63. package/packages/tui/lib/views/souls.mjs +2 -2
  64. package/packages/tui/lib/views/switcher.mjs +6 -1
  65. package/skills/oats-getting-started/SKILL.md +13 -8
@@ -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";
@@ -131,7 +131,7 @@ function openRows(detachKey, room, chorded = false) {
131
131
  ];
132
132
  }
133
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 (below) are taken there too: they never reach the agent.";
134
+ export const CHORD_OPEN_RULE = "The chords are taken there too: they never reach the agent.";
135
135
  /** The TUI's own sentences under the line of the last act: how a confirmation is worked, and that
136
136
  * what it sent is never ended by the TUI. */
137
137
  export const ACT_RULES = Object.freeze([
@@ -150,20 +150,82 @@ const sentences = (list, cols) => list.flatMap((sentence) => {
150
150
  /** What the leader pressed again does, the last line of the leader's table. */
151
151
  export const LEADER_AGAIN = "the leader again: types it into the terminal that has the focus; with the list focused, closes the hint";
152
152
 
153
- /** THE CHORDS (docs/tui.md, "Chords"): listed only while the terminal confirms the kitty keyboard
154
- * protocol, which alone sends them, as extras: the leader is the key that always works. What a
155
- * terminal may take first is said, with foot's list. */
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. */
156
159
  export const CHORD_RULES = Object.freeze([
157
- "Your terminal may take some of these first: foot takes Ctrl+Shift+C, V, R, N, O, U, Z, X and Q. The leader works in every terminal.",
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.",
158
165
  ]);
159
- /** The chords' rows: `chords` are `[key id, does]`, each said as the leader's table says its `does`. */
160
- function chordRows(chords, cols) {
161
- const said = (does) => LEADER.find((entry) => entry.does === does)?.label ?? does;
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
+ }
162
223
  return [
163
224
  heading("Chords"),
164
225
  [],
165
- ...sentences(["Your terminal sends these keys too: each does what the leader then its key does, from every focus, a terminal's too."], cols),
166
- ...table(chords.map(([key, does]) => [keyLabel(key), words(said(does))]), cols, KEYS),
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),
167
229
  ...sentences(CHORD_RULES, cols),
168
230
  ];
169
231
  }
@@ -175,7 +237,24 @@ export const PALETTE_KEYS = Object.freeze([
175
237
  Object.freeze(["Enter", "run the selected row"]),
176
238
  Object.freeze(["Esc", "close the palette"]),
177
239
  ]);
178
- 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
+ }
179
258
 
180
259
  /** The leader's rows (docs/tui.md, "The leader"): its key, then the table of what each key after
181
260
  * it does (actions.mjs LEADER), from every focus. */
@@ -216,26 +295,30 @@ const spawnRows = (cols) => [heading("The spawn prompt"), [], ...table(SPAWN_KEY
216
295
  * listed as such: the table can be changed by the user's tui.json, and the help says what is so
217
296
  * now. An action that does one thing in each view has a line per view, its key on each; under
218
297
  * the line of opening an agent stand the back key (`detachKey`, tui.json's `open.detachKey`) and
219
- * the rules of OPEN_RULES; under the line of the last act, ACT_RULES. After the leader's table,
220
- * the chords (`chords`, `[key id, does]`, or null while the terminal has not confirmed the kitty
221
- * keyboard protocol: then they are not listed), the palette's keys (PALETTE_KEYS) and the spawn
222
- * prompt's (SPAWN_KEYS, SPAWN_RULES). */
223
- export function helpRows(actions, ascii, cols = 100, detachKey = null, chords = null) {
224
- 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;
225
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 "));
226
308
  return [
309
+ ...(chorded && chordsLead ? [...chordRows(chords, cols, detachKey, ascii, keys, true), []] : []),
227
310
  heading("Keys"),
228
311
  [],
229
312
  ...table(actions.flatMap((action) => {
230
313
  const left = action.keys.length ? keyText(keysLabel(action)) : "(no key)";
231
314
  if (!action.views) return [[left, words(action.label)]];
232
- return action.views.map(([view, said]) => [left, words(said), action.id === "open" && view === "instances" && detachKey !== null ? (room) => openRows(detachKey, room, chords !== null && chords.length > 0)
315
+ return action.views.map(([view, said]) => [left, words(said), action.id === "open" && view === "instances" && detachKey !== null ? (room) => openRows(detachKey, room, chorded)
233
316
  : action.id === "restart" ? actRows : undefined]);
234
317
  }), cols, KEYS),
235
318
  ...(detachKey !== null ? [[], ...leaderRows(detachKey, cols)] : []),
236
- ...(chords !== null && chords.length > 0 ? [[], ...chordRows(chords, cols)] : []),
319
+ ...(chorded && !chordsLead ? [[], ...chordRows(chords, cols, detachKey, ascii, keys, false)] : []),
237
320
  [],
238
- ...paletteRows(cols),
321
+ ...paletteRows(cols, paletteKeys),
239
322
  [],
240
323
  ...spawnRows(cols),
241
324
  [],
@@ -248,8 +331,8 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null, chords =
248
331
  [marks.unknown, "state unknown"],
249
332
  [marks.held, ownEllipsis("held by a spawn or a retire: under way (Retiring\u2026), failed or not finished", ascii)],
250
333
  ["+N", "N instances folded away below it"],
251
- [marks.waiting, "needs input"],
252
- [`${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`],
253
336
  [marks.selected, "the selected row, and the pane the movement keys act on"],
254
337
  [OPEN_MARK, "among the workspaces: the one that is open"],
255
338
  [ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8, "among the souls: a soul, in its colour"],
@@ -273,8 +356,8 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null, chords =
273
356
 
274
357
  /** `{ rows, extent }`: `size.rows` rows for an area `size.cols` wide, scrolled to `top`, and how
275
358
  * many rows the whole help has. The movement keys scroll it. */
276
- export function help(actions, size, { top = 0, ascii = false, detachKey = null, chords = null } = {}) {
277
- const all = helpRows(actions, ascii, size.cols, detachKey, chords);
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);
278
361
  const rows = Array.from({ length: size.rows }, () => []);
279
362
  const win = windowOf({ top, count: all.length, height: size.rows });
280
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 }];
@@ -111,9 +111,12 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
111
111
  unless `sudo -n true` succeeds.
112
112
  - **npm's global folder** (`npm prefix -g`) must be writable for step 4's
113
113
  install (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node
114
- under `/usr`), either they run that install with `sudo` in their own
115
- terminal, or set a per-user prefix (`npm config set prefix ~/.local`, with
116
- `~/.local/bin` on their PATH).
114
+ under `/usr`, as NodeSource installs it), either they run that install with
115
+ `sudo` in their own terminal, or set a per-user prefix:
116
+ `npm config set prefix ~/.local`. Then put `~/.local/bin` on PATH: start
117
+ each later command of yours with `export PATH="$HOME/.local/bin:$PATH"`
118
+ (your shell does not reread their profile), and ask them to add that line
119
+ to their shell's startup file so their own terminal finds `oats` too.
117
120
  - **Windows** is not supported.
118
121
 
119
122
  ## 3. Log in to GitHub
@@ -230,9 +233,11 @@ Terminal=false
230
233
  Categories=Development;
231
234
  ```
232
235
 
233
- - **Without FUSE** (the AppImage fails with a FUSE message), add
234
- ` --appimage-extract-and-run` after the AppImage's path in `Exec=` and
235
- wherever you start it.
236
+ - **Without FUSE** (the AppImage fails with a FUSE message; Ubuntu 22.04
237
+ and later ship without `libfuse2`), either they install it in their own
238
+ terminal (`sudo apt install libfuse2`, or `libfuse2t64` on Ubuntu 24.04),
239
+ or add ` --appimage-extract-and-run` after the AppImage's path in `Exec=`
240
+ and wherever you start it.
236
241
  - **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
237
242
  download, say so and go on.
238
243
 
@@ -272,7 +277,7 @@ name: acme
272
277
  members:
273
278
  - git:github.com/acme/acme-oats # the host is a member too
274
279
  packages:
275
- oats.framework: v1.13.4 # the installed CLI's catalog versions (below)
280
+ oats.framework: v1.13.5 # the installed CLI's catalog versions (below)
276
281
  oats.aweb: v1.30.0 # messaging: agent identities, mail and chat
277
282
  defaults:
278
283
  capabilities:
@@ -285,7 +290,7 @@ defaultTeam: acme # every soul starts in this team
285
290
 
286
291
  - **The versions** are the installed CLI's catalog's:
287
292
  `"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
288
- (for example `oats-framework/v1.13.4`: write the part after the `/`) and
293
+ (for example `oats-framework/v1.13.5`: write the part after the `/`) and
289
294
  `packages."oats.aweb".ref` (for example `v1.30.0`).
290
295
  - **The team** is `default:N.aweb.ai`, with `N` the username from step 1;
291
296
  its label (here `acme`) is the workspace name.