@crewhaus/tool-fleet 0.8.0 → 0.8.2

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 CHANGED
@@ -12,6 +12,13 @@ hooks that wrap a start.
12
12
  | `CliVersionPin` | which CLI each harness would run, which one built its bundle | `harness-supervisor` (`resolveCrewhausBin`, the bundle stamp) |
13
13
  | `HooksManage` | list / set / remove the manager hooks in `.crewhaus/settings.json` | `harness-supervisor` (`parseManagerHook`, `readManagerSettings`) |
14
14
 
15
+ On the harness it runs in, `HooksManage` is refused by the runtime-state floor, `list` included
16
+ (the tool is not read-only); it manages other harnesses as before.
17
+
18
+ `CompileBundle` of the working directory goes by the rules. Of another directory, it refuses, in
19
+ the preview and the real call alike, when the output, the entry or the manifest resolves into one
20
+ of the floor's roots, or when the output directory holds one.
21
+
15
22
  ## These tools are thin on purpose
16
23
 
17
24
  Everything they enforce belongs to a package they depend on. The registry file is written by
@@ -118,10 +125,19 @@ Paths a STORE hands back are contained too: `CliVersionPin` re-contains every re
118
125
  opening a spec or a bundle under it and reports the rest as skipped, and rows are deduped by real
119
126
  path so one harness cannot be counted twice in the version roll-up.
120
127
 
128
+ A row that a store hands back is treated the same way. `HarnessRegister` relocates or removes a row,
129
+ or sets its `hidden`, `groups`, `group` or `order`, only when the row's directory, resolved through
130
+ its symlinks, is inside the workspace or is gone, and a dry run answers the same as the real call.
131
+ Any other row is the operator's, and the refusal names the verb: `crewhaus harness relocate`,
132
+ `crewhaus harness remove`, `crewhaus harness group`, or the Library in `crewhaus hangar` for
133
+ `hidden`. `tags`, `notes` and `pinned` work on every row.
134
+
121
135
  The exception is deliberate and no input can move it. The two machine-wide files —
122
136
  `<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.
137
+ (`CREWHAUS_REGISTRY_ROOT`, `CREWHAUS_HANGAR_ROOT`) by `@crewhaus/harness-registry`'s
138
+ `resolveRegistryRoot` and `resolveHangarRoot`, the resolvers the CLI uses, because a registry that
139
+ only ever saw the current workspace would not be a registry. Their absolute paths are reported in
140
+ every result.
125
141
 
126
142
  `CompileBundle` executes `crewhaus compile`. The binary comes from the supervisor's own resolver —
127
143
  harness-local `node_modules/.bin/crewhaus` first, then `PATH` — and a binary that resolves OUTSIDE
package/dist/index.js CHANGED
@@ -67,10 +67,11 @@ import * as path from "node:path";
67
67
  import { HARNESS_ID_RE, openHangarRegistry, } from "@crewhaus/harness-registry";
68
68
  import { MANAGER_HOOK_NAMES, compileIfStale, compileOutDir, createFileJobStore, createProcessOps, hookLogPath, readHookRunLog, readManagerSettings, runPrepareCommand, } from "@crewhaus/harness-supervisor";
69
69
  import { buildTool } from "@crewhaus/tool-builder";
70
+ import { protectedRootBeneath, protectedRootHolding, protectedRootsOf, protectedWriteRefusal, } from "@crewhaus/tool-safety/fs";
70
71
  import { z } from "zod";
71
72
  import { CLI_VERSION_RE, externalBinRefusal, freshnessOf, readCliVersion, readSpecFacts, resolveCli, spawnEnv, } from "./lib/bundle";
72
73
  import { countByState, filterJobs, jobView, ledgerBlockedBy, parseIsoInstant, probeLedger, sortJobs, } from "./lib/jobs";
73
- import { entryView, mutationBlockedBy, probeRegistryFile, sortEntries } from "./lib/registry";
74
+ import { entryView, mutationBlockedBy, probeRegistryFile, rowDirIsElsewhere, sortEntries, } from "./lib/registry";
74
75
  import { compareStrings, contain, containExistingDir, containUnder, containWritePaths, isInside, json, refusal, renderPath, renderStorePath, renderText, sample, } from "./lib/result";
75
76
  import { jobLedgerPath, registryFilePath } from "./lib/roots";
76
77
  import { managerBlock, parseDeclaration, probeSettings, settingsAbsPath, settingsRelPath, splitWarning, timeoutView, viewHook, withHook, writeBlockedBy, writeSettingsFile, } from "./lib/settings";
@@ -207,6 +208,27 @@ const updateFields = {
207
208
  .optional()
208
209
  .describe("this member's 1-based boot order inside `group`; omit with `group` to clear it"),
209
210
  };
211
+ /**
212
+ * Where the operator makes the change a `HarnessRegister` call asks for, for
213
+ * each change this tool makes only on a row inside its workspace or gone. Empty
214
+ * for the rest: `register` and `list` select no row, and `tags`, `notes` and
215
+ * `pinned` annotate a row without changing where it runs or what starts it.
216
+ */
217
+ function operatorVerbsFor(input) {
218
+ const { action, groups, group, order, hidden } = input;
219
+ if (action === "relocate")
220
+ return ["`crewhaus harness relocate`"];
221
+ if (action === "remove")
222
+ return ["`crewhaus harness remove`"];
223
+ if (action !== "update")
224
+ return [];
225
+ return [
226
+ ...(groups !== undefined || group !== undefined || order !== undefined
227
+ ? ["`crewhaus harness group`"]
228
+ : []),
229
+ ...(hidden !== undefined ? ["the Library in `crewhaus hangar`"] : []),
230
+ ];
231
+ }
210
232
  export const harnessRegister = buildTool({
211
233
  name: "HarnessRegister",
212
234
  operativeArgs: [
@@ -419,6 +441,13 @@ export const harnessRegister = buildTool({
419
441
  const selectedId = entry.id;
420
442
  const selectedDir = entry.dir;
421
443
  const selected = entryView(entry, root);
444
+ // The tool works inside its workspace, and a row elsewhere is the
445
+ // operator's. Before the dry-run branches, so the preview says what the
446
+ // real call would do. A moved harness (old directory gone) stays open.
447
+ const operatorVerbs = operatorVerbsFor(input);
448
+ if (operatorVerbs.length > 0 && rowDirIsElsewhere(root, entry.dir)) {
449
+ return refusal(tool, "refused", `${selectedId} points at a directory outside this workspace that still exists. This change is the operator's: ${operatorVerbs.join(" or ")}.`, { ...base, entry: selected });
450
+ }
422
451
  if (action === "remove") {
423
452
  if (dryRun) {
424
453
  return json({
@@ -773,7 +802,7 @@ export const compileBundle = buildTool({
773
802
  destructive: true,
774
803
  scope: "external",
775
804
  ioCapability: "process",
776
- execute: async (input) => {
805
+ execute: async (input, ctx) => {
777
806
  const tool = "CompileBundle";
778
807
  const dryRun = input.dryRun ?? true;
779
808
  const root = workspaceRoot();
@@ -830,6 +859,26 @@ export const compileBundle = buildTool({
830
859
  ? { resolved: false }
831
860
  : { resolved: true, bin: cli.bin, where: cli.where, inWorkspace: cli.inWorkspace },
832
861
  };
862
+ // The working directory's own compile is the run's to ask for, and the
863
+ // floor leaves it to the rules. Any other directory's output, entry and
864
+ // manifest stay out of the runtime-state roots, with links followed, and
865
+ // its output directory holds none of them, since the install writes
866
+ // `node_modules` and the lockfile there: before the dryRun branch, so the
867
+ // preview and the real call refuse identically.
868
+ if (safe.value.rel !== "") {
869
+ const roots = protectedRootsOf(ctx);
870
+ const output = path.join(harness, outDir);
871
+ const written = [
872
+ output,
873
+ ...(located === undefined
874
+ ? []
875
+ : [located.entryPath, path.join(located.bundleDir, "package.json")]),
876
+ ];
877
+ if (written.some((name) => protectedRootHolding(name, roots, root) !== undefined) ||
878
+ protectedRootBeneath(output, roots, root) !== undefined) {
879
+ return refusal(tool, "refused", protectedWriteRefusal(tool, `compiling ${shownDir}`), view);
880
+ }
881
+ }
833
882
  if (dryRun) {
834
883
  return json({
835
884
  ...view,
@@ -30,6 +30,13 @@ export declare function probeRegistryFile(path: string): RegistryFileProbe;
30
30
  * not read with one built from `EMPTY_DOC`.
31
31
  */
32
32
  export declare function mutationBlockedBy(probe: RegistryFileProbe): Loaded<undefined>;
33
+ /**
34
+ * True when a row's directory exists and stands outside the workspace,
35
+ * resolved through its symlinks. Absent is the one answer that makes a row
36
+ * "gone": a directory that could not be read (a permission, a symlink loop) is
37
+ * still taken to be there, and judged by the path the row holds.
38
+ */
39
+ export declare function rowDirIsElsewhere(workspaceRoot: string, dir: string): boolean;
33
40
  /** The entry fields a result carries, in a stable order. */
34
41
  export type EntryView = Record<string, unknown>;
35
42
  /**
@@ -27,7 +27,7 @@
27
27
  * whose file exists but did not parse is REFUSED here, and a listing says
28
28
  * `unparseable` rather than reporting zero harnesses.
29
29
  */
30
- import { readFileSync } from "node:fs";
30
+ import { readFileSync, realpathSync } from "node:fs";
31
31
  import { compareStrings, fail, isInside, probeName, renderStorePath, renderText, } from "./result";
32
32
  /** Longest registry file this tool will read for its integrity probe. */
33
33
  const MAX_REGISTRY_BYTES = 32 * 1024 * 1024;
@@ -97,6 +97,23 @@ export function mutationBlockedBy(probe) {
97
97
  const shared = "@crewhaus/harness-registry reads an unusable registry as an EMPTY one and heals it on the next write, so proceeding would replace every row, group, tag and note in that file with an empty document. A registry that could not be read is not an empty registry.";
98
98
  return fail(probe.state === "unreadable" || probe.state === "not-a-file" ? "unreadable" : "refused", `${probe.path}: ${probe.detail ?? probe.state}. ${shared}`);
99
99
  }
100
+ /**
101
+ * True when a row's directory exists and stands outside the workspace,
102
+ * resolved through its symlinks. Absent is the one answer that makes a row
103
+ * "gone": a directory that could not be read (a permission, a symlink loop) is
104
+ * still taken to be there, and judged by the path the row holds.
105
+ */
106
+ export function rowDirIsElsewhere(workspaceRoot, dir) {
107
+ try {
108
+ return !isInside(workspaceRoot, realpathSync(dir));
109
+ }
110
+ catch (err) {
111
+ const code = err.code;
112
+ if (code === "ENOENT" || code === "ENOTDIR")
113
+ return false;
114
+ return !isInside(workspaceRoot, dir);
115
+ }
116
+ }
100
117
  /**
101
118
  * One registry row, shaped for a result.
102
119
  *
@@ -1,17 +1,11 @@
1
+ import { resolveHangarRoot } from "@crewhaus/harness-registry";
1
2
  /** `<registryRoot>/harnesses.json` — the file `openHangarRegistry` opens. */
2
3
  export declare function registryFilePath(env?: Readonly<Record<string, string | undefined>>): string;
3
4
  /**
4
- * The hangar root: `CREWHAUS_HANGAR_ROOT`, else `<registryRoot>/hangar`.
5
- *
6
- * MIRRORED, not imported. `resolveHangarRoot` lives in
7
- * `apps/cli/src/hangar-cmd.ts` and a package cannot depend on the app — the
8
- * same reason `harness-supervisor/src/bundle-freshness.ts` mirrors the
9
- * bundle manifest shape instead of importing it. The second half of the rule
10
- * is not re-derived: `resolveRegistryRoot` is the registry package's own.
11
- * `roots.test.ts` pins both halves, so a change in the app fails a test here
12
- * rather than silently pointing this tool at a ledger nobody writes.
5
+ * The hangar root (`CREWHAUS_HANGAR_ROOT`, else `<registryRoot>/hangar`),
6
+ * resolved by the registry package's own resolver, the one the CLI uses.
13
7
  */
14
- export declare function resolveHangarRoot(env?: Readonly<Record<string, string | undefined>>): string;
8
+ export { resolveHangarRoot };
15
9
  /** The durable job ledger the manager appends to. */
16
10
  export declare const JOB_LEDGER_FILENAME = "jobs.jsonl";
17
11
  /** `<hangarRoot>/jobs.jsonl` — the path `createFileJobStore` is opened on. */
package/dist/lib/roots.js CHANGED
@@ -17,32 +17,17 @@
17
17
  * directory, a settings file — still goes through `resolveSafe` and stays
18
18
  * inside the workspace.
19
19
  */
20
- import { join, resolve } from "node:path";
21
- import { REGISTRY_FILENAME, resolveRegistryRoot } from "@crewhaus/harness-registry";
20
+ import { join } from "node:path";
21
+ import { REGISTRY_FILENAME, resolveHangarRoot, resolveRegistryRoot, } from "@crewhaus/harness-registry";
22
22
  /** `<registryRoot>/harnesses.json` — the file `openHangarRegistry` opens. */
23
23
  export function registryFilePath(env = process.env) {
24
24
  return join(resolveRegistryRoot(env), REGISTRY_FILENAME);
25
25
  }
26
26
  /**
27
- * The hangar root: `CREWHAUS_HANGAR_ROOT`, else `<registryRoot>/hangar`.
28
- *
29
- * MIRRORED, not imported. `resolveHangarRoot` lives in
30
- * `apps/cli/src/hangar-cmd.ts` and a package cannot depend on the app — the
31
- * same reason `harness-supervisor/src/bundle-freshness.ts` mirrors the
32
- * bundle manifest shape instead of importing it. The second half of the rule
33
- * is not re-derived: `resolveRegistryRoot` is the registry package's own.
34
- * `roots.test.ts` pins both halves, so a change in the app fails a test here
35
- * rather than silently pointing this tool at a ledger nobody writes.
27
+ * The hangar root (`CREWHAUS_HANGAR_ROOT`, else `<registryRoot>/hangar`),
28
+ * resolved by the registry package's own resolver, the one the CLI uses.
36
29
  */
37
- export function resolveHangarRoot(env = process.env) {
38
- const explicit = env["CREWHAUS_HANGAR_ROOT"];
39
- // `resolve`, like the app's copy: a relative CREWHAUS_HANGAR_ROOT must
40
- // become the same absolute path the manager opened, not one relative to
41
- // whatever directory this tool happens to run in.
42
- if (explicit !== undefined && explicit !== "")
43
- return resolve(explicit);
44
- return join(resolveRegistryRoot(env), "hangar");
45
- }
30
+ export { resolveHangarRoot };
46
31
  /** The durable job ledger the manager appends to. */
47
32
  export const JOB_LEDGER_FILENAME = "jobs.jsonl";
48
33
  /** `<hangarRoot>/jobs.jsonl` — the path `createFileJobStore` is opened on. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crewhaus/tool-fleet",
3
- "version": "0.8.0",
3
+ "version": "0.8.2",
4
4
  "type": "module",
5
5
  "description": "Deterministic fleet operations: register, recompile, version-pin and inspect the harnesses on this machine",
6
6
  "main": "dist/index.js",
@@ -16,13 +16,13 @@
16
16
  "test": "bun test src"
17
17
  },
18
18
  "dependencies": {
19
- "@crewhaus/errors": "0.8.0",
20
- "@crewhaus/harness-registry": "0.8.0",
21
- "@crewhaus/harness-supervisor": "0.8.0",
22
- "@crewhaus/spec": "0.8.0",
23
- "@crewhaus/tool-builder": "0.8.0",
24
- "@crewhaus/tool-catalog": "0.8.0",
25
- "@crewhaus/tool-safety": "0.8.0",
19
+ "@crewhaus/errors": "0.8.2",
20
+ "@crewhaus/harness-registry": "0.8.2",
21
+ "@crewhaus/harness-supervisor": "0.8.2",
22
+ "@crewhaus/spec": "0.8.2",
23
+ "@crewhaus/tool-builder": "0.8.2",
24
+ "@crewhaus/tool-catalog": "0.8.2",
25
+ "@crewhaus/tool-safety": "0.8.2",
26
26
  "zod": "^3.23.8"
27
27
  },
28
28
  "devDependencies": {