okengine 0.2.8 → 0.3.4

package/src/cli/dev.ts

@@ -13,7 +13,9 @@ import type { ConsoleState } from "../console/server/state.ts";
 import {
   DEFAULT_DOCKER_DIR,
   deriveInfrastructure,
+  loadExistingStackControls,
   loadExistingStackCredentials,
+  resolveExtraPorts,
   stackAppSlug,
   stackInstanceId,
   writeDerivedFiles,
@@ -21,7 +23,7 @@ import {
 } from "../docker/index.ts";
 import type { Manifest } from "../manifest/types.ts";
 import type { McpContext } from "../mcp/tools.ts";
-import { APP_PORT, CONSOLE_PORT, MCP_PORT } from "../runtime/types.ts";
+import { APP_PORT, CONSOLE_PORT, DOCS_MCP_PORT, MCP_PORT } from "../runtime/types.ts";
 import {
   formatDevBanner,
   formatDevLogSeparator,
@@ -90,6 +92,12 @@ export interface DevServeMcpOptions {
   readonly hostname?: string;
 }
 
+/** Options for {@link DevOptions.serveDocsMcp}. */
+export interface DevServeDocsMcpOptions {
+  readonly port: number;
+  readonly hostname?: string;
+}
+
 /** Live `oke dev` session — returned when {@link DevOptions.keepAlive} is false. */
 export interface DevSession {
   readonly plan: DevPlan;
@@ -99,6 +107,10 @@ export interface DevSession {
   readonly consolePort: number;
   readonly mcpPort: number;
   readonly mcpUrl: URL | null;
+  /** Docs MCP listen port (read-only, unauthenticated). */
+  readonly docsMcpPort: number;
+  /** Docs MCP base URL — null when the surface was skipped. */
+  readonly docsMcpUrl: URL | null;
   /** Shared with Console — mint `oke-mcp` tokens against this store/secret. */
   readonly secret: string | null;
   readonly sessions: SessionStore | null;
@@ -106,6 +118,13 @@ export interface DevSession {
   readonly consoleState: ConsoleState | null;
 }
 
+/** Minimal filesystem watcher contract, injectable for deterministic tests. */
+export type DevWatchFn = (
+  path: string,
+  options: { readonly recursive: true },
+  listener: (event: "rename" | "change", filename: string | null) => void,
+) => { close(): void };
+
 /** Options for {@link runDev}. */
 export interface DevOptions {
   readonly cwd?: string;
@@ -134,6 +153,8 @@ export interface DevOptions {
    * @param filename - Relative path from the watcher
    */
   readonly onDbAutoPush?: (filename: string) => void;
+  /** Watch project source changes (injectable for tests). */
+  readonly watchFs?: DevWatchFn;
   readonly images?: Readonly<Record<string, string>>;
   readonly credentials?: DeriveOptions["credentials"];
   readonly write?: (text: string) => void;
@@ -156,6 +177,7 @@ export interface DevOptions {
   readonly appPort?: number;
   readonly consolePort?: number;
   readonly mcpPort?: number;
+  readonly docsMcpPort?: number;
   /**
    * Boot compose (injectable).
    *
@@ -176,6 +198,12 @@ export interface DevOptions {
    * Default: {@link serveMcp} on :6535.
    */
   readonly serveMcp?: (options: DevServeMcpOptions) => Promise<DevMcpHandle>;
+  /**
+   * Serve the read-only docs MCP (injectable).
+   * Default: {@link serveDocsMcp} on :6536. Boot failure skips the surface —
+   * docs search must never take `oke dev` down.
+   */
+  readonly serveDocsMcp?: (options: DevServeDocsMcpOptions) => Promise<DevMcpHandle>;
   /**
    * Boot + serve the app entry (injectable).
    * Default: spawn `bun --hot` on the shipped {@link ./dev-app-runner.ts}
@@ -199,6 +227,7 @@ export interface DevPlan {
   readonly appPort: number;
   readonly consolePort: number;
   readonly mcpPort: number;
+  readonly docsMcpPort: number;
   readonly stackRoles: readonly string[] | null;
   readonly composeFiles: readonly string[] | null;
   readonly stackEnv: Readonly<Record<string, string>> | null;
@@ -223,24 +252,29 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   const preferredApp = options.appPort ?? Number(Bun.env.PORT ?? APP_PORT);
   const preferredConsole = options.consolePort ?? CONSOLE_PORT;
   const preferredMcp = options.mcpPort ?? MCP_PORT;
+  const preferredDocsMcp = options.docsMcpPort ?? DOCS_MCP_PORT;
   // Explicit overrides (incl. `0` ephemeral) skip probing; otherwise +1 until free.
   const ports =
     options.appPort !== undefined ||
     options.consolePort !== undefined ||
-    options.mcpPort !== undefined
+    options.mcpPort !== undefined ||
+    options.docsMcpPort !== undefined
       ? {
           app: preferredApp,
           console: preferredConsole,
           mcp: preferredMcp,
+          docsMcp: preferredDocsMcp,
         }
       : await resolveDevPorts({
           app: preferredApp,
           console: preferredConsole,
           mcp: preferredMcp,
+          docsMcp: preferredDocsMcp,
         });
   const appPort = ports.app;
   const consolePort = ports.console;
   const mcpPort = ports.mcp;
+  const docsMcpPort = ports.docsMcp;
   const keepAlive = options.keepAlive ?? true;
 
   let entry = options.entry;
@@ -344,6 +378,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     const appSlug = stackAppSlug(cwd);
     const reusedCreds =
       options.credentials ?? (await loadExistingStackCredentials(cwd, stackRoles));
+    const controls = await loadExistingStackControls(cwd);
     const derived = deriveInfrastructure({
       images,
       app: appSlug,
@@ -352,6 +387,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       composeDir,
       instanceId,
       ...(reusedCreds ? { credentials: reusedCreds } : {}),
+      ...(controls ? { controls } : {}),
       host: "127.0.0.1",
     });
     // Layer 4 is user-owned — include only if the file already exists.
@@ -383,6 +419,27 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           });
         // Compose files live under docker/; cwd for compose is that directory.
         await up(composeFiles, dockerOut);
+
+        // Real OpenBao vault: init once / unseal every start, then expose the
+        // least-privilege app token to the app + Console (never root).
+        const vaultSpec = derived.specs.find((s) => s.role === "vault");
+        if (vaultSpec) {
+          const { ensureOpenBao, openbaoStackEnv } = await import("./openbao-bootstrap.ts");
+          const vaultNames = await tryLoadVaultSecretNames(cwd);
+          const boot = await ensureOpenBao({
+            cwd,
+            url: `http://127.0.0.1:${vaultSpec.hostPort}`,
+            names: vaultNames,
+          });
+          Object.assign(stackEnv!, openbaoStackEnv(boot));
+          const envPath = resolve(dockerOut, ".env.docker");
+          const current = await Bun.file(envPath).text();
+          const tokenLine = `OKE_VAULT_TOKEN=${boot.appToken}`;
+          const next = /OKE_VAULT_TOKEN=.*/.test(current)
+            ? current.replace(/OKE_VAULT_TOKEN=.*/, tokenLine)
+            : `${current.trimEnd()}\nOKE_VAULT_TOKEN=${boot.appToken}\nOKE_VAULT_MOUNT=secret\n`;
+          await Bun.write(envPath, next);
+        }
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(msg);
@@ -392,8 +449,15 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       const roleLabel = (role: string): string => {
         if (role === "store.sql") return "postgres";
         if (role === "store.kv") return "redis";
+        if (role === "store.files") return "files";
+        if (role === "channel.email") return "mail";
         return role;
       };
+      const extraLabel = (role: string, containerPort: number): string => {
+        if (role === "channel.email" && containerPort === 8025) return "mail-ui";
+        if (role === "store.files" && containerPort === 9001) return "files-ui";
+        return `${roleLabel(role)}+${containerPort}`;
+      };
       const appDrivers = [
         ...(stackRoles.includes("store.sql") ? [stackSqlDriver] : []),
         ...(stackRoles.includes("store.kv") ? [stackKvDriver] : []),
@@ -401,10 +465,13 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       write(
         formatStackSummary({
           project: `oke-${appSlug}`,
-          services: derived.specs.map((spec) => ({
-            label: roleLabel(spec.role),
-            hostPort: spec.hostPort,
-          })),
+          services: derived.specs.flatMap((spec) => [
+            { label: roleLabel(spec.role), hostPort: spec.hostPort },
+            ...resolveExtraPorts(spec, { images, instanceId }).map((p) => ({
+              label: extraLabel(spec.role, p.containerPort),
+              hostPort: p.hostPort,
+            })),
+          ]),
           appDrivers,
         }),
       );
@@ -416,6 +483,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     appPort,
     consolePort,
     mcpPort,
+    docsMcpPort,
     stackRoles,
     composeFiles,
     stackEnv,
@@ -452,6 +520,28 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
 
   if (options.dryRun) return { code: 0, plan };
 
+  // One-shot schema sync for the session profile (both local and docker):
+  // emits schema.generated.ts for the active dialect, then pushes via
+  // drizzle-kit. Data planes stay isolated — session flags never rewrite
+  // `.oke/mode`. Watch auto-push below remains local-only.
+  if (!options.noDbPush) {
+    const { syncDevSchema } = await import("./dev-schema-sync.ts");
+    try {
+      const result = await syncDevSchema(cwd, mode, { write });
+      write(
+        formatStatusLine(
+          `oke db push (${mode} · ${result.dialect}) ${result.code === 0 ? "ok" : "failed"}`,
+        ),
+      );
+    } catch (err) {
+      write(
+        formatStatusLine(
+          `oke db push (${mode}) skipped — ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      );
+    }
+  }
+
   const autoPushEnabled = resolveDevAutoPush({
     noDbPush: options.noDbPush,
     docker: Boolean(stackEnv),
@@ -542,6 +632,24 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       };
     });
 
+  const serveDocsMcpSurface =
+    options.serveDocsMcp ??
+    (async (docsOptions) => {
+      const { serveDocsMcp } = await import("../mcp/docs-server.ts");
+      const server = await serveDocsMcp({
+        port: docsOptions.port,
+        hostname: docsOptions.hostname ?? "127.0.0.1",
+      });
+      write(formatServiceLine("Docs MCP", `http://127.0.0.1:${server.port}`));
+      return {
+        port: server.port,
+        url: server.url,
+        stop() {
+          server.stop(true);
+        },
+      };
+    });
+
   const regen =
     options.regenClient ??
     (async (appUrl) => {
@@ -581,8 +689,21 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     });
   }
 
+  // Docs MCP is independent of Console state — read-only, no sessions/secret.
+  // Boot failure (missing docs content, busy port) skips it, never kills dev.
+  let docsMcpServer: DevMcpHandle | null = null;
+  try {
+    docsMcpServer = await serveDocsMcpSurface({ port: docsMcpPort, hostname: "127.0.0.1" });
+  } catch (err) {
+    write(
+      formatStatusLine(`Docs MCP skipped — ${err instanceof Error ? err.message : String(err)}`),
+    );
+  }
+
   const boundMcpPort = mcpServer?.port ?? mcpPort;
   const mcpUrl = mcpServer?.url ?? null;
+  const boundDocsMcpPort = docsMcpServer?.port ?? docsMcpPort;
+  const docsMcpUrl = docsMcpServer?.url ?? null;
 
   const appUrl = app.url?.origin ?? `http://127.0.0.1:${boundAppPort}`;
   await regen(appUrl);
@@ -591,7 +712,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     options.dbPush ??
     (async (projectCwd: string) => {
       const configPath = await resolveDrizzleConfigPath(projectCwd);
-      return runPush(configPath, (t) => write(t));
+      return runPush(configPath, (t) => write(t), { cwd: projectCwd, env: mode });
     });
 
   let lastSchemaFilename = "";
@@ -614,7 +735,9 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
 
   write(formatDevLogSeparator());
 
-  const watcher = watch(resolve(cwd, "src"), { recursive: true }, (_event, filename) => {
+  const watchFs: DevWatchFn =
+    options.watchFs ?? ((path, watchOptions, listener) => watch(path, watchOptions, listener));
+  const watcher = watchFs(resolve(cwd, "src"), { recursive: true }, (_event, filename) => {
     void regen(appUrl);
     // Only live-extract when the host did not pin a Manifest (tests).
     if (options.manifest === undefined) {
@@ -635,6 +758,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     app.stop();
     consoleServer.stop();
     mcpServer?.stop();
+    docsMcpServer?.stop();
     process.off("SIGINT", onSignal);
     process.off("SIGTERM", onSignal);
   };
@@ -652,12 +776,15 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
       appPort: boundAppPort,
       consolePort: boundConsolePort,
       mcpPort: boundMcpPort,
+      docsMcpPort: boundDocsMcpPort,
     },
     stop,
     appPort: boundAppPort,
     consolePort: boundConsolePort,
     mcpPort: boundMcpPort,
     mcpUrl,
+    docsMcpPort: boundDocsMcpPort,
+    docsMcpUrl,
     secret,
     sessions,
     consoleState,
@@ -674,6 +801,21 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   return { code: 0, plan: session.plan, session };
 }
 
+/**
+ * Declared vault secret names from the project Manifest (policy scope).
+ *
+ * @param cwd - Project root
+ */
+async function tryLoadVaultSecretNames(cwd: string): Promise<readonly string[]> {
+  try {
+    const { extractManifest } = await import("../compiler/extract.ts");
+    const manifest = await extractManifest({ rootDir: cwd });
+    return Object.keys(manifest.vault ?? {});
+  } catch {
+    return [];
+  }
+}
+
 /**
  * True when a Manifest has no declared flows (scaffold / empty extract).
  *

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

@@ -48,20 +48,20 @@ function assertZeroGitGrep(pattern: string, ignorePrefixes: readonly string[] =
 
 describe("legacy stack-mode removal gate", () => {
   test("tracked tree has zero legacy docker-mode flag outside changelog", () => {
-    assertZeroGitGrep(FORBIDDEN_STACK_FLAG, ["docs/changelog.md:"]);
+    assertZeroGitGrep(FORBIDDEN_STACK_FLAG, ["changelog.md:"]);
   });
 
   test("tracked tree has zero legacy compose env filename outside changelog", () => {
-    assertZeroGitGrep(FORBIDDEN_ENV_STACK, ["docs/changelog.md:"]);
+    assertZeroGitGrep(FORBIDDEN_ENV_STACK, ["changelog.md:"]);
   });
 
   test("tracked tree has zero legacy OKE env outside changelog", () => {
-    assertZeroGitGrep(FORBIDDEN_LEGACY_ENV, ["docs/changelog.md:"]);
+    assertZeroGitGrep(FORBIDDEN_LEGACY_ENV, ["changelog.md:"]);
   });
 
   test("tracked tree has zero legacy vault helper outside changelog + upgrade", () => {
     assertZeroGitGrep(FORBIDDEN_FROM_STACK, [
-      "docs/changelog.md:",
+      "changelog.md:",
       "src/upgrade/codemods.ts:",
       "src/upgrade/codemods.test.ts:",
     ]);

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

@@ -63,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", () => {

package/src/cli/docker.ts

@@ -88,6 +88,16 @@ 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(

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 };
+}

package/src/cli/ensure-drizzle-config.ts

@@ -0,0 +1,50 @@
+/**
+ * Ensure a mode-aware `drizzle.config.ts` exists — created when absent,
+ * never overwritten when the user customised it.
+ */
+
+import { resolve } from "node:path";
+
+/** Mode-aware template (matches `packages/create-oke/template/drizzle.config.ts`). */
+const DRIZZLE_CONFIG_TEMPLATE = `import { defineConfig } from "drizzle-kit";
+
+/**
+ * Domain schema sync for \`oke db push|generate|migrate\`.
+ *
+ * Dialect comes from OKE's \`store.sql\` driver map (resolved by the CLI and
+ * injected as \`OKE_DRIZZLE_DIALECT\`) — never inferred from \`DATABASE_URL\`
+ * presence. \`src/schema.generated.ts\` is emitted from \`src/schema.decl.ts\`
+ * for the active dialect as a pre-step of \`oke db\` / \`oke dev\`.
+ *
+ * Versioned prod migrations land in \`./drizzle\` — never mix with \`.oke/\`.
+ */
+const dialect = (process.env.OKE_DRIZZLE_DIALECT ?? "sqlite") as "sqlite" | "postgresql";
+
+export default defineConfig({
+  dialect,
+  schema: "./src/schema.generated.ts",
+  out: "./drizzle",
+  dbCredentials: {
+    url:
+      dialect === "postgresql"
+        ? (process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL!)
+        : (process.env.OKE_SQLITE_URL ?? "file:.oke/app.sqlite"),
+  },
+});
+`;
+
+/**
+ * Create `drizzle.config.ts` at the project root when it does not exist.
+ * Returns the absolute path and whether it was created.
+ *
+ * @param cwd - Project root
+ */
+export async function ensureDrizzleConfig(
+  cwd: string,
+): Promise<{ readonly path: string; readonly created: boolean }> {
+  const path = resolve(cwd, "drizzle.config.ts");
+  const file = Bun.file(path);
+  if (await file.exists()) return { path, created: false };
+  await Bun.write(path, DRIZZLE_CONFIG_TEMPLATE);
+  return { path, created: true };
+}

package/src/cli/hero-meta.test.ts

@@ -20,7 +20,7 @@ const SAMPLE: OkeConfig = {
     },
     signal: { local: "memory", docker: "postgres", prod: "postgres" },
     clock: { local: "memory", docker: "postgres", prod: "postgres" },
-    vault: { local: "dotenv", docker: "dotenv", prod: "sops" },
+    vault: { local: "dotenv", docker: "openbao", prod: "openbao" },
     channel: {
       email: { local: "console", docker: "smtp", prod: "smtp" },
     },

package/src/cli/load-config.ts

@@ -10,6 +10,7 @@ import type { Manifest } from "../manifest/types.ts";
 const DEFAULT_SQL_IMAGE = "postgres:18-alpine";
 const DEFAULT_PGVECTOR_IMAGE = "pgvector/pgvector:pg17";
 const DEFAULT_KV_IMAGE = "redis:8-alpine";
+const DEFAULT_VAULT_IMAGE = "openbao/openbao:2.6.1";
 
 /**
  * Extract protocol id from a driver ref.
@@ -66,6 +67,11 @@ export function defaultImagesFromConfig(config: OkeConfig): Readonly<Record<stri
     out["store.kv"] = DEFAULT_KV_IMAGE;
   }
 
+  const vault = dockerOrProdId(config.drivers?.vault);
+  if (vault === "openbao") {
+    out.vault = DEFAULT_VAULT_IMAGE;
+  }
+
   return out;
 }