okengine 0.6.1 → 0.8.0

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";
+}

package/src/cli/ai-setup/detect-ollama.ts

@@ -0,0 +1,166 @@
+/**
+ * Detect local Ollama — CLI (`ollama list` / `ps`) and HTTP `/api/tags`.
+ */
+
+import { OLLAMA_DEFAULT_BASE_URL, normalizeOllamaBaseUrl } from "../../drivers/ai-ollama.ts";
+import { ALL_CURATED, type CatalogModel } from "./catalog.ts";
+
+/** Result of probing the local Ollama install. */
+export type OllamaDetectResult = {
+  readonly available: boolean;
+  readonly baseUrl: string;
+  readonly installed: readonly string[];
+  readonly running: readonly string[];
+  readonly curatedInstalled: readonly CatalogModel[];
+  readonly curatedMissing: readonly CatalogModel[];
+};
+
+/**
+ * Parse `ollama list` tabular output into model names.
+ *
+ * @param stdout - CLI stdout
+ */
+export function parseOllamaList(stdout: string): string[] {
+  const lines = stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const out: string[] = [];
+  for (const line of lines) {
+    if (/^NAME\b/i.test(line)) continue;
+    const name = line.split(/\s+/)[0];
+    if (name) out.push(name);
+  }
+  return out;
+}
+
+/**
+ * Parse `ollama ps` tabular output into running model names.
+ *
+ * @param stdout - CLI stdout
+ */
+export function parseOllamaPs(stdout: string): string[] {
+  return parseOllamaList(stdout);
+}
+
+/**
+ * Normalize installed tag for comparison (`qwen3.5:9b` vs `qwen3.5:9b-mlx`).
+ *
+ * @param id - Catalog or installed id
+ * @param installed - Installed names
+ */
+export function isInstalled(id: string, installed: readonly string[]): boolean {
+  const base = id.split(":")[0] ?? id;
+  return installed.some((name) => {
+    if (name === id) return true;
+    if (name.startsWith(`${id}-`)) return true;
+    if (name.startsWith(`${base}:`) && id.startsWith(`${base}:`)) {
+      // treat mlx / quant suffixes as matching the same family:tag when prefix matches
+      const instTag = name.slice(base.length + 1);
+      const wantTag = id.slice(base.length + 1);
+      return (
+        instTag === wantTag || instTag.startsWith(`${wantTag}-`) || wantTag.startsWith(instTag)
+      );
+    }
+    return false;
+  });
+}
+
+/**
+ * Detect Ollama via CLI then HTTP fallback.
+ *
+ * @param options - Base URL / spawn / fetch seams
+ */
+export async function detectOllama(
+  options: {
+    readonly baseUrl?: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly run?: (cmd: readonly string[]) => Promise<{ code: number; stdout: string }>;
+  } = {},
+): Promise<OllamaDetectResult> {
+  const baseUrl = normalizeOllamaBaseUrl(options.baseUrl ?? OLLAMA_DEFAULT_BASE_URL);
+  const run =
+    options.run ??
+    (async (cmd) => {
+      const proc = Bun.spawn([...cmd], { stdout: "pipe", stderr: "pipe" });
+      const stdout = await new Response(proc.stdout).text();
+      const code = await proc.exited;
+      return { code, stdout };
+    });
+
+  let installed: string[] = [];
+  let running: string[] = [];
+  let available = false;
+
+  try {
+    const list = await run(["ollama", "list"]);
+    if (list.code === 0) {
+      available = true;
+      installed = parseOllamaList(list.stdout);
+    }
+    const ps = await run(["ollama", "ps"]);
+    if (ps.code === 0) {
+      running = parseOllamaPs(ps.stdout);
+    }
+  } catch {
+    // CLI missing — try HTTP
+  }
+
+  if (!available) {
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    try {
+      const res = await fetchFn(`${baseUrl}/api/tags`, {
+        method: "GET",
+        signal: AbortSignal.timeout(2_000),
+      });
+      if (res.ok) {
+        available = true;
+        const json = (await res.json()) as { models?: readonly { name?: string }[] };
+        installed = (json.models ?? [])
+          .map((m) => m.name)
+          .filter((n): n is string => typeof n === "string");
+      }
+    } catch {
+      // unavailable
+    }
+  }
+
+  const curatedInstalled = ALL_CURATED.filter((m) => isInstalled(m.id, installed));
+  const curatedMissing = ALL_CURATED.filter((m) => !isInstalled(m.id, installed));
+
+  return {
+    available,
+    baseUrl,
+    installed,
+    running,
+    curatedInstalled,
+    curatedMissing,
+  };
+}
+
+/**
+ * Best-effort total system RAM in GB.
+ */
+export function detectTotalRamGb(): number | null {
+  try {
+    if (process.platform === "darwin") {
+      const proc = Bun.spawnSync(["sysctl", "-n", "hw.memsize"], { stdout: "pipe" });
+      if (proc.exitCode === 0) {
+        const bytes = Number(proc.stdout.toString().trim());
+        if (Number.isFinite(bytes) && bytes > 0) return Math.round(bytes / 1024 ** 3);
+      }
+    }
+    if (process.platform === "linux") {
+      const proc = Bun.spawnSync(["awk", "/MemTotal/ {print $2}", "/proc/meminfo"], {
+        stdout: "pipe",
+      });
+      if (proc.exitCode === 0) {
+        const kb = Number(proc.stdout.toString().trim());
+        if (Number.isFinite(kb) && kb > 0) return Math.round(kb / 1024 ** 2);
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}

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

@@ -0,0 +1,228 @@
+/**
+ * `oke ai setup` — interactive AI provider + model configuration.
+ */
+
+import { cancel, intro, outro, spinner } from "@clack/prompts";
+import { applyAiSetup, type AiSetupApplyInput } from "./apply.ts";
+import { askAiSetup } from "./prompts.ts";
+
+/** Parsed flags for AI setup. */
+export type AiSetupCliArgs = {
+  readonly help: boolean;
+  readonly yes: boolean;
+  readonly provider?: string;
+  readonly chat?: string;
+  readonly vision?: string;
+  readonly embed?: string;
+  readonly pull: boolean;
+  readonly cwd: string;
+};
+
+/**
+ * Parse argv after `ai setup`.
+ *
+ * @param argv - Remaining args
+ * @param cwd - Project root
+ */
+export function parseAiSetupArgs(
+  argv: readonly string[],
+  cwd: string = process.cwd(),
+): AiSetupCliArgs {
+  let help = false;
+  let yes = false;
+  let provider: string | undefined;
+  let chat: string | undefined;
+  let vision: string | undefined;
+  let embed: string | undefined;
+  let pull = true;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--help" || a === "-h") {
+      help = true;
+      continue;
+    }
+    if (a === "--yes" || a === "-y") {
+      yes = true;
+      continue;
+    }
+    if (a === "--no-pull") {
+      pull = false;
+      continue;
+    }
+    if (a === "--pull") {
+      pull = true;
+      continue;
+    }
+    if (a === "--provider") {
+      provider = argv[++i];
+      continue;
+    }
+    if (a.startsWith("--provider=")) {
+      provider = a.slice("--provider=".length);
+      continue;
+    }
+    if (a === "--chat") {
+      chat = argv[++i];
+      continue;
+    }
+    if (a.startsWith("--chat=")) {
+      chat = a.slice("--chat=".length);
+      continue;
+    }
+    if (a === "--vision") {
+      vision = argv[++i];
+      continue;
+    }
+    if (a.startsWith("--vision=")) {
+      vision = a.slice("--vision=".length);
+      continue;
+    }
+    if (a === "--embed") {
+      embed = argv[++i];
+      continue;
+    }
+    if (a.startsWith("--embed=")) {
+      embed = a.slice("--embed=".length);
+      continue;
+    }
+    throw new Error(`oke ai setup: unknown option ${a}`);
+  }
+
+  return { help, yes, provider, chat, vision, embed, pull, cwd };
+}
+
+/**
+ * Help text for `oke ai setup`.
+ */
+export function aiSetupHelp(): string {
+  return `oke ai setup — configure AI driver + models
+
+Usage:
+  oke ai setup
+  oke ai setup --provider ollama --yes
+  oke ai setup --provider anthropic --chat claude-sonnet-4-20250514 --yes
+
+Options:
+  --provider <id>   ollama | openai | anthropic | gemini | lmstudio | openrouter | custom
+  --chat <model>    Chat model id
+  --vision <model>  Vision model id (ollama)
+  --embed <model>   Embedding model id (ollama)
+  --pull / --no-pull  Pull missing Ollama models (default: pull)
+  -y, --yes         Non-interactive (requires --provider)
+  -h, --help        Show this help
+`;
+}
+
+/**
+ * Run AI setup (interactive or flags).
+ *
+ * @param args - Parsed args
+ * @returns Exit code
+ */
+export async function runAiSetup(args: AiSetupCliArgs): Promise<number> {
+  if (args.help) {
+    console.log(aiSetupHelp());
+    return 0;
+  }
+
+  const tty = Boolean(process.stdin.isTTY);
+  let input: AiSetupApplyInput | null = null;
+
+  if (args.yes || !tty) {
+    if (!args.provider) {
+      console.error("oke ai setup: --provider is required in non-interactive mode");
+      return 1;
+    }
+    input = nonInteractiveInput(args);
+  } else {
+    intro("oke ai setup");
+    input = await askAiSetup({ provider: args.provider });
+    if (input === null) {
+      cancel("Cancelled.");
+      return 1;
+    }
+    // Flag overrides for models when provided alongside interactive provider
+    if (args.chat) input = { ...input, chatModel: args.chat };
+    if (args.vision !== undefined) input = { ...input, visionModel: args.vision || null };
+    if (args.embed) input = { ...input, embedModel: args.embed };
+  }
+
+  if (input === null) return 1;
+
+  if (args.pull && input.driver === "ollama" && (args.yes || !tty) && args.chat) {
+    // Non-interactive pull of requested models
+    const toPull = [input.chatModel, input.visionModel, input.embedModel].filter(
+      (m): m is string => typeof m === "string" && m.length > 0,
+    );
+    for (const id of toPull) {
+      const proc = Bun.spawn(["ollama", "pull", id], {
+        stdout: "inherit",
+        stderr: "inherit",
+      });
+      await proc.exited;
+    }
+  }
+
+  const spun = tty ? spinner() : undefined;
+  spun?.start("Writing AI config…");
+  try {
+    const result = applyAiSetup(args.cwd, input);
+    spun?.stop("AI configured.");
+    if (tty) {
+      outro(
+        `Wrote ${result.aiTsPath}\nDriver ${input.driver}` +
+          (input.chatModel ? ` · chat ${input.chatModel}` : ""),
+      );
+    } else {
+      console.log(`oke ai setup: driver=${input.driver} chat=${input.chatModel ?? "—"}`);
+    }
+    return 0;
+  } catch (e) {
+    spun?.stop("Failed.");
+    console.error(e instanceof Error ? e.message : e);
+    return 1;
+  }
+}
+
+/**
+ * Build apply input from flags (non-interactive).
+ *
+ * @param args - Parsed args
+ */
+function nonInteractiveInput(args: AiSetupCliArgs): AiSetupApplyInput {
+  const provider = args.provider!;
+  if (provider === "ollama") {
+    return {
+      driver: "ollama",
+      baseUrl: process.env.OKE_AI_URL ?? "http://127.0.0.1:11434",
+      chatModel: args.chat ?? "gemma4:e4b",
+      visionModel: args.vision === undefined ? "qwen3-vl:4b" : args.vision || null,
+      embedModel: args.embed ?? "nomic-embed-text",
+    };
+  }
+  if (provider === "anthropic") {
+    return {
+      driver: "anthropic",
+      chatModel: args.chat ?? "claude-sonnet-4-20250514",
+      visionModel: null,
+      embedModel: null,
+      apiKeyEnv: "ANTHROPIC_API_KEY",
+    };
+  }
+  const baseUrls: Record<string, string | undefined> = {
+    openai: "https://api.openai.com/v1",
+    openrouter: "https://openrouter.ai/api/v1",
+    lmstudio: "http://127.0.0.1:1234/v1",
+    gemini: undefined,
+    custom: undefined,
+  };
+  return {
+    driver: "openai-compatible",
+    ...(baseUrls[provider] !== undefined ? { baseUrl: baseUrls[provider] } : {}),
+    chatModel: args.chat ?? "gpt-4o-mini",
+    visionModel: null,
+    embedModel: null,
+    apiKeyEnv: "OPENAI_API_KEY",
+  };
+}