clawfire 0.1.0

package/templates/functions/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Clawfire Firebase Functions Entry Point
+ *
+ * This is the main entry point for your Firebase Functions.
+ * Routes are automatically registered from app/routes/.
+ */
+import * as admin from "firebase-admin";
+import * as functions from "firebase-functions";
+import {
+  createRouter,
+  createAdminDB,
+  createSecurityMiddleware,
+} from "clawfire/functions";
+
+// Initialize Firebase Admin
+admin.initializeApp();
+
+// Create database wrapper
+export const db = createAdminDB(admin.firestore());
+
+// Create router with security middleware
+const router = createRouter({
+  auth: admin.auth(),
+  cors: [], // Add your allowed origins here
+  middleware: createSecurityMiddleware({
+    logRequests: true,
+    sanitize: true,
+  }),
+});
+
+// ── Register Routes ─────────────────────────────────────────────
+// Routes are registered here. Use /clawfire-api skill to auto-manage this.
+
+import healthRoute from "../app/routes/health";
+router.register("/health", healthRoute);
+
+import loginRoute from "../app/routes/auth/login";
+router.register("/auth/login", loginRoute);
+
+// ── Export Cloud Function ────────────────────────────────────────
+export const api = functions.https.onRequest((req, res) => {
+  router.handleRequest(req as any, res as any);
+});

package/templates/starter/.claude/skills/clawfire-api/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: clawfire-api
+description: API 생성/수정 → 스키마 기반 라우트 + 클라이언트 자동 생성
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+---
+
+# /clawfire-api
+
+API를 생성하거나 수정하고, 타입 안전한 클라이언트를 자동 생성합니다.
+
+## 사용 예시
+
+사용자: "상품 CRUD API 만들어줘"
+사용자: "주문 생성 API 추가"
+사용자: "상품 목록 API에 카테고리 필터 추가"
+
+## 수행 작업
+
+### 1. 라우트 파일 생성/수정
+
+`app/routes/<path>.ts` 에 라우트를 생성합니다.
+
+```ts
+import { defineAPI, z, Errors } from "clawfire";
+
+export default defineAPI({
+  input: z.object({
+    name: z.string().min(1),
+    price: z.number().positive(),
+    category: z.enum(["electronics", "clothing", "food"]),
+  }),
+  output: z.object({
+    product: z.object({
+      id: z.string(),
+      name: z.string(),
+      price: z.number(),
+      category: z.string(),
+      createdAt: z.string(),
+    }),
+  }),
+  meta: {
+    description: "상품 생성",
+    auth: "authenticated",
+    tags: ["products"],
+    exampleInput: {
+      name: "아이폰 16",
+      price: 1500000,
+      category: "electronics",
+    },
+  },
+  handler: async (input, ctx) => {
+    const product = {
+      id: `prod_${Date.now()}`,
+      ...input,
+      createdAt: new Date().toISOString(),
+    };
+    return { product };
+  },
+});
+```
+
+### 2. 파일 라우팅 규칙
+
+파일 경로가 곧 API 경로입니다:
+
+```
+app/routes/health.ts             → POST /api/health
+app/routes/products/list.ts      → POST /api/products/list
+app/routes/products/create.ts    → POST /api/products/create
+app/routes/products/[id]/get.ts  → POST /api/products/:id/get
+app/routes/auth/login.ts         → POST /api/auth/login
+```
+
+### 3. CRUD 패턴 (새 리소스 추가 시)
+
+새로운 리소스(예: products)를 추가할 때 표준 파일 구조:
+
+```
+app/routes/products/
+  list.ts     ← 목록 조회 (필터, 페이지네이션)
+  create.ts   ← 생성
+  update.ts   ← 수정
+  delete.ts   ← 삭제
+```
+
+### 4. 데이터 저장소 연결
+
+현재 프로젝트가 인메모리 store를 사용하는 경우:
+- `app/store.ts` 에 새 리소스의 저장소 추가
+- Map 기반 CRUD 메서드 추가
+
+Firestore를 사용하는 경우:
+- `functions/index.ts` 에서 `createAdminDB`로 생성한 `db` 사용
+- handler에서 `db.create()`, `db.query()` 등 사용
+
+## 필수 규칙
+
+- 모든 API는 **POST만** 사용 (HTTP 메서드 구분 없음)
+- `input`과 `output`은 반드시 `z.object({...})`
+- `meta.description`은 필수 (Playground/AI가 읽음)
+- `meta.auth`를 명시하지 않으면 보안 위험 — 항상 지정
+- handler는 반드시 `async` 함수
+- 에러는 `Errors.notFound()`, `Errors.forbidden()` 등 사용
+- `import`는 반드시 `from "clawfire"`
+
+## 에러 처리 패턴
+
+```ts
+import { Errors } from "clawfire";
+
+// 404
+throw Errors.notFound("Product not found");
+// 400
+throw Errors.validation("Invalid input", details);
+// 403
+throw Errors.forbidden("Admin only");
+// 409
+throw Errors.conflict("Already exists");
+```
+
+## 응답 형식
+
+성공: `{ "data": { ... } }`
+실패: `{ "error": { "code": "NOT_FOUND", "message": "..." } }`

package/templates/starter/.claude/skills/clawfire-auth/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: clawfire-auth
+description: Auth 정책 설정 → 로그인, 역할, 재인증, Guards 자동 반영
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# /clawfire-auth
+
+인증/인가 정책을 대화 기반으로 설정하고 Rules/Guards에 자동 반영합니다.
+
+## 사용 예시
+
+사용자: "관리자만 상품 삭제할 수 있게 해줘"
+사용자: "비밀번호 변경은 재인증 필요하게 해줘"
+사용자: "비회원도 상품 목록 볼 수 있게 해줘"
+
+## 수행 작업
+
+### 1. API 메타데이터 업데이트
+
+라우트 파일의 `meta.auth` 변경:
+
+```ts
+meta: {
+  auth: "role",
+  roles: ["admin"],
+}
+```
+
+### 2. Firestore Rules 업데이트
+
+모델 정의의 `rules` 속성 수정 후 `firestore.rules` 재생성.
+
+### 3. 클라이언트 코드 갱신
+
+인증 수준이 바뀌면 `generated/api-client.ts`도 업데이트.
+
+## 인증 수준
+
+| 수준 | 설명 | Header 필요 |
+|------|------|------------|
+| `public` | 인증 불필요 | 없음 |
+| `authenticated` | 로그인 필수 | `Authorization: Bearer <token>` |
+| `role` | 특정 역할 필요 | Bearer + 역할 매칭 |
+| `reauth` | 최근 재인증 필요 (5분 이내) | Bearer + 최신 토큰 |
+
+## 핸들러에서 auth 사용
+
+```ts
+handler: async (input, ctx) => {
+  // public: ctx.auth는 null일 수 있음
+  // authenticated: ctx.auth 보장 (non-null)
+  // role: ctx.auth.role 보장
+  // reauth: ctx.reauthenticated === true 보장
+
+  const userId = ctx.auth!.uid;
+  const userRole = ctx.auth!.role;
+  const email = ctx.auth!.email;
+}
+```
+
+## 역할 관리 (서버 측)
+
+```ts
+import { setUserRole, getUserRole } from "clawfire/functions";
+
+await setUserRole(auth, uid, "admin");
+const role = await getUserRole(auth, uid);
+```
+
+## 클라이언트 측 인증
+
+```ts
+import { createClientAuth } from "clawfire/client";
+import { getAuth } from "firebase/auth";
+
+const auth = createClientAuth(getAuth());
+const token = await auth.getIdToken();
+
+// API 호출 시
+fetch("/api/products/create", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${token}`,
+  },
+  body: JSON.stringify({ name: "Widget" }),
+});
+```
+
+## Firestore Rules 자동 생성 헬퍼
+
+rules 파일에 자동 포함되는 헬퍼 함수:
+- `isAuthenticated()` — 로그인 여부
+- `isOwner(userId)` — 문서 소유자 여부
+- `hasRole(role)` — 특정 역할 보유
+- `hasAnyRole(roles)` — 역할 목록 중 하나 보유
+- `isRecentAuth()` — 5분 이내 인증 여부
+
+## 주의
+
+- 기본값은 보안 우선 — 명시적으로 열어줘야 접근 가능
+- `public` API도 rate limit은 적용됨
+- `role` 사용 시 반드시 `roles` 배열 지정
+- Firestore rules와 API auth를 동기화 유지

package/templates/starter/.claude/skills/clawfire-deploy/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: clawfire-deploy
+description: Firebase Hosting + Functions 배포 자동화
+user-invocable: true
+disable-model-invocation: true
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+---
+
+# /clawfire-deploy
+
+Firebase Hosting과 Functions를 배포합니다.
+
+**이 스킬은 배포(side-effect)를 수행하므로 자동 실행이 비활성화되어 있습니다.**
+사용자가 명시적으로 "/clawfire-deploy" 또는 "배포해줘"라고 요청해야 합니다.
+
+## 배포 전 체크리스트
+
+### 1. Firebase CLI 설치 및 로그인 확인
+
+```bash
+firebase --version
+firebase login:list
+```
+
+설치 안 됐으면: `npm install -g firebase-tools`
+
+### 2. Firebase 프로젝트 연결 확인
+
+```bash
+firebase use
+```
+
+연결 안 됐으면: `firebase use --add`
+
+### 3. 빌드 확인
+
+```bash
+# TypeScript 체크
+npx tsc --noEmit
+
+# Functions 빌드
+cd functions && npm run build
+```
+
+### 4. Rules 동기화 확인
+
+- `firestore.rules`가 최신 모델을 반영하는지 확인
+- 필요 시 `/clawfire-model` 스킬로 재생성
+
+### 5. 설정 확인
+
+- `firebase.json` 존재 확인
+- `clawfire.config.ts`에 실제 Firebase 설정값 확인 (YOUR_API_KEY 등 플레이스홀더 아닌지)
+
+## 배포 실행
+
+```bash
+# 전체 배포 (Hosting + Functions + Rules + Indexes)
+firebase deploy
+
+# 개별 배포
+firebase deploy --only hosting
+firebase deploy --only functions
+firebase deploy --only firestore:rules
+firebase deploy --only firestore:indexes
+```
+
+## 배포 후 확인
+
+```bash
+# 배포된 URL
+firebase hosting:channel:list
+
+# Functions 로그
+firebase functions:log --only api
+
+# 프로젝트 대시보드
+echo "https://console.firebase.google.com/project/$(firebase use)/overview"
+```
+
+## 문제 해결
+
+- 빌드 실패: `npx tsc --noEmit`으로 타입 에러 확인
+- Rules 배포 실패: `firebase deploy --only firestore:rules --debug`
+- Functions 배포 실패: `firebase functions:log`에서 에러 확인
+- 권한 문제: `firebase login`으로 재로그인
+
+## 주의
+
+- Rules 변경은 **즉시 적용** — 실수 시 데이터 접근 문제
+- Functions 배포는 2-5분 소요
+- 프로덕션 배포 전 에뮬레이터에서 먼저 테스트 권장

package/templates/starter/.claude/skills/clawfire-diagnose/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: clawfire-diagnose
+description: 인덱스 누락, Rules 거부, 권한 문제 탐지 및 수정 제안
+user-invocable: true
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - Edit
+  - Write
+---
+
+# /clawfire-diagnose
+
+프로젝트의 문제를 탐지하고 수정을 제안합니다.
+
+## 진단 항목
+
+### 1. 구조 검증
+- `app/routes/` 내 파일이 올바른 `defineAPI` export를 가지는지
+- `app/schemas/` 내 파일이 올바른 `defineModel` export를 가지는지
+- 필수 파일 존재: `firebase.json`, `clawfire.config.ts`, `dev.ts`, `package.json`
+
+### 2. Import 검증
+- 모든 import가 `clawfire`를 사용하는지 (`clawfire` 아닌지)
+- 필요한 import 누락 여부
+
+### 3. API 계약 검증
+- `input`과 `output`이 `z.object()`인지
+- `meta.description` 존재 여부
+- `meta.auth` 명시 여부 (없으면 보안 위험 경고)
+- `meta.auth: "role"` 시 `meta.roles`가 비어있지 않은지
+- `handler`가 async 함수인지
+
+### 4. 모델 검증
+- `collection` 이름이 소문자 복수형인지
+- `rules`가 정의되어 있는지
+- `ownerField` 사용 시 해당 필드가 `fields`에 존재하는지
+
+### 5. Security Rules 검증
+- `firestore.rules`가 모델 정의와 일치하는지
+- 과도하게 열린 규칙 경고 (`allow read, write: if true`)
+- 규칙 누락 컬렉션 감지
+
+### 6. 인덱스 검증
+- 모델의 `indexes`가 `firestore.indexes.json`에 반영되어 있는지
+
+### 7. Firebase 설정 검증
+- `firebase.json` 유효성
+- `clawfire.config.ts`에 플레이스홀더 값(`YOUR_API_KEY`) 잔존 여부
+
+### 8. 데이터 스토어 일관성
+- `app/store.ts` 사용 시 → 라우트에서 올바르게 import하는지
+- Firestore 사용 시 → `functions/index.ts`에 라우트 등록 여부
+
+## 수행 방법
+
+1. 모든 `app/schemas/*.ts` 파일 스캔
+2. 모든 `app/routes/**/*.ts` 파일 스캔
+3. 설정 파일 읽기 (`firebase.json`, `firestore.rules`, `firestore.indexes.json`, `clawfire.config.ts`)
+4. 문제 목록 생성
+5. 각 문제에 대한 구체적 수정 제안
+6. 사용자 승인 시 자동 수정
+
+## 출력 형식
+
+```
+Clawfire Diagnosis Report
+═════════════════════════
+
+[OK]   firebase.json exists and is valid
+[OK]   firestore.rules exists
+[OK]   5 routes found in app/routes/
+[WARN] clawfire.config.ts contains placeholder API key
+[WARN] Model "Todo" rules allow public write — intentional?
+[ERR]  Route "products/delete" has auth: "role" but no roles specified
+
+Suggested Fixes:
+  1. Update clawfire.config.ts with real Firebase config
+  2. Consider restricting Todo write rules to "authenticated"
+  3. Add roles: ["admin"] to products/delete route
+
+Apply fixes? (y/n)
+```
+
+## 자동 수정 가능 항목
+
+- 누락된 `meta.auth` 추가 (기본: "authenticated")
+- 비어있는 `roles` 채우기
+- `firestore.rules` 재생성
+- `firestore.indexes.json` 재생성
+- import 경로 수정 (`"clawfire"` → `"clawfire"`)
+
+## 주의
+
+- 진단만 수행 — 수정은 사용자 승인 후 진행
+- `public` 규칙은 경고만 (의도적일 수 있음)
+- 에뮬레이터 로그가 있으면 추가 분석 가능

package/templates/starter/.claude/skills/clawfire-model/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: clawfire-model
+description: Firestore 모델(컬렉션) 정의 → 스키마 + Rules + 인덱스 자동 생성
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# /clawfire-model
+
+자연어로 모델을 선언하면 Firestore 구조, Security Rules, 인덱스를 자동 생성합니다.
+
+## 사용 예시
+
+사용자: "상품, 주문, 유저 모델 만들어줘"
+사용자: "상품에 옵션 배열 추가해줘"
+사용자: "주문에 배송 상태 필드 추가"
+
+## 수행 작업
+
+### 1. 모델 파일 생성/수정
+
+`app/schemas/<model>.ts` 에 모델을 정의합니다:
+
+```ts
+import { defineModel } from "clawfire";
+
+export const Product = defineModel({
+  collection: "products",
+  fields: {
+    name: { type: "string", required: true, description: "상품명" },
+    price: { type: "number", required: true, description: "가격" },
+    description: { type: "string", description: "상품 설명" },
+    category: {
+      type: "string",
+      required: true,
+      enum: ["electronics", "clothing", "food"],
+    },
+    tags: { type: "array", items: { type: "string" } },
+    inStock: { type: "boolean", required: true },
+  },
+  timestamps: true,
+  rules: {
+    read: "public",
+    create: "role",
+    createRoles: ["admin"],
+    update: "role",
+    updateRoles: ["admin"],
+    delete: "role",
+    deleteRoles: ["admin"],
+  },
+  indexes: [
+    { fields: [{ field: "category" }, { field: "price", order: "desc" }] },
+  ],
+});
+```
+
+### 2. Security Rules 업데이트
+
+모델 생성/수정 후 반드시 `firestore.rules` 업데이트:
+- 모든 `app/schemas/*.ts` 파일의 모델을 읽음
+- 통합 Firestore Security Rules 생성
+
+### 3. 인덱스 업데이트
+
+모델에 `indexes`가 있으면 `firestore.indexes.json`에 반영.
+
+## 필드 타입 레퍼런스
+
+| 타입 | 설명 | 옵션 |
+|------|------|------|
+| `string` | 문자열 | `enum: ["a", "b"]` |
+| `number` | 숫자 | - |
+| `boolean` | 불리언 | - |
+| `timestamp` | 날짜/시간 | - |
+| `array` | 배열 | `items: { type: "string" }` |
+| `map` | 객체/맵 | `values: { type: "string" }` |
+| `reference` | 문서 참조 | `ref: "products"` |
+| `geopoint` | 위치 좌표 | - |
+
+## 필드 공통 옵션
+
+```ts
+{
+  type: "string",
+  required: true,          // 필수 여부
+  description: "설명",      // AI/문서용
+  default: "기본값",        // 기본값
+  enum: ["a", "b", "c"],   // 허용 값 목록 (string만)
+}
+```
+
+## 보안 규칙 수준
+
+| 수준 | 의미 | 예시 |
+|------|------|------|
+| `public` | 누구나 | 상품 목록 조회 |
+| `authenticated` | 로그인 필수 | 프로필 수정 |
+| `role` | 특정 역할 | 관리자 전용 (roles 필수) |
+| `reauth` | 최근 재인증 | 비밀번호 변경 |
+
+### ownerField 패턴
+
+```ts
+rules: {
+  read: "public",
+  update: "authenticated",
+  ownerField: "userId",
+  // → 본인 문서만 수정 가능 (userId == auth.uid)
+}
+```
+
+## 명명 규칙
+
+- **모델명**: PascalCase (Product, User, Order)
+- **컬렉션명**: lowercase 복수형 (products, users, orders)
+- **파일명**: 소문자 단수형 (product.ts, user.ts, order.ts)
+- **필드명**: camelCase (createdAt, displayName)
+
+## 주의
+
+- `timestamps: true`가 기본 (createdAt, updatedAt 자동)
+- 보안 규칙은 최소 권한 원칙 적용 — 필요 최소한만 열기
+- `import`는 반드시 `from "clawfire"`