@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.
- package/bin/oats.mjs +66 -13
- package/docs/capabilities.md +4 -4
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +217 -6
- package/docs/desktop.md +101 -22
- package/docs/implementation.md +6 -5
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/servers.md +3 -2
- package/docs/souls-and-instances.md +20 -3
- package/docs/tui.md +570 -176
- package/docs/upgrading.md +107 -25
- package/docs/workspaces.md +1 -1
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +126 -54
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +5 -1
- package/lib/materialize.mjs +62 -11
- package/lib/servers.mjs +15 -6
- package/lib/soul-composition.mjs +7 -3
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +37 -5
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +3 -1
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +85 -24
- package/packages/client/keys-file.mjs +122 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +62 -9
- package/packages/client/spawn-naming.mjs +31 -0
- package/packages/client/spawn-preview-cli.mjs +22 -7
- package/packages/client/spawn-preview-contract.mjs +24 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +47 -2
- package/packages/tui/README.md +3 -3
- package/packages/tui/lib/actions.mjs +57 -14
- package/packages/tui/lib/client.mjs +8 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +40 -13
- package/packages/tui/lib/model.mjs +167 -63
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +148 -54
- package/packages/tui/lib/term/keys.mjs +19 -5
- package/packages/tui/lib/term/kitty.mjs +36 -11
- package/packages/tui/lib/term/through.mjs +61 -28
- package/packages/tui/lib/views/frame.mjs +158 -79
- package/packages/tui/lib/views/help.mjs +109 -26
- package/packages/tui/lib/views/instances.mjs +59 -20
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- 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
|
-
/**
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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
|
|
105
|
-
* (lib/store.mjs `led`)
|
|
106
|
-
*
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
|
|
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(
|
|
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
|
|
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
|
|
33
|
-
*
|
|
34
|
-
* (`ctrl
|
|
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
|
|
226
|
-
|
|
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(
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
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).
|