@awebai/oats 0.52.0 → 0.53.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/bin/oats.mjs +304 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/desktop-cli-api.md +673 -58
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +175 -11
- package/docs/integrations.md +6 -3
- package/docs/knowledge.md +2 -2
- package/docs/macos-test-runs.md +246 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +210 -6
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +237 -15
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +93 -4
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +569 -121
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +5 -6
- package/lib/instance-lifecycle.mjs +145 -18
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +226 -15
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +6 -35
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/workspace.mjs +49 -19
- package/package-catalog.json +4 -4
- package/package.json +2 -1
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/cli-adapter.mjs +16 -3
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-contract.mjs +4 -0
- package/packages/client/deployment-facts.mjs +71 -10
- package/packages/client/deployment-panel.mjs +49 -11
- package/packages/client/deployment-read-cli.mjs +7 -3
- package/packages/client/display-text.mjs +8 -2
- package/packages/client/instance-acts.mjs +46 -10
- package/packages/client/instance-events-contract.mjs +4 -2
- package/packages/client/instance-presentation.mjs +66 -2
- package/packages/client/instance-tree.mjs +23 -14
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-prompt-outcome.mjs +51 -16
- package/packages/client/lifecycle-contract.mjs +45 -4
- package/packages/client/liveness.mjs +14 -1
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/panel-views.mjs +18 -11
- package/packages/client/readiness-contract.mjs +3 -1
- package/packages/client/remote-address.mjs +34 -9
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +92 -6
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-contract.mjs +16 -4
- package/packages/client/spawn-messages.mjs +26 -3
- package/packages/client/spawn-preview-cli.mjs +8 -2
- package/packages/client/spawn-preview-contract.mjs +5 -1
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-views.mjs +39 -3
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +30 -12
- package/packages/tui/lib/actions.mjs +16 -1
- package/packages/tui/lib/client.mjs +32 -1
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +117 -46
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +44 -0
- package/packages/tui/lib/term/screen.mjs +16 -4
- package/packages/tui/lib/term/text.mjs +60 -0
- package/packages/tui/lib/term/tty.mjs +13 -3
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +230 -36
- package/packages/tui/lib/views/help.mjs +125 -13
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/skills/oats-getting-started/SKILL.md +2 -2
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/** The one rule for a node path that is written into something that outlives
|
|
2
|
+
* the process (a unit, a harness's settings): a path that survives an upgrade
|
|
3
|
+
* of Node. The host timer's unit (lib/schedule-host.mjs) and OATS_NODE_BIN,
|
|
4
|
+
* which every hook, provider check and dispatched command receives, are both
|
|
5
|
+
* this rule's answer. It imports nothing of the kernel, so any module can. */
|
|
6
|
+
import { realpathSync } from "node:fs";
|
|
7
|
+
import { isAbsolute, join, resolve, sep } from "node:path";
|
|
8
|
+
|
|
9
|
+
/** A versioned Homebrew keg: <prefix>/Cellar/<formula>/<version>/…, gone at the next upgrade. */
|
|
10
|
+
const KEG = /^(.*)\/Cellar\/([^/]+)\/([^/]+)\//;
|
|
11
|
+
|
|
12
|
+
/** The installer's PATH entries a unit may carry. Dropped: entries inside an
|
|
13
|
+
* OATS instance home (an instance's `.oats/bin`, anything under
|
|
14
|
+
* `instanceHome`), entries inside a versioned Homebrew keg, and relative or
|
|
15
|
+
* empty entries. An entry missing today is kept: it may exist when the tick
|
|
16
|
+
* runs, and status reports it while it does not. */
|
|
17
|
+
export function unitPathEntries(envPath, { instanceHome = process.env.OATS_INSTANCE_HOME } = {}) {
|
|
18
|
+
const home = instanceHome && isAbsolute(instanceHome) ? resolve(instanceHome) : null;
|
|
19
|
+
const hazard = (entry) => {
|
|
20
|
+
if (!entry || !isAbsolute(entry)) return true;
|
|
21
|
+
const segments = entry.split(sep);
|
|
22
|
+
if (segments.some((s, i) => s === ".oats" && segments[i + 1] === "bin")) return true;
|
|
23
|
+
if (home && (resolve(entry) === home || resolve(entry).startsWith(home + sep))) return true;
|
|
24
|
+
return KEG.test(entry.endsWith("/") ? entry : `${entry}/`);
|
|
25
|
+
};
|
|
26
|
+
return String(envPath || "").split(":").filter((entry) => !hazard(entry));
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function realpathOrNull(p) { try { return realpathSync(p); } catch { return null; } }
|
|
30
|
+
/** A node path that survives a Homebrew upgrade. A keg's
|
|
31
|
+
* `<prefix>/opt/<formula>/bin/node` when it is this node, else the first
|
|
32
|
+
* `node` on the filtered PATH that is this node, else `execPath` with a
|
|
33
|
+
* warning that the path is not stable. The warning states the fact; the
|
|
34
|
+
* caller words what it loses (`consequence`) and what to do after installing
|
|
35
|
+
* a stable node (`remedy`). */
|
|
36
|
+
export function stableNode({ execPath = process.execPath, envPath = process.env.PATH || "", instanceHome = process.env.OATS_INSTANCE_HOME, consequence, remedy } = {}) {
|
|
37
|
+
const real = realpathOrNull(execPath);
|
|
38
|
+
const keg = real && KEG.exec(real);
|
|
39
|
+
if (keg) {
|
|
40
|
+
const opt = join(keg[1], "opt", keg[2], "bin", "node");
|
|
41
|
+
if (realpathOrNull(opt) === real) return { node: opt };
|
|
42
|
+
}
|
|
43
|
+
for (const entry of unitPathEntries(envPath, { instanceHome })) {
|
|
44
|
+
const candidate = join(entry, "node");
|
|
45
|
+
if (real && realpathOrNull(candidate) === real) return { node: candidate };
|
|
46
|
+
}
|
|
47
|
+
return { node: execPath, warning: `the node path ${execPath} is not stable (no Homebrew opt link and no node on PATH resolves to it)${consequence ? `: ${consequence}` : ""}${remedy ? `; install a node with a stable path and ${remedy}` : ""}` };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
let kernel = null;
|
|
51
|
+
/** The rule's answer for the node running this kernel, on the kernel's own
|
|
52
|
+
* PATH: `node` is OATS_NODE_BIN, and `warning` (the third case only) is what a
|
|
53
|
+
* spawn and a start say, worded for a home's hooks. The rule reads the file
|
|
54
|
+
* system, so it is computed once for the node, PATH and instance home this
|
|
55
|
+
* process runs with, not once per hook. */
|
|
56
|
+
export function kernelNode() {
|
|
57
|
+
const key = [process.execPath, process.env.PATH || "", process.env.OATS_INSTANCE_HOME || ""].join("\0");
|
|
58
|
+
if (kernel?.key !== key) {
|
|
59
|
+
kernel = { key, answer: stableNode({ consequence: "what this home's hooks record with it stops working when it goes away", remedy: "restart the instance" }) };
|
|
60
|
+
}
|
|
61
|
+
return kernel.answer;
|
|
62
|
+
}
|
package/lib/teams-verbs.mjs
CHANGED
|
@@ -7,15 +7,11 @@
|
|
|
7
7
|
* schema, and no label reference the write would leave unknown. A soul's teams are the workspace's
|
|
8
8
|
* `souls:`, edited by a PR to that file: `oats soul teams` only reads them.
|
|
9
9
|
*/
|
|
10
|
-
import { readFileSync } from "node:fs";
|
|
11
|
-
import { join } from "node:path";
|
|
12
10
|
import YAML from "yaml";
|
|
13
|
-
import { parseConfigData } from "./config-data.mjs";
|
|
14
11
|
import { oatsError } from "./errors.mjs";
|
|
15
|
-
import { teamLabelProblem
|
|
12
|
+
import { teamLabelProblem } from "./workspace.mjs";
|
|
16
13
|
import { TEAM_ID_RE, localTeamsClosed, soulTeams, teamModel, teamProblems, teamReferences } from "./teams.mjs";
|
|
17
|
-
import {
|
|
18
|
-
import { withDirLock } from "./dir-lock.mjs";
|
|
14
|
+
import { editLocal } from "./local-edit.mjs";
|
|
19
15
|
|
|
20
16
|
export const TEAMS_API = 2, SOUL_TEAMS_API = 2;
|
|
21
17
|
const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
@@ -66,13 +62,6 @@ const modelOf = (ctx, local) => teamModel(ctx.workspace, local, { workspaceKey:
|
|
|
66
62
|
const refusals = (ctx, local) => new Map(teamProblems(modelOf(ctx, local))
|
|
67
63
|
.filter((p) => p.code === "E_TEAM_UNKNOWN").map((p) => [`${p.code} ${p.at}`, p]));
|
|
68
64
|
const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
|
|
69
|
-
const readLocal = (ctx) => {
|
|
70
|
-
const text = readFileSync(ctx.localPath, "utf8");
|
|
71
|
-
const doc = YAML.parseDocument(text, { keepSourceTokens: true });
|
|
72
|
-
if (doc.errors?.length) throw fail("E_WORKSPACE_SCHEMA", `${ctx.localPath}: ${doc.errors[0].message}`, { path: ctx.localPath });
|
|
73
|
-
return { text, doc, local: parseConfigData(text, { origin: { kind: "local", path: ctx.localPath } }).value };
|
|
74
|
-
};
|
|
75
|
-
|
|
76
65
|
/**
|
|
77
66
|
* Edit `doc` from `before` to `next` SURGICALLY: only the entries that change are touched, so comments and
|
|
78
67
|
* styles on everything else (inline comments on sibling entries) are kept. A map left empty is removed.
|
|
@@ -94,46 +83,29 @@ function applyState(doc, before, next) {
|
|
|
94
83
|
}
|
|
95
84
|
|
|
96
85
|
/**
|
|
97
|
-
* Rewrite oats-local.yaml
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
86
|
+
* Rewrite oats-local.yaml through the shared edit path (lib/local-edit.mjs editLocal: the file as it is
|
|
87
|
+
* NOW, the deployment's local lock, compare-and-swap, the local schema). `mutate(state, model)` edits the
|
|
88
|
+
* plain `state` (teamState) and may throw a refusal; both come from the file as that path read it, so two
|
|
89
|
+
* verbs running together cannot drop each other's change, and a conditional write sees every earlier one.
|
|
101
90
|
* `verb` names the command and `writes` the keys it adds, for the refusal where the workspace does not
|
|
102
91
|
* allow local teams (local-teams-closed); a verb that only takes local teams away (`writes: null`) runs
|
|
103
92
|
* there too, since it moves the file toward what the workspace allows. → { changed, local } (the value now).
|
|
104
|
-
*
|
|
105
|
-
* writers the compare and the rename are one step: a conditional write sees every earlier one.
|
|
93
|
+
* A write is also refused when it would leave a label reference unknown that the file did not have.
|
|
106
94
|
*/
|
|
107
|
-
function
|
|
108
|
-
|
|
109
|
-
return withDirLock(lock, `${verb} on ${ctx.localPath}`, () => editLocalLocked(ctx, { verb, writes }, mutate), {
|
|
110
|
-
retryMs: 5000,
|
|
111
|
-
busy: (why) => fail("E_LOCAL_BUSY", `${ctx.localPath} is being edited by another oats process (the lock ${lock}: ${why}); if no oats teams command is running, remove ${lock} and retry; nothing was written`, { path: ctx.localPath, lock }),
|
|
112
|
-
});
|
|
113
|
-
}
|
|
114
|
-
/** The lock every `oats teams` mutation holds: in the deployment's kernel state tree, never beside the files. */
|
|
115
|
-
const localLock = (ctx) => join(ctx.deployment, ".agents", "locks", "local.lock");
|
|
116
|
-
function editLocalLocked(ctx, { verb, writes }, mutate) {
|
|
117
|
-
for (let attempt = 0; attempt < 5; attempt++) {
|
|
118
|
-
const { text, doc, local: current } = readLocal(ctx);
|
|
95
|
+
function editTeams(ctx, { verb, writes }, mutate) {
|
|
96
|
+
return editLocal(ctx, { verb }, ({ doc, local: current }) => {
|
|
119
97
|
const model = modelOf(ctx, current);
|
|
120
98
|
if (model.localTeams === false && writes !== null) throw localTeamsClosed(writes, { verb });
|
|
121
99
|
const before = teamState(current);
|
|
122
100
|
const next = teamState(current);
|
|
123
101
|
mutate(next, model);
|
|
124
|
-
if (same(next, before)) return
|
|
102
|
+
if (same(next, before)) return null;
|
|
125
103
|
applyState(doc, before, next);
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
for (const [k, p] of refusals(ctx, local)) if (!had.has(k)) throw fail(p.code, `${p.message}; nothing was written`, Object.fromEntries(Object.entries(p).filter(([key]) => !["code", "severity", "message", "fix"].includes(key))));
|
|
132
|
-
if (readFileSync(ctx.localPath, "utf8") !== text) continue; // changed under us: redo on the new content
|
|
133
|
-
writeFileAtomic(ctx.localPath, out);
|
|
134
|
-
return { changed: true, local };
|
|
135
|
-
}
|
|
136
|
-
throw fail("E_LOCAL_CHANGED", `${ctx.localPath} kept changing while this edit ran; nothing was written — run it again`, { path: ctx.localPath });
|
|
104
|
+
return { check: (local) => {
|
|
105
|
+
const had = refusals(ctx, current);
|
|
106
|
+
for (const [k, p] of refusals(ctx, local)) if (!had.has(k)) throw fail(p.code, `${p.message}; nothing was written`, Object.fromEntries(Object.entries(p).filter(([key]) => !["code", "severity", "message", "fix"].includes(key))));
|
|
107
|
+
} };
|
|
108
|
+
});
|
|
137
109
|
}
|
|
138
110
|
|
|
139
111
|
const assertLabel = (label) => {
|
|
@@ -149,7 +121,7 @@ export function teamsAdd(ctx, label, { team, description, noDefault = false } =
|
|
|
149
121
|
if (typeof team !== "string" || !team.trim()) throw fail("E_BAD_ARGS", "oats teams add needs --team <provider team id>", { label });
|
|
150
122
|
if (!TEAM_ID_RE.test(team.trim())) throw fail("E_BAD_ARGS", `${JSON.stringify(team)} is not a team id: it must match ${TEAM_ID_RE.source} (a letter or digit first; no whitespace or control characters; at most 256 characters)`, { label, team });
|
|
151
123
|
let reused = false;
|
|
152
|
-
const result =
|
|
124
|
+
const result = editTeams(ctx, { verb: "oats teams add", writes: ["teams"] }, (s, model) => {
|
|
153
125
|
if (model.labels.has(label)) {
|
|
154
126
|
const { from, team: existing } = model.labels.get(label);
|
|
155
127
|
if (noDefault && existing === team.trim()) { reused = true; return; }
|
|
@@ -165,7 +137,7 @@ export function teamsAdd(ctx, label, { team, description, noDefault = false } =
|
|
|
165
137
|
/** `oats teams remove <label>`: a LOCAL team nothing references (no cascade). Allowed where the workspace
|
|
166
138
|
* does not allow local teams: removing them is the last step of committing them there. */
|
|
167
139
|
export function teamsRemove(ctx, label) {
|
|
168
|
-
return
|
|
140
|
+
return editTeams(ctx, { verb: "oats teams remove", writes: null }, (s, model) => {
|
|
169
141
|
if (!model.local.has(label)) {
|
|
170
142
|
if (model.shared.has(label)) throw fail("E_TEAM_SHARED", `team ${label} is shared (declared in oats-workspace.yaml): it is edited by a PR to that file, never removed here`, { label, at: model.shared.get(label).at });
|
|
171
143
|
throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared`, { label });
|
|
@@ -192,7 +164,7 @@ function assertDefaultPrecondition(model, { ifAbsent, expect }) {
|
|
|
192
164
|
* judged inside the edit, on the file as it is now (and again on every retry), after today's refusals. */
|
|
193
165
|
export function teamsDefault(ctx, label, { ifAbsent = false, expect } = {}) {
|
|
194
166
|
if (ifAbsent && expect !== undefined) throw fail("E_BAD_ARGS", "oats teams default takes --if-absent or --expect <label>, not both", { label });
|
|
195
|
-
return
|
|
167
|
+
return editTeams(ctx, { verb: "oats teams default", writes: ["defaultTeam"] }, (s, model) => {
|
|
196
168
|
if (!model.labels.has(label)) throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared: \`oats teams add\` it first`, { label });
|
|
197
169
|
if (ifAbsent || expect !== undefined) assertDefaultPrecondition(model, { ifAbsent, expect });
|
|
198
170
|
s.defaultTeam = label;
|
package/lib/workspace.mjs
CHANGED
|
@@ -41,6 +41,12 @@ function remoteOf(options) {
|
|
|
41
41
|
/** The parsed cache (lib/remote.mjs memoAtCommit, optional on the remote contract): `compute()` is a pure
|
|
42
42
|
* function of the bytes at (ref's key, commit) and this kernel. A remote without it — every in-memory fake —
|
|
43
43
|
* just computes. */
|
|
44
|
+
/** Whether a member's enumeration may be missing a soul: it says so (`soulsSkipped`, enumerateRepo), or it
|
|
45
|
+
* carries no such record. What a read did not record, it did not establish: an enumeration that was not
|
|
46
|
+
* written by this build (whatever built it) says nothing about the souls it skipped, so it counts as one
|
|
47
|
+
* that skipped some. The parsed cache is not how that arises: its entries are kept per kernel fingerprint,
|
|
48
|
+
* and another build's are never read (lib/remote.mjs, test/parsed-cache.test.mjs). */
|
|
49
|
+
const skippedSome = (soulsSkipped) => !Array.isArray(soulsSkipped) || soulsSkipped.length > 0;
|
|
44
50
|
function atCommit(remote, ref, commit, item, compute) {
|
|
45
51
|
return typeof remote.memoAtCommit === "function" ? remote.memoAtCommit(ref, commit, item, compute) : compute();
|
|
46
52
|
}
|
|
@@ -532,18 +538,21 @@ const CAP_FILE = /^([^/]+)\/oats\.json$/;
|
|
|
532
538
|
/**
|
|
533
539
|
* Enumerate souls/*\/soul.yaml and capabilities/*\/oats.json of one repo at one commit.
|
|
534
540
|
* Validates each item; collects problems instead of aborting.
|
|
535
|
-
* → { souls: [SoulEntry], capabilities: [CapEntry], problems: [{ code, path, message, repoKey }]
|
|
541
|
+
* → { souls: [SoulEntry], capabilities: [CapEntry], problems: [{ code, path, message, repoKey }],
|
|
542
|
+
* soulsSkipped: [path] }: where a soul may exist and is not in `souls` (the souls/ listing failed, or
|
|
543
|
+
* a soul.yaml could not be read or is invalid). `problems` says why; this says that a soul is missing.
|
|
536
544
|
*/
|
|
537
545
|
async function enumerateRepo(remote, ref, key, commit) {
|
|
538
546
|
const souls = [];
|
|
539
547
|
const capabilities = [];
|
|
540
548
|
const problems = [];
|
|
549
|
+
const soulsSkipped = [];
|
|
541
550
|
const problem = (code, path, message) => problems.push({ code, repoKey: key, path, message });
|
|
542
551
|
// A listing failure on one directory is a problem of THIS repo, never an abort of the whole picture.
|
|
543
552
|
const list = async (dir) => {
|
|
544
553
|
try { return await remote.listRemoteTree(ref, commit, dir, { depth: 2 }); }
|
|
545
554
|
catch (e) {
|
|
546
|
-
if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, dir, e.message); return []; }
|
|
555
|
+
if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, dir, e.message); if (dir === "souls") soulsSkipped.push(dir); return []; }
|
|
547
556
|
throw e;
|
|
548
557
|
}
|
|
549
558
|
};
|
|
@@ -555,11 +564,12 @@ async function enumerateRepo(remote, ref, key, commit) {
|
|
|
555
564
|
const file = `${path}/soul.yaml`;
|
|
556
565
|
let bytes;
|
|
557
566
|
try { ({ bytes } = await remote.readRemoteFile(ref, commit, file)); }
|
|
558
|
-
catch (e) { problem(e?.code || "E_REMOTE_UNREADABLE", file, e.message); continue; }
|
|
567
|
+
catch (e) { problem(e?.code || "E_REMOTE_UNREADABLE", file, e.message); soulsSkipped.push(file); continue; }
|
|
559
568
|
const read = readDeclaration("soul", bytes, { kind: "soul", repoKey: key, commit, path: file });
|
|
560
|
-
if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
|
|
569
|
+
if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); soulsSkipped.push(file); continue; }
|
|
561
570
|
const definition = read.value;
|
|
562
571
|
if (definition.name !== m[1]) problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(m[1])}`);
|
|
572
|
+
// (A second declaration of a name is not a missing soul: the first one is listed under that name.)
|
|
563
573
|
if (soulNames.has(definition.name)) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} is already declared by ${soulNames.get(definition.name)}; the second declaration is not listed`); continue; }
|
|
564
574
|
soulNames.set(definition.name, file);
|
|
565
575
|
// Souls have no private mode since 0.26.0: `private` is accepted, warned (soul-private-ignored) and never hides a soul.
|
|
@@ -612,7 +622,7 @@ async function enumerateRepo(remote, ref, key, commit) {
|
|
|
612
622
|
else throw e;
|
|
613
623
|
}
|
|
614
624
|
}
|
|
615
|
-
return { souls, capabilities, publishes, problems };
|
|
625
|
+
return { souls, capabilities, publishes, problems, soulsSkipped };
|
|
616
626
|
}
|
|
617
627
|
|
|
618
628
|
/**
|
|
@@ -649,11 +659,12 @@ export function packageSoulAgentName(id, soul) { return `${String(id).replace(/[
|
|
|
649
659
|
* (`package`, `version`) and its qualified name `<package>/<soul>`. A package soul.yaml still carrying
|
|
650
660
|
* `team:` (removed in 0.30: team membership is local) is invalid and not listed.
|
|
651
661
|
* Nothing here trusts the lock's digests — a spawn verifies the fetched soul against them.
|
|
652
|
-
* `lock` null (or no workspace) → nothing. → { souls: [SoulEntry], problems }
|
|
662
|
+
* `lock` null (or no workspace) → nothing. → { souls: [SoulEntry], problems, skipped: [package id] }:
|
|
663
|
+
* `skipped` names each package with a soul the lock records and this read does not list.
|
|
653
664
|
*/
|
|
654
665
|
export async function discoverPackageSouls(workspace, lock, { remote: injected, remoteOptions } = {}) {
|
|
655
|
-
const souls = [], problems = [];
|
|
656
|
-
if (!isObject(lock?.packages) || !isObject(workspace)) return { souls, problems };
|
|
666
|
+
const souls = [], problems = [], skipped = new Set();
|
|
667
|
+
if (!isObject(lock?.packages) || !isObject(workspace)) return { souls, problems, skipped: [] };
|
|
657
668
|
const remote = remoteOf({ remote: injected, remoteOptions });
|
|
658
669
|
const declared = isObject(workspace.packages) ? workspace.packages : {};
|
|
659
670
|
for (const id of Object.keys(lock.packages).sort()) {
|
|
@@ -662,10 +673,10 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
|
|
|
662
673
|
const at = (rel) => `package:${id}:${rel}`;
|
|
663
674
|
const problem = (code, path, message) => problems.push({ code, repoKey: null, package: id, path: at(path), message });
|
|
664
675
|
const ref = lockedPackageRef(entry);
|
|
665
|
-
if (!ref) { problem("E_PACKAGE_MISSING", entry.path, `the lock records no url for ${id} — run \`oats sync\``); continue; }
|
|
676
|
+
if (!ref) { problem("E_PACKAGE_MISSING", entry.path, `the lock records no url for ${id} — run \`oats sync\``); skipped.add(id); continue; }
|
|
666
677
|
let key;
|
|
667
678
|
try { key = remote.parseRepoRef(ref).key; }
|
|
668
|
-
catch (e) { if (e?.code === "E_REPO_REF") { problem("E_REPO_REF", entry.path, e.message); continue; } throw e; }
|
|
679
|
+
catch (e) { if (e?.code === "E_REPO_REF") { problem("E_REPO_REF", entry.path, e.message); skipped.add(id); continue; } throw e; }
|
|
669
680
|
for (const locked of entry.souls) {
|
|
670
681
|
const path = `${entry.path}/${locked.path}`;
|
|
671
682
|
const file = `${path}/soul.yaml`;
|
|
@@ -675,10 +686,10 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
|
|
|
675
686
|
try { return readDeclaration("soul", (await remote.readRemoteFile(ref, entry.commit, file)).bytes, { kind: "soul", repoKey: key, commit: entry.commit, path: file }); }
|
|
676
687
|
catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) return { remoteError: { code: e.code, message: e.message } }; throw e; }
|
|
677
688
|
});
|
|
678
|
-
if (read.remoteError) { problem(read.remoteError.code, file, read.remoteError.message); continue; }
|
|
679
|
-
if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
|
|
689
|
+
if (read.remoteError) { problem(read.remoteError.code, file, read.remoteError.message); skipped.add(id); continue; }
|
|
690
|
+
if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); skipped.add(id); continue; }
|
|
680
691
|
const definition = read.value;
|
|
681
|
-
if (definition.name !== locked.name) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(locked.name)}`); continue; }
|
|
692
|
+
if (definition.name !== locked.name) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(locked.name)}`); skipped.add(id); continue; }
|
|
682
693
|
souls.push({
|
|
683
694
|
name: locked.name, path, repoKey: key, ref, commit: entry.commit, private: false, definition,
|
|
684
695
|
package: id, version: entry.version, qualifiedName: `${id}/${locked.name}`, agentName: packageSoulAgentName(id, locked.name), digest: locked.digest,
|
|
@@ -697,7 +708,13 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
|
|
|
697
708
|
problems.push({ code: "E_SOUL_AMBIGUOUS", repoKey: null, package: s.package, path: `package:${s.package}:${s.path}/soul.yaml`, message: `package souls ${qualified.join(" and ")} would share the agent directory agents/${dir}/ — keep one of the packages in packages:` });
|
|
698
709
|
}
|
|
699
710
|
}
|
|
700
|
-
return { souls, problems };
|
|
711
|
+
return { souls, problems, skipped: [...skipped] };
|
|
712
|
+
}
|
|
713
|
+
|
|
714
|
+
/** The packages the workspace declares and `lock` does not hold (declared, and `oats sync` not run since), by id. */
|
|
715
|
+
export function unlockedPackages(workspace, lock) {
|
|
716
|
+
const locked = isObject(lock?.packages) ? lock.packages : {};
|
|
717
|
+
return Object.keys(isObject(workspace?.packages) ? workspace.packages : {}).filter((id) => !Object.hasOwn(locked, id)).sort();
|
|
701
718
|
}
|
|
702
719
|
|
|
703
720
|
/** Members discovered at once (a fixed bound: the laptop's git and network, not the workspace's size). */
|
|
@@ -724,7 +741,13 @@ async function boundedMap(items, limit, task) {
|
|
|
724
741
|
/**
|
|
725
742
|
* The whole picture in one access context.
|
|
726
743
|
* → { workspace, members: [{ key, commit, confirmed, reason?, souls, capabilities, publishes }], external: [...],
|
|
727
|
-
* problems: [{ code, path, message, repoKey? }] }
|
|
744
|
+
* problems: [{ code, path, message, repoKey? }], soulsUnread }
|
|
745
|
+
* `soulsUnread` is where this read may be missing a soul, for the readers of oats-local.yaml souls.launch
|
|
746
|
+
* (lib/instance-resolution.mjs soulsOffered): { members: [repo key] (a confirmed member with a soul skipped,
|
|
747
|
+
* or whose enumeration carries no record of what it skipped: skippedSome),
|
|
748
|
+
* external: [source] (an external soul skipped), packages: [id] (a locked package with a soul skipped),
|
|
749
|
+
* unlocked: [id] (a package the workspace declares and `lock` does not hold) }. It is no part of any
|
|
750
|
+
* JSON answer: `problems` rows keep their fields.
|
|
728
751
|
* `publishes` = { package, version } when the member carries oats-package/oats-package.json (informational:
|
|
729
752
|
* the package's capabilities are NOT member capabilities — non-collapse rule), else null.
|
|
730
753
|
* Members are read DISCOVERY_CONCURRENCY at a time; rows and problems are assembled in declaration order.
|
|
@@ -754,21 +777,23 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
|
|
|
754
777
|
row.souls = items.souls;
|
|
755
778
|
row.capabilities = items.capabilities;
|
|
756
779
|
row.publishes = items.publishes;
|
|
757
|
-
return { row, problems: items.problems };
|
|
780
|
+
return { row, problems: items.problems, skipped: skippedSome(items.soulsSkipped) };
|
|
758
781
|
});
|
|
759
782
|
} finally {
|
|
760
783
|
// Every member listed now has adopted its prefetch (or the discovery failed): the rest, members dropped
|
|
761
784
|
// since the host's last observed commit, are given up.
|
|
762
785
|
remote.abandonPrefetches?.();
|
|
763
786
|
}
|
|
764
|
-
|
|
787
|
+
const soulsUnread = { members: [], external: [], packages: [], unlocked: [] };
|
|
788
|
+
// An unconfirmed member carries no enumeration at all: its row says so, and it is not "skipped" here.
|
|
789
|
+
for (const d of discovered) { members.push(d.row); problems.push(...d.problems); if (d.skipped) soulsUnread.members.push(d.row.key); }
|
|
765
790
|
const externalRows = [];
|
|
766
791
|
for (const [index, entry] of (workspace.external || []).entries()) {
|
|
767
792
|
const pin = entry.source.lastIndexOf("@");
|
|
768
793
|
const sourceRef = entry.source.slice(0, pin);
|
|
769
794
|
const commit = entry.source.slice(pin + 1);
|
|
770
795
|
const file = `${entry.soul.replace(/\/+$/, "")}/soul.yaml`;
|
|
771
|
-
const pushProblem = (code, path, message) => problems.push({ code, repoKey: null, path: `external/${index}:${path}`, message, source: entry.source });
|
|
796
|
+
const pushProblem = (code, path, message) => { problems.push({ code, repoKey: null, path: `external/${index}:${path}`, message, source: entry.source }); if (!soulsUnread.external.includes(entry.source)) soulsUnread.external.push(entry.source); };
|
|
772
797
|
let key;
|
|
773
798
|
try { key = refKey(remote, sourceRef); }
|
|
774
799
|
catch (e) { if (e?.code === "E_REPO_REF") { pushProblem("E_REPO_REF", "source", e.message); continue; } throw e; }
|
|
@@ -784,7 +809,9 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
|
|
|
784
809
|
}
|
|
785
810
|
const pkg = await discoverPackageSouls(workspace, lock, { remote });
|
|
786
811
|
problems.push(...pkg.problems);
|
|
787
|
-
|
|
812
|
+
soulsUnread.packages = pkg.skipped;
|
|
813
|
+
soulsUnread.unlocked = unlockedPackages(workspace, lock);
|
|
814
|
+
return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, packageSouls: pkg.souls, problems, soulsUnread, warnings: workspaceWarnings(workspace, members, externalRows, pkg.souls) };
|
|
788
815
|
}
|
|
789
816
|
|
|
790
817
|
/**
|
|
@@ -905,5 +932,8 @@ export function standaloneRepo(ref, commit, discovery, { remote: injected } = {}
|
|
|
905
932
|
standalone: true, key, commit: source.commit ?? commit ?? null, workspace: null,
|
|
906
933
|
members: [{ key, commit: source.commit ?? commit ?? null, confirmed: false, reason: "cannot-read", detail: `workspace of ${key} cannot be read; standalone view`, souls, capabilities, publishes: source.publishes ?? null }],
|
|
907
934
|
external: [], problems, warnings: [...privateSoulWarnings(souls), ...capabilityContractWarnings(capabilities)],
|
|
935
|
+
// As discoverWorkspace's: the repo's own souls are all this view offers, so only they can be missing.
|
|
936
|
+
// A discovery or an enumeration with no record of it counts as one with a soul skipped (skippedSome).
|
|
937
|
+
soulsUnread: { members: (Array.isArray(discovery.members) ? (!Array.isArray(discovery.soulsUnread?.members) || discovery.soulsUnread.members.includes(key)) : skippedSome(source.soulsSkipped)) ? [key] : [], external: [], packages: [], unlocked: [] },
|
|
908
938
|
};
|
|
909
939
|
}
|
package/package-catalog.json
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
"packages": {
|
|
4
4
|
"oats.okf": {
|
|
5
5
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
6
|
-
"ref": "v5.0.
|
|
6
|
+
"ref": "v5.0.3",
|
|
7
7
|
"path": "oats-package"
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.27.
|
|
11
|
+
"ref": "v1.27.1",
|
|
12
12
|
"path": "oats-package"
|
|
13
13
|
},
|
|
14
14
|
"oats.jira": {
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
},
|
|
29
29
|
"oats.engineering": {
|
|
30
30
|
"url": "https://github.com/awebai/oats-engineering.git",
|
|
31
|
-
"ref": "v1.9.
|
|
31
|
+
"ref": "v1.9.1",
|
|
32
32
|
"path": "oats-package"
|
|
33
33
|
},
|
|
34
34
|
"oats.cloning": {
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
},
|
|
44
44
|
"oats.framework": {
|
|
45
45
|
"url": "https://github.com/awebai/oats.git",
|
|
46
|
-
"ref": "oats-framework/v1.9.
|
|
46
|
+
"ref": "oats-framework/v1.9.4",
|
|
47
47
|
"path": "oats-package"
|
|
48
48
|
}
|
|
49
49
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.53.0",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"type": "module",
|
|
16
16
|
"scripts": {
|
|
17
17
|
"test": "node scripts/run-tests.mjs",
|
|
18
|
+
"test:session": "node scripts/test-session-inheritance.mjs",
|
|
18
19
|
"check": "node scripts/check-package-dry-runs.mjs --syntax-only",
|
|
19
20
|
"check:pi": "node --experimental-strip-types --check packages/pi/extension/index.ts",
|
|
20
21
|
"validate": "node scripts/validate-project.mjs",
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/** What an attach's exit status says, as a word. A client compares no number: the kernel's table is
|
|
2
|
+
* read here and nowhere else (docs/execution-targets.md, "Exit status"; docs/servers.md, "Run there",
|
|
3
|
+
* for the routed form).
|
|
4
|
+
*
|
|
5
|
+
* attachExit(status, { keyed, routed }) -> "left" | "ended" | "failed" | "link" | "unknown"
|
|
6
|
+
*
|
|
7
|
+
* left 20, for an attach given a detach key: left by the key. The agent keeps running.
|
|
8
|
+
* ended 0: the viewer ended without the key. It says nothing of the agent.
|
|
9
|
+
* failed 1: a refusal, or tmux failing under the viewer. Routed: also a refusal on this side,
|
|
10
|
+
* and an ssh that could not be run here.
|
|
11
|
+
* link 255, for a routed attach: ssh's own failure, before the viewer or under it.
|
|
12
|
+
* unknown anything else: 20 without a key, 255 on this machine, any other number, null (the
|
|
13
|
+
* child was ended by a signal), any value that is not a number.
|
|
14
|
+
*
|
|
15
|
+
* `status` is the child's exit status as Node reports it. `keyed`: the attach was started with
|
|
16
|
+
* `--detach-key`. `routed`: it was started with `--server`. Each counts only when it is `true`.
|
|
17
|
+
* No sentence is here: the words a person reads are each client's. This module imports nothing, so
|
|
18
|
+
* a page can load it. */
|
|
19
|
+
export function attachExit(status, options) {
|
|
20
|
+
if (status === 20 && options?.keyed === true) return "left";
|
|
21
|
+
if (status === 0) return "ended";
|
|
22
|
+
if (status === 1) return "failed";
|
|
23
|
+
if (status === 255 && options?.routed === true) return "link";
|
|
24
|
+
return "unknown";
|
|
25
|
+
}
|
|
@@ -30,16 +30,20 @@ import { isAbsolute, join } from "node:path";
|
|
|
30
30
|
import { gitFileId, gitRevision, gitIndexRevision, gitObservation } from './instance-git-contract.mjs';
|
|
31
31
|
import { validMaxAge, maxAgeArgv } from './deployment-contract.mjs';
|
|
32
32
|
import { MACHINE_ID, machineFieldProblem } from './machine-contract.mjs';
|
|
33
|
+
import { kernelMade } from './kernel-made.mjs';
|
|
33
34
|
|
|
34
35
|
const ENVELOPE_TIMEOUT_MS = 60_000;
|
|
35
36
|
|
|
36
|
-
/** Parse the single-JSON-object stdout contract; null when contaminated.
|
|
37
|
+
/** Parse the single-JSON-object stdout contract; null when contaminated.
|
|
38
|
+
* The error of an `ok: false` envelope is marked the kernel's here (kernel-made.mjs), where the CLI's
|
|
39
|
+
* answer is parsed and nowhere else: an envelope a reader writes itself (a timeout, a protocol failure,
|
|
40
|
+
* `parseRetireEnvelope`'s incomplete cleanup) is never parsed, so its error carries no mark. */
|
|
37
41
|
export function parseEnvelope(stdout) {
|
|
38
42
|
try {
|
|
39
43
|
const doc = JSON.parse(String(stdout));
|
|
40
44
|
if (!doc || typeof doc !== "object" || doc.schemaVersion !== 1) return null;
|
|
41
45
|
if (doc.ok === true && doc.result && typeof doc.result === "object") return doc;
|
|
42
|
-
if (doc.ok === false && doc.error && typeof doc.error === "object") return doc;
|
|
46
|
+
if (doc.ok === false && doc.error && typeof doc.error === "object") { kernelMade(doc.error); return doc; }
|
|
43
47
|
return null;
|
|
44
48
|
} catch { return null; }
|
|
45
49
|
}
|
|
@@ -404,9 +408,18 @@ export function cliSoulTeams(bin, { soul, add, remove, defaultLabel, clearDefaul
|
|
|
404
408
|
return runJson(bin, argv, { cwd: workspaceDir, exec: io.exec, timeout: io.timeout || 15_000 });
|
|
405
409
|
}
|
|
406
410
|
|
|
411
|
+
/** The roster's envelope as the CLI printed it. A group the kernel could not reach carries the kernel's
|
|
412
|
+
* own error in `probe.error`: each is marked the kernel's here (kernel-made.mjs), as `parseEnvelope` marks
|
|
413
|
+
* the envelope's own. remote-roster.mjs `remotePanel` reads the mark to say who made a row's text. */
|
|
414
|
+
function parseRosterEnvelope(stdout) {
|
|
415
|
+
const doc = parseEnvelope(stdout);
|
|
416
|
+
if (doc?.ok === true && Array.isArray(doc.result.groups)) for (const group of doc.result.groups) kernelMade(group?.probe?.error);
|
|
417
|
+
return doc;
|
|
418
|
+
}
|
|
419
|
+
|
|
407
420
|
/** One bounded aggregate read; the CLI owns registry and saved-route resolution. */
|
|
408
421
|
export function cliRemoteRoster(bin, io = {}) {
|
|
409
|
-
return runJson(bin, ["server", "roster", "--json"], { cwd: io.cwd || process.cwd(), exec: io.exec, timeout: io.timeout || 60_000 });
|
|
422
|
+
return runJson(bin, ["server", "roster", "--json"], { cwd: io.cwd || process.cwd(), exec: io.exec, timeout: io.timeout || 60_000, parse: parseRosterEnvelope });
|
|
410
423
|
}
|
|
411
424
|
|
|
412
425
|
/** Local retire predates the envelope; preserve its incomplete-cleanup result. */
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
// Every candidate is canonicalized to an absolute executable and accepted
|
|
14
14
|
// ONLY if executable and `<bin> version --json` returns the v1 probe:
|
|
15
15
|
// {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
|
|
16
|
-
// Desktop accepts desktopApi === 1 and semver >=0.25.8 <0.
|
|
16
|
+
// Desktop accepts desktopApi === 1 and semver >=0.25.8 <0.54.0 (the band is
|
|
17
17
|
// spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
|
|
18
18
|
// API version — not source adjacency — is authoritative.
|
|
19
19
|
//
|
|
@@ -54,7 +54,7 @@ export const DESKTOP_API = 1;
|
|
|
54
54
|
// carry a `description` for every kind and `<kind> update <id> --description`
|
|
55
55
|
// sets one (feature `automation-descriptions`, which gates the Desktop's
|
|
56
56
|
// summary writes). The Desktop v1 surface is otherwise unchanged.
|
|
57
|
-
export const ACCEPT_RANGE = { min: [0, 25, 8], maxExclusive: [0,
|
|
57
|
+
export const ACCEPT_RANGE = { min: [0, 25, 8], maxExclusive: [0, 54, 0] };
|
|
58
58
|
/** The band as humans read it — derived, never hand-spelled, so the probe
|
|
59
59
|
* rejection reason, the backend's /api status and the degradation card can
|
|
60
60
|
* never disagree with the numbers actually enforced above. */
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
/** Native workspace-v2 read contract. No filesystem discovery or generation adapters. */
|
|
2
2
|
export const DEPLOYMENT_FEATURES = Object.freeze(['workspace-v2', 'instance-modules', 'served-identity', 'packages-no-approval']);
|
|
3
3
|
export const deploymentRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
4
|
+
/** The code of a kernel error envelope, as the deployment reader admits one (deployment-read-cli.mjs): the one
|
|
5
|
+
* test of its shape. A reason the reader marks `origin: 'kernel'` always carries such a code, and the sentence
|
|
6
|
+
* that attributes a reason to the kernel (deployment-facts.mjs) asks for both. */
|
|
7
|
+
export const deploymentErrorCode = value => typeof value === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(value);
|
|
4
8
|
|
|
5
9
|
/* Spec D: why a remote read failed (kernel E_REMOTE_UNREADABLE `details.reason`, e.g. "cache", "network",
|
|
6
10
|
* "timeout"), bounded. Only the reason and the host of `details.url` cross; never paths, pids, locks or the
|
|
@@ -5,6 +5,8 @@
|
|
|
5
5
|
* A page loads this module: it imports no Node builtin, and must not (the
|
|
6
6
|
* panel's own functions, which do, are in deployment-panel.mjs). */
|
|
7
7
|
import { requireTerms } from './client-terms.mjs';
|
|
8
|
+
import { displayLine, DETAIL_WITHHELD } from './display-text.mjs';
|
|
9
|
+
import { deploymentErrorCode } from './deployment-contract.mjs';
|
|
8
10
|
|
|
9
11
|
const text = value => typeof value === 'string' && value ? value : null;
|
|
10
12
|
/** A member's display label from its repo key (the kernel's `memberLabel`). */
|
|
@@ -19,16 +21,75 @@ export function servedIdentityText(identity) {
|
|
|
19
21
|
return `alias ${text(identity.alias) || '?'} on ${text(identity.team) || '?'}`;
|
|
20
22
|
}
|
|
21
23
|
|
|
22
|
-
/**
|
|
23
|
-
* client shows
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
24
|
+
/**
|
|
25
|
+
* The parts of what a client shows for a deployment the kernel could not observe (workspace model v2), in the
|
|
26
|
+
* order they are shown: `{ headline, lead, sentence }`, each one line or null. A fresh object at every call.
|
|
27
|
+
*
|
|
28
|
+
* still reading (no deployment yet, or `pending`) headline: that it is being read
|
|
29
|
+
* observed every part null
|
|
30
|
+
* a missing advertised feature (`reason.feature`) headline: the feature, in the client's terms
|
|
31
|
+
* (client-terms.mjs: the client that needs it)
|
|
32
|
+
* the kernel refused (`reason.origin === 'kernel'` headline: "OATS answered with an error (<code>)."
|
|
33
|
+
* and a code the reader admits) lead: "It says:"; sentence: the kernel's message
|
|
34
|
+
* any other reason headline: `<code>: <message>`, or the message, as one
|
|
35
|
+
* display line; or that the deployment could not be observed
|
|
36
|
+
*
|
|
37
|
+
* `sentence` is the only part that can carry words the client did not write: the kernel's message through
|
|
38
|
+
* the display filter (display-text.mjs `displayLine`), one line, whole or DETAIL_WITHHELD, never cut by its
|
|
39
|
+
* words, parsed or matched. A message the filter withholds, or one with nothing to show, is not introduced:
|
|
40
|
+
* no lead (the rule of lifecycle-contract.mjs `busyRefusal`). The reason is attributed to the kernel only by
|
|
41
|
+
* its mark, which the reader gives to the error the installed CLI printed (deployment-read-cli.mjs); any other
|
|
42
|
+
* value of `origin`, or the mark with a code the reader would not have admitted, reads as none. A reason
|
|
43
|
+
* without the mark is one the client made itself (deployment-contract.mjs `deploymentFailure`): its message is
|
|
44
|
+
* the client's own sentence, and each of those reads through the filter byte for byte as it is written. The
|
|
45
|
+
* line goes through the filter all the same, whole: a reason of that shape that holds anything else is one
|
|
46
|
+
* line too, or DETAIL_WITHHELD alone, or (with nothing to show) that the deployment could not be observed.
|
|
47
|
+
*
|
|
48
|
+
* A client that sets the kernel's words apart from its own (a quote, another style) calls this; one that
|
|
49
|
+
* shows one line calls `deploymentUnavailableText`.
|
|
50
|
+
*/
|
|
51
|
+
export function deploymentUnavailableParts(deployment, terms) {
|
|
52
|
+
requireTerms(terms, 'deploymentUnavailableParts');
|
|
53
|
+
const own = headline => ({ headline, lead: null, sentence: null });
|
|
54
|
+
if (!deployment || deployment.status === 'pending') return own('Reading the deployment through the installed OATS CLI…');
|
|
55
|
+
if (deployment.status === 'observed') return own(null);
|
|
30
56
|
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
|
|
57
|
+
if (reason.feature) return own(`The installed OATS CLI does not advertise ${reason.feature}, which the ${terms.name} needs to show this deployment. Update OATS and retry.`);
|
|
58
|
+
if (reason.origin === 'kernel' && deploymentErrorCode(reason.code)) {
|
|
59
|
+
const sentence = displayLine(reason.message);
|
|
60
|
+
return { headline: `OATS answered with an error (${reason.code}).`, lead: sentence !== null && sentence !== DETAIL_WITHHELD ? 'It says:' : null, sentence };
|
|
61
|
+
}
|
|
62
|
+
// The reader's own reason, through the display filter like every other form: the whole line at once, so
|
|
63
|
+
// the guarantee does not rest on where the callers are (a hand-made reason, a code that is not a code).
|
|
32
64
|
const code = text(reason.code), message = text(reason.message);
|
|
33
|
-
return code && message ? `${code}: ${message}` : message
|
|
65
|
+
return own(displayLine(code && message ? `${code}: ${message}` : message) ?? 'The deployment could not be observed.');
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Whether what a client holds for a deployment is a kept failure: its last read failed and what was
|
|
69
|
+
* observed before is still shown (deployment-panel.mjs `failedEntry`). `held` is a deployment's entry or
|
|
70
|
+
* a panel made from one (panel-views.mjs `deploymentPanel`, `panelData`); the answer is null, or
|
|
71
|
+
*
|
|
72
|
+
* { message, origin } message: the failure's text, a string, possibly empty
|
|
73
|
+
* origin: "kernel" when the installed CLI printed it, else null
|
|
74
|
+
*
|
|
75
|
+
* **The fact does not depend on the text.** `error` is a string exactly when a failure is kept, and an
|
|
76
|
+
* empty, blank or withheld message is as much a kept failure as any other: a kernel that fails with no
|
|
77
|
+
* words has still failed. This is the one place that decides it. A client asks here whether a deployment
|
|
78
|
+
* is stale and never tests `error` for truth, so the shared reason and each of a client's notices agree.
|
|
79
|
+
*
|
|
80
|
+
* `origin` is `errorOrigin` read strictly: the one value `failedEntry` writes, anything else null. A
|
|
81
|
+
* panel of another machine (remote-roster.mjs `remotePanel`) never carries the key; its `error` is a
|
|
82
|
+
* string while that machine was not reached, and reads here as a failure with no speaker.
|
|
83
|
+
* Not on the stable surface. */
|
|
84
|
+
export function keptFailure(held) {
|
|
85
|
+
if (held === null || typeof held !== 'object' || typeof held.error !== 'string') return null;
|
|
86
|
+
return { message: held.error, origin: held.errorOrigin === 'kernel' ? 'kernel' : null };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** The sentence a client shows in place of a deployment's rows when the kernel could not observe it: the parts
|
|
90
|
+
* that are there (`deploymentUnavailableParts`), joined by one space. '' for an observed deployment. */
|
|
91
|
+
export function deploymentUnavailableText(deployment, terms) {
|
|
92
|
+
requireTerms(terms, 'deploymentUnavailableText');
|
|
93
|
+
const { headline, lead, sentence } = deploymentUnavailableParts(deployment, terms);
|
|
94
|
+
return [headline, lead, sentence].filter(part => part !== null).join(' ');
|
|
34
95
|
}
|