@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,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>;
@@ -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
+ }