@awebai/oats 0.69.12 → 0.69.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +216 -178
- package/bin/oats.mjs +176 -184
- package/docs/capabilities.md +4 -1
- package/docs/configuration.md +63 -5
- package/docs/container.md +246 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +376 -37
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +69 -6
- package/docs/implementation.md +86 -29
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/schedules.md +26 -3
- package/docs/servers.md +181 -5
- package/docs/souls-and-instances.md +140 -11
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +24 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +21 -5
- package/lib/command-flags.mjs +238 -0
- package/lib/core.mjs +791 -563
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +126 -31
- package/lib/errors.mjs +1 -1
- package/lib/harness-token.mjs +110 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +138 -13
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-listing.mjs +80 -38
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +3 -0
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +119 -27
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +2 -1
- package/lib/servers.mjs +78 -23
- package/lib/session-resume.mjs +68 -53
- package/lib/session-seen.mjs +54 -5
- package/lib/start-env.mjs +13 -7
- package/lib/system-tools.mjs +1 -1
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree.mjs +56 -7
- package/package-catalog.json +1 -1
- package/package.json +2 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +92 -25
- package/lib/tmux-config.mjs +0 -35
package/lib/servers.mjs
CHANGED
|
@@ -21,6 +21,7 @@ import { createHash, randomBytes } from "node:crypto";
|
|
|
21
21
|
import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
|
22
22
|
import { homedir } from "node:os";
|
|
23
23
|
import { basename, join, resolve } from "node:path";
|
|
24
|
+
import { isDeepStrictEqual } from "node:util";
|
|
24
25
|
import { parseStrictJson } from "./canonical-json.mjs";
|
|
25
26
|
import { noteRuntimeName } from "./deprecation.mjs";
|
|
26
27
|
import { readWaitingClaim, validWaitingMessage } from "./instance-events.mjs";
|
|
@@ -39,6 +40,7 @@ export { compareSemver } from "./semver.mjs";
|
|
|
39
40
|
|
|
40
41
|
const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
|
|
41
42
|
export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
|
|
43
|
+
export const SERVER_OPERATOR_ROUTES_FILE = () => join(OATS_HOME_DIR(), "server-operator-routes.json");
|
|
42
44
|
export const REMOTE_SNAPSHOT_DIR = () => join(OATS_HOME_DIR(), "remote");
|
|
43
45
|
|
|
44
46
|
/** Every ssh invocation is non-interactive: a host that needs a password or a
|
|
@@ -131,6 +133,28 @@ export function readServers() {
|
|
|
131
133
|
return out;
|
|
132
134
|
}
|
|
133
135
|
|
|
136
|
+
/** Operator routes stay out of servers.json so an older kernel can still read every agent route. */
|
|
137
|
+
export function readServerOperatorRoutes() {
|
|
138
|
+
const file = SERVER_OPERATOR_ROUTES_FILE();
|
|
139
|
+
if (!existsSync(file)) return {};
|
|
140
|
+
let routes;
|
|
141
|
+
try { routes = JSON.parse(readFileSync(file, "utf8")); }
|
|
142
|
+
catch { throw serverError("E_SERVERS_UNREADABLE", `${file} is not valid JSON`); }
|
|
143
|
+
validateOperatorRoutes(routes);
|
|
144
|
+
return routes;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
export function validateOperatorSshHost(alias) {
|
|
148
|
+
if (typeof alias !== "string" || !SSH_HOST_RE.test(alias)) throw serverError("E_SERVER_INVALID", "operatorSshHost must be an OpenSSH host alias or host name (no user@, no options)");
|
|
149
|
+
}
|
|
150
|
+
function validateOperatorRoutes(routes) {
|
|
151
|
+
if (!routes || typeof routes !== "object" || Array.isArray(routes)) throw serverError("E_SERVERS_UNREADABLE", `${SERVER_OPERATOR_ROUTES_FILE()} must map server ids to { operatorSshHost: <alias> }`);
|
|
152
|
+
for (const [id, entry] of Object.entries(routes)) {
|
|
153
|
+
if (!ID_RE.test(id) || !entry || typeof entry !== "object" || Array.isArray(entry) || Object.keys(entry).length !== 1 || !Object.hasOwn(entry, "operatorSshHost")) throw serverError("E_SERVER_INVALID", `${SERVER_OPERATOR_ROUTES_FILE()}: expected a server id and { operatorSshHost: <alias> }`);
|
|
154
|
+
validateOperatorSshHost(entry.operatorSshHost);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
134
158
|
export function writeServers(servers) {
|
|
135
159
|
const file = SERVERS_FILE();
|
|
136
160
|
// A registration whose target changes (server add --replace) is probed afresh.
|
|
@@ -144,15 +168,24 @@ export function writeServers(servers) {
|
|
|
144
168
|
}
|
|
145
169
|
|
|
146
170
|
/** Every read-modify-write of the registry: under one short lock, over the file as it is NOW (never a
|
|
147
|
-
* copy read before a network call), written only when `change` altered it. `change(servers)`
|
|
148
|
-
* mutates its
|
|
149
|
-
|
|
171
|
+
* copy read before a network call), written only when `change` altered it. `change(servers, routes)`
|
|
172
|
+
* mutates its arguments and returns what the caller needs. With `operatorRoutes`, the sidecar is
|
|
173
|
+
* read and written under this same lock; agent-only updates never need to read it. */
|
|
174
|
+
export function updateServers(change, { operatorRoutes = false } = {}) {
|
|
150
175
|
const lock = join(OATS_HOME_DIR(), "servers.lock");
|
|
151
176
|
return withDirLock(lock, "the server registry", () => {
|
|
152
177
|
const servers = readServers();
|
|
153
|
-
const
|
|
154
|
-
const
|
|
155
|
-
|
|
178
|
+
const routes = operatorRoutes ? readServerOperatorRoutes() : undefined;
|
|
179
|
+
const before = structuredClone(servers);
|
|
180
|
+
const routesBefore = JSON.stringify(routes);
|
|
181
|
+
const out = change(servers, routes);
|
|
182
|
+
if (routes) validateOperatorRoutes(routes);
|
|
183
|
+
// Key ordering alone must not rewrite the legacy registry when only an operator route changes.
|
|
184
|
+
if (!isDeepStrictEqual(servers, before)) writeServers(servers);
|
|
185
|
+
if (JSON.stringify(routes) !== routesBefore) {
|
|
186
|
+
mkdirSync(OATS_HOME_DIR(), { recursive: true });
|
|
187
|
+
writeFileSync(SERVER_OPERATOR_ROUTES_FILE(), JSON.stringify(routes, null, 2) + "\n", { mode: 0o600 });
|
|
188
|
+
}
|
|
156
189
|
return out;
|
|
157
190
|
}, { retryMs: 5000, busy: (why) => serverError("E_SERVERS_BUSY", `the server registry is locked (${why}); if no oats process is changing it, remove ${lock} and retry; nothing was changed`) });
|
|
158
191
|
}
|
|
@@ -160,13 +193,15 @@ export function updateServers(change) {
|
|
|
160
193
|
/** Record the workspace key a host reported for registration `id`, only if the registration is still
|
|
161
194
|
* the one that was asked (same host, workspace, oats path and PATH), so a registration changed or
|
|
162
195
|
* removed meanwhile is never overwritten or brought back. → "recorded" | "same" | "changed" |
|
|
163
|
-
* { mismatch: <the recorded key> }
|
|
164
|
-
|
|
196
|
+
* { mismatch: <the recorded key> }. `replace` is the explicit server add --replace remedy: a
|
|
197
|
+
* preserved key may be replaced only while it is still the key this request observed. */
|
|
198
|
+
export function learnWorkspaceKey(id, asked, reported, { replace = false } = {}) {
|
|
165
199
|
return updateServers((servers) => {
|
|
166
200
|
const current = servers[id];
|
|
167
201
|
if (!current || JSON.stringify(targetOf(current)) !== JSON.stringify(targetOf(asked))) return "changed";
|
|
168
202
|
if (sameRepo(current.workspaceKey, reported)) return "same";
|
|
169
|
-
if (current.workspaceKey
|
|
203
|
+
if (replace && current.workspaceKey !== asked.workspaceKey) return "changed";
|
|
204
|
+
if (current.workspaceKey && !replace) return { mismatch: current.workspaceKey };
|
|
170
205
|
current.workspaceKey = reported;
|
|
171
206
|
return "recorded";
|
|
172
207
|
});
|
|
@@ -193,7 +228,7 @@ export function validateServer(id, s) {
|
|
|
193
228
|
// The canonical key of the workspace the host deployment realizes, as its own `status --json` reported it.
|
|
194
229
|
if (s.workspaceKey !== undefined && (typeof s.workspaceKey !== "string" || !WORKSPACE_KEY_RE.test(s.workspaceKey))) throw serverError("E_SERVER_INVALID", `server ${id}: workspaceKey must be a canonical workspace key (as the host's oats status --json reports it)`);
|
|
195
230
|
for (const k of Object.keys(s)) {
|
|
196
|
-
if (!["label", "sshHost", "workspace", "oatsPath", "path", "workspaceKey"].includes(k)) throw serverError("E_SERVER_INVALID", `server ${id}: unknown field ${JSON.stringify(k)} (a registration holds label, sshHost, workspace, oatsPath, path, workspaceKey and nothing else — never keys or passwords)`);
|
|
231
|
+
if (!["label", "sshHost", "workspace", "oatsPath", "path", "workspaceKey"].includes(k)) throw serverError("E_SERVER_INVALID", `server ${id}: unknown field ${JSON.stringify(k)} (a registration holds label, sshHost, workspace, oatsPath, path, workspaceKey and nothing else — never keys or passwords; operator routes belong in server-operator-routes.json)`);
|
|
197
232
|
}
|
|
198
233
|
return true;
|
|
199
234
|
}
|
|
@@ -220,9 +255,8 @@ export function workspaceMismatch(id, server, reported) {
|
|
|
220
255
|
|
|
221
256
|
export function getServer(id) {
|
|
222
257
|
const servers = readServers();
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
return { id, ...s };
|
|
258
|
+
if (!Object.hasOwn(servers, id)) throw serverError("E_SERVER_UNKNOWN", `no server registered as ${JSON.stringify(id)} (oats server list)`);
|
|
259
|
+
return { id, ...servers[id] };
|
|
226
260
|
}
|
|
227
261
|
|
|
228
262
|
// ------------------------------------------------------------------ quoting
|
|
@@ -284,6 +318,13 @@ function sshLineArgv(target, cmd, { control = false } = {}) {
|
|
|
284
318
|
return ["ssh", ...SSH_OPTS, ...(control && !controlPathProblem() ? controlOpts() : NO_CONTROL_OPTS), "--", target.sshHost, cmd];
|
|
285
319
|
}
|
|
286
320
|
|
|
321
|
+
/** The forced-command operator key must never reuse the agent route's authenticated master.
|
|
322
|
+
* Only receiver command words belong here; credential bytes go exclusively on stdin. */
|
|
323
|
+
export function operatorSshArgv(alias, words) {
|
|
324
|
+
validateOperatorSshHost(alias);
|
|
325
|
+
return ["ssh", ...SSH_OPTS, ...NO_CONTROL_OPTS, "--", alias, ...words.map(remoteQuote)];
|
|
326
|
+
}
|
|
327
|
+
|
|
287
328
|
// ------------------------------------------------------------------ running
|
|
288
329
|
|
|
289
330
|
/** Parse the remote kernel's JSON envelope; anything else on stdout is a
|
|
@@ -1442,15 +1483,17 @@ function relayedFailure(envelope, what) {
|
|
|
1442
1483
|
|
|
1443
1484
|
/**
|
|
1444
1485
|
* options: { id, sshHost, workspaceRef, dir (absolute, or ~/… resolved by the host), oatsPath?, path?,
|
|
1445
|
-
* label?, installOats?, replace?, localVersion (this kernel's: the version installed) }
|
|
1486
|
+
* label?, operatorSshHost?, noOperatorSsh?, installOats?, replace?, localVersion (this kernel's: the version installed) }
|
|
1446
1487
|
* io: { execFileSync, now, readinessBudgetMs } (the transport and clock; tests inject them).
|
|
1447
1488
|
* → { id, ready, registration, steps, human }; a failed step throws its code with
|
|
1448
1489
|
* details { ...the step's details, steps }.
|
|
1449
1490
|
*/
|
|
1450
1491
|
export function connectServer(options, io = {}) {
|
|
1451
|
-
const { id, sshHost, workspaceRef, dir, oatsPath, path, label, installOats = false, replace = false, localVersion } = options;
|
|
1492
|
+
const { id, sshHost, workspaceRef, dir, oatsPath, path, label, operatorSshHost, noOperatorSsh = false, installOats = false, replace = false, localVersion } = options;
|
|
1452
1493
|
const now = io.now || Date.now;
|
|
1453
1494
|
validateServer(id, { sshHost, workspace: "/", ...(oatsPath ? { oatsPath } : {}), ...(path ? { path } : {}), ...(label ? { label } : {}) });
|
|
1495
|
+
if (operatorSshHost !== undefined) validateOperatorSshHost(operatorSshHost);
|
|
1496
|
+
if (operatorSshHost !== undefined && noOperatorSsh) throw serverError("E_BAD_ARGS", "choose --operator-ssh or --no-operator-ssh, not both");
|
|
1454
1497
|
if (typeof dir !== "string" || !(dir === "~" || dir.startsWith("~/") || dir.startsWith("/"))) throw serverError("E_BAD_ARGS", `--dir must be an absolute path or ~/… on the host (got ${JSON.stringify(dir)})`);
|
|
1455
1498
|
io = { ...io, serverId: id, input: undefined };
|
|
1456
1499
|
const target = { sshHost, workspace: dir, oatsPath: oatsPath || "oats", ...(path ? { path } : {}) };
|
|
@@ -1551,10 +1594,18 @@ export function connectServer(options, io = {}) {
|
|
|
1551
1594
|
|
|
1552
1595
|
// One guarded update of the registry as it is now. The requested id comes first: an id registered for
|
|
1553
1596
|
// another target is refused (or replaced), never quietly answered by a twin that serves this target.
|
|
1554
|
-
run("register", () => updateServers((servers) => {
|
|
1597
|
+
run("register", () => updateServers((servers, routes) => {
|
|
1555
1598
|
const abs = check.dir;
|
|
1556
1599
|
const given = { ...(oatsPath ? { oatsPath } : {}), ...(path ? { path } : {}), ...(label ? { label } : {}) };
|
|
1557
1600
|
const entry = { sshHost, workspace: abs, ...found, ...given, workspaceKey: reportedKey };
|
|
1601
|
+
const operatorAt = (regId) => Object.hasOwn(routes, regId) ? routes[regId] : undefined;
|
|
1602
|
+
const operatorChange = (regId) => {
|
|
1603
|
+
const before = operatorAt(regId)?.operatorSshHost;
|
|
1604
|
+
if (operatorSshHost !== undefined) routes[regId] = { operatorSshHost };
|
|
1605
|
+
else if (noOperatorSsh) delete routes[regId];
|
|
1606
|
+
return before !== operatorAt(regId)?.operatorSshHost;
|
|
1607
|
+
};
|
|
1608
|
+
const joined = (regId) => ({ ...servers[regId], ...operatorAt(regId) });
|
|
1558
1609
|
const sameTarget = (s) => s.sshHost === sshHost && s.workspace === abs;
|
|
1559
1610
|
/** A registration of this very target: its key confirmed, or recorded; never contradicted. What
|
|
1560
1611
|
* this run found on the host fills only what it lacks. */
|
|
@@ -1562,30 +1613,34 @@ export function connectServer(options, io = {}) {
|
|
|
1562
1613
|
const existing = servers[regId];
|
|
1563
1614
|
if (existing.workspaceKey && !sameRepo(existing.workspaceKey, reportedKey)) throw workspaceMismatch(regId, existing, reportedKey);
|
|
1564
1615
|
registeredAs = regId;
|
|
1565
|
-
registration = existing;
|
|
1566
1616
|
const filled = Object.keys(found).filter((k) => existing[k] === undefined || existing[k] === null).sort();
|
|
1567
1617
|
for (const k of filled) existing[k] = found[k];
|
|
1568
1618
|
const keyed = !existing.workspaceKey;
|
|
1569
1619
|
if (keyed) existing.workspaceKey = reportedKey;
|
|
1570
|
-
|
|
1571
|
-
|
|
1620
|
+
const operatorDiffers = operatorSshHost !== undefined ? operatorSshHost !== operatorAt(regId)?.operatorSshHost : noOperatorSsh && operatorAt(regId) !== undefined;
|
|
1621
|
+
if (!replace && operatorDiffers) detail = [detail, "operator route differs from the registration and was not changed (--replace rewrites it)"].filter(Boolean).join("; ");
|
|
1622
|
+
const operatorChanged = replace && operatorChange(regId);
|
|
1623
|
+
registration = joined(regId);
|
|
1624
|
+
if (!filled.length && !keyed && !operatorChanged) return { status: "ok", ...(detail ? { detail } : {}) };
|
|
1625
|
+
return { status: "done", detail: [detail, filled.length ? `recorded ${filled.join(", ")}` : null, keyed ? `recorded workspace ${reportedKey}` : null, operatorChanged ? "updated operator route" : null].filter(Boolean).join("; ") };
|
|
1572
1626
|
};
|
|
1573
|
-
const mine = servers[id];
|
|
1627
|
+
const mine = Object.hasOwn(servers, id) ? servers[id] : undefined;
|
|
1574
1628
|
if (mine && sameTarget(mine)) {
|
|
1575
1629
|
// A value given differs; one only found here differs only under --replace.
|
|
1576
1630
|
const differ = ["oatsPath", "path", "label"].filter((k) => entry[k] !== undefined && entry[k] !== mine[k] && (Object.hasOwn(given, k) || replace));
|
|
1577
1631
|
if (!differ.length || !replace) return keep(id, differ.length ? `${differ.join(", ")} differ from the registration and were not changed (--replace rewrites it)` : undefined);
|
|
1578
1632
|
if (mine.workspaceKey && !sameRepo(mine.workspaceKey, reportedKey)) throw workspaceMismatch(id, mine, reportedKey);
|
|
1579
|
-
servers[id] = entry; registration =
|
|
1633
|
+
servers[id] = entry; operatorChange(id); registration = joined(id);
|
|
1580
1634
|
return { status: "done", detail: `updated ${differ.join(", ")}` };
|
|
1581
1635
|
}
|
|
1582
1636
|
if (mine && !replace) throw Object.assign(serverError("E_SERVER_EXISTS", `server ${id} is already registered for ${mine.sshHost}:${mine.workspace} (pass --replace to point it at ${sshHost}:${abs}; instances spawned through it keep their saved routes)`), { details: { registered: { sshHost: mine.sshHost, workspace: mine.workspace } } });
|
|
1583
1637
|
const twin = Object.keys(servers).find((other) => other !== id && sameTarget(servers[other]));
|
|
1584
1638
|
if (twin && !mine) return keep(twin, `${sshHost}:${abs} is already registered as ${twin}; not registered again`);
|
|
1585
1639
|
validateServer(id, entry);
|
|
1586
|
-
|
|
1640
|
+
if (!mine) delete routes[id];
|
|
1641
|
+
servers[id] = entry; operatorChange(id); registration = joined(id);
|
|
1587
1642
|
return { status: "done", detail: [mine ? `replaced ${mine.sshHost}:${mine.workspace}` : `registered ${id}`, twin ? `${sshHost}:${abs} is also registered as ${twin}` : null].filter(Boolean).join("; ") };
|
|
1588
|
-
}));
|
|
1643
|
+
}, { operatorRoutes: true }));
|
|
1589
1644
|
|
|
1590
1645
|
// Every soul the host deployment lists (disabled ones skipped), one routed readiness each, within one
|
|
1591
1646
|
// budget; each failing or unknown required item is a human line, said once for the souls sharing it.
|
package/lib/session-resume.mjs
CHANGED
|
@@ -15,9 +15,11 @@
|
|
|
15
15
|
* - Each home starts as a child process of this kernel (`session start --resume --home <home>
|
|
16
16
|
* --json`, its cwd the home's deployment), so each start resolves its own deployment's scope; at
|
|
17
17
|
* most RESUME_CONCURRENCY at once. A per-home failure is a row, never the sweep's failure.
|
|
18
|
-
* - One sweep per machine:
|
|
19
|
-
*
|
|
20
|
-
* taken
|
|
18
|
+
* - One sweep per machine: the lock `session-resume/lock` under OATS_HOME_DIR (default ~/.oats),
|
|
19
|
+
* a claim (lib/claim.mjs, through lib/dir-lock.mjs) that names its holder by pid, process start
|
|
20
|
+
* and boot id; a lock whose holder is gone, or that was taken in another boot, is taken over at
|
|
21
|
+
* once. A second sweep answers E_RESUME_BUSY; a lock that needs a person, E_RESUME_LOCK_STUCK,
|
|
22
|
+
* which `oats doctor` reports too (acquireResumeLock, resumeLockProblem).
|
|
21
23
|
* - No retry storm. A loss the sweep answered is judged (above) and not started again, whatever the
|
|
22
24
|
* boot; one note per boot (`note.json`) backs that: a refused resume is noted, and a later sweep
|
|
23
25
|
* in the same boot reports it again (`refused-this-boot`) without starting it, also when its
|
|
@@ -31,14 +33,15 @@
|
|
|
31
33
|
* The lock and the note are kernel-private, not a contract. `plan` predicts from the note, starting
|
|
32
34
|
* nothing, taking no lock and writing no note. */
|
|
33
35
|
import { execFile } from "node:child_process";
|
|
34
|
-
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync,
|
|
36
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
35
37
|
import { join, resolve } from "node:path";
|
|
36
38
|
import { oatsError } from "./errors.mjs";
|
|
37
39
|
import { deploymentState, readDeploymentsDocument } from "./deployments.mjs";
|
|
38
|
-
import {
|
|
39
|
-
import {
|
|
40
|
+
import { acquireDirLock, dirLockHeld } from "./dir-lock.mjs";
|
|
41
|
+
import { homeClaimHolder, listInstances, launchEnvRefs, missingLaunchEnvRefs, owedRetireSaid, resumeConversation } from "./core.mjs";
|
|
42
|
+
import { checkStartEnv, launchEnvChangedMessage, launchEnvMissingMessage, launchEnvUnverifiedWarning } from "./start-env.mjs";
|
|
40
43
|
import { FRESH_REASON, NOT_SWEPT, OUTCOME, RESUME_WAITING, ROW_REASON, SESSION_END } from "./session-resume-contract.mjs";
|
|
41
|
-
import { bootId, homeKey, judgeLosses, readSeen, resumeEligible, resumeStateDir } from "./session-seen.mjs";
|
|
44
|
+
import { bootId, homeKey, judgeLosses, readSeen, resumeEligible, resumeStateDir, takenInAnotherBoot } from "./session-seen.mjs";
|
|
42
45
|
import { isAgentScopeWarning } from "./tmux-server-scope.mjs";
|
|
43
46
|
|
|
44
47
|
export { bootId, resumeStateDir };
|
|
@@ -48,56 +51,67 @@ export const RESUME_SCHEMA = 1;
|
|
|
48
51
|
export const RESUME_CONCURRENCY = 4;
|
|
49
52
|
/** At most this many sweep starts of one home in one boot. */
|
|
50
53
|
export const RESUME_LIMIT = 3;
|
|
51
|
-
|
|
52
|
-
* the owner's write); older, it is a crashed acquirer's. */
|
|
53
|
-
const OWNERLESS_GRACE_MS = 60_000;
|
|
54
|
-
|
|
55
|
-
const lockDir = () => join(resumeStateDir(), "lock");
|
|
54
|
+
const lockPath = () => join(resumeStateDir(), "lock");
|
|
56
55
|
const notePath = () => join(resumeStateDir(), "note.json");
|
|
57
56
|
|
|
58
|
-
function pidAlive(pid) {
|
|
59
|
-
if (!Number.isSafeInteger(pid) || pid < 1) return false;
|
|
60
|
-
try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
|
|
61
|
-
}
|
|
62
57
|
const readJson = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } };
|
|
63
58
|
|
|
64
|
-
/**
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
|
|
69
|
-
|
|
59
|
+
/** What to do about a sweep's lock `path` that needs a person, by what was found (lib/dir-lock.mjs
|
|
60
|
+
* `found`). A directory is the lock of a kernel that locked with one: nothing here tells whether
|
|
61
|
+
* that kernel's sweep runs, so it is the operator who removes it. A record that cannot be read,
|
|
62
|
+
* or whose holder cannot be told to run, is removed once a person has seen that no sweep runs. A
|
|
63
|
+
* gone holder's record is removed without that. Where nothing is in the way (the lock was taken
|
|
64
|
+
* again each time, or this process cannot read its own start) there is nothing to remove. */
|
|
65
|
+
const STUCK_REMEDY = {
|
|
66
|
+
directory: (path) => `once no earlier oats is running on this machine, remove the directory ${path} and run it again`,
|
|
67
|
+
"cannot-take-over": (path) => `remove ${path} and run it again`,
|
|
68
|
+
"held-again": () => "run it again",
|
|
69
|
+
"own-start-unreadable": (path) => `run it again; nothing at ${path} is to be removed`,
|
|
70
|
+
};
|
|
71
|
+
const removeOnceNoSweepRuns = (path) => `if no oats session resume is running on this machine, remove ${path} and run it again`;
|
|
72
|
+
/** A sweep's lock `path` that needs a person, found as lib/dir-lock.mjs says it (`why`, `found`) →
|
|
73
|
+
* what is said of it and what to do. Exported for its test. */
|
|
74
|
+
export function resumeLockStuck(path, why, found) {
|
|
75
|
+
return {
|
|
76
|
+
lock: path, found,
|
|
77
|
+
said: `the session resume lock ${path} cannot be taken (${why})`,
|
|
78
|
+
remedy: (STUCK_REMEDY[found] ?? removeOnceNoSweepRuns)(path),
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Take the machine's resume lock → its release function. The lock is a claim (lib/dir-lock.mjs
|
|
83
|
+
* acquireDirLock) whose record also names the boot it was taken in.
|
|
84
|
+
* - A sweep that runs holds it: E_RESUME_BUSY, at once.
|
|
85
|
+
* - A holder that is gone (exited, killed, its pid another process's) is taken over at once. So
|
|
86
|
+
* is one that took the lock in another boot (takenInAnotherBoot).
|
|
87
|
+
* - A lock that needs a person is E_RESUME_LOCK_STUCK, with what was found and what to do, its
|
|
88
|
+
* `details` `{ lock, found }` (`found`: lib/dir-lock.mjs), and is left as it is: a holder
|
|
89
|
+
* whose liveness cannot be read, a record that does not parse, a gone holder's record that
|
|
90
|
+
* cannot be taken over, a lock taken again each time it was found free, this process's own
|
|
91
|
+
* start unreadable, and a directory at the lock's path, the lock of an earlier kernel, which
|
|
92
|
+
* is never judged and never removed. */
|
|
93
|
+
export function acquireResumeLock({ boot = bootId() } = {}) {
|
|
94
|
+
const path = lockPath();
|
|
70
95
|
mkdirSync(resumeStateDir(), { recursive: true, mode: 0o700 });
|
|
71
|
-
const busy = (why
|
|
72
|
-
|
|
73
|
-
const
|
|
74
|
-
|
|
75
|
-
if (boot && owner.bootId && owner.bootId !== boot) return `taken in another boot by pid ${owner.pid}`;
|
|
76
|
-
return pidAlive(owner.pid) ? null : `its owner pid ${owner.pid} is gone`;
|
|
96
|
+
const busy = (why, { found }) => {
|
|
97
|
+
if (found === "running") return oatsError("E_RESUME_BUSY", `another session resume on this machine holds ${path} (${why}); nothing was started`);
|
|
98
|
+
const stuck = resumeLockStuck(path, why, found);
|
|
99
|
+
return Object.assign(oatsError("E_RESUME_LOCK_STUCK", `${stuck.said}; ${stuck.remedy}; nothing was started`), { details: { lock: path, found } });
|
|
77
100
|
};
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
try {
|
|
93
|
-
// Read again under the takeover: another sweep may have taken it meanwhile.
|
|
94
|
-
if (existsSync(dir) && !stale()) throw busy("another sweep took it over");
|
|
95
|
-
const aside = `${dir}.stale-${process.pid}-${now()}`;
|
|
96
|
-
try { renameSync(dir, aside); rmSync(aside, { recursive: true, force: true }); } catch (r) { if (r.code !== "ENOENT") throw r; }
|
|
97
|
-
take();
|
|
98
|
-
} finally { rmSync(takeover, { recursive: true, force: true }); }
|
|
99
|
-
}
|
|
100
|
-
return () => { try { if (readJson(join(dir, "owner.json"))?.pid === process.pid) rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } };
|
|
101
|
+
return acquireDirLock(path, { bootId: boot }, { busy, holderGone: takenInAnotherBoot(boot) });
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
export const RESUME_LOCK_STUCK = "resume-lock-stuck";
|
|
105
|
+
/** `oats doctor`'s `resume-lock-stuck` problem: the machine's resume lock when it needs a person
|
|
106
|
+
* → `{ code, message, remedy }`, or null. The lock is read where a sweep would take it
|
|
107
|
+
* (lib/dir-lock.mjs dirLockHeld, with the same boot rule), and nothing is taken or changed. Every
|
|
108
|
+
* state acquireResumeLock answers E_RESUME_LOCK_STUCK for a lock it finds is one; a free lock, a
|
|
109
|
+
* sweep that runs and a lock a gone sweep left, which the next sweep takes over, are not. */
|
|
110
|
+
export function resumeLockProblem({ boot = bootId() } = {}) {
|
|
111
|
+
const path = lockPath(), held = dirLockHeld(path, { holderGone: takenInAnotherBoot(boot) });
|
|
112
|
+
if (!held || held.found === "running") return null;
|
|
113
|
+
const stuck = resumeLockStuck(path, held.why, held.found);
|
|
114
|
+
return { code: RESUME_LOCK_STUCK, message: `${stuck.said}: oats session resume starts nothing on this machine while it is there`, remedy: stuck.remedy };
|
|
101
115
|
}
|
|
102
116
|
|
|
103
117
|
/** This boot's note: `{ bootId, refused: [{ home, startId, code, message, at }], resumes: { <home>: n } }`,
|
|
@@ -329,8 +343,9 @@ function predicted(row, env) {
|
|
|
329
343
|
const refused = (code, message) => ({ ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.START_REFUSED, code, message });
|
|
330
344
|
if (!(row.launch && typeof row.launch === "object")) return refused("E_LAUNCH_LEGACY", `${row.instance} records no launch recipe (an earlier kernel spawned it): re-spawn it from the deployment`);
|
|
331
345
|
const missing = missingLaunchEnvRefs(row.launch.env, env);
|
|
332
|
-
if (missing.length) return refused("E_LAUNCH_ENV_MISSING", launchEnvMissingMessage(missing));
|
|
333
|
-
const
|
|
346
|
+
if (missing.length) return refused("E_LAUNCH_ENV_MISSING", launchEnvMissingMessage(missing, row.launch.harness));
|
|
347
|
+
const refs = launchEnvRefs(row.launch, env);
|
|
348
|
+
const fit = checkStartEnv(row.home, row.startId ?? null, refs.map((r) => r.source), Object.fromEntries(refs.map((r) => [r.source, r.value])));
|
|
334
349
|
if (fit.changed) return refused("E_LAUNCH_ENV_CHANGED", launchEnvChangedMessage(fit.changed));
|
|
335
350
|
const extra = fit.unverified ? { warnings: [launchEnvUnverifiedWarning(row.instance)] } : {};
|
|
336
351
|
const found = resumeConversation(row.home, row);
|
package/lib/session-seen.mjs
CHANGED
|
@@ -19,9 +19,10 @@
|
|
|
19
19
|
* Dependency-free. */
|
|
20
20
|
import { execFileSync } from "node:child_process";
|
|
21
21
|
import { createHash, randomBytes } from "node:crypto";
|
|
22
|
-
import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
22
|
+
import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
23
23
|
import { homedir } from "node:os";
|
|
24
24
|
import { dirname, join, resolve } from "node:path";
|
|
25
|
+
import { systemTool } from "./system-tools.mjs";
|
|
25
26
|
|
|
26
27
|
/** A loss first seen this long ago or more is not resumed. */
|
|
27
28
|
export const FIRST_SEEN_MAX_MS = 24 * 60 * 60_000;
|
|
@@ -34,11 +35,53 @@ const oatsHomeDir = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
|
|
|
34
35
|
/** The kernel-private directory of the sweep's lock, its per-boot note and this record. */
|
|
35
36
|
export const resumeStateDir = () => join(oatsHomeDir(), "session-resume");
|
|
36
37
|
|
|
37
|
-
/**
|
|
38
|
-
*
|
|
39
|
-
|
|
38
|
+
/** What says this process runs in a container: a file each runtime puts in its containers, or the
|
|
39
|
+
* variable Kubernetes sets in every pod. Docker writes `/.dockerenv`, Podman `/run/.containerenv`. */
|
|
40
|
+
const CONTAINER_FILES = ["/.dockerenv", "/run/.containerenv"];
|
|
41
|
+
const inContainer = (exists, env) => CONTAINER_FILES.some((file) => exists(file)) || Boolean(env.KUBERNETES_SERVICE_HOST);
|
|
42
|
+
|
|
43
|
+
/** When PID 1 started, as this process sees PID 1: field 22 of `/proc/1/stat`, in clock ticks after
|
|
44
|
+
* the kernel's boot, as the digits the kernel printed; null when the file cannot be read or does
|
|
45
|
+
* not hold it. The fields are counted after the last ")": the name (field 2) may hold spaces and
|
|
46
|
+
* parentheses. */
|
|
47
|
+
function initStart(read) {
|
|
48
|
+
try {
|
|
49
|
+
const stat = read("/proc/1/stat"), named = stat.lastIndexOf(")");
|
|
50
|
+
const start = named < 0 ? undefined : stat.slice(named + 1).trim().split(/\s+/)[19];
|
|
51
|
+
return typeof start === "string" && /^\d+$/.test(start) ? start : null;
|
|
52
|
+
} catch { return null; }
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** macOS's boot time, from the system's sysctl (systemTool), never one the caller's PATH names: a
|
|
56
|
+
* PATH without /usr/sbin, or with another sysctl first, must not change or lose the boot id. */
|
|
57
|
+
function systemSysctl() {
|
|
58
|
+
const tool = systemTool("sysctl");
|
|
59
|
+
if (!tool.file) throw new Error(tool.reason);
|
|
60
|
+
return execFileSync(tool.file, ["-n", "kern.boottime"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] });
|
|
61
|
+
}
|
|
62
|
+
/** This boot's identity, or null where the kernel cannot read one. A boot is what ends every
|
|
63
|
+
* process the kernel may have recorded: the sessions, their terminal server, a sweep.
|
|
64
|
+
* - macOS: the boot time (`sysctl -n kern.boottime`, its `sec`/`usec`).
|
|
65
|
+
* - Linux: the kernel's boot id (`/proc/sys/kernel/random/boot_id`).
|
|
66
|
+
* - Linux in a container (inContainer): `<boot id>:<PID 1's start>`. A container shares its
|
|
67
|
+
* host's kernel and so its boot id, which outlives a stop and start of the container; its PID 1
|
|
68
|
+
* does not. PID 1 starts once per run of the container and ends every process of the run when
|
|
69
|
+
* it ends, so its start is the same for every process of one run and another in the next; the
|
|
70
|
+
* boot id keeps a start apart from the same number of ticks after another kernel boot. When
|
|
71
|
+
* PID 1's start cannot be read there, the boot id alone: the sweep then counts a home's starts
|
|
72
|
+
* across the runs and applies the in-boot clause across them, so it starts less, never more.
|
|
73
|
+
* PID 1's start is read only in a container. A process in a PID namespace of its own on a host (a
|
|
74
|
+
* command a harness runs in a sandbox) reads that namespace's PID 1, which is not the machine's,
|
|
75
|
+
* and it is on the host's boot all the same.
|
|
76
|
+
* Each is read from the kernel without privileges and written nowhere. */
|
|
77
|
+
export function bootId({ platform = process.platform, read = (p) => readFileSync(p, "utf8"), exists = existsSync, env = process.env, sysctl = systemSysctl } = {}) {
|
|
40
78
|
try {
|
|
41
|
-
if (platform === "linux")
|
|
79
|
+
if (platform === "linux") {
|
|
80
|
+
const id = read("/proc/sys/kernel/random/boot_id").trim();
|
|
81
|
+
if (!id) return null;
|
|
82
|
+
const start = inContainer(exists, env) ? initStart(read) : null;
|
|
83
|
+
return start === null ? id : `${id}:${start}`;
|
|
84
|
+
}
|
|
42
85
|
if (platform === "darwin") { const m = /sec = (\d+), usec = (\d+)/.exec(sysctl()); return m ? `${m[1]}.${m[2]}` : null; }
|
|
43
86
|
} catch { /* unknown */ }
|
|
44
87
|
return null;
|
|
@@ -46,6 +89,12 @@ export function bootId({ platform = process.platform, read = (p) => readFileSync
|
|
|
46
89
|
let processBoot;
|
|
47
90
|
/** bootId, read once per process: a process never outlives its boot. */
|
|
48
91
|
export const thisBoot = () => (processBoot === undefined ? (processBoot = bootId()) : processBoot);
|
|
92
|
+
/** Whether the lock record `holder` (the sweep's lock, a cache write lock: lib/remote.mjs) was taken
|
|
93
|
+
* in another boot than `boot`: its holder is gone then, whatever its pid reads as. A boot ends
|
|
94
|
+
* every process, and a pid and a start counted from the boot can both come again in the next (in a
|
|
95
|
+
* container, a boot is one run: bootId). Without a boot id on either side the process alone is
|
|
96
|
+
* judged. */
|
|
97
|
+
export const takenInAnotherBoot = (boot) => (holder) => Boolean(boot) && typeof holder.bootId === "string" && holder.bootId !== "" && holder.bootId !== boot;
|
|
49
98
|
|
|
50
99
|
const realOrResolved = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
|
|
51
100
|
/** The key of `home` in a record: its real path, so a deployment reached through a symlink (an
|
package/lib/start-env.mjs
CHANGED
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
/** What a start's launch environment was (feature session-resume, #1559): the record that lets a
|
|
2
|
-
* resume refuse to start under a
|
|
2
|
+
* resume refuse to start under a reference value that changed since the start it brings back.
|
|
3
3
|
* Kernel-private files in the home, not a contract:
|
|
4
4
|
* - `.oats-start-env.key`: 32 random bytes, mode 0600, made once, at the first start that records.
|
|
5
5
|
* It never leaves the home: never logged, answered or put in an event.
|
|
6
|
-
* - `.oats-start-env.json`: `{ startId, digests: { <
|
|
6
|
+
* - `.oats-start-env.json`: `{ startId, digests: { <reference source (env name or file:path)>: <hex HMAC-SHA256(key,
|
|
7
7
|
* value)> } }`, written whole (tmp + rename) at every start that renders a recipe, for that
|
|
8
8
|
* start's id; `digests` is `{}` for a launch with no reference. A value is never written: a
|
|
9
|
-
*
|
|
9
|
+
* reference value may be a credential, and only its keyed one-way digest is kept.
|
|
10
10
|
* The record is best effort: a write that fails leaves the previous record (for another start) or
|
|
11
11
|
* none, which a resume reads as unverified. A retire's recovery copy of the home leaves both out
|
|
12
|
-
* (lib/core.mjs copyRecoveryHome).
|
|
12
|
+
* (lib/core.mjs copyRecoveryHome). Uses only Node built-ins and kernel helpers: the start, the spawn and the sweep's
|
|
13
13
|
* `--plan` read and write it through here. */
|
|
14
|
+
import { fileReferenceProblems, fileReferenceRemedy } from "./launch-env.mjs";
|
|
14
15
|
import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
|
|
15
16
|
import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
16
17
|
import { join } from "node:path";
|
|
@@ -29,8 +30,13 @@ export function fromEnvNames(recipeEnv) {
|
|
|
29
30
|
}
|
|
30
31
|
|
|
31
32
|
/** The message of a resume refused for references that are not set (E_LAUNCH_ENV_MISSING). */
|
|
32
|
-
export function launchEnvMissingMessage(names) {
|
|
33
|
-
|
|
33
|
+
export function launchEnvMissingMessage(names, harness) {
|
|
34
|
+
const files = fileReferenceProblems(names);
|
|
35
|
+
if (files.length) {
|
|
36
|
+
const variables = names.filter((name) => !name.startsWith("file:"));
|
|
37
|
+
return [...(variables.length ? [`launch references ${variables.join(", ")}, not set on this host`] : []), ...files, "nothing was created or started"].join("; ") + fileReferenceRemedy(names, harness);
|
|
38
|
+
}
|
|
39
|
+
return `this home's launch references ${names.join(", ")}, not set on this host; nothing was started${fileReferenceRemedy(names, harness)}`;
|
|
34
40
|
}
|
|
35
41
|
/** The message of a resume refused for a changed value (E_LAUNCH_ENV_CHANGED): names only, sorted. */
|
|
36
42
|
export function launchEnvChangedMessage(names) {
|
|
@@ -64,7 +70,7 @@ function writeWhole(path, bytes) {
|
|
|
64
70
|
}
|
|
65
71
|
|
|
66
72
|
/** Record the launch environment of start `startId` of `home`: the digest of each of `names` (source
|
|
67
|
-
* names, fromEnvNames) as `env` holds it. A home without a usable key gets a new one first, and its
|
|
73
|
+
* names, fromEnvNames or launchEnvRefs source fields) as `env` holds it. A home without a usable key gets a new one first, and its
|
|
68
74
|
* old record goes before the key is replaced, so no record is ever read with a key it was not made
|
|
69
75
|
* with. Never throws: → true when the record was written. */
|
|
70
76
|
export function recordStartEnv(home, startId, names, env) {
|
package/lib/system-tools.mjs
CHANGED
|
@@ -5,7 +5,7 @@ import { accessSync, constants, statSync } from "node:fs";
|
|
|
5
5
|
import { isAbsolute, join } from "node:path";
|
|
6
6
|
|
|
7
7
|
/** Where a system tool is looked for, in order. */
|
|
8
|
-
export const SYSTEM_TOOL_DIRS = Object.freeze(["/usr/bin", "/bin"]);
|
|
8
|
+
export const SYSTEM_TOOL_DIRS = Object.freeze(["/usr/bin", "/bin", "/usr/sbin", "/sbin"]);
|
|
9
9
|
|
|
10
10
|
/** The directories a system tool is looked for in → { dirs } | { reason }. SYSTEM_TOOL_DIRS, or for a
|
|
11
11
|
* test only, OATS_TEST_SYSTEM_TOOL_DIRS: absolute directories separated by `:`. A seam with any other
|
package/lib/teams.mjs
CHANGED
|
@@ -128,6 +128,9 @@ export function discoveredTeamKeys(discovery) {
|
|
|
128
128
|
|
|
129
129
|
/** The `souls:` patterns that apply to `key`, most specific first. */
|
|
130
130
|
const patternsOf = (key) => (key === "*" ? ["*"] : [key, `${key.slice(0, key.lastIndexOf("/"))}/*`, "*"]);
|
|
131
|
+
/** Whether the pattern `<prefix>/*` applies to at least one of `soulKeys` (each `<member|package>/<soul>`).
|
|
132
|
+
* The slash is compared too, so `oats.eng/*` does not match `oats.engineering/x`. */
|
|
133
|
+
const patternMatchesAny = (pattern, soulKeys) => { const prefix = `${pattern.slice(0, -2)}/`; return [...soulKeys].some((k) => k.startsWith(prefix)); };
|
|
131
134
|
|
|
132
135
|
const unknown = (label, at) => fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared (${at}): declare it with \`oats teams add\`, or in oats-workspace.yaml teams: for a shared team`, { label, at });
|
|
133
136
|
const closedMessage = (keys) => `${LOCAL_FILE} declares ${keys.join(", ")}, but oats-workspace.yaml does not allow local teams (localTeams: true): ${CLOSED_FIX}`;
|
|
@@ -204,8 +207,9 @@ const unconfiguredProblem = (model) => ({ code: "E_TEAM_UNCONFIGURED", severity:
|
|
|
204
207
|
: `run \`oats aweb setup\` to create a team, then commit it in oats-workspace.yaml as defaultTeam (or as a soul's default in souls:)${model.localTeams ? ", or record it here with `oats teams add <label> --team <id>`" : ""}` });
|
|
205
208
|
const refusalProblem = (e) => ({ code: e.code, ...e.details, severity: "failure", message: e.message,
|
|
206
209
|
fix: "declare the team (`oats teams add`), or choose another default (`oats teams default`)" });
|
|
207
|
-
const soulUnknownProblem = (key, at) => ({ code: "team-soul-unknown", severity: "warning", key, at,
|
|
208
|
-
message: `souls: ${key}
|
|
210
|
+
const soulUnknownProblem = (key, at, pattern = false) => ({ code: "team-soul-unknown", severity: "warning", key, at,
|
|
211
|
+
...(pattern ? { message: `souls: ${key} is a pattern that matches no soul of this workspace`, fix: "correct the prefix to a member's or package's name (oats souls lists them), or remove the key" }
|
|
212
|
+
: { message: `souls: ${key} names no soul of this workspace (a pattern is "*" or <member|package>/*)`, fix: "correct the key to a soul's qualified name (oats souls lists them), or remove it" }) });
|
|
209
213
|
/** local-teams-closed as a problem (oats teams, readiness, doctor): the refusal's facts, never thrown. */
|
|
210
214
|
export const localTeamsClosedProblem = (keys) => ({ code: "E_WORKSPACE_SCHEMA", severity: "failure", condition: "local-teams-closed", path: LOCAL_FILE, keys: [...keys],
|
|
211
215
|
message: closedMessage(keys), fix: CLOSED_FIX });
|
|
@@ -216,7 +220,8 @@ export const localTeamsClosedProblem = (keys) => ({ code: "E_WORKSPACE_SCHEMA",
|
|
|
216
220
|
* With `key`: only what concerns that soul (`default` marks ITS default). Local teams the workspace does
|
|
217
221
|
* not allow are the one problem either way. `messaging`: a messaging layer is active, so no default is
|
|
218
222
|
* E_TEAM_UNCONFIGURED. `soulKeys` (discoveredTeamKeys; null when the souls are not known): a `souls:` key
|
|
219
|
-
* that is
|
|
223
|
+
* that is not one of them, or a `<prefix>/*` pattern that matches none of them, is `team-soul-unknown` (a typo
|
|
224
|
+
* guard, either way); `"*"` never is.
|
|
220
225
|
*/
|
|
221
226
|
export function teamProblems(model, { key = null, messaging = false, soulKeys = null } = {}) {
|
|
222
227
|
if (model.closedKeys.length) return [localTeamsClosedProblem(model.closedKeys)];
|
|
@@ -229,7 +234,9 @@ export function teamProblems(model, { key = null, messaging = false, soulKeys =
|
|
|
229
234
|
for (const label of labels) { const d = model.labels.get(label); if (d.team === null) problems.push(unmappedProblem(d, t)); }
|
|
230
235
|
if (messaging && t.defaultTeam === null && model.localDefault === null) problems.push(unconfiguredProblem(model));
|
|
231
236
|
if (soulKeys !== null) for (const k of Object.keys(model.souls).sort(byCodepoint)) {
|
|
232
|
-
if (k
|
|
237
|
+
if (k === "*") continue;
|
|
238
|
+
const pattern = k.endsWith("/*");
|
|
239
|
+
if (pattern ? !patternMatchesAny(k, soulKeys) : !soulKeys.has(k)) problems.push(soulUnknownProblem(k, `${model.soulsAt}/${pointerKey(k)}`, pattern));
|
|
233
240
|
}
|
|
234
241
|
return problems;
|
|
235
242
|
}
|
package/lib/upgrade-state.mjs
CHANGED
|
@@ -49,8 +49,9 @@ function retryFor(home, receipt) {
|
|
|
49
49
|
return { instance, command: `oats instance upgrade ${shellWord(instance)}${receipt.undo === true ? " --undo" : ""} --plan-revision ${shellWord(receipt.planRevision)} --idempotency-key ${shellWord(receipt.idempotencyKey)}` };
|
|
50
50
|
}
|
|
51
51
|
|
|
52
|
-
/** The
|
|
53
|
-
*
|
|
52
|
+
/** The command that finishes the upgrade whose regular file is at the home's `.oats-start.lock`,
|
|
53
|
+
* or null when no regular file is there (a start makes nothing at that path). A start never
|
|
54
|
+
* reclaims an upgrade's file, even if its owner died during the initial write. */
|
|
54
55
|
export function upgradeMutexRetry(home) {
|
|
55
56
|
const path = join(home, ".oats-start.lock");
|
|
56
57
|
try { if (!lstatSync(path).isFile()) return null; }
|
|
@@ -99,3 +100,13 @@ export function packageUpgradeDrift(meta, { lock } = {}) {
|
|
|
99
100
|
locked: { version: row.current.version ?? null, commit: row.current.commit ?? null },
|
|
100
101
|
}));
|
|
101
102
|
}
|
|
103
|
+
|
|
104
|
+
/** The start's line for package modules an upgrade cannot move: their package is no longer locked, or no
|
|
105
|
+
* longer provides the capability. An upgrade keeps them; a respawn moves the home onto the lock.
|
|
106
|
+
* → a warning string, or null when there are none. */
|
|
107
|
+
export function packageRespawnWarning(meta, { lock } = {}) {
|
|
108
|
+
const rows = driftOf(meta, null, { lock }).filter((row) => row.from.kind === "package" && row.status === "missing");
|
|
109
|
+
if (!rows.length) return null;
|
|
110
|
+
const why = (row) => row.reason === "capability-absent" ? `package ${row.recorded.package} no longer provides it` : `package ${row.recorded.package} is no longer locked`;
|
|
111
|
+
return `${rows.length} package module(s) cannot move in place (${rows.map((row) => `${row.module}: ${why(row)}`).join("; ")}); an upgrade keeps them as they are, so respawn this instance to move it onto the lock`;
|
|
112
|
+
}
|