@cosmicdrift/kumiko-dev-server 0.164.0 → 0.165.1

package/bin/kumiko-build.ts

@@ -24,6 +24,7 @@ import {
   discoverServerEntry,
   formatBuildResult,
   formatServerBuildResult,
+  readExtraRuntimeExternals,
 } from "../src/build";
 import { runCodegen } from "../src/codegen";
 
@@ -73,7 +74,11 @@ try {
   }
   if (hasServer) {
     const t0 = performance.now();
-    const result = await buildServerBundle({ cwd });
+    const extraRuntimeExternals = readExtraRuntimeExternals(cwd);
+    const result = await buildServerBundle({
+      cwd,
+      ...(extraRuntimeExternals.length > 0 && { extraRuntimeExternals }),
+    });
     const ms = Math.round(performance.now() - t0);
     // biome-ignore lint/suspicious/noConsole: CLI-Output, einziger Weg
     console.log(formatServerBuildResult(result, ms));

package/bin/kumiko-schema-check.ts

@@ -68,6 +68,7 @@ async function readMountedFeatures(runConfigPath: string): Promise<Set<string>>
   const mod = (await import(runConfigPath)) as {
     APP_FEATURES?: ReadonlyArray<{ name: string }>;
     HAS_AUTH?: boolean;
+    HAS_SIGNUP?: boolean;
   };
   if (!mod.APP_FEATURES) {
     throw new Error(
@@ -85,6 +86,12 @@ async function readMountedFeatures(runConfigPath: string): Promise<Set<string>>
   if (mod.HAS_AUTH ?? true) {
     for (const name of implicitAuthModeFeatureNames()) set.add(name);
   }
+  // auth-self-registration is only prepended when authOptions.signup is set
+  // (composeFeatures) — opt-in via HAS_SIGNUP so apps without signup don't
+  // get a stale-registry false positive (#1521).
+  if (mod.HAS_SIGNUP === true) {
+    set.add("auth-self-registration");
+  }
   return set;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.164.0",
+  "version": "0.165.1",
   "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.164.0",
-    "@cosmicdrift/kumiko-framework": "0.164.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.164.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.165.1",
+    "@cosmicdrift/kumiko-framework": "0.165.1",
+    "@cosmicdrift/kumiko-server-runtime": "0.165.1",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/build-server-bundle.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { buildServerBundle } from "../build-server-bundle";
+import { buildServerBundle, readExtraRuntimeExternals } from "../build-server-bundle";
 
 // Baut ein Mini-App-Fixture (bin/main.ts + bin/kumiko.ts teilen ein Modul) und
 // prüft das Variante-B-Verhalten: ein Bun.build-Call → server.js + kumiko.js als
@@ -95,4 +95,134 @@ describe("buildServerBundle (multi-entry + splitting)", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  test("prefers node_modules/@cosmicdrift/* over packages/* when both declare a version", async () => {
+    // Framework-monorepo checkout: both the installed node_modules package
+    // (symlinked in real life, diverging here) and packages/framework exist.
+    // node_modules must win — it reflects what actually gets shipped/installed
+    // for the consumer, packages/framework is only a repo-root fallback.
+    const dir = makeFixture();
+    try {
+      const frameworkPkgDir = join(dir, "node_modules/@cosmicdrift/kumiko-framework");
+      mkdirSync(frameworkPkgDir, { recursive: true });
+      writeFileSync(
+        join(frameworkPkgDir, "package.json"),
+        `${JSON.stringify({ name: "@cosmicdrift/kumiko-framework", dependencies: { meilisearch: "^0.58.0" } })}\n`,
+      );
+
+      mkdirSync(join(dir, "packages/framework"), { recursive: true });
+      writeFileSync(
+        join(dir, "packages/framework/package.json"),
+        `${JSON.stringify({ name: "@cosmicdrift/kumiko-framework", dependencies: { meilisearch: "^0.30.0" } })}\n`,
+      );
+
+      const result = await buildServerBundle({ cwd: dir, outDir: join(dir, "dist-server") });
+
+      expect(result.runtimeDeps["meilisearch"]).toBe("^0.58.0");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("readExtraRuntimeExternals (package.json kumiko field, #1484)", () => {
+  test("reads string list from kumiko.extraRuntimeExternals", () => {
+    const dir = mkdtempSync(join(tmpdir(), "extra-ext-"));
+    try {
+      writeFileSync(
+        join(dir, "package.json"),
+        `${JSON.stringify({
+          name: "app",
+          kumiko: { extraRuntimeExternals: ["@napi-rs/canvas", "pdf-parse"] },
+        })}\n`,
+      );
+      expect(readExtraRuntimeExternals(dir)).toEqual(["@napi-rs/canvas", "pdf-parse"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("missing / invalid shapes yield empty list", () => {
+    const dir = mkdtempSync(join(tmpdir(), "extra-ext-bad-"));
+    try {
+      writeFileSync(join(dir, "package.json"), `${JSON.stringify({ name: "app" })}\n`);
+      expect(readExtraRuntimeExternals(dir)).toEqual([]);
+      writeFileSync(
+        join(dir, "package.json"),
+        `${JSON.stringify({ name: "app", kumiko: { extraRuntimeExternals: "nope" } })}\n`,
+      );
+      expect(readExtraRuntimeExternals(dir)).toEqual([]);
+      writeFileSync(
+        join(dir, "package.json"),
+        `${JSON.stringify({
+          name: "app",
+          kumiko: { extraRuntimeExternals: ["ok", 1, "", "  "] },
+        })}\n`,
+      );
+      expect(readExtraRuntimeExternals(dir)).toEqual(["ok"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("buildServerBundle + package.json extras (#1484)", () => {
+  test("extraRuntimeExternals from options land in runtimeDeps with app pin", async () => {
+    const dir = makeFixture();
+    try {
+      writeFileSync(
+        join(dir, "package.json"),
+        `${JSON.stringify({
+          name: "fixture-app",
+          dependencies: { "@napi-rs/canvas": "0.1.65" },
+          kumiko: { extraRuntimeExternals: ["@napi-rs/canvas"] },
+        })}\n`,
+      );
+      const extras = readExtraRuntimeExternals(dir);
+      const result = await buildServerBundle({
+        cwd: dir,
+        outDir: join(dir, "dist-server"),
+        extraRuntimeExternals: extras,
+      });
+      expect(result.runtimeDeps["@napi-rs/canvas"]).toBe("0.1.65");
+      const distPkg = JSON.parse(readFileSync(join(dir, "dist-server/package.json"), "utf-8")) as {
+        dependencies: Record<string, string>;
+      };
+      expect(distPkg.dependencies["@napi-rs/canvas"]).toBe("0.1.65");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("app package.json does not override framework runtime pins", async () => {
+    const dir = makeFixture();
+    try {
+      const frameworkPkgDir = join(dir, "node_modules/@cosmicdrift/kumiko-framework");
+      mkdirSync(frameworkPkgDir, { recursive: true });
+      writeFileSync(
+        join(frameworkPkgDir, "package.json"),
+        `${JSON.stringify({
+          name: "@cosmicdrift/kumiko-framework",
+          dependencies: { meilisearch: "^0.58.0" },
+        })}\n`,
+      );
+      writeFileSync(
+        join(dir, "package.json"),
+        `${JSON.stringify({
+          name: "fixture-app",
+          dependencies: { meilisearch: "^0.1.0", "@napi-rs/canvas": "0.1.65" },
+          kumiko: { extraRuntimeExternals: ["@napi-rs/canvas"] },
+        })}\n`,
+      );
+      const result = await buildServerBundle({
+        cwd: dir,
+        outDir: join(dir, "dist-server"),
+        extraRuntimeExternals: readExtraRuntimeExternals(dir),
+      });
+      expect(result.runtimeDeps["meilisearch"]).toBe("^0.58.0");
+      expect(result.runtimeDeps["@napi-rs/canvas"]).toBe("0.1.65");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

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

@@ -144,6 +144,29 @@ describe("composeStacks boots for real", () => {
     expect(() => validateBoot(features)).not.toThrow();
   });
 
+  test("money-horse-shaped composeGdprStack({sessions:true}) without a tokenVerifier provider passes boot", () => {
+    // Session-only stacks (#1570): composeGdprStack({sessions:true}) mounts
+    // auth-foundation + sessions (sessionStore). Cookie auth does not need a
+    // tokenVerifier; money-horse/solon run-configs pass none and must boot.
+    const features = composeFeatures([...composeGdprStack({ sessions: true })], {
+      includeBundled: true,
+    });
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("composeGdprStack({sessions:true, providers:[...]}) passes boot with a tokenVerifier mounted", () => {
+    const features = composeFeatures(
+      [
+        ...composeGdprStack({
+          sessions: true,
+          providers: [createPersonalAccessTokensFeature({ scopes: {} })],
+        }),
+      ],
+      { includeBundled: true },
+    );
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
   // auth-mfa's encrypted fields need a runtime KEK (env or configureEntityFieldEncryption
   // + secrets). Name-list + saas-identity-wire.integration.test.ts cover identity boot.
   test("identity stack names compose with ops + renderer under includeBundled", () => {

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

@@ -1,24 +1,15 @@
 // createKumikoServer error / graceful-degradation paths — boot rejects,
 // stylesheet pipeline failures, missing CSS route.
 
-import { afterEach, describe, expect, test } from "bun:test";
+import { 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";
+import { createKumikoServer } 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-"));

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

@@ -385,6 +385,13 @@ describe("createKumikoServer — real Bun.build (buildClient)", () => {
       const body = await res.text();
       expect(body.length).toBeGreaterThan(0);
       expect(body).toMatch(/ping/);
+
+      // Stop the watcher before teardown rmSync deletes clientEntry out from
+      // under it — a bare "client.tsx" delete event classifies as "restart"
+      // (classifyChange only special-cases endsWith("/client.tsx")) and
+      // process.exit(75) kills the whole bun test runner mid-suite.
+      await handle.stop();
+      handle = undefined;
     } finally {
       rmSync(tmpDir, { recursive: true, force: true });
     }

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

@@ -186,6 +186,27 @@ describe("scaffoldApp", () => {
     expect(readme).toContain("- `delivery`");
   });
 
+  test("callExpression/export-callability mismatch throws instead of silently mis-instantiating", async () => {
+    const dest = join(tmp, "my-shop");
+    await expect(
+      scaffoldApp({
+        name: "my-shop",
+        destination: dest,
+        features: [
+          {
+            name: "delivery",
+            importPath: "@cosmicdrift/kumiko-bundled-features/delivery",
+            exportName: "createDeliveryFeature",
+            // createDeliveryFeature is a factory function, but this claims it's
+            // a plain object export (no trailing "()") — must not silently push
+            // the function itself as a FeatureDefinition.
+            callExpression: "createDeliveryFeature",
+          },
+        ],
+      }),
+    ).rejects.toThrow(/is.*callable but callExpression/);
+  });
+
   test("bin/main.ts contains runProdApp + auth.admin stub + staticDir", async () => {
     const dest = join(tmp, "my-shop");
     await scaffoldApp({ name: "my-shop", destination: dest });

package/src/build-server-bundle.ts

@@ -224,6 +224,25 @@ function findRepoRoot(start: string): string | undefined {
   return undefined;
 }
 
+/** Read `package.json#kumiko.extraRuntimeExternals` for kumiko-build (#1484).
+ *  Invalid / missing shapes → empty list (CLI stays convention-driven). */
+export function readExtraRuntimeExternals(cwd: string): readonly string[] {
+  const pkgJson = join(cwd, "package.json");
+  if (!existsSync(pkgJson)) return [];
+  let raw: string;
+  try {
+    raw = readFileSync(pkgJson, "utf-8");
+  } catch {
+    return [];
+  }
+  const parsed = parseJsonSafe<{
+    kumiko?: { extraRuntimeExternals?: unknown };
+  }>(raw, {});
+  const list = parsed.kumiko?.extraRuntimeExternals;
+  if (!Array.isArray(list)) return [];
+  return list.filter((x): x is string => typeof x === "string" && x.trim().length > 0);
+}
+
 // Versionen für RUNTIME_EXTERNALS auflösen: erst aus den installierten
 // node_modules/@cosmicdrift/*-Packages (relativ zu cwd — funktioniert für
 // jede Consumer-App), dann als Zusatz aus packages/framework + bundled-
@@ -237,21 +256,42 @@ async function resolveRuntimeDepsVersions(
   const out: Record<string, string> = {};
 
   const pinSources = [
-    join(cwd, "node_modules/@cosmicdrift/kumiko-framework/package.json"),
-    join(cwd, "node_modules/@cosmicdrift/kumiko-bundled-features/package.json"),
     ...(repoRoot
       ? [
           join(repoRoot, "packages/framework/package.json"),
           join(repoRoot, "packages/bundled-features/package.json"),
         ]
       : []),
+    // node_modules applied last among framework sources so installed versions
+    // win over the repo-root fallback (#1217).
+    join(cwd, "node_modules/@cosmicdrift/kumiko-framework/package.json"),
+    join(cwd, "node_modules/@cosmicdrift/kumiko-bundled-features/package.json"),
   ];
   const allDeps: Record<string, string> = {};
   for (const path of pinSources) {
     if (!existsSync(path)) continue;
     const raw = await readFile(path, "utf-8");
-    const parsed = parseJsonOrThrow<{ dependencies?: Record<string, string> }>(raw, path);
-    Object.assign(allDeps, parsed.dependencies ?? {});
+    const parsed = parseJsonOrThrow<{
+      dependencies?: Record<string, string>;
+      optionalDependencies?: Record<string, string>;
+    }>(raw, path);
+    Object.assign(allDeps, parsed.dependencies ?? {}, parsed.optionalDependencies ?? {});
+  }
+  // App package.json fills gaps only — pins extraRuntimeExternals without
+  // overriding framework-native pins the app may also list (#1484 / review).
+  const appPkg = join(cwd, "package.json");
+  if (existsSync(appPkg)) {
+    const raw = await readFile(appPkg, "utf-8");
+    const parsed = parseJsonOrThrow<{
+      dependencies?: Record<string, string>;
+      optionalDependencies?: Record<string, string>;
+    }>(raw, appPkg);
+    for (const [name, ver] of Object.entries({
+      ...(parsed.dependencies ?? {}),
+      ...(parsed.optionalDependencies ?? {}),
+    })) {
+      if (allDeps[name] === undefined) allDeps[name] = ver;
+    }
   }
   for (const pkg of packages) {
     out[pkg] = allDeps[pkg] ?? "*";

package/src/build.ts

@@ -22,4 +22,5 @@ export {
   buildServerBundle,
   discoverServerEntry,
   formatServerBuildResult,
+  readExtraRuntimeExternals,
 } from "./build-server-bundle";

package/src/compose-stacks.ts

@@ -59,6 +59,11 @@ export type GdprStackOptions = {
   readonly order?: GdprStackOrder;
   readonly sessions?: boolean;
   readonly tenantLifecycle?: boolean;
+  /** Optional tokenVerifier provider(s) (e.g. PAT) when `sessions` is on.
+   *  Session-only stacks need none — sessions registers sessionStore, which
+   *  satisfies auth-foundation's boot check (#1570). Pass providers when the
+   *  app also wants Bearer/PAT auth. */
+  readonly providers?: readonly FeatureDefinition[];
 };
 
 export type UserDataRightsStackOptions = {
@@ -80,14 +85,12 @@ export type OpsStackOptions = {
  *  on composeFeatures(includeBundled). Pass `mfa` options to mount TOTP.
  *  When `sessions` is on (the default), auth-foundation is mounted alongside it —
  *  the framework's registry now hard-requires it (sessions.requires("auth-foundation")).
- *  Pass `providers` for the tokenVerifier(s) auth-foundation itself requires at least
- *  one of (e.g. createPersonalAccessTokensFeature({ scopes })) — PAT scopes are
- *  app-specific (which write-handlers an API token may call), so they stay caller-owned
- *  instead of a framework default. */
+ *  Session-only is enough for boot (#1570); optional Bearer/PAT still needs a
+ *  tokenVerifier provider from the caller (e.g. createPersonalAccessTokensFeature
+ *  ({ scopes })) — PAT scopes are app-specific, so they stay caller-owned. */
 export type IdentityStackOptions = {
   readonly sessions?: boolean;
   readonly mfa?: AuthMfaFeatureOptions;
-  readonly providers?: readonly FeatureDefinition[];
 };
 
 export function stackFeatureNames(features: readonly FeatureDefinition[]): string[] {
@@ -139,7 +142,10 @@ export function composeGdprStack(options: GdprStackOptions = {}): FeatureDefinit
   const out: FeatureDefinition[] =
     order === "compliance-first" ? [compliance, retention] : [retention, compliance];
   if (options.tenantLifecycle) out.push(createTenantLifecycleFeature());
-  if (options.sessions) out.push(authFoundationFeature, createSessionsFeature());
+  if (options.sessions) {
+    out.push(authFoundationFeature, createSessionsFeature());
+    if (options.providers) out.push(...options.providers);
+  }
   return out;
 }
 
@@ -172,7 +178,6 @@ export function composeIdentityStack(options: IdentityStackOptions = {}): Featur
   const out: FeatureDefinition[] = [];
   if (sessions) {
     out.push(authFoundationFeature, createSessionsFeature());
-    if (options.providers) out.push(...options.providers);
   }
   if (options.mfa !== undefined) out.push(createAuthMfaFeature(options.mfa));
   return out;

package/src/run-dev-app.ts

@@ -132,23 +132,28 @@ export type RunDevAppAuthOptions = {
    *  der request/confirm-Handler im auth-email-password-Feature wird
    *  registriert. Symmetrisch zu RunProdAppAuthOptions.passwordReset. */
   readonly passwordReset?: PasswordResetSetup;
-  /** Email-verification flow. Symmetric zu passwordReset. */
+  /** Email-verification flow. Symmetric to passwordReset. */
   readonly emailVerification?: EmailVerificationSetup;
-  /** Self-Signup flow (Magic-Link). Symmetric zu RunProdAppAuthOptions. */
+  /** Self-signup flow (magic link). Symmetric to RunProdAppAuthOptions. */
   readonly signup?: SignupSetup;
-  /** Tenant-Invite flow (Magic-Link). Symmetric. */
+  /** Tenant-invite flow (magic link). Symmetric. */
   readonly invite?: InviteSetup;
-  /** Account-unlock flow (#1266). Symmetric zu RunProdAppAuthOptions. */
+  /** Account-unlock flow (#1266). Symmetric to RunProdAppAuthOptions. */
   readonly accountUnlock?: AccountUnlockSetup;
   /** Domain attribute for both auth cookies (see
-   *  AuthRoutesConfig.cookieDomain). Symmetric zu RunProdAppAuthOptions. */
+   *  AuthRoutesConfig.cookieDomain). Symmetric to RunProdAppAuthOptions. */
   readonly cookieDomain?: string;
   /** Server-side Origin allowlist for the CSRF guard (see
-   *  AuthRoutesConfig.allowedOrigins). Symmetric zu RunProdAppAuthOptions —
+   *  AuthRoutesConfig.allowedOrigins). Symmetric to RunProdAppAuthOptions —
    *  required once `cookieDomain` is set. */
   readonly allowedOrigins?: readonly string[];
-  /** Opt out of the Origin guard. Symmetric zu RunProdAppAuthOptions. */
+  /** Opt out of the Origin guard. Symmetric to RunProdAppAuthOptions. */
   readonly unsafeSkipOriginCheck?: boolean;
+  /** Number of trusted reverse-proxy hops for client-IP derivation (see
+   *  AuthRoutesConfig.trustedProxyHops, kumiko-framework#1539). Symmetric to
+   *  RunProdAppAuthOptions — dev usually runs unproxied, so this is normally
+   *  left unset (default 0). */
+  readonly trustedProxyHops?: number;
 };
 
 /** Hook for app-specific seeding (demo data, fixtures). Runs after the
@@ -484,6 +489,9 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
         ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
           unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
+        ...(effectiveAuth.trustedProxyHops !== undefined && {
+          trustedProxyHops: effectiveAuth.trustedProxyHops,
+        }),
         ...sessionAuthFragment,
         ...patAuthFragment,
         ...tenantLifecycleAuthFragment,

package/src/scaffold-app.ts

@@ -852,6 +852,14 @@ async function instantiateScaffoldFeatures(
         `scaffoldApp: ${entry.importPath} missing export ${entry.exportName} for ${entry.callExpression}`,
       );
     }
+    const looksCallable = entry.callExpression.endsWith(")");
+    if (looksCallable !== (typeof exp === "function")) {
+      throw new Error(
+        `scaffoldApp: ${entry.importPath} export ${entry.exportName} is ${
+          typeof exp === "function" ? "" : "not "
+        }callable but callExpression "${entry.callExpression}" says otherwise`,
+      );
+    }
     if (typeof exp === "function") {
       instances.push((exp as (...args: unknown[]) => FeatureDefinition)(...(entry.callArgs ?? [])));
     } else {