okengine 0.6.1 → 0.8.0

package/src/cli/docker.ts

@@ -1,5 +1,5 @@
 /**
- * `oke docker` — Dockerfile + per-role compose files.
+ * `oke docker` — Dockerfile + per-role compose files · `clean` leftover stacks.
  */
 
 import { resolve } from "node:path";
@@ -10,6 +10,8 @@ import {
   type DeriveOptions,
   type DeriveResult,
 } from "../docker/index.ts";
+import { dockerCleanCli, dockerCleanHelp } from "./docker-clean.ts";
+import { EXIT_OK } from "./exit.ts";
 import { loadOkeConfig, loadManifest, resolveImages } from "./load-config.ts";
 
 /** Options for {@link runDockerDerive}. */
@@ -112,11 +114,16 @@ export async function runDockerDerive(
 }
 
 /**
- * CLI entry for `oke docker [--prod|-p] [--out|-o dir]`.
+ * CLI entry for `oke docker [clean] …` / derive flags.
  *
  * @param args - Args after `docker`
  */
 export async function dockerCli(args: readonly string[]): Promise<number> {
+  const [head, ...rest] = args;
+  if (head === "clean") {
+    return dockerCleanCli(rest);
+  }
+
   let prod = false;
   let outDir: string | undefined;
   let configPath: string | undefined;
@@ -132,8 +139,13 @@ export async function dockerCli(args: readonly string[]): Promise<number> {
 
 Derive Dockerfile + compose.<role>.yml under docker/ (default).
 --prod is opt-in (never the default). Credentials are never written into YAML.
-`);
-      return 0;
+
+${dockerCleanHelp()}`);
+      return EXIT_OK;
+    } else if (!a.startsWith("-")) {
+      console.error(`oke docker: unknown subcommand ${a}`);
+      console.error("Run `oke docker --help` for usage.");
+      return 1;
     }
   }
   const { code } = await runDockerDerive({

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

@@ -5,7 +5,7 @@
 
 import { resolve } from "node:path";
 
-/** Mode-aware template (matches `packages/create-oke/template/drizzle.config.ts`). */
+/** Mode-aware template (matches create-oke templates' drizzle.config.ts). */
 const DRIZZLE_CONFIG_TEMPLATE = `import { defineConfig } from "drizzle-kit";
 
 /**

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

@@ -18,9 +18,9 @@ const SAMPLE: OkeConfig = {
       sql: { local: "sqlite", docker: "postgres", prod: "postgres" },
       kv: { local: "memory", docker: "redis", prod: "redis" },
     },
-    signal: { local: "memory", docker: "postgres", prod: "postgres" },
-    clock: { local: "memory", docker: "postgres", prod: "postgres" },
-    vault: { local: "dotenv", docker: "openbao", prod: "openbao" },
+    signal: { local: "memory", docker: "redis", prod: "redis" },
+    clock: { local: "memory", docker: "file", prod: "file" },
+    vault: { local: "env", docker: "openbao", prod: "openbao" },
     channel: {
       email: { local: "console", docker: "smtp", prod: "smtp" },
     },
@@ -62,8 +62,9 @@ describe("hero-meta", () => {
     expect(store).toContain("postgres");
     expect(store).toContain("redis");
     expect(store).not.toContain("sqlite");
-    expect(rows.find((r) => r.element === "signal")?.detail).toBe("postgres");
-    expect(rows.find((r) => r.element === "clock")?.detail).toBe("postgres");
+    expect(rows.find((r) => r.element === "signal")?.detail).toBe("redis");
+    expect(rows.find((r) => r.element === "clock")?.detail).toBe("file");
+    expect(rows.find((r) => r.element === "gate")?.detail).toBe("redis");
     expect(rows.find((r) => r.element === "channel")?.detail).toContain("smtp");
   });
 

package/src/cli/hero-meta.ts

@@ -156,6 +156,12 @@ export function resolveHeroElements(
   // `-d` reads the `docker` profile for every element (not a store-only override).
   const configEnv: ConfigEnv = options.configEnv ?? (options.docker ? "docker" : "local");
 
+  // Gate rates share `drivers.store.kv` (no separate drivers.gate).
+  const gateKv =
+    options.kvDriver ??
+    resolveDriverId(drivers?.store?.kv, configEnv) ??
+    (options.docker ? "redis" : "memory");
+
   const byName: Record<string, string> = {
     flow: "●",
     signal: resolveDriverId(drivers?.signal, configEnv) ?? "—",
@@ -164,7 +170,7 @@ export function resolveHeroElements(
       kv: options.kvDriver,
     }),
     clock: resolveDriverId(drivers?.clock, configEnv) ?? "—",
-    gate: "—",
+    gate: gateKv,
     vault: resolveDriverId(drivers?.vault, configEnv) ?? "—",
     channel: channelDetail(drivers?.channel, configEnv),
     ai: resolveDriverId(drivers?.ai, configEnv) ?? "—",

package/src/cli/index.ts

@@ -3,6 +3,7 @@
  * `oke` CLI entry.
  */
 
+import { aiCli } from "./ai.ts";
 import { branchCli } from "./branch.ts";
 import { buildCli } from "./build.ts";
 import { clientAddCli } from "./client-add.ts";
@@ -79,6 +80,10 @@ if (cmd === "eval") {
   process.exit(await evalCli(sub ? [sub, ...rest] : rest));
 }
 
+if (cmd === "ai") {
+  process.exit(await aiCli(sub ? [sub, ...rest] : rest));
+}
+
 if (cmd === "branch") {
   process.exit(await branchCli(sub ? [sub, ...rest] : rest));
 }

package/src/cli/load-config.images.test.ts

@@ -37,6 +37,28 @@ describe("defaultImagesFromConfig", () => {
     expect(images["store.sql"]).toBe("pgvector/pgvector:pg17");
   });
 
+  test("clock postgres alone pulls store.sql image", () => {
+    const images = defaultImagesFromConfig({
+      drivers: {
+        clock: { prod: "postgres" },
+      },
+    });
+    expect(images).toEqual({
+      "store.sql": "postgres:18-alpine",
+    });
+  });
+
+  test("journal postgres alone pulls store.sql image", () => {
+    const images = defaultImagesFromConfig({
+      drivers: {
+        journal: { prod: "postgres" },
+      },
+    });
+    expect(images).toEqual({
+      "store.sql": "postgres:18-alpine",
+    });
+  });
+
   test("returns empty when no container drivers", () => {
     expect(defaultImagesFromConfig({})).toEqual({});
     expect(

package/src/cli/load-config.ts

@@ -48,13 +48,17 @@ export function defaultImagesFromConfig(config: OkeConfig): Readonly<Record<stri
   const kv = dockerOrProdId(config.drivers?.store?.kv);
   const signal = dockerOrProdId(config.drivers?.signal);
   const clock = dockerOrProdId(config.drivers?.clock);
+  const journal = dockerOrProdId(config.drivers?.journal);
 
+  // SQL-consuming facets pull a SQL image. Signal postgres still needs a
+  // LISTEN/NOTIFY client (not Bun.SQL); clock + journal postgres are real
+  // SKIP LOCKED stores (CronStore / durable-run journal).
   const needsSql =
     sql === "postgres" ||
     sql === "pgvector" ||
     index === "pgvector" ||
-    signal === "postgres" ||
     clock === "postgres" ||
+    journal === "postgres" ||
     (config.drivers?.prod ?? []).some((p) => p === "postgres" || p === "pgvector");
 
   if (needsSql) {
@@ -62,7 +66,8 @@ export function defaultImagesFromConfig(config: OkeConfig): Readonly<Record<stri
       sql === "pgvector" || index === "pgvector" ? DEFAULT_PGVECTOR_IMAGE : DEFAULT_SQL_IMAGE;
   }
 
-  const needsKv = kv === "redis" || (config.drivers?.prod ?? []).includes("redis");
+  const needsKv =
+    kv === "redis" || signal === "redis" || (config.drivers?.prod ?? []).includes("redis");
   if (needsKv) {
     out["store.kv"] = DEFAULT_KV_IMAGE;
   }

package/src/cli/openbao-bootstrap.test.ts

@@ -145,5 +145,6 @@ describe("openbao bootstrap material gates", () => {
     }
     expect(failed).toBeInstanceOf(OpenBaoBootstrapError);
     expect(String(failed)).toContain("unrecoverable");
+    expect(String(failed)).toContain("compose.vault.yml down -v");
   });
 });

package/src/cli/openbao-bootstrap.ts

@@ -221,8 +221,15 @@ export async function ensureOpenBao(
     if (!existsSync(unsealPath) || !existsSync(rootPath)) {
       throw new OpenBaoBootstrapError(
         `openbao bootstrap: OpenBao is initialized but ${stateDir} is missing ` +
-          `unseal.key/root.token. Without the unseal key the data is unrecoverable. ` +
-          `Restore your backup of .oke/openbao/ — permanent loss otherwise.`,
+          `unseal.key/root.token. Without the unseal key the vault data is unrecoverable.\n` +
+          `\n` +
+          `Usual cause in docker mode: a previous vault volume survived after the project\n` +
+          `(or .oke/openbao/) was deleted — Compose stop keeps volumes on purpose.\n` +
+          `\n` +
+          `Restore a backup of .oke/openbao/ if you have one.\n` +
+          `\n` +
+          `Dev reset (wipes vault secrets only, then re-init on next oke dev):\n` +
+          `  cd docker && docker compose -f compose.yml -f compose.vault.yml down -v`,
       );
     }
     unsealKey = readFileSync(unsealPath, "utf8").trim();

package/src/cli/registry.ts

@@ -202,7 +202,7 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
   },
   {
     name: "db",
-    summary: "domain schema — push · generate · migrate",
+    summary: "domain schema — push · generate · migrate · seed",
     subcommands: [
       {
         name: "push",
@@ -215,6 +215,12 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
             valueName: "path",
             summary: "drizzle.config.ts path",
           },
+          {
+            long: "--env",
+            takesValue: true,
+            valueName: "name",
+            summary: "Config env (local|docker|test|prod)",
+          },
           HELP,
         ],
       },
@@ -229,6 +235,12 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
             valueName: "path",
             summary: "drizzle.config.ts path",
           },
+          {
+            long: "--env",
+            takesValue: true,
+            valueName: "name",
+            summary: "Config env (local|docker|test|prod)",
+          },
           HELP,
         ],
       },
@@ -243,6 +255,30 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
             valueName: "path",
             summary: "drizzle.config.ts path",
           },
+          {
+            long: "--env",
+            takesValue: true,
+            valueName: "name",
+            summary: "Config env (local|docker|test|prod)",
+          },
+          HELP,
+        ],
+      },
+      {
+        name: "seed",
+        summary: "Run defineSeed (essential + env category); never at boot",
+        flags: [
+          {
+            long: "--env",
+            takesValue: true,
+            valueName: "name",
+            summary: "Config env (local|docker|test|prod)",
+          },
+          {
+            long: "--force",
+            summary: "Skip docker/prod confirmation prompt",
+          },
+          ENTRY,
           HELP,
         ],
       },
@@ -287,7 +323,7 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
   },
   {
     name: "docker",
-    summary: "Dockerfile + compose.<role>.yml",
+    summary: "derive compose · clean leftover stacks",
     leaf: true,
     flags: [
       {
@@ -300,6 +336,24 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
       MANIFEST,
       HELP,
     ],
+    subcommands: [
+      {
+        name: "clean",
+        summary: "Remove oke-dev stacks (containers, networks, volumes)",
+        flags: [
+          {
+            long: "--yes",
+            short: "-y",
+            summary: "Non-interactive confirm",
+          },
+          {
+            long: "--all",
+            summary: "Every oke-dev-* stack (required with --yes outside a project)",
+          },
+          HELP,
+        ],
+      },
+    ],
   },
   {
     name: "images",
@@ -346,6 +400,56 @@ export const OKE_COMMANDS: readonly CliCommand[] = [
     leaf: true,
     flags: [MANIFEST, HELP],
   },
+  {
+    name: "ai",
+    summary: "configure AI driver + models",
+    subcommands: [
+      {
+        name: "setup",
+        summary: "Interactive / flagged AI provider + model setup",
+        flags: [
+          {
+            long: "--provider",
+            takesValue: true,
+            valueName: "id",
+            summary: "ollama · openai · anthropic · gemini · lmstudio · openrouter · custom",
+          },
+          {
+            long: "--chat",
+            takesValue: true,
+            valueName: "model",
+            summary: "Chat model id",
+          },
+          {
+            long: "--vision",
+            takesValue: true,
+            valueName: "model",
+            summary: "Vision model id",
+          },
+          {
+            long: "--embed",
+            takesValue: true,
+            valueName: "model",
+            summary: "Embedding model id",
+          },
+          {
+            long: "--pull",
+            summary: "Pull missing Ollama models (default)",
+          },
+          {
+            long: "--no-pull",
+            summary: "Skip ollama pull",
+          },
+          {
+            long: "--yes",
+            short: "-y",
+            summary: "Non-interactive (requires --provider)",
+          },
+          HELP,
+        ],
+      },
+    ],
+  },
   {
     name: "branch",
     summary: "fork journaled state",
@@ -459,6 +563,16 @@ export function flagTokensFor(command: CliCommand, sub?: string): readonly strin
 }
 
 function formatCommandUsage(cmd: CliCommand): string {
+  // Leaf + subcommands (e.g. `oke docker` derive · `oke docker clean`).
+  if (cmd.leaf && cmd.subcommands && cmd.subcommands.length > 0) {
+    const flagHint = cmd.flags
+      ?.filter((f) => f.long !== "--help")
+      .slice(0, 2)
+      .map((f) => formatFlagHint(f))
+      .join(" ");
+    const subs = cmd.subcommands.map((s) => s.name).join("|");
+    return `oke ${cmd.name}${flagHint ? ` ${flagHint}` : ""} · ${subs}`;
+  }
   if (cmd.subcommands?.length === 1) {
     const sub = cmd.subcommands[0]!;
     const flagHint = sub.flags

package/src/client/live-gap.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Evidence: createClient has no live-signal subscription today.
+ *
+ * `delivery: "live"` is consumed server-side via `bus.live()` (and
+ * `on(signal, flow)` for flow subscribers). `okengine/client` exposes only
+ * HTTP REST / RPC — no SSE, WebSocket, or `api.live(…)`.
+ *
+ * Design for `client.live(signalName)` is tracked with the Signal docs page;
+ * do not treat this file as a stub to fill — ship the real surface when ready.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import * as client from "./index.ts";
+import { createClient } from "./create.ts";
+
+describe("createClient — live signal gap", () => {
+  test("public client module exports no live / subscribe helpers", () => {
+    const keys = Object.keys(client).sort();
+    expect(keys).not.toContain("live");
+    expect(keys).not.toContain("subscribe");
+    expect(keys).toContain("createClient");
+    expect(keys).toContain("createTransport");
+  });
+
+  test("createClient builds an HTTP call proxy only (no live method on the root)", async () => {
+    const api = createClient("http://app.test", {
+      fetch: async () => Response.json({ data: null, error: { code: "NotFound", data: {} } }),
+    });
+    // Root is a callable proxy for unit.flow — live is not a first-class API.
+    expect(typeof api).toBe("function");
+    expect(Object.prototype.hasOwnProperty.call(api, "live")).toBe(false);
+    expect("live" in (api as object)).toBe(false);
+  });
+});

package/src/client/transport.test.ts

@@ -47,6 +47,27 @@ describe("transport — retry", () => {
     expect(error?.code).toBe("TransportError");
     expect(n).toBe(2);
   });
+
+  test("structured 5xx envelope is returned (not TransportError)", async () => {
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async () =>
+        Response.json(
+          {
+            data: null,
+            error: {
+              code: "InternalError",
+              data: {},
+              message: "password policy failed: minLength 12",
+            },
+          },
+          { status: 500 },
+        ),
+    });
+
+    const { error } = await api.sys.ping();
+    expect(error?.code).toBe("InternalError");
+    expect(error?.message).toMatch(/password policy/i);
+  });
 });
 
 describe("transport — timeout", () => {

package/src/client/transport.ts

@@ -44,6 +44,11 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
             await opts.auth.refresh();
             continue;
           }
+          if (res.status >= 500) {
+            const structured = await decodeIfEnvelope(res);
+            if (structured) return structured;
+            throw new Error(`HTTP ${res.status}`);
+          }
           return decode(res);
         } catch (err) {
           const transient = isTransient(err);
@@ -110,21 +115,38 @@ async function once(
     ctrl && opts.timeout !== undefined ? setTimeout(() => ctrl.abort(), opts.timeout) : undefined;
 
   try {
-    const res = await fetchFn(url, {
+    return await fetchFn(url, {
       method,
       headers,
       body,
       signal: ctrl?.signal,
     });
-    if (res.status >= 500) {
-      throw new Error(`HTTP ${res.status}`);
-    }
-    return res;
   } finally {
     if (timer !== undefined) clearTimeout(timer);
   }
 }
 
+/**
+ * Decode a JSON `{ data, error }` envelope from a 5xx response, or `null`
+ * when the body is not a structured OKE failure (retry as transport error).
+ *
+ * @param res - HTTP response (body consumed)
+ */
+async function decodeIfEnvelope(res: Response): Promise<ClientResult | null> {
+  const text = await res.text();
+  if (!text) return null;
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (json !== null && typeof json === "object" && "data" in json && "error" in json) {
+    return json as ClientResult;
+  }
+  return null;
+}
+
 function rpcRequest(
   base: string,
   key: string,

package/src/compiler/effects-infer.ts

@@ -114,6 +114,7 @@ const TABLE_ARG_METHODS = new Set([
   "findById",
   "exists",
   "update",
+  "upsert",
   "increment",
   "delete",
 ]);

package/src/compiler/fixtures/skyport/oke.config.ts

@@ -9,7 +9,7 @@ export default defineConfig({
       files: { prod: "s3" },
       index: { prod: "pgvector" },
     },
-    signal: { prod: "postgres" },
+    signal: { prod: "redis" },
     vault: { prod: "openbao" },
     channel: { email: { prod: "smtp" } },
     ai: { prod: { driver: "anthropic" } },

package/src/config/define-config.test.ts

@@ -26,7 +26,7 @@ describe("fillDockerFromProd / defineConfig", () => {
   });
 
   test("vault prod → docker copies the prod driver", () => {
-    expect(fillDockerFromProd({ local: "dotenv", prod: "openbao" })?.docker).toBe("openbao");
+    expect(fillDockerFromProd({ local: "env", prod: "openbao" })?.docker).toBe("openbao");
   });
 
   test("defineConfig fills every element from prod", () => {
@@ -37,9 +37,9 @@ describe("fillDockerFromProd / defineConfig", () => {
           kv: { local: "memory", prod: "redis" },
           files: { local: "fs", prod: "s3" },
         },
-        signal: { local: "memory", prod: "postgres" },
-        clock: { local: "memory", prod: "postgres" },
-        vault: { local: "dotenv", prod: "openbao" },
+        signal: { local: "memory", prod: "redis" },
+        clock: { local: "memory", prod: "file" },
+        vault: { local: "env", prod: "openbao" },
         channel: {
           email: { local: "console", prod: "smtp" },
         },
@@ -49,8 +49,8 @@ describe("fillDockerFromProd / defineConfig", () => {
     expect(cfg.drivers?.store?.sql?.docker).toBe("postgres");
     expect(cfg.drivers?.store?.kv?.docker).toBe("redis");
     expect(cfg.drivers?.store?.files?.docker).toBe("s3");
-    expect(cfg.drivers?.signal?.docker).toBe("postgres");
-    expect(cfg.drivers?.clock?.docker).toBe("postgres");
+    expect(cfg.drivers?.signal?.docker).toBe("redis");
+    expect(cfg.drivers?.clock?.docker).toBe("file");
     expect(cfg.drivers?.vault?.docker).toBe("openbao");
     expect(cfg.drivers?.channel?.email?.docker).toBe("smtp");
     expect(cfg.drivers?.ai?.docker).toBe("anthropic");

package/src/config/index.ts

@@ -73,6 +73,8 @@ export interface DriversConfig {
   readonly store?: StoreDriversConfig;
   readonly signal?: EnvDriverMap;
   readonly clock?: EnvDriverMap;
+  /** Durable-run journal: `memory` · `file` · `postgres`. */
+  readonly journal?: EnvDriverMap;
   readonly vault?: EnvDriverMap;
   readonly channel?: ChannelDriversConfig;
   readonly ai?: EnvDriverMap;
@@ -283,6 +285,7 @@ export function normalizeDriversConfig(
     ...(store !== undefined ? { store } : {}),
     signal: normalizeEnvDriverMap(drivers.signal as RawEnvDriverMap),
     clock: normalizeEnvDriverMap(drivers.clock as RawEnvDriverMap),
+    journal: normalizeEnvDriverMap(drivers.journal as RawEnvDriverMap),
     vault: normalizeEnvDriverMap(drivers.vault as RawEnvDriverMap),
     ...(channel !== undefined ? { channel } : {}),
     ai: normalizeEnvDriverMap(drivers.ai as RawEnvDriverMap),
@@ -333,6 +336,7 @@ export function fillDriversDockerFromProd(
     ...(store !== undefined ? { store } : {}),
     signal: fillDockerFromProd(drivers.signal),
     clock: fillDockerFromProd(drivers.clock),
+    journal: fillDockerFromProd(drivers.journal),
     vault: fillDockerFromProd(drivers.vault),
     ...(channel !== undefined ? { channel } : {}),
     ai: fillDockerFromProd(drivers.ai),
@@ -344,7 +348,7 @@ export function fillDriversDockerFromProd(
  * Define an `oke.config.ts` document.
  *
  * Missing `docker` driver pins are filled from `prod` so `oke dev -d` uses the
- * same server protocols as production (vault → dotenv for `docker/.env.docker`).
+ * same server protocols as production (vault → `env` for `docker/.env.docker`).
  * Legacy `dev`/`stack` keys are normalized to `local`/`docker`.
  *
  * @param config - Driver / tenancy / i18n / topology

package/src/console/server/console.test.ts

@@ -53,6 +53,51 @@ describe("console kernel", () => {
     }
   });
 
+  test("claim rejects weak passwords with ClaimFailed password_policy (not 500)", async () => {
+    const handle = await startConsoleApp({
+      cwd,
+      secret: "test-secret-console",
+      silentClaim: true,
+    });
+    try {
+      const weak = await handle.app.fetch(
+        new Request("http://console.test/console/setup/claim", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            claimCode: handle.state.claim.code,
+            email: "ops@example.com",
+            name: "Ops",
+            password: "short1A",
+          }),
+        }),
+      );
+      // Zod min(12) rejects before createOperator — still not an opaque 500.
+      expect(weak.status).toBe(422);
+      const shortOkZod = await handle.app.fetch(
+        new Request("http://console.test/console/setup/claim", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            claimCode: handle.state.claim.code,
+            email: "ops@example.com",
+            name: "Ops",
+            password: "longenoughword",
+          }),
+        }),
+      );
+      expect(shortOkZod.status).toBe(400);
+      const body = (await shortOkZod.json()) as {
+        error: { code: string; message?: string; data?: { reason?: string } };
+      };
+      expect(body.error.code).toBe("ClaimFailed");
+      expect(body.error.data?.reason).toBe("password_policy");
+      expect(body.error.message).toMatch(/12 characters/i);
+    } finally {
+      await handle.app.stop();
+    }
+  });
+
   test("claim creates first operator and closes the wizard permanently", async () => {
     const handle = await startConsoleApp({
       cwd,