@cosmicdrift/kumiko-bundled-features 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @cosmicdrift/kumiko-bundled-features
 
+## 0.6.0
+
+### Minor Changes
+
+- 8489d18: feat(es-ops): Phase 1.5 — tenantIdOverride + dry-run-validator + E2E-Test + Doku
+
+  Phase 1.5 schließt die Lücken aus Phase 1 die den ersten Driver-Use-Case
+  (publicstatus admin-roles) blockten. Siehe Retro:
+  `kumiko-platform/docs/plans/features/es-ops-phase1-retro.md` (PR #9).
+
+  **A1 — tenantIdOverride:**
+  `SeedMigrationContext.systemWriteAs(qn, payload, tenantIdOverride?)`.
+  Default SYSTEM_TENANT_ID (unverändert für System-scope-Aggregates wie
+  config-values). Mit override: `createSystemUser(tenantIdOverride)` als
+  Executor, damit der Event-Store-Executor den Aggregate-Stream im
+  richtigen Tenant findet. Fix für die `version_conflict`-Klasse-Bug
+  (Memory `feedback_event_store_tenant_consistency.md`).
+
+  **A2 — dry-run-validator:**
+  Runner parsed seed-files vor `migration.run()` per regex
+  `systemWriteAs\(["']([^"']+)["']`, sammelt handler-QNs, validiert
+  gegen `registry.getWriteHandler(qn)`. Fail-fast mit klarer Message
+
+  - Datei + QN statt zur Runtime "handler not found". Catched camelCase-
+    typos (kebab-case-vs-camelCase Drift) + andere QN-Drift zur Boot-Zeit.
+    runProdApp reicht den richtigen Registry rein (`registry` neu in
+    RunPendingSeedMigrationsArgs).
+
+  **A3 — E2E-Test:**
+  `packages/bundled-features/src/__tests__/es-ops-e2e.integration.ts`
+  mit `setupTestStack`-Pattern: tenant+config Features echt geladen,
+  echtes Membership-Aggregate via TenantHandlers.addMember im Demo-Tenant,
+  seed-migration ruft update-member-roles mit tenantIdOverride → write
+  geht durch, Marker landed, Event in Store, Read-Model aktualisiert.
+  Plus typo-Test: seed mit camelCase fail-t Dry-Run mit
+  `/dry-run found.*unknown handler-QN/`. **TDD-First**: ohne A1+A2 wäre
+  der test rot.
+
+  **A4 — Doku:**
+  `framework/src/es-ops/README.md` erweitert um „Wann brauche ich
+  tenantIdOverride?" + „Deployment-Anforderungen" (Docker COPY, Idempotenz,
+  Multi-Replica) + „Lokaler Smoke vor Push". Recipe-README + seed-files
+  auf neue API aktualisiert.
+
+  **A5 — Smoke-Skript-Template:**
+  `samples/recipes/seed-migration/scripts/smoke.ts` als copy-paste-Template
+  für App-Authors: Bun-runnable, offline (read-only, kein DB-Write),
+  validiert Module-Load + QN-Resolution + System-User-Access. Recipe-
+  README dokumentiert Pflicht-Pattern.
+
+  **Bonus-Fix:**
+  `tenant:write:create`-access auf `["system", "SystemAdmin"]` erweitert
+  (symmetrisch zu update-member-roles). Aufgedeckt durch Recipe-Smoke +
+  initial-tenants-Seed. Pinning-Test in `tenant.integration.ts` updated.
+
+  **Test-State:** 45/45 grün (Pre-Push). Typecheck clean. Biome clean.
+  as-cast-Audit clean. Guard-silent-skip clean. Recipe-Smoke clean.
+
+  **Folge-Step (separater PR):** publicstatus driver-sample reaktivieren
+  mit lokalem Pre-Push-Smoke gegen publicstatus' echtes Feature-Set.
+
+### Patch Changes
+
+- Updated dependencies [8489d18]
+  - @cosmicdrift/kumiko-framework@0.6.0
+  - @cosmicdrift/kumiko-dispatcher-live@0.6.0
+  - @cosmicdrift/kumiko-renderer@0.6.0
+  - @cosmicdrift/kumiko-renderer-web@0.6.0
+
+## 0.5.2
+
+### Patch Changes
+
+- 4f0d781: fix(tenant): updateMemberRoles erlaubt "system"-Rolle (symmetrisch zu create)
+
+  Drift innerhalb des tenant-Features: `tenant:write:create` akzeptierte
+  `["system", "SystemAdmin"]`, `tenant:write:update-member-roles` aber
+  nur `["SystemAdmin"]`. Konsequenz: ops-tooling und seed-migrations
+  (`createSystemUser` mit `roles: ["system"]`) konnten den Handler nicht
+  aufrufen — `access_denied`.
+
+  Live entdeckt beim ersten Driver-Sample der es-ops Phase 1: publicstatus
+  seed `2026-05-20-fix-admin-roles.ts` rief `update-member-roles` via
+  `systemWriteAs` → access_denied → Pod CrashLoopBackOff.
+
+  Plus access-rule-Pinning-Test in `tenant.integration.ts`-scenario-7.
+
+- Updated dependencies [4f0d781]
+  - @cosmicdrift/kumiko-framework@0.5.2
+  - @cosmicdrift/kumiko-dispatcher-live@0.5.2
+  - @cosmicdrift/kumiko-renderer@0.5.2
+  - @cosmicdrift/kumiko-renderer-web@0.5.2
+
 ## 0.5.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -74,10 +74,10 @@
     "@aws-sdk/client-s3": "^3.1045.0",
     "@aws-sdk/lib-storage": "^3.1045.0",
     "@aws-sdk/s3-request-presigner": "^3.1045.0",
-    "@cosmicdrift/kumiko-dispatcher-live": "0.5.1",
-    "@cosmicdrift/kumiko-framework": "0.5.1",
-    "@cosmicdrift/kumiko-renderer": "0.5.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.5.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.6.0",
+    "@cosmicdrift/kumiko-framework": "0.6.0",
+    "@cosmicdrift/kumiko-renderer": "0.6.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.6.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/__tests__/es-ops-e2e.integration.ts

@@ -0,0 +1,211 @@
+// @no-server-stack: seed-runner ist boot-time-Code, kein HTTP-route.
+// setupTestStack/buildServer würden eine Hono-app aufziehen die wir nicht
+// brauchen — der seed-runner ruft dispatcher.write direkt vor dem
+// entrypoint.start(). Pattern matched die echte run-prod-app.ts-Integration
+// (siehe run-prod-app.ts:632 — createDispatcher mit identical ctx-shape
+// inline gebaut bevor entrypoint.start()).
+//
+// End-to-End-Integration-Test gegen real-Stack (Phase 1.5 / A3).
+// Catched die Bug-Klassen die runner.integration.ts mit Mock-Dispatcher
+// NICHT abdeckt:
+//   - handler-QN-Resolution (Bug 3)
+//   - access-rule-realität (Bug 4)
+//   - tenantId-stream-matching (Bug 5)
+//
+// Setup: createTestDb + tenant/config-features. Echtes Aggregate im
+// Demo-Tenant via TenantHandlers.addMember. Seed-migration ruft
+// updateMemberRoles auf — MUSS tenantIdOverride nutzen sonst
+// version_conflict.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRegistry, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEsOperationsTable,
+  createSeedMigrationContext,
+  esOperationsTable,
+  runPendingSeedMigrations,
+} from "@cosmicdrift/kumiko-framework/es-ops";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createDispatcher, type Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createConfigFeature } from "../config/feature";
+import { createConfigResolver } from "../config/resolver";
+import { configValuesTable } from "../config/table";
+import { TenantHandlers } from "../tenant/constants";
+import { createTenantFeature } from "../tenant/feature";
+import { tenantMembershipsTable } from "../tenant/membership-table";
+import { tenantEntity } from "../tenant/schema/tenant";
+
+let testDb: TestDb;
+let dispatcher: Dispatcher;
+let registry: ReturnType<typeof createRegistry>;
+
+const systemAdmin = TestUsers.systemAdmin;
+// Demo-Tenant — NICHT SYSTEM_TENANT. Echter App-Realität (publicstatus
+// hat seine Memberships in Demo-Tenants `...0001` / `...0002`).
+const demoTenantId = "00000000-0000-4000-8000-000000000001" as TenantId;
+const adminUserId = "01900000-0000-7000-8000-000000000aaa";
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, tenantEntity);
+  await unsafePushTables(testDb.db, { tenantMembershipsTable, configValuesTable });
+  await createEventsTable(testDb.db);
+  await createEsOperationsTable(testDb.db);
+
+  registry = createRegistry([createConfigFeature(), createTenantFeature()]);
+  const resolver = createConfigResolver();
+  dispatcher = createDispatcher(registry, {
+    db: testDb.db,
+    redis: undefined as never,
+    entityCache: undefined as never,
+    registry,
+    configResolver: resolver,
+  });
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(sql`
+    TRUNCATE kumiko_es_operations, kumiko_events, read_tenants, read_tenant_memberships
+  `);
+});
+
+function makeTempSeedsDir(files: readonly { name: string; content: string }[]): string {
+  const dir = mkdtempSync(join(tmpdir(), "es-ops-e2e-"));
+  for (const f of files) writeFileSync(join(dir, f.name), f.content);
+  return dir;
+}
+
+describe("es-ops Phase 1.5 — E2E gegen real-Stack", () => {
+  test("seed-migration kann updateMemberRoles auf aggregate in Demo-Tenant aufrufen (tenantIdOverride)", async () => {
+    // Setup-Stage: tenant + membership ES-konform via Handler erstellen.
+    // event lebt im demoTenant-stream.
+    const tenantRes = await dispatcher.write(
+      TenantHandlers.create,
+      { id: demoTenantId, key: "demo", name: "Demo Tenant" },
+      { ...systemAdmin, tenantId: demoTenantId },
+    );
+    expect(tenantRes.isSuccess).toBe(true);
+
+    const addRes = await dispatcher.write(
+      TenantHandlers.addMember,
+      { userId: adminUserId, tenantId: demoTenantId, roles: ["Admin"] },
+      { ...systemAdmin, tenantId: demoTenantId },
+    );
+    expect(addRes.isSuccess).toBe(true);
+
+    // Plant: seed migriert die Rolle. KEY: tenantIdOverride = demoTenantId,
+    // sonst greift SYSTEM_TENANT_ID-default und write geht in version_conflict.
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-21-add-tenant-admin.ts",
+        content: `
+          export default {
+            description: "ergänze TenantAdmin auf admin-membership im demo-tenant",
+            run: async (ctx) => {
+              const memberships = await ctx.findMembershipsOfUser("${adminUserId}");
+              for (const m of memberships) {
+                if (m.roles.includes("TenantAdmin")) continue;
+                await ctx.systemWriteAs(
+                  "tenant:write:update-member-roles",
+                  { userId: "${adminUserId}", tenantId: m.tenantId, roles: [...m.roles, "TenantAdmin"] },
+                  m.tenantId,  // ← tenantIdOverride (Phase 1.5 API)
+                );
+              }
+            },
+          };
+        `,
+      },
+    ]);
+
+    try {
+      const result = await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: dir,
+        appliedBy: "boot",
+        registry,
+        createContext: (dbRunner) => createSeedMigrationContext({ dispatcher, dbRunner }),
+        logger: () => {},
+      });
+      expect(result.appliedIds).toEqual(["2026-05-21-add-tenant-admin"]);
+
+      // Verify (a) marker
+      const markers = await testDb.db.select().from(esOperationsTable);
+      expect(markers).toHaveLength(1);
+      expect(markers[0]?.id).toBe("2026-05-21-add-tenant-admin");
+
+      // Verify (b) event in store mit tenant-membership.updated
+      const events = (await testDb.db.execute(
+        sql`SELECT type, tenant_id::text AS tenant_id FROM kumiko_events ORDER BY id`,
+      )) as unknown as readonly { type: string; tenant_id: string }[];
+      const updateEvents = events.filter((e) => e.type === "tenant-membership.updated");
+      expect(updateEvents).toHaveLength(1);
+      expect(updateEvents[0]?.tenant_id).toBe(demoTenantId);
+
+      // Verify (c) read-model aktualisiert
+      const memberships = (await testDb.db.execute(
+        sql`SELECT roles FROM read_tenant_memberships WHERE user_id = ${adminUserId}`,
+      )) as unknown as readonly { roles: string }[];
+      expect(JSON.parse(memberships[0]?.roles ?? "[]")).toEqual(["Admin", "TenantAdmin"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("seed-migration mit handler-QN-typo fail-t dry-run (vor write)", async () => {
+    // Phase 1.5 / A2 — seed-dry-run-validator soll camelCase-typo catchen
+    // BEVOR der dispatcher den write versucht.
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-21-bad-qn.ts",
+        content: `
+          export default {
+            description: "uses camelCase typo for handler-QN",
+            run: async (ctx) => {
+              await ctx.systemWriteAs(
+                "tenant:write:updateMemberRoles", // ← camelCase typo
+                { userId: "x", tenantId: "y", roles: ["z"] },
+                "y",
+              );
+            },
+          };
+        `,
+      },
+    ]);
+    try {
+      await expect(
+        runPendingSeedMigrations({
+          db: testDb.db,
+          seedsDir: dir,
+          appliedBy: "boot",
+          registry, // ← dry-run sieht den typo, wirft mit klarer message
+          createContext: (dbRunner) => createSeedMigrationContext({ dispatcher, dbRunner }),
+          logger: () => {},
+        }),
+      ).rejects.toThrow(
+        // Phase 1.5 / A2 — Dry-Run-validator wirft mit der spezifischen
+        // Phrase "dry-run found ... unknown handler-QN" + dem qn im body.
+        /dry-run found.*unknown handler-QN/,
+      );
+
+      const markers = await testDb.db.select().from(esOperationsTable);
+      expect(markers).toHaveLength(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/tenant/__tests__/tenant.integration.ts

@@ -327,7 +327,9 @@ describe("scenario 6: config integration with tenant", () => {
 
 describe("scenario 7: access rules on handlers", () => {
   test("all handlers have correct access rules", async () => {
+    // "system" für seed-migrations + ops-tooling, "SystemAdmin" für UI-Operator
     expect(rolesOf(stack.registry.getWriteHandler(TenantHandlers.create)?.access)).toEqual([
+      "system",
       "SystemAdmin",
     ]);
     expect(rolesOf(stack.registry.getWriteHandler(TenantHandlers.update)?.access)).toEqual([
@@ -337,6 +339,11 @@ describe("scenario 7: access rules on handlers", () => {
     expect(rolesOf(stack.registry.getWriteHandler(TenantHandlers.disable)?.access)).toEqual([
       "SystemAdmin",
     ]);
+    // updateMemberRoles akzeptiert "system" (für seed-migrations + ops-tooling)
+    // PLUS "SystemAdmin" (echter Operator-Pfad). Symmetrisch zu create.
+    expect(
+      rolesOf(stack.registry.getWriteHandler(TenantHandlers.updateMemberRoles)?.access),
+    ).toEqual(["system", "SystemAdmin"]);
     expect(rolesOf(stack.registry.getQueryHandler(TenantQueries.list)?.access)).toEqual([
       "SystemAdmin",
     ]);

package/src/tenant/handlers/create.write.ts

@@ -16,6 +16,10 @@ export const createWrite = defineWriteHandler({
     key: z.string().min(1).max(50),
     name: z.string().min(1).max(200),
   }),
-  access: { roles: ["SystemAdmin"] },
+  // "system" + "SystemAdmin" — symmetrisch zu update-member-roles.
+  // ops-tooling (seed-migrations + sample-recipes) nutzen System-User
+  // (roles=["system"]) als Executor; "SystemAdmin" bleibt der echte
+  // human-Operator-Pfad über die UI.
+  access: { roles: ["system", "SystemAdmin"] },
   handler: async (event, ctx) => crud.create(event.payload, event.user, ctx.db),
 });

package/src/tenant/handlers/update-member-roles.write.ts

@@ -16,7 +16,11 @@ export const updateMemberRolesWrite = defineWriteHandler({
     tenantId: z.string(),
     roles: z.array(z.string()).min(1),
   }),
-  access: { roles: ["SystemAdmin"] },
+  // "system" + "SystemAdmin" — symmetrisch zu tenant:write:create. System-
+  // User (createSystemUser, roles=["system"]) braucht den Access für seed-
+  // migrations + andere ops-tooling-Pfade. SystemAdmin ist der echte
+  // human-Operator-Pfad über die UI.
+  access: { roles: ["system", "SystemAdmin"] },
   handler: async (event, ctx) => {
     const db = ctx.db;
     const existing = await fetchOne(