create-oke 0.18.4 → 0.19.0

package/README.md

@@ -64,4 +64,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.14**. Docs: [oke.omqkhafi.dev](https://oke.omqkhafi.dev) · [handbook](https://oke.omqkhafi.dev/docs).
+Requires **Bun ≥ 1.4.2**. 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.18.4",
+  "version": "0.19.0",
   "description": "Scaffold an okengine app — bunx create-oke@latest <name>",
   "license": "MIT",
   "repository": {
@@ -25,13 +25,13 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@clack/prompts": "^1.7.0"
+    "@clack/prompts": "^1.8.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^7.0.2"
   },
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   }
 }

package/src/agents-md.ts

@@ -69,7 +69,8 @@ are inferred from what a Flow touches through it.
 |---|---|
 | **6530** | Backend |
 | **6533** | Console |
-| **6535** | MCP |
+| **6535** | App MCP |
+| **6536** | Docs MCP (read-only) |
 
 Mnemonic: O·K·E = 6·5·3.
 
@@ -81,7 +82,7 @@ oke dev          # or: bun run dev
 bun run web      # Vite SPA (proxies Flows to the app)
 \`\`\`
 
-App \`:6530\` · Console \`:6533\` · MCP \`:6535\`. Vite web is \`bun run web\`.
+App \`:6530\` · Console \`:6533\` · App MCP \`:6535\` · Docs MCP \`:6536\`. Vite web is \`bun run web\`.
 
 ## Common mistakes
 
@@ -90,13 +91,14 @@ App \`:6530\` · Console \`:6533\` · MCP \`:6535\`. Vite web is \`bun run web\`
 - ❌ Inventing a ninth “element” or a parallel handler stack beside Flows
 - ✅ New capability = new **driver** on an existing element, or a new Flow
 - ❌ Untyped HTTP handlers that skip \`on\` / \`flow\` / contracts
-- ✅ \`on(http.get(), flow({ in, out, do }))\` — or \`http.get("/…")\` / \`flow("unit.export", {…})\` when the folder is not the URL
+- ✅ \`on(http.get({ in, out }), flow({ do }))\` — or \`http.get("/…", { in, out })\` / \`call("unit.export", { in, out, do })\` when the folder is not the URL
 - ❌ Returning \`{ items, count }\` from a list \`do\` (nests the pager inside \`data\`)
 - ✅ \`out: z.array(Item)\` + \`fx.json.withQuery(rows, input)\` — or any other \`out\` you declare
 
 ## Learn more
 
 - Handbook: ${handbook}
-- Get started: ${docsUrl("/docs/get-started/introduction")}
+- Understand: ${docsUrl("/docs/understand/the-problem")}
+- See it work: ${docsUrl("/docs/understand/the-anatomy")}
 `;
 }

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

@@ -0,0 +1,278 @@
+/**
+ * Unit tests for hybrid-search embed wiring in `oke ai setup` / create-oke.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_SEARCH_EMBED_DIMS,
+  applyAiSetup,
+  ensureAiApiKeyVaultSecret,
+  ensureAppStoreSearchEmbed,
+  ensureNotesBodyEmbed,
+  ensureSummarizeNotePrompt,
+  envNameToCamelBinding,
+  hasAiApiKeyVaultSecret,
+  isIncompleteAiSetup,
+  mergeAiApiKeyVaultSecret,
+  renderAiTs,
+  resolveAiCoreSource,
+  upsertEnv,
+} from "./apply.ts";
+
+describe("ensureNotesBodyEmbed", () => {
+  test("adds bare .embed() after .searchable() on body", () => {
+    const src = `
+export const notes = store.schema.table("notes", {
+  id: field.id().primaryKey(),
+  title: field.text().searchable({ weight: 2 }).notNull(),
+  body: field.text().searchable().notNull(),
+});
+`;
+    expect(ensureNotesBodyEmbed(src)).toContain(
+      "body: field.text().searchable().embed().notNull()",
+    );
+  });
+
+  test("is idempotent when .embed() already present", () => {
+    const src = `body: field.text().searchable().embed().notNull(),`;
+    expect(ensureNotesBodyEmbed(src)).toBe(src);
+  });
+
+  test("adds .searchable().embed() when body has neither", () => {
+    const src = `body: field.text().notNull(),`;
+    expect(ensureNotesBodyEmbed(src)).toBe(`body: field.text().searchable().embed().notNull(),`);
+  });
+});
+
+describe("ensureAppStoreSearchEmbed", () => {
+  test("expands oke({ name }) with store.search.embed + embedModel import", () => {
+    const src = `import "@/core";
+import { oke } from "okengine/http";
+
+export const app = oke({ name: "notes" });
+`;
+    const next = ensureAppStoreSearchEmbed(src, DEFAULT_SEARCH_EMBED_DIMS);
+    expect(next).toContain(`import { embedModel } from "@/core";`);
+    expect(next).toContain(`embed: { model: embedModel, dims: ${DEFAULT_SEARCH_EMBED_DIMS} }`);
+    expect(next).toContain(`name: "notes"`);
+  });
+
+  test("is idempotent when store.search.embed already set", () => {
+    const src = `import { embedModel } from "@/core";
+export const app = oke({
+  name: "notes",
+  store: {
+    search: {
+      embed: { model: embedModel, dims: 768 },
+    },
+  },
+});
+`;
+    expect(ensureAppStoreSearchEmbed(src, 768)).toBe(src);
+  });
+});
+
+describe("renderAiTs embed", () => {
+  test("documents SQL .embed() vs index ai.embed pipeline", () => {
+    const out = renderAiTs({
+      driver: "openai-compatible",
+      provider: "openai-compatible",
+      embedModel: "nomic-embed-text",
+    });
+    expect(out).toContain("export const embedModel");
+    expect(out).toContain("store: { search: { embed } }");
+    expect(out).toContain("export const docsEmbed = ai.embed");
+    expect(out).toContain("separate from SQL");
+  });
+});
+
+describe("mergeAiIntoCore vs template comments", () => {
+  test("comment-only ai.model examples still get a full smart/local merge", () => {
+    const existing = `import { channel, gate, store, vault } from "okengine";
+
+// --- AI ----------------------------------------------------------------------
+// Registry cloud example:
+//   ai.model("smart", { provider: "openrouter", model: "openrouter/free" })
+`;
+    const rendered = renderAiTs({
+      driver: "openai-compatible",
+      provider: "openrouter",
+      apiKeyEnv: "OPENROUTER_API_KEY",
+      chatModel: "openrouter/free",
+    });
+    // Template comments must not short-circuit to ensureSummarizeNotePrompt-only.
+    expect(ensureSummarizeNotePrompt(existing)).toBe(existing);
+    expect(isIncompleteAiSetup(existing)).toBe(false);
+
+    const merged = resolveAiCoreSource(existing, rendered);
+    expect(merged).toContain('import { ai, channel, gate, store, vault } from "okengine"');
+    expect(merged).toContain('export const smart = ai.model("smart"');
+    expect(merged).toContain('export const local = ai.model("local"');
+    expect(merged).toContain("export const summarizeNote");
+  });
+
+  test("repairs local+summarizeNote stubs missing smart and ai import", () => {
+    const broken = `import { channel, gate, store, vault } from "okengine";
+
+// --- AI ----------------------------------------------------------------------
+//   ai.model("smart", { provider: "openrouter", model: "openrouter/free" })
+
+/** Local OpenAI-compatible binding (via \`OKE_AI_URL\`). */
+export const local = ai.model("local", {
+  provider: "openai-compatible",
+  model: process.env.OKE_AI_LOCAL_MODEL ?? "local-model",
+  ...(process.env.OKE_AI_URL?.trim() ? { baseUrl: process.env.OKE_AI_URL.trim() } : {}),
+});
+
+/** Advanced Notes summarize — used by \`notes.summarize\` via \`fx.ask\`. */
+export const summarizeNote = smart.prompt("summarize-note", {
+  via: ["smart", "local"],
+  timeout: "30s",
+});
+`;
+    expect(isIncompleteAiSetup(broken)).toBe(true);
+    const rendered = renderAiTs({
+      driver: "openai-compatible",
+      provider: "openrouter",
+      apiKeyEnv: "OPENROUTER_API_KEY",
+      chatModel: "openrouter/free",
+    });
+    const fixed = resolveAiCoreSource(broken, rendered);
+    expect(fixed).toContain('import { ai, channel, gate, store, vault } from "okengine"');
+    expect(fixed).toContain('export const smart = ai.model("smart"');
+    expect(fixed).toContain('provider: "openrouter"');
+    expect(fixed.match(/export const local = ai\.model/g)?.length).toBe(1);
+    expect(fixed.match(/export const summarizeNote/g)?.length).toBe(1);
+  });
+});
+
+describe("AI API key vault + env persistence", () => {
+  test("envNameToCamelBinding", () => {
+    expect(envNameToCamelBinding("OPENROUTER_API_KEY")).toBe("openrouterApiKey");
+    expect(envNameToCamelBinding("ANTHROPIC_API_KEY")).toBe("anthropicApiKey");
+  });
+
+  test("upsertEnv uncomments an empty # KEY= placeholder", () => {
+    const env = `# OPENROUTER_API_KEY=\n# OKE_AI_MODEL=openrouter/free\n`;
+    const next = upsertEnv(env, "OPENROUTER_API_KEY", "sk-or-v1-test");
+    expect(next).toMatch(/^OPENROUTER_API_KEY=sk-or-v1-test$/m);
+    expect(next).not.toMatch(/^#\s*OPENROUTER_API_KEY=/m);
+  });
+
+  test("mergeAiApiKeyVaultSecret inserts under Vault heading", () => {
+    const existing = `import { channel, gate, store, vault } from "okengine";
+
+// --- Vault -------------------------------------------------------------------
+
+export const webhookSecret = vault.secret("APP_WEBHOOK_SECRET", {
+  description: "HMAC",
+  dev: "dev-webhook-secret-change-me",
+});
+
+// --- AI ----------------------------------------------------------------------
+`;
+    const next = mergeAiApiKeyVaultSecret(existing, "OPENROUTER_API_KEY");
+    expect(hasAiApiKeyVaultSecret(next, "OPENROUTER_API_KEY")).toBe(true);
+    expect(next).toContain('export const openrouterApiKey = vault.secret("OPENROUTER_API_KEY"');
+    expect(next.indexOf("openrouterApiKey")).toBeLessThan(next.indexOf("webhookSecret"));
+    expect(mergeAiApiKeyVaultSecret(next, "OPENROUTER_API_KEY")).toBe(next);
+  });
+
+  test("mergeAiApiKeyVaultSecret prepends into NOTES_VAULT list", () => {
+    const existing = `import { vault } from "okengine";
+
+export const webhookSecret = vault.secret("APP_WEBHOOK_SECRET", {
+  description: "HMAC",
+  dev: "x",
+});
+
+export const NOTES_VAULT = [
+  webhookSecret,
+] as const;
+`;
+    const next = mergeAiApiKeyVaultSecret(existing, "OPENROUTER_API_KEY");
+    expect(next).toContain('export const openrouterApiKey = vault.secret("OPENROUTER_API_KEY"');
+    expect(next).toMatch(/NOTES_VAULT = \[\s*\n\s*openrouterApiKey,\s*\n\s*webhookSecret,/);
+    expect(mergeAiApiKeyVaultSecret(next, "OPENROUTER_API_KEY")).toBe(next);
+  });
+
+  test("ensureAiApiKeyVaultSecret prefers src/vault.ts over core.ts", () => {
+    const dir = mkdtempSync(join(tmpdir(), "create-oke-vault-ts-"));
+    try {
+      mkdirSync(join(dir, "src"), { recursive: true });
+      writeFileSync(
+        join(dir, "src", "vault.ts"),
+        `import { vault } from "okengine";
+export const webhookSecret = vault.secret("APP_WEBHOOK_SECRET", { description: "HMAC", dev: "x" });
+export const NOTES_VAULT = [
+  webhookSecret,
+] as const;
+`,
+        "utf8",
+      );
+      writeFileSync(join(dir, "src", "core.ts"), `export * from "@/vault";\n`, "utf8");
+      ensureAiApiKeyVaultSecret(dir, "OPENROUTER_API_KEY");
+      const vault = readFileSync(join(dir, "src", "vault.ts"), "utf8");
+      const core = readFileSync(join(dir, "src", "core.ts"), "utf8");
+      expect(vault).toContain('vault.secret("OPENROUTER_API_KEY"');
+      expect(vault).toMatch(/NOTES_VAULT = \[\s*\n\s*openrouterApiKey,/);
+      expect(core).not.toContain("OPENROUTER_API_KEY");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("applyAiSetup writes apiKey into .env.local and vault.secret into core.ts", () => {
+    const dir = mkdtempSync(join(tmpdir(), "create-oke-ai-key-"));
+    try {
+      writeFileSync(
+        join(dir, "oke.config.ts"),
+        `import { defineConfig } from "okengine/config";
+export default defineConfig({
+  drivers: {
+    channel: { email: { dev: "console", test: "console", prod: "console" } },
+  },
+});
+`,
+        "utf8",
+      );
+      mkdirSync(join(dir, "src"), { recursive: true });
+      writeFileSync(
+        join(dir, "src", "core.ts"),
+        `import { store, vault } from "okengine";
+
+// --- Vault -------------------------------------------------------------------
+
+export const webhookSecret = vault.secret("APP_WEBHOOK_SECRET", {
+  description: "HMAC",
+  dev: "dev-secret",
+});
+
+// --- AI ----------------------------------------------------------------------
+`,
+        "utf8",
+      );
+      writeFileSync(join(dir, ".env.local"), `# OPENROUTER_API_KEY=\n`, "utf8");
+
+      applyAiSetup(dir, {
+        driver: "openai-compatible",
+        provider: "openrouter",
+        chatModel: "openrouter/free",
+        apiKeyEnv: "OPENROUTER_API_KEY",
+        apiKey: "sk-or-v1-from-wizard",
+      });
+
+      const env = readFileSync(join(dir, ".env.local"), "utf8");
+      expect(env).toMatch(/^OPENROUTER_API_KEY=sk-or-v1-from-wizard$/m);
+      const core = readFileSync(join(dir, "src", "core.ts"), "utf8");
+      expect(core).toContain('vault.secret("OPENROUTER_API_KEY"');
+      expect(core).toContain('export const smart = ai.model("smart"');
+      expect(existsSync(join(dir, "src", "core", "ai.ts"))).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});