@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.
@@ -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
+ }