@mandujs/cli 0.15.2 → 0.15.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/cli",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "description": "Agent-Native Fullstack Framework - 에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS",
   "type": "module",
   "main": "./src/main.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.13.1",
+    "@mandujs/core": "^0.13.2",
     "cfonts": "^3.3.0"
   },
   "engines": {

package/src/util/lockfile.ts

@@ -8,6 +8,54 @@ import {
   type LockfileValidationResult,
 } from "@mandujs/core";
 
+/**
+ * Lockfile command templates for consistent messaging
+ */
+export const LOCKFILE_COMMANDS = {
+  update: "mandu lock",
+  diff: "mandu lock --diff",
+  safeDev: "mandu lock && mandu dev --watch",
+} as const;
+
+/**
+ * Formatted lockfile guidance lines with alternative commands
+ */
+export const LOCKFILE_GUIDE_LINES = {
+  update: `${LOCKFILE_COMMANDS.update}  (or bunx mandu lock)`,
+  diff: `${LOCKFILE_COMMANDS.diff}  (or bunx mandu lock --diff)`,
+  safeDev: `${LOCKFILE_COMMANDS.safeDev}  (or bun run dev:safe)`,
+} as const;
+
+/**
+ * Returns formatted lockfile guidance lines for display
+ *
+ * @returns Array of guidance messages with Korean labels
+ *
+ * @example
+ * ```typescript
+ * const lines = getLockfileGuidanceLines();
+ * lines.forEach(line => console.log(`   ↳ ${line}`));
+ * // Output:
+ * //    ↳ lock 갱신: mandu lock  (or bunx mandu lock)
+ * //    ↳ 변경 확인: mandu lock --diff  (or bunx mandu lock --diff)
+ * //    ↳ 안정 실행: mandu lock && mandu dev --watch  (or bun run dev:safe)
+ * ```
+ */
+export function getLockfileGuidanceLines(): string[] {
+  return [
+    `lock 갱신: ${LOCKFILE_GUIDE_LINES.update}`,
+    `변경 확인: ${LOCKFILE_GUIDE_LINES.diff}`,
+    `안정 실행: ${LOCKFILE_GUIDE_LINES.safeDev}`,
+  ];
+}
+
+/**
+ * Validates runtime lockfile against current config
+ *
+ * @param config - Mandu configuration object
+ * @param rootDir - Project root directory
+ * @returns Validation result with lockfile, action, and bypass status
+ */
 export async function validateRuntimeLockfile(config: Record<string, unknown>, rootDir: string) {
   const lockfile = await readLockfile(rootDir);
 
@@ -30,17 +78,22 @@ export async function validateRuntimeLockfile(config: Record<string, unknown>, r
   return { lockfile, lockResult, action, bypassed };
 }
 
+/**
+ * Handles blocked server start due to lockfile mismatch
+ *
+ * Exits process with error code 1 if action is "block"
+ *
+ * @param action - Policy action from lockfile validation
+ * @param lockResult - Validation result with details
+ */
 export function handleBlockedLockfile(action: "pass" | "warn" | "error" | "block", lockResult: LockfileValidationResult | null): void {
   if (action !== "block") return;
 
+  const guidance = getLockfileGuidanceLines();
   console.error("🛑 서버 시작 차단: Lockfile 불일치");
-  console.error("   설정이 변경되었습니다. 의도한 변경이라면 아래 중 하나를 실행하세요:");
-  console.error("   $ mandu lock");
-  console.error("   $ bunx mandu lock");
-  console.error("");
-  console.error("   변경 사항 확인:");
-  console.error("   $ mandu lock --diff");
-  console.error("   $ bunx mandu lock --diff");
+  console.error("   설정이 변경되었습니다. 의도한 변경이라면 아래를 실행하세요:");
+  console.error(`   ↳ ${guidance[0]}`);
+  console.error(`   ↳ ${guidance[1]}`);
   if (lockResult) {
     console.error("");
     console.error(formatValidationResult(lockResult));
@@ -48,6 +101,14 @@ export function handleBlockedLockfile(action: "pass" | "warn" | "error" | "block
   process.exit(1);
 }
 
+/**
+ * Prints runtime lockfile validation status
+ *
+ * @param action - Policy action from lockfile validation
+ * @param bypassed - Whether validation was bypassed
+ * @param lockfile - Lockfile data (null if not found)
+ * @param lockResult - Validation result with hash and validity
+ */
 export function printRuntimeLockfileStatus(
   action: "pass" | "warn" | "error" | "block",
   bypassed: boolean,
@@ -56,11 +117,12 @@ export function printRuntimeLockfileStatus(
 ): void {
   if (action === "warn") {
     console.log(`⚠️  ${formatPolicyAction(action, bypassed)}`);
-    console.log(`   ↳ lock 갱신: mandu lock  (or bunx mandu lock)`);
-    console.log(`   ↳ 변경 확인: mandu lock --diff  (or bunx mandu lock --diff)`);
+    for (const line of getLockfileGuidanceLines()) {
+      console.log(`   ↳ ${line}`);
+    }
   } else if (lockfile && lockResult?.valid) {
     console.log(`🔒 설정 무결성 확인됨 (${lockResult.currentHash?.slice(0, 8)})`);
   } else if (!lockfile) {
-    console.log(`💡 Lockfile 없음 - 'mandu lock' 또는 'bunx mandu lock'으로 생성 권장`);
+    console.log(`💡 Lockfile 없음 - '${LOCKFILE_COMMANDS.update}'으로 생성 권장`);
   }
 }

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

@@ -1,4 +1,7 @@
-import { subscribeWithSnapshot } from "@/server/application/chat-store";
+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";
@@ -6,6 +9,17 @@ 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");
@@ -14,22 +28,46 @@ export function GET(request: Request): Response {
   }
 
   const sse = createSSEConnection(request.signal);
+  const lastEventId = getLastEventId(request);
 
-  const subscription = subscribeWithSnapshot((message: ChatMessage) => {
-    const event: ChatStreamEvent = {
-      type: "message",
-      data: message,
-    };
-    sse.send(event);
-  });
+  const subscribeToLiveMessages = () => {
+    const subscription = subscribeWithSnapshot((event) => {
+      const streamEvent: ChatStreamEvent = {
+        type: "message",
+        data: event.message,
+      };
+      sse.send(streamEvent, { id: event.eventId });
+    });
 
-  const snapshot: ChatStreamEvent = {
-    type: "snapshot",
-    data: subscription.snapshot,
+    return subscription;
   };
-  sse.send(snapshot);
 
-  const unsubscribe = subscription.commit();
+  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 = {
@@ -41,7 +79,6 @@ export function GET(request: Request): Response {
 
   sse.onClose(() => {
     clearInterval(interval);
-    unsubscribe();
   });
 
   return sse.response;

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

@@ -1,5 +1,6 @@
 import type {
   ChatHistoryResponse,
+  ChatMessage,
   ChatMessagePayload,
   ChatMessageResponse,
   ChatStreamEvent,
@@ -24,7 +25,9 @@ interface ChatStreamOptions {
   onConnectionStateChange?: (state: ChatStreamConnectionState) => void;
 }
 
-const DEFAULT_STREAM_OPTIONS: Required<Omit<ChatStreamOptions, "eventSourceFactory" | "onConnectionStateChange">> = {
+type ReconnectOptions = Required<Omit<ChatStreamOptions, "eventSourceFactory" | "onConnectionStateChange">>;
+
+const DEFAULT_STREAM_OPTIONS: ReconnectOptions = {
   maxRetries: 8,
   baseDelayMs: 500,
   maxDelayMs: 10_000,
@@ -55,18 +58,36 @@ export async function fetchChatHistory(): Promise<ChatHistoryResponse> {
   return response.json() as Promise<ChatHistoryResponse>;
 }
 
-function toReconnectDelayMs(attempt: number, options: Required<Omit<ChatStreamOptions, "eventSourceFactory" | "onConnectionStateChange">>): number {
+export function mergeChatMessages(base: ChatMessage[], incoming: ChatMessage[]): ChatMessage[] {
+  const merged = new Map<string, ChatMessage>();
+
+  for (const message of base) {
+    merged.set(message.id, message);
+  }
+
+  for (const message of incoming) {
+    merged.set(message.id, message);
+  }
+
+  return [...merged.values()].sort((a, b) => {
+    const byTime = a.createdAt.localeCompare(b.createdAt);
+    if (byTime !== 0) return byTime;
+    return a.id.localeCompare(b.id);
+  });
+}
+
+function toReconnectDelayMs(attempt: number, options: ReconnectOptions): 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));
+  return Math.max(0, Math.min(options.maxDelayMs, Math.round(exponentialDelay + jitter)));
 }
 
 export function openChatStream(
   onEvent: (event: ChatStreamEvent) => void,
   streamOptions: ChatStreamOptions = {},
 ): () => void {
-  const options: Required<Omit<ChatStreamOptions, "eventSourceFactory" | "onConnectionStateChange">> = {
+  const options: ReconnectOptions = {
     maxRetries: streamOptions.maxRetries ?? DEFAULT_STREAM_OPTIONS.maxRetries,
     baseDelayMs: streamOptions.baseDelayMs ?? DEFAULT_STREAM_OPTIONS.baseDelayMs,
     maxDelayMs: streamOptions.maxDelayMs ?? DEFAULT_STREAM_OPTIONS.maxDelayMs,
@@ -79,6 +100,7 @@ export function openChatStream(
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   let reconnectAttempts = 0;
   let isDisposed = false;
+  let lastEventId: string | null = null;
 
   const setConnectionState = (state: ChatStreamConnectionState) => {
     streamOptions.onConnectionStateChange?.(state);
@@ -124,6 +146,11 @@ export function openChatStream(
     }, delayMs);
   };
 
+  const toStreamUrl = () => {
+    if (!lastEventId) return `${API_BASE}/stream`;
+    return `${API_BASE}/stream?lastEventId=${encodeURIComponent(lastEventId)}`;
+  };
+
   const connect = () => {
     if (isDisposed) {
       return;
@@ -131,7 +158,7 @@ export function openChatStream(
 
     setConnectionState("connecting");
     closeSource();
-    const currentSource = createSource(`${API_BASE}/stream`);
+    const currentSource = createSource(toStreamUrl());
     source = currentSource;
 
     currentSource.onopen = () => {
@@ -148,6 +175,11 @@ export function openChatStream(
         return;
       }
 
+      const maybeLastEventId = (event as MessageEvent).lastEventId;
+      if (typeof maybeLastEventId === "string" && maybeLastEventId.trim().length > 0) {
+        lastEventId = maybeLastEventId.trim();
+      }
+
       try {
         const parsed = JSON.parse(event.data) as ChatStreamEvent;
         onEvent(parsed);

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

@@ -3,11 +3,11 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import type { ChatMessage } from "@/shared/contracts/chat";
 import {
-  fetchChatHistory,
+  mergeChatMessages,
   openChatStream,
   sendChatMessage,
   type ChatStreamConnectionState,
-} from "./chat-api";
+} from "@/client/features/chat/chat-api";
 
 export function useRealtimeChat() {
   const [messages, setMessages] = useState<ChatMessage[]>([]);
@@ -17,14 +17,6 @@ export function useRealtimeChat() {
   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;
 
@@ -33,7 +25,7 @@ export function useRealtimeChat() {
       }
 
       if (event.type === "message" && !Array.isArray(event.data)) {
-        setMessages((prev) => [...prev, event.data]);
+        setMessages((prev) => mergeChatMessages(prev, [event.data]));
       }
     }, {
       onConnectionStateChange: (state) => {

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

@@ -1,16 +1,29 @@
 import type { ChatMessage } from "@/shared/contracts/chat";
 
-type ChatListener = (message: ChatMessage) => void;
+type ChatListener = (event: ChatMessageEvent) => void;
+
+export interface ChatMessageEvent {
+  eventId: string;
+  message: ChatMessage;
+}
 
 type SubscriptionSnapshot = {
   snapshot: ChatMessage[];
   commit: () => () => void;
 };
 
+export interface ResumePlan {
+  mode: "catch-up" | "snapshot";
+  events: ChatMessageEvent[];
+}
+
 const listeners = new Set<ChatListener>();
 const messages: ChatMessage[] = [];
 const MAX_HISTORY_MESSAGES = 200;
+const MAX_CATCH_UP_EVENTS = 500;
 let storeVersion = 0;
+let streamEventSeq = 0;
+const catchUpEvents: ChatMessageEvent[] = [];
 let testHookBeforeSubscribeCommit: (() => void) | undefined;
 
 function createMessage(role: ChatMessage["role"], text: string): ChatMessage {
@@ -22,6 +35,25 @@ function createMessage(role: ChatMessage["role"], text: string): ChatMessage {
   };
 }
 
+function createEventId(nextSeq: number): string {
+  return `msg-${nextSeq}`;
+}
+
+function parseEventSeq(eventId: string | null | undefined): number | null {
+  if (!eventId) return null;
+  const match = /^msg-(\d+)$/.exec(eventId);
+  if (!match) return null;
+  const parsed = Number.parseInt(match[1]!, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function pushCatchUpEvent(event: ChatMessageEvent): void {
+  catchUpEvents.push(event);
+  if (catchUpEvents.length > MAX_CATCH_UP_EVENTS) {
+    catchUpEvents.splice(0, catchUpEvents.length - MAX_CATCH_UP_EVENTS);
+  }
+}
+
 export function getMessages(): ChatMessage[] {
   return [...messages];
 }
@@ -35,10 +67,18 @@ export function appendMessage(role: ChatMessage["role"], text: string): ChatMess
   }
 
   storeVersion += 1;
+  streamEventSeq += 1;
+
+  const event: ChatMessageEvent = {
+    eventId: createEventId(streamEventSeq),
+    message,
+  };
+
+  pushCatchUpEvent(event);
 
   for (const listener of listeners) {
     try {
-      listener(message);
+      listener(event);
     } catch {
       // Ignore listener errors so one broken subscriber does not stop fan-out.
     }
@@ -74,10 +114,40 @@ export function subscribeWithSnapshot(listener: ChatListener): SubscriptionSnaps
   }
 }
 
+export function planResumeFrom(lastEventId: string | null | undefined): ResumePlan {
+  const parsedSeq = parseEventSeq(lastEventId);
+  if (parsedSeq === null) {
+    return { mode: "snapshot", events: [] };
+  }
+
+  if (parsedSeq === streamEventSeq) {
+    return { mode: "catch-up", events: [] };
+  }
+
+  const firstAvailable = catchUpEvents[0];
+  if (!firstAvailable) {
+    return { mode: "snapshot", events: [] };
+  }
+
+  const firstSeq = parseEventSeq(firstAvailable.eventId);
+  if (firstSeq === null || parsedSeq < firstSeq - 1 || parsedSeq > streamEventSeq) {
+    return { mode: "snapshot", events: [] };
+  }
+
+  const events = catchUpEvents.filter((event) => {
+    const seq = parseEventSeq(event.eventId);
+    return seq !== null && seq > parsedSeq;
+  });
+
+  return { mode: "catch-up", events };
+}
+
 export function __resetChatStoreForTests(): void {
   messages.length = 0;
   listeners.clear();
   storeVersion = 0;
+  streamEventSeq = 0;
+  catchUpEvents.length = 0;
   testHookBeforeSubscribeCommit = undefined;
 }
 
@@ -85,4 +155,4 @@ export function __setSubscribeCommitHookForTests(hook?: () => void): void {
   testHookBeforeSubscribeCommit = hook;
 }
 
-export { MAX_HISTORY_MESSAGES };
+export { MAX_HISTORY_MESSAGES, MAX_CATCH_UP_EVENTS };

package/templates/realtime-chat/tests/chat-api.sse.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "bun:test";
-import { openChatStream } from "@/client/features/chat/chat-api";
+import { mergeChatMessages, openChatStream } from "@/client/features/chat/chat-api";
 import type { ChatStreamEvent } from "@/shared/contracts/chat";
 
-type MessageEventLike = { data: string };
+type MessageEventLike = { data: string; lastEventId?: string };
 
 class FakeEventSource {
   onopen: ((event: Event) => void) | null = null;
@@ -16,8 +16,8 @@ class FakeEventSource {
     this.onopen?.(new Event("open"));
   }
 
-  emitMessage(data: string) {
-    this.onmessage?.({ data });
+  emitMessage(data: string, lastEventId?: string) {
+    this.onmessage?.({ data, lastEventId });
   }
 
   emitError() {
@@ -66,6 +66,32 @@ describe("openChatStream", () => {
     stop();
   });
 
+  it("adds lastEventId cursor on reconnect for resumable SSE", async () => {
+    const sources: FakeEventSource[] = [];
+
+    const stop = openChatStream(() => {}, {
+      baseDelayMs: 5,
+      maxDelayMs: 5,
+      jitterRatio: 0,
+      maxRetries: 1,
+      eventSourceFactory: (url) => {
+        const source = new FakeEventSource(url);
+        sources.push(source);
+        return source as unknown as EventSource;
+      },
+    });
+
+    expect(sources[0]?.url).toBe("/api/chat/stream");
+
+    sources[0]?.emitMessage(JSON.stringify({ type: "message" }), "msg-42");
+    sources[0]?.emitError();
+
+    await sleep(8);
+    expect(sources[1]?.url).toBe("/api/chat/stream?lastEventId=msg-42");
+
+    stop();
+  });
+
   it("notifies connection state changes and terminal failure", async () => {
     const states: Array<"connecting" | "connected" | "reconnecting" | "failed" | "closed"> = [];
     const sources: FakeEventSource[] = [];
@@ -149,3 +175,14 @@ describe("openChatStream", () => {
     stop();
   });
 });
+
+describe("mergeChatMessages", () => {
+  it("idempotently merges duplicate messages by id", () => {
+    const a = { id: "1", role: "user", text: "hello", createdAt: "2026-02-13T00:00:00.000Z" } as const;
+    const b = { id: "2", role: "assistant", text: "world", createdAt: "2026-02-13T00:00:01.000Z" } as const;
+
+    const merged = mergeChatMessages([a, b], [b]);
+    expect(merged).toHaveLength(2);
+    expect(merged.map((m) => m.id)).toEqual(["1", "2"]);
+  });
+});

package/templates/realtime-chat/tests/chat-starter.test.ts

@@ -133,6 +133,57 @@ describe("realtime chat starter template", () => {
     }
   });
 
+  it("supports catch-up resume from lastEventId without snapshot", async () => {
+    appendMessage("user", "m1");
+    appendMessage("assistant", "m2");
+
+    const request = createTestRequest("http://localhost:3000/api/chat/stream?lastEventId=msg-1");
+    const response = getStream(request);
+
+    const reader = response.body?.getReader();
+    expect(reader).toBeDefined();
+
+    const firstChunk = await reader!.read();
+    expect(firstChunk.done).toBe(false);
+
+    const firstText = new TextDecoder().decode(firstChunk.value);
+    expect(firstText).toContain("id: msg-2");
+    expect(firstText).toContain('"type":"message"');
+    expect(firstText).toContain('"text":"m2"');
+    expect(firstText).not.toContain('"type":"snapshot"');
+
+    appendMessage("user", "m3-live");
+
+    const secondChunk = await reader!.read();
+    expect(secondChunk.done).toBe(false);
+
+    const secondText = new TextDecoder().decode(secondChunk.value);
+    expect(secondText).toContain("id: msg-3");
+    expect(secondText).toContain('"type":"message"');
+    expect(secondText).toContain('"text":"m3-live"');
+
+    await reader!.cancel();
+  });
+
+  it("falls back to snapshot when lastEventId is out of catch-up range", async () => {
+    appendMessage("user", "hello");
+
+    const request = createTestRequest("http://localhost:3000/api/chat/stream?lastEventId=msg-9999");
+    const response = getStream(request);
+
+    const reader = response.body?.getReader();
+    expect(reader).toBeDefined();
+
+    const chunk = await reader!.read();
+    expect(chunk.done).toBe(false);
+
+    const text = new TextDecoder().decode(chunk.value);
+    expect(text).toContain('"type":"snapshot"');
+    expect(text).toContain('"text":"hello"');
+
+    await reader!.cancel();
+  });
+
   it("includes essential ARIA attributes in chat UI", async () => {
     const source = await Bun.file(
       new URL("../src/client/features/chat/realtime-chat-starter.client.tsx", import.meta.url),

package/templates/realtime-chat/tests/chat-store.concurrency.test.ts

@@ -22,8 +22,8 @@ describe("chat-store concurrency", () => {
     });
 
     const seen: string[] = [];
-    const subscription = subscribeWithSnapshot((message) => {
-      seen.push(message.text);
+    const subscription = subscribeWithSnapshot((event) => {
+      seen.push(event.message.text);
     });
 
     expect(subscription.snapshot.some((message) => message.text === "racing-message")).toBe(true);