@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
@@ -9,7 +9,8 @@
9
9
  // takes its default keys from the shared keymap (packages/client/keymap.mjs PLAIN_KEYS), and the
10
10
  // leader's table is the shared one (LEADER, below). What only the TUI has (q, Ctrl+C, Ctrl+Z, Ctrl+L,
11
11
  // Ctrl+K, Tab, Esc, Delete, C, i) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
12
- import { CHORDS, LEADER_TABLE, plainKeys } from "./client.mjs";
12
+ import { CHORDS, DEFAULT_CHORD_FAMILY, LEADER_TABLE, PALETTE_KEYS, chordKeyOf, plainKeys } from "./client.mjs";
13
+ import { legacyChord } from "./term/kitty.mjs";
13
14
  import { isBackKey } from "./term/through.mjs";
14
15
 
15
16
  export const ACTIONS = Object.freeze([
@@ -91,24 +92,59 @@ export const LEADER = LEADER_TABLE;
91
92
  * `next` (the instance before or after the shown terminal's, or the selection's: its tab shown,
92
93
  * or opened as a new one, with the focus in it) and `list` (the list's focus, which Esc gives). */
93
94
  export const LEADER_OWN = Object.freeze(["previous", "next", "list"]);
94
- /** Whether the TUI acts on `does`, a `does` of the shared leader table: it is one of the leader's
95
- * own (LEADER_OWN), or the id of an action of ACTIONS, which lib/store.mjs `led` runs as its key
96
- * runs it, or in its own way from the leader (the terminal's keys, the acts, the spawns). A
97
- * `does` the TUI does not handle is a failure of packages/tui/test/keymap.test.mjs, never a
98
- * key that does nothing. */
99
- export const leaderHandles = (does) => LEADER_OWN.includes(does) || ACTIONS.some((action) => action.id === does);
95
+ /** What a chord does that neither the leader's table nor an action does (lib/store.mjs `led`):
96
+ * `tab-1` to `tab-8`, the focused group's Nth tab shown, and `tab-9`, its last (as the Desktop and
97
+ * the browsers do). No key after the leader does them: LEADER has no row for them. */
98
+ export const CHORD_OWN = Object.freeze(Array.from({ length: 9 }, (_, i) => `tab-${i + 1}`));
99
+ /** Whether the TUI acts on `does`, a `does` of the shared leader table or of the chords: it is one
100
+ * of the leader's own (LEADER_OWN), of the chords' own (CHORD_OWN), or the id of an action of
101
+ * ACTIONS, which lib/store.mjs `led` runs as its key runs it, or in its own way from the leader
102
+ * (the terminal's keys, the acts, the spawns). A `does` the TUI does not handle is a failure of
103
+ * packages/tui/test/keymap.test.mjs or chords.test.mjs, never a key that does nothing. */
104
+ export const leaderHandles = (does) => LEADER_OWN.includes(does) || CHORD_OWN.includes(does) || ACTIONS.some((action) => action.id === does);
100
105
  /** key id -> what the leader then does (LEADER's `does`). */
101
106
  export const LEADER_KEYS = new Map(LEADER.flatMap((entry) => entry.keys.map((key) => [key, entry.does])));
102
107
 
103
108
  /** THE CHORDS (docs/tui.md, "Chords"): key id -> `does`, the shared ones (packages/client/keymap.mjs
104
- * CHORDS) on macOS (`isMac`) or elsewhere, each doing what the leader then its key does
105
- * (lib/store.mjs `led`). Read only while the terminal confirms the kitty keyboard protocol, which
106
- * alone sends them. Left out: a chord with `cmd+` (a terminal never passes macOS's Command to a
107
- * program), and one whose key an action of `actions` binds (a user's tui.json keeps its key).
108
- * Each `does` is one the TUI handles (leaderHandles): packages/tui/test/chords.test.mjs. */
109
- export function chordKeys(isMac, actions = ACTIONS) {
109
+ * CHORDS) on macOS (`isMac`) or elsewhere, in the table's order, each doing what the leader then
110
+ * its key does, or a tab by its place (CHORD_OWN; lib/store.mjs `led`), from every focus. Each
111
+ * row's key is the one of `family` (keymap.mjs chordKeyOf: CHORD_FAMILIES, keys.json's `chords`,
112
+ * lib/config.mjs loadKeys): `ctrl+alt`, the default, binds the `other` keys; `ctrl+shift` the
113
+ * `shift` ones (seven rows move, the others keep their key); macOS ignores it. Left out: a chord
114
+ * with `cmd+` (a terminal never passes macOS's Command to a program: with the shared table that is
115
+ * every chord of macOS), and one whose key an action of `actions` binds (a user's tui.json keeps
116
+ * its key, row by row, whichever the family), and one whose `does` the TUI does not handle
117
+ * (leaderHandles: a row may be the Desktop's alone): packages/tui/test/chords.test.mjs. `chords`
118
+ * is the shared table. Which of them are read depends on the kitty keyboard protocol (chordsRead). */
119
+ export function chordKeys(isMac, actions = ACTIONS, chords = CHORDS, family = DEFAULT_CHORD_FAMILY) {
110
120
  const bound = new Set(actions.flatMap((action) => action.keys));
111
- return new Map(CHORDS.map((entry) => [isMac ? entry.mac : entry.other, entry.does]).filter(([key, does]) => !key.startsWith("cmd+") && !bound.has(key) && leaderHandles(does)));
121
+ return new Map(chords.map((entry) => [chordKeyOf(entry, isMac, family) ?? entry.other, entry.does]).filter(([key, does]) => !key.startsWith("cmd+") && !bound.has(key) && leaderHandles(does)));
122
+ }
123
+
124
+ /** THE PALETTE'S OWN KEYS (docs/tui.md, "The palette"): key id -> `does`, the shared ones
125
+ * (packages/client/keymap.mjs PALETTE_KEYS) on macOS (`isMac`) or elsewhere, in the table's order:
126
+ * `palette-next-group` and `palette-previous-group`, the first row of the next group or of the one
127
+ * before. Read only while the palette is open, and there before every other key: the chords that
128
+ * share a key (Alt+Shift+Down is the chord `next` too) and the palette's own (lib/store.mjs
129
+ * `leading` hands them on, and inPalette reads them first). Left out: a key with `cmd+` (a
130
+ * terminal never passes macOS's Command to a program: with the shared table that is both of
131
+ * macOS's, so the macOS TUI has none). Fixed, as the palette's Up and Down are: tui.json's `keys`
132
+ * rebinds the plain keys of ACTIONS only. On Linux and Windows each is an Alt+Shift arrow, read
133
+ * with or without the kitty keyboard protocol (term/kitty.mjs LEGACY_CHORDS). `table` is the
134
+ * shared table. */
135
+ export function paletteKeys(isMac, table = PALETTE_KEYS) {
136
+ return new Map(table.map((entry) => [isMac ? entry.mac : entry.other, entry.does]).filter(([key]) => !key.startsWith("cmd+")));
137
+ }
138
+
139
+ /** The chords of `chords` (chordKeys) the TUI reads while the terminal confirms the kitty keyboard
140
+ * protocol (`kitty`) or not: all of them under it; without it only the Alt+Shift arrows
141
+ * (term/kitty.mjs LEGACY_CHORDS), whose sequence is their own, in either family. A Ctrl+Alt chord
142
+ * without the protocol is the bytes of two keys (ESC, then Ctrl+K), the agent's, and in the list
143
+ * no key. A Ctrl+Shift one is Ctrl and its letter's byte, the same as Ctrl alone (Ctrl+Shift+D is
144
+ * 0x04, EOF; Ctrl+Shift+M is 0x0d, Enter): never a chord, the agent's in its terminal and the
145
+ * list's key in the list (term/kitty.mjs kittyId reads one only from the protocol's event). */
146
+ export function chordsRead(chords, kitty) {
147
+ return kitty ? chords : new Map([...chords].filter(([key]) => legacyChord(key)));
112
148
  }
113
149
 
114
150
  /** key id -> action id. A key bound twice is a defect of the table, refused when it is read. */
@@ -130,6 +166,13 @@ export function keyLabel(key) {
130
166
  return [...parts.map((part) => NAMES[part] ?? part), name].join("+");
131
167
  }
132
168
 
169
+ /** Key ids as one label, the modifiers they share said once: `alt+shift+up` and `alt+shift+down` are
170
+ * `Alt+Shift+Up/Down`; keys that share none are each said whole, `/` between them. */
171
+ export function keysTogether(keys) {
172
+ const labels = keys.map(keyLabel), shared = labels[0].slice(0, labels[0].lastIndexOf("+") + 1);
173
+ return labels.every((label) => label.startsWith(shared) && label.length > shared.length) ? shared + labels.map((label) => label.slice(shared.length)).join("/") : labels.join("/");
174
+ }
175
+
133
176
  /** The modifiers of the back key's grammar (term/through.mjs BACK_KEY) as a person reads them. */
134
177
  const BACK_MODIFIERS = Object.freeze({ C: "Ctrl", M: "Alt", S: "Shift" });
135
178
  /** A back key (tui.json's open.detachKey, the leader) as the cheat sheet and the help name it, spelt
@@ -15,14 +15,15 @@ export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
15
15
  export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
16
16
  export { createRefreshLoop } from "../../client/refresh-loop.mjs";
17
17
  export { rosterRows, livenessInput, livenessAnswers, panelInstances, pendingEntry, failedEntry, observedEntry } from "../../client/deployment-panel.mjs";
18
- export { panelData, cliReadsRemotes, workspaceChoices, viewModel, deployments } from "../../client/panel-views.mjs";
18
+ export { panelData, cliReadsRemotes, workspaceChoices, viewModel, listedViews, deployments } from "../../client/panel-views.mjs";
19
+ export { cliDeploymentIdentity, identityReadable, identityTimedOut } from "../../client/deployment-identity.mjs";
19
20
  export { remoteRosterState } from "../../client/remote-roster.mjs";
20
21
  export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
21
22
  export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
22
- export { shortPath, deploymentLabel } from "../../client/deployment-label.mjs";
23
+ export { shortPath, deploymentLabel, machineLabels } from "../../client/deployment-label.mjs";
23
24
  export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings } from "../../client/instance-tree.mjs";
24
25
  export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
25
- export { runtimeState, runtimeCounts, originLead, siblingText } from "../../client/instance-presentation.mjs";
26
+ export { runtimeState, runtimeCounts, originLead, siblingText, instanceColor } from "../../client/instance-presentation.mjs";
26
27
  export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
27
28
  export { instanceActs, openAct } from "../../client/instance-acts.mjs";
28
29
  export { rowReason } from "../../client/remote-address.mjs";
@@ -50,7 +51,10 @@ export { subsequenceScore } from "../../client/subsequence-score.mjs";
50
51
  export { createCapabilityCatalog, capabilityCatalogKey } from "../../client/capability-catalog.mjs";
51
52
  export { memberNames, capabilitySource, groupCapabilities, hostKeyOf, capabilitySections, matchCapabilities, soulsComposition, rosterAgentName, layerLabel, capabilityUsers } from "../../client/capability-rows.mjs";
52
53
  export { capabilityFacts, CAPABILITY_COPY } from "../../client/capability-facts.mjs";
53
- export { CHORDS, LEADER_TABLE, PLAIN_KEYS, leaderKey, plainKeys } from "../../client/keymap.mjs";
54
+ export { CHORDS, CHORD_FAMILY_LABELS, DEFAULT_CHORD_FAMILY, LEADER_TABLE, PALETTE_KEYS, PLAIN_KEYS, chordKeyOf, leaderKey, plainKeys } from "../../client/keymap.mjs";
55
+ // keys.json, the chord family both clients bind (docs/tui.md, "Switch to Ctrl+Shift"): the TUI reads the file
56
+ // itself, at its start (lib/config.mjs loadKeys), and the shared reader says what its text means.
57
+ export { KEYS_LIMIT, chordFamilyFrom, chordFamilyNote, keysPath } from "../../client/keys-file.mjs";
54
58
 
55
59
  /** The words a shared sentence uses where it names the client that shows it (client-terms.mjs).
56
60
  * Made once, here: every shared function that takes `terms` is passed this constant, and refuses
@@ -6,11 +6,13 @@
6
6
  // (there is no "last wins"), because a key that silently does something else is worse than a
7
7
  // program that does not start. The lines go to a terminal, so nothing taken from the file, and
8
8
  // no path, reaches one unless it is plain printable ASCII.
9
+ // Beside it, keys.json (loadKeys, at the end): the chord family both clients bind. That file is not
10
+ // the TUI's alone, so it is never refused: whatever is wrong with it is the default, said in the help.
9
11
  import { closeSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
10
12
  import { homedir } from "node:os";
11
13
  import { basename, dirname, isAbsolute, join } from "node:path";
12
14
  import { ACTIONS, bindings, keyLabel } from "./actions.mjs";
13
- import { displayLine, leaderKey } from "./client.mjs";
15
+ import { KEYS_LIMIT, chordFamilyFrom, displayLine, keysPath, leaderKey } from "./client.mjs";
14
16
  import { isKeyId } from "./term/keys.mjs";
15
17
  import { BACK_KEY_RULE, backKeyId, isBackKey } from "./term/through.mjs";
16
18
 
@@ -20,7 +22,7 @@ export const CONFIG_LIMIT = 64 * 1024;
20
22
  const TOO_LARGE = `it is larger than ${CONFIG_LIMIT / 1024} KiB`;
21
23
  const NOT_AN_OBJECT = 'it is not one JSON object, like {"keys": {"quit": ["q"]}}';
22
24
  const SETTINGS = "the settings are keys, ascii and open";
23
- /** A key id of the shared keymap (`ctrl+\\`, `alt+o`) in the back key's spelling (`C-\\`, `M-o`):
25
+ /** A key id of the shared keymap (`ctrl+x`, `alt+o`) in the back key's spelling (`C-x`, `M-o`):
24
26
  * Ctrl or Alt and one character, which is what the shared leader is. Anything else: null. */
25
27
  function backKeyOf(keyId) {
26
28
  const [, mod, rest] = /^(ctrl|alt)\+(.)$/.exec(keyId) ?? [];
@@ -29,9 +31,9 @@ function backKeyOf(keyId) {
29
31
  /** The back key when tui.json names none, on `platform` (a `process.platform` value): the key that
30
32
  * takes the focus from an agent's terminal back to the list, the leader (the setting keeps its
31
33
  * name, `open.detachKey`, from when it left a viewer). It is the shared leader, the Desktop's too
32
- * (packages/client/keymap.mjs leaderKey): `C-\\` on macOS, whose terminals send Option as Meta
33
- * only when told to; `M-o` (Alt+O) elsewhere. Both are read as keys no action of ACTIONS holds
34
- * (`ctrl+\\`, `alt+o`), which the check of the leader below keeps true. */
34
+ * (packages/client/keymap.mjs leaderKey): `C-x` (Ctrl+X) on every platform, one byte (0x18) in
35
+ * every terminal without the kitty keyboard protocol, `CSI 120;5u` under it. It is read as a key no action
36
+ * of ACTIONS holds (`ctrl+x`), which the check of the leader below keeps true. */
35
37
  export const defaultDetachKey = (platform = process.platform) => backKeyOf(leaderKey(platform === "darwin"));
36
38
  /** An action id this program had and has no more, with what it is called now. */
37
39
  const RENAMED = Object.freeze({ "open-workspace": "open" });
@@ -195,6 +197,10 @@ const NODE_IO = Object.freeze({
195
197
  }
196
198
  },
197
199
  read(path) { return readCapped(path).toString("utf8"); },
200
+ // keys.json (loadKeys): its bytes, at most KEYS_LIMIT and one, never thrown for its size. The
201
+ // shared reader decodes them (packages/client/keys-file.mjs), as it does the Desktop's, so the same
202
+ // bytes are the same family in both clients; one byte over the limit is too large there.
203
+ keys(path) { return readUpTo(path, KEYS_LIMIT); },
198
204
  });
199
205
  /** What link(2) answers on a file system without hard links (FAT, exFAT, some network mounts). */
200
206
  const NO_LINKS = new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
@@ -222,17 +228,23 @@ function entryAt(path) {
222
228
  throw error;
223
229
  }
224
230
  }
225
- /** At most CONFIG_LIMIT bytes of a file, whatever it became since it was measured. */
226
- function readCapped(path) {
231
+ /** At most `limit` bytes of a file and one more, whatever it became since it was measured: one
232
+ * byte more is how a reader knows the file is over its limit. */
233
+ function readUpTo(path, limit) {
227
234
  const fd = openSync(path, "r");
228
235
  try {
229
- const bytes = Buffer.alloc(CONFIG_LIMIT + 1);
236
+ const bytes = Buffer.alloc(limit + 1);
230
237
  let length = 0, got = 0;
231
238
  while (length < bytes.length && (got = readSync(fd, bytes, length, bytes.length - length, null)) > 0) length += got;
232
- if (length > CONFIG_LIMIT) throw Object.assign(new Error("tui.json grew past the limit while it was read"), { code: "EFBIG" });
233
239
  return bytes.subarray(0, length);
234
240
  } finally { closeSync(fd); }
235
241
  }
242
+ /** At most CONFIG_LIMIT bytes of a file, whatever it became since it was measured. */
243
+ function readCapped(path) {
244
+ const bytes = readUpTo(path, CONFIG_LIMIT);
245
+ if (bytes.length > CONFIG_LIMIT) throw Object.assign(new Error("tui.json grew past the limit while it was read"), { code: "EFBIG" });
246
+ return bytes;
247
+ }
236
248
 
237
249
  /** A path for a line: as it is when it is printable ASCII of at most 200 characters, else `named`. */
238
250
  const shownPath = (path, named) => (PLAIN_PATH.test(path) ? path : named);
@@ -327,3 +339,32 @@ export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO,
327
339
  const checked = effectiveConfig(value, ACTIONS, platform);
328
340
  return checked.ok ? { ...checked, path } : refused(checked.problems);
329
341
  }
342
+
343
+ /** What loadKeys hands the shared reader for a path that is there and is no regular file (a
344
+ * directory, a FIFO, a device): an error that is not ENOENT or ENOTDIR, so "unreadable". Such a
345
+ * file is never opened: a FIFO would hold the start until something wrote to it. */
346
+ const NOT_A_FILE = Object.freeze({ reason: "not a regular file" });
347
+
348
+ /** Read keys.json, once, at the start (docs/tui.md, "Switch to Ctrl+Shift"): the chord family the
349
+ * TUI binds on Linux and Windows, as the shared reader (packages/client/keys-file.mjs
350
+ * chordFamilyFrom) says it, a frozen `{ family, why }`. The file is the clients' and the user's:
351
+ * `config/keys.json` beside tui.json (keysPath), `{ "chords": "ctrl+alt" | "ctrl+shift" }`. The
352
+ * TUI only reads it, and never refuses to start for it: no file, a file that cannot be read, one
353
+ * that is not a regular file, over KEYS_LIMIT, not JSON or naming no family it knows are all the
354
+ * default, Ctrl+Alt, with `why` saying which (the help says it: chordFamilyNote). A change is read
355
+ * at the next start. macOS has no family; the answer is read there too, and ignored.
356
+ *
357
+ * `io` is the file system (node:fs when omitted): `io.stat(path)` as loadConfig's, and
358
+ * `io.keys(path)` the file's bytes, at most KEYS_LIMIT and one of them (NODE_IO). Nothing it
359
+ * throws reaches the user: it is the reader's `error`. */
360
+ export function loadKeys({ env = process.env, home = homedir(), io = NODE_IO } = {}) {
361
+ const path = keysPath(env, home);
362
+ try {
363
+ const found = io.stat(path);
364
+ if (found === null) return chordFamilyFrom(null);
365
+ if (found.file !== true) return chordFamilyFrom(null, NOT_A_FILE);
366
+ return chordFamilyFrom(io.keys(path));
367
+ } catch (error) {
368
+ return chordFamilyFrom(null, error ?? NOT_A_FILE);
369
+ }
370
+ }
@@ -13,10 +13,10 @@ import { homedir } from "node:os";
13
13
  import { resolve } from "node:path";
14
14
  import { bindings } from "./actions.mjs";
15
15
  import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, displayLine, heldHome, pendingEntry, prepareRemoteTerm, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
16
- import { loadConfig } from "./config.mjs";
16
+ import { loadConfig, loadKeys } from "./config.mjs";
17
17
  import { ACT_WORDS, LIST_WORDS, actContext, actCwd, localDeployments, model, outcomeOf, reachedMachines, roster, spawnContext } from "./model.mjs";
18
18
  import { createPanel, sweep } from "./panel.mjs";
19
- import { CHANGE_FILES, admitDeployment, createReader, findDeployment, leaveInstance, probeKernel, realpath, startExec, tellable } from "./read.mjs";
19
+ import { CHANGE_FILES, admitDeployment, createIdentityReads, createReader, findDeployment, leaveInstance, probeKernel, realpath, startExec, tellable } from "./read.mjs";
20
20
  import { initialState, reduce } from "./store.mjs";
21
21
  import { captureRows } from "./term/capture.mjs";
22
22
  import { createKeyParser, keyId } from "./term/keys.mjs";
@@ -93,8 +93,9 @@ function errorLines(error) {
93
93
  * factories are the shared home's preview, apply boundary and transaction, replaceable so a test
94
94
  * can answer them. `deploymentList` is the shared cliDeploymentList (this computer's deployments
95
95
  * list, through the kernel: awebai/oats#1390), and `startExec` the exec it is handed before the
96
- * terminal is taken; replaceable so a test can answer the list. */
97
- const EFFECTS = Object.freeze({ loadConfig, findDeployment, probeKernel, createReader, deploymentList: cliDeploymentList, startExec, admitDeployment, prepareRemoteTerm, createPanel, sweep,
96
+ * terminal is taken; replaceable so a test can answer the list. `loadKeys` reads keys.json, the
97
+ * chord family (lib/config.mjs), replaceable so no test reads a user's file. */
98
+ const EFFECTS = Object.freeze({ loadConfig, loadKeys, findDeployment, probeKernel, createReader, createIdentityReads, deploymentList: cliDeploymentList, startExec, admitDeployment, prepareRemoteTerm, createPanel, sweep,
98
99
  runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
99
100
  createCapabilityCatalog, createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction });
100
101
 
@@ -144,6 +145,9 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
144
145
  if (!isTerminal({ stdin, stdout, env })) { stderr.write(`${NO_TERMINAL}\n`); return 1; }
145
146
  const config = effects.loadConfig({ env, home, platform: proc.platform });
146
147
  if (!config.ok) { stderr.write(config.lines.map((line) => `${line}\n`).join("")); return 1; }
148
+ // keys.json, the chord family (docs/tui.md, "Switch to Ctrl+Shift"): read once, here, and never
149
+ // a reason not to start: what is wrong with it is the default, and the help says why.
150
+ const keysRead = effects.loadKeys({ env, home });
147
151
  const found = effects.findDeployment(resolve(cwd(), options.dir ?? "."));
148
152
  // A `--dir` that is in no deployment is refused as it is: what was asked for is not there.
149
153
  if (!found.ok && options.dir !== null) { stderr.write(`${noDeployment(found.dir)}\n`); return 1; }
@@ -163,7 +167,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
163
167
  const clock = () => new Date(now()).toISOString();
164
168
  const look = glyphs(env, { ascii: options.ascii || config.ascii });
165
169
  const screen = createScreen({ ...look, color: colorEnabled(env) });
166
- let state = initialState({ deployment: found.ok ? found.deployment : null, cli: probe.cli, home, entry: found.ok ? pendingEntry(null, clock()) : null, actions: config.actions, ascii: look.ascii, platform: proc.platform, detachKey: config.detachKey });
170
+ let state = initialState({ deployment: found.ok ? found.deployment : null, cli: probe.cli, home, entry: found.ok ? pendingEntry(null, clock()) : null, actions: config.actions, ascii: look.ascii, platform: proc.platform, detachKey: config.detachKey, keysRead });
167
171
  const keymap = bindings(state.actions);
168
172
  // THE KITTY KEYBOARD PROTOCOL (docs/tui.md, "Chords"): asked for as the terminal is taken (the
169
173
  // guard's PUSH and QUERY), "asking" until it answers or KEYBOARD_WAIT_MS passes, then the flags
@@ -172,7 +176,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
172
176
  let kb = keyboard ? "asking" : null, kbTimer = null;
173
177
  /** The clock time the wait for the answer ends: what may begin it is held up to then. */
174
178
  const answerBy = keyboard ? now() + KEYBOARD_WAIT_MS : null;
175
- const newParser = () => createKeyParser({ now, keyboard: kb, chords: state.chords, answerBy });
179
+ const newParser = () => createKeyParser({ now, keyboard: kb, chords: state.chords, leader: state.leaderKey, answerBy });
176
180
  let parser = newParser();
177
181
  // While a terminal has the focus the bytes typed go to the agent: this scanner takes from them
178
182
  // only the back key, the chords and a bracketed paste (term/through.mjs). A new one each time the
@@ -430,12 +434,18 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
430
434
  if (effect === "suspend") guard.suspend();
431
435
  if (effect === "redraw") guard.reassert(); // the modes again, then the whole screen
432
436
  if (effect === null || typeof effect !== "object") return false;
433
- if (effect.list) readList();
437
+ if (effect.list) readList({ identify: effect.identify === true });
434
438
  if (effect.remove) removeListed(effect.remove);
435
439
  if (effect.admit !== undefined) {
436
440
  const admitted = effects.admitDeployment(effect.admit);
437
441
  took(reduce(state, admitted.ok ? { admitted: admitted.deployment, at: clock() } : { refused: effect.admit }, keymap));
438
442
  }
443
+ if (effect.join) {
444
+ // Each listed deployment of the workspace picked, asked whether it is a deployment now, as a picked row is.
445
+ const answers = effect.join.paths.map((path) => [path, effects.admitDeployment(path)]);
446
+ const canonical = new Map(answers.filter(([, a]) => a.ok).map(([path, a]) => [path, a.deployment]));
447
+ took(reduce(state, { joined: { admitted: [...canonical.values()], opens: effect.join.opens.map((id) => canonical.get(id) ?? id) }, at: clock() }, keymap));
448
+ }
439
449
  if (effect.abandon) giveUpPreflight();
440
450
  // A tab shown (`show`) needs nothing here: the frame after it brings the panel to it (fitPanel).
441
451
  if (effect.close !== undefined) for (const id of effect.close) closeTerminal(id);
@@ -476,18 +486,32 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
476
486
  /** The read on its way: `{ again }`, `again` once another was asked for meanwhile; or null. */
477
487
  let listRead = null;
478
488
  const listChange = (bin, argv, options, callback) => reader.changeExec(bin, argv, { ...options, label: LIST_CHANGE }, callback);
479
- function readList() {
489
+ /** `identify`: once the list has answered, read the identities of its rows (`identify` below). A read asked
490
+ * for while one is on its way keeps the wish of either. */
491
+ function readList({ identify: wanted = false } = {}) {
480
492
  if (ended || !listing) return;
481
- if (listRead !== null) { listRead.again = true; return; }
482
- const mine = listRead = { again: false };
493
+ if (listRead !== null) { listRead.again = true; listRead.identify ||= wanted; return; }
494
+ const mine = listRead = { again: false, identify: wanted };
483
495
  Promise.resolve()
484
496
  .then(() => effects.deploymentList(probe.cli, { action: "list" }, { exec: reader.exec, env }))
485
497
  .then((answer) => (answer.ok ? { rows: answer.value.rows } : { failure: answer.reason }), () => ({ failure: NOT_ASKED }))
486
498
  .then((listed) => {
487
499
  listRead = null;
488
- if (mine.again) readList(); else heard({ listed });
500
+ if (mine.again) return readList({ identify: mine.identify });
501
+ heard({ listed });
502
+ if (mine.identify) identify();
489
503
  });
490
504
  }
505
+ // THE IDENTITY READS (lib/read.mjs createIdentityReads; docs/tui.md, "The switcher"): the rows of this
506
+ // computer's list that this run does not serve and that the kernel says are deployments, each read for
507
+ // its workspace's identity, one at a time, so the switcher puts it in its workspace's row. At the start
508
+ // and when the switcher is opened or refreshed, never on a timer; their answers come in as the screen
509
+ // is used. A suspend gives the run up (what a stopped TUI reads is no evidence), as it does the cycles.
510
+ const identities = effects.createIdentityReads({ cli: probe.cli, exec: reader.exec, env, onRead: (identity) => heard({ identity }) });
511
+ function identify() {
512
+ if (ended) return;
513
+ identities.start(state.listed.rows.filter((row) => row.state === "ok" && !state.ctxs.includes(row.path)).map((row) => row.path));
514
+ }
491
515
  /** Remove the row the store asked about (`{ path, name }`) from the list: nothing on disk is
492
516
  * touched. Its answer goes to the store, which asks for the list again. */
493
517
  function removeListed({ path, name }) {
@@ -774,7 +798,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
774
798
  // The run's directory goes last, made for whichever of the two needed it first: the reader
775
799
  // removes it only when it wrote a change there, and one it cannot remove (a change still
776
800
  // writing) stays.
777
- onEnd() { ended = true; spawnTimers.end(); dismiss(confirmation?.n); panel.end(); reader.stop(); if (dir !== null) { try { effects.removeDir(dir); } catch { /* not empty, or gone */ } } },
801
+ onEnd() { ended = true; spawnTimers.end(); dismiss(confirmation?.n); panel.end(); identities.stop(); reader.stop(); if (dir !== null) { try { effects.removeDir(dir); } catch { /* not empty, or gone */ } } },
778
802
  });
779
803
  function refresh(how) { Promise.resolve(reader.request(how)).catch(() => {}); }
780
804
  /** A preflight under way when the process stops: given up, and the store told. */
@@ -785,7 +809,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
785
809
  }
786
810
  /** Every read in flight is void (lib/read.mjs), the roster's with them: the reader says nothing
787
811
  * for a void read, so the state is told here that none is in flight. */
788
- function dropReads() { reader.voidInFlight(); state = reduce(state, { collecting: false }, keymap).state; }
812
+ function dropReads() { reader.voidInFlight(); identities.stop(); state = reduce(state, { collecting: false }, keymap).state; }
789
813
  /** The events of one batch of input, in order. Once one of them gave the terminal the focus,
790
814
  * the rest are dropped: they were typed before it had it, and neither the list nor the agent
791
815
  * is to have them (a `q` behind the Enter would end the run). Each batch is one read of input,
@@ -816,6 +840,9 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
816
840
  if (kb === "asking" && !ended) kbTimer = setTimer(() => { kbTimer = null; guard.attempt(() => { const released = parser.giveUp(); answered(null); if (released.length && !typing()) act(released); watchEscape(); }); }, Math.max(0, answerBy - now()));
817
841
  guard.attempt(() => { if (!ended) Promise.resolve(reader.start()).catch(() => {}); });
818
842
  if (found.ok) guard.attempt(() => { if (!ended) listStart(found.deployment); });
843
+ // Once a run, at the start: the identities of this computer's listed deployments, the list read first
844
+ // when the run did not read it before the terminal was taken.
845
+ guard.attempt(() => { if (!ended) { if (listedAtStart) identify(); else readList({ identify: true }); } });
819
846
  guard.attempt(() => guard.draw());
820
847
  // Once a run, after the first frame: what runs that are gone left of their private servers
821
848
  // (lib/panel.mjs sweep, which signals nothing and removes only what it can prove is dead).