@cosmicdrift/kumiko-framework 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @cosmicdrift/kumiko-framework
 
+## 0.5.1
+
+### Patch Changes
+
+- 0e00015: fix(es-ops): path.resolve statt path.join für seedsDir → seed-files
+
+  Bun's `await import()` braucht absolute Pfade. Wenn der App-Author
+  `runProdApp({ seedsDir: "./seeds" })` setzt (relativ), würde
+  `path.join("./seeds", "foo.ts")` einen relativen Pfad liefern → Bun's
+  Import-Resolver such relativ zum `runner.ts`-Modul (nicht zum
+  `process.cwd()`) → `Cannot find module 'seeds/...' from '<runner-path>'`.
+
+  `path.resolve` löst gegen `process.cwd()` auf → absolute Pfade →
+  Import funktioniert. Aufgedeckt beim ersten Live-Boot der publicstatus-
+  Driver-Migration (Pod CrashLoopBackOff).
+
+## 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.
+
 ## 0.4.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -32,6 +32,10 @@
       "types": "./src/compliance/index.ts",
       "default": "./src/compliance/index.ts"
     },
+    "./es-ops": {
+      "types": "./src/es-ops/index.ts",
+      "default": "./src/es-ops/index.ts"
+    },
     "./engine": {
       "types": "./src/engine/index.ts",
       "default": "./src/engine/index.ts"
@@ -159,7 +163,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.4.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.5.1",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "drizzle-kit": "^0.31.10",

package/src/es-ops/README.md

@@ -0,0 +1,119 @@
+# es-ops
+
+ES-Operations für Kumiko-Apps. Phase 1 liefert `seed-migrations` als file-basiertes Diff-and-Apply für Aggregate-State-Updates, die idempotent-Seeder nicht erfassen können.
+
+## Quick API
+
+```ts
+import { runProdApp } from "@cosmicdrift/kumiko-dev-server";
+
+await runProdApp({
+  features: [...],
+  seedsDir: "./seeds",   // ← einzige Setup-Pflicht
+  // ...
+});
+```
+
+> **Phase 1 Scope:** `runProdApp`-only. `runDevApp`-Integration folgt in Phase 1.5 (braucht separaten Dispatcher-Bootstrap, der stack-typed ist). Für lokale Tests: laufe `bunx kumiko ops seed:status` gegen die Dev-DB um pending seeds zu sehen, dann `runProdApp` lokal mit DEV-Connection für Apply.
+
+```ts
+// seeds/2026-05-20-fix-admin-roles.ts
+import type { SeedMigration } from "@cosmicdrift/kumiko-framework/es-ops";
+
+export default {
+  description: "ergänze TenantAdmin-Rolle für admin@example.com",
+  run: async (ctx) => {
+    const admin = await ctx.findUserByEmail("admin@example.com");
+    if (!admin) return;
+    for (const m of await ctx.findMembershipsOfUser(admin.id)) {
+      if (m.roles.includes("TenantAdmin")) continue;
+      await ctx.systemWriteAs("tenant:write:updateMemberRoles", {
+        userId: admin.id,
+        tenantId: m.tenantId,
+        roles: [...m.roles, "TenantAdmin"],
+      });
+    }
+  },
+} satisfies SeedMigration;
+```
+
+## CLI
+
+```bash
+bunx kumiko ops seed:new <slug>    # scaffold seeds/<date>-<slug>.ts
+bunx kumiko ops seed:status        # was applied, was pending
+bunx kumiko ops seed:apply [--dry-run]  # pending applien (CLI-Pfad in Phase 1.5)
+```
+
+## Garantien
+
+| Garantie | Wie |
+|---|---|
+| **Single-Run** | Marker in `kumiko_es_operations` + `pg_advisory_xact_lock` sequentialisiert Multi-Replica-Boots |
+| **Marker-Atomicity** | Runner-Tx + Re-Check inside lock → Marker reflektiert "Run wurde wirklich attempted" |
+| **Order** | File-name = chronologische ID; Failure stoppt alle pending |
+| **ES-konform** | `systemWriteAs` ruft existing Handler → Events landen im Store |
+| **Recovery** | `skippable: true` + `KUMIKO_SKIP_ES_OPS_<ID>=1` env-flag für Notfall-Skip |
+| **Boot-skip** | `KUMIKO_SKIP_ES_OPS=1` env-var skipped alle pending (Debug-Boots) |
+
+### Was NICHT garantiert ist
+
+**Seed-Body ist NICHT atomic vs. den Marker.** `systemWriteAs` läuft durch den App-Dispatcher mit dessen eigener Tx-Verwaltung (separat von der Runner-Tx). Wenn ein Seed `systemWriteAs` 5× erfolgreich aufruft und dann throws, sind die 5 Events **committed**, der Marker aber **nicht** geschrieben. Beim nächsten Boot retried der Runner — Seeds müssen daher **idempotent** sein:
+
+```ts
+// Gut: skip wenn schon korrigiert
+for (const m of memberships) {
+  if (m.roles.includes("TenantAdmin")) continue;
+  await ctx.systemWriteAs(...);
+}
+
+// Schlecht: jeder Re-Run dupliziert
+for (const m of memberships) {
+  await ctx.systemWriteAs("create-something-new", ...); // double on retry!
+}
+```
+
+Die meisten realen Seeds sind natürlich idempotent (existing-Lookup → conditional-write). Volle End-to-End-Atomicity (write + marker im gleichen Tx) ist als Phase 1.5 vorgesehen — braucht Refactor wie der Dispatcher die outer-Tx übernimmt.
+
+## Architektur
+
+`packages/framework/src/es-ops/` enthält:
+
+| File | Zweck |
+|---|---|
+| `operations-schema.ts` | `kumiko_es_operations` table-definition + `createEsOperationsTable` helper |
+| `types.ts` | `SeedMigration` + `SeedMigrationContext` Public-API |
+| `runner.ts` | `runPendingSeedMigrations` — Diff + Tx + Marker |
+| `context.ts` | `createSeedMigrationContext` — Read-Helpers + `systemWriteAs` |
+| `index.ts` | barrel-export |
+
+Tabellen-Schema:
+
+```sql
+CREATE TABLE kumiko_es_operations (
+  id              TEXT PRIMARY KEY,
+  operation_type  TEXT NOT NULL,                -- "seed-migration" | (Phase 2+)
+  applied_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  duration_ms     INTEGER NOT NULL,
+  applied_by      TEXT NOT NULL,                -- "boot" | "cli" | "ci-pipeline"
+  notes           TEXT
+);
+```
+
+## Phase 2+
+
+`operation_type`-Discriminator lässt zukünftige Operations dieselbe Tabelle + dasselbe CLI-Pattern nutzen:
+
+- `projection-rebuild` — TRUNCATE read_* + Replay aus Events
+- `event-replay` — Notification re-send ohne DB-Write
+- `event-backfill` — Missing-Events für Pre-ES-Daten
+- `stream-migration` — Aggregate-Stream-Tenant-Move (Sysadmin-Bug)
+- `aggregate-rebuild` — Snapshot-Refresh
+
+Implementation: **on demand** (siehe `kumiko-platform/docs/plans/features/es-ops.md`).
+
+## Driver-Use-Case
+
+publicstatus' admin-Member hatte initial `roles: ["Admin"]`. Sprint Role-Naming-Drift ergänzte „TenantAdmin", aber der idempotent-Seeder skipped existing Memberships → DB-Drift. Phase 1 löst genau diese Klasse von Bugs.
+
+Siehe Sample: `samples/recipes/seed-migration/`.

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

@@ -0,0 +1,267 @@
+// Integration-Tests für SeedMigrationContext-Read-Helpers + skippable-
+// integration. Verifizieren dass:
+// - findUserByEmail liest read_users korrekt (typed result-cast)
+// - findMembershipsOfUser parst JSON-encoded roles korrekt
+// - findTenants returnt sorted-by-inserted_at
+// - skippable + env-flag: kein marker geschrieben (gegen real-DB)
+// - ctx.db ist DbRunner (Escape-Hatch für direct-reads)
+//
+// Schema-stubs sind raw CREATE TABLE, weil das vollständige user/tenant-
+// Feature in den Tests zu schwer wäre — wir testen nur den Read-Helper-
+// Layer, nicht die volle Event-Store-Pipeline.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+import { createTestDb, type TestDb } from "../../stack";
+import { createSeedMigrationContext } from "../context";
+import { createEsOperationsTable, esOperationsTable } from "../operations-schema";
+import { runPendingSeedMigrations } from "../runner";
+
+let testDb: TestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEsOperationsTable(testDb.db);
+
+  // Minimal-Schema-Stubs für die 3 Read-Tabellen die context.ts liest.
+  // Spalten matchen production (siehe Sysadmin-Stream-Tenant-Bug Memory).
+  await testDb.db.execute(sql`
+    CREATE TABLE IF NOT EXISTS read_users (
+      id          uuid PRIMARY KEY,
+      email       text NOT NULL,
+      tenant_id   uuid NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
+      id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+      user_id     text NOT NULL,
+      tenant_id   uuid NOT NULL,
+      roles       text NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS read_tenants (
+      id            uuid PRIMARY KEY,
+      name          text NOT NULL,
+      tenant_key    text NOT NULL,
+      inserted_at   timestamptz NOT NULL DEFAULT now()
+    );
+  `);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(sql`
+    TRUNCATE kumiko_es_operations, read_users, read_tenant_memberships, read_tenants
+  `);
+});
+
+function makeMockDispatcher() {
+  return {
+    write: vi.fn(async () => ({ isSuccess: true as const, data: {} })),
+    query: vi.fn(),
+    command: vi.fn(),
+    batch: vi.fn(),
+    resolveAuthClaims: vi.fn(),
+  };
+}
+
+function makeTempSeedsDir(files: readonly { name: string; content: string }[]): string {
+  const dir = mkdtempSync(join(tmpdir(), "es-ops-ctx-integ-"));
+  for (const f of files) writeFileSync(join(dir, f.name), f.content);
+  return dir;
+}
+
+// --- Read-Helpers --------------------------------------------------------
+
+describe("SeedMigrationContext.findUserByEmail (integration)", () => {
+  test("liest existing user-row korrekt + maps tenant_id → tenantId", async () => {
+    const userId = "01900000-0000-7000-8000-000000000001";
+    const tenantId = "00000000-0000-4000-8000-000000000099";
+    await testDb.db.execute(sql`
+      INSERT INTO read_users (id, email, tenant_id)
+      VALUES (${userId}::uuid, 'admin@example.com', ${tenantId}::uuid)
+    `);
+
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const found = await ctx.findUserByEmail("admin@example.com");
+    expect(found).toEqual({ id: userId, email: "admin@example.com", tenantId });
+  });
+
+  test("liefert null bei unknown email (kein throw)", async () => {
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const found = await ctx.findUserByEmail("does-not-exist@example.com");
+    expect(found).toBeNull();
+  });
+});
+
+describe("SeedMigrationContext.findMembershipsOfUser (integration)", () => {
+  test("parst JSON-encoded roles-Spalte zu string[]", async () => {
+    const userId = "01900000-0000-7000-8000-000000000001";
+    const tenantId1 = "00000000-0000-4000-8000-000000000001";
+    const tenantId2 = "00000000-0000-4000-8000-000000000002";
+    await testDb.db.execute(sql`
+      INSERT INTO read_tenant_memberships (user_id, tenant_id, roles) VALUES
+        (${userId}, ${tenantId1}::uuid, '["Admin", "TenantAdmin"]'),
+        (${userId}, ${tenantId2}::uuid, '["User"]')
+    `);
+
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const memberships = await ctx.findMembershipsOfUser(userId);
+    expect(memberships).toHaveLength(2);
+
+    const m1 = memberships.find((m) => m.tenantId === tenantId1);
+    expect(m1?.roles).toEqual(["Admin", "TenantAdmin"]);
+
+    const m2 = memberships.find((m) => m.tenantId === tenantId2);
+    expect(m2?.roles).toEqual(["User"]);
+  });
+
+  test("malformed roles-JSON → leeres Array (defensive, no throw)", async () => {
+    // Defensive: wenn ein corrupted row kommt, soll der Seed nicht
+    // explodieren — kann selbst entscheiden was zu tun ist.
+    const userId = "01900000-0000-7000-8000-000000000002";
+    await testDb.db.execute(sql`
+      INSERT INTO read_tenant_memberships (user_id, tenant_id, roles) VALUES
+        (${userId}, '00000000-0000-4000-8000-000000000003'::uuid, 'not-json')
+    `);
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const memberships = await ctx.findMembershipsOfUser(userId);
+    expect(memberships[0]?.roles).toEqual([]);
+  });
+
+  test("liefert leere Liste bei userId ohne memberships", async () => {
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const memberships = await ctx.findMembershipsOfUser("01900000-0000-7000-8000-000000000099");
+    expect(memberships).toEqual([]);
+  });
+});
+
+describe("SeedMigrationContext.findTenants (integration)", () => {
+  test("returnt alle Tenants sortiert nach inserted_at", async () => {
+    await testDb.db.execute(sql`
+      INSERT INTO read_tenants (id, name, tenant_key, inserted_at) VALUES
+        ('00000000-0000-4000-8000-000000000002'::uuid, 'Beta',  'beta',  '2026-01-02'),
+        ('00000000-0000-4000-8000-000000000001'::uuid, 'Alpha', 'alpha', '2026-01-01')
+    `);
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const tenants = await ctx.findTenants();
+    expect(tenants.map((t) => t.tenantKey)).toEqual(["alpha", "beta"]); // ORDER BY inserted_at ASC
+    expect(tenants[0]).toMatchObject({ name: "Alpha", tenantKey: "alpha" });
+  });
+});
+
+// --- skippable + env-flag (Integration) ---------------------------------
+
+describe("runPendingSeedMigrations: skippable + env-flag (integration)", () => {
+  test("skippable=true + env-flag='1' → kein Marker in DB", async () => {
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-skip-via-env.ts",
+        content: `
+          export default {
+            description: "skippable seed",
+            skippable: true,
+            run: async () => {
+              throw new Error("MUST NOT BE CALLED — env-flag should skip me");
+            },
+          };
+        `,
+      },
+    ]);
+    const envKey = "KUMIKO_SKIP_ES_OPS_2026_05_20_SKIP_VIA_ENV";
+    process.env[envKey] = "1";
+    try {
+      const r = await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: (dbRunner) =>
+          createSeedMigrationContext({ dispatcher: makeMockDispatcher() as never, dbRunner }),
+        logger: () => {},
+      });
+      expect(r.appliedIds).toEqual([]);
+      expect(r.skippedIds).toEqual(["2026-05-20-skip-via-env"]);
+
+      // Kritisch: KEIN Marker — beim nächsten Boot ohne env-flag würde
+      // der Seed dann tatsächlich laufen.
+      const markers = await testDb.db.select().from(esOperationsTable);
+      expect(markers).toHaveLength(0);
+    } finally {
+      delete process.env[envKey];
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("skippable=true OHNE env-flag → läuft normal", async () => {
+    const dir = makeTempSeedsDir([
+      {
+        name: "2026-05-20-skippable-but-no-flag.ts",
+        content: `
+          export default {
+            description: "skippable seed, kein env-flag gesetzt",
+            skippable: true,
+            run: async () => {},
+          };
+        `,
+      },
+    ]);
+    try {
+      const r = await runPendingSeedMigrations({
+        db: testDb.db,
+        seedsDir: dir,
+        appliedBy: "boot",
+        createContext: (dbRunner) =>
+          createSeedMigrationContext({ dispatcher: makeMockDispatcher() as never, dbRunner }),
+        logger: () => {},
+      });
+      expect(r.appliedIds).toEqual(["2026-05-20-skippable-but-no-flag"]);
+      expect(r.skippedIds).toEqual([]);
+
+      const markers = await testDb.db.select().from(esOperationsTable);
+      expect(markers).toHaveLength(1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// --- ctx.db Escape-Hatch (Integration) -----------------------------------
+
+describe("SeedMigrationContext.db (escape-hatch, integration)", () => {
+  test("ctx.db kann für eigene Lookups genutzt werden (read-only)", async () => {
+    await testDb.db.execute(sql`
+      INSERT INTO read_tenants (id, name, tenant_key) VALUES
+        ('00000000-0000-4000-8000-000000000007'::uuid, 'Lucky', 'lucky')
+    `);
+    const ctx = createSeedMigrationContext({
+      dispatcher: makeMockDispatcher() as never,
+      dbRunner: testDb.db,
+    });
+    const rows = (await ctx.db.execute(
+      sql`SELECT name FROM read_tenants WHERE tenant_key = 'lucky'`,
+    )) as unknown as readonly { name: string }[];
+    expect(rows[0]?.name).toBe("Lucky");
+  });
+});