okengine 0.2.6 → 0.3.2

package/src/cli/doc-staleness.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Gate: removed legacy stack-mode soft-compat stays gone.
+ *
+ * Mirrors {@link ../drivers/vault-driver-removal.test.ts} — `git grep` over the
+ * tracked tree must find zero hits (changelog history may still document the
+ * rename; upgrade codemods may still rewrite the old tokens).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+
+const ROOT = join(import.meta.dir, "../..");
+
+/** Forbidden CLI flag, split so this file does not match itself. */
+const FORBIDDEN_STACK_FLAG = ["--", "stack"].join("");
+/** Forbidden compose env filename. */
+const FORBIDDEN_ENV_STACK = [".env.", "stack"].join("");
+/** Forbidden env var — name avoids the contiguous token so this file is clean. */
+const FORBIDDEN_LEGACY_ENV = ["OKE_", "STACK"].join("");
+/** Forbidden vault helper. */
+const FORBIDDEN_FROM_STACK = ["from", "Stack"].join("");
+
+/**
+ * Run `git grep -F` and assert zero matches after ignoring allow-listed paths.
+ *
+ * @param pattern - Fixed-string pattern
+ * @param ignorePrefixes - Path prefixes to ignore (`path:line:` hits)
+ */
+function assertZeroGitGrep(pattern: string, ignorePrefixes: readonly string[] = []): void {
+  const proc = Bun.spawnSync(["git", "grep", "-F", "-n", "-e", pattern, "--"], {
+    cwd: ROOT,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  // git grep exits 1 when there are no matches.
+  if (proc.exitCode === 1) {
+    expect(proc.stdout.toString()).toBe("");
+    return;
+  }
+  const hits = proc.stdout
+    .toString()
+    .trim()
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .filter((line) => !ignorePrefixes.some((prefix) => line.startsWith(prefix)));
+  expect(hits.join("\n")).toBe("");
+}
+
+describe("legacy stack-mode removal gate", () => {
+  test("tracked tree has zero legacy docker-mode flag outside changelog", () => {
+    assertZeroGitGrep(FORBIDDEN_STACK_FLAG, ["changelog.md:"]);
+  });
+
+  test("tracked tree has zero legacy compose env filename outside changelog", () => {
+    assertZeroGitGrep(FORBIDDEN_ENV_STACK, ["changelog.md:"]);
+  });
+
+  test("tracked tree has zero legacy OKE env outside changelog", () => {
+    assertZeroGitGrep(FORBIDDEN_LEGACY_ENV, ["changelog.md:"]);
+  });
+
+  test("tracked tree has zero legacy vault helper outside changelog + upgrade", () => {
+    assertZeroGitGrep(FORBIDDEN_FROM_STACK, [
+      "changelog.md:",
+      "src/upgrade/codemods.ts:",
+      "src/upgrade/codemods.test.ts:",
+    ]);
+  });
+});

package/src/cli/docker-cli.test.ts

@@ -1,5 +1,5 @@
 /**
- * `oke docker` / `oke stack` / `oke images pin` / `oke schema` / `oke dev --stack`.
+ * `oke docker` / `oke stack` / `oke images pin` / `oke schema` / `oke dev --docker`.
  */
 
 import { describe, expect, test } from "bun:test";
@@ -39,12 +39,10 @@ describe("oke docker CLI", () => {
     expect(code).toBe(0);
     expect(result).toBeDefined();
     expect(await Bun.file(join(dir, "docker/Dockerfile")).exists()).toBe(true);
-    expect(
-      await Bun.file(join(dir, "docker/compose.store.sql.yml")).exists(),
-    ).toBe(true);
+    expect(await Bun.file(join(dir, "docker/compose.store.sql.yml")).exists()).toBe(true);
     const yml = await Bun.file(join(dir, "docker/compose.store.sql.yml")).text();
     expect(yml).not.toContain("test-password-not-in-yaml");
-    expect(yml).toContain("../.env.stack");
+    expect(yml).toContain(".env.docker");
     expect(logs.join("")).toContain("docker/compose.override.yml");
   });
 });
@@ -65,6 +63,26 @@ describe("oke stack", () => {
     expect(out).toContain("postgres");
     expect(await Bun.file(join(dir, "compose.yml")).exists()).toBe(false);
   });
+
+  test("uses per-project host ports (not raw recipe defaults)", async () => {
+    const { stackInstanceId, hostPortForInstance } = await import("../docker/index.ts");
+    const dir = await mkdtemp(join(tmpdir(), "oke-cli-stack-ports-"));
+    let out = "";
+    const code = await runStackPreview({
+      cwd: dir,
+      images: {
+        "channel.email": "axllent/mailpit:v1.22.3",
+      },
+      write: (t) => {
+        out += t;
+      },
+    });
+    expect(code).toBe(0);
+    const id = stackInstanceId(dir);
+    const smtp = hostPortForInstance("channel.email", 1025, id);
+    expect(out).toContain(`${smtp}:1025`);
+    expect(out).not.toContain("1025:1025");
+  });
 });
 
 describe("oke images pin", () => {
@@ -149,13 +167,14 @@ describe("oke schema generate", () => {
   });
 });
 
-describe("oke dev --stack", () => {
-  test("plans stack with postgres and writes nothing on dryRun", async () => {
+describe("oke dev --docker", () => {
+  test("plans docker with postgres and writes nothing on dryRun", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-cli-dev-dry-"));
     await Bun.write(join(dir, "src/app.ts"), "export {}\n");
     const { code, plan } = await runDev({
+      stdinIsTTY: false,
       cwd: dir,
-      stack: ["store.sql"],
+      docker: ["store.sql"],
       images,
       credentials,
       dryRun: true,

package/src/cli/docker.ts

@@ -88,14 +88,22 @@ export async function runDockerDerive(
       await writeDerivedFiles(result, outDir, { writeStackEnv: false });
     }
 
+    const vaultSpec = result.specs.find((s) => s.role === "vault");
+    if (vaultSpec) {
+      const rel = composeDir === "." ? ".oke/openbao/" : `${composeDir}/../.oke/openbao/`;
+      write(
+        `oke docker: OpenBao first boot — bring the stack up (e.g. \`oke dev -d\`), and oke ` +
+          `will initialize + unseal it once. Root/unseal material stays on the host at ${rel} ` +
+          `(0600, gitignored) — back it up; losing it loses every secret permanently.\n`,
+      );
+    }
+
     write(`oke docker: wrote ${result.files.length} file(s) → ${composeDir}/\n`);
     for (const f of result.files) write(`  ${composeDir}/${f.path}\n`);
     write(
       `compose merge order (cwd ${composeDir}/):\n${result.composeFiles.map((f) => `  -f ${f}`).join("\n")}\n`,
     );
-    write(
-      `(${composeDir}/compose.override.yml is layer 4 — user-owned, never written by oke)\n`,
-    );
+    write(`(${composeDir}/compose.override.yml is layer 4 — user-owned, never written by oke)\n`);
     return { code: 0, result };
   } catch (err) {
     console.error(err instanceof Error ? err.message : String(err));

package/src/cli/doctor-diff.test.ts

@@ -9,10 +9,7 @@ import type { Manifest } from "../manifest/types.ts";
 import { parseManifest } from "../manifest/validate.ts";
 import { runDoctorDiff } from "./doctor-diff.ts";
 
-const baseUrl = new URL(
-  "../manifest/fixtures/base.manifest.json",
-  import.meta.url,
-);
+const baseUrl = new URL("../manifest/fixtures/base.manifest.json", import.meta.url);
 
 async function loadBase(): Promise<Manifest> {
   return parseManifest(await Bun.file(baseUrl).text());
@@ -88,4 +85,3 @@ describe("oke doctor --diff", () => {
     }
   });
 });
-

package/src/cli/doctor-diff.ts

@@ -34,10 +34,7 @@ export interface DoctorDiffOptions {
    * @param cwd - Repo root
    * @param baseBranch - Preferred base
    */
-  readonly resolveMergeBase?: (
-    cwd: string,
-    baseBranch?: string,
-  ) => Promise<string | null>;
+  readonly resolveMergeBase?: (cwd: string, baseBranch?: string) => Promise<string | null>;
   /**
    * Read a file at a git revision (tests).
    *
@@ -45,11 +42,7 @@ export interface DoctorDiffOptions {
    * @param rev - Commit-ish
    * @param path - Path relative to repo root
    */
-  readonly readAtRevision?: (
-    cwd: string,
-    rev: string,
-    path: string,
-  ) => Promise<string | null>;
+  readonly readAtRevision?: (cwd: string, rev: string, path: string) => Promise<string | null>;
   /** Manifest relative path when using git (default: auto-detect). */
   readonly manifestPath?: string;
   readonly write?: (text: string) => void;
@@ -67,9 +60,7 @@ export interface DoctorDiffResult {
  *
  * @param options - Paths / injections / git helpers
  */
-export async function runDoctorDiff(
-  options: DoctorDiffOptions = {},
-): Promise<DoctorDiffResult> {
+export async function runDoctorDiff(options: DoctorDiffOptions = {}): Promise<DoctorDiffResult> {
   const write = options.write ?? ((t) => process.stdout.write(t));
   const cwd = options.cwd ?? process.cwd();
 
@@ -86,15 +77,11 @@ export async function runDoctorDiff(
     return { code: EXIT_OK, undeclared, allChanges: all };
   }
 
-  write(
-    `oke doctor --diff: ${undeclared.length} undeclared contract-breaking change(s)\n`,
-  );
+  write(`oke doctor --diff: ${undeclared.length} undeclared contract-breaking change(s)\n`);
   for (const c of undeclared) {
     write(`  [contract-breaking] ${c.path}: ${c.summary}\n`);
   }
-  write(
-    "Acknowledge intentional breaks with `breaking: true` on the owning flow.\n",
-  );
+  write("Acknowledge intentional breaks with `breaking: true` on the owning flow.\n");
   return { code: EXIT_RUNTIME, undeclared, allChanges: all };
 }
 
@@ -125,20 +112,16 @@ async function resolveManifests(
     );
   }
 
-  const rel =
-    options.manifestPath ??
-    (await detectManifestRel(cwd));
+  const rel = options.manifestPath ?? (await detectManifestRel(cwd));
   if (!rel) {
     throw new Error(
       "oke doctor --diff: no oke.manifest.json or manifest.oke.json in cwd — pass --before/--after",
     );
   }
 
-  const after =
-    options.after ?? (await loadManifest(resolve(cwd, rel)));
+  const after = options.after ?? (await loadManifest(resolve(cwd, rel)));
 
-  const resolveBase =
-    options.resolveMergeBase ?? gitMergeBase;
+  const resolveBase = options.resolveMergeBase ?? gitMergeBase;
   const readAt = options.readAtRevision ?? gitShow;
   const mergeBase = await resolveBase(cwd, options.baseBranch);
   if (!mergeBase) {
@@ -177,23 +160,18 @@ async function detectManifestRel(cwd: string): Promise<string | null> {
  * @param cwd - Repo root
  * @param baseBranch - Preferred base
  */
-export async function gitMergeBase(
-  cwd: string,
-  baseBranch?: string,
-): Promise<string | null> {
+export async function gitMergeBase(cwd: string, baseBranch?: string): Promise<string | null> {
   const candidates = baseBranch
     ? [baseBranch, ...BASE_BRANCH_CANDIDATES.filter((b) => b !== baseBranch)]
     : [...BASE_BRANCH_CANDIDATES];
 
   for (const base of candidates) {
-    const proc = Bun.spawn(
-      ["git", "merge-base", "HEAD", base],
-      { cwd, stdout: "pipe", stderr: "pipe" },
-    );
-    const [stdout, exitCode] = await Promise.all([
-      new Response(proc.stdout).text(),
-      proc.exited,
-    ]);
+    const proc = Bun.spawn(["git", "merge-base", "HEAD", base], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
     if (exitCode === 0) {
       const rev = stdout.trim();
       if (rev.length > 0) return rev;
@@ -209,20 +187,13 @@ export async function gitMergeBase(
  * @param rev - Commit-ish
  * @param path - Path relative to repo root
  */
-export async function gitShow(
-  cwd: string,
-  rev: string,
-  path: string,
-): Promise<string | null> {
+export async function gitShow(cwd: string, rev: string, path: string): Promise<string | null> {
   const proc = Bun.spawn(["git", "show", `${rev}:${path}`], {
     cwd,
     stdout: "pipe",
     stderr: "pipe",
   });
-  const [stdout, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    proc.exited,
-  ]);
+  const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
   if (exitCode !== 0) return null;
   return stdout;
 }

package/src/cli/doctor-pii.ts

@@ -4,10 +4,7 @@
  * Reuses {@link assertAllowPiiForAsk} — does not reimplement matching.
  */
 
-import {
-  AiPiiBuildError,
-  assertAllowPiiForAsk,
-} from "../elements/ai/pii.ts";
+import { AiPiiBuildError, assertAllowPiiForAsk } from "../elements/ai/pii.ts";
 import type {
   AiPrompt,
   ClassificationValue,
@@ -23,9 +20,7 @@ import type { DoctorFinding } from "./doctor.ts";
  *
  * @param manifest - Extracted Manifest
  */
-export function checkManifestPiiAsks(
-  manifest: Manifest,
-): readonly DoctorFinding[] {
+export function checkManifestPiiAsks(manifest: Manifest): readonly DoctorFinding[] {
   const findings: DoctorFinding[] = [];
   const classifications = collectClassifications(manifest);
   const flows = manifest.flows ?? {};

package/src/cli/doctor.test.ts

@@ -14,13 +14,12 @@ describe("oke doctor", () => {
       ports: [],
       currentSchemaFingerprint: null,
       expectedSchemaFingerprint: undefined,
+      skipDbDrift: true,
       write: () => {},
     });
     expect(code).toBe(2);
     expect(findings.some((f) => f.code === "missing_secret")).toBe(true);
-    expect(
-      findings.find((f) => f.message.includes("STRIPE_KEY")),
-    ).toBeDefined();
+    expect(findings.find((f) => f.message.includes("STRIPE_KEY"))).toBeDefined();
   });
 
   test("catches a port conflict", async () => {
@@ -30,6 +29,7 @@ describe("oke doctor", () => {
       isPortInUse: async (p) => p === 6530,
       currentSchemaFingerprint: "abc",
       expectedSchemaFingerprint: "abc",
+      skipDbDrift: true,
       write: () => {},
     });
     expect(code).toBe(2);
@@ -37,17 +37,36 @@ describe("oke doctor", () => {
     expect(findings[0]!.message).toContain("6530");
   });
 
-  test("catches schema drift", async () => {
+  test("catches core stub schema drift", async () => {
     const { code, findings } = await runDoctor({
       secrets: [],
       ports: [],
       isPortInUse: async () => false,
       expectedSchemaFingerprint: "aaa",
       currentSchemaFingerprint: "bbb",
+      skipDbDrift: true,
       write: () => {},
     });
     expect(code).toBe(2);
     expect(findings.some((f) => f.code === "schema_drift")).toBe(true);
+    expect(findings.find((f) => f.code === "schema_drift")?.message).toContain(
+      "oke schema generate",
+    );
+  });
+
+  test("catches domain db_drift from drizzle-kit probe", async () => {
+    const { code, findings } = await runDoctor({
+      secrets: [],
+      ports: [],
+      isPortInUse: async () => false,
+      currentSchemaFingerprint: null,
+      skipDbDrift: false,
+      detectDbDrift: async () => ({ drifted: true, detail: "pending migrations" }),
+      write: () => {},
+    });
+    expect(code).toBe(2);
+    expect(findings.some((f) => f.code === "db_drift")).toBe(true);
+    expect(findings.find((f) => f.code === "db_drift")?.message).toContain("pending");
   });
 
   test("ok when secrets present, ports free, schema matches", async () => {
@@ -58,6 +77,7 @@ describe("oke doctor", () => {
       isPortInUse: async () => false,
       expectedSchemaFingerprint: "same",
       currentSchemaFingerprint: "same",
+      skipDbDrift: true,
       write: () => {},
     });
     expect(code).toBe(0);
@@ -99,6 +119,7 @@ describe("oke doctor", () => {
       secrets: [],
       ports: [],
       currentSchemaFingerprint: null,
+      skipDbDrift: true,
       write: () => {},
     });
 
@@ -142,6 +163,7 @@ describe("oke doctor", () => {
       ports: [],
       expectedSchemaFingerprint: "same",
       currentSchemaFingerprint: "same",
+      skipDbDrift: true,
       write: () => {},
     });
     expect(code).toBe(0);

package/src/cli/doctor.ts

@@ -20,6 +20,7 @@ export interface DoctorFinding {
     | "missing_secret"
     | "port_conflict"
     | "schema_drift"
+    | "db_drift"
     | "tenancy"
     | "driver"
     | "pii_ask";
@@ -44,6 +45,16 @@ export interface DoctorOptions {
   readonly expectedSchemaFingerprint?: string;
   /** Current schema fingerprint (tests). */
   readonly currentSchemaFingerprint?: string | null;
+  /**
+   * Inject domain DB drift probe (tests). When unset, runs drizzle-kit
+   * push explain when `drizzle.config.ts` exists.
+   */
+  readonly detectDbDrift?: () => Promise<{
+    readonly drifted: boolean;
+    readonly detail?: string;
+  }>;
+  /** Skip live DB drift probe (default false). */
+  readonly skipDbDrift?: boolean;
   readonly write?: (text: string) => void;
   /** Write hints / progress (defaults to stderr). */
   readonly writeErr?: (text: string) => void;
@@ -79,9 +90,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
   }
 
   const env = options.env ?? ((k) => Bun.env[k] ?? process.env[k]);
-  const secretNames =
-    options.secrets ??
-    (manifest?.vault ? Object.keys(manifest.vault) : []);
+  const secretNames = options.secrets ?? (manifest?.vault ? Object.keys(manifest.vault) : []);
 
   for (const name of secretNames) {
     const value = env(name);
@@ -90,9 +99,7 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
       findings.push({
         code: "missing_secret",
         severity: "error",
-        message: description
-          ? `missing secret ${name}: ${description}`
-          : `missing secret ${name}`,
+        message: description ? `missing secret ${name}: ${description}` : `missing secret ${name}`,
       });
     }
   }
@@ -120,24 +127,42 @@ export async function runDoctor(options: DoctorOptions = {}): Promise<{
     options.currentSchemaFingerprint !== undefined
   ) {
     const expected =
-      options.expectedSchemaFingerprint ??
-      (await schemaFingerprint(cwd).catch(() => null));
+      options.expectedSchemaFingerprint ?? (await schemaFingerprint(cwd).catch(() => null));
     if (expected !== null && current !== null && expected !== current) {
       findings.push({
         code: "schema_drift",
         severity: "error",
         message:
-          "schema drift detected — run `oke schema generate` (or --check in CI)",
+          "core stub schema drift — run `oke schema generate` (schema/oke.ts; not domain migrations)",
       });
     } else if (expected !== null && current === null) {
       findings.push({
         code: "schema_drift",
         severity: "error",
-        message: "schema/oke.ts missing — run `oke schema generate`",
+        message: "schema/oke.ts missing — run `oke schema generate` (core/plugin stubs)",
       });
     }
   }
 
+  // Domain schema ↔ live DB — drizzle-kit is the single source of truth.
+  if (!options.skipDbDrift) {
+    const drizzleConfig = Bun.file(resolve(cwd, "drizzle.config.ts"));
+    if (options.detectDbDrift || (await drizzleConfig.exists())) {
+      const { detectDbDrift } = await import("./db.ts");
+      const probe = options.detectDbDrift ?? (() => detectDbDrift({ cwd }));
+      const drift = await probe();
+      if (drift.drifted) {
+        findings.push({
+          code: "db_drift",
+          severity: "error",
+          message:
+            drift.detail ??
+            "domain schema differs from the database — run `oke db generate` then `oke db migrate` (or `oke db push` in local)",
+        });
+      }
+    }
+  }
+
   if (manifest?.tenancy?.isolation) {
     // Structural tenancy check is compile-time; doctor warns when isolation
     // is set but no tenant resolver string is recorded on the Manifest.
@@ -205,4 +230,3 @@ Verify secrets, ports, schema drift, and PII→model egress before serving.
   const { code } = await runDoctor({ manifestPath, json });
   return code;
 }
-

package/src/cli/drizzle-env.test.ts

@@ -0,0 +1,67 @@
+/**
+ * drizzle-kit env resolution — dialect from configured driver, not URL sniffing.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { OkeConfig } from "../config/index.ts";
+import { resolveDrizzleKitEnv } from "./drizzle-env.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-drizzle-env-"));
+  dirs.push(dir);
+  return dir;
+}
+
+const dualConfig = {
+  drivers: {
+    store: {
+      sql: { local: "sqlite", docker: "postgres", prod: "postgres", test: "memory" },
+    },
+  },
+} as unknown as OkeConfig;
+
+describe("resolveDrizzleKitEnv", () => {
+  test("local env → sqlite dialect + sqlite url", async () => {
+    const dir = await tempDir();
+    const ctx = await resolveDrizzleKitEnv(dir, dualConfig, "local");
+    expect(ctx.dialect).toBe("sqlite");
+    expect(ctx.overlay.OKE_DRIZZLE_DIALECT).toBe("sqlite");
+    expect(ctx.overlay.OKE_SQLITE_URL).toContain(".oke/app.sqlite");
+    expect(ctx.overlay.DATABASE_URL).toBeUndefined();
+  });
+
+  test("docker env → postgresql dialect + DATABASE_URL from compose env", async () => {
+    const dir = await tempDir();
+    await mkdir(join(dir, "docker"), { recursive: true });
+    await writeFile(
+      join(dir, "docker", ".env.docker"),
+      "DATABASE_URL=postgres://u:p@127.0.0.1:5432/oke\n",
+    );
+    const ctx = await resolveDrizzleKitEnv(dir, dualConfig, "docker");
+    expect(ctx.dialect).toBe("postgresql");
+    expect(ctx.overlay.OKE_DRIZZLE_DIALECT).toBe("postgresql");
+    expect(ctx.overlay.DATABASE_URL).toBe("postgres://u:p@127.0.0.1:5432/oke");
+    expect(ctx.overlay.OKE_SQLITE_URL).toBeUndefined();
+  });
+
+  test("docker dialect is postgresql even when DATABASE_URL unset (no URL guessing)", async () => {
+    const dir = await tempDir();
+    const ctx = await resolveDrizzleKitEnv(dir, dualConfig, "docker");
+    expect(ctx.dialect).toBe("postgresql");
+  });
+
+  test("unsupported driver id errors clearly", async () => {
+    const dir = await tempDir();
+    const bad = { drivers: { store: { sql: { local: "memory" } } } } as unknown as OkeConfig;
+    await expect(resolveDrizzleKitEnv(dir, bad, "local")).rejects.toThrow(/not supported/);
+  });
+});

package/src/cli/drizzle-env.ts

@@ -0,0 +1,78 @@
+/**
+ * drizzle-kit child-env overlay — resolved from the configured `store.sql`
+ * driver for the active env (never guessed from `DATABASE_URL` presence).
+ */
+
+import { resolveDriverId, type ConfigEnv, type OkeConfig } from "../config/index.ts";
+import {
+  drizzleDialectFromSqlDriver,
+  type OkeDrizzleKitDialect,
+} from "../drivers/drizzle-dialect.ts";
+import { parseDotenv } from "../drivers/vault-dotenv-parse.ts";
+import { resolveComposeEnvPath } from "../elements/vault/chain.ts";
+
+/** Resolved drizzle env context for one project env. */
+export interface DrizzleKitEnvContext {
+  /** Active env used for driver resolution. */
+  readonly env: ConfigEnv;
+  /** drizzle-kit dialect (from `SQL_DRIVER_TO_DRIZZLE_DIALECT`). */
+  readonly dialect: OkeDrizzleKitDialect;
+  /** Env overlay for the drizzle-kit child process. */
+  readonly overlay: Record<string, string>;
+}
+
+/**
+ * Load `docker/.env.docker` (or legacy `.env.docker`) as a name→value map.
+ *
+ * @param cwd - Project root
+ */
+async function readComposeEnv(cwd: string): Promise<Map<string, string>> {
+  const { path } = resolveComposeEnvPath(cwd);
+  const file = Bun.file(path);
+  if (!(await file.exists())) return new Map();
+  try {
+    return parseDotenv(await file.text());
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Resolve the drizzle-kit env context for a project + env.
+ *
+ * Dialect comes from the configured driver via the exhaustive
+ * `SQL_DRIVER_TO_DRIZZLE_DIALECT` map — a missing/unsupported driver id is a
+ * compile-time gap there, and a clear runtime error here (never a silent
+ * sqlite fallback).
+ *
+ * @param cwd - Project root
+ * @param config - Loaded `oke.config.ts` (null → sqlite/local defaults)
+ * @param env - Active env (`local` | `docker` for dev tooling)
+ */
+export async function resolveDrizzleKitEnv(
+  cwd: string,
+  config: OkeConfig | null | undefined,
+  env: ConfigEnv,
+): Promise<DrizzleKitEnvContext> {
+  const driverId = resolveDriverId(config?.drivers?.store?.sql, env) ?? "sqlite";
+  if (driverId !== "sqlite" && driverId !== "postgres") {
+    throw new Error(
+      `oke db: store.sql driver "${driverId}" is not supported by drizzle-kit (sqlite | postgres)`,
+    );
+  }
+  const dialect = drizzleDialectFromSqlDriver(driverId);
+
+  const compose = env === "docker" ? await readComposeEnv(cwd) : new Map<string, string>();
+
+  const overlay: Record<string, string> = { OKE_DRIZZLE_DIALECT: dialect };
+  if (dialect === "postgresql") {
+    const url =
+      process.env.DATABASE_URL ?? compose.get("DATABASE_URL") ?? compose.get("OKE_STORE_SQL_URL");
+    if (url !== undefined) overlay.DATABASE_URL = url;
+  } else {
+    const url =
+      process.env.OKE_SQLITE_URL ?? compose.get("OKE_SQLITE_URL") ?? "file:.oke/app.sqlite";
+    overlay.OKE_SQLITE_URL = url;
+  }
+  return { env, dialect, overlay };
+}