@cosmicdrift/kumiko-bundled-features 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.19.0",
+  "version": "0.20.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>",

package/src/__tests__/boot-seed-contract.integration.test.ts

@@ -0,0 +1,119 @@
+// Pins the shared boot-seed contract (DEFAULT_SEED_IF_EXISTS="skip") across
+// event-sourced seed helpers. Feature-specific behaviour stays in each
+// helper's own test file; here we assert cross-cutting invariants only.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createComplianceProfilesFeature } from "../compliance-profiles/feature";
+import {
+  tenantComplianceProfileEntity,
+  tenantComplianceProfileTable,
+} from "../compliance-profiles/schema/profile-selection";
+import { seedComplianceProfile } from "../compliance-profiles/seeding";
+import { createTextContentFeature } from "../text-content/feature";
+import { seedTextBlock } from "../text-content/seeding";
+import { type TextBlockRow, textBlockEntity, textBlocksTable } from "../text-content/table";
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [createTextContentFeature(), createComplianceProfilesFeature()],
+  });
+  await unsafeCreateEntityTable(stack.db, textBlockEntity);
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("boot-seed contract", () => {
+  test("seedTextBlock: re-boot skip preserves user edit + event count", async () => {
+    const tenantId = testTenantId(301);
+
+    await seedTextBlock(stack.db, {
+      tenantId,
+      slug: "imprint",
+      lang: "de",
+      title: "Impressum",
+      body: "seed body",
+    });
+    await seedTextBlock(stack.db, {
+      tenantId,
+      slug: "imprint",
+      lang: "de",
+      title: "Impressum (edited)",
+      body: "admin body",
+      ifExists: "update",
+    });
+    await seedTextBlock(stack.db, {
+      tenantId,
+      slug: "imprint",
+      lang: "de",
+      title: "Impressum",
+      body: "seed body",
+    });
+
+    const row = await fetchOne<TextBlockRow>(stack.db, textBlocksTable, {
+      tenantId,
+      slug: "imprint",
+      lang: "de",
+    });
+    expect(row).toMatchObject({ title: "Impressum (edited)", body: "admin body", version: 2 });
+
+    const events = await selectMany(stack.db, eventsTable, { aggregateId: String(row!.id) });
+    expect(events).toHaveLength(2);
+  });
+
+  test("seedComplianceProfile: re-boot skip preserves profile + event count", async () => {
+    const tenantId = testTenantId(302);
+
+    await seedComplianceProfile(stack.db, { tenantId, profileKey: "eu-dsgvo" });
+    await seedComplianceProfile(stack.db, {
+      tenantId,
+      profileKey: "swiss-dsg",
+      ifExists: "update",
+    });
+    await seedComplianceProfile(stack.db, { tenantId, profileKey: "eu-dsgvo" });
+
+    const profileRow = (await fetchOne(stack.db, tenantComplianceProfileTable, {
+      tenantId,
+    })) as { id: string; profileKey: string; version: number };
+    expect(profileRow.profileKey).toBe("swiss-dsg");
+    expect(profileRow.version).toBe(2);
+
+    const events = await selectMany(stack.db, eventsTable, {
+      aggregateId: profileRow.id,
+    });
+    expect(events).toHaveLength(2);
+    expect(events.map((e) => e.type)).toEqual([
+      "tenant-compliance-profile.created",
+      "tenant-compliance-profile.updated",
+    ]);
+  });
+
+  test('seedComplianceProfile ifExists="update" overwrites existing profile', async () => {
+    const tenantId = testTenantId(303);
+
+    await seedComplianceProfile(stack.db, { tenantId, profileKey: "eu-dsgvo" });
+    await seedComplianceProfile(stack.db, {
+      tenantId,
+      profileKey: "swiss-dsg",
+      ifExists: "update",
+    });
+
+    const row = (await fetchOne(stack.db, tenantComplianceProfileTable, {
+      tenantId,
+    })) as { profileKey: string };
+    expect(row.profileKey).toBe("swiss-dsg");
+  });
+});

package/src/compliance-profiles/__tests__/seeding.integration.test.ts

@@ -3,13 +3,13 @@
 // Beweist:
 //   1. Helper umgeht set-profile-Zod-Engung (kann minimal-no-region
 //      setzen für Migration-Edge-Case-Tests in Sprint 2+)
-//   2. Idempotent: zweiter Call mit gleichem tenantId updated den
-//      bestehenden Eintrag
+//   2. Default skip: zweiter Boot-Call ohne ifExists="update" ändert nichts
 //   3. Override wird als JSON-String persistiert + via for-tenant
 //      korrekt zurueckgelesen
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
   setupTestStack,
@@ -17,7 +17,11 @@ import {
   testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { createComplianceProfilesFeature, tenantComplianceProfileEntity } from "../feature";
+import { createComplianceProfilesFeature } from "../feature";
+import {
+  tenantComplianceProfileEntity,
+  tenantComplianceProfileTable,
+} from "../schema/profile-selection";
 import { seedComplianceProfile } from "../seeding";
 
 const FOR_TENANT = "compliance-profiles:query:for-tenant";
@@ -47,17 +51,42 @@ describe("seedComplianceProfile", () => {
     expect(result.profile.key).toBe("eu-dsgvo");
   });
 
-  test("idempotent: zweiter Call updated den bestehenden Eintrag", async () => {
+  test('ifExists="update" overwrites bestehenden Eintrag', async () => {
     const tenantId = testTenantId(201);
     const user = createTestUser({ id: 201, tenantId, roles: ["TenantAdmin"] });
 
     await seedComplianceProfile(stack.db, { tenantId, profileKey: "eu-dsgvo" });
-    await seedComplianceProfile(stack.db, { tenantId, profileKey: "swiss-dsg" });
+    await seedComplianceProfile(stack.db, {
+      tenantId,
+      profileKey: "swiss-dsg",
+      ifExists: "update",
+    });
 
     const result = await stack.http.queryOk<{ profile: { key: string } }>(FOR_TENANT, {}, user);
     expect(result.profile.key).toBe("swiss-dsg");
   });
 
+  test("default skip: zweiter Boot-Call ohne update überschreibt nicht", async () => {
+    const tenantId = testTenantId(204);
+
+    await seedComplianceProfile(stack.db, { tenantId, profileKey: "eu-dsgvo" });
+    await seedComplianceProfile(stack.db, {
+      tenantId,
+      profileKey: "swiss-dsg",
+      ifExists: "update",
+    });
+    await seedComplianceProfile(stack.db, { tenantId, profileKey: "de-hr-dsgvo-hgb" });
+
+    const row = (await fetchOne(stack.db, tenantComplianceProfileTable, {
+      tenantId,
+    })) as { id: string; profileKey: string; version: number };
+    expect(row.profileKey).toBe("swiss-dsg");
+    expect(row.version).toBe(2);
+
+    const events = await selectMany(stack.db, eventsTable, { aggregateId: row.id });
+    expect(events).toHaveLength(2);
+  });
+
   test("kann minimal-no-region direkt seeden (Migration-Edge-Case, ohne set-profile-Zod-Engung)", async () => {
     const tenantId = testTenantId(202);
     const user = createTestUser({ id: 202, tenantId, roles: ["TenantAdmin"] });

package/src/compliance-profiles/seeding.ts

@@ -2,7 +2,7 @@
 // über den Event-Store-Executor an — gleicher Pfad wie der echte
 // set-profile-Handler, aber ohne Zod-Schema-Engung (akzeptiert
 // minimal-no-region für Migration-Edge-Case-Tests) und ohne Access-
-// Check. Idempotent: zweiter Call mit gleichem tenantId updated.
+// Check. Default ifExists="skip": nur fehlende Profile anlegen.
 //
 // Sprint 2 user-data-rights nutzt das fuer Test-Setup ("user kann
 // Daten exportieren mit profile X" — pro Test ein frischer Tenant +
@@ -21,6 +21,7 @@ import {
   type DbConnection,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
 import {
   tenantComplianceProfileEntity,
@@ -38,6 +39,7 @@ export type SeedComplianceProfileOptions = {
   readonly profileKey: ComplianceProfileKey;
   readonly override?: ComplianceProfileOverride;
   readonly by?: SessionUser;
+  readonly ifExists?: SeedIfExists;
 };
 
 export async function seedComplianceProfile(
@@ -55,39 +57,42 @@ export async function seedComplianceProfile(
     tenantId: opts.tenantId,
   })) as { id: string; version: number } | null; // @cast-boundary db-runner
 
-  if (existing) {
-    const result = await executor.update(
-      {
-        id: existing.id,
-        version: existing.version,
-        changes: { profileKey: opts.profileKey, override: overrideJson },
-      },
-      by,
-      tdb,
-    );
-    if (!result.isSuccess) {
-      throw new Error(`seedComplianceProfile update failed: ${JSON.stringify(result)}`);
-    }
-    return { id: existing.id };
-  }
-
-  const result = await executor.create(
-    {
-      profileKey: opts.profileKey,
-      override: overrideJson,
-      tenantId: opts.tenantId,
+  return runEventStoreSeed({
+    existing,
+    ifExists: opts.ifExists,
+    create: async () => {
+      const result = await executor.create(
+        {
+          profileKey: opts.profileKey,
+          override: overrideJson,
+          tenantId: opts.tenantId,
+        },
+        by,
+        tdb,
+      );
+      if (!result.isSuccess) {
+        throw new Error(`seedComplianceProfile create failed: ${JSON.stringify(result)}`);
+      }
+      const data = result.data as { id?: string };
+      if (data.id === undefined) {
+        throw new Error("seedComplianceProfile: executor.create did not return an id");
+      }
+      return { id: data.id };
+    },
+    update: async (row) => {
+      const result = await executor.update(
+        {
+          id: row.id,
+          version: row.version,
+          changes: { profileKey: opts.profileKey, override: overrideJson },
+        },
+        by,
+        tdb,
+      );
+      if (!result.isSuccess) {
+        throw new Error(`seedComplianceProfile update failed: ${JSON.stringify(result)}`);
+      }
+      return { id: row.id };
     },
-    by,
-    tdb,
-  );
-  if (!result.isSuccess) {
-    throw new Error(`seedComplianceProfile create failed: ${JSON.stringify(result)}`);
-  }
-  // @cast-boundary db-row: executor.create-result enthält die inserted
-  // Row als Record<string, unknown>; id ist nach INSERT garantiert.
-  const data = result.data as { id?: string };
-  if (data.id === undefined) {
-    throw new Error("seedComplianceProfile: executor.create did not return an id");
-  }
-  return { id: data.id };
+  });
 }

package/src/legal-pages/README.md

@@ -48,8 +48,8 @@ legal-pages doesn't have its own table — it uses text-content's
 `read_text_blocks`. Table setup therefore goes through text-content:
 
 ```bash
-yarn kumiko migrate generate    # text-block entity is detected
-yarn kumiko migrate apply
+bun kumiko migrate generate    # text-block entity is detected
+bun kumiko migrate apply
 ```
 
 See [text-content/README.md](../text-content/README.md#production-table-setup).

package/src/legal-pages/__tests__/legal-pages.integration.test.ts

@@ -153,6 +153,7 @@ describe("legal-pages :: edge-cases", () => {
       lang: "de",
       title: "Impressum",
       body: "## XSS-Test\n\n<script>window.x=1</script>\n\nDanach.",
+      ifExists: "update",
     });
     const res = await stack.app.request("/legal/impressum");
     expect(res.status).toBe(200);

package/src/tenant/seeding.ts

@@ -25,11 +25,7 @@
 // correct event + projection.
 //
 // Idempotent: calling twice for the same (userId, tenantId) is a no-op on
-// the second call. Test fixtures that seed the same membership across
-// `beforeEach` runs don't need explicit cleanup. A real `addMember` handler
-// returns ConflictError on duplicates — that's the user-facing contract.
-// Fixture-seeding prioritises "make the state exist" over "detect duplicate
-// seeding", which is usually a test-author bug we don't need to surface.
+// the second call (ifExists="skip", siehe @cosmicdrift/kumiko-framework/seeding).
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
@@ -77,8 +73,8 @@ export type SeedTenantOptions = {
 };
 
 /**
- * Seed a tenant through the event-store executor. Idempotent: a second
- * call for the same `id` is a no-op. Same TX-semantics as the real
+ * Seed a tenant through the event-store executor. Idempotent (ifExists="skip"):
+ * a second call for the same `id` is a no-op. Same TX-semantics as the real
  * `TenantHandlers.create`, minus the SystemAdmin-access-check and minus
  * ConflictError-on-duplicate.
  */

package/src/text-content/README.md

@@ -22,20 +22,23 @@ runProdApp({
 
 ### Production table setup
 
-Each app creates the `read_text_blocks` table via a Drizzle migration:
+Each app creates the `read_text_blocks` table via a schema migration:
 
 ```bash
-# In the app workspace (e.g. samples/showcases/myapp):
-yarn kumiko migrate generate    # detects the new r.entity("text-block")
-                                # → drizzle migration in the drizzle/ folder
-yarn kumiko migrate apply       # apply (pre-deploy step in prod)
+# In the app workspace (legacy drizzle.config.ts apps):
+bun kumiko migrate generate    # detects the new r.entity("text-block")
+bun kumiko migrate apply       # pre-deploy step in prod
+
+# New apps (kumiko/schema.ts):
+bun kumiko schema generate text-content
+bun kumiko schema apply
 ```
 
 The boot gate (`runProdApp`) checks hard: missing table = `SchemaDriftError`,
 container exits. No auto-heal in production. See
 [docs/plans/architecture/migrations.md](../../../../docs/plans/architecture/migrations.md).
 
-In integration tests (vitest) it's enough to do:
+In integration tests (`bun test`) it's enough to do:
 
 ```typescript
 import { unsafeCreateEntityTable } from "@cosmicdrift/kumiko-framework/stack";

package/src/text-content/__tests__/text-content.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { type DbConnection, fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
   setupTestStack,
@@ -12,7 +12,7 @@ import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
 import { TextContentHandlers, TextContentQueries } from "../constants";
 import { createTextContentFeature } from "../feature";
 import { seedTextBlock } from "../seeding";
-import { textBlockEntity } from "../table";
+import { type TextBlockRow, textBlockEntity, textBlocksTable } from "../table";
 
 let stack: TestStack;
 let db: DbConnection;
@@ -395,7 +395,7 @@ describe("text-content :: edge-cases", () => {
 });
 
 describe("text-content :: seedTextBlock", () => {
-  test("seedTextBlock is idempotent", async () => {
+  test('ifExists="update" overwrites existing row (same aggregate id)', async () => {
     const a = await seedTextBlock(db, {
       tenantId: tenantAdmin.tenantId,
       slug: "seed-test",
@@ -409,10 +409,44 @@ describe("text-content :: seedTextBlock", () => {
       lang: "de",
       title: "v2",
       body: "neu",
+      ifExists: "update",
     });
     expect(a.id).toBe(b.id);
   });
 
+  test('default ifExists="skip" does not overwrite on re-boot', async () => {
+    const base = {
+      tenantId: tenantAdmin.tenantId,
+      slug: "seed-skip",
+      lang: "de",
+    };
+    await seedTextBlock(db, {
+      ...base,
+      title: "Initial",
+      body: "from seed",
+    });
+    await seedTextBlock(db, {
+      ...base,
+      title: "User edit",
+      body: "from admin",
+      ifExists: "update",
+    });
+    await seedTextBlock(db, {
+      ...base,
+      title: "Seed again",
+      body: "would overwrite",
+    });
+
+    const row = await fetchOne<TextBlockRow>(db, textBlocksTable, base);
+    expect(row).toMatchObject({ title: "User edit", body: "from admin", version: 2 });
+
+    const events = await selectMany(db, eventsTable, {
+      aggregateId: String(row!.id),
+    });
+    expect(events).toHaveLength(2);
+    expect(events.map((e) => e.type)).toEqual(["text-block.created", "text-block.updated"]);
+  });
+
   // Drift-Documentation: seedTextBlock geht direkt durch den Executor
   // OHNE slugSchema-Validation, set.write läuft DURCH die Validation.
   // Folge: seedTextBlock akzeptiert Slugs mit ":" oder "/" (legal-pages

package/src/text-content/seeding.ts

@@ -1,7 +1,7 @@
 // Test-Helper für text-content. Legt einen TextBlock direkt über den
 // Event-Store-Executor an — gleicher Pfad wie der echte set-Handler,
-// aber ohne Access-Check. Idempotent: zweiter Call mit gleichem
-// (tenantId, slug, lang) updated den existing Block.
+// aber ohne Access-Check. Default ifExists="skip": nur fehlende Blocks
+// anlegen; opt-in update für Demo-Fixtures.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
@@ -10,6 +10,7 @@ import {
   type DbConnection,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
 import { type TextBlockRow, textBlockEntity, textBlocksTable } from "./table";
 
@@ -29,6 +30,7 @@ export type SeedTextBlockOptions = {
    *  set.write die geseedete Row später überschreiben kann. */
   readonly folder?: string | null;
   readonly by?: SessionUser;
+  readonly ifExists?: SeedIfExists;
 };
 
 export async function seedTextBlock(
@@ -54,43 +56,45 @@ export async function seedTextBlock(
 
   const folder = opts.folder ?? null;
 
-  if (existing) {
-    const result = await executor.update(
-      {
-        id: existing.id,
-        version: existing.version,
-        changes: { title: opts.title, body: opts.body ?? null, folder },
-      },
-      by,
-      tdb,
-    );
-    if (!result.isSuccess) {
-      throw new Error(`seedTextBlock update failed: ${JSON.stringify(result)}`);
-    }
-    return { id: existing.id };
-  }
-
-  const result = await executor.create(
-    {
-      slug: opts.slug,
-      lang: opts.lang,
-      title: opts.title,
-      body: opts.body ?? null,
-      folder,
-      tenantId: opts.tenantId,
+  return runEventStoreSeed({
+    existing,
+    ifExists: opts.ifExists,
+    create: async () => {
+      const result = await executor.create(
+        {
+          slug: opts.slug,
+          lang: opts.lang,
+          title: opts.title,
+          body: opts.body ?? null,
+          folder,
+          tenantId: opts.tenantId,
+        },
+        by,
+        tdb,
+      );
+      if (!result.isSuccess) {
+        throw new Error(`seedTextBlock create failed: ${JSON.stringify(result)}`);
+      }
+      const data = result.data as Partial<TextBlockRow>;
+      if (data.id === undefined) {
+        throw new Error("seedTextBlock: executor.create did not return an id");
+      }
+      return { id: data.id };
+    },
+    update: async (row) => {
+      const result = await executor.update(
+        {
+          id: row.id,
+          version: row.version,
+          changes: { title: opts.title, body: opts.body ?? null, folder },
+        },
+        by,
+        tdb,
+      );
+      if (!result.isSuccess) {
+        throw new Error(`seedTextBlock update failed: ${JSON.stringify(result)}`);
+      }
+      return { id: row.id };
     },
-    by,
-    tdb,
-  );
-  if (!result.isSuccess) {
-    throw new Error(`seedTextBlock create failed: ${JSON.stringify(result)}`);
-  }
-  // @cast-boundary db-row executor.create result.data ist Drizzle-row
-  // (Record<string, unknown>), projected nach INSERT/RETURNING auf
-  // TextBlockRow. Runtime-narrowing in der nächsten Zeile.
-  const data = result.data as Partial<TextBlockRow>;
-  if (data.id === undefined) {
-    throw new Error("seedTextBlock: executor.create did not return an id");
-  }
-  return { id: data.id };
+  });
 }

package/src/user/seeding.ts

@@ -1,8 +1,9 @@
 // Testing-Helper fürs user-Feature. `seedUser` legt einen User direkt
 // über den Event-Store-Executor an — gleicher Pfad wie der echte
 // `UserHandlers.create`, aber ohne Access-Check und ohne ConflictError
-// bei Duplikaten (idempotent: zweiter Aufruf für dieselbe Email
-// liefert die existierende userId zurück).
+// bei Duplikaten. Verhält sich wie ifExists="skip" (siehe
+// @cosmicdrift/kumiko-framework/seeding): existierende Email → return
+// ohne Event.
 //
 // Warum nicht direkt `db.insert(userTable)`: das würde den Event-Store
 // umgehen, also kein `user.created`-Event und keine MSP-Konsumenten