@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,298 @@
|
|
|
1
|
+
# Upgrading OATS on a host
|
|
2
|
+
|
|
3
|
+
Upgrading OATS means three things, in this order, on each host:
|
|
4
|
+
|
|
5
|
+
1. **The CLI** (`@awebai/oats`, the kernel).
|
|
6
|
+
2. **The pi bridge** (`@awebai/oats-pi`), in every pi folder the host's
|
|
7
|
+
deployments launch pi with: `oats update`, in each deployment.
|
|
8
|
+
3. **A check of each deployment**: `oats doctor`.
|
|
9
|
+
|
|
10
|
+
The kernel and the bridge are published together, from one version tag, and
|
|
11
|
+
must be at the same version: a pi session with an older bridge runs old
|
|
12
|
+
extension code against a new kernel. A host that launches no pi instance has
|
|
13
|
+
no bridge, and step 2 has nothing to move.
|
|
14
|
+
|
|
15
|
+
**A release's own steps are in its notes.** Read the `## Upgrade` section of
|
|
16
|
+
every version between yours and the new one in the
|
|
17
|
+
[release notes](release-notes/) first: it says what to do before the CLI
|
|
18
|
+
changes, and what else must change with it (the Desktop, another tool, a
|
|
19
|
+
package pin). This page is the part that is the same for every release.
|
|
20
|
+
|
|
21
|
+
**Package versions are a different thing.** `oats update` moves the CLI and
|
|
22
|
+
the bridge, never a package. A deployment's capabilities come from the
|
|
23
|
+
packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
|
|
24
|
+
([Packages](packages.md)).
|
|
25
|
+
|
|
26
|
+
## The steps
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
npm install -g @awebai/oats # 1. the CLI
|
|
30
|
+
oats update # 2. in a deployment: the plan, then it asks before it runs
|
|
31
|
+
oats doctor # 3. in the same deployment
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Run steps 2 and 3 in every deployment on the host, or name one from anywhere
|
|
35
|
+
with `oats update --dir <deployment>`. Then restart the pi sessions that were
|
|
36
|
+
running: a session keeps the bridge it loaded when it started.
|
|
37
|
+
|
|
38
|
+
In a terminal, `oats update` shows its plan and asks before it runs anything.
|
|
39
|
+
Without a terminal (a script, an agent's shell) it runs only with `--yes`.
|
|
40
|
+
`oats update --check` shows the plan and runs nothing.
|
|
41
|
+
|
|
42
|
+
`oats update` also does step 1: when npm lists a newer `@awebai/oats`, its
|
|
43
|
+
plan starts with that install, and the bridges move to that same version in
|
|
44
|
+
the same run.
|
|
45
|
+
|
|
46
|
+
**`oats update` only moves forward.** It never installs an older CLI or an
|
|
47
|
+
older bridge than the one in place:
|
|
48
|
+
|
|
49
|
+
- **The CLI** is installed only when the version npm lists is newer than the
|
|
50
|
+
installed one. When the installed CLI is ahead of it (a checkout, a build
|
|
51
|
+
that is not published yet), the plan says so in one line and holds no step
|
|
52
|
+
for the CLI.
|
|
53
|
+
- **The bridges** are brought to the version the CLI has after the run: the
|
|
54
|
+
one npm lists when the CLI moves to it, the installed one otherwise. A
|
|
55
|
+
bridge ahead of that version is left alone.
|
|
56
|
+
|
|
57
|
+
Versions are compared as semver, so a prerelease is below its release:
|
|
58
|
+
`0.53.0-rc.1` is ahead of `0.52.0` and behind `0.53.0`. Build metadata makes
|
|
59
|
+
no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
|
|
60
|
+
installed over it.
|
|
61
|
+
|
|
62
|
+
## Which pi folders
|
|
63
|
+
|
|
64
|
+
pi keeps its packages in one folder: `~/.pi/agent`, or the folder
|
|
65
|
+
`PI_CODING_AGENT_DIR` names. A deployment can launch pi with several folders,
|
|
66
|
+
so `oats update` and `oats doctor` look at each of these:
|
|
67
|
+
|
|
68
|
+
- **the default**, `~/.pi/agent`;
|
|
69
|
+
- **this shell's**, when `PI_CODING_AGENT_DIR` is set where the command runs;
|
|
70
|
+
- **each launch configuration's**: the `PI_CODING_AGENT_DIR` in the `env` of
|
|
71
|
+
every `launch-configs` entry of the deployment's `oats-local.yaml` whose
|
|
72
|
+
harness is `pi` ([Configuration](configuration.md#launch-configurations)).
|
|
73
|
+
The value is a path, or a `{fromEnv: NAME}` reference read from the
|
|
74
|
+
environment the command runs in. A leading `~` is your home.
|
|
75
|
+
|
|
76
|
+
Two names for one folder (two configurations, a configuration that names the
|
|
77
|
+
default, a symbolic link) are one folder, listed once with every reason it is
|
|
78
|
+
looked at.
|
|
79
|
+
|
|
80
|
+
The bridge of a folder is read from
|
|
81
|
+
`<folder>/npm/node_modules/@awebai/oats-pi/package.json`, where pi installs
|
|
82
|
+
it.
|
|
83
|
+
|
|
84
|
+
**The deployment** is the one at or above the directory the command runs in,
|
|
85
|
+
or the one `--dir` names. With no deployment there, `oats update` still moves
|
|
86
|
+
the default folder and this shell's, and says, in the plan and again as its
|
|
87
|
+
last line, that no launch configuration was looked at. It says the same about
|
|
88
|
+
a deployment whose `oats-local.yaml` it cannot load; `oats doctor` reports
|
|
89
|
+
what is wrong with that file. An explicit `--dir` with no deployment at or
|
|
90
|
+
above it is refused.
|
|
91
|
+
|
|
92
|
+
**Folders that are not looked at.** Only the deployment's current
|
|
93
|
+
`launch-configs` are read. An instance home records the launch it was created
|
|
94
|
+
with, and keeps it when the configuration is later changed or removed; a
|
|
95
|
+
folder named only by such a record is not in the list. Move its bridge with
|
|
96
|
+
the command under [By hand](#by-hand).
|
|
97
|
+
|
|
98
|
+
## What `oats update` does in each folder
|
|
99
|
+
|
|
100
|
+
The plan lists every folder with the bridge found in it and one of these:
|
|
101
|
+
|
|
102
|
+
| The plan says | When | What happens |
|
|
103
|
+
|---|---|---|
|
|
104
|
+
| `move to <version>` | the bridge is at an older version | `pi install` runs there |
|
|
105
|
+
| `left alone, already at <version>` | the bridge is at that version | nothing |
|
|
106
|
+
| `left alone, ahead of <version>` | the bridge is at a newer version | nothing: a bridge is never moved back |
|
|
107
|
+
| `no bridge` | the folder does not exist, or holds no bridge | nothing |
|
|
108
|
+
| `not touched`, with a reason | see below | nothing; the plan prints the command to run there |
|
|
109
|
+
|
|
110
|
+
`oats update` moves a bridge. It never creates a folder and never installs a
|
|
111
|
+
first bridge: a spawn's own package check says when a capability needs one
|
|
112
|
+
that is missing.
|
|
113
|
+
|
|
114
|
+
A folder is **not touched** when:
|
|
115
|
+
|
|
116
|
+
- **it does not resolve**: a `{fromEnv: NAME}` whose variable is not set where
|
|
117
|
+
the command runs, or a path that is not absolute. Run `oats update` again
|
|
118
|
+
where the variable is set, or the printed command.
|
|
119
|
+
- **its bridge cannot be read** (a `package.json` that does not parse).
|
|
120
|
+
- **only launch configurations with their own `executable` name it.** A
|
|
121
|
+
wrapper is your program: `oats update` never runs one. The plan prints the
|
|
122
|
+
install command with that executable; when the configurations name several
|
|
123
|
+
executables, one command for each, with the configurations it is for. A
|
|
124
|
+
folder that the default, this shell or a configuration without an
|
|
125
|
+
`executable` also names is moved with the plain `pi`.
|
|
126
|
+
|
|
127
|
+
For a folder it moves, `oats update` runs the `pi` found on `PATH`, with
|
|
128
|
+
`PI_CODING_AGENT_DIR` set to that folder:
|
|
129
|
+
|
|
130
|
+
```sh
|
|
131
|
+
PI_CODING_AGENT_DIR=<folder> npm_config_prefer_online=true pi install npm:@awebai/oats-pi@<version>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
For the default folder the variable is left out, unless this shell sets one.
|
|
135
|
+
|
|
136
|
+
## Nothing is removed before its replacement is known to install
|
|
137
|
+
|
|
138
|
+
The move is one `pi install` over the installed bridge. pi replaces the
|
|
139
|
+
settings entry and the files of a package it already holds, and an install
|
|
140
|
+
that fails leaves the old ones in place. There is no `pi uninstall`.
|
|
141
|
+
|
|
142
|
+
Before any step runs, the CLI's own install included, `oats update` asks the
|
|
143
|
+
registry for the bridge's exact version, with npm told to revalidate its
|
|
144
|
+
cache (`npm view @awebai/oats-pi@<version> version --prefer-online`). A new
|
|
145
|
+
version is listed a few minutes after it is published, and the kernel's
|
|
146
|
+
listing says nothing about the bridge's. If the version does not resolve,
|
|
147
|
+
the update stops with nothing changed and every bridge in place: run it again
|
|
148
|
+
in a few minutes. The same setting goes to pi's own npm for the install
|
|
149
|
+
(`npm_config_prefer_online=true`). `--check` does not make this lookup: it
|
|
150
|
+
shows what would run, and the run looks again.
|
|
151
|
+
|
|
152
|
+
When the installed CLI is ahead of the registry, the version asked for is
|
|
153
|
+
the installed one, and it may not be published at all. The plan does not
|
|
154
|
+
know: it makes no lookup. So when it lists a move to that version, it says
|
|
155
|
+
under the folders what the move depends on:
|
|
156
|
+
|
|
157
|
+
```text
|
|
158
|
+
A bridge moves to 0.53.0 only if @awebai/oats-pi@0.53.0 is published: the installed kernel is ahead of the registry's 0.52.0, and a run checks that before any step.
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
When the run's lookup then does not find the version, the message says that
|
|
162
|
+
the installed kernel is ahead of the registry, instead of telling you to wait
|
|
163
|
+
a few minutes.
|
|
164
|
+
|
|
165
|
+
**What npm answers is checked before it is used.** Both lookups must answer
|
|
166
|
+
one version and nothing else: three numbers and an optional prerelease, on
|
|
167
|
+
one line. Any other answer (nothing, several lines, a list, text around the
|
|
168
|
+
version) stops the update before any step, with nothing changed. The message
|
|
169
|
+
names the lookup and shows the answer cut to 80 characters, with its control
|
|
170
|
+
characters shown as escapes or replaced. Run `oats update` again.
|
|
171
|
+
|
|
172
|
+
npm's own error output of a lookup is not passed to your terminal either.
|
|
173
|
+
When the first lookup fails, the message says how it ended (`exit 1`) and
|
|
174
|
+
then what npm said, cut to 300 characters and made safe the same way.
|
|
175
|
+
|
|
176
|
+
The update stops at the first step that fails. Its message names the folder
|
|
177
|
+
and the exact step to run again, says what that folder holds now (the old
|
|
178
|
+
bridge still, or no bridge), and lists the folders it did not reach. A step
|
|
179
|
+
that ends without an error but leaves another version in the folder is a
|
|
180
|
+
failure too. Run the printed step, then `oats update` again: folders already
|
|
181
|
+
at the version are left alone.
|
|
182
|
+
|
|
183
|
+
## What `oats doctor` reports
|
|
184
|
+
|
|
185
|
+
`oats doctor` prints one warning per folder whose bridge is not the kernel's
|
|
186
|
+
version, naming the folder and why it is looked at:
|
|
187
|
+
|
|
188
|
+
```text
|
|
189
|
+
WARNING: version skew — kernel 0.53.0, pi bridge 0.52.0 in /srv/pi-work (launch configuration work); run `oats update` (they publish in lockstep)
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
A bridge ahead of the kernel is a skew too. `oats update` moves no bridge
|
|
193
|
+
back, and `oats doctor` does not ask the registry, so the warning says what
|
|
194
|
+
ends the skew:
|
|
195
|
+
|
|
196
|
+
```text
|
|
197
|
+
WARNING: version skew — kernel 0.52.0, pi bridge 0.53.0 in /srv/pi-work (launch configuration work); the bridge is ahead of the kernel, and `oats update` never moves a bridge back. The skew ends when the kernel is at 0.53.0 (`oats update` moves it once npm lists that version), or when the kernel's bridge is installed there by hand (docs/upgrading.md, "By hand")
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
It also warns about a folder it could not look at (one that does not
|
|
201
|
+
resolve, or a bridge that cannot be read). A folder that does not exist or
|
|
202
|
+
holds no bridge is not a skew, and it says nothing about it. The warnings are
|
|
203
|
+
in the text output only; `oats doctor --json` does not carry them.
|
|
204
|
+
|
|
205
|
+
## After a change of Node version
|
|
206
|
+
|
|
207
|
+
Two paths are written into things that outlive a command: the kernel's, and
|
|
208
|
+
the `node` that runs it. A new Node version can leave either behind.
|
|
209
|
+
|
|
210
|
+
**The kernel's path.** The CLI is an npm global package: it is installed
|
|
211
|
+
under npm's global prefix (`npm prefix -g`).
|
|
212
|
+
|
|
213
|
+
- **The prefix is outside the Node install.** The kernel's path does not
|
|
214
|
+
change with the Node version: the CLI needs no reinstall.
|
|
215
|
+
- **The prefix is the Node version's own directory**, the usual layout of a
|
|
216
|
+
version manager (mise, nvm, asdf, fnm). Every Node version then has its own
|
|
217
|
+
global packages: a new version has no `oats`, and removing the old version
|
|
218
|
+
removes the kernel with it. Four things name that kernel by its path: each
|
|
219
|
+
instance home's own `oats` (`<home>/.oats/bin/oats`), the Claude Code hooks
|
|
220
|
+
of a Claude instance, the host timer's unit, and what `oats setup` installs
|
|
221
|
+
(the turn record's capture hooks and its watcher, which name the capture
|
|
222
|
+
script inside the kernel). OATS cannot make a path inside a Node version
|
|
223
|
+
outlast that version.
|
|
224
|
+
|
|
225
|
+
Both layouts can exist on one host: check the prefix in the shell that
|
|
226
|
+
installs the CLI.
|
|
227
|
+
|
|
228
|
+
**The `node`'s path**, whatever the prefix. The Claude Code hooks of a
|
|
229
|
+
Claude instance, the host timer's unit and what `oats setup` installs also
|
|
230
|
+
record the `node` that runs them, by one rule
|
|
231
|
+
([the node a hook writes down](capabilities.md#the-node-a-hook-writes-down)):
|
|
232
|
+
|
|
233
|
+
- **On Homebrew**, the `opt` link (`<prefix>/opt/node/bin/node`) when it is
|
|
234
|
+
the `node` running the kernel. `brew upgrade node` repoints it, so the
|
|
235
|
+
recorded path outlasts the upgrade: the hooks, the timer and the capture
|
|
236
|
+
watcher need nothing done.
|
|
237
|
+
- **Otherwise**, a `node` on `PATH` that is the same file as the one running
|
|
238
|
+
the kernel. With mise that is the version's own install, which does not
|
|
239
|
+
outlast the version (other version managers were not measured).
|
|
240
|
+
- **When there is neither**, the path of the `node` as it is. A spawn, a
|
|
241
|
+
start, `oats schedule host install` and `oats setup` then warn that it is
|
|
242
|
+
not stable.
|
|
243
|
+
|
|
244
|
+
**What `oats setup` records is in your own files, not in an instance home:**
|
|
245
|
+
the capture hooks (`Stop` and `SessionEnd`) in every `~/.claude*/settings.json`
|
|
246
|
+
of the user who ran it, and the capture watcher's unit
|
|
247
|
+
(`~/Library/LaunchAgents/ai.aweb.turn-record-capture.plist` on macOS,
|
|
248
|
+
`~/.config/systemd/user/turn-record-capture.service` on Linux). No spawn,
|
|
249
|
+
start or restart writes them: only `oats setup` run again does, and it
|
|
250
|
+
replaces its own hooks and unit, it does not add a second one.
|
|
251
|
+
|
|
252
|
+
Once the recorded `node` no longer exists (an old version removed under a
|
|
253
|
+
version manager, for example), the hooks fail without a message, so the
|
|
254
|
+
instance stops reporting that it waits on you, and
|
|
255
|
+
`oats schedule host status` reports `node-missing`. The capture hooks then
|
|
256
|
+
fail at every stop of every Claude Code session of that user, and launchd or
|
|
257
|
+
systemd keeps restarting a watcher that cannot start.
|
|
258
|
+
|
|
259
|
+
**A home spawned with an oats.core that does not read `OATS_NODE_BIN`** does
|
|
260
|
+
not follow the rule. Its hooks record the path of the `node` its hook ran
|
|
261
|
+
under, which on Homebrew is the versioned keg
|
|
262
|
+
(`…/Cellar/node/<version>/bin/node`), and a start writes that again, because
|
|
263
|
+
a start runs the copy of oats.core in the home. `brew upgrade node` removes
|
|
264
|
+
the keg at once, so such a home needs the restart of step 2 after every Node
|
|
265
|
+
upgrade, until it is respawned.
|
|
266
|
+
|
|
267
|
+
So after moving to another Node version, and before removing the old one,
|
|
268
|
+
wherever a recorded path does not outlast it:
|
|
269
|
+
|
|
270
|
+
1. Where the prefix is the version's own directory, install the CLI in the
|
|
271
|
+
new version: `npm install -g @awebai/oats`.
|
|
272
|
+
2. Restart the instances, from a shell on the new version
|
|
273
|
+
(`oats session restart --home <home>`). A start writes the home's `oats`
|
|
274
|
+
and its Claude Code hooks again
|
|
275
|
+
([Configuration](configuration.md#launch-configurations)).
|
|
276
|
+
3. On a host that runs schedules, run `oats schedule host install` again,
|
|
277
|
+
from your own shell, not from an instance home. Without it,
|
|
278
|
+
`oats schedule host status` reports `oats-bin-missing` or `node-missing`
|
|
279
|
+
once the old version is removed
|
|
280
|
+
([Schedules](schedules.md#the-host-timers-unit)).
|
|
281
|
+
4. On a host where `oats setup` was run, run `oats setup` again, as the same
|
|
282
|
+
user and from your own shell. `oats setup --dry-run` prints the `node` it
|
|
283
|
+
would record and changes nothing.
|
|
284
|
+
|
|
285
|
+
Until the old version is removed, the instances and the timer keep running
|
|
286
|
+
what it holds.
|
|
287
|
+
|
|
288
|
+
## By hand
|
|
289
|
+
|
|
290
|
+
In any pi folder, with the `pi` that is launched with it:
|
|
291
|
+
|
|
292
|
+
```sh
|
|
293
|
+
PI_CODING_AGENT_DIR=<folder> pi install npm:@awebai/oats-pi@<the CLI's version>
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
`oats version` prints the CLI's version. For the default folder, leave the
|
|
297
|
+
assignment out only when your shell does not set `PI_CODING_AGENT_DIR`;
|
|
298
|
+
when it does, name the folder: `PI_CODING_AGENT_DIR="$HOME/.pi/agent"`.
|
package/docs/workspaces.md
CHANGED
|
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.9.
|
|
58
|
-
oats.okf: v5.0.
|
|
57
|
+
oats.framework: v1.9.4 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.0.3
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
61
61
|
teams: # SHARED teams: the same provider team for everyone
|
|
@@ -198,7 +198,7 @@ as `confirmed` or the reason it is not:
|
|
|
198
198
|
| `not-listed` | the workspace does not list the repo |
|
|
199
199
|
| `no-backlink` | no (or invalid) `oats-membership.yaml` at the member's default branch |
|
|
200
200
|
| `backlink-elsewhere` | the member names a different workspace (a case-only difference is flagged: repo paths are case-sensitive identities) |
|
|
201
|
-
| `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout / killed: the system killed git, e.g. out of memory), or this machine's remote cache could not be written (cache) |
|
|
201
|
+
| `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout / killed: the system killed git, e.g. out of memory / unknown: git failed for a reason the kernel cannot name), or this machine's remote cache could not be written (cache) |
|
|
202
202
|
|
|
203
203
|
An unconfirmed member contributes nothing but its row: its souls are invisible,
|
|
204
204
|
its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).
|
package/lib/automations.mjs
CHANGED
|
@@ -38,6 +38,7 @@ import { dirname, join } from "node:path";
|
|
|
38
38
|
import { recordLocalInput } from "./local-inputs.mjs";
|
|
39
39
|
import YAML from "yaml";
|
|
40
40
|
import { parseConfigData } from "./config-data.mjs";
|
|
41
|
+
import { editLocal } from "./local-edit.mjs";
|
|
41
42
|
|
|
42
43
|
export const AUTOMATIONS_API = 1;
|
|
43
44
|
export const SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
|
|
@@ -361,29 +362,28 @@ function refreshViaCli(dep, io) {
|
|
|
361
362
|
// ------------------------------------------------------------ opting out here
|
|
362
363
|
|
|
363
364
|
/** Add or remove `<member>/<id>` in oats-local.yaml `<kind>s.disabled` (`triggers.disabled` or
|
|
364
|
-
* `schedules.disabled`),
|
|
365
|
-
*
|
|
366
|
-
|
|
365
|
+
* `schedules.disabled`), through the one path that rewrites that file (lib/local-edit.mjs editLocal:
|
|
366
|
+
* the deployment's local lock, the file as it is under it, the local schema, a rename): the rest of the
|
|
367
|
+
* file stays as written, comments included, and no other writer's change is dropped.
|
|
368
|
+
* `ctx`: { deployment, localPath }. → { changed, disabled } (the list now). */
|
|
369
|
+
export function setDisabledHere(ctx, kind, qid, disabled) {
|
|
367
370
|
const section = `${kind}s`;
|
|
368
|
-
|
|
369
|
-
const
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
if (problems.length) throw automationError("E_WORKSPACE_SCHEMA", `the rewritten ${localPath} would be invalid (${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}); nothing was written`);
|
|
385
|
-
writeFileSync(localPath, out);
|
|
386
|
-
return { changed: true, disabled: next };
|
|
371
|
+
let list = [];
|
|
372
|
+
const { changed } = editLocal(ctx, { verb: `oats ${kind} ${disabled ? "disable" : "enable"}` }, ({ doc }) => {
|
|
373
|
+
const current = doc.getIn([section, "disabled"]);
|
|
374
|
+
list = current && typeof current.toJSON === "function" ? current.toJSON() : Array.isArray(current) ? current : [];
|
|
375
|
+
const next = disabled ? [...new Set([...list, qid])].sort() : list.filter((x) => x !== qid);
|
|
376
|
+
if (JSON.stringify(next) === JSON.stringify(list)) return null;
|
|
377
|
+
if (next.length) doc.setIn([section, "disabled"], next);
|
|
378
|
+
else if (doc.hasIn([section, "disabled"])) {
|
|
379
|
+
doc.deleteIn([section, "disabled"]);
|
|
380
|
+
const rest = doc.get(section);
|
|
381
|
+
if (rest && typeof rest.toJSON === "function" && !Object.keys(rest.toJSON() || {}).length) doc.delete(section);
|
|
382
|
+
}
|
|
383
|
+
list = next;
|
|
384
|
+
return {};
|
|
385
|
+
});
|
|
386
|
+
return { changed, disabled: list };
|
|
387
387
|
}
|
|
388
388
|
|
|
389
389
|
// ------------------------------------------------------------ writing a workspace file
|
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) => {
|