@awebai/oats 0.59.0 → 0.61.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 (43) hide show
  1. package/README.md +14 -18
  2. package/bin/oats.mjs +42 -10
  3. package/docs/configuration.md +9 -0
  4. package/docs/desktop-cli-api.md +40 -10
  5. package/docs/desktop.md +7 -0
  6. package/docs/execution-targets.md +7 -2
  7. package/docs/first-team.md +8 -0
  8. package/docs/implementation.md +1 -0
  9. package/docs/integrations.md +1 -1
  10. package/docs/official-catalog.md +2 -2
  11. package/docs/packages.md +7 -7
  12. package/docs/release-notes/v0.60.0.md +104 -0
  13. package/docs/release-notes/v0.61.0.md +155 -0
  14. package/docs/tui.md +133 -19
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +42 -15
  17. package/lib/session-input.mjs +45 -28
  18. package/package-catalog.json +2 -2
  19. package/package.json +1 -1
  20. package/packages/client/capability-catalog.mjs +93 -0
  21. package/packages/client/capability-facts.mjs +59 -0
  22. package/packages/client/capability-rows.mjs +121 -0
  23. package/packages/client/catalog-messages.mjs +12 -0
  24. package/packages/client/cli-locator.mjs +2 -2
  25. package/packages/client/instance-presentation.mjs +10 -0
  26. package/packages/client/instance-tree.mjs +48 -6
  27. package/packages/client/soul-catalog.mjs +8 -0
  28. package/packages/client/soul-facts.mjs +7 -0
  29. package/packages/client/spawn-messages.mjs +8 -0
  30. package/packages/client/subsequence-score.mjs +15 -0
  31. package/packages/tui/README.md +1 -1
  32. package/packages/tui/lib/actions.mjs +1 -1
  33. package/packages/tui/lib/client.mjs +9 -4
  34. package/packages/tui/lib/main.mjs +58 -9
  35. package/packages/tui/lib/model.mjs +150 -50
  36. package/packages/tui/lib/store.mjs +133 -16
  37. package/packages/tui/lib/views/capabilities.mjs +239 -0
  38. package/packages/tui/lib/views/frame.mjs +55 -20
  39. package/packages/tui/lib/views/help.mjs +9 -4
  40. package/packages/tui/lib/views/palette.mjs +13 -4
  41. package/packages/tui/lib/views/souls.mjs +6 -4
  42. package/packages/tui/lib/views/spawn.mjs +5 -3
  43. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -0,0 +1,239 @@
1
+ // The Capabilities view: (model, pane) -> rows of spans, the list of the open workspace's
2
+ // capabilities in their sections and groups, and the selected capability's detail. Pure: no IO, no
3
+ // clock, no escape byte. A capability's name, its description, a group's name and note, the facts
4
+ // of where it comes from and what it provides, the names of the souls that use it, the shared words
5
+ // of the detail (lib/model.mjs passes CAPABILITY_COPY's) and a failed read's sentence are text the
6
+ // TUI did not write and go through shown(); the section titles, the separators and the few lines
7
+ // of CAPABILITIES_TEXT are the TUI's own. Nothing is told by colour alone: the selected row and the
8
+ // marked soul carry `>` as well as reverse video, a soul's colour is drawn on a mark that is there
9
+ // without it, and the souls on an older version are said so in words before their warning style.
10
+ import { lit, shown, shownLines } from "../term/text.mjs";
11
+ import { COLORS, style } from "../term/style.mjs";
12
+ import { keyLabel } from "../actions.mjs";
13
+ import { cutNote, headingRow, marksOf, measured } from "./instances.mjs";
14
+ import { windowOf } from "./scroll.mjs";
15
+ import { COUNT_SIGN, SOUL_MARK, flowed, ownLines } from "./souls.mjs";
16
+
17
+ /** The TUI's own lines in the Capabilities view. The section titles are the Desktop's own
18
+ * (renderer/workspace-catalog.mjs), word for word: the shared home holds none (Spec 7, Settled 6).
19
+ * `retry` stands after the key that reads again (tui.json may rebind it). `reading` and
20
+ * `readingSouls` end in an ellipsis, drawn `...` in ASCII. */
21
+ export const CAPABILITIES_TEXT = Object.freeze({
22
+ reading: "Reading capabilities…",
23
+ none: "This workspace offers no capabilities. `oats capabilities` says why.",
24
+ nomatch: "No capability matches the filter.",
25
+ retry: "reads them again.",
26
+ noWorkspace: "Open a workspace of this machine to see its capabilities.",
27
+ readingSouls: "Reading souls…",
28
+ sections: Object.freeze({ workspace: "Workspace owned", repo: "Repo owned", packages: "Packages" }),
29
+ });
30
+
31
+ /** The columns of the list: the selection mark, a section's title, a group's heading, a capability's name. */
32
+ const SECTION = 1, GROUP = 2, NAME = 4;
33
+ /** Where a line of the TUI's own and a failed read's sentence start in the list (views/souls.mjs). */
34
+ const SENTENCE_INDENT = 3;
35
+ /** The detail's title and headings start here: the first cell holds the mark of the pane with the
36
+ * focus (views/detail.mjs). Each section's lines are set in to INNER. */
37
+ const LEFT = 2, INNER = LEFT + 2;
38
+ /** The fewest cells a fact's value keeps beside its label: under them it goes on the row under it. */
39
+ const VALUE_MIN = 16;
40
+ /** The most rows a wrapped value or sentence takes, and the description. */
41
+ const WRAP_ROWS = 6, DESCRIPTION_ROWS = 8;
42
+
43
+ const PLAIN = style();
44
+ const BOLD = style({ bold: true });
45
+ const DIM = style({ dim: true });
46
+ const SELECTED = style({ reverse: true });
47
+ /** The warning style: what it marks says so in words too. */
48
+ const WARN = style({ bold: true, fg: "yellow" });
49
+
50
+ /** The mark between a group's name and its note, and before the instances on an older version. */
51
+ const dotOf = (ascii) => (ascii ? "-" : "·");
52
+ /** A line of the TUI's own as the screen draws it: the ellipsis is `...` in ASCII. */
53
+ const ownText = (text, ascii) => (ascii ? text.replace(/…/g, "...") : text);
54
+
55
+ /** The first key of the action `id` as the user has it, `{ text, width }`, or null when it has none. */
56
+ function keyOf(m, id) {
57
+ const action = (m.actions ?? []).find((a) => a.id === id && a.keys.length);
58
+ return action ? measured(keyLabel(action.keys[0])) : null;
59
+ }
60
+
61
+ /** Whether the list stands, beside the detail on a wide terminal: once the catalog was read (its
62
+ * rows, or none of them matching the filter), and over the rows a failed re-read kept. A body of
63
+ * one sentence (reading, a failed first read, an empty catalog, no workspace here) has the whole
64
+ * width instead. */
65
+ export function capabilitiesListed(c) {
66
+ return Boolean(c) && c.local !== false && (c.heading != null || c.state === "rows" || c.state === "nomatch" || (c.list?.length ?? 0) > 0);
67
+ }
68
+
69
+ /** Text from outside, then `after` (parts `{ text, style }` of the TUI's own or shown already, each
70
+ * `width` cells) one cell after it, from column `col` in a row ending at `end`: the text is cut
71
+ * before what follows it is, which stands whole beside what is left of it, or not at all when no
72
+ * cell of the text would be left. */
73
+ function nameThen(name, after, col, end, look) {
74
+ const afterWidth = after.reduce((sum, part) => sum + 1 + part.width, 0);
75
+ const kept = end - col > afterWidth ? after : [];
76
+ const room = end - col - (kept.length ? afterWidth : 0);
77
+ if (room <= 0) return [];
78
+ const nameWidth = Math.min(name.width, room);
79
+ const spans = [{ col, text: name.text, style: look(PLAIN), width: kept.length ? nameWidth : room }];
80
+ let at = col + nameWidth;
81
+ for (const part of kept) { at += 1; spans.push({ col: at, text: part.text, style: look(part.style), width: part.width }); at += part.width; }
82
+ return spans;
83
+ }
84
+
85
+ /** One item of the list in a pane `cols` wide: a section's title (bold), a group's heading (dim,
86
+ * `name · note`), or a capability: the selection mark, its name, and its layer's label dim when it
87
+ * has one. One cell is kept at the right edge. */
88
+ function itemRow(item, cols, ascii) {
89
+ const end = cols - 1;
90
+ if (item.section !== undefined) {
91
+ const title = CAPABILITIES_TEXT.sections[item.section];
92
+ return [{ col: SECTION, text: lit(title), style: BOLD, width: Math.max(0, Math.min(title.length, end - SECTION)) }];
93
+ }
94
+ if (item.group !== undefined) {
95
+ const name = measured(item.group), note = item.note ? measured(item.note) : null;
96
+ const spans = [{ col: GROUP, text: name.text, style: DIM, width: Math.max(0, Math.min(name.width, end - GROUP)) }];
97
+ const at = GROUP + name.width;
98
+ if (note && at + 3 < end) spans.push({ col: at + 1, text: lit(dotOf(ascii)), style: DIM, width: 1 }, { col: at + 3, text: note.text, style: DIM, width: Math.max(0, end - at - 3) });
99
+ return spans.filter((span) => span.width > 0);
100
+ }
101
+ const look = (own) => (item.selected ? SELECTED : own);
102
+ const spans = item.selected ? [{ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(marksOf(ascii).selected), style: SELECTED, width: 1 }] : [];
103
+ const layer = item.layer ? measured(item.layer) : null;
104
+ return [...spans, ...nameThen(measured(item.name), layer ? [{ text: layer.text, width: layer.width, style: DIM }] : [], NAME, end, look)];
105
+ }
106
+
107
+ /** `size.rows` rows for the list pane, `size.cols` wide: the model's window of the sections, the
108
+ * groups and the capabilities (after the heading of a failed re-read, when there is one) and on
109
+ * the last row what is cut off; or the one body the catalog's state gives: reading, a failed first
110
+ * read (its sentence, then the key that reads again), an empty catalog, nothing matching the
111
+ * filter, no workspace of this machine. */
112
+ export function capabilitiesList(m, size) {
113
+ const c = m.capabilities, ascii = m.ascii;
114
+ const rows = Array.from({ length: size.rows }, () => []);
115
+ if (size.rows < 1 || !c) return rows;
116
+ const width = Math.max(0, size.cols - SENTENCE_INDENT - 1);
117
+ /** A line of the TUI's own, dim, from row `at` on: the rows it took. */
118
+ const own = (text, at) => {
119
+ const lines = ownLines(ownText(text, ascii), width).slice(0, Math.max(0, size.rows - at));
120
+ lines.forEach((line, i) => { rows[at + i] = [{ col: SENTENCE_INDENT, text: lit(line), style: DIM, width }]; });
121
+ return lines.length;
122
+ };
123
+ if (c.local === false) { own(CAPABILITIES_TEXT.noWorkspace, 0); return rows; }
124
+ if (!capabilitiesListed(c)) {
125
+ if (c.state === "failed") {
126
+ // The sentence from outside, whole where the rows allow, and under it the key that reads again.
127
+ const retry = keyOf(m, "refresh");
128
+ const lines = shownLines(c.failure, width, Math.max(1, size.rows - (retry ? 1 : 0)), { ascii });
129
+ lines.forEach((line, i) => { rows[i] = [{ col: SENTENCE_INDENT, text: line, width }]; });
130
+ if (retry && lines.length < size.rows) {
131
+ const at = lines.length, words = SENTENCE_INDENT + retry.width + 1;
132
+ rows[at] = [{ col: SENTENCE_INDENT, text: retry.text, style: BOLD, width: Math.min(retry.width, width) },
133
+ ...(words < size.cols - 1 ? [{ col: words, text: lit(CAPABILITIES_TEXT.retry), style: DIM, width: size.cols - 1 - words }] : [])];
134
+ }
135
+ } else own(c.state === "none" ? CAPABILITIES_TEXT.none : CAPABILITIES_TEXT.reading, 0);
136
+ return rows;
137
+ }
138
+ let at = 0;
139
+ if (c.heading) rows[at++] = headingRow(c.heading, size.cols, ascii);
140
+ if (c.state === "none" || c.state === "nomatch") own(CAPABILITIES_TEXT[c.state], at);
141
+ else c.list.forEach((item, i) => { if (at + i < size.rows) rows[at + i] = itemRow(item, size.cols, ascii); });
142
+ const note = cutNote(c.above ?? 0, c.below ?? 0);
143
+ if (note) rows[size.rows - 1] = [{ col: SENTENCE_INDENT, text: lit(note), style: DIM, width: Math.max(0, size.cols - SENTENCE_INDENT) }];
144
+ return rows;
145
+ }
146
+
147
+ /** `{ rows, mark }`: every row of the selected capability's detail for a pane `cols` wide, before it
148
+ * is scrolled, and the row of the marked soul of "Used by" (-1 when none is marked). Top to bottom:
149
+ * the name and its layer's label, a failed re-read's sentence (in the warning style; it says so in
150
+ * words), the description; where it comes from (each fact `label value`); what it provides (each
151
+ * kind its names, flowed, or the shared word for none or not listable); and the souls that use it,
152
+ * eight at most and then `+n`, each its colour mark, its name, a dim count of its instances that
153
+ * carry it and how many of those are on an older version. A section with nothing to say is left out. */
154
+ export function capabilityDetailRows(m, cols) {
155
+ const d = m.capabilities?.detail;
156
+ if (!d) return { rows: [], mark: -1 };
157
+ const ascii = m.ascii, wide = Math.max(0, cols - LEFT), inner = Math.max(0, cols - INNER);
158
+ const label = (text, col = LEFT) => { const t = measured(text); return { col, text: t.text, style: DIM, width: Math.max(0, Math.min(t.width, cols - col)) }; };
159
+ const layer = d.layer ? measured(d.layer) : null;
160
+ const rows = [nameThen(measured(d.name), layer ? [{ text: layer.text, width: layer.width, style: DIM }] : [], LEFT, cols, (own) => (own === PLAIN ? BOLD : own))];
161
+ /** Safe lines placed at `col`, each `width` cells, the first beside `first` when given. */
162
+ const lines = (list, col, width, look, first = null) => list.forEach((line, i) => rows.push([...(i === 0 && first ? [first] : []), { col, text: line, width, ...(look ? { style: look } : {}) }]));
163
+ /** Facts `{ label, value }` under a section's heading: the labels in a column of their own, and
164
+ * each value beside its label, wrapped, or under it when the column leaves too few cells (and
165
+ * none at all in a pane with no cell for it). */
166
+ const facts = (list, value) => {
167
+ const names = list.map((fact) => measured(fact.label));
168
+ const column = Math.max(0, ...names.map((name) => name.width));
169
+ const beside = inner - column - 2 >= VALUE_MIN;
170
+ list.forEach((fact, i) => {
171
+ const name = { col: INNER, text: names[i].text, style: DIM, width: Math.min(names[i].width, inner) };
172
+ if (beside) value(fact, INNER + column + 2, inner - column - 2, name);
173
+ else { rows.push([name]); if (inner - 2 >= 1) value(fact, INNER + 2, inner - 2, null); }
174
+ });
175
+ };
176
+ const blank = () => rows.push([]);
177
+
178
+ if (d.failure) lines(shownLines(d.failure, wide, WRAP_ROWS, { ascii }), LEFT, wide, WARN);
179
+ lines(shownLines(d.description, wide, DESCRIPTION_ROWS, { ascii }), LEFT, wide);
180
+
181
+ if (d.comesFrom.length) {
182
+ blank();
183
+ rows.push([label(d.words.comesFrom)]);
184
+ facts(d.comesFrom, (fact, col, width, name) => lines(shownLines(fact.value, width, WRAP_ROWS, { ascii }), col, width, null, name));
185
+ }
186
+
187
+ if (d.provides.length) {
188
+ blank();
189
+ rows.push([label(d.words.provides)]);
190
+ const comma = { text: lit(","), width: 1, glue: true };
191
+ facts(d.provides, (kind, col, width, name) => {
192
+ if (kind.said) { lines(shownLines(kind.said, width, WRAP_ROWS, { ascii }), col, width, DIM, name); return; }
193
+ const set = width < 1 ? [] : flowed(kind.names.map((each, i, all) => [measured(each), ...(i < all.length - 1 ? [comma] : [])]), width);
194
+ if (!set.length) { if (name) rows.push([name]); return; }
195
+ set.forEach((spans, i) => rows.push([...(i === 0 && name ? [name] : []), ...spans.map((span) => ({ ...span, col: span.col + col }))]));
196
+ });
197
+ }
198
+
199
+ const u = d.used;
200
+ blank();
201
+ const count = u.count ? measured(u.count) : null, heading = label(d.words.usedBy);
202
+ rows.push([heading, ...(count && LEFT + heading.width + 2 < cols ? [{ col: LEFT + heading.width + 2, text: count.text, style: DIM, width: Math.max(0, Math.min(count.width, cols - LEFT - heading.width - 2)) }] : [])]);
203
+ let mark = -1;
204
+ if (u.state === "reading") lines([lit(ownText(CAPABILITIES_TEXT.readingSouls, ascii))], INNER, inner, DIM);
205
+ else if (u.state === "failed") lines(shownLines(u.failure, inner, WRAP_ROWS, { ascii }), INNER, inner, WARN);
206
+ else if (u.empty) lines(shownLines(u.empty, inner, WRAP_ROWS, { ascii }), INNER, inner, DIM);
207
+ const sign = ascii ? COUNT_SIGN.ascii : COUNT_SIGN.utf8, soulMark = ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8, end = cols - 1;
208
+ u.shown.forEach((user, i) => {
209
+ const marked = i === m.capabilities.mark;
210
+ if (marked) mark = rows.length;
211
+ const look = (own) => (marked ? SELECTED : own);
212
+ const colour = typeof user.color === "string" && COLORS.includes(user.color) ? user.color : null;
213
+ const spans = marked ? [{ col: LEFT, width: Math.max(0, cols - LEFT), style: SELECTED }, { col: LEFT, text: lit(">"), style: SELECTED, width: 1 }] : [];
214
+ spans.push({ col: INNER, text: lit(soulMark), style: look(colour ? style({ fg: colour }) : PLAIN), width: 1 });
215
+ const counted = `${sign}${user.count}`;
216
+ const after = [{ text: lit(counted), width: counted.length, style: DIM }];
217
+ if (user.behind) { const behind = measured(user.behind); after.push({ text: lit(dotOf(ascii)), width: 1, style: DIM }, { text: behind.text, width: behind.width, style: WARN }); }
218
+ rows.push([...spans, ...nameThen(measured(user.name), after, INNER + 2, end, look)]);
219
+ });
220
+ if (u.more > 0) rows.push([{ col: INNER, text: lit(`+${u.more}`), style: DIM, width: `+${u.more}`.length }]);
221
+ return { rows, mark };
222
+ }
223
+
224
+ /** `{ rows, extent, top }`: `size.rows` rows of the detail for a pane `size.cols` wide, scrolled to
225
+ * the model's `detailTop`, or the least from there that shows the marked soul while the detail was
226
+ * not scrolled away from it (`keep`); how many rows the whole detail has; and the row it was drawn
227
+ * from, which the loop gives the store. The pane with the focus says so with `>` beside the title,
228
+ * never by an attribute alone (views/detail.mjs). */
229
+ export function capabilityDetail(m, size) {
230
+ const { rows: all, mark } = capabilityDetailRows(m, size.cols);
231
+ const rows = Array.from({ length: size.rows }, () => []);
232
+ const c = m.capabilities;
233
+ const win = windowOf({ top: c?.detailTop ?? 0, count: all.length, height: size.rows, keep: c?.keep && mark >= 0 ? mark : -1 });
234
+ all.slice(win.top, win.top + win.size).forEach((spans, i) => { rows[i] = spans; });
235
+ const note = cutNote(win.above, win.below);
236
+ if (note && size.rows > 0) rows[size.rows - 1] = [{ col: LEFT, text: lit(note), style: DIM, width: Math.max(0, size.cols - LEFT) }];
237
+ if (c?.focus === "detail" && size.rows > 0 && all.length) rows[0] = [{ col: 0, text: lit(">"), style: BOLD, width: 1 }, ...rows[0]];
238
+ return { rows, extent: all.length, top: win.top };
239
+ }
@@ -2,6 +2,7 @@
2
2
  // byte. It places the views: the header, the list of instances and the detail beside it (or as a
3
3
  // page of its own on a narrow terminal), an agent's open terminal in the detail's place (or over
4
4
  // the whole body, zoomed), the souls of the open workspace and a soul's detail in the same places,
5
+ // and its capabilities and a capability's detail there too,
5
6
  // the switcher of workspaces over the whole body, the palette and the spawn prompt over the whole
6
7
  // body too, the help, and the footer. The TUI's own words are lit(); everything else is shown().
7
8
  // Meaning never rests on colour alone: what is dim or bold also says what it is in words or by a
@@ -16,6 +17,7 @@ import { instances, measured } from "./instances.mjs";
16
17
  import { textWidth } from "../term/width.mjs";
17
18
  import { palette } from "./palette.mjs";
18
19
  import { soulDetail, soulsList, soulsListed } from "./souls.mjs";
20
+ import { capabilitiesList, capabilitiesListed, capabilityDetail } from "./capabilities.mjs";
19
21
  import { spawn } from "./spawn.mjs";
20
22
  import { splitFits, splitRegions } from "./split.mjs";
21
23
  import { switcher } from "./switcher.mjs";
@@ -215,9 +217,11 @@ function countSpans(counts, cols) {
215
217
  * first kept longest), so a hint can stand first and still be given up before another: in the
216
218
  * list of instances the acts go first (`restart`, `start`, `retire`, then `stop`), then
217
219
  * `workspaces`, `refresh`, the key that clears a
218
- * kept filter, `detail`, the open terminal's `close-terminal` and `zoom`, `open` and last `filter`
220
+ * kept filter, the keys that show the tab before and after (`[/] tab`, with two tabs or more in
221
+ * the focused group), `detail`, the open terminal's `close-terminal` and `zoom`, `open` and last `filter`
219
222
  * (`filter` before `open` while a filter is kept: its own `/` stands in the footer then); in the
220
- * Souls view `workspaces`, `refresh`, `filter`, `close`, then `i` and last Enter. A row
223
+ * Souls view `workspaces`, `refresh`, `filter`, `close`, then `i` and last Enter, and in the
224
+ * Capabilities view the same without `i`. A row
221
225
  * too narrow for the whole of a hint drops it. The views have no hint: the header names them.
222
226
  * The palette's footer says how to work it: Enter, Up/Down and Esc; the spawn prompt's, how to
223
227
  * work its step (spawnHints).
@@ -239,7 +243,10 @@ function footer(m, cols) {
239
243
  // Enter does (from the list it shows the detail, from the detail the soul's instances) stands
240
244
  // first, as `open` does in the list, so a kept filter leaves it its room.
241
245
  const soul = m.view === "souls" && m.souls ? m.souls : null;
242
- const filter = soul ? soul.filter : m.filter;
246
+ // The Capabilities view's the same way: from the list Enter shows the detail, and from the detail
247
+ // the marked soul of "Used by" in the Souls view (no hint while none is marked).
248
+ const capability = m.view === "capabilities" && m.capabilities ? m.capabilities : null;
249
+ const filter = soul ? soul.filter : capability ? capability.filter : m.filter;
243
250
  // A filter is kept by its text, or in the list of instances by a soul (the Souls view's `i`):
244
251
  // drawn `soul <name>` where the text's `/` stands.
245
252
  const bySoul = !soul && m.view === "instances" && filter.soul && !filter.query ? filter.soul : null;
@@ -250,6 +257,8 @@ function footer(m, cols) {
250
257
  return { key, word: said, width: key.width + 1 + said.width };
251
258
  };
252
259
  const hint = (id, label) => { const a = action(id); return a ? made(keyText(keyLabel(a.keys[0])), label ?? a.label) : null; };
260
+ /** `[/] tab`: the keys of `tab-previous` and `tab-next`, while both have one. */
261
+ const tabsHint = () => { const [before, after] = [action("tab-previous"), action("tab-next")]; return before && after ? made(keyText(`${keyLabel(before.keys[0])}/${keyLabel(after.keys[0])}`), "tab") : null; };
253
262
  /** The hints that are no one action's: made below. */
254
263
  const hintOf = {};
255
264
  const edge = cols - MARGIN; // nothing stands at or past it
@@ -316,9 +325,11 @@ function footer(m, cols) {
316
325
  // An action with no key (tui.json may unbind one) has no hint: nothing stands first then. On the
317
326
  // row whose terminal is open, Enter goes to it.
318
327
  const first = (asking ? [["open", hint("close", "stop opening")]] : listing && m.onTerminal ? [["open", hint("open", "focus terminal")]] : listing && m.openable ? [["open", hint("open")]]
319
- : soul?.detail ? [["open", hint("open", soul.focus === "detail" ? "instances" : "detail")]] : []).filter(([, h]) => h);
320
- // With a terminal open, the keys that zoom it and close it stand after `open`, kept as long.
321
- const terminal = listing && m.terminal ? [["zoom", hint("zoom")], ["close-terminal", hint("close-terminal")]].filter(([, h]) => h) : [];
328
+ : soul?.detail ? [["open", hint("open", soul.focus === "detail" ? "instances" : "detail")]]
329
+ : capability?.detail ? (capability.focus !== "detail" ? [["open", hint("open", "detail")]] : capability.mark >= 0 ? [["open", hint("open", "soul")]] : []) : []).filter(([, h]) => h);
330
+ // With a terminal open, the keys that zoom it and close it stand after `open`, kept as long;
331
+ // with two tabs or more in the focused group, then the keys that show the tab before and after.
332
+ const terminal = listing && m.terminal ? [["zoom", hint("zoom")], ["close-terminal", hint("close-terminal")], ...((m.tabs?.length ?? 0) > 1 ? [["tabs", tabsHint()]] : [])].filter(([, h]) => h) : [];
322
333
  // The acts the selected row offers now stand after those, and are the first given up.
323
334
  const acts = listing && !asking ? (m.actable ?? []).map((verb) => [verb, hint(verb)]).filter(([, h]) => h) : [];
324
335
  const ACTS = ["stop", "retire", "start", "restart"];
@@ -332,13 +343,16 @@ function footer(m, cols) {
332
343
  // help names n and N.
333
344
  : soul ? (soul.local === false ? [["close", "workspaces"], ["close", "workspaces"]]
334
345
  : [[...(soul.detail ? ["soul-instances"] : []), "filter", "refresh", "close", "workspaces"], ["open", "soul-instances", "close", "filter", "refresh", "workspaces"]])
335
- : m.view === "capabilities" ? [["close", "workspaces"], ["close", "workspaces"]]
346
+ // The Capabilities view: the filter, a read again, Esc and the workspaces, given up from the
347
+ // workspaces on; Enter last. With no workspace of this machine, Esc and the workspaces only.
348
+ : capability ? (capability.local === false ? [["close", "workspaces"], ["close", "workspaces"]]
349
+ : [["filter", "refresh", "close", "workspaces"], ["open", "close", "filter", "refresh", "workspaces"]])
336
350
  // Esc closes the switcher only onto a view, and there is none before a workspace is opened.
337
351
  // A kept filter puts `close` before `refresh`, as in the list: the key that clears it is the hint to keep.
338
352
  : m.view === "switcher" ? [["open", "filter", ...(m.filter.query ? ["close", "refresh"] : ["refresh", ...(m.open ? ["close"] : [])])], null]
339
- : m.focus === "detail" ? [["detail", "close", "refresh"], ["open", "zoom", "close-terminal", "detail", "close", "refresh", ...ACTS]]
353
+ : m.focus === "detail" ? [["detail", "close", "refresh"], ["open", "zoom", "close-terminal", "detail", "tabs", "close", "refresh", ...ACTS]]
340
354
  // A kept filter shows its own `/` beside the hints: then `open` outlives the `/ filter` hint.
341
- : [["filter", "detail", ...(filtered ? ["close"] : []), "refresh", "workspaces", ...VIEW_KEYS], [...(filtered ? ["open", "zoom", "close-terminal", "filter"] : ["filter", "open", "zoom", "close-terminal"]), "detail", "close", "refresh", "workspaces", ...VIEW_KEYS, ...ACTS]];
355
+ : [["filter", "detail", ...(filtered ? ["close"] : []), "refresh", "workspaces", ...VIEW_KEYS], [...(filtered ? ["open", "zoom", "close-terminal", "filter"] : ["filter", "open", "zoom", "close-terminal"]), "detail", "tabs", "close", "refresh", "workspaces", ...VIEW_KEYS, ...ACTS]];
342
356
  const hints = [...first, ...terminal, ...acts, ...ids.filter((id) => !(asking && id === "close")).map((id) => [id, id in hintOf ? hintOf[id] : hint(id)])].filter(([, h]) => h).map(([id, h]) => [id, spansOf(h)]);
343
357
  // `help` and `quit` stand last, and always but in one case: when the two do not fit whole
344
358
  // after the leader (keys tui.json made long), `help` is given up, then `quit`. The leader
@@ -475,13 +489,14 @@ function framed(m, size) {
475
489
  return { rows, page: Math.max(1, g.body.rows), extent: 0, room: 1, cursor: { row: g.body.top, col: drawn.cursor } };
476
490
  }
477
491
  // The spawn prompt in the same place (the palette wins if both are ever set). `extent` and `room`
478
- // are its preview's, which the store scrolls as it scrolls a confirmation; `armed` says the ready
492
+ // are its preview's, which the store scrolls as it scrolls a confirmation; `drawnTop` the
493
+ // row its window was drawn from, which the loop gives the store once the frame is written; `armed` says the ready
479
494
  // Spawn button is drawn, which the loop tells the store once the frame is written.
480
495
  if (m.spawn) {
481
496
  rows[2] = rule(cols, m.ascii);
482
497
  const drawn = spawn(m, { cols, rows: g.body.rows });
483
498
  drawn.rows.forEach((spans, i) => { rows[g.body.top + i] = spans; });
484
- return { rows, page: Math.max(1, g.body.rows), extent: drawn.extent, room: drawn.room, cursor: drawn.cursor ? { row: g.body.top + drawn.cursor.row, col: drawn.cursor.col } : null, ...(drawn.armed ? { armed: true } : {}) };
499
+ return { rows, page: Math.max(1, g.body.rows), extent: drawn.extent, room: drawn.room, ...(drawn.top !== undefined ? { drawnTop: drawn.top } : {}), cursor: drawn.cursor ? { row: g.body.top + drawn.cursor.row, col: drawn.cursor.col } : null, ...(drawn.armed ? { armed: true } : {}) };
485
500
  }
486
501
  if (m.view === "act" && m.act) {
487
502
  rows[2] = rule(cols, m.ascii);
@@ -504,14 +519,6 @@ function framed(m, size) {
504
519
  return { rows, page: Math.max(1, g.body.rows), extent: 0, room: 1 };
505
520
  }
506
521
 
507
- // The view of this machine not in this version says what it will hold, and what to run until
508
- // then. The Souls view is drawn below, in the panes of the list.
509
- if (m.view === "capabilities") {
510
- rows[2] = rule(cols, m.ascii);
511
- partRows(m.body?.said ?? [], cols - 2 * MARGIN, g.body.rows, { ascii: m.ascii }).forEach((spans, i) => { rows[g.body.top + 1 + i] = placed(spans, MARGIN); });
512
- return { rows, page: Math.max(1, g.body.rows), extent: 0, room: 1 };
513
- }
514
-
515
522
  // The state of a deployment that is not live, and on rows of its own the reason, which is the
516
523
  // shared home's sentence or the kernel's: nothing of the TUI's stands on a reason's row. Then
517
524
  // the note of the one deployment of a view without headings, the shared home's sentence too.
@@ -525,6 +532,7 @@ function framed(m, size) {
525
532
  for (const spans of g.outcome) said.push(placed(spans, MARGIN));
526
533
  said.slice(0, g.above).forEach((spans, i) => { rows[g.body.top + i] = spans; });
527
534
  if (m.view === "souls" && m.souls) return soulsFrame(m, size, g, rows);
535
+ if (m.view === "capabilities" && m.capabilities) return capabilitiesFrame(m, size, g, rows);
528
536
  const area = terminalAt(m, size, g);
529
537
  const zoomed = area !== null && area.whole;
530
538
  const paged = !zoomed && !g.wide && m.focus === "detail" && m.detail;
@@ -547,7 +555,8 @@ function framed(m, size) {
547
555
  // The rule between two groups: a column side by side, a row one above the other.
548
556
  const p = area.panel, r = area.rule;
549
557
  if (r?.col !== undefined) for (let i = 0; i <= p.rows; i++) rows[p.title + i] = [...rows[p.title + i], { col: r.col, text: lit(m.ascii ? "|" : "\u2502"), style: DIM, width: 1 }];
550
- if (r?.row !== undefined) rows[r.row] = [...rows[r.row], { col: p.col, text: lit((m.ascii ? "-" : "\u2500").repeat(p.cols)), style: DIM, width: p.cols }];
558
+ // Beside the list, the row meets the list's bar there: a joint (`├`, `+` in ASCII).
559
+ if (r?.row !== undefined) rows[r.row] = [...rows[r.row], ...(split && p.col === g.listCols + 1 ? [{ col: g.listCols, text: lit(m.ascii ? "+" : "\u251c"), style: DIM, width: 1 }] : []), { col: p.col, text: lit((m.ascii ? "-" : "\u2500").repeat(p.cols)), style: DIM, width: p.cols }];
551
560
  } else if (split || paged) {
552
561
  const at = paged ? MARGIN : g.listCols + 2;
553
562
  const drawn = detail(m, { cols: Math.max(0, cols - at - MARGIN), rows: g.panes.rows });
@@ -590,6 +599,32 @@ function soulsFrame(m, size, g, rows) {
590
599
  return { rows, page: Math.max(1, g.page), extent, room: Math.max(1, g.panes.rows) };
591
600
  }
592
601
 
602
+ /** The Capabilities view in the panes of the list (views/capabilities.mjs), as the Souls view: the
603
+ * capabilities in the list's place and width, and beside them the selected capability's detail;
604
+ * under WIDE columns the list alone, and the detail in its place while it has the focus. A body of
605
+ * one sentence has the whole width. `capabilitiesTop` is the row the detail was drawn from, which
606
+ * the loop gives the store once the frame is written (it keeps the marked soul in sight). */
607
+ function capabilitiesFrame(m, size, g, rows) {
608
+ const { cols } = size, c = m.capabilities;
609
+ const paged = !g.wide && c.focus === "detail" && Boolean(c.detail);
610
+ const split = g.wide && g.panes.rows > 0 && capabilitiesListed(c);
611
+ const joint = split ? { col: g.listCols } : null;
612
+ const opening = m.observed && g.above > 0 ? g.panes.top - 1 : 2;
613
+ rows[2] = rule(cols, m.ascii, opening === 2 ? joint : null);
614
+ if (opening !== 2 && opening < size.rows - 1) rows[opening] = rule(cols, m.ascii, joint);
615
+ if (!paged) capabilitiesList(m, { cols: split ? g.listCols : cols, rows: g.panes.rows }).forEach((spans, i) => { rows[g.panes.top + i] = spans; });
616
+ let extent = 0, top;
617
+ if (split || paged) {
618
+ const at = paged ? MARGIN : g.listCols + 2;
619
+ const bar = split ? [{ col: g.listCols, text: lit(m.ascii ? "|" : "│"), style: DIM, width: 1 }] : [];
620
+ const drawn = capabilityDetail(m, { cols: Math.max(0, cols - at - MARGIN), rows: g.panes.rows });
621
+ extent = drawn.extent;
622
+ top = drawn.top;
623
+ drawn.rows.forEach((spans, i) => { rows[g.panes.top + i] = [...rows[g.panes.top + i], ...bar, ...placed(spans, at)]; });
624
+ }
625
+ return { rows, page: Math.max(1, g.page), extent, room: Math.max(1, g.panes.rows), ...(top !== undefined ? { capabilitiesTop: top } : {}) };
626
+ }
627
+
593
628
  /** Where the open terminal stands for a model and a size, or null while it is not shown (no
594
629
  * terminal; another view over the body; the detail in its place; the list's focus on a terminal
595
630
  * too narrow for it beside the list). `{ title, top, col, cols, rows, whole }`, the focused
@@ -7,6 +7,7 @@ import { lit, ownEllipsis } from "../term/text.mjs";
7
7
  import { style } from "../term/style.mjs";
8
8
  import { cutNote, marksOf, measured } from "./instances.mjs";
9
9
  import { windowOf } from "./scroll.mjs";
10
+ import { SOUL_MARK } from "./souls.mjs";
10
11
  import { OPEN_MARK } from "./switcher.mjs";
11
12
 
12
13
  const TITLE = style({ bold: true });
@@ -33,6 +34,8 @@ export const NOT_YET = Object.freeze([
33
34
  // choose, and no task: the rest is the kernel's command's (run on that machine for another).
34
35
  Object.freeze({ what: "spawn on another machine", command: "oats spawn <soul>" }),
35
36
  Object.freeze({ what: "spawn with a harness, model or task", command: "oats spawn <soul>" }),
37
+ // The Capabilities view lists them and their facts: a capability's skills' text and its files are the kernel's command's.
38
+ Object.freeze({ what: "see a capability's skills and files", command: "oats capabilities show <name>" }),
36
39
  Object.freeze({ what: "open an agent in its own tmux window", command: "oats session attach --home <home>" }),
37
40
  Object.freeze({ what: "start with another harness or model", command: "oats session start --home <home>" }),
38
41
  Object.freeze({ what: "add a machine to this workspace", command: "oats server connect <id> --ssh <alias>" }),
@@ -46,14 +49,14 @@ export const NOT_YET = Object.freeze([
46
49
  export const MACHINES = Object.freeze([
47
50
  "A machine's rows are what it reported at the time on its heading (in a view of one machine, in the header).",
48
51
  "Nothing is kept on disk: a machine not reached in this run is listed by its own name.",
49
- "Souls and Capabilities, when they come, are this machine's.",
52
+ "Souls and Capabilities are this machine's.",
50
53
  ]);
51
- /** The views the frame names, what each holds, and what to run for what a view does not do yet:
52
- * Capabilities is not built. The Souls view spawns an agent of the selected soul (n, N). */
54
+ /** The views the frame names, what each holds, and what to run for what a view does not do yet.
55
+ * The Souls view spawns an agent of the selected soul (n, N). */
53
56
  export const VIEWS = Object.freeze([
54
57
  Object.freeze({ name: "1 Instances", what: "the instances of the open workspace", commands: Object.freeze([]) }),
55
58
  Object.freeze({ name: "2 Souls", what: "the souls of the open workspace and their detail, i their instances, n an agent of the selected soul", commands: Object.freeze([]) }),
56
- Object.freeze({ name: "3 Capabilities", what: "not in this version", commands: Object.freeze(["oats capabilities"]) }),
59
+ Object.freeze({ name: "3 Capabilities", what: "the capabilities of the open workspace and their detail, Enter on a soul that uses one shows it in Souls", commands: Object.freeze([]) }),
57
60
  ]);
58
61
 
59
62
  const words = (text) => text.split(" ");
@@ -188,6 +191,8 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null) {
188
191
  [`${marks.waiting}N`, "N instances folded away below it need input"],
189
192
  [marks.selected, "the selected row, and the pane the movement keys act on"],
190
193
  [OPEN_MARK, "among the workspaces: the one that is open"],
194
+ [ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8, "among the souls: a soul, in its colour"],
195
+ ["!", "among the souls: a spawn of it here would be refused"],
191
196
  ].map(([mark, meaning]) => [mark, words(meaning)]), cols),
192
197
  [],
193
198
  heading("Views"),
@@ -1,9 +1,10 @@
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 or a soul's name, a machine and the query are text the TUI did not write and go
5
- // through shown(); the labels of the views, the acts and the commands are the TUI's own. Nothing
6
- // is told by colour alone: each row says in a word what kind it is.
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.
7
8
  import { lit, shown } from "../term/text.mjs";
8
9
  import { style } from "../term/style.mjs";
9
10
  import { cutNote, marksOf, measured } from "./instances.mjs";
@@ -13,7 +14,7 @@ const PROMPT = ">", PROMPT_CELLS = 2;
13
14
  /** The cells a row's text starts at: the selection mark, a gap, an instance's state mark, a gap. */
14
15
  const LEAD = 4;
15
16
  /** The word at a row's right edge that says what it is. */
16
- const KINDS = Object.freeze({ instance: "instance", soul: "soul", view: "view", act: "act", command: "command" });
17
+ const KINDS = Object.freeze({ instance: "instance", soul: "soul", capability: "capability", view: "view", act: "act", command: "command" });
17
18
  /** The TUI's word before another machine's name. */
18
19
  const ON = "on";
19
20
 
@@ -37,6 +38,14 @@ function itemRow(item, cols, marks) {
37
38
  const name = measured(item.name);
38
39
  put(name.text, name.width, PLAIN);
39
40
  if (item.machine !== null && item.machine !== undefined) { put(lit(ON), ON.length, DIM); const where = measured(item.machine); put(where.text, where.width, DIM); }
41
+ // An instance's siblings, dim, in the shared words (which hold their names): last, so the
42
+ // first cut, and the name keeps the room.
43
+ if (item.kind === "instance" && item.sibling) { const kin = measured(item.sibling); put(kin.text, kin.width, DIM); }
44
+ } else if (item.kind === "capability") {
45
+ // A capability's name and, dim, where it comes from (its repository or package): text from outside.
46
+ const name = measured(item.name), where = measured(item.source);
47
+ put(name.text, name.width, PLAIN);
48
+ put(where.text, where.width, DIM);
40
49
  } else {
41
50
  put(lit(item.label), item.label.length, PLAIN);
42
51
  if (item.kind === "act") { const name = measured(item.name); put(name.text, name.width, DIM); }
@@ -79,8 +79,9 @@ export function soulsListed(s) {
79
79
  }
80
80
 
81
81
  /** A line of the TUI's own on as many rows of `width` cells as it needs, broken at its spaces but
82
- * never inside a command between backticks: a command cut in two cannot be typed. */
83
- function ownLines(text, width) {
82
+ * never inside a command between backticks: a command cut in two cannot be typed. The Capabilities
83
+ * view sets its own lines with it too. */
84
+ export function ownLines(text, width) {
84
85
  const words = text.match(/`[^`]*`[^\s`]*|\S+/g) ?? [];
85
86
  return words.reduce((lines, word) => {
86
87
  const last = lines.at(-1);
@@ -92,8 +93,9 @@ function ownLines(text, width) {
92
93
 
93
94
  /** Units set on rows of `width` cells from column 0, `gap` cells between two: a unit is pieces
94
95
  * (`{ text, width, style, glue }`) written together, one cell between two but before a glued one
95
- * (a comma). A unit is never broken over two rows; one wider than a row is cut there. */
96
- function flowed(units, width, gap = 1) {
96
+ * (a comma). A unit is never broken over two rows; one wider than a row is cut there. The
97
+ * Capabilities view flows what a capability provides with it. */
98
+ export function flowed(units, width, gap = 1) {
97
99
  const unitWidth = (unit) => unit.reduce((sum, piece, i) => sum + piece.width + (i > 0 && !piece.glue ? 1 : 0), 0);
98
100
  const rows = [];
99
101
  let row = [], used = 0;
@@ -272,7 +272,9 @@ const SCROLL_MIN = 3;
272
272
  * above them the rest scrolled to the model's `top`, or to the window that holds the fold with
273
273
  * the focus (the store scrolls only with the movement keys; Tab can land on a fold out of sight).
274
274
  * The scrolling part's last row says what is cut off. `extent` and `room` are the scrolling
275
- * part's, for the store's scroll; `armed` is whether the ready Spawn button is on the screen. */
275
+ * part's, for the store's scroll, and `top` the row the window drawn starts at (which keeps the
276
+ * focused fold in sight, and so may stand where the model's `top` does not), which the loop
277
+ * gives the store once it is painted; `armed` is whether the ready Spawn button is on the screen. */
276
278
  function preview(s, size, ascii) {
277
279
  const rows = Array.from({ length: size.rows }, () => []);
278
280
  const fixed = previewRows(s, size.cols, ascii, { problemRows: 0 }).pinned.length;
@@ -286,10 +288,10 @@ function preview(s, size, ascii) {
286
288
  pinned.forEach((spans, i) => { rows[room + i] = spans; });
287
289
  const cut = all.pinned.length - pinned.length;
288
290
  const cursor = all.cursor && all.cursor.row >= cut ? { row: room + all.cursor.row - cut, col: all.cursor.col } : null;
289
- return { rows, cursor, extent: all.scroll.length, room: Math.max(1, room), armed: s.ready === true && all.button >= cut };
291
+ return { rows, cursor, extent: all.scroll.length, room: Math.max(1, room), top: win.top, armed: s.ready === true && all.button >= cut };
290
292
  }
291
293
 
292
- /** `{ rows, cursor, extent, room, armed? }`: `size.rows` rows for an area `size.cols` wide, the step of the
294
+ /** `{ rows, cursor, extent, room, top?, armed? }`: `size.rows` rows for an area `size.cols` wide, the step of the
293
295
  * prompt the model is at. `cursor` is `{ row, col }` in the area (the query's end, or the name
294
296
  * field's while it has the focus), or null; `extent` and `room` are the preview's scrolling
295
297
  * part's, for the store's scroll (0 and 1 for the picker, which the model windows itself). */
@@ -60,7 +60,7 @@ members:
60
60
  - git:github.com/acme/agents # the host is a member too
61
61
  - git:github.com/acme/platform
62
62
  packages:
63
- oats.framework: v1.12.2 # bare versions resolve through the official catalog
63
+ oats.framework: v1.13.0 # bare versions resolve through the official catalog
64
64
  oats.okf: v5.2.1
65
65
  defaults:
66
66
  capabilities: { oats.core: { from: package } }