@awebai/oats 0.51.0 → 0.53.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.
Files changed (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -0,0 +1,183 @@
1
+ /** Workspace views (#482): what the switcher lists and a window shows. One view per workspace
2
+ * identity `(key, default team)` its deployments report, matched by the kernel's rules
3
+ * (docs/desktop-cli-api.md, "Matching workspaces across machines" and "Matching teams across
4
+ * machines"), plus one view per deployment that cannot be matched, under that deployment's own id.
5
+ * Pure: no I/O. The identity is the kernel's `workspace` object, read as reported; nothing is
6
+ * derived from a path, a ref or a host name, and `ref` is never compared. */
7
+ import { createHash } from 'node:crypto';
8
+ import { requireTerms } from './client-terms.mjs';
9
+ import { displayLine, DETAIL_WITHHELD } from './display-text.mjs';
10
+ import { originLead } from './instance-presentation.mjs';
11
+
12
+ const TEXT_MAX = 2048;
13
+ const text = v => typeof v === 'string' && v.length > 0 && v.length <= TEXT_MAX && !v.includes('\0');
14
+ const record = v => !!v && typeof v === 'object' && !Array.isArray(v);
15
+
16
+ /** The identity fields of a reported `workspace` object, validated and copied, or a classification:
17
+ * `{ status: 'none' }` when nothing was reported (null, absent, not an object), `{ status: 'old' }`
18
+ * for a host before 0.36.0 (the reachability-only object has no `key` field), `{ status: 'invalid' }`
19
+ * for a shape the contract does not allow, else `{ status: 'identity', identity }`. */
20
+ export function readIdentity(workspace) {
21
+ if (!record(workspace)) return { status: 'none' };
22
+ if (!Object.hasOwn(workspace, 'key')) return { status: 'old' };
23
+ const { key, ref = null, keyFrom = null, standalone, defaultTeam = null, teams = {}, teamsFrom } = workspace;
24
+ const team = v => v === null || text(v);
25
+ const ok = (key === null || text(key)) && (ref === null || text(ref)) && [null, 'workspace', 'member'].includes(keyFrom)
26
+ && typeof standalone === 'boolean' && ['observed', 'cache', 'local'].includes(teamsFrom)
27
+ && (defaultTeam === null || record(defaultTeam) && text(defaultTeam.label) && team(defaultTeam.team))
28
+ && record(teams) && Object.keys(teams).length <= 256 && Object.entries(teams).every(([label, id]) => text(label) && team(id));
29
+ if (!ok) return { status: 'invalid' };
30
+ return { status: 'identity', identity: { key, ref, keyFrom, standalone, teamsFrom,
31
+ defaultTeam: defaultTeam && { label: defaultTeam.label, team: defaultTeam.team }, teams: { ...teams } } };
32
+ }
33
+
34
+ /** How one identity attaches, by the kernel's rules: `{ key, team, unmapped, note? }` (team null and
35
+ * unmapped true for an unmapped default team, which matches only unmapped), or `{ unattached }` with
36
+ * the reason's key. `note` is information, not a failure (a standalone deployment's local teams). */
37
+ export function attachment(identity) {
38
+ if (!identity) return { unattached: 'no-report' };
39
+ if (identity.keyFrom === 'member') return { unattached: 'member' };
40
+ if (identity.key === null || identity.keyFrom !== 'workspace') return { unattached: 'invalid-ref' };
41
+ const team = identity.defaultTeam?.team ?? null;
42
+ if (identity.teamsFrom === 'local' && !identity.standalone && team === null) return { unattached: 'unknown-team' };
43
+ return { key: identity.key, team, unmapped: team === null,
44
+ ...(identity.teamsFrom === 'local' && identity.standalone && team === null ? { note: 'standalone' } : {}) };
45
+ }
46
+
47
+ /** A stable view id for one `(key, team)`: never a path, so it cannot collide with a deployment id. */
48
+ export function viewId(key, team) {
49
+ return `ws:${createHash('sha256').update(JSON.stringify([key, team])).digest('hex').slice(0, 20)}`;
50
+ }
51
+
52
+ /** The kernel's own reason texts where docs/desktop-cli-api.md gives them, else the spec's: the full
53
+ * sentence, the short label (headings, the switcher) and the fix as plain steps. `there` names where
54
+ * the fix runs ("there" for a remote, "in this deployment" for a local one). */
55
+ const REASONS = {
56
+ member: ({ there }) => ({ short: 'Workspace not known yet', detail: 'This deployment\'s workspace reference names a member whose workspace isn\'t known yet; run oats sync there.', fix: [`Run \`oats sync\` ${there}.`] }),
57
+ 'invalid-ref': ({ ref }) => ({ short: 'Invalid workspace reference', detail: `This deployment's workspace reference${ref ? ` (${ref})` : ''} isn't valid; fix oats-local.yaml.`,
58
+ fix: [`Fix the workspace reference${ref ? ` (\`${ref}\`)` : ''} in its oats-local.yaml.`] }),
59
+ 'unknown-team': ({ there }) => ({ short: 'Workspace not observed yet', detail: 'This host hasn\'t observed its workspace yet; run oats sync there.', fix: [`Run \`oats sync\` ${there}.`] }),
60
+ standalone: () => ({ short: 'Local teams only', detail: 'Teams are local only on this host (standalone).', fix: [] }),
61
+ };
62
+
63
+ /** True when a failed probe's message is ssh's own timeout: the kernel reports an ssh that timed out
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). */
65
+ const TIMED_OUT = /timed out|timeout/i;
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
+
98
+ /** Why a deployment is not live or not matched, or null: `{ short, detail, fix }`. `short` is a few
99
+ * words for a heading or the switcher ("OATS too old to report its workspace"); `detail` the one full
100
+ * sentence; `fix` the plain steps (possibly none: the detail then says what happens next). The steps
101
+ * carry every fact the sentence has (a host, a reference): with steps, a heading shows only them.
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`).
106
+ * `terms`: the client's own (client-terms.mjs): its name where a sentence names it, and the label of its
107
+ * machine where `d` names none. */
108
+ export function deploymentReasonParts(d, terms) {
109
+ requireTerms(terms, 'deploymentReasonParts');
110
+ const machine = d.machine || terms.thisMachine;
111
+ const updateHere = ['Update OATS on this computer.'];
112
+ if (d.local) {
113
+ if (d.unavailable) return { short: 'Not observed', detail: d.unavailable, fix: [] };
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: [] };
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 };
117
+ if (d.identityStatus === 'old' || d.identityStatus === 'none') return { short: 'Reports no workspace', detail: 'This deployment reports no workspace identity.', fix: [] };
118
+ } else {
119
+ if (d.cliReadsRemotes === false) return { short: 'OATS here can\'t read other machines', detail: 'This computer\'s OATS can\'t read other machines; update OATS here.', fix: updateHere };
120
+ if (d.identityStatus === 'feature' && d.probe?.ok === true) return { short: 'OATS here too old to read workspaces', detail: 'This computer\'s OATS is too old to read other machines\' workspaces; update OATS here.', fix: updateHere };
121
+ if (d.rosterError) return { short: 'Not reached', detail: `${machine} was not reached: ${d.rosterError}`, fix: [] };
122
+ if (d.probe && d.probe.ok !== true) {
123
+ const code = d.probe.error?.code, message = typeof d.probe.error?.message === 'string' ? d.probe.error.message : '';
124
+ if (code === 'E_ROSTER_BUDGET' || code === 'E_CLI_TIMEOUT' || TIMED_OUT.test(message)) return { short: 'Timed out', detail: `${machine} timed out; it is tried again on the next read.`, fix: [] };
125
+ if (code === 'E_SSH') {
126
+ const host = d.sshHost || machine;
127
+ return { short: 'ssh needs a prompt', detail: `${machine} needs ssh to connect without a prompt; run \`ssh ${host}\` once in a terminal.`,
128
+ fix: [`Run \`ssh ${host}\` once in a terminal and answer its prompt (a host key or a password).`, `${terms.name} tries again on its next read.`] };
129
+ }
130
+ return { short: 'Not reached', detail: `${machine} was not reached${code ? ` (${code})` : ''}.`, fix: [] };
131
+ }
132
+ if (d.identityStatus === 'old') return { short: 'OATS too old to report its workspace', detail: `${machine}'s OATS is too old to report its workspace; update OATS there.`, fix: [`Update OATS on ${machine}.`] };
133
+ if (d.identityStatus === 'none') return { short: 'Reports no workspace', detail: `${machine} reports no workspace for this deployment.`, fix: [] };
134
+ }
135
+ if (d.identityStatus === 'invalid') return { short: 'Unreadable workspace report', detail: `${machine} reported a workspace ${terms.self} can't read.`, fix: [] };
136
+ const reason = d.attach?.unattached && REASONS[d.attach.unattached];
137
+ return reason ? reason({ ref: d.ref, there: d.local ? 'in this deployment' : `on ${machine}` }) : null;
138
+ }
139
+
140
+ /** The one plain sentence for a deployment that is not live or not matched, or null. */
141
+ export function deploymentReason(d, terms) {
142
+ requireTerms(terms, 'deploymentReason');
143
+ return deploymentReasonParts(d, terms)?.detail ?? null;
144
+ }
145
+
146
+ /** The last segment of a canonical key: github.com/GreaterSkies/tsm → tsm. */
147
+ const keyTail = key => String(key).split('/').filter(Boolean).pop() || String(key);
148
+
149
+ /** Build the views from the served deployments, in their served order (locals first, as given).
150
+ * `deployments`: `[{ id, local, name, attach }]` where `attach` comes from attachment().
151
+ * Returns `[{ id, name, key, team, teamLabel, unattached, deployments: [id…], primary }]`: attached
152
+ * views first in order of their first deployment, then one view per unattached deployment, under
153
+ * its deployment id (today's id, so nothing saved breaks). */
154
+ export function buildViews(deployments) {
155
+ const attached = new Map(), loose = [];
156
+ for (const d of deployments) {
157
+ if (!d.attach || d.attach.unattached) { loose.push(d); continue; }
158
+ const id = viewId(d.attach.key, d.attach.team);
159
+ if (!attached.has(id)) attached.set(id, { id, key: d.attach.key, team: d.attach.team, teamLabel: d.teamLabel ?? null, members: [] });
160
+ attached.get(id).members.push(d);
161
+ }
162
+ const views = [...attached.values()].map(v => {
163
+ const primary = v.members.find(d => d.local) || v.members[0];
164
+ const localName = v.members.find(d => d.local && d.name)?.name;
165
+ return { id: v.id, name: localName || keyTail(v.key), key: v.key, team: v.team, teamLabel: v.teamLabel,
166
+ unattached: false, deployments: v.members.map(d => d.id), primary: primary.id };
167
+ });
168
+ // The same key with another team is another workspace: both names say which team.
169
+ const byKey = new Map();
170
+ for (const v of views) byKey.set(v.key, [...(byKey.get(v.key) || []), v]);
171
+ for (const same of byKey.values()) {
172
+ if (same.length < 2) continue;
173
+ const labels = same.map(v => v.teamLabel);
174
+ for (const v of same) {
175
+ const label = v.team === null ? 'unmapped'
176
+ : v.teamLabel && labels.filter(l => l === v.teamLabel).length === 1 ? v.teamLabel : v.team;
177
+ v.name = `${v.name} · ${label}`;
178
+ }
179
+ }
180
+ for (const v of views) delete v.teamLabel;
181
+ for (const d of loose) views.push({ id: d.id, name: d.name || d.id, key: null, team: null, unattached: true, deployments: [d.id], primary: d.id });
182
+ return views;
183
+ }
@@ -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: node = process.execPath,
13
- // scripts resolved relative to this file, so it works from a global npm
14
- // install, npx, or a repo checkout alike.
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 = process.execPath;
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, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
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).trim().split(/\s+/);
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(NODE, [CAPTURE, "--owner", owner], { stdio: "inherit" });
372
+ const pass = spawnSync(process.execPath, [CAPTURE, "--owner", owner], { stdio: "inherit" });
280
373
  process.exit(pass.status ?? 1);
281
374
  }
@@ -0,0 +1,64 @@
1
+ # OATS TUI (preview)
2
+
3
+ `oats tui` is the OATS terminal client: one full-screen, keyboard-only program
4
+ for people who work in terminals and on machines with no display. It ships
5
+ inside `@awebai/oats` and is never published on its own.
6
+
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.
11
+
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
15
+ never does.
16
+
17
+ ## For developers
18
+
19
+ | path | contents |
20
+ |---|---|
21
+ | `bin/tui.mjs` | the entry `bin/oats.mjs` loads: it imports the whole module graph, then runs `main()` |
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 |
29
+ | `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock |
30
+ | `lib/term/width.mjs` | the cells a grapheme takes |
31
+ | `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
32
+ | `lib/term/style.mjs` | style values: the sixteen ANSI colours and four attributes |
33
+ | `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
+
37
+ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
38
+
39
+ - No dependency, and no import outside `node:` modules, this package and the
40
+ one path in `lib/client.mjs`. No dynamic `import()`.
41
+ - Nothing in `lib/` or `bin/` of the kernel imports this package, except the
42
+ one dynamic import where `bin/oats.mjs` dispatches the word.
43
+ - Only `term/screen.mjs` and `term/tty.mjs` produce an ESC byte. Views are
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.
53
+ - The screen takes safe text only. Text the TUI did not write goes through
54
+ `shown()`; `lit()` is for the TUI's own words and refuses anything the
55
+ display filter would change, a run of spaces included, so a row is spans
56
+ placed by column, never one padded string.
57
+
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`).
@@ -0,0 +1,7 @@
1
+ // The entry of `oats tui`, loaded by bin/oats.mjs with one dynamic import.
2
+ // The import below loads every module of packages/tui/lib/ statically, BEFORE the terminal is
3
+ // looked at: `oats tui` with no terminal therefore proves that the installed package holds the
4
+ // whole module graph (scripts/clean-room-smoke.mjs runs exactly that).
5
+ import { main } from "../lib/main.mjs";
6
+
7
+ process.exitCode = await main({ argv: process.argv.slice(2), stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, env: process.env });
@@ -0,0 +1,44 @@
1
+ // The action table: what the TUI can do and the keys that do it. The reducer and the help view
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 replaces (config.mjs), so everything
4
+ // that acts on a key or names one reads the EFFECTIVE table it is handed, never this constant.
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" },
20
+ { id: "help", keys: ["?"], label: "help" },
21
+ { id: "close", keys: ["escape"], label: "close" },
22
+ { id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
23
+ { id: "suspend", keys: ["ctrl+z"], label: "suspend" },
24
+ { id: "redraw", keys: ["ctrl+l"], label: "redraw" },
25
+ ].map((action) => Object.freeze({ ...action, keys: Object.freeze([...action.keys]) })));
26
+
27
+ /** key id -> action id. A key bound twice is a defect of the table, refused when it is read. */
28
+ export function bindings(actions = ACTIONS) {
29
+ const map = new Map();
30
+ for (const action of actions) for (const key of action.keys) {
31
+ if (map.has(key)) throw new Error(`key ${key} is bound to ${map.get(key)} and to ${action.id}`);
32
+ map.set(key, action.id);
33
+ }
34
+ return map;
35
+ }
36
+
37
+ const NAMES = Object.freeze({ escape: "Esc", enter: "Enter", tab: "Tab", backspace: "Backspace", space: "Space", up: "Up", down: "Down", left: "Left", right: "Right", home: "Home", end: "End", pageup: "PageUp", pagedown: "PageDown", insert: "Insert", delete: "Delete", ctrl: "Ctrl", alt: "Alt", shift: "Shift" });
38
+ /** A key id as a person reads it: `ctrl+c` is `Ctrl+C`, `escape` is `Esc`, `?` is `?`. */
39
+ export function keyLabel(key) {
40
+ if (key.length === 1) return key;
41
+ const parts = key.split("+"), last = parts.pop();
42
+ const name = NAMES[last] ?? (/^f\d+$/.test(last) ? last.toUpperCase() : parts.length && last.length === 1 ? last.toUpperCase() : last);
43
+ return [...parts.map((part) => NAMES[part] ?? part), name].join("+");
44
+ }
@@ -0,0 +1,35 @@
1
+ // The ONE module of packages/tui/ that imports the shared client home (packages/client/): the rest
2
+ // of the TUI names no reader path, so what the TUI takes from the shared readers is this list
3
+ // (test/tui-boundary.test.mjs pins it). Every function here is the Desktop's own, never a copy:
4
+ // the roster, its order, its words and what a failed read becomes are decided there, once, for
5
+ // both clients. test/client-boundary.test.mjs holds each name to the home's stable surface.
6
+ import { fileURLToPath } from "node:url";
7
+ import { clientTerms } from "../../client/client-terms.mjs";
8
+
9
+ export { displayLine, DETAIL_WITHHELD } from "../../client/display-text.mjs";
10
+ export { parseProbeStdout, acceptProbe, cliRecord } from "../../client/cli-locator.mjs";
11
+ export { cliDeploymentRead } from "../../client/deployment-read-cli.mjs";
12
+ export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
13
+ export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
14
+ export { createRefreshLoop } from "../../client/refresh-loop.mjs";
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";
17
+ export { remoteRosterState } from "../../client/remote-roster.mjs";
18
+ export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
19
+ export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
20
+ export { shortPath } from "../../client/deployment-label.mjs";
21
+ export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome } from "../../client/instance-tree.mjs";
22
+ export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
23
+ export { runtimeState, runtimeCounts, originLead } from "../../client/instance-presentation.mjs";
24
+ export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
25
+ export { instanceActs } from "../../client/instance-acts.mjs";
26
+ export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
27
+ export { validateWorkspace, deploymentsInside } from "../../client/workspace-admission.mjs";
28
+
29
+ /** The words a shared sentence uses where it names the client that shows it (client-terms.mjs).
30
+ * Made once, here: every shared function that takes `terms` is passed this constant, and refuses
31
+ * anything else. */
32
+ export const TERMS = clientTerms({ name: "oats tui", self: "oats tui", selfInitial: "oats tui", update: "OATS", thisMachine: "This machine" });
33
+
34
+ /** The liveness collector, a program of the shared home: started as a child, never imported. */
35
+ export const COLLECTOR = fileURLToPath(new URL("../../client/liveness-main.mjs", import.meta.url));