@cosmicdrift/kumiko-dev-server 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @cosmicdrift/kumiko-dev-server
 
+## 0.5.0
+
+### Minor Changes
+
+- 7ff69ab: feat(es-ops): Phase 1 — file-based seed-migrations
+
+  Neues first-class Operations-Pattern fürs Framework. Liefert `seed-migrations`
+  als drizzle-migrate-equivalent für Event-Sourcing-Aggregate-Updates die
+  idempotent-Seeder nicht erfassen können (z.B. „Member hat schon eine
+  Rolle, aber jetzt soll noch eine dazukommen").
+
+  Public-API:
+
+  - `runProdApp({ seedsDir })` — Auto-apply pending Migrations beim Boot
+  - `SeedMigration`-Interface (default-Export einer `seeds/<id>.ts`-File)
+  - `SeedMigrationContext` mit `systemWriteAs` (ruft existing write-handler
+    als System-User) + Read-Helpers (`findUserByEmail`,
+    `findMembershipsOfUser`, `findTenants`)
+  - CLI: `bunx kumiko ops seed:new|status|apply`
+  - Tracking-Table `kumiko_es_operations` mit `operation_type`-Discriminator
+    (vorbereitet auf Phase 2+ Operations: projection-rebuild, event-replay,
+    stream-migration, ...)
+  - Env-Flags: `KUMIKO_SKIP_ES_OPS=1` (alle skippen für Recovery),
+    `KUMIKO_SKIP_ES_OPS_<ID>=1` (einzelne kaputte skippen)
+
+  Garantien: single-run via tracking, atomic via per-migration-Tx,
+  chronological order via filename-prefix, fail-stop bei Failure (kein
+  Partial-Apply), ES-konform via Handler-Dispatch.
+
+  Sub-path-Export: `@cosmicdrift/kumiko-framework/es-ops`
+
+  Plan-Doc: `kumiko-platform/docs/plans/features/es-ops.md`
+  Recipe: `samples/recipes/seed-migration/`
+  Driver-Use-Case: publicstatus admin-roles-drift (parallel-Branch
+  `feat/es-ops-driver-admin-roles`).
+
+  Phase 2+ skizziert + offen markiert — Implementation pro Use-Case.
+
+### Patch Changes
+
+- Updated dependencies [7ff69ab]
+  - @cosmicdrift/kumiko-framework@0.5.0
+  - @cosmicdrift/kumiko-bundled-features@0.5.0
+
+## 0.4.1
+
+### Patch Changes
+
+- 010b410: feat(auth-email-password): "Bestätigungs-Mail erneut senden" im LoginScreen
+
+  LoginScreen bietet bei reason=email_not_verified jetzt einen Resend-Link
+  im Fehler-Banner — der existierende `requestEmailVerification`-Endpoint
+  wird direkt aufgerufen, der Banner wechselt nach Erfolg zum Info-Variant
+  ("Wir haben dir eine neue Bestätigungs-Mail geschickt.").
+
+  UX-Details:
+
+  - Bei 429 → inline-Hint "Bitte warte kurz und versuche es erneut."
+  - Bei Netzwerk/sonstigen Fehlern → inline-Hint "Konnte nicht senden."
+  - Anti-Typo-Gate: ändert der User die Email-Eingabe nach dem Login-Fail,
+    verschwindet der Resend-Link — sonst würde Resend silent-success an die
+    geänderte (potentiell typoed) Adresse gehen ohne User-Feedback.
+  - Andere Failure-Codes (invalid_credentials etc.) zeigen weiterhin keinen
+    Resend-Link.
+
+  i18n: 4 neue Keys (DE+EN) im `auth.login.resend*`-Namespace, additive.
+  Apps die ihre Translations override-en müssen nichts ändern.
+
+  Additive UI-Feature — keine API-Breaks, keine Schema-Migration.
+
+- Updated dependencies [010b410]
+  - @cosmicdrift/kumiko-framework@0.4.1
+  - @cosmicdrift/kumiko-bundled-features@0.4.1
+
 ## 0.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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>",
@@ -48,8 +48,8 @@
     "kumiko-dev": "./bin/kumiko-dev.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.4.0",
-    "@cosmicdrift/kumiko-framework": "0.4.0"
+    "@cosmicdrift/kumiko-bundled-features": "0.5.0",
+    "@cosmicdrift/kumiko-framework": "0.5.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/__tests__/config-seed-boot.integration.ts

@@ -0,0 +1,157 @@
+// Pins the boot-wiring contract for config-seeds. runDevApp's onAfterSetup
+// and runProdApp's seed-block both call `applyBootSeeds(...)` — this test
+// calls the SAME helper, so if someone removes the call site from
+// runDevApp / runProdApp the helper still has at least one caller (this
+// test). Code review then sees an orphaned helper, not a silently broken
+// boot. For a stricter end-to-end pin you'd start an actual runDevApp;
+// that's heavy and not done here.
+//
+// Tests:
+//   1. seed rows land in the projection after applyBootSeeds runs,
+//   2. a re-boot is a no-op (idempotent),
+//   3. an admin set on top of a seed wins the resolver cascade; coexistence
+//      vs. override semantics depend on the admin user's tenantId.
+
+import {
+  configValuesTable,
+  createConfigAccessorFactory,
+  createConfigFeature,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  access,
+  createSystemConfig,
+  createSystemSeed,
+  createTenantConfig,
+  createTenantSeed,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { applyBootSeeds } from "../boot/apply-boot-seeds";
+
+const bootSeedsFeature = defineFeature("boot-seeds-test", (r) => {
+  r.requires("config");
+  r.config({
+    keys: {
+      siteName: createTenantConfig("text", {
+        default: "DEFAULT_SITE",
+        read: access.all,
+        write: access.all,
+      }),
+      maintenance: createSystemConfig("boolean", {
+        default: false,
+        read: access.all,
+        write: access.systemAdmin,
+      }),
+    },
+    seeds: {
+      siteName: createTenantSeed({ value: "from-seed" }),
+      maintenance: createSystemSeed({ value: true }),
+    },
+  });
+});
+
+const SITE_KEY = "boot-seeds-test:config:site-name";
+const MAINT_KEY = "boot-seeds-test:config:maintenance";
+
+let stack: TestStack;
+const resolver = createConfigResolver();
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createConfigFeature(), bootSeedsFeature],
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    }),
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("config-seed boot wiring", () => {
+  test("first boot: applyBootSeeds writes one row per seed", async () => {
+    await applyBootSeeds({ registry: stack.registry, db: stack.db });
+
+    const rows = await stack.db.select().from(configValuesTable);
+    expect(rows.length).toBe(2);
+
+    const siteKeyDef = stack.registry.getConfigKey(SITE_KEY);
+    expect(siteKeyDef).toBeDefined();
+    const sitePeek = await resolver.get(
+      SITE_KEY,
+      siteKeyDef!,
+      TestUsers.systemAdmin.tenantId,
+      TestUsers.systemAdmin.id,
+      stack.db,
+    );
+    expect(sitePeek).toBe("from-seed");
+
+    const maintKeyDef = stack.registry.getConfigKey(MAINT_KEY);
+    expect(maintKeyDef).toBeDefined();
+    const maintPeek = await resolver.get(
+      MAINT_KEY,
+      maintKeyDef!,
+      TestUsers.systemAdmin.tenantId,
+      TestUsers.systemAdmin.id,
+      stack.db,
+    );
+    expect(maintPeek).toBe(true);
+  });
+
+  test("re-boot: idempotent — every seed already on disk → no extra rows", async () => {
+    await applyBootSeeds({ registry: stack.registry, db: stack.db });
+
+    const rows = await stack.db.select().from(configValuesTable);
+    expect(rows.length).toBe(2);
+  });
+
+  test("admin set on top of seed wins resolver — Re-Boot preserves admin", async () => {
+    // siteName is a TENANT-scope key. The seed writes a row under
+    // SYSTEM_TENANT_ID (= "for all tenants"). An admin on a real tenant
+    // writes a row under THAT tenantId — higher specificity. Both rows
+    // coexist; the resolver returns the more specific one.
+    //
+    // If the admin happens to write as SYSTEM_TENANT_ID (e.g. test user
+    // is the system-admin on the system-tenant), the admin write hits
+    // the seed-row directly and updates the same aggregate stream. Both
+    // paths end up with the admin value winning — the row-count
+    // assertion makes the path explicit.
+    await stack.http.writeOk(
+      "config:write:set",
+      { key: SITE_KEY, value: "admin-override", scope: "tenant" },
+      TestUsers.systemAdmin,
+    );
+
+    await applyBootSeeds({ registry: stack.registry, db: stack.db });
+
+    const siteKeyDef = stack.registry.getConfigKey(SITE_KEY);
+    expect(siteKeyDef).toBeDefined();
+    const peek = await resolver.get(
+      SITE_KEY,
+      siteKeyDef!,
+      TestUsers.systemAdmin.tenantId,
+      TestUsers.systemAdmin.id,
+      stack.db,
+    );
+    expect(peek).toBe("admin-override");
+
+    // Row-count tells us which path was hit:
+    //   - 2 rows = override path (admin tenantId === SYSTEM_TENANT_ID,
+    //     updated the seed-stream in place).
+    //   - 3 rows = coexistence path (admin tenantId !== SYSTEM_TENANT_ID,
+    //     new specific-tenant row sits next to the seed system-row).
+    // Either is correct as long as the resolver picks the admin value.
+    const rows = await stack.db.select().from(configValuesTable);
+    expect([2, 3]).toContain(rows.length);
+  });
+});

package/src/boot/apply-boot-seeds.ts

@@ -0,0 +1,17 @@
+import { seedAllConfigValues } from "@cosmicdrift/kumiko-bundled-features/config";
+import type { DbConnection, EncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+
+// Single boot-seed entry-point. runDevApp + runProdApp both call this
+// from their post-stack hook, so the wiring lives in exactly one place
+// — config-seed-boot.integration.ts pins this helper, which means a
+// missing call site (e.g. someone deletes the line from runDevApp)
+// surfaces as a missing-helper-use in code review rather than silently
+// shipping a server that never seeds.
+export async function applyBootSeeds(deps: {
+  registry: Registry;
+  db: DbConnection;
+  encryption?: EncryptionProvider;
+}): Promise<void> {
+  await seedAllConfigValues(deps.registry, deps.db, deps.encryption);
+}

package/src/run-dev-app.ts

@@ -24,7 +24,6 @@ import {
   type SessionCallbacks,
 } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
-
 import type { SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
 import {
   type EffectiveFeaturesResolver,
@@ -35,6 +34,7 @@ import {
   type TierResolverPlugin,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
+import { applyBootSeeds } from "./boot/apply-boot-seeds";
 
 import { watchAndRegenerate } from "./codegen";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
@@ -325,6 +325,11 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
       if (options.auth) {
         await seedAdmin(stack.db, options.auth.admin);
       }
+      // Apply r.config({ seeds }) declared by any registered feature.
+      // Runs before user-supplied seed callbacks so those can read /
+      // override the deploy-defaults. The helper indirection is what
+      // config-seed-boot.integration.ts pins — keep it as a single call.
+      await applyBootSeeds({ registry: stack.registry, db: stack.db });
       for (const seed of options.seeds ?? []) {
         await seed(stack);
       }

package/src/run-prod-app.ts

@@ -42,7 +42,7 @@ import { createSessionCallbacks } from "@cosmicdrift/kumiko-bundled-features/ses
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
 import { createSseBroker, type SseBroker } from "@cosmicdrift/kumiko-framework/api";
-import { createDbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createDbConnection, type DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import {
   buildAppSchema,
   createRegistry,
@@ -58,13 +58,20 @@ import {
   type ApiEntrypointOptions,
   createApiEntrypoint,
 } from "@cosmicdrift/kumiko-framework/entrypoint";
+import {
+  createEsOperationsTable,
+  createSeedMigrationContext,
+  runPendingSeedMigrations,
+} from "@cosmicdrift/kumiko-framework/es-ops";
 import { assertSchemaCurrent, SchemaDriftError } from "@cosmicdrift/kumiko-framework/migrations";
 import {
+  createDispatcher,
   createEntityCache,
   createEventDedup,
   createIdempotencyGuard,
 } from "@cosmicdrift/kumiko-framework/pipeline";
 import Redis from "ioredis";
+import { applyBootSeeds } from "./boot/apply-boot-seeds";
 import { ASSETS_DIR } from "./build-prod-bundle";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
 import { injectSchema } from "./inject-schema";
@@ -274,6 +281,12 @@ export type RunProdAppOptions = {
   readonly auth?: RunProdAppAuthOptions;
   /** Custom seed functions, run after the admin seed (when auth-mode). */
   readonly seeds?: readonly ProdSeedFn[];
+  /** Pfad zum seeds-Directory für ES-Operations / Seed-Migrations
+   *  (file-basiert wie drizzle-migrate). Wenn gesetzt + KUMIKO_SKIP_ES_OPS
+   *  != "1": runProdApp scannt das Verzeichnis nach `<id>.ts` Files,
+   *  diff vs kumiko_es_operations-Table, läuft pending in Tx.
+   *  Plan: kumiko-platform/docs/plans/features/es-ops.md */
+  readonly seedsDir?: string;
   /** Anonymous-access for public endpoints (same shape as runDevApp).
    *  Akzeptiert entweder einen statischen Config-Object ODER eine
    *  Factory `({db, redis, registry}) => Config` — die Factory wird
@@ -589,17 +602,42 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // statt eines fixed JSON-Strings. Heute: registry-static, also OK.
   const appSchemaJson = JSON.stringify(buildAppSchema(registry));
 
-  // 9. Seeds: admin first, then app-specific. Both expected to be
-  //    idempotent — runProdApp doesn't gate "first boot" via flag,
-  //    seeds check their own preconditions. seedAdmin checks email,
-  //    app seeds typically check "is my fixture row there?".
+  // 9. Seeds: admin first, then config-seeds from r.config({seeds}),
+  //    then app-specific. All idempotent — runProdApp doesn't gate
+  //    "first boot" via flag, every seed-step checks its own
+  //    preconditions. Config-seeds rely on a deterministic
+  //    aggregate-id so re-boot becomes a version_conflict skip.
   if (options.auth) {
     await seedAdmin(db, options.auth.admin);
   }
+  await applyBootSeeds({ registry, db });
   for (const seed of options.seeds ?? []) {
     await seed({ db });
   }
 
+  // ES-Operations / Seed-Migrations (Phase 1). Läuft NACH applyBootSeeds +
+  // existing seeds-array — die deklarativen Seeds sind die "always-insert-
+  // if-missing"-Schicht; seed-migrations sind die "diff-and-update"-
+  // Schicht für Drift den existing Seeds nicht erfassen können (z.B.
+  // Membership-Roles-Change nach initialer Seed-Erstellung).
+  if (options.seedsDir !== undefined && process.env["KUMIKO_SKIP_ES_OPS"] !== "1") {
+    await createEsOperationsTable(db);
+    const seedDispatcher = createDispatcher(registry, {
+      db,
+      redis,
+      entityCache,
+      registry,
+      ...extraContext,
+    });
+    await runPendingSeedMigrations({
+      db,
+      seedsDir: options.seedsDir,
+      appliedBy: "boot",
+      createContext: (dbRunner: DbRunner) =>
+        createSeedMigrationContext({ dispatcher: seedDispatcher, dbRunner }),
+    });
+  }
+
   await entrypoint.start();
 
   // 10. App-eigene HTTP-Routes mounten — vor dem static-fallback. Hono