@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
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.
|
package/dist/index.d.ts
ADDED
|
@@ -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 {};
|