gencow 0.1.169 → 0.1.171

package/lib/backup-command.mjs

@@ -20,7 +20,7 @@ export function resolveBackupAppId(restArgs, gencowJson = null) {
 export function resolveBackupFilePath(restArgs) {
   for (let i = 0; i < restArgs.length; i++) {
     const arg = restArgs[i];
-    if (arg === "--app" || arg === "-a") {
+    if (arg === "--app" || arg === "-a" || arg === "--limit" || arg === "--cursor") {
       i++;
       continue;
     }
@@ -45,10 +45,34 @@ export function formatBackupDate(value) {
   });
 }
 
+export function parseBackupListOptions(restArgs) {
+  const options = { all: false, cursor: null, limit: 20 };
+  for (let i = 0; i < restArgs.length; i++) {
+    const arg = restArgs[i];
+    if (arg === "--all") {
+      options.all = true;
+      continue;
+    }
+    if (arg === "--limit") {
+      const next = Number(restArgs[i + 1]);
+      if (Number.isFinite(next)) options.limit = Math.min(100, Math.max(1, Math.trunc(next)));
+      i++;
+      continue;
+    }
+    if (arg === "--cursor") {
+      options.cursor = restArgs[i + 1] || null;
+      i++;
+    }
+  }
+  return options;
+}
+
 function renderBackupHelp(logImpl = log, errorImpl = error, subCmd = null) {
   if (subCmd) errorImpl(`Unknown sub-command: ${subCmd}`);
   logImpl(`\n  ${BOLD}Usage:${RESET}`);
-  logImpl(`    gencow backup list               List all backups`);
+  logImpl(`    gencow backup list               List recent backups`);
+  logImpl(`    gencow backup list --all         List all backups by following cursors`);
+  logImpl(`    gencow backup list --limit 50    List a page with up to 50 backups`);
   logImpl(`    gencow backup create [note]       Create a manual backup`);
   logImpl(`    gencow backup restore <id>        Restore from backup`);
   logImpl(`    gencow backup restore-file <path> Restore from a downloaded dump file`);
@@ -56,18 +80,23 @@ function renderBackupHelp(logImpl = log, errorImpl = error, subCmd = null) {
   logImpl(`    gencow backup download <id>       Download backup file (Pro+)\n`);
 }
 
-async function promptRestoreConfirm(sourceLabel, { createInterfaceImpl }) {
+export function buildRestoreConfirmPrompt(sourceLabel, { includeStorageRisk = false } = {}) {
+  const storageRisk = includeStorageRisk
+    ? `\n  ${YELLOW}⚠ 백업 파일 복원은 DB만 교체하며 storage object/blob는 함께 이동하지 않습니다.${RESET}` +
+      `\n  ${DIM}기본 용도는 같은 환경 복원(prod→prod, dev→dev)입니다. 다른 환경의 dump를 복원하면 이미지/파일 참조가 깨질 수 있습니다.${RESET}`
+    : "";
+  return `\n  ${YELLOW}⚠ 현재 데이터베이스가 ${sourceLabel}로 교체됩니다.${RESET}${storageRisk}\n  계속하시겠습니까? (y/N): `;
+}
+
+async function promptRestoreConfirm(sourceLabel, { createInterfaceImpl, includeStorageRisk = false }) {
   const createInterface = createInterfaceImpl ?? (await import("readline")).createInterface;
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   return await new Promise((resolveAnswer) => {
-    rl.question(
-      `\n  ${YELLOW}⚠ 현재 데이터베이스가 ${sourceLabel}로 교체됩니다. 계속하시겠습니까? (y/N): ${RESET}`,
-      (answer) => {
-        rl.close();
-        const normalized = answer.trim().toLowerCase();
-        resolveAnswer(normalized === "y" || normalized === "yes");
-      },
-    );
+    rl.question(buildRestoreConfirmPrompt(sourceLabel, { includeStorageRisk }), (answer) => {
+      rl.close();
+      const normalized = answer.trim().toLowerCase();
+      resolveAnswer(normalized === "y" || normalized === "yes");
+    });
   });
 }
 
@@ -108,19 +137,39 @@ export function createBackupCommand({
     switch (subCmd) {
       case "list":
       case "ls": {
-        const response = await rpcQueryImpl(creds, "backup.list", { appName: appId });
-        if (!response.ok) {
-          errorImpl(
-            `Failed to fetch backup list: ${(await response.json().catch(() => ({}))).error || response.statusText}`,
-          );
-          return;
+        const options = parseBackupListOptions(restArgs);
+        const backups = [];
+        let data = null;
+        let cursor = options.cursor;
+        for (let page = 0; page < 1000; page++) {
+          const response = await rpcQueryImpl(creds, "backup.list", {
+            appName: appId,
+            limit: options.limit,
+            cursor,
+          });
+          if (!response.ok) {
+            errorImpl(
+              `Failed to fetch backup list: ${(await response.json().catch(() => ({}))).error || response.statusText}`,
+            );
+            return;
+          }
+          data = await response.json();
+          backups.push(...(data.backups || []));
+          cursor = data.pageInfo?.nextCursor || null;
+          if (options.all && cursor && page === 999) {
+            errorImpl(
+              "Backup list is too large to fetch with --all. Resume with --cursor from the previous page.",
+            );
+            return;
+          }
+          if (!options.all || !cursor) break;
         }
-        const data = await response.json();
-        const backups = data.backups || [];
-        const limits = data.limits || {};
+        const limits = data?.limits || {};
+        const summary = data?.summary || {};
+        const pageInfo = data?.pageInfo || {};
 
         logImpl(
-          `\n${BOLD}${CYAN}Database Backups${RESET} — ${appId}  ${DIM}(Plan: ${data.plan || "free"})${RESET}\n`,
+          `\n${BOLD}${CYAN}Database Backups${RESET} — ${appId}  ${DIM}(Plan: ${data?.plan || "free"})${RESET}\n`,
         );
 
         if (backups.length === 0) {
@@ -136,6 +185,16 @@ export function createBackupCommand({
           }
         }
 
+        const totalCount = summary.totalCount ?? backups.length;
+        const pendingCount = summary.pendingCount ?? 0;
+        const shownLabel = options.all
+          ? `${backups.length}/${totalCount}`
+          : `${backups.length} of ${totalCount}`;
+        logImpl(`\n  ${DIM}Showing: ${shownLabel} | Pending: ${pendingCount}${RESET}`);
+        if (!options.all && pageInfo.nextCursor) {
+          logImpl(`  ${DIM}Next page: gencow backup list --cursor ${pageInfo.nextCursor}${RESET}`);
+          logImpl(`  ${DIM}Full history: gencow backup list --all${RESET}`);
+        }
         logImpl(
           `\n  ${DIM}Limits: ${limits.maxManualBackups || "?"} manual | ${limits.retentionDays || "?"} days | Auto: ${limits.autoBackupEnabled ? "ON" : "OFF"}${RESET}\n`,
         );
@@ -198,7 +257,10 @@ export function createBackupCommand({
           return;
         }
 
-        const confirmed = await promptRestoreConfirm(`파일 ${filePath}`, { createInterfaceImpl });
+        const confirmed = await promptRestoreConfirm(`파일 ${filePath}`, {
+          createInterfaceImpl,
+          includeStorageRisk: true,
+        });
         if (!confirmed) {
           infoImpl("Restore cancelled.");
           return;
@@ -209,14 +271,10 @@ export function createBackupCommand({
         const buffer = await readFileAsync(filePath);
         const form = new FormData();
         form.append("file", new Blob([buffer]), filePath.split(/[\\/]/).pop() || "backup.dump");
-        const response = await platformFetchImpl(
-          creds,
-          `/platform/apps/${appId}/backups/restore-file`,
-          {
-            method: "POST",
-            body: form,
-          },
-        );
+        const response = await platformFetchImpl(creds, `/platform/apps/${appId}/backups/restore-file`, {
+          method: "POST",
+          body: form,
+        });
         if (!response.ok) {
           errorImpl(
             `Restore failed: ${(await response.json?.().catch(() => ({}))).error || response.statusText}`,

package/lib/component-readme.mjs

@@ -48,9 +48,18 @@ export function LoginPage() {
 | \`ai.estimateTokens()\` | \`function\` | Lightweight token estimate |
 | \`ai.trimMessages()\` | \`function\` | Trim messages to a token budget |`,
     usage: `\`\`\`typescript
-import { ai } from "@/gencow/ai";
+import { generateText, rerank } from "ai";
+import { ai, createGencowAI } from "@/gencow/ai";
 
-// Text generation
+const gencow = createGencowAI();
+
+// Pure AI SDK text generation
+const sdkReply = await generateText({
+    model: gencow.languageModel("gpt-5.4-mini"),
+    messages: [{ role: "user", content: "Hello" }],
+});
+
+// Legacy facade text generation
 const reply = await ai.chat({
     system: "You are a helpful assistant.",
     messages: [{ role: "user", content: "Hello" }],
@@ -77,6 +86,14 @@ const ranked = await ai.rerank({
     topK: 5,
 });
 
+// Pure AI SDK rerank path
+const sdkRanked = await rerank({
+    model: gencow.rerankingModel("Cohere-rerank-v4.0-fast"),
+    documents: candidates.map((candidate) => candidate.text),
+    query: "refund policy",
+    topN: 5,
+});
+
 // Image generation
 const image = await ai.image.generate({
     prompt: "A clean app icon for a todo product",
@@ -91,7 +108,9 @@ const receipt = await ai.vision.extractText({
 });
 \`\`\``,
     vibePrompt: `AI Engine API:
-  import { ai } from "@/gencow/ai";
+  import { ai, createGencowAI } from "@/gencow/ai";
+  createGencowAI().languageModel("gpt-5.4-mini") // pure AI SDK model
+  createGencowAI().rerankingModel("Cohere-rerank-v4.0-fast") // pure rerank model
   ai.chat({ messages })       // text generation
   ai.stream({ messages })     // streaming
   ai.embed("text")            // embedding
@@ -108,6 +127,7 @@ const receipt = await ai.vision.extractText({
     title: "🤖 Workflow Agent",
     table: `| Function | Type | Description |
 | :--- | :--- | :--- |
+| \`createWorkflowAgent()\` | \`factory\` | Compose the starter with an injected AI SDK language model |
 | \`runAgent\` | \`workflow\` | Durable multi-step agent entrypoint |
 | \`wf.step()\` | \`runtime\` | Memoized checkpoint step |
 | \`wf.parallel()\` | \`runtime\` | Branch fan-out with partial progress retention |
@@ -115,8 +135,15 @@ const receipt = await ai.vision.extractText({
 | \`workflows.signal()\` | \`mutation\` | Wake waiting workflow with payload |`,
     usage: `\`\`\`typescript
 import { api } from "@/gencow/api";
+import { createGencowAI } from "@/gencow/ai";
+import { createWorkflowAgent } from "@/gencow/agent";
 import { useMutation, useWorkflow } from "@gencow/react";
 
+const gencow = createGencowAI();
+export const customRunAgent = createWorkflowAgent({
+    model: gencow.languageModel("gpt-5.4-mini"),
+});
+
 const { mutate: start } = useMutation(api.agents.run);
 const { mutate: signal } = useMutation(api.workflows.signal);
 
@@ -131,6 +158,7 @@ await signal({
 \`\`\``,
     vibePrompt: `Workflow Agent Starter:
   workflow("agents.run", { args, handler })     // durable start entrypoint
+  createWorkflowAgent({ model })                // pure AI SDK composition
   wf.step("plan", fn)                           // memoized checkpoint
   wf.parallel([taskA, taskB])                   // branch fan-out
   wf.waitForEvent("approval")                   // human approval checkpoint
@@ -141,6 +169,7 @@ await signal({
     title: "🔍 RAG Engine",
     table: `| Function | Type | Description |
 | :--- | :--- | :--- |
+| \`createRag()\` | \`factory\` | Compose RAG with injected embedding and answer models |
 | \`rag.ingest()\` | \`function\` | Document chunking plus embedding storage |
 | \`rag.retrieve()\` | \`function\` | Relevant document retrieval; currently vector search, hybrid-ready |
 | \`rag.search()\` | \`function\` | \`rag.retrieve()\` compatibility alias |
@@ -150,7 +179,14 @@ await signal({
 | \`rag.extractTopics()\` | \`function\` | Topic extraction grounded answer |
 | \`rag.delete()\` | \`function\` | Delete documents by source |`,
     usage: `\`\`\`typescript
-import { rag } from "@/gencow/rag";
+import { createGencowAI } from "@/gencow/ai";
+import { createRag, rag } from "@/gencow/rag";
+
+const gencow = createGencowAI();
+const customRag = createRag({
+    embeddingModel: gencow.embeddingModel("text-embedding-3-small"),
+    answerModel: gencow.languageModel("gpt-5.4-mini"),
+});
 
 // Legacy local RAG path: ingest documents into rag_documents.
 await rag.ingest(ctx, "manual.pdf", documentText, { strategy: "markdown" });
@@ -175,6 +211,7 @@ await rag.delete(ctx, "old-manual.pdf");
 \`\`\``,
     vibePrompt: `RAG Engine API:
   import { rag } from "@/gencow/rag";
+  createRag({ embeddingModel, answerModel }) // pure AI SDK composition
   rag.ingest(ctx, source, text)              // document ingest with smart chunking
   rag.retrieve(ctx, query, { filter })       // relevant document retrieval
   rag.search(ctx, query, { filter })         // compatibility alias
@@ -237,6 +274,8 @@ const hybrid = await hybridSearchRecords(ctx, "searchable_docs", "refund", {
 | \`defineTools()\` | \`function\` | Define AI tools with ctx injection |`,
     usage: `\`\`\`typescript
 import { defineTools } from "@/gencow/tools";
+import { generateText } from "ai";
+import { createGencowAI } from "@/gencow/ai";
 
 const tools = defineTools(ctx, {
     getOrderStatus: {
@@ -250,21 +289,35 @@ const tools = defineTools(ctx, {
 });
 
 const reply = await ai.chat({ messages, tools });
+const sdkReply = await generateText({
+    model: createGencowAI().languageModel("gpt-5.4-mini"),
+    messages,
+    tools,
+});
 \`\`\``,
     vibePrompt: `Tool Calling API:
   import { defineTools } from "@/gencow/tools";
   const tools = defineTools(ctx, { ... })  // define AI tools
+  generateText({ model, messages, tools }) // pure AI SDK tool call
   ai.chat({ messages, tools })             // respond with tool calls`,
   },
   "memory.ts": {
     title: "🧠 Agent Memory",
     table: `| Function | Type | Description |
 | :--- | :--- | :--- |
+| \`createMemory()\` | \`factory\` | Compose memory with injected extraction and embedding models |
 | \`memory.extract()\` | \`function\` | Automatically extract facts from conversations |
 | \`memory.search()\` | \`function\` | Semantic search over related memories |
 | \`memory.buildContext()\` | \`function\` | Compose memory context for agents |`,
     usage: `\`\`\`typescript
-import { memory } from "@/gencow/memory";
+import { createGencowAI } from "@/gencow/ai";
+import { createMemory, memory } from "@/gencow/memory";
+
+const gencow = createGencowAI();
+const customMemory = createMemory({
+    extractionModel: gencow.languageModel("gpt-5.4-mini"),
+    embeddingModel: gencow.embeddingModel("text-embedding-3-small"),
+});
 
 const memCtx = await memory.buildContext(ctx, userId, sessionId, query);
 const reply = await ai.chat({
@@ -274,6 +327,7 @@ const reply = await ai.chat({
 \`\`\``,
     vibePrompt: `Agent Memory API:
   import { memory } from "@/gencow/memory";
+  createMemory({ extractionModel, embeddingModel }) // pure AI SDK composition
   memory.buildContext(ctx, userId, sessionId, query)  // memory context
   memory.extract(ctx, userId, conversation)           // fact extraction`,
   },
@@ -293,14 +347,23 @@ const reply = await ai.chat({
     title: "🎯 Reranker",
     table: `| Function | Type | Description |
 | :--- | :--- | :--- |
-| \`reranker.rerank()\` | \`function\` | LLM-based search result reranking |
+| \`createReranker()\` | \`factory\` | Compose reranking with an injected AI SDK reranking model |
+| \`reranker.rerank()\` | \`function\` | AI SDK rerank primary path with explicit LLM compatibility fallback |
 | \`reranker.searchAndRerank()\` | \`function\` | Integrated RAG search plus rerank |
 | \`reranker.answerGrounded()\` | \`function\` | Phase 3 grounded answer helper |`,
     usage: `\`\`\`typescript
-import { reranker } from "@/gencow/reranker";
+import { createGencowAI } from "@/gencow/ai";
+import { createReranker, reranker } from "@/gencow/reranker";
 import { rag } from "@/gencow/rag";
 
-// Rerank vector search results with an LLM.
+const gencow = createGencowAI();
+const customReranker = createReranker({
+    rerankingModel: gencow.rerankingModel("Cohere-rerank-v4.0-fast"),
+    fallbackModel: gencow.languageModel("gpt-5.4-mini"),
+});
+
+// Rerank vector search results with the proxy-backed AI SDK rerank path.
+// In local direct mode, the generated starter can use the fallback model path.
 const results = await rag.retrieve(ctx, query, { limit: 20 });
 const reranked = await reranker.rerank(query, results, { topK: 5 });
 
@@ -312,7 +375,8 @@ const grounded = await reranker.answerGrounded(ctx, query, { corpus: "default" }
 \`\`\``,
     vibePrompt: `Reranker API:
   import { reranker } from "@/gencow/reranker";
-  reranker.rerank(query, docs, { topK: 5 })  // LLM rerank
+  createReranker({ rerankingModel, fallbackModel }) // pure AI SDK + compat fallback
+  reranker.rerank(query, docs, { topK: 5 })         // SDK rerank primary, compat fallback secondary
   reranker.searchAndRerank(ctx, rag, query)   // integrated pipeline
   reranker.answerGrounded(ctx, query, opts)   // grounded answer`,
   },
@@ -320,11 +384,18 @@ const grounded = await reranker.answerGrounded(ctx, query, { corpus: "default" }
     title: "🛡️ Guardrails",
     table: `| Function | Type | Description |
 | :--- | :--- | :--- |
+| \`createGuardrails()\` | \`factory\` | Compose guardrails with an injected AI SDK language model |
 | \`guardrails.validateInput()\` | \`function\` | Input validation for PII, topics, and length |
 | \`guardrails.validateOutput()\` | \`function\` | Output validation for length, patterns, and custom checks |
 | \`guardrails.wrap()\` | \`function\` | Wrap input, AI call, and output validation in one helper |`,
     usage: `\`\`\`typescript
-import { guardrails } from "@/gencow/guardrails";
+import { createGencowAI } from "@/gencow/ai";
+import { createGuardrails, guardrails } from "@/gencow/guardrails";
+
+const gencow = createGencowAI();
+const customGuardrails = createGuardrails({
+    model: gencow.languageModel("gpt-5.4-mini"),
+});
 
 // Mask PII and block disallowed topics.
 const safe = await guardrails.validateInput(userMsg, {
@@ -343,6 +414,7 @@ const result = await guardrails.wrap(
 \`\`\``,
     vibePrompt: `Guardrails API:
   import { guardrails } from "@/gencow/guardrails";
+  createGuardrails({ model })                            // pure AI SDK composition
   guardrails.validateInput(text, { maskPII: true })  // PII masking
   guardrails.validateInput(text, { blockTopics })     // topic blocking
   guardrails.wrap(fn, input, inputOpts, outputOpts)   // one-call wrapper`,

package/lib/readme-codegen.mjs

@@ -291,11 +291,13 @@ export function buildAiPrompt(apiObj, namespaces) {
   md += `- Prefer SHA-256 with node:crypto or Web Crypto API instead of custom 32-bit hashes.\n`;
   md += `  const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));\n\n`;
   md += `AI rules:\n`;
-  md += `- New AI SDK-native code can use createGencowAI() from "./ai" with generateText(), embed(), and generateImage().\n`;
+  md += `- New AI SDK-native code can use createGencowAI() from "./ai" with generateText(), embed(), rerank(), and generateImage().\n`;
   md += `- Existing generated components can use ai.chat(), ai.rerank(), ai.vision.extractText(), ai.image.generate(), and ai.generateObject() through the Gencow facade.\n`;
   md += `- Do not import @ai-sdk/openai/createOpenAI directly, call provider APIs directly, or create wrapper files such as openai-direct.ts.\n`;
   md += `- Do not log image base64, prompts, provider tokens, or raw private document snippets.\n`;
-  md += `- Use ai.rerank() only after retrieval authorization; do not pass private metadata as provider payload.\n`;
+  md += `- Use rerank({ model: createGencowAI().rerankingModel(...) }) or ai.rerank() only after retrieval authorization; do not pass private metadata as provider payload.\n`;
+  md += `- createGencowAI().rerankingModel(...) is proxy-only today. Local direct mode with only OPENAI_API_KEY must fail fast for reranking.\n`;
+  md += `- The generated reranker starter may use an explicit fallbackModel compatibility path, but strict providerPreference such as azure_cohere must still fail closed on auth/config errors.\n`;
   md += `- Recommended chat models: gpt-5.4-mini for most apps, gpt-5.4 for Pro/Scale highest quality, gpt-5.4-nano for high-volume extraction.\n`;
   md += `- Use ai.generateObject() with a Zod schema for structured output. Do not use ai.chat() + JSON.parse().\n`;
   md += `- Install AI with gencow add AI, RAG with gencow add RAG, Memory with gencow add Memory, and durable agents with gencow add Agent.\n`;
@@ -308,7 +310,7 @@ export function buildAiUsageSection() {
   md += `Gencow supports an Azure-first active chat catalog: gpt-5.4 on Pro/Scale, gpt-5.4-mini by default, gpt-5.4-nano for high volume, plus compatibility models gpt-5-mini and gpt-5-nano. Deprecated requests such as \`gpt-5.5\` and \`gpt-4o-mini\` are automatically substituted to the closest supported model before provider execution. Image and embedding models are also controlled by the platform \`model_pricing\` catalog.\n`;
   md += `Local development uses \`OPENAI_API_KEY\`; cloud deployments automatically use the Gencow AI proxy and service credits.\n\n`;
   md += `\`\`\`typescript\n`;
-  md += `import { generateImage, generateText } from "ai";\n`;
+  md += `import { generateImage, generateText, rerank } from "ai";\n`;
   md += `import { createGencowAI, ai } from "./ai";\n\n`;
   md += `const gencow = createGencowAI();\n\n`;
   md += `const result = await generateText({\n`;
@@ -320,6 +322,12 @@ export function buildAiUsageSection() {
   md += `  model: gencow.imageModel("gpt-image-2"),\n`;
   md += `  prompt: "A clean app icon for a project management product",\n`;
   md += `});\n\n`;
+  md += `const ranked = await rerank({\n`;
+  md += `  model: gencow.rerankingModel("Cohere-rerank-v4.0-fast"),\n`;
+  md += `  documents: ["Refunds are available within 7 days.", "Shipping takes 2 days."],\n`;
+  md += `  query: "refund policy",\n`;
+  md += `  topN: 1,\n`;
+  md += `});\n\n`;
   md += `const icon = await ai.image.generate({\n`;
   md += `  prompt: "A clean app icon for a project management product",\n`;
   md += `  model: "gpt-image-2",\n`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gencow",
-  "version": "0.1.169",
+  "version": "0.1.171",
   "description": "Gencow — AI Backend Engine",
   "type": "module",
   "bin": {