@cosmicdrift/kumiko-dev-server 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,57 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Marc Frost
+
+Licensed Work:        @cosmicdrift/kumiko-framework
+                      The Licensed Work is © 2026 Marc Frost.
+
+Additional Use Grant: 
+You may use the Licensed Work in production for any purpose, including 
+commercially, EXCEPT for the Restricted Use. 
+
+"Restricted Use" is defined as using the Licensed Work to provide a platform 
+or service to third parties that allows them to host, deploy, or run their 
+own applications built with the Licensed Work. This includes, but is not 
+limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
+platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
+managed offering of the Licensed Work.
+
+This restriction does not apply to the Licensor, any entity controlled by, 
+controlling, or under common control with the Licensor ("Affiliates"), or 
+contractors acting on their behalf. The Licensor remains free to use the 
+Licensed Work for any purpose, including for the operation of kumiko.so.
+
+Change Date:          2030-05-05
+Change License:       Apache License, Version 2.0
+
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, 
+redistribute, and make non-production use of the Licensed Work. The Licensor may 
+make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly 
+available distribution of the Licensed Work under this License, whichever comes 
+first, this License will convert to the Change License.
+
+This Business Source License governs use of the Licensed Work in all cases, except 
+as to any use that is explicitly granted in the Additional Use Grant above or 
+under the Change License after the Change Date.
+
+If your use of the Licensed Work does not comply with the requirements of this 
+License, you must cease use of the Licensed Work immediately.
+
+All copies of the Licensed Work, and all derivative works thereof, must include 
+this License.
+
+This License does not grant you any right, title, or interest in any trademark, 
+logo, or branding of the Licensor, except as required to comply with this License.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
+“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
+WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
+TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
+ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Development server bootstrap for Kumiko apps. Bundles the client, mints dev-JWTs, injects the resolved AppSchema, and seeds an admin. Not for production.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cosmicdriftgamestudio/kumiko-framework.git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
     "directory": "packages/dev-server"
   },
   "bugs": {
-    "url": "https://github.com/cosmicdriftgamestudio/kumiko-framework/issues"
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
   },
   "homepage": "https://kumiko.so",
   "type": "module",

package/src/__tests__/compose-features-wiring.integration.ts

@@ -36,11 +36,11 @@ import { seedTenantMembership } from "@cosmicdrift/kumiko-bundled-features/tenan
 import { UserHandlers, userEntity, userTable } from "@cosmicdrift/kumiko-bundled-features/user";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
-  createEntityTable,
-  pushTables,
   setupTestStack,
   type TestStack,
   TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "vitest";
 import { composeFeatures } from "../compose-features";
@@ -110,9 +110,9 @@ async function bootStack(
     },
   });
 
-  await createEntityTable(stack.db, userEntity);
-  await createEntityTable(stack.db, tenantEntity);
-  await pushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
 
   return { stack, resetEmails, verifyEmails };
 }

package/src/__tests__/run-prod-app.integration.ts

@@ -27,7 +27,7 @@ import {
   createEventConsumerStateTable,
   createProjectionStateTable,
 } from "@cosmicdrift/kumiko-framework/pipeline";
-import { ensureEntityTable } from "@cosmicdrift/kumiko-framework/stack";
+import { unsafeEnsureEntityTable } from "@cosmicdrift/kumiko-framework/stack";
 import { sql } from "drizzle-orm";
 import postgres from "postgres";
 import { afterEach, beforeAll, describe, expect, test } from "vitest";
@@ -116,7 +116,7 @@ async function migrateTestDb(): Promise<void> {
     await createArchivedStreamsTable(db);
     await createProjectionStateTable(db);
     await createEventConsumerStateTable(db);
-    await ensureEntityTable(db, widgetEntity, "widget");
+    await unsafeEnsureEntityTable(db, widgetEntity, "widget");
   } finally {
     await close();
   }
@@ -167,7 +167,7 @@ describe("runProdApp", () => {
   test("second boot against the same DB is idempotent — no crash, no duplicate tables", async () => {
     await boot();
     // First boot left tables in place. Restart on the same DB —
-    // ensureEntityTable should be a no-op for the existing rows.
+    // unsafeEnsureEntityTable should be a no-op for the existing rows.
     const second = await boot();
 
     const res = await second.entrypoint.app.fetch(new Request("http://test/health"));

package/src/create-kumiko-server.ts

@@ -23,7 +23,7 @@ import { type AuthRoutesConfig, generateToken } from "@cosmicdrift/kumiko-framew
 import { buildAppSchema, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
-  ensureEntityTable,
+  pushEntityProjectionTables,
   setupTestStack,
   type TestStack,
   type TestStackOptions,
@@ -170,8 +170,16 @@ export type CreateKumikoServerOptions = {
    *  Handler `roles: ["anonymous"]` deklariert. Tenant-Resolution per
    *  Header/Cookie/Default; siehe AnonymousAccessConfig. */
   readonly anonymousAccess?: TestStackOptions["anonymousAccess"];
+  /** Feature-toggle resolver — durchgereicht an setupTestStack. Wenn
+   *  gesetzt, konsultiert der dispatcher-feature-gate, hook-filter, MSP-
+   *  filter den callback; absent = alle features always-on. Erforderlich
+   *  für Tier-Composition (Sprint 8) wo per-Tenant unterschiedliche
+   *  features aktiv sein sollen. Die typische produktive Implementierung
+   *  ist `() => globalFeatureToggleRuntime.effectiveFeatures` post-boot
+   *  (createLateBoundHolder-pattern, weil runtime stack.db braucht). */
+  readonly effectiveFeatures?: TestStackOptions["effectiveFeatures"];
   /** Wird nach dem Aufsetzen der Entity-Tabellen aufgerufen. Hook für
-   *  non-entity-tables (pushTables) und Seeding (admin user, initial
+   *  non-entity-tables (unsafePushTables) und Seeding (admin user, initial
    *  tenant, …). Muss idempotent sein — im persistent-DB-Modus läuft
    *  es bei jedem Boot. */
   readonly onAfterSetup?: (stack: TestStack) => Promise<void>;
@@ -526,26 +534,6 @@ async function startTailwindWatcher(
   };
 }
 
-// Create all entity tables declared by the given features. Uses
-// ensureEntityTable so a persistent DB (KUMIKO_DEV_DB_NAME) can
-// reuse tables from the previous boot without the caller having to
-// check.
-async function createEntityTablesForFeatures(
-  stack: TestStack,
-  features: readonly FeatureDefinition[],
-): Promise<void> {
-  for (const feature of features) {
-    for (const [entityName, entity] of Object.entries(feature.entities)) {
-      const created = await ensureEntityTable(stack.db, entity, entityName);
-      if (!created) {
-        logInfo(
-          `[kumiko-server] table ${entity.table ?? entityName} already exists — skipping create`,
-        );
-      }
-    }
-  }
-}
-
 /** @internal — normalisierte Client-Entry-Form, einheitlich über
  *  Single-Mode (`clientEntry`) und Multi-Mode (`clientEntries`). */
 type NormalizedEntry = {
@@ -661,9 +649,12 @@ export async function createKumikoServer(
     ...(options.auth !== undefined && { authConfig: options.auth }),
     ...(options.extraContext !== undefined && { extraContext: options.extraContext }),
     ...(options.anonymousAccess !== undefined && { anonymousAccess: options.anonymousAccess }),
+    ...(options.effectiveFeatures !== undefined && {
+      effectiveFeatures: options.effectiveFeatures,
+    }),
   });
   await createEventsTable(stack.db);
-  await createEntityTablesForFeatures(stack, options.features);
+  await pushEntityProjectionTables(stack, stack.registry);
 
   // Hook für Caller-spezifische Tables + Seed. Läuft nach den Entity-
   // Tabellen damit das Sample auf `stack.db` / `stack.dispatcher`

package/src/run-dev-app.ts

@@ -26,7 +26,14 @@ import {
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 
 import type { SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
-import type { FeatureDefinition, SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type EffectiveFeaturesResolver,
+  type FeatureDefinition,
+  findTierResolverUsage,
+  type SessionUser,
+  type TenantId,
+  type TierResolverPlugin,
+} from "@cosmicdrift/kumiko-framework/engine";
 import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
 
 import { watchAndRegenerate } from "./codegen";
@@ -138,6 +145,13 @@ export type RunDevAppOptions = {
    *  Hono-app gehängt, läuft VOR dem static-asset-Pfad. Symmetrisch zur
    *  gleichnamigen Option in runProdApp. */
   readonly extraRoutes?: CreateKumikoServerOptions["extraRoutes"];
+  /** Feature-toggle resolver — durchgereicht an createKumikoServer →
+   *  setupTestStack. Sprint-8 Tier-Composition: per-Tenant unterschied-
+   *  liche features aktiv via globalFeatureToggleRuntime. Pattern in
+   *  bin/server.ts: createLateBoundHolder + post-boot runtime.initialize
+   *  in einem seed-fn, weil die runtime stack.db braucht und die seed-
+   *  Funktionen nach setupTestStack laufen. */
+  readonly effectiveFeatures?: CreateKumikoServerOptions["effectiveFeatures"];
 };
 
 export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServerHandle> {
@@ -163,6 +177,33 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(composeAuthOptions && { authOptions: composeAuthOptions }),
   });
 
+  // Sprint-8a Tier-Composition auto-wire: scan features for a
+  // tenantTierResolver-extension. If found AND user didn't supply own
+  // effectiveFeatures, we wire a late-bound wrapper here and fill it
+  // in onAfterSetup (where stack.db + stack.registry are available).
+  // App-Author sees nothing — `createTierEngineFeature(opts)` mounts +
+  // framework auto-wires.
+  const tierResolverUsage = options.effectiveFeatures ? undefined : findTierResolverUsage(features);
+  const tierResolverHolder: { resolver: EffectiveFeaturesResolver | undefined } = {
+    resolver: undefined,
+  };
+  const finalEffectiveFeatures: EffectiveFeaturesResolver | undefined =
+    options.effectiveFeatures ??
+    (tierResolverUsage
+      ? (tenantId: TenantId) => {
+          // Defensive: Server starts AFTER onAfterSetup completes, so the
+          // resolver is filled before any request comes in. Throwing here
+          // means a programming error (boot order) rather than silent
+          // "all-features-on" misbehavior.
+          if (!tierResolverHolder.resolver) {
+            throw new Error(
+              "tier-resolver: extension found but resolver not yet built — boot order issue?",
+            );
+          }
+          return tierResolverHolder.resolver(tenantId);
+        }
+      : undefined);
+
   // configResolver-default fürs config-feature — im auth-mode immer
   // hinzufügen, im no-auth-mode dem Caller überlassen. Factory-form
   // wird gewrap't damit der spread auf das aufgerufene Result greift,
@@ -216,6 +257,9 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(extraContext !== undefined && { extraContext }),
     ...(options.anonymousAccess !== undefined && { anonymousAccess: options.anonymousAccess }),
     ...(options.extraRoutes !== undefined && { extraRoutes: options.extraRoutes }),
+    ...(finalEffectiveFeatures !== undefined && {
+      effectiveFeatures: finalEffectiveFeatures,
+    }),
     ...(options.auth && {
       auth: {
         membershipQuery: TenantQueries.memberships,
@@ -261,6 +305,16 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
       },
     }),
     onAfterSetup: async (stack) => {
+      // Sprint-8a: build tier-resolver BEFORE any seeds so seeds can rely
+      // on the resolver being live (e.g. seed that writes a SystemAdmin's
+      // tier-assignment can immediately read tier-cuts).
+      if (tierResolverUsage) {
+        const plugin = tierResolverUsage.options as TierResolverPlugin;
+        tierResolverHolder.resolver = await plugin.build({
+          db: stack.db,
+          registry: stack.registry,
+        });
+      }
       if (options.auth?.sessions !== undefined) {
         const expiresInMs = options.auth.sessions.expiresInMs;
         sessionCallbacks = createSessionCallbacks({

package/src/run-prod-app.ts

@@ -46,7 +46,11 @@ import { createDbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   buildAppSchema,
   createRegistry,
+  type EffectiveFeaturesResolver,
   type FeatureDefinition,
+  findTierResolverUsage,
+  type TenantId,
+  type TierResolverPlugin,
   validateBoot,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -351,6 +355,12 @@ export type RunProdAppOptions = {
    *  the fetch-handler directly (Bun.serve isn't available under vitest +
    *  node), then call handle.listen() manually if needed. */
   readonly autoListen?: boolean;
+  /** Feature-toggle resolver — durchgereicht an createApiEntrypoint's
+   *  dispatcherOptions. Sprint-8 Tier-Composition: per-Tenant unterschied-
+   *  liche features aktiv via globalFeatureToggleRuntime. Pattern:
+   *  createLateBoundHolder + post-boot runtime.initialize in einem
+   *  seed-fn (db ist erst nach migrations + features ready). */
+  readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
 };
 
 export type ProdAppHandle = {
@@ -403,6 +413,20 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   validateBoot(features);
   const registry = createRegistry(features);
 
+  // Sprint-8a Tier-Composition auto-wire: scan features for a
+  // tenantTierResolver-extension. If found AND user didn't supply own
+  // effectiveFeatures, build the resolver here (db + registry are
+  // available) before the dispatcher is constructed. App-Author sees
+  // nothing — `createTierEngineFeature(opts)` mounts + framework auto-wires.
+  let resolvedEffectiveFeatures: EffectiveFeaturesResolver | undefined = options.effectiveFeatures;
+  if (resolvedEffectiveFeatures === undefined) {
+    const tierResolverUsage = findTierResolverUsage(features);
+    if (tierResolverUsage) {
+      const plugin = tierResolverUsage.options as TierResolverPlugin;
+      resolvedEffectiveFeatures = await plugin.build({ db, registry });
+    }
+  }
+
   // 5. Schema-Drift-Gate. Drizzle-kit migrate (yarn kumiko migrate apply)
   //    läuft als CI-Step VOR dem Container-Rollout. Boot prüft hier nur:
   //      (a) Alle Migrations aus drizzle/migrations/meta/_journal.json
@@ -486,7 +510,10 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     jwtSecret,
     ...(jwtIssuer && { jwtIssuer }),
     ...(instanceId && { instanceId }),
-    dispatcherOptions: { idempotency },
+    dispatcherOptions: {
+      idempotency,
+      ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
+    },
     eventDedup,
     ...(options.auth && {
       auth: {