clawfire 0.1.0 → 0.2.1

package/README.md

@@ -2,56 +2,183 @@
 
 **AI-First Firebase App Framework — Speak. Build. Deploy.**
 
-Clawfire는 "말하면 완성되는 Firebase 앱 플랫폼"입니다. 코드를 작성하지 않고, AI(Claude Skills)에게 말하며 앱을 만듭니다.
+[![npm version](https://img.shields.io/npm/v/clawfire)](https://www.npmjs.com/package/clawfire)
+[![license](https://img.shields.io/npm/l/clawfire)](./LICENSE)
+
+Clawfire lets you build Firebase apps by talking to AI. Define your API contracts with Zod, and get type-safe routing, auto-generated clients, security rules, and deployment — all from a single source of truth.
+
+---
 
 ## Features
 
-- **Contract-based API** — Zod 스키마로 input/output 계약 정의
-- **File-based Routing** — `app/routes/` 디렉터리 = API 경로
-- **Auto Client Generation** — 타입 안전한 `api.xxx.yyy()` 클라이언트 자동 생성
-- **Firebase-Only Stack** — Firestore, Auth, Functions, Hosting 완전 통합
-- **Security by Default** — 입력 검증, CORS, Rate Limit, 로그 마스킹 기본 제공
-- **AI Skills System** — `/clawfire-*` 커맨드로 프로젝트 관리
-- **API Playground** — 웹 기반 API 탐색기 내장
-- **Auto Security Rules** — 모델 정의에서 Firestore Rules 자동 생성
+- **Contract-based API** — Define input/output with Zod schemas. Runtime validation, type safety, and docs come for free.
+- **File-based Routing** — `app/routes/todos/create.ts` becomes `POST /api/todos/create`. No configuration.
+- **Page Routing** — `app/pages/about.html` becomes `/about`. Layouts, components, and SPA navigation built in.
+- **Layouts & Components** — `_layout.html` wraps pages via `<slot />`. `<c-nav />` inserts `app/components/nav.html`.
+- **SPA Navigation** — Internal links swap page content without full reload. Tailwind CSS via CDN.
+- **Two-Port Dev Server** — Frontend app on port 3000, API + Playground on port 3456. One command.
+- **Hot Reload** — API, page, and CSS changes reload instantly. No manual refresh needed.
+- **API Playground** — Interactive API explorer auto-generated from your route definitions.
+- **Auto Client Generation** — Type-safe `api.todos.create({ title })` client generated from your contracts.
+- **Firebase-Native** — Firestore, Auth, Functions, Hosting. Fully integrated, no alternatives needed.
+- **Security by Default** — Input validation, CORS deny, rate limiting, XSS sanitization, log masking — all ON.
+- **Auto Security Rules** — Firestore rules generated from model definitions.
+- **AI Skills** — Six `/clawfire-*` Claude Code commands to manage your entire project.
+
+---
 
 ## Quick Start
 
+### 1. Create a New Project
+
 ```bash
-# 새 프로젝트 초기화
+mkdir my-app && cd my-app
 npx clawfire init
+npm install
+```
 
-# 또는 기존 프로젝트에 설치
-npm install clawfire
+### 2. Start the Dev Server
+
+```bash
+npm run dev
 ```
 
-## Usage
+This starts **two servers** in a single process:
 
-### Define a Model
+```
+  ⚡ Clawfire Dev Server
+  ─────────────────────────────────────
+  App        : http://localhost:3000
+  API        : http://localhost:3456/api/...
+  Playground : http://localhost:3456
+  Pages      : ON (app/pages/)
+
+  Routes (5):
+    POST /api/health         [public] Health check endpoint
+    POST /api/todos/create   [public] Create a new todo
+    POST /api/todos/delete   [public] Delete a todo
+    POST /api/todos/list     [public] List all todos
+    POST /api/todos/update   [public] Update a todo
+
+  Hot Reload : ON
+  Watching: app/routes/, app/schemas/, app/pages/, app/components/, public/
+```
 
-```typescript
-// app/schemas/product.ts
-import { defineModel } from "clawfire";
+### 3. Open in Your Browser
 
-export const Product = defineModel({
-  collection: "products",
-  fields: {
-    name: { type: "string", required: true },
-    price: { type: "number", required: true },
-    category: { type: "string", enum: ["electronics", "clothing"] },
-  },
-  timestamps: true,
-  rules: {
-    read: "public",
-    create: "role",
-    createRoles: ["admin"],
-  },
-});
+| URL | What You'll See |
+|-----|-----------------|
+| [http://localhost:3000](http://localhost:3000) | Your app (Todo starter) |
+| [http://localhost:3456](http://localhost:3456) | API Playground |
+
+### 4. Test the API
+
+```bash
+# Via the API server directly
+curl -s -X POST http://localhost:3456/api/health \
+  -H 'Content-Type: application/json' -d '{}' | jq
+
+# Or via the frontend proxy (same result, no CORS issues)
+curl -s -X POST http://localhost:3000/api/todos/create \
+  -H 'Content-Type: application/json' \
+  -d '{"title":"Learn Clawfire"}' | jq
 ```
 
+---
+
+## Dev Server Architecture
+
+Clawfire runs a **two-port dev server** in a single process:
+
+```
+DevServer (single process)
+  ├─ PageCompiler (compiles app/pages/ + app/components/ → HTML)
+  ├─ Frontend Server (port 3000)
+  │   ├─ Serves compiled pages (app/pages/ → routes)
+  │   ├─ Serves public/ directory (static assets)
+  │   ├─ Auto-injects HMR script into HTML
+  │   ├─ Proxies /api/* → API server (no CORS)
+  │   └─ SPA fallback with partial page loading
+  │
+  └─ API Server (port 3456)
+      ├─ API routes at /api/*
+      ├─ Playground UI at /
+      └─ SSE for live reload
+```
+
+**Key behaviors:**
+
+- **HMR auto-injection** — Every HTML response gets a `<script>` tag injected automatically. You never write SSE code.
+- **CSS hot replace** — Edit a `.css` file in `public/` and see changes instantly without page reload.
+- **API proxy** — Your frontend can call `fetch('/api/todos/list')` — the frontend server proxies it to the API server. No CORS configuration needed.
+- **SPA fallback** — Unknown paths serve `index.html`, supporting client-side routing.
+- **Playground** — Always available at the API server root. Auto-discovers routes, shows auth levels, generates example payloads.
+
+### Custom Ports
+
+```bash
+npx clawfire dev --port=4000 --api-port=5000
+```
+
+Or in `clawfire.config.ts`:
+
+```ts
+dev: {
+  port: 4000,
+  apiPort: 5000,
+}
+```
+
+---
+
+## Project Structure
+
+```
+my-app/
+  app/
+    store.ts              In-memory data store (works without Firebase)
+    pages/                File-based page routing (frontend)
+      _layout.html        Root layout (wraps all pages via <slot />)
+      _404.html           404 error page
+      index.html          Home page (/)
+      about.html          /about page
+      todos/
+        index.html        /todos page
+    components/           Reusable HTML components
+      nav.html            <c-nav /> navigation bar
+      footer.html         <c-footer /> page footer
+    routes/               API route handlers (file-based routing)
+      health.ts           → POST /api/health
+      todos/
+        list.ts           → POST /api/todos/list
+        create.ts         → POST /api/todos/create
+        update.ts         → POST /api/todos/update
+        delete.ts         → POST /api/todos/delete
+    schemas/              Firestore model definitions
+      todo.ts
+  public/                 Static assets (CSS, images, fonts)
+  generated/              Auto-generated files (DO NOT EDIT)
+    api-client.ts         Typed API client
+    manifest.json         API manifest
+  functions/
+    index.ts              Firebase Functions entry point (for deploy)
+  dev.ts                  Dev server entry point
+  clawfire.config.ts      Configuration
+  firebase.json           Firebase config
+  firestore.rules         Firestore security rules
+  firestore.indexes.json  Firestore indexes
+  CLAUDE.md               Project guide for Claude AI
+```
+
+---
+
+## Core Concepts
+
 ### Define an API
 
-```typescript
+Every API endpoint is a file in `app/routes/` that exports a `defineAPI` contract:
+
+```ts
 // app/routes/products/list.ts
 import { defineAPI, z } from "clawfire";
 
@@ -69,20 +196,137 @@ export default defineAPI({
     hasMore: z.boolean(),
   }),
   meta: {
-    description: "상품 목록 조회",
+    description: "List products",
     auth: "public",
     tags: ["products"],
   },
   handler: async (input, ctx) => {
-    // Your business logic here
     return { products: [], hasMore: false };
   },
 });
 ```
 
-### Server Setup (Firebase Functions)
+**Rules:**
+- All APIs are **POST only** — no HTTP method routing
+- `input` and `output` must be `z.object({})`
+- `meta.description` is required
+- `handler` must be `async`
+- File path = API path: `app/routes/products/list.ts` → `POST /api/products/list`
+
+### Define a Model
 
-```typescript
+Models define Firestore collections and auto-generate security rules:
+
+```ts
+// app/schemas/product.ts
+import { defineModel } from "clawfire";
+
+export const Product = defineModel({
+  collection: "products",
+  fields: {
+    name: { type: "string", required: true },
+    price: { type: "number", required: true },
+    category: { type: "string", enum: ["electronics", "clothing"] },
+  },
+  timestamps: true,
+  rules: {
+    read: "public",
+    create: "role",
+    createRoles: ["admin"],
+    update: "authenticated",
+    delete: "role",
+    deleteRoles: ["admin"],
+    ownerField: "userId",
+  },
+});
+```
+
+### Error Handling
+
+```ts
+import { Errors } from "clawfire";
+
+throw Errors.notFound("Product not found");      // 404
+throw Errors.validation("Invalid input", err);   // 400
+throw Errors.forbidden("No access");             // 403
+throw Errors.unauthorized("Login required");     // 401
+throw Errors.conflict("Already exists");         // 409
+throw Errors.rateLimited("Too many requests");   // 429
+```
+
+**Response format:**
+
+```json
+// Success
+{ "data": { "products": [...], "hasMore": false } }
+
+// Error
+{ "error": { "code": "NOT_FOUND", "message": "Product not found" } }
+```
+
+---
+
+## Auth Levels
+
+Every API endpoint declares an auth level in `meta.auth`:
+
+| Level | Description | Header Required |
+|-------|-------------|-----------------|
+| `public` | No authentication | None |
+| `authenticated` | Must be logged in | `Authorization: Bearer <token>` |
+| `role` | Specific role required | Bearer token + role match |
+| `reauth` | Recent login required (5 min) | Bearer token + fresh |
+
+```ts
+meta: {
+  description: "Delete user account",
+  auth: "reauth",  // Must have re-authenticated within 5 minutes
+}
+```
+
+---
+
+## Configuration
+
+All settings in `clawfire.config.ts`:
+
+```ts
+import { configureClawfire } from "clawfire";
+
+export default configureClawfire({
+  firebase: {
+    apiKey: "...",
+    authDomain: "myapp.firebaseapp.com",
+    projectId: "my-project",
+    appId: "1:123:web:abc",
+  },
+  server: {
+    region: "us-central1",
+    cors: ["https://myapp.web.app"],
+    rateLimit: 100,
+  },
+  security: {
+    validateInput: true,
+    safeHeaders: true,
+    maskLogs: true,
+  },
+  playground: {
+    enabled: true,
+  },
+  dev: {
+    port: 3000,      // Frontend server
+    apiPort: 3456,   // API server + Playground
+  },
+});
+```
+
+---
+
+## Production Deployment
+
+### Firebase Functions Entry Point
+
+```ts
 // functions/index.ts
 import * as admin from "firebase-admin";
 import * as functions from "firebase-functions";
@@ -106,10 +350,10 @@ export const api = functions.https.onRequest((req, res) => {
 });
 ```
 
-### Client Usage
+### Auto-Generated Client
 
-```typescript
-// Generated api-client.ts provides typed access
+```ts
+// In your frontend code
 import { api, configureClient } from "./generated/api-client";
 import { getAuth } from "firebase/auth";
 
@@ -118,64 +362,118 @@ configureClient("https://us-central1-myapp.cloudfunctions.net", async () => {
   return user ? user.getIdToken() : null;
 });
 
+// Fully typed — autocomplete and compile-time checking
 const result = await api.products.list({ category: "electronics", limit: 10 });
 ```
 
-## Project Structure
+---
 
-```
-app/
-  routes/           API route handlers (file-based routing)
-  schemas/          Model definitions (Firestore collections)
-generated/          Auto-generated files (DO NOT EDIT)
-  api-client.ts     Typed API client
-  manifest.json     API manifest
-functions/          Firebase Functions entry point
-public/             Static files for Firebase Hosting
-firebase.json       Firebase config
-firestore.rules     Firestore security rules
-clawfire.config.ts  Clawfire configuration
+## CLI Reference
+
+```bash
+clawfire init              # Initialize a new project (starter template)
+clawfire dev               # Start dev server (frontend + API + Playground)
+clawfire dev --port=4000   # Custom frontend port
+clawfire dev --api-port=5000  # Custom API port
+clawfire codegen           # Generate route imports
+clawfire playground        # Generate standalone playground HTML
+clawfire rules             # Info about rules generation
+clawfire help              # Show help
 ```
 
-## AI Skills (Claude Code)
+---
 
-| Command | Description |
-|---------|-------------|
-| `/clawfire-init` | Initialize project / connect Firebase |
-| `/clawfire-model` | Create/modify data models |
-| `/clawfire-api` | Create/modify APIs |
-| `/clawfire-auth` | Configure authentication |
-| `/clawfire-deploy` | Deploy to Firebase |
-| `/clawfire-diagnose` | Diagnose and fix issues |
+## AI Skills (Claude Code)
 
-## Auth Levels
+When using [Claude Code](https://claude.ai/claude-code), these slash commands are available:
 
-| Level | Description |
-|-------|-------------|
-| `public` | No authentication required |
-| `authenticated` | Login required |
-| `role` | Specific role required |
-| `reauth` | Recent re-authentication required |
-
-## Exports
-
-| Path | Description |
-|------|-------------|
-| `clawfire` | Core types, defineAPI, defineModel, Zod |
-| `clawfire/functions` | Server-side: Router, DB, Auth, Security |
-| `clawfire/client` | Client-side: Auth helpers |
-| `clawfire/admin` | Admin: Rules, Indexes, User management |
-| `clawfire/codegen` | Code generation utilities |
-| `clawfire/playground` | Playground HTML generator |
-
-## Tech Stack (Fixed)
-
-- **DB**: Firestore
-- **Auth**: Firebase Auth
-- **Hosting**: Firebase Hosting
-- **Backend**: Firebase Functions
-- **Schema**: Zod
-- **Language**: TypeScript
+| Command | What It Does |
+|---------|-------------|
+| `/clawfire-init` | Initialize project, connect Firebase, set up config |
+| `/clawfire-model` | Create/modify Firestore models → auto-generates rules + indexes |
+| `/clawfire-api` | Create/modify API endpoints → auto-generates typed client |
+| `/clawfire-auth` | Configure auth policies, roles, guards |
+| `/clawfire-deploy` | Deploy to Firebase (explicit request only) |
+| `/clawfire-diagnose` | Detect missing indexes, rule denials, permission issues |
+
+---
+
+## Package Exports
+
+| Import Path | Contents |
+|-------------|----------|
+| `clawfire` | `defineAPI`, `defineModel`, `z`, `Errors`, `configureClawfire`, `ClawfireError` |
+| `clawfire/functions` | `createRouter`, `createAdminDB`, `verifyToken`, `createSecurityMiddleware` |
+| `clawfire/client` | `createClientAuth` |
+| `clawfire/admin` | `generateFirestoreRules`, `generateFirestoreIndexes`, `setUserRole` |
+| `clawfire/codegen` | `generateClientCode`, `discoverRoutes`, `generateRouteImports` |
+| `clawfire/playground` | `generatePlaygroundHtml` |
+| `clawfire/dev` | `DevServer`, `startDevServer`, `FileWatcher`, `PageCompiler` |
+
+---
+
+## Security Defaults
+
+All security features are **ON by default**:
+
+| Feature | Default | Description |
+|---------|---------|-------------|
+| Input Validation | ON | Zod schema validation on every request |
+| CORS | Deny all | Must explicitly allow origins |
+| Rate Limiting | 100 req/min/IP | Per-endpoint configurable |
+| XSS Sanitization | ON | `<` `>` auto-escaped in string inputs |
+| Safe Headers | ON | `X-Frame-Options`, `X-Content-Type-Options` |
+| Log Masking | ON | `password`, `token`, `secret` fields masked |
+
+---
+
+## Dev vs Production
+
+| | Dev Server | Production (Firebase) |
+|--|-----------|----------------------|
+| Frontend | `localhost:3000` (static + HMR) | Firebase Hosting |
+| API | `localhost:3456` | Firebase Functions |
+| Playground | Always on at `:3456` | Configurable |
+| CORS | Allow all (`*`) | Configured origins only |
+| Rate Limiting | Disabled | Enabled |
+| Auth | Optional / mockable | Firebase Auth |
+| Hot Reload | Yes (API + CSS + HTML) | N/A |
+
+---
+
+## Documentation
+
+Full documentation is in the [`docs/`](./docs/) directory:
+
+- [Getting Started](./docs/getting-started.md) — 5-minute quickstart
+- [API Routes](./docs/api-routes.md) — `defineAPI`, file-based routing, handlers
+- [Models](./docs/models.md) — `defineModel`, Firestore collections, rules
+- [Dev Server](./docs/dev-server.md) — Two-port architecture, HMR, Playground
+- [Authentication](./docs/authentication.md) — Auth levels, tokens, roles
+- [Security](./docs/security.md) — Middleware, rate limiting, CORS, sanitization
+- [Configuration](./docs/configuration.md) — All config options and defaults
+- [Client Codegen](./docs/client-codegen.md) — Auto-generated typed API client
+- [Deployment](./docs/deployment.md) — Firebase deploy workflow
+- [CLI Reference](./docs/cli-reference.md) — All CLI commands and flags
+- [Architecture](./docs/architecture.md) — How everything fits together
+- [API Reference](./docs/api-reference.md) — Full TypeScript API reference
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Database | Firestore |
+| Auth | Firebase Auth |
+| Hosting | Firebase Hosting |
+| Backend | Firebase Functions |
+| Schema | Zod |
+| Language | TypeScript |
+
+This stack is fixed by design. Clawfire is opinionated — one way to do things, done well.
+
+---
 
 ## License
 

package/dist/admin.d.cts

@@ -1,6 +1,6 @@
 import { e as ModelDefinition } from './schema-BJsictSV.cjs';
 export { f as ModelField, i as ModelIndex, j as ModelRules, h as defineModel, m as modelToZodSchema } from './schema-BJsictSV.cjs';
-import { C as ClawfireConfig } from './config-QMBJRn9G.cjs';
+import { C as ClawfireConfig } from './config-D-Chojiu.cjs';
 export { g as getUserRole, s as setCustomClaims, b as setUserRole } from './auth-DQ3cifhb.cjs';
 import 'zod';
 

package/dist/admin.d.ts

@@ -1,6 +1,6 @@
 import { e as ModelDefinition } from './schema-BJsictSV.js';
 export { f as ModelField, i as ModelIndex, j as ModelRules, h as defineModel, m as modelToZodSchema } from './schema-BJsictSV.js';
-import { C as ClawfireConfig } from './config-QMBJRn9G.js';
+import { C as ClawfireConfig } from './config-D-Chojiu.js';
 export { g as getUserRole, s as setCustomClaims, b as setUserRole } from './auth-DtnUPbXT.js';
 import 'zod';
 

package/dist/cli.js

@@ -26,6 +26,11 @@ function printHelp() {
     clawfire rules         Generate Firestore security rules
     clawfire help          Show this help
 
+  Dev Server Flags:
+    --port=<n>             Frontend server port (default: 3000)
+    --api-port=<n>         API server port (default: 3456)
+    --no-hot-reload        Disable hot reload
+
   Most tasks are done through AI Skills, not CLI.
   Run Claude Code and use /clawfire-* commands instead.
 `);
@@ -112,6 +117,8 @@ async function initProject() {
     const dirs = [
       "app/routes",
       "app/schemas",
+      "app/pages",
+      "app/components",
       "generated",
       "public",
       "functions"
@@ -179,23 +186,34 @@ export const api = functions.https.onRequest((req, res) => {
     console.log("  Created functions/index.ts");
   }
   console.log("\n  \x1B[32m\u2713\x1B[0m Clawfire project initialized!\n");
+  console.log("  Project structure:");
+  console.log("    \x1B[36mapp/pages/\x1B[0m       \u2192 File-based page routing (Tailwind + layouts)");
+  console.log("    \x1B[36mapp/components/\x1B[0m  \u2192 Reusable HTML components (<c-name />)");
+  console.log("    \x1B[36mapp/routes/\x1B[0m      \u2192 API endpoints (POST, Zod validation)");
+  console.log("    \x1B[36mapp/schemas/\x1B[0m     \u2192 Firestore model definitions");
+  console.log("    \x1B[36mpublic/\x1B[0m          \u2192 Static assets (CSS, images, fonts)");
+  console.log("");
   console.log("  Next steps:");
   console.log("    \x1B[36m1.\x1B[0m npm install");
   console.log("    \x1B[36m2.\x1B[0m npm run dev");
-  console.log("    \x1B[36m3.\x1B[0m Open \x1B[1mhttp://localhost:3456\x1B[0m in your browser");
+  console.log("    \x1B[36m3.\x1B[0m Open \x1B[1mhttp://localhost:3000\x1B[0m");
+  console.log("");
+  console.log("  Your app is ready with a Todo demo, page routing, and API playground.");
   console.log("");
-  console.log("  Your Todo app is ready! Try adding, completing, and deleting todos.");
-  console.log("  Edit files in \x1B[1mapp/routes/\x1B[0m and see changes instantly.\n");
+  console.log("  npm: \x1B[4mhttps://www.npmjs.com/package/clawfire\x1B[0m\n");
 }
 async function runDevServer() {
   const projectDir = process.cwd();
   const portArg = args.find((a) => a.startsWith("--port="));
-  const port = portArg ? parseInt(portArg.split("=")[1], 10) : 3456;
+  const apiPortArg = args.find((a) => a.startsWith("--api-port="));
+  const port = portArg ? parseInt(portArg.split("=")[1], 10) : 3e3;
+  const apiPort = apiPortArg ? parseInt(apiPortArg.split("=")[1], 10) : 3456;
   const noHotReload = args.includes("--no-hot-reload");
-  const { startDevServer } = await import("./dev-server-QAVWINAT.js");
+  const { startDevServer } = await import("./dev-server-ZGXJARNY.js");
   await startDevServer({
     projectDir,
     port,
+    apiPort,
     hotReload: !noHotReload
   });
 }

package/dist/{config-QMBJRn9G.d.cts → config-D-Chojiu.d.cts}

@@ -39,6 +39,13 @@ interface ClawfireConfig {
         /** 경로 */
         path?: string;
     };
+    /** 개발 서버 설정 */
+    dev?: {
+        /** 프론트엔드 서버 포트 (기본: 3000) */
+        port?: number;
+        /** API 서버 포트 (기본: 3456) */
+        apiPort?: number;
+    };
 }
 declare function configureClawfire(config: ClawfireConfig): ClawfireConfig;
 declare function getConfig(): ClawfireConfig;

package/dist/{config-QMBJRn9G.d.ts → config-D-Chojiu.d.ts}

@@ -39,6 +39,13 @@ interface ClawfireConfig {
         /** 경로 */
         path?: string;
     };
+    /** 개발 서버 설정 */
+    dev?: {
+        /** 프론트엔드 서버 포트 (기본: 3000) */
+        port?: number;
+        /** API 서버 포트 (기본: 3456) */
+        apiPort?: number;
+    };
 }
 declare function configureClawfire(config: ClawfireConfig): ClawfireConfig;
 declare function getConfig(): ClawfireConfig;