@serfab/cadre-host 1.10.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-host",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "type": "module",
   "description": "Self-hosted cadre node manager for basement-PC deployments",
   "main": "dist/index.js",
@@ -65,9 +65,9 @@
     "@libp2p/interface": "^3.3.0",
     "@libp2p/peer-id": "^6.0.15",
     "@multiformats/multiaddr": "^13.0.3",
-    "@serfab/cadre-cli": "^1.10.0",
-    "@serfab/cadre-core": "^1.10.0",
-    "@serfab/cadre-provider": "^1.10.0",
+    "@serfab/cadre-cli": "^1.12.0",
+    "@serfab/cadre-core": "^1.12.0",
+    "@serfab/cadre-provider": "^1.12.0",
     "commander": "^14.0.2",
     "debug": "^4.4.3",
     "fastify": "^5.7.1",

package/src/__tests__/global-setup.ts

@@ -1,58 +1,58 @@
-/**
- * Vitest global setup — runs once before the whole cadre-host suite.
- *
- * `src/update/manifest.ts` and `src/push/index.ts` import real symbols from
- * `@serfab/cadre-core` (`canonicalJson`, `validatePushCredentials`), and
- * `trust-circle-integration.test.ts` imports and drives a real `CadreNode` from
- * it too. `@serfab/cadre-core`'s compiled entry point in turn imports
- * `@serfab/quereus-plugin-sereus`, which imports the `@optimystic/*` and
- * `@quereus/quereus` packages linked in from their sibling checkouts.
- * `host-process-orchestrator.ts` also resolves `@serfab/cadre-cli`'s bin path at
- * runtime, and `@serfab/cadre-provider` is a declared dependency in its own
- * right. Every one of those resolves through a `node_modules` symlink whose
- * manifest points at `dist`, so an edit to any of their `src` with no following
- * build is invisible here: the suite runs the previous build and reports green
- * about code it never executed. Fail the run up front instead.
- *
- * NOTE: accepted tradeoff — this does not cover cadre-host's *own* `src` going
- * stale relative to its own `dist`. The CLI smoke tests spawn `dist/bin/host.js`
- * as a child process, which is a same-package staleness concern, not the
- * cross-package one `BuildTarget` is meant to check (see
- * `test-harness/build-freshness.ts`'s module comment). Consequence: a `src`-only
- * edit to `bin/host.ts` is checked by `bin/__tests__/cli-reference.test.ts`
- * (which reads `src`) but not by the smoke tests (which read `dist`), so run
- * `yarn workspace @serfab/cadre-host build:server` before the suite. Revisit if
- * a stale `dist` ever produces a false green rather than merely a weaker check.
- *
- * The guard itself lives at the repo root (`test-harness/build-freshness.ts`),
- * shared with the other suites that call it; the list of packages below is this
- * suite's own concern.
- */
-
-import { assertBuildFresh, type BuildTarget } from '../../../../test-harness/build-freshness.js';
-
-/**
- * Every package this suite runs compiled code from — the `workspace:` entries of
- * `package.json`'s `dependencies`, plus the `link:` packages reached
- * transitively through them.
- *
- * Exported so `build-targets.test.ts` can hold it against this package's actual
- * `dependencies` — a hand-written list rots silently otherwise.
- */
-export const TARGETS: BuildTarget[] = [
-	{ packageName: '@serfab/cadre-cli', distEntry: 'dist/bin/cadre.js', location: 'workspace' },
-	{ packageName: '@serfab/cadre-core', distEntry: 'dist/index.js', location: 'workspace' },
-	{ packageName: '@serfab/cadre-provider', distEntry: 'dist/index.js', location: 'workspace' },
-	// Reached through `@serfab/cadre-cli`, whose spawned `dist` loads it.
-	{ packageName: '@serfab/config-check', distEntry: 'dist/index.js', location: 'workspace' },
-	{ packageName: '@serfab/quereus-plugin-sereus', distEntry: 'dist/index.js', location: 'workspace' },
-	{ packageName: '@optimystic/db-core', distEntry: 'dist/src/index.js', location: 'linked' },
-	{ packageName: '@optimystic/db-p2p', distEntry: 'dist/src/index.js', location: 'linked' },
-	{ packageName: '@optimystic/quereus-plugin-crypto', distEntry: 'dist/index.js', location: 'linked' },
-	{ packageName: '@optimystic/quereus-plugin-optimystic', distEntry: 'dist/index.js', location: 'linked' },
-	{ packageName: '@quereus/quereus', distEntry: 'dist/src/index.js', location: 'linked' },
-];
-
-export default function setup(): void {
-	assertBuildFresh(TARGETS, import.meta.url);
-}
+/**
+ * Vitest global setup — runs once before the whole cadre-host suite.
+ *
+ * `src/update/manifest.ts` and `src/push/index.ts` import real symbols from
+ * `@serfab/cadre-core` (`canonicalJson`, `validatePushCredentials`), and
+ * `trust-circle-integration.test.ts` imports and drives a real `CadreNode` from
+ * it too. `@serfab/cadre-core`'s compiled entry point in turn imports
+ * `@serfab/quereus-plugin-sereus`, which imports the `@optimystic/*` and
+ * `@quereus/quereus` packages linked in from their sibling checkouts.
+ * `host-process-orchestrator.ts` also resolves `@serfab/cadre-cli`'s bin path at
+ * runtime, and `@serfab/cadre-provider` is a declared dependency in its own
+ * right. Every one of those resolves through a `node_modules` symlink whose
+ * manifest points at `dist`, so an edit to any of their `src` with no following
+ * build is invisible here: the suite runs the previous build and reports green
+ * about code it never executed. Fail the run up front instead.
+ *
+ * NOTE: accepted tradeoff — this does not cover cadre-host's *own* `src` going
+ * stale relative to its own `dist`. The CLI smoke tests spawn `dist/bin/host.js`
+ * as a child process, which is a same-package staleness concern, not the
+ * cross-package one `BuildTarget` is meant to check (see
+ * `test-harness/build-freshness.ts`'s module comment). Consequence: a `src`-only
+ * edit to `bin/host.ts` is checked by `bin/__tests__/cli-reference.test.ts`
+ * (which reads `src`) but not by the smoke tests (which read `dist`), so run
+ * `yarn workspace @serfab/cadre-host build:server` before the suite. Revisit if
+ * a stale `dist` ever produces a false green rather than merely a weaker check.
+ *
+ * The guard itself lives at the repo root (`test-harness/build-freshness.ts`),
+ * shared with the other suites that call it; the list of packages below is this
+ * suite's own concern.
+ */
+
+import { assertBuildFresh, type BuildTarget } from '../../../../test-harness/build-freshness.js';
+
+/**
+ * Every package this suite runs compiled code from — the `workspace:` entries of
+ * `package.json`'s `dependencies`, plus the `link:` packages reached
+ * transitively through them.
+ *
+ * Exported so `build-targets.test.ts` can hold it against this package's actual
+ * `dependencies` — a hand-written list rots silently otherwise.
+ */
+export const TARGETS: BuildTarget[] = [
+	{ packageName: '@serfab/cadre-cli', distEntry: 'dist/bin/cadre.js', location: 'workspace' },
+	{ packageName: '@serfab/cadre-core', distEntry: 'dist/index.js', location: 'workspace' },
+	{ packageName: '@serfab/cadre-provider', distEntry: 'dist/index.js', location: 'workspace' },
+	// Reached through `@serfab/cadre-cli`, whose spawned `dist` loads it.
+	{ packageName: '@serfab/config-check', distEntry: 'dist/index.js', location: 'workspace' },
+	{ packageName: '@serfab/quereus-plugin-sereus', distEntry: 'dist/index.js', location: 'workspace' },
+	{ packageName: '@optimystic/db-core', distEntry: 'dist/src/index.js', location: 'linked' },
+	{ packageName: '@optimystic/db-p2p', distEntry: 'dist/src/index.js', location: 'linked' },
+	{ packageName: '@optimystic/quereus-plugin-crypto', distEntry: 'dist/index.js', location: 'linked' },
+	{ packageName: '@optimystic/quereus-plugin-optimystic', distEntry: 'dist/index.js', location: 'linked' },
+	{ packageName: '@quereus/quereus', distEntry: 'dist/src/index.js', location: 'linked' },
+];
+
+export default function setup(): void {
+	assertBuildFresh(TARGETS, import.meta.url);
+}

package/src/__tests__/orchestrator-handle-contract.ts

@@ -1,134 +1,134 @@
-/**
- * The handle rules `HostProcessOrchestrator` and its test stand-in
- * `FakeOrchestrator` (`donation/__tests__/fake-orchestrator.ts`) must both obey,
- * written once and run against each: `orchestrator.test.ts` registers them over
- * the real class, `fake-orchestrator.test.ts` over the fake. A rule one of them
- * stops obeying fails in that file's run.
- *
- * Not a `.test.ts` file, so vitest does not collect it on its own.
- *
- * Only what both classes can satisfy belongs here — no ports, no files on disk,
- * none of the fake's recording arrays. Those stay in the two calling files.
- */
-
-import { describe, expect, it } from 'vitest';
-
-import type { OrchestratorCreateRequest, OrchestratorCreateResult } from '@serfab/cadre-provider';
-
-import type { HostProcessOrchestrator } from '../orchestrator/host-process-orchestrator.js';
-
-/** What the contract needs from either orchestrator. */
-export type ContractOrchestrator = Pick<
-  HostProcessOrchestrator,
-  'createContainer' | 'stopContainer' | 'removeContainer' | 'resolveDockerId'
->;
-
-export interface HandleContractHarness<O extends ContractOrchestrator> {
-  /** A fresh orchestrator. Teardown is the calling file's own afterEach. */
-  make(): O;
-  request(containerId: string): OrchestratorCreateRequest;
-  /** Resolve once the spawn named by `dockerId` reads as running. */
-  started(orch: O, dockerId: string): Promise<void>;
-  /**
-   * Make `createContainer` for `containerId` throw from here on. Only called
-   * after that container has been spawned once and stopped, and no case creates
-   * again afterwards.
-   */
-  failNextCreate(orch: O, containerId: string): void;
-}
-
-const CONTAINER = 'grn_contract_a';
-const OTHER_CONTAINER = 'grn_contract_b';
-
-export function describeHandleContract<O extends ContractOrchestrator>(
-  label: string,
-  harness: HandleContractHarness<O>,
-): void {
-  async function spawn(orch: O, containerId: string): Promise<OrchestratorCreateResult> {
-    const result = await orch.createContainer(harness.request(containerId));
-    await harness.started(orch, result.dockerId);
-    return result;
-  }
-
-  // Stops first: a container whose previous child is still running is refused.
-  async function respawn(orch: O, containerId: string, previousDockerId: string): Promise<OrchestratorCreateResult> {
-    await orch.stopContainer(previousDockerId);
-    return spawn(orch, containerId);
-  }
-
-  describe(`${label} handle contract`, () => {
-    it('rejects a dockerId it never issued', async () => {
-      const orch = harness.make();
-
-      await expectNotFound(orch.stopContainer('never-issued'), 'never-issued');
-      await expectNotFound(orch.removeContainer('never-issued'), 'never-issued');
-    });
-
-    it('rejects a dockerId once its container has been removed', async () => {
-      const orch = harness.make();
-      const { dockerId } = await spawn(orch, CONTAINER);
-      await orch.stopContainer(dockerId);
-
-      await orch.removeContainer(dockerId);
-
-      await expectNotFound(orch.stopContainer(dockerId), dockerId);
-      await expectNotFound(orch.removeContainer(dockerId), dockerId);
-    });
-
-    it('replaces the first spawn\'s dockerId when the container re-spawns', async () => {
-      const orch = harness.make();
-      const first = await spawn(orch, CONTAINER);
-
-      const second = await respawn(orch, CONTAINER, first.dockerId);
-
-      await expectNotFound(orch.stopContainer(first.dockerId), first.dockerId);
-      expect(orch.resolveDockerId(CONTAINER)).toBe(second.dockerId);
-      await expect(orch.stopContainer(second.dockerId)).resolves.toBeUndefined();
-    });
-
-    // Launching over a live child hands its ports to a second child that then
-    // dies on them, while the caller records the new dockerId and seed token.
-    it('refuses to re-spawn a container whose previous child is still running', async () => {
-      const orch = harness.make();
-      const first = await spawn(orch, CONTAINER);
-
-      await expect(orch.createContainer(harness.request(CONTAINER)))
-        .rejects.toHaveProperty('message', `container ${CONTAINER} is still running`);
-
-      expect(orch.resolveDockerId(CONTAINER)).toBe(first.dockerId);
-      await expect(orch.stopContainer(first.dockerId)).resolves.toBeUndefined();
-    });
-
-    // The drop on re-spawn filters on containerId; an orchestrator that cleared
-    // every handle would still pass the same-container case above.
-    it('leaves another container\'s dockerId alone when one container re-spawns', async () => {
-      const orch = harness.make();
-      const other = await spawn(orch, OTHER_CONTAINER);
-      const first = await spawn(orch, CONTAINER);
-
-      await respawn(orch, CONTAINER, first.dockerId);
-
-      expect(orch.resolveDockerId(OTHER_CONTAINER)).toBe(other.dockerId);
-      await expect(orch.stopContainer(other.dockerId)).resolves.toBeUndefined();
-    });
-
-    // What lets a caller still clean up the node it knows about after a re-spawn
-    // that did not happen.
-    it('keeps the first spawn\'s dockerId when the re-spawn fails', async () => {
-      const orch = harness.make();
-      const first = await spawn(orch, CONTAINER);
-      await orch.stopContainer(first.dockerId);
-
-      harness.failNextCreate(orch, CONTAINER);
-      await expect(orch.createContainer(harness.request(CONTAINER))).rejects.toThrow();
-
-      expect(orch.resolveDockerId(CONTAINER)).toBe(first.dockerId);
-      await expect(orch.removeContainer(first.dockerId)).resolves.toBeUndefined();
-    });
-  });
-}
-
-/** The whole message, not a substring, so the two classes cannot come to word it differently. */
-async function expectNotFound(call: Promise<void>, dockerId: string): Promise<void> {
-  await expect(call).rejects.toHaveProperty('message', `Container not found: ${dockerId}`);
-}
+/**
+ * The handle rules `HostProcessOrchestrator` and its test stand-in
+ * `FakeOrchestrator` (`donation/__tests__/fake-orchestrator.ts`) must both obey,
+ * written once and run against each: `orchestrator.test.ts` registers them over
+ * the real class, `fake-orchestrator.test.ts` over the fake. A rule one of them
+ * stops obeying fails in that file's run.
+ *
+ * Not a `.test.ts` file, so vitest does not collect it on its own.
+ *
+ * Only what both classes can satisfy belongs here — no ports, no files on disk,
+ * none of the fake's recording arrays. Those stay in the two calling files.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import type { OrchestratorCreateRequest, OrchestratorCreateResult } from '@serfab/cadre-provider';
+
+import type { HostProcessOrchestrator } from '../orchestrator/host-process-orchestrator.js';
+
+/** What the contract needs from either orchestrator. */
+export type ContractOrchestrator = Pick<
+  HostProcessOrchestrator,
+  'createContainer' | 'stopContainer' | 'removeContainer' | 'resolveDockerId'
+>;
+
+export interface HandleContractHarness<O extends ContractOrchestrator> {
+  /** A fresh orchestrator. Teardown is the calling file's own afterEach. */
+  make(): O;
+  request(containerId: string): OrchestratorCreateRequest;
+  /** Resolve once the spawn named by `dockerId` reads as running. */
+  started(orch: O, dockerId: string): Promise<void>;
+  /**
+   * Make `createContainer` for `containerId` throw from here on. Only called
+   * after that container has been spawned once and stopped, and no case creates
+   * again afterwards.
+   */
+  failNextCreate(orch: O, containerId: string): void;
+}
+
+const CONTAINER = 'grn_contract_a';
+const OTHER_CONTAINER = 'grn_contract_b';
+
+export function describeHandleContract<O extends ContractOrchestrator>(
+  label: string,
+  harness: HandleContractHarness<O>,
+): void {
+  async function spawn(orch: O, containerId: string): Promise<OrchestratorCreateResult> {
+    const result = await orch.createContainer(harness.request(containerId));
+    await harness.started(orch, result.dockerId);
+    return result;
+  }
+
+  // Stops first: a container whose previous child is still running is refused.
+  async function respawn(orch: O, containerId: string, previousDockerId: string): Promise<OrchestratorCreateResult> {
+    await orch.stopContainer(previousDockerId);
+    return spawn(orch, containerId);
+  }
+
+  describe(`${label} handle contract`, () => {
+    it('rejects a dockerId it never issued', async () => {
+      const orch = harness.make();
+
+      await expectNotFound(orch.stopContainer('never-issued'), 'never-issued');
+      await expectNotFound(orch.removeContainer('never-issued'), 'never-issued');
+    });
+
+    it('rejects a dockerId once its container has been removed', async () => {
+      const orch = harness.make();
+      const { dockerId } = await spawn(orch, CONTAINER);
+      await orch.stopContainer(dockerId);
+
+      await orch.removeContainer(dockerId);
+
+      await expectNotFound(orch.stopContainer(dockerId), dockerId);
+      await expectNotFound(orch.removeContainer(dockerId), dockerId);
+    });
+
+    it('replaces the first spawn\'s dockerId when the container re-spawns', async () => {
+      const orch = harness.make();
+      const first = await spawn(orch, CONTAINER);
+
+      const second = await respawn(orch, CONTAINER, first.dockerId);
+
+      await expectNotFound(orch.stopContainer(first.dockerId), first.dockerId);
+      expect(orch.resolveDockerId(CONTAINER)).toBe(second.dockerId);
+      await expect(orch.stopContainer(second.dockerId)).resolves.toBeUndefined();
+    });
+
+    // Launching over a live child hands its ports to a second child that then
+    // dies on them, while the caller records the new dockerId and seed token.
+    it('refuses to re-spawn a container whose previous child is still running', async () => {
+      const orch = harness.make();
+      const first = await spawn(orch, CONTAINER);
+
+      await expect(orch.createContainer(harness.request(CONTAINER)))
+        .rejects.toHaveProperty('message', `container ${CONTAINER} is still running`);
+
+      expect(orch.resolveDockerId(CONTAINER)).toBe(first.dockerId);
+      await expect(orch.stopContainer(first.dockerId)).resolves.toBeUndefined();
+    });
+
+    // The drop on re-spawn filters on containerId; an orchestrator that cleared
+    // every handle would still pass the same-container case above.
+    it('leaves another container\'s dockerId alone when one container re-spawns', async () => {
+      const orch = harness.make();
+      const other = await spawn(orch, OTHER_CONTAINER);
+      const first = await spawn(orch, CONTAINER);
+
+      await respawn(orch, CONTAINER, first.dockerId);
+
+      expect(orch.resolveDockerId(OTHER_CONTAINER)).toBe(other.dockerId);
+      await expect(orch.stopContainer(other.dockerId)).resolves.toBeUndefined();
+    });
+
+    // What lets a caller still clean up the node it knows about after a re-spawn
+    // that did not happen.
+    it('keeps the first spawn\'s dockerId when the re-spawn fails', async () => {
+      const orch = harness.make();
+      const first = await spawn(orch, CONTAINER);
+      await orch.stopContainer(first.dockerId);
+
+      harness.failNextCreate(orch, CONTAINER);
+      await expect(orch.createContainer(harness.request(CONTAINER))).rejects.toThrow();
+
+      expect(orch.resolveDockerId(CONTAINER)).toBe(first.dockerId);
+      await expect(orch.removeContainer(first.dockerId)).resolves.toBeUndefined();
+    });
+  });
+}
+
+/** The whole message, not a substring, so the two classes cannot come to word it differently. */
+async function expectNotFound(call: Promise<void>, dockerId: string): Promise<void> {
+  await expect(call).rejects.toHaveProperty('message', `Container not found: ${dockerId}`);
+}