gencow 0.1.76 → 0.1.78

package/lib/env-parser.mjs

@@ -0,0 +1,82 @@
+/**
+ * .env File Parser — Pure function extracted from gencow.mjs buildEnv()
+ *
+ * Parses .env file content into a key-value object.
+ * Handles comments, blank lines, quoted values, and inline comments.
+ */
+
+/**
+ * Parse .env file content string into key-value pairs.
+ *
+ * Rules:
+ * - Lines starting with # are comments (ignored)
+ * - Blank lines are ignored
+ * - Format: KEY=VALUE
+ * - Quoted values: KEY="value" or KEY='value' → strips quotes
+ * - Inline comments after unquoted values are stripped
+ *
+ * @param {string} content - Raw .env file content
+ * @returns {Record<string, string>} Parsed key-value object
+ */
+export function parseEnvFile(content) {
+    const env = {};
+    if (!content) return env;
+
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+
+        // Skip empty lines and comments
+        if (!trimmed || trimmed.startsWith("#")) continue;
+
+        // Find first = sign
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx === -1) continue;
+
+        const key = trimmed.slice(0, eqIdx).trim();
+        let val = trimmed.slice(eqIdx + 1).trim();
+
+        // Strip surrounding quotes
+        if (
+            (val.startsWith('"') && val.endsWith('"')) ||
+            (val.startsWith("'") && val.endsWith("'"))
+        ) {
+            val = val.slice(1, -1);
+        }
+
+        // Skip empty keys
+        if (!key) continue;
+
+        env[key] = val;
+    }
+
+    return env;
+}
+
+/**
+ * Validate environment variable key format.
+ * Only allows alphanumeric + underscores, must start with letter or underscore.
+ *
+ * @param {string} key
+ * @returns {boolean}
+ */
+export function isValidEnvKey(key) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+}
+
+/**
+ * Serialize env object back to .env file format.
+ *
+ * @param {Record<string, string>} env
+ * @returns {string}
+ */
+export function serializeEnvFile(env) {
+    return Object.entries(env)
+        .map(([key, val]) => {
+            // Quote values containing spaces, #, or special chars
+            if (/[\s#"']/.test(val)) {
+                return `${key}="${val}"`;
+            }
+            return `${key}=${val}`;
+        })
+        .join("\n") + "\n";
+}

package/lib/project-validator.mjs

@@ -0,0 +1,89 @@
+/**
+ * Project Validator — Pure function extracted from gencow.mjs
+ *
+ * Validates gencow project structure before init/deploy.
+ */
+
+/**
+ * Validate project structure for deploy readiness.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.files - List of relative file paths in the project
+ * @param {string} opts.functionsDir - Functions directory name (e.g. "gencow")
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateProjectStructure({ files, functionsDir = "gencow" }) {
+    const errors = [];
+    const warnings = [];
+
+    // Required: index.ts or index.js in functions dir
+    const hasIndex = files.some(
+        (f) =>
+            f === `${functionsDir}/index.ts` ||
+            f === `${functionsDir}/index.js`
+    );
+    if (!hasIndex) {
+        errors.push(`${functionsDir}/index.ts が見つかりません (必須)`);
+    }
+
+    // Required: schema.ts
+    const hasSchema = files.some(
+        (f) =>
+            f === `${functionsDir}/schema.ts` ||
+            f === `${functionsDir}/schema.js`
+    );
+    if (!hasSchema) {
+        errors.push(`${functionsDir}/schema.ts が見つかりません (必須)`);
+    }
+
+    // Warning: no package.json
+    const hasPackageJson = files.some((f) => f === "package.json");
+    if (!hasPackageJson) {
+        warnings.push("package.json が見つかりません");
+    }
+
+    // Warning: crons.ts exists but not exported from index
+    const hasCrons = files.some(
+        (f) =>
+            f === `${functionsDir}/crons.ts` ||
+            f === `${functionsDir}/crons.js`
+    );
+    if (hasCrons) {
+        // Can't check content here (pure function), but flag for awareness
+        warnings.push(
+            `${functionsDir}/crons.ts が見つかりました — export default crons を忘れないでください`
+        );
+    }
+
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+
+/**
+ * Check if a file should be excluded from deploy bundle.
+ *
+ * @param {string} filePath - Relative file path
+ * @returns {boolean} true if file should be excluded
+ */
+export function shouldExcludeFromDeploy(filePath) {
+    const excludePatterns = [
+        /node_modules\//,
+        /\.git\//,
+        /\.gencow\//,
+        /\.env$/,
+        /\.env\.local$/,
+        /\.DS_Store$/,
+        /dist\//,
+        /\.next\//,
+        /\.turbo\//,
+        /coverage\//,
+        /__tests__\//,
+        /\.test\.(ts|js|tsx|jsx)$/,
+        /\.spec\.(ts|js|tsx|jsx)$/,
+    ];
+
+    return excludePatterns.some((pattern) => pattern.test(filePath));
+}

package/lib/readme-codegen.mjs

@@ -0,0 +1,510 @@
+/**
+ * README Codegen — Pure function extracted from gencow.mjs generateReadmeMd()
+ *
+ * Generates gencow/README.md content for AI vibe-coding.
+ * This module is purely functional: takes API object, returns markdown string.
+ * File I/O remains in gencow.mjs.
+ */
+
+/**
+ * @typedef {{ queries: string[], mutations: string[] }} NamespaceFns
+ * @typedef {Record<string, NamespaceFns>} ApiObj
+ * @typedef {{ timestamp?: string, existingComponentsBlock?: string }} ReadmeOpts
+ */
+
+/**
+ * Build the full README.md markdown content for a Gencow project.
+ *
+ * @param {ApiObj} apiObj - API namespace map (e.g. { tasks: { queries: ['list'], mutations: ['create'] } })
+ * @param {ReadmeOpts} [opts] - Optional overrides
+ * @returns {string} Complete README.md content
+ */
+export function buildReadmeMarkdown(apiObj, opts = {}) {
+    const now = opts.timestamp || new Date().toLocaleString("ko-KR");
+    const namespaces = Object.keys(apiObj);
+
+    let md = "";
+
+    // ── Header ────────────────────────────────────────────
+    md += `# Gencow API Guide\n`;
+    md += `> ⚡ Auto-generated by Gencow CLI — do not edit manually.\n`;
+    md += `> Last updated: ${now}\n`;
+    md += `> 📚 Gencow 공식 문서 (전체 참조): https://docs.gencow.com/llms-full.txt\n\n`;
+    md += `---\n\n`;
+
+    // ── 1. API Reference Table ────────────────────────────
+    md += buildApiTable(apiObj);
+
+    // ── 2. React 사용법 ──────────────────────────────────
+    md += buildReactUsage(apiObj);
+
+    // ── 2.5. 프론트엔드 초기 설정 ────────────────────────
+    md += buildFrontendSetup();
+
+    // ── 3. Auth ──────────────────────────────────────────
+    md += buildAuthSection();
+
+    // ── 4. RPC 직접 호출 ─────────────────────────────────
+    md += buildRpcSection(apiObj, namespaces);
+
+    // ── 5. AI Vibe-Coding Prompt ─────────────────────────
+    md += buildAiPrompt(apiObj, namespaces);
+
+    // ── 6. AI 사용법 ─────────────────────────────────────
+    md += buildAiUsageSection();
+
+    // ── 7. 배포 가이드 (요약 + 상세) ─────────────────────
+    md += buildDeploySection();
+
+    // ── 8. Cron Jobs ─────────────────────────────────────
+    md += buildCronSection();
+
+    // ── 9. Dev Tips ──────────────────────────────────────
+    md += buildDevTips();
+
+    // ── 기존 컴포넌트 섹션 보존 ──────────────────────────
+    if (opts.existingComponentsBlock) {
+        md += "\n" + opts.existingComponentsBlock + "\n";
+    }
+
+    return md;
+}
+
+// ─── Section Builders (all pure) ──────────────────────────
+
+/** @param {ApiObj} apiObj */
+export function buildApiTable(apiObj) {
+    let md = `## 📦 Available APIs\n\n`;
+    for (const [ns, fns] of Object.entries(apiObj)) {
+        md += `### \`${ns}\`\n\n`;
+        md += `| Function | Type | Description |\n`;
+        md += `| :--- | :--- | :--- |\n`;
+        for (const q of fns.queries) {
+            md += `| \`api.${ns}.${q}\` | \`query\` | Fetch ${ns} data |\n`;
+        }
+        for (const m of fns.mutations) {
+            md += `| \`api.${ns}.${m}\` | \`mutation\` | Modify ${ns} data |\n`;
+        }
+        md += `\n`;
+    }
+    return md;
+}
+
+/** @param {ApiObj} apiObj */
+export function buildReactUsage(apiObj) {
+    let md = `---\n\n## ⚡ 데이터 사용법 (필수 — 반드시 이 방식을 사용하세요)\n\n`;
+    md += `> ⚠️ **\`useQuery\` / \`useMutation\` Hook을 반드시 사용하세요.**\n`;
+    md += `> Gencow는 WebSocket 실시간 동기화를 내장하고 있어, Hook을 사용하면 데이터가 **자동으로 동기화**됩니다.\n`;
+    md += `> \`fetch()\`를 직접 호출하거나 \`apiPost()\` 같은 래퍼를 만들지 마세요.\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `import { api } from "@/gencow/api";  // 자동 생성됨\n`;
+    md += `import { useQuery, useMutation } from "@gencow/react";\n\n`;
+    for (const [ns, fns] of Object.entries(apiObj)) {
+        if (fns.queries.length > 0) {
+            md += `// ${ns} 데이터 조회 (실시간 자동 갱신)\n`;
+            md += `const ${ns} = useQuery(api.${ns}.${fns.queries[0]});  // ${capitalize(ns)}[] | undefined\n`;
+        }
+        if (fns.mutations.length > 0) {
+            md += `// ${ns} 데이터 변경 (로딩/에러 자동 관리)\n`;
+            md += `const [${fns.mutations[0]}${capitalize(ns)}, isPending] = useMutation(api.${ns}.${fns.mutations[0]});\n`;
+        }
+        md += `\n`;
+    }
+    md += `\`\`\`\n\n`;
+
+    // Anti-pattern
+    md += `### ❌ 절대 하지 마세요\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `// ❌ fetch()로 직접 API 호출하지 마세요\n`;
+    md += `fetch("/api/query", { body: JSON.stringify({ name: "tasks.create", args: {...} }) })\n`;
+    md += `apiPost("tasks/create", { ... })  // ❌ 래퍼도 만들지 마세요\n\n`;
+    md += `// ✅ useMutation을 사용하세요 — 실시간 동기화 + 로딩 상태 자동 관리\n`;
+    md += `const [create] = useMutation(api.tasks.create);\n`;
+    md += `await create({ title: "새 태스크" });\n`;
+    md += `// → 서버가 WebSocket으로 useQuery를 자동 갱신 — fetchTasks() 같은 수동 리페치 불필요!\n`;
+    md += `\`\`\`\n\n`;
+
+    // Conditional query
+    md += `### 조건부 쿼리 (skip/enabled)\n\n`;
+    md += `선택된 항목이 없을 때 등 조건부로 쿼리를 건너뛰어야 할 때:\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `// 방법 A: "skip" 토큰 (Convex 스타일) — 추천\n`;
+    md += `const messages = useQuery(api.chat.getMessages,\n`;
+    md += `    conversationId ? { conversationId } : "skip"\n`;
+    md += `);\n\n`;
+    md += `// 방법 B: enabled 옵션 (TanStack Query 스타일)\n`;
+    md += `const messages = useQuery(api.chat.getMessages,\n`;
+    md += `    { conversationId },\n`;
+    md += `    { enabled: !!conversationId }\n`;
+    md += `);\n`;
+    md += `// → skip 상태에서는 API 호출 없이 undefined 반환\n`;
+    md += `\`\`\`\n\n`;
+
+    return md;
+}
+
+export function buildFrontendSetup() {
+    let md = `---\n\n## 🏗️ 프론트엔드 초기 설정 (3단계)\n\n`;
+    md += `> 프론트엔드에서 Gencow API를 사용하려면 아래 3단계를 설정하세요.\n`;
+    md += `> ⚠️ 이 설정 없이 \`useQuery\`/\`useMutation\`을 사용하면 에러가 발생합니다.\n\n`;
+    md += `### 1단계: Auth 클라이언트 생성\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `// src/lib/auth.ts\n`;
+    md += `import { gencowAuth } from "@gencow/react";\n\n`;
+    md += `// VITE_API_URL은 .env에서 자동 읽음 (gencow init 시 자동 설정)\n`;
+    md += `export const { signIn, signUp, signOut, useAuth } = gencowAuth();\n`;
+    md += `\`\`\`\n\n`;
+    md += `### 2단계: GencowProvider 설정\n\n`;
+    md += `\`\`\`tsx\n`;
+    md += `// src/main.tsx\n`;
+    md += `import { GencowProvider } from "@gencow/react";\n`;
+    md += `import { useAuth } from "./lib/auth";\n\n`;
+    md += `function App() {\n`;
+    md += `    const { token } = useAuth();\n`;
+    md += `    const baseUrl = import.meta.env.VITE_API_URL;\n`;
+    md += `    return (\n`;
+    md += `        <GencowProvider baseUrl={baseUrl} token={token}>\n`;
+    md += `            <YourApp />\n`;
+    md += `        </GencowProvider>\n`;
+    md += `    );\n`;
+    md += `}\n`;
+    md += `\`\`\`\n\n`;
+    md += `### 3단계: api.ts import 후 Hook 사용\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `import { api } from "@/gencow/api";  // gencow dev가 자동 생성\n`;
+    md += `import { useQuery, useMutation } from "@gencow/react";\n\n`;
+    md += `const tasks = useQuery(api.tasks.list);          // 실시간 구독\n`;
+    md += `const [create] = useMutation(api.tasks.create);  // 데이터 변경\n`;
+    md += `\`\`\`\n\n`;
+    md += `### ❌ 흔한 실수\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `// ❌ 문자열을 전달하지 마세요 — 타입 에러 발생\n`;
+    md += `useQuery("tasks.list");  // TS2345: string은 QueryDef에 할당 불가\n\n`;
+    md += `// ✅ api 객체의 정의를 전달하세요\n`;
+    md += `useQuery(api.tasks.list);\n\n`;
+    md += `// ❌ GencowProvider props\n`;
+    md += `<GencowProvider url="http://...">   // 'url' prop은 없습니다\n\n`;
+    md += `// ✅ baseUrl + token을 사용하세요\n`;
+    md += `<GencowProvider baseUrl={apiUrl} token={token}>\n`;
+    md += `\`\`\`\n\n`;
+    return md;
+}
+
+export function buildAuthSection() {
+    let md = `---\n\n## 🔐 인증 (better-auth, 세션 기반)\n\n`;
+    md += `| 엔드포인트 | 메서드 | 설명 |\n`;
+    md += `| :--- | :--- | :--- |\n`;
+    md += `| \`/api/auth/sign-up/email\` | POST | 회원가입 (\`{ email, password, name }\`) |\n`;
+    md += `| \`/api/auth/sign-in/email\` | POST | 로그인 (\`{ email, password }\`) |\n`;
+    md += `| \`/api/auth/sign-out\` | POST | 로그아웃 |\n\n`;
+    md += `> ⚠️ 모든 API 요청에 \`credentials: "include"\`를 포함해야 합니다 (세션 쿠키 전송)\n`;
+    md += `> ⚠️ JWT 토큰이나 \`/auth/register\` 같은 커스텀 경로를 만들지 마세요.\n\n`;
+    md += `### 프론트엔드 연동 (프록시 설정)\n\n`;
+    md += `로컬 개발 시 프론트엔드와 백엔드가 다른 포트에서 실행되므로,\n`;
+    md += `프록시를 설정해야 인증이 작동합니다:\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `// vite.config.ts (Vite) 또는 next.config.ts (Next.js)\n`;
+    md += `// 로컬 개발 전용 — 배포 시에는 VITE_API_URL 환경변수 사용\n`;
+    md += `const BACKEND_URL = process.env.VITE_API_URL || "http://localhost:5456";\n`;
+    md += `// proxy: { "/api": { target: BACKEND_URL }, "/ws": { target: BACKEND_URL, ws: true } }\n`;
+    md += `\`\`\`\n\n`;
+    md += `\`gencowAuth()\` 사용 시 반드시 \`VITE_API_URL\` 환경변수를 전달하세요:\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `const { signIn, useAuth } = gencowAuth(import.meta.env.VITE_API_URL);\n`;
+    md += `\`\`\`\n\n`;
+    md += `> ⚠️ \`VITE_API_URL\`은 \`.env\`에 설정하세요. \`gencow init\` / \`gencow deploy\` 시 자동으로 설정됩니다.\n\n`;
+    return md;
+}
+
+/**
+ * @param {ApiObj} apiObj
+ * @param {string[]} namespaces
+ */
+export function buildRpcSection(apiObj, namespaces) {
+    let md = `---\n\n`;
+    md += `<details>\n`;
+    md += `<summary>📡 RPC 직접 호출 (Node.js / cURL / 비-React 환경)</summary>\n\n`;
+    md += `> ⚠️ React에서는 이 방법을 사용하지 마세요. 위의 \`useQuery\`/\`useMutation\`을 사용하세요.\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `// Query 호출 (서버 내부 self-fetch 시 GENCOW_INTERNAL_URL 자동 주입됨)\n`;
+    md += `const baseUrl = process.env.GENCOW_INTERNAL_URL; // 서버 부팅 시 자동 설정\n`;
+    md += `const res = await fetch(\`\${baseUrl}/api/query\`, {\n`;
+    md += `    method: "POST",\n`;
+    md += `    headers: { "Content-Type": "application/json" },\n`;
+    md += `    credentials: "include",\n`;
+    if (namespaces.length > 0 && Object.values(apiObj)[0]?.queries?.[0]) {
+        md += `    body: JSON.stringify({ name: "${namespaces[0]}.${Object.values(apiObj)[0].queries[0]}", args: {} }),\n`;
+    } else {
+        md += `    body: JSON.stringify({ name: "namespace.functionName", args: {} }),\n`;
+    }
+    md += `});\n\n`;
+    if (Object.values(apiObj)[0]?.mutations?.length > 0) {
+        const firstMut = Object.values(apiObj)[0].mutations[0];
+        md += `// Mutation 호출\n`;
+        md += `const res = await fetch(\`\${baseUrl}/api/mutation\`, {\n`;
+        md += `    method: "POST",\n`;
+        md += `    headers: { "Content-Type": "application/json" },\n`;
+        md += `    credentials: "include",\n`;
+        md += `    body: JSON.stringify({ name: "${namespaces[0]}.${firstMut}", args: { /* ... */ } }),\n`;
+        md += `});\n`;
+    }
+    md += `\`\`\`\n\n`;
+    md += `</details>\n\n`;
+    return md;
+}
+
+/**
+ * @param {ApiObj} apiObj
+ * @param {string[]} namespaces
+ */
+export function buildAiPrompt(apiObj, namespaces) {
+    let md = `---\n\n## 🤖 AI Vibe-Coding Prompt (복사해서 AI에게 전달)\n\n`;
+    md += `> 아래 프롬프트를 Cursor / Claude / ChatGPT에 붙여넣으세요.\n\n`;
+    md += `\`\`\`\n`;
+    md += `다음은 현재 Gencow 백엔드에 등록된 API 구조야:\n\n`;
+    for (const [ns, fns] of Object.entries(apiObj)) {
+        md += `[${ns}]\n`;
+        for (const q of fns.queries) md += `  - api.${ns}.${q} (query)\n`;
+        for (const m of fns.mutations) md += `  - api.${ns}.${m} (mutation)\n`;
+    }
+    md += `\n`;
+    md += `React Hook 사용법:\n`;
+    md += `  useQuery(api.namespace.fnName)        // 데이터 구독 (실시간 자동 갱신)\n`;
+    md += `  useMutation(api.namespace.fnName)     // 데이터 변경 (로딩/에러 자동 관리)\n`;
+    md += `\n`;
+    md += `⚠️ 중요 규칙:\n`;
+    md += `- 반드시 useQuery와 useMutation을 사용해서 데이터와 연결해줘.\n`;
+    md += `- fetch()를 직접 호출하거나 apiPost() 같은 래퍼를 만들지 마.\n`;
+    md += `- gencow/api.ts는 자동 생성된 파일이야. 수동으로 만들지 마.\n`;
+    md += `- gencow/index.ts의 re-export는 export * as moduleName from "./moduleName" 패턴을 써.\n`;
+    md += `  Module, Mod 같은 접미사를 붙이지 마.\n`;
+    md += `\n`;
+    md += `⚠️ mutation 제한:\n`;
+    md += `- mutation은 10초 이내에 완료되어야 해. 외부 API나 LLM 호출이 길면 단계별로 분리해.\n`;
+    md += `- 긴 작업은 ctx.scheduler.runAfter(0, "module.nextStep", { sessionId }) 로 다음 단계를 예약.\n`;
+    md += `- 예: 크롤링(Step1) → 필터링(Step2) → 요약(Step3) 각각 별도 mutation으로 분리.\n`;
+    md += `- 같은 서버의 다른 모듈 함수를 호출할 때는 fetch()가 아닌 직접 import해서 호출해.\n`;
+    md += `  예: import { fetchNews } from "./naverApi"; → const result = await fetchNews.handler(ctx, { keyword });\n`;
+    md += `  HTTP self-fetch (fetch("/api/mutation")) 패턴은 불필요한 네트워크 우회이므로 사용하지 마.\n`;
+    md += `\n`;
+    md += `크론 잡 (예약 작업):\n`;
+    md += `  gencow/crons.ts에서 cronJobs()로 선언\n`;
+    md += `  crons.interval("name", { minutes: N }, "module.mutation")\n`;
+    md += `  crons.daily("name", { hour: H }, "module.mutation")\n`;
+    md += `  crons.weekly("name", { dayOfWeek: D, hour: H }, "module.mutation")\n`;
+    md += `  crons.cron("name", "cron-expression", "module.mutation")\n`;
+    md += `  반드시 export default crons 필요\n`;
+    md += `\n`;
+    md += `위 API를 기반으로 Next.js + Tailwind CSS UI 컴포넌트를 만들어줘.\n`;
+    md += `- TypeScript 타입을 최대한 활용하고, 로딩/에러 상태도 처리해줘.\n`;
+    md += `- ctx.ai.chat()을 사용해서 AI를 호출하고, OpenAI SDK를 직접 설치하지 마.\n`;
+    md += `배포 규칙:\n`;
+    md += `- 백엔드: \`npx gencow deploy\` (gencow/ 폴더만 배포됨. 프론트엔드는 포함 안 됨)\n`;
+    md += `- 풀스택: VITE_API_URL=https://{앱ID}.gencow.app npm run build 후 \`npx gencow deploy --static dist/\`\n`;
+    md += `  → 백엔드가 감지되면 자동으로 백엔드 먼저 배포 후 프론트엔드 배포\n`;
+    md += `- 프론트엔드만 배포: \`npx gencow deploy --static --no-backend dist/\`\n`;
+    md += `- 환경변수는 \`npx gencow env set KEY=VALUE\`로 클라우드에 설정해.\n`;
+    md += `- .env 파일은 로컬 개발 전용이야. 클라우드에는 gencow env push로 올려.\n`;
+    md += `- 로컬 dev 서버에 설정하려면 \`gencow env set --local KEY=VALUE\`를 써.\n`;
+    md += `\n`;
+    md += `⚠️ 패키지 제한 (중요):\n`;
+    md += `- gencow 클라우드에서 사용 가능한 npm 패키지는 아래만 해당돼:\n`;
+    md += `  @gencow/core, drizzle-orm, better-auth, postgres, hono, ai, @ai-sdk/openai, zod, esbuild\n`;
+    md += `- npm install로 추가한 서드파티 패키지(langfuse, openai, axios, cheerio 등)는 배포 시 사용 불가.\n`;
+    md += `  배포하면 "new version unhealthy" 에러가 발생해.\n`;
+    md += `\n`;
+    md += `⚠️ 해싱/암호화:\n`;
+    md += `- node:crypto 모듈은 사용 불가. 해싱이 필요하면 Web Crypto API를 사용해:\n`;
+    md += `  const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));\n`;
+    md += `  const hex = [...new Uint8Array(hash)].map(b => b.toString(16).padStart(2, "0")).join("");\n`;
+    md += `- 직접 구현한 simpleHash 같은 32비트 해시는 충돌 위험이 있으니 SHA-256을 사용해.\n`;
+    md += `- AI 호출이 필요하면 ctx.ai.chat()을 사용해. OpenAI SDK를 직접 설치하지 마.\n`;
+    md += `\`\`\`\n\n`;
+    return md;
+}
+
+export function buildAiUsageSection() {
+    let md = `---\n\n## 🤖 AI 사용법 (ctx.ai)\n\n`;
+    md += `> Gencow는 OpenAI GPT-4o/4o-mini를 내장 지원합니다.\n`;
+    md += `> API 키 관리, 과금, 보안을 플랫폼이 자동 처리합니다.\n\n`;
+    md += `### 백엔드에서 AI 호출\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `// gencow/ai.ts\n`;
+    md += `import { mutation, v } from "@gencow/core";\n\n`;
+    md += `export const chat = mutation("ai.chat", {\n`;
+    md += `    args: { message: v.string() },\n`;
+    md += `    handler: async (ctx, args) => {\n`;
+    md += `        const result = await ctx.ai.chat({\n`;
+    md += `            model: "gpt-4o-mini",  // 또는 "gpt-4o"\n`;
+    md += `            messages: [{ role: "user", content: args.message }],\n`;
+    md += `        });\n`;
+    md += `        return result.text;\n`;
+    md += `    },\n`;
+    md += `});\n`;
+    md += `\`\`\`\n\n`;
+    md += `### 로컬 개발 설정\n\n`;
+    md += `로컬에서 AI 기능을 테스트하려면 \`.env\`에 키를 추가하세요:\n\n`;
+    md += `\`\`\`\n# .env\nOPENAI_API_KEY=sk-your-key-here\n\`\`\`\n\n`;
+    md += `> ⚠️ 배포 후에는 플랫폼 키가 자동 사용됩니다. .env의 키는 로컬 전용입니다.\n\n`;
+    md += `### ❌ 하지 마세요\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `// ❌ OpenAI SDK를 직접 설치하지 마세요\n`;
+    md += `import OpenAI from "openai";\n`;
+    md += `const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });\n\n`;
+    md += `// ✅ ctx.ai.chat()을 사용하세요 — 키 관리 + 과금 자동\n`;
+    md += `const result = await ctx.ai.chat({ model: "gpt-4o-mini", messages: [...] });\n`;
+    md += `\`\`\`\n\n`;
+    return md;
+}
+
+export function buildDeploySection() {
+    let md = `---\n\n## 🚀 배포\n\n`;
+    md += `### 클라우드 배포 (3단계)\n\n`;
+    md += `\`\`\`bash\n`;
+    md += `# 1. 로그인 (최초 1회)\n`;
+    md += `npx gencow login\n\n`;
+    md += `# 2. 배포\n`;
+    md += `npx gencow deploy\n\n`;
+    md += `# 3. 환경변수 설정 (필요 시)\n`;
+    md += `npx gencow env set DATABASE_URL=postgres://...   # 클라우드에 설정\n`;
+    md += `npx gencow env list                               # 클라우드 환경변수 목록\n`;
+    md += `\`\`\`\n\n`;
+    md += `> 배포 후 앱은 \`https://{앱이름}.gencow.app\`에서 접근 가능\n\n`;
+    md += `### 환경변수 관리\n\n`;
+    md += `| 명령어 | 설명 |\n`;
+    md += `| :--- | :--- |\n`;
+    md += `| \`gencow env list\` | 클라우드 환경변수 목록 |\n`;
+    md += `| \`gencow env set KEY=VALUE\` | 클라우드 환경변수 추가/수정 |\n`;
+    md += `| \`gencow env unset KEY\` | 클라우드 환경변수 삭제 |\n`;
+    md += `| \`gencow env push\` | .env를 클라우드에 일괄 업로드 |\n`;
+    md += `| \`--local\` 옵션 | 로컬 dev 서버 대상 (예: \`env set --local K=V\`) |\n\n`;
+
+    // 상세 배포 가이드
+    md += `---\n\n## 🚀 배포\n\n`;
+    md += `### 백엔드 API 배포\n`;
+    md += `\`\`\`bash\n`;
+    md += `gencow deploy              # gencow/ 폴더 → 클라우드 서버 배포\n`;
+    md += `\`\`\`\n\n`;
+    md += `### 프론트엔드 배포 (frontend/ 있는 경우)\n`;
+    md += `\`\`\`bash\n`;
+    md += `# 1. 백엔드 URL을 환경변수로 빌드\n`;
+    md += `cd frontend\n`;
+    md += `VITE_API_URL=https://{앱ID}.gencow.app npm run build\n\n`;
+    md += `# 2. --static 배포 — 백엔드가 감지되면 자동으로 백엔드 먼저 배포 후 프론트엔드 배포\n`;
+    md += `gencow deploy --static dist/\n`;
+    md += `\`\`\`\n\n`;
+    md += `> 💡 동일 프로젝트에 \`gencow/\` 폴더가 있으면 백엔드를 자동 감지하여 백엔드 → 프론트엔드 순서로 배포합니다.\n`;
+    md += `> 프론트엔드만 배포하려면: \`gencow deploy --static --no-backend dist/\`\n\n`;
+    md += `### 정적 사이트 전용 (API 없는 경우)\n`;
+    md += `\`\`\`bash\n`;
+    md += `gencow deploy --static dist/   # 순수 HTML/CSS/JS만 배포\n`;
+    md += `\`\`\`\n\n`;
+    md += `> ⚠️ 프론트엔드에서 API를 호출하려면 빌드 시 \`VITE_API_URL\`을 반드시 설정하세요.\n\n`;
+
+    // 패키지 제한 경고
+    md += `### ⚠️ 서드파티 npm 패키지 제한\n\n`;
+    md += `Gencow 클라우드 런타임에서 사용 가능한 패키지는 다음으로 제한됩니다:\n\n`;
+    md += `| 패키지 | 설명 |\n`;
+    md += `| :--- | :--- |\n`;
+    md += `| \`@gencow/core\` | Gencow 핵심 프레임워크 |\n`;
+    md += `| \`drizzle-orm\` | ORM (스키마, 쿼리 빌더) |\n`;
+    md += `| \`better-auth\` | 인증 시스템 |\n`;
+    md += `| \`postgres\` | PostgreSQL 드라이버 |\n`;
+    md += `| \`hono\` | HTTP 프레임워크 |\n`;
+    md += `| \`ai\`, \`@ai-sdk/*\` | AI SDK |\n`;
+    md += `| \`zod\` | 밸리데이션 |\n\n`;
+    md += `> ⚠️ \`npm install\`로 추가한 서드파티 패키지(langfuse, openai, axios 등)는 배포 시 사용할 수 없습니다.\n`;
+    md += `> 배포하면 "new version unhealthy" 에러가 발생합니다.\n`;
+    md += `> AI 호출이 필요하면 \`ctx.ai.chat()\`을 사용하세요.\n\n`;
+    md += `### CORS 설정\n\n`;
+    md += `- \`*.gencow.app\` 서브도메인 간 요청은 **자동 허용**됩니다.\n`;
+    md += `- 커스텀 도메인에서 API를 호출하려면 환경변수를 설정하세요:\n\n`;
+    md += `\`\`\`bash\n`;
+    md += `gencow env set CORS_ORIGINS=https://myapp.com,https://www.myapp.com   # 클라우드에 설정\n`;
+    md += `\`\`\`\n\n`;
+
+    // 해싱/암호화 대안
+    md += `### 🔐 해싱/암호화 (node:crypto 대안)\n\n`;
+    md += `Gencow 클라우드에서 \`node:crypto\` 모듈은 사용할 수 없습니다.\n`;
+    md += `해싱이 필요하면 **Web Crypto API** (\`crypto.subtle\`)를 사용하세요:\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `// SHA-256 해싱 (node:crypto 대신 Web Crypto API)\n`;
+    md += `async function sha256(text: string): Promise<string> {\n`;
+    md += `    const data = new TextEncoder().encode(text);\n`;
+    md += `    const hash = await crypto.subtle.digest("SHA-256", data);\n`;
+    md += `    return [...new Uint8Array(hash)]\n`;
+    md += `        .map(b => b.toString(16).padStart(2, "0"))\n`;
+    md += `        .join("");\n`;
+    md += `}\n\n`;
+    md += `// 사용 예: 중복 탐지, 캐시 키, 콘텐츠 해싱\n`;
+    md += `const articleHash = await sha256(article.url + article.title);\n`;
+    md += `\`\`\`\n\n`;
+    md += `> ⚠️ 직접 구현한 \`simpleHash()\` 같은 32비트 해시는 대량 데이터에서 충돌 위험이 있습니다.\n`;
+    md += `> 반드시 SHA-256을 사용하세요 (2^256 가능 값, 사실상 충돌 0).\n\n`;
+
+    return md;
+}
+
+export function buildCronSection() {
+    let md = `---\n\n## ⏰ Cron Jobs (예약 작업)\n\n`;
+    md += `\`gencow/crons.ts\` 파일에 선언하면 서버 시작 시 자동 등록됩니다.\n\n`;
+    md += `\`\`\`typescript\n`;
+    md += `import { cronJobs } from "@gencow/core";\n\n`;
+    md += `const crons = cronJobs();\n\n`;
+    md += `// 매 30분마다 실행\n`;
+    md += `crons.interval("sync", { minutes: 30 }, "data.sync");\n\n`;
+    md += `// 매일 오전 9시 실행 (서버 시간)\n`;
+    md += `crons.daily("report", { hour: 9 }, "reports.generate");\n\n`;
+    md += `// 매주 월요일 오전 10시\n`;
+    md += `crons.weekly("weekly", { dayOfWeek: 1, hour: 10 }, "reports.weekly");\n\n`;
+    md += `// 커스텀 cron 표현식\n`;
+    md += `crons.cron("custom", "0 */2 * * *", "custom.handler");\n\n`;
+    md += `export default crons;  // ← 필수!\n`;
+    md += `\`\`\`\n\n`;
+    md += `> ⚠️ \`export default crons\`가 없으면 서버가 cron을 인식하지 않습니다.\n`;
+    md += `> ⚠️ action 문자열은 기존 mutation 이름과 정확히 매칭되어야 합니다.\n\n`;
+    md += `> 💡 cron 핸들러에서 mutation을 호출하려면 self-fetch를 사용하세요:\n`;
+    md += `> \`\`\`typescript\n`;
+    md += `> const baseUrl = process.env.GENCOW_INTERNAL_URL; // 서버 부팅 시 자동 설정\n`;
+    md += `> await fetch(\`\${baseUrl}/api/mutation\`, { method: "POST", ... });\n`;
+    md += `> \`\`\`\n\n`;
+    return md;
+}
+
+export function buildDevTips() {
+    let md = `---\n\n## 💡 개발 팁\n\n`;
+    md += `- \`gencow/\` 폴더 내 파일을 수정하면 \`api.ts\`와 이 README가 **자동으로 재생성**됩니다.\n`;
+    md += `- 스키마 변경 후 \`gencow db:push\`를 실행하면 DB가 즉시 동기화됩니다.\n`;
+    md += `- MCP 서버를 사용하면 AI가 이 구조를 자동으로 인식합니다.\n`;
+    md += `- 로컬 개발: \`gencow dev\` — 로컬 서버 시작\n`;
+    md += `- 배포된 앱: \`https://{앱ID}.gencow.app\` — .env의 VITE_API_URL에 자동 설정됨\n`;
+    md += `- Self-fetch: \`process.env.GENCOW_INTERNAL_URL\` — cron/mutation에서 다른 함수 호출 시 사용 (자동 설정)\n`;
+    md += `- .env 파일은 로컬 전용. 클라우드에는 \`gencow env push\`로 올리세요. (로컬 서버는 \`--local\`)\n`;
+    return md;
+}
+
+// ─── Utilities ────────────────────────────────────────────
+
+/** @param {string} s */
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/** Marker constants for component block preservation */
+export const COMP_START = "<!-- gencow-components-start -->";
+export const COMP_END = "<!-- gencow-components-end -->";
+
+/**
+ * Extract the components block from existing README content.
+ * Returns the block string if found, otherwise undefined.
+ *
+ * @param {string} existingContent
+ * @returns {string | undefined}
+ */
+export function extractComponentsBlock(existingContent) {
+    if (!existingContent?.includes(COMP_START)) return undefined;
+    const startIdx = existingContent.indexOf(COMP_START);
+    const endIdx = existingContent.indexOf(COMP_END);
+    if (endIdx === -1) return undefined;
+    return existingContent.slice(startIdx, endIdx + COMP_END.length);
+}