okengine 0.6.0 → 0.7.0

package/src/cli/ai-setup/ai-setup.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Unit tests for `oke ai setup` catalog, detect, and apply.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { applyAiSetup, renderAiTs, upsertAiDrivers, upsertEnv } from "./apply.ts";
+import { cloudChatModels, recommendChatModel, recommendCloudChat } from "./catalog.ts";
+import { isInstalled, parseOllamaList } from "./detect-ollama.ts";
+import { parseAiSetupArgs } from "./index.ts";
+
+describe("catalog", () => {
+  test("recommendChatModel respects RAM tiers", () => {
+    expect(recommendChatModel(8).id).toBe("gemma4:e4b");
+    expect(recommendChatModel(16).ramGb).toBeLessThanOrEqual(16);
+    expect(recommendChatModel(null).recommended).toBe(true);
+  });
+
+  test("cloud providers ship short curated chat lists + recommended", () => {
+    expect(cloudChatModels("openai").length).toBeGreaterThan(0);
+    expect(cloudChatModels("anthropic").some((m) => m.recommended)).toBe(true);
+    expect(recommendCloudChat("openai")).toBe("gpt-4o-mini");
+    expect(recommendCloudChat("anthropic")).toContain("claude");
+  });
+});
+
+describe("detect-ollama", () => {
+  test("parseOllamaList skips header", () => {
+    const out = parseOllamaList(`NAME           ID      SIZE
+qwen3.5:9b     abc     5.0 GB
+nomic-embed-text  def  274 MB
+`);
+    expect(out).toEqual(["qwen3.5:9b", "nomic-embed-text"]);
+  });
+
+  test("isInstalled matches mlx suffixes", () => {
+    expect(isInstalled("qwen3.5:9b", ["qwen3.5:9b-mlx"])).toBe(true);
+    expect(isInstalled("gemma4:e4b", ["qwen3.5:9b"])).toBe(false);
+  });
+});
+
+describe("apply", () => {
+  test("upsertAiDrivers inserts after channel (sibling, not nested)", () => {
+    const src = `export default defineConfig({
+  drivers: {
+    channel: {
+      email: {
+        local: "console",
+        docker: "smtp",
+        test: "console",
+        prod: "smtp",
+      },
+    },
+  },
+  images: {},
+});
+`;
+    const next = upsertAiDrivers(src, "ollama");
+    expect(next).toMatch(/^ {4}ai:\s*\{/m);
+    expect(next).toContain('local: "ollama"');
+    const channel = next.match(/^ {4}channel:\s*\{[\s\S]*?\n {4}\},?\n/m)?.[0] ?? "";
+    expect(channel).toContain("email:");
+    expect(channel).not.toContain("ai:");
+  });
+
+  test("upsertEnv uncomment / set", () => {
+    const env = `# OKE_AI_DRIVER=mock\nOKE_AI_URL=http://x\n`;
+    expect(upsertEnv(env, "OKE_AI_DRIVER", "ollama")).toContain("OKE_AI_DRIVER=ollama");
+  });
+
+  test("renderAiTs includes vision + embed", () => {
+    const ts = renderAiTs({
+      driver: "ollama",
+      chatModel: "gemma4:e4b",
+      visionModel: "qwen3-vl:4b",
+      embedModel: "nomic-embed-text",
+    });
+    expect(ts).toContain('ai.model("smart"');
+    expect(ts).toContain('ai.model("vision"');
+    expect(ts).toContain("docsEmbed");
+  });
+
+  test("applyAiSetup writes config, env, ai.ts", () => {
+    const dir = mkdtempSync(join(tmpdir(), "oke-ai-setup-"));
+    try {
+      writeFileSync(
+        join(dir, "oke.config.ts"),
+        `import { defineConfig } from "okengine/config";
+export default defineConfig({
+  drivers: {
+    channel: {
+      email: {
+        local: "console",
+        docker: "smtp",
+        test: "console",
+        prod: "smtp",
+      },
+    },
+  },
+  images: {
+    "store.sql": "postgres:18-alpine",
+  },
+});
+`,
+        "utf8",
+      );
+      mkdirSync(join(dir, "src"), { recursive: true });
+      writeFileSync(join(dir, "src", "app.ts"), `export const app = {};\n`, "utf8");
+
+      applyAiSetup(dir, {
+        driver: "ollama",
+        baseUrl: "http://127.0.0.1:11434",
+        chatModel: "gemma4:e4b",
+        visionModel: "qwen3-vl:4b",
+        embedModel: "nomic-embed-text",
+      });
+
+      const config = readFileSync(join(dir, "oke.config.ts"), "utf8");
+      expect(config).toContain('local: "ollama"');
+      expect(config).toContain('ai: "ollama/ollama:latest"');
+      const env = readFileSync(join(dir, ".env.local"), "utf8");
+      expect(env).toContain("OKE_AI_DRIVER=ollama");
+      expect(env).toContain("OKE_AI_MODEL=gemma4:e4b");
+      const aiTs = readFileSync(join(dir, "src", "ai.ts"), "utf8");
+      expect(aiTs).toContain("smart");
+      const app = readFileSync(join(dir, "src", "app.ts"), "utf8");
+      expect(app).toContain('import "./ai"');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("parseAiSetupArgs", () => {
+  test("parses provider and models", () => {
+    const a = parseAiSetupArgs(["--provider", "ollama", "--chat=qwen3.5:9b", "--no-pull", "--yes"]);
+    expect(a.provider).toBe("ollama");
+    expect(a.chat).toBe("qwen3.5:9b");
+    expect(a.pull).toBe(false);
+    expect(a.yes).toBe(true);
+  });
+});

package/src/cli/ai-setup/apply.ts

@@ -0,0 +1,214 @@
+/**
+ * Write AI driver config, env, and `src/ai.ts` for `oke ai setup`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Choices applied to the project. */
+export type AiSetupApplyInput = {
+  readonly driver: "ollama" | "anthropic" | "openai-compatible" | "mock";
+  readonly baseUrl?: string;
+  readonly chatModel?: string;
+  readonly visionModel?: string | null;
+  readonly embedModel?: string | null;
+  readonly apiKeyEnv?: string;
+};
+
+/** Options for {@link applyAiSetup}. */
+export type AiSetupApplyOptions = {
+  /**
+   * When false, leave `drivers.ai` / `images.ai` alone (create-oke already
+   * wrote per-env pins). Default true for standalone `oke ai setup`.
+   */
+  readonly updateDrivers?: boolean;
+};
+
+/**
+ * Apply AI setup to a project root.
+ *
+ * @param cwd - Project root
+ * @param input - Selected provider / models
+ * @param options - Pin-preserving knobs for create-oke
+ */
+export function applyAiSetup(
+  cwd: string,
+  input: AiSetupApplyInput,
+  options: AiSetupApplyOptions = {},
+): {
+  readonly configPath: string;
+  readonly envPath: string;
+  readonly aiTsPath: string;
+} {
+  const updateDrivers = options.updateDrivers !== false;
+  const configPath = join(cwd, "oke.config.ts");
+  if (!existsSync(configPath)) {
+    throw new Error("oke ai setup: no oke.config.ts in the current directory");
+  }
+
+  if (updateDrivers) {
+    let config = readFileSync(configPath, "utf8");
+    config = upsertAiDrivers(config, input.driver);
+    if (input.driver === "ollama") {
+      config = upsertImage(config, "ai", "ollama/ollama:latest");
+    }
+    writeFileSync(configPath, config, "utf8");
+  }
+
+  const envPath = join(cwd, ".env.local");
+  const envExample = join(cwd, ".env.example");
+  let env = existsSync(envPath)
+    ? readFileSync(envPath, "utf8")
+    : existsSync(envExample)
+      ? readFileSync(envExample, "utf8")
+      : "";
+  env = upsertEnv(env, "OKE_AI_DRIVER", input.driver);
+  if (input.baseUrl) env = upsertEnv(env, "OKE_AI_URL", input.baseUrl);
+  if (input.chatModel) env = upsertEnv(env, "OKE_AI_MODEL", input.chatModel);
+  if (input.visionModel) env = upsertEnv(env, "OKE_AI_VISION_MODEL", input.visionModel);
+  if (input.embedModel) env = upsertEnv(env, "OKE_AI_EMBED_MODEL", input.embedModel);
+  if (input.apiKeyEnv) {
+    // Ensure the key name is present (value left blank for the user)
+    if (!new RegExp(`^${input.apiKeyEnv}=`, "m").test(env)) {
+      env = `${env.trimEnd()}\n${input.apiKeyEnv}=\n`;
+    }
+  }
+  writeFileSync(envPath, env.endsWith("\n") ? env : `${env}\n`, "utf8");
+
+  const aiTsPath = join(cwd, "src", "ai.ts");
+  mkdirSync(dirname(aiTsPath), { recursive: true });
+  writeFileSync(aiTsPath, renderAiTs(input), "utf8");
+  ensureAiImported(cwd);
+
+  return { configPath, envPath, aiTsPath };
+}
+
+/**
+ * @param source - oke.config.ts
+ * @param driver - AI driver id
+ */
+export function upsertAiDrivers(source: string, driver: string): string {
+  const block = `{
+    local: "${driver}",
+    docker: "${driver === "mock" ? "mock" : driver}",
+    test: "mock",
+    prod: "${driver === "mock" ? "mock" : driver}",
+  }`;
+  // Top-level drivers.ai only (4-space indent) — never nest under channel.email.
+  const aiRe = /^( {4})ai:\s*\{[\s\S]*?\n\1\}/m;
+  if (aiRe.test(source)) {
+    return source.replace(aiRe, `$1ai: ${block}`);
+  }
+  const channelRe = /^( {4})channel:\s*\{[\s\S]*?\n\1\},?\n/m;
+  if (channelRe.test(source)) {
+    return source.replace(channelRe, (match) => `${match}    ai: ${block},\n`);
+  }
+  const driversClose = /(drivers:\s*\{[\s\S]*?)(\n\s*\},)/;
+  if (!driversClose.test(source)) {
+    throw new Error("oke ai setup: could not find drivers block in oke.config.ts");
+  }
+  return source.replace(driversClose, `$1\n    ai: ${block},$2`);
+}
+
+/**
+ * @param source - Config source
+ * @param key - Image role
+ * @param image - Image ref
+ */
+export function upsertImage(source: string, key: string, image: string): string {
+  const keyLit = key.includes(".") ? `"${key}"` : key;
+  const line = `    ${keyLit}: "${image}",`;
+  const imagesRe = /images:\s*\{([\s\S]*?)\n\s*\}/;
+  const m = imagesRe.exec(source);
+  if (!m) return source;
+  const body = m[1]!;
+  if (new RegExp(`${keyLit}\\s*:`).test(body) || new RegExp(`"${key}"\\s*:`).test(body)) {
+    return source.replace(
+      new RegExp(`(["']?${key.replace(".", "\\.")}["']?\\s*:\\s*)"[^"]*"`),
+      `$1"${image}"`,
+    );
+  }
+  return source.replace(imagesRe, `images: {${body}\n${line}\n  }`);
+}
+
+/**
+ * @param env - dotenv text
+ * @param key - Variable name
+ * @param value - Value
+ */
+export function upsertEnv(env: string, key: string, value: string): string {
+  const line = `${key}=${value}`;
+  const re = new RegExp(`^#?\\s*${key}=.*$`, "m");
+  if (re.test(env)) return env.replace(re, line);
+  const aiSection = /(# ── AI[^\n]*\n)/;
+  if (aiSection.test(env)) {
+    return env.replace(aiSection, `$1${line}\n`);
+  }
+  return `${env.trimEnd()}\n\n# ── AI ──────────────────────────────────────────────────────\n${line}\n`;
+}
+
+/**
+ * @param input - Setup choices
+ */
+export function renderAiTs(input: AiSetupApplyInput): string {
+  const chat = input.chatModel ?? "default";
+  const provider =
+    input.driver === "ollama"
+      ? "ollama"
+      : input.driver === "anthropic"
+        ? "anthropic"
+        : input.driver === "mock"
+          ? "mock"
+          : "openai-compatible";
+
+  const lines = [
+    `import { ai } from "okengine";`,
+    ``,
+    `export const smart = ai.model("smart", {`,
+    `  provider: "${provider}",`,
+    `  model: process.env.OKE_AI_MODEL ?? "${chat}",`,
+    `});`,
+  ];
+
+  if (input.visionModel) {
+    lines.push(
+      ``,
+      `export const vision = ai.model("vision", {`,
+      `  provider: "${provider}",`,
+      `  model: process.env.OKE_AI_VISION_MODEL ?? "${input.visionModel}",`,
+      `});`,
+    );
+  }
+
+  if (input.embedModel) {
+    lines.push(
+      ``,
+      `export const embedModel = ai.model("embed", {`,
+      `  provider: "${provider}",`,
+      `  model: process.env.OKE_AI_EMBED_MODEL ?? "${input.embedModel}",`,
+      `});`,
+      ``,
+      `export const docsEmbed = ai.embed("docs", { model: embedModel });`,
+    );
+  }
+
+  lines.push(``);
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Ensure `src/app.ts` (or `src/core.ts`) imports `./ai`.
+ *
+ * @param cwd - Project root
+ */
+function ensureAiImported(cwd: string): void {
+  for (const rel of ["src/app.ts", "src/core.ts"]) {
+    const path = join(cwd, rel);
+    if (!existsSync(path)) continue;
+    const src = readFileSync(path, "utf8");
+    if (/from\s+["']\.\/ai["']/.test(src) || /import\s+["']\.\/ai["']/.test(src)) return;
+    const next = `import "./ai";\n${src}`;
+    writeFileSync(path, next, "utf8");
+    return;
+  }
+}

package/src/cli/ai-setup/catalog.ts

@@ -0,0 +1,263 @@
+/**
+ * Curated Ollama model catalog for `oke ai setup`.
+ *
+ * Short lists with Recommended — not the full Ollama library.
+ * Tags verified against common 2026 library names; override freely.
+ */
+
+/** Role a model can fill in the wizard. */
+export type CatalogRole = "chat" | "vision" | "embed";
+
+/** One curated model entry. */
+export type CatalogModel = {
+  readonly id: string;
+  readonly label: string;
+  readonly hint: string;
+  readonly role: CatalogRole;
+  readonly recommended?: boolean;
+  /** Approximate RAM (GB) needed to run comfortably. */
+  readonly ramGb: number;
+};
+
+/** Chat models (short list). */
+export const CHAT_MODELS: readonly CatalogModel[] = [
+  {
+    id: "gemma4:e4b",
+    label: "Gemma 4 4B",
+    hint: "Fast · ≈8GB-class machine",
+    role: "chat",
+    recommended: true,
+    ramGb: 8,
+  },
+  {
+    id: "qwen3.5:9b",
+    label: "Qwen3.5 9B",
+    hint: "Better coding · ≈16GB-class",
+    role: "chat",
+    ramGb: 16,
+  },
+  {
+    id: "qwen3.5:27b",
+    label: "Qwen3.5 27B",
+    hint: "Best local quality · ≈32GB-class",
+    role: "chat",
+    ramGb: 32,
+  },
+  {
+    id: "llama4:scout",
+    label: "Llama 4 Scout",
+    hint: "General purpose · ≈16GB-class",
+    role: "chat",
+    ramGb: 16,
+  },
+  {
+    id: "deepseek-r1:8b",
+    label: "DeepSeek R1 8B",
+    hint: "Strong reasoning · ≈10GB-class",
+    role: "chat",
+    ramGb: 10,
+  },
+];
+
+/** Vision models (short list + skip handled in prompts). */
+export const VISION_MODELS: readonly CatalogModel[] = [
+  {
+    id: "qwen3-vl:4b",
+    label: "Qwen3-VL 4B",
+    hint: "Vision-language",
+    role: "vision",
+    recommended: true,
+    ramGb: 8,
+  },
+  {
+    id: "gemma4:e4b",
+    label: "Gemma Vision",
+    hint: "Multimodal Gemma 4",
+    role: "vision",
+    ramGb: 8,
+  },
+];
+
+/** Embedding models. */
+export const EMBED_MODELS: readonly CatalogModel[] = [
+  {
+    id: "nomic-embed-text",
+    label: "nomic-embed-text",
+    hint: "Default local RAG embedder",
+    role: "embed",
+    recommended: true,
+    ramGb: 1,
+  },
+  {
+    id: "bge-m3",
+    label: "bge-m3",
+    hint: "Multilingual + long docs",
+    role: "embed",
+    ramGb: 2,
+  },
+  {
+    id: "jina-embeddings-v4",
+    label: "jina-embeddings-v4",
+    hint: "High-quality embedder",
+    role: "embed",
+    ramGb: 2,
+  },
+];
+
+/** All curated ids (for detect / not-installed). */
+export const ALL_CURATED: readonly CatalogModel[] = [
+  ...CHAT_MODELS,
+  ...VISION_MODELS.filter((m) => !CHAT_MODELS.some((c) => c.id === m.id)),
+  ...EMBED_MODELS,
+];
+
+/**
+ * Recommend a chat model for the host RAM (comfortable headroom).
+ *
+ * Prefer {@link recommendChatForNeeds} when use-case answers are available.
+ *
+ * @param totalRamGb - Detected total system RAM in GB (or null)
+ */
+export function recommendChatModel(totalRamGb: number | null): CatalogModel {
+  // Keep catalog free of recommend.ts cycles — same rules as comfortableChatModels.
+  const HEADROOM = 4;
+  const sorted = [...CHAT_MODELS].sort((a, b) => a.ramGb - b.ramGb);
+  const smallest = sorted[0]!;
+  if (totalRamGb === null || !Number.isFinite(totalRamGb)) {
+    return CHAT_MODELS.find((m) => m.recommended) ?? smallest;
+  }
+  const comfortable = sorted.filter(
+    (m) => (m.id === smallest.id && m.ramGb <= totalRamGb) || m.ramGb + HEADROOM <= totalRamGb,
+  );
+  if (comfortable.length > 0) return comfortable[comfortable.length - 1]!;
+  // Fall back to largest that meets the machine tier (tight but runnable).
+  const tierOk = sorted.filter((m) => m.ramGb <= totalRamGb);
+  return tierOk.length > 0 ? tierOk[tierOk.length - 1]! : smallest;
+}
+
+/**
+ * Recommend vision / embed defaults.
+ *
+ * @param role - vision or embed
+ */
+export function recommendForRole(role: "vision" | "embed"): CatalogModel {
+  const list = role === "vision" ? VISION_MODELS : EMBED_MODELS;
+  return list.find((m) => m.recommended) ?? list[0]!;
+}
+
+/** Thin cloud provider menu (non-Ollama). */
+export const CLOUD_PROVIDERS = [
+  {
+    value: "openai",
+    label: "OpenAI",
+    driver: "openai-compatible" as const,
+    baseUrl: "https://api.openai.com/v1",
+  },
+  { value: "anthropic", label: "Anthropic", driver: "anthropic" as const, baseUrl: undefined },
+  {
+    value: "gemini",
+    label: "Gemini",
+    driver: "openai-compatible" as const,
+    baseUrl: undefined,
+  },
+  {
+    value: "lmstudio",
+    label: "LM Studio",
+    driver: "openai-compatible" as const,
+    baseUrl: "http://127.0.0.1:1234/v1",
+  },
+  {
+    value: "openrouter",
+    label: "OpenRouter",
+    driver: "openai-compatible" as const,
+    baseUrl: "https://openrouter.ai/api/v1",
+  },
+  {
+    value: "custom",
+    label: "Custom OpenAI Compatible",
+    driver: "openai-compatible" as const,
+    baseUrl: undefined,
+  },
+] as const;
+
+/** Cloud chat model entry (no RAM tier). */
+export type CloudModel = {
+  readonly id: string;
+  readonly label: string;
+  readonly hint: string;
+  readonly recommended?: boolean;
+};
+
+/** Short curated chat models per cloud / openai-compatible provider. */
+export const CLOUD_CHAT_MODELS: Readonly<Record<string, readonly CloudModel[]>> = {
+  openai: [
+    { id: "gpt-4o-mini", label: "GPT-4o mini", hint: "Fast · cheap default", recommended: true },
+    { id: "gpt-4o", label: "GPT-4o", hint: "Strong general / vision" },
+    { id: "gpt-4.1", label: "GPT-4.1", hint: "Latest flagship" },
+    { id: "o4-mini", label: "o4-mini", hint: "Reasoning · lower cost" },
+  ],
+  anthropic: [
+    {
+      id: "claude-sonnet-4-20250514",
+      label: "Claude Sonnet 4",
+      hint: "Balanced default",
+      recommended: true,
+    },
+    { id: "claude-opus-4-20250514", label: "Claude Opus 4", hint: "Highest quality" },
+    { id: "claude-haiku-4-20250514", label: "Claude Haiku 4", hint: "Fast · cheap" },
+  ],
+  gemini: [
+    {
+      id: "gemini-2.5-flash",
+      label: "Gemini 2.5 Flash",
+      hint: "Fast default",
+      recommended: true,
+    },
+    { id: "gemini-2.5-pro", label: "Gemini 2.5 Pro", hint: "Higher quality" },
+  ],
+  openrouter: [
+    {
+      id: "openai/gpt-4o-mini",
+      label: "GPT-4o mini",
+      hint: "via OpenRouter",
+      recommended: true,
+    },
+    { id: "anthropic/claude-sonnet-4", label: "Claude Sonnet 4", hint: "via OpenRouter" },
+    { id: "google/gemini-2.5-flash", label: "Gemini 2.5 Flash", hint: "via OpenRouter" },
+  ],
+  lmstudio: [
+    {
+      id: "local-model",
+      label: "local-model",
+      hint: "LM Studio loaded model id",
+      recommended: true,
+    },
+  ],
+  custom: [
+    {
+      id: "default",
+      label: "default",
+      hint: "Whatever your endpoint expects",
+      recommended: true,
+    },
+  ],
+};
+
+/**
+ * Curated chat models for a cloud provider (empty → Other-only).
+ *
+ * @param provider - Menu provider id
+ */
+export function cloudChatModels(provider: string): readonly CloudModel[] {
+  return CLOUD_CHAT_MODELS[provider] ?? [];
+}
+
+/**
+ * Recommended cloud chat model id for a provider.
+ *
+ * @param provider - Menu provider id
+ */
+export function recommendCloudChat(provider: string): string {
+  const list = cloudChatModels(provider);
+  return list.find((m) => m.recommended)?.id ?? list[0]?.id ?? "gpt-4o-mini";
+}