okengine 0.6.0 → 0.7.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;
 }
 

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

@@ -139,6 +139,65 @@ export const entries = sqliteTable("entries", {
     expect(pushes.length).toBeGreaterThan(before);
   });
 
+  test("schema.generated.ts change does not re-trigger dbPush", async () => {
+    const cwd = await scaffoldProject();
+    const pushes: string[] = [];
+    const watcher = controlledWatcher();
+    let resolveReady!: () => void;
+    const ready = new Promise<void>((r) => {
+      resolveReady = r;
+    });
+
+    const result = await runDev({
+      cwd,
+      local: true,
+      keepAlive: false,
+      dryRun: false,
+      appPort: 0,
+      consolePort: 0,
+      mcpPort: 0,
+      silentClaim: true,
+      stdinIsTTY: false,
+      startApp: async () => ({
+        port: 0,
+        url: new URL("http://127.0.0.1:9"),
+        stop() {},
+      }),
+      serveConsole: async () => ({
+        port: 0,
+        stop() {},
+      }),
+      serveMcp: async () => ({
+        port: 0,
+        url: new URL("http://127.0.0.1:9"),
+        stop() {},
+      }),
+      regenClient: async () => {},
+      dbPush: async () => {
+        pushes.push("push");
+        return 0;
+      },
+      onDbAutoPush: () => {
+        resolveReady();
+      },
+      watchFs: watcher.watchFs,
+      onReady: async (session) => {
+        sessions.push(session);
+      },
+    });
+
+    expect(result.code).toBe(0);
+    await Promise.race([ready, Bun.sleep(800)]);
+    const before = pushes.length;
+    expect(before).toBeGreaterThanOrEqual(1);
+
+    // Simulate emit writing schema.generated.ts after push — must not loop.
+    watcher.change("schema.generated.ts");
+    watcher.change("src/schema.generated.ts");
+    await Bun.sleep(500);
+    expect(pushes.length).toBe(before);
+  });
+
   test("--no-db-push / noDbPush never calls dbPush", async () => {
     const cwd = await scaffoldProject();
     const pushes: string[] = [];

package/src/cli/dev.test.ts

@@ -645,6 +645,46 @@ describe("oke dev mode resolution", () => {
     expect(await readDevMode(dir)).toBeNull();
   });
 
+  test("session stop calls composeStop after a successful docker up", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-dev-compose-stop-"));
+    await Bun.write(join(dir, "src/app.ts"), "export {}\n");
+    await writeDevMode(dir, "docker");
+    let upCalls = 0;
+    let stopCalls = 0;
+    let stoppedFiles: readonly string[] | undefined;
+    const result = await runDev({
+      cwd: dir,
+      stdinIsTTY: false,
+      images: { "store.sql": "postgres:16-alpine" },
+      credentials: {
+        "store.sql": {
+          user: "oke",
+          password: "test-password-not-in-yaml",
+          database: "oke",
+        },
+      },
+      composeUp: async (files) => {
+        upCalls++;
+        expect(files.length).toBeGreaterThan(0);
+      },
+      composeStop: (files) => {
+        stopCalls++;
+        stoppedFiles = files;
+      },
+      startApp: async () => ({ stop() {} }),
+      serveConsole: async () => ({ stop() {} }),
+      regenClient: async () => {},
+      write: () => {},
+      keepAlive: false,
+    });
+    expect(result.code).toBe(0);
+    expect(upCalls).toBe(1);
+    expect(result.session).toBeDefined();
+    result.session!.stop();
+    expect(stopCalls).toBe(1);
+    expect(stoppedFiles?.length).toBeGreaterThan(0);
+  });
+
   test("saved docker + compose failure exits loudly (no silent downgrade)", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-dev-mode-fail-"));
     await Bun.write(join(dir, "src/app.ts"), "export {}\n");

package/src/cli/dev.ts

@@ -101,7 +101,7 @@ export interface DevServeDocsMcpOptions {
 /** Live `oke dev` session — returned when {@link DevOptions.keepAlive} is false. */
 export interface DevSession {
   readonly plan: DevPlan;
-  /** Stop app · Console · MCP · watcher. */
+  /** Stop app · Console · MCP · watcher · docker compose (when this session started it). */
   readonly stop: () => void;
   readonly appPort: number;
   readonly consolePort: number;
@@ -185,6 +185,19 @@ export interface DevOptions {
    * @param cwd - Compose directory (`docker/`)
    */
   readonly composeUp?: (composeFiles: readonly string[], cwd: string) => Promise<void>;
+  /**
+   * Stop compose containers on session exit (injectable). Keeps volumes.
+   * Default: `docker compose … stop` with the same `-f` / cwd / env as up.
+   *
+   * @param composeFiles - `-f` list used at up
+   * @param cwd - Compose directory (`docker/`)
+   * @param env - Stack env merged into the process env for compose
+   */
+  readonly composeStop?: (
+    composeFiles: readonly string[],
+    cwd: string,
+    env: Readonly<Record<string, string>>,
+  ) => void;
   /**
    * Regenerate client types (injectable).
    *
@@ -330,6 +343,12 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   let stackRoles: string[] | null = null;
   let composeFiles: string[] | null = null;
   let stackEnv: Record<string, string> | null = null;
+  /** Set only after a successful `compose up` — torn down on SIGINT / stop. */
+  let dockerStarted: {
+    files: readonly string[];
+    cwd: string;
+    env: Record<string, string>;
+  } | null = null;
   let stackSqlDriver = "postgres";
   let stackKvDriver = "redis";
   let loadedConfig: Awaited<ReturnType<typeof loadOkeConfig>>["config"] | null = null;
@@ -437,6 +456,12 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           });
         // Compose files live under docker/; cwd for compose is that directory.
         await up(composeFiles, dockerOut);
+        // Remember for SIGINT / terminal close — `stop` keeps volumes (not `down -v`).
+        dockerStarted = {
+          files: composeFiles,
+          cwd: dockerOut,
+          env: { ...stackEnv! },
+        };
 
         // Real OpenBao vault: init once / unseal every start, then expose the
         // least-privilege app token to the app + Console (never root).
@@ -450,6 +475,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
             names: vaultNames,
           });
           Object.assign(stackEnv!, openbaoStackEnv(boot));
+          Object.assign(dockerStarted.env, openbaoStackEnv(boot));
           const envPath = resolve(dockerOut, ".env.docker");
           const current = await Bun.file(envPath).text();
           const tokenLine = `OKE_VAULT_TOKEN=${boot.appToken}`;
@@ -779,8 +805,34 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     consoleServer.stop();
     mcpServer?.stop();
     docsMcpServer?.stop();
+    if (dockerStarted) {
+      const started = dockerStarted;
+      dockerStarted = null;
+      const stopCompose =
+        options.composeStop ??
+        ((files, dir, env) => {
+          const args = ["compose", ...files.flatMap((f) => ["-f", f]), "stop"];
+          const result = Bun.spawnSync(["docker", ...args], {
+            cwd: dir,
+            stdout: "inherit",
+            stderr: "inherit",
+            env: { ...process.env, ...env },
+          });
+          if (result.exitCode !== 0) {
+            console.error(
+              `oke dev: docker compose stop exited ${result.exitCode ?? "unknown"} (containers may still be running)`,
+            );
+          }
+        });
+      try {
+        stopCompose(started.files, started.cwd, started.env);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+      }
+    }
     process.off("SIGINT", onSignal);
     process.off("SIGTERM", onSignal);
+    process.off("SIGHUP", onSignal);
   };
 
   const onSignal = () => {
@@ -789,6 +841,8 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
   };
   process.on("SIGINT", onSignal);
   process.on("SIGTERM", onSignal);
+  // Terminal close often delivers SIGHUP rather than SIGINT.
+  process.on("SIGHUP", onSignal);
 
   const session: DevSession = {
     plan: {