@cosmicdrift/kumiko-framework 0.19.0 → 0.20.0

package/README.md

@@ -7,7 +7,7 @@ Framework core for Kumiko — engine, pipeline, API, DB, event-store, and
 every other bit that makes Kumiko go.
 
 > Multi-tenant, command-based, event-sourced app framework for Bun + Hono +
-> Drizzle. Define features, register entities, write commands — the framework
+> Postgres. Define features, register entities, write commands — the framework
 > wires dispatch, persistence, projections, async subscribers, and realtime
 > delivery.
 
@@ -18,12 +18,12 @@ for runnable examples of every feature.
 ## Install
 
 ```bash
-yarn add @cosmicdrift/kumiko-framework
+bun add @cosmicdrift/kumiko-framework
 # peers you probably already have:
-yarn add drizzle-orm hono ioredis zod
+bun add hono ioredis zod
 ```
 
-Bun is the intended runtime. Node 20+ works for the CLI and tests.
+Bun is the intended runtime and test runner.
 
 ## At-a-glance
 
@@ -108,7 +108,7 @@ export const taskFeature = defineFeature("tasks", (r) => {
 | Entry | What's in it |
 |---|---|
 | `@cosmicdrift/kumiko-framework/engine` | `defineFeature`, `createEntity`, field helpers, access rules, registry |
-| `@cosmicdrift/kumiko-framework/db` | Drizzle re-exports, `createEventStoreExecutor`, table builders, tenant-db |
+| `@cosmicdrift/kumiko-framework/db` | `buildEntityTableMeta`, `createEventStoreExecutor`, migrations, tenant-db |
 | `@cosmicdrift/kumiko-framework/event-store` | `events` table, `append`, `loadAggregate`, `loadAggregateAsOf` |
 | `@cosmicdrift/kumiko-framework/pipeline` | Dispatcher, event-dispatcher (AsyncDaemon), projection-rebuild, SSE + search consumers |
 | `@cosmicdrift/kumiko-framework/api` | `buildServer`, auth middleware, SSE route, error contract |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "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>",
@@ -123,6 +123,10 @@
       "types": "./src/search/meilisearch-adapter.ts",
       "default": "./src/search/meilisearch-adapter.ts"
     },
+    "./seeding": {
+      "types": "./src/seeding/index.ts",
+      "default": "./src/seeding/index.ts"
+    },
     "./secrets": {
       "types": "./src/secrets/index.ts",
       "default": "./src/secrets/index.ts"

package/src/db/__tests__/rebuild-marker.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { EntityTableMeta } from "../entity-table-meta";
+import { diffSnapshots, snapshotFromMetas } from "../migrate-generator";
+import { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker } from "../rebuild-marker";
+
+function meta(
+  tableName: string,
+  extraColumn?: EntityTableMeta["columns"][number],
+): EntityTableMeta {
+  return {
+    tableName,
+    source: "unmanaged",
+    indexes: [],
+    columns: [
+      { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+      ...(extraColumn ? [extraColumn] : []),
+    ],
+  };
+}
+
+function tmpDir(): string {
+  return mkdtempSync(join(tmpdir(), "rebuild-marker-"));
+}
+
+describe("rebuildTablesFromDiff", () => {
+  test("includes new + changed tables, excludes dropped, sorted + unique", () => {
+    const prev = snapshotFromMetas([meta("read_a"), meta("read_c")]);
+    const next = snapshotFromMetas([
+      meta("read_a", { name: "title", pgType: "text", notNull: true }),
+      meta("read_b"),
+    ]);
+    const diff = diffSnapshots(prev, next);
+    expect(rebuildTablesFromDiff(diff)).toEqual(["read_a", "read_b"]);
+  });
+
+  test("no schema change → empty", () => {
+    const snap = snapshotFromMetas([meta("read_a")]);
+    expect(rebuildTablesFromDiff(diffSnapshots(snap, snap))).toEqual([]);
+  });
+});
+
+describe("write/read marker", () => {
+  test("roundtrip: write tables → read them back via migration-id", () => {
+    const dir = tmpDir();
+    try {
+      writeRebuildMarker(dir, "0002_add_locale.sql", ["read_users", "read_text_blocks"]);
+      expect(existsSync(join(dir, "0002_add_locale.rebuild.json"))).toBe(true);
+      expect(readRebuildMarker(dir, "0002_add_locale")).toEqual(["read_users", "read_text_blocks"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("empty table list → no marker file written, read returns []", () => {
+    const dir = tmpDir();
+    try {
+      writeRebuildMarker(dir, "0003_noop.sql", []);
+      expect(existsSync(join(dir, "0003_noop.rebuild.json"))).toBe(false);
+      expect(readRebuildMarker(dir, "0003_noop")).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("missing marker → []", () => {
+    const dir = tmpDir();
+    try {
+      expect(readRebuildMarker(dir, "9999_absent")).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("corrupt marker file → [] (does not throw)", () => {
+    const dir = tmpDir();
+    try {
+      writeFileSync(join(dir, "0004_broken.rebuild.json"), "{ not json");
+      expect(readRebuildMarker(dir, "0004_broken")).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/db/index.ts

@@ -95,6 +95,11 @@ export {
   transaction,
   updateMany,
 } from "./query-api";
+export {
+  readRebuildMarker,
+  rebuildTablesFromDiff,
+  writeRebuildMarker,
+} from "./rebuild-marker";
 export { seedReferenceData } from "./reference-data";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl";
 export { tableExists } from "./schema-inspection";

package/src/db/rebuild-marker.ts

@@ -0,0 +1,75 @@
+// Rebuild-Marker für den drizzle-freien Migrations-Pfad.
+//
+// `kumiko schema generate` schreibt neben jedes `NNNN_<name>.sql` einen
+// Sibling-Marker `NNNN_<name>.rebuild.json`, der die in dieser Migration
+// geänderten/neu angelegten Tabellen listet. `kumiko schema apply` liest den
+// Marker für jede frisch applizierte Migration und rebuildet die betroffenen
+// Projektionen.
+//
+// Bewusst nur **Tabellennamen** (kein Projection-Name): der Generator ist
+// registry-frei (kennt die App-Projektionen nicht). Die Auflösung
+// Tabelle→Projection passiert app-seitig beim Apply via
+// `buildProjectionTableIndex(registry)`. Tabellen ohne zugehörige Projektion
+// werden dort einfach übersprungen.
+//
+// Marker werden zum generate-Zeitpunkt aus dem strukturierten `SchemaDiff`
+// geschrieben — nicht beim Apply aus dem (ggf. hand-editierten) SQL
+// re-derived.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { SchemaDiff } from "./migrate-generator";
+
+const MARKER_VERSION = 1 as const;
+
+type RebuildMarker = {
+  readonly version: typeof MARKER_VERSION;
+  readonly tables: readonly string[];
+};
+
+function markerPathFor(migrationsDir: string, migrationId: string): string {
+  return join(migrationsDir, `${migrationId}.rebuild.json`);
+}
+
+// Tabellen die nach dieser Migration einen Projection-Rebuild brauchen können:
+// neu angelegte + spalten-/index-geänderte. Gelöschte Tabellen NICHT (die
+// Projektion ist mit der Tabelle weg). Sortiert + dedupliziert für stabilen
+// PR-Diff.
+export function rebuildTablesFromDiff(diff: SchemaDiff): readonly string[] {
+  const names = new Set<string>();
+  for (const t of diff.changedTables) names.add(t.tableName);
+  for (const t of diff.newTables) names.add(t.tableName);
+  return [...names].sort();
+}
+
+// Schreibt `<sqlFilename ohne .sql>.rebuild.json`. Leere Tabellen-Liste →
+// kein Marker (z.B. reine Drop-Migration).
+export function writeRebuildMarker(
+  migrationsDir: string,
+  sqlFilename: string,
+  tables: readonly string[],
+): void {
+  // skip: leere Tabellen-Liste → kein Marker (z.B. reine Drop-Migration).
+  if (tables.length === 0) return;
+  const migrationId = sqlFilename.replace(/\.sql$/, "");
+  const marker: RebuildMarker = { version: MARKER_VERSION, tables };
+  writeFileSync(markerPathFor(migrationsDir, migrationId), `${JSON.stringify(marker, null, 2)}\n`);
+}
+
+// Liest die Tabellen-Liste für eine applizierte Migration. Kein Marker /
+// kaputtes File → leere Liste (Migration ohne Projection-Impact).
+export function readRebuildMarker(migrationsDir: string, migrationId: string): readonly string[] {
+  const path = markerPathFor(migrationsDir, migrationId);
+  if (!existsSync(path)) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return [];
+  }
+  if (typeof parsed !== "object" || parsed === null || !("tables" in parsed)) return [];
+  const { tables } = parsed;
+  if (!Array.isArray(tables)) return [];
+  return tables.filter((t): t is string => typeof t === "string");
+}

package/src/schema-cli.ts

@@ -17,8 +17,10 @@ import {
   generateMigration,
   loadMigrationsFromDir,
   loadSnapshotJson,
+  rebuildTablesFromDiff,
   type renderTablesDdl,
   runMigrationsFromDir,
+  writeRebuildMarker,
   writeSnapshotJson,
 } from "./db";
 
@@ -105,11 +107,22 @@ export async function runSchemaCli(
       writeFileSync(join(migrationsDir, result.filename), result.sqlContent);
       writeSnapshotJson(snapshotPath, result.snapshot);
 
+      // Rebuild-Marker nur für inkrementelle Migrationen — die Init-Migration
+      // (prevSnapshot===null) legt nur Tabellen an, es gibt keine historischen
+      // Events zum Replayen.
+      const rebuildTables = prevSnapshot === null ? [] : rebuildTablesFromDiff(result.diff);
+      writeRebuildMarker(migrationsDir, result.filename, rebuildTables);
+
       out.log("");
       out.log(`  ✓ ${result.filename}`);
       out.log(
         `    new tables: ${result.diff.newTables.length}, changed: ${result.diff.changedTables.length}, dropped: ${result.diff.droppedTables.length}`,
       );
+      if (rebuildTables.length > 0) {
+        out.log(
+          `    rebuild-marker: ${result.filename.replace(/\.sql$/, ".rebuild.json")} (${rebuildTables.length} table(s))`,
+        );
+      }
       out.log("");
       out.log("  Review + ggf. hand-edit + git add + commit. Apply via: kumiko-schema apply");
       out.log("");

package/src/seeding/__tests__/entity-seed.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { runEventStoreSeed } from "../entity-seed";
+
+describe("runEventStoreSeed", () => {
+  test('default ifExists="skip" returns existing id without update', async () => {
+    let updateCalls = 0;
+    let createCalls = 0;
+
+    const result = await runEventStoreSeed({
+      existing: { id: "agg-1", version: 3 },
+      create: async () => {
+        createCalls++;
+        return { id: "new" };
+      },
+      update: async () => {
+        updateCalls++;
+        return { id: "agg-1" };
+      },
+    });
+
+    expect(result.id).toBe("agg-1");
+    expect(updateCalls).toBe(0);
+    expect(createCalls).toBe(0);
+  });
+
+  test('ifExists="update" calls update when row exists', async () => {
+    let updateCalls = 0;
+
+    const result = await runEventStoreSeed({
+      existing: { id: "agg-2", version: 1 },
+      ifExists: "update",
+      create: async () => ({ id: "new" }),
+      update: async (existing) => {
+        updateCalls++;
+        expect(existing.version).toBe(1);
+        return { id: existing.id };
+      },
+    });
+
+    expect(result.id).toBe("agg-2");
+    expect(updateCalls).toBe(1);
+  });
+
+  test("missing row calls create", async () => {
+    let createCalls = 0;
+
+    const result = await runEventStoreSeed({
+      existing: null,
+      create: async () => {
+        createCalls++;
+        return { id: "created" };
+      },
+      update: async () => ({ id: "never" }),
+    });
+
+    expect(result.id).toBe("created");
+    expect(createCalls).toBe(1);
+  });
+});

package/src/seeding/entity-seed.ts

@@ -0,0 +1,27 @@
+import { DEFAULT_SEED_IF_EXISTS, type SeedIfExists } from "./types";
+
+export type EventStoreSeedExisting = {
+  readonly id: string | number;
+  readonly version: number;
+};
+
+export type RunEventStoreSeedOptions<TExisting extends EventStoreSeedExisting> = {
+  readonly existing: TExisting | null | undefined;
+  readonly ifExists?: SeedIfExists;
+  readonly create: () => Promise<{ id: string | number }>;
+  readonly update: (existing: TExisting) => Promise<{ id: string | number }>;
+};
+
+/** Shared create-or-skip/update path for event-store boot-seed helpers. */
+export async function runEventStoreSeed<TExisting extends EventStoreSeedExisting>(
+  opts: RunEventStoreSeedOptions<TExisting>,
+): Promise<{ id: string | number }> {
+  const ifExists = opts.ifExists ?? DEFAULT_SEED_IF_EXISTS;
+  if (opts.existing != null) {
+    if (ifExists === "skip") {
+      return { id: opts.existing.id };
+    }
+    return opts.update(opts.existing);
+  }
+  return opts.create();
+}

package/src/seeding/index.ts

@@ -0,0 +1,6 @@
+export {
+  type EventStoreSeedExisting,
+  type RunEventStoreSeedOptions,
+  runEventStoreSeed,
+} from "./entity-seed";
+export { DEFAULT_SEED_IF_EXISTS, type SeedIfExists } from "./types";

package/src/seeding/types.ts

@@ -0,0 +1,8 @@
+/** Boot-seed semantics for event-sourced entity helpers.
+ *
+ *  - `skip` (default): row exists → return without write (no event).
+ *  - `update`: row exists → overwrite via executor.update (opt-in, e.g.
+ *    demo-fixtures where code is source-of-truth). */
+export type SeedIfExists = "skip" | "update";
+
+export const DEFAULT_SEED_IF_EXISTS: SeedIfExists = "skip";