@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.
Files changed (100) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +314 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
  6. package/docs/desktop-cli-api.md +696 -60
  7. package/docs/desktop-instance-start.md +25 -12
  8. package/docs/execution-targets.md +1 -0
  9. package/docs/implementation.md +184 -12
  10. package/docs/integrations.md +6 -3
  11. package/docs/knowledge.md +2 -2
  12. package/docs/macos-test-runs.md +246 -0
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-lane.md +210 -6
  16. package/docs/release-notes/v0.53.0.md +1288 -0
  17. package/docs/release-notes/v0.54.0.md +142 -0
  18. package/docs/schedules.md +7 -1
  19. package/docs/souls-and-instances.md +239 -16
  20. package/docs/tui.md +453 -21
  21. package/docs/upgrading.md +310 -0
  22. package/docs/workspaces.md +123 -3
  23. package/lib/automations.mjs +22 -22
  24. package/lib/claim.mjs +93 -4
  25. package/lib/config-data.mjs +4 -1
  26. package/lib/core.mjs +569 -121
  27. package/lib/instance-events.mjs +19 -1
  28. package/lib/instance-git.mjs +39 -3
  29. package/lib/instance-inspect.mjs +5 -6
  30. package/lib/instance-lifecycle.mjs +145 -18
  31. package/lib/instance-resolution.mjs +59 -6
  32. package/lib/launch-preference.mjs +226 -15
  33. package/lib/local-edit.mjs +118 -0
  34. package/lib/packages.mjs +18 -5
  35. package/lib/pi-bridge.mjs +308 -0
  36. package/lib/refused-text.mjs +11 -0
  37. package/lib/remote.mjs +404 -60
  38. package/lib/resolve.mjs +2 -1
  39. package/lib/retained-after-retire.mjs +2 -2
  40. package/lib/retire-output.mjs +12 -1
  41. package/lib/schedule-host.mjs +6 -35
  42. package/lib/shell-word.mjs +13 -0
  43. package/lib/soul-launch-verbs.mjs +153 -0
  44. package/lib/stable-node.mjs +62 -0
  45. package/lib/teams-verbs.mjs +18 -46
  46. package/lib/workspace.mjs +75 -27
  47. package/package-catalog.json +4 -4
  48. package/package.json +2 -1
  49. package/packages/client/attach-exit.mjs +25 -0
  50. package/packages/client/cli-adapter.mjs +16 -3
  51. package/packages/client/cli-locator.mjs +2 -2
  52. package/packages/client/deployment-contract.mjs +4 -0
  53. package/packages/client/deployment-facts.mjs +71 -10
  54. package/packages/client/deployment-panel.mjs +49 -11
  55. package/packages/client/deployment-read-cli.mjs +7 -3
  56. package/packages/client/display-text.mjs +8 -2
  57. package/packages/client/instance-acts.mjs +46 -10
  58. package/packages/client/instance-events-contract.mjs +4 -2
  59. package/packages/client/instance-presentation.mjs +66 -2
  60. package/packages/client/instance-tree.mjs +23 -14
  61. package/packages/client/kernel-lines.mjs +31 -0
  62. package/packages/client/kernel-made.mjs +23 -0
  63. package/packages/client/launch-prompt-outcome.mjs +51 -16
  64. package/packages/client/lifecycle-contract.mjs +45 -4
  65. package/packages/client/liveness.mjs +14 -1
  66. package/packages/client/own-codes.mjs +31 -0
  67. package/packages/client/panel-views.mjs +18 -11
  68. package/packages/client/readiness-contract.mjs +3 -1
  69. package/packages/client/remote-address.mjs +34 -9
  70. package/packages/client/remote-identity-memory.mjs +94 -0
  71. package/packages/client/remote-roster.mjs +92 -6
  72. package/packages/client/session-attach.mjs +175 -0
  73. package/packages/client/spawn-apply-contract.mjs +16 -4
  74. package/packages/client/spawn-messages.mjs +26 -3
  75. package/packages/client/spawn-preview-cli.mjs +8 -2
  76. package/packages/client/spawn-preview-contract.mjs +5 -1
  77. package/packages/client/terminal-exec.mjs +21 -0
  78. package/packages/client/workspace-choices.mjs +95 -0
  79. package/packages/client/workspace-views.mjs +39 -3
  80. package/packages/record/README.md +21 -0
  81. package/packages/record/bin/setup.mjs +108 -15
  82. package/packages/tui/README.md +30 -12
  83. package/packages/tui/lib/actions.mjs +16 -1
  84. package/packages/tui/lib/client.mjs +32 -1
  85. package/packages/tui/lib/config.mjs +151 -0
  86. package/packages/tui/lib/main.mjs +117 -46
  87. package/packages/tui/lib/model.mjs +392 -0
  88. package/packages/tui/lib/read.mjs +473 -0
  89. package/packages/tui/lib/store.mjs +364 -0
  90. package/packages/tui/lib/term/keys.mjs +44 -0
  91. package/packages/tui/lib/term/screen.mjs +16 -4
  92. package/packages/tui/lib/term/text.mjs +60 -0
  93. package/packages/tui/lib/term/tty.mjs +13 -3
  94. package/packages/tui/lib/views/detail.mjs +46 -0
  95. package/packages/tui/lib/views/frame.mjs +230 -36
  96. package/packages/tui/lib/views/help.mjs +125 -13
  97. package/packages/tui/lib/views/instances.mjs +137 -0
  98. package/packages/tui/lib/views/scroll.mjs +19 -0
  99. package/packages/tui/lib/views/switcher.mjs +97 -0
  100. 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
- return afterEndedSteps(ended, asKernelError(e, "E_LIFECYCLE_FAILED", `the claim ${path} could not be taken (${e?.message ?? e}); ${nothingAfter(ended)}`));
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);
@@ -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" && /^[\s]*[\[{]/.test(source));
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) => {