@mandujs/cli 0.15.1 → 0.15.3

package/templates/default/src/client/shared/ui/input.tsx

@@ -5,10 +5,14 @@ export interface InputProps
   extends React.InputHTMLAttributes<HTMLInputElement> {}
 
 const Input = React.forwardRef<HTMLInputElement, InputProps>(
-  ({ className, type, ...props }, ref) => {
+  ({ className, type, placeholder, "aria-label": ariaLabel, ...props }, ref) => {
+    const accessibleLabel = ariaLabel ?? (typeof placeholder === "string" ? placeholder : undefined);
+
     return (
       <input
         type={type}
+        placeholder={placeholder}
+        aria-label={accessibleLabel}
         className={cn(
           "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
           className

package/templates/default/tests/example.test.ts

@@ -1,58 +1,58 @@
-// Mandu Example Test
-// 이 파일은 테스트 작성 방법을 보여주는 예제입니다.
-
-import { describe, it, expect } from "bun:test";
-import { createTestRequest, parseJsonResponse, assertStatus } from "./helpers";
-
-describe("Example Tests", () => {
-  describe("Basic Assertions", () => {
-    it("should pass basic equality test", () => {
-      expect(1 + 1).toBe(2);
-    });
-
-    it("should pass object equality test", () => {
-      const obj = { status: "ok", data: { message: "hello" } };
-      expect(obj).toEqual({
-        status: "ok",
-        data: { message: "hello" },
-      });
-    });
-  });
-
-  describe("Test Helpers", () => {
-    it("should create test request", () => {
-      const req = createTestRequest("http://localhost:3000/api/test", {
-        method: "POST",
-        body: { name: "test" },
-      });
-
-      expect(req.method).toBe("POST");
-      expect(req.url).toBe("http://localhost:3000/api/test");
-    });
-
-    it("should parse JSON response", async () => {
-      const mockResponse = new Response(
-        JSON.stringify({ status: "ok" }),
-        { status: 200 }
-      );
-
-      const data = await parseJsonResponse<{ status: string }>(mockResponse);
-      expect(data.status).toBe("ok");
-    });
-  });
-});
-
-// API 핸들러 테스트 예제 (실제 핸들러 import 후 사용)
-// import handler from "../.mandu/generated/server/routes/health.route";
-//
-// describe("API: GET /api/health", () => {
-//   it("should return 200 with status ok", async () => {
-//     const req = createTestRequest("http://localhost:3000/api/health");
-//     const response = handler(req, {});
-//
-//     assertStatus(response, 200);
-//
-//     const data = await parseJsonResponse<{ status: string }>(response);
-//     expect(data.status).toBe("ok");
-//   });
-// });
+// Mandu Example Test
+// 이 파일은 테스트 작성 방법을 보여주는 예제입니다.
+
+import { describe, it, expect } from "bun:test";
+import { createTestRequest, parseJsonResponse, assertStatus } from "./helpers";
+
+describe("Example Tests", () => {
+  describe("Basic Assertions", () => {
+    it("should pass basic equality test", () => {
+      expect(1 + 1).toBe(2);
+    });
+
+    it("should pass object equality test", () => {
+      const obj = { status: "ok", data: { message: "hello" } };
+      expect(obj).toEqual({
+        status: "ok",
+        data: { message: "hello" },
+      });
+    });
+  });
+
+  describe("Test Helpers", () => {
+    it("should create test request", () => {
+      const req = createTestRequest("http://localhost:3000/api/test", {
+        method: "POST",
+        body: { name: "test" },
+      });
+
+      expect(req.method).toBe("POST");
+      expect(req.url).toBe("http://localhost:3000/api/test");
+    });
+
+    it("should parse JSON response", async () => {
+      const mockResponse = new Response(
+        JSON.stringify({ status: "ok" }),
+        { status: 200 }
+      );
+
+      const data = await parseJsonResponse<{ status: string }>(mockResponse);
+      expect(data.status).toBe("ok");
+    });
+  });
+});
+
+// API 핸들러 테스트 예제 (실제 핸들러 import 후 사용)
+// import handler from "../.mandu/generated/server/routes/health.route";
+//
+// describe("API: GET /api/health", () => {
+//   it("should return 200 with status ok", async () => {
+//     const req = createTestRequest("http://localhost:3000/api/health");
+//     const response = handler(req, {});
+//
+//     assertStatus(response, 200);
+//
+//     const data = await parseJsonResponse<{ status: string }>(response);
+//     expect(data.status).toBe("ok");
+//   });
+// });

package/templates/default/tests/helpers.ts

@@ -1,52 +1,52 @@
-// Mandu Test Helpers
-// 테스트에서 사용할 유틸리티 함수들
-
-import type { Request } from "bun";
-
-/**
- * API 핸들러 테스트용 Request 생성
- */
-export function createTestRequest(
-  url: string,
-  options?: {
-    method?: string;
-    body?: unknown;
-    headers?: Record<string, string>;
-  }
-): Request {
-  const { method = "GET", body, headers = {} } = options || {};
-
-  return new Request(url, {
-    method,
-    headers: {
-      "Content-Type": "application/json",
-      ...headers,
-    },
-    body: body ? JSON.stringify(body) : undefined,
-  });
-}
-
-/**
- * Response를 JSON으로 파싱
- */
-export async function parseJsonResponse<T = unknown>(response: Response): Promise<T> {
-  return response.json() as Promise<T>;
-}
-
-/**
- * Response 상태 검증
- */
-export function assertStatus(response: Response, expectedStatus: number): void {
-  if (response.status !== expectedStatus) {
-    throw new Error(
-      `Expected status ${expectedStatus}, got ${response.status}`
-    );
-  }
-}
-
-/**
- * 테스트용 라우트 파라미터 생성
- */
-export function createParams(params: Record<string, string>): Record<string, string> {
-  return params;
-}
+// Mandu Test Helpers
+// 테스트에서 사용할 유틸리티 함수들
+
+import type { Request } from "bun";
+
+/**
+ * API 핸들러 테스트용 Request 생성
+ */
+export function createTestRequest(
+  url: string,
+  options?: {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+  }
+): Request {
+  const { method = "GET", body, headers = {} } = options || {};
+
+  return new Request(url, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+}
+
+/**
+ * Response를 JSON으로 파싱
+ */
+export async function parseJsonResponse<T = unknown>(response: Response): Promise<T> {
+  return response.json() as Promise<T>;
+}
+
+/**
+ * Response 상태 검증
+ */
+export function assertStatus(response: Response, expectedStatus: number): void {
+  if (response.status !== expectedStatus) {
+    throw new Error(
+      `Expected status ${expectedStatus}, got ${response.status}`
+    );
+  }
+}
+
+/**
+ * 테스트용 라우트 파라미터 생성
+ */
+export function createParams(params: Record<string, string>): Record<string, string> {
+  return params;
+}

package/templates/default/tests/setup.ts

@@ -1,9 +1,9 @@
-// Mandu Test Setup
-// Bun 테스트 환경 설정
-
-// 테스트 타임아웃 설정 (필요 시)
-// import { setDefaultTimeout } from "bun:test";
-// setDefaultTimeout(10000);
-
-// 환경 변수 설정
-process.env.NODE_ENV = "test";
+// Mandu Test Setup
+// Bun 테스트 환경 설정
+
+// 테스트 타임아웃 설정 (필요 시)
+// import { setDefaultTimeout } from "bun:test";
+// setDefaultTimeout(10000);
+
+// 환경 변수 설정
+process.env.NODE_ENV = "test";

package/templates/default/tsconfig.json

@@ -1,23 +1,23 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "esModuleInterop": true,
-    "strict": true,
-    "skipLibCheck": true,
-    "jsx": "react-jsx",
-    "types": ["bun-types"],
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "include": [
-    "app/**/*.ts",
-    "app/**/*.tsx",
-    "src/**/*.ts",
-    "src/**/*.tsx"
-  ],
-  "exclude": ["node_modules"]
-}
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "types": ["bun-types"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "app/**/*.ts",
+    "app/**/*.tsx",
+    "src/**/*.ts",
+    "src/**/*.tsx"
+  ],
+  "exclude": ["node_modules"]
+}

package/templates/realtime-chat/AGENTS.md

@@ -0,0 +1,96 @@
+# AI Agent Instructions for Mandu Project
+
+이 프로젝트는 **Mandu Framework**로 구축되었습니다. AI 에이전트가 이 프로젝트를 다룰 때 아래 지침을 따라주세요.
+
+## 패키지 매니저: Bun (필수)
+
+**⚠️ 중요: 이 프로젝트는 Bun만 사용합니다. npm/yarn/pnpm을 사용하지 마세요.**
+
+```bash
+# ✅ 올바른 명령어
+bun install              # 의존성 설치
+bun add <package>        # 패키지 추가
+bun remove <package>     # 패키지 제거
+bun run dev              # 개발 서버 시작
+bun run build            # 프로덕션 빌드
+bun test                 # 테스트 실행
+
+# ❌ 사용 금지
+npm install / yarn install / pnpm install
+```
+
+## 프로젝트 구조
+
+```
+├── app/                  # FS 기반 라우팅 (페이지, API)
+│   ├── page.tsx         # / 라우트
+│   ├── layout.tsx       # 루트 레이아웃
+│   ├── globals.css      # Tailwind CSS (v4)
+│   └── api/             # API 라우트
+├── src/
+│   ├── client/          # 클라이언트 코드 (FSD 구조)
+│   │   ├── shared/      # 공용 UI, 유틸리티
+│   │   ├── entities/    # 엔티티 컴포넌트
+│   │   ├── features/    # 기능 컴포넌트
+│   │   └── widgets/     # 위젯/Island 컴포넌트
+│   ├── server/          # 서버 코드 (Clean Architecture)
+│   │   ├── domain/      # 도메인 모델
+│   │   ├── application/ # 비즈니스 로직
+│   │   └── infra/       # 인프라/DB
+│   └── shared/          # 클라이언트-서버 공유 코드
+│       ├── contracts/   # API 계약 타입
+│       └── types/       # 공용 타입
+└── mandu.config.ts      # Mandu 설정 (선택)
+```
+
+## 주요 규칙
+
+### 1. Island 컴포넌트
+클라이언트 상호작용이 필요한 컴포넌트는 `*.island.tsx`로 명명:
+```tsx
+// src/client/widgets/counter/Counter.island.tsx
+"use client";
+export function CounterIsland() { ... }
+```
+
+### 2. API 라우트
+`app/api/` 폴더에 `route.ts` 파일로 정의:
+```typescript
+// app/api/users/route.ts
+import { Mandu } from "@mandujs/core";
+export default Mandu.filling()
+  .get((ctx) => ctx.ok({ users: [] }))
+  .post(async (ctx) => { ... });
+```
+
+### 3. Tailwind CSS v4
+CSS-first 설정 사용 (`tailwind.config.ts` 없음):
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@theme {
+  --color-primary: hsl(222.2 47.4% 11.2%);
+}
+```
+
+### 4. Import Alias
+`@/` = `src/` 경로:
+```typescript
+import { Button } from "@/client/shared/ui/button";
+```
+
+## 실행 방법
+
+```bash
+bun install     # 최초 설치
+bun run dev     # 개발 서버 (http://localhost:4000)
+bun run build   # 프로덕션 빌드
+bun run guard   # 아키텍처 검증
+```
+
+## 기술 스택
+
+- **Runtime**: Bun 1.x
+- **Framework**: Mandu (React 19 + Bun native)
+- **Styling**: Tailwind CSS v4
+- **Language**: TypeScript 5.x

package/templates/realtime-chat/app/api/chat/messages/route.ts

@@ -0,0 +1,63 @@
+import { getAIAdapter } from "@/server/application/ai-adapter";
+import { appendMessage, getMessages } from "@/server/application/chat-store";
+import {
+  isChatMessagePayload,
+  type ChatHistoryResponse,
+  type ChatMessageResponse,
+} from "@/shared/contracts/chat";
+import { createRateLimiter } from "@mandujs/core/runtime/server.ts";
+
+// Rate limiter: 1분당 10개 메시지로 제한
+const limiter = createRateLimiter({ max: 10, windowMs: 60000 });
+
+export function GET(request: Request): Response {
+  // GET 요청은 제한을 느슨하게 (1분당 30회)
+  const getDecision = createRateLimiter({ max: 30, windowMs: 60000 }).check(request, "chat-messages-get");
+  if (!getDecision.allowed) {
+    return limiter.createResponse(getDecision);
+  }
+
+  const body: ChatHistoryResponse = { messages: getMessages() };
+  const response = Response.json(body);
+  return limiter.addHeaders(response, getDecision);
+}
+
+export async function POST(request: Request): Promise<Response> {
+  // Rate limiting 체크
+  const decision = limiter.check(request, "chat-messages-post");
+  if (!decision.allowed) {
+    return limiter.createResponse(decision);
+  }
+
+  let payload: unknown;
+
+  try {
+    payload = (await request.json()) as unknown;
+  } catch {
+    return Response.json({ error: "Invalid JSON payload" }, { status: 400 });
+  }
+
+  if (!isChatMessagePayload(payload)) {
+    return Response.json({ error: "Invalid payload" }, { status: 400 });
+  }
+
+  const user = appendMessage("user", payload.text.trim());
+  const adapter = getAIAdapter();
+
+  try {
+    const completion = await adapter.complete({
+      userText: user.text,
+      history: getMessages(),
+    });
+
+    if (completion && completion.trim().length > 0) {
+      appendMessage("assistant", completion);
+    }
+  } catch {
+    // Keep user message committed even when assistant completion fails.
+  }
+
+  const body: ChatMessageResponse = { message: user };
+  const response = Response.json(body, { status: 201 });
+  return limiter.addHeaders(response, decision);
+}

package/templates/realtime-chat/app/api/chat/stream/route.ts

@@ -0,0 +1,85 @@
+import {
+  planResumeFrom,
+  subscribeWithSnapshot,
+} from "@/server/application/chat-store";
+import type { ChatMessage, ChatStreamEvent } from "@/shared/contracts/chat";
+import { createSSEConnection } from "@mandujs/core";
+import { createRateLimiter } from "@mandujs/core/runtime/server.ts";
+
+// Rate limiter: 1분당 5개 연결로 제한 (SSE는 장시간 유지되므로 보수적으로 설정)
+const limiter = createRateLimiter({ max: 5, windowMs: 60000 });
+
+function getLastEventId(request: Request): string | null {
+  const fromHeader = request.headers.get("last-event-id");
+  if (fromHeader && fromHeader.trim()) return fromHeader.trim();
+
+  const url = new URL(request.url);
+  const fromQuery = url.searchParams.get("lastEventId");
+  if (fromQuery && fromQuery.trim()) return fromQuery.trim();
+
+  return null;
+}
+
+export function GET(request: Request): Response {
+  // Rate limiting 체크
+  const decision = limiter.check(request, "chat-stream");
+  if (!decision.allowed) {
+    return limiter.createResponse(decision);
+  }
+
+  const sse = createSSEConnection(request.signal);
+  const lastEventId = getLastEventId(request);
+
+  const subscribeToLiveMessages = () => {
+    const subscription = subscribeWithSnapshot((event) => {
+      const streamEvent: ChatStreamEvent = {
+        type: "message",
+        data: event.message,
+      };
+      sse.send(streamEvent, { id: event.eventId });
+    });
+
+    return subscription;
+  };
+
+  const resume = planResumeFrom(lastEventId);
+
+  if (resume.mode === "catch-up") {
+    for (const event of resume.events) {
+      const streamEvent: ChatStreamEvent = {
+        type: "message",
+        data: event.message,
+      };
+      sse.send(streamEvent, { id: event.eventId });
+    }
+
+    const liveSubscription = subscribeToLiveMessages();
+    const unsubscribe = liveSubscription.commit();
+    sse.onClose(() => unsubscribe());
+  } else {
+    const snapshotSubscription = subscribeToLiveMessages();
+
+    const snapshot: ChatStreamEvent = {
+      type: "snapshot",
+      data: snapshotSubscription.snapshot,
+    };
+    sse.send(snapshot);
+
+    const unsubscribe = snapshotSubscription.commit();
+    sse.onClose(() => unsubscribe());
+  }
+
+  const interval = setInterval(() => {
+    const heartbeat: ChatStreamEvent = {
+      type: "heartbeat",
+      data: { ts: new Date().toISOString() },
+    };
+    sse.send(heartbeat);
+  }, 15000);
+
+  sse.onClose(() => {
+    clearInterval(interval);
+  });
+
+  return sse.response;
+}

package/templates/realtime-chat/app/api/health/route.ts

@@ -0,0 +1,13 @@
+/**
+ * Health Check API
+ *
+ * GET /api/health
+ */
+
+export function GET() {
+  return Response.json({
+    status: "ok",
+    timestamp: new Date().toISOString(),
+    framework: "Mandu",
+  });
+}

package/templates/realtime-chat/app/globals.css

@@ -0,0 +1,49 @@
+@import "tailwindcss";
+
+/*
+ * Tailwind CSS v4 - CSS-first Configuration
+ * https://tailwindcss.com/docs/v4
+ */
+
+@theme {
+  /* Colors - shadcn/ui compatible */
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(222.2 84% 4.9%);
+  --color-card: hsl(0 0% 100%);
+  --color-card-foreground: hsl(222.2 84% 4.9%);
+  --color-popover: hsl(0 0% 100%);
+  --color-popover-foreground: hsl(222.2 84% 4.9%);
+  --color-primary: hsl(222.2 47.4% 11.2%);
+  --color-primary-foreground: hsl(210 40% 98%);
+  --color-secondary: hsl(210 40% 96.1%);
+  --color-secondary-foreground: hsl(222.2 47.4% 11.2%);
+  --color-muted: hsl(210 40% 96.1%);
+  --color-muted-foreground: hsl(215.4 16.3% 46.9%);
+  --color-accent: hsl(210 40% 96.1%);
+  --color-accent-foreground: hsl(222.2 47.4% 11.2%);
+  --color-destructive: hsl(0 84.2% 60.2%);
+  --color-destructive-foreground: hsl(210 40% 98%);
+  --color-border: hsl(214.3 31.8% 91.4%);
+  --color-input: hsl(214.3 31.8% 91.4%);
+  --color-ring: hsl(222.2 84% 4.9%);
+
+  /* Radius */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+
+  /* Fonts */
+  --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
+}
+
+/* Base styles */
+* {
+  border-color: var(--color-border);
+}
+
+body {
+  background-color: var(--color-background);
+  color: var(--color-foreground);
+  font-family: var(--font-sans);
+}

package/templates/realtime-chat/app/layout.tsx

@@ -0,0 +1,27 @@
+/**
+ * Root Layout
+ *
+ * 모든 페이지의 공통 레이아웃
+ * globals.css를 여기서 임포트
+ */
+
+import "./globals.css";
+
+interface RootLayoutProps {
+  children: React.ReactNode;
+}
+
+export default function RootLayout({ children }: RootLayoutProps) {
+  return (
+    <html lang="ko">
+      <head>
+        <meta charSet="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>{{PROJECT_NAME}}</title>
+      </head>
+      <body className="min-h-screen bg-background font-sans antialiased">
+        {children}
+      </body>
+    </html>
+  );
+}

package/templates/realtime-chat/app/page.tsx

@@ -0,0 +1,16 @@
+import { RealtimeChatStarter } from "@/client/features/chat/realtime-chat-starter.client";
+
+export default function HomePage() {
+  return (
+    <main className="mx-auto flex min-h-screen w-full max-w-3xl flex-col p-6">
+      <header className="mb-6">
+        <h1 className="text-3xl font-bold">🥟 Mandu Realtime Chat Starter</h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          Official starter template with typed client hook, message API, and SSE stream.
+        </p>
+      </header>
+
+      <RealtimeChatStarter />
+    </main>
+  );
+}