okengine 0.2.6 → 0.2.8

package/src/cli/db.ts

@@ -0,0 +1,386 @@
+/**
+ * `oke db push|generate|migrate` — domain schema sync via drizzle-kit.
+ *
+ * Distinct from `oke schema generate` (core/plugin stub tables).
+ * When abstract decls exist (`src/schema.decl.ts`), emits Drizzle first —
+ * not a third schema CLI.
+ */
+
+import { resolve } from "node:path";
+import {
+  dialectFromDriverId,
+  maybeEmitDomainSchema,
+  type SqlDialect,
+} from "../elements/store/emit-drizzle.ts";
+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 { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
+import { loadOkeConfig } from "./load-config.ts";
+
+/** Subcommands under `oke db`. */
+export type DbSubcommand = "push" | "generate" | "migrate";
+
+/** Options for {@link runDb}. */
+export interface DbOptions {
+  readonly cwd?: string;
+  /** Path to drizzle.config.ts (overrides `db.config`). */
+  readonly config?: string;
+  readonly write?: (text: string) => void;
+  /** Injectable push (tests). */
+  readonly pushFn?: (opts: { config: string }) => Promise<DbKitResult>;
+  /** Injectable generate (tests). */
+  readonly generateFn?: (opts: {
+    config: string;
+  }) => Promise<DbKitResult & { readonly migration_path?: string }>;
+  /** Injectable migrate (tests). */
+  readonly migrateFn?: (opts: { config: string; cwd: string }) => Promise<number>;
+  /**
+   * Dry-run push via drizzle-kit `explain` — used by doctor drift checks.
+   */
+  readonly explain?: boolean;
+  /**
+   * Skip abstract-schema emit pre-step (tests / explain-only).
+   */
+  readonly skipEmit?: boolean;
+  /** Active config env for dialect resolution (default `local`). */
+  readonly env?: ConfigEnv;
+  /**
+   * Injectable plugin tables for emit (tests). When omitted, loads the live
+   * app entry and reads `app.plugins.tableContributions()`.
+   */
+  readonly pluginTables?: readonly TableContribution[];
+  /** Override app entry path for plugin-table discovery. */
+  readonly entry?: string;
+}
+
+/** Minimal drizzle-kit envelope we handle. */
+export interface DbKitResult {
+  readonly status: "ok" | "no_changes" | "missing_hints" | "error" | string;
+  readonly error?: { readonly code?: string; readonly message?: string };
+  readonly unresolved?: readonly unknown[];
+}
+
+/**
+ * Resolve the drizzle config path for a project.
+ *
+ * @param cwd - Project root
+ * @param options - CLI / config overrides
+ */
+export async function resolveDrizzleConfigPath(
+  cwd: string,
+  options: {
+    readonly config?: string;
+    readonly loadedConfig?: OkeConfig | null;
+  } = {},
+): Promise<string> {
+  if (options.config) return resolve(cwd, options.config);
+  const loaded = options.loadedConfig ?? (await loadOkeConfig(cwd).catch(() => null))?.config;
+  const fromConfig = loaded?.db?.config;
+  return resolve(cwd, fromConfig ?? "drizzle.config.ts");
+}
+
+/**
+ * Run `oke db <subcommand>`.
+ *
+ * @param sub - push | generate | migrate
+ * @param options - Paths / injectables
+ */
+export async function runDb(sub: DbSubcommand, options: DbOptions = {}): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const cwd = options.cwd ?? process.cwd();
+  const loaded = await loadOkeConfig(cwd).catch(() => null);
+  if (!options.skipEmit) {
+    await emitAbstractSchemaPrestep(cwd, loaded?.config, write, options.env ?? "local", {
+      pluginTables: options.pluginTables,
+      entry: options.entry,
+    });
+  }
+  const configPath = await resolveDrizzleConfigPath(cwd, {
+    config: options.config,
+    loadedConfig: loaded?.config,
+  });
+
+  if (sub === "push") {
+    return runPush(configPath, write, { ...options, skipEmit: true });
+  }
+  if (sub === "generate") {
+    return runGenerate(configPath, write, { ...options, skipEmit: true });
+  }
+  if (sub === "migrate") {
+    return runMigrate(configPath, cwd, write, { ...options, skipEmit: true });
+  }
+  write(`oke db: unknown subcommand\n`);
+  return EXIT_USAGE;
+}
+
+/**
+ * Emit `schema.generated.ts` from abstract decls + live plugged plugin tables.
+ *
+ * @param cwd - Project root
+ * @param config - Loaded oke config
+ * @param write - Output
+ * @param env - Active env for dialect
+ * @param options - Injectables / entry override
+ */
+export async function emitAbstractSchemaPrestep(
+  cwd: string,
+  config: OkeConfig | null | undefined,
+  write: (text: string) => void = () => {},
+  env: ConfigEnv = "local",
+  options: {
+    readonly pluginTables?: readonly TableContribution[];
+    readonly entry?: string;
+  } = {},
+): Promise<boolean> {
+  const driverId = resolveDriverId(config?.drivers?.store?.sql, env);
+  const dialect: SqlDialect = dialectFromDriverId(driverId);
+  const pluginTables =
+    options.pluginTables ??
+    (await loadPluginTablesFromAppEntry(cwd, {
+      entry: options.entry ?? config?.db?.entry,
+      write,
+    }));
+  const result = await maybeEmitDomainSchema({
+    cwd,
+    dialect,
+    declarePath: config?.db?.declare,
+    outPath: config?.db?.generated,
+    pluginTables,
+    write,
+  });
+  return result.emitted;
+}
+
+/**
+ * Push domain schema to the live database (dev).
+ *
+ * @param configPath - Absolute drizzle.config.ts
+ * @param write - Output
+ * @param options - Injectables / explain
+ */
+export async function runPush(
+  configPath: string,
+  write: (text: string) => void = (t) => process.stdout.write(t),
+  options: DbOptions = {},
+): Promise<number> {
+  const cwd = options.cwd ?? process.cwd();
+  if (!options.skipEmit) {
+    const loaded = await loadOkeConfig(cwd).catch(() => null);
+    await emitAbstractSchemaPrestep(cwd, loaded?.config, write, options.env ?? "local", {
+      pluginTables: options.pluginTables,
+      entry: options.entry,
+    });
+  }
+
+  const pushFn =
+    options.pushFn ??
+    (async (opts: { config: string }) => {
+      const { push } = await import("drizzle-kit/cli");
+      return (await push({
+        config: opts.config,
+        ...(options.explain ? { explain: true } : {}),
+      })) as DbKitResult;
+    });
+
+  let result: DbKitResult;
+  try {
+    result = await pushFn({ config: configPath });
+  } catch (err) {
+    write(`oke db push: ${err instanceof Error ? err.message : String(err)}\n`);
+    write("         → install drizzle-kit and ensure drizzle.config.ts exists\n");
+    return EXIT_RUNTIME;
+  }
+
+  return reportKitResult("push", result, write);
+}
+
+/**
+ * Generate versioned migration SQL under `out` (prod artefact folder).
+ *
+ * @param configPath - Absolute drizzle.config.ts
+ * @param write - Output
+ * @param options - Injectables
+ */
+export async function runGenerate(
+  configPath: string,
+  write: (text: string) => void = (t) => process.stdout.write(t),
+  options: DbOptions = {},
+): Promise<number> {
+  const cwd = options.cwd ?? process.cwd();
+  if (!options.skipEmit) {
+    const loaded = await loadOkeConfig(cwd).catch(() => null);
+    await emitAbstractSchemaPrestep(cwd, loaded?.config, write, options.env ?? "local", {
+      pluginTables: options.pluginTables,
+      entry: options.entry,
+    });
+  }
+
+  const generateFn =
+    options.generateFn ??
+    (async (opts: { config: string }) => {
+      const { generate } = await import("drizzle-kit/cli");
+      return (await generate({ config: opts.config })) as DbKitResult & {
+        readonly migration_path?: string;
+      };
+    });
+
+  let result: DbKitResult & { readonly migration_path?: string };
+  try {
+    result = await generateFn({ config: configPath });
+  } catch (err) {
+    write(`oke db generate: ${err instanceof Error ? err.message : String(err)}\n`);
+    write("         → install drizzle-kit and ensure drizzle.config.ts exists\n");
+    return EXIT_RUNTIME;
+  }
+
+  if (result.status === "ok" && result.migration_path) {
+    write(`oke db generate: wrote ${result.migration_path}\n`);
+    return EXIT_OK;
+  }
+  return reportKitResult("generate", result, write);
+}
+
+/**
+ * Apply versioned migrations (`drizzle-kit migrate`).
+ *
+ * @param configPath - Absolute drizzle.config.ts
+ * @param cwd - Project root
+ * @param write - Output
+ * @param options - Injectables
+ */
+export async function runMigrate(
+  configPath: string,
+  cwd: string,
+  write: (text: string) => void = (t) => process.stdout.write(t),
+  options: DbOptions = {},
+): Promise<number> {
+  if (!options.skipEmit) {
+    const loaded = await loadOkeConfig(cwd).catch(() => null);
+    await emitAbstractSchemaPrestep(cwd, loaded?.config, write, options.env ?? "local", {
+      pluginTables: options.pluginTables,
+      entry: options.entry,
+    });
+  }
+
+  const migrateFn =
+    options.migrateFn ??
+    (async (opts: { config: string; cwd: string }) => {
+      const proc = Bun.spawn(["bunx", "drizzle-kit", "migrate", "--config", opts.config], {
+        cwd: opts.cwd,
+        stdout: "inherit",
+        stderr: "inherit",
+        env: process.env as Record<string, string>,
+      });
+      return await proc.exited;
+    });
+
+  try {
+    const code = await migrateFn({ config: configPath, cwd });
+    if (code === 0) {
+      write("oke db migrate: applied\n");
+      return EXIT_OK;
+    }
+    write(`oke db migrate: exited ${code}\n`);
+    return EXIT_RUNTIME;
+  } catch (err) {
+    write(`oke db migrate: ${err instanceof Error ? err.message : String(err)}\n`);
+    return EXIT_RUNTIME;
+  }
+}
+
+/**
+ * Whether domain schema differs from the live DB (drizzle-kit push explain).
+ *
+ * @param options - Paths / injectables
+ */
+export async function detectDbDrift(options: DbOptions = {}): Promise<{
+  readonly drifted: boolean;
+  readonly detail?: string;
+}> {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = await resolveDrizzleConfigPath(cwd, { config: options.config });
+  const pushFn =
+    options.pushFn ??
+    (async (opts: { config: string }) => {
+      const { push } = await import("drizzle-kit/cli");
+      return (await push({ config: opts.config, explain: true })) as DbKitResult;
+    });
+
+  try {
+    const result = await pushFn({ config: configPath });
+    if (result.status === "no_changes") return { drifted: false };
+    if (result.status === "ok" || result.status === "missing_hints") {
+      return { drifted: true, detail: `drizzle-kit push explain: ${result.status}` };
+    }
+    if (result.status === "error") {
+      return {
+        drifted: false,
+        detail: result.error?.message ?? "drizzle-kit push explain failed",
+      };
+    }
+    return { drifted: false };
+  } catch (err) {
+    return {
+      drifted: false,
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * CLI entry: parse `oke db <push|generate|migrate> [--config path]`.
+ *
+ * @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]
+
+Domain schema sync via drizzle-kit.
+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.
+Hand-written src/schema.ts remains supported (emit skipped if nothing to emit).
+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)
+`);
+    return sub ? EXIT_OK : EXIT_USAGE;
+  }
+  if (sub !== "push" && sub !== "generate" && sub !== "migrate") {
+    console.error(`oke db: unknown subcommand "${sub}"`);
+    return EXIT_USAGE;
+  }
+
+  let config: 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 === "--help" || a === "-h") {
+      return dbCli(["--help"]);
+    }
+  }
+
+  return runDb(sub, { config });
+}
+
+function reportKitResult(verb: string, result: DbKitResult, write: (text: string) => void): number {
+  if (result.status === "ok" || result.status === "no_changes") {
+    write(`oke db ${verb}: ${result.status}\n`);
+    return EXIT_OK;
+  }
+  if (result.status === "missing_hints") {
+    write(
+      `oke db ${verb}: missing_hints — resolve destructive changes manually (not auto-applied)\n`,
+    );
+    return EXIT_RUNTIME;
+  }
+  write(
+    `oke db ${verb}: ${result.status}${result.error?.message ? ` — ${result.error.message}` : ""}\n`,
+  );
+  return EXIT_RUNTIME;
+}

package/src/cli/dev-app-runner.ts

@@ -19,11 +19,7 @@ import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createBunRuntime } from "../runtime/bun.ts";
 import { APP_PORT, type FetchApp } from "../runtime/types.ts";
-import {
-  clearTerminalScreen,
-  formatAppReadyLine,
-  formatDevHero,
-} from "../term.ts";
+import { clearTerminalScreen, formatAppReadyLine, formatDevHero } from "../term.ts";
 import { decodeHeroSnapshot } from "./hero-meta.ts";
 
 /** Stable Bun.serve id so `--hot` reuses the socket across soft reloads. */
@@ -62,9 +58,7 @@ if (
   typeof mod.app.boot !== "function" ||
   typeof mod.app.fetch !== "function"
 ) {
-  console.error(
-    `oke dev: ${absoluteEntry} must export app with boot() and fetch()`,
-  );
+  console.error(`oke dev: ${absoluteEntry} must export app with boot() and fetch()`);
   process.exit(1);
 }
 

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

@@ -0,0 +1,163 @@
+/**
+ * `oke dev` auto `oke db push` on schema change + opt-out.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runDev, type DevSession } from "./dev.ts";
+
+const sessions: DevSession[] = [];
+
+afterEach(() => {
+  for (const s of sessions.splice(0)) s.stop();
+});
+
+async function scaffoldProject(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "oke-dev-db-"));
+  await mkdir(join(dir, "src"), { recursive: true });
+  const configMod = join(import.meta.dir, "../config/index.ts");
+  await writeFile(
+    join(dir, "oke.config.ts"),
+    `import { defineConfig } from ${JSON.stringify(configMod)};
+export default defineConfig({
+  drivers: { store: { sql: { local: "sqlite", test: "memory", prod: "postgres" } } },
+});
+`,
+  );
+  await writeFile(join(dir, "src", "app.ts"), `export {};\n`);
+  await writeFile(
+    join(dir, "src", "schema.ts"),
+    `import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+export const entries = sqliteTable("entries", { id: text("id").primaryKey() });
+`,
+  );
+  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::memory:" },
+});
+`,
+  );
+  return dir;
+}
+
+describe("oke dev db auto-push", () => {
+  test("schema change triggers dbPush when auto-push is on", async () => {
+    const cwd = await scaffoldProject();
+    const pushes: string[] = [];
+    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();
+      },
+      onReady: async (session) => {
+        sessions.push(session);
+      },
+    });
+
+    expect(result.code).toBe(0);
+    // Initial boot triggers one push.
+    await Promise.race([ready, Bun.sleep(800)]);
+    expect(pushes.length).toBeGreaterThanOrEqual(1);
+
+    const before = pushes.length;
+    await writeFile(
+      join(cwd, "src", "schema.ts"),
+      `import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+export const entries = sqliteTable("entries", {
+  id: text("id").primaryKey(),
+  n: integer("n"),
+});
+`,
+    );
+    await Bun.sleep(500);
+    expect(pushes.length).toBeGreaterThan(before);
+  });
+
+  test("--no-db-push / noDbPush never calls dbPush", async () => {
+    const cwd = await scaffoldProject();
+    const pushes: string[] = [];
+
+    const result = await runDev({
+      cwd,
+      local: true,
+      noDbPush: true,
+      keepAlive: 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;
+      },
+      onReady: async (session) => {
+        sessions.push(session);
+      },
+    });
+
+    expect(result.code).toBe(0);
+    await writeFile(
+      join(cwd, "src", "schema.ts"),
+      `import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+export const entries = sqliteTable("entries", { id: text("id").primaryKey(), x: text("x") });
+`,
+    );
+    await Bun.sleep(500);
+    expect(pushes).toHaveLength(0);
+  });
+});

package/src/cli/dev-mode.test.ts

@@ -0,0 +1,45 @@
+/**
+ * `.oke/mode` persistence and prompt gating.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseDevMode, readDevMode, shouldAskDevMode, writeDevMode } from "./dev-mode.ts";
+
+const dirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })));
+});
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "oke-mode-"));
+  dirs.push(dir);
+  return dir;
+}
+
+describe("dev-mode", () => {
+  test("parseDevMode accepts local|docker only", () => {
+    expect(parseDevMode("local")).toBe("local");
+    expect(parseDevMode(" docker \n")).toBe("docker");
+    expect(parseDevMode("stack")).toBeNull();
+    expect(parseDevMode(undefined)).toBeNull();
+  });
+
+  test("read/write round-trip", async () => {
+    const dir = await tempDir();
+    expect(await readDevMode(dir)).toBeNull();
+    await writeDevMode(dir, "docker");
+    expect(await readDevMode(dir)).toBe("docker");
+  });
+
+  test("shouldAskDevMode: TTY + unset → ask; non-TTY → never", () => {
+    expect(shouldAskDevMode({ saved: null, explicit: false, stdinIsTTY: true })).toBe(true);
+    expect(shouldAskDevMode({ saved: null, explicit: false, stdinIsTTY: false })).toBe(false);
+    expect(shouldAskDevMode({ saved: null, explicit: false, stdinIsTTY: undefined })).toBe(false);
+    expect(shouldAskDevMode({ saved: "local", explicit: false, stdinIsTTY: true })).toBe(false);
+    expect(shouldAskDevMode({ saved: null, explicit: true, stdinIsTTY: true })).toBe(false);
+  });
+});

package/src/cli/dev-mode.ts

@@ -0,0 +1,78 @@
+/**
+ * Persisted `oke dev` run mode — `local` vs `docker`.
+ */
+
+import { mkdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+/** Saved / selectable `oke dev` infrastructure mode. */
+export type DevMode = "local" | "docker";
+
+/** Relative path under the project root. */
+export const DEV_MODE_RELATIVE_PATH = ".oke/mode";
+
+/**
+ * Absolute path to the mode preference file.
+ *
+ * @param cwd - Project root
+ */
+export function devModePath(cwd: string): string {
+  return resolve(cwd, DEV_MODE_RELATIVE_PATH);
+}
+
+/**
+ * Parse a raw mode string.
+ *
+ * @param raw - File contents or CLI arg
+ */
+export function parseDevMode(raw: string | undefined | null): DevMode | null {
+  if (raw === undefined || raw === null) return null;
+  const value = raw.trim().toLowerCase();
+  if (value === "local" || value === "docker") return value;
+  return null;
+}
+
+/**
+ * Read the saved mode from `.oke/mode`, or `null` when unset / invalid.
+ *
+ * @param cwd - Project root
+ */
+export async function readDevMode(cwd: string): Promise<DevMode | null> {
+  const path = devModePath(cwd);
+  const file = Bun.file(path);
+  if (!(await file.exists())) return null;
+  try {
+    return parseDevMode(await file.text());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist the preferred mode for future `oke dev` invocations.
+ *
+ * @param cwd - Project root
+ * @param mode - Mode to save
+ */
+export async function writeDevMode(cwd: string, mode: DevMode): Promise<void> {
+  const path = devModePath(cwd);
+  await mkdir(join(cwd, ".oke"), { recursive: true });
+  await Bun.write(path, `${mode}\n`);
+}
+
+/**
+ * Whether `oke dev` should open the one-time mode prompt.
+ *
+ * Mirrors create-oke: never prompt when stdin is not a TTY.
+ *
+ * @param options - Preference + TTY + explicit flag
+ */
+export function shouldAskDevMode(options: {
+  readonly saved: DevMode | null;
+  readonly explicit: boolean;
+  readonly stdinIsTTY: boolean | undefined;
+}): boolean {
+  if (options.explicit) return false;
+  if (options.saved !== null) return false;
+  return Boolean(options.stdinIsTTY);
+}