@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 ADDED
@@ -0,0 +1,247 @@
1
+ # @crewhaus/tool-fleet
2
+
3
+ The harnesses on this machine, as deterministic tools: register them, ask what the job queue
4
+ did, recompile a stale bundle, see which CLI version each one is really running, and manage the
5
+ hooks that wrap a start.
6
+
7
+ | Tool | Does | Consumes |
8
+ |---|---|---|
9
+ | `HarnessRegister` | add / remove / relocate / list / annotate registry rows | `@crewhaus/harness-registry` (`openHangarRegistry`) |
10
+ | `HarnessJobStatus` | read the manager's durable job ledger | `@crewhaus/harness-supervisor` (`createFileJobStore`) |
11
+ | `CompileBundle` | judge a bundle against its spec and recompile a stale one | `harness-supervisor` (`bundleStaleness`, `compileIfStale`) |
12
+ | `CliVersionPin` | which CLI each harness would run, which one built its bundle | `harness-supervisor` (`resolveCrewhausBin`, the bundle stamp) |
13
+ | `HooksManage` | list / set / remove the manager hooks in `.crewhaus/settings.json` | `harness-supervisor` (`parseManagerHook`, `readManagerSettings`) |
14
+
15
+ ## These tools are thin on purpose
16
+
17
+ Everything they enforce belongs to a package they depend on. The registry file is written by
18
+ `@crewhaus/harness-registry` and by nothing here — its atomic tmp+rename, its `0600` mode and its
19
+ fingerprint-checked read-merge-write retry are what stop two sessions and a running manager from
20
+ losing each other's rows, and a read-modify-write of `harnesses.json` in this package would defeat
21
+ all three. Bundle staleness is the supervisor's spec-hash comparison, the recompile is its
22
+ `compileIfStale`, the hook grammar is its `parseManagerHook`, the job fold is its
23
+ `createFileJobStore`. This package contributes the schema, the containment, the refusals, the
24
+ verification after the fact and the result shape.
25
+
26
+ ## An empty store and an unreadable one are different answers
27
+
28
+ Every store behind these tools answers a file it could not open with an empty result:
29
+
30
+ ```js
31
+ try { parsed = JSON.parse(readFileSync(path, "utf8")); } catch { parsed = undefined; } // harness-registry
32
+ try { text = readFileSync(path, "utf8"); } catch { return []; } // job store
33
+ const manager = readManagerBlock(dir); if (manager === undefined) return EMPTY; // manager settings
34
+ ```
35
+
36
+ Each is right where it lives — all three are read on a boot path that must not die on a typo —
37
+ and each is a lie in a report. So every tool here probes the file's CONDITION before concluding
38
+ anything from an empty result, and says which of the two it got:
39
+
40
+ - `HarnessRegister list` on an unparseable registry returns `status: "unreadable"`, never
41
+ `status: "ok", count: 0`.
42
+ - `HarnessJobStatus` refuses a ledger it cannot open instead of reporting an idle queue, and
43
+ distinguishes "the file is there and folded to no records" from "there is no file".
44
+ - `HooksManage list` on a settings file that does not parse says the hooks shown are the reader's
45
+ DEFAULTS, not the file's contents.
46
+ - A mutation against a registry or a settings file that exists and did not parse is **refused**:
47
+ the next write would heal it wholesale, taking every row, group, tag, note — or the runtime's
48
+ own `hooks` and `permissions` blocks — with it.
49
+ - `CREWHAUS_NO_REGISTRY=1` turns registry writes into silent no-ops while the API still returns a
50
+ perfectly plausible entry. Mutations refuse rather than report an entry that was never
51
+ persisted, and `list` carries `writesDisabled`.
52
+ - `list()` can also fail to PERSIST (a root-owned `~/.crewhaus`, a read-only home) and degrades to
53
+ an un-persisted view through an `onWarn` whose default is silence. Those warnings are captured
54
+ and reported as `registryWarnings`.
55
+
56
+ ## A bundle that could not be judged is not a fresh bundle
57
+
58
+ `bundleStaleness` has six states. `compileIfStale` recompiles on `stale` and `approximate-stale`;
59
+ for `unstamped` and `unknown` it returns `{ ok: true, replan: false }` and carries on. Reporting
60
+ that as success is how ten of eleven harnesses sat on last month's CLI with every status line
61
+ green. `CompileBundle` therefore reports three verdicts:
62
+
63
+ | library state | verdict | exact |
64
+ |---|---|---|
65
+ | `fresh` / `stale` | fresh / stale | yes — spec-hash stamped |
66
+ | `approximate-fresh` / `approximate-stale` | fresh / stale | no — mtimes only |
67
+ | `unstamped` / `unknown` | **undetermined** | no |
68
+
69
+ A real run on an undetermined verdict is refused, with the command that fixes it. The mapping is a
70
+ `switch` with a `never` default, so a seventh state added upstream is a build error here instead of
71
+ landing silently in "fresh".
72
+
73
+ After a real compile the freshness is **re-read from disk**: an exit code of 0 says the command
74
+ succeeded, only the stamp says the bundle now matches the spec. A compile that exited 0 and left
75
+ the bundle stale is reported as `incomplete`, with `stillNotFresh`.
76
+
77
+ `BundleFreshness` in `@crewhaus/tool-crewhaus` answers a different question — preflight's mtime
78
+ heuristic. When the two disagree, the stamp is the one the manager acts on.
79
+
80
+ ## The identity key is the id, not the path
81
+
82
+ A relocate changes the directory and keeps the `hrn_` id, which inverts the key every other call
83
+ uses. So:
84
+
85
+ - an `id` input is validated against `HARNESS_ID_RE` first, because the registry silently treats
86
+ any other string as a DIRECTORY and resolves it against the working directory;
87
+ - `remove` and `relocate` resolve the ENTRY first and then act on `entry.id`, so the preview and
88
+ the real call select the same row;
89
+ - after a relocate the registry is re-read and the result carries `entriesWithId` and
90
+ `entriesLeftAtOldDir` — a registry keyed by path answers a relocate by adding a second row, and
91
+ the count is the only thing that catches it;
92
+ - a directory reached through a symlink is registered under its REAL path, and a register that
93
+ finds an existing row under either spelling refreshes that row instead of adding a second.
94
+
95
+ ## Containment, and the one named exception
96
+
97
+ Every path a caller supplies goes through `resolveSafe` — the verbatim `@crewhaus/tool-pkg` copy —
98
+ and so does **every leaf underneath it that these tools actually open**, not just the directory the
99
+ caller named. Containing a directory and not its leaves contains nothing: none of the four files
100
+ below is named in any schema, each is handed back by a library that resolves it with `existsSync`
101
+ (which FOLLOWS a symlink), and each is opened.
102
+
103
+ | leaf | found by | what a symlink out of the workspace would do |
104
+ |---|---|---|
105
+ | `crewhaus.yaml` / `.yml` | `findSpecPath` | another harness's spec parses and its `name`/`target` come back as this one's — and `HarnessRegister` writes them into the machine-wide registry |
106
+ | `dist`/`build`/`.` + its entry and `package.json` | `resolveBundle` | the stamp is read from elsewhere — and `compileIfStale` runs `crewhaus compile … -o dist` and `bun install --cwd dist` with the harness as cwd, so the recompile WRITES there |
107
+ | `.crewhaus/settings.json` | `readManagerSettings` | another file's hooks are reported as this harness's, and the atomic rewrite ends in a rename that replaces the link's target |
108
+ | `.crewhaus/run/hooks.json` | `readHookRunLog` | another harness's hook history is reported as this one's |
109
+
110
+ Each is refused, with the reason, and there is no flag to follow the link. `CompileBundle`'s gate
111
+ runs BEFORE the `dryRun` branch, so the preview and the real call refuse identically. The check is
112
+ the same `resolveSafe` the root went through, never a second symlink walker — and it resolves a
113
+ DANGLING link by hand, because `stat` reports one absent while an `open(…, "w")` through it creates
114
+ the target. `HooksManage` additionally contains the temp file its atomic replace renames from: that
115
+ name is one this tool creates and nothing else checks.
116
+
117
+ Paths a STORE hands back are contained too: `CliVersionPin` re-contains every registry row before
118
+ opening a spec or a bundle under it and reports the rest as skipped, and rows are deduped by real
119
+ path so one harness cannot be counted twice in the version roll-up.
120
+
121
+ The exception is deliberate and no input can move it. The two machine-wide files —
122
+ `<registryRoot>/harnesses.json` and `<hangarRoot>/jobs.jsonl` — are resolved from the environment
123
+ (`CREWHAUS_REGISTRY_ROOT`, `CREWHAUS_HANGAR_ROOT`), because a registry that only ever saw the
124
+ current workspace would not be a registry. Their absolute paths are reported in every result.
125
+
126
+ Two binaries are executed: `crewhaus compile` (by `CompileBundle`) and `<bin> --version` (by
127
+ `CliVersionPin --probe`). Both come from the supervisor's own resolver — harness-local
128
+ `node_modules/.bin/crewhaus` first, then `PATH` — and a binary that resolves OUTSIDE the workspace
129
+ is refused unless `allowExternalCli` is passed, with its path named.
130
+
131
+ ## What a compile is given
132
+
133
+ A minimal environment: `PATH`, `HOME`, `TMPDIR`/`TEMP`/`TMP`, `LANG`, `LC_ALL`, `SHELL`, plus any
134
+ names passed in `forwardEnv` (names only — values come from this process, and the result reports
135
+ which ones actually had one). This is deliberately NOT the harness's merged `.env` chain, which is
136
+ what the manager hands a compile: a compile reads a spec and writes a bundle, and a tool that
137
+ spawns it with the harness's provider keys makes every compile a place a credential can leak into
138
+ a log. The cost: a harness whose `bun install` needs a private-registry token has to forward it by
139
+ name.
140
+
141
+ ## What this build does not do, and why
142
+
143
+ - **Install, switch or pin a CLI version.** That is `@crewhaus/chvm` talking to
144
+ `registry.npmjs.org`. Neither the dependency nor the network call belongs here, so
145
+ `CliVersionPin` reports `cannotDo` with the `chvm` command instead of half-doing it.
146
+ - **A FIRST compile.** `compileIfStale` only acts on a stale verdict, so a harness that has never
147
+ been compiled (`unknown`) cannot be compiled through it. The refusal names
148
+ `crewhaus compile <spec> -o <outDir>` rather than reimplementing the compile — that would be a
149
+ second compile path, which is the drift this architecture exists to avoid.
150
+ - **Execute a hook.** `HooksManage` reports what a declaration parses to, where its command
151
+ resolves and whether that file exists and is executable, and never runs it. The probe answers on
152
+ the NAME first: `access(…, X_OK)` succeeds on a directory (the bit means "traversable" there), so
153
+ a command that is a directory — or a dangling symlink — would otherwise be written as
154
+ `executable` and then refuse every start of the harness with EACCES. A dry run that
155
+ spawned an operator-supplied command would be a tool that runs arbitrary code to answer a
156
+ question about configuration.
157
+ - **Cancel a job.** The job store is append-only and has no cancel route; `HarnessJobStatus` is
158
+ read-only.
159
+ - **Say whether a job is terminal.** `TERMINAL_JOB_STATES` lives in
160
+ `harness-supervisor/src/queue.ts` and is not re-exported from that package's index, and a second
161
+ copy here could disagree with the queue. States are reported verbatim and counted by state
162
+ instead. `interrupted` IS final — a manager that died mid-job reopens the row as interrupted and
163
+ never re-runs it — which is why it is called out in the tool's description.
164
+
165
+ ## Where this differs from the survey sketch
166
+
167
+ - **`HooksManage` manages the MANAGER hooks, not the runtime ones.** The sketch pointed it at
168
+ `@crewhaus/hooks-engine`'s `{event, matcher, command}` entries. Those are runtime hooks that fire
169
+ on model-driven moments; the hooks a FLEET tool is about are the `postCompile`/`preSpawn` steps
170
+ the supervisor runs around a start, they live in the same `settings.json`, and their owner is
171
+ already a dependency here. `hooks-engine` is also not a dependency of this package and adding one
172
+ is a standing maintainer no.
173
+ - **No hook is executed.** The sketch had `dryRun` spawn the hook against a fixture under the
174
+ engine's restricted env. Running an operator-supplied command to answer a question about
175
+ configuration is a bigger thing than the question, and the restricted-env fidelity argument does
176
+ not apply to manager hooks — they run with the harness's own merged environment by design. What
177
+ the sketch wanted from that spawn (does this hook actually work?) is answered without it: the
178
+ parsed argv, the resolved command, whether that file exists and is executable, and the last run
179
+ the supervisor recorded.
180
+ - **`CliVersionPin` reports; it does not pin.** The sketch had it call chvm's install/use/list.
181
+ That needs `@crewhaus/chvm` and `registry.npmjs.org`. The version JOIN it describes is the
182
+ valuable half and needs neither, so that is what it does — with the tri-state it asked for, made
183
+ explicit: a version that could not be read is `unknown` with a reason, and a bundle with no stamp
184
+ is not counted as agreeing with anything.
185
+ - **`HarnessJobStatus` has no `wait`.** A poll loop inside a tool holds the caller's turn for a
186
+ duration nobody declared, and its answer depends on when it happened to be called; re-calling the
187
+ tool is the same information, on the caller's own schedule. The insight behind the sketch's
188
+ `wait` is kept where it belongs — `interrupted` is final, and the description says so.
189
+ - **No `scan-register`.** Walking a tree for `crewhaus.yaml` is `discoverHarnesses`, which
190
+ `HarnessInventory` in `@crewhaus/tool-crewhaus` already exposes; a second walk here would be a
191
+ second definition of what a harness is. Feed its output to `HarnessRegister register`.
192
+ - **The registry root is not an input.** The sketch's `allowedRoots` check becomes the containment
193
+ boundary every other path in this package already passes: a harness registered through this tool
194
+ is inside the workspace, resolved through its symlinks, and no input can move the registry file
195
+ itself.
196
+
197
+ ## Result statuses
198
+
199
+ Every result is one JSON object carrying a `status`:
200
+
201
+ | status | means |
202
+ |---|---|
203
+ | `ok` | a listing, and the store it came from was readable |
204
+ | `preview` | `dryRun` — carries `nothingWasTouched` and what WOULD happen |
205
+ | `applied` | the change was made AND read back |
206
+ | `unchanged` | nothing needed doing (a fresh bundle, a hook that was not declared) |
207
+ | `incomplete` | the step ran and the state it should have produced is not there |
208
+ | `failed` | the step ran and did not succeed — carries its stage, exit code and output |
209
+ | `undetermined` | the question could not be answered; never a stand-in for "no" |
210
+ | `unreadable` | the store could not be read; the numbers in the result mean nothing |
211
+ | `refused` | the tool would not proceed — carries a `code` and a `reason` |
212
+
213
+ ## Notes
214
+
215
+ - `HarnessJobStatus` and `CliVersionPin` declare `readOnly: true`, and nothing they do writes.
216
+ `harness-registry`'s `list()` normally persists its own missing-directory stamps and any pending
217
+ pre-v2 lift ON A READ, so merely reporting the fleet would edit a machine-wide file — and
218
+ `readOnly` is a flag a permission layer acts on, not a note. Every enumerating READ here opens
219
+ the registry through the library's own `CREWHAUS_NO_REGISTRY` switch: the computed view,
220
+ including the freshly stamped `missingSince`, is identical and every write becomes a no-op.
221
+ `HarnessRegister list` does the same, because its schema calls it "the only one that never
222
+ writes". A test asserts the registry file is byte-for-byte unchanged after both.
223
+ - **A cap that stops an enumeration says so.** `CliVersionPin` inspects at most 500 harnesses; past
224
+ that it reports `truncated: true`, `registryRows` and a note, because `mixedFleet: false`
225
+ computed over the first 500 rows of a larger fleet is an answer about a subset that reads as an
226
+ answer about the fleet.
227
+ - **Text these tools did not write is bounded and made printable** before it lands in a result: a
228
+ spec's `name`, a bundle manifest's `compiledWith` (which is also a KEY in the version roll-up), a
229
+ row another writer put in the shared registry, a job's `error`, a line a spawned binary printed.
230
+ That is not a claim the text is trustworthy — a short printable sentence can still read like an
231
+ instruction — only that one of them cannot spend a model's whole context or forge a line break
232
+ out of the field it sits in.
233
+ - **A registry write that cannot land is reported, not thrown.** Every setter in
234
+ `harness-registry` throws when its rename fails (only `list()` degrades), and an exception out of
235
+ `execute` reaches the caller as a bare `EACCES` with no tool and no code. A multi-field `update`
236
+ reports `applied`, `notApplied` and `failedAt`, because it is several atomic writes and a failure
237
+ halfway through leaves some fields on disk and some not.
238
+ - `dryRun` defaults to **true** on every mutating action. The preview runs the same selection code
239
+ as the real call: the same registry lookup, the same staleness verdict, the same parsed hook.
240
+ - A multi-field `HarnessRegister update` is several atomic writes (one per registry setter), not
241
+ one transaction. Another writer can land between them. The alternative would be a second
242
+ document-level write path in this package.
243
+ - The registry-condition probe and the registry's own write are two separate operations; a file
244
+ that becomes unparseable between them is not caught. The probe closes the window that matters —
245
+ an operator running a tool against a registry that is *already* broken.
246
+ - `HooksManage` preserves the settings file's mode when it rewrites it, and creates `.crewhaus`
247
+ with mode `0700` when a harness has never been supervised.
@@ -0,0 +1,81 @@
1
+ /**
2
+ * @crewhaus/tool-fleet — the harnesses on this machine, as deterministic
3
+ * tools: register them, ask what the queue did, recompile a stale bundle,
4
+ * see which CLI version each one is actually running, and manage the hooks
5
+ * that wrap a start.
6
+ *
7
+ * Five properties hold across the package.
8
+ *
9
+ * 1. THE REAL STORES. The registry file is written by
10
+ * `@crewhaus/harness-registry` and by nothing else here: its atomic
11
+ * tmp+rename, its 0600 mode and its fingerprint-checked
12
+ * read-merge-write retry are what keep two sessions and a running
13
+ * manager from losing each other's rows, and a read-modify-write of
14
+ * `harnesses.json` in this package would defeat all three. Bundle
15
+ * staleness is `@crewhaus/harness-supervisor`'s spec-hash comparison,
16
+ * the recompile is its `compileIfStale`, the hook grammar is its
17
+ * `parseManagerHook`, the job fold is its `createFileJobStore`. Nothing
18
+ * here is a second copy of any of them.
19
+ * 2. AN EMPTY STORE AND AN UNREADABLE ONE ARE DIFFERENT ANSWERS. Every
20
+ * store these tools read answers a file it could not open with an empty
21
+ * result, because each is read on a boot path that must not die on a
22
+ * typo. That is the right posture there and a lie in a report, so each
23
+ * file's CONDITION is probed before anything is concluded from an empty
24
+ * result — and a mutation against a registry or a settings file that
25
+ * could not be parsed is refused, because the next write would heal it
26
+ * wholesale and take every row, group, tag and note with it.
27
+ * 3. A BUNDLE THAT COULD NOT BE JUDGED IS NOT A FRESH BUNDLE. The
28
+ * supervisor recompiles on `stale`; `unknown` and `unstamped` it treats
29
+ * as "not stale" and carries on with `{ ok: true }`. Reported as
30
+ * success, that is how ten of eleven harnesses sat on last month's CLI
31
+ * with every status line green. Here those two states are a THIRD
32
+ * verdict — `undetermined` — and a real recompile on one is refused by
33
+ * name rather than reported as a no-op success.
34
+ * 4. THE IDENTITY KEY IS THE ID, NOT THE PATH. A relocate changes the
35
+ * directory and keeps the `hrn_` id, which inverts the key every other
36
+ * call uses. So an id is validated as an id before it is passed
37
+ * anywhere (the registry silently treats a non-`hrn_` string as a
38
+ * DIRECTORY and resolves it against the working directory), a relocate
39
+ * is looked up by id and verified afterwards to leave exactly one entry
40
+ * carrying it, and a register that finds a row under the other spelling
41
+ * of the same directory refreshes THAT row instead of adding a second
42
+ * one.
43
+ * 5. CONTAINMENT, AND ONE NAMED EXCEPTION. Every path a CALLER supplies
44
+ * goes through `resolveSafe` — the verbatim `@crewhaus/tool-pkg` copy —
45
+ * and so does every leaf underneath it that is actually OPENED, not
46
+ * only the ones a write lands on. The four that matter are named in no
47
+ * schema and are handed back by a library that finds them with
48
+ * `existsSync`, which follows a symlink: `crewhaus.yaml`, the bundle
49
+ * directory with its entry and manifest, `.crewhaus/settings.json` and
50
+ * `.crewhaus/run/hooks.json`. Reading one that leads out of the
51
+ * workspace reports another harness's identity as this one's; the
52
+ * bundle directory is worse, because the recompile WRITES into it.
53
+ * The exception is deliberate and cannot be moved by an input: the two
54
+ * machine-wide files (`<registryRoot>/harnesses.json`,
55
+ * `<hangarRoot>/jobs.jsonl`) are resolved from the environment, because
56
+ * a registry that only ever saw the current workspace would not be a
57
+ * registry. Each is reported, absolute, in every result that read it.
58
+ *
59
+ * WHAT THIS PACKAGE DOES NOT DO. It does not install or switch a CLI version
60
+ * (that is `@crewhaus/chvm` and the npm registry — see `CliVersionPin`), it
61
+ * never starts, stops or cancels anything (the job ledger is read-only here,
62
+ * and no cancel route exists in the store), and it does not execute a hook.
63
+ */
64
+ import { type JobState } from "@crewhaus/harness-supervisor";
65
+ import type { RegisteredTool } from "@crewhaus/tool-catalog";
66
+ export declare const harnessRegister: RegisteredTool;
67
+ /**
68
+ * The job states the ledger can hold, so a caller can filter on one.
69
+ *
70
+ * The constant below fails to COMPILE if `JobState` ever gains a member this
71
+ * list does not carry — the only kind of drift guard worth having, one that
72
+ * cannot pass vacuously.
73
+ */
74
+ declare const JOB_STATES: readonly ["pending", "running", "done", "failed", "cancelled", "interrupted"];
75
+ /** Compile-time proof that `JOB_STATES` covers every `JobState`. */
76
+ export declare const JOB_STATES_COVER_JOBSTATE: Exclude<JobState, (typeof JOB_STATES)[number]> extends never ? true : never;
77
+ export declare const harnessJobStatus: RegisteredTool;
78
+ export declare const compileBundle: RegisteredTool;
79
+ export declare const cliVersionPin: RegisteredTool;
80
+ export declare const hooksManage: RegisteredTool;
81
+ export {};