@awebai/oats 0.52.0 → 0.54.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/bin/oats.mjs +314 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +696 -60
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +184 -12
- package/docs/integrations.md +6 -3
- package/docs/knowledge.md +2 -2
- package/docs/macos-test-runs.md +246 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +210 -6
- package/docs/release-notes/v0.53.0.md +1288 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +239 -16
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +310 -0
- package/docs/workspaces.md +123 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +93 -4
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +569 -121
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +5 -6
- package/lib/instance-lifecycle.mjs +145 -18
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +226 -15
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +18 -5
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +404 -60
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +6 -35
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/workspace.mjs +75 -27
- package/package-catalog.json +4 -4
- package/package.json +2 -1
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/cli-adapter.mjs +16 -3
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-contract.mjs +4 -0
- package/packages/client/deployment-facts.mjs +71 -10
- package/packages/client/deployment-panel.mjs +49 -11
- package/packages/client/deployment-read-cli.mjs +7 -3
- package/packages/client/display-text.mjs +8 -2
- package/packages/client/instance-acts.mjs +46 -10
- package/packages/client/instance-events-contract.mjs +4 -2
- package/packages/client/instance-presentation.mjs +66 -2
- package/packages/client/instance-tree.mjs +23 -14
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-prompt-outcome.mjs +51 -16
- package/packages/client/lifecycle-contract.mjs +45 -4
- package/packages/client/liveness.mjs +14 -1
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/panel-views.mjs +18 -11
- package/packages/client/readiness-contract.mjs +3 -1
- package/packages/client/remote-address.mjs +34 -9
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +92 -6
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-contract.mjs +16 -4
- package/packages/client/spawn-messages.mjs +26 -3
- package/packages/client/spawn-preview-cli.mjs +8 -2
- package/packages/client/spawn-preview-contract.mjs +5 -1
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-views.mjs +39 -3
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +30 -12
- package/packages/tui/lib/actions.mjs +16 -1
- package/packages/tui/lib/client.mjs +32 -1
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +117 -46
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +44 -0
- package/packages/tui/lib/term/screen.mjs +16 -4
- package/packages/tui/lib/term/text.mjs +60 -0
- package/packages/tui/lib/term/tty.mjs +13 -3
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +230 -36
- package/packages/tui/lib/views/help.mjs +125 -13
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/skills/oats-getting-started/SKILL.md +8 -2
package/lib/claim.mjs
CHANGED
|
@@ -38,6 +38,15 @@
|
|
|
38
38
|
* message is rewritten here. A refusal that was made without them is still answered after
|
|
39
39
|
* them (claimUnavailable). A refusal before any effect stays what its caller made it.
|
|
40
40
|
* - Released by unlinking `path`, only while it still names this holding.
|
|
41
|
+
* - A claim that could not be WRITTEN is marked as that, for the one caller that then reads it
|
|
42
|
+
* in place of taking it (`oats instance stop --apply`: lib/core.mjs claimHomeFor). The mark is
|
|
43
|
+
* made at the place, one of the claim's writes (claimWrite: its directory, its private file,
|
|
44
|
+
* its link, and the same of a takeover's own claim), for the system's code as it was thrown
|
|
45
|
+
* there, one of CLAIM_UNWRITABLE_CODES; it travels on the refusal (unwritableCode). No reader
|
|
46
|
+
* of an answer's code, words or details can tell this failure from another, and none tries:
|
|
47
|
+
* a defect, and a claim that could not be removed, are E_LIFECYCLE_FAILED too. Whether
|
|
48
|
+
* anybody holds a claim that was not taken is read by claimUnheld, which says "nobody" only
|
|
49
|
+
* of a path that is absent or of a claim whose holder is verifiably gone.
|
|
41
50
|
* - A claim is read back as whatever JSON is in its file, and the file is where others than its
|
|
42
51
|
* writer can write. Who holds it, and whether that process lives, is decided on the record as
|
|
43
52
|
* it is; what an ANSWER shows of it is only what shownHolder allows, never the file's text.
|
|
@@ -84,7 +93,7 @@
|
|
|
84
93
|
* owner (a home's lifecycle claim: `action`, the holder's verb).
|
|
85
94
|
* It is in the record that is linked, so the claim is never
|
|
86
95
|
* seen without it; the owner's four fields win over it */
|
|
87
|
-
import { linkSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
|
|
96
|
+
import { linkSync, lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
|
|
88
97
|
import { randomBytes } from "node:crypto";
|
|
89
98
|
import { isStartToken, processLiveness, processStart } from "./worktree-hooks.mjs";
|
|
90
99
|
import { NOTHING_ELSE, afterEndedSteps, asKernelError, nothingAfter } from "./errors.mjs";
|
|
@@ -130,6 +139,39 @@ export function shownHolder(record) {
|
|
|
130
139
|
};
|
|
131
140
|
}
|
|
132
141
|
|
|
142
|
+
/** The system's codes for which a claim that cannot be written is read in place of being taken, by
|
|
143
|
+
* the one verb that may (a stop apply). Each is here for one reason: what stops this process
|
|
144
|
+
* from writing a claim in that directory stops a retire or another stop of the same user as
|
|
145
|
+
* well, so a claim that reads as held by nobody is held by nobody.
|
|
146
|
+
* ENOSPC the file system is full
|
|
147
|
+
* EDQUOT this user's quota is spent
|
|
148
|
+
* EROFS the file system is read-only
|
|
149
|
+
* EACCES, EPERM the claims directory is not writable by this user (EPERM also where the file
|
|
150
|
+
* system has no hard links). Every instance of a deployment can change that
|
|
151
|
+
* directory, and one that takes write permission from it must not take Stop from the
|
|
152
|
+
* operator.
|
|
153
|
+
* It is not true of space that is freed a moment later, nor of a process of another user. Any
|
|
154
|
+
* other code (EIO, EMFILE, ENAMETOOLONG, EEXIST from a file where the directory belongs) says
|
|
155
|
+
* nothing about who else could write there, and is never in this list. */
|
|
156
|
+
export const CLAIM_UNWRITABLE_CODES = Object.freeze(["ENOSPC", "EDQUOT", "EROFS", "EACCES", "EPERM"]);
|
|
157
|
+
const UNWRITABLE = Symbol("oats.claimUnwritable");
|
|
158
|
+
/** Make one of a claim's writes: `write()`, and what it returns. An error of the system's it
|
|
159
|
+
* throws with a code of CLAIM_UNWRITABLE_CODES is marked with that code and thrown as it is:
|
|
160
|
+
* the place and the code as thrown are what make a claim "one that could not be written"
|
|
161
|
+
* (unwritableCode). For the writes of taking a claim and for no other call: its directory
|
|
162
|
+
* (the caller's mkdir), its private file, its link. */
|
|
163
|
+
export function claimWrite(write) {
|
|
164
|
+
try { return write(); }
|
|
165
|
+
catch (e) {
|
|
166
|
+
if (e instanceof Error && typeof e.syscall === "string" && CLAIM_UNWRITABLE_CODES.includes(e.code)) Object.defineProperty(e, UNWRITABLE, { value: e.code });
|
|
167
|
+
throw e;
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
/** The code for which the claim behind `refusal` could not be written (CLAIM_UNWRITABLE_CODES),
|
|
171
|
+
* when that is why it was not taken and nothing was ended before; else undefined. `refusal` is
|
|
172
|
+
* what acquireClaim or claimUnavailable answered. */
|
|
173
|
+
export const unwritableCode = (refusal) => (refusal instanceof Error ? refusal[UNWRITABLE] : undefined);
|
|
174
|
+
|
|
133
175
|
/** The refusal for a claim `path` that could not be taken because of `e`, an error that is not the
|
|
134
176
|
* kernel's. The caller's command did nothing: it acts only once it holds its claim. Also for a
|
|
135
177
|
* caller that fails to make the claim's directory. `ended` is what this acquisition's takeovers
|
|
@@ -140,7 +182,52 @@ export function shownHolder(record) {
|
|
|
140
182
|
* comes after something was done says so (takeOver: the claim of a gone holder that cannot be
|
|
141
183
|
* removed once that holder's step was ended). */
|
|
142
184
|
export function claimUnavailable(path, e, ended) {
|
|
143
|
-
|
|
185
|
+
const refusal = asKernelError(e, "E_LIFECYCLE_FAILED", `the claim ${path} could not be taken (${e?.message ?? e}); ${nothingAfter(ended)}`);
|
|
186
|
+
// The mark of a write that failed (claimWrite) goes with the refusal. Once something was ended
|
|
187
|
+
// the answer is another error, made below, and carries none: nobody reads a claim in the place
|
|
188
|
+
// of an answer that says what was done.
|
|
189
|
+
const code = unwritableCode(e);
|
|
190
|
+
if (code && refusal !== e) Object.defineProperty(refusal, UNWRITABLE, { value: code });
|
|
191
|
+
return afterEndedSteps(ended, refusal);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** Whether anybody holds the claim `path`, read and not taken: for the caller whose claim could
|
|
195
|
+
* not be written (unwritableCode). Returns when NOBODY holds it, which is said only of a path
|
|
196
|
+
* that is absent and of a claim whose holder is verifiably gone and that could be taken over
|
|
197
|
+
* (it is left as it is). Throws otherwise, what taking it would have answered for what is
|
|
198
|
+
* there, from the caller's refusals (`opts`, as acquireClaim takes them):
|
|
199
|
+
* a holder that lives, or whose liveness cannot be read busy
|
|
200
|
+
* bytes that are no claim; a directory; a path that is
|
|
201
|
+
* there and reads as absent (a dangling symbolic link) unreadableClaim
|
|
202
|
+
* a gone holder whose claim no kernel can take over cannotTakeOver
|
|
203
|
+
* and `otherwise`, the refusal of the write that failed, when the read itself fails for a
|
|
204
|
+
* reason of the system's: the path was not reached, so neither a holder nor nobody was
|
|
205
|
+
* established. The read is positive or it is nothing. */
|
|
206
|
+
export function claimUnheld(path, opts, otherwise) {
|
|
207
|
+
for (let pass = 0; ; pass++) {
|
|
208
|
+
let text;
|
|
209
|
+
try { text = readFileSync(path, "utf8"); }
|
|
210
|
+
catch (e) {
|
|
211
|
+
// Something is there that is no file to read: no claim, as the taking finds it.
|
|
212
|
+
if (e?.code === "EISDIR") throw opts.unreadableClaim(path, []);
|
|
213
|
+
if (e?.code !== "ENOENT") throw otherwise;
|
|
214
|
+
// Absent, unless the path itself is there: a link to nowhere reads as absent for ever.
|
|
215
|
+
let entry;
|
|
216
|
+
try { entry = lstatSync(path); } catch (e2) { if (e2?.code === "ENOENT") return; throw otherwise; }
|
|
217
|
+
// A claim made between the two reads is read again, once, and is a claim.
|
|
218
|
+
if (entry.isSymbolicLink() || pass) throw opts.unreadableClaim(path, []);
|
|
219
|
+
continue;
|
|
220
|
+
}
|
|
221
|
+
let holder;
|
|
222
|
+
try { holder = JSON.parse(text); } catch { holder = null; }
|
|
223
|
+
// readClaim's own reading of bytes that are no claim, `unreadable` in a record included.
|
|
224
|
+
if (!holder || typeof holder !== "object" || holder.unreadable) throw opts.unreadableClaim(path, []);
|
|
225
|
+
const live = processLiveness(holder);
|
|
226
|
+
if (live.state !== "gone") throw opts.busy(holder, live.state === "unknown" ? live.reason : null, path, []);
|
|
227
|
+
const stuck = cannotBeTakenOver(holder, 0);
|
|
228
|
+
if (stuck) throw opts.cannotTakeOver(holder, path, stuck, []);
|
|
229
|
+
return;
|
|
230
|
+
}
|
|
144
231
|
}
|
|
145
232
|
|
|
146
233
|
/** Take the claim `path` → this holding (`{ pid, processStart, nonce, at }`, with `opts.facts`), to
|
|
@@ -160,11 +247,13 @@ function takeClaim(path, opts, depth, endedSteps) {
|
|
|
160
247
|
if (own.state !== "alive") throw opts.ownStartUnreadable(own.reason ?? `pid ${process.pid} reads as ${own.state}`, path, endedSteps);
|
|
161
248
|
const me = { ...opts.facts, pid: process.pid, processStart: own.token, nonce: randomBytes(16).toString("hex"), at: new Date().toISOString() };
|
|
162
249
|
const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
|
|
163
|
-
writeFileSync(tmp, JSON.stringify(me) + "\n", { mode: 0o600 });
|
|
164
250
|
try {
|
|
251
|
+
// Inside the block that removes it: a write that fails after the file was created (a full
|
|
252
|
+
// file system does exactly that) leaves nothing behind.
|
|
253
|
+
claimWrite(() => writeFileSync(tmp, JSON.stringify(me) + "\n", { mode: 0o600 }));
|
|
165
254
|
const deadline = Date.now() + waitMs;
|
|
166
255
|
for (let freed = 0; ;) {
|
|
167
|
-
try { linkSync(tmp, path); return me; }
|
|
256
|
+
try { claimWrite(() => linkSync(tmp, path)); return me; }
|
|
168
257
|
catch (e) { if (e?.code !== "EEXIST") throw e; }
|
|
169
258
|
const holder = readClaim(path);
|
|
170
259
|
if (holder?.unreadable) throw opts.unreadableClaim(path, endedSteps);
|
package/lib/config-data.mjs
CHANGED
|
@@ -34,6 +34,9 @@ function boundedYaml(source, limits) {
|
|
|
34
34
|
}
|
|
35
35
|
return result;
|
|
36
36
|
}
|
|
37
|
+
/** The syntax `format: "auto"` reads a document as: one that opens with `{` or `[` is strict JSON, anything
|
|
38
|
+
* else YAML. A writer that rewrites a document keeps it in the syntax this names (lib/local-edit.mjs). */
|
|
39
|
+
export const isJsonSource = (source) => /^[\s]*[\[{]/.test(source);
|
|
37
40
|
export function parseConfigData(input, { format = "auto", origin = null, limits: requested = {} } = {}) {
|
|
38
41
|
const limits = dataLimits({ maxBytes: 1024 * 1024, ...requested });
|
|
39
42
|
const data = typeof input === "string" ? input : byteView(input);
|
|
@@ -42,7 +45,7 @@ export function parseConfigData(input, { format = "auto", origin = null, limits:
|
|
|
42
45
|
const source = decodeUtf8(input);
|
|
43
46
|
canonicalJson(origin, { maxBytes: 64 * 1024, maxDepth: 16, maxEntries: 1024 });
|
|
44
47
|
if (!["auto", "json", "yaml"].includes(format)) throw oatsError("invalid-declaration", "unsupported configuration syntax");
|
|
45
|
-
const json = format === "json" || (format === "auto" &&
|
|
48
|
+
const json = format === "json" || (format === "auto" && isJsonSource(source));
|
|
46
49
|
const origins = Object.create(null);
|
|
47
50
|
let entries = 0;
|
|
48
51
|
const mark = (pointer, depth, node) => {
|