@fuzdev/fuz_app 0.64.0 → 0.66.0

package/dist/testing/cross_backend/standard.js

@@ -0,0 +1,49 @@
+import '../assert_dev_env.js';
+import { describe_standard_integration_tests } from '../integration.js';
+import { describe_standard_admin_integration_tests } from '../admin_integration.js';
+import { describe_round_trip_validation } from '../round_trip.js';
+import { describe_rpc_round_trip_tests } from '../rpc_round_trip.js';
+import { describe_data_exposure_tests } from '../data_exposure.js';
+/**
+ * Run the cross-process standard test bundle — integration, admin (when
+ * `roles` provided), round trip, RPC round trip, data exposure. See the
+ * module doc for the suites omitted from this bundle and why.
+ */
+export const describe_standard_cross_process_tests = (options) => {
+    describe_standard_integration_tests({
+        setup_test: options.setup_test,
+        surface_source: options.surface_source,
+        capabilities: options.capabilities,
+        session_options: options.session_options,
+        rpc_endpoints: options.rpc_endpoints,
+        error_coverage_min: options.error_coverage_min,
+    });
+    describe_round_trip_validation({
+        setup_test: options.setup_test,
+        surface_source: options.surface_source,
+        capabilities: options.capabilities,
+    });
+    describe_rpc_round_trip_tests({
+        setup_test: options.setup_test,
+        surface_source: options.surface_source,
+        capabilities: options.capabilities,
+        session_options: options.session_options,
+        rpc_endpoints: options.rpc_endpoints,
+    });
+    describe_data_exposure_tests({
+        setup_test: options.setup_test,
+        surface_source: options.surface_source,
+        capabilities: options.capabilities,
+    });
+    if (options.roles) {
+        describe_standard_admin_integration_tests({
+            setup_test: options.setup_test,
+            surface_source: options.surface_source,
+            capabilities: options.capabilities,
+            session_options: options.session_options,
+            roles: options.roles,
+            rpc_endpoints: options.rpc_endpoints,
+            admin_prefix: options.admin_prefix,
+        });
+    }
+};

package/dist/testing/cross_backend/testing_reset_actions.d.ts

@@ -0,0 +1,171 @@
+import '../assert_dev_env.js';
+/**
+ * Test-binary RPC actions for cross-process integration tests.
+ *
+ * Single daemon-token-authed action: **`_testing_reset`** — full DB
+ * wipe + keeper re-seed + optional secondary-account seeding. The
+ * handler wipes every auth-namespace row (no keeper-preserve filter),
+ * flips `bootstrap_lock` back to its post-bootstrap shape, seeds a
+ * fresh keeper account inline (reusing `create_test_account_with_credentials`
+ * so cross-process matches in-process write semantics), seeds any
+ * caller-requested `extra_accounts` (also direct-inserted at this
+ * setup step), refreshes the daemon-token cache to point at the new
+ * keeper, and fires the consumer-supplied domain-state callback. The
+ * new keeper + secondary credentials return as the action output so
+ * the per-test fixture closes over them.
+ *
+ * The redesign converges in-process and cross-process keeper
+ * lifetimes: both modes now run against a freshly bootstrapped keeper
+ * per test. Mutation-cascade tests (password change, revoke-all,
+ * hardcoded-username signup uniqueness) and direct keeper-vs-admin
+ * probes work uniformly cross-process.
+ *
+ * **Keeper ≠ admin.** The `keeper` and `admin` roles are independent.
+ * Keeper authorizes daemon-token / bootstrap paths; admin authorizes
+ * the user-facing admin RPC surface. `_testing_reset` seeds the keeper
+ * account with `[ROLE_KEEPER, ROLE_ADMIN]` by default — matching the
+ * production `bootstrap_account` flow — plus any roles passed via
+ * `extra_keeper_roles`. Tests probing the keeper-vs-admin separation
+ * (a keeper-only account must 403 on admin RPCs) declare a secondary
+ * via `extra_accounts: [{username, roles: [ROLE_KEEPER]}]` so the
+ * account is seeded at this same bootstrap-equivalent step.
+ *
+ * **No free-form runtime bypass.** Earlier drafts considered a separate
+ * `_testing_seed_role_grant` action for arbitrary direct grants; that
+ * was rejected because a runtime bypass would let tests skip the
+ * production consent flow's side-effects (audit emit, WS fan-out) and
+ * silently mask bugs in those paths. The bypass that does exist —
+ * `extra_accounts` — is framed as bootstrap-time seeding, the same
+ * shape `bootstrap_account` itself uses to grant the initial
+ * `KEEPER` + `ADMIN` pair. Tests that want a role on a *post-bootstrap*
+ * account must route through `role_grant_offer_create` +
+ * `role_grant_offer_accept` (the production path); they observe the
+ * full event chain.
+ *
+ * Production safety: this module lives under `cross_backend/` and starts
+ * with `import '../assert_dev_env.js';` — production bundles either
+ * tree-shake the module out or throw at startup. The Rust mirror
+ * (`fuz_testing` crate) ships a parallel action; `cargo xtask
+ * check-release` blocks `fuz_testing` from entering production dep
+ * graphs.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { type RpcAction } from '../../actions/action_rpc.js';
+import type { AppDeps } from '../../auth/deps.js';
+import type { SessionOptions } from '../../auth/session_cookie.js';
+import type { DaemonTokenState } from '../../auth/daemon_token.js';
+/**
+ * The `_testing_reset` action spec.
+ *
+ * Input:
+ * - `extra_keeper_roles` — roles to grant the fresh keeper *in addition
+ *   to* `[ROLE_KEEPER, ROLE_ADMIN]` (matching production bootstrap).
+ * - `extra_accounts` — additional accounts to seed at this same
+ *   bootstrap-equivalent step. Each entry's `roles` are direct-granted
+ *   (bypassing offer/accept) because the seed is *part of bootstrap*,
+ *   not a post-bootstrap action. Use this for accounts whose required
+ *   roles aren't admin-grantable via offer/accept (e.g. `ROLE_KEEPER`,
+ *   whose `RoleSpec.grant_paths` is bootstrap-only). For
+ *   admin-grantable roles, prefer `fixture.create_account({roles})`
+ *   (offer/accept production path).
+ *
+ * Output: keeper credentials plus a parallel array of seeded
+ * `extra_accounts` (same order as input). The per-test fixture closes
+ * over the returned values; subsequent calls in the same test see the
+ * fresh keeper and any requested secondaries.
+ *
+ * `auth` gates on the daemon-token credential — the keeper holds it
+ * exclusively. The action is internally privileged (it runs direct
+ * DB writes the production wire never exposes); daemon-token auth is
+ * the structural fence.
+ */
+export declare const testing_reset_action_spec: {
+    readonly method: "_testing_reset";
+    readonly kind: "request_response";
+    readonly initiator: "frontend";
+    readonly auth: {
+        readonly account: "required";
+        readonly actor: "none";
+        readonly credential_types: readonly ["daemon_token"];
+    };
+    readonly side_effects: true;
+    readonly input: z.ZodObject<{
+        extra_keeper_roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        extra_accounts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            username: z.ZodString;
+            password_value: z.ZodOptional<z.ZodString>;
+            roles: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    readonly output: z.ZodObject<{
+        account: z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            username: z.ZodString;
+        }, z.core.$strict>;
+        actor: z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        }, z.core.$strict>;
+        api_token: z.ZodString;
+        session_cookie: z.ZodString;
+        extra_accounts: z.ZodArray<z.ZodObject<{
+            account: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+                username: z.ZodString;
+            }, z.core.$strict>;
+            actor: z.ZodObject<{
+                id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+            }, z.core.$strict>;
+            api_token: z.ZodString;
+            session_cookie: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    readonly async: true;
+    readonly description: "Test-binary only — wipe auth tables, re-bootstrap a fresh keeper (+ optional extras), fire the domain-state reset.";
+};
+/** Options for `create_testing_actions`. */
+export interface CreateTestingActionsOptions {
+    /**
+     * Session cookie options — the reset action uses these when signing
+     * the fresh keeper's (and any extra accounts') session cookies.
+     * Pass the same `SessionOptions` the live `create_app_server` call
+     * was wired with.
+     */
+    readonly session_options: SessionOptions<string>;
+    /**
+     * Daemon-token runtime state — the reset action mutates
+     * `state.keeper_account_id` to point at the freshly seeded keeper
+     * after the old row is wiped. Pass the same `DaemonTokenState`
+     * instance the daemon-token middleware reads.
+     */
+    readonly daemon_token_state: DaemonTokenState;
+    /**
+     * Consumer-supplied callback invoked after the auth-table reset.
+     * `testing_zzz_server` clears workspace registry + terminals + the
+     * scoped FS scratch dir here; `testing_spine_stub` has no domain
+     * layer and passes a no-op (or omits the option). Runs inside the
+     * same RPC dispatch as the auth-table writes, so a throw surfaces
+     * to the caller as a JSON-RPC error and the per-test fixture
+     * short-circuits.
+     */
+    readonly reset_state?: () => Promise<void> | void;
+}
+/**
+ * Build the testing RPC actions for a test binary's registry.
+ *
+ * Returns `_testing_reset` — the single privileged action test binaries
+ * register. The test binary calls this at server-assembly time and
+ * registers the result on its dispatcher.
+ *
+ * The reset action's table-wipe list mirrors
+ * `auth_integration_truncate_tables` from `testing/db.ts` — the
+ * canonical "auth tables a between-test reset must clear" set.
+ * `testing_reset_actions.coverage.test.ts` enforces the set-equality
+ * invariant so a future auth migration that adds a table to that list
+ * without updating this handler fails CI.
+ */
+export declare const create_testing_actions: (deps: AppDeps, options: CreateTestingActionsOptions) => Array<RpcAction>;
+/** Set of auth-namespace tables `_testing_reset` wipes. Mirrored by the coverage test. */
+export declare const testing_reset_wiped_tables: string[];
+//# sourceMappingURL=testing_reset_actions.d.ts.map

package/dist/testing/cross_backend/testing_reset_actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing_reset_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/testing_reset_actions.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,EAAa,KAAK,SAAS,EAAC,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,4BAA4B,CAAC;AAajE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwBQ,CAAC;AAE/C,4CAA4C;AAC5C,MAAM,WAAW,2BAA2B;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,EAAE,gBAAgB,CAAC;IAC9C;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,OAAO,EACb,SAAS,2BAA2B,KAClC,KAAK,CAAC,SAAS,CA4FjB,CAAC;AAEF,0FAA0F;AAC1F,eAAO,MAAM,0BAA0B,UAAmC,CAAC"}

package/dist/testing/cross_backend/testing_reset_actions.js

@@ -0,0 +1,213 @@
+import '../assert_dev_env.js';
+/**
+ * Test-binary RPC actions for cross-process integration tests.
+ *
+ * Single daemon-token-authed action: **`_testing_reset`** — full DB
+ * wipe + keeper re-seed + optional secondary-account seeding. The
+ * handler wipes every auth-namespace row (no keeper-preserve filter),
+ * flips `bootstrap_lock` back to its post-bootstrap shape, seeds a
+ * fresh keeper account inline (reusing `create_test_account_with_credentials`
+ * so cross-process matches in-process write semantics), seeds any
+ * caller-requested `extra_accounts` (also direct-inserted at this
+ * setup step), refreshes the daemon-token cache to point at the new
+ * keeper, and fires the consumer-supplied domain-state callback. The
+ * new keeper + secondary credentials return as the action output so
+ * the per-test fixture closes over them.
+ *
+ * The redesign converges in-process and cross-process keeper
+ * lifetimes: both modes now run against a freshly bootstrapped keeper
+ * per test. Mutation-cascade tests (password change, revoke-all,
+ * hardcoded-username signup uniqueness) and direct keeper-vs-admin
+ * probes work uniformly cross-process.
+ *
+ * **Keeper ≠ admin.** The `keeper` and `admin` roles are independent.
+ * Keeper authorizes daemon-token / bootstrap paths; admin authorizes
+ * the user-facing admin RPC surface. `_testing_reset` seeds the keeper
+ * account with `[ROLE_KEEPER, ROLE_ADMIN]` by default — matching the
+ * production `bootstrap_account` flow — plus any roles passed via
+ * `extra_keeper_roles`. Tests probing the keeper-vs-admin separation
+ * (a keeper-only account must 403 on admin RPCs) declare a secondary
+ * via `extra_accounts: [{username, roles: [ROLE_KEEPER]}]` so the
+ * account is seeded at this same bootstrap-equivalent step.
+ *
+ * **No free-form runtime bypass.** Earlier drafts considered a separate
+ * `_testing_seed_role_grant` action for arbitrary direct grants; that
+ * was rejected because a runtime bypass would let tests skip the
+ * production consent flow's side-effects (audit emit, WS fan-out) and
+ * silently mask bugs in those paths. The bypass that does exist —
+ * `extra_accounts` — is framed as bootstrap-time seeding, the same
+ * shape `bootstrap_account` itself uses to grant the initial
+ * `KEEPER` + `ADMIN` pair. Tests that want a role on a *post-bootstrap*
+ * account must route through `role_grant_offer_create` +
+ * `role_grant_offer_accept` (the production path); they observe the
+ * full event chain.
+ *
+ * Production safety: this module lives under `cross_backend/` and starts
+ * with `import '../assert_dev_env.js';` — production bundles either
+ * tree-shake the module out or throw at startup. The Rust mirror
+ * (`fuz_testing` crate) ships a parallel action; `cargo xtask
+ * check-release` blocks `fuz_testing` from entering production dep
+ * graphs.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+import { rpc_action } from '../../actions/action_rpc.js';
+import { ROLE_ADMIN, ROLE_KEEPER } from '../../auth/role_schema.js';
+import { auth_integration_truncate_tables } from '../db.js';
+import { create_test_account_with_credentials, DEFAULT_TEST_PASSWORD } from '../app_server.js';
+/** Output shape for an individual seeded account (keeper or extra). */
+const SeededAccountShape = z.strictObject({
+    account: z.strictObject({ id: Uuid, username: z.string() }),
+    actor: z.strictObject({ id: Uuid }),
+    api_token: z.string(),
+    session_cookie: z.string(),
+});
+/**
+ * The `_testing_reset` action spec.
+ *
+ * Input:
+ * - `extra_keeper_roles` — roles to grant the fresh keeper *in addition
+ *   to* `[ROLE_KEEPER, ROLE_ADMIN]` (matching production bootstrap).
+ * - `extra_accounts` — additional accounts to seed at this same
+ *   bootstrap-equivalent step. Each entry's `roles` are direct-granted
+ *   (bypassing offer/accept) because the seed is *part of bootstrap*,
+ *   not a post-bootstrap action. Use this for accounts whose required
+ *   roles aren't admin-grantable via offer/accept (e.g. `ROLE_KEEPER`,
+ *   whose `RoleSpec.grant_paths` is bootstrap-only). For
+ *   admin-grantable roles, prefer `fixture.create_account({roles})`
+ *   (offer/accept production path).
+ *
+ * Output: keeper credentials plus a parallel array of seeded
+ * `extra_accounts` (same order as input). The per-test fixture closes
+ * over the returned values; subsequent calls in the same test see the
+ * fresh keeper and any requested secondaries.
+ *
+ * `auth` gates on the daemon-token credential — the keeper holds it
+ * exclusively. The action is internally privileged (it runs direct
+ * DB writes the production wire never exposes); daemon-token auth is
+ * the structural fence.
+ */
+export const testing_reset_action_spec = {
+    method: '_testing_reset',
+    kind: 'request_response',
+    initiator: 'frontend',
+    auth: { account: 'required', actor: 'none', credential_types: ['daemon_token'] },
+    side_effects: true,
+    input: z.strictObject({
+        extra_keeper_roles: z.array(z.string()).optional(),
+        extra_accounts: z
+            .array(z.strictObject({
+            username: z.string(),
+            password_value: z.string().optional(),
+            roles: z.array(z.string()),
+        }))
+            .optional(),
+    }),
+    output: SeededAccountShape.extend({
+        extra_accounts: z.array(SeededAccountShape),
+    }),
+    async: true,
+    description: 'Test-binary only — wipe auth tables, re-bootstrap a fresh keeper (+ optional extras), fire the domain-state reset.',
+};
+/**
+ * Build the testing RPC actions for a test binary's registry.
+ *
+ * Returns `_testing_reset` — the single privileged action test binaries
+ * register. The test binary calls this at server-assembly time and
+ * registers the result on its dispatcher.
+ *
+ * The reset action's table-wipe list mirrors
+ * `auth_integration_truncate_tables` from `testing/db.ts` — the
+ * canonical "auth tables a between-test reset must clear" set.
+ * `testing_reset_actions.coverage.test.ts` enforces the set-equality
+ * invariant so a future auth migration that adds a table to that list
+ * without updating this handler fails CI.
+ */
+export const create_testing_actions = (deps, options) => {
+    const { session_options, daemon_token_state, reset_state } = options;
+    const log = deps.log;
+    return [
+        rpc_action(testing_reset_action_spec, async (input, ctx) => {
+            log.info('[_testing_reset] resetting auth state + re-seeding keeper');
+            // 1. Wipe every auth-namespace row. No keeper-preserve filter —
+            //    the fresh-keeper-per-test contract means mutation-cascade
+            //    tests (password change, revoke-all) and hardcoded-username
+            //    signup-uniqueness tests can't leak between cases.
+            //
+            //    `audit_log` has no FK to account so it wipes wholesale.
+            //    `role_grant_offer` + `invite` likewise (callers don't carry
+            //    state across resets). For account-FK tables we wipe rows
+            //    referencing actor/account first to satisfy FK order.
+            await ctx.db.query('DELETE FROM audit_log');
+            await ctx.db.query('DELETE FROM role_grant_offer');
+            await ctx.db.query('DELETE FROM invite');
+            await ctx.db.query('DELETE FROM api_token');
+            await ctx.db.query('DELETE FROM auth_session');
+            await ctx.db.query('DELETE FROM role_grant');
+            await ctx.db.query('DELETE FROM actor');
+            await ctx.db.query('DELETE FROM account');
+            // 2. Reset singleton `app_settings` to production defaults
+            //    (matches in-process `_build_test_backend` behavior in
+            //    `app_server.ts`). Tests that flipped `open_signup` mid-run
+            //    revert.
+            await ctx.db.query('UPDATE app_settings SET open_signup = false, updated_at = NULL, updated_by = NULL ' +
+                'WHERE open_signup = true OR updated_at IS NOT NULL');
+            // 3. Flip `bootstrap_lock` to its post-bootstrap shape. Production
+            //    `bootstrap_account` flips this to `true` on success; the
+            //    in-process `bootstrap_test_keeper` mirrors the flip. We're
+            //    about to seed the keeper here, so the final state needs to
+            //    be `bootstrapped = true`. We don't need an intermediate flip
+            //    to `false` — nothing reads it between our DELETEs and the
+            //    UPDATE.
+            await ctx.db.query('UPDATE bootstrap_lock SET bootstrapped = true WHERE id = 1');
+            // 4. Seed the fresh keeper inline. Reuses the same primitive
+            //    in-process tests use (`create_test_account_with_credentials`)
+            //    so cross-process and in-process write semantics stay in
+            //    parity — same hash, same account+actor+role_grants+
+            //    api_token+session_cookie shape.
+            //
+            //    Roles default to `[ROLE_KEEPER, ROLE_ADMIN]` to match
+            //    production `bootstrap_account`. `extra_keeper_roles` adds
+            //    on top.
+            const keeper = await create_test_account_with_credentials({
+                db: ctx.db,
+                keyring: deps.keyring,
+                session_options,
+                password: deps.password,
+                password_value: DEFAULT_TEST_PASSWORD,
+                roles: [ROLE_KEEPER, ROLE_ADMIN, ...(input.extra_keeper_roles ?? [])],
+            });
+            // 5. Seed any caller-requested extras. These are bootstrap-time
+            //    secondaries — the bypass exists in the same cradle the
+            //    keeper does, not as a free-form runtime action.
+            const extras = [];
+            for (const spec of input.extra_accounts ?? []) {
+                const seeded = await create_test_account_with_credentials({
+                    db: ctx.db,
+                    keyring: deps.keyring,
+                    session_options,
+                    password: deps.password,
+                    username: spec.username,
+                    password_value: spec.password_value ?? DEFAULT_TEST_PASSWORD,
+                    roles: spec.roles,
+                });
+                extras.push(seeded);
+            }
+            // 6. Refresh the daemon-token cache so subsequent daemon-token
+            //    requests resolve to the freshly seeded keeper. The
+            //    middleware's lazy-refresh path only fires when the cached
+            //    id is null; setting it directly here avoids one round-trip
+            //    of stale-id-then-refresh on the next call.
+            daemon_token_state.keeper_account_id = keeper.account.id;
+            // 7. Fire domain-state reset (zzz workspaces/terminals/scratch,
+            //    or no-op for spine_stub).
+            if (reset_state)
+                await reset_state();
+            return { ...keeper, extra_accounts: extras };
+        }),
+    ];
+};
+/** Set of auth-namespace tables `_testing_reset` wipes. Mirrored by the coverage test. */
+export const testing_reset_wiped_tables = auth_integration_truncate_tables;

package/dist/testing/cross_backend/testing_server_bun.d.ts

@@ -0,0 +1,5 @@
+import '../assert_dev_env.js';
+import type { TestingServerAdapter } from './testing_server_core.js';
+/** Build the Bun {@link TestingServerAdapter}. */
+export declare const create_bun_testing_adapter: () => TestingServerAdapter;
+//# sourceMappingURL=testing_server_bun.d.ts.map

package/dist/testing/cross_backend/testing_server_bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing_server_bun.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/testing_server_bun.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6B9B,OAAO,KAAK,EAAc,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAehF,kDAAkD;AAClD,eAAO,MAAM,0BAA0B,QAAO,oBA+B5C,CAAC"}

package/dist/testing/cross_backend/testing_server_bun.js

@@ -0,0 +1,59 @@
+import '../assert_dev_env.js';
+/**
+ * Bun runtime adapter for spawnable cross-process test server binaries.
+ *
+ * Binds `Bun.serve` and `hono/bun`'s module-level `upgradeWebSocket` +
+ * `websocket` handler. The shared `testing_server_core.ts` owns the rest.
+ * Third sibling to `testing_server_node.ts` / `testing_server_deno.ts` —
+ * together the three isolate the JS-runtime axis (Node V8 / Deno V8 / Bun
+ * JSC) on identical TS surfaces, and the Rust spine binary covers the
+ * cross-language axis.
+ *
+ * Needs **no extra deps**: `hono/bun` ships with the `hono` peer dep and
+ * `Bun.serve` is built in (unlike Node, which pulls `@hono/node-server` +
+ * `@hono/node-ws`). `RuntimeDeps` reuse `create_node_runtime` — Bun
+ * implements the `node:fs` / `node:process` surface `RuntimeDeps` +
+ * `cli/daemon` touch.
+ *
+ * `Bun.serve` is declared locally (mirroring `testing_server_deno.ts`'s
+ * `Deno` declaration) so this module typechecks under fuz_app's Node-based
+ * config without `@types/bun`. It is only ever *run* under Bun.
+ *
+ * @module
+ */
+import process from 'node:process';
+import { getConnInfo, upgradeWebSocket, websocket } from 'hono/bun';
+import { create_node_runtime } from '../../runtime/node.js';
+/** Build the Bun {@link TestingServerAdapter}. */
+export const create_bun_testing_adapter = () => ({
+    runtime_label: 'Bun',
+    runtime: create_node_runtime(),
+    get_connection_ip: (c) => getConnInfo(c).remote.address,
+    // Bun's WS upgrade is module-level and stateless (like Deno) — no
+    // post-serve attach. The `websocket` handler is threaded into `serve`
+    // below, where `Bun.serve` wants it.
+    prepare_websocket: () => ({ upgrade_websocket: upgradeWebSocket }),
+    serve: ({ fetch, port, hostname }) => {
+        const server = Bun.serve({
+            fetch: fetch,
+            port,
+            hostname,
+            // Harmless for HTTP-only binaries — Bun only invokes it for sockets
+            // upgraded via `upgradeWebSocket`.
+            websocket,
+        });
+        const handle = {
+            shutdown: async () => {
+                await server.stop();
+            },
+            native: server,
+        };
+        return handle;
+    },
+    pid: process.pid,
+    register_shutdown_signals: (handler) => {
+        process.on('SIGINT', () => void handler());
+        process.on('SIGTERM', () => void handler());
+    },
+    exit: (code) => process.exit(code),
+});

package/dist/testing/cross_backend/testing_server_core.d.ts

@@ -0,0 +1,140 @@
+import '../assert_dev_env.js';
+/**
+ * Runtime-agnostic core for spawnable cross-process **test** server
+ * binaries.
+ *
+ * A test binary mounts a fuz_app-derived surface over a real HTTP socket so
+ * the `cross_backend/*` suites (and the cross-impl bench) can drive it the
+ * same way they drive the Rust spine. This module owns the runtime-neutral
+ * orchestration — stale-daemon check, daemon-info write, serve, post-serve
+ * WS attach, graceful drain shutdown — and delegates the runtime-boundary
+ * primitives (HTTP serve, WS upgrade construction, signals, pid, exit) to a
+ * {@link TestingServerAdapter}. The two shipped adapters are
+ * `testing_server_node.ts` (`@hono/node-server` + `@hono/node-ws`) and
+ * `testing_server_deno.ts` (`Deno.serve` + `hono/deno`).
+ *
+ * The app itself — routes, RPC, DB, `_testing_reset`, optional WS mount —
+ * is the caller's {@link StartTestingServerOptions.build_app} seam, so this
+ * core stays domain-free. fuz_app's own `testing_spine_server` passes a
+ * no-domain build; consumers (zzz, fuz_forge) pass their domain build.
+ *
+ * **NEVER ships in a release.** This module lives under `cross_backend/` and
+ * opens with `import '../assert_dev_env.js';`, which throws on
+ * production-bundle load. The runtime adapters reach for the optional
+ * `@hono/node-server` / `@hono/node-ws` peer deps; only test binaries import
+ * them.
+ *
+ * @module
+ */
+import type { Context, Hono } from 'hono';
+import type { UpgradeWebSocket } from 'hono/ws';
+import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
+import type { RuntimeDeps } from '../../runtime/deps.js';
+/**
+ * Adapter-built handle to a bound HTTP server.
+ *
+ * `shutdown` stops accepting new connections and drains in-flight ones.
+ * `native` is an adapter-specific server reference — used by Node's
+ * `@hono/node-ws` `injectWebSocket(server)` post-serve hook; Deno leaves it
+ * unset.
+ */
+export interface ServeHandle {
+    shutdown: () => Promise<void>;
+    /** Adapter-specific server ref for post-serve hooks. Type-erased at the seam. */
+    native?: unknown;
+}
+/**
+ * Result of an adapter's WS preparation step.
+ *
+ * `upgrade_websocket` is the Hono `UpgradeWebSocket` closure the caller's
+ * WS mount uses to register the endpoint. `attach_to_server` runs after
+ * `serve()` returns a {@link ServeHandle} — Node uses it for
+ * `injectWebSocket(server)`; Deno leaves it undefined.
+ */
+export interface PreparedWebsocket {
+    upgrade_websocket: UpgradeWebSocket;
+    attach_to_server?: (handle: ServeHandle) => void;
+}
+/**
+ * Runtime adapter contract for the test-binary entry. Each adapter
+ * (`testing_server_node.ts`, `testing_server_deno.ts`) implements this and
+ * hands the shape to {@link start_testing_server}.
+ */
+export interface TestingServerAdapter {
+    /** Human-readable runtime label for log output (e.g. `"Node"`, `"Deno"`). */
+    runtime_label: string;
+    /** `RuntimeDeps` capability bundle from `create_node_runtime` / `create_deno_runtime`. */
+    runtime: RuntimeDeps;
+    /** Extract the raw TCP connection IP from a Hono context. */
+    get_connection_ip: (c: Context) => string | undefined;
+    /** Build the WS upgrade closure after the caller's `build_app` returns the app. */
+    prepare_websocket: (app: Hono) => PreparedWebsocket;
+    /** Bind `app.fetch` to `port` on `hostname`; return a {@link ServeHandle}. */
+    serve: (options: {
+        fetch: Hono['fetch'];
+        port: number;
+        hostname: string;
+    }) => ServeHandle;
+    /** Current process pid (for `daemon.json`). */
+    pid: number;
+    /** Register SIGINT/SIGTERM listeners that invoke `handler` once each. */
+    register_shutdown_signals: (handler: () => Promise<void>) => void;
+    /** Forceful exit on graceful-shutdown completion or fatal error. */
+    exit: (code: number) => never;
+}
+/**
+ * The assembled app a {@link StartTestingServerOptions.build_app} seam
+ * returns.
+ *
+ * `mount_websocket` is invoked by the core after the app exists and the
+ * adapter prepared the WS upgrade closure — the closure mounts the WS
+ * endpoint(s) (e.g. via `register_ws_endpoint`) and wires any
+ * audit-revocation guards. Omit it for an HTTP-only binary.
+ */
+export interface BuiltTestingApp {
+    /** The assembled Hono app (HTTP routes + RPC already mounted). */
+    app: Hono;
+    /** Tear down backend(s) + DB + any rotation on graceful shutdown. */
+    close: () => Promise<void>;
+    /** Mount WS endpoint(s) given the runtime-prepared upgrade closure. */
+    mount_websocket?: (upgrade_websocket: UpgradeWebSocket) => void;
+}
+/** Options for {@link start_testing_server}. */
+export interface StartTestingServerOptions {
+    /** Runtime-boundary adapter (Node or Deno). */
+    adapter: TestingServerAdapter;
+    /**
+     * Daemon-info namespace — the `cli/daemon` key the `daemon.json` is
+     * written under (e.g. `'fuz_app_spine'`). The cross-process harness
+     * reads the daemon token from the rotation file, not this; `daemon.json`
+     * is for stale-process detection + parity with production daemon
+     * lifecycle.
+     */
+    daemon_name: string;
+    /** Bind host (e.g. `'localhost'`). */
+    host: string;
+    /** Bind port. */
+    port: number;
+    /** App version recorded in `daemon.json`. */
+    app_version?: string;
+    /**
+     * Build the app. Closes over the entry's runtime + connection-IP getter
+     * + password deps + resolved config — so this core never touches the
+     * domain. Returns the assembled app, a `close` teardown, and an optional
+     * `mount_websocket` hook.
+     */
+    build_app: () => Promise<BuiltTestingApp>;
+    /** Optional logger; defaults to a `[daemon_name]`-namespaced `Logger`. */
+    log?: LoggerType;
+}
+/**
+ * Boot a test-mode server using the supplied runtime adapter.
+ *
+ * Mirrors a production `start_server` at the surface level — stale-daemon
+ * check, daemon-info write, bind, graceful drain — but the app is the
+ * caller's no-domain (or domain) {@link StartTestingServerOptions.build_app}
+ * and the runtime boundary is the {@link TestingServerAdapter}. Refuses to
+ * bind an open host (the test binary must stay on loopback).
+ */
+export declare const start_testing_server: (options: StartTestingServerOptions) => Promise<void>;
+//# sourceMappingURL=testing_server_core.d.ts.map

package/dist/testing/cross_backend/testing_server_core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing_server_core.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/testing_server_core.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG1E,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,uBAAuB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,iBAAiB,EAAE,gBAAgB,CAAC;IACpC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CACjD;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACpC,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,OAAO,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,mFAAmF;IACnF,iBAAiB,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,iBAAiB,CAAC;IACpD,8EAA8E;IAC9E,KAAK,EAAE,CAAC,OAAO,EAAE;QAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,KAAK,WAAW,CAAC;IACxF,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,yBAAyB,EAAE,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IAClE,oEAAoE;IACpE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC/B,kEAAkE;IAClE,GAAG,EAAE,IAAI,CAAC;IACV,qEAAqE;IACrE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,uEAAuE;IACvE,eAAe,CAAC,EAAE,CAAC,iBAAiB,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAChE;AAED,gDAAgD;AAChD,MAAM,WAAW,yBAAyB;IACzC,+CAA+C;IAC/C,OAAO,EAAE,oBAAoB,CAAC;IAC9B;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,GAAG,CAAC,EAAE,UAAU,CAAC;CACjB;AAKD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAU,SAAS,yBAAyB,KAAG,OAAO,CAAC,IAAI,CA4D3F,CAAC"}