@crewhaus/tool-fleet 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +247 -0
- package/dist/index.d.ts +81 -0
- package/dist/index.js +1449 -0
- package/dist/lib/bundle.d.ts +131 -0
- package/dist/lib/bundle.js +330 -0
- package/dist/lib/jobs.d.ts +54 -0
- package/dist/lib/jobs.js +134 -0
- package/dist/lib/registry.d.ts +46 -0
- package/dist/lib/registry.js +145 -0
- package/dist/lib/result.d.ts +117 -0
- package/dist/lib/result.js +228 -0
- package/dist/lib/roots.d.ts +18 -0
- package/dist/lib/roots.js +51 -0
- package/dist/lib/settings.d.ts +97 -0
- package/dist/lib/settings.js +280 -0
- package/dist/paths.d.ts +42 -0
- package/dist/paths.js +158 -0
- package/package.json +48 -0
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { HangarHarnessEntry } from "@crewhaus/harness-registry";
|
|
2
|
+
import { type Loaded } from "./result";
|
|
3
|
+
/** The condition of `harnesses.json` itself. */
|
|
4
|
+
export type RegistryFileState = "absent" | "ok" | "unparseable" | "not-a-file" | "unreadable";
|
|
5
|
+
export type RegistryFileProbe = {
|
|
6
|
+
readonly state: RegistryFileState;
|
|
7
|
+
/** Absolute path, always reported so a reader knows which file answered. */
|
|
8
|
+
readonly path: string;
|
|
9
|
+
/** Present for every state except `ok`/`absent`. */
|
|
10
|
+
readonly detail?: string;
|
|
11
|
+
/** Rows the raw document carries, when it parsed. Independent of the
|
|
12
|
+
* normalized view, so "the file has 11 rows but the API returned 0" is
|
|
13
|
+
* visible instead of invisible. */
|
|
14
|
+
readonly rawHarnessCount?: number;
|
|
15
|
+
};
|
|
16
|
+
/**
|
|
17
|
+
* What condition the registry file is in — READ ONLY, and never healed.
|
|
18
|
+
*
|
|
19
|
+
* Deliberately NOT a `JSON.parse` wrapped in a shrug: each failure mode gets
|
|
20
|
+
* its own state, because the remedies differ (restore a backup, fix a
|
|
21
|
+
* permission, delete a stray directory) and because "absent" is the only one
|
|
22
|
+
* a mutation may proceed through.
|
|
23
|
+
*/
|
|
24
|
+
export declare function probeRegistryFile(path: string): RegistryFileProbe;
|
|
25
|
+
/**
|
|
26
|
+
* Refuse a mutation the registry would answer by destroying the file.
|
|
27
|
+
*
|
|
28
|
+
* `absent` and `ok` are the two states a write may proceed through. Every
|
|
29
|
+
* other one means the next `writeDoc` would replace a file this tool could
|
|
30
|
+
* not read with one built from `EMPTY_DOC`.
|
|
31
|
+
*/
|
|
32
|
+
export declare function mutationBlockedBy(probe: RegistryFileProbe): Loaded<undefined>;
|
|
33
|
+
/** The entry fields a result carries, in a stable order. */
|
|
34
|
+
export type EntryView = Record<string, unknown>;
|
|
35
|
+
/**
|
|
36
|
+
* One registry row, shaped for a result.
|
|
37
|
+
*
|
|
38
|
+
* `dir` is reported as the registry holds it — absolute, and possibly
|
|
39
|
+
* outside this workspace, because the registry is machine-wide. `inWorkspace`
|
|
40
|
+
* says which, and it is the flag every caller of this module keys on before
|
|
41
|
+
* doing any I/O of its own on that directory: a path a STORE handed back is
|
|
42
|
+
* not a path a caller passed containment for.
|
|
43
|
+
*/
|
|
44
|
+
export declare function entryView(entry: HangarHarnessEntry, workspaceRoot: string): EntryView;
|
|
45
|
+
/** Registry rows in a stable order — by dir, with plain string comparison. */
|
|
46
|
+
export declare function sortEntries(entries: readonly HangarHarnessEntry[]): HangarHarnessEntry[];
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading the registry FILE's condition, which the registry API cannot tell
|
|
3
|
+
* you, and shaping an entry for a result.
|
|
4
|
+
*
|
|
5
|
+
* `openHangarRegistry` is the only thing in this package that ever WRITES
|
|
6
|
+
* `harnesses.json`: it owns the atomic tmp+rename, the 0600 mode and the
|
|
7
|
+
* fingerprint-checked read-merge-write retry that keeps two sessions and a
|
|
8
|
+
* running manager from losing each other's rows. Nothing here reimplements
|
|
9
|
+
* any of that, and nothing here opens the file for writing.
|
|
10
|
+
*
|
|
11
|
+
* What it does do is READ the file once, before a mutation, because the
|
|
12
|
+
* registry's own reader cannot report what this package has to report:
|
|
13
|
+
*
|
|
14
|
+
* ```js
|
|
15
|
+
* try { parsed = JSON.parse(readFileSync(path, "utf8")); … }
|
|
16
|
+
* catch { parsed = undefined; } // registry.ts, read()
|
|
17
|
+
* … healable ? normalizeDoc(…) : { doc: EMPTY_DOC, … }
|
|
18
|
+
* ```
|
|
19
|
+
*
|
|
20
|
+
* A registry that could not be parsed therefore reads as an EMPTY registry,
|
|
21
|
+
* and the next write persists that empty document over the file — the
|
|
22
|
+
* package's own comment calls this "healed wholesale by the next write". For
|
|
23
|
+
* a boot hook that is the right posture. For a tool that is about to add,
|
|
24
|
+
* remove or relocate a row it is the worst possible one: the operator asked
|
|
25
|
+
* to move one harness and every other row, every group, every tag and every
|
|
26
|
+
* note in a hand-recoverable file is gone. So a mutation against a registry
|
|
27
|
+
* whose file exists but did not parse is REFUSED here, and a listing says
|
|
28
|
+
* `unparseable` rather than reporting zero harnesses.
|
|
29
|
+
*/
|
|
30
|
+
import { readFileSync } from "node:fs";
|
|
31
|
+
import { compareStrings, fail, isInside, probeName, renderStorePath, renderText, } from "./result";
|
|
32
|
+
/** Longest registry file this tool will read for its integrity probe. */
|
|
33
|
+
const MAX_REGISTRY_BYTES = 32 * 1024 * 1024;
|
|
34
|
+
/**
|
|
35
|
+
* What condition the registry file is in — READ ONLY, and never healed.
|
|
36
|
+
*
|
|
37
|
+
* Deliberately NOT a `JSON.parse` wrapped in a shrug: each failure mode gets
|
|
38
|
+
* its own state, because the remedies differ (restore a backup, fix a
|
|
39
|
+
* permission, delete a stray directory) and because "absent" is the only one
|
|
40
|
+
* a mutation may proceed through.
|
|
41
|
+
*/
|
|
42
|
+
export function probeRegistryFile(path) {
|
|
43
|
+
const kind = probeName(path, path);
|
|
44
|
+
if (!kind.ok)
|
|
45
|
+
return { state: "unreadable", path, detail: kind.reason };
|
|
46
|
+
if (kind.value === undefined)
|
|
47
|
+
return { state: "absent", path };
|
|
48
|
+
if (kind.value === "directory" || kind.value === "other") {
|
|
49
|
+
return {
|
|
50
|
+
state: "not-a-file",
|
|
51
|
+
path,
|
|
52
|
+
detail: `the registry path is a ${kind.value}, not a file`,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
let text;
|
|
56
|
+
try {
|
|
57
|
+
text = readFileSync(path, "utf8");
|
|
58
|
+
}
|
|
59
|
+
catch (err) {
|
|
60
|
+
const code = err.code;
|
|
61
|
+
return { state: "unreadable", path, detail: `could not be read (${code ?? "unknown error"})` };
|
|
62
|
+
}
|
|
63
|
+
if (text.length > MAX_REGISTRY_BYTES) {
|
|
64
|
+
return { state: "unreadable", path, detail: `larger than ${MAX_REGISTRY_BYTES} bytes` };
|
|
65
|
+
}
|
|
66
|
+
let parsed;
|
|
67
|
+
try {
|
|
68
|
+
parsed = JSON.parse(text);
|
|
69
|
+
}
|
|
70
|
+
catch (err) {
|
|
71
|
+
return {
|
|
72
|
+
state: "unparseable",
|
|
73
|
+
path,
|
|
74
|
+
detail: `not valid JSON (${err instanceof Error ? err.message : "parse error"})`,
|
|
75
|
+
};
|
|
76
|
+
}
|
|
77
|
+
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
|
|
78
|
+
return { state: "unparseable", path, detail: "the document is not a JSON object" };
|
|
79
|
+
}
|
|
80
|
+
const harnesses = parsed["harnesses"];
|
|
81
|
+
return {
|
|
82
|
+
state: "ok",
|
|
83
|
+
path,
|
|
84
|
+
...(Array.isArray(harnesses) ? { rawHarnessCount: harnesses.length } : {}),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Refuse a mutation the registry would answer by destroying the file.
|
|
89
|
+
*
|
|
90
|
+
* `absent` and `ok` are the two states a write may proceed through. Every
|
|
91
|
+
* other one means the next `writeDoc` would replace a file this tool could
|
|
92
|
+
* not read with one built from `EMPTY_DOC`.
|
|
93
|
+
*/
|
|
94
|
+
export function mutationBlockedBy(probe) {
|
|
95
|
+
if (probe.state === "ok" || probe.state === "absent")
|
|
96
|
+
return { ok: true, value: undefined };
|
|
97
|
+
const shared = "@crewhaus/harness-registry reads an unusable registry as an EMPTY one and heals it on the next write, so proceeding would replace every row, group, tag and note in that file with an empty document. A registry that could not be read is not an empty registry.";
|
|
98
|
+
return fail(probe.state === "unreadable" || probe.state === "not-a-file" ? "unreadable" : "refused", `${probe.path}: ${probe.detail ?? probe.state}. ${shared}`);
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* One registry row, shaped for a result.
|
|
102
|
+
*
|
|
103
|
+
* `dir` is reported as the registry holds it — absolute, and possibly
|
|
104
|
+
* outside this workspace, because the registry is machine-wide. `inWorkspace`
|
|
105
|
+
* says which, and it is the flag every caller of this module keys on before
|
|
106
|
+
* doing any I/O of its own on that directory: a path a STORE handed back is
|
|
107
|
+
* not a path a caller passed containment for.
|
|
108
|
+
*/
|
|
109
|
+
export function entryView(entry, workspaceRoot) {
|
|
110
|
+
// EVERY STRING HERE CAME OUT OF A SHARED FILE. `harnesses.json` is
|
|
111
|
+
// machine-wide and every crewhaus process on the box writes it, so a row's
|
|
112
|
+
// name, notes, tags and groups are text this package neither wrote nor
|
|
113
|
+
// validated — and this view is on its way into a model's context. Bounded
|
|
114
|
+
// and stripped of control characters so a row cannot spend the whole
|
|
115
|
+
// context or forge a line break out of the field it sits in. The
|
|
116
|
+
// containment decision is made on `entry.dir` itself, never on the
|
|
117
|
+
// rendered copy.
|
|
118
|
+
return {
|
|
119
|
+
id: entry.id,
|
|
120
|
+
dir: renderStorePath(entry.dir),
|
|
121
|
+
inWorkspace: isInside(workspaceRoot, entry.dir),
|
|
122
|
+
specName: renderText(entry.specName),
|
|
123
|
+
target: renderText(entry.target),
|
|
124
|
+
origin: entry.origin,
|
|
125
|
+
...(entry.originDetail !== "" ? { originDetail: renderText(entry.originDetail) } : {}),
|
|
126
|
+
kind: entry.kind,
|
|
127
|
+
groups: [...entry.groups].sort(compareStrings).map((g) => renderText(g, 100)),
|
|
128
|
+
...(entry.groupOrder !== undefined ? { groupOrder: entry.groupOrder } : {}),
|
|
129
|
+
tags: [...entry.tags].sort(compareStrings).map((t) => renderText(t, 100)),
|
|
130
|
+
pinned: entry.pinned,
|
|
131
|
+
hidden: entry.hidden,
|
|
132
|
+
...(entry.notes !== "" ? { notes: renderText(entry.notes, 1000) } : {}),
|
|
133
|
+
registeredAt: entry.registeredAt,
|
|
134
|
+
lastSeen: entry.lastSeen,
|
|
135
|
+
// `null` means the directory was there at the last listing. Reported as
|
|
136
|
+
// an explicit field either way: a vanished harness is never pruned, and
|
|
137
|
+
// an operator reading this table needs to see which rows point at
|
|
138
|
+
// nothing.
|
|
139
|
+
missingSince: entry.missingSince,
|
|
140
|
+
};
|
|
141
|
+
}
|
|
142
|
+
/** Registry rows in a stable order — by dir, with plain string comparison. */
|
|
143
|
+
export function sortEntries(entries) {
|
|
144
|
+
return [...entries].sort((a, b) => compareStrings(a.dir, b.dir) || compareStrings(a.id, b.id));
|
|
145
|
+
}
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import { type SafePath } from "../paths";
|
|
2
|
+
/** Compact JSON — the reader is a model, and every byte is context. */
|
|
3
|
+
export declare const json: (value: unknown) => string;
|
|
4
|
+
/**
|
|
5
|
+
* Text this package did not write, on its way into a model's context.
|
|
6
|
+
*
|
|
7
|
+
* Every string these tools report that they did not compute themselves came
|
|
8
|
+
* from somewhere a caller does not control and an attacker might: a spec's
|
|
9
|
+
* `name`, a bundle manifest's `compiledWith`, a row another writer put in
|
|
10
|
+
* the machine registry, a line a spawned binary printed. Each is bounded
|
|
11
|
+
* (so one of them cannot spend the whole context) and stripped of control
|
|
12
|
+
* characters (so it cannot forge a second line of output, move a terminal
|
|
13
|
+
* cursor, or end the framing of the field it sits in).
|
|
14
|
+
*
|
|
15
|
+
* This is NOT a claim that the text is trustworthy — a bounded, printable
|
|
16
|
+
* sentence can still read like an instruction. It is the part that can be
|
|
17
|
+
* done mechanically: whatever is reported stays inside the field it was put
|
|
18
|
+
* in, and stays small.
|
|
19
|
+
*/
|
|
20
|
+
export declare function renderText(given: string, limit?: number): string;
|
|
21
|
+
/** A caller-supplied string, safe to put in a message: bounded and printable. */
|
|
22
|
+
export declare function renderPath(given: string): string;
|
|
23
|
+
/** A path a STORE handed back, safe to put in a result. */
|
|
24
|
+
export declare function renderStorePath(given: string): string;
|
|
25
|
+
/**
|
|
26
|
+
* Why something could not be loaded.
|
|
27
|
+
*
|
|
28
|
+
* `missing` is the only code a caller may carry on past ("there is nothing
|
|
29
|
+
* here"); every other one is a refusal that must be returned. It is a field
|
|
30
|
+
* rather than something sniffed out of the message so that rewording a
|
|
31
|
+
* message can never silently turn a refusal into a carry-on.
|
|
32
|
+
*/
|
|
33
|
+
export type FailCode = "refused" | "missing" | "not-a-directory" | "not-a-file" | "bad-input" | "unreadable" | "conflict" | "unavailable";
|
|
34
|
+
export type Failure = {
|
|
35
|
+
readonly ok: false;
|
|
36
|
+
readonly reason: string;
|
|
37
|
+
readonly code: FailCode;
|
|
38
|
+
};
|
|
39
|
+
export type Loaded<T> = {
|
|
40
|
+
readonly ok: true;
|
|
41
|
+
readonly value: T;
|
|
42
|
+
} | Failure;
|
|
43
|
+
export declare function fail(code: FailCode, reason: string): Failure;
|
|
44
|
+
/** The JSON a tool returns when it will not proceed. */
|
|
45
|
+
export declare function refusal(tool: string, code: FailCode, reason: string, extra?: {}): string;
|
|
46
|
+
/**
|
|
47
|
+
* Resolve a caller-supplied path inside the workspace.
|
|
48
|
+
*
|
|
49
|
+
* The NUL guard is here rather than in `paths.ts` (which is a verbatim copy
|
|
50
|
+
* of `@crewhaus/tool-pkg`'s, deliberately): a NUL truncates a path at the
|
|
51
|
+
* syscall boundary, so `a\u0000/../../etc` can resolve one way in the
|
|
52
|
+
* containment check and another way in the `open` that follows. Refused at
|
|
53
|
+
* the gate instead of surfacing later as "unreadable".
|
|
54
|
+
*/
|
|
55
|
+
export declare function contain(toolName: string, rel: string): Loaded<SafePath>;
|
|
56
|
+
/** Resolve a directory that must already exist. */
|
|
57
|
+
export declare function containExistingDir(toolName: string, rel: string): Loaded<SafePath>;
|
|
58
|
+
/**
|
|
59
|
+
* Contain a path an operation will OPEN under an already-contained root.
|
|
60
|
+
*
|
|
61
|
+
* `contain` proves the DIRECTORY sits inside the workspace, with its own
|
|
62
|
+
* symlinks resolved. It says nothing about the names below it, and every
|
|
63
|
+
* file these tools read is one of those names: `<harness>/crewhaus.yaml`,
|
|
64
|
+
* `<harness>/dist/package.json`, `<harness>/.crewhaus/settings.json`. A
|
|
65
|
+
* symlink at one of them is read straight through — the spec of a harness
|
|
66
|
+
* somewhere else entirely gets parsed, and its `name` comes back as this
|
|
67
|
+
* harness's identity (and, for `HarnessRegister`, goes into the machine
|
|
68
|
+
* registry). `@crewhaus/tool-crewhaus` already refuses exactly this for
|
|
69
|
+
* `PreflightRun` and `HarnessInventory`; this is the same gate, so the two
|
|
70
|
+
* packages answer a symlinked spec the same way.
|
|
71
|
+
*
|
|
72
|
+
* The leaf goes through the SAME `resolveSafe` the root went through, never
|
|
73
|
+
* a second symlink walker. Returns the contained leaf, or the refusal.
|
|
74
|
+
*/
|
|
75
|
+
export declare function containUnder(toolName: string, root: SafePath, rel: string): Loaded<SafePath>;
|
|
76
|
+
/**
|
|
77
|
+
* Contain every path an operation will WRITE, not just the directory it was
|
|
78
|
+
* handed.
|
|
79
|
+
*
|
|
80
|
+
* `contain` resolves the ROOT through its symlinks and proves the root sits
|
|
81
|
+
* inside the workspace. It says nothing about the names BELOW it — and the
|
|
82
|
+
* write this package performs goes to one of those names:
|
|
83
|
+
* `<harness>/.crewhaus/settings.json`, plus the temp file the atomic replace
|
|
84
|
+
* renames from. A symlink sitting at one of those names sends the write to
|
|
85
|
+
* the link's target instead, and a DANGLING one is the worst case: `stat`
|
|
86
|
+
* reports it absent, so it does not even look like a conflict, while
|
|
87
|
+
* `open(…, "w")` through it CREATES the target. Validating the directory and
|
|
88
|
+
* then writing through a link underneath it is exactly the "validate one
|
|
89
|
+
* spelling, act on another" shape this repository keeps paying for — and the
|
|
90
|
+
* write here ends in a RENAME, which replaces whatever the link points at.
|
|
91
|
+
*
|
|
92
|
+
* Each write path goes through the SAME `resolveSafe` the root went through,
|
|
93
|
+
* rather than a second symlink walker written here. Returns the refusal, or
|
|
94
|
+
* `undefined` when every write path stays inside the workspace.
|
|
95
|
+
*/
|
|
96
|
+
export declare function containWritePaths(toolName: string, root: SafePath, rels: ReadonlyArray<string>): Failure | undefined;
|
|
97
|
+
/** What a NAME is, keeping "absent" and "could not tell" apart. */
|
|
98
|
+
export type NameKind = "file" | "directory" | "symlink" | "other";
|
|
99
|
+
/**
|
|
100
|
+
* Probe a path with `lstat` — the NAME itself, never what it leads to.
|
|
101
|
+
*
|
|
102
|
+
* Returned as a `Loaded` so the three answers stay three: it is there and it
|
|
103
|
+
* is a file, it is not there, or it could not be determined. A boolean
|
|
104
|
+
* `existsSync` collapses the last two, which is how an EACCES store gets
|
|
105
|
+
* reported as an empty one.
|
|
106
|
+
*/
|
|
107
|
+
export declare function probeName(shown: string, abs: string): Loaded<NameKind | undefined>;
|
|
108
|
+
/** True when `candidate` is `parent` or lives underneath it (both absolute). */
|
|
109
|
+
export declare function isInside(parent: string, candidate: string): boolean;
|
|
110
|
+
/** A bounded slice of a list, plus the full count, for a result field. */
|
|
111
|
+
export declare function sample<T>(items: ReadonlyArray<T>, limit?: number): {
|
|
112
|
+
shown: T[];
|
|
113
|
+
total: number;
|
|
114
|
+
};
|
|
115
|
+
/** Plain string order — never `localeCompare`, so a listing is the same
|
|
116
|
+
* bytes on every machine regardless of locale. */
|
|
117
|
+
export declare function compareStrings(a: string, b: string): number;
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The shared answer shapes for this package: how a caller-supplied path is
|
|
3
|
+
* echoed back, how a path argument is contained, and how a read that COULD
|
|
4
|
+
* NOT BE PERFORMED is kept apart from one that found nothing.
|
|
5
|
+
*
|
|
6
|
+
* That last distinction is the reason the `Loaded` type exists rather than a
|
|
7
|
+
* bare `T | undefined`. Every tool here reports on a store somebody else
|
|
8
|
+
* writes — the machine registry, a job ledger, a compiled bundle, a
|
|
9
|
+
* human-owned `settings.json` — and every one of those stores answers an
|
|
10
|
+
* unreadable file with an EMPTY result: `openHangarRegistry`'s reader
|
|
11
|
+
* swallows a parse error into an empty document, `createFileJobStore.read`
|
|
12
|
+
* returns `[]` for a file it could not open, `readManagerSettings` returns
|
|
13
|
+
* its defaults for a file that is not JSON. Each is the right posture for a
|
|
14
|
+
* boot path that must not die on a typo, and each is a LIE in a report: "no
|
|
15
|
+
* harnesses registered" and "the registry could not be read" are different
|
|
16
|
+
* answers, and only one of them means the fleet is empty.
|
|
17
|
+
*
|
|
18
|
+
* So the tools probe the file themselves before concluding anything from an
|
|
19
|
+
* empty result, and the probe's failure has its own code and its own reason
|
|
20
|
+
* here, which never collapses into `[]`.
|
|
21
|
+
*/
|
|
22
|
+
import { lstatSync, statSync } from "node:fs";
|
|
23
|
+
import * as path from "node:path";
|
|
24
|
+
import { ToolPermissionError, resolveSafe } from "../paths";
|
|
25
|
+
/** Compact JSON — the reader is a model, and every byte is context. */
|
|
26
|
+
export const json = (value) => JSON.stringify(value);
|
|
27
|
+
/**
|
|
28
|
+
* How much of a caller-supplied string is echoed back in a message.
|
|
29
|
+
*
|
|
30
|
+
* The message goes into a model's context, so a caller cannot be allowed to
|
|
31
|
+
* spend that context with a megabyte of path, and cannot be allowed to
|
|
32
|
+
* smuggle control characters (a NUL, an ANSI escape, a newline that forges a
|
|
33
|
+
* second line of output) through a string a human or a model then reads.
|
|
34
|
+
*/
|
|
35
|
+
const MAX_ECHOED_CHARS = 200;
|
|
36
|
+
/**
|
|
37
|
+
* How much of a PATH a store handed back is echoed back.
|
|
38
|
+
*
|
|
39
|
+
* Longer than a caller's own argument, because truncating an absolute path
|
|
40
|
+
* an operator has to act on (a registry row's `dir`, a resolved hook
|
|
41
|
+
* command) makes the answer useless; `PATH_MAX` is 1024 on every platform
|
|
42
|
+
* this runs on, so nothing legitimate is cut.
|
|
43
|
+
*/
|
|
44
|
+
const MAX_ECHOED_STORE_PATH_CHARS = 1024;
|
|
45
|
+
/**
|
|
46
|
+
* Text this package did not write, on its way into a model's context.
|
|
47
|
+
*
|
|
48
|
+
* Every string these tools report that they did not compute themselves came
|
|
49
|
+
* from somewhere a caller does not control and an attacker might: a spec's
|
|
50
|
+
* `name`, a bundle manifest's `compiledWith`, a row another writer put in
|
|
51
|
+
* the machine registry, a line a spawned binary printed. Each is bounded
|
|
52
|
+
* (so one of them cannot spend the whole context) and stripped of control
|
|
53
|
+
* characters (so it cannot forge a second line of output, move a terminal
|
|
54
|
+
* cursor, or end the framing of the field it sits in).
|
|
55
|
+
*
|
|
56
|
+
* This is NOT a claim that the text is trustworthy — a bounded, printable
|
|
57
|
+
* sentence can still read like an instruction. It is the part that can be
|
|
58
|
+
* done mechanically: whatever is reported stays inside the field it was put
|
|
59
|
+
* in, and stays small.
|
|
60
|
+
*/
|
|
61
|
+
export function renderText(given, limit = MAX_ECHOED_CHARS) {
|
|
62
|
+
// biome-ignore lint/suspicious/noControlCharactersInRegex: neutralising control characters is the point
|
|
63
|
+
const printable = given.replace(/[\u0000-\u001f\u007f]/g, "\uFFFD");
|
|
64
|
+
return printable.length > limit ? `${printable.slice(0, limit)}…` : printable;
|
|
65
|
+
}
|
|
66
|
+
/** A caller-supplied string, safe to put in a message: bounded and printable. */
|
|
67
|
+
export function renderPath(given) {
|
|
68
|
+
return renderText(given, MAX_ECHOED_CHARS);
|
|
69
|
+
}
|
|
70
|
+
/** A path a STORE handed back, safe to put in a result. */
|
|
71
|
+
export function renderStorePath(given) {
|
|
72
|
+
return renderText(given, MAX_ECHOED_STORE_PATH_CHARS);
|
|
73
|
+
}
|
|
74
|
+
export function fail(code, reason) {
|
|
75
|
+
return { ok: false, reason, code };
|
|
76
|
+
}
|
|
77
|
+
/** The JSON a tool returns when it will not proceed. */
|
|
78
|
+
export function refusal(tool, code, reason, extra = {}) {
|
|
79
|
+
return json({ tool, status: "refused", code, reason, ...extra });
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Resolve a caller-supplied path inside the workspace.
|
|
83
|
+
*
|
|
84
|
+
* The NUL guard is here rather than in `paths.ts` (which is a verbatim copy
|
|
85
|
+
* of `@crewhaus/tool-pkg`'s, deliberately): a NUL truncates a path at the
|
|
86
|
+
* syscall boundary, so `a\u0000/../../etc` can resolve one way in the
|
|
87
|
+
* containment check and another way in the `open` that follows. Refused at
|
|
88
|
+
* the gate instead of surfacing later as "unreadable".
|
|
89
|
+
*/
|
|
90
|
+
export function contain(toolName, rel) {
|
|
91
|
+
if (rel.includes("\u0000")) {
|
|
92
|
+
return fail("refused", `"${renderPath(rel)}" contains a NUL byte`);
|
|
93
|
+
}
|
|
94
|
+
try {
|
|
95
|
+
return { ok: true, value: resolveSafe(toolName, rel) };
|
|
96
|
+
}
|
|
97
|
+
catch (err) {
|
|
98
|
+
if (err instanceof ToolPermissionError) {
|
|
99
|
+
// The error's own message carries the path unrendered; rebuild it so a
|
|
100
|
+
// control character in the caller's input cannot reach the output.
|
|
101
|
+
return fail("refused", `tool "${toolName}" rejected path "${renderPath(rel)}": resolved location escapes the workspace root`);
|
|
102
|
+
}
|
|
103
|
+
throw err;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
/** Resolve a directory that must already exist. */
|
|
107
|
+
export function containExistingDir(toolName, rel) {
|
|
108
|
+
const safe = contain(toolName, rel);
|
|
109
|
+
if (!safe.ok)
|
|
110
|
+
return safe;
|
|
111
|
+
const shown = renderPath(rel);
|
|
112
|
+
let stat;
|
|
113
|
+
try {
|
|
114
|
+
stat = statSync(safe.value.real);
|
|
115
|
+
}
|
|
116
|
+
catch (err) {
|
|
117
|
+
const code = err.code;
|
|
118
|
+
// ENOENT is "there is nothing here"; EACCES/ELOOP/anything else is "this
|
|
119
|
+
// could not be read", which is a different answer and must not be
|
|
120
|
+
// reported as absence.
|
|
121
|
+
return code === "ENOENT"
|
|
122
|
+
? fail("missing", `"${shown}" does not exist`)
|
|
123
|
+
: fail("unreadable", `"${shown}" could not be read (${code ?? "unknown error"})`);
|
|
124
|
+
}
|
|
125
|
+
if (!stat.isDirectory())
|
|
126
|
+
return fail("not-a-directory", `"${shown}" is not a directory`);
|
|
127
|
+
return safe;
|
|
128
|
+
}
|
|
129
|
+
/** A leaf's path as the workspace root sees it. One spelling, so the write
|
|
130
|
+
* gate and the read gate walk the same symlinks. */
|
|
131
|
+
function underRel(root, rel) {
|
|
132
|
+
return root.rel === "" ? rel : `${root.rel}/${rel}`;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Contain a path an operation will OPEN under an already-contained root.
|
|
136
|
+
*
|
|
137
|
+
* `contain` proves the DIRECTORY sits inside the workspace, with its own
|
|
138
|
+
* symlinks resolved. It says nothing about the names below it, and every
|
|
139
|
+
* file these tools read is one of those names: `<harness>/crewhaus.yaml`,
|
|
140
|
+
* `<harness>/dist/package.json`, `<harness>/.crewhaus/settings.json`. A
|
|
141
|
+
* symlink at one of them is read straight through — the spec of a harness
|
|
142
|
+
* somewhere else entirely gets parsed, and its `name` comes back as this
|
|
143
|
+
* harness's identity (and, for `HarnessRegister`, goes into the machine
|
|
144
|
+
* registry). `@crewhaus/tool-crewhaus` already refuses exactly this for
|
|
145
|
+
* `PreflightRun` and `HarnessInventory`; this is the same gate, so the two
|
|
146
|
+
* packages answer a symlinked spec the same way.
|
|
147
|
+
*
|
|
148
|
+
* The leaf goes through the SAME `resolveSafe` the root went through, never
|
|
149
|
+
* a second symlink walker. Returns the contained leaf, or the refusal.
|
|
150
|
+
*/
|
|
151
|
+
export function containUnder(toolName, root, rel) {
|
|
152
|
+
const safe = contain(toolName, underRel(root, rel));
|
|
153
|
+
if (safe.ok)
|
|
154
|
+
return safe;
|
|
155
|
+
const shownRoot = root.rel === "" ? "." : root.rel;
|
|
156
|
+
return fail("refused", `"${renderPath(rel)}" under "${renderPath(shownRoot)}" resolves outside the workspace root — a symlink on that path leads out, so this call would open, and a recompile would WRITE, a location the workspace does not contain, and report it as this harness's own. Remove the link and run again; there is no flag for following it.`);
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Contain every path an operation will WRITE, not just the directory it was
|
|
160
|
+
* handed.
|
|
161
|
+
*
|
|
162
|
+
* `contain` resolves the ROOT through its symlinks and proves the root sits
|
|
163
|
+
* inside the workspace. It says nothing about the names BELOW it — and the
|
|
164
|
+
* write this package performs goes to one of those names:
|
|
165
|
+
* `<harness>/.crewhaus/settings.json`, plus the temp file the atomic replace
|
|
166
|
+
* renames from. A symlink sitting at one of those names sends the write to
|
|
167
|
+
* the link's target instead, and a DANGLING one is the worst case: `stat`
|
|
168
|
+
* reports it absent, so it does not even look like a conflict, while
|
|
169
|
+
* `open(…, "w")` through it CREATES the target. Validating the directory and
|
|
170
|
+
* then writing through a link underneath it is exactly the "validate one
|
|
171
|
+
* spelling, act on another" shape this repository keeps paying for — and the
|
|
172
|
+
* write here ends in a RENAME, which replaces whatever the link points at.
|
|
173
|
+
*
|
|
174
|
+
* Each write path goes through the SAME `resolveSafe` the root went through,
|
|
175
|
+
* rather than a second symlink walker written here. Returns the refusal, or
|
|
176
|
+
* `undefined` when every write path stays inside the workspace.
|
|
177
|
+
*/
|
|
178
|
+
export function containWritePaths(toolName, root, rels) {
|
|
179
|
+
const shownRoot = root.rel === "" ? "." : root.rel;
|
|
180
|
+
for (const rel of rels) {
|
|
181
|
+
if (!contain(toolName, underRel(root, rel)).ok) {
|
|
182
|
+
return fail("refused", `"${renderPath(rel)}" under "${renderPath(shownRoot)}" resolves outside the workspace root — a symlink on that path leads out, so the write would land on the link's target rather than inside "${renderPath(shownRoot)}". Remove the link and run again; there is no flag for writing through it.`);
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
return undefined;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Probe a path with `lstat` — the NAME itself, never what it leads to.
|
|
189
|
+
*
|
|
190
|
+
* Returned as a `Loaded` so the three answers stay three: it is there and it
|
|
191
|
+
* is a file, it is not there, or it could not be determined. A boolean
|
|
192
|
+
* `existsSync` collapses the last two, which is how an EACCES store gets
|
|
193
|
+
* reported as an empty one.
|
|
194
|
+
*/
|
|
195
|
+
export function probeName(shown, abs) {
|
|
196
|
+
let stat;
|
|
197
|
+
try {
|
|
198
|
+
stat = lstatSync(abs);
|
|
199
|
+
}
|
|
200
|
+
catch (err) {
|
|
201
|
+
const code = err.code;
|
|
202
|
+
return code === "ENOENT" || code === "ENOTDIR"
|
|
203
|
+
? { ok: true, value: undefined }
|
|
204
|
+
: fail("unreadable", `"${shown}" could not be read (${code ?? "unknown error"})`);
|
|
205
|
+
}
|
|
206
|
+
if (stat.isSymbolicLink())
|
|
207
|
+
return { ok: true, value: "symlink" };
|
|
208
|
+
if (stat.isDirectory())
|
|
209
|
+
return { ok: true, value: "directory" };
|
|
210
|
+
if (stat.isFile())
|
|
211
|
+
return { ok: true, value: "file" };
|
|
212
|
+
return { ok: true, value: "other" };
|
|
213
|
+
}
|
|
214
|
+
/** True when `candidate` is `parent` or lives underneath it (both absolute). */
|
|
215
|
+
export function isInside(parent, candidate) {
|
|
216
|
+
const p = path.resolve(parent);
|
|
217
|
+
const c = path.resolve(candidate);
|
|
218
|
+
return c === p || c.startsWith(`${p}${path.sep}`);
|
|
219
|
+
}
|
|
220
|
+
/** A bounded slice of a list, plus the full count, for a result field. */
|
|
221
|
+
export function sample(items, limit = 50) {
|
|
222
|
+
return { shown: items.slice(0, limit), total: items.length };
|
|
223
|
+
}
|
|
224
|
+
/** Plain string order — never `localeCompare`, so a listing is the same
|
|
225
|
+
* bytes on every machine regardless of locale. */
|
|
226
|
+
export function compareStrings(a, b) {
|
|
227
|
+
return a < b ? -1 : a > b ? 1 : 0;
|
|
228
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** `<registryRoot>/harnesses.json` — the file `openHangarRegistry` opens. */
|
|
2
|
+
export declare function registryFilePath(env?: Readonly<Record<string, string | undefined>>): string;
|
|
3
|
+
/**
|
|
4
|
+
* The hangar root: `CREWHAUS_HANGAR_ROOT`, else `<registryRoot>/hangar`.
|
|
5
|
+
*
|
|
6
|
+
* MIRRORED, not imported. `resolveHangarRoot` lives in
|
|
7
|
+
* `apps/cli/src/hangar-cmd.ts` and a package cannot depend on the app — the
|
|
8
|
+
* same reason `harness-supervisor/src/bundle-freshness.ts` mirrors the
|
|
9
|
+
* bundle manifest shape instead of importing it. The second half of the rule
|
|
10
|
+
* is not re-derived: `resolveRegistryRoot` is the registry package's own.
|
|
11
|
+
* `roots.test.ts` pins both halves, so a change in the app fails a test here
|
|
12
|
+
* rather than silently pointing this tool at a ledger nobody writes.
|
|
13
|
+
*/
|
|
14
|
+
export declare function resolveHangarRoot(env?: Readonly<Record<string, string | undefined>>): string;
|
|
15
|
+
/** The durable job ledger the manager appends to. */
|
|
16
|
+
export declare const JOB_LEDGER_FILENAME = "jobs.jsonl";
|
|
17
|
+
/** `<hangarRoot>/jobs.jsonl` — the path `createFileJobStore` is opened on. */
|
|
18
|
+
export declare function jobLedgerPath(env?: Readonly<Record<string, string | undefined>>): string;
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The two MACHINE-WIDE roots these tools read, and why neither is a caller
|
|
3
|
+
* input.
|
|
4
|
+
*
|
|
5
|
+
* A fleet tool is about the harnesses on this machine, and the two files
|
|
6
|
+
* that record them — `<registryRoot>/harnesses.json` and
|
|
7
|
+
* `<hangarRoot>/jobs.jsonl` — live outside any workspace on purpose: the
|
|
8
|
+
* registry is what makes a harness visible to a manager started from
|
|
9
|
+
* somewhere else entirely. Containing them to `process.cwd()` would mean
|
|
10
|
+
* these tools could never see the real registry; taking them as a caller
|
|
11
|
+
* argument would mean a caller could aim a 0600 write anywhere on the disk.
|
|
12
|
+
*
|
|
13
|
+
* So they are resolved from the ENVIRONMENT, by the same functions the CLI
|
|
14
|
+
* and the manager resolve them with, and no input field can move them. The
|
|
15
|
+
* tools report the absolute path they used, so a reader always knows which
|
|
16
|
+
* file an answer came from. Every path a CALLER supplies — a harness
|
|
17
|
+
* directory, a settings file — still goes through `resolveSafe` and stays
|
|
18
|
+
* inside the workspace.
|
|
19
|
+
*/
|
|
20
|
+
import { join, resolve } from "node:path";
|
|
21
|
+
import { REGISTRY_FILENAME, resolveRegistryRoot } from "@crewhaus/harness-registry";
|
|
22
|
+
/** `<registryRoot>/harnesses.json` — the file `openHangarRegistry` opens. */
|
|
23
|
+
export function registryFilePath(env = process.env) {
|
|
24
|
+
return join(resolveRegistryRoot(env), REGISTRY_FILENAME);
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* The hangar root: `CREWHAUS_HANGAR_ROOT`, else `<registryRoot>/hangar`.
|
|
28
|
+
*
|
|
29
|
+
* MIRRORED, not imported. `resolveHangarRoot` lives in
|
|
30
|
+
* `apps/cli/src/hangar-cmd.ts` and a package cannot depend on the app — the
|
|
31
|
+
* same reason `harness-supervisor/src/bundle-freshness.ts` mirrors the
|
|
32
|
+
* bundle manifest shape instead of importing it. The second half of the rule
|
|
33
|
+
* is not re-derived: `resolveRegistryRoot` is the registry package's own.
|
|
34
|
+
* `roots.test.ts` pins both halves, so a change in the app fails a test here
|
|
35
|
+
* rather than silently pointing this tool at a ledger nobody writes.
|
|
36
|
+
*/
|
|
37
|
+
export function resolveHangarRoot(env = process.env) {
|
|
38
|
+
const explicit = env["CREWHAUS_HANGAR_ROOT"];
|
|
39
|
+
// `resolve`, like the app's copy: a relative CREWHAUS_HANGAR_ROOT must
|
|
40
|
+
// become the same absolute path the manager opened, not one relative to
|
|
41
|
+
// whatever directory this tool happens to run in.
|
|
42
|
+
if (explicit !== undefined && explicit !== "")
|
|
43
|
+
return resolve(explicit);
|
|
44
|
+
return join(resolveRegistryRoot(env), "hangar");
|
|
45
|
+
}
|
|
46
|
+
/** The durable job ledger the manager appends to. */
|
|
47
|
+
export const JOB_LEDGER_FILENAME = "jobs.jsonl";
|
|
48
|
+
/** `<hangarRoot>/jobs.jsonl` — the path `createFileJobStore` is opened on. */
|
|
49
|
+
export function jobLedgerPath(env = process.env) {
|
|
50
|
+
return join(resolveHangarRoot(env), JOB_LEDGER_FILENAME);
|
|
51
|
+
}
|