gencow 0.1.76 → 0.1.78

package/lib/__tests__/readme-codegen.test.ts

@@ -0,0 +1,439 @@
+import { describe, it, expect } from "bun:test";
+import {
+    buildReadmeMarkdown,
+    buildApiTable,
+    buildReactUsage,
+    buildFrontendSetup,
+    buildAuthSection,
+    buildRpcSection,
+    buildAiPrompt,
+    buildAiUsageSection,
+    buildDeploySection,
+    buildCronSection,
+    buildDevTips,
+    extractComponentsBlock,
+    COMP_START,
+    COMP_END,
+} from "../readme-codegen.mjs";
+
+// ─── Sample API objects for testing ──────────────────────
+const SIMPLE_API = {
+    tasks: { queries: ["list"], mutations: ["create", "delete"] },
+};
+
+const MULTI_NS_API = {
+    tasks: { queries: ["list", "getById"], mutations: ["create"] },
+    users: { queries: ["me"], mutations: ["updateProfile"] },
+};
+
+const EMPTY_API = {};
+
+const QUERY_ONLY_API = {
+    products: { queries: ["list", "search"], mutations: [] },
+};
+
+const MUTATION_ONLY_API = {
+    orders: { queries: [], mutations: ["place", "cancel"] },
+};
+
+// ═══════════════════════════════════════════════════════════
+describe("buildReadmeMarkdown — 전체 생성", () => {
+    it("헤더에 타이틀과 타임스탬프 포함", () => {
+        const md = buildReadmeMarkdown(SIMPLE_API, { timestamp: "2026-03-26" });
+        expect(md).toContain("# Gencow API Guide");
+        expect(md).toContain("2026-03-26");
+        expect(md).toContain("Auto-generated");
+    });
+
+    it("빈 API 객체도 에러 없이 생성", () => {
+        const md = buildReadmeMarkdown(EMPTY_API, { timestamp: "test" });
+        expect(md).toContain("# Gencow API Guide");
+        expect(md).toContain("Available APIs");
+    });
+
+    it("기존 컴포넌트 블록 보존", () => {
+        const compBlock = `${COMP_START}\n### My Component\n${COMP_END}`;
+        const md = buildReadmeMarkdown(SIMPLE_API, {
+            timestamp: "test",
+            existingComponentsBlock: compBlock,
+        });
+        expect(md).toContain(COMP_START);
+        expect(md).toContain("My Component");
+        expect(md).toContain(COMP_END);
+    });
+
+    it("모든 필수 섹션 포함", () => {
+        const md = buildReadmeMarkdown(SIMPLE_API, { timestamp: "test" });
+        expect(md).toContain("## 📦 Available APIs");
+        expect(md).toContain("## ⚡ 데이터 사용법");
+        expect(md).toContain("## 🏗️ 프론트엔드 초기 설정");
+        expect(md).toContain("## 🔐 인증");
+        expect(md).toContain("## 🤖 AI Vibe-Coding Prompt");
+        expect(md).toContain("## 🤖 AI 사용법");
+        expect(md).toContain("## 🚀 배포");
+        expect(md).toContain("## ⏰ Cron Jobs");
+        expect(md).toContain("## 💡 개발 팁");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildApiTable — API 레퍼런스 테이블", () => {
+    it("네임스페이스별 테이블 생성", () => {
+        const md = buildApiTable(SIMPLE_API);
+        expect(md).toContain("### `tasks`");
+        expect(md).toContain("api.tasks.list");
+        expect(md).toContain("api.tasks.create");
+        expect(md).toContain("api.tasks.delete");
+    });
+
+    it("query는 query 타입, mutation은 mutation 타입", () => {
+        const md = buildApiTable(SIMPLE_API);
+        expect(md).toContain("| `api.tasks.list` | `query`");
+        expect(md).toContain("| `api.tasks.create` | `mutation`");
+    });
+
+    it("여러 네임스페이스 처리", () => {
+        const md = buildApiTable(MULTI_NS_API);
+        expect(md).toContain("### `tasks`");
+        expect(md).toContain("### `users`");
+        expect(md).toContain("api.users.me");
+    });
+
+    it("빈 API → 섹션 헤더만 존재", () => {
+        const md = buildApiTable(EMPTY_API);
+        expect(md).toContain("## 📦 Available APIs");
+        expect(md).not.toContain("###");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildReactUsage — React Hook 사용법", () => {
+    it("useQuery/useMutation import 포함", () => {
+        const md = buildReactUsage(SIMPLE_API);
+        expect(md).toContain("import { useQuery, useMutation }");
+        expect(md).toContain("@gencow/react");
+    });
+
+    it("쿼리용 useQuery 예제 생성", () => {
+        const md = buildReactUsage(SIMPLE_API);
+        expect(md).toContain("useQuery(api.tasks.list)");
+    });
+
+    it("뮤테이션용 useMutation 예제 생성", () => {
+        const md = buildReactUsage(SIMPLE_API);
+        expect(md).toContain("useMutation(api.tasks.create)");
+    });
+
+    it("네임스페이스 대문자화 (capitalize)", () => {
+        const md = buildReactUsage(SIMPLE_API);
+        expect(md).toContain("Tasks");  // capitalize('tasks')
+    });
+
+    it("query만 있는 네임스페이스", () => {
+        const md = buildReactUsage(QUERY_ONLY_API);
+        expect(md).toContain("useQuery(api.products.list)");
+        expect(md).not.toContain("useMutation(api.products");
+    });
+
+    it("mutation만 있는 네임스페이스", () => {
+        const md = buildReactUsage(MUTATION_ONLY_API);
+        expect(md).not.toContain("useQuery(api.orders");
+        expect(md).toContain("useMutation(api.orders.place)");
+    });
+
+    it("안티패턴 경고 포함", () => {
+        const md = buildReactUsage(SIMPLE_API);
+        expect(md).toContain("❌ 절대 하지 마세요");
+        expect(md).toContain("fetch()로 직접 API 호출하지 마세요");
+    });
+
+    it("조건부 쿼리 (skip/enabled) 포함", () => {
+        const md = buildReactUsage(SIMPLE_API);
+        expect(md).toContain("skip");
+        expect(md).toContain("enabled");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildAuthSection — 인증 섹션", () => {
+    it("better-auth 엔드포인트 테이블", () => {
+        const md = buildAuthSection();
+        expect(md).toContain("/api/auth/sign-up/email");
+        expect(md).toContain("/api/auth/sign-in/email");
+        expect(md).toContain("/api/auth/sign-out");
+    });
+
+    it("credentials include 경고", () => {
+        const md = buildAuthSection();
+        expect(md).toContain('credentials: "include"');
+    });
+
+    it("프론트엔드 프록시 설정 + VITE_API_URL 안내", () => {
+        const md = buildAuthSection();
+        expect(md).toContain("VITE_API_URL");
+        expect(md).toContain("프록시");
+        expect(md).toContain("gencowAuth(import.meta.env.VITE_API_URL)");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildRpcSection — RPC 직접 호출", () => {
+    it("details 접힘 블록", () => {
+        const md = buildRpcSection(SIMPLE_API, ["tasks"]);
+        expect(md).toContain("<details>");
+        expect(md).toContain("</details>");
+    });
+
+    it("실제 네임스페이스 이름 반영", () => {
+        const md = buildRpcSection(SIMPLE_API, ["tasks"]);
+        expect(md).toContain("tasks.list");
+    });
+
+    it("mutation 예제 포함 (mutation 있을 때)", () => {
+        const md = buildRpcSection(SIMPLE_API, ["tasks"]);
+        expect(md).toContain("tasks.create");
+        expect(md).toContain("/api/mutation");
+    });
+
+    it("query만 있으면 mutation 예제 없음", () => {
+        const md = buildRpcSection(QUERY_ONLY_API, ["products"]);
+        expect(md).not.toContain("/api/mutation");
+    });
+
+    it("빈 API → fallback 네임스페이스", () => {
+        const md = buildRpcSection(EMPTY_API, []);
+        expect(md).toContain("namespace.functionName");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildAiPrompt — AI Vibe-Coding 프롬프트", () => {
+    it("API 구조 포함", () => {
+        const md = buildAiPrompt(SIMPLE_API, ["tasks"]);
+        expect(md).toContain("[tasks]");
+        expect(md).toContain("api.tasks.list (query)");
+        expect(md).toContain("api.tasks.create (mutation)");
+    });
+
+    it("Hook 사용법 포함", () => {
+        const md = buildAiPrompt(SIMPLE_API, ["tasks"]);
+        expect(md).toContain("useQuery(api.namespace.fnName)");
+        expect(md).toContain("useMutation(api.namespace.fnName)");
+    });
+
+    it("mutation 제한 경고 포함", () => {
+        const md = buildAiPrompt(SIMPLE_API, ["tasks"]);
+        expect(md).toContain("mutation은 10초 이내");
+        expect(md).toContain("scheduler.runAfter");
+    });
+
+    it("크론 잡 사용법 포함", () => {
+        const md = buildAiPrompt(SIMPLE_API, ["tasks"]);
+        expect(md).toContain("cronJobs()");
+        expect(md).toContain("crons.interval");
+        expect(md).toContain("export default crons");
+    });
+
+    it("배포 규칙 포함", () => {
+        const md = buildAiPrompt(SIMPLE_API, ["tasks"]);
+        expect(md).toContain("npx gencow deploy");
+        expect(md).toContain("--static");
+        expect(md).toContain("--no-backend");
+        expect(md).toContain("백엔드가 감지되면");
+    });
+
+    it("여러 네임스페이스 모두 나열", () => {
+        const md = buildAiPrompt(MULTI_NS_API, ["tasks", "users"]);
+        expect(md).toContain("[tasks]");
+        expect(md).toContain("[users]");
+        expect(md).toContain("api.users.me (query)");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildAiUsageSection — AI ctx.ai 사용법", () => {
+    it("ctx.ai.chat 예제 포함", () => {
+        const md = buildAiUsageSection();
+        expect(md).toContain("ctx.ai.chat");
+        expect(md).toContain("gpt-4o-mini");
+    });
+
+    it("OpenAI SDK 직접 사용 금지 경고", () => {
+        const md = buildAiUsageSection();
+        expect(md).toContain('import OpenAI from "openai"');
+        expect(md).toContain("❌ OpenAI SDK를 직접 설치하지 마세요");
+    });
+
+    it("OPENAI_API_KEY 로컬 설정 안내", () => {
+        const md = buildAiUsageSection();
+        expect(md).toContain("OPENAI_API_KEY");
+        expect(md).toContain("로컬 전용");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildDeploySection — 배포 가이드", () => {
+    it("3단계 배포 프로세스", () => {
+        const md = buildDeploySection();
+        expect(md).toContain("gencow login");
+        expect(md).toContain("gencow deploy");
+        expect(md).toContain("gencow env set");
+    });
+
+    it("환경변수 관리 명령어 테이블", () => {
+        const md = buildDeploySection();
+        expect(md).toContain("gencow env list");
+        expect(md).toContain("gencow env unset");
+        expect(md).toContain("gencow env push");
+    });
+
+    it("프론트엔드 배포 가이드", () => {
+        const md = buildDeploySection();
+        expect(md).toContain("VITE_API_URL");
+        expect(md).toContain("--static dist/");
+    });
+
+    it("CORS 설정 안내", () => {
+        const md = buildDeploySection();
+        expect(md).toContain("CORS_ORIGINS");
+    });
+
+    it("풀스택 통합 배포 (백엔드 자동 감지) 안내", () => {
+        const md = buildDeploySection();
+        expect(md).toContain("백엔드가 감지되면 자동으로");
+        expect(md).toContain("gencow/");
+    });
+
+    it("--no-backend 옵션 안내", () => {
+        const md = buildDeploySection();
+        expect(md).toContain("--no-backend");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildCronSection — 크론 잡", () => {
+    it("모든 크론 타입 예제", () => {
+        const md = buildCronSection();
+        expect(md).toContain("crons.interval");
+        expect(md).toContain("crons.daily");
+        expect(md).toContain("crons.weekly");
+        expect(md).toContain("crons.cron");
+    });
+
+    it("export default 경고", () => {
+        const md = buildCronSection();
+        expect(md).toContain("export default crons");
+    });
+
+    it("self-fetch 팁", () => {
+        const md = buildCronSection();
+        expect(md).toContain("GENCOW_INTERNAL_URL");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildDevTips — 개발 팁", () => {
+    it("핵심 팁 포함", () => {
+        const md = buildDevTips();
+        expect(md).toContain("자동으로 재생성");
+        expect(md).toContain("db:push");
+        expect(md).toContain("MCP 서버");
+        expect(md).toContain("gencow dev");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildFrontendSetup — 프론트엔드 초기 설정", () => {
+    it("3단계 헤더 포함", () => {
+        const md = buildFrontendSetup();
+        expect(md).toContain("프론트엔드 초기 설정 (3단계)");
+        expect(md).toContain("1단계");
+        expect(md).toContain("2단계");
+        expect(md).toContain("3단계");
+    });
+
+    it("gencowAuth 설정 예제 포함", () => {
+        const md = buildFrontendSetup();
+        expect(md).toContain("gencowAuth");
+        expect(md).toContain("signIn, signUp, signOut, useAuth");
+    });
+
+    it("GencowProvider 올바른 props 예제", () => {
+        const md = buildFrontendSetup();
+        expect(md).toContain("GencowProvider");
+        expect(md).toContain("baseUrl={baseUrl}");
+        expect(md).toContain("token={token}");
+    });
+
+    it("api.ts import 패턴", () => {
+        const md = buildFrontendSetup();
+        expect(md).toContain('@/gencow/api');
+        expect(md).toContain("gencow dev가 자동 생성");
+    });
+
+    it("흔한 실수 경고 — 문자열 전달 금지", () => {
+        const md = buildFrontendSetup();
+        expect(md).toContain("흔한 실수");
+        expect(md).toContain('useQuery("tasks.list")');
+        expect(md).toContain("TS2345");
+    });
+
+    it("흔한 실수 경고 — GencowProvider props", () => {
+        const md = buildFrontendSetup();
+        expect(md).toContain('url="http://..."');
+        expect(md).toContain("url' prop은 없습니다");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildDeploySection — 해싱/암호화 가이드", () => {
+    it("Web Crypto API sha256 스니펫 포함", () => {
+        const md = buildDeploySection();
+        expect(md).toContain("crypto.subtle.digest");
+        expect(md).toContain("SHA-256");
+        expect(md).toContain("sha256");
+    });
+
+    it("simpleHash 충돌 경고", () => {
+        const md = buildDeploySection();
+        expect(md).toContain("simpleHash");
+        expect(md).toContain("충돌");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("buildAiPrompt — 해싱 가이드 포함", () => {
+    it("AI 프롬프트에 crypto 대안 안내", () => {
+        const md = buildAiPrompt(SIMPLE_API, ["tasks"]);
+        expect(md).toContain("crypto.subtle.digest");
+        expect(md).toContain("node:crypto");
+    });
+});
+
+// ═══════════════════════════════════════════════════════════
+describe("extractComponentsBlock — 컴포넌트 블록 추출", () => {
+    it("컴포넌트 블록이 있으면 추출", () => {
+        const content = `# README\n${COMP_START}\n### Button\n${COMP_END}\nEnd`;
+        const block = extractComponentsBlock(content);
+        expect(block).toContain(COMP_START);
+        expect(block).toContain("Button");
+        expect(block).toContain(COMP_END);
+    });
+
+    it("컴포넌트 블록이 없으면 undefined", () => {
+        expect(extractComponentsBlock("# No components")).toBeUndefined();
+    });
+
+    it("빈 문자열 → undefined", () => {
+        expect(extractComponentsBlock("")).toBeUndefined();
+    });
+
+    it("null/undefined → undefined", () => {
+        expect(extractComponentsBlock(null)).toBeUndefined();
+        expect(extractComponentsBlock(undefined)).toBeUndefined();
+    });
+
+    it("종료 마커 없으면 undefined", () => {
+        expect(extractComponentsBlock(`${COMP_START}\nno end`)).toBeUndefined();
+    });
+});

package/lib/deploy-auditor.mjs

@@ -0,0 +1,227 @@
+/**
+ * Deploy Auditor — Pure function for pre-deploy dependency validation.
+ *
+ * Checks if user code imports packages that are not available
+ * in the Gencow cloud runtime. This prevents "new version unhealthy"
+ * deploy failures caused by missing third-party dependencies.
+ *
+ * How it works:
+ *   1. Uses esbuild metafile to extract all external imports
+ *   2. Filters out relative imports, Node built-ins, and platform packages
+ *   3. Returns list of unsupported packages with source file info
+ *
+ * Usage:
+ *   const result = await auditDeployDependencies("./gencow/index.ts");
+ *   if (!result.passed) { ... block deploy ... }
+ */
+import { build } from "esbuild";
+
+// ── Platform packages (available in cloud runtime NODE_PATH) ──
+// These are installed in the platform's node_modules and accessible
+// via NODE_PATH at runtime. Keep in sync with server NODE_PATH setup.
+const PLATFORM_PACKAGES = new Set([
+    // Gencow core
+    "@gencow/core",
+    "gencow",
+    // ORM
+    "drizzle-orm",
+    "drizzle-kit",
+    // Auth
+    "better-auth",
+    // DB drivers
+    "postgres",
+    "@electric-sql/pglite",
+    // HTTP framework
+    "hono",
+    // Build tools (used by auditor itself)
+    "esbuild",
+    // AI SDK
+    "ai",
+    "@ai-sdk/openai",
+    "@ai-sdk/anthropic",
+    "@ai-sdk/google",
+    // Validation
+    "zod",
+]);
+
+// ── Node.js built-in modules (always available) ──
+const NODE_BUILTINS = new Set([
+    "assert", "buffer", "child_process", "cluster", "crypto",
+    "dgram", "dns", "events", "fs", "http", "http2", "https",
+    "net", "os", "path", "perf_hooks", "process", "querystring",
+    "readline", "stream", "string_decoder", "timers", "tls",
+    "tty", "url", "util", "v8", "vm", "worker_threads", "zlib",
+]);
+
+/**
+ * @typedef {Object} UnsupportedDep
+ * @property {string} packageName - The npm package name
+ * @property {string} importedFrom - The source file that imports it
+ */
+
+/**
+ * @typedef {Object} AuditResult
+ * @property {boolean} passed - true if no unsupported deps found
+ * @property {UnsupportedDep[]} unsupported - List of unsupported packages
+ */
+
+/**
+ * Check if a module specifier is a platform-provided package.
+ *
+ * Handles subpath imports like "drizzle-orm/pg-core" → "drizzle-orm".
+ * Handles scoped packages like "@gencow/core/reactive" → "@gencow/core".
+ *
+ * @param {string} specifier - The import specifier
+ * @returns {boolean}
+ */
+export function isPlatformPackage(specifier) {
+    // Exact match
+    if (PLATFORM_PACKAGES.has(specifier)) return true;
+
+    // Subpath: "drizzle-orm/pg-core" → check "drizzle-orm"
+    // Scoped: "@gencow/core/reactive" → check "@gencow/core"
+    let root;
+    if (specifier.startsWith("@")) {
+        // @scope/name/subpath → @scope/name
+        const parts = specifier.split("/");
+        root = parts.length >= 2 ? `${parts[0]}/${parts[1]}` : specifier;
+    } else {
+        // name/subpath → name
+        root = specifier.split("/")[0];
+    }
+    return PLATFORM_PACKAGES.has(root);
+}
+
+/**
+ * Check if a module specifier is a Node.js built-in.
+ *
+ * Handles "node:" prefix: "node:fs" → "fs".
+ *
+ * @param {string} specifier
+ * @returns {boolean}
+ */
+export function isNodeBuiltin(specifier) {
+    const bare = specifier.startsWith("node:") ? specifier.slice(5) : specifier;
+    // Handle subpaths like "fs/promises"
+    const root = bare.split("/")[0];
+    return NODE_BUILTINS.has(root);
+}
+
+/**
+ * Audit user functions for unsupported third-party dependencies.
+ *
+ * @param {string} entryPoint - Path to the gencow/ entry point (e.g. "./gencow/index.ts")
+ * @returns {Promise<AuditResult>}
+ */
+export async function auditDeployDependencies(entryPoint) {
+    /** @type {UnsupportedDep[]} */
+    const unsupported = [];
+
+    try {
+        const result = await build({
+            entryPoints: [entryPoint],
+            bundle: true,
+            write: false,
+            metafile: true,
+            platform: "node",
+            format: "esm",
+            packages: "external",   // Don't bundle node_modules, just collect imports
+            logLevel: "silent",
+        });
+
+        if (!result.metafile) {
+            return { passed: true, unsupported: [] };
+        }
+
+        // Collect all unique external imports with their source files
+        /** @type {Map<string, string>} packageName → first importedFrom */
+        const seen = new Map();
+
+        for (const [filePath, fileData] of Object.entries(result.metafile.inputs)) {
+            for (const imp of /** @type {any[]} */ (fileData.imports)) {
+                const spec = imp.path;
+                if (!spec) continue;
+
+                // Skip relative/absolute imports (user's own code)
+                if (spec.startsWith(".") || spec.startsWith("/")) continue;
+
+                // Skip Node builtins
+                if (isNodeBuiltin(spec)) continue;
+
+                // Skip platform packages
+                if (isPlatformPackage(spec)) continue;
+
+                // Extract package root for dedup
+                let pkgRoot;
+                if (spec.startsWith("@")) {
+                    const parts = spec.split("/");
+                    pkgRoot = parts.length >= 2 ? `${parts[0]}/${parts[1]}` : spec;
+                } else {
+                    pkgRoot = spec.split("/")[0];
+                }
+
+                if (!seen.has(pkgRoot)) {
+                    // Clean up file path for display
+                    const cleanPath = filePath.replace(/^\.\//, "");
+                    seen.set(pkgRoot, cleanPath);
+                }
+            }
+        }
+
+        for (const [packageName, importedFrom] of seen) {
+            unsupported.push({ packageName, importedFrom });
+        }
+    } catch (err) {
+        // If esbuild analysis fails (e.g. syntax error), warn but don't block
+        console.warn("[deploy-auditor] Dependency audit skipped — could not analyze:", err.message);
+        return { passed: true, unsupported: [] };
+    }
+
+    return {
+        passed: unsupported.length === 0,
+        unsupported,
+    };
+}
+
+/**
+ * Format audit result as a human-readable error message for CLI output.
+ *
+ * @param {AuditResult} result
+ * @returns {string} Formatted message (empty string if passed)
+ */
+export function formatAuditError(result) {
+    if (result.passed) return "";
+
+    const lines = [
+        "",
+        "╔═══════════════════════════════════════════════════════════════╗",
+        "║  ⛔ DEPLOY BLOCKED — Unsupported Dependencies Detected       ║",
+        "╚═══════════════════════════════════════════════════════════════╝",
+        "",
+        "  The following packages are NOT available in the Gencow cloud runtime:",
+        "",
+    ];
+
+    for (const dep of result.unsupported) {
+        lines.push(`    ✗  ${dep.packageName} (imported in ${dep.importedFrom})`);
+    }
+
+    lines.push("");
+    lines.push("  Gencow 클라우드에서 사용 가능한 패키지:");
+    lines.push("    @gencow/core, drizzle-orm, better-auth, postgres, hono, ai, zod");
+    lines.push("");
+    lines.push("  해결 방법:");
+    lines.push("    1. 해당 패키지 사용을 제거하거나 동적 import (try/catch)로 변경");
+    lines.push("    2. gencow deploy --force 로 강제 배포 (서버 크래시 위험)");
+    lines.push("");
+
+    return lines.join("\n");
+}
+
+/**
+ * Get the list of platform-provided packages (for display/docs).
+ * @returns {string[]}
+ */
+export function getPlatformPackageList() {
+    return [...PLATFORM_PACKAGES].sort();
+}