@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,131 @@
|
|
|
1
|
+
import { type BundleFreshness } from "@crewhaus/harness-supervisor";
|
|
2
|
+
import type { SafePath } from "../paths";
|
|
3
|
+
import { type Loaded } from "./result";
|
|
4
|
+
export type SpecFacts = {
|
|
5
|
+
/** Absolute path of the spec file that was read. */
|
|
6
|
+
readonly specPath: string;
|
|
7
|
+
readonly name?: string;
|
|
8
|
+
/** The shape. `resolveBundle` needs it to know whether the bundle's entry
|
|
9
|
+
* is `daemon.ts` or `agent.ts`. */
|
|
10
|
+
readonly target: string;
|
|
11
|
+
};
|
|
12
|
+
/**
|
|
13
|
+
* The harness's spec file, CONTAINED.
|
|
14
|
+
*
|
|
15
|
+
* `findSpecPath` is the supervisor's own discovery (which of the two
|
|
16
|
+
* filenames, in which order) and is kept. What is added is the gate: the
|
|
17
|
+
* path it hands back is a path a STORE produced, not one a caller passed
|
|
18
|
+
* containment for, and `existsSync` follows a symlink — so
|
|
19
|
+
* `<harness>/crewhaus.yaml -> /elsewhere/secret.yaml` resolves, parses, and
|
|
20
|
+
* comes back as this harness's identity. Contained here, once, so every
|
|
21
|
+
* caller of this module gets the same answer.
|
|
22
|
+
*
|
|
23
|
+
* `{ ok: true, value: undefined }` means there is no spec — a fact, not a
|
|
24
|
+
* failure. A refusal means there is one and it leads out of the workspace.
|
|
25
|
+
*/
|
|
26
|
+
export declare function containedSpecPath(tool: string, harness: SafePath): Loaded<SafePath | undefined>;
|
|
27
|
+
/**
|
|
28
|
+
* Read a harness's spec and take its `target` from the PARSED document.
|
|
29
|
+
*
|
|
30
|
+
* Never from a line scan of the text. The supervisor picks the bundle entry
|
|
31
|
+
* file from `target`, so a target read out of a spec that does not parse
|
|
32
|
+
* would send the freshness check looking for the wrong file and report
|
|
33
|
+
* "no compiled bundle found" for a bundle that is sitting right there. A
|
|
34
|
+
* spec that will not parse is its own answer, with the parser's first issue
|
|
35
|
+
* attached.
|
|
36
|
+
*/
|
|
37
|
+
export declare function readSpecFacts(tool: string, harness: SafePath): Loaded<SpecFacts>;
|
|
38
|
+
export type Verdict = "fresh" | "stale" | "undetermined";
|
|
39
|
+
export type FreshnessView = {
|
|
40
|
+
/** The library's own state, verbatim. */
|
|
41
|
+
readonly state: BundleFreshness["state"];
|
|
42
|
+
readonly verdict: Verdict;
|
|
43
|
+
/** True only for the two hash-compared states — the library's own flag. */
|
|
44
|
+
readonly exact: boolean;
|
|
45
|
+
readonly label: string;
|
|
46
|
+
/** Would `compileIfStale` recompile on this verdict? */
|
|
47
|
+
readonly wouldRecompile: boolean;
|
|
48
|
+
/** The crewhaus version whose emitters produced the bundle, when stamped. */
|
|
49
|
+
readonly compiledWith?: string;
|
|
50
|
+
};
|
|
51
|
+
export declare function classify(freshness: BundleFreshness): FreshnessView;
|
|
52
|
+
export type ContainedBundle = {
|
|
53
|
+
/** Absolute bundle dir, contained. */
|
|
54
|
+
readonly bundleDir: string;
|
|
55
|
+
readonly entryPath: string;
|
|
56
|
+
/** The bundle dir relative to the harness, `/`-separated — the `-o` a
|
|
57
|
+
* recompile is given, and the name a write gate has to contain. */
|
|
58
|
+
readonly outDirRel: string;
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* Where the compiled bundle is — with every name a read OR a recompile
|
|
62
|
+
* touches proven to be inside the workspace.
|
|
63
|
+
*
|
|
64
|
+
* `resolveBundle` is the supervisor's own search (`dist`, `build`, then the
|
|
65
|
+
* harness root) and is kept. What is added is the gate on what it hands
|
|
66
|
+
* back: `join` does not resolve symlinks, so `<harness>/dist -> /elsewhere`
|
|
67
|
+
* comes back as `<harness>/dist` and every later step follows the link.
|
|
68
|
+
* That matters twice. The freshness reader OPENS `<bundleDir>/package.json`
|
|
69
|
+
* and the entry. And `compileIfStale` spawns
|
|
70
|
+
* `crewhaus compile <spec> -o dist` with the harness as its cwd, then
|
|
71
|
+
* `bun install --cwd <bundleDir>` — so a symlinked `dist` is a WRITE
|
|
72
|
+
* straight out of the workspace, performed by a child process this tool
|
|
73
|
+
* cannot contain after the fact. Refused here, before either happens.
|
|
74
|
+
*
|
|
75
|
+
* `{ ok: true, value: undefined }` means there is no bundle.
|
|
76
|
+
*/
|
|
77
|
+
export declare function containedBundle(tool: string, harness: SafePath, target: string): Loaded<ContainedBundle | undefined>;
|
|
78
|
+
/**
|
|
79
|
+
* The supervisor's stamp comparison for one harness, classified — once every
|
|
80
|
+
* file it will open has been contained.
|
|
81
|
+
*
|
|
82
|
+
* GATE, THEN DELEGATE. `bundleStaleness` re-runs `findSpecPath` and
|
|
83
|
+
* `resolveBundle` itself and opens what they return; re-deriving its verdict
|
|
84
|
+
* here from `bundleFreshness` would be a second copy of the rule this
|
|
85
|
+
* package exists not to have. So the same two locators are run FIRST, purely
|
|
86
|
+
* to contain their answers, and the library is called unchanged only when
|
|
87
|
+
* both stay inside the workspace.
|
|
88
|
+
*/
|
|
89
|
+
export declare function freshnessOf(tool: string, harness: SafePath, target: string): Loaded<{
|
|
90
|
+
readonly freshness: FreshnessView;
|
|
91
|
+
readonly bundle: ContainedBundle | undefined;
|
|
92
|
+
}>;
|
|
93
|
+
export type CliResolution = {
|
|
94
|
+
/** Absolute path of the binary, as the supervisor's resolver returned it. */
|
|
95
|
+
readonly bin: string;
|
|
96
|
+
/** Which of the resolver's two sources answered. */
|
|
97
|
+
readonly where: "harness-local" | "PATH";
|
|
98
|
+
/** True when the binary (with its symlinks followed) is inside the
|
|
99
|
+
* workspace this tool is contained to. */
|
|
100
|
+
readonly inWorkspace: boolean;
|
|
101
|
+
/** The path after following symlinks, when it differs. */
|
|
102
|
+
readonly real?: string;
|
|
103
|
+
};
|
|
104
|
+
/**
|
|
105
|
+
* Which `crewhaus` would run for this harness, and whether executing it
|
|
106
|
+
* stays inside the workspace.
|
|
107
|
+
*
|
|
108
|
+
* The resolution itself is `resolveCrewhausBin`'s — harness-local
|
|
109
|
+
* `node_modules/.bin/crewhaus` first, then PATH — so the binary reported is
|
|
110
|
+
* the binary a `daemon start --compile` would spawn. The `where` label is
|
|
111
|
+
* derived by comparing against the harness-local candidate rather than by
|
|
112
|
+
* re-implementing the search.
|
|
113
|
+
*/
|
|
114
|
+
export declare function resolveCli(harnessRoot: string, workspaceRoot: string): CliResolution | undefined;
|
|
115
|
+
/**
|
|
116
|
+
* Refuse to EXECUTE a binary that sits outside the workspace unless the
|
|
117
|
+
* caller said so.
|
|
118
|
+
*
|
|
119
|
+
* Containment is about the paths a tool opens, and a globally installed
|
|
120
|
+
* `crewhaus` on `PATH` is one this tool did not get from the caller and
|
|
121
|
+
* cannot contain. Rather than pretend (either by refusing every real machine
|
|
122
|
+
* or by quietly running whatever `PATH` resolved), the refusal names the
|
|
123
|
+
* path it would have run and the flag that allows it.
|
|
124
|
+
*/
|
|
125
|
+
export declare function externalBinRefusal(cli: CliResolution, allowExternal: boolean): {
|
|
126
|
+
readonly reason: string;
|
|
127
|
+
} | undefined;
|
|
128
|
+
export declare function spawnEnv(forward?: readonly string[], source?: Readonly<Record<string, string | undefined>>): {
|
|
129
|
+
readonly env: Record<string, string>;
|
|
130
|
+
readonly forwarded: string[];
|
|
131
|
+
};
|
|
@@ -0,0 +1,330 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a harness IS (its spec, its shape), what its bundle's freshness
|
|
3
|
+
* verdict MEANS, and which `crewhaus` binary would run for it.
|
|
4
|
+
*
|
|
5
|
+
* None of the three questions is answered here. The spec is parsed by
|
|
6
|
+
* `@crewhaus/spec`, the freshness verdict comes from
|
|
7
|
+
* `@crewhaus/harness-supervisor`'s `bundleStaleness` — the spec-hash stamp
|
|
8
|
+
* comparison the manager itself gates a daemon start on — and the binary
|
|
9
|
+
* comes from the supervisor's `resolveCrewhausBin`. This module CLASSIFIES
|
|
10
|
+
* those answers, which is a different job and the one the tools need:
|
|
11
|
+
*
|
|
12
|
+
* FRESH means the bundle was compiled from this exact spec.
|
|
13
|
+
* STALE means it was compiled from a different one.
|
|
14
|
+
* UNDETERMINED means neither could be established.
|
|
15
|
+
*
|
|
16
|
+
* The third is the whole point. `bundleStaleness` has six states, and two of
|
|
17
|
+
* them — `unstamped` (no spec-hash stamp and no usable mtime pair) and
|
|
18
|
+
* `unknown` (no bundle found, or a spec that could not be read) — are not
|
|
19
|
+
* verdicts at all. `compileIfStale` recompiles on `stale`/`approximate-stale`
|
|
20
|
+
* and carries on for everything else with `{ ok: true, replan: false }`, so a
|
|
21
|
+
* caller that reports its success as "the bundle is current" reports an
|
|
22
|
+
* undetermined bundle as a fresh one. That is how a fleet ends up running
|
|
23
|
+
* last month's CLI with every status line green.
|
|
24
|
+
*/
|
|
25
|
+
import { readFileSync, realpathSync, statSync } from "node:fs";
|
|
26
|
+
import { join, relative } from "node:path";
|
|
27
|
+
import { bundleStaleness, findSpecPath, resolveBundle, resolveCrewhausBin, } from "@crewhaus/harness-supervisor";
|
|
28
|
+
import { parseSpec, parseSpecIssues } from "@crewhaus/spec";
|
|
29
|
+
import { containUnder, fail, isInside, renderPath, renderText } from "./result";
|
|
30
|
+
/** A spec is YAML a human wrote; anything past this is not one. */
|
|
31
|
+
const MAX_SPEC_BYTES = 4 * 1024 * 1024;
|
|
32
|
+
/**
|
|
33
|
+
* The harness's spec file, CONTAINED.
|
|
34
|
+
*
|
|
35
|
+
* `findSpecPath` is the supervisor's own discovery (which of the two
|
|
36
|
+
* filenames, in which order) and is kept. What is added is the gate: the
|
|
37
|
+
* path it hands back is a path a STORE produced, not one a caller passed
|
|
38
|
+
* containment for, and `existsSync` follows a symlink — so
|
|
39
|
+
* `<harness>/crewhaus.yaml -> /elsewhere/secret.yaml` resolves, parses, and
|
|
40
|
+
* comes back as this harness's identity. Contained here, once, so every
|
|
41
|
+
* caller of this module gets the same answer.
|
|
42
|
+
*
|
|
43
|
+
* `{ ok: true, value: undefined }` means there is no spec — a fact, not a
|
|
44
|
+
* failure. A refusal means there is one and it leads out of the workspace.
|
|
45
|
+
*/
|
|
46
|
+
export function containedSpecPath(tool, harness) {
|
|
47
|
+
const found = findSpecPath(harness.real);
|
|
48
|
+
if (found === undefined)
|
|
49
|
+
return { ok: true, value: undefined };
|
|
50
|
+
const safe = containUnder(tool, harness, toRel(harness, found));
|
|
51
|
+
if (!safe.ok)
|
|
52
|
+
return safe;
|
|
53
|
+
return { ok: true, value: safe.value };
|
|
54
|
+
}
|
|
55
|
+
/** A path under the harness, as the containment gate wants it. */
|
|
56
|
+
function toRel(harness, abs) {
|
|
57
|
+
const rel = relative(harness.real, abs);
|
|
58
|
+
return rel === "" ? "." : rel.split(/[\\/]/).join("/");
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Read a harness's spec and take its `target` from the PARSED document.
|
|
62
|
+
*
|
|
63
|
+
* Never from a line scan of the text. The supervisor picks the bundle entry
|
|
64
|
+
* file from `target`, so a target read out of a spec that does not parse
|
|
65
|
+
* would send the freshness check looking for the wrong file and report
|
|
66
|
+
* "no compiled bundle found" for a bundle that is sitting right there. A
|
|
67
|
+
* spec that will not parse is its own answer, with the parser's first issue
|
|
68
|
+
* attached.
|
|
69
|
+
*/
|
|
70
|
+
export function readSpecFacts(tool, harness) {
|
|
71
|
+
const contained = containedSpecPath(tool, harness);
|
|
72
|
+
if (!contained.ok)
|
|
73
|
+
return contained;
|
|
74
|
+
if (contained.value === undefined) {
|
|
75
|
+
return fail("missing", "no crewhaus.yaml (or crewhaus.yml) at the harness root");
|
|
76
|
+
}
|
|
77
|
+
const specPath = contained.value.real;
|
|
78
|
+
let size;
|
|
79
|
+
try {
|
|
80
|
+
size = statSync(specPath).size;
|
|
81
|
+
}
|
|
82
|
+
catch (err) {
|
|
83
|
+
const code = err.code;
|
|
84
|
+
return fail("unreadable", `the spec could not be read (${code ?? "unknown error"})`);
|
|
85
|
+
}
|
|
86
|
+
if (size > MAX_SPEC_BYTES) {
|
|
87
|
+
return fail("unreadable", `the spec is larger than ${MAX_SPEC_BYTES} bytes`);
|
|
88
|
+
}
|
|
89
|
+
let text;
|
|
90
|
+
try {
|
|
91
|
+
text = readFileSync(specPath, "utf8");
|
|
92
|
+
}
|
|
93
|
+
catch (err) {
|
|
94
|
+
const code = err.code;
|
|
95
|
+
return fail("unreadable", `the spec could not be read (${code ?? "unknown error"})`);
|
|
96
|
+
}
|
|
97
|
+
let parsed;
|
|
98
|
+
try {
|
|
99
|
+
parsed = parseSpec(text);
|
|
100
|
+
}
|
|
101
|
+
catch {
|
|
102
|
+
const issue = parseSpecIssues(text)[0];
|
|
103
|
+
const where = issue === undefined ? "" : issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
|
|
104
|
+
return fail("bad-input", `the spec does not parse (${where}${issue?.message ?? "unknown issue"}) — its target is unknown, so which file a compiled bundle should have cannot be determined`);
|
|
105
|
+
}
|
|
106
|
+
const target = parsed["target"];
|
|
107
|
+
if (typeof target !== "string" || target === "") {
|
|
108
|
+
return fail("bad-input", "the spec parsed but carries no target");
|
|
109
|
+
}
|
|
110
|
+
const name = parsed["name"];
|
|
111
|
+
// BOUNDED AND PRINTABLE. Both strings are spec text this package did not
|
|
112
|
+
// write: they are reported to a model AND (for `HarnessRegister`) written
|
|
113
|
+
// into the machine-wide registry, where every later reader inherits them.
|
|
114
|
+
// A `name` carrying newlines or a kilobyte of prose is not an identity.
|
|
115
|
+
return {
|
|
116
|
+
ok: true,
|
|
117
|
+
value: {
|
|
118
|
+
specPath,
|
|
119
|
+
...(typeof name === "string" && name !== "" ? { name: renderText(name) } : {}),
|
|
120
|
+
target: renderText(target),
|
|
121
|
+
},
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Every state the library can return, mapped to a verdict — as a SWITCH, so
|
|
126
|
+
* that a state added upstream fails to compile here.
|
|
127
|
+
*
|
|
128
|
+
* This is the one mapping in the package that must never acquire a default
|
|
129
|
+
* branch: with a `Set` of undetermined states and an `else` meaning "fresh",
|
|
130
|
+
* a seventh state invented next release would land silently in "fresh", and
|
|
131
|
+
* a verdict that defaults to fresh is the exact failure this package exists
|
|
132
|
+
* to prevent. The `never` assignment is what makes a new state a build
|
|
133
|
+
* error instead.
|
|
134
|
+
*
|
|
135
|
+
* `unknown`: no bundle found at all, or a spec that could not be read.
|
|
136
|
+
* `unstamped`: no spec-hash stamp AND no pair of mtimes to fall back on.
|
|
137
|
+
* Neither says anything about whether the bundle matches the spec.
|
|
138
|
+
*/
|
|
139
|
+
function verdictFor(state) {
|
|
140
|
+
switch (state) {
|
|
141
|
+
case "fresh":
|
|
142
|
+
case "approximate-fresh":
|
|
143
|
+
return "fresh";
|
|
144
|
+
case "stale":
|
|
145
|
+
case "approximate-stale":
|
|
146
|
+
return "stale";
|
|
147
|
+
case "unstamped":
|
|
148
|
+
case "unknown":
|
|
149
|
+
return "undetermined";
|
|
150
|
+
default: {
|
|
151
|
+
const unhandled = state;
|
|
152
|
+
return unhandled;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Verdicts on which `compileIfStale` actually recompiles.
|
|
158
|
+
*
|
|
159
|
+
* MIRRORS `STALE_STATES` in `harness-supervisor/src/prepare.ts`, which is a
|
|
160
|
+
* module-private constant — this package cannot import it. It is used only
|
|
161
|
+
* to PREDICT, and the prediction is checked against what the real call did
|
|
162
|
+
* (see `CompileBundle`: a predicted recompile that produced no `replan` is
|
|
163
|
+
* reported as a disagreement rather than as a success), so a drift shows up
|
|
164
|
+
* as a loud result field instead of a quiet wrong answer.
|
|
165
|
+
*/
|
|
166
|
+
const RECOMPILE_STATES = new Set([
|
|
167
|
+
"stale",
|
|
168
|
+
"approximate-stale",
|
|
169
|
+
]);
|
|
170
|
+
export function classify(freshness) {
|
|
171
|
+
const state = freshness.state;
|
|
172
|
+
return {
|
|
173
|
+
state,
|
|
174
|
+
verdict: verdictFor(state),
|
|
175
|
+
exact: freshness.exact,
|
|
176
|
+
label: freshness.label,
|
|
177
|
+
wouldRecompile: RECOMPILE_STATES.has(state),
|
|
178
|
+
// BOUNDED AND PRINTABLE at the source. `compiledWith` is a string the
|
|
179
|
+
// bundle's own `package.json` supplied — anyone who can write a bundle
|
|
180
|
+
// writes it — and it ends up both in a row and as a KEY in
|
|
181
|
+
// `CliVersionPin`'s version roll-up.
|
|
182
|
+
...(freshness.compiledWith !== undefined
|
|
183
|
+
? { compiledWith: renderText(freshness.compiledWith, 120) }
|
|
184
|
+
: {}),
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Where the compiled bundle is — with every name a read OR a recompile
|
|
189
|
+
* touches proven to be inside the workspace.
|
|
190
|
+
*
|
|
191
|
+
* `resolveBundle` is the supervisor's own search (`dist`, `build`, then the
|
|
192
|
+
* harness root) and is kept. What is added is the gate on what it hands
|
|
193
|
+
* back: `join` does not resolve symlinks, so `<harness>/dist -> /elsewhere`
|
|
194
|
+
* comes back as `<harness>/dist` and every later step follows the link.
|
|
195
|
+
* That matters twice. The freshness reader OPENS `<bundleDir>/package.json`
|
|
196
|
+
* and the entry. And `compileIfStale` spawns
|
|
197
|
+
* `crewhaus compile <spec> -o dist` with the harness as its cwd, then
|
|
198
|
+
* `bun install --cwd <bundleDir>` — so a symlinked `dist` is a WRITE
|
|
199
|
+
* straight out of the workspace, performed by a child process this tool
|
|
200
|
+
* cannot contain after the fact. Refused here, before either happens.
|
|
201
|
+
*
|
|
202
|
+
* `{ ok: true, value: undefined }` means there is no bundle.
|
|
203
|
+
*/
|
|
204
|
+
export function containedBundle(tool, harness, target) {
|
|
205
|
+
const found = resolveBundle(harness.real, target);
|
|
206
|
+
if (found === undefined)
|
|
207
|
+
return { ok: true, value: undefined };
|
|
208
|
+
const outDirRel = toRel(harness, found.bundleDir);
|
|
209
|
+
const dir = containUnder(tool, harness, outDirRel);
|
|
210
|
+
if (!dir.ok)
|
|
211
|
+
return dir;
|
|
212
|
+
// The DIRECTORY being contained says nothing about the two names inside it
|
|
213
|
+
// the stamp reader opens and a compile replaces.
|
|
214
|
+
for (const leaf of [found.entry, "package.json"]) {
|
|
215
|
+
const under = outDirRel === "." ? leaf : `${outDirRel}/${leaf}`;
|
|
216
|
+
const safe = containUnder(tool, harness, under);
|
|
217
|
+
if (!safe.ok)
|
|
218
|
+
return safe;
|
|
219
|
+
}
|
|
220
|
+
return {
|
|
221
|
+
ok: true,
|
|
222
|
+
value: { bundleDir: found.bundleDir, entryPath: found.entryPath, outDirRel },
|
|
223
|
+
};
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* The supervisor's stamp comparison for one harness, classified — once every
|
|
227
|
+
* file it will open has been contained.
|
|
228
|
+
*
|
|
229
|
+
* GATE, THEN DELEGATE. `bundleStaleness` re-runs `findSpecPath` and
|
|
230
|
+
* `resolveBundle` itself and opens what they return; re-deriving its verdict
|
|
231
|
+
* here from `bundleFreshness` would be a second copy of the rule this
|
|
232
|
+
* package exists not to have. So the same two locators are run FIRST, purely
|
|
233
|
+
* to contain their answers, and the library is called unchanged only when
|
|
234
|
+
* both stay inside the workspace.
|
|
235
|
+
*/
|
|
236
|
+
export function freshnessOf(tool, harness, target) {
|
|
237
|
+
const spec = containedSpecPath(tool, harness);
|
|
238
|
+
if (!spec.ok)
|
|
239
|
+
return spec;
|
|
240
|
+
const bundle = containedBundle(tool, harness, target);
|
|
241
|
+
if (!bundle.ok)
|
|
242
|
+
return bundle;
|
|
243
|
+
// The located bundle travels with the verdict so a caller does not run the
|
|
244
|
+
// gate a second time to learn where the bundle is — one gate, one answer.
|
|
245
|
+
return {
|
|
246
|
+
ok: true,
|
|
247
|
+
value: { freshness: classify(bundleStaleness(harness.real, target)), bundle: bundle.value },
|
|
248
|
+
};
|
|
249
|
+
}
|
|
250
|
+
/** Follow symlinks where possible; a path that cannot be resolved is its
|
|
251
|
+
* own answer, not an error — it is about to be reported, not opened. */
|
|
252
|
+
function realOrSame(p) {
|
|
253
|
+
try {
|
|
254
|
+
return realpathSync(p);
|
|
255
|
+
}
|
|
256
|
+
catch {
|
|
257
|
+
return p;
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
/**
|
|
261
|
+
* Which `crewhaus` would run for this harness, and whether executing it
|
|
262
|
+
* stays inside the workspace.
|
|
263
|
+
*
|
|
264
|
+
* The resolution itself is `resolveCrewhausBin`'s — harness-local
|
|
265
|
+
* `node_modules/.bin/crewhaus` first, then PATH — so the binary reported is
|
|
266
|
+
* the binary a `daemon start --compile` would spawn. The `where` label is
|
|
267
|
+
* derived by comparing against the harness-local candidate rather than by
|
|
268
|
+
* re-implementing the search.
|
|
269
|
+
*/
|
|
270
|
+
export function resolveCli(harnessRoot, workspaceRoot) {
|
|
271
|
+
const bin = resolveCrewhausBin(harnessRoot);
|
|
272
|
+
if (bin === undefined)
|
|
273
|
+
return undefined;
|
|
274
|
+
const local = join(harnessRoot, "node_modules", ".bin", "crewhaus");
|
|
275
|
+
const real = realOrSame(bin);
|
|
276
|
+
return {
|
|
277
|
+
bin,
|
|
278
|
+
where: bin === local ? "harness-local" : "PATH",
|
|
279
|
+
inWorkspace: isInside(workspaceRoot, real),
|
|
280
|
+
...(real !== bin ? { real } : {}),
|
|
281
|
+
};
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* Refuse to EXECUTE a binary that sits outside the workspace unless the
|
|
285
|
+
* caller said so.
|
|
286
|
+
*
|
|
287
|
+
* Containment is about the paths a tool opens, and a globally installed
|
|
288
|
+
* `crewhaus` on `PATH` is one this tool did not get from the caller and
|
|
289
|
+
* cannot contain. Rather than pretend (either by refusing every real machine
|
|
290
|
+
* or by quietly running whatever `PATH` resolved), the refusal names the
|
|
291
|
+
* path it would have run and the flag that allows it.
|
|
292
|
+
*/
|
|
293
|
+
export function externalBinRefusal(cli, allowExternal) {
|
|
294
|
+
if (allowExternal || cli.inWorkspace)
|
|
295
|
+
return undefined;
|
|
296
|
+
return {
|
|
297
|
+
reason: `the crewhaus CLI that would run resolves to "${renderPath(cli.real ?? cli.bin)}", outside the workspace root. Pass allowExternalCli:true to run it; this tool does not execute a binary it cannot contain without being told to.`,
|
|
298
|
+
};
|
|
299
|
+
}
|
|
300
|
+
// ---------------------------------------------------------------------------
|
|
301
|
+
// the environment a spawned step gets
|
|
302
|
+
// ---------------------------------------------------------------------------
|
|
303
|
+
/**
|
|
304
|
+
* The names forwarded to a compile by default.
|
|
305
|
+
*
|
|
306
|
+
* DELIBERATELY NOT the harness's merged `.env` chain, which is what the
|
|
307
|
+
* manager hands a compile. A compile reads a spec and writes a bundle; it
|
|
308
|
+
* has no business holding the harness's provider keys, and a tool that
|
|
309
|
+
* spawns with them makes every compile a place a credential can leak into a
|
|
310
|
+
* log. The cost is named in the README: a harness whose `bun install` needs
|
|
311
|
+
* a private-registry token has to forward it by name.
|
|
312
|
+
*/
|
|
313
|
+
const BASE_ENV_KEYS = ["PATH", "HOME", "TMPDIR", "TEMP", "TMP", "LANG", "LC_ALL", "SHELL"];
|
|
314
|
+
export function spawnEnv(forward = [], source = process.env) {
|
|
315
|
+
const env = {};
|
|
316
|
+
for (const key of BASE_ENV_KEYS) {
|
|
317
|
+
const value = source[key];
|
|
318
|
+
if (typeof value === "string")
|
|
319
|
+
env[key] = value;
|
|
320
|
+
}
|
|
321
|
+
const forwarded = [];
|
|
322
|
+
for (const key of forward) {
|
|
323
|
+
const value = source[key];
|
|
324
|
+
if (typeof value !== "string")
|
|
325
|
+
continue;
|
|
326
|
+
env[key] = value;
|
|
327
|
+
forwarded.push(key);
|
|
328
|
+
}
|
|
329
|
+
return { env, forwarded: forwarded.sort() };
|
|
330
|
+
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { JobRecord } from "@crewhaus/harness-supervisor";
|
|
2
|
+
import { type Loaded } from "./result";
|
|
3
|
+
export type LedgerState = "absent" | "ok" | "not-a-file" | "unreadable";
|
|
4
|
+
export type LedgerProbe = {
|
|
5
|
+
readonly state: LedgerState;
|
|
6
|
+
readonly path: string;
|
|
7
|
+
readonly bytes?: number;
|
|
8
|
+
readonly detail?: string;
|
|
9
|
+
};
|
|
10
|
+
/** What condition the job ledger is in. Read-only; opens nothing. */
|
|
11
|
+
export declare function probeLedger(path: string): LedgerProbe;
|
|
12
|
+
/** The ledger states a listing may be built from. */
|
|
13
|
+
export declare function ledgerBlockedBy(probe: LedgerProbe): Loaded<undefined>;
|
|
14
|
+
export type JobFilter = {
|
|
15
|
+
/** Absolute harness directories; a record matches any of them. Both the
|
|
16
|
+
* lexical and the symlink-resolved spelling are passed, because the
|
|
17
|
+
* manager records whichever one it was given. */
|
|
18
|
+
readonly harnessDirs?: readonly string[];
|
|
19
|
+
readonly harnessId?: string;
|
|
20
|
+
readonly jobId?: string;
|
|
21
|
+
readonly kind?: string;
|
|
22
|
+
readonly state?: string;
|
|
23
|
+
/** ISO 8601; keeps records enqueued at or after this instant. */
|
|
24
|
+
readonly sinceIso?: string;
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Apply the filter to already-folded records.
|
|
28
|
+
*
|
|
29
|
+
* `since` compares PARSED timestamps, never the strings: two valid ISO 8601
|
|
30
|
+
* instants can be spelled differently (`Z` versus `+00:00`, fractional
|
|
31
|
+
* seconds) and a string comparison would order them wrongly. A record whose
|
|
32
|
+
* `enqueuedAt` does not parse is KEPT and flagged, never silently dropped —
|
|
33
|
+
* dropping it would hide a job from a status listing on the strength of a
|
|
34
|
+
* malformed field.
|
|
35
|
+
*/
|
|
36
|
+
export declare function filterJobs(records: readonly JobRecord[], filter: JobFilter): {
|
|
37
|
+
readonly kept: JobRecord[];
|
|
38
|
+
readonly unparsedTimestamps: string[];
|
|
39
|
+
};
|
|
40
|
+
/** Newest first by enqueue time; an unparseable timestamp sorts last, and
|
|
41
|
+
* ties break on `jobId` so the order is stable rather than readdir-shaped. */
|
|
42
|
+
export declare function sortJobs(records: readonly JobRecord[]): JobRecord[];
|
|
43
|
+
/**
|
|
44
|
+
* One job, shaped for a result. Every field comes from the record.
|
|
45
|
+
*
|
|
46
|
+
* The ledger is a machine-wide append-only file the manager writes, and an
|
|
47
|
+
* `error` is whatever a failed child process said. Both are text this
|
|
48
|
+
* package did not write, on their way into a model's context, so each is
|
|
49
|
+
* bounded and stripped of control characters — the FILTERS above run on the
|
|
50
|
+
* record's own values, never on these rendered copies.
|
|
51
|
+
*/
|
|
52
|
+
export declare function jobView(record: JobRecord): Record<string, unknown>;
|
|
53
|
+
/** How many jobs sit in each state, in a stable key order. */
|
|
54
|
+
export declare function countByState(records: readonly JobRecord[]): Record<string, number>;
|
package/dist/lib/jobs.js
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading the manager's durable job ledger without mistaking "could not
|
|
3
|
+
* read it" for "nothing ran".
|
|
4
|
+
*
|
|
5
|
+
* The fold itself belongs to `@crewhaus/harness-supervisor`:
|
|
6
|
+
* `createFileJobStore(path).read()` is append-only JSONL folded by `jobId`,
|
|
7
|
+
* last write wins, torn trailing line skipped. Nothing here parses a record.
|
|
8
|
+
*
|
|
9
|
+
* What is here is the part the store cannot express. Its reader is:
|
|
10
|
+
*
|
|
11
|
+
* ```js
|
|
12
|
+
* try { text = readFileSync(path, "utf8"); } catch { return []; }
|
|
13
|
+
* ```
|
|
14
|
+
*
|
|
15
|
+
* — so a ledger the manager is writing to but this process cannot open
|
|
16
|
+
* (EACCES on a root-owned hangar, a directory where the file should be, an
|
|
17
|
+
* I/O error) comes back as an empty array, indistinguishable from a fleet
|
|
18
|
+
* that has never run a job. A status tool that reports that as "no jobs" is
|
|
19
|
+
* the reason somebody concludes a queue is idle while it is running.
|
|
20
|
+
*
|
|
21
|
+
* So the path is probed first, and a ledger that exists but folded to
|
|
22
|
+
* nothing is reported as exactly that rather than as an absent one.
|
|
23
|
+
*/
|
|
24
|
+
import { statSync } from "node:fs";
|
|
25
|
+
import { compareStrings, fail, probeName, renderStorePath, renderText, } from "./result";
|
|
26
|
+
/** What condition the job ledger is in. Read-only; opens nothing. */
|
|
27
|
+
export function probeLedger(path) {
|
|
28
|
+
const kind = probeName(path, path);
|
|
29
|
+
if (!kind.ok)
|
|
30
|
+
return { state: "unreadable", path, detail: kind.reason };
|
|
31
|
+
if (kind.value === undefined)
|
|
32
|
+
return { state: "absent", path };
|
|
33
|
+
if (kind.value === "directory" || kind.value === "other") {
|
|
34
|
+
return { state: "not-a-file", path, detail: `the ledger path is a ${kind.value}, not a file` };
|
|
35
|
+
}
|
|
36
|
+
try {
|
|
37
|
+
return { state: "ok", path, bytes: statSync(path).size };
|
|
38
|
+
}
|
|
39
|
+
catch (err) {
|
|
40
|
+
const code = err.code;
|
|
41
|
+
return { state: "unreadable", path, detail: `could not be read (${code ?? "unknown error"})` };
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
/** The ledger states a listing may be built from. */
|
|
45
|
+
export function ledgerBlockedBy(probe) {
|
|
46
|
+
if (probe.state === "ok" || probe.state === "absent")
|
|
47
|
+
return { ok: true, value: undefined };
|
|
48
|
+
return fail("unreadable", `${probe.path}: ${probe.detail ?? probe.state}. @crewhaus/harness-supervisor's job store answers an unopenable ledger with an empty list, so this would otherwise have been reported as "no jobs".`);
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Apply the filter to already-folded records.
|
|
52
|
+
*
|
|
53
|
+
* `since` compares PARSED timestamps, never the strings: two valid ISO 8601
|
|
54
|
+
* instants can be spelled differently (`Z` versus `+00:00`, fractional
|
|
55
|
+
* seconds) and a string comparison would order them wrongly. A record whose
|
|
56
|
+
* `enqueuedAt` does not parse is KEPT and flagged, never silently dropped —
|
|
57
|
+
* dropping it would hide a job from a status listing on the strength of a
|
|
58
|
+
* malformed field.
|
|
59
|
+
*/
|
|
60
|
+
export function filterJobs(records, filter) {
|
|
61
|
+
const since = filter.sinceIso === undefined ? undefined : Date.parse(filter.sinceIso);
|
|
62
|
+
const dirs = filter.harnessDirs === undefined ? undefined : new Set(filter.harnessDirs);
|
|
63
|
+
const unparsedTimestamps = [];
|
|
64
|
+
const kept = records.filter((record) => {
|
|
65
|
+
if (filter.jobId !== undefined && record.jobId !== filter.jobId)
|
|
66
|
+
return false;
|
|
67
|
+
if (dirs !== undefined && !dirs.has(record.harnessDir))
|
|
68
|
+
return false;
|
|
69
|
+
if (filter.harnessId !== undefined && record.harnessId !== filter.harnessId)
|
|
70
|
+
return false;
|
|
71
|
+
if (filter.kind !== undefined && record.kind !== filter.kind)
|
|
72
|
+
return false;
|
|
73
|
+
if (filter.state !== undefined && record.state !== filter.state)
|
|
74
|
+
return false;
|
|
75
|
+
if (since !== undefined && !Number.isNaN(since)) {
|
|
76
|
+
const at = Date.parse(record.enqueuedAt);
|
|
77
|
+
if (Number.isNaN(at)) {
|
|
78
|
+
unparsedTimestamps.push(record.jobId);
|
|
79
|
+
return true;
|
|
80
|
+
}
|
|
81
|
+
if (at < since)
|
|
82
|
+
return false;
|
|
83
|
+
}
|
|
84
|
+
return true;
|
|
85
|
+
});
|
|
86
|
+
return { kept, unparsedTimestamps: unparsedTimestamps.sort(compareStrings) };
|
|
87
|
+
}
|
|
88
|
+
/** Newest first by enqueue time; an unparseable timestamp sorts last, and
|
|
89
|
+
* ties break on `jobId` so the order is stable rather than readdir-shaped. */
|
|
90
|
+
export function sortJobs(records) {
|
|
91
|
+
const at = (record) => {
|
|
92
|
+
const ms = Date.parse(record.enqueuedAt);
|
|
93
|
+
return Number.isNaN(ms) ? Number.NEGATIVE_INFINITY : ms;
|
|
94
|
+
};
|
|
95
|
+
return [...records].sort((a, b) => at(b) - at(a) || compareStrings(a.jobId, b.jobId));
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* One job, shaped for a result. Every field comes from the record.
|
|
99
|
+
*
|
|
100
|
+
* The ledger is a machine-wide append-only file the manager writes, and an
|
|
101
|
+
* `error` is whatever a failed child process said. Both are text this
|
|
102
|
+
* package did not write, on their way into a model's context, so each is
|
|
103
|
+
* bounded and stripped of control characters — the FILTERS above run on the
|
|
104
|
+
* record's own values, never on these rendered copies.
|
|
105
|
+
*/
|
|
106
|
+
export function jobView(record) {
|
|
107
|
+
return {
|
|
108
|
+
jobId: renderText(record.jobId, 200),
|
|
109
|
+
harnessDir: renderStorePath(record.harnessDir),
|
|
110
|
+
...(record.harnessId !== undefined ? { harnessId: renderText(record.harnessId, 100) } : {}),
|
|
111
|
+
kind: renderText(record.kind, 100),
|
|
112
|
+
state: record.state,
|
|
113
|
+
mutating: record.mutating,
|
|
114
|
+
argv: record.argv.map((part) => renderText(part, 400)),
|
|
115
|
+
enqueuedAt: renderText(record.enqueuedAt, 64),
|
|
116
|
+
...(record.startedAt !== undefined ? { startedAt: renderText(record.startedAt, 64) } : {}),
|
|
117
|
+
...(record.endedAt !== undefined ? { endedAt: renderText(record.endedAt, 64) } : {}),
|
|
118
|
+
...(record.exitCode !== undefined ? { exitCode: record.exitCode } : {}),
|
|
119
|
+
...(record.error !== undefined ? { error: renderText(record.error, 1000) } : {}),
|
|
120
|
+
...(record.forced === true ? { forced: true } : {}),
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
/** How many jobs sit in each state, in a stable key order. */
|
|
124
|
+
export function countByState(records) {
|
|
125
|
+
const counts = new Map();
|
|
126
|
+
// The KEY is a record's own `state`. The store does not validate it, so a
|
|
127
|
+
// hand-edited or future ledger line puts an arbitrary string here — and it
|
|
128
|
+
// becomes a field name in a count somebody acts on.
|
|
129
|
+
for (const record of records) {
|
|
130
|
+
const key = renderText(record.state, 60);
|
|
131
|
+
counts.set(key, (counts.get(key) ?? 0) + 1);
|
|
132
|
+
}
|
|
133
|
+
return Object.fromEntries([...counts.entries()].sort((a, b) => compareStrings(a[0], b[0])));
|
|
134
|
+
}
|