@cosmicdrift/kumiko-framework 0.4.1 → 0.5.0

package/src/es-ops/index.ts

@@ -0,0 +1,34 @@
+// es-ops — ES-Operations-Pattern für Kumiko-Apps.
+//
+// Phase 1: seed-migrations. Phase 2+ docken an dieselbe Infra an
+// (kumiko_es_operations-Table mit operation_type-Discriminator).
+//
+// App-Author-API:
+//   - SeedMigration: default-export-Typ einer seed-file
+//   - runProdApp({ seedsDir }): Framework runs pending bei Boot
+//   - bunx kumiko ops seed:new|status|apply (CLI)
+//
+// Plan-Doc: kumiko-platform/docs/plans/features/es-ops.md
+
+export {
+  type CreateSeedMigrationContextArgs,
+  createSeedMigrationContext,
+} from "./context";
+export {
+  createEsOperationsTable,
+  type EsOperationAppliedBy,
+  type EsOperationType,
+  esOperationsTable,
+} from "./operations-schema";
+export {
+  type RunPendingSeedMigrationsArgs,
+  type RunPendingSeedMigrationsResult,
+  runPendingSeedMigrations,
+} from "./runner";
+export type {
+  SeedMembershipRow,
+  SeedMigration,
+  SeedMigrationContext,
+  SeedTenantRow,
+  SeedUserRow,
+} from "./types";

package/src/es-ops/operations-schema.ts

@@ -0,0 +1,57 @@
+// Tracking-Table für ES-Operations (Phase 1: seed-migrations; Phase 2+:
+// projection-rebuild, event-replay, stream-migration, ... — siehe
+// kumiko-platform/docs/plans/features/es-ops.md).
+//
+// File-ID-Tracking analog drizzle-kit: filename ist die ID, applied-set
+// liegt in dieser Tabelle. Pending = files-on-disk MINUS applied-set.
+//
+// operation_type-Discriminator lässt Phase 2+ dieselbe Tabelle nutzen,
+// kein Schema-Sprawl. CLI-Status filtert per type:
+//   bunx kumiko ops seed:status      → operation_type = "seed-migration"
+//   bunx kumiko ops projection:status → operation_type = "projection-rebuild"
+
+import { sql } from "drizzle-orm";
+import { type DbConnection, tableExists } from "../db";
+import { index, integer, table as pgTable, text, timestamp } from "../db/dialect";
+import { unsafePushTables } from "../stack";
+
+export type EsOperationType = "seed-migration";
+// Phase 2+ extensions — append here when implemented:
+// | "projection-rebuild"
+// | "event-replay"
+// | "stream-migration"
+// | "aggregate-rebuild"
+// | "archived-stream-purge"
+
+export type EsOperationAppliedBy = "boot" | "cli" | "ci-pipeline";
+
+export const esOperationsTable = pgTable(
+  "kumiko_es_operations",
+  {
+    // Filename without extension serves as ID. Chronologically sortable
+    // (date-prefix convention), human-meaningful, no separate hash needed.
+    // Renaming a file = different ID = re-run; intentional (drizzle parity).
+    id: text("id").primaryKey(),
+    operationType: text("operation_type").notNull().$type<EsOperationType>(),
+    appliedAt: timestamp("applied_at", { withTimezone: true, mode: "string" })
+      .notNull()
+      .default(sql`now()`),
+    durationMs: integer("duration_ms").notNull(),
+    // Trace: came from boot-time auto-apply, explicit CLI, or CI step.
+    // Helps when forensics ask "wer hat das wann angestoßen".
+    appliedBy: text("applied_by").notNull().$type<EsOperationAppliedBy>(),
+    // Optional human-readable annotation — surfaced in `ops <op>:status`.
+    notes: text("notes"),
+  },
+  (t) => ({
+    typeIdx: index("kumiko_es_operations_type_idx").on(t.operationType),
+  }),
+);
+
+// Convenience for tests + boot-time setup (idempotent). Mirrors the
+// createEventsTable pattern in event-store/events-schema.ts.
+export async function createEsOperationsTable(db: DbConnection): Promise<void> {
+  if (!(await tableExists(db, "public.kumiko_es_operations"))) {
+    await unsafePushTables(db, { kumikoEsOperations: esOperationsTable });
+  }
+}

package/src/es-ops/runner.ts

@@ -0,0 +1,208 @@
+// Runner für pending seed-migrations beim Boot.
+//
+// Flow:
+//   1. List seeds/<*.ts> sorted ascending (filename = chronologische ID)
+//   2. SELECT id FROM kumiko_es_operations WHERE operation_type='seed-migration'
+//   3. pending = files \ applied
+//   4. Für jeden pending in Order:
+//      a. dynamic import → default-export (SeedMigration)
+//      b. wenn migration.skippable && env[KUMIKO_SKIP_ES_OPS_<sanitized>]='1':
+//         → console.log + continue (kein Marker geschrieben)
+//      c. Tx start
+//      d. await migration.run(ctx)
+//      e. INSERT marker mit duration_ms + appliedBy
+//      f. Tx commit
+//   5. On any failure: Tx rollback + console.error + throw
+//      → App-Boot bricht ab. Operator muss Failure fixen + retry.
+//
+// Skippable-Pattern: seed.skippable=true erlaubt im Notfall ein
+// `KUMIKO_SKIP_ES_OPS_<id>=1` env-flag um eine kaputte Migration zu
+// überspringen ohne ihr Code touchen zu müssen. NICHT als
+// Standard-Workflow — wirklich Notfall.
+
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { eq, sql } from "drizzle-orm";
+import type { DbConnection, DbRunner } from "../db";
+import { esOperationsTable } from "./operations-schema";
+import type { EsOperationAppliedBy, SeedMigration, SeedMigrationContext } from "./types";
+
+// Stabiler 32-bit-Integer-Lock-Key für pg_advisory_xact_lock. Multi-Replica-
+// Boots gegen den selben Stack greifen denselben Lock — sequentialisiert
+// die Migration ohne dass jedes Pod alle pending Files parallel anwendet.
+// Ohne Lock: Pod A + Pod B sehen beide dieselbe pending-Liste → beide
+// laufen migration.run() → events DOUBLED, marker-unique-constraint
+// catched zu spät (nur den Marker, nicht die schon-committed Events).
+const ES_OPS_LOCK_KEY = 0x65_73_6f_70; // 'esop' als hex
+
+export type RunPendingSeedMigrationsArgs = {
+  readonly db: DbConnection;
+  /** Absoluter Pfad zum seeds-Directory (typically <appRoot>/seeds). */
+  readonly seedsDir: string;
+  /** Factory die den Context für jede einzelne seed-Migration erzeugt.
+   *  Caller bekommt einen DbRunner (Connection ODER aktive Tx) — Runner
+   *  ruft das pro-migration im tx-Scope auf. */
+  readonly createContext: (dbRunner: DbRunner) => SeedMigrationContext;
+  /** Trace-marker: boot | cli | ci-pipeline. Landet in applied_by. */
+  readonly appliedBy: EsOperationAppliedBy;
+  /** Optional log-prefix override, default "[es-ops/seed-migration]". */
+  readonly logger?: (line: string) => void;
+};
+
+export type RunPendingSeedMigrationsResult = {
+  readonly appliedIds: readonly string[];
+  readonly skippedIds: readonly string[];
+};
+
+const DEFAULT_LOGGER = (line: string): void => {
+  // biome-ignore lint/suspicious/noConsole: boot-time-output, kein Logger-Inject hier
+  console.log(line);
+};
+
+const LOG_PREFIX = "[es-ops/seed-migration]";
+
+export async function runPendingSeedMigrations(
+  args: RunPendingSeedMigrationsArgs,
+): Promise<RunPendingSeedMigrationsResult> {
+  const log = args.logger ?? DEFAULT_LOGGER;
+
+  const onDisk = await listSeedFiles(args.seedsDir);
+  if (onDisk.length === 0) {
+    log(`${LOG_PREFIX} no seed files in ${args.seedsDir} — skipping`);
+    return { appliedIds: [], skippedIds: [] };
+  }
+
+  const applied = await loadAppliedIds(args.db);
+  const pending = onDisk.filter((entry) => !applied.has(entry.id));
+  if (pending.length === 0) {
+    log(`${LOG_PREFIX} ${onDisk.length} on disk, all applied — nothing to do`);
+    return { appliedIds: [], skippedIds: [] };
+  }
+
+  log(`${LOG_PREFIX} ${pending.length}/${onDisk.length} pending`);
+
+  const appliedIds: string[] = [];
+  const skippedIds: string[] = [];
+
+  for (const entry of pending) {
+    const migration = await loadSeedModule(entry.filePath);
+
+    const envFlag = `KUMIKO_SKIP_ES_OPS_${sanitizeForEnv(entry.id)}`;
+    if (migration.skippable === true && process.env[envFlag] === "1") {
+      log(`${LOG_PREFIX} skip "${entry.id}" — ${envFlag}=1`);
+      skippedIds.push(entry.id);
+      continue;
+    }
+
+    const start = Date.now();
+    try {
+      await args.db.transaction(async (tx) => {
+        // Advisory-Lock: sequentialisiert Multi-Replica-Boots. Zweiter
+        // Pod blockt bis erster fertig ist, dann re-checked sein
+        // applied-set (außerhalb dieser Funktion in nächster Iteration)
+        // und findet den Marker → skip. Lock wird beim Tx-Commit
+        // automatisch released (xact-scope).
+        await tx.execute(sql`SELECT pg_advisory_xact_lock(${ES_OPS_LOCK_KEY})`);
+
+        // Re-check applied-set INSIDE Tx + Lock — verhindert Race
+        // wo Pod-A schon committed hat während Pod-B vor dem Lock
+        // war. Sonst würde Pod-B die Migration nochmal ausführen.
+        const reCheck = (await tx.execute(
+          sql`SELECT 1 FROM kumiko_es_operations WHERE id = ${entry.id} LIMIT 1`,
+        )) as unknown as readonly unknown[];
+        if (reCheck.length > 0) {
+          log(`${LOG_PREFIX} race-skip "${entry.id}" — applied by parallel boot`);
+          // skip: race-detected — other replica committed marker between
+          // loadAppliedIds() and this tx; their run already covered the work.
+          return;
+        }
+
+        const ctx = args.createContext(tx);
+        await migration.run(ctx);
+        await tx.insert(esOperationsTable).values({
+          id: entry.id,
+          operationType: "seed-migration",
+          durationMs: Date.now() - start,
+          appliedBy: args.appliedBy,
+          notes: migration.description,
+        });
+      });
+      const elapsed = Date.now() - start;
+      log(`${LOG_PREFIX} ✓ ${entry.id} (${elapsed}ms) — ${migration.description}`);
+      appliedIds.push(entry.id);
+    } catch (err) {
+      const elapsed = Date.now() - start;
+      log(`${LOG_PREFIX} ✗ ${entry.id} (${elapsed}ms) — ${stringifyError(err)}`);
+      log(
+        `${LOG_PREFIX} ABORT — ${pending.length - appliedIds.length - skippedIds.length - 1} pending migrations were NOT attempted`,
+      );
+      throw err;
+    }
+  }
+
+  return { appliedIds, skippedIds };
+}
+
+type SeedFileEntry = { readonly id: string; readonly filePath: string };
+
+async function listSeedFiles(seedsDir: string): Promise<readonly SeedFileEntry[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(seedsDir);
+  } catch {
+    // Directory doesn't exist → treat as empty. App ohne seeds-Dir ist
+    // ein valider Zustand (no-op).
+    return [];
+  }
+  return entries
+    .filter((name) => name.endsWith(".ts") || name.endsWith(".mts") || name.endsWith(".js"))
+    .filter((name) => !name.startsWith("_") && !name.startsWith("."))
+    .sort() // filename = chronologische ID (date-prefix-convention)
+    .map((name) => ({
+      id: name.replace(/\.(ts|mts|js)$/, ""),
+      filePath: path.join(seedsDir, name),
+    }));
+}
+
+async function loadAppliedIds(db: DbConnection): Promise<Set<string>> {
+  const rows = await db
+    .select({ id: esOperationsTable.id })
+    .from(esOperationsTable)
+    .where(eq(esOperationsTable.operationType, "seed-migration"));
+  return new Set(rows.map((r: { id: string }) => r.id));
+}
+
+async function loadSeedModule(filePath: string): Promise<SeedMigration> {
+  // Bun + Node both honor dynamic import on absolute paths. The seed-files
+  // must export their SeedMigration as default.
+  const mod = await import(filePath);
+  const migration: unknown = mod.default;
+  if (!isSeedMigration(migration)) {
+    throw new Error(
+      `[es-ops] seed file ${filePath} must export a SeedMigration as default ` +
+        `(object with { description: string, run: (ctx) => Promise<void> })`,
+    );
+  }
+  return migration;
+}
+
+function isSeedMigration(value: unknown): value is SeedMigration {
+  if (typeof value !== "object" || value === null) return false;
+  // @cast-boundary generic-record — narrowing unknown to property-bag for shape-check
+  const v = value as Partial<SeedMigration>;
+  return typeof v.description === "string" && typeof v.run === "function";
+}
+
+// "2026-05-20-fix-admin-roles" → "2026_05_20_FIX_ADMIN_ROLES"
+function sanitizeForEnv(id: string): string {
+  return id.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+}
+
+function stringifyError(err: unknown): string {
+  if (err instanceof Error) return `${err.name}: ${err.message}`;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}

package/src/es-ops/types.ts

@@ -0,0 +1,85 @@
+// Public API für seed-migrations. Files in /seeds/<date>-<slug>.ts
+// exportieren ein default-Object dieses Typs. Runner ruft `run(ctx)` in
+// chronologischer Reihenfolge auf, einmal pro App-Boot (track in
+// kumiko_es_operations).
+//
+// API-Stabilität: Phase 1 ist "minimal-viable". Helper am Context
+// (findUserByEmail, etc.) wachsen on-demand — wenn eine real-Migration
+// einen Lookup braucht den der Context nicht anbietet, fügen wir ihn
+// dort hinzu. Das vermeidet "wir-bauen-alle-möglichen-Helper-spekulativ".
+//
+// ctx.db als Escape-Hatch ist erlaubt für READ-only lookups. WRITES
+// IMMER via ctx.systemWriteAs damit Event-Store-Invariants bleiben
+// (Source-of-Truth + Projection läuft automatisch).
+
+import type { DbRunner } from "../db";
+import type { WriteResult } from "../engine";
+
+export type EsOperationAppliedBy = "boot" | "cli" | "ci-pipeline";
+
+/** Default-Export einer seed-Migration-File. */
+export type SeedMigration = {
+  /** Kurze Beschreibung was die Migration tut. Wird in kumiko_es_operations.notes
+   *  und im `ops seed:status`-Output gezeigt. */
+  readonly description: string;
+
+  /** Optional: skippe diesen Seed wenn die env-var
+   *  `KUMIKO_SKIP_ES_OPS_<sanitized-filename>=1` gesetzt ist (für Recovery /
+   *  Debug-Boots). Default false = always-run-pending. */
+  readonly skippable?: boolean;
+
+  /** Hauptarbeit. ctx liefert systemWriteAs (Event-Store-konformer Pfad,
+   *  bypassed Access-Checks via system-user) plus Read-Helpers.
+   *
+   *  Throws → Marker NICHT geschrieben, App-Boot bricht ab, Retry bei
+   *  nächstem Boot. Pro-Migration eigene Transaction; ein Failure stoppt
+   *  alle nachfolgenden pending-Migrations (Order-Erhalt). */
+  readonly run: (ctx: SeedMigrationContext) => Promise<void>;
+};
+
+/** Read-shape eines User-Eintrags wie an Seed-Helpers exposed.
+ *  Schmaler Subset von AuthUserRow — Seeds brauchen typischerweise nur
+ *  diese Felder zur Identifikation. */
+export type SeedUserRow = {
+  readonly id: string;
+  readonly email: string;
+  readonly tenantId: string;
+};
+
+/** Read-shape eines Membership-Eintrags wie an Seed-Helpers exposed. */
+export type SeedMembershipRow = {
+  readonly userId: string;
+  readonly tenantId: string;
+  readonly roles: readonly string[];
+};
+
+/** Read-shape eines Tenant-Eintrags wie an Seed-Helpers exposed. */
+export type SeedTenantRow = {
+  readonly id: string;
+  readonly name: string;
+  readonly tenantKey: string;
+};
+
+export type SeedMigrationContext = {
+  /** Event-Store-konformer Write via existing write-handler. System-User
+   *  als Executor bypassed Access-Check (Standard-Seed-Pattern). Events
+   *  haben inserted_by_id = SYSTEM_TENANT_ID-User → audit-fähig.
+   *
+   *  Typ-Signatur folgt existing ctx.writeAs (payload als unknown) — Type-
+   *  Safety kommt über handler-spezifische Wrapper im Aufrufer ("ich weiß
+   *  was updateMemberRoles braucht"). Versucht NICHT Generic-Magic. */
+  readonly systemWriteAs: (handlerQualifiedName: string, payload: unknown) => Promise<WriteResult>;
+
+  // Read-helpers für die häufigsten Lookups. Wachsen on-demand —
+  // Phase 1 deckt den admin-roles-Driver-Use-Case ab; weitere Lookups
+  // kommen mit weiteren Seeds.
+  readonly findUserByEmail: (email: string) => Promise<SeedUserRow | null>;
+  readonly findMembershipsOfUser: (userId: string) => Promise<readonly SeedMembershipRow[]>;
+  readonly findTenants: () => Promise<readonly SeedTenantRow[]>;
+
+  /** Escape-Hatch — direkter DB-Zugang. Nur für READ-only Lookups die der
+   *  Context nicht standard-mäßig anbietet. WRITES via systemWriteAs!
+   *  Type ist DbRunner (Connection oder aktive Tx) weil der Runner den
+   *  Context pro-Migration im Tx-Scope erzeugt. */
+  readonly db: DbRunner;
+};