okengine 0.14.1 → 0.16.0

package/src/cli/ai-setup/apply.ts

@@ -244,7 +244,9 @@ export function renderAiTs(input: AiSetupApplyInput): string {
 }
 
 /**
- * Write AI model declarations into `src/core.ts` (preferred) or legacy `src/core/ai.ts`.
+ * Write AI model declarations into `src/core/ai.ts` when that split exists
+ * (so a thin `src/core.ts` barrel stays a re-export), else `src/core.ts`,
+ * else legacy `src/core/index.ts` + sidecar.
  *
  * @param cwd - Project root
  * @param input - Setup choices
@@ -252,9 +254,25 @@ export function renderAiTs(input: AiSetupApplyInput): string {
  */
 function writeAiModels(cwd: string, input: AiSetupApplyInput): string {
   const rendered = renderAiTs(input);
+  const coreAiPath = join(cwd, "src", "core", "ai.ts");
   const coreTsPath = join(cwd, "src", "core.ts");
   const legacyIndex = join(cwd, "src", "core", "index.ts");
 
+  if (existsSync(coreAiPath)) {
+    const existing = readFileSync(coreAiPath, "utf8");
+    if (hasAiModels(existing)) {
+      const withPrompt = ensureSummarizeNotePrompt(existing);
+      if (withPrompt !== existing) {
+        writeFileSync(coreAiPath, withPrompt, "utf8");
+      }
+    } else {
+      writeFileSync(coreAiPath, mergeAiIntoCore(existing, rendered), "utf8");
+    }
+    ensureCoreBarrelExportsAi(cwd);
+    ensureCoreImported(cwd);
+    return coreAiPath;
+  }
+
   // Folder layout still in the wild — keep writing a sidecar.
   if (!existsSync(coreTsPath) && existsSync(legacyIndex)) {
     const aiTsPath = join(cwd, "src", "core", "ai.ts");
@@ -364,6 +382,19 @@ export function ensureNamedOkengineImport(source: string, name: string): string
   return source.replace(re, `import { ${sorted.join(", ")} } from "okengine";`);
 }
 
+/**
+ * Keep a `src/core.ts` barrel re-exporting `./core/ai.ts` after a split write.
+ *
+ * @param cwd - Project root
+ */
+function ensureCoreBarrelExportsAi(cwd: string): void {
+  const coreTsPath = join(cwd, "src", "core.ts");
+  if (!existsSync(coreTsPath)) return;
+  const src = readFileSync(coreTsPath, "utf8");
+  if (/from\s+["']\.\/core\/ai/.test(src)) return;
+  writeFileSync(coreTsPath, `${src.trimEnd()}\nexport * from "./core/ai.ts";\n`, "utf8");
+}
+
 /**
  * Ensure `src/app.ts` loads `@/core` / `./core` so merged AI registers.
  *

package/src/cli/attach-host-console.test.ts

@@ -28,7 +28,7 @@ describe("attachHostToConsole", () => {
 import { oke, on, flow, http, gate, store } from ${JSON.stringify(OKE)};
 const db = store.sql("db");
 export const ping = on(
-  http.get("/ping").gate.public,
+  http.get("/ping").public(),
   flow("main.ping", { do: () => ({ ok: true }) }),
 );
 export const app = oke({
@@ -69,6 +69,7 @@ export const app = oke({
     expect(ingested.some((row) => row.event?.flow === "main.ping")).toBe(true);
     await attached!.stop();
     expect(state.invokeUserFlow).toBeNull();
+    expect(state.storeRuntime).toBeNull();
   });
 
   test("binds host aiRuntime so Console projection sees a journaled ask", async () => {
@@ -81,7 +82,7 @@ import { oke, on, flow, http, gate, ai } from ${JSON.stringify(OKE)};
 const smart = ai.model("smart", { provider: "mock" });
 smart.prompt("ticket-triage", { version: 2 });
 export const ping = on(
-  http.get("/ping").gate.public,
+  http.get("/ping").public(),
   flow("main.ping", {
     effects: { asks: ["ticket-triage"] },
     do: (_input, fx) => fx.ask("ticket-triage", { subject: "hello" }),
@@ -122,6 +123,43 @@ export const app = oke({
     await attached!.stop();
   });
 
+  test("Console Access uses the host apiKeyStore instance (not Console SQL)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-attach-keys-"));
+    const entry = join(dir, "app.ts");
+    await writeFile(
+      entry,
+      `
+import { oke, on, flow, http, gate, store } from ${JSON.stringify(OKE)};
+const db = store.sql("db");
+const member = gate.policy("member", ({ auth }) => !!auth.verified);
+export const ping = on(
+  http.get("/ping").gate(member),
+  flow("main.ping", { do: () => ({ ok: true }) }),
+);
+export const app = oke({
+  name: "attach-keys",
+  stores: [db],
+  gate: {
+    auth: { secret: "attach-host-key-pepper", http: false },
+    policies: [member],
+  },
+}).adopt({ ping });
+`,
+    );
+
+    const consoleKeys = { keys: new Map(), persist: async () => {} };
+    const state = {
+      invokeUserFlow: null,
+      storeRuntime: null,
+      apiKeys: consoleKeys,
+    } as unknown as ConsoleState;
+    const attached = await attachHostToConsole({ entry, cwd: dir, state });
+    expect(attached).not.toBeNull();
+    expect(state.apiKeys).not.toBe(consoleKeys);
+    expect(state.apiKeys.persist).not.toBe(consoleKeys.persist);
+    await attached!.stop();
+  });
+
   test("returns null when the entry is not a bootable app", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-attach-empty-"));
     const entry = join(dir, "app.ts");

package/src/cli/attach-host-console.ts

@@ -69,10 +69,19 @@ export async function attachHostToConsole(
   if (vault) options.state.vaultRuntime = vault;
   const ai = host.elements?.ai ?? host.bootResult?.ai;
   if (ai) bindAiRuntime(options.state, ai);
+  const hostKeys = host.apiKeys;
+  if (hostKeys) {
+    // Host `gate.auth.apiKeyStore` is the durable store (`oke_api_keys` on
+    // `store.sql()`). Console displays that instance — never the reverse.
+    options.state.apiKeys = hostKeys;
+  }
 
   return {
     stop: async () => {
       options.state.invokeUserFlow = null;
+      options.state.storeRuntime = null;
+      options.state.vaultRuntime = null;
+      options.state.aiRuntime = null;
       await host.stop();
     },
   };

package/src/cli/build.test.ts

@@ -32,8 +32,10 @@ describe("oke build — .adopt() barrel regeneration", () => {
       expect(code).toBe(0);
 
       const after = await readFile(generatedPath, "utf8");
-      expect(after).toContain('export * as main from "./main/index.ts";');
-      expect(after).toContain('export * as notes from "./notes/index.ts";');
+      expect(after).toContain('import * as main from "./main/index.ts";');
+      expect(after).toContain('import * as notes from "./notes/index.ts";');
+      expect(after).toContain("export { main }");
+      expect(after).toContain("export { notes }");
     } finally {
       await rm(root, { recursive: true, force: true });
     }

package/src/cli/db-seed.ts

@@ -1,10 +1,10 @@
 /**
  * `oke db seed` — load `defineSeed`, boot the app store, run essential +
- * env-selected category (`dev` | `prod`).
+ * env-selected category (`dev` | `prod`). Tallies SQL upserts and `kv.set`.
  */
 
 import { resolve } from "node:path";
-import { isCancel, text } from "@clack/prompts";
+import { intro, isCancel, outro, text } from "@clack/prompts";
 import type { ConfigEnv, OkeConfig } from "../config/index.ts";
 import {
   normalizeSeedFns,
@@ -25,11 +25,13 @@ import { EXIT_OK, EXIT_RUNTIME, EXIT_USAGE } from "./exit.ts";
 import { loadOkeConfig } from "./load-config.ts";
 import { resolveDevSqlEnv } from "./resolve-dev-sql-env.ts";
 
-/** Per-function upsert outcome counts. */
+/** Per-function upsert / KV-set outcome counts. */
 export interface SeedTally {
   upserted: number;
   changed: number;
   alreadyExisted: number;
+  /** `fx.store(kv).set` calls (cache or durable). */
+  keys: number;
 }
 
 /** Options for {@link runSeed}. */
@@ -56,6 +58,11 @@ export interface SeedOptions {
    */
   readonly confirmEnv?: (env: ConfigEnv, target: string) => Promise<boolean>;
   readonly stdinIsTTY?: boolean;
+  /**
+   * Clack `intro` / `outro` for the standalone `oke db seed` path.
+   * Default: on when stdin is a TTY.
+   */
+  readonly intro?: boolean;
 }
 
 /**
@@ -127,12 +134,13 @@ export async function runSeedFns(
 ): Promise<void> {
   for (let i = 0; i < fns.length; i++) {
     const fn = fns[i]!;
-    const tally: SeedTally = { upserted: 0, changed: 0, alreadyExisted: 0 };
+    const tally: SeedTally = { upserted: 0, changed: 0, alreadyExisted: 0, keys: 0 };
     const instrumented = instrumentFxUpserts(fx, tally);
     await fn(instrumented);
     const label = fn.name.length > 0 ? fn.name : String(i);
+    const kv = tally.keys > 0 ? ` · keys ${tally.keys}` : "";
     write(
-      `oke db seed: ${category} ${label} — upserted ${tally.upserted} · changed ${tally.changed} · already-existed ${tally.alreadyExisted}\n`,
+      `oke db seed: ${category} ${label} — upserted ${tally.upserted} · changed ${tally.changed} · already-existed ${tally.alreadyExisted}${kv}\n`,
     );
   }
 }
@@ -233,7 +241,13 @@ export async function bootSeedFx(
   if (!app) {
     throw new Error(`oke db seed: no oke() app export in ${entryAbs}`);
   }
-  await app.boot({ env, startScheduler: false, config: config ?? undefined, rootDir: cwd });
+  await app.boot({
+    env,
+    startScheduler: false,
+    config: config ?? undefined,
+    rootDir: cwd,
+    docker: process.env.OKE_DOCKER === "1",
+  });
   const storeRuntime = app.elements?.store ?? app.bootResult?.store;
   if (!storeRuntime) {
     throw new Error(
@@ -243,6 +257,7 @@ export async function bootSeedFx(
   const fx = createFx({
     flow: "oke.db.seed",
     storeRuntime,
+    rlsBypass: true,
   });
   return {
     fx,
@@ -262,6 +277,14 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
   const cwd = options.cwd ?? process.cwd();
   const loaded = await loadOkeConfig(cwd).catch(() => null);
   const env = options.env ?? (await resolveDevSqlEnv(cwd));
+  const tty = options.stdinIsTTY ?? Boolean(process.stdin.isTTY);
+  const useIntro = options.intro !== false && tty;
+  if (useIntro) intro("oke db seed");
+
+  const finish = (code: number, message: string): number => {
+    if (useIntro) outro(message);
+    return code;
+  };
 
   let targetLabel = String(env);
   try {
@@ -274,7 +297,6 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
 
   if (env === "dev" || env === "prod") {
     if (options.force !== true) {
-      const tty = options.stdinIsTTY ?? Boolean(process.stdin.isTTY);
       const confirm =
         options.confirmEnv ??
         (tty
@@ -288,7 +310,7 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
       const ok = await confirm(env, targetLabel);
       if (!ok) {
         write("oke db seed: cancelled\n");
-        return EXIT_USAGE;
+        return finish(EXIT_USAGE, "Cancelled.");
       }
     }
   }
@@ -308,10 +330,10 @@ export async function runSeed(options: SeedOptions = {}): Promise<number> {
     stop = session.stop;
     await executeSeedDef(def, env, session.fx, write);
     write("oke db seed: ok\n");
-    return EXIT_OK;
+    return finish(EXIT_OK, "oke db seed: ok");
   } catch (err) {
     write(`oke db seed: ${err instanceof Error ? err.message : String(err)}\n`);
-    return EXIT_RUNTIME;
+    return finish(EXIT_RUNTIME, "oke db seed: failed");
   } finally {
     if (stop) await stop().catch(() => {});
   }
@@ -374,14 +396,18 @@ function instrumentFxUpserts(fx: Fx, tally: SeedTally): Fx {
 
 function instrumentUpsertHandle<T>(handle: T, tally: SeedTally): T {
   if (!handle || typeof handle !== "object") return handle;
-  const h = handle as { upsert?: (...args: unknown[]) => Promise<{ status: UpsertStatus }> };
-  if (typeof h.upsert !== "function") return handle;
-  const orig = h.upsert.bind(h);
+  const h = handle as {
+    upsert?: (...args: unknown[]) => Promise<{ status: UpsertStatus }>;
+    set?: (...args: unknown[]) => Promise<unknown>;
+  };
+  const origUpsert = typeof h.upsert === "function" ? h.upsert.bind(h) : undefined;
+  const origSet = typeof h.set === "function" ? h.set.bind(h) : undefined;
+  if (!origUpsert && !origSet) return handle;
   return new Proxy(handle as object, {
     get(target, prop, receiver) {
-      if (prop === "upsert") {
+      if (prop === "upsert" && origUpsert) {
         return async (...args: unknown[]) => {
-          const result = await orig(...args);
+          const result = await origUpsert(...args);
           const status =
             result && typeof result === "object" && "status" in result
               ? (result as { status: UpsertStatus }).status
@@ -392,6 +418,13 @@ function instrumentUpsertHandle<T>(handle: T, tally: SeedTally): T {
           return result;
         };
       }
+      if (prop === "set" && origSet) {
+        return async (...args: unknown[]) => {
+          const result = await origSet(...args);
+          tally.keys += 1;
+          return result;
+        };
+      }
       return Reflect.get(target, prop, receiver);
     },
   }) as T;

package/src/cli/db.test.ts

@@ -11,9 +11,11 @@ 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 {
+  createHintsForRenameOrCreate,
   dbCli,
   emitAbstractSchemaPrestep,
   executeSeedDef,
+  formatKitError,
   runSeedFns,
   runDb,
   runGenerate,
@@ -116,6 +118,13 @@ describe("oke db", () => {
     expect(out.join("")).toContain("0001_init.sql");
   });
 
+  test("formatKitError joins code message and sql", () => {
+    expect(formatKitError({ code: "query_error", message: "boom", sql: "CREATE TABLE t" })).toBe(
+      " — query_error — boom — CREATE TABLE t",
+    );
+    expect(formatKitError(undefined)).toBe("");
+  });
+
   test("missing_hints exits runtime", async () => {
     const out: string[] = [];
     const code = await runDb("push", {
@@ -131,6 +140,75 @@ describe("oke db", () => {
     expect(out.join("")).toContain("DROP TABLE leftover");
   });
 
+  test("createHintsForRenameOrCreate maps rename_or_create only", () => {
+    expect(
+      createHintsForRenameOrCreate([
+        { type: "rename_or_create", kind: "table", entity: ["public", "activity"] },
+        {
+          type: "confirm_data_loss",
+          kind: "table",
+          entity: ["public", "old"],
+          reason: "non_empty",
+        },
+      ]),
+    ).toEqual([{ type: "create", kind: "table", entity: ["public", "activity"] }]);
+  });
+
+  test("push retries rename_or_create as create", async () => {
+    const hints: unknown[] = [];
+    const out: string[] = [];
+    const code = await runPush("/tmp/drizzle.config.ts", (t) => out.push(t), {
+      skipEmit: true,
+      pushFn: async (opts) => {
+        hints.push(opts.hints);
+        if (!opts.hints) {
+          return {
+            status: "missing_hints",
+            unresolved: [{ type: "rename_or_create", kind: "table", entity: ["public", "notes"] }],
+          };
+        }
+        return { status: "ok" };
+      },
+    });
+    expect(code).toBe(EXIT_OK);
+    expect(hints[1]).toEqual([{ type: "create", kind: "table", entity: ["public", "notes"] }]);
+    expect(out.join("")).toContain("creating 1 new object");
+    expect(out.join("")).toContain("oke db push: ok");
+  });
+
+  test("push does not retry confirm_data_loss-only missing_hints", async () => {
+    let calls = 0;
+    const code = await runPush("/tmp/drizzle.config.ts", () => {}, {
+      skipEmit: true,
+      pushFn: async () => {
+        calls += 1;
+        return {
+          status: "missing_hints",
+          unresolved: [{ type: "confirm_data_loss", kind: "table", entity: ["public", "notes"] }],
+        };
+      },
+    });
+    expect(code).toBe(EXIT_RUNTIME);
+    expect(calls).toBe(1);
+  });
+
+  test("explain does not auto-create on missing_hints", async () => {
+    let calls = 0;
+    const code = await runPush("/tmp/drizzle.config.ts", () => {}, {
+      skipEmit: true,
+      explain: true,
+      pushFn: async () => {
+        calls += 1;
+        return {
+          status: "missing_hints",
+          unresolved: [{ type: "rename_or_create", kind: "table", entity: ["public", "notes"] }],
+        };
+      },
+    });
+    expect(code).toBe(EXIT_RUNTIME);
+    expect(calls).toBe(1);
+  });
+
   test("resolveDrizzleConfigPath uses db.config from oke.config", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-db-"));
     await writeFile(
@@ -551,6 +629,32 @@ describe("oke db seed", () => {
     expect(out.join("")).toContain("dev volume — upserted 0 · changed 1 · already-existed 0");
   });
 
+  test("runSeedFns tallies kv.set as keys", async () => {
+    const out: string[] = [];
+    const fx = {
+      store: () => ({
+        set: async () => undefined,
+      }),
+    } as unknown as ReturnType<typeof createFx>;
+    await runSeedFns(
+      "dev",
+      [
+        async function volume(seedFx) {
+          const kv = seedFx.store("kv" as never) as unknown as {
+            set: (key: string, value: unknown) => Promise<void>;
+          };
+          await kv.set("ENG-12", { title: "SSO" });
+          await kv.set("ENG-14", { title: "Polish" });
+        },
+      ],
+      fx,
+      (t) => out.push(t),
+    );
+    expect(out.join("")).toContain(
+      "dev volume — upserted 0 · changed 0 · already-existed 0 · keys 2",
+    );
+  });
+
   test("executeSeedDef is the category source of truth", async () => {
     const order: string[] = [];
     const out: string[] = [];

package/src/cli/db.ts

@@ -8,6 +8,7 @@
  */
 
 import { resolve } from "node:path";
+import type { Hint as DrizzleKitHint } from "drizzle-kit/cli";
 import {
   dialectFromDriverId,
   maybeEmitDomainSchema,
@@ -17,6 +18,7 @@ import { loadPluginTablesFromAppEntry } from "../elements/store/load-plugin-tabl
 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 { installOkeRlsHelpers as runOkeRlsHelperStatements } from "../drivers/pg-rls.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";
@@ -90,7 +92,10 @@ export interface DbOptions {
   readonly config?: string;
   readonly write?: (text: string) => void;
   /** Injectable push (tests). */
-  readonly pushFn?: (opts: { config: string }) => Promise<DbKitResult>;
+  readonly pushFn?: (opts: {
+    config: string;
+    hints?: readonly DbKitHint[];
+  }) => Promise<DbKitResult>;
   /** Injectable generate (tests). */
   readonly generateFn?: (opts: {
     config: string;
@@ -129,13 +134,61 @@ export interface DbOptions {
   readonly stdinIsTTY?: boolean;
 }
 
+/** drizzle-kit SDK hint — create vs rename vs confirm data loss. */
+export type DbKitHint =
+  | {
+      readonly type: "create";
+      readonly kind: string;
+      readonly entity: readonly string[];
+    }
+  | {
+      readonly type: "rename";
+      readonly kind: string;
+      readonly from: readonly string[];
+      readonly to: readonly string[];
+    }
+  | {
+      readonly type: "confirm_data_loss";
+      readonly kind: string;
+      readonly entity: readonly 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 error?: {
+    readonly code?: string;
+    readonly message?: string;
+    readonly sql?: string;
+  };
   readonly unresolved?: readonly unknown[];
 }
 
+/**
+ * Auto-resolve drizzle-kit `rename_or_create` as create (dev push).
+ * Leaves `confirm_data_loss` for the caller to fail on.
+ *
+ * @param unresolved - Kit `missing_hints` payload
+ */
+export function createHintsForRenameOrCreate(
+  unresolved: readonly unknown[] | undefined,
+): DbKitHint[] {
+  const hints: DbKitHint[] = [];
+  if (!unresolved) return hints;
+  for (const item of unresolved) {
+    if (!item || typeof item !== "object") continue;
+    const rec = item as Record<string, unknown>;
+    if (rec.type !== "rename_or_create") continue;
+    if (typeof rec.kind !== "string" || !Array.isArray(rec.entity)) continue;
+    hints.push({
+      type: "create",
+      kind: rec.kind,
+      entity: rec.entity.map((part) => String(part)),
+    });
+  }
+  return hints;
+}
+
 /**
  * Resolve the drizzle config path for a project.
  *
@@ -295,19 +348,30 @@ export async function runPush(
 
   const pushFn =
     options.pushFn ??
-    (async (opts: { config: string }) => {
+    (async (opts: { config: string; hints?: readonly DbKitHint[] }) => {
       const { push } = await import("drizzle-kit/cli");
       return (await push({
         config: opts.config,
         ...(options.explain ? { explain: true } : {}),
+        ...(opts.hints && opts.hints.length > 0
+          ? { hints: [...opts.hints] as DrizzleKitHint[] }
+          : {}),
       })) as DbKitResult;
     });
 
   let result: DbKitResult;
   try {
-    result = await withDrizzleKitEnv(cwd, loaded?.config, env, () =>
-      pushFn({ config: configPath }),
-    );
+    result = await withDrizzleKitEnv(cwd, loaded?.config, env, async () => {
+      await installOkeRlsHelpers(write);
+      const first = await pushFn({ config: configPath });
+      if (options.explain || first.status !== "missing_hints") return first;
+      const createHints = createHintsForRenameOrCreate(first.unresolved);
+      if (createHints.length === 0) return first;
+      write(
+        `oke db push: creating ${createHints.length} new ${createHints.length === 1 ? "object" : "objects"}\n`,
+      );
+      return pushFn({ config: configPath, hints: createHints });
+    });
   } 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");
@@ -402,7 +466,9 @@ export async function runMigrate(
     });
 
   const { overlay } = await resolveDrizzleKitEnv(cwd, loaded?.config, env);
+  const restore = applyDrizzleEnvOverlay(overlay);
   try {
+    await installOkeRlsHelpers(write);
     const code = await migrateFn({
       config: configPath,
       cwd,
@@ -417,6 +483,8 @@ export async function runMigrate(
   } catch (err) {
     write(`oke db migrate: ${err instanceof Error ? err.message : String(err)}\n`);
     return EXIT_RUNTIME;
+  } finally {
+    restore();
   }
 }
 
@@ -523,7 +591,7 @@ 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
+  seed       Run defineSeed (essential + env category) — standard CLI path
   studio     Open drizzle-kit Studio (long-running)
 
   --env      Override config env (dev|test|prod)
@@ -571,6 +639,39 @@ Not the same as \`oke schema generate\` (core/plugin stub tables).
   return runDb(sub, { config, env, force, entry });
 }
 
+/**
+ * Install `oke.gate()` / `oke.user()` / `oke.has_scope()` before drizzle-kit
+ * so `CREATE POLICY … oke.gate()` succeeds.
+ *
+ * @param write - Output
+ */
+async function installOkeRlsHelpers(write: (text: string) => void): Promise<void> {
+  const url = process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL;
+  const pgliteUrl = process.env.OKE_PGLITE_URL;
+  try {
+    if (pgliteUrl && !url) {
+      const { connectPglite } = await import("../drivers/pglite.ts");
+      const conn = await connectPglite({ url: pgliteUrl });
+      try {
+        await runOkeRlsHelperStatements((sql) => conn.exec(sql));
+      } finally {
+        await conn.close();
+      }
+      return;
+    }
+    if (!url) return;
+    const { connectPostgres } = await import("../drivers/postgres.ts");
+    const conn = await connectPostgres({ url });
+    try {
+      await runOkeRlsHelperStatements((sql) => conn.exec(sql));
+    } finally {
+      await conn.close();
+    }
+  } catch (err) {
+    write(`oke db: oke.* helpers skipped — ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}
+
 function parseConfigEnv(value: string | undefined): ConfigEnv | undefined {
   if (value === "dev" || value === "test" || value === "prod") return value;
   // Soft-compat for older CLI flags / docs.
@@ -616,8 +717,19 @@ function reportKitResult(verb: string, result: DbKitResult, write: (text: string
     if (detail) write(detail);
     return EXIT_RUNTIME;
   }
-  write(
-    `oke db ${verb}: ${result.status}${result.error?.message ? ` — ${result.error.message}` : ""}\n`,
-  );
+  write(`oke db ${verb}: ${result.status}${formatKitError(result.error)}\n`);
   return EXIT_RUNTIME;
 }
+
+/**
+ * Format a drizzle-kit `error` object for the CLI line.
+ *
+ * @param error - Kit envelope error
+ */
+export function formatKitError(error: DbKitResult["error"] | undefined): string {
+  if (!error) return "";
+  const parts = [error.code, error.message, error.sql].filter(
+    (part): part is string => typeof part === "string" && part.length > 0,
+  );
+  return parts.length > 0 ? ` — ${parts.join(" — ")}` : "";
+}