@awebai/oats 0.51.0 → 0.52.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 (128) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +109 -37
  3. package/docs/capabilities.md +9 -2
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +927 -92
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +144 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +66 -9
  12. package/docs/integrations.md +9 -8
  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/oats-local.schema.json +4 -3
  20. package/docs/official-catalog.md +4 -4
  21. package/docs/packages.md +14 -14
  22. package/docs/release-lane.md +15 -5
  23. package/docs/release-notes/v0.44.0.md +1 -1
  24. package/docs/release-notes/v0.52.0.md +933 -0
  25. package/docs/schedules.md +91 -4
  26. package/docs/souls-and-instances.md +95 -25
  27. package/docs/tui.md +152 -0
  28. package/docs/workspaces.md +2 -2
  29. package/lib/claim.mjs +186 -46
  30. package/lib/core.mjs +730 -185
  31. package/lib/errors.mjs +170 -0
  32. package/lib/harness-trust-write.mjs +68 -27
  33. package/lib/harness-trust.mjs +34 -16
  34. package/lib/instance-inspect.mjs +40 -11
  35. package/lib/instance-lifecycle.mjs +169 -47
  36. package/lib/launch-preference.mjs +16 -0
  37. package/lib/launch-prompt-completion.mjs +7 -43
  38. package/lib/launch-prompt-evidence.mjs +14 -7
  39. package/lib/launch-prompt-fixtures/README.md +86 -152
  40. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  41. package/lib/launch-prompt-fixtures.mjs +122 -109
  42. package/lib/launch-prompt-transport.mjs +2 -56
  43. package/lib/launch-prompts.mjs +102 -100
  44. package/lib/schedule-host.mjs +154 -22
  45. package/lib/schedule.mjs +73 -24
  46. package/lib/system-tools.mjs +39 -0
  47. package/lib/tmux-server-scope.mjs +62 -0
  48. package/lib/triggers.mjs +4 -4
  49. package/lib/workspace.mjs +5 -11
  50. package/lib/worktree-hooks.mjs +98 -20
  51. package/lib/worktree.mjs +83 -24
  52. package/package-catalog.json +3 -3
  53. package/package.json +7 -2
  54. package/packages/client/capability-show-contract.mjs +230 -0
  55. package/packages/client/capability-warnings-contract.mjs +57 -0
  56. package/packages/client/cli-adapter.mjs +548 -0
  57. package/packages/client/cli-environment.mjs +53 -0
  58. package/packages/client/cli-locator.mjs +253 -0
  59. package/packages/client/cli-probe-contract.mjs +47 -0
  60. package/packages/client/client-terms.mjs +60 -0
  61. package/packages/client/deployment-contract.mjs +68 -0
  62. package/packages/client/deployment-data.mjs +483 -0
  63. package/packages/client/deployment-facts.mjs +34 -0
  64. package/packages/client/deployment-label.mjs +76 -0
  65. package/packages/client/deployment-observer.mjs +89 -0
  66. package/packages/client/deployment-panel.mjs +142 -0
  67. package/packages/client/deployment-read-cli.mjs +53 -0
  68. package/packages/client/display-text.mjs +44 -0
  69. package/packages/client/harness-names.mjs +30 -0
  70. package/packages/client/inspect-contract.mjs +62 -0
  71. package/packages/client/instance-acts.mjs +54 -0
  72. package/packages/client/instance-admission.mjs +45 -0
  73. package/packages/client/instance-events-contract.mjs +74 -0
  74. package/packages/client/instance-git-contract.mjs +80 -0
  75. package/packages/client/instance-presentation.mjs +22 -0
  76. package/packages/client/instance-tree.mjs +453 -0
  77. package/packages/client/kernel-environment.mjs +11 -0
  78. package/packages/client/launch-contract.mjs +51 -0
  79. package/packages/client/launch-prompt-outcome.mjs +165 -0
  80. package/packages/client/lifecycle-cli.mjs +61 -0
  81. package/packages/client/lifecycle-contract.mjs +372 -0
  82. package/packages/client/liveness-main.mjs +10 -0
  83. package/packages/client/liveness.mjs +35 -0
  84. package/packages/client/machine-contract.mjs +123 -0
  85. package/packages/client/own-environment.mjs +22 -0
  86. package/packages/client/panel-views.mjs +286 -0
  87. package/packages/client/readiness-contract.mjs +172 -0
  88. package/packages/client/refresh-loop.mjs +52 -0
  89. package/packages/client/remote-address.mjs +126 -0
  90. package/packages/client/remote-roster.mjs +67 -0
  91. package/packages/client/roster-sections.mjs +80 -0
  92. package/packages/client/spawn-apply-cli.mjs +104 -0
  93. package/packages/client/spawn-apply-contract.mjs +183 -0
  94. package/packages/client/spawn-decision.mjs +46 -0
  95. package/packages/client/spawn-messages.mjs +119 -0
  96. package/packages/client/spawn-preview-cli.mjs +32 -0
  97. package/packages/client/spawn-preview-contract.mjs +314 -0
  98. package/packages/client/team-members.mjs +41 -0
  99. package/packages/client/team-rows.mjs +45 -0
  100. package/packages/client/terminal-contract.mjs +57 -0
  101. package/packages/client/tmux-status.mjs +66 -0
  102. package/packages/client/waiting-on-you.mjs +88 -0
  103. package/packages/client/workspace-admission.mjs +45 -0
  104. package/packages/client/workspace-cli.mjs +142 -0
  105. package/packages/client/workspace-views.mjs +147 -0
  106. package/packages/tui/README.md +46 -0
  107. package/packages/tui/bin/tui.mjs +7 -0
  108. package/packages/tui/lib/actions.mjs +29 -0
  109. package/packages/tui/lib/client.mjs +4 -0
  110. package/packages/tui/lib/main.mjs +105 -0
  111. package/packages/tui/lib/term/keys.mjs +323 -0
  112. package/packages/tui/lib/term/screen.mjs +122 -0
  113. package/packages/tui/lib/term/style.mjs +43 -0
  114. package/packages/tui/lib/term/text.mjs +49 -0
  115. package/packages/tui/lib/term/tty.mjs +168 -0
  116. package/packages/tui/lib/term/width.mjs +124 -0
  117. package/packages/tui/lib/views/frame.mjs +62 -0
  118. package/packages/tui/lib/views/help.mjs +28 -0
  119. package/packages/tui/package.json +8 -0
  120. package/skills/oats-getting-started/SKILL.md +29 -22
  121. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  122. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  123. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  124. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  127. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  128. package/lib/launch-prompt-policy.mjs +0 -87
@@ -0,0 +1,483 @@
1
+ /** Native kernel JSON → bounded public observations. This module has no I/O.
2
+ * It does not resolve a deployment, read metadata, infer drift, or reproduce
3
+ * any kernel lifecycle/trust logic. Producer shapes remain command-specific. */
4
+ import { dirname, basename, join, isAbsolute, resolve } from 'node:path';
5
+ import { deploymentRecord as record } from './deployment-contract.mjs';
6
+ import { harnessOf } from './harness-names.mjs';
7
+ import { teamRow, teamRowsOf, defaultTeamOf, TEAM_ID } from './team-rows.mjs';
8
+ import { launchOf, REPORT_FROM } from './launch-contract.mjs';
9
+ import { readIdentity } from './workspace-views.mjs';
10
+ import { waitingOnYouData } from './waiting-on-you.mjs';
11
+ const text = value => typeof value === 'string' && value.length <= 8192 && !value.includes('\0');
12
+ const absolute = value => text(value) && isAbsolute(value) && resolve(value) === value;
13
+ const own = (value, key) => Object.hasOwn(value, key);
14
+ const bad = (code = 'E_CLI_PROTOCOL') => { throw Object.assign(new Error(code), { code }); };
15
+ const check = (condition, code) => { if (!condition) bad(code); };
16
+ const array = (value, limit = 2000) => { check(Array.isArray(value) && value.length <= limit); return value; };
17
+ const strings = value => array(value).map(v => { check(text(v)); return v; });
18
+ function fields(value, names) {
19
+ check(record(value));
20
+ const out = {};
21
+ for (const key of names) if (own(value, key)) { check(value[key] === null || text(value[key])); out[key] = value[key]; }
22
+ return out;
23
+ }
24
+ /** The row's harness (`harness`, or a released kernel's `runtime`), validated like fields(). */
25
+ function withHarness(value, out) {
26
+ const harness = harnessOf(value);
27
+ if (harness !== undefined) { check(harness === null || text(harness)); out.harness = harness; }
28
+ return out;
29
+ }
30
+ function flags(value, names, into) {
31
+ for (const key of names) if (own(value, key)) { check(typeof value[key] === 'boolean'); into[key] = value[key]; }
32
+ return into;
33
+ }
34
+ /* Desktop facts (feature desktop-facts, kernel #217): additive fields, projected when reported. */
35
+ const fileRef = value => value === null ? null : fields(value, ['path', 'url']);
36
+ const problemRef = value => value === null ? null : fields(value, ['code', 'message']);
37
+ function nameRows(value) {
38
+ return array(value, 500).map(row => { const out = fields(row, ['name', 'from']); check(text(out.name)); flags(row, ['off'], out); return out; });
39
+ }
40
+ function defaultsFacts(value) {
41
+ // defaults.byTeam is 0.29's; team model v2 (0.30) drops it, so it is optional (absent stays absent).
42
+ const hasByTeam = own(value, 'byTeam');
43
+ check(record(value) && record(value.slots) && (!hasByTeam || record(value.byTeam)) && Object.keys(value.slots).length <= 64 && (!hasByTeam || Object.keys(value.byTeam).length <= 256));
44
+ const slots = Object.fromEntries(Object.entries(value.slots).map(([slot, v]) => {
45
+ check(text(slot) && slot.length > 0);
46
+ return [slot, v === null || v === 'none' ? v : fields(v, ['name', 'from'])];
47
+ }));
48
+ if (!hasByTeam) return { slots, capabilities: nameRows(value.capabilities) };
49
+ const byTeam = Object.fromEntries(Object.entries(value.byTeam).map(([label, v]) => { check(text(label) && label.length > 0 && record(v)); return [label, { capabilities: nameRows(v.capabilities) }]; }));
50
+ return { slots, capabilities: nameRows(value.capabilities), byTeam };
51
+ }
52
+ function cloneRow(row) {
53
+ const out = fields(row, ['key', 'name']); check(text(out.key));
54
+ check(row.path === null || absolute(row.path)); out.path = row.path;
55
+ check(row.rule === null || row.rule === 'clones' || row.rule === 'convention'); out.rule = row.rule;
56
+ if (own(row, 'problem')) out.problem = problemRef(row.problem);
57
+ return out;
58
+ }
59
+ function lockFact(value) {
60
+ check(record(value) && absolute(value.path) && Number.isSafeInteger(value.lockfileVersion));
61
+ return { path: value.path, lockfileVersion: value.lockfileVersion };
62
+ }
63
+ function source(value) {
64
+ return fields(value, ['kind', 'package', 'version', 'commit', 'integrity', 'repoKey']);
65
+ }
66
+ function soulSource(value) {
67
+ return value === null ? null : fields(value, ['repoKey', 'commit', 'current', 'status', 'path']);
68
+ }
69
+ function modules(value) {
70
+ if (Array.isArray(value)) return array(value).map(row => {
71
+ const out = fields(row, ['name', 'commit', 'status', 'reason']);
72
+ check(text(row.name) && row.name.length > 0);
73
+ if (own(row, 'from')) out.from = source(row.from);
74
+ if (own(row, 'current')) out.current = row.current === null ? null : fields(row.current, ['commit', 'version']);
75
+ return out;
76
+ });
77
+ // Native v2's offline result is the recorded map, NOT live drift rows.
78
+ // Preserve that distinction; never fabricate "current" or convert it into
79
+ // a claimed online observation just because a commit was recorded.
80
+ check(record(value)); check(Object.keys(value).length <= 2000);
81
+ return Object.fromEntries(Object.entries(value).map(([name, row]) => {
82
+ check(text(name) && name.length > 0);
83
+ const out = fields(row, ['commit', 'digest', 'materializedAt']);
84
+ if (own(row, 'from')) out.from = source(row.from);
85
+ return [name, out];
86
+ }));
87
+ }
88
+ function servedIdentity(value) {
89
+ if (value === null) return null;
90
+ const out = fields(value, ['mode', 'alias', 'team', 'address', 'resident', 'provider']);
91
+ if (own(value, 'grant')) {
92
+ out.grant = fields(value.grant, ['id', 'expiresAt']);
93
+ if (own(value.grant, 'scopes')) out.grant.scopes = strings(value.grant.scopes);
94
+ }
95
+ return out;
96
+ }
97
+ function recordedWorkspace(value) {
98
+ const out = fields(value, ['key', 'commit', 'resolution']);
99
+ flags(value, ['standalone'], out);
100
+ if (own(value, 'soul')) out.soul = fields(value.soul, ['id', 'repoKey', 'commit', 'team']);
101
+ return out;
102
+ }
103
+
104
+ /** workspace status is the sole header authority (lock current / out of
105
+ * date). Declaring a package in `packages:` is the trust decision, so there
106
+ * is no approval state to read. No inspect.scope dependency. */
107
+ export function workspaceStatusData(document, deployment) {
108
+ check(absolute(deployment), 'E_BAD_ARGS');
109
+ check(record(document) && document.schemaVersion === 1 && document.ok === true);
110
+ const data = document.result;
111
+ check(record(data) && data.workspaceStatusApi === 1);
112
+ check(record(data.workspace) && absolute(data.workspace.local));
113
+ check(data.workspace.local === join(deployment, 'oats-local.yaml'), 'E_DEPLOYMENT_SCOPE');
114
+ const workspace = fields(data.workspace, ['name', 'key', 'url', 'commit', 'observedAt', 'local']);
115
+ check(text(workspace.name) && text(workspace.key));
116
+ if (own(data.workspace, 'teams')) {
117
+ // 0.29: the declared labels (strings). Team model v2 (0.30): the committed SHARED teams as rows
118
+ // {label, team: <id>|null, description|null}; `teams` stays the labels (what Setup lists) and
119
+ // the rows travel as `sharedTeams`. A mixed or malformed list fails the read.
120
+ const rows = array(data.workspace.teams, 256);
121
+ if (rows.every(r => typeof r === 'string')) workspace.teams = strings(rows);
122
+ else {
123
+ workspace.sharedTeams = rows.map(r => { const out = fields(r, ['label', 'team', 'description']); check(TEAM_LABEL.test(out.label ?? '')); return out; });
124
+ check(new Set(workspace.sharedTeams.map(r => r.label)).size === rows.length);
125
+ workspace.teams = workspace.sharedTeams.map(r => r.label);
126
+ }
127
+ }
128
+ if (own(data.workspace, 'file')) workspace.file = fileRef(data.workspace.file);
129
+ const members = array(data.members).map(memberRow);
130
+ const packages = array(data.packages).map(packageRow);
131
+ const facts = {};
132
+ if (own(data, 'defaults')) facts.defaults = defaultsFacts(data.defaults);
133
+ if (own(data, 'clones')) facts.clones = array(data.clones).map(cloneRow);
134
+ if (own(data, 'disabledSouls')) facts.disabledSouls = strings(data.disabledSouls);
135
+ if (own(data, 'lock')) facts.lock = lockFact(data.lock);
136
+ return flags(data, ['standalone'], { workspaceStatusApi: 1, workspace, members, packages, ...facts,
137
+ declaredPackages: strings(data.declaredPackages), unsynced: strings(data.unsynced), stale: strings(data.stale),
138
+ external: array(data.external).map(row => fields(row, ['source', 'soul', 'team'])),
139
+ problems: problemRows(data.problems), // warnings[] since kernel #185 (for example an unmapped team label); absent before.
140
+ // 0.30 automation trust adds automation-untrusted {kind, id, remedy} and automation-trust-stale {entry}.
141
+ warnings: own(data, 'warnings') ? array(data.warnings).map(warningRow) : [] });
142
+ }
143
+ /** One workspace warning. 0.49.0's hook-event-unsupported adds `capability` and `path`: kept when text, else
144
+ * dropped, never refusing the status (the earlier keys stay strict). */
145
+ function warningRow(row) {
146
+ const out = fields(row, ['code', 'message', 'label', 'soul', 'repoKey', 'kind', 'id', 'remedy', 'entry']);
147
+ for (const key of ['capability', 'path']) if (text(row[key])) out[key] = row[key];
148
+ return out;
149
+ }
150
+
151
+ /** The kernel's observation provenance (feature observe-max-age): `observation` sits at the
152
+ * top of the raw `status` object and under `result` in a schemaVersion:1 envelope; its shape
153
+ * is {observedAt: ISO-8601, reused: boolean}, reported whenever --max-age was passed (0 included).
154
+ * Absent, or present but malformed, projects as nulls: the stamp is provenance beside the
155
+ * result, never the result, so a bad stamp must not cost the roster or the document — the
156
+ * caller falls back to the time its read completed (maintainer's contract decision). */
157
+ export function observationData(document) {
158
+ const holder = record(document) ? (document.schemaVersion === 1 ? document.result : document) : null;
159
+ const value = record(holder) ? holder.observation : undefined;
160
+ const sound = record(value) && typeof value.observedAt === 'string' && value.observedAt.length <= 64 && !Number.isNaN(Date.parse(value.observedAt))
161
+ && typeof value.reused === 'boolean';
162
+ return sound ? { observedAt: value.observedAt, reused: value.reused } : { observedAt: null, reused: null };
163
+ }
164
+
165
+ /** status stays a native {root,agents,workspace} observation. No task/state
166
+ * parsing, file counts, runtime defaults, metadata hydration or v1 card DTO.
167
+ * Liveness here is the kernel's report; terminal-target observation is a
168
+ * separate v2-agnostic Desktop concern. */
169
+ const inside = (path, parent) => path.startsWith(parent.endsWith('/') ? parent : parent + '/');
170
+ /** A Herdr-recorded row's sessionTarget, reduced to what recognises it as unsupported.
171
+ * Nothing connects with it, so no socket, pane or terminal id is forwarded. */
172
+ function sessionTarget(value) {
173
+ return fields(value, ['backend']);
174
+ }
175
+ export function deploymentStatusData(document, deployment) {
176
+ check(absolute(deployment), 'E_BAD_ARGS'); check(record(document));
177
+ check(document.root === join(deployment, 'agents'), 'E_DEPLOYMENT_SCOPE');
178
+ const root = document.root;
179
+ const seenHomes = new Set(), seenSouls = new Set(), withheld = [];
180
+ const agents = array(document.agents).map(agent => {
181
+ check(record(agent) && text(agent.name) && agent.name.length > 0 && absolute(agent.dir));
182
+ // Every soul directory the kernel reports must belong to the selected
183
+ // deployment. The Desktop does not name or search any layout itself.
184
+ check(inside(agent.dir, deployment), 'E_DEPLOYMENT_SCOPE');
185
+ check(!seenSouls.has(agent.dir)); seenSouls.add(agent.dir);
186
+ const out = withHarness(agent, fields(agent, ['name', 'description', 'work', 'model', 'backend', 'team', 'dir', 'kind', 'repo', 'capability', 'color', 'launch-config']));
187
+ if (own(agent, 'yolo')) { check(agent.yolo === null || typeof agent.yolo === 'boolean'); out.yolo = agent.yolo; }
188
+ // The kernel's soul key, or null when no instance records a workspace soul (an instance-less
189
+ // soul dir, e.g. after a preview or its last retire): the roster contract allows both.
190
+ if (own(agent, 'key')) { check(agent.key === null || soulKey(agent.key)); out.key = agent.key; }
191
+ if (own(agent, 'soulSource')) out.soulSource = soulSource(agent.soulSource);
192
+ if (own(agent, 'retireFailures')) out.retireFailures = array(agent.retireFailures).map(row => fields(row, ['instance', 'completedAt', 'error', 'resultPath']));
193
+ out.instances = array(agent.instances, 10000).flatMap(instance => {
194
+ check(record(instance) && text(instance.instance) && instance.instance.length > 0 && absolute(instance.home));
195
+ // A row whose reported home is not <soul dir>/instances/<instance>, or
196
+ // that repeats another row's home, is WITHHELD — never acted on, never
197
+ // silently dropped: the count and reason reach the header.
198
+ if (dirname(instance.home) !== join(agent.dir, 'instances') || basename(instance.home) !== instance.instance) {
199
+ withheld.push({ agent: agent.name, instance: instance.instance, reason: 'home-outside-soul' }); return [];
200
+ }
201
+ if (seenHomes.has(instance.home)) { withheld.push({ agent: agent.name, instance: instance.instance, reason: 'duplicate-home' }); return []; }
202
+ check(seenHomes.size < 10000); seenHomes.add(instance.home);
203
+ const row = withHarness(instance, fields(instance, ['instance', 'agent', 'home', 'repo', 'work', 'branch', 'model', 'createdAt',
204
+ 'parentInstance', 'siblingInstance', 'relation', 'relativeTo', 'runtimeState', 'runtimeError', 'spawnOrigin', 'capability',
205
+ 'startedAt', 'modelFrom', 'identityAddress']));
206
+ for (const key of ['running', 'launched', 'captured']) if (own(instance, key)) {
207
+ check(instance[key] === null || typeof instance[key] === 'boolean'); row[key] = instance[key];
208
+ }
209
+ if (own(instance, 'tmux')) row.tmux = instance.tmux === null ? null : fields(instance.tmux, ['session', 'window', 'socket']);
210
+ if (own(instance, 'sessionTarget')) row.sessionTarget = sessionTarget(instance.sessionTarget);
211
+ if (own(instance, 'retirePending')) row.retirePending = true;
212
+ if (own(instance, 'rollbackIncomplete')) row.rollbackIncomplete = true;
213
+ // #802 (feature worktree-event): a spawn running its worktree hooks, verifiably alive. Boolean true only;
214
+ // any other value is dropped, never checked: the row stays an ordinary one.
215
+ if (own(instance, 'spawnInProgress') && instance.spawnInProgress === true) row.spawnInProgress = true;
216
+ if (own(instance, 'modules')) row.modules = modules(instance.modules);
217
+ if (own(instance, 'soul')) row.soul = soulSource(instance.soul);
218
+ if (own(instance, 'workspace')) row.workspace = recordedWorkspace(instance.workspace);
219
+ // Missing identity is the producer's absent fact, not a fabricated null
220
+ // principal or a name/address guessed from the instance/soul.
221
+ if (own(instance, 'identity')) row.identity = servedIdentity(instance.identity);
222
+ // Needs input (PR K): validated, never check()ed — an invalid claim is null (unknown), never an E_* that
223
+ // fails the roster. Absent stays absent.
224
+ if (own(instance, 'waitingOnYou')) row.waitingOnYou = waitingOnYouData(instance.waitingOnYou);
225
+ return [row];
226
+ });
227
+ return out;
228
+ });
229
+ const out = { root, agents, withheld };
230
+ if (own(document, 'workspace')) {
231
+ out.workspace = fields(document.workspace, ['code', 'reason', 'message']);
232
+ flags(document.workspace, ['reachable'], out.workspace);
233
+ // Workspace identity (feature workspace-identity, #482): kept as reported for matching this deployment
234
+ // to its workspace across machines (workspace-views.mjs). A shape the contract does not allow
235
+ // never fails the roster: it is marked, and the deployment is shown unmatched.
236
+ if (own(document.workspace, 'key')) {
237
+ const read = readIdentity(document.workspace);
238
+ if (read.status === 'identity') Object.assign(out.workspace, read.identity);
239
+ else out.workspace.identityInvalid = true;
240
+ }
241
+ }
242
+ return out;
243
+ }
244
+
245
+ /* ── Workspace model v2 catalog, sync and onboarding (F2) ───────────────
246
+ Command-specific shapes, projected once where they are read. The kernel's
247
+ rows are kept verbatim within bounds; nothing is joined, inferred or
248
+ re-derived (members' publishes and package capabilities stay distinct —
249
+ the non-collapse rule). */
250
+ function memberRow(row) {
251
+ const out = fields(row, ['key', 'name', 'commit', 'status', 'detail', 'team']);
252
+ check(text(out.key)); flags(row, ['confirmed'], out);
253
+ for (const key of ['souls', 'capabilities']) if (own(row, key)) out[key] = strings(row[key]);
254
+ if (own(row, 'publishes')) out.publishes = row.publishes === null ? null : fields(row.publishes, ['package', 'version']);
255
+ if (own(row, 'url')) { check(row.url === null || text(row.url)); out.url = row.url; }
256
+ if (own(row, 'membershipFile')) out.membershipFile = fileRef(row.membershipFile);
257
+ return out;
258
+ }
259
+ function packageRow(row) {
260
+ const out = fields(row, ['id', 'version', 'source', 'commit', 'integrity']); check(text(out.id));
261
+ if (own(row, 'capabilities')) out.capabilities = strings(row.capabilities);
262
+ if (own(row, 'latest')) out.latest = row.latest === null ? null : fields(row.latest, ['version', 'ref']);
263
+ return out;
264
+ }
265
+ const problemRows = value => array(value).map(row => fields(row, ['code', 'message', 'repoKey', 'path']));
266
+
267
+ /** `oats sync --json` (syncApi 1): the lock it wrote and what changed. */
268
+ export function syncData(document, deployment) {
269
+ check(absolute(deployment), 'E_BAD_ARGS');
270
+ check(record(document) && document.schemaVersion === 1 && document.ok === true);
271
+ const data = document.result;
272
+ check(record(data) && data.syncApi === 1 && record(data.workspace));
273
+ check(data.workspace.local === join(deployment, 'oats-local.yaml'), 'E_DEPLOYMENT_SCOPE');
274
+ const workspace = fields(data.workspace, ['name', 'key', 'url', 'commit', 'observedAt', 'local', 'lock']);
275
+ check(text(workspace.name) && text(workspace.key));
276
+ return flags(data, ['standalone'], { syncApi: 1, workspace,
277
+ members: array(data.members).map(memberRow), packages: array(data.packages).map(packageRow),
278
+ changes: array(data.changes).map(row => { const out = fields(row, ['id', 'from', 'to', 'commit']); check(text(out.id)); return out; }),
279
+ problems: problemRows(data.problems) });
280
+ }
281
+
282
+ /** `oats capabilities --json` (capabilitiesApi 1): every non-private item of
283
+ * every confirmed member, external souls' and locked packages' capabilities. */
284
+ export function capabilitiesData(document) {
285
+ check(record(document) && document.schemaVersion === 1 && document.ok === true);
286
+ const data = document.result;
287
+ check(record(data) && data.capabilitiesApi === 1);
288
+ const workspace = fields(data.workspace, ['name', 'key', 'commit']);
289
+ const capabilities = array(data.capabilities).map(row => {
290
+ const out = fields(row, ['name', 'origin', 'kind', 'repoKey', 'commit', 'team', 'path', 'layer', 'version', 'package', 'description', 'tree']);
291
+ check(text(out.name) && out.name.length > 0 && ['member', 'package', 'external'].includes(out.kind));
292
+ // What it provides (desktop-facts); skills is null when a spawn could not list them.
293
+ if (own(row, 'skills')) out.skills = row.skills === null ? null : strings(row.skills);
294
+ for (const key of ['commands', 'hooks']) if (own(row, key)) out[key] = strings(row[key]);
295
+ if (own(row, 'file')) out.file = fileRef(row.file);
296
+ return flags(row, ['private'], out);
297
+ });
298
+ return { capabilitiesApi: 1, workspace, capabilities, problems: problemRows(data.problems) };
299
+ }
300
+
301
+ /** `oats souls --json` (soulsApi 1): the deployment's spawn catalog — every
302
+ * non-private soul of a confirmed member, and external souls, with the work
303
+ * mode each declares. Names are unique per catalog (the kernel refuses an
304
+ * ambiguous bare name with E_SOUL_AMBIGUOUS; such a soul is not offered). */
305
+ const SOUL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
306
+ const TEAM_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
307
+ const PACKAGE_ID = /^[a-z0-9][a-z0-9._-]{0,127}$/; // the kernel's package-id grammar, bounded
308
+ // The kernel's soul key (K1's pattern): '*' never names one soul, so it is not a row key.
309
+ const SOUL_KEY = /^(?:[a-z0-9][a-z0-9._-]*\/)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
310
+ const soulKey = v => typeof v === 'string' && v.length <= 256 && SOUL_KEY.test(v);
311
+ /** A soul row's `capabilities` (feature souls-capabilities, OATS 0.45.0): the soul's composed capabilities
312
+ * (turned-off ones are not listed), each in `oats capabilities`' own row keys — `{name, kind: 'member', repoKey}`
313
+ * or `{name, kind: 'package', package}`; the kernel reports no external entry — plus `from` ('soul' | 'workspace';
314
+ * 'soul' when it is both). `null`: the soul did not resolve (exactly when it is not spawnable); `[]` composes
315
+ * nothing. The one place the entry shape is read: anything else is undefined, and the caller refuses the document. */
316
+ const COMPOSED_FROM = ['soul', 'workspace'];
317
+ const capabilityName = v => typeof v === 'string' && v.length > 0 && v.length <= 256;
318
+ const repoKeyOf = v => typeof v === 'string' && v.length > 0 && v.length <= 1024;
319
+ export function soulCapabilitiesOf(value) {
320
+ if (value === null) return null;
321
+ if (!Array.isArray(value) || value.length > 1024) return undefined;
322
+ const out = [];
323
+ for (const entry of value) {
324
+ if (!record(entry) || !capabilityName(entry.name) || !COMPOSED_FROM.includes(entry.from)) return undefined;
325
+ if (entry.kind === 'package') {
326
+ if (!(typeof entry.package === 'string' && PACKAGE_ID.test(entry.package)) || own(entry, 'repoKey')) return undefined;
327
+ out.push({ name: entry.name, kind: 'package', package: entry.package, from: entry.from });
328
+ } else if (entry.kind === 'member') {
329
+ if (!repoKeyOf(entry.repoKey) || own(entry, 'package')) return undefined;
330
+ out.push({ name: entry.name, kind: 'member', repoKey: entry.repoKey, from: entry.from });
331
+ } else return undefined;
332
+ }
333
+ return out;
334
+ }
335
+ export function soulsData(document) {
336
+ check(record(document) && document.schemaVersion === 1 && document.ok === true);
337
+ const data = document.result;
338
+ check(record(data) && data.soulsApi === 1);
339
+ const workspace = fields(data.workspace, ['name', 'key', 'commit']);
340
+ const seen = new Map();
341
+ for (const row of array(data.souls)) {
342
+ const out = fields(row, ['name', 'origin', 'kind', 'repoKey', 'commit', 'team', 'path', 'work', 'description']);
343
+ check(SOUL_NAME.test(out.name ?? '') && ['member', 'external', 'package'].includes(out.kind)
344
+ && ['worktree', 'checkout', 'directory', 'workspace', 'attached'].includes(out.work));
345
+ // Package souls (feature package-souls, 0.28): a soul a locked package ships, addressed by its
346
+ // qualified name `<package>/<soul>`.
347
+ if (out.kind === 'package') {
348
+ check(typeof row.package === 'string' && PACKAGE_ID.test(row.package) && typeof row.version === 'string' && row.version.length > 0 && row.version.length <= 64
349
+ && row.qualifiedName === `${row.package}/${out.name}`);
350
+ Object.assign(out, { package: row.package, version: row.version, qualifiedName: row.qualifiedName });
351
+ } else check(!own(row, 'qualifiedName') && !own(row, 'package'));
352
+ // The soul key (`oats soul teams <key>`, the souls.teams/souls.default keys) is the kernel's
353
+ // soul-key rule, exactly: a package soul's qualified name, every other soul's bare name
354
+ // (external included). When the row reports `key`, it must BE that key: a mismatch refuses the
355
+ // document (a kernel/contract defect, never papered over).
356
+ out.key = out.kind === 'package' ? out.qualifiedName : out.name;
357
+ if (own(row, 'key')) check(soulKey(row.key) && row.key === out.key);
358
+ flags(row, ['private', 'spawnable'], out);
359
+ // desktop-facts: whether a spawn here would refuse, and the file. The row's flat harness/model/harnessFrom
360
+ // are not kept: with launch-preference (0.30) the soul and this machine choose them, and the row's `launch`
361
+ // (below) carries the kernel's report of that choice; before 0.30 they were always the kernel's default.
362
+ if (own(row, 'problem')) out.problem = problemRef(row.problem);
363
+ if (own(row, 'file')) out.file = fileRef(row.file);
364
+ // Team model v2 (0.30): the soul's teams here (TeamRow, the default first) and its default.
365
+ if (own(row, 'teams')) { const teams = teamRowsOf(row.teams); check(teams !== undefined); out.teams = teams; }
366
+ if (own(row, 'defaultTeam')) { const d = defaultTeamOf(row.defaultTeam); check(d !== undefined); out.defaultTeam = d; }
367
+ // Launch preferences (0.30, feature launch-preference): what a spawn with no flags would decide here.
368
+ if (own(row, 'launch')) { const l = launchOf(row.launch, REPORT_FROM); check(l !== undefined); out.launch = l; }
369
+ // Its composed capabilities (feature souls-capabilities): Capabilities' "Used by" reads them.
370
+ // null exactly when the kernel reports the soul not spawnable here (the contract): a disagreement refuses the document.
371
+ if (own(row, 'capabilities')) {
372
+ const c = soulCapabilitiesOf(row.capabilities); check(c !== undefined);
373
+ if (typeof row.spawnable === 'boolean') check((c === null) === (row.spawnable === false));
374
+ out.capabilities = c;
375
+ }
376
+ // 0.29: every team label the soul carries (primary first; teams contract), when reported.
377
+ if (own(row, 'labels')) {
378
+ check(Array.isArray(row.labels) && row.labels.length <= 64 && row.labels.every(l => typeof l === 'string' && TEAM_LABEL.test(l)) && new Set(row.labels).size === row.labels.length);
379
+ out.labels = [...row.labels];
380
+ }
381
+ // One soul per key: a package soul never collides with a member of the same bare name, while a
382
+ // member and an external soul of one name stay ambiguous (never guess which one spawns).
383
+ const id = out.key;
384
+ seen.set(id, seen.has(id) ? null : out);
385
+ }
386
+ const souls = [...seen.values()].filter(Boolean);
387
+ const ambiguous = [...seen].filter(([, row]) => row === null).map(([key]) => key);
388
+ return { soulsApi: 1, workspace, souls, ambiguous, problems: problemRows(data.problems) };
389
+ }
390
+
391
+ /** `oats onboard --json` (onboardApi 2) for the directory the operator chose. */
392
+ export function onboardData(document, dir) {
393
+ check(absolute(dir), 'E_BAD_ARGS');
394
+ check(record(document) && document.schemaVersion === 1 && document.ok === true);
395
+ const data = document.result;
396
+ check(record(data) && data.onboardApi === 2 && data.dir === dir, 'E_DEPLOYMENT_SCOPE');
397
+ check(data.local === join(dir, 'oats-local.yaml'), 'E_DEPLOYMENT_SCOPE');
398
+ const out = fields(data, ['local', 'dir', 'agents', 'lock']);
399
+ out.sync = syncData({ schemaVersion: 1, ok: true, result: data.sync }, dir);
400
+ if (own(data, 'hosting')) { out.hosting = fields(data.hosting, ['host', 'rule']); flags(data.hosting, ['hostIsMember'], out.hosting); }
401
+ check(record(data.next));
402
+ out.next = { clone: array(data.next.clone).map(row => flags(row, ['present', 'host'], fields(row, ['key', 'name', 'url', 'dir']))),
403
+ spawn: data.next.spawn === null || data.next.spawn === undefined ? null : (check(text(data.next.spawn)), data.next.spawn),
404
+ souls: own(data.next, 'souls') ? strings(data.next.souls) : [] };
405
+ return out;
406
+ }
407
+
408
+ /* ── Team model v2 (feature team-model-2, OATS 0.30): the deployment's and a soul's teams.
409
+ docs/desktop-cli-api.md "Team model v2". Config-only kernel verbs; the kernel's rows are kept
410
+ within bounds, never re-derived. */
411
+ const labels = value => { const out = array(value, 256); check(out.every(l => typeof l === 'string' && TEAM_LABEL.test(l)) && new Set(out).size === out.length); return [...out]; };
412
+ const labelOrNull = value => { check(value === null || (typeof value === 'string' && TEAM_LABEL.test(value))); return value; };
413
+ const changed = (data, out) => { if (own(data, 'changed')) { check(typeof data.changed === 'boolean'); out.changed = data.changed; } return out; };
414
+ /* A team readiness item: its code, severity, the kernel's message and fix, and the problem's own keys
415
+ (a label, a souls: key, the local-teams-closed condition with its path and keys). */
416
+ function teamProblems(value) {
417
+ return array(value, 256).map(row => {
418
+ const out = fields(row, ['code', 'label', 'key', 'severity', 'message', 'fix', 'at', 'condition', 'path']);
419
+ check(text(out.code) && (out.severity === undefined || ['failure', 'warning'].includes(out.severity)));
420
+ if (own(row, 'keys')) out.keys = [...strings(row.keys)];
421
+ return flags(row, ['default'], out);
422
+ });
423
+ }
424
+ /** `oats teams [add|remove|default …] --json`: this deployment's teams. teamsApi 1 (team-model-2, OATS
425
+ * 0.30–0.37) or teamsApi 2 (team-model-3, OATS 0.38), each read in its own shape. */
426
+ export function teamsData(document, deployment) {
427
+ check(absolute(deployment), 'E_BAD_ARGS');
428
+ check(record(document) && document.schemaVersion === 1 && document.ok === true);
429
+ const data = document.result;
430
+ check(record(data) && (data.teamsApi === 1 || data.teamsApi === 2));
431
+ check(data.deployment === deployment, 'E_DEPLOYMENT_SCOPE');
432
+ const teams = array(data.teams, 256).map(row => {
433
+ const out = fields(row, ['label', 'team', 'description', 'from', 'at']);
434
+ check(TEAM_LABEL.test(out.label ?? '') && ['shared', 'local'].includes(out.from) && typeof row.default === 'boolean' && (out.team === null || TEAM_ID.test(out.team)));
435
+ out.default = row.default; return out;
436
+ });
437
+ check(new Set(teams.map(t => t.label)).size === teams.length && teams.filter(t => t.default).length <= 1);
438
+ if (data.teamsApi === 2) {
439
+ // Team model 3: whether local teams are allowed (null: the standalone view), the DefaultTeam a soul
440
+ // without a souls: default gets here, and the workspace's souls: patterns as committed.
441
+ check(data.localTeams === null || typeof data.localTeams === 'boolean');
442
+ const defaultTeam = defaultTeamOf(data.defaultTeam); check(defaultTeam !== undefined);
443
+ check(record(data.souls) && Object.keys(data.souls).length <= 1024);
444
+ const souls = Object.fromEntries(Object.entries(data.souls).map(([pattern, rule]) => {
445
+ check(text(pattern) && pattern.length <= 256 && record(rule));
446
+ const out = {};
447
+ if (own(rule, 'default')) { check(typeof rule.default === 'string' && TEAM_LABEL.test(rule.default)); out.default = rule.default; }
448
+ if (own(rule, 'teams')) out.teams = rule.teams === 'any' ? 'any' : labels(rule.teams);
449
+ return [pattern, out];
450
+ }));
451
+ return changed(data, { teamsApi: 2, deployment, localTeams: data.localTeams, defaultTeam, teams, souls, problems: teamProblems(data.problems) });
452
+ }
453
+ check(record(data.souls) && record(data.souls.teams) && record(data.souls.default));
454
+ const map = (value, one) => Object.fromEntries(Object.entries(value).map(([key, v]) => { check(text(key) && key.length <= 256); return [key, one ? labelOrNull(v) : labels(v)]; }));
455
+ return changed(data, { teamsApi: 1, deployment, defaultTeam: labelOrNull(data.defaultTeam), teams,
456
+ souls: { teams: map(data.souls.teams, false), default: map(data.souls.default, true) }, problems: teamProblems(data.problems) });
457
+ }
458
+ /* Why a soul may join a team, in the kernel's order: soulTeamsApi 1 (the deployment's souls.teams) and
459
+ soulTeamsApi 2 (team model 3: its default, its workspace souls: pattern, a local team). */
460
+ const VIA = { 1: ['default', '*', 'soul'], 2: ['default', 'workspace', 'local'] };
461
+ /** `oats soul teams <soul>|'*' … --json`. soulTeamsApi 1 (team-model-2: the reply to a show or an edit)
462
+ * or soulTeamsApi 2 (team-model-3: read only, with the souls: keys its teams and default came from). */
463
+ export function soulTeamsData(document) {
464
+ check(record(document) && document.schemaVersion === 1 && document.ok === true);
465
+ const data = document.result;
466
+ check(record(data) && (data.soulTeamsApi === 1 || data.soulTeamsApi === 2) && text(data.soul) && text(data.key));
467
+ const defaultTeam = defaultTeamOf(data.defaultTeam); check(defaultTeam !== undefined);
468
+ const via = VIA[data.soulTeamsApi];
469
+ const teams = array(data.teams, 128).map(row => {
470
+ const out = teamRow(row);
471
+ check(out && Object.hasOwn(out, 'default') && Array.isArray(row.via) && row.via.length > 0 && row.via.every(v => via.includes(v))
472
+ && new Set(row.via).size === row.via.length && row.via.every((v, i) => i === 0 || via.indexOf(row.via[i - 1]) < via.indexOf(v)));
473
+ return { ...out, via: [...row.via] };
474
+ });
475
+ check(new Set(teams.map(t => t.label)).size === teams.length);
476
+ if (data.soulTeamsApi === 2) {
477
+ const key = v => { check(v === null || (text(v) && v.length <= 256)); return v; };
478
+ return changed(data, { soulTeamsApi: 2, soul: data.soul, key: data.key, match: key(data.match), defaultMatch: key(data.defaultMatch), defaultTeam, teams });
479
+ }
480
+ check(record(data.local));
481
+ return changed(data, { soulTeamsApi: 1, soul: data.soul, key: data.key, defaultTeam, teams,
482
+ local: { teams: labels(data.local.teams), default: labelOrNull(data.local.default) }, all: labels(data.all) });
483
+ }
@@ -0,0 +1,34 @@
1
+ /** Display text for an instance's workspace-model v2 facts, exactly as
2
+ * `oats status --json` reported them, and for a deployment that is not observed.
3
+ * Formatting only: no drift is computed, no identity is derived from names,
4
+ * and absent facts stay absent.
5
+ * A page loads this module: it imports no Node builtin, and must not (the
6
+ * panel's own functions, which do, are in deployment-panel.mjs). */
7
+ import { requireTerms } from './client-terms.mjs';
8
+
9
+ const text = value => typeof value === 'string' && value ? value : null;
10
+ /** A member's display label from its repo key (the kernel's `memberLabel`). */
11
+ export const memberLabel = key => String(key || '').split('/').filter(Boolean).pop()?.replace(/\.git$/, '') || String(key || '');
12
+
13
+ /** `acts as <address> via grant, expires <t>` / `alias <alias> on <team>`. */
14
+ export function servedIdentityText(identity) {
15
+ if (!identity || typeof identity !== 'object') return null;
16
+ if (identity.mode === 'global' && identity.grant) {
17
+ return `acts as ${text(identity.address) || text(identity.alias) || text(identity.resident) || '?'} via grant${text(identity.grant.expiresAt) ? `, expires ${identity.grant.expiresAt}` : ''}`;
18
+ }
19
+ return `alias ${text(identity.alias) || '?'} on ${text(identity.team) || '?'}`;
20
+ }
21
+
22
+ /** The message for a deployment the kernel could not observe (workspace model v2): the sentence a
23
+ * client shows in place of its rows. Still reading (no deployment yet, or `pending`) says so; an
24
+ * observed deployment has none (''). A missing advertised feature is named, in the client's terms
25
+ * (client-terms.mjs: the client that needs it); a kernel refusal keeps its code and message. */
26
+ export function deploymentUnavailableText(deployment, terms) {
27
+ requireTerms(terms, 'deploymentUnavailableText');
28
+ if (!deployment || deployment.status === 'pending') return 'Reading the deployment through the installed OATS CLI…';
29
+ if (deployment.status === 'observed') return '';
30
+ const reason = deployment.reason || {};
31
+ if (reason.feature) return `The installed OATS CLI does not advertise ${reason.feature}, which the ${terms.name} needs to show this deployment. Update OATS and retry.`;
32
+ const code = text(reason.code), message = text(reason.message);
33
+ return code && message ? `${code}: ${message}` : message || 'The deployment could not be observed.';
34
+ }
@@ -0,0 +1,76 @@
1
+ /** How a deployment is named on screen: its machine and a short path (#482). Shared by the server,
2
+ * which labels every deployment of a workspace view, and the renderer, which shows the labels.
3
+ * A deployment that names no machine is on the machine the client runs on, and takes that machine's
4
+ * label from the client's terms (client-terms.mjs `thisMachine`: "This Mac"). */
5
+ import { requireTerms } from './client-terms.mjs';
6
+
7
+ const MAX_PATH = 40;
8
+
9
+ /** A path for display only: the home directory as `~` (this computer's own home for a local
10
+ * deployment; a remote host's `/Users/<name>` or `/home/<name>` prefix, which is only a display
11
+ * guess, since the host's home is never asked), and its last two segments when it is still long. */
12
+ export function shortPath(path, { home = null } = {}) {
13
+ if (typeof path !== 'string' || !path) return '';
14
+ let shown = path;
15
+ if (typeof home === 'string' && home.length > 1 && (path === home || path.startsWith(home.endsWith('/') ? home : `${home}/`))) {
16
+ shown = `~${path.slice(home.replace(/\/$/, '').length)}`;
17
+ } else if (home === null) {
18
+ const m = path.match(/^\/(?:Users|home)\/[^/]+(\/.*)?$/);
19
+ if (m) shown = `~${m[1] || ''}`;
20
+ }
21
+ if (shown.length <= MAX_PATH) return shown;
22
+ const parts = shown.split('/').filter(Boolean);
23
+ return parts.length > 2 ? `…/${parts.slice(-2).join('/')}` : shown;
24
+ }
25
+
26
+ /** The two halves of a deployment's label: `{ machine, path }` ("This Mac", "~/Agents/oats"; path ''
27
+ * when none). Headings style them apart: a machine label may be uppercased, a path never. */
28
+ export function deploymentLabelParts(deployment, terms) {
29
+ requireTerms(terms, 'deploymentLabelParts');
30
+ const machine = typeof deployment?.machine === 'string' && deployment.machine ? deployment.machine : terms.thisMachine;
31
+ const path = typeof deployment?.label === 'string' && deployment.label ? deployment.label : '';
32
+ return { machine, path };
33
+ }
34
+
35
+ /** `This Mac · ~/Agents/oats`, `altair · ~/Agents/tsm`. */
36
+ export function deploymentLabel(deployment, terms) {
37
+ requireTerms(terms, 'deploymentLabel');
38
+ const { machine, path } = deploymentLabelParts(deployment, terms);
39
+ return path ? `${machine} · ${path}` : machine;
40
+ }
41
+
42
+ /** The last segment of a path ("/Users/juan/awebai/oats-v2" → "oats-v2"), or the last `n`. */
43
+ export function pathTail(path, n = 1) {
44
+ if (typeof path !== 'string' || !path) return '';
45
+ return path.split('/').filter(Boolean).slice(-n).join('/');
46
+ }
47
+
48
+ /** Each deployment's short name on screen (UI spec, #482): its machine ("This Mac", "altair"); when one
49
+ * machine holds two or more of the deployments, the machine and its path tail ("This Mac · oats-v2"),
50
+ * the last two segments when the tails collide. Never an id. Returns Map<deployment id, label>. */
51
+ export function machineLabels(deployments, terms) {
52
+ requireTerms(terms, 'machineLabels');
53
+ const out = new Map();
54
+ for (const [id, { machine, tail }] of machineLabelParts(deployments, terms)) out.set(id, tail ? `${machine} · ${tail}` : machine);
55
+ return out;
56
+ }
57
+
58
+ /** machineLabels in two halves: Map<deployment id, { machine, tail }> (`tail` '' when the machine is
59
+ * enough). A heading uppercases the machine only; a path tail keeps its case. */
60
+ export function machineLabelParts(deployments, terms) {
61
+ requireTerms(terms, 'machineLabelParts');
62
+ const list = Array.isArray(deployments) ? deployments.filter(d => d && typeof d.id === 'string') : [];
63
+ const machineOf = d => (typeof d.machine === 'string' && d.machine) ? d.machine : terms.thisMachine;
64
+ const byMachine = new Map();
65
+ for (const d of list) byMachine.set(machineOf(d), [...(byMachine.get(machineOf(d)) || []), d]);
66
+ const out = new Map();
67
+ for (const [machine, same] of byMachine) {
68
+ if (same.length === 1) { out.set(same[0].id, { machine, tail: '' }); continue; }
69
+ const tails = same.map(d => pathTail(d.path));
70
+ same.forEach((d, i) => {
71
+ const tail = tails.filter(t => t === tails[i]).length > 1 ? pathTail(d.path, 2) : tails[i];
72
+ out.set(d.id, { machine, tail: tail || '' });
73
+ });
74
+ }
75
+ return out;
76
+ }