@awebai/oats 0.52.0 → 0.54.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 +2 -1
- package/bin/oats.mjs +314 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +696 -60
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +184 -12
- package/docs/integrations.md +6 -3
- package/docs/knowledge.md +2 -2
- package/docs/macos-test-runs.md +246 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +210 -6
- package/docs/release-notes/v0.53.0.md +1288 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +239 -16
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +310 -0
- package/docs/workspaces.md +123 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +93 -4
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +569 -121
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +5 -6
- package/lib/instance-lifecycle.mjs +145 -18
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +226 -15
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +18 -5
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +404 -60
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +6 -35
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/workspace.mjs +75 -27
- package/package-catalog.json +4 -4
- package/package.json +2 -1
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/cli-adapter.mjs +16 -3
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-contract.mjs +4 -0
- package/packages/client/deployment-facts.mjs +71 -10
- package/packages/client/deployment-panel.mjs +49 -11
- package/packages/client/deployment-read-cli.mjs +7 -3
- package/packages/client/display-text.mjs +8 -2
- package/packages/client/instance-acts.mjs +46 -10
- package/packages/client/instance-events-contract.mjs +4 -2
- package/packages/client/instance-presentation.mjs +66 -2
- package/packages/client/instance-tree.mjs +23 -14
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-prompt-outcome.mjs +51 -16
- package/packages/client/lifecycle-contract.mjs +45 -4
- package/packages/client/liveness.mjs +14 -1
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/panel-views.mjs +18 -11
- package/packages/client/readiness-contract.mjs +3 -1
- package/packages/client/remote-address.mjs +34 -9
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +92 -6
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-contract.mjs +16 -4
- package/packages/client/spawn-messages.mjs +26 -3
- package/packages/client/spawn-preview-cli.mjs +8 -2
- package/packages/client/spawn-preview-contract.mjs +5 -1
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-views.mjs +39 -3
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +30 -12
- package/packages/tui/lib/actions.mjs +16 -1
- package/packages/tui/lib/client.mjs +32 -1
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +117 -46
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +44 -0
- package/packages/tui/lib/term/screen.mjs +16 -4
- package/packages/tui/lib/term/text.mjs +60 -0
- package/packages/tui/lib/term/tty.mjs +13 -3
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +230 -36
- package/packages/tui/lib/views/help.mjs +125 -13
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/skills/oats-getting-started/SKILL.md +8 -2
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
import { displayLine } from './display-text.mjs';
|
|
9
9
|
import { ROLLED_BACK_CODES } from './spawn-apply-contract.mjs';
|
|
10
10
|
|
|
11
|
+
const UNMATCHED = 'E_LAUNCH_PREFERENCE_UNMATCHED';
|
|
12
|
+
|
|
11
13
|
const COMMON = {
|
|
12
14
|
E_BAD_ARGS: 'Some of these values can’t be used. Check the name and Developer settings.',
|
|
13
15
|
E_BUSY: 'Another spawn is in progress. Try again in a moment.',
|
|
@@ -27,7 +29,6 @@ const COMMON = {
|
|
|
27
29
|
E_BRANCH_EXISTS: 'That branch already exists. Choose another branch in Developer settings.',
|
|
28
30
|
E_BASE_UNKNOWN: 'That base isn’t a branch, tag or commit in this soul’s repository. Check it in Developer settings.',
|
|
29
31
|
E_CLONE_MISSING: 'This soul’s repository isn’t cloned on this machine yet. Clone it, then try again — Details shows how.',
|
|
30
|
-
E_REQUIREMENT_INACTIVE: 'Something this soul needs isn’t set up yet. Check the soul in the Workspace view.',
|
|
31
32
|
E_LAUNCH_ENV_MISSING: 'The chosen launch configuration can’t start on this machine. Choose another in Developer settings.',
|
|
32
33
|
E_LAUNCH_EXECUTABLE: 'The chosen launch configuration can’t start on this machine. Choose another in Developer settings.',
|
|
33
34
|
E_LAUNCH_PROBE_UNSUPPORTED: 'The chosen launch configuration can’t be checked safely. Choose another in Developer settings.',
|
|
@@ -39,6 +40,11 @@ const COMMON = {
|
|
|
39
40
|
// 0.30 launch preferences: shown in the kernel's own words when it sends them (spawnProblem: the
|
|
40
41
|
// message, then the reason's flat `fix`), which name the harness and where it was chosen; this is the fallback.
|
|
41
42
|
E_HARNESS_UNAVAILABLE: 'The harness this soul would run isn’t installed on this machine. Install it, or pick another harness above.',
|
|
43
|
+
// 0.53.0: the kernel refuses a spawn that names no launch while `souls.launch` holds a key that names no
|
|
44
|
+
// soul. This sentence points at the controls above it and at Details, so it is read only where both are
|
|
45
|
+
// there: at the preview, with the kernel's message and fix quoted under Details (spawnProblem's `kernel`
|
|
46
|
+
// parts). Everywhere else the shorter one of SPAWN is read.
|
|
47
|
+
[UNMATCHED]: 'This machine’s launch preferences name a soul this workspace doesn’t offer, so OATS won’t choose a launch for this soul. To spawn now, pick a harness above, or a launch configuration in Developer settings. To fix it for every spawn, correct the preference (Details).',
|
|
42
48
|
E_MODEL_UNKNOWN: 'That model isn’t available for this harness. Pick another model, or keep the default.',
|
|
43
49
|
E_INSTANCE_NAME_INVALID: 'Use lowercase letters, numbers and dashes, at most 64 characters, and don’t reuse a soul’s name.',
|
|
44
50
|
E_INSTANCE_NAME_TAKEN: 'An instance with this name already exists. Choose another name.',
|
|
@@ -71,16 +77,33 @@ const SPAWN = {
|
|
|
71
77
|
E_CLI_OUTPUT_LIMIT: 'OATS couldn’t confirm the spawn. Use Check result before spawning again.',
|
|
72
78
|
E_CLI_PROTOCOL: 'OATS couldn’t complete the spawn. Try again, or see Details.',
|
|
73
79
|
E_CLI_FAILED: 'OATS couldn’t complete the spawn. Try again, or see Details.',
|
|
80
|
+
// An unmatched launch preference where nothing is above the sentence and Details hold no kernel text: the
|
|
81
|
+
// notice after a press has left the dialog, and a preview whose reason carries no `fix`.
|
|
82
|
+
[UNMATCHED]: 'This machine’s launch preferences name a soul this workspace doesn’t offer, so OATS won’t choose a launch for this soul. To spawn now, pick a harness or a launch configuration for this spawn. To fix it for every spawn, correct the preference.',
|
|
74
83
|
};
|
|
75
84
|
|
|
76
|
-
/** { text, detail } for a { code, message } reason. `stage` is 'preview'
|
|
77
|
-
* (reading defaults) or 'spawn' (after the operator pressed Spawn).
|
|
85
|
+
/** { text, code, detail } for a { code, message } reason. `stage` is 'preview'
|
|
86
|
+
* (reading defaults) or 'spawn' (after the operator pressed Spawn).
|
|
87
|
+
*
|
|
88
|
+
* For an unmatched launch preference whose reason carries the kernel's `fix`, the answer also has
|
|
89
|
+
* `kernel: { message, fix }`: the kernel's two texts, the strings as they came, for the client to quote
|
|
90
|
+
* under the kernel's name (the lead is the client's, `originLead` with its terms). `detail` is then the
|
|
91
|
+
* code alone, so that no reader of `detail` shows a kernel text without its speaker. A `fix` decides it
|
|
92
|
+
* because `previewFailure` keeps one only beside the kernel's own message, never beside a table's sentence:
|
|
93
|
+
* a reason without one (a press, a kernel that sent none, a message that did not travel) reads
|
|
94
|
+
* `code · message` as every other code does. */
|
|
78
95
|
export function spawnProblem(reason, stage = 'preview') {
|
|
79
96
|
const code = typeof reason?.code === 'string' ? reason.code : 'E_CLI_FAILED';
|
|
80
97
|
const own = stage === 'spawn' ? SPAWN : PREVIEW;
|
|
81
98
|
const message = typeof reason?.message === 'string' ? reason.message.trim() : '';
|
|
82
99
|
// A missing harness is said as the kernel words it, with its fix (launch preferences, 0.30).
|
|
83
100
|
const fix = typeof reason?.fix === 'string' ? reason.fix.trim() : '';
|
|
101
|
+
if (code === UNMATCHED) {
|
|
102
|
+
const kernel = fix ? { message: typeof reason.message === 'string' ? reason.message : '', fix: reason.fix } : null;
|
|
103
|
+
// The sentence that says "above" and "(Details)" is read only where Details hold the kernel's texts.
|
|
104
|
+
if (kernel) return { text: stage === 'preview' ? COMMON[UNMATCHED] : SPAWN[UNMATCHED], code, detail: code, kernel };
|
|
105
|
+
return { text: SPAWN[UNMATCHED], code, detail: message ? `${code} · ${message}` : code };
|
|
106
|
+
}
|
|
84
107
|
// The kernel's message usually already ends with its fix: said once.
|
|
85
108
|
const kernelWords = code === 'E_HARNESS_UNAVAILABLE' && message ? (fix && !message.includes(fix) ? `${message.replace(/[.\s]+$/, '')}: ${fix}` : message) : null;
|
|
86
109
|
const text = kernelWords ?? own[code] ?? COMMON[code] ?? (stage === 'spawn' ? SPAWN.E_CLI_FAILED : PREVIEW.E_CLI_FAILED);
|
|
@@ -2,7 +2,13 @@
|
|
|
2
2
|
import { execFile } from 'node:child_process';
|
|
3
3
|
import { parseEnvelope } from './cli-adapter.mjs';
|
|
4
4
|
import { previewChoices, previewTarget, previewSupported, previewFailure, choiceArgv } from './spawn-preview-contract.mjs';
|
|
5
|
-
|
|
5
|
+
/** A refusal, in the kernel's own shape (`{ code, message, details: { fix } }`). `previewFailure` decides what of the
|
|
6
|
+
* kernel's travels: its message when that is printable and within the bound, and its `fix` only beside that message.
|
|
7
|
+
* No other key of `details` travels. */
|
|
8
|
+
function failure(code, message, kernelFix) {
|
|
9
|
+
const { fix, ...error } = previewFailure(code, null, message, kernelFix).reason;
|
|
10
|
+
return { schemaVersion: 1, ok: false, error: fix === undefined ? error : { ...error, details: { fix } } };
|
|
11
|
+
}
|
|
6
12
|
/** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`). */
|
|
7
13
|
export function cliSpawnPreview(cli, options = {}, io = {}) {
|
|
8
14
|
// Defense at the actual exec owner as well as at HTTP admission.
|
|
@@ -23,7 +29,7 @@ export function cliSpawnPreview(cli, options = {}, io = {}) {
|
|
|
23
29
|
if (err?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return resolve(failure('E_CLI_OUTPUT_LIMIT'));
|
|
24
30
|
if (err?.killed) return resolve(failure('E_CLI_TIMEOUT'));
|
|
25
31
|
const doc = parseEnvelope(stdout);
|
|
26
|
-
if (doc?.ok === false) return resolve(failure(doc.error?.code, doc.error?.message));
|
|
32
|
+
if (doc?.ok === false) return resolve(failure(doc.error?.code, doc.error?.message, doc.error?.details?.fix));
|
|
27
33
|
if (err) return resolve(failure('E_CLI_FAILED'));
|
|
28
34
|
resolve(doc?.ok === true ? doc : failure('E_CLI_PROTOCOL'));
|
|
29
35
|
});
|
|
@@ -213,12 +213,16 @@ const errors = {
|
|
|
213
213
|
E_UNSUPPORTED_OPTION: 'A chosen option is not supported for this soul or installed CLI.',
|
|
214
214
|
E_BRANCH_EXISTS: 'The proposed branch already exists. Choose another branch and preview again.',
|
|
215
215
|
E_BASE_UNKNOWN: 'The proposed base does not resolve to a commit.', E_CHILD_SPAWNS_DISABLED: 'The selected parent does not allow child spawns.',
|
|
216
|
-
|
|
216
|
+
E_LAUNCH_ENV_MISSING: 'Required launch environment references are unavailable.',
|
|
217
217
|
E_LAUNCH_EXECUTABLE: 'The selected launch executable is unavailable.', E_LAUNCH_PROBE_UNSUPPORTED: 'The selected launch cannot be preflighted safely.',
|
|
218
218
|
E_LAUNCH_CONFIG_UNKNOWN: 'The selected launch configuration is unavailable.', E_MODEL_UNKNOWN: 'The selected model could not be resolved.',
|
|
219
219
|
// 0.52.0: several launch configurations for the harness, no default, and the spawn names none. Listed so the
|
|
220
220
|
// code survives where the kernel's own message cannot travel (the apply's reason; a message over the bound).
|
|
221
221
|
E_LAUNCH_CONFIG_AMBIGUOUS: 'More than one launch configuration is declared for this harness and none is the default.',
|
|
222
|
+
// 0.53.0: `souls.launch` holds a key that names no soul, and the spawn names no launch. Listed for the same
|
|
223
|
+
// reason: the code survives where the kernel's own message cannot travel (the apply's reason, after the
|
|
224
|
+
// server's own preview before a dispatch was refused; a message the bound or the filter here does not pass).
|
|
225
|
+
E_LAUNCH_PREFERENCE_UNMATCHED: 'A launch preference on this machine names a soul the workspace does not offer, and this spawn names no launch.',
|
|
222
226
|
E_CLONE_MISSING: 'This soul works in a member repository that is not cloned on this machine.',
|
|
223
227
|
E_INSTANCE_NAME_INVALID: 'That name is not a valid instance name (a lowercase slug of at most 64 characters that is not a soul name).',
|
|
224
228
|
E_INSTANCE_NAME_TAKEN: 'An instance with that name already exists in this deployment.',
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
// Cancellation is a request, not process-exit evidence. In particular Node's
|
|
2
|
+
// AbortError can precede child close. Hold the caller's reservation until BOTH
|
|
3
|
+
// execFile's bounded result and the owned child's close have arrived. A failed
|
|
4
|
+
// command keeps its bounded stdout on the rejection: the CLI prints its JSON
|
|
5
|
+
// refusal and exits nonzero.
|
|
6
|
+
import { execFile } from 'node:child_process';
|
|
7
|
+
export function runTerminalCommand(binary, args, options, exec = execFile) {
|
|
8
|
+
return new Promise((resolve, reject) => {
|
|
9
|
+
let result, closed = false;
|
|
10
|
+
const settle = () => {
|
|
11
|
+
if (!closed || !result) return;
|
|
12
|
+
if (result.error) reject(Object.assign(result.error, { stdout: result.stdout })); else resolve({ stdout: result.stdout, stderr: result.stderr });
|
|
13
|
+
};
|
|
14
|
+
try {
|
|
15
|
+
const child = exec(binary, args, { ...options, shell: false }, (error, stdout, stderr) => {
|
|
16
|
+
result = { error, stdout, stderr }; settle();
|
|
17
|
+
});
|
|
18
|
+
child.once('close', () => { closed = true; settle(); });
|
|
19
|
+
} catch (error) { reject(error); } // spawn did not return an owned child
|
|
20
|
+
});
|
|
21
|
+
}
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/** The words a workspace switcher shows for a view (UI spec, #482; #855, 3a): its name, its one muted
|
|
2
|
+
* line, how many of its deployments are not live, its tooltip, and whether a typed filter keeps it.
|
|
3
|
+
* From what panel-views.mjs `workspaceChoices` answers. Words only: a client draws them (the Desktop's
|
|
4
|
+
* menu is packages/desktop/renderer/workspace-switcher.mjs).
|
|
5
|
+
*
|
|
6
|
+
* No state: arguments in, values out, and no argument is changed.
|
|
7
|
+
* A page loads this module: it imports no Node builtin, and must not. */
|
|
8
|
+
import { pathTail } from "./deployment-label.mjs";
|
|
9
|
+
|
|
10
|
+
/** A choice id that is this computer's folder (a deployment from an older server, an unattached
|
|
11
|
+
* one): its path may be shown, as a tooltip. Any other id (a view's `ws:…`, a remote's `remote:…`)
|
|
12
|
+
* is never shown (#482). */
|
|
13
|
+
export const isLocalPath = (id) => typeof id === "string" && id.startsWith("/");
|
|
14
|
+
const short = (value, max = 256) => typeof value === "string" && value.length > 0 && value.length <= max ? value : "";
|
|
15
|
+
|
|
16
|
+
const machinesOf = (choice) => Array.isArray(choice?.machines) ? choice.machines.filter((m) => short(m)) : [];
|
|
17
|
+
|
|
18
|
+
/** The machines a choice's deployments are on, as one line (UI spec, #482): "This Mac · altair", from
|
|
19
|
+
* the server's `machines`. Never a path or an id: without `machines` (an older server), nothing. */
|
|
20
|
+
export function workspaceChoicePlace(choice) {
|
|
21
|
+
return machinesOf(choice).join(" · ");
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** Each choice's name, in order. Two choices of one name are told apart by a suffix. */
|
|
25
|
+
export function workspaceChoiceLabels(choices) {
|
|
26
|
+
const base = choices.map((choice) => choice.name
|
|
27
|
+
|| (isLocalPath(choice.id) ? String(choice.id).split("/").filter(Boolean).at(-1) : "")
|
|
28
|
+
|| "Workspace");
|
|
29
|
+
const counts = new Map();
|
|
30
|
+
for (const name of base) counts.set(name, (counts.get(name) || 0) + 1);
|
|
31
|
+
return choices.map((choice, index) => {
|
|
32
|
+
if (counts.get(base[index]) === 1) return base[index];
|
|
33
|
+
// Two choices of one name: their workspace keys tell them apart, else a folder's last two
|
|
34
|
+
// segments or the machines; never a ws: or remote: id, never a full path.
|
|
35
|
+
const which = short(choice.key, 512) || (isLocalPath(choice.id) ? pathTail(choice.id, 2) : workspaceChoicePlace(choice));
|
|
36
|
+
const suffix = [short(choice.team?.name), which].filter(Boolean).join(" · ");
|
|
37
|
+
return suffix ? `${base[index]} — ${suffix}` : base[index];
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** The tooltip of a choice: its deployments' labels (machine and short path) when the server sends
|
|
42
|
+
* them, else a local folder's path; never an id. */
|
|
43
|
+
function choiceTooltip(choice) {
|
|
44
|
+
const deployments = Array.isArray(choice?.deployments) ? choice.deployments : [];
|
|
45
|
+
const labels = Array.isArray(choice?.deploymentLabels) && choice.deploymentLabels.length === deployments.length
|
|
46
|
+
&& choice.deploymentLabels.every((l) => short(l, 512)) ? choice.deploymentLabels : [];
|
|
47
|
+
return labels.join(", ") || (isLocalPath(choice?.id) ? choice.id : "");
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** The section a switcher lists unattached views under (#482, expert decision Q4). */
|
|
51
|
+
export const UNMATCHED_SECTION = "Not matched to a workspace";
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* What a switcher says for each choice, in the same order. Every entry is its name and ONE muted line
|
|
55
|
+
* (UI spec, #482): a view's machines, an unattached view's machine and short reason.
|
|
56
|
+
*
|
|
57
|
+
* id the choice's id
|
|
58
|
+
* label its name (`workspaceChoiceLabels`)
|
|
59
|
+
* place the muted line. A matched view: its machines, joined by " · ". An unattached one: its
|
|
60
|
+
* machine, unless the label already is that machine (a remote group is named by its
|
|
61
|
+
* server), then its short reason, joined the same way
|
|
62
|
+
* notLive for a matched view, how many of its deployments are not live when that is a positive
|
|
63
|
+
* integer; else 0
|
|
64
|
+
* notLiveText "1 deployment not live", "N deployments not live", or ""
|
|
65
|
+
* unattached whether no workspace identity matched it: such a view goes under UNMATCHED_SECTION
|
|
66
|
+
* tooltip its deployments' labels when there is one label per deployment, else a local folder's
|
|
67
|
+
* path, else ""
|
|
68
|
+
* deployment for an unattached view, its first deployment's id (where its full reason and its fix
|
|
69
|
+
* are shown); else null
|
|
70
|
+
*
|
|
71
|
+
* @param {Array<object>} choices what `workspaceChoices` (panel-views.mjs) answers
|
|
72
|
+
*/
|
|
73
|
+
export function workspaceChoiceRows(choices) {
|
|
74
|
+
const labels = workspaceChoiceLabels(choices);
|
|
75
|
+
return choices.map((choice, index) => {
|
|
76
|
+
const label = labels[index], unattached = !!choice.unattached;
|
|
77
|
+
const place = unattached
|
|
78
|
+
// The machine, unless the entry is already named by it (a remote group is named by its server).
|
|
79
|
+
? [machinesOf(choice)[0] === label ? "" : machinesOf(choice)[0] || "", short(choice.short)].filter(Boolean).join(" · ")
|
|
80
|
+
: workspaceChoicePlace(choice);
|
|
81
|
+
const notLive = !unattached && Number.isInteger(choice.notLive) && choice.notLive > 0 ? choice.notLive : 0;
|
|
82
|
+
return { id: choice.id, label, place, notLive,
|
|
83
|
+
notLiveText: notLive ? `${notLive} ${notLive === 1 ? "deployment" : "deployments"} not live` : "",
|
|
84
|
+
unattached, tooltip: choiceTooltip(choice),
|
|
85
|
+
deployment: (unattached && Array.isArray(choice.deployments) ? choice.deployments[0] : null) || null };
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** A switcher's filter: whether a row is kept for what was typed. The query is trimmed and lower-cased
|
|
90
|
+
* here; it is looked for in the row's label and place, joined by a space and lower-cased, so what is not
|
|
91
|
+
* shown (a tooltip, a full reason) is never matched. No query keeps every row. */
|
|
92
|
+
export function choiceMatches(row, query) {
|
|
93
|
+
const wanted = String(query ?? "").trim().toLocaleLowerCase();
|
|
94
|
+
return !wanted || `${row.label} ${row.place}`.toLocaleLowerCase().includes(wanted);
|
|
95
|
+
}
|
|
@@ -6,6 +6,8 @@
|
|
|
6
6
|
* derived from a path, a ref or a host name, and `ref` is never compared. */
|
|
7
7
|
import { createHash } from 'node:crypto';
|
|
8
8
|
import { requireTerms } from './client-terms.mjs';
|
|
9
|
+
import { displayLine, DETAIL_WITHHELD } from './display-text.mjs';
|
|
10
|
+
import { originLead } from './instance-presentation.mjs';
|
|
9
11
|
|
|
10
12
|
const TEXT_MAX = 2048;
|
|
11
13
|
const text = v => typeof v === 'string' && v.length > 0 && v.length <= TEXT_MAX && !v.includes('\0');
|
|
@@ -62,11 +64,45 @@ const REASONS = {
|
|
|
62
64
|
* as E_SSH with ssh's stderr and no code of its own, so ssh's text is the only signal (a documented limit). */
|
|
63
65
|
const TIMED_OUT = /timed out|timeout/i;
|
|
64
66
|
|
|
67
|
+
/** The client's own sentence for a deployment whose last read failed and whose last observation is kept. */
|
|
68
|
+
const LAST_READ_FAILED = 'This deployment\'s last read failed. It shows what was last observed.';
|
|
69
|
+
|
|
70
|
+
/** The reason of a kept failure, in parts and joined. `message` is the failure's text and `origin` its
|
|
71
|
+
* speaker ("kernel" when the installed CLI printed it; deployment-facts.mjs `keptFailure`). The message
|
|
72
|
+
* is one display line in every form (display-text.mjs `displayLine`), whole or withheld whole:
|
|
73
|
+
*
|
|
74
|
+
* origin the line detail
|
|
75
|
+
* "kernel" a line "<own sentence> OATS says: <line>"
|
|
76
|
+
* "kernel" "[Detail withheld]" "<own sentence> [Detail withheld]"
|
|
77
|
+
* "kernel" nothing to show "<own sentence>"
|
|
78
|
+
* none a line "This deployment's last read failed: <line>. It shows what was last observed."
|
|
79
|
+
* none "[Detail withheld]" "This deployment's last read failed: [Detail withheld]. It shows what was last observed."
|
|
80
|
+
* none nothing to show "<own sentence>"
|
|
81
|
+
*
|
|
82
|
+
* The kernel's words stand apart, after the client's sentence and the speaker's lead
|
|
83
|
+
* (instance-presentation.mjs `originLead`); a withheld or missing message is never introduced by the
|
|
84
|
+
* lead. A message with no origin keeps the words a client always showed, inside its own sentence.
|
|
85
|
+
* The parts, as deployment-facts.mjs `deploymentUnavailableParts` answers them: `headline` the client's
|
|
86
|
+
* sentence, `lead` the speaker's words or null, `sentence` the kernel's line or null; `detail` is those
|
|
87
|
+
* that are there, joined by one space. With no origin the whole detail is the headline. */
|
|
88
|
+
function lastReadFailed(message, origin, terms) {
|
|
89
|
+
const line = displayLine(message);
|
|
90
|
+
if (origin !== 'kernel') {
|
|
91
|
+
const detail = line === null ? LAST_READ_FAILED : `This deployment's last read failed: ${line}. It shows what was last observed.`;
|
|
92
|
+
return { headline: detail, lead: null, sentence: null, detail };
|
|
93
|
+
}
|
|
94
|
+
const lead = line === null || line === DETAIL_WITHHELD ? null : originLead('kernel', terms);
|
|
95
|
+
return { headline: LAST_READ_FAILED, lead, sentence: line, detail: [LAST_READ_FAILED, lead, line].filter(part => part !== null).join(' ') };
|
|
96
|
+
}
|
|
97
|
+
|
|
65
98
|
/** Why a deployment is not live or not matched, or null: `{ short, detail, fix }`. `short` is a few
|
|
66
99
|
* words for a heading or the switcher ("OATS too old to report its workspace"); `detail` the one full
|
|
67
100
|
* sentence; `fix` the plain steps (possibly none: the detail then says what happens next). The steps
|
|
68
101
|
* carry every fact the sentence has (a host, a reference): with steps, a heading shows only them.
|
|
69
|
-
* `d`: `{ local, machine, sshHost?, probe?, identityStatus, attach, ref, cliReadsRemotes, rosterError?, unavailable?, readError? }`.
|
|
102
|
+
* `d`: `{ local, machine, sshHost?, probe?, identityStatus, attach, ref, cliReadsRemotes, rosterError?, unavailable?, readError?, readErrorOrigin? }`.
|
|
103
|
+
* `readError` is a kept failure's message and `readErrorOrigin` its speaker (deployment-facts.mjs
|
|
104
|
+
* `keptFailure`): a string, possibly empty, says the last read failed, whatever it holds. That answer
|
|
105
|
+
* alone also carries `headline`, `lead` and `sentence`, the parts `detail` joins (`lastReadFailed`).
|
|
70
106
|
* `terms`: the client's own (client-terms.mjs): its name where a sentence names it, and the label of its
|
|
71
107
|
* machine where `d` names none. */
|
|
72
108
|
export function deploymentReasonParts(d, terms) {
|
|
@@ -75,8 +111,8 @@ export function deploymentReasonParts(d, terms) {
|
|
|
75
111
|
const updateHere = ['Update OATS on this computer.'];
|
|
76
112
|
if (d.local) {
|
|
77
113
|
if (d.unavailable) return { short: 'Not observed', detail: d.unavailable, fix: [] };
|
|
78
|
-
// A re-read failed and the last observation was kept (
|
|
79
|
-
if (d.readError) return { short: 'Last read failed',
|
|
114
|
+
// A re-read failed and the last observation was kept (deployment-panel.mjs `failedEntry`): a string, whatever it holds.
|
|
115
|
+
if (typeof d.readError === 'string') return { short: 'Last read failed', ...lastReadFailed(d.readError, d.readErrorOrigin, terms), fix: [] };
|
|
80
116
|
if (d.identityStatus === 'feature') return { short: 'OATS here too old to report workspaces', detail: 'This computer\'s OATS is too old to report its workspace; update OATS here.', fix: updateHere };
|
|
81
117
|
if (d.identityStatus === 'old' || d.identityStatus === 'none') return { short: 'Reports no workspace', detail: 'This deployment reports no workspace identity.', fix: [] };
|
|
82
118
|
} else {
|
|
@@ -78,6 +78,27 @@ turn-record recall --reindex # full rebuild of the derived in
|
|
|
78
78
|
```
|
|
79
79
|
|
|
80
80
|
Store root: `--root`, else `$TURN_RECORD_ROOT`, else `~/.turn-record`.
|
|
81
|
+
|
|
82
|
+
**The `node` that `setup` writes down.** The hooks and the watcher's unit name
|
|
83
|
+
a `node` by its path, and only `setup` run again rewrites them. Which path
|
|
84
|
+
depends on how it is run:
|
|
85
|
+
|
|
86
|
+
- **`oats setup`** records a path that survives an upgrade of Node where there
|
|
87
|
+
is one (on Homebrew the `opt` link, not the versioned keg), and warns when
|
|
88
|
+
there is none. The kernel works it out and hands it in as `OATS_NODE_BIN`.
|
|
89
|
+
- **`turn-record setup`**, run alone, has no such rule. It records
|
|
90
|
+
`OATS_NODE_BIN` when that is set to an absolute path, else the `node` it runs
|
|
91
|
+
under (`process.execPath`). On Homebrew that is the versioned keg, which
|
|
92
|
+
`brew upgrade node` removes: run `setup` again after an upgrade.
|
|
93
|
+
|
|
94
|
+
`--dry-run` prints the `node` it would record. The first capture pass always
|
|
95
|
+
runs under the `node` that runs `setup`.
|
|
96
|
+
|
|
97
|
+
Each path is written for what reads it: a shell word in the hook's command,
|
|
98
|
+
systemd's quoting in `ExecStart`, XML text in the launchd plist. A path of
|
|
99
|
+
plain characters is written bare. A run finds the hooks of an earlier run by
|
|
100
|
+
their shape, quoted or not, and replaces their command; a command it cannot
|
|
101
|
+
read as its own is left alone and a new hook is added beside it.
|
|
81
102
|
Stream owner: `--owner`, else `$TURN_RECORD_OWNER`, else the short hostname.
|
|
82
103
|
|
|
83
104
|
## Ignoring sessions and paths (privacy)
|
|
@@ -9,9 +9,11 @@
|
|
|
9
9
|
// unit on Linux (printed instructions elsewhere);
|
|
10
10
|
// 3. then runs the first capture pass (the expensive one) unless --dry-run.
|
|
11
11
|
//
|
|
12
|
-
// Everything is derived from the running install:
|
|
13
|
-
//
|
|
14
|
-
//
|
|
12
|
+
// Everything is derived from the running install: scripts resolved relative
|
|
13
|
+
// to this file, so it works from a global npm install, npx, or a repo
|
|
14
|
+
// checkout alike. The node written into the hooks and the service is the one
|
|
15
|
+
// handed in (OATS_NODE_BIN, which `oats setup` sets to a path that survives
|
|
16
|
+
// an upgrade of Node), else process.execPath: see recordedNode().
|
|
15
17
|
//
|
|
16
18
|
// --owner <name> stream owner (default: LocalHostName on macOS, hostname)
|
|
17
19
|
// --no-hooks skip step 1
|
|
@@ -21,7 +23,7 @@
|
|
|
21
23
|
import { execFileSync, spawnSync } from "node:child_process";
|
|
22
24
|
import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
|
|
23
25
|
import { homedir, hostname, platform } from "node:os";
|
|
24
|
-
import { dirname, join } from "node:path";
|
|
26
|
+
import { dirname, isAbsolute, join } from "node:path";
|
|
25
27
|
import { fileURLToPath } from "node:url";
|
|
26
28
|
|
|
27
29
|
// Config files deserve the same crash safety as the store's objects:
|
|
@@ -32,10 +34,90 @@ function writeFileAtomic(path, content) {
|
|
|
32
34
|
renameSync(tmp, path);
|
|
33
35
|
}
|
|
34
36
|
|
|
37
|
+
// The node written into what outlives this process: the hooks and the
|
|
38
|
+
// service. `oats setup` hands in the kernel's answer for a node that survives
|
|
39
|
+
// an upgrade of Node, as OATS_NODE_BIN; this package has no such rule of its
|
|
40
|
+
// own, so run alone it records the node it runs under. What runs at once (the
|
|
41
|
+
// first capture pass) runs under process.execPath whatever is recorded.
|
|
42
|
+
function recordedNode(env = process.env) {
|
|
43
|
+
const handed = env.OATS_NODE_BIN;
|
|
44
|
+
return typeof handed === "string" && isAbsolute(handed) ? handed : process.execPath;
|
|
45
|
+
}
|
|
46
|
+
|
|
35
47
|
const HERE = dirname(fileURLToPath(import.meta.url));
|
|
36
|
-
const NODE =
|
|
48
|
+
const NODE = recordedNode();
|
|
37
49
|
const CAPTURE = join(HERE, "capture.mjs");
|
|
38
50
|
|
|
51
|
+
// Each path is written for the reader it has: a shell (the hook's command),
|
|
52
|
+
// systemd (ExecStart) or an XML parser (the plist). A path of plain
|
|
53
|
+
// characters is written bare by all three, so the files of an install that
|
|
54
|
+
// needs no quoting do not change.
|
|
55
|
+
const SHELL_PLAIN = /^[A-Za-z0-9_./:@%+,-]+$/;
|
|
56
|
+
const SYSTEMD_PLAIN = /^[A-Za-z0-9_./:@+,-]+$/;
|
|
57
|
+
|
|
58
|
+
// A shell word: POSIX single quotes, a quote itself as '\''.
|
|
59
|
+
function shellWord(value) {
|
|
60
|
+
return SHELL_PLAIN.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
// The words of a command as /bin/sh reads them, for what setup writes: plain
|
|
64
|
+
// characters, single-quoted runs and \' for a quote, adjacent pieces joined
|
|
65
|
+
// into one word, words apart by spaces or tabs. null when the command holds
|
|
66
|
+
// anything else outside quotes (an expansion, an operator, a redirection, a
|
|
67
|
+
// double quote, a newline, which ends a command) or a quote left open: the
|
|
68
|
+
// shell would do more with it than run those words, so it is not read.
|
|
69
|
+
//
|
|
70
|
+
// Any character above U+007F is part of a word too, as an earlier setup
|
|
71
|
+
// wrote it bare in a path (shellWord now quotes it). bash, dash and zsh end
|
|
72
|
+
// a word only at a space, a tab, a newline or an operator, all ASCII, so a
|
|
73
|
+
// command of such words carries nothing a rewrite would lose. POSIX lets a
|
|
74
|
+
// shell end a word at any blank of its locale (U+3000, say): such a shell
|
|
75
|
+
// would see one more argument of the same command, which a rewrite does not
|
|
76
|
+
// lose either, so no character above U+007F is refused.
|
|
77
|
+
function shellWords(command) {
|
|
78
|
+
const words = [];
|
|
79
|
+
let word = null;
|
|
80
|
+
for (let i = 0; i < command.length; ) {
|
|
81
|
+
const c = command[i];
|
|
82
|
+
if (c === " " || c === "\t") {
|
|
83
|
+
if (word !== null) words.push(word);
|
|
84
|
+
word = null;
|
|
85
|
+
i++;
|
|
86
|
+
} else if (c === "'") {
|
|
87
|
+
const end = command.indexOf("'", i + 1);
|
|
88
|
+
if (end < 0) return null;
|
|
89
|
+
word = (word ?? "") + command.slice(i + 1, end);
|
|
90
|
+
i = end + 1;
|
|
91
|
+
} else if (c === "\\" && command[i + 1] === "'") {
|
|
92
|
+
word = (word ?? "") + "'";
|
|
93
|
+
i += 2;
|
|
94
|
+
} else if (SHELL_PLAIN.test(c) || c > "\x7F") {
|
|
95
|
+
word = (word ?? "") + c;
|
|
96
|
+
i++;
|
|
97
|
+
} else return null;
|
|
98
|
+
}
|
|
99
|
+
if (word !== null) words.push(word);
|
|
100
|
+
return words;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
// A word of a systemd command line: `%` is a specifier (`%%`), a
|
|
104
|
+
// double-quoted string protects spaces, backslash and double quote are
|
|
105
|
+
// escaped. In an argument `${VAR}` is substituted and a literal dollar is
|
|
106
|
+
// `$$`; the executable is not substituted, and `$$` there names another file.
|
|
107
|
+
// (systemd itself starts no executable whose path holds a quote or a
|
|
108
|
+
// backslash, however it is written: its refusal is what setup reports.)
|
|
109
|
+
function systemdWord(value, { argument = false } = {}) {
|
|
110
|
+
if (SYSTEMD_PLAIN.test(value)) return value;
|
|
111
|
+
let v = value.replace(/%/g, "%%").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
|
|
112
|
+
if (argument) v = v.replace(/\$/g, "$$$$");
|
|
113
|
+
return `"${v}"`;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// Text of an XML element.
|
|
117
|
+
function xmlText(value) {
|
|
118
|
+
return value.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
|
|
119
|
+
}
|
|
120
|
+
|
|
39
121
|
function parseArgs(argv) {
|
|
40
122
|
const args = {};
|
|
41
123
|
for (let i = 0; i < argv.length; i++) {
|
|
@@ -77,7 +159,7 @@ if (!/^[A-Za-z0-9._-]+$/.test(owner)) {
|
|
|
77
159
|
process.exit(2);
|
|
78
160
|
}
|
|
79
161
|
|
|
80
|
-
const hookCommand = `${NODE} ${CAPTURE} --owner ${owner} --quiet`;
|
|
162
|
+
const hookCommand = `${shellWord(NODE)} ${shellWord(CAPTURE)} --owner ${owner} --quiet`;
|
|
81
163
|
const HOOK = { type: "command", command: hookCommand, async: true, timeout: 120 };
|
|
82
164
|
|
|
83
165
|
console.log(`owner: ${owner}`);
|
|
@@ -120,10 +202,19 @@ function installHooks() {
|
|
|
120
202
|
// whole tokens) keep it from firing on unrelated hooks that merely
|
|
121
203
|
// mention similar words; when in doubt it errs toward appending a new
|
|
122
204
|
// group, never toward overwriting someone else's command.
|
|
205
|
+
//
|
|
206
|
+
// The tokens are the command's words as the shell reads them
|
|
207
|
+
// (shellWords), and only a command that reads whole that way can be
|
|
208
|
+
// ours: one that also carries a second command, an operator or a
|
|
209
|
+
// redirection would lose it when rewritten. It reads the quoted form and
|
|
210
|
+
// every command written before paths were quoted, except one with `=`,
|
|
211
|
+
// `~` or another ASCII character outside the plain set left bare in a
|
|
212
|
+
// path, or with a space in one, which was split.
|
|
123
213
|
const ours = (h) => {
|
|
124
214
|
if (h?.type !== "command") return false;
|
|
125
|
-
const tokens = String(h.command)
|
|
215
|
+
const tokens = shellWords(String(h.command));
|
|
126
216
|
return (
|
|
217
|
+
tokens !== null &&
|
|
127
218
|
tokens.length >= 2 &&
|
|
128
219
|
tokens[1].endsWith("/capture.mjs") &&
|
|
129
220
|
tokens.includes("--owner") &&
|
|
@@ -133,6 +224,8 @@ function installHooks() {
|
|
|
133
224
|
for (const event of ["Stop", "SessionEnd"]) {
|
|
134
225
|
const groups = (settings.hooks[event] = settings.hooks[event] ?? []);
|
|
135
226
|
let found = false;
|
|
227
|
+
// Every hook that is ours gets the current command and none is removed,
|
|
228
|
+
// two in one event included: the shape is not proof of ownership.
|
|
136
229
|
for (const group of groups) {
|
|
137
230
|
for (const hook of group.hooks ?? []) {
|
|
138
231
|
if (!ours(hook)) continue;
|
|
@@ -173,8 +266,8 @@ function installServiceDarwin() {
|
|
|
173
266
|
<string>${label}</string>
|
|
174
267
|
<key>ProgramArguments</key>
|
|
175
268
|
<array>
|
|
176
|
-
<string>${NODE}</string>
|
|
177
|
-
<string>${CAPTURE}</string>
|
|
269
|
+
<string>${xmlText(NODE)}</string>
|
|
270
|
+
<string>${xmlText(CAPTURE)}</string>
|
|
178
271
|
<string>--watch</string>
|
|
179
272
|
<string>--owner</string>
|
|
180
273
|
<string>${owner}</string>
|
|
@@ -186,9 +279,9 @@ function installServiceDarwin() {
|
|
|
186
279
|
<key>ThrottleInterval</key>
|
|
187
280
|
<integer>60</integer>
|
|
188
281
|
<key>StandardOutPath</key>
|
|
189
|
-
<string>${logPath}</string>
|
|
282
|
+
<string>${xmlText(logPath)}</string>
|
|
190
283
|
<key>StandardErrorPath</key>
|
|
191
|
-
<string>${logPath}</string>
|
|
284
|
+
<string>${xmlText(logPath)}</string>
|
|
192
285
|
</dict>
|
|
193
286
|
</plist>
|
|
194
287
|
`;
|
|
@@ -211,7 +304,7 @@ function installServiceDarwin() {
|
|
|
211
304
|
} else {
|
|
212
305
|
console.error(
|
|
213
306
|
`service: wrote ${path} but launchctl bootstrap failed (${(boot.stderr || "").trim()}); ` +
|
|
214
|
-
`load it manually: launchctl bootstrap gui/${uid} ${path}`,
|
|
307
|
+
`load it manually: launchctl bootstrap gui/${uid} ${shellWord(path)}`,
|
|
215
308
|
);
|
|
216
309
|
}
|
|
217
310
|
}
|
|
@@ -222,7 +315,7 @@ function installServiceLinux() {
|
|
|
222
315
|
Description=turn-record capture watcher
|
|
223
316
|
|
|
224
317
|
[Service]
|
|
225
|
-
ExecStart=${NODE} ${CAPTURE} --watch --owner ${owner}
|
|
318
|
+
ExecStart=${systemdWord(NODE)} ${systemdWord(CAPTURE, { argument: true })} --watch --owner ${owner}
|
|
226
319
|
Restart=always
|
|
227
320
|
RestartSec=60
|
|
228
321
|
|
|
@@ -262,7 +355,7 @@ function installService() {
|
|
|
262
355
|
else {
|
|
263
356
|
console.log(
|
|
264
357
|
`service: no service template for ${os}; run this in the background yourself:\n` +
|
|
265
|
-
` ${NODE} ${CAPTURE} --watch --owner ${owner}`,
|
|
358
|
+
` ${shellWord(NODE)} ${shellWord(CAPTURE)} --watch --owner ${owner}`,
|
|
266
359
|
);
|
|
267
360
|
}
|
|
268
361
|
}
|
|
@@ -276,6 +369,6 @@ if (dry) {
|
|
|
276
369
|
console.log("dry run: no first capture pass");
|
|
277
370
|
} else {
|
|
278
371
|
console.log("running first capture pass (the initial one can take minutes)...");
|
|
279
|
-
const pass = spawnSync(
|
|
372
|
+
const pass = spawnSync(process.execPath, [CAPTURE, "--owner", owner], { stdio: "inherit" });
|
|
280
373
|
process.exit(pass.status ?? 1);
|
|
281
374
|
}
|
package/packages/tui/README.md
CHANGED
|
@@ -4,12 +4,14 @@
|
|
|
4
4
|
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
|
-
**It is a preview.** This version
|
|
8
|
-
|
|
9
|
-
|
|
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, and follows
|
|
9
|
+
them; it changes nothing. While it is a preview its screens and its
|
|
10
|
+
configuration file may change without notice.
|
|
10
11
|
|
|
11
|
-
[`docs/tui.md`](../../docs/tui.md) is the reference: how to start it, the
|
|
12
|
-
the
|
|
12
|
+
[`docs/tui.md`](../../docs/tui.md) is the reference: how to start it, what the
|
|
13
|
+
view shows, the keys and how to change them, what it reads and runs, the
|
|
14
|
+
complete list of what it changes in the terminal and restores, and what it
|
|
13
15
|
never does.
|
|
14
16
|
|
|
15
17
|
## For developers
|
|
@@ -17,16 +19,20 @@ never does.
|
|
|
17
19
|
| path | contents |
|
|
18
20
|
|---|---|
|
|
19
21
|
| `bin/tui.mjs` | the entry `bin/oats.mjs` loads: it imports the whole module graph, then runs `main()` |
|
|
20
|
-
| `lib/main.mjs` | the
|
|
21
|
-
| `lib/actions.mjs` | the action table: the reducer and the help
|
|
22
|
-
| `lib/
|
|
22
|
+
| `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel) and the loop: events through `reduce`, effects out, the frame drawn |
|
|
23
|
+
| `lib/actions.mjs` | the action table and its default keys: the reducer, the footer and the help read the effective one |
|
|
24
|
+
| `lib/config.mjs` | `tui.json`: read once, checked, and the effective action table |
|
|
25
|
+
| `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
|
|
26
|
+
| `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 child, and the two looks at the file system the switcher needs (the entries of `~/Agents`, and whether a picked folder is a deployment) |
|
|
27
|
+
| `lib/store.mjs` | the state and `reduce(state, event)`: pure |
|
|
28
|
+
| `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 |
|
|
23
29
|
| `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock |
|
|
24
30
|
| `lib/term/width.mjs` | the cells a grapheme takes |
|
|
25
31
|
| `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
|
|
26
32
|
| `lib/term/style.mjs` | style values: the sixteen ANSI colours and four attributes |
|
|
27
33
|
| `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
|
|
28
34
|
| `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
|
|
29
|
-
| `lib/views/` | pure functions from
|
|
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 |
|
|
30
36
|
|
|
31
37
|
Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
32
38
|
|
|
@@ -36,11 +42,23 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
36
42
|
one dynamic import where `bin/oats.mjs` dispatches the word.
|
|
37
43
|
- Only `term/screen.mjs` and `term/tty.mjs` produce an ESC byte. Views are
|
|
38
44
|
pure: no IO, no clock, no escape bytes.
|
|
45
|
+
- No function of this package decodes a kernel answer, groups or orders
|
|
46
|
+
instances, or decides what a failed read means: `lib/model.mjs` and
|
|
47
|
+
`lib/read.mjs` call the shared readers and pass their answers on. A string
|
|
48
|
+
the shared readers give reaches the screen through `shown()`.
|
|
49
|
+
- The store holds no size and no cell: a key event carries the height of the
|
|
50
|
+
panes as the last frame drew them.
|
|
51
|
+
- Every child process runs in a session of its own and is ended on every way
|
|
52
|
+
out; this version starts only reads.
|
|
39
53
|
- The screen takes safe text only. Text the TUI did not write goes through
|
|
40
54
|
`shown()`; `lit()` is for the TUI's own words and refuses anything the
|
|
41
55
|
display filter would change, a run of spaces included, so a row is spans
|
|
42
56
|
placed by column, never one padded string.
|
|
43
57
|
|
|
44
|
-
Tests: `node --test packages/tui/test/*.test.mjs
|
|
45
|
-
|
|
46
|
-
|
|
58
|
+
Tests: `node --test packages/tui/test/*.test.mjs`, the root tests
|
|
59
|
+
`test/tui-*.test.mjs`, and the end-to-end tests in a real tmux on a private
|
|
60
|
+
socket (`test/tui-terminal.test.mjs`). All of them need the root's install
|
|
61
|
+
(`npm ci` at the repository root). The package has no dependency of its own,
|
|
62
|
+
but one of its tests runs the real kernel, which has: "KERNEL_BIN is this
|
|
63
|
+
install's own bin/oats.mjs, and its `version --json` is a record the probe
|
|
64
|
+
accepts" (`packages/tui/test/read.test.mjs`).
|
|
@@ -1,7 +1,22 @@
|
|
|
1
1
|
// The action table: what the TUI can do and the keys that do it. The reducer and the help view
|
|
2
2
|
// both read it, so the help cannot name a key the program does not act on. `keys` are key ids
|
|
3
|
-
// (term/keys.mjs keyId); they are the part a user's tui.json
|
|
3
|
+
// (term/keys.mjs keyId); they are the part a user's tui.json replaces (config.mjs), so everything
|
|
4
|
+
// that acts on a key or names one reads the EFFECTIVE table it is handed, never this constant.
|
|
4
5
|
export const ACTIONS = Object.freeze([
|
|
6
|
+
{ id: "up", keys: ["up", "k"], label: "up" },
|
|
7
|
+
{ id: "down", keys: ["down", "j"], label: "down" },
|
|
8
|
+
{ id: "top", keys: ["g", "home"], label: "first" },
|
|
9
|
+
{ id: "bottom", keys: ["G", "end"], label: "last" },
|
|
10
|
+
{ id: "page-up", keys: ["pageup"], label: "page up" },
|
|
11
|
+
{ id: "page-down", keys: ["pagedown"], label: "page down" },
|
|
12
|
+
{ id: "collapse", keys: ["left", "h"], label: "collapse, or go to the parent" },
|
|
13
|
+
{ id: "expand", keys: ["right", "l"], label: "expand, or go to the first child" },
|
|
14
|
+
{ id: "detail", keys: ["tab"], label: "detail" },
|
|
15
|
+
{ id: "filter", keys: ["/"], label: "filter" },
|
|
16
|
+
{ id: "refresh", keys: ["r"], label: "refresh" },
|
|
17
|
+
{ id: "instances", keys: ["1"], label: "instances" },
|
|
18
|
+
{ id: "workspaces", keys: ["w"], label: "workspaces" },
|
|
19
|
+
{ id: "open-workspace", keys: ["enter"], label: "open" },
|
|
5
20
|
{ id: "help", keys: ["?"], label: "help" },
|
|
6
21
|
{ id: "close", keys: ["escape"], label: "close" },
|
|
7
22
|
{ id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
|