@mandujs/cli 0.15.1 → 0.15.2

package/templates/realtime-chat/src/client/features/chat/chat-api.ts

@@ -0,0 +1,177 @@
+import type {
+  ChatHistoryResponse,
+  ChatMessagePayload,
+  ChatMessageResponse,
+  ChatStreamEvent,
+} from "@/shared/contracts/chat";
+
+const API_BASE = "/api/chat";
+
+export type ChatStreamConnectionState =
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "failed"
+  | "closed";
+
+interface ChatStreamOptions {
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  jitterRatio?: number;
+  random?: () => number;
+  eventSourceFactory?: (url: string) => EventSource;
+  onConnectionStateChange?: (state: ChatStreamConnectionState) => void;
+}
+
+const DEFAULT_STREAM_OPTIONS: Required<Omit<ChatStreamOptions, "eventSourceFactory" | "onConnectionStateChange">> = {
+  maxRetries: 8,
+  baseDelayMs: 500,
+  maxDelayMs: 10_000,
+  jitterRatio: 0.25,
+  random: Math.random,
+};
+
+export async function sendChatMessage(payload: ChatMessagePayload): Promise<ChatMessageResponse> {
+  const response = await fetch(`${API_BASE}/messages`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to send message: ${response.status}`);
+  }
+
+  return response.json() as Promise<ChatMessageResponse>;
+}
+
+export async function fetchChatHistory(): Promise<ChatHistoryResponse> {
+  const response = await fetch(`${API_BASE}/messages`);
+  if (!response.ok) {
+    throw new Error(`Failed to load history: ${response.status}`);
+  }
+
+  return response.json() as Promise<ChatHistoryResponse>;
+}
+
+function toReconnectDelayMs(attempt: number, options: Required<Omit<ChatStreamOptions, "eventSourceFactory" | "onConnectionStateChange">>): number {
+  const exponentialDelay = Math.min(options.maxDelayMs, options.baseDelayMs * 2 ** attempt);
+  const jitterRange = exponentialDelay * options.jitterRatio;
+  const jitter = (options.random() * 2 - 1) * jitterRange;
+  return Math.max(0, Math.round(exponentialDelay + jitter));
+}
+
+export function openChatStream(
+  onEvent: (event: ChatStreamEvent) => void,
+  streamOptions: ChatStreamOptions = {},
+): () => void {
+  const options: Required<Omit<ChatStreamOptions, "eventSourceFactory" | "onConnectionStateChange">> = {
+    maxRetries: streamOptions.maxRetries ?? DEFAULT_STREAM_OPTIONS.maxRetries,
+    baseDelayMs: streamOptions.baseDelayMs ?? DEFAULT_STREAM_OPTIONS.baseDelayMs,
+    maxDelayMs: streamOptions.maxDelayMs ?? DEFAULT_STREAM_OPTIONS.maxDelayMs,
+    jitterRatio: streamOptions.jitterRatio ?? DEFAULT_STREAM_OPTIONS.jitterRatio,
+    random: streamOptions.random ?? DEFAULT_STREAM_OPTIONS.random,
+  };
+  const createSource = streamOptions.eventSourceFactory ?? ((url: string) => new EventSource(url));
+
+  let source: EventSource | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let reconnectAttempts = 0;
+  let isDisposed = false;
+
+  const setConnectionState = (state: ChatStreamConnectionState) => {
+    streamOptions.onConnectionStateChange?.(state);
+  };
+
+  const clearReconnectTimer = () => {
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  };
+
+  const closeSource = () => {
+    if (!source) {
+      return;
+    }
+
+    source.onopen = null;
+    source.onmessage = null;
+    source.onerror = null;
+    source.close();
+    source = null;
+  };
+
+  const scheduleReconnect = () => {
+    if (isDisposed || reconnectTimer) {
+      return;
+    }
+
+    if (reconnectAttempts >= options.maxRetries) {
+      closeSource();
+      setConnectionState("failed");
+      return;
+    }
+
+    setConnectionState("reconnecting");
+    const delayMs = toReconnectDelayMs(reconnectAttempts, options);
+    reconnectAttempts += 1;
+
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, delayMs);
+  };
+
+  const connect = () => {
+    if (isDisposed) {
+      return;
+    }
+
+    setConnectionState("connecting");
+    closeSource();
+    const currentSource = createSource(`${API_BASE}/stream`);
+    source = currentSource;
+
+    currentSource.onopen = () => {
+      if (source !== currentSource || isDisposed) {
+        return;
+      }
+
+      reconnectAttempts = 0;
+      setConnectionState("connected");
+    };
+
+    currentSource.onmessage = (event) => {
+      if (source !== currentSource || isDisposed) {
+        return;
+      }
+
+      try {
+        const parsed = JSON.parse(event.data) as ChatStreamEvent;
+        onEvent(parsed);
+      } catch {
+        // Ignore malformed SSE payloads.
+      }
+    };
+
+    currentSource.onerror = () => {
+      if (source !== currentSource || isDisposed) {
+        return;
+      }
+
+      closeSource();
+      scheduleReconnect();
+    };
+  };
+
+  connect();
+
+  return () => {
+    isDisposed = true;
+    clearReconnectTimer();
+    closeSource();
+    setConnectionState("closed");
+  };
+}

package/templates/realtime-chat/src/client/features/chat/realtime-chat-starter.client.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import { FormEvent, useMemo, useState } from "react";
+import { Button, Input } from "@/client/shared/ui";
+import { useRealtimeChat } from "./use-realtime-chat";
+
+export function RealtimeChatStarter() {
+  const { messages, send, canSend, sending, connectionState } = useRealtimeChat();
+  const [text, setText] = useState("");
+  const messagesWithTime = useMemo(
+    () =>
+      messages.map((message) => ({
+        ...message,
+        displayTime: new Date(message.createdAt).toLocaleTimeString(),
+      })),
+    [messages],
+  );
+
+  const onSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const current = text;
+    setText("");
+    await send(current);
+  };
+
+  const showConnectionWarning = connectionState === "reconnecting" || connectionState === "failed";
+
+  return (
+    <section className="flex h-[70vh] flex-col rounded-xl border bg-card" aria-label="Realtime chat">
+      {showConnectionWarning ? (
+        <div className="border-b border-amber-300 bg-amber-50 px-4 py-2 text-xs text-amber-900">
+          {connectionState === "failed"
+            ? "Live updates disconnected. Please refresh to reconnect."
+            : "Live updates are reconnecting..."}
+        </div>
+      ) : null}
+
+      <div
+        className="flex-1 space-y-3 overflow-y-auto p-4"
+        role="log"
+        aria-live="polite"
+        aria-label="Chat messages"
+        aria-relevant="additions text"
+      >
+        {messages.length === 0 ? (
+          <p className="text-sm text-muted-foreground" role="status">
+            No messages yet. Start chatting.
+          </p>
+        ) : (
+          messagesWithTime.map((message) => (
+            <div
+              key={message.id}
+              className={`max-w-[80%] rounded-lg px-3 py-2 text-sm ${
+                message.role === "user"
+                  ? "ml-auto bg-primary text-primary-foreground"
+                  : "bg-muted"
+              }`}
+            >
+              <div>{message.text}</div>
+              <div className="mt-1 text-[10px] opacity-70">{message.displayTime}</div>
+            </div>
+          ))
+        )}
+      </div>
+
+      <form onSubmit={onSubmit} className="flex gap-2 border-t p-3" aria-label="Send chat message">
+        <Input
+          value={text}
+          onChange={(e) => setText(e.target.value)}
+          placeholder="Type your message..."
+          className="flex-1"
+          maxLength={500}
+          aria-label="Chat message input"
+          aria-describedby="chat-input-description"
+        />
+        <span id="chat-input-description" className="sr-only">
+          Press Enter to send your message.
+        </span>
+        <Button
+          type="submit"
+          aria-label="Send message"
+          disabled={!canSend || text.trim().length === 0}
+        >
+          {sending ? "Sending..." : "Send"}
+        </Button>
+      </form>
+    </section>
+  );
+}

package/templates/realtime-chat/src/client/features/chat/use-realtime-chat.ts

@@ -0,0 +1,73 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type { ChatMessage } from "@/shared/contracts/chat";
+import {
+  fetchChatHistory,
+  openChatStream,
+  sendChatMessage,
+  type ChatStreamConnectionState,
+} from "./chat-api";
+
+export function useRealtimeChat() {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [sending, setSending] = useState(false);
+  const [connectionState, setConnectionState] = useState<ChatStreamConnectionState>("connecting");
+
+  useEffect(() => {
+    let mounted = true;
+
+    fetchChatHistory()
+      .then((res) => {
+        if (mounted) setMessages(res.messages);
+      })
+      .catch(() => {
+        // starter template keeps errors simple
+      });
+
+    const close = openChatStream((event) => {
+      if (!mounted) return;
+
+      if (event.type === "snapshot" && Array.isArray(event.data)) {
+        setMessages(event.data);
+      }
+
+      if (event.type === "message" && !Array.isArray(event.data)) {
+        setMessages((prev) => [...prev, event.data]);
+      }
+    }, {
+      onConnectionStateChange: (state) => {
+        if (mounted) {
+          setConnectionState(state);
+        }
+      },
+    });
+
+    return () => {
+      mounted = false;
+      close();
+    };
+  }, []);
+
+  const send = useCallback(async (text: string) => {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+
+    setSending(true);
+    try {
+      await sendChatMessage({ text: trimmed });
+    } finally {
+      setSending(false);
+    }
+  }, []);
+
+  const canSend = useMemo(() => !sending, [sending]);
+
+  return {
+    messages,
+    send,
+    sending,
+    canSend,
+    connectionState,
+  };
+}

package/templates/realtime-chat/src/client/features/index.ts

@@ -0,0 +1 @@
+export * from "./chat/use-realtime-chat";

package/templates/realtime-chat/src/client/pages/index.ts

@@ -0,0 +1 @@
+export {};

package/templates/realtime-chat/src/client/shared/index.ts

@@ -0,0 +1 @@
+export {};

package/templates/realtime-chat/src/client/shared/lib/utils.ts

@@ -0,0 +1,16 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * cn - Tailwind CSS 클래스 병합 유틸리티
+ *
+ * clsx로 조건부 클래스를 결합하고
+ * tailwind-merge로 충돌하는 클래스를 스마트하게 병합
+ *
+ * @example
+ * cn("px-4 py-2", isActive && "bg-primary", className)
+ * cn("text-sm", "text-lg") // → "text-lg" (충돌 해결)
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/realtime-chat/src/client/shared/ui/button.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/client/shared/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+);
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return (
+      <Comp
+        className={cn(buttonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Button.displayName = "Button";
+
+export { Button, buttonVariants };

package/templates/realtime-chat/src/client/shared/ui/card.tsx

@@ -0,0 +1,78 @@
+import * as React from "react";
+import { cn } from "@/client/shared/lib/utils";
+
+const Card = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      "rounded-lg border bg-card text-card-foreground shadow-sm",
+      className
+    )}
+    {...props}
+  />
+));
+Card.displayName = "Card";
+
+const CardHeader = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex flex-col space-y-1.5 p-6", className)}
+    {...props}
+  />
+));
+CardHeader.displayName = "CardHeader";
+
+const CardTitle = React.forwardRef<
+  HTMLHeadingElement,
+  React.HTMLAttributes<HTMLHeadingElement>
+>(({ className, ...props }, ref) => (
+  <h3
+    ref={ref}
+    className={cn(
+      "text-2xl font-semibold leading-none tracking-tight",
+      className
+    )}
+    {...props}
+  />
+));
+CardTitle.displayName = "CardTitle";
+
+const CardDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn("text-sm text-muted-foreground", className)}
+    {...props}
+  />
+));
+CardDescription.displayName = "CardDescription";
+
+const CardContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn("p-6 pt-0", className)} {...props} />
+));
+CardContent.displayName = "CardContent";
+
+const CardFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("flex items-center p-6 pt-0", className)}
+    {...props}
+  />
+));
+CardFooter.displayName = "CardFooter";
+
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent };

package/templates/realtime-chat/src/client/shared/ui/index.ts

@@ -0,0 +1,21 @@
+/**
+ * UI Components
+ *
+ * shadcn/ui 스타일의 컴포넌트 라이브러리
+ * Radix UI primitives + Tailwind CSS + cva 기반
+ */
+
+export { Button, buttonVariants } from "./button";
+export type { ButtonProps } from "./button";
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardDescription,
+  CardContent,
+} from "./card";
+
+export { Input } from "./input";
+export type { InputProps } from "./input";

package/templates/realtime-chat/src/client/shared/ui/input.tsx

@@ -0,0 +1,28 @@
+import * as React from "react";
+import { cn } from "@/client/shared/lib/utils";
+
+export interface InputProps
+  extends React.InputHTMLAttributes<HTMLInputElement> {}
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ 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
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Input.displayName = "Input";
+
+export { Input };

package/templates/realtime-chat/src/client/widgets/index.ts

@@ -0,0 +1 @@
+export {};

package/templates/realtime-chat/src/server/api/index.ts

@@ -0,0 +1 @@
+export {};

package/templates/realtime-chat/src/server/application/ai-adapter.ts

@@ -0,0 +1,24 @@
+import type { ChatMessage } from "@/shared/contracts/chat";
+
+export interface AIChatAdapter {
+  complete(input: {
+    userText: string;
+    history: ChatMessage[];
+  }): Promise<string | null>;
+}
+
+class EchoAdapter implements AIChatAdapter {
+  async complete(input: { userText: string }): Promise<string> {
+    return `Echo: ${input.userText}`;
+  }
+}
+
+let adapter: AIChatAdapter = new EchoAdapter();
+
+export function getAIAdapter(): AIChatAdapter {
+  return adapter;
+}
+
+export function setAIAdapter(next: AIChatAdapter): void {
+  adapter = next;
+}

package/templates/realtime-chat/src/server/application/chat-store.ts

@@ -0,0 +1,88 @@
+import type { ChatMessage } from "@/shared/contracts/chat";
+
+type ChatListener = (message: ChatMessage) => void;
+
+type SubscriptionSnapshot = {
+  snapshot: ChatMessage[];
+  commit: () => () => void;
+};
+
+const listeners = new Set<ChatListener>();
+const messages: ChatMessage[] = [];
+const MAX_HISTORY_MESSAGES = 200;
+let storeVersion = 0;
+let testHookBeforeSubscribeCommit: (() => void) | undefined;
+
+function createMessage(role: ChatMessage["role"], text: string): ChatMessage {
+  return {
+    id: crypto.randomUUID(),
+    role,
+    text,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+export function getMessages(): ChatMessage[] {
+  return [...messages];
+}
+
+export function appendMessage(role: ChatMessage["role"], text: string): ChatMessage {
+  const message = createMessage(role, text);
+  messages.push(message);
+
+  if (messages.length > MAX_HISTORY_MESSAGES) {
+    messages.splice(0, messages.length - MAX_HISTORY_MESSAGES);
+  }
+
+  storeVersion += 1;
+
+  for (const listener of listeners) {
+    try {
+      listener(message);
+    } catch {
+      // Ignore listener errors so one broken subscriber does not stop fan-out.
+    }
+  }
+
+  return message;
+}
+
+export function subscribe(listener: ChatListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function subscribeWithSnapshot(listener: ChatListener): SubscriptionSnapshot {
+  // Optimistic lock-free retry: snapshot과 subscribe 사이에 write가 끼면 재시도
+  // => snapshot-subscription 경계에서 메시지 유실 방지
+  // commit()은 snapshot 전송 후 호출하여 listener 활성화 (이벤트 순서 보장)
+  for (;;) {
+    const beforeVersion = storeVersion;
+    const snapshot = [...messages];
+
+    testHookBeforeSubscribeCommit?.();
+
+    if (beforeVersion === storeVersion) {
+      return {
+        snapshot,
+        commit: () => {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+      };
+    }
+  }
+}
+
+export function __resetChatStoreForTests(): void {
+  messages.length = 0;
+  listeners.clear();
+  storeVersion = 0;
+  testHookBeforeSubscribeCommit = undefined;
+}
+
+export function __setSubscribeCommitHookForTests(hook?: () => void): void {
+  testHookBeforeSubscribeCommit = hook;
+}
+
+export { MAX_HISTORY_MESSAGES };

package/templates/realtime-chat/src/server/application/index.ts

@@ -0,0 +1 @@
+export {};

package/templates/realtime-chat/src/server/core/index.ts

@@ -0,0 +1 @@
+export {};

package/templates/realtime-chat/src/server/domain/index.ts

@@ -0,0 +1 @@
+export {};

package/templates/realtime-chat/src/server/infra/index.ts

@@ -0,0 +1 @@
+export {};