clawfire 0.1.0

package/templates/starter/CLAUDE.md

@@ -0,0 +1,227 @@
+# Clawfire Project
+
+This is a **Clawfire** project — an AI-First Firebase app framework.
+**"Speak. Build. Deploy."**
+
+사용자가 자연어로 요청하면 Claude가 자율적으로 API, 모델, 인증, 배포를 수행합니다.
+
+---
+
+## Stack (Fixed — do not change)
+
+| Layer | Technology |
+|-------|-----------|
+| DB | Firestore |
+| Auth | Firebase Auth |
+| Hosting | Firebase Hosting |
+| Backend | Firebase Functions |
+| Schema | Zod |
+| Language | TypeScript |
+| Framework | clawfire |
+
+**이 스택은 고정입니다. 다른 DB, 다른 프레임워크를 제안하지 마세요.**
+
+---
+
+## Project Structure
+
+```
+app/
+  store.ts              ← 인메모리 데이터 저장소 (Firebase 없이 동작)
+  routes/               ← API 라우트 핸들러 (파일 기반 라우팅)
+    health.ts           ← 서버 상태 확인
+    todos/              ← Todo CRUD
+      list.ts
+      create.ts
+      update.ts
+      delete.ts
+  schemas/              ← Firestore 모델 정의
+    todo.ts
+public/
+  index.html            ← 프론트엔드 (바닐라 JS, 빌드 불필요)
+generated/              ← 자동 생성 파일 (DO NOT EDIT)
+functions/
+  index.ts              ← Firebase Functions 진입점 (배포용)
+dev.ts                  ← Dev 서버 진입점
+clawfire.config.ts      ← Clawfire 설정
+firebase.json           ← Firebase 설정
+firestore.rules         ← Firestore 보안 규칙
+firestore.indexes.json  ← Firestore 인덱스
+```
+
+---
+
+## Commands
+
+```bash
+npm run dev       # 개발 서버 시작 (http://localhost:3456)
+npm run build     # TypeScript 체크
+npm run deploy    # Firebase 배포
+```
+
+---
+
+## AI Skills (slash commands)
+
+| Command | Description |
+|---------|-------------|
+| `/clawfire-api` | API 생성/수정 → 라우트 + 클라이언트 자동 생성 |
+| `/clawfire-model` | 모델 생성/수정 → Rules + 인덱스 자동 생성 |
+| `/clawfire-auth` | 인증 정책 설정 → Guards 자동 반영 |
+| `/clawfire-deploy` | Firebase 배포 (명시적 요청 필요) |
+| `/clawfire-diagnose` | 문제 탐지 및 수정 제안 |
+
+---
+
+## Core Pattern: defineAPI
+
+모든 API는 이 패턴을 따릅니다:
+
+```ts
+import { defineAPI, z } from "clawfire";
+
+export default defineAPI({
+  input: z.object({ ... }),         // Zod 입력 스키마
+  output: z.object({ ... }),        // Zod 출력 스키마
+  meta: {
+    description: "...",             // 필수 — AI/Playground가 읽음
+    auth: "public",                 // "public" | "authenticated" | "role" | "reauth"
+    tags: ["..."],                  // 그룹화용
+  },
+  handler: async (input, ctx) => {  // 비즈니스 로직
+    return { ... };
+  },
+});
+```
+
+**절대 규칙:**
+- 모든 API는 **POST만** 사용
+- `input`과 `output`은 반드시 `z.object({})`
+- `meta.description`은 필수
+- `handler`는 반드시 `async`
+- import는 `from "clawfire"` (NOT `"clawfire"`)
+
+---
+
+## Core Pattern: defineModel
+
+```ts
+import { defineModel } from "clawfire";
+
+export const Todo = defineModel({
+  collection: "todos",
+  fields: {
+    title: { type: "string", required: true },
+    completed: { type: "boolean", required: true },
+  },
+  timestamps: true,
+  rules: {
+    read: "public",
+    create: "authenticated",
+    update: "authenticated",
+    delete: "role",
+    deleteRoles: ["admin"],
+    ownerField: "userId",
+  },
+});
+```
+
+---
+
+## File-Based Routing
+
+파일 경로 = API 경로:
+
+```
+app/routes/health.ts             → POST /api/health
+app/routes/todos/list.ts         → POST /api/todos/list
+app/routes/products/[id]/get.ts  → POST /api/products/:id/get
+```
+
+---
+
+## Error Handling
+
+```ts
+import { Errors } from "clawfire";
+
+throw Errors.notFound("Not found");         // 404
+throw Errors.validation("Bad input", err);  // 400
+throw Errors.forbidden("No access");        // 403
+throw Errors.unauthorized("Login required");// 401
+throw Errors.conflict("Already exists");    // 409
+```
+
+---
+
+## Response Format
+
+성공: `{ "data": { ... } }`
+실패: `{ "error": { "code": "NOT_FOUND", "message": "..." } }`
+
+---
+
+## Auth Levels
+
+| Level | 의미 | Header |
+|-------|------|--------|
+| `public` | 인증 불필요 | 없음 |
+| `authenticated` | 로그인 필수 | `Authorization: Bearer <token>` |
+| `role` | 특정 역할 필요 | Bearer + role 매칭 |
+| `reauth` | 최근 인증 필요 (5분) | Bearer + 최신 토큰 |
+
+---
+
+## Adding a New Resource (Step-by-Step)
+
+사용자가 "상품 API 만들어줘"라고 하면:
+
+### Step 1: Store 추가 (인메모리 모드)
+
+`app/store.ts`에 새 Map + CRUD 메서드 추가.
+
+### Step 2: Schema 생성
+
+`app/schemas/product.ts` 생성 → `defineModel(...)`.
+
+### Step 3: Routes 생성
+
+```
+app/routes/products/
+  list.ts     ← 목록 조회
+  create.ts   ← 생성
+  update.ts   ← 수정
+  delete.ts   ← 삭제
+```
+
+각 파일에 `defineAPI(...)` with 적절한 input/output/handler.
+
+### Step 4: Dev 서버 확인
+
+`npm run dev` → 라우트 자동 발견, 핫 리로드.
+
+### Step 5: Frontend 업데이트
+
+`public/index.html`에 UI 추가하거나, 사용자에게 별도 프론트엔드 구현 안내.
+
+---
+
+## Security Defaults (변경하지 마세요)
+
+- Input validation: **ON** (Zod 스키마 자동 검증)
+- CORS: **Deny all** (dev에서만 허용)
+- Rate limit: **100 req/min/IP**
+- XSS sanitization: **ON** (`<` `>` 자동 이스케이프)
+- Safe headers: **ON** (X-Frame-Options, X-Content-Type-Options)
+- Log masking: **ON** (password, token 등 자동 마스킹)
+
+---
+
+## Important: What NOT to do
+
+- HTTP method routing 사용 금지 (GET, PUT, DELETE 등) — 모든 것은 POST
+- Express, Fastify 등 다른 프레임워크 사용 금지
+- `from "clawfire"` import 금지 — 반드시 `from "clawfire"`
+- `generated/` 폴더 내 파일 직접 수정 금지
+- Firestore 보안 규칙을 수동으로 작성하지 마세요 — `/clawfire-model` 사용
+- 불필요한 보안 규칙 완화 금지 (최소 권한 원칙)

package/templates/starter/app/routes/health.ts

@@ -0,0 +1,20 @@
+import { defineAPI, z } from "clawfire";
+
+export default defineAPI({
+  input: z.object({}),
+  output: z.object({
+    status: z.string(),
+    timestamp: z.string(),
+    version: z.string(),
+  }),
+  meta: {
+    description: "Health check endpoint",
+    auth: "public",
+    tags: ["system"],
+  },
+  handler: async () => ({
+    status: "ok",
+    timestamp: new Date().toISOString(),
+    version: "1.0.0",
+  }),
+});

package/templates/starter/app/routes/todos/create.ts

@@ -0,0 +1,25 @@
+import { defineAPI, z } from "clawfire";
+import { todoStore } from "../../store.js";
+
+export default defineAPI({
+  input: z.object({
+    title: z.string().min(1).max(200),
+  }),
+  output: z.object({
+    todo: z.object({
+      id: z.string(),
+      title: z.string(),
+      completed: z.boolean(),
+      createdAt: z.string(),
+    }),
+  }),
+  meta: {
+    description: "Create a new todo",
+    auth: "public",
+    tags: ["todos"],
+  },
+  handler: async (input) => {
+    const todo = todoStore.create(input.title);
+    return { todo };
+  },
+});

package/templates/starter/app/routes/todos/delete.ts

@@ -0,0 +1,20 @@
+import { defineAPI, z } from "clawfire";
+import { todoStore } from "../../store.js";
+
+export default defineAPI({
+  input: z.object({
+    id: z.string(),
+  }),
+  output: z.object({
+    success: z.boolean(),
+  }),
+  meta: {
+    description: "Delete a todo",
+    auth: "public",
+    tags: ["todos"],
+  },
+  handler: async (input) => {
+    const success = todoStore.delete(input.id);
+    return { success };
+  },
+});

package/templates/starter/app/routes/todos/list.ts

@@ -0,0 +1,26 @@
+import { defineAPI, z } from "clawfire";
+import { todoStore } from "../../store.js";
+
+export default defineAPI({
+  input: z.object({}),
+  output: z.object({
+    todos: z.array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        completed: z.boolean(),
+        createdAt: z.string(),
+      }),
+    ),
+    count: z.number(),
+  }),
+  meta: {
+    description: "List all todos",
+    auth: "public",
+    tags: ["todos"],
+  },
+  handler: async () => {
+    const todos = todoStore.list();
+    return { todos, count: todos.length };
+  },
+});

package/templates/starter/app/routes/todos/update.ts

@@ -0,0 +1,32 @@
+import { defineAPI, z } from "clawfire";
+import { todoStore } from "../../store.js";
+
+export default defineAPI({
+  input: z.object({
+    id: z.string(),
+    title: z.string().min(1).max(200).optional(),
+    completed: z.boolean().optional(),
+  }),
+  output: z.object({
+    todo: z
+      .object({
+        id: z.string(),
+        title: z.string(),
+        completed: z.boolean(),
+        createdAt: z.string(),
+      })
+      .nullable(),
+  }),
+  meta: {
+    description: "Update a todo (toggle complete, edit title)",
+    auth: "public",
+    tags: ["todos"],
+  },
+  handler: async (input) => {
+    const todo = todoStore.update(input.id, {
+      title: input.title,
+      completed: input.completed,
+    });
+    return { todo };
+  },
+});

package/templates/starter/app/schemas/todo.ts

@@ -0,0 +1,16 @@
+import { defineModel } from "clawfire";
+
+export const Todo = defineModel({
+  collection: "todos",
+  fields: {
+    title: { type: "string", required: true, description: "Todo title" },
+    completed: { type: "boolean", required: true, description: "Completion status" },
+  },
+  timestamps: true,
+  rules: {
+    read: "public",
+    create: "public",
+    update: "public",
+    delete: "public",
+  },
+});

package/templates/starter/app/store.ts

@@ -0,0 +1,56 @@
+/**
+ * In-memory Todo Store
+ *
+ * Firebase 없이 동작하는 간단한 인메모리 저장소.
+ * 나중에 Firestore로 교체할 수 있습니다.
+ */
+
+export interface Todo {
+  id: string;
+  title: string;
+  completed: boolean;
+  createdAt: string;
+}
+
+const todos: Map<string, Todo> = new Map();
+let idCounter = 0;
+
+function generateId(): string {
+  return `todo_${++idCounter}_${Date.now()}`;
+}
+
+export const todoStore = {
+  list(): Todo[] {
+    return Array.from(todos.values()).sort(
+      (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+    );
+  },
+
+  get(id: string): Todo | undefined {
+    return todos.get(id);
+  },
+
+  create(title: string): Todo {
+    const todo: Todo = {
+      id: generateId(),
+      title,
+      completed: false,
+      createdAt: new Date().toISOString(),
+    };
+    todos.set(todo.id, todo);
+    return todo;
+  },
+
+  update(id: string, data: Partial<Pick<Todo, "title" | "completed">>): Todo | null {
+    const todo = todos.get(id);
+    if (!todo) return null;
+    if (data.title !== undefined) todo.title = data.title;
+    if (data.completed !== undefined) todo.completed = data.completed;
+    todos.set(id, todo);
+    return todo;
+  },
+
+  delete(id: string): boolean {
+    return todos.delete(id);
+  },
+};

package/templates/starter/clawfire.config.ts

@@ -0,0 +1,25 @@
+import { configureClawfire } from "clawfire";
+
+export default configureClawfire({
+  firebase: {
+    apiKey: "YOUR_API_KEY",
+    authDomain: "YOUR_PROJECT.firebaseapp.com",
+    projectId: "YOUR_PROJECT_ID",
+    storageBucket: "YOUR_PROJECT.firebasestorage.app",
+    appId: "YOUR_APP_ID",
+  },
+  server: {
+    region: "us-central1",
+    cors: [],
+    rateLimit: 100,
+  },
+  security: {
+    validateInput: true,
+    safeHeaders: true,
+    maskLogs: true,
+  },
+  playground: {
+    enabled: true,
+    path: "/__playground",
+  },
+});

package/templates/starter/dev.ts

@@ -0,0 +1,12 @@
+/**
+ * Clawfire Dev Server Entry Point
+ *
+ * Usage: npx tsx dev.ts
+ * Or:    npm run dev
+ */
+import { startDevServer } from "clawfire/dev";
+
+startDevServer({
+  port: 3456,
+  hotReload: true,
+});

package/templates/starter/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "my-clawfire-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "npx tsx dev.ts",
+    "build": "tsc --noEmit",
+    "deploy": "npx clawfire deploy"
+  },
+  "dependencies": {
+    "clawfire": "latest"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  }
+}