@awebai/oats 0.65.0 → 0.67.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -5
- package/bin/oats.mjs +74 -20
- package/docs/capabilities.md +4 -4
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +222 -10
- package/docs/desktop.md +101 -22
- package/docs/implementation.md +16 -6
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.66.0.md +183 -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 +5 -4
- package/docs/souls-and-instances.md +20 -3
- package/docs/tui.md +658 -143
- package/docs/upgrading.md +107 -25
- package/docs/workspaces.md +9 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +126 -54
- package/lib/deployments.mjs +21 -5
- 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 +2 -2
- 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 +99 -11
- package/packages/client/keys-file.mjs +122 -0
- package/packages/client/machine-contract.mjs +1 -5
- 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/record/bin/setup.mjs +10 -2
- package/packages/record/docs/capture-service.md +45 -6
- package/packages/record/lib/capture-service-install.mjs +6 -95
- package/packages/record/lib/capture-setup-write.mjs +233 -0
- package/packages/tui/README.md +9 -8
- package/packages/tui/lib/actions.mjs +108 -64
- package/packages/tui/lib/client.mjs +8 -3
- package/packages/tui/lib/config.mjs +208 -26
- package/packages/tui/lib/main.mjs +91 -20
- package/packages/tui/lib/model.mjs +167 -61
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +156 -47
- package/packages/tui/lib/term/keys.mjs +150 -34
- package/packages/tui/lib/term/kitty.mjs +223 -0
- package/packages/tui/lib/term/through.mjs +174 -27
- package/packages/tui/lib/term/tty.mjs +43 -12
- package/packages/tui/lib/views/frame.mjs +158 -79
- package/packages/tui/lib/views/help.mjs +143 -21
- 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 +107 -34
|
@@ -5,29 +5,35 @@
|
|
|
5
5
|
// An action that does one thing in the list of instances and another in the switcher (`open`)
|
|
6
6
|
// says so in `views`: what it does in each, in the order the help lists them. An action of one
|
|
7
7
|
// view only (the four acts) names that view, so the help says where it acts.
|
|
8
|
+
// The keys the TUI shares with the Desktop are not written here: an action with no `keys` of its own
|
|
9
|
+
// takes its default keys from the shared keymap (packages/client/keymap.mjs PLAIN_KEYS), and the
|
|
10
|
+
// leader's table is the shared one (LEADER, below). What only the TUI has (q, Ctrl+C, Ctrl+Z, Ctrl+L,
|
|
11
|
+
// Ctrl+K, Tab, Esc, Delete, C, i) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
|
|
12
|
+
import { CHORDS, DEFAULT_CHORD_FAMILY, LEADER_TABLE, PALETTE_KEYS, chordKeyOf, plainKeys } from "./client.mjs";
|
|
13
|
+
import { legacyChord } from "./term/kitty.mjs";
|
|
8
14
|
import { isBackKey } from "./term/through.mjs";
|
|
9
15
|
|
|
10
16
|
export const ACTIONS = Object.freeze([
|
|
11
|
-
{ id: "up",
|
|
12
|
-
{ id: "down",
|
|
13
|
-
{ id: "top",
|
|
14
|
-
{ id: "bottom",
|
|
15
|
-
{ id: "page-up",
|
|
16
|
-
{ id: "page-down",
|
|
17
|
-
{ id: "collapse",
|
|
18
|
-
{ id: "expand",
|
|
17
|
+
{ id: "up", label: "up" },
|
|
18
|
+
{ id: "down", label: "down" },
|
|
19
|
+
{ id: "top", label: "first" },
|
|
20
|
+
{ id: "bottom", label: "last" },
|
|
21
|
+
{ id: "page-up", label: "page up" },
|
|
22
|
+
{ id: "page-down", label: "page down" },
|
|
23
|
+
{ id: "collapse", label: "collapse, or go to the parent" },
|
|
24
|
+
{ id: "expand", label: "expand, or go to the first child" },
|
|
19
25
|
{ id: "detail", keys: ["tab"], label: "detail" },
|
|
20
|
-
{ id: "filter",
|
|
21
|
-
{ id: "refresh",
|
|
26
|
+
{ id: "filter", label: "filter" },
|
|
27
|
+
{ id: "refresh", label: "refresh" },
|
|
22
28
|
// The views by their number. The sidebar names the views, each with its key at the right of its row
|
|
23
29
|
// (docs/tui.md, "What it shows"): the digits are named here, so in the help and the sidebar.
|
|
24
|
-
{ id: "instances",
|
|
25
|
-
{ id: "souls",
|
|
26
|
-
{ id: "capabilities",
|
|
27
|
-
{ id: "workspaces",
|
|
30
|
+
{ id: "instances", label: "instances" },
|
|
31
|
+
{ id: "souls", label: "souls" },
|
|
32
|
+
{ id: "capabilities", label: "capabilities" },
|
|
33
|
+
{ id: "workspaces", label: "workspaces" },
|
|
28
34
|
// The palette (docs/tui.md, "The palette"): from every focus it is the leader and then `k`.
|
|
29
35
|
{ id: "palette", keys: ["ctrl+k"], label: "palette" },
|
|
30
|
-
{ id: "open",
|
|
36
|
+
{ id: "open", label: "open", views: [["instances", "open the selected agent's terminal as a tab beside the list, or show its tab when it has one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"], ["souls", "show the selected soul's detail, and from the detail its instances, in the Souls view"], ["capabilities", "show the selected capability's detail, and from the detail the marked soul that uses it, in the Capabilities view"]] },
|
|
31
37
|
// The switcher's Remove (docs/tui.md, "The switcher"; awebai/oats#1390): a row of this computer's
|
|
32
38
|
// deployments list, after a confirmation; nothing on disk is touched. Delete, and no letter: a new
|
|
33
39
|
// default key that a user's tui.json already gives to another action would make that file refused
|
|
@@ -40,76 +46,107 @@ export const ACTIONS = Object.freeze([
|
|
|
40
46
|
// The open terminal, from the list (docs/tui.md, "Open an agent's terminal"). While the terminal
|
|
41
47
|
// has the focus the TUI takes no key but the leader (tui.json's open.detachKey), so neither of
|
|
42
48
|
// these is ever read there: the leader's table has its own (LEADER).
|
|
43
|
-
{ id: "zoom",
|
|
44
|
-
{ id: "close-terminal",
|
|
45
|
-
{ id: "tab-previous",
|
|
46
|
-
{ id: "tab-next",
|
|
49
|
+
{ id: "zoom", label: "zoom", views: [["instances", "go to the shown terminal with the whole screen; the leader then Esc brings the list back"]] },
|
|
50
|
+
{ id: "close-terminal", label: "close terminal", views: [["instances", "close the shown terminal and show its neighbour; the agent keeps running"]] },
|
|
51
|
+
{ id: "tab-previous", label: "previous tab", views: [["instances", "show the terminal of the tab before the shown one"]] },
|
|
52
|
+
{ id: "tab-next", label: "next tab", views: [["instances", "show the terminal of the tab after the shown one"]] },
|
|
47
53
|
// The split (docs/tui.md, "Splits"): two groups of tabs at most, side by side or one above the
|
|
48
54
|
// other. `group-next`, `tab-move` and `group-close` have no key of their own here by default
|
|
49
55
|
// (Tab is the detail's, and `m` and `x` are often a tui.json's): the leader's are.
|
|
50
|
-
{ id: "split-right",
|
|
51
|
-
{ id: "split-down",
|
|
56
|
+
{ id: "split-right", label: "split right", views: [["instances", "split the panel side by side; the new group, on the right, is empty and focused"]] },
|
|
57
|
+
{ id: "split-down", label: "split down", views: [["instances", "split the panel one above the other; the new group, below, is empty and focused"]] },
|
|
52
58
|
{ id: "group-next", keys: [], label: "next group", views: [["instances", "go to the other group's terminal, or to the focused group's from the list"]] },
|
|
53
59
|
{ id: "tab-move", keys: [], label: "move tab", views: [["instances", "move the shown tab to the other group, and go there"]] },
|
|
54
60
|
{ id: "group-close", keys: [], label: "close group", views: [["instances", "close the focused group while it is empty"]] },
|
|
55
61
|
// The four acts on an instance: each opens a confirmation, and nothing is done before a move and
|
|
56
62
|
// a press in it. Capitals: a lower-case key is one slip away, a capital takes Shift.
|
|
57
|
-
{ id: "stop",
|
|
58
|
-
{ id: "retire",
|
|
59
|
-
{ id: "start",
|
|
60
|
-
{ id: "restart",
|
|
63
|
+
{ id: "stop", label: "stop", views: [["instances", "stop the selected agent, after a confirmation"]] },
|
|
64
|
+
{ id: "retire", label: "retire", views: [["instances", "retire the selected agent, after a confirmation"]] },
|
|
65
|
+
{ id: "start", label: "start", views: [["instances", "start the selected agent as it was last launched, after a confirmation"]] },
|
|
66
|
+
{ id: "restart", label: "restart", views: [["instances", "restart the selected agent as it was last launched, after a confirmation"]] },
|
|
61
67
|
// A spawn (docs/tui.md, "Spawning an agent"): a prompt over the list, the soul picked, the
|
|
62
68
|
// shared preview, and one Enter. Only on this machine's workspace, one spawn at a time.
|
|
63
|
-
{ id: "spawn",
|
|
64
|
-
{ id: "spawn-another",
|
|
69
|
+
{ id: "spawn", label: "spawn", views: [["instances", "spawn an agent: pick its soul, then the preview, and Enter spawns it"], ["souls", "spawn an agent of the selected soul: the preview, and Enter spawns it"]] },
|
|
70
|
+
{ id: "spawn-another", label: "spawn another", views: [["instances", "spawn another agent of the selected agent's soul: the preview, and Enter spawns it"], ["souls", "the same as n"]] },
|
|
65
71
|
// Offered only while a spawn's outcome is not known: it asks the kernel once, never spawns again.
|
|
66
72
|
{ id: "spawn-check", keys: ["C"], label: "check spawn", views: [["instances", "check the result of a spawn whose outcome is not known, while one is"]] },
|
|
67
|
-
{ id: "help",
|
|
73
|
+
{ id: "help", label: "help" },
|
|
68
74
|
{ id: "close", keys: ["escape"], label: "close" },
|
|
69
75
|
{ id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
|
|
70
76
|
{ id: "suspend", keys: ["ctrl+z"], label: "suspend" },
|
|
71
77
|
{ id: "redraw", keys: ["ctrl+l"], label: "redraw" },
|
|
72
|
-
].map((action) => Object.freeze({
|
|
78
|
+
].map(({ keys, ...action }) => Object.freeze({ id: action.id, keys: Object.freeze([...(keys ?? plainKeys(action.id))]), ...action, ...(action.views ? { views: Object.freeze(action.views.map((view) => Object.freeze([...view]))) } : {}) })));
|
|
73
79
|
|
|
74
80
|
/** THE LEADER'S TABLE (docs/tui.md, "The leader"): the keys read after the leader (tui.json's
|
|
75
|
-
* open.detachKey) and what each does, from every focus.
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
{ keys: ["X"], does: "stop", label: "stop" },
|
|
100
|
-
{ keys: ["R"], does: "restart", label: "restart" },
|
|
101
|
-
{ keys: ["S"], does: "start", label: "start" },
|
|
102
|
-
{ keys: ["D"], does: "retire", label: "retire" },
|
|
103
|
-
{ keys: ["n"], does: "spawn", label: "spawn" },
|
|
104
|
-
{ keys: ["N"], does: "spawn-another", label: "spawn another" },
|
|
105
|
-
{ keys: ["/"], does: "filter", label: "filter" },
|
|
106
|
-
{ keys: ["o"], does: "workspaces", label: "workspaces" },
|
|
107
|
-
{ keys: ["?"], does: "help", label: "help" },
|
|
108
|
-
{ keys: ["escape"], does: "list", label: "the list" },
|
|
109
|
-
].map((entry) => Object.freeze({ ...entry, keys: Object.freeze([...entry.keys]) })));
|
|
81
|
+
* open.detachKey) and what each does, from every focus. It is the shared one, the Desktop's too
|
|
82
|
+
* (packages/client/keymap.mjs LEADER_TABLE), in its order, with its labels and its `terminal`
|
|
83
|
+
* rows: named in the hint only while a terminal is open, and nothing without one. What the TUI
|
|
84
|
+
* adds to a row is its own, keyed by `does`: the hint's filters (views/frame.mjs leaderHints:
|
|
85
|
+
* the tab keys only with two tabs or more, the split's only where they apply). Fixed: tui.json's
|
|
86
|
+
* `keys` rebinds the plain keys of ACTIONS only. Each `does` is handled by the TUI
|
|
87
|
+
* (leaderHandles); the leader pressed again is not in the table, as it is the user's key: from the
|
|
88
|
+
* open terminal's focus it types the leader's own bytes into the agent, the focus staying there,
|
|
89
|
+
* and from any other focus it only closes the hint (lib/store.mjs `twice`). */
|
|
90
|
+
export const LEADER = LEADER_TABLE;
|
|
91
|
+
/** What the leader does that no action of ACTIONS does (lib/store.mjs `led`): `previous` and
|
|
92
|
+
* `next` (the instance before or after the shown terminal's, or the selection's: its tab shown,
|
|
93
|
+
* or opened as a new one, with the focus in it) and `list` (the list's focus, which Esc gives). */
|
|
94
|
+
export const LEADER_OWN = Object.freeze(["previous", "next", "list"]);
|
|
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);
|
|
110
105
|
/** key id -> what the leader then does (LEADER's `does`). */
|
|
111
106
|
export const LEADER_KEYS = new Map(LEADER.flatMap((entry) => entry.keys.map((key) => [key, entry.does])));
|
|
112
107
|
|
|
108
|
+
/** THE CHORDS (docs/tui.md, "Chords"): key id -> `does`, the shared ones (packages/client/keymap.mjs
|
|
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) {
|
|
120
|
+
const bound = new Set(actions.flatMap((action) => action.keys));
|
|
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)));
|
|
148
|
+
}
|
|
149
|
+
|
|
113
150
|
/** key id -> action id. A key bound twice is a defect of the table, refused when it is read. */
|
|
114
151
|
export function bindings(actions = ACTIONS) {
|
|
115
152
|
const map = new Map();
|
|
@@ -129,6 +166,13 @@ export function keyLabel(key) {
|
|
|
129
166
|
return [...parts.map((part) => NAMES[part] ?? part), name].join("+");
|
|
130
167
|
}
|
|
131
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
|
+
|
|
132
176
|
/** The modifiers of the back key's grammar (term/through.mjs BACK_KEY) as a person reads them. */
|
|
133
177
|
const BACK_MODIFIERS = Object.freeze({ C: "Ctrl", M: "Alt", S: "Shift" });
|
|
134
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,6 +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";
|
|
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";
|
|
53
58
|
|
|
54
59
|
/** The words a shared sentence uses where it names the client that shows it (client-terms.mjs).
|
|
55
60
|
* Made once, here: every shared function that takes `terms` is passed this constant, and refuses
|
|
@@ -1,15 +1,18 @@
|
|
|
1
1
|
// The user's key file, tui.json: which keys do what, whether the screen is drawn in ASCII, and the
|
|
2
2
|
// key that takes the focus from an agent's terminal back to the list.
|
|
3
|
-
// Read once at start and never written
|
|
4
|
-
// problem as one line that says what to change:
|
|
3
|
+
// Read once at start, and never written but by its move from where it was before (moved()). A file
|
|
4
|
+
// that is wrong in any way is refused whole, each problem as one line that says what to change:
|
|
5
|
+
// the TUI resolves no conflict and guesses nothing
|
|
5
6
|
// (there is no "last wins"), because a key that silently does something else is worse than a
|
|
6
7
|
// program that does not start. The lines go to a terminal, so nothing taken from the file, and
|
|
7
8
|
// no path, reaches one unless it is plain printable ASCII.
|
|
8
|
-
|
|
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.
|
|
11
|
+
import { closeSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
|
|
9
12
|
import { homedir } from "node:os";
|
|
10
|
-
import { isAbsolute, join } from "node:path";
|
|
13
|
+
import { basename, dirname, isAbsolute, join } from "node:path";
|
|
11
14
|
import { ACTIONS, bindings, keyLabel } from "./actions.mjs";
|
|
12
|
-
import { displayLine } from "./client.mjs";
|
|
15
|
+
import { KEYS_LIMIT, chordFamilyFrom, displayLine, keysPath, leaderKey } from "./client.mjs";
|
|
13
16
|
import { isKeyId } from "./term/keys.mjs";
|
|
14
17
|
import { BACK_KEY_RULE, backKeyId, isBackKey } from "./term/through.mjs";
|
|
15
18
|
|
|
@@ -19,12 +22,19 @@ export const CONFIG_LIMIT = 64 * 1024;
|
|
|
19
22
|
const TOO_LARGE = `it is larger than ${CONFIG_LIMIT / 1024} KiB`;
|
|
20
23
|
const NOT_AN_OBJECT = 'it is not one JSON object, like {"keys": {"quit": ["q"]}}';
|
|
21
24
|
const SETTINGS = "the settings are keys, ascii and open";
|
|
25
|
+
/** A key id of the shared keymap (`ctrl+x`, `alt+o`) in the back key's spelling (`C-x`, `M-o`):
|
|
26
|
+
* Ctrl or Alt and one character, which is what the shared leader is. Anything else: null. */
|
|
27
|
+
function backKeyOf(keyId) {
|
|
28
|
+
const [, mod, rest] = /^(ctrl|alt)\+(.)$/.exec(keyId) ?? [];
|
|
29
|
+
return mod === undefined ? null : `${mod === "ctrl" ? "C" : "M"}-${rest}`;
|
|
30
|
+
}
|
|
22
31
|
/** The back key when tui.json names none, on `platform` (a `process.platform` value): the key that
|
|
23
32
|
* takes the focus from an agent's terminal back to the list, the leader (the setting keeps its
|
|
24
|
-
* name, `open.detachKey`, from when it left a viewer).
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
|
|
33
|
+
* name, `open.detachKey`, from when it left a viewer). It is the shared leader, the Desktop's too
|
|
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. */
|
|
37
|
+
export const defaultDetachKey = (platform = process.platform) => backKeyOf(leaderKey(platform === "darwin"));
|
|
28
38
|
/** An action id this program had and has no more, with what it is called now. */
|
|
29
39
|
const RENAMED = Object.freeze({ "open-workspace": "open" });
|
|
30
40
|
const KEY_IDS = "key ids look like q, ctrl+c, shift+tab, f5, space";
|
|
@@ -45,12 +55,22 @@ const isObject = (value) => value !== null && typeof value === "object" && !Arra
|
|
|
45
55
|
/** Never the text of an error, which may hold anything: its code, when that is a plain one. */
|
|
46
56
|
const unreadable = (error) => { const code = error?.code; return `it cannot be read${typeof code === "string" && ERROR_CODE.test(code) ? ` (${code})` : ""}`; };
|
|
47
57
|
|
|
48
|
-
/** The path of tui.json:
|
|
49
|
-
*
|
|
58
|
+
/** The path of tui.json: `config/tui.json` in OATS's own directory of this user, `$OATS_HOME_DIR`
|
|
59
|
+
* when that is set and not empty, else `<home>/.oats` (the kernel's rule for its files, as
|
|
60
|
+
* lib/deployments.mjs has it for this computer's list of deployments). */
|
|
50
61
|
export function configPath(env, home) {
|
|
62
|
+
const own = env?.OATS_HOME_DIR;
|
|
63
|
+
return join(typeof own === "string" && own !== "" ? own : join(home, ".oats"), "config", "tui.json");
|
|
64
|
+
}
|
|
65
|
+
/** Where tui.json was before awebai/oats#1390 step (b), and is looked for only to move it
|
|
66
|
+
* (moved()): `$XDG_CONFIG_HOME/oats/tui.json` when that variable is set, not empty and absolute
|
|
67
|
+
* (the XDG rule: a relative value is ignored), else `<home>/.config/oats/tui.json`. */
|
|
68
|
+
export function oldConfigPath(env, home) {
|
|
51
69
|
const xdg = env?.XDG_CONFIG_HOME;
|
|
52
70
|
return join(typeof xdg === "string" && xdg !== "" && isAbsolute(xdg) ? xdg : join(home, ".config"), "oats", "tui.json");
|
|
53
71
|
}
|
|
72
|
+
/** What the old file is renamed to once it is copied: beside it, so it is never lost. */
|
|
73
|
+
export const MIGRATED = "tui.json.migrated";
|
|
54
74
|
|
|
55
75
|
/** What tui.json says, checked: `value` is the file already parsed, `defaults` the action table,
|
|
56
76
|
* `platform` the one the TUI runs on (a `process.platform` value). Pure. Answers
|
|
@@ -137,9 +157,36 @@ function openProblem(given) {
|
|
|
137
157
|
|
|
138
158
|
/** The file system as loadConfig needs it. `stat` follows symbolic links and answers null for a
|
|
139
159
|
* path that does not exist, which includes a path under something that is not a directory (an
|
|
140
|
-
*
|
|
141
|
-
* the limit and one byte, whatever the file became since it was measured
|
|
160
|
+
* OATS_HOME_DIR of /dev/null); every other failure is thrown. `read` never takes in more than
|
|
161
|
+
* the limit and one byte, whatever the file became since it was measured, and `bytes` the same as
|
|
162
|
+
* bytes. For the move (moved()): `entry` answers `{ ino }` when an entry is at the path, a link
|
|
163
|
+
* not followed (a link to nothing is an entry), or null; `place` writes `bytes` as a new file at
|
|
164
|
+
* `path`, never over one: a file of its own first (mode 0600, synced), in the directory it makes
|
|
165
|
+
* with mode 0700 when it is missing, then linked there. It answers that file's `{ ino }`, with
|
|
166
|
+
* `taken: true` when an entry was at `path` already and nothing was placed; every failure is
|
|
167
|
+
* thrown, marked `noLinks` when the file system has no hard links. `rename` and `remove` are rename(2) and unlink(2), which act on a link itself. */
|
|
142
168
|
const NODE_IO = Object.freeze({
|
|
169
|
+
entry: entryAt,
|
|
170
|
+
bytes(path) { return readCapped(path); },
|
|
171
|
+
place(bytes, to) {
|
|
172
|
+
mkdirSync(dirname(to), { recursive: true, mode: 0o700 });
|
|
173
|
+
const own = join(dirname(to), `.${basename(to)}.${process.pid}.${Date.now()}.tmp`);
|
|
174
|
+
const ino = written(own, bytes);
|
|
175
|
+
try {
|
|
176
|
+
linkSync(own, to);
|
|
177
|
+
return { ino };
|
|
178
|
+
} catch (error) {
|
|
179
|
+
if (error?.code === "EEXIST") return { ino, taken: true };
|
|
180
|
+
// A file system without hard links has no step that is both whole and never over a file
|
|
181
|
+
// (there is no rename that refuses one): the move is refused, nothing placed.
|
|
182
|
+
if (NO_LINKS.has(error?.code)) error.noLinks = true;
|
|
183
|
+
throw error;
|
|
184
|
+
} finally {
|
|
185
|
+
try { unlinkSync(own); } catch { /* its own file, in a directory it could write */ }
|
|
186
|
+
}
|
|
187
|
+
},
|
|
188
|
+
rename(from, to) { renameSync(from, to); },
|
|
189
|
+
remove(path) { unlinkSync(path); },
|
|
143
190
|
stat(path) {
|
|
144
191
|
try {
|
|
145
192
|
const found = statSync(path);
|
|
@@ -149,19 +196,122 @@ const NODE_IO = Object.freeze({
|
|
|
149
196
|
throw error;
|
|
150
197
|
}
|
|
151
198
|
},
|
|
152
|
-
read(path) {
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
while (length < bytes.length && (got = readSync(fd, bytes, length, bytes.length - length, null)) > 0) length += got;
|
|
158
|
-
if (length > CONFIG_LIMIT) throw Object.assign(new Error("tui.json grew past the limit while it was read"), { code: "EFBIG" });
|
|
159
|
-
return bytes.toString("utf8", 0, length);
|
|
160
|
-
} finally { closeSync(fd); }
|
|
161
|
-
},
|
|
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); },
|
|
162
204
|
});
|
|
205
|
+
/** What link(2) answers on a file system without hard links (FAT, exFAT, some network mounts). */
|
|
206
|
+
const NO_LINKS = new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "ENOSYS"]);
|
|
207
|
+
/** `bytes` as a new file at `path`, made only where nothing is (mode 0600) and synced; answers its
|
|
208
|
+
* inode. A file it made and could not finish is removed. */
|
|
209
|
+
function written(path, bytes) {
|
|
210
|
+
const fd = openSync(path, "wx", 0o600);
|
|
211
|
+
let ino;
|
|
212
|
+
try {
|
|
213
|
+
for (let at = 0; at < bytes.length;) at += writeSync(fd, bytes, at, bytes.length - at);
|
|
214
|
+
fsyncSync(fd);
|
|
215
|
+
ino = fstatSync(fd).ino;
|
|
216
|
+
} catch (error) {
|
|
217
|
+
closeSync(fd);
|
|
218
|
+
try { unlinkSync(path); } catch { /* the error thrown says what failed */ }
|
|
219
|
+
throw error;
|
|
220
|
+
}
|
|
221
|
+
closeSync(fd);
|
|
222
|
+
return ino;
|
|
223
|
+
}
|
|
224
|
+
/** `{ ino }` of the entry at `path`, a link not followed, or null when there is none. */
|
|
225
|
+
function entryAt(path) {
|
|
226
|
+
try { return { ino: lstatSync(path).ino }; } catch (error) {
|
|
227
|
+
if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return null;
|
|
228
|
+
throw error;
|
|
229
|
+
}
|
|
230
|
+
}
|
|
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) {
|
|
234
|
+
const fd = openSync(path, "r");
|
|
235
|
+
try {
|
|
236
|
+
const bytes = Buffer.alloc(limit + 1);
|
|
237
|
+
let length = 0, got = 0;
|
|
238
|
+
while (length < bytes.length && (got = readSync(fd, bytes, length, bytes.length - length, null)) > 0) length += got;
|
|
239
|
+
return bytes.subarray(0, length);
|
|
240
|
+
} finally { closeSync(fd); }
|
|
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
|
+
}
|
|
248
|
+
|
|
249
|
+
/** A path for a line: as it is when it is printable ASCII of at most 200 characters, else `named`. */
|
|
250
|
+
const shownPath = (path, named) => (PLAIN_PATH.test(path) ? path : named);
|
|
251
|
+
/** Why a step of the move failed, for its line: never the text of an error, only its code. */
|
|
252
|
+
const failedBy = (error) => { const code = error?.code; return typeof code === "string" && ERROR_CODE.test(code) ? code : "it failed"; };
|
|
163
253
|
|
|
164
|
-
/**
|
|
254
|
+
/** THE MOVE OF tui.json (docs/tui.md, "Change the keys: tui.json"; awebai/oats#1390 §3), before
|
|
255
|
+
* it is read: the file the old rule found (`old`, oldConfigPath) and the one read now (`path`).
|
|
256
|
+
* old present, new absent its bytes are copied to the new path (placed: never over a file),
|
|
257
|
+
* then the old file is renamed to tui.json.migrated beside it (a link
|
|
258
|
+
* is renamed, not followed); then the new file is read. A copy that
|
|
259
|
+
* cannot be made, or a rename that fails, refuses with the line that
|
|
260
|
+
* says to move it by hand, the copy deleted first when it was made.
|
|
261
|
+
* both present refused: the old file is no longer read, and nothing is chosen.
|
|
262
|
+
* old absent nothing to move: the new file is read, or the defaults are used.
|
|
263
|
+
* "Present" is an entry at the path, a link to nothing included: it is reported, not guessed at.
|
|
264
|
+
* Answers null when the new file is to be read, else the line that refuses. A run that loses a
|
|
265
|
+
* race to another one starting (a new file placed by it after this run looked) asks the table
|
|
266
|
+
* again (again()): it reads the file that run placed once that run has moved the old file, and
|
|
267
|
+
* refuses as for both while an old file is still there, its own or the other's not yet renamed. */
|
|
268
|
+
function moved(old, path, io) {
|
|
269
|
+
const from = shownPath(old, "its old configuration file"), to = shownPath(path, "its configuration file");
|
|
270
|
+
const cannot = (reason) => `oats: \`oats tui\` cannot move ${from} to ${to} (${reason}); move it yourself (E_TUI_CONFIG)`;
|
|
271
|
+
const both = `oats: \`oats tui\`: ${from} is no longer read: the TUI reads ${to}. Copy what you need into ${to}, then remove ${from} (E_TUI_CONFIG)`;
|
|
272
|
+
// A step that fails because another run placed a new file since this one looked (the old file
|
|
273
|
+
// renamed, its backup made, the new path taken) asks the table again: a new file and no old one
|
|
274
|
+
// is that run's move, read; a new file beside this run's old one (another XDG_CONFIG_HOME's
|
|
275
|
+
// move) is both, refused; no new file is this step's failure.
|
|
276
|
+
const again = (reason) => {
|
|
277
|
+
try {
|
|
278
|
+
if (io.entry(path) === null) return cannot(reason);
|
|
279
|
+
return io.entry(old) === null ? null : both;
|
|
280
|
+
} catch { return cannot(reason); }
|
|
281
|
+
};
|
|
282
|
+
let had, has;
|
|
283
|
+
try { had = io.entry(old); } catch (error) { return cannot(failedBy(error)); }
|
|
284
|
+
if (had === null) return null;
|
|
285
|
+
try { has = io.entry(path); } catch (error) { return cannot(failedBy(error)); }
|
|
286
|
+
if (has !== null) return both;
|
|
287
|
+
const aside = join(dirname(old), MIGRATED);
|
|
288
|
+
let found, bytes, placed;
|
|
289
|
+
try {
|
|
290
|
+
// A backup of an earlier move is never written over.
|
|
291
|
+
if (io.entry(aside) !== null) return again(`${MIGRATED} is there already`);
|
|
292
|
+
found = io.stat(old);
|
|
293
|
+
} catch (error) { return again(failedBy(error)); }
|
|
294
|
+
if (found === null) return again("it is a link to nothing");
|
|
295
|
+
if (found.file !== true) return cannot("it is not a regular file");
|
|
296
|
+
if (!(typeof found.size === "number" && found.size <= CONFIG_LIMIT)) return cannot(TOO_LARGE);
|
|
297
|
+
try { bytes = io.bytes(old); } catch (error) { return error?.code === "EFBIG" ? cannot(TOO_LARGE) : again(failedBy(error)); }
|
|
298
|
+
try { placed = io.place(bytes, path); } catch (error) { return cannot(error?.noLinks === true ? "this file system has no hard links" : failedBy(error)); }
|
|
299
|
+
// Only an entry found at the new path itself is another run's file; an EEXIST thrown on the way
|
|
300
|
+
// (a `config` that is a file) is a failure like any other.
|
|
301
|
+
if (placed.taken === true) return again("EEXIST");
|
|
302
|
+
try { io.rename(old, aside); } catch (error) {
|
|
303
|
+
// The old file gone and a new one there (moved meanwhile by something else): the copy is the
|
|
304
|
+
// old file's bytes, and it is read; nothing is deleted.
|
|
305
|
+
try { if (io.entry(old) === null && io.entry(path) !== null) return null; } catch { /* refused below */ }
|
|
306
|
+
// The copy is deleted only while it is still the one this run made.
|
|
307
|
+
try { if (io.entry(path)?.ino === placed.ino) io.remove(path); } catch { /* the line says to move it by hand */ }
|
|
308
|
+
return cannot(failedBy(error));
|
|
309
|
+
}
|
|
310
|
+
return null;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** Read tui.json, once, after its move from where it was before (moved()). Answers
|
|
314
|
+
* `{ ok: true, actions, ascii, detachKey, path }`, or
|
|
165
315
|
* `{ ok: false, lines }`: the complete lines to print (no trailing newline), after which the TUI
|
|
166
316
|
* must not start. No file is the defaults: `actions` is ACTIONS itself, `ascii` is false and
|
|
167
317
|
* `detachKey` is defaultDetachKey(platform); `platform` is the one the TUI runs on (a
|
|
@@ -169,11 +319,14 @@ const NODE_IO = Object.freeze({
|
|
|
169
319
|
*
|
|
170
320
|
* `io` is the file system (node:fs when omitted): `io.stat(path)` answers `{ file, size }` after
|
|
171
321
|
* following symbolic links, or null when the path does not exist, and throws for anything else;
|
|
172
|
-
* `io.read(path)` answers the text
|
|
173
|
-
*
|
|
322
|
+
* `io.read(path)` answers the text; the move uses `entry`, `bytes`, `place`, `rename` and `remove`
|
|
323
|
+
* (see NODE_IO). The size is checked before `read` or `bytes` is called, so a file over
|
|
324
|
+
* CONFIG_LIMIT, a directory or a FIFO is never opened. A line holds a path only when it is
|
|
174
325
|
* printable ASCII, and never the text of an error: only its code, when it is a plain one. */
|
|
175
326
|
export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO, platform = process.platform } = {}) {
|
|
176
327
|
const path = configPath(env, home);
|
|
328
|
+
const refusal = moved(oldConfigPath(env, home), path, io);
|
|
329
|
+
if (refusal !== null) return { ok: false, lines: [refusal] };
|
|
177
330
|
const listed = (problems) => (problems.length > MAX_PROBLEMS ? [...problems.slice(0, MAX_PROBLEMS), problems.length - MAX_PROBLEMS === 1 ? "1 more problem is not listed" : `${problems.length - MAX_PROBLEMS} more problems are not listed`] : problems);
|
|
178
331
|
const refused = (problems) => ({ ok: false, lines: listed(problems).map((problem) => `oats: \`oats tui\` cannot use ${PLAIN_PATH.test(path) ? path : "its configuration file"}: ${problem} (E_TUI_CONFIG)`) });
|
|
179
332
|
let found, text, value;
|
|
@@ -186,3 +339,32 @@ export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO,
|
|
|
186
339
|
const checked = effectiveConfig(value, ACTIONS, platform);
|
|
187
340
|
return checked.ok ? { ...checked, path } : refused(checked.problems);
|
|
188
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
|
+
}
|