gencow 0.1.67 → 0.1.69

package/bin/gencow.mjs

@@ -523,8 +523,9 @@ function generateReadmeMd(config, apiObj) {
     md += `<summary>📡 RPC 직접 호출 (Node.js / cURL / 비-React 환경)</summary>\n\n`;
     md += `> ⚠️ React에서는 이 방법을 사용하지 마세요. 위의 \`useQuery\`/\`useMutation\`을 사용하세요.\n\n`;
     md += `\`\`\`typescript\n`;
-    md += `// Query 호출\n`;
-    md += `const res = await fetch("http://localhost:5456/api/query", {\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`;
@@ -537,7 +538,7 @@ function generateReadmeMd(config, apiObj) {
     if (Object.values(apiObj)[0]?.mutations?.length > 0) {
         const firstMut = Object.values(apiObj)[0].mutations[0];
         md += `// Mutation 호출\n`;
-        md += `const res = await fetch("http://localhost:5456/api/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`;
@@ -566,6 +567,13 @@ function generateReadmeMd(config, apiObj) {
     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 += `\n`;
     md += `크론 잡 (예약 작업):\n`;
     md += `  gencow/crons.ts에서 cronJobs()로 선언\n`;
@@ -578,7 +586,11 @@ function generateReadmeMd(config, apiObj) {
     md += `위 API를 기반으로 Next.js + Tailwind CSS UI 컴포넌트를 만들어줘.\n`;
     md += `- TypeScript 타입을 최대한 활용하고, 로딩/에러 상태도 처리해줘.\n`;
     md += `- ctx.ai.chat()을 사용해서 AI를 호출하고, OpenAI SDK를 직접 설치하지 마.\n`;
-    md += `- 배포는 \`npx gencow deploy\`로 해.\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 += `\`\`\`\n\n`;
@@ -654,13 +666,45 @@ function generateReadmeMd(config, apiObj) {
     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`;
 
-    // ── 7. Dev Tips ────────────────────────────────────────
+    // ── 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\`로 올리세요.\n`;
 
     // ── 5. 기존 컴포넌트 섹션 보존 (gencow add로 추가된 부분) ──
@@ -919,6 +963,39 @@ const commands = {
             success("Created gencow/SECURITY.md (보안 가이드)");
         }
 
+        // 3.7. crons.ts scaffold (크론 스케줄러 — 빈 템플릿)
+        const cronsPath = resolve(gencowDir, "crons.ts");
+        if (!existsSync(cronsPath)) {
+            writeFileSync(cronsPath, `/**
+ * gencow/crons.ts
+ * 크론 스케줄러 정의 — 주기적으로 실행할 작업을 등록합니다.
+ *
+ * ⚠️ export default crons 가 없으면 서버가 cron을 인식하지 않습니다.
+ * ⚠️ action 문자열은 기존 mutation 이름과 정확히 매칭되어야 합니다.
+ */
+import { cronJobs } from "@gencow/core";
+
+const crons = cronJobs();
+
+// ─── 예제 (필요한 것만 주석 해제) ──────────────────────
+
+// 30분마다 실행
+// crons.interval("crawlNews", { minutes: 30 }, "crawlPipeline.runStep1");
+
+// 매일 KST 07:00 (UTC 22:00) 실행
+// crons.daily("generateDigest", { hour: 22 }, "llmActions.generateDigest");
+
+// 매주 월요일 09:00 (UTC 00:00) 실행
+// crons.weekly("weeklyReport", { dayOfWeek: 1, hour: 0 }, "reports.generateWeekly");
+
+// cron 표현식 직접 사용
+// crons.cron("customJob", "0 */6 * * *", "module.mutation");
+
+export default crons;
+`);
+            success("Created gencow/crons.ts (크론 스케줄러 템플릿)");
+        }
+
         // 3.7. auth.ts (auth 설정 — defineAuth 기반, shadcn 패턴으로 사용자 소유)
         const authConfigSource = resolve(__dirname, "..", "templates", "auth.ts");
         if (existsSync(authConfigSource)) {
@@ -2118,6 +2195,67 @@ ${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);
+                        }
+                    }
+                    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 { /* 스캔 실패 — 무시하고 진행 */ }
+
+            // ── 가드레일 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}`);
+                log("");
+            }
+
             // 1. tar.gz 패키징
             info("정적 파일 패키징 중...");
             const { execSync: exec } = await import("child_process");

package/package.json

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

package/server/index.js

@@ -72587,6 +72587,7 @@ var websocket2 = {
 app.use("*", cors({
   origin: (origin) => {
     if (!origin || origin.startsWith("http://localhost")) return origin;
+    if (origin.endsWith(".gencow.app")) return origin;
     const allowed = process.env.CORS_ORIGINS?.split(",") ?? [];
     return allowed.includes(origin) ? origin : "";
   },
@@ -73420,6 +73421,9 @@ async function main() {
     );
   }
   const port = Number(process.env.PORT || 5456);
+  if (!process.env.GENCOW_INTERNAL_URL) {
+    process.env.GENCOW_INTERNAL_URL = `http://localhost:${port}`;
+  }
   if (IS_BAAS && !process.env.PORT) {
     console.error("[FATAL] BaaS app started without PORT env var. All apps would collide on :5456. Exiting.");
     process.exit(1);