gencow 0.1.75 → 0.1.76

package/bin/gencow.mjs

@@ -23,6 +23,7 @@ import { resolve, dirname, basename } from "path";
 import { homedir } from "os";
 import { fileURLToPath } from "url";
 import { createRequire } from "module";
+import { buildReadmeMarkdown, extractComponentsBlock } from "../lib/readme-codegen.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -416,316 +417,21 @@ process.exit(0);
 // Pure logic lives in lib/readme-codegen.mjs (testable).
 // This wrapper handles only file I/O.
 
+
 function generateReadmeMd(config, apiObj) {
     const absoluteFunctions = resolve(process.cwd(), config.functionsDir);
     const readmePath = resolve(absoluteFunctions, "README.md");
 
-
-    const now = new Date().toLocaleString("ko-KR");
-    const namespaces = Object.keys(apiObj);
-
-    let 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 += `## 📦 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`;
-    }
-
-    // ── 1-1. React 사용법 (Primary — 최상단 배치) ────────────
-    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]});  // ${ns.charAt(0).toUpperCase() + ns.slice(1)}[] | undefined\n`;
-        }
-        if (fns.mutations.length > 0) {
-            md += `// ${ns} 데이터 변경 (로딩/에러 자동 관리)\n`;
-            md += `const [${fns.mutations[0]}${ns.charAt(0).toUpperCase() + ns.slice(1)}, isPending] = useMutation(api.${ns}.${fns.mutations[0]});\n`;
-        }
-        md += `\n`;
-    }
-    md += `\`\`\`\n\n`;
-    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`;
-    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`;
-
-    // ── 1-2. Auth ────────────────────────────────────────────
-    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 += `### Next.js 프론트엔드 연동 (필수)\n\n`;
-    md += `프론트엔드(localhost:3000)와 백엔드(localhost:5456)가 다른 포트에서 실행되므로,\n`;
-    md += `\`next.config.ts\`에 rewrites 프록시를 설정해야 인증이 작동합니다:\n\n`;
-    md += `\`\`\`typescript\n`;
-    md += `// next.config.ts\n`;
-    md += `const nextConfig = {\n`;
-    md += `    async rewrites() {\n`;
-    md += `        return [\n`;
-    md += `            { source: "/api/:path*", destination: "http://localhost:5456/api/:path*" },\n`;
-    md += `            { source: "/ws", destination: "http://localhost:5456/ws" },\n`;
-    md += `        ];\n`;
-    md += `    },\n`;
-    md += `};\n`;
-    md += `\`\`\`\n\n`;
-    md += `또는 \`gencowAuth()\`에 명시적으로 baseUrl을 전달하세요:\n\n`;
-    md += `\`\`\`typescript\n`;
-    md += `const { signIn, useAuth } = gencowAuth(import.meta.env.VITE_API_URL || "http://localhost:5456");\n`;
-    md += `\`\`\`\n\n`;
-
-    // ── 1-3. RPC 직접 호출 (접힘 — 비-React 환경용) ──────────
-    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: 서버 내부에서 다른 함수 호출 시)\n`;
-    md += `const baseUrl = process.env.GENCOW_INTERNAL_URL || "http://localhost:5456";\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`;
-
-    // ── 3. Copy-Paste AI Prompt ────────────────────────────
-    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 += `배포 규칙:\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 += `- gencow deploy는 프론트엔드를 포함하지 않아. 반드시 별도로 --static 배포해.\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\n`;
-
-    // ── 4. AI 사용법 ────────────────────────────────────
-    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`;
-
-    // ── 5. 배포 가이드 ───────────────────────────────────
-    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`;
-
-    // ── 6. Cron Jobs ──────────────────────────────────────
-    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 || "http://localhost:5456";\n`;
-    md += `> await fetch(\`\${baseUrl}/api/mutation\`, { method: "POST", ... });\n`;
-    md += `> \`\`\`\n\n`;
-
-    // ── 7. 배포 ──────────────────────────────────────────────
-    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. 빌드 결과물 정적 배포\n`;
-    md += `gencow deploy --static dist/\n`;
-    md += `\`\`\`\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 += `### 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`;
-
-    // ── 8. Dev Tips ────────────────────────────────────────
-    md += `---\n\n## 💡 개발 팁\n\n`;
-    md += `- \`gencow/\` 폴더 내 파일을 수정하면 \`api.ts\`와 이 README가 **자동으로 재생성**됩니다.\n`;
-    md += `- 스키마 변경 후 \`gencow db:push\`를 실행하면 DB가 즉시 동기화됩니다.\n`;
-    md += `- MCP 서버를 사용하면 AI가 이 구조를 자동으로 인식합니다.\n`;
-    md += `- 로컬 개발: \`gencow dev\` → \`http://localhost:5456\`\n`;
-    md += `- Self-fetch: \`process.env.GENCOW_INTERNAL_URL\` — cron/mutation에서 다른 함수 호출 시 사용\n`;
-    md += `- .env 파일은 로컬 전용. 클라우드에는 \`gencow env push\`로 올리세요. (로컬 서버는 \`--local\`)\n`;
-
-    // ── 5. 기존 컴포넌트 섹션 보존 (gencow add로 추가된 부분) ──
-    const COMP_START = "<!-- gencow-components-start -->";
-    const COMP_END = "<!-- gencow-components-end -->";
-
+    // Preserve existing component block (added by `gencow add`)
+    let existingComponentsBlock;
     try {
         const existingReadme = readFileSync(readmePath, "utf-8");
-        if (existingReadme.includes(COMP_START)) {
-            const startIdx = existingReadme.indexOf(COMP_START);
-            const endIdx = existingReadme.indexOf(COMP_END) + COMP_END.length;
-            md += "\n" + existingReadme.slice(startIdx, endIdx) + "\n";
-        }
+        existingComponentsBlock = extractComponentsBlock(existingReadme);
     } catch { /* README doesn't exist yet */ }
 
+    // Generate README content using the canonical pure function
+    const md = buildReadmeMarkdown(apiObj, { existingComponentsBlock });
+
     writeFileSync(readmePath, md);
     success(`Generated ${config.functionsDir}/README.md (AI vibe-coding guide)`);
 }
@@ -1950,11 +1656,13 @@ ${BOLD}Examples:${RESET}
             let staticDir = null; // --static 옵션
             let isStatic = false;
             let forceDeploy = false; // --force: skip dependency audit
+            let noBackend = false; // --no-backend: skip backend auto-deploy in --static mode
 
             for (let i = 0; i < deployArgs.length; i++) {
                 const a = deployArgs[i];
                 if (a === "--prod") envTarget = "prod";
                 else if (a === "--force" || a === "-f") forceDeploy = true;
+                else if (a === "--no-backend") noBackend = true;
                 else if (a === "--app" || a === "-a") appId = deployArgs[++i];
                 else if (a === "--static") {
                     isStatic = true;
@@ -1985,7 +1693,7 @@ ${BOLD}Examples:${RESET}
 
             // ── Static Deploy 분기 ────────────────────────────────
             if (isStatic) {
-                return await this._deployStatic(creds, appId, displayName, staticDir, gencowJsonPath);
+                return await this._deployStatic(creds, appId, displayName, staticDir, gencowJsonPath, { forceDeploy, noBackend, envTarget });
             }
 
             log(`\n${BOLD}${CYAN}Gencow Deploy${RESET}\n`);
@@ -2200,7 +1908,9 @@ ${BOLD}Examples:${RESET}
         },
 
     // ── deploy --static 내부 헬퍼 ─────────────────────────
-    async _deployStatic(creds, appId, displayName, staticDirArg, gencowJsonPath) {
+    async _deployStatic(creds, appId, displayName, staticDirArg, gencowJsonPath, opts = {}) {
+            const { forceDeploy = false, noBackend = false, envTarget = "dev" } = opts;
+
             // 정적 폴더 자동 감지
             const AUTO_DETECT = ["dist", "out", "build", ".next/out"];
             let targetDir = staticDirArg;
@@ -2222,8 +1932,24 @@ ${BOLD}Examples:${RESET}
                 process.exit(1);
             }
 
-            log(`\n${BOLD}${CYAN}Gencow Static Deploy${RESET}\n`);
-            info(`폴더:  ${targetDir}/`);
+            // ── 백엔드 감지: CWD 또는 상위 디렉토리에 gencow/ 존재 여부 ──
+            const parentDir = resolve(process.cwd(), "..");
+            const hasCwdBackend = existsSync(resolve(process.cwd(), "gencow"))
+                && existsSync(resolve(process.cwd(), "package.json"));
+            const hasParentBackend = existsSync(resolve(parentDir, "gencow"))
+                && (existsSync(resolve(parentDir, "gencow.config.ts")) || existsSync(resolve(parentDir, "package.json")));
+            const detectedBackend = hasCwdBackend || hasParentBackend;
+            const backendRoot = hasCwdBackend ? process.cwd() : (hasParentBackend ? parentDir : null);
+            const shouldDeployBackend = detectedBackend && !noBackend;
+
+            if (shouldDeployBackend) {
+                log(`\n${BOLD}${CYAN}Gencow Deploy (Fullstack)${RESET}\n`);
+                info(`백엔드 감지: ${backendRoot === process.cwd() ? "gencow/" : resolve(backendRoot, "gencow/")} (자동 배포)`);
+                info(`프론트엔드: ${targetDir}/`);
+            } else {
+                log(`\n${BOLD}${CYAN}Gencow Static Deploy${RESET}\n`);
+                info(`폴더:  ${targetDir}/`);
+            }
             if (appId) {
                 info(`앱 ID: ${appId}`);
             } else {
@@ -2231,65 +1957,152 @@ ${BOLD}Examples:${RESET}
             }
             log("");
 
-            // ── 가드레일 1: 빌드 결과물 API 참조 스캔 ──────────────
-            try {
-                const fullTargetDir = resolve(process.cwd(), targetDir);
-                const scanDir = (dir) => {
-                    const entries = readdirSync(dir, { withFileTypes: true });
-                    const files = [];
-                    for (const e of entries) {
-                        const p = resolve(dir, e.name);
-                        if (e.isDirectory() && e.name !== "node_modules") {
-                            files.push(...scanDir(p));
-                        } else if (e.isFile() && e.name.endsWith(".js")) {
-                            files.push(p);
+            // ── 가드레일: 빌드 결과물 API 참조 스캔 ───────────────
+            // 백엔드 자동 배포 시에는 API 서버가 존재하므로 경고 불필요
+            if (!shouldDeployBackend) {
+                try {
+                    const fullTargetDir = resolve(process.cwd(), targetDir);
+                    const scanDir = (dir) => {
+                        const entries = readdirSync(dir, { withFileTypes: true });
+                        const files = [];
+                        for (const e of entries) {
+                            const p = resolve(dir, e.name);
+                            if (e.isDirectory() && e.name !== "node_modules") {
+                                files.push(...scanDir(p));
+                            } else if (e.isFile() && e.name.endsWith(".js")) {
+                                files.push(p);
+                            }
+                        }
+                        return files;
+                    };
+                    const jsFiles = scanDir(fullTargetDir);
+                    const apiRefFiles = [];
+                    for (const f of jsFiles) {
+                        const content = readFileSync(f, "utf8");
+                        if (content.includes("/api/query") || content.includes("/api/mutation")) {
+                            apiRefFiles.push(f.replace(fullTargetDir + "/", ""));
                         }
                     }
-                    return files;
-                };
-                const jsFiles = scanDir(fullTargetDir);
-                const apiRefFiles = [];
-                for (const f of jsFiles) {
-                    const content = readFileSync(f, "utf8");
-                    if (content.includes("/api/query") || content.includes("/api/mutation")) {
-                        apiRefFiles.push(f.replace(fullTargetDir + "/", ""));
+                    if (apiRefFiles.length > 0) {
+                        log("");
+                        warn(`빌드 파일에서 API 참조가 발견되었습니다:`);
+                        for (const f of apiRefFiles.slice(0, 5)) log(`    ${DIM}- ${f}${RESET}`);
+                        if (apiRefFiles.length > 5) log(`    ${DIM}... 외 ${apiRefFiles.length - 5}개${RESET}`);
+                        log("");
+                        warn(`정적 호스팅에는 API 서버가 없어 404가 발생합니다.`);
+                        info(`💡 백엔드가 필요하다면: ${CYAN}VITE_API_URL=https://{backend}.gencow.app npm run build${RESET} 후 배포`);
+                        info(`💡 별도 백엔드를 사용한다면: ${CYAN}VITE_API_URL${RESET} 환경변수로 빌드 대상을 지정하세요.`);
+                        log("");
+
+                        const { createInterface } = await import("readline");
+                        const rl = createInterface({ input: process.stdin, output: process.stdout });
+                        const answer = await new Promise(resolve => {
+                            rl.question(`  ${YELLOW}⚠${RESET} 그래도 정적 배포를 계속하시겠습니까? (y/N) `, resolve);
+                        });
+                        rl.close();
+                        if (answer.toLowerCase() !== "y") {
+                            info("배포 취소됨.");
+                            return;
+                        }
+                        log("");
+                    }
+                } catch { /* 스캔 실패 — 무시하고 진행 */ }
+            }
+
+            // ── 백엔드 자동 배포 (감지된 경우) ────────────────────
+            if (shouldDeployBackend) {
+                log(`  ${BOLD}── 백엔드 배포 ──────────────────────${RESET}\n`);
+
+                // 1-0. Pre-deploy dependency audit
+                if (!forceDeploy) {
+                    try {
+                        const { auditDeployDependencies, formatAuditError } = await import("../lib/deploy-auditor.mjs");
+                        const entryPoint = resolve(backendRoot, "gencow", "index.ts");
+                        if (existsSync(entryPoint)) {
+                            const auditResult = await auditDeployDependencies(entryPoint);
+                            if (!auditResult.passed) {
+                                log(formatAuditError(auditResult));
+                                process.exit(1);
+                            }
+                        }
+                    } catch (auditErr) {
+                        warn(`의존성 검사 스킵: ${auditErr.message}`);
                     }
                 }
-                if (apiRefFiles.length > 0) {
-                    log("");
-                    warn(`빌드 파일에서 API 참조가 발견되었습니다:`);
-                    for (const f of apiRefFiles.slice(0, 5)) log(`    ${DIM}- ${f}${RESET}`);
-                    if (apiRefFiles.length > 5) log(`    ${DIM}... 외 ${apiRefFiles.length - 5}개${RESET}`);
-                    log("");
-                    warn(`정적 호스팅에는 API 서버가 없어 404가 발생합니다.`);
-                    info(`💡 백엔드가 필요하다면: ${CYAN}VITE_API_URL=https://{backend}.gencow.app npm run build${RESET} 후 배포`);
-                    info(`💡 별도 백엔드를 사용한다면: ${CYAN}VITE_API_URL${RESET} 환경변수로 빌드 대상을 지정하세요.`);
-                    log("");
 
-                    const { createInterface } = await import("readline");
-                    const rl = createInterface({ input: process.stdin, output: process.stdout });
-                    const answer = await new Promise(resolve => {
-                        rl.question(`  ${YELLOW}⚠${RESET} 그래도 정적 배포를 계속하시겠습니까? (y/N) `, resolve);
-                    });
-                    rl.close();
-                    if (answer.toLowerCase() !== "y") {
-                        info("배포 취소됨.");
-                        return;
+                // 1. tar.gz 패키징 (백엔드)
+                info("백엔드 패키징 중...");
+                const { execSync: exec } = await import("child_process");
+                const tmpBackendBundle = resolve(backendRoot, ".gencow", "deploy-bundle.tar.gz");
+                mkdirSync(dirname(tmpBackendBundle), { recursive: true });
+
+                const backendFiles = ["gencow/", "package.json"];
+                if (existsSync(resolve(backendRoot, "bun.lockb"))) backendFiles.push("bun.lockb");
+                if (existsSync(resolve(backendRoot, "package-lock.json"))) backendFiles.push("package-lock.json");
+                if (existsSync(resolve(backendRoot, "tsconfig.json"))) backendFiles.push("tsconfig.json");
+
+                try {
+                    exec(`tar -czf "${tmpBackendBundle}" ${backendFiles.join(" ")}`, { cwd: backendRoot });
+                } catch (e) {
+                    error(`백엔드 패키징 실패: ${e.message}`);
+                    process.exit(1);
+                }
+
+                const backendBundleSize = statSync(tmpBackendBundle).size;
+                success(`백엔드 번들 생성: ${(backendBundleSize / 1024).toFixed(1)} KB`);
+
+                // 2. 앱이 없으면 생성
+                if (!appId) {
+                    info("앱 생성 중 (ID 자동 생성)...");
+                    const createRes = await rpcMutation(creds, "apps.create", { name: displayName });
+                    if (!createRes.ok) {
+                        const createErr = await createRes.json().catch(() => ({}));
+                        error(`앱 생성 실패: ${createErr.error || createRes.statusText}`);
+                        process.exit(1);
                     }
-                    log("");
+                    const createData = await createRes.json();
+                    appId = createData.appId || createData.name;
+                    if (!appId) {
+                        error("앱 생성 응답에 appId가 없습니다.");
+                        process.exit(1);
+                    }
+                    success(`앱 "${appId}" 생성 완료. 프로비저닝 대기 중...`);
+                    writeFileSync(gencowJsonPath, JSON.stringify({
+                        appId, displayName, platformUrl: creds.platformUrl,
+                    }, null, 2));
+                    info(`${DIM}gencow.json 생성됨 (appId: ${appId})${RESET}`);
+                    await new Promise(r => setTimeout(r, 3000));
                 }
-            } catch { /* 스캔 실패 — 무시하고 진행 */ }
 
-            // ── 가드레일 2: 동일 프로젝트 백엔드 감지 ─────────────
-            const parentDir = resolve(process.cwd(), "..");
-            const hasParentBackend = existsSync(resolve(parentDir, "gencow"))
-                || existsSync(resolve(parentDir, "gencow.config.ts"));
-            const hasSelfBackend = existsSync(resolve(process.cwd(), "..", "gencow"))
-                && process.cwd().includes("frontend");
-            if (hasParentBackend || hasSelfBackend) {
-                warn(`상위 디렉토리에 Gencow 백엔드 프로젝트가 감지되었습니다.`);
-                info(`💡 통합 배포: ${CYAN}cd ${hasSelfBackend ? ".." : resolve(parentDir)} && gencow deploy${RESET}`);
+                // 3. 백엔드 업로드
+                info("백엔드 배포 중...");
+                const backendBuffer = readFileSync(tmpBackendBundle);
+                const backendDeployRes = await platformFetch(creds, `/platform/apps/${appId}/deploy?env=${envTarget}`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/octet-stream" },
+                    body: backendBuffer,
+                });
+                try { unlinkSync(tmpBackendBundle); } catch { }
+
+                if (!backendDeployRes.ok) {
+                    const errData = await backendDeployRes.json().catch(() => ({}));
+                    error(`백엔드 배포 실패: ${errData.error || backendDeployRes.statusText}`);
+                    if (errData.crashLogs?.length) {
+                        log("");
+                        warn("서버 시작 실패 원인:");
+                        for (const line of errData.crashLogs) log(`  ${DIM}${line}${RESET}`);
+                    }
+                    error("백엔드 배포 실패로 프론트엔드 배포를 건너뜁니다.");
+                    process.exit(1);
+                }
+
+                const backendData = await backendDeployRes.json();
+                success(`백엔드 배포 완료!`);
+                info(`URL:   ${backendData.url}`);
+                info(`Hash:  ${backendData.bundleHash}`);
+                updateEnvLocalUrl(backendData.url);
                 log("");
+                log(`  ${BOLD}── 프론트엔드 배포 ──────────────────${RESET}\n`);
             }
 
             // 1. tar.gz 패키징

package/package.json

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