@awebai/oats 0.55.1 → 0.57.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/bin/oats.mjs +96 -72
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +375 -37
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +65 -11
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +153 -11
- package/docs/integrations.md +5 -3
- package/docs/knowledge.md +117 -43
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +134 -19
- package/docs/tui.md +215 -31
- package/docs/upgrading.md +4 -1
- package/docs/workspaces.md +26 -6
- package/lib/automations.mjs +3 -4
- package/lib/bounded-read.mjs +18 -0
- package/lib/capability-show.mjs +13 -2
- package/lib/claim.mjs +3 -4
- package/lib/core.mjs +919 -278
- package/lib/errors.mjs +39 -0
- package/lib/harness-trust-write.mjs +119 -40
- package/lib/harness-trust.mjs +31 -18
- package/lib/instance-inspect.mjs +160 -11
- package/lib/instance-lifecycle.mjs +90 -37
- package/lib/packages.mjs +8 -5
- package/lib/pi-bridge.mjs +18 -19
- package/lib/remote.mjs +88 -51
- package/lib/retire-output.mjs +9 -4
- package/lib/schedule.mjs +3 -4
- package/lib/servers.mjs +39 -6
- package/lib/session-viewer.mjs +25 -1
- package/lib/triggers.mjs +3 -4
- package/lib/workspace.mjs +6 -6
- package/lib/worktree.mjs +33 -8
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +108 -13
- package/packages/client/cli-locator.mjs +16 -14
- package/packages/client/deployment-panel.mjs +4 -3
- package/packages/client/display-text.mjs +2 -1
- package/packages/client/instance-events-contract.mjs +4 -3
- package/packages/client/instance-lifecycle.mjs +235 -0
- package/packages/client/instance-presentation.mjs +9 -0
- package/packages/client/instance-tree.mjs +10 -8
- package/packages/client/kernel-lines.mjs +3 -3
- package/packages/client/launch-contract.mjs +11 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/lifecycle-cli.mjs +12 -6
- package/packages/client/lifecycle-confirmation.mjs +407 -0
- package/packages/client/lifecycle-contract.mjs +6 -2
- package/packages/client/own-codes.mjs +1 -0
- package/packages/client/panel-views.mjs +39 -2
- package/packages/client/readiness-contract.mjs +2 -2
- package/packages/client/remote-roster.mjs +50 -5
- package/packages/client/roster-sections.mjs +3 -3
- package/packages/client/session-start.mjs +98 -0
- package/packages/client/start-gate.mjs +46 -0
- package/packages/client/start-messages.mjs +17 -0
- package/packages/client/workspace-views.mjs +2 -2
- package/packages/tui/README.md +21 -8
- package/packages/tui/lib/actions.mjs +11 -2
- package/packages/tui/lib/client.mjs +9 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +168 -20
- package/packages/tui/lib/model.mjs +315 -13
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +171 -16
- package/packages/tui/lib/store.mjs +171 -10
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +145 -33
- package/packages/tui/lib/views/help.mjs +46 -11
- package/skills/oats-getting-started/SKILL.md +6 -3
|
@@ -2,6 +2,7 @@ import { harnessOf } from "./harness-names.mjs";
|
|
|
2
2
|
import { unsupportedSession, unsupportedSessionOrigin, hasRuntimeError } from "./instance-presentation.mjs";
|
|
3
3
|
import { madeByKernel } from "./kernel-made.mjs";
|
|
4
4
|
import { waitingOnYouData } from "./waiting-on-you.mjs";
|
|
5
|
+
import { readIdentity } from "./workspace-views.mjs";
|
|
5
6
|
/** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
|
|
6
7
|
export function remoteWorkspace(group) {
|
|
7
8
|
return {
|
|
@@ -97,10 +98,11 @@ const rosterError = (message) => ({ code: "E_REMOTE_ROSTER", message });
|
|
|
97
98
|
* previous: { remoteGroups, rosterAnswered, rosterFailure }
|
|
98
99
|
* outcome: { gated: true } no accepted CLI, or one that does not read other machines
|
|
99
100
|
* (panel-views.mjs `cliReadsRemotes`): the read was not made
|
|
100
|
-
* | { envelope }
|
|
101
|
+
* | { envelope, asked? } what the CLI answered (cli-adapter.mjs `cliRemoteRoster`); `asked`
|
|
102
|
+
* when the read passed workspace keys (#1124): { keys, keyOf }
|
|
101
103
|
* | { thrown: string } the read failed: the message of what was thrown
|
|
102
104
|
* at: the caller's time, the one `remotePanel` stamps
|
|
103
|
-
* -> { remoteGroups, rosterAnswered, rosterFailure, reported }
|
|
105
|
+
* -> { remoteGroups, rosterAnswered, rosterFailure, reported, kept? }
|
|
104
106
|
*
|
|
105
107
|
* `remoteGroups` is the last readable roster: an answer replaces it only when every group of it can be
|
|
106
108
|
* projected (`remotePanel`), and a failed read keeps the groups held, each marked not reached
|
|
@@ -108,6 +110,15 @@ const rosterError = (message) => ({ code: "E_REMOTE_ROSTER", message });
|
|
|
108
110
|
* sentence, kept only while none has. `reported` is what the client hands to its memory of identities
|
|
109
111
|
* (remote-identity-memory.mjs `observeIdentities`): the groups of an `ok` envelope, else null.
|
|
110
112
|
*
|
|
113
|
+
* An answer read with workspace keys (`asked`) holds only the groups the kernel probed: those registered
|
|
114
|
+
* for one of `keys`, those of unknown workspace and those known only from saved routes. It replaces
|
|
115
|
+
* those. A held registered group it does not list, and whose last-known key (`keyOf(group)`:
|
|
116
|
+
* `lastKnownKey`) is one the read did not ask for, was not probed: it is kept as it was last read, after the answer's
|
|
117
|
+
* groups, and named in `kept` (its id, in order), so the caller keeps its read time (`keptReadTimes`).
|
|
118
|
+
* A held group whose key is unknown, or is one of `keys`, or that is known only from saved routes
|
|
119
|
+
* (`registrationPresent` false: the kernel always probes those), and that the answer does not list is
|
|
120
|
+
* gone, as after any answer. `reported` then holds the kept groups too, so the memory keeps their identities.
|
|
121
|
+
*
|
|
111
122
|
* The sentence of a thrown read carries the message of an error from outside the client: a client
|
|
112
123
|
* shows it through `displayLine` (display-text.mjs) only.
|
|
113
124
|
*
|
|
@@ -130,6 +141,17 @@ export function remoteRosterState(previous, outcome, at) {
|
|
|
130
141
|
const incoming = env.ok && Array.isArray(env.result?.groups)
|
|
131
142
|
? env.result.groups : unavailableGroups(previous.remoteGroups, env.error || rosterError(ROSTER_UNAVAILABLE));
|
|
132
143
|
for (const group of incoming) remotePanel(group, at); // validate before replacing the last readable roster
|
|
144
|
+
if (env.ok && outcome.asked) {
|
|
145
|
+
const listed = new Set(incoming.map((g) => g?.id)), keys = new Set(outcome.asked.keys);
|
|
146
|
+
// Only a registered group can be outside the read: one known only from saved routes is always probed.
|
|
147
|
+
const kept = previous.remoteGroups.filter((g) => {
|
|
148
|
+
if (listed.has(g.id) || g.registrationPresent !== true) return false;
|
|
149
|
+
const key = outcome.asked.keyOf(g);
|
|
150
|
+
return key !== null && !keys.has(key);
|
|
151
|
+
});
|
|
152
|
+
const groups = [...incoming, ...kept];
|
|
153
|
+
return { remoteGroups: groups, rosterAnswered: true, rosterFailure: null, reported: groups, kept: kept.map((g) => g.id) };
|
|
154
|
+
}
|
|
133
155
|
if (env.ok) return { remoteGroups: incoming, rosterAnswered: true, rosterFailure: null, reported: incoming };
|
|
134
156
|
return { remoteGroups: incoming, rosterAnswered: previous.rosterAnswered,
|
|
135
157
|
rosterFailure: previous.rosterAnswered ? previous.rosterFailure : env.error?.message || ROSTER_UNAVAILABLE, reported: null };
|
|
@@ -139,10 +161,33 @@ export function remoteRosterState(previous, outcome, at) {
|
|
|
139
161
|
}
|
|
140
162
|
}
|
|
141
163
|
|
|
142
|
-
/** The panel of each group, keyed as a client's snapshot keys it: [[`remote:<group id>`, panel], …], every one made at `at
|
|
143
|
-
|
|
164
|
+
/** The panel of each group, keyed as a client's snapshot keys it: [[`remote:<group id>`, panel], …], every one made at `at`,
|
|
165
|
+
* except a group kept from an earlier read (`readAt`, a Map of group id → its read time: `keptReadTimes`), which is
|
|
166
|
+
* stamped with the time it was read: a read that did not probe it never makes it look newer. */
|
|
167
|
+
export function remotePanelEntries(remoteGroups, at, readAt = null) {
|
|
144
168
|
requireTime(at, "remotePanelEntries");
|
|
145
|
-
return remoteGroups.map((group) => { const panel = remotePanel(group, at); return [panel.workspace.id, panel]; });
|
|
169
|
+
return remoteGroups.map((group) => { const panel = remotePanel(group, readAt?.get(group.id) ?? at); return [panel.workspace.id, panel]; });
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** The workspace key a held group was last known by (#1124): the key its last reached read reported,
|
|
173
|
+
* else the one remembered for it (`remembered.get`, remote-identity-memory.mjs `identityMemory`), else
|
|
174
|
+
* null: unknown. Any reported key counts, member-derived included: a registration records the key the
|
|
175
|
+
* host reports, whatever its `keyFrom`. */
|
|
176
|
+
export function lastKnownKey(group, remembered) {
|
|
177
|
+
const reported = group?.probe?.ok === true ? readIdentity(group.workspace) : { status: "none" };
|
|
178
|
+
if (reported.status === "identity") return typeof reported.identity.key === "string" ? reported.identity.key : null;
|
|
179
|
+
const key = remembered?.get(group?.id)?.workspace?.key;
|
|
180
|
+
return typeof key === "string" ? key : null;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/** The read time of each kept group after one outcome (#1124): `times` is the Map held before it,
|
|
184
|
+
* `state` what `remoteRosterState` answered, `answeredAt` the time of the answer before this one (when a
|
|
185
|
+
* group first kept was last read). Only an answer changes it: a kept group keeps its time, or takes
|
|
186
|
+
* `answeredAt` when it was read by that answer; a group read now has none. A failed read, which marks
|
|
187
|
+
* every held group not reached, changes nothing; a gated one holds no group. */
|
|
188
|
+
export function keptReadTimes(times, state, answeredAt) {
|
|
189
|
+
if (!state.reported) return state.remoteGroups.length ? times : new Map();
|
|
190
|
+
return new Map((state.kept || []).map((id) => [id, times.get(id) ?? answeredAt]));
|
|
146
191
|
}
|
|
147
192
|
|
|
148
193
|
export function spawnedWorkspace(groups, result) {
|
|
@@ -19,10 +19,10 @@ export const primaryDeployment = deployments => (Array.isArray(deployments) && (
|
|
|
19
19
|
|
|
20
20
|
/** A deployment's state, in words (never colour alone): `{ key, text, detail }`.
|
|
21
21
|
* live: reached (or, on this computer, observed) now. stale: this computer's deployment whose last
|
|
22
|
-
* re-read failed
|
|
23
|
-
* last report. not reached / not observed: with why. */
|
|
22
|
+
* re-read failed, or a machine the last roster read did not ask for (#1124): its rows are the last
|
|
23
|
+
* observation. remembered: not reached, its workspace is the last report. not reached / not observed: with why. */
|
|
24
24
|
export function deploymentState(d) {
|
|
25
|
-
//
|
|
25
|
+
// Its rows are the last observation: a failed re-read here, or a machine outside a filtered roster read.
|
|
26
26
|
if (d?.stale) return { key: 'stale', text: 'stale', detail: d.reason || '' };
|
|
27
27
|
if (d?.reachable) return { key: 'live', text: 'live', detail: '' };
|
|
28
28
|
if (d?.identityFrom === 'remembered') {
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/** The start and restart rule of an existing instance (#855, 5a-2): whether a row can be started now
|
|
2
|
+
* (`startGate`), the home a local start launches in (`verifiedLocalHome`), and the start itself
|
|
3
|
+
* (`startInstance`). A client decides through these and words nothing of its own for them, except the codes
|
|
4
|
+
* the rule leaves to it (below). Every function that words a sentence takes the client's `terms`
|
|
5
|
+
* (client-terms.mjs) and refuses a call without them. No state.
|
|
6
|
+
*
|
|
7
|
+
* A failed start is one of two outcomes, and the words are "nothing was started", never "nothing happened"
|
|
8
|
+
* (a restart that lost the race has already run its own stop, and a start may have written its pending receipt):
|
|
9
|
+
* refused this request started nothing: every refusal of the gate and of the home check, and the
|
|
10
|
+
* kernel's STARTED_NOTHING_CODES;
|
|
11
|
+
* uncertain anything else: no envelope, any other code, and E_START_UNCONFIRMED, the end of the wait
|
|
12
|
+
* for a start that goes on (cli-adapter.mjs cliStart: no deadline, START_WAIT_MS). That code
|
|
13
|
+
* carries no sentence: each client words it (the Desktop: renderer/start-unconfirmed.mjs).
|
|
14
|
+
* After any failed start, refused or uncertain, the client reads the row again before it offers anything. */
|
|
15
|
+
import { basename, dirname, sep } from 'node:path';
|
|
16
|
+
import { cliStart } from './cli-adapter.mjs';
|
|
17
|
+
import { harnessFlag } from './harness-names.mjs';
|
|
18
|
+
import { startGate } from './start-gate.mjs';
|
|
19
|
+
import { retainedSpawnDetails } from './launch-prompt-outcome.mjs';
|
|
20
|
+
import { displayLine } from './display-text.mjs';
|
|
21
|
+
import { requireTerms } from './client-terms.mjs';
|
|
22
|
+
|
|
23
|
+
/** The gate is page-safe and lives apart (start-gate.mjs); a client takes it from here, with the rest of the rule. */
|
|
24
|
+
export { startGate };
|
|
25
|
+
|
|
26
|
+
/** The kernel's codes for a start that started nothing: the home's start lock is held, or an earlier start's
|
|
27
|
+
* pane is still a shell without its completion marker (E_SESSION_START_BUSY); the instance was seen running,
|
|
28
|
+
* or its window appeared during the start (E_SESSION_RUNNING). Some places that raise E_SESSION_RUNNING come
|
|
29
|
+
* after the kernel has written the start's pending receipt, or after a restart's stop: nothing was started,
|
|
30
|
+
* not nothing happened. A code joins only when every place the kernel raises it in a start launches nothing. */
|
|
31
|
+
export const STARTED_NOTHING_CODES = Object.freeze(['E_SESSION_START_BUSY', 'E_SESSION_RUNNING']);
|
|
32
|
+
|
|
33
|
+
/** The two kernel codes' own sentences, for a client that words by code. The kernel's message is the
|
|
34
|
+
* answer's `detail`, through the display filter. E_SESSION_START_BUSY says no more than busy: the kernel answers
|
|
35
|
+
* it for a start lock that is there, which a start that ended without removing it leaves behind too. */
|
|
36
|
+
const STARTED_NOTHING = Object.freeze({
|
|
37
|
+
E_SESSION_START_BUSY: 'OATS refused this start as busy. Nothing was started.',
|
|
38
|
+
E_SESSION_RUNNING: 'This instance is already running. Nothing was started.',
|
|
39
|
+
});
|
|
40
|
+
const CLI_FAILED = 'The start could not be confirmed: the call to the OATS CLI failed. Refresh its status before starting it again.';
|
|
41
|
+
|
|
42
|
+
/** The home a local start launches in, or null. It is DERIVED and VERIFIED, never trusted from roster data
|
|
43
|
+
* alone: the exact home the kernel's status reported for this row in one of `deployments` (`[{ id, remote,
|
|
44
|
+
* instances }]`: a deployment's directory and the rows it reported), canonicalizing to …/instances/<name>
|
|
45
|
+
* inside that deployment's canonical directory. `realpath` is the caller's; this reads no file system of its
|
|
46
|
+
* own. A server's row has no local home. */
|
|
47
|
+
export function verifiedLocalHome(row, deployments, realpath) {
|
|
48
|
+
if (!row?.home || typeof row.home !== 'string' || row.server) return null;
|
|
49
|
+
let real;
|
|
50
|
+
try { real = realpath(row.home); } catch { return null; }
|
|
51
|
+
if (basename(real) !== String(row.instance) || basename(dirname(real)) !== 'instances') return null;
|
|
52
|
+
for (const w of deployments || []) {
|
|
53
|
+
if (w.remote) continue;
|
|
54
|
+
if (!(w.instances || []).some(i => !i.server && i.instance === row.instance && i.home === row.home)) continue;
|
|
55
|
+
let scope;
|
|
56
|
+
try { scope = realpath(w.id); } catch { continue; }
|
|
57
|
+
if (real.startsWith(scope.endsWith(sep) ? scope : scope + sep)) return real;
|
|
58
|
+
}
|
|
59
|
+
return null;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Start or restart one row.
|
|
63
|
+
* choices { model, launchConfig, harness, yolo }: the launch choices, each one argv value
|
|
64
|
+
* restart a restart (the kernel's one call, never a stop then a start)
|
|
65
|
+
* localCwd where a server's start runs from (this machine's own directory)
|
|
66
|
+
* verifyHome(row) -> canonical home | null the caller's local home check; default verifiedLocalHome over
|
|
67
|
+
* `deployments` and `realpath`
|
|
68
|
+
* start the CLI call (cli-adapter.mjs cliStart, with its own session and its wait); `exec`, `after` and
|
|
69
|
+
* `wait` pass to it
|
|
70
|
+
* -> { ok: true, result } | { ok: false, outcome, code, sentence, detail, ran, incomplete? }
|
|
71
|
+
* `ran`: whether the CLI was called (E_CLI_FAILED: the call was made and failed; whether the CLI began is not
|
|
72
|
+
* known). `sentence` is null for a code the client words (E_START_UNCONFIRMED) and
|
|
73
|
+
* for one it does not know: it then shows `detail`, the kernel's message through the display filter.
|
|
74
|
+
* `incomplete`: a start that stopped at a launch prompt (E_SPAWN_INCOMPLETE) and names this row, decoded. */
|
|
75
|
+
export async function startInstance(cli, row, choices = {}, { restart = false, deployments = [], realpath, localCwd, verifyHome, start = cliStart, exec, after, wait, terms } = {}) {
|
|
76
|
+
requireTerms(terms, 'startInstance');
|
|
77
|
+
const refused = (code, sentence, more = {}) => ({ ok: false, outcome: 'refused', code, sentence, detail: null, ran: false, ...more });
|
|
78
|
+
const gate = startGate(cli, row, { restart, choices }, terms);
|
|
79
|
+
if (gate) return refused(gate.code, gate.sentence, gate.detail ? { detail: gate.detail } : {});
|
|
80
|
+
const local = !row.server;
|
|
81
|
+
if (local && !(verifyHome ? verifyHome(row) : verifiedLocalHome(row, deployments, realpath)))
|
|
82
|
+
return refused('E_HOME_UNVERIFIED', 'Instance home is outside the workspace instances layout');
|
|
83
|
+
let envelope;
|
|
84
|
+
// A call that could not be made, or failed on its way (an exec that throws, a rejected call), is uncertain like
|
|
85
|
+
// any answer this cannot read: the CLI may have begun the start. Its words are the rule's; the exception's text
|
|
86
|
+
// is no kernel's message, and is not passed on as `detail`.
|
|
87
|
+
try { envelope = await start(cli.bin, { home: row.home, model: choices.model, launchConfig: choices.launchConfig, harness: choices.harness,
|
|
88
|
+
harnessFlag: harnessFlag(cli), yolo: choices.yolo, restart, workspaceDir: local ? dirname(row.agentsRoot) : localCwd, server: row.server },
|
|
89
|
+
{ ...(exec ? { exec } : {}), ...(after ? { after } : {}), ...(wait !== undefined ? { wait } : {}) }); }
|
|
90
|
+
catch { return { ok: false, outcome: 'uncertain', code: 'E_CLI_FAILED', sentence: CLI_FAILED, detail: null, ran: true }; }
|
|
91
|
+
if (envelope?.ok === true) return { ok: true, result: envelope.result };
|
|
92
|
+
const code = typeof envelope?.error?.code === 'string' ? envelope.error.code : 'E_CLI_PROTOCOL';
|
|
93
|
+
const detail = displayLine(envelope?.error?.message);
|
|
94
|
+
const kept = code === 'E_SPAWN_INCOMPLETE' ? retainedSpawnDetails(envelope.error.details) : null;
|
|
95
|
+
return { ok: false, outcome: STARTED_NOTHING_CODES.includes(code) ? 'refused' : 'uncertain', code,
|
|
96
|
+
sentence: Object.hasOwn(STARTED_NOTHING, code) ? STARTED_NOTHING[code] : null, detail, ran: true,
|
|
97
|
+
...(kept?.launchPrompts && kept.instance === row.instance ? { incomplete: kept } : {}) };
|
|
98
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/** The start rule's gate (#855, 5a-2): whether a row can be started, or restarted, now. Its own module, apart from
|
|
2
|
+
* session-start.mjs (which re-exports it, and is where a client takes it from), because the Desktop's page decides
|
|
3
|
+
* by it too and a page loads no Node builtin: this module imports none, and none of its imports does
|
|
4
|
+
* (packages/desktop/test/inventory.test.mjs). Every sentence takes the client's `terms`. No state. */
|
|
5
|
+
import { canAddressRemote, unaddressableSentence } from './remote-address.mjs';
|
|
6
|
+
import { displayLine } from './display-text.mjs';
|
|
7
|
+
import { requireTerms } from './client-terms.mjs';
|
|
8
|
+
|
|
9
|
+
const STATE_UNKNOWN = 'Could not verify whether this instance is running. Refresh its status before starting.';
|
|
10
|
+
const has = (list, name) => Array.isArray(list) && list.includes(name);
|
|
11
|
+
|
|
12
|
+
/** Why this row cannot be started (or restarted) now, or null. The first rule that applies, in this order:
|
|
13
|
+
* 1 `not-in-roster` the caller holds no such row (it passes the current row, or null);
|
|
14
|
+
* 2 `already-running` running, and not a restart (a client offers its terminal instead);
|
|
15
|
+
* 3 `state-unknown` its state is not known stopped, and this is not a restart of a running row: unknown is
|
|
16
|
+
* not stopped. `detail` is the row's own runtime error through the display filter, when
|
|
17
|
+
* it has one, for the client to show with its speaker;
|
|
18
|
+
* 4 E_SNAPSHOT_UNKNOWN a server's row the kernel does not report addressable;
|
|
19
|
+
* 5 `cli-unavailable` / `unsupported-start-option` / `unsupported-remote-operation` no accepted CLI, no
|
|
20
|
+
* session-start, or (a server's row) no remote session-start;
|
|
21
|
+
* 6 `unsupported-start-option` a restart without session-restart (a server's row: also remote);
|
|
22
|
+
* 7 `unsupported-start-option` a launch choice (launchConfig, harness, yolo) without launch-config (a
|
|
23
|
+
* server's row: also remote). The word that selects no configuration is a choice like
|
|
24
|
+
* any other: no refusal of its own.
|
|
25
|
+
* -> null | { code, sentence, detail? } */
|
|
26
|
+
export function startGate(cli, row, { restart = false, choices = {} } = {}, terms) {
|
|
27
|
+
requireTerms(terms, 'startGate');
|
|
28
|
+
const refused = (code, sentence, more = {}) => ({ code, sentence, ...more });
|
|
29
|
+
if (!row) return refused('not-in-roster', 'This instance is no longer in this workspace. Refresh the workspace roster.');
|
|
30
|
+
const running = row.running === true, remote = !!row.server;
|
|
31
|
+
if (running && !restart) return refused('already-running', 'This instance is already running.');
|
|
32
|
+
if (row.running !== false && !(restart && running)) {
|
|
33
|
+
const detail = displayLine(row.runtimeError);
|
|
34
|
+
return refused('state-unknown', STATE_UNKNOWN, detail ? { detail } : {});
|
|
35
|
+
}
|
|
36
|
+
if (!canAddressRemote(row)) return refused('E_SNAPSHOT_UNKNOWN', unaddressableSentence(row));
|
|
37
|
+
if (cli?.ok !== true || !has(cli.features, 'session-start'))
|
|
38
|
+
return refused(cli?.ok === true ? 'unsupported-start-option' : 'cli-unavailable', `Starting an existing instance needs an updated OATS CLI. ${displayLine(cli?.install) || 'Update OATS and retry.'}`);
|
|
39
|
+
if (remote && !has(cli.remote, 'session-start')) return refused('unsupported-remote-operation', 'Update the OATS CLI to enable starting instances on a server.');
|
|
40
|
+
if (restart && (!has(cli.features, 'session-restart') || (remote && !has(cli.remote, 'session-restart'))))
|
|
41
|
+
return refused('unsupported-start-option', 'Update OATS to restart with another harness or configuration.');
|
|
42
|
+
if ([choices?.launchConfig, choices?.harness, choices?.yolo].some(v => v !== undefined)
|
|
43
|
+
&& (!has(cli.features, 'launch-config') || (remote && !has(cli.remote, 'launch-config'))))
|
|
44
|
+
return refused('unsupported-start-option', 'Update OATS to change the launch configuration.');
|
|
45
|
+
return null;
|
|
46
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** What a client says, in its own words, of a start it could not make: a start, a restart or a launch
|
|
2
|
+
* preview of an existing home that the kernel refused. One sentence per refusal code a client has words
|
|
3
|
+
* for; every other refusal reads as the kernel's message, as before.
|
|
4
|
+
*
|
|
5
|
+
* A sentence names the Start dialog's own two controls (its Launch configuration list and that list's
|
|
6
|
+
* entry for the bare harness), never a machine: it is the same for a home on this computer and on a
|
|
7
|
+
* server. It holds no part of the kernel's message, which a client shows under it, attributed and through
|
|
8
|
+
* the display filter (display-text.mjs). No kernel text is parsed or compared to choose it: the code alone.
|
|
9
|
+
* Not on the stable surface. */
|
|
10
|
+
const SENTENCES = Object.freeze({
|
|
11
|
+
// Several launch configurations are declared for the harness a start named, none is the default, and the
|
|
12
|
+
// start named no configuration.
|
|
13
|
+
E_LAUNCH_CONFIG_AMBIGUOUS: 'More than one launch configuration is declared for the chosen harness, and none is the default. Choose one under Launch configuration, or choose "No launch configuration" to run the harness as installed.',
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
/** The client's sentence for a start's refusal `code`, or null when it has none. */
|
|
17
|
+
export const startRefusalSentence = code => (typeof code === 'string' && Object.hasOwn(SENTENCES, code) ? SENTENCES[code] : null);
|
|
@@ -74,10 +74,10 @@ const LAST_READ_FAILED = 'This deployment\'s last read failed. It shows what was
|
|
|
74
74
|
*
|
|
75
75
|
* origin the line detail
|
|
76
76
|
* "kernel" a line "<own sentence> OATS says: <line>"
|
|
77
|
-
* "kernel" "[
|
|
77
|
+
* "kernel" "[withheld]" "<own sentence> [withheld]"
|
|
78
78
|
* "kernel" nothing to show "<own sentence>"
|
|
79
79
|
* none a line "This deployment's last read failed: <line>. It shows what was last observed."
|
|
80
|
-
* none "[
|
|
80
|
+
* none "[withheld]" "This deployment's last read failed: [withheld]. It shows what was last observed."
|
|
81
81
|
* none nothing to show "<own sentence>"
|
|
82
82
|
*
|
|
83
83
|
* The kernel's words stand apart, after the client's sentence and the speaker's lead
|
package/packages/tui/README.md
CHANGED
|
@@ -5,8 +5,9 @@ for people who work in terminals and on machines with no display. It ships
|
|
|
5
5
|
inside `@awebai/oats` and is never published on its own.
|
|
6
6
|
|
|
7
7
|
**It is a preview.** This version shows a workspace's instances, on this
|
|
8
|
-
machine and on the other machines registered on it, in one list,
|
|
9
|
-
them
|
|
8
|
+
machine and on the other machines registered on it, in one list, follows
|
|
9
|
+
them, opens an agent's terminal, and stops, starts, restarts and retires an
|
|
10
|
+
agent after a confirmation. While it is a preview its screens and its
|
|
10
11
|
configuration file may change without notice.
|
|
11
12
|
|
|
12
13
|
[`docs/tui.md`](../../docs/tui.md) is the reference: how to start it, what the
|
|
@@ -23,7 +24,8 @@ never does.
|
|
|
23
24
|
| `lib/actions.mjs` | the action table and its default keys: the reducer, the footer and the help read the effective one |
|
|
24
25
|
| `lib/config.mjs` | `tui.json`: read once, checked, and the effective action table |
|
|
25
26
|
| `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
|
|
26
|
-
| `lib/
|
|
27
|
+
| `lib/open.mjs` | the viewer of an opened agent: `oats session attach` run by the same kernel on the user's terminal, and the end of its standard error kept |
|
|
28
|
+
| `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), and the two looks at the file system the switcher needs (the entries of `~/Agents`, and whether a picked folder is a deployment) |
|
|
27
29
|
| `lib/store.mjs` | the state and `reduce(state, event)`: pure |
|
|
28
30
|
| `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows, by calling the shared readers: pure, no cell position |
|
|
29
31
|
| `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock |
|
|
@@ -31,8 +33,8 @@ never does.
|
|
|
31
33
|
| `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
|
|
32
34
|
| `lib/term/style.mjs` | style values: the sixteen ANSI colours and four attributes |
|
|
33
35
|
| `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
|
|
34
|
-
| `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
|
|
35
|
-
| `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help |
|
|
36
|
+
| `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, the lend of the terminal to a viewer, one write per frame |
|
|
37
|
+
| `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help, the confirmation of an act (`act.mjs`) |
|
|
36
38
|
|
|
37
39
|
Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
38
40
|
|
|
@@ -48,8 +50,17 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
48
50
|
the shared readers give reaches the screen through `shown()`.
|
|
49
51
|
- The store holds no size and no cell: a key event carries the height of the
|
|
50
52
|
panes as the last frame drew them.
|
|
51
|
-
- Every
|
|
52
|
-
|
|
53
|
+
- Every read runs in a session of its own and is ended on every way out.
|
|
54
|
+
The viewer (`lib/open.mjs`) shares the user's terminal, the guard lends it
|
|
55
|
+
the terminal, and it is ended first on every way out while it has it. A
|
|
56
|
+
change (`lib/read.mjs` `changeExec`: the apply of a stop or a retire, a
|
|
57
|
+
start, a restart) is never signalled: on the way out it is let go, and its
|
|
58
|
+
output goes to files, so it never meets a closed pipe.
|
|
59
|
+
- The acts decide nothing the shared home decides: which act a row offers is
|
|
60
|
+
`instanceActs`, a stop or a retire is the shared confirmation over the
|
|
61
|
+
run's one lifecycle boundary, a start or a restart is `startInstance`, and
|
|
62
|
+
no lifecycle sentence is written in this package where the shared home
|
|
63
|
+
has one.
|
|
53
64
|
- The screen takes safe text only. Text the TUI did not write goes through
|
|
54
65
|
`shown()`; `lit()` is for the TUI's own words and refuses anything the
|
|
55
66
|
display filter would change, a run of spaces included, so a row is spans
|
|
@@ -57,7 +68,9 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
57
68
|
|
|
58
69
|
Tests: `node --test packages/tui/test/*.test.mjs`, the root tests
|
|
59
70
|
`test/tui-*.test.mjs`, and the end-to-end tests in a real tmux on a private
|
|
60
|
-
socket (`test/tui-terminal.test.mjs`
|
|
71
|
+
socket (`test/tui-terminal.test.mjs`, and `test/tui-open-terminal.test.mjs`
|
|
72
|
+
for opening an agent, with a second private server for the agents;
|
|
73
|
+
`test/tui-acts.test.mjs` for the acts, run on CI only). All of them need the root's install
|
|
61
74
|
(`npm ci` at the repository root). The package has no dependency of its own,
|
|
62
75
|
but one of its tests runs the real kernel, which has: "KERNEL_BIN is this
|
|
63
76
|
install's own bin/oats.mjs, and its `version --json` is a record the probe
|
|
@@ -2,6 +2,9 @@
|
|
|
2
2
|
// both read it, so the help cannot name a key the program does not act on. `keys` are key ids
|
|
3
3
|
// (term/keys.mjs keyId); they are the part a user's tui.json replaces (config.mjs), so everything
|
|
4
4
|
// that acts on a key or names one reads the EFFECTIVE table it is handed, never this constant.
|
|
5
|
+
// An action that does one thing in the list of instances and another in the switcher (`open`)
|
|
6
|
+
// says so in `views`: what it does in each, in the order the help lists them. An action of one
|
|
7
|
+
// view only (the four acts) names that view, so the help says where it acts.
|
|
5
8
|
export const ACTIONS = Object.freeze([
|
|
6
9
|
{ id: "up", keys: ["up", "k"], label: "up" },
|
|
7
10
|
{ id: "down", keys: ["down", "j"], label: "down" },
|
|
@@ -16,13 +19,19 @@ export const ACTIONS = Object.freeze([
|
|
|
16
19
|
{ id: "refresh", keys: ["r"], label: "refresh" },
|
|
17
20
|
{ id: "instances", keys: ["1"], label: "instances" },
|
|
18
21
|
{ id: "workspaces", keys: ["w"], label: "workspaces" },
|
|
19
|
-
{ id: "open
|
|
22
|
+
{ id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"]] },
|
|
23
|
+
// The four acts on an instance: each opens a confirmation, and nothing is done before a move and
|
|
24
|
+
// a press in it. Capitals: a lower-case key is one slip away, a capital takes Shift.
|
|
25
|
+
{ id: "stop", keys: ["X"], label: "stop", views: [["instances", "stop the selected agent, after a confirmation"]] },
|
|
26
|
+
{ id: "retire", keys: ["D"], label: "retire", views: [["instances", "retire the selected agent, after a confirmation"]] },
|
|
27
|
+
{ id: "start", keys: ["S"], label: "start", views: [["instances", "start the selected agent as it was last launched, after a confirmation"]] },
|
|
28
|
+
{ id: "restart", keys: ["R"], label: "restart", views: [["instances", "restart the selected agent as it was last launched, after a confirmation"]] },
|
|
20
29
|
{ id: "help", keys: ["?"], label: "help" },
|
|
21
30
|
{ id: "close", keys: ["escape"], label: "close" },
|
|
22
31
|
{ id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
|
|
23
32
|
{ id: "suspend", keys: ["ctrl+z"], label: "suspend" },
|
|
24
33
|
{ id: "redraw", keys: ["ctrl+l"], label: "redraw" },
|
|
25
|
-
].map((action) => Object.freeze({ ...action, keys: Object.freeze([...action.keys]) })));
|
|
34
|
+
].map((action) => Object.freeze({ ...action, keys: Object.freeze([...action.keys]), ...(action.views ? { views: Object.freeze(action.views.map((view) => Object.freeze([...view]))) } : {}) })));
|
|
26
35
|
|
|
27
36
|
/** key id -> action id. A key bound twice is a defect of the table, refused when it is read. */
|
|
28
37
|
export function bindings(actions = ACTIONS) {
|
|
@@ -13,7 +13,7 @@ export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
|
|
|
13
13
|
export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
|
|
14
14
|
export { createRefreshLoop } from "../../client/refresh-loop.mjs";
|
|
15
15
|
export { rosterRows, livenessInput, livenessAnswers, panelInstances, pendingEntry, failedEntry, observedEntry } from "../../client/deployment-panel.mjs";
|
|
16
|
-
export { panelData, cliReadsRemotes, workspaceChoices, viewModel } from "../../client/panel-views.mjs";
|
|
16
|
+
export { panelData, cliReadsRemotes, workspaceChoices, viewModel, deployments } from "../../client/panel-views.mjs";
|
|
17
17
|
export { remoteRosterState } from "../../client/remote-roster.mjs";
|
|
18
18
|
export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
|
|
19
19
|
export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
|
|
@@ -22,7 +22,14 @@ export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterIn
|
|
|
22
22
|
export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
|
|
23
23
|
export { runtimeState, runtimeCounts, originLead } from "../../client/instance-presentation.mjs";
|
|
24
24
|
export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
|
|
25
|
-
export { instanceActs } from "../../client/instance-acts.mjs";
|
|
25
|
+
export { instanceActs, openAct } from "../../client/instance-acts.mjs";
|
|
26
|
+
export { sessionAttachArgv, prepareRemoteTerm, detachKeySupported, hostDetachKeySupported, preflightFailure, DETACH_KEY_FEATURE } from "../../client/session-attach.mjs";
|
|
27
|
+
export { attachExit } from "../../client/attach-exit.mjs";
|
|
28
|
+
export { kernelLines } from "../../client/kernel-lines.mjs";
|
|
29
|
+
export { createLifecycleBoundary } from "../../client/instance-lifecycle.mjs";
|
|
30
|
+
export { createLifecycleConfirmation } from "../../client/lifecycle-confirmation.mjs";
|
|
31
|
+
export { startGate, startInstance } from "../../client/session-start.mjs";
|
|
32
|
+
export { retainedStartMessage, launchFlagIgnored, flagIgnoredNotice } from "../../client/launch-prompt-outcome.mjs";
|
|
26
33
|
export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
|
|
27
34
|
export { validateWorkspace, deploymentsInside } from "../../client/workspace-admission.mjs";
|
|
28
35
|
|
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
// The user's key file, tui.json: which keys do what,
|
|
1
|
+
// The user's key file, tui.json: which keys do what, whether the screen is drawn in ASCII, and the
|
|
2
|
+
// key that leaves an agent's terminal.
|
|
2
3
|
// Read once at start and never written. A file that is wrong in any way is refused whole, each
|
|
3
4
|
// problem as one line that says what to change: the TUI resolves no conflict and guesses nothing
|
|
4
5
|
// (there is no "last wins"), because a key that silently does something else is worse than a
|
|
@@ -16,7 +17,14 @@ export const CONFIG_LIMIT = 64 * 1024;
|
|
|
16
17
|
|
|
17
18
|
const TOO_LARGE = `it is larger than ${CONFIG_LIMIT / 1024} KiB`;
|
|
18
19
|
const NOT_AN_OBJECT = 'it is not one JSON object, like {"keys": {"quit": ["q"]}}';
|
|
19
|
-
const SETTINGS = "the settings are keys and
|
|
20
|
+
const SETTINGS = "the settings are keys, ascii and open";
|
|
21
|
+
/** The key that leaves an agent's terminal when tui.json names none: the kernel's suggested key. */
|
|
22
|
+
export const DETACH_KEY = "C-\\";
|
|
23
|
+
/** A detach key as tui.json may hold it: 1 to 16 printable ASCII characters. Its grammar is the
|
|
24
|
+
* kernel's, never checked here: a key the kernel refuses is said when an agent is opened. */
|
|
25
|
+
const DETACH_KEY_TEXT = /^[\x20-\x7e]{1,16}$/;
|
|
26
|
+
/** An action id this program had and has no more, with what it is called now. */
|
|
27
|
+
const RENAMED = Object.freeze({ "open-workspace": "open" });
|
|
20
28
|
const KEY_IDS = "key ids look like q, ctrl+c, shift+tab, f5, space";
|
|
21
29
|
/** A name from the file is echoed only when it is this: it cannot move a cursor or fill a screen. */
|
|
22
30
|
const PLAIN_NAME = /^[\x21-\x7e]{1,40}$/;
|
|
@@ -43,7 +51,8 @@ export function configPath(env, home) {
|
|
|
43
51
|
}
|
|
44
52
|
|
|
45
53
|
/** What tui.json says, checked: `value` is the file already parsed, `defaults` the action table.
|
|
46
|
-
* Pure. Answers `{ ok: true, actions, ascii }` or `{ ok: false, problems }
|
|
54
|
+
* Pure. Answers `{ ok: true, actions, ascii, detachKey }` or `{ ok: false, problems }`:
|
|
55
|
+
* `detachKey` is `open.detachKey`, or DETACH_KEY when the file names none.
|
|
47
56
|
*
|
|
48
57
|
* `actions` is a frozen table shaped exactly like `defaults` (same order, ids and labels, frozen
|
|
49
58
|
* rows with frozen `keys`) in which the list of each action the file names REPLACES that action's
|
|
@@ -60,6 +69,7 @@ export function effectiveConfig(value, defaults = ACTIONS) {
|
|
|
60
69
|
for (const [setting, given] of Object.entries(value)) {
|
|
61
70
|
if (setting === "keys") { if (!isObject(given)) return { ok: false, problems: ['keys must be an object, like {"quit": ["q"]}'] }; }
|
|
62
71
|
else if (setting === "ascii") { if (typeof given !== "boolean") return { ok: false, problems: ["ascii must be true or false"] }; }
|
|
72
|
+
else if (setting === "open") { const refused = openProblem(given); if (refused) return { ok: false, problems: [refused] }; }
|
|
63
73
|
else return { ok: false, problems: [`${plain(setting) ? `unknown setting ${setting}` : "a setting whose name cannot be shown is unknown"}; ${SETTINGS}`] };
|
|
64
74
|
}
|
|
65
75
|
|
|
@@ -80,7 +90,9 @@ export function effectiveConfig(value, defaults = ACTIONS) {
|
|
|
80
90
|
// where the file gives it. (Two of them clashing is a defect of the table, said the same way.)
|
|
81
91
|
for (const action of defaults) if (!named.has(action.id)) for (const key of action.keys) claim(key, action.id);
|
|
82
92
|
for (const [id, list] of lists) {
|
|
83
|
-
if (!ids.has(id)) {
|
|
93
|
+
if (!ids.has(id) && Object.hasOwn(RENAMED, id) && ids.has(RENAMED[id])) {
|
|
94
|
+
problems.push(`${id} is called ${RENAMED[id]} now; rename it`);
|
|
95
|
+
} else if (!ids.has(id)) {
|
|
84
96
|
problems.push(`${plain(id) ? `unknown action ${id}` : "an action id that cannot be shown is unknown"}; the actions are ${[...ids].filter(plain).join(", ")}`);
|
|
85
97
|
} else if (!Array.isArray(list) || !list.every((key) => typeof key === "string")) {
|
|
86
98
|
problems.push(`${say(id)} must be a list of key ids, like ["q", "ctrl+c"]`);
|
|
@@ -97,7 +109,24 @@ export function effectiveConfig(value, defaults = ACTIONS) {
|
|
|
97
109
|
|
|
98
110
|
const actions = Object.freeze(defaults.map((action) => Object.freeze({ ...action, keys: Object.freeze([...(named.get(action.id) ?? action.keys)]) })));
|
|
99
111
|
try { bindings(actions); } catch { return { ok: false, problems: ["a key is given to two actions; a key does one thing"] }; }
|
|
100
|
-
return { ok: true, actions, ascii: value.ascii === true };
|
|
112
|
+
return { ok: true, actions, ascii: value.ascii === true, detachKey: value.open?.detachKey ?? DETACH_KEY };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** What is wrong with the `open` setting, or null. It holds one member, `detachKey`: a string of 1
|
|
116
|
+
* to 16 printable ASCII characters, handed to `oats session attach --detach-key` as it is. Its
|
|
117
|
+
* grammar is the kernel's. Two things that are not grammar are refused here: a value that begins
|
|
118
|
+
* with `-`, which the kernel would read as another flag and refuse in that flag's words (no key of
|
|
119
|
+
* its grammar begins with one), and a value the display filter would change, which the footer and
|
|
120
|
+
* the help would draw as another key. */
|
|
121
|
+
function openProblem(given) {
|
|
122
|
+
if (!isObject(given)) return 'open must be an object, like {"detachKey": "F12"}';
|
|
123
|
+
for (const [member, key] of Object.entries(given)) {
|
|
124
|
+
if (member !== "detachKey") return `${plain(member) ? `unknown member ${member} of open` : "a member of open whose name cannot be shown is unknown"}; open has detachKey`;
|
|
125
|
+
if (typeof key !== "string" || !DETACH_KEY_TEXT.test(key)) return 'open.detachKey must be 1 to 16 printable ASCII characters, like "F12"';
|
|
126
|
+
if (key.startsWith("-")) return "open.detachKey cannot begin with -";
|
|
127
|
+
if (displayLine(key) !== key) return "open.detachKey is a key the help cannot name; give a key whose characters can be shown";
|
|
128
|
+
}
|
|
129
|
+
return null;
|
|
101
130
|
}
|
|
102
131
|
|
|
103
132
|
/** The file system as loadConfig needs it. `stat` follows symbolic links and answers null for a
|
|
@@ -126,9 +155,10 @@ const NODE_IO = Object.freeze({
|
|
|
126
155
|
},
|
|
127
156
|
});
|
|
128
157
|
|
|
129
|
-
/** Read tui.json, once. Answers `{ ok: true, actions, ascii, path }`, or
|
|
130
|
-
* the complete lines to print (no trailing newline), after which the TUI
|
|
131
|
-
* No file is the defaults: `actions` is ACTIONS itself
|
|
158
|
+
/** Read tui.json, once. Answers `{ ok: true, actions, ascii, detachKey, path }`, or
|
|
159
|
+
* `{ ok: false, lines }`: the complete lines to print (no trailing newline), after which the TUI
|
|
160
|
+
* must not start. No file is the defaults: `actions` is ACTIONS itself, `ascii` is false and
|
|
161
|
+
* `detachKey` is DETACH_KEY.
|
|
132
162
|
*
|
|
133
163
|
* `io` is the file system (node:fs when omitted): `io.stat(path)` answers `{ file, size }` after
|
|
134
164
|
* following symbolic links, or null when the path does not exist, and throws for anything else;
|
|
@@ -141,7 +171,7 @@ export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO }
|
|
|
141
171
|
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)`) });
|
|
142
172
|
let found, text, value;
|
|
143
173
|
try { found = io.stat(path); } catch (error) { return refused([unreadable(error)]); }
|
|
144
|
-
if (found === null) return { ok: true, actions: ACTIONS, ascii: false, path };
|
|
174
|
+
if (found === null) return { ok: true, actions: ACTIONS, ascii: false, detachKey: DETACH_KEY, path };
|
|
145
175
|
if (found.file !== true) return refused(["it is not a regular file"]);
|
|
146
176
|
if (!(typeof found.size === "number" && found.size <= CONFIG_LIMIT)) return refused([TOO_LARGE]); // read only what is known to fit
|
|
147
177
|
try { text = io.read(path); } catch (error) { return refused([error?.code === "EFBIG" ? TOO_LARGE : unreadable(error)]); }
|