@serfab/cadre-host 0.10.0 → 0.12.0

package/src/__tests__/cli-nat.smoke.test.ts

@@ -1,212 +1,212 @@
-/**
- * CLI smoke test for the `nat` subcommand. Spawns a stub HTTP server playing
- * the role of cadre-host's management API and asserts the CLI:
- *   - GETs /nat/status
- *   - POSTs /nat/test
- *   - PUTs /nat/ddns with the expected body
- *   - PUTs /nat/settings
- *   - Exits non-zero when the host is not reachable
- *
- * Relies on `yarn build` having produced dist/bin/host.js.
- */
-
-import { spawn } from 'node:child_process';
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
-import { existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, resolve } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-const here = dirname(fileURLToPath(import.meta.url));
-const binPath = resolve(here, '../../dist/bin/host.js');
-
-// These smoke tests cold-start the built CLI as a child process (Node boot +,
-// for some, an HTTP server). That comfortably exceeds vitest's 5s default under
-// heavy parallel load, so give the subprocess generous headroom.
-vi.setConfig({ testTimeout: 30000 });
-
-interface StubServer {
-  server: Server;
-  port: number;
-  requests: Array<{ method: string; url: string; body: string }>;
-  setResponse(handler: (req: IncomingMessage, res: ServerResponse) => void): void;
-}
-
-const DEFAULT_STATUS = {
-  portMode: 'auto-upnp',
-  externalPort: 4001,
-  internalPort: 4001,
-  routerExternalIp: '203.0.113.5',
-  mappingLeaseExpiresAt: null,
-  externalIp: '203.0.113.5',
-  externalIpDetectedAt: new Date().toISOString(),
-  cgnatDetected: false,
-  directReachability: 'reachable',
-  lastTestedAt: null,
-  ddns: {
-    providerId: 'duckdns',
-    hostname: 'foo.duckdns.org',
-    externallyManaged: false,
-    lastUpdateAt: null,
-    lastUpdateOk: null,
-    lastError: null,
-  },
-};
-
-async function startStub(): Promise<StubServer> {
-  const requests: StubServer['requests'] = [];
-  let handler: (req: IncomingMessage, res: ServerResponse) => void = (_req, res) => {
-    res.statusCode = 200;
-    res.setHeader('content-type', 'application/json');
-    res.end(JSON.stringify(DEFAULT_STATUS));
-  };
-
-  const server = createServer((req, res) => {
-    const chunks: Buffer[] = [];
-    req.on('data', (chunk: Buffer) => chunks.push(chunk));
-    req.on('end', () => {
-      requests.push({ method: req.method ?? '', url: req.url ?? '', body: Buffer.concat(chunks).toString('utf8') });
-      handler(req, res);
-    });
-  });
-
-  await new Promise<void>((resolveStart) => server.listen(0, '127.0.0.1', () => resolveStart()));
-  const addr = server.address();
-  const port = typeof addr === 'object' && addr ? addr.port : 0;
-  return {
-    server,
-    port,
-    requests,
-    setResponse: (h) => { handler = h; },
-  };
-}
-
-function runCli(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
-  return new Promise((resolveRun) => {
-    const child = spawn(process.execPath, [binPath, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8'); });
-    child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8'); });
-    child.on('close', (code) => resolveRun({ code: code ?? -1, stdout, stderr }));
-  });
-}
-
-let stub: StubServer;
-
-beforeEach(async () => {
-  if (!existsSync(binPath)) {
-    throw new Error(`cadre-host bin not built at ${binPath}; run \`yarn build\` first`);
-  }
-  stub = await startStub();
-});
-
-afterEach(async () => {
-  await new Promise<void>((resolveClose) => stub.server.close(() => resolveClose()));
-});
-
-describe('cadre-host nat status', () => {
-  it('GETs /nat/status and renders the snapshot', async () => {
-    const result = await runCli(['nat', 'status', '--port', String(stub.port)]);
-    expect(result.code).toBe(0);
-    expect(stub.requests).toHaveLength(1);
-    expect(stub.requests[0]!.method).toBe('GET');
-    expect(stub.requests[0]!.url).toBe('/nat/status');
-    expect(result.stdout).toContain('auto-upnp');
-    expect(result.stdout).toContain('203.0.113.5');
-    expect(result.stdout).toContain('foo.duckdns.org');
-  });
-
-  it('--json prints raw JSON', async () => {
-    const result = await runCli(['nat', 'status', '--port', String(stub.port), '--json']);
-    expect(result.code).toBe(0);
-    const parsed = JSON.parse(result.stdout);
-    expect(parsed.portMode).toBe('auto-upnp');
-  });
-
-  it('exits 2 when cadre-host is unreachable', async () => {
-    const port = stub.port;
-    await new Promise<void>((resolveClose) => stub.server.close(() => resolveClose()));
-    const result = await runCli(['nat', 'status', '--port', String(port)]);
-    expect(result.code).toBe(2);
-    expect(result.stderr).toMatch(/cadre-host start|Failed to reach/);
-  });
-});
-
-describe('cadre-host nat test', () => {
-  it('POSTs /nat/test', async () => {
-    const result = await runCli(['nat', 'test', '--port', String(stub.port)]);
-    expect(result.code).toBe(0);
-    expect(stub.requests[0]!.method).toBe('POST');
-    expect(stub.requests[0]!.url).toBe('/nat/test');
-  });
-});
-
-describe('cadre-host nat ddns set', () => {
-  it('PUTs /nat/ddns with provider + hostname + token', async () => {
-    const result = await runCli([
-      'nat', 'ddns', 'set', 'duckdns',
-      '--hostname', 'foo.duckdns.org',
-      '--token', 'TOK',
-      '--port', String(stub.port),
-    ]);
-    expect(result.code).toBe(0);
-    expect(stub.requests[0]!.method).toBe('PUT');
-    expect(stub.requests[0]!.url).toBe('/nat/ddns');
-    const body = JSON.parse(stub.requests[0]!.body);
-    expect(body.providerId).toBe('duckdns');
-    expect(body.hostname).toBe('foo.duckdns.org');
-    expect(body.config).toEqual({ token: 'TOK' });
-  });
-
-  it('exits 1 when --hostname is missing', async () => {
-    const result = await runCli([
-      'nat', 'ddns', 'set', 'duckdns',
-      '--token', 'TOK',
-      '--port', String(stub.port),
-    ]);
-    expect(result.code).toBe(1);
-    expect(result.stderr).toMatch(/--hostname/);
-  });
-
-  it('exits 1 when --token is missing on a non-TTY stdin', async () => {
-    const result = await runCli([
-      'nat', 'ddns', 'set', 'duckdns',
-      '--hostname', 'foo.duckdns.org',
-      '--port', String(stub.port),
-    ]);
-    expect(result.code).toBe(1);
-    expect(result.stderr).toMatch(/--token/);
-  });
-});
-
-describe('cadre-host nat ddns external', () => {
-  it('PUTs /nat/settings with externallyManaged=true', async () => {
-    const result = await runCli([
-      'nat', 'ddns', 'external',
-      '--hostname', 'mydomain.example.com',
-      '--port', String(stub.port),
-    ]);
-    expect(result.code).toBe(0);
-    expect(stub.requests[0]!.method).toBe('PUT');
-    expect(stub.requests[0]!.url).toBe('/nat/settings');
-    const body = JSON.parse(stub.requests[0]!.body);
-    expect(body.ddns.hostname).toBe('mydomain.example.com');
-    expect(body.ddns.externallyManaged).toBe(true);
-  });
-});
-
-describe('cadre-host nat settings', () => {
-  it('PUTs /nat/settings with --external-port and --no-upnp', async () => {
-    const result = await runCli([
-      'nat', 'settings',
-      '--external-port', '4002',
-      '--no-upnp',
-      '--port', String(stub.port),
-    ]);
-    expect(result.code).toBe(0);
-    const body = JSON.parse(stub.requests[0]!.body);
-    expect(body.externalPort).toBe(4002);
-    expect(body.upnpEnabled).toBe(false);
-  });
-});
+/**
+ * CLI smoke test for the `nat` subcommand. Spawns a stub HTTP server playing
+ * the role of cadre-host's management API and asserts the CLI:
+ *   - GETs /nat/status
+ *   - POSTs /nat/test
+ *   - PUTs /nat/ddns with the expected body
+ *   - PUTs /nat/settings
+ *   - Exits non-zero when the host is not reachable
+ *
+ * Relies on `yarn build` having produced dist/bin/host.js.
+ */
+
+import { spawn } from 'node:child_process';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const binPath = resolve(here, '../../dist/bin/host.js');
+
+// These smoke tests cold-start the built CLI as a child process (Node boot +,
+// for some, an HTTP server). That comfortably exceeds vitest's 5s default under
+// heavy parallel load, so give the subprocess generous headroom.
+vi.setConfig({ testTimeout: 30000 });
+
+interface StubServer {
+  server: Server;
+  port: number;
+  requests: Array<{ method: string; url: string; body: string }>;
+  setResponse(handler: (req: IncomingMessage, res: ServerResponse) => void): void;
+}
+
+const DEFAULT_STATUS = {
+  portMode: 'auto-upnp',
+  externalPort: 4001,
+  internalPort: 4001,
+  routerExternalIp: '203.0.113.5',
+  mappingLeaseExpiresAt: null,
+  externalIp: '203.0.113.5',
+  externalIpDetectedAt: new Date().toISOString(),
+  cgnatDetected: false,
+  directReachability: 'reachable',
+  lastTestedAt: null,
+  ddns: {
+    providerId: 'duckdns',
+    hostname: 'foo.duckdns.org',
+    externallyManaged: false,
+    lastUpdateAt: null,
+    lastUpdateOk: null,
+    lastError: null,
+  },
+};
+
+async function startStub(): Promise<StubServer> {
+  const requests: StubServer['requests'] = [];
+  let handler: (req: IncomingMessage, res: ServerResponse) => void = (_req, res) => {
+    res.statusCode = 200;
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify(DEFAULT_STATUS));
+  };
+
+  const server = createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => {
+      requests.push({ method: req.method ?? '', url: req.url ?? '', body: Buffer.concat(chunks).toString('utf8') });
+      handler(req, res);
+    });
+  });
+
+  await new Promise<void>((resolveStart) => server.listen(0, '127.0.0.1', () => resolveStart()));
+  const addr = server.address();
+  const port = typeof addr === 'object' && addr ? addr.port : 0;
+  return {
+    server,
+    port,
+    requests,
+    setResponse: (h) => { handler = h; },
+  };
+}
+
+function runCli(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise((resolveRun) => {
+    const child = spawn(process.execPath, [binPath, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8'); });
+    child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8'); });
+    child.on('close', (code) => resolveRun({ code: code ?? -1, stdout, stderr }));
+  });
+}
+
+let stub: StubServer;
+
+beforeEach(async () => {
+  if (!existsSync(binPath)) {
+    throw new Error(`cadre-host bin not built at ${binPath}; run \`yarn build\` first`);
+  }
+  stub = await startStub();
+});
+
+afterEach(async () => {
+  await new Promise<void>((resolveClose) => stub.server.close(() => resolveClose()));
+});
+
+describe('cadre-host nat status', () => {
+  it('GETs /nat/status and renders the snapshot', async () => {
+    const result = await runCli(['nat', 'status', '--port', String(stub.port)]);
+    expect(result.code).toBe(0);
+    expect(stub.requests).toHaveLength(1);
+    expect(stub.requests[0]!.method).toBe('GET');
+    expect(stub.requests[0]!.url).toBe('/nat/status');
+    expect(result.stdout).toContain('auto-upnp');
+    expect(result.stdout).toContain('203.0.113.5');
+    expect(result.stdout).toContain('foo.duckdns.org');
+  });
+
+  it('--json prints raw JSON', async () => {
+    const result = await runCli(['nat', 'status', '--port', String(stub.port), '--json']);
+    expect(result.code).toBe(0);
+    const parsed = JSON.parse(result.stdout);
+    expect(parsed.portMode).toBe('auto-upnp');
+  });
+
+  it('exits 2 when cadre-host is unreachable', async () => {
+    const port = stub.port;
+    await new Promise<void>((resolveClose) => stub.server.close(() => resolveClose()));
+    const result = await runCli(['nat', 'status', '--port', String(port)]);
+    expect(result.code).toBe(2);
+    expect(result.stderr).toMatch(/cadre-host start|Failed to reach/);
+  });
+});
+
+describe('cadre-host nat test', () => {
+  it('POSTs /nat/test', async () => {
+    const result = await runCli(['nat', 'test', '--port', String(stub.port)]);
+    expect(result.code).toBe(0);
+    expect(stub.requests[0]!.method).toBe('POST');
+    expect(stub.requests[0]!.url).toBe('/nat/test');
+  });
+});
+
+describe('cadre-host nat ddns set', () => {
+  it('PUTs /nat/ddns with provider + hostname + token', async () => {
+    const result = await runCli([
+      'nat', 'ddns', 'set', 'duckdns',
+      '--hostname', 'foo.duckdns.org',
+      '--token', 'TOK',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(0);
+    expect(stub.requests[0]!.method).toBe('PUT');
+    expect(stub.requests[0]!.url).toBe('/nat/ddns');
+    const body = JSON.parse(stub.requests[0]!.body);
+    expect(body.providerId).toBe('duckdns');
+    expect(body.hostname).toBe('foo.duckdns.org');
+    expect(body.config).toEqual({ token: 'TOK' });
+  });
+
+  it('exits 1 when --hostname is missing', async () => {
+    const result = await runCli([
+      'nat', 'ddns', 'set', 'duckdns',
+      '--token', 'TOK',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toMatch(/--hostname/);
+  });
+
+  it('exits 1 when --token is missing on a non-TTY stdin', async () => {
+    const result = await runCli([
+      'nat', 'ddns', 'set', 'duckdns',
+      '--hostname', 'foo.duckdns.org',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(1);
+    expect(result.stderr).toMatch(/--token/);
+  });
+});
+
+describe('cadre-host nat ddns external', () => {
+  it('PUTs /nat/settings with externallyManaged=true', async () => {
+    const result = await runCli([
+      'nat', 'ddns', 'external',
+      '--hostname', 'mydomain.example.com',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(0);
+    expect(stub.requests[0]!.method).toBe('PUT');
+    expect(stub.requests[0]!.url).toBe('/nat/settings');
+    const body = JSON.parse(stub.requests[0]!.body);
+    expect(body.ddns.hostname).toBe('mydomain.example.com');
+    expect(body.ddns.externallyManaged).toBe(true);
+  });
+});
+
+describe('cadre-host nat settings', () => {
+  it('PUTs /nat/settings with --external-port and --no-upnp', async () => {
+    const result = await runCli([
+      'nat', 'settings',
+      '--external-port', '4002',
+      '--no-upnp',
+      '--port', String(stub.port),
+    ]);
+    expect(result.code).toBe(0);
+    const body = JSON.parse(stub.requests[0]!.body);
+    expect(body.externalPort).toBe(4002);
+    expect(body.upnpEnabled).toBe(false);
+  });
+});

package/src/__tests__/cli.smoke.test.ts

@@ -1,46 +1,51 @@
-/**
- * Smoke test: invokes the compiled CLI with --help and asserts the expected
- * subcommands are listed. Relies on `yarn build` having produced dist/bin/host.js.
- */
-
-import { execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, resolve } from 'node:path';
-import { describe, it, expect, vi } from 'vitest';
-
-const here = dirname(fileURLToPath(import.meta.url));
-const binPath = resolve(here, '../../dist/bin/host.js');
-
-// These smoke tests cold-start the built CLI as a child process (Node boot +,
-// for some, an HTTP server). That comfortably exceeds vitest's 5s default under
-// heavy parallel load, so give the subprocess generous headroom.
-vi.setConfig({ testTimeout: 30000 });
-
-describe('cadre-host CLI smoke test', () => {
-  it('prints help with all subcommands', () => {
-    if (!existsSync(binPath)) {
-      throw new Error(`cadre-host bin not built at ${binPath}; run \`yarn build\` first`);
-    }
-
-    const stdout = execFileSync(process.execPath, [binPath, '--help'], {
-      encoding: 'utf8',
-    });
-
-    expect(stdout.length).toBeGreaterThan(0);
-    for (const cmd of ['install', 'start', 'status', 'invite', 'uninstall']) {
-      expect(stdout).toContain(cmd);
-    }
-  });
-
-  it('prints version', () => {
-    if (!existsSync(binPath)) {
-      throw new Error(`cadre-host bin not built at ${binPath}; run \`yarn build\` first`);
-    }
-
-    const stdout = execFileSync(process.execPath, [binPath, '--version'], {
-      encoding: 'utf8',
-    });
-    expect(stdout.trim().length).toBeGreaterThan(0);
-  });
-});
+/**
+ * Smoke test: invokes the compiled CLI with --help and asserts the expected
+ * subcommands are listed. Relies on `yarn build` having produced dist/bin/host.js.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { describe, it, expect, vi } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const binPath = resolve(here, '../../dist/bin/host.js');
+
+// These smoke tests cold-start the built CLI as a child process (Node boot +,
+// for some, an HTTP server). That comfortably exceeds vitest's 5s default under
+// heavy parallel load, so give the subprocess generous headroom.
+vi.setConfig({ testTimeout: 30000 });
+
+describe('cadre-host CLI smoke test', () => {
+  it('prints help with all subcommands', () => {
+    if (!existsSync(binPath)) {
+      throw new Error(`cadre-host bin not built at ${binPath}; run \`yarn build\` first`);
+    }
+
+    const stdout = execFileSync(process.execPath, [binPath, '--help'], {
+      encoding: 'utf8',
+    });
+
+    expect(stdout.length).toBeGreaterThan(0);
+    for (const cmd of ['install', 'start', 'status', 'invite', 'uninstall']) {
+      expect(stdout).toContain(cmd);
+    }
+  });
+
+  it('prints the version from package.json', () => {
+    if (!existsSync(binPath)) {
+      throw new Error(`cadre-host bin not built at ${binPath}; run \`yarn build\` first`);
+    }
+
+    const stdout = execFileSync(process.execPath, [binPath, '--version'], {
+      encoding: 'utf8',
+    });
+    // The built CLI reads package.json at runtime, so this holds even against a
+    // stale dist — it catches the version falling back to '0.0.0-unknown'.
+    const pkg = JSON.parse(
+      readFileSync(resolve(here, '../../package.json'), 'utf8'),
+    ) as { version: string };
+    expect(stdout.trim()).toBe(pkg.version);
+  });
+});

package/src/__tests__/global-setup.ts

@@ -1,51 +1,56 @@
-/**
- * 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.
- *
- * 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 a cross-package one `BuildTarget` is
- * meant to check (see `test-harness/build-freshness.ts`'s module comment).
- *
- * 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' },
-	{ 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' },
+	{ 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);
+}