okengine 0.11.2 → 0.13.0

package/src/docker/recipes/traefik.ts

@@ -74,6 +74,7 @@ export const traefik: ImageRecipe = {
         volumes: ["/var/run/docker.sock:/var/run/docker.sock:ro"],
         networks: ["oke"],
       },
+      // Overlay — compose drops this when `includeApp` is false (`oke dev`).
       app: {
         labels: traefikAppLabels(),
       },

package/src/docker/recipes/valkey.ts

@@ -5,7 +5,7 @@
  * `valkey/valkey`.
  */
 
-import { credEnv } from "../helpers.ts";
+import { credEnv, kvServerCommand } from "../helpers.ts";
 import type { ImageRecipe } from "../types.ts";
 
 /** Valkey — Redis protocol on 6379. */
@@ -14,11 +14,7 @@ export const valkey: ImageRecipe = {
   port: 6379,
   match: (i) => /valkey/i.test(i),
   apply: (s) => ({
-    command: [
-      "sh",
-      "-c",
-      'exec valkey-server --requirepass "$$OKE_STORE_KV_PASSWORD" --maxmemory "$${OKE_STORE_KV_MAXMEMORY:-0}" --maxmemory-policy "$${OKE_STORE_KV_MAXMEMORY_POLICY:-noeviction}"',
-    ],
+    command: ["sh", "-c", kvServerCommand(s, "valkey-server")],
     healthcheck: {
       test: ["CMD", "valkey-cli", "-a", credEnv(s, "PASSWORD"), "ping"],
       interval: "5s",

package/src/docker/recipes/vllm.ts

@@ -9,7 +9,7 @@
 import type { ImageRecipe } from "../types.ts";
 
 /** Pinned vLLM OpenAI server image — never `latest`. */
-export const VLLM_IMAGE = "vllm/vllm-openai:v0.26.0";
+export const VLLM_IMAGE = "vllm/vllm-openai:v0.27.1";
 
 /** vLLM — OpenAI-compatible HTTP on 8000; GPU reservation; loopback publish. */
 export const vllm: ImageRecipe = {

package/src/docker/stack-id.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -56,28 +56,19 @@ describe("hostPortForInstance", () => {
 });
 
 describe("loadExistingStackControls", () => {
-  test("seeds OKE_AI_MODEL from .env.local when .env.docker omits it", async () => {
+  test("seeds OKE_AI_MODEL from .env.local", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-stack-ai-"));
     await writeFile(join(dir, ".env.local"), "OKE_AI_MODEL=gemma4:e4b-q4_K_M\n", "utf8");
     const controls = await loadExistingStackControls(dir);
     expect(controls?.OKE_AI_MODEL).toBe("gemma4:e4b-q4_K_M");
   });
 
-  test("seeds commented OKE_AI_MODEL from .env.local when .env.docker omits it", async () => {
+  test("seeds commented OKE_AI_MODEL from .env.local", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-stack-ai-"));
     await writeFile(join(dir, ".env.local"), "# OKE_AI_MODEL=gemma4:e4b-q4_K_M\n", "utf8");
     const controls = await loadExistingStackControls(dir);
     expect(controls?.OKE_AI_MODEL).toBe("gemma4:e4b-q4_K_M");
   });
-
-  test("prefers active OKE_AI_MODEL in docker/.env.docker over .env.local", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "oke-stack-ai-"));
-    await mkdir(join(dir, "docker"), { recursive: true });
-    await writeFile(join(dir, "docker", ".env.docker"), "OKE_AI_MODEL=smollm2\n", "utf8");
-    await writeFile(join(dir, ".env.local"), "# OKE_AI_MODEL=gemma4:e4b-q4_K_M\n", "utf8");
-    const controls = await loadExistingStackControls(dir);
-    expect(controls?.OKE_AI_MODEL).toBe("smollm2");
-  });
 });
 
 describe("parseStackCredentials", () => {
@@ -151,8 +142,8 @@ describe("deriveInfrastructure instanceId", () => {
     const n = instancePortOffset(id);
     const result = deriveInfrastructure({
       images: {
-        "channel.email": "axllent/mailpit:v1.22.3",
-        "store.files": "rustfs/rustfs:1.0.0-beta.11",
+        "channel.email": "axllent/mailpit:v1.30.7",
+        "store.files": "rustfs/rustfs:1.0.0-rc.2",
       },
       app: `dev-${id}`,
       instanceId: id,

package/src/docker/stack-id.ts

@@ -8,7 +8,6 @@
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import type { ServiceCredentials } from "./types.ts";
-import { DEFAULT_DOCKER_DIR } from "./types.ts";
 import { defaultHostPort, envPrefix } from "./helpers.ts";
 
 /**
@@ -86,7 +85,7 @@ export function extraHostPortForInstance(
 }
 
 /**
- * Parse role credentials from an existing `.env.docker` body (reuse on restart).
+ * Parse role credentials from an existing `.env.local` body (reuse on restart).
  *
  * @param text - Dotenv contents
  * @param roles - Roles to look up
@@ -114,7 +113,7 @@ export function parseStackCredentials(
   return out;
 }
 
-/** Optional `.env.docker` keys preserved when generated files refresh. */
+/** Optional `.env.local` keys preserved when generated files refresh. */
 export const STACK_CONTROL_KEYS = [
   "PGDATA",
   "POSTGRES_INITDB_ARGS",
@@ -134,7 +133,7 @@ export const STACK_CONTROL_KEYS = [
 ] as const;
 
 /**
- * Read supported user controls from an existing `.env.docker`.
+ * Read supported user controls from an existing `.env.local`.
  *
  * @param text - Dotenv contents
  */
@@ -149,9 +148,7 @@ export function parseStackControls(text: string): Record<string, string> {
 }
 
 /**
- * Load credentials from `docker/.env.docker` when present.
- *
- * Soft-compat: also reads legacy project-root `.env.docker`.
+ * Load credentials from `.env.local` when present.
  *
  * @param cwd - Project root
  * @param roles - Image roles
@@ -160,43 +157,26 @@ export async function loadExistingStackCredentials(
   cwd: string,
   roles: readonly string[],
 ): Promise<Readonly<Record<string, ServiceCredentials>> | undefined> {
-  const candidates = [resolve(cwd, DEFAULT_DOCKER_DIR, ".env.docker"), resolve(cwd, ".env.docker")];
-  for (const path of candidates) {
-    const file = Bun.file(path);
-    if (!(await file.exists())) continue;
-    const parsed = parseStackCredentials(await file.text(), roles);
-    if (Object.keys(parsed).length > 0) return parsed;
-  }
-  return undefined;
+  const file = Bun.file(resolve(cwd, ".env.local"));
+  if (!(await file.exists())) return undefined;
+  const parsed = parseStackCredentials(await file.text(), roles);
+  return Object.keys(parsed).length > 0 ? parsed : undefined;
 }
 
 /**
- * Load optional controls from `docker/.env.docker` when present.
+ * Load optional controls from `.env.local` when present.
  *
  * @param cwd - Project root
  */
 export async function loadExistingStackControls(
   cwd: string,
 ): Promise<Readonly<Record<string, string>> | undefined> {
-  const candidates = [resolve(cwd, DEFAULT_DOCKER_DIR, ".env.docker"), resolve(cwd, ".env.docker")];
-  let controls: Record<string, string> = {};
-  for (const path of candidates) {
-    const file = Bun.file(path);
-    if (!(await file.exists())) continue;
-    controls = parseStackControls(await file.text());
-    break;
-  }
-  // create-oke / `oke ai setup` write the chosen model into `.env.local` as a
-  // commented hint (active would shadow `docker/.env.docker`). Seed active or
-  // commented `OKE_AI_MODEL` on first docker boot so `LLAMA_ARG_DOCKER_REPO`
-  // is not stuck on the recipe default (`granite3.3:2b`).
-  if (!controls.OKE_AI_MODEL) {
-    const localEnv = Bun.file(resolve(cwd, ".env.local"));
-    if (await localEnv.exists()) {
-      const model = readEnvAssignment(await localEnv.text(), "OKE_AI_MODEL");
-      if (model) controls = { ...controls, OKE_AI_MODEL: model };
-    }
-  }
+  const file = Bun.file(resolve(cwd, ".env.local"));
+  if (!(await file.exists())) return undefined;
+  const text = await file.text();
+  const parsed = parseStackControls(text);
+  const model = readEnvAssignment(text, "OKE_AI_MODEL");
+  const controls = model && !parsed.OKE_AI_MODEL ? { ...parsed, OKE_AI_MODEL: model } : parsed;
   return Object.keys(controls).length > 0 ? controls : undefined;
 }
 

package/src/docker/stack.integration.test.ts

@@ -121,11 +121,11 @@ describe("oke dev --docker postgres integration", () => {
           await sql.close();
         }
 
-        // Prove credentials live in docker/.env.docker, not YAML.
+        // Prove credentials live in .env.local, not YAML.
         const yml = await Bun.file(join(dockerDir, "docker-compose.yml")).text();
         expect(yml).not.toContain("stack-integration-pass");
         expect(formatStackEnv(derived.stackEnv)).toContain("stack-integration-pass");
-        expect(await Bun.file(join(dockerDir, ".env.docker")).exists()).toBe(true);
+        expect(await Bun.file(join(dir, ".env.local")).exists()).toBe(true);
       } finally {
         await Bun.spawn(
           ["docker", "compose", "-p", project, "-f", "docker-compose.yml", "down", "-v"],

package/src/docker/types.ts

@@ -37,7 +37,7 @@ export interface ServiceSpec {
   readonly port: number;
   /** Host port published in compose (dev defaults). */
   readonly hostPort: number;
-  /** Credential placeholders (values live in `.env.docker`, not YAML). */
+  /** Credential placeholders (values live in `.env.local`, not YAML). */
   readonly credentials: ServiceCredentials;
 }
 
@@ -96,9 +96,17 @@ export interface RecipeApplyResult {
   /**
    * Extra `services` entries merged into this role's compose layer —
    * companions (e.g. Docker socket proxy) or overlays on peers
-   * (e.g. Traefik routing labels on `app`).
+   * (e.g. Traefik routing labels on `app` when `includeApp` is true).
    */
   readonly services?: Readonly<Record<string, Record<string, unknown>>>;
+  /**
+   * Compose `build` for locally derived images (opt-in advisor Postgres).
+   * `dockerfile` is relative to the compose directory.
+   */
+  readonly build?: {
+    readonly context: string;
+    readonly dockerfile: string;
+  };
 }
 
 /**
@@ -173,13 +181,14 @@ export interface DeriveOptions {
   readonly serverMemoryGb?: number;
   /**
    * Include the `app` service in the compose document (default true).
-   * `oke dev --docker` sets false — host Bun runs the app; Docker is infra only.
+   * `oke dev` sets false — host Bun runs the app; Docker is infra only.
+   * Recipe overlays on `app` (Traefik labels) are dropped in that mode.
    */
   readonly includeApp?: boolean;
   /**
    * Compose artefact directory relative to the project root (default `docker`).
-   * Controls generated `env_file` / `build.context` paths (`.env.docker` lives
-   * beside compose under this directory).
+   * Controls generated `env_file` / `build.context` paths (`.env.local` lives
+   * at the project root; compose under `docker/` uses `../.env.local`).
    * Pass `"."` for legacy root-level layout.
    */
   readonly composeDir?: string;
@@ -191,7 +200,7 @@ export interface DeriveOptions {
   readonly host?: string;
   /** Extra image recipes (plugins). */
   readonly recipes?: readonly ImageRecipe[];
-  /** Preserved optional controls from an existing `.env.docker`. */
+  /** Preserved optional controls from an existing `.env.local`. */
   readonly controls?: Readonly<Record<string, string>>;
   /**
    * Local stack instance id (6-hex). When set, host ports are offset so two
@@ -218,7 +227,7 @@ export interface DeriveResult {
   /** Generated files (Dockerfile + compose layers). */
   readonly files: readonly GeneratedFile[];
   /**
-   * Stack env contents for `.env.docker` — written by `oke dev --docker`,
+   * Stack env contents merged into `.env.local` by `oke dev --docker`,
    * never embedded in YAML.
    */
   readonly stackEnv: Readonly<Record<string, string>>;

package/src/drivers/ai-mock.ts

@@ -50,7 +50,8 @@ export const mockAiDriver: AiDriver = {
           }
         }
         if (payload === undefined) {
-          payload = canned["*"] ?? { ok: true, echo: last };
+          payload = canned["*"] ??
+            fixtureFromResponseFormat(opts.responseFormat) ?? { ok: true, echo: last };
         }
 
         // Scripted tool calls: `{ __toolCalls: [...] }` or MockToolCallScript shape
@@ -124,6 +125,45 @@ export const mockAiDriver: AiDriver = {
   },
 };
 
+/**
+ * Build a schema-shaped payload from `response_format.json_schema`.
+ *
+ * @param responseFormat - Runtime response format
+ */
+function fixtureFromResponseFormat(responseFormat: unknown): Record<string, unknown> | undefined {
+  if (!responseFormat || typeof responseFormat !== "object") return undefined;
+  const wrapped = (responseFormat as { json_schema?: { schema?: unknown } }).json_schema?.schema;
+  const schema =
+    wrapped && typeof wrapped === "object"
+      ? wrapped
+      : "properties" in responseFormat
+        ? responseFormat
+        : undefined;
+  if (!schema || typeof schema !== "object" || !("properties" in schema)) return undefined;
+  const props = (schema as { properties?: Record<string, unknown> }).properties ?? {};
+  const requiredRaw = (schema as { required?: unknown }).required;
+  const required = Array.isArray(requiredRaw) ? (requiredRaw as string[]) : Object.keys(props);
+  const out: Record<string, unknown> = {};
+  for (const key of required) {
+    const spec = props[key];
+    const type =
+      spec && typeof spec === "object" && "type" in spec
+        ? String((spec as { type?: unknown }).type)
+        : "string";
+    out[key] =
+      type === "number" || type === "integer"
+        ? 0
+        : type === "boolean"
+          ? true
+          : type === "array"
+            ? []
+            : type === "object"
+              ? {}
+              : "ok";
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 /**
  * Register a mock response helper for tests.
  *

package/src/drivers/ai-openai-compatible.ts

@@ -102,7 +102,7 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
       if (opts.temperature !== undefined) body.temperature = opts.temperature;
       if (opts.maxTokens !== undefined) body.max_tokens = opts.maxTokens;
       if (opts.responseFormat !== undefined) {
-        body.response_format = opts.responseFormat;
+        body.response_format = wireOpenaiResponseFormat(opts.responseFormat);
       }
       if (opts.tools !== undefined && opts.tools.length > 0) {
         body.tools = opts.tools.map((t) => ({
@@ -199,6 +199,24 @@ export const openaiCompatibleAiDriver: AiDriver = {
   open: openOpenaiCompatible,
 };
 
+/**
+ * llama.cpp granite empties `content` on `json_schema`; `json_object` plus
+ * the ask-time schema instruction is the portable contract.
+ *
+ * @param responseFormat - Runtime format (may be json_schema)
+ */
+function wireOpenaiResponseFormat(responseFormat: unknown): unknown {
+  if (
+    responseFormat &&
+    typeof responseFormat === "object" &&
+    "type" in responseFormat &&
+    (responseFormat as { type?: unknown }).type === "json_schema"
+  ) {
+    return { type: "json_object" };
+  }
+  return responseFormat;
+}
+
 function serializeMessage(m: AiCompleteOptions["messages"][number]): Record<string, unknown> {
   const out: Record<string, unknown> = {
     role: m.role,

package/src/drivers/index.ts

@@ -124,6 +124,13 @@ export {
   type BunJournalClient,
 } from "./journal-postgres.ts";
 
+export {
+  createPostgresInstanceStore,
+  type PostgresInstanceSql,
+  type CreatePostgresInstanceStoreOptions,
+  type BunInstanceClient,
+} from "./instances-postgres.ts";
+
 export {
   redisSignalDriver,
   openRedisSignal,
@@ -150,6 +157,8 @@ export {
 export {
   managedVaultDriver,
   createManagedVaultBag,
+  MANAGED_VAULT_PROVIDER_IDS,
+  MANAGED_VAULT_PROVIDER_LIST,
   type ManagedVaultOptions,
   type ManagedVaultProviderId,
 } from "./vault-managed.ts";
@@ -158,6 +167,29 @@ export {
   type AwsSecretsManagerClient,
   type OpenAwsSecretsManagerOptions,
 } from "./vault-aws-secrets-manager.ts";
+export {
+  openAzureKeyVaultBag,
+  toAzureName,
+  fromAzureName,
+  type OpenAzureKeyVaultOptions,
+} from "./vault-azure-key-vault.ts";
+export {
+  openGcpSecretManagerBag,
+  type OpenGcpSecretManagerOptions,
+} from "./vault-gcp-secret-manager.ts";
+export { openDopplerBag, type OpenDopplerOptions } from "./vault-doppler.ts";
+export { openOnePasswordBag, type OpenOnePasswordOptions } from "./vault-1password.ts";
+export {
+  openRemoteSecretBag,
+  asRemoteVaultError,
+  vaultHttpJson,
+  remoteErrorCode,
+  type RemoteSecretClient,
+  type OpenRemoteSecretBagOptions,
+  type VaultErrorTranslator,
+  type VaultHttpJsonOptions,
+  type VaultHttpJsonResult,
+} from "./vault-remote-bag.ts";
 
 export type {
   ChannelDriverId,

package/src/drivers/instances-postgres.ts

@@ -0,0 +1,154 @@
+/**
+ * `postgres` instance registry — one row per process, TTL liveness.
+ *
+ * Own-row UPSERT (not SKIP LOCKED). Alive ⇔ `lease_expires_at > now`.
+ * No sweeper — readers filter expired rows.
+ */
+
+import type { ConfigEnv } from "../config/index.ts";
+import type { InstanceRow, InstanceStore } from "../kernel/instances.ts";
+import { toPostgresParams } from "./postgres.ts";
+
+/** Minimal SQL surface for the postgres instance store. */
+export interface PostgresInstanceSql {
+  query(sql: string, params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
+  exec(sql: string, params?: readonly unknown[]): Promise<{ changes: number }>;
+  close(): Promise<void>;
+}
+
+/** Options for {@link createPostgresInstanceStore}. */
+export interface CreatePostgresInstanceStoreOptions {
+  /** Postgres connection URL (Bun.SQL). Ignored when `sql` is injected. */
+  readonly url?: string;
+  /** Injected SQL surface (tests / fakes). */
+  readonly sql?: PostgresInstanceSql;
+  /** Injected Bun.SQL-compatible client. */
+  readonly client?: BunInstanceClient;
+}
+
+/** Minimal Bun.SQL surface used by the real driver. */
+export interface BunInstanceClient {
+  unsafe(
+    sql: string,
+    values?: unknown[],
+  ): PromiseLike<Record<string, unknown>[] | { length: number; changes?: number }>;
+  close?(options?: { timeout?: number }): Promise<void>;
+}
+
+const UPSERT_SQL = `INSERT INTO oke_instances (id, started_at, heartbeat_at, lease_expires_at, env, pid) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (id) DO UPDATE SET heartbeat_at = EXCLUDED.heartbeat_at, lease_expires_at = EXCLUDED.lease_expires_at, env = EXCLUDED.env, pid = EXCLUDED.pid`;
+
+function wrapBunClient(client: BunInstanceClient): PostgresInstanceSql {
+  return {
+    async query(sql, params = []) {
+      const pg = toPostgresParams(sql);
+      const result = await client.unsafe(pg, [...params]);
+      if (Array.isArray(result)) return result as Record<string, unknown>[];
+      return Array.from(result as ArrayLike<Record<string, unknown>>);
+    },
+    async exec(sql, params = []) {
+      const pg = toPostgresParams(sql);
+      const result = await client.unsafe(pg, [...params]);
+      if (
+        result &&
+        typeof result === "object" &&
+        "changes" in result &&
+        typeof (result as { changes: unknown }).changes === "number"
+      ) {
+        return { changes: (result as { changes: number }).changes };
+      }
+      if (Array.isArray(result)) return { changes: result.length };
+      return { changes: 0 };
+    },
+    async close() {
+      await client.close?.();
+    },
+  };
+}
+
+function numOrUndef(v: unknown): number | undefined {
+  if (v === undefined || v === null || v === "") return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function rowFromDb(row: Record<string, unknown>): InstanceRow {
+  const pid = numOrUndef(row.pid);
+  return {
+    id: String(row.id),
+    startedAt: Number(row.started_at),
+    heartbeatAt: Number(row.heartbeat_at),
+    leaseExpiresAt: Number(row.lease_expires_at),
+    env: String(row.env) as ConfigEnv,
+    ...(pid !== undefined ? { pid } : {}),
+  };
+}
+
+async function ensureSchema(sql: PostgresInstanceSql): Promise<void> {
+  await sql.exec(`CREATE TABLE IF NOT EXISTS oke_instances (
+    id TEXT PRIMARY KEY,
+    started_at BIGINT NOT NULL,
+    heartbeat_at BIGINT NOT NULL,
+    lease_expires_at BIGINT NOT NULL,
+    env TEXT NOT NULL,
+    pid INTEGER
+  )`);
+  await sql.exec(
+    `CREATE INDEX IF NOT EXISTS oke_instances_lease ON oke_instances (lease_expires_at)`,
+  );
+}
+
+/**
+ * Open a postgres-backed instance store (shared fleet census).
+ *
+ * @param options - URL / injected sql / Bun.SQL client
+ */
+export async function createPostgresInstanceStore(
+  options: CreatePostgresInstanceStoreOptions = {},
+): Promise<InstanceStore & { readonly sql: PostgresInstanceSql }> {
+  const sql =
+    options.sql ??
+    wrapBunClient(
+      options.client ??
+        (new Bun.SQL(
+          options.url ?? process.env.DATABASE_URL ?? "postgres://localhost:5432/oke",
+        ) as unknown as BunInstanceClient),
+    );
+
+  await ensureSchema(sql);
+
+  const store: InstanceStore & { readonly sql: PostgresInstanceSql } = {
+    kind: "postgres",
+    sql,
+    async upsert(row) {
+      await sql.exec(UPSERT_SQL, [
+        row.id,
+        row.startedAt,
+        row.heartbeatAt,
+        row.leaseExpiresAt,
+        row.env,
+        row.pid ?? null,
+      ]);
+    },
+    async get(id) {
+      const rows = await sql.query(`SELECT * FROM oke_instances WHERE id = ?`, [id]);
+      if (!rows[0]) return undefined;
+      return rowFromDb(rows[0]);
+    },
+    async list() {
+      const rows = await sql.query(`SELECT * FROM oke_instances`);
+      return rows.map(rowFromDb);
+    },
+    async listAlive(now) {
+      const rows = await sql.query(`SELECT * FROM oke_instances WHERE lease_expires_at > ?`, [now]);
+      return rows.map(rowFromDb);
+    },
+    async remove(id) {
+      await sql.exec(`DELETE FROM oke_instances WHERE id = ?`, [id]);
+    },
+    async close() {
+      await sql.close();
+    },
+  };
+
+  return store;
+}

package/src/drivers/meilisearch.integration.test.ts

@@ -63,6 +63,15 @@ describe("meilisearch live — arabic + typo tolerance", () => {
     expect(found.hits.map((h) => h.id)).toContain("d1");
   });
 
+  live("re-open of an existing index does not fail", async () => {
+    const name = `reopen-${crypto.randomUUID().slice(0, 8)}`;
+    const first = await liveIndex(name);
+    await first.upsert("d1", { title: "already here" });
+    const second = await liveIndex(name);
+    const listed = await second.list(10);
+    expect(listed.map((h) => h.id)).toContain("d1");
+  });
+
   live("filter + facets aggregate real results", async () => {
     const index = await liveIndex(`fac-${crypto.randomUUID().slice(0, 8)}`);
     await index.upsert("d1", { title: "red apple", color: "red" });