@awebai/oats 0.48.0 → 0.50.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/bin/oats.mjs +326 -28
- package/docs/capabilities.md +425 -8
- package/docs/capability-manifest.schema.json +60 -5
- package/docs/configuration.md +103 -0
- package/docs/desktop-cli-api.md +542 -47
- package/docs/desktop.md +85 -5
- package/docs/execution-targets.md +50 -9
- package/docs/implementation.md +74 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +289 -53
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +450 -60
- package/docs/workspaces.md +3 -3
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +18 -2
- package/lib/core.mjs +1374 -394
- package/lib/instance-events.mjs +9 -10
- package/lib/instance-git.mjs +19 -10
- package/lib/instance-inspect.mjs +58 -18
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/refused-text.mjs +17 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +9 -2
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +705 -108
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
package/docs/capabilities.md
CHANGED
|
@@ -94,15 +94,49 @@ A self-contained package has an `oats.json`:
|
|
|
94
94
|
slot.
|
|
95
95
|
- `skills` entries can be skill directories or roots containing skills.
|
|
96
96
|
- `inject` is optional instance instruction Markdown.
|
|
97
|
-
- The hooks are `spawn`, `launch` and `
|
|
97
|
+
- The hooks are `spawn`, `launch`, `retire` and `worktree`
|
|
98
|
+
([The worktree event](#the-worktree-event)). A hook is a
|
|
98
99
|
command string, or `{ command, required }`. `required: true` is valid **only
|
|
99
|
-
on `spawn`**:
|
|
100
|
+
on `spawn` and `worktree`**: a required spawn hook's failure fails the spawn
|
|
101
|
+
and rolls it back,
|
|
100
102
|
instead of producing an instance whose capability never configured itself —
|
|
101
103
|
an aweb identity that could not be minted leaves an agent believing it can be
|
|
102
|
-
woken by mail.
|
|
104
|
+
woken by mail. A required `worktree` hook's failure fails the spawn the same
|
|
105
|
+
way, or removes the tree `oats worktree add` made. Every other hook stays
|
|
106
|
+
best-effort and only warns, so advisory
|
|
103
107
|
work never becomes a spawn blocker. `launch` and `retire` cannot be
|
|
104
108
|
required: they run outside a spawn transaction, so there is no moment to
|
|
105
109
|
enforce them. A `soul-scaffold` hook is tolerated and ignored.
|
|
110
|
+
- An **event this kernel does not run** (a newer kernel's) is accepted from
|
|
111
|
+
0.49.0 on, so a capability that adopts a new event keeps composing on an
|
|
112
|
+
older host. Declared as a command string, `{ command }` or
|
|
113
|
+
`{ command, required: false }`, it is ignored and never runs, and the
|
|
114
|
+
capability carries the warning `hook-event-unsupported`: `capability <id>
|
|
115
|
+
declares hook "<event>", which this kernel does not run`. Declared
|
|
116
|
+
`required: true`, it is refused (`declares unsupported hook`), because
|
|
117
|
+
skipping a hook its author declared essential would fail open. The
|
|
118
|
+
tolerance covers the event's name only: its declaration is checked as for a
|
|
119
|
+
known event (a non-empty command, no unknown keys, a boolean `required`, a
|
|
120
|
+
script inside the capability), and a malformed one is refused. It helps
|
|
121
|
+
from 0.49.0 on only: a kernel before 0.49.0 refuses every unknown event, so
|
|
122
|
+
a capability that must load there declares only the events it runs.
|
|
123
|
+
- The warning is `{code: "hook-event-unsupported", capability, path,
|
|
124
|
+
message}`. It appears in `oats sync` and `oats workspace status`, `oats
|
|
125
|
+
capabilities show`, `oats inspect`, `oats readiness` and `oats doctor` (in
|
|
126
|
+
their `warnings`), and as its message in the `warnings` strings of `oats
|
|
127
|
+
spawn --preview` and `oats spawn` (clipped to fit their receipt), in JSON and in text
|
|
128
|
+
([desktop-cli-api.md](desktop-cli-api.md#capability-warnings-hook-event-unsupported-oats-0490)).
|
|
129
|
+
`path` names the manifest that was read, in one of two forms, never an
|
|
130
|
+
absolute host path:
|
|
131
|
+
|
|
132
|
+
| Read from | `path` | Commands |
|
|
133
|
+
|---|---|---|
|
|
134
|
+
| the workspace (a member's or a package's manifest) | `<repoKey>:<dir>/oats.json#/hooks/<event>`, or `package:<id>:<dir>/oats.json#/hooks/<event>`; `<dir>` relative to the repository | sync, workspace status, capabilities show, inspect and readiness `--soul`, doctor, spawn |
|
|
135
|
+
| an instance home's module copy | `.oats/modules/<name>/oats.json#/hooks/<event>`, relative to the home | inspect and readiness `--home` |
|
|
136
|
+
|
|
137
|
+
Doctor without `--soul` reads every member and locked package capability
|
|
138
|
+
from this machine's cache only. What the cache cannot answer is reported as
|
|
139
|
+
unchecked (`hook-events-unchecked` in its information), never as no warning.
|
|
106
140
|
- A capability declaring a **required** spawn hook should declare a `retire` hook
|
|
107
141
|
too. Without one, OATS has no way to undo what the spawn hook did and no way to
|
|
108
142
|
know whether it did anything, so a failure quarantines the home rather than
|
|
@@ -118,7 +152,8 @@ A self-contained package has an `oats.json`:
|
|
|
118
152
|
`oats status` reports it as retained state rather than a live instance, and
|
|
119
153
|
`oats retire <instance>` retries the cleanup — re-running the retire hooks and
|
|
120
154
|
the worktree removal, verifying both, and verifying (never deleting) the
|
|
121
|
-
branch: no retire deletes a branch
|
|
155
|
+
branch: no retire deletes a branch, with one exception, a spawn killed while
|
|
156
|
+
its `worktree` hooks ran (below). While the branch the failed spawn created
|
|
122
157
|
is still there, the retry stays incomplete with the item `the branch the
|
|
123
158
|
failed spawn created is left: OATS does not delete it. Inspect it and delete
|
|
124
159
|
it with Git if it is not wanted, then retry`. The item names no branch: the
|
|
@@ -147,6 +182,60 @@ A self-contained package has an `oats.json`:
|
|
|
147
182
|
success, and every Git step it records must be re-run and verified. A retry that resolves no
|
|
148
183
|
capabilities — a hand-edited descriptor, or config drift since the spawn — is an
|
|
149
184
|
incomplete cleanup, not a clean one, and the home stays.
|
|
185
|
+
- **A spawn in progress** (0.49.0). A `work: worktree` spawn that fires
|
|
186
|
+
[`worktree` hooks](#the-worktree-event) writes the same marker just before
|
|
187
|
+
the first of them, so a parent killed while they run (SIGKILL included)
|
|
188
|
+
leaves a home `oats retire` can clean up. Its `outstanding` holds the retire
|
|
189
|
+
hooks of the capabilities whose spawn hooks ran, plus the Git steps
|
|
190
|
+
`worktree` and `branch`. It adds an optional top-level `inProgress: { pid,
|
|
191
|
+
processStart, startedAt, branch, baseOid, hookPgid?, hookStart? }`: the
|
|
192
|
+
spawning process, identified by its pid and start time, the branch the spawn
|
|
193
|
+
created and the commit it created it at, and the process group of the hook
|
|
194
|
+
running. The spawn removes the marker once its final `instance.json` and
|
|
195
|
+
baseline are written; a failure's compensation replaces it in one rename.
|
|
196
|
+
Such a marker satisfies every rule above, so a reader that does not know
|
|
197
|
+
`inProgress` reads it as a quarantine. While the spawning process is
|
|
198
|
+
verifiably alive (its pid runs with the recorded start time):
|
|
199
|
+
- `oats status` gives the home's row `spawnInProgress: true` and no
|
|
200
|
+
`rollbackIncomplete`;
|
|
201
|
+
- `oats retire` refuses with `E_LIFECYCLE_BUSY`, `--force` included;
|
|
202
|
+
- `oats session start` refuses it as any quarantined home
|
|
203
|
+
(`E_INSTANCE_RETIRING`).
|
|
204
|
+
|
|
205
|
+
Whether the process exists is the operating system's answer (`kill -0`:
|
|
206
|
+
"no such process" is gone, another user's process exists), the same on
|
|
207
|
+
every host. Only then is its start time read: from `/proc`, or with `ps`
|
|
208
|
+
(in a fixed `LC_ALL=C`, `TZ=UTC` environment) where there is no `/proc`,
|
|
209
|
+
as on macOS. A start that cannot be read is never taken to mean the process is
|
|
210
|
+
gone, nor shown as alive: `oats status` shows the quarantine
|
|
211
|
+
(`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
|
|
212
|
+
refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
|
|
213
|
+
check by hand. Once that check shows the spawn is gone, `oats retire
|
|
214
|
+
<instance> --force` retires the home and keeps the branch
|
|
215
|
+
(`spawnCompensation.reason`, `forcedIncomplete`).
|
|
216
|
+
|
|
217
|
+
Once that process is gone (killed with SIGKILL, or its rollback cut
|
|
218
|
+
short), `oats retire` finishes the spawn's own compensation, in order:
|
|
219
|
+
1. it ends the hook process group the spawn left, only when the group's
|
|
220
|
+
leader runs with its recorded start time. A group whose leader has
|
|
221
|
+
exited is not signalled, and a warning names it;
|
|
222
|
+
2. it runs the owed retire hooks;
|
|
223
|
+
3. it removes the worktree and verifies the removal;
|
|
224
|
+
4. only then, it deletes `inProgress.branch` with an atomic
|
|
225
|
+
compare-and-delete at `inProgress.baseOid` (`git update-ref -d
|
|
226
|
+
refs/heads/<b> <baseOid>`).
|
|
227
|
+
|
|
228
|
+
This is the one exception to "no retire deletes a branch": a branch still
|
|
229
|
+
at the commit it was created at holds no work. Retire does not delete it,
|
|
230
|
+
and falls back to the "branch left" item above naming the branch (the home
|
|
231
|
+
is retained), when its tip moved, when it is checked out in any worktree,
|
|
232
|
+
or when its ref cannot be read. Every other quarantine keeps its branch.
|
|
233
|
+
The retire result's `branchDeleted` means exactly "retire's own
|
|
234
|
+
`--delete-branch`" (refused, so always `false`), not whether a branch was
|
|
235
|
+
deleted. This step is reported in the additive `spawnCompensation`, the one
|
|
236
|
+
place a retire's branch deletion is reported: `{ branch, branchDeleted:
|
|
237
|
+
true }`, or `{ branch, branchDeleted: false, reason }`, present only when
|
|
238
|
+
the step was reached.
|
|
150
239
|
- Because some cleanups can never succeed (a capability offering no way to undo its
|
|
151
240
|
own setup, a permanently unreachable remote), **`--force` also overrides
|
|
152
241
|
retention**: the home is removed, and everything still outstanding is printed as
|
|
@@ -210,17 +299,35 @@ A self-contained package has an `oats.json`:
|
|
|
210
299
|
`home`, the roots are recorded at spawn. The other work modes do not use
|
|
211
300
|
them.
|
|
212
301
|
|
|
302
|
+
A root is read the way spawn records it: a backslash reads as `/`, one
|
|
303
|
+
leading `./` and one trailing `/` are dropped (`./build/` is `build`).
|
|
304
|
+
What is left must be a relative path with no empty, `.` or `..` segment
|
|
305
|
+
(`build`, `node_modules/.cache`). Refused: an empty string, an absolute
|
|
306
|
+
path (`/x`, `\x`, or a Windows one such as `C:/x`, on every host),
|
|
307
|
+
`../x`, `a/../b`, `a//b`, `a/./b`, `.`. Two entries of one manifest that
|
|
308
|
+
overlap, the same root or one inside the other (`build` and `./build/`,
|
|
309
|
+
`a` and `a/b`), are refused too.
|
|
310
|
+
|
|
311
|
+
Spawn alone can see two more cases, and refuses the spawn with
|
|
312
|
+
`E_CAPABILITY_BROKEN` and rolls it back: a declared root that is a
|
|
313
|
+
symlink in the work (also one whose target is missing), and roots of
|
|
314
|
+
different capabilities that overlap. `oats spawn --json` reports these,
|
|
315
|
+
as other spawn failures, as `E_SPAWN_FAILED` with the same message.
|
|
316
|
+
|
|
213
317
|
A malformed `retirement` is refused wherever the manifest is read: member
|
|
214
318
|
discovery (`E_WORKSPACE_SCHEMA`), package manifests (`E_PACKAGE_MANIFEST`)
|
|
215
319
|
and the kernel loader refuse the same manifest, with a JSON pointer:
|
|
216
320
|
`/retirement` (no `disposable` map, or a key other than `disposable`,
|
|
217
321
|
`home` and `work`), `/retirement/disposable/<scope>` (not an array of
|
|
218
|
-
strings)
|
|
219
|
-
grammar)
|
|
322
|
+
strings), `/retirement/disposable/home/<i>` (an entry outside the
|
|
323
|
+
grammar) or `/retirement/disposable/work/<i>` (a root outside the grammar,
|
|
324
|
+
or one that overlaps an earlier entry):
|
|
220
325
|
|
|
221
326
|
```text
|
|
222
327
|
capability <id> manifest retirement.disposable.home entry "<value>" must name one hidden top-level home entry (".name", or ".prefix-*")
|
|
223
328
|
capability <id> manifest retirement.disposable.home entry "<value>" covers a kernel-owned home entry
|
|
329
|
+
capability <id> manifest retirement.disposable.work entry "<value>" must be a relative path under work/ with no empty, "." or ".." segment
|
|
330
|
+
capability <id> manifest retirement.disposable.work entry "<value>" overlaps entry "<earlier>": the same root, or one inside the other
|
|
224
331
|
```
|
|
225
332
|
|
|
226
333
|
This kernel reads the field. What retire does with the entries is in
|
|
@@ -246,6 +353,9 @@ A self-contained package has an `oats.json`:
|
|
|
246
353
|
separate from declaring the package.
|
|
247
354
|
- `environment` lists the exact launch variables the capability may set;
|
|
248
355
|
spawn hook output must be a subset and use the capability vendor prefix.
|
|
356
|
+
- `triggerSources` (optional) declares the capability's
|
|
357
|
+
[trigger sources](#trigger-sources-triggersources). It is checked only
|
|
358
|
+
where a source is used, never when the capability loads.
|
|
249
359
|
- Target names never appear in a package manifest.
|
|
250
360
|
|
|
251
361
|
`capability` is the only manifest identity field; it may also carry
|
|
@@ -441,7 +551,8 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
|
|
|
441
551
|
`OATS_TRIGGER_EVENT_FILE`. A launch hook also gets `OATS_HARNESS` and
|
|
442
552
|
`OATS_PREVIOUS_HARNESS`, and `OATS_LAUNCH_PREVIEW=1` when it runs for a
|
|
443
553
|
preview (only a preview-aware hook does, below); on a real run
|
|
444
|
-
`OATS_LAUNCH_PREVIEW` is not set.
|
|
554
|
+
`OATS_LAUNCH_PREVIEW` is not set. A worktree hook also gets the tree
|
|
555
|
+
variables of [The worktree event](#the-worktree-event).
|
|
445
556
|
|
|
446
557
|
A dispatched command (`oats <namespace> <command>`, from an instance home or
|
|
447
558
|
from the deployment directory) receives:
|
|
@@ -483,7 +594,8 @@ a home with none recorded gives `{}`. A final JSON line may return `meta`,
|
|
|
483
594
|
`brief`, `warning`, or harness-specific `launch` arguments; a preview-aware
|
|
484
595
|
launch hook's preview answer may add `volatileEnv` (below). A **spawn or
|
|
485
596
|
launch hook** may also return an `env` object for the launched process;
|
|
486
|
-
returning `env` from a retire hook is an
|
|
597
|
+
returning `env` from a retire or [worktree](#the-worktree-event) hook is an
|
|
598
|
+
explicit contract error.
|
|
487
599
|
|
|
488
600
|
A **launch hook** runs at every start and restart of a home for each provider
|
|
489
601
|
recorded at spawn (under its recorded settings). Its `launch` arguments and
|
|
@@ -615,6 +727,145 @@ Spawn order is by capability name; retirement reverses successful
|
|
|
615
727
|
spawn order. Hooks run from the instance's own copy
|
|
616
728
|
(`<home>/.oats/modules/<cap>/`).
|
|
617
729
|
|
|
730
|
+
### The worktree event
|
|
731
|
+
|
|
732
|
+
`OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
|
|
733
|
+
kernel has just created: install dependencies, link environment files, pin
|
|
734
|
+
a toolchain. The kernel runs only the hooks of the instance's own
|
|
735
|
+
capabilities; it runs no code from the repository.
|
|
736
|
+
|
|
737
|
+
**When it fires.** Once for each tree the kernel creates:
|
|
738
|
+
|
|
739
|
+
- `./work` of a `work: worktree` spawn, after the spawn hooks succeed and
|
|
740
|
+
inside the spawn's transaction;
|
|
741
|
+
- each extra tree `oats worktree add` makes
|
|
742
|
+
([extra trees](souls-and-instances.md#extra-trees)).
|
|
743
|
+
|
|
744
|
+
It never fires for a `checkout`, `attached`, `workspace` or `directory`
|
|
745
|
+
`./work`, for a tree made with raw Git, or at start, restart, resume or
|
|
746
|
+
retire. `oats worktree remove` fires no hook. An `add` that finds its tree
|
|
747
|
+
already made (same clone, branch and base) runs no hook again.
|
|
748
|
+
|
|
749
|
+
**How it runs.** Hooks run in capability-name order, from the module copy,
|
|
750
|
+
like every hook. Other events keep their own behaviour (120 s, buffered,
|
|
751
|
+
cwd the home); this one differs:
|
|
752
|
+
|
|
753
|
+
- **cwd is the new tree.** `OATS_TREE` names it too.
|
|
754
|
+
- stdin is `/dev/null`, with no terminal.
|
|
755
|
+
- The hook is started detached, in its own process group, so a timeout or an
|
|
756
|
+
interrupt ends the whole group.
|
|
757
|
+
- stdout and stderr go to `<home>/.oats/logs/worktree-<purpose>-<cap>.log`
|
|
758
|
+
(`worktree-work-<cap>.log` for `./work`), created 0600 and truncated on each
|
|
759
|
+
run. On `oats worktree add` they are also copied to the kernel's stderr,
|
|
760
|
+
never its stdout: `--json` prints only the envelope. A caller that closes
|
|
761
|
+
its end of stderr or stdout (a tool shell killed, Desktop gone) only stops
|
|
762
|
+
the copy: the hooks and the add run to their end, and the log is whole. The log holds whatever
|
|
763
|
+
the hook printed, so its content never enters any JSON answer, receipt,
|
|
764
|
+
record, marker or instance event: they carry the log's path only. The
|
|
765
|
+
`warning` of the hook's last JSON line is the one piece of its output that
|
|
766
|
+
may surface.
|
|
767
|
+
- The timeout is 30 minutes, fixed. At the timeout the kernel sends the group
|
|
768
|
+
SIGTERM, then SIGKILL after a short grace.
|
|
769
|
+
- The result is the exit status. Of the last stdout line's JSON only
|
|
770
|
+
`warning` is read. Returning `env` is a contract error
|
|
771
|
+
(`E_HOOK_ENVIRONMENT_CONTRACT`), as at retire; `meta`, `brief` and `launch`
|
|
772
|
+
are ignored.
|
|
773
|
+
- A non-required hook that fails or times out is a warning; the tree is kept.
|
|
774
|
+
A required one (`{ command, required: true }`) fails closed:
|
|
775
|
+
- at spawn, it fails the spawn through the required-hook rollback above
|
|
776
|
+
(retire hooks compensate in reverse, the worktree-mode Git state is
|
|
777
|
+
removed and verified, and the home is deleted, or kept as a quarantine).
|
|
778
|
+
The hook's log was in that home: once it is deleted, the answer names
|
|
779
|
+
no log path (each `details.hooks` entry's `log` is `null`) and says to run
|
|
780
|
+
the setup with `oats worktree add` in an existing instance to see its
|
|
781
|
+
output; a quarantined home keeps its logs, and the answer names them;
|
|
782
|
+
- at `oats worktree add`, the tree is removed. The branch is deleted only
|
|
783
|
+
when that `add` created it, no worktree has it checked out, and it is
|
|
784
|
+
still where `add` created it.
|
|
785
|
+
|
|
786
|
+
Both exit nonzero, naming the capability and its log. `oats worktree add`
|
|
787
|
+
refuses with `E_REQUIRED_HOOK_FAILED` (`E_HOOK_ENVIRONMENT_CONTRACT` for an
|
|
788
|
+
`env` answer); `oats spawn` fails as for a required spawn hook.
|
|
789
|
+
- A hook that removes or moves the tree fails the check that follows the
|
|
790
|
+
hooks: a failure when any hook is required, else a warning.
|
|
791
|
+
- SIGINT, SIGTERM or SIGHUP to the kernel while the hooks run ends the running
|
|
792
|
+
hook's group, rolls back as for a required failure, and exits 128 + the
|
|
793
|
+
signal number with `E_INTERRUPTED`. A parent killed with SIGKILL leaves a
|
|
794
|
+
record the next command completes: the `creating` tree record for `add`
|
|
795
|
+
(the next `oats worktree add` or `remove` of that purpose rolls it back), or
|
|
796
|
+
the spawn's [in-progress marker](#manifest) for a spawn (`oats retire`).
|
|
797
|
+
That recovery signals the hook process group the killed parent left only
|
|
798
|
+
while the group's leader runs with its recorded start time. A group whose
|
|
799
|
+
leader has exited is never signalled, because its id may already belong to
|
|
800
|
+
another group. The recovery reports it in a warning, and any leftover
|
|
801
|
+
processes are ended by hand. A group that still has members while its
|
|
802
|
+
leader's start cannot be read (where `ps` fails) is not signalled either,
|
|
803
|
+
and the recovery does not go on past it: the leader may still be that hook,
|
|
804
|
+
or that git step. `add`, `remove` and `oats retire` refuse with
|
|
805
|
+
`E_LIFECYCLE_BUSY` and keep the record, naming the group, its recorded
|
|
806
|
+
start and the way out: check the group by hand and, if it is that hook or
|
|
807
|
+
git step, end it (`kill -TERM -- -<pgid>`) and retry. If it is not, remove
|
|
808
|
+
the record named in the message (for `add` and `remove`), or run `oats retire
|
|
809
|
+
<instance> --force`, which then keeps the branch.
|
|
810
|
+
|
|
811
|
+
**Leave the tree clean.** `oats worktree remove` refuses a tree with
|
|
812
|
+
uncommitted changes (`E_WORKTREE_DIRTY`). So a hook should leave the tree
|
|
813
|
+
clean: an install that does not rewrite the lockfile (`npm ci`, `yarn install
|
|
814
|
+
--immutable`, not a plain `npm install`), and outputs that are gitignored. A
|
|
815
|
+
hook that has to change tracked files says so in its capability's brief.
|
|
816
|
+
|
|
817
|
+
**Environment.** The standard hook variables above, and:
|
|
818
|
+
|
|
819
|
+
| Variable | Value |
|
|
820
|
+
|---|---|
|
|
821
|
+
| `OATS_TREE` | the absolute canonical path of the new tree |
|
|
822
|
+
| `OATS_TREE_CLONE` | the absolute path of the clone the tree was added from |
|
|
823
|
+
| `OATS_TREE_REMOTE` | the clone's `origin` URL, without credentials (below) |
|
|
824
|
+
| `OATS_TREE_MEMBER` | the member repository key, or empty (below) |
|
|
825
|
+
| `OATS_BRANCH` | the branch the tree was created on |
|
|
826
|
+
| `OATS_TREE_BASE` | the base as given: `--base`, or the spawn's planned base ref |
|
|
827
|
+
| `OATS_TREE_BASE_OID` | the commit the tree's HEAD is at when the hook starts |
|
|
828
|
+
| `OATS_PURPOSE` | the `--purpose`; empty for `./work` |
|
|
829
|
+
| `OATS_TREE_ORIGIN` | `spawn` or `add` |
|
|
830
|
+
|
|
831
|
+
`OATS_TREE_MEMBER` is never inferred over the network:
|
|
832
|
+
|
|
833
|
+
- `oats worktree add --repo <key>`: that key;
|
|
834
|
+
- `oats worktree add` without `--repo`: the soul's member key, when the
|
|
835
|
+
clone's local remotes name that repository;
|
|
836
|
+
- `oats worktree add --repo <path>`: empty;
|
|
837
|
+
- a spawn: the soul's member key, when the clone is a clone of the soul's
|
|
838
|
+
repository; else empty.
|
|
839
|
+
|
|
840
|
+
`OATS_TREE_REMOTE` never carries a credential. For a URL-style remote
|
|
841
|
+
(`scheme://userinfo@host/...`), the whole userinfo (`user:password@` or
|
|
842
|
+
`token@`) is dropped; for an scp-style remote (`user@host:path`), the `user@`
|
|
843
|
+
is dropped. `https://user:tok@host/org/r.git` becomes
|
|
844
|
+
`https://host/org/r.git`, and `git@host:org/r.git` becomes `host:org/r.git`.
|
|
845
|
+
The kernel records, prints, logs and passes on only this form: the hook
|
|
846
|
+
environment, the tree record, the instance event and the receipt.
|
|
847
|
+
|
|
848
|
+
**The environment is inherited.** As for every hook, the hook runs with the
|
|
849
|
+
environment of whoever ran the command; inside an instance session that is
|
|
850
|
+
the session's own. The kernel adds no credentials. A hook that needs a
|
|
851
|
+
registry token or a deploy key gets it from that environment, or from its
|
|
852
|
+
own configuration.
|
|
853
|
+
|
|
854
|
+
**Adoption.** A kernel before 0.49.0 refuses a manifest that declares
|
|
855
|
+
`hooks.worktree`, and with it the whole capability. In order:
|
|
856
|
+
|
|
857
|
+
1. Upgrade the kernel on **every host that composes the capability**.
|
|
858
|
+
2. Only then declare `hooks.worktree`, with `compatibility.oats:
|
|
859
|
+
">=0.49.0"`, so an older host refuses with `E_CAPABILITY_INCOMPATIBLE`
|
|
860
|
+
naming the release, not with a schema error.
|
|
861
|
+
3. The blast radius is every soul that composes the capability, on every host
|
|
862
|
+
below the release: one capability can stop every developer soul of a
|
|
863
|
+
workspace from spawning, as in lfx-oats-workspace#22, where one capability
|
|
864
|
+
took down every developer soul.
|
|
865
|
+
4. To limit it, put the hook in a small capability composed only by the souls
|
|
866
|
+
that need the setup.
|
|
867
|
+
5. Declare it `required` when the tree is unusable without the setup.
|
|
868
|
+
|
|
618
869
|
## Official packages
|
|
619
870
|
|
|
620
871
|
The official packages and the capabilities and souls each carries are listed
|
|
@@ -1016,3 +1267,169 @@ checks in one readiness read share 60 s, and checks the budget does not reach
|
|
|
1016
1267
|
are not run (`unknown`, `time-budget-exhausted`). Answer from configuration
|
|
1017
1268
|
and local state. A provider that must call a remote service should bound that
|
|
1018
1269
|
call well inside the 30 s.
|
|
1270
|
+
|
|
1271
|
+
## Trigger sources (`triggerSources`)
|
|
1272
|
+
|
|
1273
|
+
A capability may declare **trigger sources**: each is one of its own commands
|
|
1274
|
+
that, at each poll, lists the events that are due now. A
|
|
1275
|
+
[trigger](schedules.md#capability-sources) names one as `on.source:
|
|
1276
|
+
"<capability>:<source>"`, and the kernel keeps everything after the list:
|
|
1277
|
+
event keys, at-least-once recording, pending events, concurrency, the
|
|
1278
|
+
instance name, the event file and the spawn.
|
|
1279
|
+
|
|
1280
|
+
```json
|
|
1281
|
+
"commands": { "review-source": "bin/graph.mjs review-source" },
|
|
1282
|
+
"triggerSources": {
|
|
1283
|
+
"harvest-branches": {
|
|
1284
|
+
"command": "review-source",
|
|
1285
|
+
"description": "Ready harvest/* branches, one event per judged head",
|
|
1286
|
+
"events": ["opened", "updated"],
|
|
1287
|
+
"parameters": { "prefix": { "default": "harvest/", "description": "Branch prefix", "pattern": "^[A-Za-z0-9._/-]{1,80}$" } },
|
|
1288
|
+
"fields": { "graph": { "pattern": "^[a-z0-9-]{1,40}$" }, "branch": {} },
|
|
1289
|
+
"urlHosts": ["graph.example.org"]
|
|
1290
|
+
}
|
|
1291
|
+
}
|
|
1292
|
+
```
|
|
1293
|
+
|
|
1294
|
+
- **The source name** is 1 to 40 lowercase letters, digits and dashes,
|
|
1295
|
+
starting with a letter or digit. At most 16 sources.
|
|
1296
|
+
- **`command`** names one of `commands`. Its script must resolve to a regular
|
|
1297
|
+
file inside the module directory.
|
|
1298
|
+
- **`description`** (optional): one line of at most 200 characters.
|
|
1299
|
+
- **`events`**: 1 to 16 distinct names, each 1 to 40 lowercase letters,
|
|
1300
|
+
digits and underscores, starting with a letter.
|
|
1301
|
+
- **`parameters`** (optional, at most 16), named with a letter then letters,
|
|
1302
|
+
digits and underscores (at most 40): `{ required?, default?, description?,
|
|
1303
|
+
pattern? }`. A value is a string of at most 200 characters matching
|
|
1304
|
+
`pattern`, by default `^[A-Za-z0-9._/:@ ,*-]{0,200}$`; a `default` must
|
|
1305
|
+
match it too. Parameters reach the source only, never a task.
|
|
1306
|
+
- **`fields`** (optional, at most 16, named as parameters): `{ pattern? }`, by
|
|
1307
|
+
default `^[A-Za-z0-9._/:@-]{1,200}$`. A trigger's template may name a
|
|
1308
|
+
declared field as `{fields.<name>}`; the value is the event's, validated.
|
|
1309
|
+
Whatever the pattern admits (`.*` included), a value longer than 200
|
|
1310
|
+
characters (code points), or carrying a control character, a line or
|
|
1311
|
+
paragraph separator, a bidi control, U+200B, U+2060, U+FEFF or a tag
|
|
1312
|
+
character, makes its event invalid, and the pattern is never run on one.
|
|
1313
|
+
- **Patterns** are JavaScript regular expressions with the `u` flag (the flag
|
|
1314
|
+
JSON Schema's `pattern` uses), compiled once and always matched whole: the
|
|
1315
|
+
kernel wraps each as `^(?:…)$`. One that does not compile makes the source
|
|
1316
|
+
malformed.
|
|
1317
|
+
- **`urlHosts`** (optional, at most 16): the exact lowercase hostnames an
|
|
1318
|
+
event's `url` may name. With none declared, an event's `url` is invalid.
|
|
1319
|
+
The allow-list lives here, never on an event. An event's `url` must also be
|
|
1320
|
+
printable ASCII with no space (`0x21`–`0x7e`) as written: percent-encode
|
|
1321
|
+
anything else.
|
|
1322
|
+
|
|
1323
|
+
**Containment.** A malformed `triggerSources` **never refuses the
|
|
1324
|
+
capability**. It is not part of the manifest contract that spawn, discovery
|
|
1325
|
+
and the lock check: they ignore it. It is validated only where a source is
|
|
1326
|
+
used, by `trigger add`, a poll, `trigger test` and `trigger poll`, **per
|
|
1327
|
+
source**: a malformed source fails only the triggers naming it
|
|
1328
|
+
(`E_TRIGGER_SOURCE`, `details: { capability, source, pointer }`, the pointer
|
|
1329
|
+
into the manifest), and a well-formed sibling keeps working. A malformed top
|
|
1330
|
+
level (not an object, or more than 16 sources) fails every trigger naming the
|
|
1331
|
+
capability. `oats capabilities show <name> --json` adds `triggerSources`,
|
|
1332
|
+
exactly as declared, and, when the declaration has any, the problems a trigger
|
|
1333
|
+
would get as `triggerSourceProblems: [{ source, pointer, message }]`
|
|
1334
|
+
(`source` `null` for the top level); it never refuses the command. The
|
|
1335
|
+
closed sub-schema is in
|
|
1336
|
+
[`capability-manifest.schema.json`](capability-manifest.schema.json); what a
|
|
1337
|
+
schema cannot say (a pattern compiles, `command` names a command, a default
|
|
1338
|
+
matches its pattern) is checked at use only.
|
|
1339
|
+
|
|
1340
|
+
**Schema tooling.** The runtime ignores manifest keys it does not know, but
|
|
1341
|
+
until this release the published `capability-manifest.schema.json` was closed
|
|
1342
|
+
at the top level (`additionalProperties: false`). A tool validating a manifest
|
|
1343
|
+
against an older copy of the schema flags `triggerSources`: the repository's
|
|
1344
|
+
own `validate-project`, the package dry-run checks, a provider's CI that pins
|
|
1345
|
+
the schema. Validate against this release's schema, or declare the key once
|
|
1346
|
+
your tooling uses it. A provider declaring `triggerSources` does not need to
|
|
1347
|
+
raise `compatibility.oats`: every workspace-model kernel ignores the key, and
|
|
1348
|
+
only the host that runs a trigger naming the source needs this release.
|
|
1349
|
+
|
|
1350
|
+
**Invocation.** A poll runs the command's script with `node`, from the
|
|
1351
|
+
capability's directory in the deployment's verified module store (the
|
|
1352
|
+
capability at its resolved commit, digest-verified, for a member capability
|
|
1353
|
+
as for a package one), with the command's words after the script as
|
|
1354
|
+
arguments and no shell. The host tick runs it through a child `oats trigger
|
|
1355
|
+
poll <id> --run-source --max-age 600`; a person, through `oats trigger poll
|
|
1356
|
+
<id> --run-source` or `oats trigger test <id> --run-source`. Those
|
|
1357
|
+
**execute the capability's source command** whatever the host's trust and
|
|
1358
|
+
the trigger's `runsOn` say, and so only with `--run-source`: without it they
|
|
1359
|
+
are refused (`E_TRIGGER_SOURCE_RUN`) before anything of the capability runs
|
|
1360
|
+
or is written. The flag is caller intent, never trust consent: see
|
|
1361
|
+
[schedules.md](schedules.md#capability-sources). A poll records nothing on
|
|
1362
|
+
its own; the tick records what it folds.
|
|
1363
|
+
|
|
1364
|
+
**Request** — one JSON document on stdin, with exactly these keys:
|
|
1365
|
+
|
|
1366
|
+
```json
|
|
1367
|
+
{"schemaVersion":1,"phase":"poll","capability":"acme.graph","source":"harvest-branches","trigger":"local/harvest-review",
|
|
1368
|
+
"params":{"prefix":"harvest/"},"settings":{"store":"~/.graph"},
|
|
1369
|
+
"input":{"context":{"kind":"workspace","workspace":"github.com/acme/agents","deployment":"/srv/acme",
|
|
1370
|
+
"soul":"graph-reviewer","host":"kb-bot-server"}}}
|
|
1371
|
+
```
|
|
1372
|
+
|
|
1373
|
+
- `trigger` is the qualified trigger id.
|
|
1374
|
+
- `params` are the trigger's, with the declared defaults applied (a parameter
|
|
1375
|
+
with neither a value nor a default is absent).
|
|
1376
|
+
- `settings` is the merged provider payload the trigger's soul resolves for
|
|
1377
|
+
the capability.
|
|
1378
|
+
- `host` is this host's `host.name`, or `null`.
|
|
1379
|
+
|
|
1380
|
+
**Environment:** the one a `--soul` [readiness check](#readiness-check-bindingcheck)
|
|
1381
|
+
gets, for the trigger's soul: every ambient `OATS_*`, `OAS_*` and `PI_*`
|
|
1382
|
+
variable removed, the rest inherited, and the kernel's `OATS_CAPABILITY`,
|
|
1383
|
+
`OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `OATS_WORKSPACE`,
|
|
1384
|
+
the team variables, `OATS_AGENT`, `OATS_SOUL_ID` and `OATS_SOUL`. There is no
|
|
1385
|
+
`OATS_INSTANCE` or `OATS_INSTANCE_HOME`, and the kernel passes no credential.
|
|
1386
|
+
Under the host timer, the inherited environment is the timer's (only `PATH`
|
|
1387
|
+
and `OATS_HOME_DIR`): keep the source's login in its own store under `HOME`,
|
|
1388
|
+
not in an exported variable.
|
|
1389
|
+
|
|
1390
|
+
**Answer** — exit 0, and exactly one JSON document on stdout, at most 1 MiB
|
|
1391
|
+
(whitespace around it is fine; progress text is not):
|
|
1392
|
+
|
|
1393
|
+
```json
|
|
1394
|
+
{"schemaVersion":1,"phase":"poll","capability":"acme.graph","source":"harvest-branches","ok":true,
|
|
1395
|
+
"result":{"events":[{"key":"harvest/x:9f2c41d","subject":"harvest/x","event":"opened",
|
|
1396
|
+
"url":"https://graph.example.org/x","fields":{"graph":"kb","branch":"harvest/x"}}],
|
|
1397
|
+
"skipped":[{"subject":"harvest/y","why":"not judged yet"}]}}
|
|
1398
|
+
```
|
|
1399
|
+
|
|
1400
|
+
- **The envelope** has exactly `schemaVersion, phase, capability, source, ok,
|
|
1401
|
+
result`; `schemaVersion`, `phase`, `capability` and `source` echo the
|
|
1402
|
+
request. `result` is `{ events, skipped? }`, exactly.
|
|
1403
|
+
- **A refusal** is `{…, "ok": false, "error": { "code", "message"? }}`.
|
|
1404
|
+
- **An event** is `{ key, subject, event, url?, fields? }`: the rules are in
|
|
1405
|
+
[schedules.md](schedules.md#capability-sources). An invalid event is
|
|
1406
|
+
dropped alone; the others go on.
|
|
1407
|
+
- **`skipped`** (optional) is `[{ subject, why }]`: what the source looked at
|
|
1408
|
+
and chose not to list, shown in `trigger status` and `trigger test`.
|
|
1409
|
+
|
|
1410
|
+
| Outcome | `E_TRIGGER_POLL` `details.cause` | recorded |
|
|
1411
|
+
|---|---|---|
|
|
1412
|
+
| nonzero exit or a signal | `exit` | nothing; pending events kept |
|
|
1413
|
+
| not exactly one JSON document, unknown keys, a wrong echo, a malformed `result`, over 1 MiB | `result` | nothing |
|
|
1414
|
+
| more than 500 events, or more than 100 skipped | `too-many-events` | nothing |
|
|
1415
|
+
| over 30 s (killed) | `timeout` | nothing |
|
|
1416
|
+
| `ok: false` | `refused`, with `details.source: { code, message? }` | nothing |
|
|
1417
|
+
| the soul does not resolve | `resolution` | nothing |
|
|
1418
|
+
| the trigger's meaning does not hold | (`E_TRIGGER_SOURCE` / `E_TRIGGER_INVALID`) | nothing; the source does not run |
|
|
1419
|
+
|
|
1420
|
+
**Your text is untrusted.** A skipped item's `why`, a refusal's `message` and
|
|
1421
|
+
its `code` are never composed into a task or any kernel sentence. They are
|
|
1422
|
+
kept only in fields that name the source and printed under `source says:`,
|
|
1423
|
+
capped (`why` 200 characters, `message` 500, `code` 128) and with every
|
|
1424
|
+
control character, line or paragraph separator, bidi control, U+200B,
|
|
1425
|
+
U+2060, U+FEFF and tag character replaced by U+FFFD. What a task may carry
|
|
1426
|
+
(`{subject}`, `{key}`, `{url}`, `{fields.<name>}`) is refused rather than
|
|
1427
|
+
replaced: an event whose `url` is not printable ASCII, or whose field value
|
|
1428
|
+
is longer than 200 characters or carries one of those characters whatever
|
|
1429
|
+
its pattern admits, is an invalid event.
|
|
1430
|
+
|
|
1431
|
+
**Time.** A source gets at most 30 s and is killed after that; the tick's
|
|
1432
|
+
whole poll, resolution included, gets 35 s, and polls run only while they can
|
|
1433
|
+
end within 50 s of the tick's start. Answer from a cache or a quick query: a
|
|
1434
|
+
source slower than that should cache.
|
|
1435
|
+
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
"OptionalHook": {
|
|
25
25
|
"oneOf":[
|
|
26
26
|
{"type":"string"},
|
|
27
|
-
{"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"required":{"const":false,"description":"Only the
|
|
27
|
+
{"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"required":{"const":false,"description":"Only the spawn and worktree hooks may be required."},"inputs":{"$ref":"#/$defs/HookInputs"}}}
|
|
28
28
|
]
|
|
29
29
|
}
|
|
30
30
|
},
|
|
@@ -248,6 +248,48 @@
|
|
|
248
248
|
}
|
|
249
249
|
}
|
|
250
250
|
},
|
|
251
|
+
"triggerSources": {
|
|
252
|
+
"description": "Trigger sources (#669): each a command of this capability that, at each poll, lists the events due now; a trigger names one as on.source \"<capability>:<source>\". Validated only where a source is used (trigger add, a poll, trigger test and trigger poll), never when the capability loads: a malformed declaration fails the triggers naming it (E_TRIGGER_SOURCE) and nothing else. Checked at use only, not by this schema: every pattern compiles; command names a key of commands; a parameter default matches its pattern. A pattern is ECMA-262 with the u flag, matched anchored as ^(?:…)$; the default parameter value pattern is ^[A-Za-z0-9._/:@ ,*-]{0,200}$ and the default field pattern ^[A-Za-z0-9._/:@-]{1,200}$. Whatever its pattern admits, an event's field value is at most 200 code points and carries no control, bidi, invisible or tag character.",
|
|
253
|
+
"type": "object",
|
|
254
|
+
"maxProperties": 16,
|
|
255
|
+
"propertyNames": { "pattern": "^[a-z0-9][a-z0-9-]{0,39}$" },
|
|
256
|
+
"additionalProperties": {
|
|
257
|
+
"type": "object",
|
|
258
|
+
"required": ["command", "events"],
|
|
259
|
+
"additionalProperties": false,
|
|
260
|
+
"properties": {
|
|
261
|
+
"command": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "One of this manifest's commands: the source's program, run once per poll (one JSON request on stdin, one JSON answer on stdout)." },
|
|
262
|
+
"description": { "type": "string", "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
|
|
263
|
+
"events": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } },
|
|
264
|
+
"parameters": {
|
|
265
|
+
"type": "object",
|
|
266
|
+
"maxProperties": 16,
|
|
267
|
+
"propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}$" },
|
|
268
|
+
"additionalProperties": {
|
|
269
|
+
"type": "object",
|
|
270
|
+
"additionalProperties": false,
|
|
271
|
+
"properties": {
|
|
272
|
+
"required": { "type": "boolean" },
|
|
273
|
+
"default": { "type": "string", "maxLength": 200 },
|
|
274
|
+
"description": { "type": "string", "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
|
|
275
|
+
"pattern": { "type": "string", "minLength": 1 }
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
},
|
|
279
|
+
"fields": {
|
|
280
|
+
"type": "object",
|
|
281
|
+
"maxProperties": 16,
|
|
282
|
+
"propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}$" },
|
|
283
|
+
"additionalProperties": {
|
|
284
|
+
"type": "object",
|
|
285
|
+
"additionalProperties": false,
|
|
286
|
+
"properties": { "pattern": { "type": "string", "minLength": 1 } }
|
|
287
|
+
}
|
|
288
|
+
},
|
|
289
|
+
"urlHosts": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "maxLength": 253, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$" } }
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
},
|
|
251
293
|
"hooks": {
|
|
252
294
|
"type": "object",
|
|
253
295
|
"properties": {
|
|
@@ -259,9 +301,17 @@
|
|
|
259
301
|
]
|
|
260
302
|
},
|
|
261
303
|
"retire": {"$ref":"#/$defs/OptionalHook"},
|
|
262
|
-
"launch": {"$ref":"#/$defs/OptionalHook"}
|
|
304
|
+
"launch": {"$ref":"#/$defs/OptionalHook"},
|
|
305
|
+
"worktree": {
|
|
306
|
+
"description": "Runs once in each tree the kernel creates: ./work of a work: worktree spawn (after the spawn hooks) and each `oats worktree add`. Its cwd is the new tree; see docs/capabilities.md, The worktree event.",
|
|
307
|
+
"oneOf":[
|
|
308
|
+
{"type":"string"},
|
|
309
|
+
{"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"required":{"type":"boolean","description":"When true, a failure or timeout fails the spawn, or removes the tree `oats worktree add` made."},"inputs":{"$ref":"#/$defs/HookInputs"}}}
|
|
310
|
+
]
|
|
311
|
+
}
|
|
263
312
|
},
|
|
264
|
-
"additionalProperties":
|
|
313
|
+
"additionalProperties": {"$ref":"#/$defs/OptionalHook"},
|
|
314
|
+
"description": "Lifecycle events to commands. An event this kernel does not run (a newer kernel's) is accepted with a warning and ignored, unless it is declared required: that is refused. Kernels before 0.49.0 refuse every unknown event."
|
|
265
315
|
},
|
|
266
316
|
"settings": {
|
|
267
317
|
"type": "object",
|
|
@@ -320,10 +370,15 @@
|
|
|
320
370
|
},
|
|
321
371
|
"work": {
|
|
322
372
|
"type": "array",
|
|
323
|
-
"description": "Relative roots under work/ that a worktree instance's capability generates. Their untracked or ignored bytes do not count as the instance's untracked or ignored worktree bytes; they are still copied when a recovery copy is made.",
|
|
373
|
+
"description": "Relative roots under work/ that a worktree instance's capability generates. Their untracked or ignored bytes do not count as the instance's untracked or ignored worktree bytes; they are still copied when a recovery copy is made. A backslash reads as /, one leading ./ and one trailing / are dropped, and what is left must be a relative path with no empty, . or .. segment; an absolute path (/x, C:/x) is refused. Two entries of one manifest that overlap (the same root, or one inside the other) are refused; spawn also refuses roots of different capabilities that overlap, and a root that is a symlink in the work.",
|
|
324
374
|
"items": {
|
|
325
375
|
"type": "string",
|
|
326
|
-
"minLength": 1
|
|
376
|
+
"minLength": 1,
|
|
377
|
+
"pattern": "^(?:\\.[/\\\\])?(?!\\.{1,2}(?:[/\\\\]|$))[^/\\\\]+(?:[/\\\\](?!\\.{1,2}(?:[/\\\\]|$))[^/\\\\]+)*[/\\\\]?$",
|
|
378
|
+
"not": {
|
|
379
|
+
"description": "A Windows absolute path is refused on every host.",
|
|
380
|
+
"pattern": "^[A-Za-z]:[/\\\\]"
|
|
381
|
+
}
|
|
327
382
|
}
|
|
328
383
|
}
|
|
329
384
|
},
|