@cosmicdrift/kumiko-framework 0.18.0 → 0.19.1

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.18.0",
+  "version": "0.19.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>",
@@ -123,10 +123,18 @@
       "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"
     },
+    "./schema-cli": {
+      "types": "./src/schema-cli.ts",
+      "default": "./src/schema-cli.ts"
+    },
     "./stack": {
       "types": "./src/stack/index.ts",
       "default": "./src/stack/index.ts"

package/src/schema-cli.ts

@@ -0,0 +1,228 @@
+// Shared core for the schema-migration CLI (generate | apply | baseline | status).
+//
+// Used by BOTH the dev `kumiko schema` command (bin/commands/schema.ts) and the
+// shipped `kumiko-schema` bin (dev-server) — so apps run migrations without the
+// full dev-CLI registry (which eager-loads ts-morph-heavy dev commands).
+//
+// NO-MAGIC-ON-DATA: reads only checked-in artifacts (kumiko/schema.ts →
+// ENTITY_METAS, kumiko/migrations/*.sql). Never auto-generates at runtime,
+// never applies on app-boot — apply/baseline are explicit deploy-steps.
+
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import {
+  baselineMigrations,
+  createDbConnection,
+  fetchAppliedMigrations,
+  generateMigration,
+  loadMigrationsFromDir,
+  loadSnapshotJson,
+  type renderTablesDdl,
+  runMigrationsFromDir,
+  writeSnapshotJson,
+} from "./db";
+
+export type SchemaCliOut = {
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+};
+
+const SNAPSHOT_FILENAME = ".snapshot.json";
+
+async function loadEntityMetasFromApp(
+  schemaFile: string,
+): Promise<Parameters<typeof renderTablesDdl>[0]> {
+  // bun imports TS directly — no spawn needed.
+  const mod = (await import(schemaFile)) as { ENTITY_METAS?: unknown };
+  if (!Array.isArray(mod.ENTITY_METAS)) {
+    throw new Error(
+      `Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`,
+    );
+  }
+  return mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0];
+}
+
+function nextSequenceNumber(migrationsDir: string): number {
+  if (!existsSync(migrationsDir)) return 1;
+  const files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql"));
+  let max = 0;
+  for (const f of files) {
+    const m = f.match(/^(\d+)_/);
+    if (m) {
+      const n = Number(m[1]);
+      if (n > max) max = n;
+    }
+  }
+  return max + 1;
+}
+
+/**
+ * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where
+ * `kumiko/schema.ts` + `kumiko/migrations/` live). Returns a process exit code.
+ */
+export async function runSchemaCli(
+  argv: readonly string[],
+  appCwd: string,
+  out: SchemaCliOut,
+): Promise<number> {
+  const sub = argv[0];
+  const schemaFile = resolvePath(appCwd, "kumiko/schema.ts");
+  const migrationsDir = resolvePath(appCwd, "kumiko/migrations");
+
+  switch (sub) {
+    case "generate": {
+      const name = argv[1];
+      if (!name) {
+        out.err("  Usage: kumiko-schema generate <name>");
+        return 1;
+      }
+      if (!existsSync(schemaFile)) {
+        out.err(`  ${schemaFile} fehlt.`);
+        out.err("  App-Convention: kumiko/schema.ts mit");
+        out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
+        return 1;
+      }
+      const metas = await loadEntityMetasFromApp(schemaFile);
+      const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
+      const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
+      const result = generateMigration({
+        metas,
+        prevSnapshot,
+        name,
+        sequenceNumber: nextSequenceNumber(migrationsDir),
+      });
+
+      const isEmpty =
+        result.diff.newTables.length === 0 &&
+        result.diff.changedTables.length === 0 &&
+        result.diff.droppedTables.length === 0;
+      if (isEmpty) {
+        out.log("  No schema changes detected — kein neues Migration-File geschrieben.");
+        return 0;
+      }
+
+      if (!existsSync(migrationsDir)) mkdirSync(migrationsDir, { recursive: true });
+      writeFileSync(join(migrationsDir, result.filename), result.sqlContent);
+      writeSnapshotJson(snapshotPath, result.snapshot);
+
+      out.log("");
+      out.log(`  ✓ ${result.filename}`);
+      out.log(
+        `    new tables: ${result.diff.newTables.length}, changed: ${result.diff.changedTables.length}, dropped: ${result.diff.droppedTables.length}`,
+      );
+      out.log("");
+      out.log("  Review + ggf. hand-edit + git add + commit. Apply via: kumiko-schema apply");
+      out.log("");
+      return 0;
+    }
+
+    case "apply": {
+      const dbUrl = process.env["DATABASE_URL"];
+      if (!dbUrl) {
+        out.err("  DATABASE_URL not set.");
+        return 1;
+      }
+      if (!existsSync(migrationsDir)) {
+        out.err(`  ${migrationsDir} fehlt — erst kumiko-schema generate <name>.`);
+        return 1;
+      }
+      const { db, close } = createDbConnection(dbUrl);
+      try {
+        const result = await runMigrationsFromDir(db, migrationsDir);
+        out.log("");
+        if (result.applied.length === 0) {
+          out.log(`  ✓ All ${result.skipped.length} migrations already applied.`);
+        } else {
+          out.log(`  ✓ Applied ${result.applied.length}:`);
+          for (const id of result.applied) out.log(`    + ${id}`);
+          if (result.skipped.length > 0) out.log(`  (${result.skipped.length} already applied)`);
+        }
+        out.log("");
+        return 0;
+      } catch (e) {
+        out.err("");
+        out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+        out.err("");
+        return 1;
+      } finally {
+        await close();
+      }
+    }
+
+    case "baseline": {
+      // Adopt an existing DB: mark all checked-in migrations as applied WITHOUT
+      // running their SQL (prod tables already exist — cutover from the legacy
+      // drizzle system). Afterwards the boot-gate is drift-free.
+      const dbUrl = process.env["DATABASE_URL"];
+      if (!dbUrl) {
+        out.err("  DATABASE_URL not set.");
+        return 1;
+      }
+      if (!existsSync(migrationsDir)) {
+        out.err(`  ${migrationsDir} fehlt — erst kumiko-schema generate <name>.`);
+        return 1;
+      }
+      const { db, close } = createDbConnection(dbUrl);
+      try {
+        const result = await baselineMigrations(db, loadMigrationsFromDir(migrationsDir));
+        out.log("");
+        out.log(`  ✓ Marked ${result.marked.length} migration(s) as applied (no SQL run):`);
+        for (const id of result.marked) out.log(`    + ${id}`);
+        if (result.alreadyTracked.length > 0) {
+          out.log(`  (${result.alreadyTracked.length} already tracked)`);
+        }
+        out.log("");
+        return 0;
+      } catch (e) {
+        out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+      } finally {
+        await close();
+      }
+    }
+
+    case "status": {
+      const dbUrl = process.env["DATABASE_URL"];
+      if (!dbUrl) {
+        out.err("  DATABASE_URL not set.");
+        return 1;
+      }
+      if (!existsSync(migrationsDir)) {
+        out.log("  Kein kumiko/migrations/ — App ist noch auf dem alten drizzle-Pfad.");
+        return 0;
+      }
+      const local = loadMigrationsFromDir(migrationsDir);
+      const { db, close } = createDbConnection(dbUrl);
+      try {
+        // fetchAppliedMigrations wirft wenn die tracking-table noch nicht da ist.
+        let applied: Set<string>;
+        try {
+          applied = new Set((await fetchAppliedMigrations(db)).map((a) => a.id));
+        } catch {
+          applied = new Set();
+        }
+        out.log("");
+        out.log(`  ${local.length} migrations in ${migrationsDir}:`);
+        for (const m of local) out.log(`    ${applied.has(m.id) ? "✓" : " "} ${m.id}`);
+        const pending = local.filter((m) => !applied.has(m.id)).length;
+        out.log("");
+        out.log(`  ${applied.size} applied, ${pending} pending.`);
+        out.log("");
+        return 0;
+      } finally {
+        await close();
+      }
+    }
+
+    default: {
+      out.log("");
+      out.log("  Subcommands:");
+      out.log("    generate <name>   Schreibe neue Migration aus EntityTableMeta-Diff");
+      out.log("    apply             Applied pending checked-in SQL-Files");
+      out.log("    baseline          Markiere checked-in Migrations als applied (kein SQL-Run)");
+      out.log("    status            Liste applied vs pending");
+      out.log("");
+      return 0;
+    }
+  }
+}

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";