okengine 0.6.1 → 0.8.0

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

@@ -0,0 +1,100 @@
+/**
+ * Smart Ollama recommendation scoring + RAM tier rules.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { recommendChatModel } from "./catalog.ts";
+import {
+  fittingChatModels,
+  formatMachineSummary,
+  isTightFit,
+  modelFitsComfortably,
+  modelFitsOnMachine,
+  recommendChatForNeeds,
+  type AiNeeds,
+} from "./recommend.ts";
+
+const balanced: AiNeeds = {
+  useCase: "balanced",
+  priority: "balanced",
+  wantVision: false,
+};
+
+describe("modelFitsOnMachine", () => {
+  test("catalog ramGb is machine tier, not download size", () => {
+    expect(modelFitsOnMachine({ id: "x", label: "x", hint: "", role: "chat", ramGb: 16 }, 24)).toBe(
+      true,
+    );
+    expect(modelFitsOnMachine({ id: "x", label: "x", hint: "", role: "chat", ramGb: 32 }, 24)).toBe(
+      false,
+    );
+  });
+});
+
+describe("recommendChatForNeeds", () => {
+  test("8GB → entry-level only", () => {
+    const pick = recommendChatForNeeds(8, balanced);
+    expect(pick.id).toBe("gemma4:e4b");
+    expect(pick.ramGb).toBeLessThanOrEqual(8);
+  });
+
+  test("16GB → never recommends 27b / 32GB-class", () => {
+    const pick = recommendChatForNeeds(16, { ...balanced, useCase: "coding", priority: "quality" });
+    expect(pick.ramGb).toBeLessThanOrEqual(16);
+    expect(pick.id).not.toBe("qwen3.5:27b");
+  });
+
+  test("24GB does not treat full RAM as model size", () => {
+    const pick = recommendChatForNeeds(24, balanced);
+    // Must leave headroom — not a fictional "24GB model"
+    expect(pick.ramGb).toBeLessThan(24);
+    expect(pick.ramGb).toBeLessThanOrEqual(16);
+    const summary = formatMachineSummary(24, pick);
+    expect(summary).toContain("Your machine: ~24GB");
+    expect(summary).toContain(`${pick.ramGb}GB-class`);
+    expect(summary).not.toMatch(/download a 24GB/i);
+  });
+
+  test("coding preference leans Qwen when it fits", () => {
+    const pick = recommendChatForNeeds(24, {
+      useCase: "coding",
+      priority: "balanced",
+      wantVision: false,
+    });
+    expect(pick.id.startsWith("qwen")).toBe(true);
+  });
+
+  test("reasoning preference leans DeepSeek when it fits", () => {
+    const pick = recommendChatForNeeds(16, {
+      useCase: "reasoning",
+      priority: "balanced",
+      wantVision: false,
+    });
+    expect(pick.id).toContain("deepseek");
+  });
+});
+
+describe("comfortable vs tight", () => {
+  test("16GB-class on 16GB machine is tight", () => {
+    const qwen = fittingChatModels(16).find((m) => m.id === "qwen3.5:9b");
+    expect(qwen).toBeDefined();
+    expect(modelFitsOnMachine(qwen!, 16)).toBe(true);
+    expect(modelFitsComfortably(qwen!, 16)).toBe(false);
+    expect(isTightFit(qwen!, 16)).toBe(true);
+  });
+
+  test("16GB-class on 24GB machine is comfortable", () => {
+    const qwen = fittingChatModels(24).find((m) => m.id === "qwen3.5:9b")!;
+    expect(modelFitsComfortably(qwen, 24)).toBe(true);
+    expect(isTightFit(qwen, 24)).toBe(false);
+  });
+});
+
+describe("recommendChatModel", () => {
+  test("respects tiers with headroom preference", () => {
+    expect(recommendChatModel(8).id).toBe("gemma4:e4b");
+    expect(recommendChatModel(16).ramGb).toBeLessThanOrEqual(16);
+    expect(recommendChatModel(24).ramGb).toBeLessThanOrEqual(16);
+    expect(recommendChatModel(null).recommended).toBe(true);
+  });
+});

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

@@ -0,0 +1,203 @@
+/**
+ * Smart local-model recommendations — machine-tier fit + use-case scoring.
+ *
+ * Catalog `ramGb` is the **recommended machine tier** for that model (not the
+ * download size). A 24GB laptop must never be told it will "download a 24GB
+ * model" — that number was machine RAM shown in the wrong place.
+ *
+ * Most dev machines are 8–16GB. Prefer picks that leave ~4GB for OS / IDE /
+ * browser when several models fit.
+ */
+
+import { CHAT_MODELS, VISION_MODELS, type CatalogModel } from "./catalog.ts";
+
+/** Reserved for OS + IDE + browser while the model runs. */
+export const OS_HEADROOM_GB = 4;
+
+/** What the developer mainly wants from the local model. */
+export type AiUseCase = "coding" | "general" | "reasoning" | "balanced";
+
+/** Speed vs quality preference. */
+export type AiPriority = "speed" | "balanced" | "quality";
+
+/** Answers from the short Ollama questionnaire. */
+export type AiNeeds = {
+  readonly useCase: AiUseCase;
+  readonly priority: AiPriority;
+  readonly wantVision: boolean;
+};
+
+/**
+ * RAM left after reserving OS/IDE headroom.
+ *
+ * @param totalRamGb - Detected machine RAM
+ */
+export function usableRamGb(totalRamGb: number): number {
+  return Math.max(0, totalRamGb - OS_HEADROOM_GB);
+}
+
+/**
+ * Whether the machine meets the model's recommended tier (`model.ramGb`).
+ *
+ * @param model - Catalog entry
+ * @param totalRamGb - Machine RAM (null → only the catalog default recommended)
+ */
+export function modelFitsOnMachine(model: CatalogModel, totalRamGb: number | null): boolean {
+  if (totalRamGb === null || !Number.isFinite(totalRamGb)) {
+    return Boolean(model.recommended);
+  }
+  return model.ramGb <= totalRamGb;
+}
+
+/**
+ * Whether the model fits with comfortable headroom for OS/IDE.
+ *
+ * @param model - Catalog entry
+ * @param totalRamGb - Machine RAM
+ */
+export function modelFitsComfortably(model: CatalogModel, totalRamGb: number | null): boolean {
+  if (totalRamGb === null || !Number.isFinite(totalRamGb)) {
+    return Boolean(model.recommended);
+  }
+  const smallest = [...CHAT_MODELS].sort((a, b) => a.ramGb - b.ramGb)[0]!;
+  // Always allow the entry-level model on machines that meet its tier.
+  if (model.id === smallest.id) return model.ramGb <= totalRamGb;
+  return model.ramGb + OS_HEADROOM_GB <= totalRamGb;
+}
+
+/**
+ * True when the model meets the tier but leaves little room for OS/IDE.
+ *
+ * @param model - Catalog entry
+ * @param totalRamGb - Machine RAM
+ */
+export function isTightFit(model: CatalogModel, totalRamGb: number | null): boolean {
+  if (totalRamGb === null || !Number.isFinite(totalRamGb)) return false;
+  return modelFitsOnMachine(model, totalRamGb) && !modelFitsComfortably(model, totalRamGb);
+}
+
+/**
+ * Chat models that meet the machine tier, smallest → largest.
+ *
+ * @param totalRamGb - Machine RAM
+ */
+export function fittingChatModels(totalRamGb: number | null): readonly CatalogModel[] {
+  const fits = CHAT_MODELS.filter((m) => modelFitsOnMachine(m, totalRamGb));
+  if (fits.length > 0) return [...fits].sort((a, b) => a.ramGb - b.ramGb);
+  return [[...CHAT_MODELS].sort((a, b) => a.ramGb - b.ramGb)[0]!];
+}
+
+/**
+ * Prefer comfortable fits; fall back to any tier-fit if needed.
+ *
+ * @param totalRamGb - Machine RAM
+ */
+export function comfortableChatModels(totalRamGb: number | null): readonly CatalogModel[] {
+  const comfortable = CHAT_MODELS.filter((m) => modelFitsComfortably(m, totalRamGb));
+  if (comfortable.length > 0) {
+    return [...comfortable].sort((a, b) => a.ramGb - b.ramGb);
+  }
+  return fittingChatModels(totalRamGb);
+}
+
+/**
+ * Score a fitting chat model for the user's needs (higher = better).
+ *
+ * @param model - Candidate
+ * @param needs - Questionnaire answers
+ * @param totalRamGb - Machine RAM (tight-fit penalty)
+ */
+export function scoreChatModel(
+  model: CatalogModel,
+  needs: AiNeeds,
+  totalRamGb: number | null = null,
+): number {
+  let score = 0;
+  if (needs.priority === "speed") score += 100 - model.ramGb * 3;
+  else if (needs.priority === "quality") score += model.ramGb * 4;
+  else score += model.ramGb * 2;
+
+  if (needs.useCase === "coding") {
+    if (model.id.startsWith("qwen")) score += 40;
+    if (model.id.includes("deepseek")) score += 15;
+  } else if (needs.useCase === "reasoning") {
+    if (model.id.includes("deepseek") || model.id.includes("r1")) score += 45;
+    if (model.id.startsWith("qwen")) score += 20;
+  } else if (needs.useCase === "general") {
+    if (model.id.includes("llama") || model.id.includes("gemma")) score += 35;
+    if (model.id.startsWith("qwen")) score += 20;
+  } else {
+    if (model.recommended) score += 25;
+    if (model.id.startsWith("qwen3.5:9b")) score += 30;
+    if (model.id.startsWith("gemma")) score += 20;
+  }
+
+  // Prefer leaving OS/IDE headroom unless the user asked for max quality.
+  if (isTightFit(model, totalRamGb) && needs.priority !== "quality") {
+    score -= 35;
+  }
+  return score;
+}
+
+/**
+ * Pick the best chat model for RAM + needs.
+ *
+ * @param totalRamGb - Machine RAM
+ * @param needs - Questionnaire (defaults to balanced/speed-friendly)
+ */
+export function recommendChatForNeeds(
+  totalRamGb: number | null,
+  needs: AiNeeds = { useCase: "balanced", priority: "balanced", wantVision: false },
+): CatalogModel {
+  // Prefer comfortable pool; quality may still score a tight tier-fit higher.
+  const pool =
+    needs.priority === "quality"
+      ? fittingChatModels(totalRamGb)
+      : comfortableChatModels(totalRamGb);
+  let best = pool[0]!;
+  let bestScore = Number.NEGATIVE_INFINITY;
+  for (const m of pool) {
+    const s = scoreChatModel(m, needs, totalRamGb);
+    if (s > bestScore) {
+      best = m;
+      bestScore = s;
+    }
+  }
+  return best;
+}
+
+/**
+ * Vision model that fits; null if user skipped or none fit.
+ *
+ * @param totalRamGb - Machine RAM
+ * @param wantVision - From questionnaire
+ */
+export function recommendVisionForNeeds(
+  totalRamGb: number | null,
+  wantVision: boolean,
+): CatalogModel | null {
+  if (!wantVision) return null;
+  const fits = VISION_MODELS.filter((m) => modelFitsOnMachine(m, totalRamGb));
+  return fits.find((m) => m.recommended) ?? fits[0] ?? null;
+}
+
+/**
+ * Human summary line for the recommendation panel.
+ *
+ * Separates **machine RAM** from **model tier** so "~24GB" is never read as
+ * download size.
+ *
+ * @param totalRamGb - Machine RAM
+ * @param chat - Chosen chat model
+ */
+export function formatMachineSummary(totalRamGb: number | null, chat: CatalogModel): string {
+  if (totalRamGb === null || !Number.isFinite(totalRamGb)) {
+    return `⭐ Suggested: ${chat.label} (≈${chat.ramGb}GB-class machine · not download size)`;
+  }
+  const budget = usableRamGb(totalRamGb);
+  const tight = isTightFit(chat, totalRamGb) ? " · tight on this machine" : "";
+  return [
+    `Your machine: ~${totalRamGb}GB RAM (keep ~${OS_HEADROOM_GB}GB free for OS/IDE → ~${budget}GB model budget)`,
+    `⭐ For you: ${chat.label} — ≈${chat.ramGb}GB-class (Ollama pull is usually much smaller than RAM)${tight}`,
+  ].join("\n");
+}

package/src/cli/ai.ts

@@ -0,0 +1,38 @@
+/**
+ * `oke ai` — AI element CLI commands.
+ */
+
+import { EXIT_OK, EXIT_USAGE } from "./exit.ts";
+import { aiSetupHelp, parseAiSetupArgs, runAiSetup } from "./ai-setup/index.ts";
+
+/**
+ * CLI entry for `oke ai …`.
+ *
+ * @param args - Args after `ai`
+ */
+export async function aiCli(args: readonly string[]): Promise<number> {
+  const [sub, ...rest] = args;
+
+  if (sub === undefined || sub === "--help" || sub === "-h" || sub === "help") {
+    console.log(`oke ai — AI element helpers
+
+Commands:
+  setup   Configure AI driver + models (interactive)
+
+${aiSetupHelp()}`);
+    return sub ? EXIT_OK : EXIT_USAGE;
+  }
+
+  if (sub === "setup") {
+    try {
+      return await runAiSetup(parseAiSetupArgs(rest));
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : e);
+      return 1;
+    }
+  }
+
+  console.error(`oke ai: unknown subcommand ${sub}`);
+  console.error("Run `oke ai --help` for usage.");
+  return EXIT_USAGE;
+}

package/src/cli/db-auto-push.test.ts

@@ -15,7 +15,12 @@ describe("isDomainSchemaWatchPath", () => {
     expect(isDomainSchemaWatchPath("drizzle.config.ts")).toBe(true);
     expect(isDomainSchemaWatchPath("flows/notes/schema.ts")).toBe(true);
     expect(isDomainSchemaWatchPath("src/schema.decl.ts")).toBe(true);
-    expect(isDomainSchemaWatchPath("src/schema.generated.ts")).toBe(true);
+  });
+
+  test("ignores emit output (avoids push ↔ generated feedback loop)", () => {
+    expect(isDomainSchemaWatchPath("src/schema.generated.ts")).toBe(false);
+    expect(isDomainSchemaWatchPath("schema.generated.ts")).toBe(false);
+    expect(isDomainSchemaWatchPath("flows/notes/schema.generated.tsx")).toBe(false);
   });
 
   test("ignores unrelated files", () => {

package/src/cli/db-auto-push.ts

@@ -10,20 +10,25 @@ export const DB_AUTO_PUSH_DEBOUNCE_MS = 300;
 /**
  * Whether a watched path should trigger `oke db push`.
  *
+ * Inputs only: declaration / drizzle config / app entry. Never the emit
+ * output (`schema.generated.ts`) — push rewrites that file every run, so
+ * watching it loops `oke db push` forever under `oke dev`.
+ *
  * @param filename - Relative path from the watcher (may be undefined)
  */
 export function isDomainSchemaWatchPath(filename: string | null | undefined): boolean {
   if (!filename) return false;
   const normalized = filename.replace(/\\/g, "/");
   const base = basename(normalized);
+  // Emit output — never a watch trigger (feedback loop with `oke db push`).
+  if (base === "schema.generated.ts" || base === "schema.generated.tsx") return false;
   if (base === "schema.ts" || base === "schema.tsx") return true;
   if (base === "schema.decl.ts" || base === "schema.decl.tsx") return true;
-  if (base === "schema.generated.ts" || base === "schema.generated.tsx") return true;
   if (base === "drizzle.config.ts" || base === "drizzle.config.js") return true;
   // App entry / plugins — `.plug()` table contributions feed emit.
   if (base === "app.ts" || base === "app.tsx") return true;
-  // Nested domain schemas commonly live under src/**/schema.ts
-  if (/(^|\/)schema(\.decl|\.generated)?\.tsx?$/.test(normalized)) return true;
+  // Nested domain schemas commonly live under src/**/schema.ts (not .generated).
+  if (/(^|\/)schema(\.decl)?\.tsx?$/.test(normalized)) return true;
   return false;
 }