@cosmicdrift/kumiko-dev-server 0.158.2 → 0.160.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.158.2",
+  "version": "0.160.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Not shipped into production node_modules — see @cosmicdrift/kumiko-server-runtime for the prod boot path.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -54,9 +54,9 @@
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.158.2",
-    "@cosmicdrift/kumiko-framework": "0.158.2",
-    "@cosmicdrift/kumiko-server-runtime": "0.158.2",
+    "@cosmicdrift/kumiko-bundled-features": "0.160.0",
+    "@cosmicdrift/kumiko-framework": "0.160.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.160.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/compose-stacks.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
 import {
@@ -110,9 +112,15 @@ describe("composeStacks", () => {
     expect(names.filter((n) => n === "sessions")).toHaveLength(2);
     expect(() =>
       validateBoot(
-        composeFeatures([...composeIdentityStack(), ...composeGdprStack({ sessions: true })], {
-          includeBundled: true,
-        }),
+        composeFeatures(
+          [
+            authFoundationFeature,
+            createPersonalAccessTokensFeature({ scopes: {} }),
+            ...composeIdentityStack(),
+            ...composeGdprStack({ sessions: true }),
+          ],
+          { includeBundled: true },
+        ),
       ),
     ).toThrow(/duplicate feature/i);
   });
@@ -123,6 +131,8 @@ describe("composeStacks boots for real", () => {
   test("studio-shaped combined stack passes validateBoot (not just name-list comparison)", () => {
     const features = composeFeatures(
       [
+        authFoundationFeature,
+        createPersonalAccessTokensFeature({ scopes: {} }),
         ...composeOpsStack({ rateLimiting: true }),
         ...composePagesStack(),
         ...composeMailStack({ transports: ["inmemory"] }),

package/src/__tests__/create-kumiko-server-errors.test.ts

@@ -0,0 +1,63 @@
+// createKumikoServer error / graceful-degradation paths — boot rejects,
+// stylesheet pipeline failures, missing CSS route.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createKumikoServer, type KumikoServerHandle } from "../create-kumiko-server";
+
+const emptyFeature = defineFeature("dev-server-errors-probe", () => {});
+
+let handle: KumikoServerHandle | undefined;
+
+afterEach(async () => {
+  if (handle) {
+    await handle.stop();
+    handle = undefined;
+  }
+});
+
+describe("createKumikoServer — client bundle failure", () => {
+  test("broken clientEntry rejects at boot with client bundle failed", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "kumiko-bundle-fail-"));
+    const entry = join(tmpDir, "client.tsx");
+    writeFileSync(entry, "const x = {{{\n");
+    try {
+      await expect(
+        createKumikoServer({
+          features: [emptyFeature],
+          port: 0,
+          installSignalHandlers: false,
+          clientEntry: entry,
+          stylesheet: false,
+        }),
+      ).rejects.toThrow(/client bundle failed|Bundle failed/);
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("_buildBundle throw propagates at boot", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "kumiko-stub-fail-"));
+    const entry = join(tmpDir, "client.tsx");
+    writeFileSync(entry, "// noop\n");
+    try {
+      await expect(
+        createKumikoServer({
+          features: [emptyFeature],
+          port: 0,
+          installSignalHandlers: false,
+          clientEntry: entry,
+          stylesheet: false,
+          _buildBundle: async () => {
+            throw new Error("stub build blew up");
+          },
+        }),
+      ).rejects.toThrow(/stub build blew up/);
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/create-kumiko-server.integration.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
@@ -336,3 +336,123 @@ describe("createKumikoServer extraRoutes-deps", () => {
     expect(body.data?.roles).toContain("SystemAdmin");
   });
 });
+
+describe("createKumikoServer — stylesheet tailwind failure (graceful)", () => {
+  test("missing stylesheet entry boots without CSS — GET /styles.css → 404", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "kumiko-css-fail-"));
+    const entry = join(tmpDir, "client.tsx");
+    writeFileSync(entry, "export const x = 1;\n");
+    try {
+      handle = await createKumikoServer({
+        features: [probeFeature],
+        port: 0,
+        installSignalHandlers: false,
+        clientEntry: entry,
+        stylesheet: join(tmpDir, "does-not-exist.css"),
+        _buildBundle: async () => ({ js: "// stub", map: "" }),
+      });
+      const cssRes = await handle.fetch(new Request("http://localhost/styles.css"));
+      expect(cssRes.status).toBe(404);
+      expect(await cssRes.text()).toBe("no stylesheet");
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("createKumikoServer — real Bun.build (buildClient)", () => {
+  test("clientEntry without _buildBundle produces a JS bundle via Bun.build", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "kumiko-real-build-"));
+    const entry = join(tmpDir, "client.tsx");
+    // Minimal entry Bun.build can emit — no JSX, no imports.
+    writeFileSync(entry, "export const ping = 1;\n");
+    // Empty dirs matching a glob — exercises expandWatchPatterns without
+    // writing files (avoids process.exit(75) from bare .tsx events).
+    mkdirSync(join(tmpDir, "pkg-a"));
+    mkdirSync(join(tmpDir, "pkg-b"));
+    try {
+      handle = await createKumikoServer({
+        features: [probeFeature],
+        port: 0,
+        installSignalHandlers: false,
+        clientEntry: entry,
+        stylesheet: false,
+        watchDirs: [join(tmpDir, "pkg-*")],
+      });
+      const res = await handle.fetch(new Request("http://localhost/client.js"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toMatch(/application\/javascript/);
+      const body = await res.text();
+      expect(body.length).toBeGreaterThan(0);
+      expect(body).toMatch(/ping/);
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("createKumikoServer — hot-reload broadcast", () => {
+  test("file change under web/ rebuilds and broadcasts SSE reload", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "kumiko-watch-"));
+    const entry = join(tmpDir, "client.tsx");
+    const webDir = join(tmpDir, "web");
+    mkdirSync(webDir);
+    writeFileSync(entry, "export const ping = 1;\n");
+
+    let builds = 0;
+    try {
+      handle = await createKumikoServer({
+        features: [probeFeature],
+        port: 0,
+        installSignalHandlers: false,
+        clientEntry: entry,
+        stylesheet: false,
+        // Only the entry dir is watched (no extra watchDirs) — a nested
+        // web/page.tsx event arrives as "web/page.tsx" → hot-reload.
+        // Watching web/ separately would fire bare "page.tsx" → restart
+        // → process.exit(75) and kill the test runner.
+        _buildBundle: async () => {
+          builds += 1;
+          return { js: `// build-${builds}`, map: "" };
+        },
+      });
+
+      const sseRes = await handle.fetch(new Request("http://localhost/_reload"));
+      expect(sseRes.status).toBe(200);
+      const reader = sseRes.body?.getReader();
+      expect(reader).toBeDefined();
+      if (!reader) return;
+
+      await reader.read(); // drain connected comment
+
+      const initialBuilds = builds;
+      writeFileSync(join(webDir, "page.tsx"), "export const x = 1;\n");
+
+      const deadline = Date.now() + 3000;
+      let sawReload = false;
+      while (Date.now() < deadline && !sawReload) {
+        const readPromise = reader.read();
+        const timeout = new Promise<{ done: true; value: undefined }>((resolve) =>
+          setTimeout(() => resolve({ done: true, value: undefined }), 200),
+        );
+        const { value, done } = await Promise.race([readPromise, timeout]);
+        if (done || value === undefined) continue;
+        const chunk = new TextDecoder().decode(value);
+        if (chunk.includes("event: reload")) sawReload = true;
+      }
+      await reader.cancel();
+
+      expect(builds).toBeGreaterThan(initialBuilds);
+      expect(sawReload).toBe(true);
+
+      const js = await handle.fetch(new Request("http://localhost/client.js"));
+      expect(await js.text()).toMatch(/build-/);
+
+      // Abort watchers before teardown rmSync can fire a restart event.
+      await handle.stop();
+      handle = undefined;
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/resolve-stylesheet.test.ts

@@ -64,6 +64,22 @@ describe("resolveStylesheet", () => {
     }
   });
 
+  test("Bun.resolveSync failure → undefined (catch path, no throw)", () => {
+    const tmpDir = realpathSync(mkdtempSync(join(tmpdir(), "kumiko-resolve-catch-")));
+    const cwdBefore = process.cwd();
+    process.chdir(tmpDir);
+    try {
+      const out = resolveStylesheet({
+        features: [],
+        clientEntry: "./entry.tsx",
+      });
+      expect(out).toBeUndefined();
+    } finally {
+      process.chdir(cwdBefore);
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
   test("undefined + clientEntry + src/styles.css existiert → returns App-Theme-Override", () => {
     // Auto-Detection greift VOR dem renderer-web-Fallback: Wenn die App
     // ein eigenes src/styles.css hat (App-Theme-Pattern), wird das

package/src/__tests__/saas-identity-wire.integration.test.ts

@@ -12,6 +12,7 @@ import {
   seedAdmin,
   seedUserWithPassword,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import {
   AuthMfaHandlers,
   base32Decode,
@@ -94,6 +95,13 @@ async function markVerified(userId: string): Promise<void> {
   await updateRows(stack.db, userTable, { emailVerified: true }, { id: userId });
 }
 
+// writeOk drives real HTTP through the auth middleware, so a hand-built
+// actor needs a live sid — sessionChecker rejects sidless JWTs.
+async function withSession(user: SessionUser): Promise<SessionUser> {
+  const sid = await callbacks.get().sessionCreator(user, { ip: "127.0.0.1", userAgent: "test" });
+  return { ...user, sid };
+}
+
 beforeAll(async () => {
   configureEntityFieldEncryption(createTestEnvelopeCipher());
   const bound = sessionCallbacksFromLateBound(callbacks);
@@ -110,6 +118,7 @@ beforeAll(async () => {
 
   const features = composeFeatures(
     [
+      authFoundationFeature,
       ...identity,
       ...composeOpsStack({ delivery: true, audit: false, jobs: false }),
       ...composeRendererStack(),
@@ -147,8 +156,8 @@ beforeAll(async () => {
     }),
     authConfig: {
       ...bound.asAuthConfig(),
-      // No sessionStrictMode: seed/writeOk uses TestUsers JWTs without sid.
-      // Login still gets jti via sessionCreator (asserted below).
+      // sessionChecker rejects sidless JWTs — hand-built actors used with
+      // writeOk go through withSession() to get a live sid first.
       membershipQuery: "tenant:query:memberships",
       loginHandler: AuthHandlers.login,
       mfaVerifyHandler: AuthMfaHandlers.verify,
@@ -293,7 +302,7 @@ describe("saas-identity-wire", () => {
     });
     await markVerified(adminId);
 
-    const admin: SessionUser = { id: adminId, tenantId, roles: ["Admin"] };
+    const admin = await withSession({ id: adminId, tenantId, roles: ["Admin"] });
     const invitee = "carol-wire@example.com";
     await stack.http.writeOk(AuthHandlers.inviteCreate, { email: invitee, role: "User" }, admin);
     expect(emailTransport.sent.length).toBeGreaterThanOrEqual(1);
@@ -368,7 +377,7 @@ describe("saas-identity-wire", () => {
       ],
     });
     await markVerified(userId);
-    const user: SessionUser = { id: userId, tenantId, roles: ["User"] };
+    const user = await withSession({ id: userId, tenantId, roles: ["User"] });
 
     const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
       AuthMfaHandlers.enableStart,

package/src/__tests__/scaffold-app.test.ts

@@ -92,6 +92,7 @@ describe("scaffoldApp", () => {
 
     const kumikoBin = readFileSync(join(dest, "bin/kumiko.ts"), "utf-8");
     expect(kumikoBin).toContain("runSchemaCli");
+    expect(kumikoBin).toContain("runConsumerCli");
     expect(kumikoBin).toContain("includeBundled: HAS_AUTH");
   });
 

package/src/__tests__/walkthrough.integration.test.ts

@@ -13,6 +13,8 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { createRegistry, defineFeature, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
@@ -77,18 +79,32 @@ describe("walkthrough — DX-3.1 snapshot", () => {
     // a dummy defineFeature here — the scaffold-side of "notesFeature"
     // (file-content) is pinned in test 2; this test pins the runtime-side
     // (composeFeatures auto-prepend behaviour the walkthrough claims).
+    //
+    // sessions now requires auth-foundation (#1370/#1371), which itself
+    // needs a tokenVerifier provider mounted (#1368) — PAT here, mirroring
+    // the scaffold picker's real-world default. Not part of the walkthrough's
+    // advertised 7-feature count (that count is about includeBundled's
+    // auto-mount, unrelated to this coupling), so both are added on top.
     const notesFeature = defineFeature("notes", () => {});
-    const APP_FEATURES = [createSecretsFeature(), createSessionsFeature(), notesFeature];
+    const APP_FEATURES = [
+      createSecretsFeature(),
+      authFoundationFeature,
+      createPersonalAccessTokensFeature({ scopes: {} }),
+      createSessionsFeature(),
+      notesFeature,
+    ];
 
     const composed = composeFeatures(APP_FEATURES, { includeBundled: true });
-    // 3 explicit + 4 auto-mounted bundled = 7 total features.
-    expect(composed.length).toBe(7);
+    // 5 explicit + 4 auto-mounted bundled = 9 total features.
+    expect(composed.length).toBe(9);
 
     const composedNames = composed.map((f) => f.name).sort();
     expect(composedNames).toEqual([
       "auth-email-password",
+      "auth-foundation",
       "config",
       "notes",
+      "personal-access-tokens",
       "secrets",
       "sessions",
       "tenant",
@@ -97,9 +113,9 @@ describe("walkthrough — DX-3.1 snapshot", () => {
 
     // validateBoot must pass (no missing-requires, no schema-errors).
     expect(() => validateBoot(composed)).not.toThrow();
-    // Registry must contain all 7 features.
+    // Registry must contain all 9 features.
     const registry = createRegistry(composed);
-    expect(registry.features.size).toBe(7);
+    expect(registry.features.size).toBe(9);
   });
 
   test("bin/main.ts contains the auth.admin stub the walkthrough relies on", async () => {

package/src/run-dev-app.ts

@@ -18,6 +18,7 @@ import {
   type SeedAdminOptions,
   seedAdmin,
 } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/seeding";
+import { resolveTokenVerifier } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import {
   AUTH_MFA_FEATURE,
   AuthMfaHandlers,
@@ -28,10 +29,8 @@ import {
   createConfigResolver,
 } from "@cosmicdrift/kumiko-bundled-features/config";
 import {
-  createPatResolver,
   PAT_FEATURE,
   patRateLimitFromFeature,
-  patScopesFromFeature,
 } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import {
   bindAutoRevokeFromFeature,
@@ -44,7 +43,7 @@ import {
   resolveTenantLifecycleGate,
   TENANT_LIFECYCLE_FEATURE,
 } from "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle";
-import type { PatResolver, SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
+import type { SessionMetadata, TokenVerifier } from "@cosmicdrift/kumiko-framework/api";
 import { createInMemoryLoginRateLimiter } from "@cosmicdrift/kumiko-framework/api";
 import {
   configureBlindIndexKey,
@@ -89,6 +88,7 @@ import { renderWelcomeBanner } from "./welcome-banner";
 // @cosmicdrift/kumiko-server-runtime (single source of truth) — hier nur
 // durchgereicht.
 export type {
+  AccountUnlockSetup,
   AuthMailOptions,
   EmailVerificationSetup,
   InviteSetup,
@@ -97,6 +97,7 @@ export type {
 } from "@cosmicdrift/kumiko-server-runtime/run-prod-app";
 
 import type {
+  AccountUnlockSetup,
   AuthMailOptions,
   EmailVerificationSetup,
   InviteSetup,
@@ -120,7 +121,7 @@ export type RunDevAppAuthOptions = {
   /** Opt-in: revocable server-side sessions. Caller MUSS
    *  `createSessionsFeature()` zu `features` adden — runDevApp wired
    *  hier nur die Auth-Callbacks (creator/revoker/checker) gegen
-   *  stack.db, plus sessionStrictMode=true.
+   *  stack.db (sidless JWTs werden dann abgelehnt).
    *
    *  Standardverhalten ohne diese Option: stateless JWTs ohne sid,
    *  Logout ist client-side cookie-clear, Karten­haus existing-Apps
@@ -145,6 +146,8 @@ export type RunDevAppAuthOptions = {
   readonly signup?: SignupSetup;
   /** Tenant-Invite flow (Magic-Link). Symmetric. */
   readonly invite?: InviteSetup;
+  /** Account-unlock flow (#1266). Symmetric zu RunProdAppAuthOptions. */
+  readonly accountUnlock?: AccountUnlockSetup;
   /** Domain attribute for both auth cookies (see
    *  AuthRoutesConfig.cookieDomain). Symmetric zu RunProdAppAuthOptions. */
   readonly cookieDomain?: string;
@@ -406,21 +409,21 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     }
     return sessionCallbacks;
   };
-  // PAT opt-in: same late-bound holder pattern — the resolver needs the real
-  // db (only concrete after setupTestStack). Wired when the feature is mounted;
-  // scopes come from the feature's exports (single source with its handlers).
-  let patResolver: PatResolver | undefined;
+  // Token-verifier opt-in: same late-bound holder pattern — resolveTokenVerifier
+  // needs the real db+registry (only concrete after setupTestStack). Wired
+  // whenever a provider feature (personal-access-tokens today) is mounted.
+  let tokenVerifier: TokenVerifier | undefined;
   let lifecycleDb: DbConnection | undefined;
   const patFeature = features.find((f) => f.name === PAT_FEATURE);
   const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
   const tenantLifecycleFeature = features.find((f) => f.name === TENANT_LIFECYCLE_FEATURE);
   const patAuthFragment = patFeature
     ? {
-        patResolver: (rawToken: string) => {
-          if (!patResolver) {
-            throw new Error("[runDevApp] pat-resolver accessed before onAfterSetup");
+        tokenVerifier: (rawToken: string) => {
+          if (!tokenVerifier) {
+            throw new Error("[runDevApp] token-verifier accessed before onAfterSetup");
           }
-          return patResolver(rawToken);
+          return tokenVerifier(rawToken);
         },
         patRateLimiter: (() => {
           const rl = patRateLimitFromFeature(patFeature);
@@ -449,11 +452,6 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
           sessionRevoker: (sid: string) => requireSessions().sessionRevoker(sid),
           sessionChecker: (sid: string, userId: string) =>
             requireSessions().sessionChecker(sid, userId),
-          // strict-mode: jede neue Plattform-App startet ohne legacy-
-          // JWTs ohne sid, daher safe als Default. Wer Sessions opt-in
-          // wählt, will explizite Server-side Revocation — strict-mode
-          // ist der einzige Modus der das tatsächlich erzwingt.
-          sessionStrictMode: true,
         }
       : {};
 
@@ -509,6 +507,12 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
             confirmHandler: AuthHandlers.verifyEmail,
           },
         }),
+        ...(effectiveAuth.accountUnlock && {
+          accountUnlock: {
+            requestHandler: AuthHandlers.requestAccountUnlock,
+            confirmHandler: AuthHandlers.confirmAccountUnlock,
+          },
+        }),
         ...(effectiveAuth.signup && {
           signup: {
             requestHandler: AuthHandlers.signupRequest,
@@ -558,7 +562,8 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
         }
       }
       if (patFeature) {
-        patResolver = createPatResolver({ db: stack.db, scopes: patScopesFromFeature(patFeature) });
+        tokenVerifier = (rawToken) =>
+          resolveTokenVerifier({ db: stack.db, registry: stack.registry }, rawToken);
       }
       if (effectiveAuth) {
         await seedAdmin(stack.db, effectiveAuth.admin);

package/src/scaffold-app.ts

@@ -42,6 +42,8 @@ export type ScaffoldFeatureEntry = {
   readonly importPath: string;
   readonly exportName: string;
   readonly callExpression: string;
+  /** Runtime args for factory-style exports that need config the codegen text can't parse back out (e.g. `{ scopes: {} }`). Omit for zero-arg factories and object-style exports. */
+  readonly callArgs?: readonly unknown[];
 };
 
 export type ScaffoldAppOptions = {
@@ -765,7 +767,7 @@ deploys. Build context = app repo root; migrations ship in \`kumiko/migrations/\
 - \`kumiko/schema.ts\` — same feature set → \`ENTITY_METAS\` for \`kumiko schema\`.
 - \`bin/dev.ts\` — dev-server entry (\`bun dev\`).
 - \`bin/main.ts\` — production-bootstrap (\`bun run start\`).
-- \`bin/kumiko.ts\` — schema-CLI bundled into \`dist-server/kumiko.js\`.
+- \`bin/kumiko.ts\` — schema + consumer-ops CLI bundled into \`dist-server/kumiko.js\`.
 - \`docker-compose.yml\` — local Postgres + Redis for \`bun dev\`.
 
 For full docs see https://docs.kumiko.rocks.
@@ -806,25 +808,32 @@ function renderBinKumiko(): string {
   return [
     "#!/usr/bin/env bun",
     "",
-    "// Standalone kumiko schema-CLI for the production bundle. The deploy",
-    "// migrate-step runs `bun /app/kumiko.js schema apply`; kumiko-build bundles",
-    "// this file to dist-server/kumiko.js.",
+    "// Standalone kumiko CLI for the production bundle. The deploy migrate-step",
+    "// runs `bun /app/kumiko.js schema apply`; ops runs `bun /app/kumiko.js",
+    "// consumer status|restart <name>` to recover a dead event consumer without",
+    "// ad-hoc SQL. kumiko-build bundles this file to dist-server/kumiko.js.",
     "",
     'import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";',
+    'import { runConsumerCli } from "@cosmicdrift/kumiko-framework/consumer-cli";',
     'import { runSchemaCli } from "@cosmicdrift/kumiko-framework/schema-cli";',
     'import { APP_FEATURES, HAS_AUTH } from "../src/run-config";',
     "",
     "const [, , cmd, ...rest] = Bun.argv;",
-    'if (cmd !== "schema") {',
-    "  // biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
-    '  console.error("\\n  Unknown: kumiko " + (cmd ?? "") + " — only \'kumiko schema <sub>\' in the standalone bundle.\\n");',
-    "  process.exit(1);",
+    "// biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
+    "const out = { log: (l: string) => console.log(l), err: (l: string) => console.error(l) };",
+    "",
+    'if (cmd === "schema") {',
+    "  const features = composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH });",
+    "  process.exit(await runSchemaCli(rest, process.env.INIT_CWD ?? process.cwd(), out, { features }));",
+    "}",
+    "",
+    'if (cmd === "consumer") {',
+    "  process.exit(await runConsumerCli(rest, out));",
     "}",
     "",
-    "const features = composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH });",
     "// biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
-    "const out = { log: (l: string) => console.log(l), err: (l: string) => console.error(l) };",
-    "process.exit(await runSchemaCli(rest, process.env.INIT_CWD ?? process.cwd(), out, { features }));",
+    'console.error("\\n  Unknown: kumiko " + (cmd ?? "") + " — only \'kumiko schema <sub>\' or \'kumiko consumer <sub>\' in the standalone bundle.\\n");',
+    "process.exit(1);",
     "",
   ].join("\n");
 }
@@ -843,11 +852,8 @@ async function instantiateScaffoldFeatures(
         `scaffoldApp: ${entry.importPath} missing export ${entry.exportName} for ${entry.callExpression}`,
       );
     }
-    if (entry.callExpression.endsWith("()")) {
-      if (typeof exp !== "function") {
-        throw new Error(`scaffoldApp: ${entry.exportName} is not callable (${entry.importPath})`);
-      }
-      instances.push((exp as () => FeatureDefinition)());
+    if (typeof exp === "function") {
+      instances.push((exp as (...args: unknown[]) => FeatureDefinition)(...(entry.callArgs ?? [])));
     } else {
       instances.push(exp as FeatureDefinition);
     }