@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/agents/examples/seed-migration.md

@@ -97,3 +97,215 @@ Wenn eine kaputte Migration den Boot blockiert: setze `skippable: true` im seed-
 ## See also
 
 - **Driver-Use-Case:** `seeds/2026-02-01-fix-admin-roles.ts` in this recipe
+
+## Source files
+
+### scripts/smoke.ts
+
+```ts
+// biome-ignore-all lint/suspicious/noConsole: CLI tool output
+//
+// Lokaler Smoke-Test für seed-migrations.
+//
+// Was er prüft (offline, ohne Pod-Deploy):
+//   1. Alle seed-files in ./seeds/ können dynamic-import geladen werden
+//      → catched syntax-errors + missing default-exports + falsche paths
+//   2. Jeder handler-QN den die seeds referenzieren ist in der echten
+//      App-Registry registriert → catched camelCase-typos + drift
+//      (Bug-Klasse 3 aus Phase 1 retro)
+//   3. Jeder system-user (mit oder ohne tenantIdOverride) hat Access auf
+//      die referenzierten Handler → catched access-rule-Drift
+//      (Bug-Klasse 4 aus Phase 1 retro)
+//
+// Schreibt NICHTS in die DB. Reine Read-only Validation.
+//
+// Usage:
+//   bun scripts/smoke.ts                  (gegen ./seeds/)
+//   bun scripts/smoke.ts --seeds-dir foo  (custom path)
+//
+// In CI: vor `build`-Step laufen lassen — fängt 80% der Phase-1-Bugs
+// lokal in <5 Sekunden statt nach 8-Minuten-Docker-Build im Pod-Boot.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+// App-spezifisch: nimm die EFFEKTIVEN Features die deine App zur Runtime
+// nutzt. Im typischen Setup mit `runProdApp({ features, auth })`:
+//
+//   import { composeFeatures } from "@cosmicdrift/kumiko-dev-server";
+//   import { APP_FEATURES } from "../src/run-config";
+//   const composed = composeFeatures(APP_FEATURES, { includeBundled: true, ... });
+//   const features = composed.features;
+//
+// Bei reiner App-Feature-Setup (kein auth-mode) reicht ein direkter
+// Import der App-Features. Hier im Recipe der minimale set für die
+// referenzierten Recipe-Seeds (tenant + config) — App-Author tauscht
+// gegen sein eigenes Feature-Set.
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import {
+  createRegistry,
+  createSystemUser,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const features = [createConfigFeature(), createTenantFeature()];
+
+const seedsDir = (() => {
+  const idx = process.argv.indexOf("--seeds-dir");
+  return idx >= 0 ? resolve(process.argv[idx + 1] ?? "./seeds") : resolve("./seeds");
+})();
+
+if (!existsSync(seedsDir)) {
+  console.log(`✓ no seeds-dir at ${seedsDir} — nothing to smoke-test`);
+  process.exit(0);
+}
+
+const seedFiles = readdirSync(seedsDir)
+  .filter((n) => n.endsWith(".ts") && !n.startsWith("_") && !n.startsWith("."))
+  .sort();
+
+if (seedFiles.length === 0) {
+  console.log(`✓ ${seedsDir} is empty — nothing to smoke-test`);
+  process.exit(0);
+}
+
+const registry = createRegistry(features);
+
+let failed = 0;
+
+for (const file of seedFiles) {
+  const filePath = resolve(seedsDir, file);
+  console.log(`\nseed: ${file}`);
+
+  // 1. Module-load
+  try {
+    const mod = await import(filePath);
+    if (!mod.default || typeof mod.default.run !== "function") {
+      console.error("  ✗ missing valid SeedMigration default-export");
+      failed++;
+      continue;
+    }
+    console.log(`  ✓ loads: "${mod.default.description}"`);
+  } catch (err) {
+    console.error(`  ✗ load fail: ${err instanceof Error ? err.message : String(err)}`);
+    failed++;
+    continue;
+  }
+
+  // 2 + 3. QN-Resolution + Access (regex-based, gleiche Logik wie runner's
+  // dry-run-validator). Pattern matched inline-string-QNs:
+  const source = readFileSync(filePath, "utf-8");
+  const qnPattern = /systemWriteAs\s*\(\s*["']([^"']+)["']/g;
+  const qns = new Set<string>();
+  for (const m of source.matchAll(qnPattern)) {
+    const qn = m[1];
+    if (qn) qns.add(qn);
+  }
+
+  for (const qn of qns) {
+    const handler = registry.getWriteHandler(qn);
+    if (!handler) {
+      console.error(`  ✗ handler "${qn}" not registered`);
+      failed++;
+      continue;
+    }
+    const accessRoles = (handler.access as { roles?: readonly string[] }).roles ?? [];
+    const systemUserRoles = createSystemUser(SYSTEM_TENANT_ID).roles;
+    const hasAccess = systemUserRoles.some((r) => accessRoles.includes(r));
+    if (!hasAccess) {
+      console.error(
+        `  ✗ system-user roles=${JSON.stringify([...systemUserRoles])} NOT in access.roles=${JSON.stringify([...accessRoles])} for "${qn}"`,
+      );
+      failed++;
+      continue;
+    }
+    console.log(`  ✓ "${qn}" registered + accessible`);
+  }
+}
+
+if (failed > 0) {
+  console.error(`\n${failed} issue(s) — fix before push.`);
+  process.exit(1);
+}
+console.log(`\n✓ all ${seedFiles.length} seed-file(s) pass smoke.`);
+```
+
+### seeds/2026-01-01-initial-tenants.ts
+
+```ts
+// Initial-Seed: Demo-Tenants anlegen.
+//
+// Note: in real apps wäre "initial tenants" wahrscheinlich nicht als
+// seed-migration sondern als `r.config({seeds})` oder `auth.admin`-
+// Config umgesetzt — die laufen jedes-Boot idempotent. Hier ist es als
+// seed-migration gezeigt um das Pattern zu demonstrieren.
+//
+// Pattern: jede seed-migration arbeitet write-only via `systemWriteAs`
+// damit alles als Event-Stream persistiert wird. Read-only Lookups
+// (find*) am Context oder direkt via ctx.db.
+
+import type { SeedMigration } from "@cosmicdrift/kumiko-framework/es-ops";
+
+export default {
+  description: "initial demo tenants (alice-corp, beta-inc)",
+  run: async (ctx) => {
+    // Idempotent-Check: wenn Tenants schon existieren (z.B. via auth.admin-
+    // seed), skip diese Migration. Verhindert Konflikt beim re-boot wenn
+    // jemand den Marker manuell gelöscht hat.
+    const existing = await ctx.findTenants();
+    if (existing.some((t) => t.tenantKey === "alice-corp")) return;
+
+    await ctx.systemWriteAs("tenant:write:create", {
+      name: "Alice Corp",
+      tenantKey: "alice-corp",
+    });
+    await ctx.systemWriteAs("tenant:write:create", {
+      name: "Beta Inc",
+      tenantKey: "beta-inc",
+    });
+  },
+} satisfies SeedMigration;
+```
+
+### seeds/2026-02-01-fix-admin-roles.ts
+
+```ts
+// Driver-Pattern: ergänze fehlende Rolle auf existierenden Memberships.
+// Spiegelt den realen publicstatus-Bug 2026-05-20 (admin@publicstatus.eu
+// hatte "Admin" aber nicht "TenantAdmin" → text-content + legal-pages
+// access_denied weil bundled-features TenantAdmin erwarten).
+//
+// Funktioniert für jede App mit dem gleichen Pattern: User-Lookup per
+// E-Mail → alle Memberships durchgehen → bei Bedarf via existierendem
+// updateMemberRoles-Handler korrigieren.
+
+import type { SeedMigration } from "@cosmicdrift/kumiko-framework/es-ops";
+
+export default {
+  description: "ergänze TenantAdmin-Rolle für admin@example.com auf allen Memberships",
+  run: async (ctx) => {
+    const admin = await ctx.findUserByEmail("admin@example.com");
+    if (!admin) return; // idempotent: admin nicht (mehr) vorhanden
+
+    for (const m of await ctx.findMembershipsOfUser(admin.id)) {
+      if (m.roles.includes("TenantAdmin")) continue; // bereits korrigiert
+
+      await ctx.systemWriteAs(
+        "tenant:write:update-member-roles", // kebab-case QN — wird vom Dry-Run-Validator gecheckt
+        {
+          userId: admin.id,
+          tenantId: m.tenantId,
+          roles: Array.from(new Set([...m.roles, "TenantAdmin"])),
+        },
+        // tenantIdOverride: stream-tenant aus kumiko_events.v1 — NICHT
+        // m.tenantId (payload-tenant). Beide stimmen oft überein, weichen
+        // aber ab wenn das Aggregate ursprünglich von einem fremden
+        // Executor angelegt wurde (seedTenantMembership by=systemAdmin —
+        // publicstatus-Pattern). findMembershipsOfUser liefert beide,
+        // kein eigener JOIN nötig.
+        m.streamTenantId,
+      );
+    }
+  },
+} satisfies SeedMigration;
+```

package/agents/examples/state-machine.md

@@ -492,6 +492,7 @@ export const invoiceTable = buildEntityTable("invoice", invoiceEntity);
 
 import type { EventDef } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
+import { INVOICE_STATES } from "./entities/invoice.ts";
 
 export const FEATURE_NAME = "billing";
 export const ENTITY_NAME = "invoice";
@@ -523,8 +524,8 @@ export const INVOICE_CREATED_EVENT = `${ENTITY_NAME}.created` as const;
 
 export const emptyEventPayload = z.object({});
 export const statusForcedPayload = z.object({
-  newStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
-  fromStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
+  newStatus: z.enum(INVOICE_STATES),
+  fromStatus: z.enum(INVOICE_STATES),
 });
 
 // The EventDefs r.defineEvent returns inside the feature setup. Handlers receive them so that

package/agents/examples/tenant-isolation.md

@@ -13,6 +13,7 @@ Multi-tenant data isolation by default.
 ## What it shows
 
 - Tenant filter on ordinary handlers
+- `ctx.db.upsert`: insert-or-update on a tenant-scoped, non-event-sourced table. `conflictTarget` must contain `tenantId` and match a declared unique index (here `tenant_id, key`); event-fed tables are rejected
 - What breaks if you forget tenancy (and how the framework prevents it)
 
 ## Source
@@ -37,6 +38,7 @@ bun test
 // Proves: tenant_id scopes all data, cross-tenant access returns nothing
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createTestUser, TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
@@ -45,7 +47,7 @@ import {
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-testing/stack";
-import { noteEntity, noteFeature } from "../feature";
+import { noteEntity, noteFeature, preferenceTable } from "../feature";
 
 let stack: TestStack;
 
@@ -136,12 +138,48 @@ describe("tenant isolation", () => {
     expect(listB.rows.some((r) => r["title"] === "A-Note")).toBe(false);
   });
 });
+
+describe("ctx.db.upsert", () => {
+  const setPreference = (user: typeof tenantBAdmin, key: string, value: string) =>
+    stack.http.writeOk<{ value: string }>("notes:write:preference:set", { key, value }, user);
+
+  test("a second upsert with the same key updates the tenant's row instead of inserting", async () => {
+    await setPreference(tenantAAdmin, "theme", "light");
+    const second = await setPreference(tenantAAdmin, "theme", "dark");
+
+    expect(second.value).toBe("dark");
+    const rows = await selectMany(stack.db, preferenceTable, {
+      tenantId: tenantAAdmin.tenantId,
+      key: "theme",
+    });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["value"]).toBe("dark");
+  });
+
+  test("the same key in another tenant creates a separate row and leaves A's value alone", async () => {
+    await setPreference(tenantAAdmin, "language", "de");
+    await setPreference(tenantBAdmin, "language", "en");
+
+    const rowsA = await selectMany(stack.db, preferenceTable, {
+      tenantId: tenantAAdmin.tenantId,
+      key: "language",
+    });
+    const rowsB = await selectMany(stack.db, preferenceTable, {
+      tenantId: tenantBAdmin.tenantId,
+      key: "language",
+    });
+    expect(rowsA.map((row) => row["value"])).toEqual(["de"]);
+    expect(rowsB.map((row) => row["value"])).toEqual(["en"]);
+  });
+});
 ```
 
 ### src/feature.ts
 
 ```ts
+import { defineUnmanagedTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
 
 export const noteEntity = createEntity({
   table: "read_sample_notes",
@@ -151,6 +189,26 @@ export const noteEntity = createEntity({
   },
 });
 
+// Not event-sourced: ctx.db.upsert rejects executor-managed tables.
+export const preferenceTable = defineUnmanagedTable({
+  tableName: "sample_tenant_preferences",
+  columns: [
+    {
+      name: "id",
+      pgType: "uuid",
+      notNull: true,
+      primaryKey: true,
+      defaultSql: "gen_random_uuid()",
+    },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "key", pgType: "text", notNull: true },
+    { name: "value", pgType: "text", notNull: true },
+  ],
+  indexes: [
+    { name: "sample_tenant_preferences_tenant_key", columns: ["tenant_id", "key"], unique: true },
+  ],
+});
+
 const adminWrite = { access: { roles: ["Admin"] } } as const;
 const openRead = {
   access: {
@@ -168,5 +226,19 @@ export const noteFeature = defineFeature("notes", (r) => {
     read: openRead,
     verbs: { update: false, delete: false, restore: false },
   });
+
+  r.storeTable(preferenceTable, { reason: "settings.tenant_preferences" });
+
+  r.writeHandler({
+    name: "preference:set",
+    schema: z.object({ key: z.string().min(1), value: z.string() }),
+    handler: async (event, ctx) => {
+      const row = await ctx.db.upsert<{ value: string }>(preferenceTable, event.payload, {
+        conflictTarget: ["tenantId", "key"],
+      });
+      return { isSuccess: true, data: { value: row?.value } };
+    },
+    ...adminWrite,
+  });
 });
 ```