@crewhaus/runtime-core 0.6.0 → 0.8.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/LICENSE +201 -0
- package/NOTICE +9 -0
- package/README.md +9 -0
- package/dist/alert-watchdog.d.ts +17 -1
- package/dist/alert-watchdog.js +91 -18
- package/dist/cli-markdown-lines.d.ts +20 -0
- package/dist/cli-markdown-lines.js +91 -0
- package/dist/cli-markdown.js +15 -13
- package/dist/flatten-union.d.ts +36 -0
- package/dist/flatten-union.js +65 -0
- package/dist/forged-footer.d.ts +51 -0
- package/dist/forged-footer.js +212 -0
- package/dist/identity.js +47 -21
- package/dist/incident-collector.js +25 -6
- package/dist/index.d.ts +257 -19
- package/dist/index.js +2097 -200
- package/dist/lineage-screen.d.ts +33 -0
- package/dist/lineage-screen.js +46 -0
- package/dist/observability.d.ts +11 -3
- package/dist/observability.js +52 -13
- package/dist/path-canonical.d.ts +74 -0
- package/dist/path-canonical.js +676 -0
- package/dist/pre-route.d.ts +5 -3
- package/dist/state-roots.d.ts +12 -0
- package/dist/state-roots.js +79 -0
- package/dist/tool-limit.d.ts +54 -0
- package/dist/tool-limit.js +66 -0
- package/package.json +51 -44
|
@@ -0,0 +1,676 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a path-kind operative value really lands, for the permission gate.
|
|
3
|
+
*
|
|
4
|
+
* The matcher (`@crewhaus/tool-permission-matcher`) and the subject builder
|
|
5
|
+
* (`preparePermissionSubject` in `@crewhaus/tool-executor`) are pure — the
|
|
6
|
+
* worker runtime runs them on a Cloudflare Worker, where there is no
|
|
7
|
+
* filesystem to ask. Following symlinks needs one, so it lives here, in the
|
|
8
|
+
* Node runtime that owns the workspace, and is handed to the subject builder
|
|
9
|
+
* as its `canonicalizePath`.
|
|
10
|
+
*
|
|
11
|
+
* A path is resolved against the workspace root, `..` collapsed, and its
|
|
12
|
+
* directories followed through symlinks (the deepest one that exists is
|
|
13
|
+
* realpath'd) — so it names the place the tool will actually touch — then
|
|
14
|
+
* written relative to the workspace. When the last component exists, it is
|
|
15
|
+
* written the way the directory stores it: on a filesystem that ignores case
|
|
16
|
+
* or Unicode normal form (macOS, Windows), `.ENV` opens `.env`, and a rule
|
|
17
|
+
* about `.env` must see that. When the last component is itself a symlink,
|
|
18
|
+
* its target is a second value. A path that ends up outside the workspace,
|
|
19
|
+
* whose destination cannot be worked out, or that is longer than any path can
|
|
20
|
+
* be ({@link MAX_PATH_CHARS}), is flagged; the matcher never lets it satisfy
|
|
21
|
+
* an allow rule and always lets it satisfy a deny or ask.
|
|
22
|
+
* A path on a filesystem that ignores case (or where that cannot be told) is
|
|
23
|
+
* marked `caseInsensitive`, so a deny or ask compares it ignoring case — the
|
|
24
|
+
* name a tool is about to CREATE has no stored spelling to read. A path that
|
|
25
|
+
* names an existing file (or a link to one) is marked `notDirectory`: a tool
|
|
26
|
+
* that walks what a directory holds finds nothing beneath it.
|
|
27
|
+
*
|
|
28
|
+
* The workspace root can itself be reached another way — the shell's `$PWD`
|
|
29
|
+
* through a symlinked directory, or a top-level symlink such as macOS's
|
|
30
|
+
* `/tmp` → `/private/tmp` — and a rule may name it that way:
|
|
31
|
+
* `alwaysDeny Write(/tmp/ws/.crewhaus/**)` while the runtime's cwd reads
|
|
32
|
+
* `/private/tmp/ws`. The same location under each of those spellings of the
|
|
33
|
+
* root is a further spelling, so such a deny is not dodged by a relative
|
|
34
|
+
* path. (A spelling, not a canonical value: it widens what a deny or ask
|
|
35
|
+
* catches, never what an allow grants.)
|
|
36
|
+
*/
|
|
37
|
+
import { lstatSync, readdirSync, readlinkSync, realpathSync, statSync } from "node:fs";
|
|
38
|
+
import * as path from "node:path";
|
|
39
|
+
import { physicalPath } from "@crewhaus/tool-safety/fs";
|
|
40
|
+
function toPosix(p) {
|
|
41
|
+
return path.sep === "\\" ? p.split(path.sep).join("/") : p;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The longest path this resolves, in UTF-16 code units; a longer one is
|
|
45
|
+
* refused before it is walked. Nothing that long can be opened or created:
|
|
46
|
+
* PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
|
|
47
|
+
* 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
|
|
48
|
+
* UTF-16 one. The limit is twice that because the part of a path that exists
|
|
49
|
+
* is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
|
|
50
|
+
* own: no spelling of the place reaches it, not even one through a symlink
|
|
51
|
+
* that shortens the part that exists.
|
|
52
|
+
*/
|
|
53
|
+
export const MAX_PATH_CHARS = 2 * (process.platform === "darwin" ? 1_024 : process.platform === "win32" ? 32_767 : 4_096);
|
|
54
|
+
/** Top-level symlinks and the directory each resolves to, read once per process. */
|
|
55
|
+
let topLevelLinksRead;
|
|
56
|
+
function topLevelLinks() {
|
|
57
|
+
if (topLevelLinksRead !== undefined)
|
|
58
|
+
return topLevelLinksRead;
|
|
59
|
+
const out = [];
|
|
60
|
+
const top = path.parse(path.resolve("/")).root;
|
|
61
|
+
try {
|
|
62
|
+
for (const entry of readdirSync(top, { withFileTypes: true })) {
|
|
63
|
+
if (!entry.isSymbolicLink())
|
|
64
|
+
continue;
|
|
65
|
+
const link = path.join(top, entry.name);
|
|
66
|
+
try {
|
|
67
|
+
out.push([link, realpathSync(link)]);
|
|
68
|
+
}
|
|
69
|
+
catch {
|
|
70
|
+
// A dangling top-level link names no directory a workspace is in.
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
catch {
|
|
75
|
+
// An unreadable root has no aliases to offer.
|
|
76
|
+
}
|
|
77
|
+
topLevelLinksRead = out;
|
|
78
|
+
return out;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* The other absolute spellings of the workspace root `rootReal` (already
|
|
82
|
+
* realpath'd): the root as given, `$PWD` when it resolves to the root, and
|
|
83
|
+
* the root under each top-level symlink whose target contains it.
|
|
84
|
+
*/
|
|
85
|
+
function rootAliases(rootAbs, rootReal, sources) {
|
|
86
|
+
const out = new Set();
|
|
87
|
+
if (rootAbs !== rootReal)
|
|
88
|
+
out.add(rootAbs);
|
|
89
|
+
const pwd = "pwd" in sources ? sources.pwd : process.env["PWD"];
|
|
90
|
+
if (pwd !== undefined && path.isAbsolute(pwd)) {
|
|
91
|
+
try {
|
|
92
|
+
if (realpathSync(pwd) === rootReal)
|
|
93
|
+
out.add(path.resolve(pwd));
|
|
94
|
+
}
|
|
95
|
+
catch {
|
|
96
|
+
// A $PWD that no longer resolves names nothing.
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
for (const [link, target] of sources.topLevelLinks ?? topLevelLinks()) {
|
|
100
|
+
if (rootReal === target)
|
|
101
|
+
out.add(link);
|
|
102
|
+
else if (rootReal.startsWith(target.endsWith(path.sep) ? target : `${target}${path.sep}`)) {
|
|
103
|
+
out.add(`${link}${rootReal.slice(target.length)}`);
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
out.delete(rootReal);
|
|
107
|
+
return [...out];
|
|
108
|
+
}
|
|
109
|
+
/** A relative path that leaves its base: `..`, `../x`, or another drive. */
|
|
110
|
+
function climbsOut(relative) {
|
|
111
|
+
return relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
|
|
112
|
+
}
|
|
113
|
+
/** True when the NAME exists, whether or not a symlink there leads anywhere. */
|
|
114
|
+
function nameExists(p) {
|
|
115
|
+
try {
|
|
116
|
+
lstatSync(p);
|
|
117
|
+
return true;
|
|
118
|
+
}
|
|
119
|
+
catch {
|
|
120
|
+
return false;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* True when `p` names an existing entry that is not a directory, following a
|
|
125
|
+
* symlink: nothing lies beneath it. A dangling link, or a name that is not
|
|
126
|
+
* there, is not known to be a file, so a tool that walks directories may
|
|
127
|
+
* still find something beneath it by the time it runs.
|
|
128
|
+
*/
|
|
129
|
+
function isNonDirectory(p) {
|
|
130
|
+
try {
|
|
131
|
+
return !statSync(p).isDirectory();
|
|
132
|
+
}
|
|
133
|
+
catch {
|
|
134
|
+
return false;
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
function isSymlink(p) {
|
|
138
|
+
try {
|
|
139
|
+
return lstatSync(p).isSymbolicLink();
|
|
140
|
+
}
|
|
141
|
+
catch {
|
|
142
|
+
return false;
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Where `target` would land with every symlink on the way followed — the
|
|
147
|
+
* deepest ancestor that exists is resolved, a dangling link is followed a hop
|
|
148
|
+
* by hand (a missing target is still a door), and the parts that do not exist
|
|
149
|
+
* yet are appended. Mirrors `resolveLocation` in `@crewhaus/tool-fs`, which is
|
|
150
|
+
* what the file tools check containment against. Throws when the chain
|
|
151
|
+
* cannot be resolved; the caller treats that as "cannot tell where it lands".
|
|
152
|
+
*/
|
|
153
|
+
function resolveLocation(target, depth = 0) {
|
|
154
|
+
if (depth > 40)
|
|
155
|
+
throw new Error(`symlink chain at "${target}" is too long to resolve`);
|
|
156
|
+
const { probe, tail } = deepestName(target);
|
|
157
|
+
let real;
|
|
158
|
+
try {
|
|
159
|
+
real = realpathSync(probe);
|
|
160
|
+
}
|
|
161
|
+
catch (err) {
|
|
162
|
+
if (err.code !== "ENOENT")
|
|
163
|
+
throw err;
|
|
164
|
+
const link = readlinkSync(probe);
|
|
165
|
+
real = resolveLocation(path.resolve(realpathSync(path.dirname(probe)), link), depth + 1);
|
|
166
|
+
}
|
|
167
|
+
// One string, not one argument per name: Bun's `path.join` keeps only
|
|
168
|
+
// (argument count mod 65,536) of its arguments, so 65,536 missing names
|
|
169
|
+
// would give back `real` alone — a path the tool, whose own walk has one
|
|
170
|
+
// name more, does not act on.
|
|
171
|
+
return tail.length > 0 ? path.join(real, tail) : real;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* `target`, an absolute path, split where its deepest prefix that exists as
|
|
175
|
+
* a NAME ends: that prefix, and the names below it, which do not exist, as
|
|
176
|
+
* one string ("" when `target` itself exists). This is `path.dirname` and
|
|
177
|
+
* `path.basename` worked by index on `target` itself: handing them each
|
|
178
|
+
* shorter prefix in turn copied the rest of the path once per missing name,
|
|
179
|
+
* the square of a count the caller picks.
|
|
180
|
+
*/
|
|
181
|
+
function deepestName(target) {
|
|
182
|
+
const top = path.parse(target).root.length;
|
|
183
|
+
const isSep = (i) => target[i] === "/" || target[i] === path.sep;
|
|
184
|
+
let probe = target;
|
|
185
|
+
let start = target.length;
|
|
186
|
+
let stop = -1;
|
|
187
|
+
while (!nameExists(probe)) {
|
|
188
|
+
// `path.basename(probe)` is `target.slice(start, end)`, and
|
|
189
|
+
// `path.dirname(probe)` is `target.slice(0, up)`.
|
|
190
|
+
let end = probe.length;
|
|
191
|
+
while (end > top && isSep(end - 1))
|
|
192
|
+
end--;
|
|
193
|
+
if (stop < 0)
|
|
194
|
+
stop = end;
|
|
195
|
+
start = end;
|
|
196
|
+
while (start > top && !isSep(start - 1))
|
|
197
|
+
start--;
|
|
198
|
+
const up = start > top ? start - 1 : top;
|
|
199
|
+
if (up === probe.length)
|
|
200
|
+
break; // reached the filesystem root
|
|
201
|
+
probe = target.slice(0, up);
|
|
202
|
+
}
|
|
203
|
+
return { probe, tail: stop < 0 ? "" : target.slice(start, stop) };
|
|
204
|
+
}
|
|
205
|
+
/** Two paths that are the same directory entry: same device, same inode. */
|
|
206
|
+
function sameEntry(a, b) {
|
|
207
|
+
try {
|
|
208
|
+
const x = lstatSync(a);
|
|
209
|
+
const y = lstatSync(b);
|
|
210
|
+
return x.dev === y.dev && x.ino === y.ino;
|
|
211
|
+
}
|
|
212
|
+
catch {
|
|
213
|
+
return false;
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
/** Case and Unicode normal form folded away — how a folding filesystem compares names. */
|
|
217
|
+
function foldName(name) {
|
|
218
|
+
return name.normalize("NFC").toLowerCase();
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* How the directory `dir` stores the existing entry the caller named `name`:
|
|
222
|
+
* `[name]` when that is an entry as spelled, otherwise the entry (or, for a
|
|
223
|
+
* name with several hard links there, the entries) the filesystem resolved it
|
|
224
|
+
* to — `.env` for `.ENV` on a case-insensitive volume. `undefined` when the
|
|
225
|
+
* directory cannot be listed or no entry is that file: the caller cannot tell
|
|
226
|
+
* which name a rule should see.
|
|
227
|
+
*/
|
|
228
|
+
function storedNames(dir, name) {
|
|
229
|
+
let entries;
|
|
230
|
+
try {
|
|
231
|
+
entries = readdirSync(dir);
|
|
232
|
+
}
|
|
233
|
+
catch {
|
|
234
|
+
return undefined;
|
|
235
|
+
}
|
|
236
|
+
if (entries.includes(name))
|
|
237
|
+
return [name];
|
|
238
|
+
const at = path.join(dir, name);
|
|
239
|
+
// A folding filesystem resolves `name` to an entry that folds the same way;
|
|
240
|
+
// look at those first, and at every entry only if its folding is not ours.
|
|
241
|
+
const folded = foldName(name);
|
|
242
|
+
const likely = entries.filter((e) => foldName(e) === folded && sameEntry(path.join(dir, e), at));
|
|
243
|
+
if (likely.length > 0)
|
|
244
|
+
return likely;
|
|
245
|
+
const any = entries.filter((e) => sameEntry(path.join(dir, e), at));
|
|
246
|
+
return any.length > 0 ? any : undefined;
|
|
247
|
+
}
|
|
248
|
+
/**
|
|
249
|
+
* Does the filesystem at `dir` treat names that differ only in letter case as
|
|
250
|
+
* the same? Asked of the nearest existing directory whose own name has a
|
|
251
|
+
* letter: its name with the case swapped either finds the same directory
|
|
252
|
+
* (yes) or nothing (no). `undefined` when no such directory answers.
|
|
253
|
+
*/
|
|
254
|
+
function ignoresCase(dir) {
|
|
255
|
+
// `path.basename` and `path.dirname` worked by index on `dir`, as in
|
|
256
|
+
// `deepestName`: `dir` can end in as many missing names as a caller wrote.
|
|
257
|
+
const top = path.parse(dir).root.length;
|
|
258
|
+
const isSep = (i) => dir[i] === "/" || dir[i] === path.sep;
|
|
259
|
+
let end = dir.length;
|
|
260
|
+
for (;;) {
|
|
261
|
+
let stop = end;
|
|
262
|
+
while (stop > top && isSep(stop - 1))
|
|
263
|
+
stop--;
|
|
264
|
+
let start = stop;
|
|
265
|
+
while (start > top && !isSep(start - 1))
|
|
266
|
+
start--;
|
|
267
|
+
const probe = dir.slice(0, end);
|
|
268
|
+
const parent = dir.slice(0, start > top ? start - 1 : top);
|
|
269
|
+
const base = dir.slice(start, stop);
|
|
270
|
+
const swapped = [...base]
|
|
271
|
+
.map((c) => (c === c.toLowerCase() ? c.toUpperCase() : c.toLowerCase()))
|
|
272
|
+
.join("");
|
|
273
|
+
if (swapped !== base && nameExists(probe)) {
|
|
274
|
+
const other = path.join(parent, swapped);
|
|
275
|
+
if (!nameExists(other))
|
|
276
|
+
return false;
|
|
277
|
+
return sameEntry(probe, other);
|
|
278
|
+
}
|
|
279
|
+
if (parent.length === end)
|
|
280
|
+
return undefined;
|
|
281
|
+
end = parent.length;
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
/**
|
|
285
|
+
* The value(s) `raw` names inside the workspace at `root`. Parent
|
|
286
|
+
* directories are followed through symlinks — `build/link/app.ts` with
|
|
287
|
+
* `build/link → ../src` IS `src/app.ts` for every tool. The last component is
|
|
288
|
+
* not followed, because a tool that replaces or deletes it acts on the link
|
|
289
|
+
* itself; but it is written the way its directory stores it when it exists
|
|
290
|
+
* (`.ENV` is `.env` on macOS), and when it is a symlink, a tool that opens it
|
|
291
|
+
* acts on the target instead, so the target is a second value. An allow then
|
|
292
|
+
* has to cover both, and a deny fires on either. The name as written stays a
|
|
293
|
+
* spelling a deny also fires on.
|
|
294
|
+
*/
|
|
295
|
+
export function canonicalWorkspacePath(raw, root, rootSpellings = {}) {
|
|
296
|
+
return readWorkspacePath(raw, root, rootSpellings).values;
|
|
297
|
+
}
|
|
298
|
+
/**
|
|
299
|
+
* {@link canonicalWorkspacePath}, with the place each value stands for: the
|
|
300
|
+
* absolute location, with every symlink followed, that a value inside the
|
|
301
|
+
* workspace names in `canonical` — and that a value flagged outside does
|
|
302
|
+
* not, since a rule needs only the flag. An approval is bound to these
|
|
303
|
+
* places, and an outside place is a place an operator approved as much as an
|
|
304
|
+
* inside one.
|
|
305
|
+
*
|
|
306
|
+
* Where `realpath` cannot say where a path lands, the rule still reads only
|
|
307
|
+
* the outside flag, but the place is walked the way the file tools walk it
|
|
308
|
+
* (`physicalPath` in `@crewhaus/tool-safety/fs`, one `lstat`/`readlink` per
|
|
309
|
+
* name): a directory that can be searched but not read (mode 0300) stops
|
|
310
|
+
* `realpath` and stops listing it, and stops no tool. Only where that walk
|
|
311
|
+
* fails too (a loop of links, a directory that cannot be searched), which is
|
|
312
|
+
* where the tool cannot open the path either, is the place
|
|
313
|
+
* {@link UNRESOLVED_PLACE} followed by the path as written.
|
|
314
|
+
*/
|
|
315
|
+
function readWorkspacePath(raw, root, rootSpellings) {
|
|
316
|
+
const rootAbs = path.resolve(root);
|
|
317
|
+
let rootReal;
|
|
318
|
+
try {
|
|
319
|
+
rootReal = realpathSync(rootAbs);
|
|
320
|
+
}
|
|
321
|
+
catch {
|
|
322
|
+
rootReal = rootAbs;
|
|
323
|
+
}
|
|
324
|
+
const aliases = rootAliases(rootAbs, rootReal, rootSpellings);
|
|
325
|
+
// Lexical: `..` collapsed, symlinks untouched.
|
|
326
|
+
const lexicalAbs = path.resolve(rootAbs, raw);
|
|
327
|
+
const lexicalRel = path.relative(rootAbs, lexicalAbs);
|
|
328
|
+
const spellings = [raw, toPosix(lexicalRel === "" ? "." : lexicalRel), toPosix(lexicalAbs)];
|
|
329
|
+
const outside = {
|
|
330
|
+
kind: "path",
|
|
331
|
+
canonical: [],
|
|
332
|
+
spellings,
|
|
333
|
+
outsideWorkspace: true,
|
|
334
|
+
};
|
|
335
|
+
const asWritten = toPosix(path.resolve(rootReal, lexicalRel));
|
|
336
|
+
const unresolved = `${UNRESOLVED_PLACE}${toPosix(lexicalAbs)}`;
|
|
337
|
+
const known = { lexical: rootAbs, physical: rootReal };
|
|
338
|
+
/** Where `abs` lands, walked as the tools walk it; `undefined` where they could not open it. */
|
|
339
|
+
const walked = (abs) => {
|
|
340
|
+
try {
|
|
341
|
+
return toPosix(physicalPath(abs, { known }));
|
|
342
|
+
}
|
|
343
|
+
catch {
|
|
344
|
+
return undefined;
|
|
345
|
+
}
|
|
346
|
+
};
|
|
347
|
+
/**
|
|
348
|
+
* The entry `name` in the directory that really holds it, and where it
|
|
349
|
+
* leads when it is a symlink: the places the normal reading below gives a
|
|
350
|
+
* rule, for a directory it could not read.
|
|
351
|
+
*/
|
|
352
|
+
const entryPlaces = (dir, name) => {
|
|
353
|
+
const at = path.join(dir, name);
|
|
354
|
+
if (!isSymlink(at))
|
|
355
|
+
return [toPosix(at)];
|
|
356
|
+
const target = walked(at);
|
|
357
|
+
if (target === undefined)
|
|
358
|
+
return [toPosix(at), unresolved];
|
|
359
|
+
return target === toPosix(at) ? [toPosix(at)] : [toPosix(at), target];
|
|
360
|
+
};
|
|
361
|
+
/** The places of `lexicalAbs` where its directory could not be read. */
|
|
362
|
+
const placesByWalk = () => {
|
|
363
|
+
const dir = walked(path.dirname(lexicalAbs));
|
|
364
|
+
return dir === undefined ? [unresolved] : entryPlaces(dir, path.basename(lexicalAbs));
|
|
365
|
+
};
|
|
366
|
+
const read = (values, places) => {
|
|
367
|
+
let known = typeof places === "function" ? undefined : places;
|
|
368
|
+
return {
|
|
369
|
+
values,
|
|
370
|
+
places: () => {
|
|
371
|
+
known ??= places();
|
|
372
|
+
return known;
|
|
373
|
+
},
|
|
374
|
+
asWritten,
|
|
375
|
+
};
|
|
376
|
+
};
|
|
377
|
+
let caseInsensitive = true;
|
|
378
|
+
const located = (real) => {
|
|
379
|
+
const rel = path.relative(rootReal, real);
|
|
380
|
+
if (climbsOut(rel))
|
|
381
|
+
return outside;
|
|
382
|
+
const relPosix = rel === "" ? "." : toPosix(rel);
|
|
383
|
+
const underAliases = aliases.map((a) => toPosix(rel === "" ? a : path.join(a, rel)));
|
|
384
|
+
return {
|
|
385
|
+
kind: "path",
|
|
386
|
+
canonical: relPosix === "." ? [".", toPosix(real)] : [relPosix, `./${relPosix}`, toPosix(real)],
|
|
387
|
+
spellings: underAliases.length === 0 ? spellings : [...spellings, ...underAliases],
|
|
388
|
+
...(caseInsensitive ? { caseInsensitive: true } : {}),
|
|
389
|
+
// A tool that walks a directory (`beneath`) acts on nothing beneath a
|
|
390
|
+
// file, so a deny naming something under this name cannot concern it.
|
|
391
|
+
...(isNonDirectory(real) ? { notDirectory: true } : {}),
|
|
392
|
+
};
|
|
393
|
+
};
|
|
394
|
+
if (climbsOut(lexicalRel)) {
|
|
395
|
+
// A rule needs only the flag. The place is walked for only when an
|
|
396
|
+
// approval asks, so a grant made for one place outside is not spent on
|
|
397
|
+
// another — and walked in one pass over the path: `resolveLocation`
|
|
398
|
+
// hands the rest of the path to dirname and basename once per missing
|
|
399
|
+
// name, the square of a length the model chooses.
|
|
400
|
+
return read([outside], () => [walked(lexicalAbs) ?? unresolved]);
|
|
401
|
+
}
|
|
402
|
+
// Longer than any path can be: no tool acts on it, and it is not walked.
|
|
403
|
+
if (lexicalAbs.length > MAX_PATH_CHARS)
|
|
404
|
+
return read([outside], [unresolved]);
|
|
405
|
+
if (lexicalAbs === rootAbs) {
|
|
406
|
+
caseInsensitive = ignoresCase(rootReal) !== false;
|
|
407
|
+
return read([located(rootReal)], [toPosix(rootReal)]);
|
|
408
|
+
}
|
|
409
|
+
let parent;
|
|
410
|
+
try {
|
|
411
|
+
parent = resolveLocation(path.dirname(lexicalAbs));
|
|
412
|
+
}
|
|
413
|
+
catch {
|
|
414
|
+
// Where it lands cannot be worked out: an allow must not guess.
|
|
415
|
+
return read([outside], placesByWalk());
|
|
416
|
+
}
|
|
417
|
+
// Unknown counts as "ignores case": that only widens what a deny or an ask
|
|
418
|
+
// catches, never what an allow grants.
|
|
419
|
+
caseInsensitive = ignoresCase(parent) !== false;
|
|
420
|
+
const leaf = path.basename(lexicalAbs);
|
|
421
|
+
let names = [leaf];
|
|
422
|
+
if (nameExists(path.join(parent, leaf))) {
|
|
423
|
+
// It exists, so the tool will open the entry the filesystem resolves the
|
|
424
|
+
// name to — which, on a filesystem that folds case or Unicode form, may
|
|
425
|
+
// be stored under another spelling. A rule sees that spelling.
|
|
426
|
+
const stored = storedNames(parent, leaf);
|
|
427
|
+
if (stored === undefined)
|
|
428
|
+
return read([outside], placesByWalk());
|
|
429
|
+
names = stored;
|
|
430
|
+
}
|
|
431
|
+
const values = [];
|
|
432
|
+
const places = [];
|
|
433
|
+
for (const name of names) {
|
|
434
|
+
const at = path.join(parent, name);
|
|
435
|
+
values.push(located(at));
|
|
436
|
+
places.push(toPosix(at));
|
|
437
|
+
if (isSymlink(at)) {
|
|
438
|
+
let target;
|
|
439
|
+
try {
|
|
440
|
+
target = resolveLocation(at);
|
|
441
|
+
}
|
|
442
|
+
catch {
|
|
443
|
+
values.push(outside);
|
|
444
|
+
places.push(walked(at) ?? unresolved);
|
|
445
|
+
continue;
|
|
446
|
+
}
|
|
447
|
+
if (target !== at) {
|
|
448
|
+
values.push(located(target));
|
|
449
|
+
places.push(toPosix(target));
|
|
450
|
+
}
|
|
451
|
+
}
|
|
452
|
+
}
|
|
453
|
+
return read(values, places);
|
|
454
|
+
}
|
|
455
|
+
/**
|
|
456
|
+
* How a place reads when even the tools' own walk cannot follow the path: a
|
|
457
|
+
* loop of links, or a directory that cannot be searched. A tool cannot open
|
|
458
|
+
* such a path either.
|
|
459
|
+
*/
|
|
460
|
+
export const UNRESOLVED_PLACE = "unresolved:";
|
|
461
|
+
function isSeparator(code) {
|
|
462
|
+
return code === 0x2f || (path.sep === "\\" && code === 0x5c);
|
|
463
|
+
}
|
|
464
|
+
/**
|
|
465
|
+
* `rel` walked from the physical directory `dir` the way the kernel walks it:
|
|
466
|
+
* `physicalPath` from a start already known to be physical, so each `..` is
|
|
467
|
+
* applied after the link before it, never folded as text first.
|
|
468
|
+
*/
|
|
469
|
+
function walkFrom(dir, rel) {
|
|
470
|
+
if (rel === "")
|
|
471
|
+
return dir;
|
|
472
|
+
const joined = dir.endsWith(path.sep) ? `${dir}${rel}` : `${dir}${path.sep}${rel}`;
|
|
473
|
+
return physicalPath(joined, { known: { lexical: dir, physical: dir } });
|
|
474
|
+
}
|
|
475
|
+
/**
|
|
476
|
+
* Where a command word that names a file lands (`ProgramPathReader` in
|
|
477
|
+
* `@crewhaus/tool-executor`): from the directory the command runs in — the
|
|
478
|
+
* tools join `runsIn` to the root as text and the kernel then follows it —
|
|
479
|
+
* each name followed the way the kernel follows it, a `..` after a link
|
|
480
|
+
* climbing out of the link's target. `link/../run.sh` with `link →
|
|
481
|
+
* secrets/deep` is `secrets/run.sh`, which `path.resolve` would fold to
|
|
482
|
+
* `run.sh` before any link was seen. The last name is kept as written; when
|
|
483
|
+
* it is a symlink, where it leads is the program the kernel runs, and a
|
|
484
|
+
* second place.
|
|
485
|
+
*/
|
|
486
|
+
function readProgramPlace(word, runsIn, rootReal, prefix, walked) {
|
|
487
|
+
const dirLexical = path.resolve(rootReal, runsIn ?? ".");
|
|
488
|
+
const lexical = path.resolve(dirLexical, prefix, word);
|
|
489
|
+
const asWritten = toPosix(lexical);
|
|
490
|
+
const unresolved = {
|
|
491
|
+
reading: undefined,
|
|
492
|
+
at: [`${UNRESOLVED_PLACE}${asWritten}`],
|
|
493
|
+
asWritten,
|
|
494
|
+
};
|
|
495
|
+
// Longer than any path can be: the kernel refuses to run it.
|
|
496
|
+
if (word.length > MAX_PATH_CHARS ||
|
|
497
|
+
dirLexical.length > MAX_PATH_CHARS ||
|
|
498
|
+
prefix.length > MAX_PATH_CHARS) {
|
|
499
|
+
return unresolved;
|
|
500
|
+
}
|
|
501
|
+
const inWorkspace = (p) => {
|
|
502
|
+
const rel = path.relative(rootReal, p);
|
|
503
|
+
return climbsOut(rel) ? undefined : rel === "" ? "." : toPosix(rel);
|
|
504
|
+
};
|
|
505
|
+
// The last name, and the directory part before it, by index.
|
|
506
|
+
let end = word.length;
|
|
507
|
+
while (end > 0 && isSeparator(word.charCodeAt(end - 1)))
|
|
508
|
+
end--;
|
|
509
|
+
let cut = end;
|
|
510
|
+
while (cut > 0 && !isSeparator(word.charCodeAt(cut - 1)))
|
|
511
|
+
cut--;
|
|
512
|
+
const leaf = word.slice(cut, end);
|
|
513
|
+
const head = word.slice(0, cut);
|
|
514
|
+
const known = { lexical: rootReal, physical: rootReal };
|
|
515
|
+
let at;
|
|
516
|
+
let target;
|
|
517
|
+
const absolute = path.isAbsolute(word);
|
|
518
|
+
// The directory a relative word is walked from: the one the command runs
|
|
519
|
+
// in, then where a wrapper moved it. Walked once per call for every word
|
|
520
|
+
// read there, so a deep directory and many words cost their sum.
|
|
521
|
+
let start;
|
|
522
|
+
if (absolute)
|
|
523
|
+
start = path.parse(word).root;
|
|
524
|
+
else {
|
|
525
|
+
const key = `${dirLexical}\u0000${prefix}`;
|
|
526
|
+
let dir = walked.get(key);
|
|
527
|
+
if (dir === undefined) {
|
|
528
|
+
try {
|
|
529
|
+
const base = physicalPath(dirLexical, { known });
|
|
530
|
+
dir =
|
|
531
|
+
prefix === ""
|
|
532
|
+
? base
|
|
533
|
+
: path.isAbsolute(prefix)
|
|
534
|
+
? physicalPath(prefix, { known })
|
|
535
|
+
: walkFrom(base, prefix);
|
|
536
|
+
}
|
|
537
|
+
catch {
|
|
538
|
+
dir = null;
|
|
539
|
+
}
|
|
540
|
+
walked.set(key, dir);
|
|
541
|
+
}
|
|
542
|
+
if (dir === null)
|
|
543
|
+
return unresolved;
|
|
544
|
+
start = dir;
|
|
545
|
+
}
|
|
546
|
+
try {
|
|
547
|
+
const from = (rel) => absolute ? physicalPath(`${start}${rel}`, { known }) : walkFrom(start, rel);
|
|
548
|
+
const relHead = absolute ? head.slice(start.length) : head;
|
|
549
|
+
if (leaf === "" || leaf === "." || leaf === "..") {
|
|
550
|
+
at = from(absolute ? word.slice(start.length) : word);
|
|
551
|
+
}
|
|
552
|
+
else {
|
|
553
|
+
const parent = from(relHead);
|
|
554
|
+
at = path.join(parent, leaf);
|
|
555
|
+
if (isSymlink(at)) {
|
|
556
|
+
const led = walkFrom(parent, leaf);
|
|
557
|
+
if (led !== at)
|
|
558
|
+
target = led;
|
|
559
|
+
}
|
|
560
|
+
}
|
|
561
|
+
}
|
|
562
|
+
catch {
|
|
563
|
+
return unresolved;
|
|
564
|
+
}
|
|
565
|
+
const atInWorkspace = inWorkspace(at);
|
|
566
|
+
const targetInWorkspace = target !== undefined ? inWorkspace(target) : undefined;
|
|
567
|
+
const reading = {
|
|
568
|
+
at: toPosix(at),
|
|
569
|
+
...(atInWorkspace !== undefined ? { inWorkspace: atInWorkspace } : {}),
|
|
570
|
+
asWritten,
|
|
571
|
+
writtenInWorkspace: inWorkspace(lexical) !== undefined,
|
|
572
|
+
...(target !== undefined
|
|
573
|
+
? {
|
|
574
|
+
target: {
|
|
575
|
+
at: toPosix(target),
|
|
576
|
+
...(targetInWorkspace !== undefined ? { inWorkspace: targetInWorkspace } : {}),
|
|
577
|
+
},
|
|
578
|
+
}
|
|
579
|
+
: {}),
|
|
580
|
+
};
|
|
581
|
+
return {
|
|
582
|
+
reading,
|
|
583
|
+
at: target !== undefined ? [toPosix(at), toPosix(target)] : [toPosix(at)],
|
|
584
|
+
asWritten,
|
|
585
|
+
};
|
|
586
|
+
}
|
|
587
|
+
/** `text` without its trailing separators, in one pass from the end. */
|
|
588
|
+
function withoutTrailingSeparators(text) {
|
|
589
|
+
let end = text.length;
|
|
590
|
+
while (end > 0 && isSeparator(text.charCodeAt(end - 1)))
|
|
591
|
+
end--;
|
|
592
|
+
return text.slice(0, end);
|
|
593
|
+
}
|
|
594
|
+
/**
|
|
595
|
+
* The gate's canonicaliser, keeping a record of every path it read and where
|
|
596
|
+
* each one lands — absolute, every symlink followed, one place per value it
|
|
597
|
+
* gave a rule (the entry itself and, when that is a symlink, its target),
|
|
598
|
+
* inside or outside the workspace alike. That record is what a headless
|
|
599
|
+
* approval is bound to (`landsWhereApproved` in this package). Paths a call names through a directory field (a
|
|
600
|
+
* command's `cwd`, a PATH entry it sets) are read through it too, and so is
|
|
601
|
+
* each command word that names a file — the program run by its path, the
|
|
602
|
+
* script an interpreter is handed — through `readProgramPath`, so the record
|
|
603
|
+
* is everything on the filesystem the gate's decision rested on.
|
|
604
|
+
*/
|
|
605
|
+
export function placeRecordingCanonicalizer(root = process.cwd()) {
|
|
606
|
+
const seen = new Map();
|
|
607
|
+
const programs = new Map();
|
|
608
|
+
// The root as the kernel finds it, and each directory a word was read
|
|
609
|
+
// from, walked once (see readProgramPlace).
|
|
610
|
+
let rootReal;
|
|
611
|
+
const realRoot = () => {
|
|
612
|
+
if (rootReal === undefined) {
|
|
613
|
+
const rootAbs = path.resolve(root);
|
|
614
|
+
try {
|
|
615
|
+
rootReal = realpathSync(rootAbs);
|
|
616
|
+
}
|
|
617
|
+
catch {
|
|
618
|
+
rootReal = rootAbs;
|
|
619
|
+
}
|
|
620
|
+
}
|
|
621
|
+
return rootReal;
|
|
622
|
+
};
|
|
623
|
+
const walked = new Map();
|
|
624
|
+
const byKey = (entries) => [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
|
|
625
|
+
return {
|
|
626
|
+
canonicalizePath: (raw) => {
|
|
627
|
+
const reading = readWorkspacePath(raw, root, {});
|
|
628
|
+
seen.set(raw, reading);
|
|
629
|
+
return reading.values;
|
|
630
|
+
},
|
|
631
|
+
readProgramPath: (word, runsIn, opts) => {
|
|
632
|
+
const prefix = opts?.prefix ?? "";
|
|
633
|
+
const place = readProgramPlace(word, runsIn, realRoot(), prefix, walked);
|
|
634
|
+
// A bare word an interpreter is handed may be a subcommand or a module
|
|
635
|
+
// (`bun run build`, `python -m pytest`): it is a place only where it
|
|
636
|
+
// names an entry, or a card would list files that are not there.
|
|
637
|
+
const separated = word.includes("/") || (path.sep === "\\" && word.includes("\\"));
|
|
638
|
+
if (!separated && place.reading !== undefined && !nameExists(place.reading.at)) {
|
|
639
|
+
return place.reading;
|
|
640
|
+
}
|
|
641
|
+
// An argument (or a candidate on a PATH the call sets) is a place only
|
|
642
|
+
// where it lands elsewhere than it reads, or is a link: anywhere else
|
|
643
|
+
// its text says where it lands, and it would only crowd the card. A
|
|
644
|
+
// grant is still bound to it, since a link moving in or out of its way
|
|
645
|
+
// adds or drops it. One that cannot be walked (text longer than any
|
|
646
|
+
// path, a loop of links) is no file the call names.
|
|
647
|
+
const onItsFace = place.at.length === 1 && place.at[0] === place.asWritten;
|
|
648
|
+
if (opts?.argument === true && (onItsFace || place.reading === undefined)) {
|
|
649
|
+
return place.reading;
|
|
650
|
+
}
|
|
651
|
+
const dir = [runsIn, prefix]
|
|
652
|
+
.map((d) => (d !== undefined ? withoutTrailingSeparators(d) : ""))
|
|
653
|
+
.filter((d) => d !== "" && d !== ".")
|
|
654
|
+
.join("/");
|
|
655
|
+
const key = dir === "" || path.isAbsolute(word) ? word : `${dir}/${word}`;
|
|
656
|
+
programs.set(key, place);
|
|
657
|
+
return place.reading;
|
|
658
|
+
},
|
|
659
|
+
places: () => [
|
|
660
|
+
...byKey(seen.entries()).map(([p, r]) => ({ path: p, at: [...r.places()] })),
|
|
661
|
+
...byKey(programs.entries()).map(([p, r]) => ({ path: p, at: [...r.at] })),
|
|
662
|
+
],
|
|
663
|
+
allAsWritten: () => [...seen.values()].every((r) => {
|
|
664
|
+
const at = r.places();
|
|
665
|
+
return at.length === 1 && at[0] === r.asWritten;
|
|
666
|
+
}) && [...programs.values()].every((r) => r.at.length === 1 && r.at[0] === r.asWritten),
|
|
667
|
+
};
|
|
668
|
+
}
|
|
669
|
+
/**
|
|
670
|
+
* The canonicaliser the permission gate hands `preparePermissionSubject`:
|
|
671
|
+
* paths resolved against `root` — by default the current working directory,
|
|
672
|
+
* which is the root every workspace tool resolves against at call time.
|
|
673
|
+
*/
|
|
674
|
+
export function workspacePathCanonicalizer(root = process.cwd()) {
|
|
675
|
+
return (raw) => canonicalWorkspacePath(raw, root);
|
|
676
|
+
}
|
package/dist/pre-route.d.ts
CHANGED
|
@@ -31,11 +31,13 @@
|
|
|
31
31
|
* reason `classifier failed`;
|
|
32
32
|
* 6. otherwise the hint only carries `eligible[]` and the policy decides.
|
|
33
33
|
*
|
|
34
|
-
* Also here: the SYNTHETIC-message marker. runtime-core pushes
|
|
34
|
+
* Also here: the SYNTHETIC-message marker. runtime-core pushes six kinds of
|
|
35
35
|
* non-human `role: "user"` messages onto the transcript (the grader-rationale
|
|
36
36
|
* correction, the continue nudge, the tombstone retry, loop-detection
|
|
37
|
-
* notices, the resume/toolset marker
|
|
38
|
-
*
|
|
37
|
+
* notices, the resume/toolset marker, and autocompact's summary marker and
|
|
38
|
+
* continuation notice); the first five are `synthetic: true` in the event
|
|
39
|
+
* log (compaction output is never logged as a user message), and all are
|
|
40
|
+
* marked in memory here so `latestHumanUserMessage` — the
|
|
39
41
|
* text the rules and the classifier read — never sees them (a `/model fast`
|
|
40
42
|
* echoed inside a judge's rationale must not steer routing, §7.2.1).
|
|
41
43
|
* Directives themselves are parsed at the typed INPUT seams (the REPL input,
|