@awebai/oats 0.47.0 → 0.49.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 +293 -41
- package/docs/capabilities.md +264 -8
- package/docs/capability-manifest.schema.json +18 -5
- package/docs/configuration.md +7 -1
- package/docs/desktop-cli-api.md +439 -40
- package/docs/desktop.md +72 -5
- package/docs/execution-targets.md +19 -1
- package/docs/implementation.md +81 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +6 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.48.0.md +106 -0
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/schedules.md +62 -39
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +395 -52
- package/docs/workspaces.md +18 -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 +5 -2
- package/lib/core.mjs +1147 -319
- package/lib/instance-events.mjs +6 -3
- package/lib/instance-git.mjs +11 -5
- package/lib/instance-inspect.mjs +14 -3
- 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/resolve.mjs +4 -4
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +1 -0
- package/lib/servers.mjs +32 -6
- package/lib/teams-verbs.mjs +40 -9
- package/lib/tree-copy.mjs +18 -7
- package/lib/triggers.mjs +201 -65
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +12 -5
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
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.
|
|
58
|
-
oats.okf:
|
|
57
|
+
oats.framework: v1.8.0 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.0.0
|
|
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
|
|
@@ -421,11 +421,26 @@ the workspace). A soul's teams are edited by a PR to `oats-workspace.yaml`:
|
|
|
421
421
|
```
|
|
422
422
|
oats teams [--json] # the teams, ids, the default, localTeams, the workspace's souls:, problems
|
|
423
423
|
oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the local default)
|
|
424
|
+
oats teams add <label> --team <id> --no-default # the mapping only; the same label and id again is reuse
|
|
424
425
|
oats teams remove <label> # refused while it is the local default (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
|
|
425
426
|
oats teams default <label> # the local default
|
|
427
|
+
oats teams default <label> --if-absent # ... only where there is no effective default
|
|
428
|
+
oats teams default <label> --expect <label0> # ... only where the effective default is <label0>
|
|
426
429
|
oats soul teams <soul>|'*' [--json] # a soul's default and teams here, and which souls: key gave them
|
|
427
430
|
```
|
|
428
431
|
|
|
432
|
+
`--if-absent` and `--expect` make a setup safe to run against a deployment
|
|
433
|
+
whose default it has not chosen: the condition is the effective default that
|
|
434
|
+
`oats teams` reports (the local one, else the workspace's), judged when the
|
|
435
|
+
file is written, and a failed one (`E_TEAM_DEFAULT_MISMATCH`) reports what it
|
|
436
|
+
found and writes nothing. A soul's `souls:` default is not the deployment's
|
|
437
|
+
default and is not looked at. Concurrent `oats teams` writes on one deployment
|
|
438
|
+
are serialized, so of two racing conditional writes the later one refuses;
|
|
439
|
+
hand edits to `oats-local.yaml` and changes to `oats-workspace.yaml` are not
|
|
440
|
+
serialized with them. Each form refuses a flag it does not take (`E_USAGE`).
|
|
441
|
+
Callers check for the feature `teams-conditional-default` in `oats version
|
|
442
|
+
--json` first: an older kernel ignores these flags.
|
|
443
|
+
|
|
429
444
|
The messaging provider's own setup creates provider teams (see the provider's
|
|
430
445
|
documentation). The spawn preview, `inspect` and `oats souls` report a soul's
|
|
431
446
|
`teams` and `defaultTeam`; readiness reports the team problems in
|
|
@@ -441,7 +456,7 @@ Why it is shaped this way: [team model 3](design/2026-10-02-team-model-3.md).
|
|
|
441
456
|
|
|
442
457
|
| What it is | Where | Example |
|
|
443
458
|
|---|---|---|
|
|
444
|
-
| True of every instance of the soul | `soul.yaml` → `knowledge:` / `messaging:` / `tasks:` | `messaging: { channels: [acme-eng] }`; `knowledge: { harvest
|
|
459
|
+
| True of every instance of the soul | `soul.yaml` → `knowledge:` / `messaging:` / `tasks:` | `messaging: { channels: [acme-eng] }`; `knowledge: { harvest: off }` |
|
|
445
460
|
| A fact about this machine | `oats-local.yaml` → `settings.<cap>.<key>` (absolute paths are refused in the workspace file) | `settings.oats.okf.state-dir: /Users/ana/.oats/okf` |
|
|
446
461
|
| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
|
|
447
462
|
|
package/injects/work-checkout.md
CHANGED
|
@@ -12,23 +12,29 @@ in the same tree as the human and possibly other agents.
|
|
|
12
12
|
### Extra trees
|
|
13
13
|
|
|
14
14
|
When the work needs another branch, or another repository of this deployment,
|
|
15
|
-
create an extra tree in your home.
|
|
16
|
-
(
|
|
17
|
-
|
|
18
|
-
branch itself, when you rework an existing one):
|
|
15
|
+
create an extra tree in your home. Run this from your home; `<base>` is the
|
|
16
|
+
remote branch the work starts from (the branch itself, when you rework an
|
|
17
|
+
existing one):
|
|
19
18
|
|
|
20
|
-
|
|
21
|
-
git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
|
|
22
|
-
git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
|
|
19
|
+
oats worktree add --purpose <purpose> --branch <branch> --base <base>
|
|
23
20
|
|
|
24
|
-
|
|
25
|
-
|
|
21
|
+
It makes `.work-<purpose>` in your home, on a new `<branch>` at `origin`'s
|
|
22
|
+
`<base>`. The repository is yours unless `--repo <member key|clone path>`
|
|
23
|
+
names another; `--preview` shows what it would do.
|
|
24
|
+
|
|
25
|
+
- It starts from the remote's current state and moves none of the clone's
|
|
26
|
+
refs. Never start a tree from a local branch of the clone, which may be stale.
|
|
26
27
|
- Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
|
|
27
|
-
If it already exists in that clone, `
|
|
28
|
+
If it already exists in that clone, `add` refuses: use `<instance>/<branch>`.
|
|
28
29
|
Never `-C`/`-B`, which reset a branch someone else may own.
|
|
30
|
+
- If a capability of yours sets up new trees, `add` runs that setup, which
|
|
31
|
+
may take minutes: give it a long timeout, or run it in the background and
|
|
32
|
+
wait for it to exit. A killed `add` rolls back; run it again. Once it has
|
|
33
|
+
finished, running it again with the same arguments does nothing.
|
|
29
34
|
- The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
|
|
30
35
|
(`<base>` when you rework an existing branch).
|
|
31
36
|
- Before your task closes, merge each extra tree into your PR branch, or push its
|
|
32
37
|
branch and name it in your hand-back; then
|
|
33
|
-
`
|
|
38
|
+
`oats worktree remove --purpose <purpose>`, which keeps the branch and
|
|
39
|
+
refuses a tree with uncommitted work.
|
|
34
40
|
Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
|
package/injects/work-worktree.md
CHANGED
|
@@ -4,8 +4,8 @@ Your `./work` is a **git worktree on your own branch** — a full checkout that
|
|
|
4
4
|
yours alone: build, test and commit there, on your branch.
|
|
5
5
|
|
|
6
6
|
- **Never work in a shared checkout** (the repo's main checkout, or any clone
|
|
7
|
-
others use): don't edit, commit or switch branches there.
|
|
8
|
-
|
|
7
|
+
others use): don't edit, commit or switch branches there. A clone is touched
|
|
8
|
+
only through `oats worktree add`/`remove` below. If unsure, `pwd`.
|
|
9
9
|
- Everything you change happens in `work/` or your extra trees — **including your
|
|
10
10
|
own soul** when it lives in this repo: soul edits are branch changes, reviewed
|
|
11
11
|
and merged like code.
|
|
@@ -14,23 +14,29 @@ yours alone: build, test and commit there, on your branch.
|
|
|
14
14
|
### Extra trees
|
|
15
15
|
|
|
16
16
|
When the work needs another branch, or another repository of this deployment,
|
|
17
|
-
create an extra tree in your home.
|
|
18
|
-
(
|
|
19
|
-
|
|
20
|
-
branch itself, when you rework an existing one):
|
|
17
|
+
create an extra tree in your home. Run this from your home; `<base>` is the
|
|
18
|
+
remote branch the work starts from (the branch itself, when you rework an
|
|
19
|
+
existing one):
|
|
21
20
|
|
|
22
|
-
|
|
23
|
-
git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
|
|
24
|
-
git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
|
|
21
|
+
oats worktree add --purpose <purpose> --branch <branch> --base <base>
|
|
25
22
|
|
|
26
|
-
|
|
27
|
-
|
|
23
|
+
It makes `.work-<purpose>` in your home, on a new `<branch>` at `origin`'s
|
|
24
|
+
`<base>`. The repository is yours unless `--repo <member key|clone path>`
|
|
25
|
+
names another; `--preview` shows what it would do.
|
|
26
|
+
|
|
27
|
+
- It starts from the remote's current state and moves none of the clone's
|
|
28
|
+
refs. Never start a tree from a local branch of the clone, which may be stale.
|
|
28
29
|
- Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
|
|
29
|
-
If it already exists in that clone, `
|
|
30
|
+
If it already exists in that clone, `add` refuses: use `<instance>/<branch>`.
|
|
30
31
|
Never `-C`/`-B`, which reset a branch someone else may own.
|
|
32
|
+
- If a capability of yours sets up new trees, `add` runs that setup, which
|
|
33
|
+
may take minutes: give it a long timeout, or run it in the background and
|
|
34
|
+
wait for it to exit. A killed `add` rolls back; run it again. Once it has
|
|
35
|
+
finished, running it again with the same arguments does nothing.
|
|
31
36
|
- The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
|
|
32
37
|
(`<base>` when you rework an existing branch).
|
|
33
38
|
- Before your task closes, merge each extra tree into your PR branch, or push its
|
|
34
39
|
branch and name it in your hand-back; then
|
|
35
|
-
`
|
|
40
|
+
`oats worktree remove --purpose <purpose>`, which keeps the branch and
|
|
41
|
+
refuses a tree with uncommitted work.
|
|
36
42
|
Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
|
|
@@ -6,11 +6,16 @@
|
|
|
6
6
|
*
|
|
7
7
|
* Covers what the kernel enforces when it RUNS a capability, checked where the
|
|
8
8
|
* manifest is READ instead: the launch environment a capability may declare
|
|
9
|
-
* (names, namespaces), its hooks (approved events,
|
|
10
|
-
*
|
|
11
|
-
* value against the manifest's
|
|
9
|
+
* (names, namespaces), its hooks (approved events, an unknown one a warning unless
|
|
10
|
+
* required; declaration shape, `required` only on spawn and worktree, the script
|
|
11
|
+
* inside the capability), and a provider payload's value against the manifest's
|
|
12
|
+
* `settings.<key>.values`. Dependency-free. */
|
|
12
13
|
|
|
13
|
-
export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch"]);
|
|
14
|
+
export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch", "worktree"]);
|
|
15
|
+
/** The events whose hook may be declared `required: true`: each has a moment
|
|
16
|
+
* that can fail closed (a spawn's transaction; `oats worktree add`, which
|
|
17
|
+
* removes the tree it made). */
|
|
18
|
+
export const REQUIRABLE_HOOKS = new Set(["spawn", "worktree"]);
|
|
14
19
|
export const PORTABLE_ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
|
|
15
20
|
export const CAPABILITY_ENV_ID_RE = /^[a-z][a-z0-9]*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
|
|
16
21
|
export const CORE_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME"]);
|
|
@@ -34,9 +39,25 @@ export function hookScriptEscapes(command) {
|
|
|
34
39
|
}
|
|
35
40
|
|
|
36
41
|
/** Every contract problem of one manifest → [{ pointer, message }] (empty when it is sound).
|
|
37
|
-
*
|
|
42
|
+
* The problems of `manifestContract`, for a reader that has no warning channel. */
|
|
38
43
|
export function manifestContractProblems(m) {
|
|
44
|
+
return manifestContract(m).problems;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** One manifest against the kernel contract → { problems, warnings }, each
|
|
48
|
+
* [{ pointer, message }] (warnings also carry `code`). A problem refuses the
|
|
49
|
+
* manifest; a warning names what this kernel ignores in a manifest it accepts.
|
|
50
|
+
* Messages name the capability; `pointer` is the JSON pointer inside oats.json.
|
|
51
|
+
*
|
|
52
|
+
* An unknown hook event is forward-tolerant (0.49.0): a newer kernel's event
|
|
53
|
+
* declared as a command, `{ command }` or `{ command, required: false }` is a
|
|
54
|
+
* warning and never runs here, so the next new event does not drop every
|
|
55
|
+
* capability that adopts it on an older host. Declared `required: true`, it
|
|
56
|
+
* stays refused: skipping a hook its author declared essential is fail-open.
|
|
57
|
+
* The declaration's shape and its script are checked as for a known event. */
|
|
58
|
+
export function manifestContract(m) {
|
|
39
59
|
const problems = [];
|
|
60
|
+
const warnings = [];
|
|
40
61
|
const id = m?.capability;
|
|
41
62
|
const bad = (pointer, message) => problems.push({ pointer, message: `capability ${id} ${message}` });
|
|
42
63
|
|
|
@@ -76,15 +97,19 @@ export function manifestContractProblems(m) {
|
|
|
76
97
|
if (hooks.length && !/^[a-z][a-z0-9]*\./.test(String(id))) bad("/hooks", "declares hooks but its id has no dotted lowercase vendor component (e.g. acme.tool); only a dotted id can carry hooks");
|
|
77
98
|
for (const [event, value] of hooks) {
|
|
78
99
|
const at = `/hooks/${pointerKey(event)}`;
|
|
79
|
-
|
|
100
|
+
const known = APPROVED_HOOKS.has(event);
|
|
101
|
+
const sound = problems.length;
|
|
80
102
|
const extraKeys = isObject(value) ? Object.keys(value).filter((k) => !["command", "required", "inputs"].includes(k)) : [];
|
|
81
103
|
const command = typeof value === "string" ? value : isObject(value) && typeof value.command === "string" ? value.command : undefined;
|
|
82
104
|
if (command === undefined || !command.trim() || extraKeys.length) { bad(at, `hook "${event}" must be a command string or { command, required, inputs }${extraKeys.length ? ` (unknown: ${extraKeys.join(", ")})` : ""}`); continue; }
|
|
83
105
|
if (isObject(value) && value.required !== undefined && typeof value.required !== "boolean") bad(`${at}/required`, `hook "${event}": "required" must be a boolean`);
|
|
84
|
-
//
|
|
85
|
-
|
|
86
|
-
|
|
106
|
+
// An unknown event its author declared essential cannot be skipped.
|
|
107
|
+
else if (!known && isObject(value) && value.required === true) bad(at, `declares unsupported hook "${event}" (${[...APPROVED_HOOKS].join(", ")})`);
|
|
108
|
+
// Only a spawn or worktree hook can fail what it serves; marking others
|
|
109
|
+
// required would promise an enforcement that has no defined moment to act.
|
|
110
|
+
else if (known && isObject(value) && value.required === true && !REQUIRABLE_HOOKS.has(event)) bad(`${at}/required`, `hook "${event}" cannot be required — only the spawn and worktree hooks are enforced (retire, launch and soul-scaffold run outside a transaction that can fail closed)`);
|
|
87
111
|
if (hookScriptEscapes(command)) bad(isObject(value) ? `${at}/command` : at, `hook "${event}" script ${JSON.stringify(command.trim().split(/\s+/)[0])} escapes the capability directory; a hook script is a path inside it`);
|
|
112
|
+
if (!known && problems.length === sound) warnings.push({ code: "hook-event-unsupported", pointer: at, message: `capability ${id} declares hook "${event}", which this kernel does not run; it is ignored (this kernel runs ${[...APPROVED_HOOKS].join(", ")})` });
|
|
88
113
|
}
|
|
89
114
|
|
|
90
115
|
if (m.retirement !== undefined) {
|
|
@@ -98,7 +123,17 @@ export function manifestContractProblems(m) {
|
|
|
98
123
|
if (roots === undefined) continue;
|
|
99
124
|
const at = `/retirement/disposable/${scope}`;
|
|
100
125
|
if (!Array.isArray(roots) || roots.some((root) => typeof root !== "string")) { bad(at, `manifest retirement.disposable.${scope} must be an array of relative roots`); continue; }
|
|
101
|
-
if (scope
|
|
126
|
+
if (scope === "work") {
|
|
127
|
+
const sound = [];
|
|
128
|
+
roots.forEach((root, i) => {
|
|
129
|
+
if (disposableWorkRootProblem(root)) { bad(`${at}/${i}`, `manifest retirement.disposable.work entry ${JSON.stringify(root)} must be a relative path under work/ with no empty, "." or ".." segment`); return; }
|
|
130
|
+
const normalized = normalizeDisposableWorkRoot(root);
|
|
131
|
+
const other = sound.find((r) => disposableWorkRootsOverlap(r.normalized, normalized));
|
|
132
|
+
if (other) bad(`${at}/${i}`, `manifest retirement.disposable.work entry ${JSON.stringify(root)} overlaps entry ${JSON.stringify(other.root)}: the same root, or one inside the other`);
|
|
133
|
+
else sound.push({ root, normalized });
|
|
134
|
+
});
|
|
135
|
+
continue;
|
|
136
|
+
}
|
|
102
137
|
roots.forEach((root, i) => {
|
|
103
138
|
const problem = disposableHomeRootProblem(root);
|
|
104
139
|
if (problem === "shape") bad(`${at}/${i}`, `manifest retirement.disposable.home entry ${JSON.stringify(root)} must name one hidden top-level home entry (".name", or ".prefix-*")`);
|
|
@@ -107,7 +142,29 @@ export function manifestContractProblems(m) {
|
|
|
107
142
|
}
|
|
108
143
|
}
|
|
109
144
|
}
|
|
110
|
-
return problems;
|
|
145
|
+
return { problems, warnings };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** A manifest's contract warnings as a command reports them: [{ code, capability, path, message }],
|
|
149
|
+
* `path` the warning's JSON pointer under `at`, where the manifest is read
|
|
150
|
+
* (`<repoKey>:<dir>/oats.json` for a member's, `package:<id>:<dir>/oats.json` for a package's,
|
|
151
|
+
* a file path for a home's module copy). Empty for a manifest with none. */
|
|
152
|
+
export function locatedContractWarnings(manifest, at) {
|
|
153
|
+
return manifestContract(manifest).warnings.map((w) => ({ code: w.code, capability: manifest.capability, path: `${at}#${w.pointer}`, message: w.message }));
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/** Contract warnings as the spawn and its preview carry them, among their other warning strings:
|
|
157
|
+
* each message clipped to CONTRACT_WARNING_TEXT characters, and at most CONTRACT_WARNING_LINES of
|
|
158
|
+
* them, then one line naming how many more (inspect lists every one, unclipped). A hook event's
|
|
159
|
+
* name is unbounded; the Desktop reads a spawn's warnings as at most 512 strings of at most 4096
|
|
160
|
+
* characters, and refuses the whole receipt past that. */
|
|
161
|
+
export const CONTRACT_WARNING_TEXT = 1000;
|
|
162
|
+
export const CONTRACT_WARNING_LINES = 32;
|
|
163
|
+
export function contractWarningMessages(warnings) {
|
|
164
|
+
const clip = (text) => (text.length > CONTRACT_WARNING_TEXT ? `${text.slice(0, CONTRACT_WARNING_TEXT - 1)}…` : text);
|
|
165
|
+
const shown = warnings.length > CONTRACT_WARNING_LINES ? warnings.slice(0, CONTRACT_WARNING_LINES - 1) : warnings;
|
|
166
|
+
const more = warnings.length - shown.length;
|
|
167
|
+
return [...shown.map((w) => clip(w.message)), ...(more ? [`${more} more hook events this kernel does not run are ignored (oats inspect lists every one)`] : [])];
|
|
111
168
|
}
|
|
112
169
|
|
|
113
170
|
/** `retirement.disposable.home`: provider-owned top-level entries of an instance
|
|
@@ -145,6 +202,38 @@ export function disposableHomeRootMatches(root, name) {
|
|
|
145
202
|
return root.endsWith("*") ? name.startsWith(root.slice(0, -1)) : name === root;
|
|
146
203
|
}
|
|
147
204
|
|
|
205
|
+
/** `retirement.disposable.work`: roots under an instance's work/ that a
|
|
206
|
+
* capability generates. The grammar is the one spawn applies where it records
|
|
207
|
+
* the roots (lib/core.mjs retirementDisposableRoots), so a manifest this
|
|
208
|
+
* accepts is one spawn records: a backslash reads as `/`, one leading `./` and
|
|
209
|
+
* one trailing `/` are dropped, and what is left is non-empty with no empty,
|
|
210
|
+
* `.` or `..` segment. An absolute path is refused as any host's spawn refuses
|
|
211
|
+
* it, a Windows one (`C:/x`) included: a manifest is read on every host. Spawn
|
|
212
|
+
* alone refuses a root that is a symlink in the work, or roots of different
|
|
213
|
+
* capabilities that overlap. The published schema
|
|
214
|
+
* (docs/capability-manifest.schema.json) states the same grammar. */
|
|
215
|
+
const ABSOLUTE_PATH_RE = /^(?:[/\\]|[A-Za-z]:[/\\])/;
|
|
216
|
+
|
|
217
|
+
/** Why `root` is not a declarable work root: "absolute", "segment" (empty
|
|
218
|
+
* after normalization, or an empty, "." or ".." segment), "shape" (not a
|
|
219
|
+
* non-empty string), or undefined when it is sound. */
|
|
220
|
+
export function disposableWorkRootProblem(root) {
|
|
221
|
+
if (typeof root !== "string" || !root) return "shape";
|
|
222
|
+
if (ABSOLUTE_PATH_RE.test(root)) return "absolute";
|
|
223
|
+
const normalized = normalizeDisposableWorkRoot(root);
|
|
224
|
+
return !normalized || normalized.split("/").some((part) => !part || part === "." || part === "..") ? "segment" : undefined;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/** A work root as spawn records it. */
|
|
228
|
+
function normalizeDisposableWorkRoot(root) {
|
|
229
|
+
return root.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** Whether two normalized work roots overlap: the same root, or one inside the other. */
|
|
233
|
+
function disposableWorkRootsOverlap(a, b) {
|
|
234
|
+
return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
|
|
235
|
+
}
|
|
236
|
+
|
|
148
237
|
/** The setting keys a manifest declares (`settings.<key>`), sorted: names only, never their
|
|
149
238
|
* descriptions or defaults. The spawn preview and inspect expose them so a client can gate
|
|
150
239
|
* a choice on a declared key (e.g. a messaging provider's `join`). */
|
package/lib/capability-show.mjs
CHANGED
|
@@ -22,6 +22,7 @@ import { posix } from "node:path";
|
|
|
22
22
|
import YAML from "yaml";
|
|
23
23
|
import { oatsError } from "./errors.mjs";
|
|
24
24
|
import { bindRemote } from "./packages.mjs";
|
|
25
|
+
import { locatedContractWarnings } from "./capability-contract.mjs";
|
|
25
26
|
import { capabilitySkills, lockedCapability, lockedPackageCapabilities, manifestFilePath, memberRef, unsafeRelPath } from "./resolve.mjs";
|
|
26
27
|
import { memberRowByKey } from "./workspace.mjs";
|
|
27
28
|
|
|
@@ -165,6 +166,8 @@ async function listing(source, { remote, remoteOptions }) {
|
|
|
165
166
|
}
|
|
166
167
|
|
|
167
168
|
const header = (source) => ({ capabilityShowApi: CAPABILITY_SHOW_API, name: source.name, kind: source.kind });
|
|
169
|
+
/** What the capability declares and this kernel ignores (an unknown hook event), where its manifest is read. */
|
|
170
|
+
const contractWarnings = (source) => locatedContractWarnings(source.manifest, source.kind === "package" ? `package:${source.package}:${source.dir}/oats.json` : `${source.repoKey}:${source.dir}/oats.json`);
|
|
168
171
|
|
|
169
172
|
/** The show answer (capabilityShowApi 1): the inject with its text, each skill with its description and files. */
|
|
170
173
|
export async function capabilityShow(source, { remote, remoteOptions }) {
|
|
@@ -192,7 +195,7 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
|
|
|
192
195
|
skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
|
|
193
196
|
}
|
|
194
197
|
}
|
|
195
|
-
return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems };
|
|
198
|
+
return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source) };
|
|
196
199
|
}
|
|
197
200
|
|
|
198
201
|
/** The `--file` answer: one file the show lists (the inject, or a listed skill file), at the row's commit.
|
|
@@ -204,5 +207,5 @@ export async function capabilityFile(source, path, { remote, remoteOptions }) {
|
|
|
204
207
|
const known = (listed.inject?.safe && listed.inject.path === path) || (listed.skills ?? []).some((s) => (s.files ?? []).some((f) => f.path === path));
|
|
205
208
|
if (!known) throw fail("E_CAPABILITY_FILE_UNKNOWN", `${path} is not a file \`oats capabilities show ${source.name}\` lists (the inject, or a skill's files)`, { path, name: source.name });
|
|
206
209
|
const { bytes, size } = await bindRemote(remote, remoteOptions).readRemoteFile(source.ref, source.commit, posix.join(source.dir, path));
|
|
207
|
-
return { ...header(source), commit: source.commit, file: { path, bytes: size, ...decodeText(bytes) } };
|
|
210
|
+
return { ...header(source), commit: source.commit, file: { path, bytes: size, ...decodeText(bytes) }, warnings: contractWarnings(source) };
|
|
208
211
|
}
|