okengine 0.9.0 → 0.10.0

package/src/docker/compose-health.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import {
+  composeHealthByService,
+  composeRowToStatus,
+  parseComposePsJson,
+  startComposeHealthWatch,
+  watchComposeHealth,
+} from "./compose-health.ts";
+
+describe("compose-health", () => {
+  test("composeRowToStatus maps Health and State", () => {
+    expect(composeRowToStatus({ Health: "healthy", State: "running" })).toBe("ready");
+    expect(composeRowToStatus({ Health: "starting", State: "running" })).toBe("pending");
+    expect(composeRowToStatus({ Health: "unhealthy", State: "running" })).toBe("error");
+    expect(composeRowToStatus({ State: "exited" })).toBe("error");
+    expect(composeRowToStatus({ State: "stopped" })).toBe("error");
+    expect(composeRowToStatus({ Status: "Exited (0) 3 seconds ago" })).toBe("error");
+    expect(composeRowToStatus({ State: "running" })).toBe("ready");
+    expect(composeRowToStatus({ Status: "Up 2 seconds (health: starting)" })).toBe("pending");
+  });
+
+  test("parseComposePsJson accepts NDJSON and arrays", () => {
+    const nd = [
+      JSON.stringify({ Service: "ai", Health: "starting", State: "running" }),
+      JSON.stringify({ Service: "store-sql", Health: "healthy", State: "running" }),
+    ].join("\n");
+    expect(parseComposePsJson(nd)).toHaveLength(2);
+
+    const arr = JSON.stringify([
+      { Service: "redis", State: "running" },
+      { Service: "vault", Health: "unhealthy", State: "running" },
+    ]);
+    const map = composeHealthByService(arr);
+    expect(map.get("redis")).toBe("ready");
+    expect(map.get("vault")).toBe("error");
+  });
+
+  test("watchComposeHealth emits changes until done", async () => {
+    let calls = 0;
+    const updates: string[] = [];
+    const map = await watchComposeHealth({
+      files: ["compose.yml"],
+      cwd: "/tmp",
+      env: {},
+      intervalMs: 1,
+      timeoutMs: 5_000,
+      sleep: async () => {},
+      run: async () => {
+        calls += 1;
+        if (calls === 1) {
+          return JSON.stringify([{ Service: "store-sql", Health: "starting", State: "running" }]);
+        }
+        return JSON.stringify([{ Service: "store-sql", Health: "healthy", State: "running" }]);
+      },
+      onUpdate: (service, status) => {
+        updates.push(`${service}:${status}`);
+      },
+    });
+    expect(map.get("store-sql")).toBe("ready");
+    expect(updates).toEqual(["store-sql:pending", "store-sql:ready"]);
+  });
+
+  test("readComposeHealth / watch use ps -a", async () => {
+    let seen: readonly string[] = [];
+    await watchComposeHealth({
+      files: ["compose.yml"],
+      cwd: "/tmp",
+      env: {},
+      intervalMs: 1,
+      timeoutMs: 1,
+      sleep: async () => {},
+      run: async (args) => {
+        seen = args;
+        return JSON.stringify([{ Service: "ai", State: "exited", Status: "Exited (0) 1s ago" }]);
+      },
+      isDone: () => true,
+    });
+    expect(seen).toContain("-a");
+  });
+
+  test("startComposeHealthWatch reports ready → error", async () => {
+    let calls = 0;
+    const changes: string[] = [];
+    let stopWatch: (() => void) | undefined;
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("health watch timeout")), 2_000);
+      stopWatch = startComposeHealthWatch({
+        files: ["compose.yml"],
+        cwd: "/tmp",
+        env: {},
+        intervalMs: 1,
+        sleep: async () => {},
+        run: async () => {
+          calls += 1;
+          if (calls === 1) {
+            return JSON.stringify([{ Service: "ai", Health: "healthy", State: "running" }]);
+          }
+          return JSON.stringify([
+            { Service: "ai", State: "exited", Status: "Exited (0) 1 second ago" },
+          ]);
+        },
+        onChange: (_map, changed) => {
+          for (const c of changed) changes.push(`${c.service}:${c.status}`);
+          if (changes.includes("ai:ready") && changes.includes("ai:error")) {
+            clearTimeout(timer);
+            stopWatch?.();
+            resolve();
+          }
+        },
+      });
+    });
+    expect(changes).toContain("ai:ready");
+    expect(changes).toContain("ai:error");
+  });
+});

package/src/docker/compose-health.ts

@@ -0,0 +1,234 @@
+/**
+ * Read `docker compose ps` health for `oke dev` status dots.
+ */
+
+import type { DevStatus } from "../term.ts";
+
+/** One service row from `docker compose ps --format json`. */
+export type ComposePsRow = {
+  readonly Service?: string;
+  readonly State?: string;
+  readonly Health?: string;
+  readonly Status?: string;
+};
+
+/**
+ * Map a compose ps row to a {@link DevStatus}.
+ *
+ * @param row - Parsed ps line
+ */
+export function composeRowToStatus(row: ComposePsRow): DevStatus {
+  const health = (row.Health ?? "").trim().toLowerCase();
+  const state = (row.State ?? "").trim().toLowerCase();
+  if (health === "healthy") return "ready";
+  if (health === "unhealthy") return "error";
+  if (health === "starting") return "pending";
+  if (state === "running" || state === "up") return "ready";
+  if (
+    state === "exited" ||
+    state === "dead" ||
+    state === "stopped" ||
+    state === "restarting" ||
+    state === "removing" ||
+    state === "oomkilled"
+  ) {
+    return "error";
+  }
+  // Status text for stopped containers (`Exited (0) 2 seconds ago`).
+  const statusText = (row.Status ?? "").toLowerCase();
+  if (statusText.startsWith("exited") || statusText.startsWith("dead")) return "error";
+  if (state === "created" || state === "paused" || state.length === 0) return "pending";
+  // Status text like "Up 3 seconds (healthy)"
+  if (statusText.includes("(healthy)")) return "ready";
+  if (statusText.includes("(unhealthy)")) return "error";
+  if (statusText.includes("(health: starting)") || statusText.includes("(starting)")) {
+    return "pending";
+  }
+  if (statusText.startsWith("up")) return "ready";
+  return "pending";
+}
+
+/**
+ * Parse NDJSON or a JSON array from `docker compose ps --format json`.
+ *
+ * @param text - stdout
+ */
+export function parseComposePsJson(text: string): readonly ComposePsRow[] {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  if (trimmed.startsWith("[")) {
+    try {
+      const arr: unknown = JSON.parse(trimmed);
+      return Array.isArray(arr) ? (arr as ComposePsRow[]) : [];
+    } catch {
+      return [];
+    }
+  }
+  const rows: ComposePsRow[] = [];
+  for (const line of trimmed.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      rows.push(JSON.parse(t) as ComposePsRow);
+    } catch {
+      // skip garbage lines
+    }
+  }
+  return rows;
+}
+
+/**
+ * Build service-name → status from compose ps output.
+ *
+ * @param text - stdout from `docker compose ps --format json`
+ */
+export function composeHealthByService(text: string): Map<string, DevStatus> {
+  const map = new Map<string, DevStatus>();
+  for (const row of parseComposePsJson(text)) {
+    const name = row.Service?.trim();
+    if (!name) continue;
+    map.set(name, composeRowToStatus(row));
+  }
+  return map;
+}
+
+/** Options for {@link readComposeHealth}. */
+export type ReadComposeHealthOptions = {
+  readonly files: readonly string[];
+  readonly cwd: string;
+  readonly env: Record<string, string>;
+  /** Injectable runner (tests). */
+  readonly run?: (
+    args: readonly string[],
+    cwd: string,
+    env: Record<string, string>,
+  ) => Promise<string>;
+};
+
+/**
+ * Query `docker compose ps` and return health by Compose service name.
+ *
+ * @param opts - Compose files + cwd
+ */
+export async function readComposeHealth(
+  opts: ReadComposeHealthOptions,
+): Promise<Map<string, DevStatus>> {
+  const run =
+    opts.run ??
+    (async (args, cwd, env) => {
+      const proc = Bun.spawn(["docker", ...args], {
+        cwd,
+        stdout: "pipe",
+        stderr: "pipe",
+        env: { ...process.env, ...env },
+      });
+      const [stdout, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+      if (code !== 0) return "";
+      return stdout;
+    });
+  // `-a` includes stopped/exited — default `ps` hides them and ● would stay green.
+  const args = ["compose", ...opts.files.flatMap((f) => ["-f", f]), "ps", "-a", "--format", "json"];
+  const text = await run(args, opts.cwd, opts.env);
+  return composeHealthByService(text);
+}
+
+/** Options for {@link watchComposeHealth}. */
+export type WatchComposeHealthOptions = ReadComposeHealthOptions & {
+  /** Fired when a service status changes. */
+  readonly onUpdate?: (service: string, status: DevStatus) => void;
+  /** Stop early when this returns true. Default: every service ready or error. */
+  readonly isDone?: (map: Map<string, DevStatus>) => boolean;
+  readonly intervalMs?: number;
+  readonly timeoutMs?: number;
+  readonly sleep?: (ms: number) => Promise<void>;
+  readonly now?: () => number;
+};
+
+/**
+ * Poll compose health until ready/error/timeout, emitting per-service changes.
+ *
+ * @param opts - Compose target + callbacks
+ */
+export async function watchComposeHealth(
+  opts: WatchComposeHealthOptions,
+): Promise<Map<string, DevStatus>> {
+  const intervalMs = opts.intervalMs ?? 500;
+  const timeoutMs = opts.timeoutMs ?? 20_000;
+  const sleep = opts.sleep ?? ((ms: number) => Bun.sleep(ms));
+  const now = opts.now ?? Date.now;
+  const started = now();
+  const prev = new Map<string, DevStatus>();
+  let latest = new Map<string, DevStatus>();
+  const done =
+    opts.isDone ??
+    ((map) => map.size > 0 && [...map.values()].every((s) => s === "ready" || s === "error"));
+
+  for (;;) {
+    latest = await readComposeHealth(opts);
+    for (const [name, status] of latest) {
+      if (prev.get(name) !== status) {
+        prev.set(name, status);
+        opts.onUpdate?.(name, status);
+      }
+    }
+    if (done(latest)) return latest;
+    if (now() - started >= timeoutMs) return latest;
+    await sleep(intervalMs);
+  }
+}
+
+/** Options for {@link startComposeHealthWatch}. */
+export type StartComposeHealthWatchOptions = ReadComposeHealthOptions & {
+  /** Fired on every poll with the full map (and when any service changed). */
+  readonly onChange: (
+    map: Map<string, DevStatus>,
+    changed: readonly { readonly service: string; readonly status: DevStatus }[],
+  ) => void;
+  readonly intervalMs?: number;
+  readonly sleep?: (ms: number) => Promise<void>;
+};
+
+/**
+ * Poll compose health for the life of an `oke dev` session.
+ *
+ * @param opts - Compose target + change callback
+ * @returns Stop function
+ */
+export function startComposeHealthWatch(opts: StartComposeHealthWatchOptions): () => void {
+  const intervalMs = opts.intervalMs ?? 2_000;
+  const sleep = opts.sleep ?? ((ms: number) => Bun.sleep(ms));
+  let stopped = false;
+  const prev = new Map<string, DevStatus>();
+
+  const tick = async (): Promise<void> => {
+    while (!stopped) {
+      const latest = await readComposeHealth(opts);
+      if (stopped) return;
+      const changed: { service: string; status: DevStatus }[] = [];
+      for (const [name, status] of latest) {
+        if (prev.get(name) !== status) {
+          prev.set(name, status);
+          changed.push({ service: name, status });
+        }
+      }
+      // Services that vanished from ps -a (removed) → treat as error once.
+      for (const name of [...prev.keys()]) {
+        if (!latest.has(name)) {
+          prev.delete(name);
+          changed.push({ service: name, status: "error" });
+          latest.set(name, "error");
+        }
+      }
+      if (changed.length > 0 || prev.size === 0) {
+        for (const [name, status] of latest) prev.set(name, status);
+        opts.onChange(latest, changed);
+      }
+      await sleep(intervalMs);
+    }
+  };
+
+  void tick();
+  return () => {
+    stopped = true;
+  };
+}

package/src/docker/compose.ts

@@ -133,13 +133,14 @@ export function emitComposeLayers(
   for (const spec of specs) {
     const recipe = recipeFor(spec.image, recipes);
     const applied = recipe.apply(spec);
+    const bindPrefix = applied.publishBind ? `${applied.publishBind}:` : "";
     const ports = [
-      `${spec.hostPort}:${spec.port}`,
+      `${bindPrefix}${spec.hostPort}:${spec.port}`,
       ...(applied.extraPorts ?? []).map((p) => {
         const hostPort = options.instanceId
           ? extraHostPortForInstance(spec.role, p.host, options.instanceId)
           : p.host;
-        return `${hostPort}:${p.container}`;
+        return `${bindPrefix}${hostPort}:${p.container}`;
       }),
     ];
     const service: Record<string, unknown> = {
@@ -156,6 +157,8 @@ export function emitComposeLayers(
     if (applied.user) service.user = applied.user;
     if (applied.ulimits) service.ulimits = applied.ulimits;
     if (applied.labels) service.labels = applied.labels;
+    if (applied.ipc) service.ipc = applied.ipc;
+    if (applied.deploy) service.deploy = applied.deploy;
     if (applied.dependsOn) {
       const deps = { ...applied.dependsOn };
       if (!includeApp) delete deps.app;
@@ -357,9 +360,14 @@ export function buildStackEnv(
       env.SMTP_PORT = String(spec.hostPort);
       if (uiHost !== undefined) env.MAILPIT_UI_URL = `http://${host}:${uiHost}`;
     } else if (spec.role === "vault") {
-      // Token is minted by the bootstrap — never a generated password here.
+      // Token is minted by OpenBao bootstrap and preserved via stack controls —
+      // never a generated password here.
       env[`${prefix}_URL`] = url;
       env.OKE_VAULT_URL = url;
+      if (controls.OKE_VAULT_TOKEN) {
+        env.OKE_VAULT_TOKEN = controls.OKE_VAULT_TOKEN;
+        env.OKE_VAULT_MOUNT = controls.OKE_VAULT_MOUNT ?? "secret";
+      }
     } else if (spec.role === "store.index") {
       // Meilisearch: standalone HTTP URL + the generated master key.
       env[`${prefix}_URL`] = url;
@@ -412,14 +420,15 @@ const ROLE_SECTION_TITLE: Readonly<Record<string, string>> = {
   "channel.email": "channel.email — Mailpit (SMTP + UI)",
   signal: "signal — message bus",
   vault: "vault — OpenBao",
-  ai: "ai — Ollama (local models)",
+  ai: "ai — local inference (llama.cpp / Ollama / vLLM / SGLang)",
   proxy: "proxy — TLS terminator (Caddy / Traefik)",
 };
 
 /** Friendly aliases emitted beside their role block. */
 const ROLE_ALIASES: Readonly<Record<string, readonly string[]>> = {
   "store.sql": ["DATABASE_URL", "PGDATA", "POSTGRES_INITDB_ARGS"],
-  pgdog: ["OKE_PGDOG_URL"],
+  // OKE_PGDOG_URL is already emitted as `${prefix}_URL`.
+  pgdog: [],
   "store.kv": ["REDIS_URL", "OKE_STORE_KV_MAXMEMORY", "OKE_STORE_KV_MAXMEMORY_POLICY"],
   "store.files": [
     "S3_ACCESS_KEY_ID",
@@ -442,8 +451,11 @@ const ROLE_ALIASES: Readonly<Record<string, readonly string[]>> = {
     "MP_SMTP_AUTH_ACCEPT_ANY",
     "MP_SMTP_AUTH_ALLOW_INSECURE",
   ],
-  ai: ["OKE_AI_URL", "OKE_AI_MODEL"],
+  // OKE_AI_URL is already emitted as `${prefix}_URL` — do not alias it again.
+  ai: ["OKE_AI_MODEL"],
   proxy: ["OKE_PROXY_HOST", "OKE_PROXY_ACME_EMAIL"],
+  vault: ["OKE_VAULT_TOKEN", "OKE_VAULT_MOUNT"],
+  "store.index": ["OKE_STORE_INDEX_KEY"],
 };
 
 /** Optional controls documented in `.env.docker` and preserved on regeneration. */
@@ -458,8 +470,8 @@ const ROLE_CONTROL_EXAMPLES: Readonly<Record<string, readonly string[]>> = {
     "MP_SMTP_AUTH_ACCEPT_ANY=1",
     "MP_SMTP_AUTH_ALLOW_INSECURE=1",
   ],
-  // qwen3.5:9b is a balanced local-dev starting point — override freely.
-  ai: ["OKE_AI_MODEL=qwen3.5:9b"],
+  // Curated Docker Hub `ai/` model id for llama.cpp; Ollama tags differ.
+  ai: ["OKE_AI_MODEL=smollm2"],
   proxy: ["OKE_PROXY_HOST=localhost", "OKE_PROXY_ACME_EMAIL=admin@example.com"],
 };
 
@@ -481,6 +493,10 @@ function roleFromEnvKey(key: string): string | undefined {
   if (key === "OKE_PROXY_URL" || key === "OKE_PROXY_HOST" || key === "OKE_PROXY_ACME_EMAIL") {
     return "proxy";
   }
+  if (key === "OKE_VAULT_TOKEN" || key === "OKE_VAULT_MOUNT" || key === "OKE_VAULT_URL") {
+    return "vault";
+  }
+  if (key === "OKE_STORE_INDEX_KEY" || key === "OKE_STORE_INDEX_URL") return "store.index";
   return undefined;
 }
 

package/src/docker/derive.ts

@@ -12,6 +12,11 @@ import {
 } from "./compose.ts";
 import { emitDockerfile } from "./dockerfile.ts";
 import { buildCaddyfile } from "./recipes/caddy.ts";
+import {
+  buildLlamaCppEntrypoint,
+  LLAMA_CPP_ENTRYPOINT_FILE,
+  llamaCpp,
+} from "./recipes/llama-cpp.ts";
 import { buildPgDogToml, buildPgDogUsersToml } from "./recipes/pgdog.ts";
 import type { DeriveOptions, DeriveResult, GeneratedFile } from "./types.ts";
 import { DEFAULT_DOCKER_DIR } from "./types.ts";
@@ -45,12 +50,21 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
     path: "Dockerfile",
     content: emitDockerfile({ appPort: normalised.appPort }),
   };
+  const stackEnv = buildStackEnv(
+    specs,
+    normalised.recipes ?? [],
+    normalised.host ?? "127.0.0.1",
+    normalised.controls,
+    normalised.instanceId,
+  );
+
   // Always emit Dockerfile for deploy; stack-only runs ignore it.
   const files = [
     dockerfile,
     ...composeFilesContent,
     ...pgdogConfigFiles(specs),
     ...proxyConfigFiles(specs, normalised.appPort),
+    ...llamaCppEntrypointFiles(specs),
   ];
 
   for (const f of files) {
@@ -62,17 +76,26 @@ export function deriveInfrastructure(options: DeriveOptions): DeriveResult {
     }
   }
 
-  const stackEnv = buildStackEnv(
-    specs,
-    normalised.recipes ?? [],
-    normalised.host ?? "127.0.0.1",
-    normalised.controls,
-    normalised.instanceId,
-  );
-
   return { specs, files, stackEnv, composeFiles };
 }
 
+/**
+ * Emit `llama-entrypoint.sh` when the AI role is llama.cpp so first boot can
+ * Hub-pull then serve single-model (router `--docker-repo` hangs on b10290+).
+ *
+ * @param specs - Normalised services
+ */
+function llamaCppEntrypointFiles(specs: DeriveResult["specs"]): GeneratedFile[] {
+  const ai = specs.find((s) => s.role === "ai");
+  if (!ai || !llamaCpp.match(ai.image)) return [];
+  return [
+    {
+      path: LLAMA_CPP_ENTRYPOINT_FILE,
+      content: buildLlamaCppEntrypoint(),
+    },
+  ];
+}
+
 /**
  * Emit PgDog TOML configs when both `pgdog` and `store.sql` are in the stack.
  *
@@ -88,7 +111,10 @@ function pgdogConfigFiles(specs: DeriveResult["specs"]): GeneratedFile[] {
   return [
     {
       path: "pgdog.toml",
-      content: buildPgDogToml({ database: sql.credentials.database }),
+      content: buildPgDogToml({
+        database: sql.credentials.database,
+        postgresPort: sql.port,
+      }),
     },
     {
       path: "users.toml",