create-oke 0.6.1 → 0.8.0

package/README.md

@@ -8,8 +8,21 @@ cd my-app
 oke dev
 ```
 
-On a TTY, create-oke opens a Clack wizard to confirm the name and optionally
-install dependencies and start `oke dev`. Pass `--yes` for non-interactive use.
+On a TTY, create-oke opens a Clack wizard:
+
+1. Project name
+2. **Starter** — `standard` (local-first Notes) or `advanced` (same domain,
+   docker-ready + files/digest/AI hooks)
+3. **Recommended defaults** · **Customize** (pick **local** or **docker** first,
+   walk facets for that side, then optionally customize the other; saved to
+   user-global `~/.oke/create-defaults.json`) · **Reuse previous settings**
+   (only when saved settings exist for the selected template).
+   The project-name step rejects a path that already exists and is not empty.
+   Customize steps include **← Back**. Scaffold writes `.oke/mode` from the
+   primary side (recommended: standard → `local`, advanced → `docker`).
+4. Install dependencies and start `oke dev`?
+
+Pass `--yes` for non-interactive recommended defaults (zero prompts).
 
 | Port    | What                |
 | ------- | ------------------- |
@@ -17,21 +30,23 @@ install dependencies and start `oke dev`. Pass `--yes` for non-interactive use.
 | `:6533` | Console             |
 | `:6535` | MCP (live Manifest) |
 
-The single bundled template is **standard**: the full recommended file layout
-with empty scaffolding.
-
 ```bash
 bunx create-oke@latest my-app --template standard
+bunx create-oke@latest my-app --template advanced
 bunx create-oke@latest my-app --sql postgres
 bunx create-oke@latest my-app --yes
+bunx create-oke@latest my-app --ai      # force AI model wizard before install
+bunx create-oke@latest my-app --no-ai
 ```
 
 `--sql sqlite|postgres` is opt-in. The default keeps the dual-mode Store
 config (`local: sqlite` · `docker`/`prod: postgres`) and abstract
 `src/schema.decl.ts` (dialect emitted from the active driver). Pass
 `--sql postgres` to pin `oke.config.ts` `store.sql` local/docker/prod to
-`postgres`. The interactive wizard does not ask and keeps the same dual-mode
-default.
+`postgres`. Customize can set drivers the template exposes; when AI is enabled,
+model selection runs in the wizard **before** `bun install` (writes `.env.local`
+
+- `src/ai.ts`).
 
 Store-bearing scaffolds ship `drizzle.config.ts` and `.env.example`. Local
 `oke dev` auto-runs `oke db push` on schema change; use `oke mode docker` /
@@ -47,4 +62,4 @@ Every scaffold writes an `AGENTS.md` so coding agents know the OKE contract
 | npm (CLI) | [`create-oke`](https://www.npmjs.com/package/create-oke) — use this with `bunx`                         |
 | JSR       | [`@omqkhafi/create-oke`](https://jsr.io/@omqkhafi/create-oke) — same sources; prefer npm for the binary |
 
-Requires **Bun ≥ 1.3**. Docs: [oke.omqkhafi.dev](https://oke.omqkhafi.dev) · [handbook](https://oke.omqkhafi.dev/docs).
+Requires **Bun ≥ 1.3.14**. Docs: [oke.omqkhafi.dev](https://oke.omqkhafi.dev) · [handbook](https://oke.omqkhafi.dev/docs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-oke",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Scaffold an okengine app — bunx create-oke@latest <name>",
   "license": "MIT",
   "repository": {
@@ -13,7 +13,7 @@
   },
   "files": [
     "src",
-    "template"
+    "templates"
   ],
   "type": "module",
   "sideEffects": false,
@@ -33,6 +33,6 @@
     "typescript": "^7.0.2"
   },
   "engines": {
-    "bun": ">=1.3"
+    "bun": ">=1.3.14"
   }
 }

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