@awebai/oats 0.63.0 → 0.65.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -1
- package/bin/oats.mjs +158 -26
- package/docs/desktop-cli-api.md +127 -3
- package/docs/desktop.md +14 -5
- package/docs/execution-targets.md +9 -5
- package/docs/first-team.md +6 -0
- package/docs/implementation.md +17 -3
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.64.0.md +105 -0
- package/docs/release-notes/v0.65.0.md +187 -0
- package/docs/souls-and-instances.md +26 -6
- package/docs/tui.md +416 -238
- package/docs/upgrading.md +2 -1
- package/docs/workspaces.md +125 -1
- package/lib/core.mjs +43 -11
- package/lib/deployments.mjs +325 -0
- package/lib/resolved-deployment.mjs +37 -0
- package/lib/session-input.mjs +12 -2
- package/lib/workspace.mjs +2 -0
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-label.mjs +2 -2
- package/packages/client/deployment-list-cli.mjs +98 -0
- package/packages/client/deployment-list.mjs +91 -0
- package/packages/client/instance-tree.mjs +53 -3
- package/packages/client/keymap.mjs +106 -0
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/panel-views.mjs +1 -1
- package/packages/client/roster-sections.mjs +22 -6
- package/packages/client/workspace-admission.mjs +2 -1
- package/packages/tui/README.md +4 -4
- package/packages/tui/lib/actions.mjs +29 -5
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/config.mjs +21 -14
- package/packages/tui/lib/main.mjs +108 -31
- package/packages/tui/lib/model.mjs +71 -41
- package/packages/tui/lib/read.mjs +15 -45
- package/packages/tui/lib/store.mjs +158 -39
- package/packages/tui/lib/term/through.mjs +40 -18
- package/packages/tui/lib/views/act.mjs +17 -13
- package/packages/tui/lib/views/frame.mjs +418 -421
- package/packages/tui/lib/views/help.mjs +41 -19
- package/packages/tui/lib/views/instances.mjs +38 -9
- package/packages/tui/lib/views/switcher.mjs +65 -21
- package/skills/oats-getting-started/SKILL.md +440 -170
|
@@ -5,6 +5,8 @@
|
|
|
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
|
+
import { isBackKey } from "./term/through.mjs";
|
|
9
|
+
|
|
8
10
|
export const ACTIONS = Object.freeze([
|
|
9
11
|
{ id: "up", keys: ["up", "k"], label: "up" },
|
|
10
12
|
{ id: "down", keys: ["down", "j"], label: "down" },
|
|
@@ -17,8 +19,8 @@ export const ACTIONS = Object.freeze([
|
|
|
17
19
|
{ id: "detail", keys: ["tab"], label: "detail" },
|
|
18
20
|
{ id: "filter", keys: ["/"], label: "filter" },
|
|
19
21
|
{ id: "refresh", keys: ["r"], label: "refresh" },
|
|
20
|
-
// The views by their number. The
|
|
21
|
-
// (docs/tui.md, "
|
|
22
|
+
// The views by their number. The sidebar names the views, each with its key at the right of its row
|
|
23
|
+
// (docs/tui.md, "What it shows"): the digits are named here, so in the help and the sidebar.
|
|
22
24
|
{ id: "instances", keys: ["1"], label: "instances" },
|
|
23
25
|
{ id: "souls", keys: ["2"], label: "souls" },
|
|
24
26
|
{ id: "capabilities", keys: ["3"], label: "capabilities" },
|
|
@@ -26,13 +28,19 @@ export const ACTIONS = Object.freeze([
|
|
|
26
28
|
// The palette (docs/tui.md, "The palette"): from every focus it is the leader and then `k`.
|
|
27
29
|
{ id: "palette", keys: ["ctrl+k"], label: "palette" },
|
|
28
30
|
{ id: "open", keys: ["enter"], 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
|
+
// The switcher's Remove (docs/tui.md, "The switcher"; awebai/oats#1390): a row of this computer's
|
|
32
|
+
// deployments list, after a confirmation; nothing on disk is touched. Delete, and no letter: a new
|
|
33
|
+
// default key that a user's tui.json already gives to another action would make that file refused
|
|
34
|
+
// at the start (config.mjs claims every default first), and the free letters are the ones a
|
|
35
|
+
// tui.json is likeliest to use (`x` and `m` among them, see the split below).
|
|
36
|
+
{ id: "remove", keys: ["delete"], label: "remove", views: [["switcher", "remove the selected row of this computer's list of deployments, after a confirmation; its folder stays"]] },
|
|
29
37
|
// The Souls view (docs/tui.md, "The Souls view"): the selected soul's instances, in the
|
|
30
38
|
// Instances view, filtered by that soul.
|
|
31
39
|
{ id: "soul-instances", keys: ["i"], label: "instances", views: [["souls", "the selected soul's instances, in the Instances view"]] },
|
|
32
40
|
// The open terminal, from the list (docs/tui.md, "Open an agent's terminal"). While the terminal
|
|
33
41
|
// has the focus the TUI takes no key but the leader (tui.json's open.detachKey), so neither of
|
|
34
42
|
// these is ever read there: the leader's table has its own (LEADER).
|
|
35
|
-
{ id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the shown terminal with the whole screen; the leader
|
|
43
|
+
{ id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the shown terminal with the whole screen; the leader then Esc brings the list back"]] },
|
|
36
44
|
{ id: "close-terminal", keys: ["c"], label: "close terminal", views: [["instances", "close the shown terminal and show its neighbour; the agent keeps running"]] },
|
|
37
45
|
{ id: "tab-previous", keys: ["["], label: "previous tab", views: [["instances", "show the terminal of the tab before the shown one"]] },
|
|
38
46
|
{ id: "tab-next", keys: ["]"], label: "next tab", views: [["instances", "show the terminal of the tab after the shown one"]] },
|
|
@@ -67,8 +75,10 @@ export const ACTIONS = Object.freeze([
|
|
|
67
75
|
* open.detachKey) and what each does, from every focus. Fixed: tui.json's `keys` rebinds the plain
|
|
68
76
|
* keys of ACTIONS only. `does` is an action id of ACTIONS, or one of the leader's own: `previous`
|
|
69
77
|
* and `next` (the instance before or after the shown terminal's, or the selection's: its tab
|
|
70
|
-
* shown, or opened as a new one, with the focus in it) and `list` (the list's focus
|
|
71
|
-
*
|
|
78
|
+
* shown, or opened as a new one, with the focus in it) and `list` (the list's focus, which
|
|
79
|
+
* Esc gives). The leader pressed again is not in this table either, as it is the user's key: from
|
|
80
|
+
* the open terminal's focus it types the leader's own bytes into the agent, the focus staying
|
|
81
|
+
* there, and from any other focus it only closes the hint (lib/store.mjs `twice`). `terminal`: named in the hint only while a terminal
|
|
72
82
|
* is open, and nothing without one (the hint names the tab keys only with two tabs or more). */
|
|
73
83
|
export const LEADER = Object.freeze([
|
|
74
84
|
{ keys: ["k", "space"], does: "palette", label: "palette" },
|
|
@@ -118,3 +128,17 @@ export function keyLabel(key) {
|
|
|
118
128
|
const name = NAMES[last] ?? (/^f\d+$/.test(last) ? last.toUpperCase() : parts.length && last.length === 1 ? last.toUpperCase() : last);
|
|
119
129
|
return [...parts.map((part) => NAMES[part] ?? part), name].join("+");
|
|
120
130
|
}
|
|
131
|
+
|
|
132
|
+
/** The modifiers of the back key's grammar (term/through.mjs BACK_KEY) as a person reads them. */
|
|
133
|
+
const BACK_MODIFIERS = Object.freeze({ C: "Ctrl", M: "Alt", S: "Shift" });
|
|
134
|
+
/** A back key (tui.json's open.detachKey, the leader) as the cheat sheet and the help name it, spelt
|
|
135
|
+
* for people as keyLabel spells a key id: `C-\\` is `Ctrl+\\`, `C-x` is `Ctrl+X`, `M-o` is `Alt+O`,
|
|
136
|
+
* `M-5` is `Alt+5`, `F12` is `F12`, `S-F5` is `Shift+F5`. A letter is written as a capital, which
|
|
137
|
+
* never means Shift (the grammar has lowercase Meta letters only). Pure. A value outside the
|
|
138
|
+
* grammar is answered as it was given (tui.json refuses it; a view draws it as text from outside). */
|
|
139
|
+
export function backKeyLabel(key) {
|
|
140
|
+
if (!isBackKey(key)) return key;
|
|
141
|
+
const [, mod, rest] = /^(?:([CMS])-)?(.+)$/.exec(key);
|
|
142
|
+
const name = rest.length === 1 ? rest.toUpperCase() : rest;
|
|
143
|
+
return mod ? `${BACK_MODIFIERS[mod]}+${name}` : name;
|
|
144
|
+
}
|
|
@@ -9,6 +9,8 @@ import { clientTerms } from "../../client/client-terms.mjs";
|
|
|
9
9
|
export { displayLine, DETAIL_WITHHELD } from "../../client/display-text.mjs";
|
|
10
10
|
export { parseProbeStdout, acceptProbe, cliRecord } from "../../client/cli-locator.mjs";
|
|
11
11
|
export { cliDeploymentRead } from "../../client/deployment-read-cli.mjs";
|
|
12
|
+
export { cliDeploymentList } from "../../client/deployment-list-cli.mjs";
|
|
13
|
+
export { deploymentsListSupported } from "../../client/deployment-list.mjs";
|
|
12
14
|
export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
|
|
13
15
|
export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
|
|
14
16
|
export { createRefreshLoop } from "../../client/refresh-loop.mjs";
|
|
@@ -33,7 +35,7 @@ export { createRetiresInFlight, retiringRows } from "../../client/retire-in-flig
|
|
|
33
35
|
export { startGate, startInstance } from "../../client/session-start.mjs";
|
|
34
36
|
export { retainedStartMessage, launchFlagIgnored, flagIgnoredNotice } from "../../client/launch-prompt-outcome.mjs";
|
|
35
37
|
export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
|
|
36
|
-
export { validateWorkspace
|
|
38
|
+
export { validateWorkspace } from "../../client/workspace-admission.mjs";
|
|
37
39
|
export { createSoulCatalog, soulCatalogKey } from "../../client/soul-catalog.mjs";
|
|
38
40
|
export { soulRows } from "../../client/soul-rows.mjs";
|
|
39
41
|
export { soulFacts, spawnRefusal, soulMatches } from "../../client/soul-facts.mjs";
|
|
@@ -19,9 +19,12 @@ export const CONFIG_LIMIT = 64 * 1024;
|
|
|
19
19
|
const TOO_LARGE = `it is larger than ${CONFIG_LIMIT / 1024} KiB`;
|
|
20
20
|
const NOT_AN_OBJECT = 'it is not one JSON object, like {"keys": {"quit": ["q"]}}';
|
|
21
21
|
const SETTINGS = "the settings are keys, ascii and open";
|
|
22
|
-
/** The back key when tui.json names none
|
|
23
|
-
* back to the list (the setting keeps its
|
|
24
|
-
|
|
22
|
+
/** The back key when tui.json names none, on `platform` (a `process.platform` value): the key that
|
|
23
|
+
* 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). `C-\\` on macOS, whose terminals send
|
|
25
|
+
* Option as Meta only when told to; `M-o` (Alt+O) elsewhere. Both are read as keys no action of
|
|
26
|
+
* ACTIONS holds (`ctrl+\\`, `alt+o`), which the check of the leader below keeps true. */
|
|
27
|
+
export const defaultDetachKey = (platform = process.platform) => (platform === "darwin" ? "C-\\" : "M-o");
|
|
25
28
|
/** An action id this program had and has no more, with what it is called now. */
|
|
26
29
|
const RENAMED = Object.freeze({ "open-workspace": "open" });
|
|
27
30
|
const KEY_IDS = "key ids look like q, ctrl+c, shift+tab, f5, space";
|
|
@@ -33,7 +36,7 @@ const ERROR_CODE = /^[A-Z][A-Z0-9_]{0,30}$/;
|
|
|
33
36
|
export const MAX_PROBLEMS = 20;
|
|
34
37
|
|
|
35
38
|
const plain = (name) => typeof name === "string" && PLAIN_NAME.test(name);
|
|
36
|
-
/** Whether the
|
|
39
|
+
/** Whether the cheat sheet and the help can name a key: its label is drawn as text from outside (the
|
|
37
40
|
* shared display filter), and a label that filter would change would name another key, or none.
|
|
38
41
|
* Such a key (a bidi override, a combining mark on a space) is refused here, with the file named,
|
|
39
42
|
* where a key the views cannot draw would otherwise be bound and never said. */
|
|
@@ -49,9 +52,10 @@ export function configPath(env, home) {
|
|
|
49
52
|
return join(typeof xdg === "string" && xdg !== "" && isAbsolute(xdg) ? xdg : join(home, ".config"), "oats", "tui.json");
|
|
50
53
|
}
|
|
51
54
|
|
|
52
|
-
/** What tui.json says, checked: `value` is the file already parsed, `defaults` the action table
|
|
53
|
-
*
|
|
54
|
-
* `detachKey`
|
|
55
|
+
/** What tui.json says, checked: `value` is the file already parsed, `defaults` the action table,
|
|
56
|
+
* `platform` the one the TUI runs on (a `process.platform` value). Pure. Answers
|
|
57
|
+
* `{ ok: true, actions, ascii, detachKey }` or `{ ok: false, problems }`: `detachKey` is
|
|
58
|
+
* `open.detachKey`, or defaultDetachKey(platform) when the file names none.
|
|
55
59
|
*
|
|
56
60
|
* `actions` is a frozen table shaped exactly like `defaults` (same order, ids and labels, frozen
|
|
57
61
|
* rows with frozen `keys`) in which the list of each action the file names REPLACES that action's
|
|
@@ -63,7 +67,7 @@ export function configPath(env, home) {
|
|
|
63
67
|
* order. A key given to two actions is judged with the kept defaults included and names both. An
|
|
64
68
|
* action whose list is refused takes no part in that judgement: what it was meant to hold is not
|
|
65
69
|
* known. The ids of `defaults` are the program's own; one that is not plain is still never echoed. */
|
|
66
|
-
export function effectiveConfig(value, defaults = ACTIONS) {
|
|
70
|
+
export function effectiveConfig(value, defaults = ACTIONS, platform = process.platform) {
|
|
67
71
|
if (!isObject(value)) return { ok: false, problems: [NOT_AN_OBJECT] };
|
|
68
72
|
for (const [setting, given] of Object.entries(value)) {
|
|
69
73
|
if (setting === "keys") { if (!isObject(given)) return { ok: false, problems: ['keys must be an object, like {"quit": ["q"]}'] }; }
|
|
@@ -106,9 +110,11 @@ export function effectiveConfig(value, defaults = ACTIONS) {
|
|
|
106
110
|
}
|
|
107
111
|
// The leader is read as a key wherever the TUI reads keys (docs/tui.md, "The leader"), so no
|
|
108
112
|
// action may hold the key it reads as: `C-l` would be redraw's Ctrl+L, `C-j` open's Enter.
|
|
109
|
-
const detachKey = value.open?.detachKey ??
|
|
113
|
+
const detachKey = value.open?.detachKey ?? defaultDetachKey(platform), leader = backKeyId(detachKey);
|
|
110
114
|
const taken = defaults.find((action) => (named.get(action.id) ?? action.keys).includes(leader));
|
|
111
|
-
|
|
115
|
+
// A file that names no leader is told it is the default, which it did not write.
|
|
116
|
+
const which = value.open?.detachKey === undefined ? `the default leader ${detachKey}` : `open.detachKey ${detachKey}`;
|
|
117
|
+
if (taken) problems.push(`${which} is read as ${keyLabel(leader)}, the key of ${say(taken.id)}; give the leader a key no action has, or give ${say(taken.id)} another`);
|
|
112
118
|
if (problems.length > 0) return { ok: false, problems };
|
|
113
119
|
|
|
114
120
|
const actions = Object.freeze(defaults.map((action) => Object.freeze({ ...action, keys: Object.freeze([...(named.get(action.id) ?? action.keys)]) })));
|
|
@@ -158,24 +164,25 @@ const NODE_IO = Object.freeze({
|
|
|
158
164
|
/** Read tui.json, once. Answers `{ ok: true, actions, ascii, detachKey, path }`, or
|
|
159
165
|
* `{ ok: false, lines }`: the complete lines to print (no trailing newline), after which the TUI
|
|
160
166
|
* must not start. No file is the defaults: `actions` is ACTIONS itself, `ascii` is false and
|
|
161
|
-
* `detachKey` is
|
|
167
|
+
* `detachKey` is defaultDetachKey(platform); `platform` is the one the TUI runs on (a
|
|
168
|
+
* `process.platform` value, given so the answer is known for each).
|
|
162
169
|
*
|
|
163
170
|
* `io` is the file system (node:fs when omitted): `io.stat(path)` answers `{ file, size }` after
|
|
164
171
|
* following symbolic links, or null when the path does not exist, and throws for anything else;
|
|
165
172
|
* `io.read(path)` answers the text. The size is checked before `read` is called, so a file over
|
|
166
173
|
* CONFIG_LIMIT, a directory or a FIFO is never opened. A line holds the path only when it is
|
|
167
174
|
* printable ASCII, and never the text of an error: only its code, when it is a plain one. */
|
|
168
|
-
export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO } = {}) {
|
|
175
|
+
export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO, platform = process.platform } = {}) {
|
|
169
176
|
const path = configPath(env, home);
|
|
170
177
|
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);
|
|
171
178
|
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)`) });
|
|
172
179
|
let found, text, value;
|
|
173
180
|
try { found = io.stat(path); } catch (error) { return refused([unreadable(error)]); }
|
|
174
|
-
if (found === null) return { ok: true, actions: ACTIONS, ascii: false, detachKey:
|
|
181
|
+
if (found === null) return { ok: true, actions: ACTIONS, ascii: false, detachKey: defaultDetachKey(platform), path };
|
|
175
182
|
if (found.file !== true) return refused(["it is not a regular file"]);
|
|
176
183
|
if (!(typeof found.size === "number" && found.size <= CONFIG_LIMIT)) return refused([TOO_LARGE]); // read only what is known to fit
|
|
177
184
|
try { text = io.read(path); } catch (error) { return refused([error?.code === "EFBIG" ? TOO_LARGE : unreadable(error)]); }
|
|
178
185
|
try { value = JSON.parse(text); } catch { return refused(["it is not valid JSON"]); }
|
|
179
|
-
const checked = effectiveConfig(value);
|
|
186
|
+
const checked = effectiveConfig(value, ACTIONS, platform);
|
|
180
187
|
return checked.ok ? { ...checked, path } : refused(checked.problems);
|
|
181
188
|
}
|
|
@@ -12,11 +12,11 @@
|
|
|
12
12
|
import { homedir } from "node:os";
|
|
13
13
|
import { resolve } from "node:path";
|
|
14
14
|
import { bindings } from "./actions.mjs";
|
|
15
|
-
import { TERMS, capabilityCatalogKey, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, displayLine, heldHome, pendingEntry, prepareRemoteTerm, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
|
|
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
16
|
import { loadConfig } from "./config.mjs";
|
|
17
|
-
import { ACT_WORDS, actContext, actCwd, localDeployments, model, outcomeOf, reachedMachines, roster, spawnContext } from "./model.mjs";
|
|
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,
|
|
19
|
+
import { CHANGE_FILES, admitDeployment, 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";
|
|
@@ -24,7 +24,7 @@ import { createScreen, glyphs } from "./term/screen.mjs";
|
|
|
24
24
|
import { colorEnabled } from "./term/style.mjs";
|
|
25
25
|
import { backKeySequences, createThrough } from "./term/through.mjs";
|
|
26
26
|
import { createGuard, isTerminal } from "./term/tty.mjs";
|
|
27
|
-
import { frame, layout, panelPlace } from "./views/frame.mjs";
|
|
27
|
+
import { frame, layout, mainArea, panelPlace } from "./views/frame.mjs";
|
|
28
28
|
|
|
29
29
|
export const USAGE = "oats tui [--dir <path>] [--ascii]";
|
|
30
30
|
const HELP = `Usage:
|
|
@@ -45,6 +45,10 @@ export const NO_TERMINAL = "oats: `oats tui` needs a terminal on stdin and stdou
|
|
|
45
45
|
/** A path is echoed only when it is plain: these lines go to a terminal. */
|
|
46
46
|
const plainPath = (path) => (typeof path === "string" && /^[\x20-\x7e]{1,200}$/.test(path) ? path : "that directory");
|
|
47
47
|
export const noDeployment = (dir) => `oats: no OATS deployment at or above ${plainPath(dir)} (E_NO_DEPLOYMENT); name one with \`oats tui --dir <path>\``;
|
|
48
|
+
/** A start outside every deployment, with no `--dir`, when this computer's deployments list holds none (awebai/oats#1390). */
|
|
49
|
+
export const noDeploymentListed = (dir) => `oats: no deployment at or above ${plainPath(dir)}, and this computer's list of deployments holds none (E_NO_DEPLOYMENT): \`oats tui --dir <path>\` opens one (and lists it), \`oats onboard <dir> --workspace <ref>\` creates one`;
|
|
50
|
+
/** The same start, when the list could not be read: the kernel's code and its message, which says what to do. */
|
|
51
|
+
export const noList = (reason) => `oats: \`oats tui\` could not read this computer's list of deployments (${/^E_[A-Z0-9_]{1,62}$/.test(reason?.code ?? "") ? reason.code : NOT_ASKED.code}): ${displayLine(reason?.message) ?? "it gave no reason"}`;
|
|
48
52
|
export const noKernel = (reason) => `oats: \`oats tui\` could not use its own kernel (E_TUI_KERNEL): ${displayLine(reason) ?? "it gave no reason"}`;
|
|
49
53
|
|
|
50
54
|
/** The arguments: `--ascii`, `--help`/`-h`, `--dir <path>` and `--dir=<path>`. Everything else is
|
|
@@ -65,6 +69,12 @@ export function parseArgs(argv) {
|
|
|
65
69
|
return { options };
|
|
66
70
|
}
|
|
67
71
|
|
|
72
|
+
/** The label of a change to this computer's deployments list (an add or a remove), for the line after leaving. */
|
|
73
|
+
const LIST_CHANGE = Object.freeze({ verb: "list" });
|
|
74
|
+
/** Why a call to this computer's deployments list has no answer at all: it threw before the kernel
|
|
75
|
+
* could answer. The shared adapter's own code for a kernel call that failed (deployment-list-cli.mjs). */
|
|
76
|
+
const NOT_ASKED = Object.freeze({ code: "E_CLI_FAILED", message: "the kernel could not be asked" });
|
|
77
|
+
|
|
68
78
|
/** An error as lines fit for a terminal: its stack, each line through the display filter. */
|
|
69
79
|
function errorLines(error) {
|
|
70
80
|
const text = error instanceof Error ? error.stack || error.message : String(error);
|
|
@@ -80,8 +90,10 @@ function errorLines(error) {
|
|
|
80
90
|
* catalog of a workspace's souls, and `createCapabilityCatalog` its table of capabilities, each
|
|
81
91
|
* replaceable so a test can count its reads; the three spawn
|
|
82
92
|
* factories are the shared home's preview, apply boundary and transaction, replaceable so a test
|
|
83
|
-
* can answer them.
|
|
84
|
-
|
|
93
|
+
* can answer them. `deploymentList` is the shared cliDeploymentList (this computer's deployments
|
|
94
|
+
* list, through the kernel: awebai/oats#1390), and `startExec` the exec it is handed before the
|
|
95
|
+
* terminal is taken; replaceable so a test can answer the list. */
|
|
96
|
+
const EFFECTS = Object.freeze({ loadConfig, findDeployment, probeKernel, createReader, deploymentList: cliDeploymentList, startExec, admitDeployment, prepareRemoteTerm, createPanel, sweep,
|
|
85
97
|
runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
|
|
86
98
|
createCapabilityCatalog, createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction });
|
|
87
99
|
|
|
@@ -111,7 +123,9 @@ export function createRunTimers({ setTimer, clearTimer }) {
|
|
|
111
123
|
* Before the alternate screen, in this order, each failure one line on stderr and status 1:
|
|
112
124
|
* the arguments; the instance variables removed from the environment (a TUI started in an
|
|
113
125
|
* agent's pane must read the deployment it was asked about, and so must every child it starts);
|
|
114
|
-
* the terminal; the user's tui.json; the deployment; the kernel it shipped with
|
|
126
|
+
* the terminal; the user's tui.json; the deployment; the kernel it shipped with; and, for a start
|
|
127
|
+
* outside every deployment with no `--dir`, this computer's deployments list, read through that
|
|
128
|
+
* kernel. */
|
|
115
129
|
export async function main({ argv, stdin, stdout, stderr, env, proc = process, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout, cwd = () => process.cwd(), home = homedir(), effects: given = EFFECTS }) {
|
|
116
130
|
const effects = given === EFFECTS ? EFFECTS : { ...EFFECTS, ...given };
|
|
117
131
|
const { options, error } = parseArgs(argv);
|
|
@@ -119,16 +133,23 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
119
133
|
if (options.help) { stdout.write(HELP); return 0; }
|
|
120
134
|
leaveInstance(env);
|
|
121
135
|
if (!isTerminal({ stdin, stdout, env })) { stderr.write(`${NO_TERMINAL}\n`); return 1; }
|
|
122
|
-
const config = effects.loadConfig({ env, home });
|
|
136
|
+
const config = effects.loadConfig({ env, home, platform: proc.platform });
|
|
123
137
|
if (!config.ok) { stderr.write(config.lines.map((line) => `${line}\n`).join("")); return 1; }
|
|
124
138
|
const found = effects.findDeployment(resolve(cwd(), options.dir ?? "."));
|
|
125
|
-
//
|
|
126
|
-
|
|
127
|
-
const offered = found.ok || options.dir !== null ? null : effects.offeredDeployments(home, []);
|
|
128
|
-
if (!found.ok && !offered?.offered.length) { stderr.write(`${noDeployment(found.dir)}\n`); return 1; }
|
|
139
|
+
// A `--dir` that is in no deployment is refused as it is: what was asked for is not there.
|
|
140
|
+
if (!found.ok && options.dir !== null) { stderr.write(`${noDeployment(found.dir)}\n`); return 1; }
|
|
129
141
|
// The kernel is asked once: an upgrade under a running TUI is met by starting it again.
|
|
130
142
|
const probe = await effects.probeKernel({ env });
|
|
131
143
|
if (!probe.ok) { stderr.write(`${noKernel(probe.reason)}\n`); return 1; }
|
|
144
|
+
// Outside every deployment, and with none named: the switcher, when this computer's deployments
|
|
145
|
+
// list holds a row, read through the kernel just asked. A list that cannot be read is no empty one.
|
|
146
|
+
let listedAtStart = null;
|
|
147
|
+
if (!found.ok) {
|
|
148
|
+
const listed = await effects.deploymentList(probe.cli, { action: "list" }, { exec: effects.startExec, env });
|
|
149
|
+
if (!listed.ok) { stderr.write(`${noList(listed.reason)}\n`); return 1; }
|
|
150
|
+
if (!listed.value.rows.length) { stderr.write(`${noDeploymentListed(found.dir)}\n`); return 1; }
|
|
151
|
+
listedAtStart = listed.value.rows;
|
|
152
|
+
}
|
|
132
153
|
|
|
133
154
|
const clock = () => new Date(now()).toISOString();
|
|
134
155
|
const look = glyphs(env, { ascii: options.ascii || config.ascii });
|
|
@@ -141,16 +162,18 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
141
162
|
// takes the focus, so nothing held from before is typed into it.
|
|
142
163
|
const backKey = backKeySequences(state.detachKey);
|
|
143
164
|
let through = createThrough({ sequences: backKey, now }), throughTimer = null;
|
|
144
|
-
if (
|
|
165
|
+
if (listedAtStart) state = reduce(state, { listed: { rows: listedAtStart } }, keymap).state;
|
|
145
166
|
// What the last frame drew, for the store: how tall the list pane is and how far the other
|
|
146
167
|
// pane scrolls. The store holds no size of its own; the panel's room goes with each key as it
|
|
147
168
|
// is when the key is read (placed), whatever the last frame drew.
|
|
148
|
-
let drawn = { page: 1, extent: 0, room: 1, cols: 1 };
|
|
169
|
+
let drawn = { page: 1, extent: 0, room: 1, cols: 1, area: 1 };
|
|
149
170
|
let full = true, escTimer = null, ended = false, reads = 0;
|
|
150
171
|
/** The preflight of another machine's agent under way: `{ id, controller, prepared }`, where
|
|
151
172
|
* `prepared` is what it answered (`{ binary, args }`) once it has; or null. */
|
|
152
173
|
let preflight = null;
|
|
153
|
-
/** The run's private directory, made at the first change
|
|
174
|
+
/** The run's private directory, made at the first change (with a kernel that lists this
|
|
175
|
+
* computer's deployments, the add of the deployment the run started in, at the start) or the
|
|
176
|
+
* first open (lib/read.mjs
|
|
154
177
|
* CHANGE_FILES): the reader writes a change's output there, and the panel keeps its tmux
|
|
155
178
|
* server's socket there. */
|
|
156
179
|
let dir = null;
|
|
@@ -379,8 +402,9 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
379
402
|
});
|
|
380
403
|
}
|
|
381
404
|
/** One step of the reducer taken: the state, then what only the loop can do. True once the
|
|
382
|
-
* TUI is leaving.
|
|
383
|
-
*
|
|
405
|
+
* TUI is leaving. Asking whether a picked row is a deployment reads the file system
|
|
406
|
+
* (lib/read.mjs), and reading or changing this computer's deployments list asks the kernel; what
|
|
407
|
+
* each finds is an event of its own. */
|
|
384
408
|
function took(step) {
|
|
385
409
|
state = step.state;
|
|
386
410
|
const effect = step.effect;
|
|
@@ -388,7 +412,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
388
412
|
if (effect === "suspend") guard.suspend();
|
|
389
413
|
if (effect === "redraw") guard.reassert(); // the modes again, then the whole screen
|
|
390
414
|
if (effect === null || typeof effect !== "object") return false;
|
|
391
|
-
if (effect.
|
|
415
|
+
if (effect.list) readList();
|
|
416
|
+
if (effect.remove) removeListed(effect.remove);
|
|
392
417
|
if (effect.admit !== undefined) {
|
|
393
418
|
const admitted = effects.admitDeployment(effect.admit);
|
|
394
419
|
took(reduce(state, admitted.ok ? { admitted: admitted.deployment, at: clock() } : { refused: effect.admit }, keymap));
|
|
@@ -402,6 +427,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
402
427
|
preflight = null;
|
|
403
428
|
if (ready?.id === effect.panel && ready.prepared) view(effect.panel, ready.prepared.binary, ready.prepared.args);
|
|
404
429
|
}
|
|
430
|
+
// The leader twice from the terminal's focus: its own bytes to the agent, as what is typed goes.
|
|
431
|
+
if (effect.input) { if (keysReady()) panel.input(effect.input); }
|
|
405
432
|
if (effect.dismiss !== undefined) dismiss(effect.dismiss);
|
|
406
433
|
if (effect.act) openConfirmation(effect.act);
|
|
407
434
|
if (effect.call) callConfirmation(effect.call);
|
|
@@ -417,6 +444,49 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
417
444
|
return false;
|
|
418
445
|
}
|
|
419
446
|
|
|
447
|
+
// THIS COMPUTER'S DEPLOYMENTS LIST (docs/tui.md, "The switcher"; awebai/oats#1390), the kernel's,
|
|
448
|
+
// through the shared cliDeploymentList. A read of it is a read (the reader's exec, ended on every
|
|
449
|
+
// way out), and one runs at a time: a read asked for while one is on its way is one more, after
|
|
450
|
+
// it, however many times it was asked, and the answer of the one on its way is not taken, since
|
|
451
|
+
// it may be of the list as it was before what asked again (a Remove). An add or a remove is a
|
|
452
|
+
// change (the reader's changeExec: never ended by the TUI, only at the adapter's own deadline),
|
|
453
|
+
// labelled so the line after leaving names the list. The kernel this TUI shipped with lists
|
|
454
|
+
// this computer's deployments in every release; one that does not (a checkout between the
|
|
455
|
+
// kernel's change and this one) is asked nothing in the run, and its "Update oats" is not said
|
|
456
|
+
// of the TUI's own kernel.
|
|
457
|
+
const listing = deploymentsListSupported(probe.cli);
|
|
458
|
+
/** The read on its way: `{ again }`, `again` once another was asked for meanwhile; or null. */
|
|
459
|
+
let listRead = null;
|
|
460
|
+
const listChange = (bin, argv, options, callback) => reader.changeExec(bin, argv, { ...options, label: LIST_CHANGE }, callback);
|
|
461
|
+
function readList() {
|
|
462
|
+
if (ended || !listing) return;
|
|
463
|
+
if (listRead !== null) { listRead.again = true; return; }
|
|
464
|
+
const mine = listRead = { again: false };
|
|
465
|
+
Promise.resolve()
|
|
466
|
+
.then(() => effects.deploymentList(probe.cli, { action: "list" }, { exec: reader.exec, env }))
|
|
467
|
+
.then((answer) => (answer.ok ? { rows: answer.value.rows } : { failure: answer.reason }), () => ({ failure: NOT_ASKED }))
|
|
468
|
+
.then((listed) => {
|
|
469
|
+
listRead = null;
|
|
470
|
+
if (mine.again) readList(); else heard({ listed });
|
|
471
|
+
});
|
|
472
|
+
}
|
|
473
|
+
/** Remove the row the store asked about (`{ path, name }`) from the list: nothing on disk is
|
|
474
|
+
* touched. Its answer goes to the store, which asks for the list again. */
|
|
475
|
+
function removeListed({ path, name }) {
|
|
476
|
+
Promise.resolve()
|
|
477
|
+
.then(() => effects.deploymentList(probe.cli, { action: "remove", path }, { exec: listChange, env }))
|
|
478
|
+
.then((answer) => heard({ removed: { path, name, ok: answer.ok, reason: answer.ok ? null : answer.reason } }), () => heard({ removed: { path, name, ok: false, reason: NOT_ASKED } }));
|
|
479
|
+
}
|
|
480
|
+
/** The deployment the run started in (from where it was started, or `--dir`), added to the list
|
|
481
|
+
* once, as the TUI's: best effort. A failure opens nothing less, and is said once, in the line
|
|
482
|
+
* under the sidebar's title. A row opened from the switcher is on the list already. */
|
|
483
|
+
function listStart(path) {
|
|
484
|
+
if (!listing) return;
|
|
485
|
+
Promise.resolve()
|
|
486
|
+
.then(() => effects.deploymentList(probe.cli, { action: "add", path, via: "tui" }, { exec: listChange, env }))
|
|
487
|
+
.then((answer) => { if (!answer.ok) heard({ notListed: answer.reason }); }, () => heard({ notListed: NOT_ASKED }));
|
|
488
|
+
}
|
|
489
|
+
|
|
420
490
|
/** What the boundary admits a request of deployment `id` against, read at every admission. */
|
|
421
491
|
const contextOf = (id) => actContext(state, id, clock());
|
|
422
492
|
/** Open the shared confirmation of a stop or a retire the store decided on (`{ n, verb, row,
|
|
@@ -558,20 +628,26 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
558
628
|
if (keys !== null && keys !== keysTo) { panel.focus(keys); keysTo = keys; }
|
|
559
629
|
}
|
|
560
630
|
/** The frame for the state now, with what the loop needs of it: the layout first, because the
|
|
561
|
-
* model's window is as tall, and its sentences as wide, as the list
|
|
562
|
-
*
|
|
563
|
-
*
|
|
631
|
+
* model's window is as tall, and its sentences as wide, as the sidebar's list it gives, and an
|
|
632
|
+
* overlay's window as tall as the area it gives (`body`). The open view of the sidebar is the
|
|
633
|
+
* one under the help or a confirmation; the switcher opens none and has no notice of a
|
|
634
|
+
* deployment. The last captures of the displayed tabs go with the model: they are the panel's,
|
|
635
|
+
* not the store's. */
|
|
564
636
|
function composed() {
|
|
565
|
-
const { size, g, m } = modelled();
|
|
566
|
-
return { size, g, made: frame(m, size) };
|
|
637
|
+
const { size, g, m, area } = modelled();
|
|
638
|
+
return { size, g, area, made: frame(m, size) };
|
|
567
639
|
}
|
|
640
|
+
/** The model for the state and the size now, and the width of the main area (`area`,
|
|
641
|
+
* views/frame.mjs mainArea), which the switcher stands in: the lines above its choices wrap to it. */
|
|
568
642
|
function modelled() {
|
|
569
643
|
const size = guard.size(), at = clock();
|
|
570
|
-
const
|
|
571
|
-
const
|
|
572
|
-
const
|
|
573
|
-
const
|
|
574
|
-
|
|
644
|
+
const under = state.view === "help" || state.view === "act" ? state.back : state.view;
|
|
645
|
+
const listing = under === "switcher";
|
|
646
|
+
const r = listing ? { notice: null, note: null } : roster(state, at);
|
|
647
|
+
const g = layout(r.notice, size, { note: r.note, ascii: state.ascii, outcome: listing ? null : outcomeOf(state), terminal: state.tabs.length > 0, open: listing ? null : under });
|
|
648
|
+
const area = mainArea(g, size.cols).cols;
|
|
649
|
+
const m = { ...model(state, { page: g.page, body: g.body, now: now(), at, cols: g.listCols, area }), screen: screens.get(state.terminal?.id) ?? null, screens };
|
|
650
|
+
return { size, g, m, area };
|
|
575
651
|
}
|
|
576
652
|
/** Where the panel stands for the state and the size now, as the Instances view gives it with
|
|
577
653
|
* the terminal's focus (views/frame.mjs panelPlace): measured whatever is drawn over it, and
|
|
@@ -620,8 +696,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
620
696
|
const guard = createGuard({
|
|
621
697
|
stdin, stdout, proc, setTimer, clearTimer,
|
|
622
698
|
frame() {
|
|
623
|
-
const { size, g, made } = composed();
|
|
624
|
-
drawn = { page: made.page, extent: made.extent, room: made.room, cols: g.listCols };
|
|
699
|
+
const { size, g, area, made } = composed();
|
|
700
|
+
drawn = { page: made.page, extent: made.extent, room: made.room, cols: g.listCols, area };
|
|
625
701
|
fitPanel(made);
|
|
626
702
|
const bytes = screen.render(made.rows, size, { full, cursor: made.cursor });
|
|
627
703
|
full = false;
|
|
@@ -696,6 +772,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
696
772
|
|
|
697
773
|
guard.start();
|
|
698
774
|
guard.attempt(() => { if (!ended) Promise.resolve(reader.start()).catch(() => {}); });
|
|
775
|
+
if (found.ok) guard.attempt(() => { if (!ended) listStart(found.deployment); });
|
|
699
776
|
guard.attempt(() => guard.draw());
|
|
700
777
|
// Once a run, after the first frame: what runs that are gone left of their private servers
|
|
701
778
|
// (lib/panel.mjs sweep, which signals nothing and removes only what it can prove is dead).
|
|
@@ -707,7 +784,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
707
784
|
// One line per change still running, to a terminal or a file only; the status never depends on it.
|
|
708
785
|
const running = reader.changes?.() ?? [];
|
|
709
786
|
if (running.length && effects.tellable(stderr)) {
|
|
710
|
-
try { stderr.write(running.map(({ label }) => `${ACT_WORDS.leaving(label?.verb ?? "change", displayLine(label?.name) ?? "an instance")}\n`).join("")); } catch { /* nothing to tell it to */ }
|
|
787
|
+
try { stderr.write(running.map(({ label }) => `${label === LIST_CHANGE ? LIST_WORDS.leaving : ACT_WORDS.leaving(label?.verb ?? "change", displayLine(label?.name) ?? "an instance")}\n`).join("")); } catch { /* nothing to tell it to */ }
|
|
711
788
|
}
|
|
712
789
|
if (end.error !== undefined) stderr.write(`oats: \`oats tui\` stopped on an internal error; the terminal was restored\n${errorLines(end.error).map((line) => ` ${line}\n`).join("")}`);
|
|
713
790
|
return end.status;
|