okengine 0.6.1 → 0.8.0

package/src/cli/db.test.ts

@@ -3,15 +3,74 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { Database } from "bun:sqlite";
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
-import { dbCli, emitAbstractSchemaPrestep, runDb, runGenerate, runPush } from "./db.ts";
+import { createFx } from "../kernel/fx.ts";
+import { defineSeed, type SeedFn } from "../elements/store/seed.ts";
+import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
+import {
+  dbCli,
+  emitAbstractSchemaPrestep,
+  executeSeedDef,
+  runDb,
+  runGenerate,
+  runPush,
+  runSeed,
+} from "./db.ts";
 
 /** Repo public entry — absolute import so temp apps need no install. */
 const OKE_INDEX = resolve(import.meta.dir, "../index.ts");
 const CONFIG_MOD = resolve(import.meta.dir, "../config/index.ts");
+const DB_MOD = resolve(import.meta.dir, "./db.ts");
+
+/**
+ * Run `oke db generate|migrate` in a fresh Bun process.
+ *
+ * drizzle-kit's in-process `generate` caches the schema module — a second
+ * generate in the same process after rewriting the schema file returns
+ * `no_changes`. Real CLI invocations are one process each; the adversarial
+ * multi-migration test must match that.
+ *
+ * Temp projects live under {@link import.meta.dir} so `bunx drizzle-kit`
+ * (migrate's default) walks up to the repo `node_modules`.
+ */
+async function runDbFresh(
+  sub: "generate" | "migrate",
+  cwd: string,
+): Promise<{ readonly code: number; readonly out: string }> {
+  const proc = Bun.spawn(
+    [
+      "bun",
+      "-e",
+      `import { runDb } from ${JSON.stringify(DB_MOD)};
+const cwd = ${JSON.stringify(cwd)};
+const prev = process.cwd();
+process.chdir(cwd);
+try {
+  process.exit(await runDb(${JSON.stringify(sub)}, { cwd, skipEmit: true }));
+} finally {
+  process.chdir(prev);
+}
+`,
+    ],
+    { cwd, stdout: "pipe", stderr: "pipe", env: process.env as Record<string, string> },
+  );
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, out: `${stdout}${stderr}` };
+}
+
+async function migrationFolders(drizzleDir: string): Promise<string[]> {
+  return (await readdir(drizzleDir, { withFileTypes: true }))
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort();
+}
 
 describe("oke db", () => {
   test("help lists subcommands", async () => {
@@ -26,6 +85,7 @@ describe("oke db", () => {
       expect(lines.join("\n")).toContain("push");
       expect(lines.join("\n")).toContain("generate");
       expect(lines.join("\n")).toContain("migrate");
+      expect(lines.join("\n")).toContain("seed");
       expect(lines.join("\n")).toContain("oke schema generate");
     } finally {
       console.log = orig;
@@ -187,3 +247,281 @@ export const app = oke({ name: "plugin-only" }).plug(
     expect(generated).toContain('integer("hits")');
   });
 });
+
+describe("oke db multi-migration catch-up", () => {
+  /**
+   * Real drizzle-kit generate/migrate through `oke db` — proves multi-file
+   * versioned migrations and that re-migrate / environment lag only apply
+   * previously-unapplied files (drizzle-kit `__drizzle_migrations` history).
+   * The CLI wrapper must not interfere with that bookkeeping.
+   */
+  test("second migrate skips applied files; lag DB catches up with only the new one", async () => {
+    const dir = await mkdtemp(join(import.meta.dir, ".tmp-db-mig-"));
+    try {
+      await mkdir(join(dir, "src"), { recursive: true });
+      await writeFile(
+        join(dir, "src", "schema.ts"),
+        `import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+export const notes = sqliteTable("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+});
+`,
+      );
+      await writeFile(
+        join(dir, "drizzle.config.ts"),
+        `import { defineConfig } from "drizzle-kit";
+export default defineConfig({
+  dialect: "sqlite",
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dbCredentials: { url: "file:./app.db" },
+});
+`,
+      );
+
+      const gen1 = await runDbFresh("generate", dir);
+      expect(gen1.code).toBe(EXIT_OK);
+      expect(gen1.out).toMatch(/oke db generate: wrote /);
+      const migsAfterFirst = await migrationFolders(join(dir, "drizzle"));
+      expect(migsAfterFirst.length).toBe(1);
+      const initialMig = migsAfterFirst[0];
+      expect(initialMig).toBeDefined();
+      if (initialMig === undefined) throw new Error("expected initial migration folder");
+
+      const mig1 = await runDbFresh("migrate", dir);
+      expect(mig1.code).toBe(EXIT_OK);
+      expect(mig1.out).toContain("oke db migrate: applied");
+
+      let db = new Database(join(dir, "app.db"));
+      expect(
+        db.query("SELECT name FROM sqlite_master WHERE type='table' AND name='notes'").get(),
+      ).toBeTruthy();
+      let history = db.query("SELECT name FROM __drizzle_migrations ORDER BY id").all() as Array<{
+        name: string;
+      }>;
+      expect(history.map((r) => r.name)).toEqual([initialMig]);
+      db.close();
+
+      await writeFile(
+        join(dir, "src", "schema.ts"),
+        `import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+export const notes = sqliteTable("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  pinned: integer("pinned").notNull().default(0),
+});
+`,
+      );
+      // Distinct timestamp folder names (drizzle-kit uses YYYYMMDDHHmmss).
+      await Bun.sleep(1100);
+
+      const gen2 = await runDbFresh("generate", dir);
+      expect(gen2.code).toBe(EXIT_OK);
+      expect(gen2.out).toMatch(/oke db generate: wrote /);
+      const migs = await migrationFolders(join(dir, "drizzle"));
+      expect(migs.length).toBe(2);
+      const firstMig = migs[0];
+      const secondMig = migs[1];
+      expect(firstMig).toBeDefined();
+      expect(secondMig).toBeDefined();
+      if (firstMig === undefined || secondMig === undefined) {
+        throw new Error("expected two migration folders");
+      }
+      expect(firstMig).toBe(initialMig);
+
+      const mig2 = await runDbFresh("migrate", dir);
+      expect(mig2.code).toBe(EXIT_OK);
+
+      db = new Database(join(dir, "app.db"));
+      history = db.query("SELECT name FROM __drizzle_migrations ORDER BY id").all() as Array<{
+        name: string;
+      }>;
+      expect(history.map((r) => r.name)).toEqual([firstMig, secondMig]);
+      const cols = db.query("PRAGMA table_info(notes)").all() as Array<{ name: string }>;
+      expect(cols.map((c) => c.name)).toContain("pinned");
+      db.close();
+
+      // Idempotent re-migrate: history unchanged, no error.
+      const migNoop = await runDbFresh("migrate", dir);
+      expect(migNoop.code).toBe(EXIT_OK);
+      db = new Database(join(dir, "app.db"));
+      const historyNoop = db
+        .query("SELECT name FROM __drizzle_migrations ORDER BY id")
+        .all() as Array<{ name: string }>;
+      expect(historyNoop.map((r) => r.name)).toEqual([firstMig, secondMig]);
+      db.close();
+
+      // Staging/prod lag: fresh DB with only the first migration applied,
+      // then both files present — catch up applies only the second.
+      await rm(join(dir, "app.db"), { force: true });
+      const stash = join(dir, "_stash_second");
+      await rm(stash, { recursive: true, force: true });
+      await rename(join(dir, "drizzle", secondMig), stash);
+
+      const lagFirst = await runDbFresh("migrate", dir);
+      expect(lagFirst.code).toBe(EXIT_OK);
+      db = new Database(join(dir, "app.db"));
+      const lagHist1 = db
+        .query("SELECT name FROM __drizzle_migrations ORDER BY id")
+        .all() as Array<{ name: string }>;
+      expect(lagHist1.map((r) => r.name)).toEqual([firstMig]);
+      const lagCols1 = db.query("PRAGMA table_info(notes)").all() as Array<{ name: string }>;
+      expect(lagCols1.map((c) => c.name)).not.toContain("pinned");
+      db.close();
+
+      await rename(stash, join(dir, "drizzle", secondMig));
+      const lagCatchUp = await runDbFresh("migrate", dir);
+      expect(lagCatchUp.code).toBe(EXIT_OK);
+      db = new Database(join(dir, "app.db"));
+      const lagHist2 = db
+        .query("SELECT name FROM __drizzle_migrations ORDER BY id")
+        .all() as Array<{ name: string }>;
+      expect(lagHist2.map((r) => r.name)).toEqual([firstMig, secondMig]);
+      const lagCols2 = db.query("PRAGMA table_info(notes)").all() as Array<{ name: string }>;
+      expect(lagCols2.map((c) => c.name)).toContain("pinned");
+      db.close();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }, 120_000);
+});
+
+describe("oke db seed", () => {
+  function trackingDef(order: string[]) {
+    const a: SeedFn = async function a() {
+      order.push("a");
+    };
+    const b: SeedFn = async function b() {
+      order.push("b");
+    };
+    const dev: SeedFn = async function seedDev() {
+      order.push("dev");
+    };
+    const prod: SeedFn = async function seedProd() {
+      order.push("prod");
+    };
+    return defineSeed({
+      essential: [a, b],
+      dev,
+      prod,
+    });
+  }
+
+  async function seedWith(
+    env: "local" | "docker" | "test" | "prod",
+    extras: Parameters<typeof runSeed>[0] = {},
+  ) {
+    const order: string[] = [];
+    const out: string[] = [];
+    const code = await runSeed({
+      env,
+      seedDef: trackingDef(order),
+      createFx: async () => ({
+        fx: createFx({ flow: "oke.db.seed.test" }),
+        stop: async () => {},
+      }),
+      write: (t) => out.push(t),
+      force: true,
+      ...extras,
+    });
+    return { code, order, out: out.join("") };
+  }
+
+  test("essential array order is execution order", async () => {
+    const { code, order, out } = await seedWith("local");
+    expect(code).toBe(EXIT_OK);
+    expect(order.slice(0, 2)).toEqual(["a", "b"]);
+    expect(out).toContain("oke db seed: essential a");
+    expect(out).toContain("oke db seed: ok");
+  });
+
+  test("local runs essential + dev, never prod", async () => {
+    const { order } = await seedWith("local");
+    expect(order).toEqual(["a", "b", "dev"]);
+  });
+
+  test("docker runs essential + dev, never prod", async () => {
+    const { order } = await seedWith("docker");
+    expect(order).toEqual(["a", "b", "dev"]);
+  });
+
+  test("prod runs essential + prod, never dev", async () => {
+    const { order } = await seedWith("prod");
+    expect(order).toEqual(["a", "b", "prod"]);
+  });
+
+  test("test runs essential only", async () => {
+    const { order, out } = await seedWith("test");
+    expect(order).toEqual(["a", "b"]);
+    expect(out).toContain("essential only");
+  });
+
+  test("prod without --force requires confirmEnv", async () => {
+    const out: string[] = [];
+    let asked = false;
+    const code = await runSeed({
+      env: "prod",
+      force: false,
+      stdinIsTTY: true,
+      seedDef: defineSeed({ essential: async () => {} }),
+      createFx: async () => ({
+        fx: createFx({ flow: "oke.db.seed.test" }),
+        stop: async () => {},
+      }),
+      confirmEnv: async () => {
+        asked = true;
+        return false;
+      },
+      write: (t) => out.push(t),
+    });
+    expect(asked).toBe(true);
+    expect(code).toBe(EXIT_USAGE);
+    expect(out.join("")).toContain("cancelled");
+  });
+
+  test("prod with --force skips confirm", async () => {
+    let asked = false;
+    const { code } = await seedWith("prod", {
+      force: true,
+      confirmEnv: async () => {
+        asked = true;
+        return false;
+      },
+    });
+    expect(asked).toBe(false);
+    expect(code).toBe(EXIT_OK);
+  });
+
+  test("docker confirm proceeds when confirmEnv returns true", async () => {
+    const out: string[] = [];
+    const order: string[] = [];
+    const code = await runSeed({
+      env: "docker",
+      force: false,
+      stdinIsTTY: true,
+      seedDef: trackingDef(order),
+      createFx: async () => ({
+        fx: createFx({ flow: "oke.db.seed.test" }),
+        stop: async () => {},
+      }),
+      confirmEnv: async (env, target) => {
+        expect(env).toBe("docker");
+        expect(target.length).toBeGreaterThan(0);
+        return true;
+      },
+      write: (t) => out.push(t),
+    });
+    expect(code).toBe(EXIT_OK);
+    expect(order).toEqual(["a", "b", "dev"]);
+    expect(out.join("")).toContain("oke db seed:");
+  });
+
+  test("executeSeedDef is the category source of truth", async () => {
+    const order: string[] = [];
+    const out: string[] = [];
+    const fx = createFx({ flow: "x" });
+    await executeSeedDef(trackingDef(order), "prod", fx, (t) => out.push(t));
+    expect(order).toEqual(["a", "b", "prod"]);
+  });
+});

package/src/cli/db.ts

@@ -1,5 +1,6 @@
 /**
- * `oke db push|generate|migrate` — domain schema sync via drizzle-kit.
+ * `oke db push|generate|migrate|seed` — domain schema sync via drizzle-kit,
+ * plus explicit seed runs.
  *
  * Distinct from `oke schema generate` (core/plugin stub tables).
  * When abstract decls exist (`src/schema.decl.ts`), emits Drizzle first —
@@ -15,11 +16,24 @@ import {
 import { loadPluginTablesFromAppEntry } from "../elements/store/load-plugin-tables.ts";
 import { resolveDriverId, type ConfigEnv, type OkeConfig } from "../config/index.ts";
 import type { TableContribution } from "../kernel/plugin.ts";
+import { runSeed, type SeedOptions } from "./db-seed.ts";
 import { resolveDrizzleKitEnv } from "./drizzle-env.ts";
 import { resolveDevSqlEnv } from "./resolve-dev-sql-env.ts";
 import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
 import { loadOkeConfig } from "./load-config.ts";
 
+export {
+  executeSeedDef,
+  formatSeedTarget,
+  isSeedDef,
+  loadSeedDef,
+  redactConnectionTarget,
+  runSeed,
+  runSeedFns,
+  type SeedOptions,
+  type SeedTally,
+} from "./db-seed.ts";
+
 /**
  * Apply a drizzle-kit env overlay to `process.env` for the in-process SDK,
  * returning a restore function. drizzle-kit's `push`/`generate` read
@@ -67,7 +81,7 @@ export async function withDrizzleKitEnv<T>(
 }
 
 /** Subcommands under `oke db`. */
-export type DbSubcommand = "push" | "generate" | "migrate";
+export type DbSubcommand = "push" | "generate" | "migrate" | "seed";
 
 /** Options for {@link runDb}. */
 export interface DbOptions {
@@ -104,6 +118,15 @@ export interface DbOptions {
   readonly pluginTables?: readonly TableContribution[];
   /** Override app entry path for plugin-table discovery. */
   readonly entry?: string;
+  /** Skip docker/prod confirm for seed (`--force`). */
+  readonly force?: boolean;
+  /** Seed module path override. */
+  readonly seedPath?: string;
+  /** Seed-only injectables forwarded to {@link runSeed}. */
+  readonly seedDef?: SeedOptions["seedDef"];
+  readonly createFx?: SeedOptions["createFx"];
+  readonly confirmEnv?: SeedOptions["confirmEnv"];
+  readonly stdinIsTTY?: boolean;
 }
 
 /** Minimal drizzle-kit envelope we handle. */
@@ -135,7 +158,7 @@ export async function resolveDrizzleConfigPath(
 /**
  * Run `oke db <subcommand>`.
  *
- * @param sub - push | generate | migrate
+ * @param sub - push | generate | migrate | seed
  * @param options - Paths / injectables
  */
 export async function runDb(sub: DbSubcommand, options: DbOptions = {}): Promise<number> {
@@ -143,6 +166,22 @@ export async function runDb(sub: DbSubcommand, options: DbOptions = {}): Promise
   const cwd = options.cwd ?? process.cwd();
   const loaded = await loadOkeConfig(cwd).catch(() => null);
   const env = options.env ?? (await resolveDevSqlEnv(cwd));
+
+  if (sub === "seed") {
+    return runSeed({
+      cwd,
+      write,
+      env,
+      force: options.force,
+      seedPath: options.seedPath,
+      entry: options.entry,
+      seedDef: options.seedDef,
+      createFx: options.createFx,
+      confirmEnv: options.confirmEnv,
+      stdinIsTTY: options.stdinIsTTY,
+    });
+  }
+
   if (!options.skipEmit) {
     await emitAbstractSchemaPrestep(cwd, loaded?.config, write, env, {
       pluginTables: options.pluginTables,
@@ -399,16 +438,16 @@ export async function detectDbDrift(options: DbOptions = {}): Promise<{
 }
 
 /**
- * CLI entry: parse `oke db <push|generate|migrate> [--config path]`.
+ * CLI entry: parse `oke db <push|generate|migrate|seed> […]`.
  *
  * @param args - Args after `db`
  */
 export async function dbCli(args: readonly string[]): Promise<number> {
   const sub = args[0];
   if (!sub || sub === "--help" || sub === "-h") {
-    console.log(`oke db push|generate|migrate [--config|-c drizzle.config.ts]
+    console.log(`oke db push|generate|migrate|seed [--config|-c] [--env name] [--force]
 
-Domain schema sync via drizzle-kit.
+Domain schema sync via drizzle-kit, plus explicit seed.
 When src/schema.decl.ts and/or a plugged app entry exists, emits
 schema.generated.ts from store.schema.table + live plugin .table()
 contributions — then runs drizzle-kit.
@@ -418,24 +457,52 @@ Not the same as \`oke schema generate\` (core/plugin stub tables).
   push       Apply schema to the live local DB (dev; no migration files)
   generate   Write versioned SQL under drizzle/ for review
   migrate    Apply generated migrations (explicit; never automatic in prod)
+  seed       Run defineSeed (essential + env category); never at boot
+
+  --env      Override config env (local|docker|test|prod)
+  --force    Skip docker/prod confirmation prompt (CI)
+  --entry    App entry for seed boot / plugin table discovery
 `);
     return sub ? EXIT_OK : EXIT_USAGE;
   }
-  if (sub !== "push" && sub !== "generate" && sub !== "migrate") {
+  if (sub !== "push" && sub !== "generate" && sub !== "migrate" && sub !== "seed") {
     console.error(`oke db: unknown subcommand "${sub}"`);
     return EXIT_USAGE;
   }
 
   let config: string | undefined;
+  let env: ConfigEnv | undefined;
+  let force = false;
+  let entry: string | undefined;
   for (let i = 1; i < args.length; i++) {
     const a = args[i]!;
     if (a === "--config" || a === "-c") config = args[++i];
+    else if (a === "--env") {
+      const value = args[++i];
+      const parsed = parseConfigEnv(value);
+      if (!parsed) {
+        console.error(`oke db: invalid --env ${JSON.stringify(value)} (local|docker|test|prod)`);
+        return EXIT_USAGE;
+      }
+      env = parsed;
+    } else if (a === "--force") force = true;
+    else if (a === "--entry" || a === "-e") entry = args[++i];
     else if (a === "--help" || a === "-h") {
       return dbCli(["--help"]);
+    } else if (a.startsWith("-")) {
+      console.error(`oke db ${sub}: unknown flag ${a}`);
+      return EXIT_USAGE;
     }
   }
 
-  return runDb(sub, { config });
+  return runDb(sub, { config, env, force, entry });
+}
+
+function parseConfigEnv(value: string | undefined): ConfigEnv | undefined {
+  if (value === "local" || value === "docker" || value === "test" || value === "prod") {
+    return value;
+  }
+  return undefined;
 }
 
 function reportKitResult(verb: string, result: DbKitResult, write: (text: string) => void): number {

package/src/cli/dev-db-push.test.ts

@@ -139,6 +139,65 @@ export const entries = sqliteTable("entries", {
     expect(pushes.length).toBeGreaterThan(before);
   });
 
+  test("schema.generated.ts change does not re-trigger dbPush", async () => {
+    const cwd = await scaffoldProject();
+    const pushes: string[] = [];
+    const watcher = controlledWatcher();
+    let resolveReady!: () => void;
+    const ready = new Promise<void>((r) => {
+      resolveReady = r;
+    });
+
+    const result = await runDev({
+      cwd,
+      local: true,
+      keepAlive: false,
+      dryRun: false,
+      appPort: 0,
+      consolePort: 0,
+      mcpPort: 0,
+      silentClaim: true,
+      stdinIsTTY: false,
+      startApp: async () => ({
+        port: 0,
+        url: new URL("http://127.0.0.1:9"),
+        stop() {},
+      }),
+      serveConsole: async () => ({
+        port: 0,
+        stop() {},
+      }),
+      serveMcp: async () => ({
+        port: 0,
+        url: new URL("http://127.0.0.1:9"),
+        stop() {},
+      }),
+      regenClient: async () => {},
+      dbPush: async () => {
+        pushes.push("push");
+        return 0;
+      },
+      onDbAutoPush: () => {
+        resolveReady();
+      },
+      watchFs: watcher.watchFs,
+      onReady: async (session) => {
+        sessions.push(session);
+      },
+    });
+
+    expect(result.code).toBe(0);
+    await Promise.race([ready, Bun.sleep(800)]);
+    const before = pushes.length;
+    expect(before).toBeGreaterThanOrEqual(1);
+
+    // Simulate emit writing schema.generated.ts after push — must not loop.
+    watcher.change("schema.generated.ts");
+    watcher.change("src/schema.generated.ts");
+    await Bun.sleep(500);
+    expect(pushes.length).toBe(before);
+  });
+
   test("--no-db-push / noDbPush never calls dbPush", async () => {
     const cwd = await scaffoldProject();
     const pushes: string[] = [];

package/src/cli/dev.test.ts

@@ -645,6 +645,46 @@ describe("oke dev mode resolution", () => {
     expect(await readDevMode(dir)).toBeNull();
   });
 
+  test("session stop calls composeStop after a successful docker up", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-dev-compose-stop-"));
+    await Bun.write(join(dir, "src/app.ts"), "export {}\n");
+    await writeDevMode(dir, "docker");
+    let upCalls = 0;
+    let stopCalls = 0;
+    let stoppedFiles: readonly string[] | undefined;
+    const result = await runDev({
+      cwd: dir,
+      stdinIsTTY: false,
+      images: { "store.sql": "postgres:16-alpine" },
+      credentials: {
+        "store.sql": {
+          user: "oke",
+          password: "test-password-not-in-yaml",
+          database: "oke",
+        },
+      },
+      composeUp: async (files) => {
+        upCalls++;
+        expect(files.length).toBeGreaterThan(0);
+      },
+      composeStop: (files) => {
+        stopCalls++;
+        stoppedFiles = files;
+      },
+      startApp: async () => ({ stop() {} }),
+      serveConsole: async () => ({ stop() {} }),
+      regenClient: async () => {},
+      write: () => {},
+      keepAlive: false,
+    });
+    expect(result.code).toBe(0);
+    expect(upCalls).toBe(1);
+    expect(result.session).toBeDefined();
+    result.session!.stop();
+    expect(stopCalls).toBe(1);
+    expect(stoppedFiles?.length).toBeGreaterThan(0);
+  });
+
   test("saved docker + compose failure exits loudly (no silent downgrade)", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-dev-mode-fail-"));
     await Bun.write(join(dir, "src/app.ts"), "export {}\n");