@mandujs/mcp 0.30.0 → 0.31.0

package/src/resources/skills/mandu-deployment/rules/db-provider-supabase.md

@@ -0,0 +1,300 @@
+---
+title: Use Supabase as Postgres provider
+impact: MEDIUM
+impactDescription: Managed Postgres + optional Realtime / Storage / Auth — Mandu consumes it as a connection string, not a deploy target
+tags: database, postgres, supabase, baas
+---
+
+## Use Supabase as Postgres provider
+
+> **Supabase 는 Mandu 의 배포 타겟이 아닙니다.** Mandu 앱은 Render / Fly / Railway /
+> Vercel / Docker 등으로 배포하고, Supabase 는 **Postgres 제공자 + 선택적
+> BaaS 기능** (Realtime, Storage, Auth, Edge Functions) 으로만 사용합니다.
+> Mandu 의 `@mandujs/core/db` 가 `Bun.SQL` wrapper 이기 때문에 Supabase 의
+> pooler URL 을 그대로 꽂으면 별도 SDK 없이 바로 동작합니다.
+
+## 1. 가장 단순한 경로 — DB-only (권장)
+
+Supabase 를 Postgres 로만 쓰는 경우. Mandu 의 네이티브 DB 레이어가 그대로 커버합니다.
+
+### 1.1 Connection string 획득
+
+Supabase Dashboard → Settings → Database → **Connection pooling**
+- `Transaction` 모드 URL 복사 (포트 `6543`)
+- 형식: `postgres://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:6543/postgres`
+
+### 1.2 `.env` 에 저장
+
+```bash
+DATABASE_URL=postgres://postgres.xxxx:your-password@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+```
+
+### 1.3 Mandu DB 핸들 생성
+
+```typescript
+// lib/db.ts
+import { createDb } from "@mandujs/core/db";
+
+export const db = createDb({
+  url: process.env.DATABASE_URL!,
+});
+```
+
+### 1.4 Filling 에서 쿼리
+
+```typescript
+// app/users/[id]/route.ts
+import { defineFilling, notFound } from "@mandujs/core/filling";
+import { db } from "@/lib/db";
+
+export const filling = defineFilling({
+  async loader({ params }) {
+    const user = await db.one<{ id: string; email: string; name: string }>`
+      SELECT id, email, name FROM users WHERE id = ${params.id}
+    `;
+    if (!user) throw notFound();
+    return { user };
+  },
+});
+```
+
+트랜잭션:
+
+```typescript
+await db.transaction(async (tx) => {
+  const user = await tx.one<{ id: string }>`
+    INSERT INTO users (email, name) VALUES (${email}, ${name}) RETURNING id
+  `;
+  await tx`INSERT INTO profiles (user_id, bio) VALUES (${user!.id}, ${bio})`;
+});
+```
+
+**필요한 Supabase-specific 의존성**: 없음. `@mandujs/core/db` 만 사용. Supabase 가 바뀌어도 connection string 교체뿐.
+
+## 2. 마이그레이션
+
+Mandu 의 기본 마이그레이션 러너를 사용하거나 (`@mandujs/core/db/migrations`), Supabase CLI 를 병행할 수 있습니다.
+
+### Mandu 마이그레이션 (권장)
+
+```sql
+-- migrations/001_users.sql
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT UNIQUE NOT NULL,
+  name TEXT,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+```bash
+bun run mandu db migrate
+```
+
+### Supabase CLI 병행
+
+RLS (Row Level Security) / policies 등 Supabase-native 기능이 필요한 경우:
+
+```bash
+npm install -g supabase
+supabase login
+supabase init
+supabase migration new create_users_table
+# edit supabase/migrations/<timestamp>_create_users_table.sql
+supabase db push
+```
+
+`ALTER TABLE users ENABLE ROW LEVEL SECURITY;` 등은 plain SQL 이므로 Mandu 마이그레이션에도 그대로 작성 가능. Supabase CLI 는 RLS policy 편집 UX 와 타입 생성 (`supabase gen types typescript`) 때문에 편리합니다.
+
+## 3. Supabase SDK 를 함께 쓰고 싶다면 (BaaS 기능)
+
+DB 는 `@mandujs/core/db` 로, Supabase-specific 기능 (Realtime / Storage / Edge Functions) 만 SDK 로 사용하는 하이브리드가 깔끔합니다.
+
+### 3.1 클라이언트 설정
+
+```bash
+bun add @supabase/supabase-js
+```
+
+```typescript
+// lib/supabase.ts
+import { createClient } from "@supabase/supabase-js";
+
+const supabaseUrl = process.env.SUPABASE_URL!;
+const supabaseAnonKey = process.env.SUPABASE_ANON_KEY!;
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey);
+
+// 서버 사이드 (Service Role) — filling 안에서만 사용
+export function createServerSupabase() {
+  return createClient(supabaseUrl, process.env.SUPABASE_SERVICE_ROLE_KEY!, {
+    auth: { autoRefreshToken: false, persistSession: false },
+  });
+}
+```
+
+### 3.2 Realtime (Island)
+
+Mandu 의 client island 에서 Realtime 구독:
+
+```tsx
+// app/messages/MessagesIsland.client.tsx
+import { island } from "@mandujs/core/client";
+import { useEffect, useState } from "react";
+import { supabase } from "@/lib/supabase";
+
+function Messages() {
+  const [messages, setMessages] = useState<Array<{ id: string; content: string }>>([]);
+
+  useEffect(() => {
+    supabase.from("messages").select("*").then(({ data }) => {
+      setMessages(data ?? []);
+    });
+
+    const channel = supabase
+      .channel("messages")
+      .on(
+        "postgres_changes",
+        { event: "INSERT", schema: "public", table: "messages" },
+        (payload) => {
+          setMessages((prev) => [...prev, payload.new as { id: string; content: string }]);
+        },
+      )
+      .subscribe();
+
+    return () => {
+      supabase.removeChannel(channel);
+    };
+  }, []);
+
+  return (
+    <ul>
+      {messages.map((m) => <li key={m.id}>{m.content}</li>)}
+    </ul>
+  );
+}
+
+export default island("visible", <Messages />);
+```
+
+### 3.3 Storage
+
+```typescript
+// filling 내에서
+const serverSupabase = createServerSupabase();
+
+const { data, error } = await serverSupabase.storage
+  .from("avatars")
+  .upload(`${userId}/avatar.png`, file);
+
+const { data: { publicUrl } } = serverSupabase.storage
+  .from("avatars")
+  .getPublicUrl(`${userId}/avatar.png`);
+```
+
+### 3.4 Edge Functions
+
+Supabase 의 Deno 런타임에서 도는 서버리스 함수. Mandu 앱 바깥에서 별도 배포되고, Mandu 는 HTTP 로 호출만:
+
+```typescript
+const res = await fetch(`${process.env.SUPABASE_URL}/functions/v1/hello`, {
+  method: "POST",
+  headers: {
+    "Authorization": `Bearer ${process.env.SUPABASE_ANON_KEY}`,
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({ name: "mandu" }),
+});
+```
+
+## 4. Supabase Auth 와 Mandu auth — 선택 문제
+
+두 가지가 겹치는 영역이라 **둘 중 하나만** 씁니다:
+
+| Mandu 의 `@mandujs/core/auth` (native) | Supabase Auth |
+|---|---|
+| Bun.password (argon2id) | Bcrypt + custom hashing |
+| `@mandujs/core/middleware/session` SQLite session store | JWT + cookie |
+| CSRF (`@mandujs/core/middleware/csrf`) | — |
+| Mandu 프로젝트 자체 사용자 테이블 | Supabase `auth.users` 테이블 |
+
+**추천**: Mandu 앱이 Supabase 의 다른 기능 (Realtime / Storage) 을 안 쓰면 **Mandu native auth** 가 의존성 적고 예측 가능. Supabase 의 social providers (GitHub / Google OAuth UI) 가 필요하면 Supabase Auth 를 쓰고 Mandu auth 는 bypass.
+
+병행 사용 (Supabase Auth 만 이용하면서 Mandu filling 안에서 token 검증):
+
+```typescript
+// middleware/supabase-auth.ts
+import { createServerSupabase } from "@/lib/supabase";
+
+export async function supabaseAuthMiddleware(ctx) {
+  const header = ctx.headers.get("authorization");
+  if (!header?.startsWith("Bearer ")) return ctx.unauthorized("Missing token");
+
+  const token = header.slice(7);
+  const supabase = createServerSupabase();
+  const { data: { user }, error } = await supabase.auth.getUser(token);
+  if (error || !user) return ctx.unauthorized("Invalid token");
+
+  ctx.set("user", user);
+}
+```
+
+## 5. 환경 변수
+
+```bash
+# .env
+# DB connection (최소 요구사항)
+DATABASE_URL=postgres://postgres.xxx:password@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+
+# Supabase SDK 사용 시 추가
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_ANON_KEY=eyJ...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...   # 서버 전용, 클라이언트에 노출 금지
+```
+
+## 6. 배포 플랫폼과 조합
+
+Supabase 는 DB layer 이므로 **Mandu 앱 자체는 다른 곳** 에 배포합니다. `DATABASE_URL` 만 환경 변수로 주입:
+
+### Render (`mandu deploy --target=render` 가 자동 생성)
+
+```yaml
+# render.yaml
+services:
+  - type: web
+    name: mandu-app
+    runtime: node
+    buildCommand: |
+      curl -fsSL https://bun.sh/install | bash
+      export PATH="$HOME/.bun/bin:$PATH"
+      bun install --frozen-lockfile
+      bun run build
+    startCommand: bun run start
+    envVars:
+      - key: DATABASE_URL
+        sync: false           # Render 대시보드에서 Supabase pooler URL 설정
+      - key: SUPABASE_URL
+        sync: false           # SDK 쓸 때만
+      - key: SUPABASE_ANON_KEY
+        sync: false
+```
+
+### Fly / Railway
+
+```bash
+fly secrets set DATABASE_URL="postgres://..." SUPABASE_URL="..." SUPABASE_ANON_KEY="..."
+railway variables set DATABASE_URL="postgres://..." SUPABASE_URL="..." SUPABASE_ANON_KEY="..."
+```
+
+## 7. 주의사항
+
+- **Transaction mode pooler (6543) 를 사용**하세요. Session mode (5432) 는 커넥션 고정이 필요한 경우에만.
+- **Service Role key 는 서버 전용**. Client island 에서 절대 import 하지 마세요 — Mandu 의 island 번들에 포함되면 공개됩니다.
+- **RLS 를 켜지 않은 테이블** 은 anon key 로 전체 읽기가 가능해집니다. 항상 `ENABLE ROW LEVEL SECURITY` 적용하고 policy 를 명시.
+- **Realtime 구독은 client bundle 비용**이 큽니다 (`@supabase/supabase-js` ~60 KB). 페이지 단위로 island 분리하세요.
+
+## Reference
+
+- [Supabase Docs](https://supabase.com/docs)
+- `@mandujs/core/db` — Bun.SQL wrapper, provider-agnostic. `packages/core/src/db/index.ts`
+- Deploy adapters — `packages/cli/src/commands/deploy/adapters/{render,fly,railway,vercel,netlify,docker,docker-compose,cf-pages}.ts`

package/src/server.ts

@@ -29,7 +29,8 @@ import { registerBuiltinTools, getToolsSummary } from "./tools/index.js";
 
 // DNA-007: 에러 처리
 import { createToolResponse, logToolError } from "./executor/error-handler.js";
-import { ToolExecutor, createToolExecutor } from "./executor/tool-executor.js";
+import type { ToolExecutor} from "./executor/tool-executor.js";
+import { createToolExecutor } from "./executor/tool-executor.js";
 
 // DNA-008: 로깅 통합
 import { setupMcpLogging, teardownMcpLogging } from "./logging/mcp-transport.js";