okengine 0.6.0 → 0.7.0

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.ts

@@ -47,14 +47,13 @@ export function defaultImagesFromConfig(config: OkeConfig): Readonly<Record<stri
   const index = dockerOrProdId(config.drivers?.store?.index);
   const kv = dockerOrProdId(config.drivers?.store?.kv);
   const signal = dockerOrProdId(config.drivers?.signal);
-  const clock = dockerOrProdId(config.drivers?.clock);
 
+  // Only real SQL-consuming facets pull a SQL image. Clock/signal no longer
+  // advertise a fictional postgres CronStore / LISTEN bus via compose.
   const needsSql =
     sql === "postgres" ||
     sql === "pgvector" ||
     index === "pgvector" ||
-    signal === "postgres" ||
-    clock === "postgres" ||
     (config.drivers?.prod ?? []).some((p) => p === "postgres" || p === "pgvector");
 
   if (needsSql) {
@@ -62,7 +61,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/openbao-restart.integration.test.ts

@@ -3,7 +3,7 @@
  *
  * Proves the acceptance criterion — set a secret, kill/restart the container
  * on the same Raft volume, re-run the bootstrap unseal, and read the secret
- * back. Skips when no Docker daemon is available.
+ * back. Opt-in via `OKE_TEST_DOCKER=1` plus a live Docker daemon.
  */
 
 import { describe, expect, test } from "bun:test";
@@ -13,10 +13,9 @@ import { join } from "node:path";
 import { deriveInfrastructure, writeDerivedFiles } from "../docker/index.ts";
 import { ensureOpenBao } from "./openbao-bootstrap.ts";
 
-async function dockerAvailable(): Promise<boolean> {
+function dockerAvailable(): boolean {
   try {
-    const proc = Bun.spawn(["docker", "info"], { stdout: "pipe", stderr: "pipe" });
-    return (await proc.exited) === 0;
+    return Bun.spawnSync(["docker", "info"], { stdout: "pipe", stderr: "pipe" }).exitCode === 0;
   } catch {
     return false;
   }
@@ -31,106 +30,116 @@ async function compose(project: string, dir: string, args: readonly string[]): P
   return proc.exited;
 }
 
-describe("openbao restart persistence (real container)", () => {
-  test("secret set before restart is readable after restart + unseal", async () => {
-    if (!(await dockerAvailable())) {
-      console.warn("skipping: docker daemon not available");
-      return;
-    }
-
-    const dir = await mkdtemp(join(tmpdir(), "oke-openbao-it-"));
-    const dockerDir = join(dir, "docker");
-    const project = `oke-bao-${Date.now()}`;
-    const composeFiles = ["compose.yml", "compose.vault.yml"];
-    try {
-      const derived = deriveInfrastructure({
-        images: { vault: "openbao/openbao:2.6.1" },
-        app: "baotest",
-        includeApp: false,
-        composeDir: "docker",
-      });
-      await writeDerivedFiles(derived, dockerDir, { writeStackEnv: true });
-      const spec = derived.specs.find((s) => s.role === "vault")!;
-      const url = `http://127.0.0.1:${spec.hostPort}`;
-
-      const up = await compose(project, dockerDir, [
-        ...composeFiles.flatMap((f) => ["-f", f]),
-        "up",
-        "-d",
-      ]);
-      expect(up).toBe(0);
+const WANT = process.env.OKE_TEST_DOCKER === "1";
+const DOCKER = WANT && dockerAvailable();
+if (!DOCKER) {
+  console.log(
+    WANT
+      ? "skip: openbao restart e2e (docker daemon not available)"
+      : "skip: openbao restart e2e (OKE_TEST_DOCKER≠1)",
+  );
+}
+const live = DOCKER ? test : test.skip;
 
-      const names = ["STRIPE_KEY"];
-      let first;
+describe("openbao restart persistence (real container)", () => {
+  live(
+    "secret set before restart is readable after restart + unseal",
+    async () => {
+      const dir = await mkdtemp(join(tmpdir(), "oke-openbao-it-"));
+      const dockerDir = join(dir, "docker");
+      const project = `oke-bao-${Date.now()}`;
+      const composeFiles = ["compose.yml", "compose.vault.yml"];
       try {
-        first = await ensureOpenBao({ cwd: dir, url, names });
-      } catch (err) {
-        const logs = Bun.spawn(
-          [
-            "docker",
-            "compose",
-            "-p",
-            project,
-            ...composeFiles.flatMap((f) => ["-f", f]),
-            "logs",
-            "vault",
-          ],
-          { cwd: dockerDir, stdout: "pipe", stderr: "pipe" },
-        );
-        console.error(await new Response(logs.stdout).text());
-        console.error(await new Response(logs.stderr).text());
-        await logs.exited;
-        throw err;
-      }
-      expect(first.appToken.length).toBeGreaterThan(0);
+        const derived = deriveInfrastructure({
+          images: { vault: "openbao/openbao:2.6.1" },
+          app: "baotest",
+          includeApp: false,
+          composeDir: "docker",
+        });
+        await writeDerivedFiles(derived, dockerDir, { writeStackEnv: true });
+        const spec = derived.specs.find((s) => s.role === "vault")!;
+        const url = `http://127.0.0.1:${spec.hostPort}`;
 
-      const write = await fetch(`${url}/v1/secret/data/STRIPE_KEY`, {
-        method: "POST",
-        headers: { "X-Vault-Token": first.appToken, "content-type": "application/json" },
-        body: JSON.stringify({ data: { value: "sk_restart_persistent" } }),
-      });
-      if (!write.ok) console.error("write failed", write.status, await write.text());
-      expect(write.ok).toBe(true);
+        const up = await compose(project, dockerDir, [
+          ...composeFiles.flatMap((f) => ["-f", f]),
+          "up",
+          "-d",
+        ]);
+        expect(up).toBe(0);
 
-      // Kill + start the same volume (a real restart, not a fresh stack).
-      const restart = await compose(project, dockerDir, [
-        ...composeFiles.flatMap((f) => ["-f", f]),
-        "restart",
-      ]);
-      expect(restart).toBe(0);
-      // Poll the API until the server is back (sealed or unsealed).
-      let apiUp = false;
-      for (let i = 0; i < 60; i++) {
+        const names = ["STRIPE_KEY"];
+        let first;
         try {
-          const probe = await fetch(`${url}/v1/sys/seal-status`);
-          if (probe.ok) {
-            apiUp = true;
-            break;
+          first = await ensureOpenBao({ cwd: dir, url, names });
+        } catch (err) {
+          const logs = Bun.spawn(
+            [
+              "docker",
+              "compose",
+              "-p",
+              project,
+              ...composeFiles.flatMap((f) => ["-f", f]),
+              "logs",
+              "vault",
+            ],
+            { cwd: dockerDir, stdout: "pipe", stderr: "pipe" },
+          );
+          console.error(await new Response(logs.stdout).text());
+          console.error(await new Response(logs.stderr).text());
+          await logs.exited;
+          throw err;
+        }
+        expect(first.appToken.length).toBeGreaterThan(0);
+
+        const write = await fetch(`${url}/v1/secret/data/STRIPE_KEY`, {
+          method: "POST",
+          headers: { "X-Vault-Token": first.appToken, "content-type": "application/json" },
+          body: JSON.stringify({ data: { value: "sk_restart_persistent" } }),
+        });
+        if (!write.ok) console.error("write failed", write.status, await write.text());
+        expect(write.ok).toBe(true);
+
+        // Kill + start the same volume (a real restart, not a fresh stack).
+        const restart = await compose(project, dockerDir, [
+          ...composeFiles.flatMap((f) => ["-f", f]),
+          "restart",
+        ]);
+        expect(restart).toBe(0);
+        // Poll the API until the server is back (sealed or unsealed).
+        let apiUp = false;
+        for (let i = 0; i < 60; i++) {
+          try {
+            const probe = await fetch(`${url}/v1/sys/seal-status`);
+            if (probe.ok) {
+              apiUp = true;
+              break;
+            }
+          } catch {
+            // not up yet
           }
-        } catch {
-          // not up yet
+          await Bun.sleep(500);
         }
-        await Bun.sleep(500);
-      }
-      expect(apiUp).toBe(true);
+        expect(apiUp).toBe(true);
 
-      const second = await ensureOpenBao({ cwd: dir, url, names });
-      expect(second.initializedNow).toBe(false);
-      expect(second.appToken).toBe(first.appToken);
+        const second = await ensureOpenBao({ cwd: dir, url, names });
+        expect(second.initializedNow).toBe(false);
+        expect(second.appToken).toBe(first.appToken);
 
-      const read = await fetch(`${url}/v1/secret/data/STRIPE_KEY`, {
-        headers: { "X-Vault-Token": second.appToken },
-      });
-      expect(read.ok).toBe(true);
-      const body = (await read.json()) as { data?: { data?: { value?: string } } };
-      expect(body.data?.data?.value).toBe("sk_restart_persistent");
-    } finally {
-      await compose(project, dockerDir, [
-        ...composeFiles.flatMap((f) => ["-f", f]),
-        "down",
-        "-v",
-      ]).catch(() => 0);
-      await rm(dir, { recursive: true, force: true }).catch(() => {});
-    }
-  }, 180_000);
+        const read = await fetch(`${url}/v1/secret/data/STRIPE_KEY`, {
+          headers: { "X-Vault-Token": second.appToken },
+        });
+        expect(read.ok).toBe(true);
+        const body = (await read.json()) as { data?: { data?: { value?: string } } };
+        expect(body.data?.data?.value).toBe("sk_restart_persistent");
+      } finally {
+        await compose(project, dockerDir, [
+          ...composeFiles.flatMap((f) => ["-f", f]),
+          "down",
+          "-v",
+        ]).catch(() => 0);
+        await rm(dir, { recursive: true, force: true }).catch(() => {});
+      }
+    },
+    180_000,
+  );
 });

package/src/cli/registry.ts

@@ -287,7 +287,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 +300,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 +364,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 +527,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/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

@@ -344,7 +344,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,