okengine 0.9.0 → 0.10.0

package/src/docker/docker.test.ts

@@ -15,6 +15,7 @@ import {
   buildPgDogUsersToml,
   builtinRecipes,
   caddy,
+  cockroach,
   deriveInfrastructure,
   dragonfly,
   emitDockerfile,
@@ -26,11 +27,25 @@ import {
   resolveStack,
   SOCKET_PROXY_IMAGE,
   SOCKET_PROXY_SERVICE,
+  timescale,
   traefik,
   traefikAppLabels,
   valkey,
   writeDerivedFiles,
+  yugabyte,
+  ensureOllamaModel,
+  llamaCpp,
+  LLAMA_CPP_IMAGE,
+  LLAMA_CPP_MIN_SAFE_BUILD,
+  OllamaPullError,
+  OLLAMA_IMAGE,
+  OLLAMA_MIN_SAFE_VERSION,
+  sglang,
+  SGLANG_IMAGE,
+  vllm,
+  VLLM_IMAGE,
   type ImageRecipe,
+  type OllamaFetch,
   type ServiceSpec,
 } from "./index.ts";
 
@@ -152,6 +167,95 @@ describe("image recipes", () => {
     expect(derived.stackEnv.REDIS_URL).toContain("redis://");
   });
 
+  test("cockroach matches official image, port 26257, COCKROACH_* env, sslmode=require URL", () => {
+    const image = "cockroachdb/cockroach:v25.2.0";
+    expect(recipeFor(image).id).toBe("cockroach");
+    expect(cockroach.match(image)).toBe(true);
+    expect(postgres.match(image)).toBe(false);
+    const spec: ServiceSpec = {
+      role: "store.sql",
+      serviceName: "store-sql",
+      image,
+      port: 26257,
+      hostPort: 5432,
+      credentials: fixedCreds["store.sql"],
+    };
+    const applied = recipeFor(spec.image).apply(spec);
+    expect(applied.command).toEqual(["start-single-node", "--accept-sql-without-tls"]);
+    expect(applied.environment?.COCKROACH_USER).toBe("${OKE_STORE_SQL_USER}");
+    expect(applied.environment?.COCKROACH_PASSWORD).toBe("${OKE_STORE_SQL_PASSWORD}");
+    expect(applied.environment?.COCKROACH_DATABASE).toBe("${OKE_STORE_SQL_DB}");
+    expect(applied.extraPorts).toEqual([{ host: 8080, container: 8080 }]);
+    expect(applied.volumes?.[0]).toContain("/cockroach/cockroach-data");
+    const url = recipeFor(spec.image).url(spec, {
+      host: "127.0.0.1",
+      port: 5432,
+      ...fixedCreds["store.sql"],
+    });
+    expect(url).toContain("sslmode=require");
+    expect(url).toContain(":5432/");
+
+    const derived = deriveInfrastructure({
+      images: { "store.sql": image },
+      credentials: { "store.sql": fixedCreds["store.sql"] },
+    });
+    expect(derived.specs[0]!.port).toBe(26257);
+    expect(derived.specs[0]!.hostPort).toBe(5432);
+    const sqlYml = derived.files.find((f) => f.path === "compose.store.sql.yml")?.content ?? "";
+    expect(sqlYml).toContain("26257");
+    expect(sqlYml).toContain("COCKROACH_");
+    expect(derived.stackEnv.DATABASE_URL).toContain("sslmode=require");
+  });
+
+  test("yugabyte matches official image, YSQL on 5433, YSQL_* env", () => {
+    const image = "yugabytedb/yugabyte:2025.1.0.0-b100";
+    expect(recipeFor(image).id).toBe("yugabyte");
+    expect(yugabyte.match(image)).toBe(true);
+    const spec: ServiceSpec = {
+      role: "store.sql",
+      serviceName: "store-sql",
+      image,
+      port: 5433,
+      hostPort: 5432,
+      credentials: fixedCreds["store.sql"],
+    };
+    const applied = recipeFor(spec.image).apply(spec);
+    expect(String(applied.command)).toContain("yugabyted");
+    expect(applied.environment?.YSQL_USER).toBe("${OKE_STORE_SQL_USER}");
+    expect(applied.environment?.YSQL_PASSWORD).toBe("${OKE_STORE_SQL_PASSWORD}");
+    expect(applied.environment?.YSQL_DB).toBe("${OKE_STORE_SQL_DB}");
+    expect(applied.volumes?.[0]).toContain("/home/yugabyte/yb_data");
+    const url = recipeFor(spec.image).url(spec, {
+      host: "127.0.0.1",
+      port: 5432,
+      ...fixedCreds["store.sql"],
+    });
+    expect(url).toStartWith("postgres://oke:");
+
+    const derived = deriveInfrastructure({
+      images: { "store.sql": image },
+      credentials: { "store.sql": fixedCreds["store.sql"] },
+    });
+    expect(derived.specs[0]!.port).toBe(5433);
+    const sqlYml = derived.files.find((f) => f.path === "compose.store.sql.yml")?.content ?? "";
+    expect(sqlYml).toContain("5433");
+    expect(sqlYml).toContain("YSQL_");
+  });
+
+  test("timescale matches ahead of generic postgres with the same POSTGRES_* contract", () => {
+    const image = "timescale/timescaledb:latest-pg17";
+    expect(recipeFor(image).id).toBe("timescale");
+    expect(timescale.match(image)).toBe(true);
+    expect(postgres.match(image)).toBe(false);
+    const derived = deriveInfrastructure({
+      images: { "store.sql": image },
+      credentials: { "store.sql": fixedCreds["store.sql"] },
+    });
+    const sqlYml = derived.files.find((f) => f.path === "compose.store.sql.yml")?.content ?? "";
+    expect(sqlYml).toContain("POSTGRES_USER");
+    expect(derived.stackEnv.DATABASE_URL).toContain("postgres://");
+  });
+
   test("pgdog matches the official image and waits on store-sql", () => {
     expect(recipeFor("ghcr.io/pgdogdev/pgdog:v0.1.51").id).toBe("pgdog");
     expect(pgdog.match("ghcr.io/pgdogdev/pgdog:main")).toBe(true);
@@ -215,25 +319,27 @@ describe("image recipes", () => {
     expect(url).toBe("http://127.0.0.1:7700");
   });
 
-  test("ollama matches the official image, pulls configured model, emits http URL", () => {
-    expect(recipeFor("ollama/ollama:latest").id).toBe("ollama");
+  test("ollama matches the official image, serves on 11434, emits http URL", () => {
+    expect(recipeFor(OLLAMA_IMAGE).id).toBe("ollama");
+    expect(OLLAMA_IMAGE).not.toContain("latest");
+    expect(OLLAMA_MIN_SAFE_VERSION).toBe("0.17.1");
     const spec: ServiceSpec = {
       role: "ai",
       serviceName: "ai",
-      image: "ollama/ollama:latest",
+      image: OLLAMA_IMAGE,
       port: 11434,
       hostPort: 11434,
       credentials: { user: "oke", password: "unused", database: "oke" },
     };
     const applied = recipeFor(spec.image).apply(spec);
     expect(applied.environment?.OKE_AI_MODEL).toBe("${OKE_AI_MODEL:-qwen3.5:9b}");
+    expect(applied.environment?.OLLAMA_HOST).toBe("0.0.0.0:11434");
+    expect(applied.publishBind).toBe("127.0.0.1");
     expect(applied.volumes).toContain("ai-data:/root/.ollama");
     expect(applied.healthcheck?.test.join(" ")).toContain("ollama list");
-    expect(String(applied.command)).toContain("ollama pull");
-    // Compose must see `$$` so `$pid` / `$i` are not treated as project env.
-    expect(String(applied.command)).toContain("pid=$$!");
-    expect(String(applied.command)).toContain("wait $$pid");
-    expect(String(applied.command)).not.toMatch(/(?<!\$)\$pid\b/);
+    // Pull is host-side via ensureOllamaModel — never a boot `ollama pull` CLI.
+    expect(applied.command).toBeUndefined();
+    expect(applied.entrypoint).toBeUndefined();
     const url = recipeFor(spec.image).url(spec, {
       host: "127.0.0.1",
       port: 11434,
@@ -244,6 +350,153 @@ describe("image recipes", () => {
     expect(url).toBe("http://127.0.0.1:11434");
   });
 
+  test("llama-cpp is the default local AI recipe — OpenAI /v1, loopback publish, pinned ≥ b8146", () => {
+    expect(recipeFor(LLAMA_CPP_IMAGE).id).toBe("llama-cpp");
+    expect(LLAMA_CPP_IMAGE).not.toContain("latest");
+    const build = Number(/server-b(\d+)/.exec(LLAMA_CPP_IMAGE)?.[1]);
+    expect(build).toBeGreaterThanOrEqual(LLAMA_CPP_MIN_SAFE_BUILD);
+    const spec: ServiceSpec = {
+      role: "ai",
+      serviceName: "ai",
+      image: LLAMA_CPP_IMAGE,
+      port: 8080,
+      hostPort: 8080,
+      credentials: { user: "oke", password: "unused", database: "oke" },
+    };
+    const applied = llamaCpp.apply(spec);
+    expect(applied.publishBind).toBe("127.0.0.1");
+    // Never put docker-repo / models-preset / interpolated OKE_AI_MODEL in
+    // service environment — router children recurse / OOM; Compose ${} would
+    // also override env_file from an empty host shell.
+    expect(applied.environment?.LLAMA_ARG_MODELS_PRESET).toBeUndefined();
+    expect(applied.environment?.LLAMA_ARG_DOCKER_REPO).toBeUndefined();
+    expect(applied.environment?.OKE_AI_MODEL).toBeUndefined();
+    expect(applied.entrypoint).toEqual(["/usr/bin/python3", "/oke/llama-entrypoint.py"]);
+    expect(applied.command).toBeUndefined();
+    expect(applied.volumes?.some((v) => v.includes("llama-entrypoint.py"))).toBe(true);
+    expect(applied.extraPorts).toBeUndefined();
+    expect(llamaCpp.url(spec, { host: "127.0.0.1", port: 8080, ...spec.credentials })).toBe(
+      "http://127.0.0.1:8080/v1",
+    );
+  });
+
+  test("vllm recipe is GPU-aware, OpenAI /v1, loopback publish, never latest", () => {
+    expect(recipeFor(VLLM_IMAGE).id).toBe("vllm");
+    expect(VLLM_IMAGE).not.toContain("latest");
+    const spec: ServiceSpec = {
+      role: "ai",
+      serviceName: "ai",
+      image: VLLM_IMAGE,
+      port: 8000,
+      hostPort: 8000,
+      credentials: { user: "oke", password: "unused", database: "oke" },
+    };
+    const applied = vllm.apply(spec);
+    expect(applied.publishBind).toBe("127.0.0.1");
+    expect(applied.ipc).toBe("host");
+    expect(JSON.stringify(applied.deploy)).toContain("nvidia");
+    expect(vllm.url(spec, { host: "127.0.0.1", port: 8000, ...spec.credentials })).toBe(
+      "http://127.0.0.1:8000/v1",
+    );
+  });
+
+  test("sglang recipe is GPU-aware, OpenAI /v1, loopback publish, never latest", () => {
+    expect(recipeFor(SGLANG_IMAGE).id).toBe("sglang");
+    expect(SGLANG_IMAGE).not.toContain("latest");
+    const spec: ServiceSpec = {
+      role: "ai",
+      serviceName: "ai",
+      image: SGLANG_IMAGE,
+      port: 30000,
+      hostPort: 30000,
+      credentials: { user: "oke", password: "unused", database: "oke" },
+    };
+    const applied = sglang.apply(spec);
+    expect(applied.publishBind).toBe("127.0.0.1");
+    expect(applied.ipc).toBe("host");
+    expect(JSON.stringify(applied.deploy)).toContain("nvidia");
+    expect(sglang.url(spec, { host: "127.0.0.1", port: 30000, ...spec.credentials })).toBe(
+      "http://127.0.0.1:30000/v1",
+    );
+  });
+
+  test("ensureOllamaModel POSTs /api/pull to the container base URL (not a host CLI)", async () => {
+    const calls: { url: string; method: string; body?: string }[] = [];
+    const fetchFn: OllamaFetch = async (input, init) => {
+      const url = String(input);
+      const method = (init?.method ?? "GET").toUpperCase();
+      const body = typeof init?.body === "string" ? init.body : undefined;
+      calls.push({ url, method, ...(body !== undefined ? { body } : {}) });
+      if (url.endsWith("/api/tags") && method === "GET") {
+        return new Response(JSON.stringify({ models: [] }), { status: 200 });
+      }
+      if (url.endsWith("/api/pull") && method === "POST") {
+        expect(body).toContain('"model":"qwen3.5:9b"');
+        expect(body).toContain('"stream":true');
+        return new Response(`${JSON.stringify({ status: "success" })}\n`, { status: 200 });
+      }
+      return new Response("unexpected", { status: 500 });
+    };
+
+    await ensureOllamaModel({
+      url: "http://127.0.0.1:11434",
+      model: "qwen3.5:9b",
+      fetch: fetchFn,
+      readyTimeoutMs: 2_000,
+      pullTimeoutMs: 5_000,
+    });
+
+    expect(
+      calls.some((c) => c.url === "http://127.0.0.1:11434/api/tags" && c.method === "GET"),
+    ).toBe(true);
+    const pull = calls.find((c) => c.url === "http://127.0.0.1:11434/api/pull");
+    expect(pull?.method).toBe("POST");
+    expect(pull?.body).toBe(JSON.stringify({ model: "qwen3.5:9b", stream: true }));
+    // No host-side `ollama` binary assumption — only HTTP to the given URL.
+    expect(calls.every((c) => c.url.startsWith("http://127.0.0.1:11434/"))).toBe(true);
+  });
+
+  test("ensureOllamaModel skips pull when /api/tags already lists the model", async () => {
+    const calls: string[] = [];
+    const statuses: string[] = [];
+    const fetchFn: OllamaFetch = async (input, init) => {
+      const url = String(input);
+      const method = (init?.method ?? "GET").toUpperCase();
+      calls.push(`${method} ${url}`);
+      if (url.endsWith("/api/tags")) {
+        return new Response(JSON.stringify({ models: [{ name: "gemma4:e4b" }] }), {
+          status: 200,
+        });
+      }
+      return new Response("should not pull", { status: 500 });
+    };
+
+    await ensureOllamaModel({
+      url: "http://127.0.0.1:23100",
+      model: "gemma4:e4b",
+      fetch: fetchFn,
+      readyTimeoutMs: 2_000,
+      onStatus: (line) => statuses.push(line),
+    });
+
+    expect(calls.some((c) => c.includes("/api/pull"))).toBe(false);
+    expect(statuses.some((s) => /already has gemma4:e4b/.test(s))).toBe(true);
+  });
+
+  test("ensureOllamaModel fails loud when the container API never becomes ready", async () => {
+    const fetchFn: OllamaFetch = async () => {
+      throw new Error("connection refused");
+    };
+    await expect(
+      ensureOllamaModel({
+        url: "http://127.0.0.1:59999",
+        model: "qwen3.5:9b",
+        fetch: fetchFn,
+        readyTimeoutMs: 800,
+      }),
+    ).rejects.toBeInstanceOf(OllamaPullError);
+  });
+
   test("a new image recipe is ≤15 lines", async () => {
     const src = await Bun.file(`${import.meta.dir}/recipes/postgres.ts`).text();
     const exportLines = src
@@ -519,18 +772,57 @@ describe("deriveInfrastructure", () => {
     expect(result.stackEnv.DATABASE_URL).toBeUndefined();
   });
 
-  test("ai ollama emits OKE_AI_URL and documents the default model control", () => {
+  test("ai ollama emits OKE_AI_URL, loopback publish, and never binds 0.0.0.0 on the host", () => {
     const result = deriveInfrastructure({
-      images: { ai: "ollama/ollama:latest" },
+      images: { ai: OLLAMA_IMAGE },
       app: "skyport",
     });
     const yml = result.files.find((f) => f.path === "compose.ai.yml")!.content;
-    expect(yml).toContain("ollama/ollama:latest");
+    expect(yml).toContain(OLLAMA_IMAGE);
     expect(yml).toContain("OKE_AI_MODEL");
     expect(yml).toContain("qwen3.5:9b");
+    expect(yml).toContain("127.0.0.1:11434:11434");
+    expect(yml).not.toMatch(/ports:\s*\n\s*-\s*"?11434:11434"?/);
     expect(result.stackEnv.OKE_AI_URL).toBe("http://127.0.0.1:11434");
     const envText = formatStackEnv(result.stackEnv);
-    expect(envText).toContain("# ── ai — Ollama");
+    expect(envText).toContain("# ── ai — local inference");
+    expect(envText.match(/^OKE_AI_URL=/gm)?.length).toBe(1);
+  });
+
+  test("ai llama-cpp (default) emits /v1 URL and loopback-only publish", () => {
+    const result = deriveInfrastructure({
+      images: { ai: LLAMA_CPP_IMAGE },
+      app: "skyport",
+      controls: { OKE_AI_MODEL: "gemma4:e4b-q4_K_M" },
+    });
+    const yml = result.files.find((f) => f.path === "compose.ai.yml")!.content;
+    expect(yml).toContain(LLAMA_CPP_IMAGE);
+    expect(yml).toContain("127.0.0.1:8080:8080");
+    expect(yml).toContain("llama-entrypoint.py");
+    expect(yml).toContain("/oke/llama-entrypoint.py");
+    expect(yml).not.toMatch(/ports:\s*\n\s*-\s*"?8080:8080"?/);
+    expect(result.stackEnv.OKE_AI_URL).toBe("http://127.0.0.1:8080/v1");
+    expect(result.stackEnv.OKE_AI_MODEL).toBe("gemma4:e4b-q4_K_M");
+    const entry = result.files.find((f) => f.path === "llama-entrypoint.py")!.content;
+    expect(entry).toContain("llama download");
+    expect(entry).toContain("org.cncf.model.filepath");
+    expect(entry).toContain("CNCF / Hub registry pull");
+    expect(entry).toContain("llama-server");
+    expect(entry).toContain("--alias");
+    expect(yml).not.toContain("--models-preset");
+  });
+
+  test("ai vllm and sglang emit loopback publish + GPU deploy", () => {
+    for (const [image, port, path] of [
+      [VLLM_IMAGE, 8000, "compose.ai.yml"],
+      [SGLANG_IMAGE, 30000, "compose.ai.yml"],
+    ] as const) {
+      const result = deriveInfrastructure({ images: { ai: image }, app: "skyport" });
+      const yml = result.files.find((f) => f.path === path)!.content;
+      expect(yml).toContain(`127.0.0.1:${port}:${port}`);
+      expect(yml).toContain("nvidia");
+      expect(result.stackEnv.OKE_AI_URL).toBe(`http://127.0.0.1:${port}/v1`);
+    }
   });
 
   test("emits protocol-specific env keys plus optional control notes", () => {

package/src/docker/helpers.ts

@@ -15,6 +15,62 @@ export function credEnv(spec: ServiceSpec, field: "USER" | "PASSWORD" | "DB"): s
   return `\${${key}}`;
 }
 
+/** Postgres-protocol env shape (`POSTGRES_*`) — shared by postgres / supabase / timescale. */
+export function postgresEnv(s: ServiceSpec): Record<string, string> {
+  return {
+    POSTGRES_USER: credEnv(s, "USER"),
+    POSTGRES_PASSWORD: credEnv(s, "PASSWORD"),
+    POSTGRES_DB: credEnv(s, "DB"),
+  };
+}
+
+/** Postgres-protocol healthcheck — shared by postgres / supabase / timescale. */
+export const postgresHealth = {
+  test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER"],
+  interval: "5s",
+  timeout: "3s",
+  retries: 10,
+} as const;
+
+/** CockroachDB single-node env (`COCKROACH_*`) — used only when the data dir is empty. */
+export function cockroachEnv(s: ServiceSpec): Record<string, string> {
+  return {
+    COCKROACH_USER: credEnv(s, "USER"),
+    COCKROACH_PASSWORD: credEnv(s, "PASSWORD"),
+    COCKROACH_DATABASE: credEnv(s, "DB"),
+  };
+}
+
+/** CockroachDB readiness — DB Console `/health?ready=1`. */
+export const cockroachHealth = {
+  test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/health?ready=1 >/dev/null 2>&1 || exit 1"],
+  interval: "5s",
+  timeout: "5s",
+  retries: 20,
+  start_period: "15s",
+} as const;
+
+/** YugabyteDB YSQL env — `YSQL_PASSWORD` enables authentication automatically. */
+export function yugabyteEnv(s: ServiceSpec): Record<string, string> {
+  return {
+    YSQL_USER: credEnv(s, "USER"),
+    YSQL_PASSWORD: credEnv(s, "PASSWORD"),
+    YSQL_DB: credEnv(s, "DB"),
+  };
+}
+
+/** YugabyteDB YSQL readiness — cluster boot is slow; long `start_period`. */
+export const yugabyteHealth = {
+  test: [
+    "CMD-SHELL",
+    'PGPASSWORD="$$YSQL_PASSWORD" bin/ysqlsh -h 127.0.0.1 -p 5433 -U "$$YSQL_USER" -d "$$YSQL_DB" -c "SELECT 1" >/dev/null 2>&1 || exit 1',
+  ],
+  interval: "10s",
+  timeout: "10s",
+  retries: 30,
+  start_period: "90s",
+} as const;
+
 /**
  * Compose service name for a role (`store.sql` → `store-sql`).
  *

package/src/docker/index.ts

@@ -15,6 +15,7 @@ export type {
   ImageRecipe,
   RecipeApplyResult,
   RecipeExtraPort,
+  RecipePublishBind,
   RecipeUlimit,
   ServiceCredentials,
   ServiceEndpoint,
@@ -39,21 +40,72 @@ export { deriveInfrastructure, writeDerivedFiles } from "./derive.ts";
 export { emitDockerfile } from "./dockerfile.ts";
 export { credEnv, envPrefix, serviceNameFor } from "./helpers.ts";
 export { generateCredentials } from "./credentials.ts";
+export {
+  ensureOllamaModel,
+  normalizeOllamaPullUrl,
+  ollamaTagsInclude,
+  parseOllamaTagsNames,
+  OllamaPullError,
+  type EnsureOllamaModelOptions,
+  type OllamaFetch,
+} from "./ollama-pull.ts";
+export {
+  aiModelIdsMatch,
+  formatAiModelStatusMessage,
+  normalizeAiProbeUrl,
+  probeAiModelStatus,
+  startAiModelWatch,
+  statusFromOllamaTags,
+  statusFromOpenAiModels,
+  type AiModelFetch,
+  type AiModelPhase,
+  type AiModelProbeKind,
+  type AiModelStatus,
+  type ProbeAiModelStatusOptions,
+  type StartAiModelWatchOptions,
+} from "./ai-model-status.ts";
+export {
+  composeHealthByService,
+  composeRowToStatus,
+  parseComposePsJson,
+  readComposeHealth,
+  startComposeHealthWatch,
+  watchComposeHealth,
+  type ComposePsRow,
+  type ReadComposeHealthOptions,
+  type StartComposeHealthWatchOptions,
+  type WatchComposeHealthOptions,
+} from "./compose-health.ts";
 export {
   builtinRecipes,
   caddy,
+  cockroach,
   dragonfly,
+  llamaCpp,
+  buildLlamaCppEntrypoint,
+  LLAMA_CPP_ENTRYPOINT_FILE,
+  LLAMA_CPP_ENTRYPOINT_MOUNT,
+  LLAMA_CPP_IMAGE,
+  LLAMA_CPP_MIN_SAFE_BUILD,
   mailpit,
   meilisearch,
   ollama,
+  OLLAMA_IMAGE,
+  OLLAMA_MIN_SAFE_VERSION,
   openbao,
   pgdog,
   postgres,
   recipeFor,
   redis,
   rustfs,
+  sglang,
+  SGLANG_IMAGE,
+  timescale,
   traefik,
   valkey,
+  vllm,
+  VLLM_IMAGE,
+  yugabyte,
 } from "./recipes/index.ts";
 export { CADDY_APP_SERVICE, buildCaddyfile } from "./recipes/caddy.ts";
 export { PGDOG_BACKEND_SERVICE, buildPgDogToml, buildPgDogUsersToml } from "./recipes/pgdog.ts";