@mandujs/cli 0.15.1 → 0.15.3

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

@@ -0,0 +1,158 @@
+import type { ChatMessage } from "@/shared/contracts/chat";
+
+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 {
+  return {
+    id: crypto.randomUUID(),
+    role,
+    text,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+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];
+}
+
+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;
+  streamEventSeq += 1;
+
+  const event: ChatMessageEvent = {
+    eventId: createEventId(streamEventSeq),
+    message,
+  };
+
+  pushCatchUpEvent(event);
+
+  for (const listener of listeners) {
+    try {
+      listener(event);
+    } 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 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;
+}
+
+export function __setSubscribeCommitHookForTests(hook?: () => void): void {
+  testHookBeforeSubscribeCommit = hook;
+}
+
+export { MAX_HISTORY_MESSAGES, MAX_CATCH_UP_EVENTS };

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 {};

package/templates/realtime-chat/src/shared/contracts/chat.ts

@@ -0,0 +1,29 @@
+export interface ChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+  createdAt: string;
+}
+
+export interface ChatMessagePayload {
+  text: string;
+}
+
+export interface ChatMessageResponse {
+  message: ChatMessage;
+}
+
+export interface ChatHistoryResponse {
+  messages: ChatMessage[];
+}
+
+export interface ChatStreamEvent {
+  type: "snapshot" | "message" | "heartbeat";
+  data: ChatMessage[] | ChatMessage | { ts: string };
+}
+
+export function isChatMessagePayload(value: unknown): value is ChatMessagePayload {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<ChatMessagePayload>;
+  return typeof candidate.text === "string" && candidate.text.trim().length > 0;
+}

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

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

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

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

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

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

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

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

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

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

package/templates/realtime-chat/src/shared/utils/server/index.ts

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

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

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "bun:test";
+import { mergeChatMessages, openChatStream } from "@/client/features/chat/chat-api";
+import type { ChatStreamEvent } from "@/shared/contracts/chat";
+
+type MessageEventLike = { data: string; lastEventId?: string };
+
+class FakeEventSource {
+  onopen: ((event: Event) => void) | null = null;
+  onmessage: ((event: MessageEventLike) => void) | null = null;
+  onerror: ((event: Event) => void) | null = null;
+  closed = false;
+
+  constructor(readonly url: string) {}
+
+  emitOpen() {
+    this.onopen?.(new Event("open"));
+  }
+
+  emitMessage(data: string, lastEventId?: string) {
+    this.onmessage?.({ data, lastEventId });
+  }
+
+  emitError() {
+    this.onerror?.(new Event("error"));
+  }
+
+  close() {
+    this.closed = true;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe("openChatStream", () => {
+  it("reconnects with capped retries when stream errors", async () => {
+    const sources: FakeEventSource[] = [];
+    const stop = openChatStream(() => {}, {
+      baseDelayMs: 5,
+      maxDelayMs: 20,
+      jitterRatio: 0,
+      maxRetries: 2,
+      eventSourceFactory: (url) => {
+        const source = new FakeEventSource(url);
+        sources.push(source);
+        return source as unknown as EventSource;
+      },
+    });
+
+    expect(sources.length).toBe(1);
+    expect(sources[0]?.url).toBe("/api/chat/stream");
+
+    sources[0]?.emitError();
+    await sleep(8);
+    expect(sources.length).toBe(2);
+
+    sources[1]?.emitError();
+    await sleep(12);
+    expect(sources.length).toBe(3);
+
+    sources[2]?.emitError();
+    await sleep(25);
+    expect(sources.length).toBe(3);
+
+    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[] = [];
+
+    const stop = openChatStream(() => {}, {
+      baseDelayMs: 5,
+      maxDelayMs: 5,
+      jitterRatio: 0,
+      maxRetries: 1,
+      onConnectionStateChange: (state) => {
+        states.push(state);
+      },
+      eventSourceFactory: (url) => {
+        const source = new FakeEventSource(url);
+        sources.push(source);
+        return source as unknown as EventSource;
+      },
+    });
+
+    expect(states).toEqual(["connecting"]);
+
+    sources[0]?.emitOpen();
+    expect(states).toEqual(["connecting", "connected"]);
+
+    sources[0]?.emitError();
+    expect(states).toEqual(["connecting", "connected", "reconnecting"]);
+
+    await sleep(8);
+    expect(states).toEqual(["connecting", "connected", "reconnecting", "connecting"]);
+
+    sources[1]?.emitError();
+    expect(states).toEqual(["connecting", "connected", "reconnecting", "connecting", "failed"]);
+
+    stop();
+    expect(states).toEqual(["connecting", "connected", "reconnecting", "connecting", "failed", "closed"]);
+  });
+
+  it("cleans up source and pending reconnect timer on stop", async () => {
+    const sources: FakeEventSource[] = [];
+    const stop = openChatStream(() => {}, {
+      baseDelayMs: 20,
+      maxDelayMs: 20,
+      jitterRatio: 0,
+      maxRetries: 3,
+      eventSourceFactory: (url) => {
+        const source = new FakeEventSource(url);
+        sources.push(source);
+        return source as unknown as EventSource;
+      },
+    });
+
+    expect(sources.length).toBe(1);
+
+    sources[0]?.emitError();
+    stop();
+
+    await sleep(30);
+    expect(sources.length).toBe(1);
+    expect(sources[0]?.closed).toBe(true);
+  });
+
+  it("forwards valid payload and ignores malformed payload", () => {
+    const events: ChatStreamEvent[] = [];
+    const sources: FakeEventSource[] = [];
+
+    const stop = openChatStream((event) => {
+      events.push(event);
+    }, {
+      eventSourceFactory: (url) => {
+        const source = new FakeEventSource(url);
+        sources.push(source);
+        return source as unknown as EventSource;
+      },
+    });
+
+    sources[0]?.emitMessage("{not-json");
+    sources[0]?.emitMessage(JSON.stringify({ type: "message" }));
+
+    expect(events).toEqual([{ type: "message" }]);
+
+    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

@@ -0,0 +1,200 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import { GET as getMessages, POST as postMessage } from "../app/api/chat/messages/route";
+import { GET as getStream } from "../app/api/chat/stream/route";
+import {
+  __resetChatStoreForTests,
+  appendMessage,
+  getMessages as getStoreMessages,
+  MAX_HISTORY_MESSAGES,
+} from "../src/server/application/chat-store";
+import { getAIAdapter, setAIAdapter } from "../src/server/application/ai-adapter";
+import { createTestRequest, parseJsonResponse } from "./helpers";
+
+describe("realtime chat starter template", () => {
+  const originalAdapter = getAIAdapter();
+
+  beforeEach(() => {
+    __resetChatStoreForTests();
+    setAIAdapter(originalAdapter);
+  });
+
+  it("returns empty history by default", async () => {
+    const request = createTestRequest("http://localhost:3000/api/chat/messages");
+    const response = getMessages(request);
+    expect(response.status).toBe(200);
+
+    const json = await parseJsonResponse<{ messages: unknown[] }>(response);
+    expect(Array.isArray(json.messages)).toBe(true);
+    expect(json.messages.length).toBe(0);
+  });
+
+  it("rejects invalid message payload", async () => {
+    const request = createTestRequest("http://localhost:3000/api/chat/messages", {
+      method: "POST",
+      body: { text: "   " },
+    });
+
+    const response = await postMessage(request);
+    expect(response.status).toBe(400);
+  });
+
+  it("rejects malformed json payload", async () => {
+    const request = new Request("http://localhost:3000/api/chat/messages", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{not-valid-json",
+    });
+
+    const response = await postMessage(request);
+    expect(response.status).toBe(400);
+  });
+
+  it("accepts valid payload and appends assistant reply", async () => {
+    const request = createTestRequest("http://localhost:3000/api/chat/messages", {
+      method: "POST",
+      body: { text: "hello" },
+    });
+
+    const response = await postMessage(request);
+    expect(response.status).toBe(201);
+
+    const historyRequest = createTestRequest("http://localhost:3000/api/chat/messages");
+    const history = getMessages(historyRequest);
+    const json = await parseJsonResponse<{ messages: Array<{ role: string }> }>(history);
+
+    expect(json.messages.length).toBe(2);
+    expect(json.messages.at(-1)?.role).toBe("assistant");
+  });
+
+  it("keeps user message when adapter completion fails", async () => {
+    setAIAdapter({
+      async complete() {
+        throw new Error("adapter-failure");
+      },
+    });
+
+    const request = createTestRequest("http://localhost:3000/api/chat/messages", {
+      method: "POST",
+      body: { text: "hello" },
+    });
+
+    const response = await postMessage(request);
+    expect(response.status).toBe(201);
+
+    const messages = getStoreMessages();
+    expect(messages.length).toBe(1);
+    expect(messages[0]?.role).toBe("user");
+  });
+
+  it("caps in-memory history size", () => {
+    for (let i = 0; i < MAX_HISTORY_MESSAGES + 25; i++) {
+      appendMessage("user", `msg-${i}`);
+    }
+
+    const messages = getStoreMessages();
+    expect(messages.length).toBe(MAX_HISTORY_MESSAGES);
+    expect(messages[0]?.text).toBe("msg-25");
+  });
+
+  it("exposes SSE stream endpoint", () => {
+    const request = createTestRequest("http://localhost:3000/api/chat/stream");
+    const response = getStream(request);
+    expect(response.status).toBe(200);
+    expect(response.headers.get("Content-Type")).toContain("text/event-stream");
+  });
+
+  it("SSE stream emits snapshot and live message events", async () => {
+    const abortController = new AbortController();
+    const request = new Request("http://localhost:3000/api/chat/stream", {
+      signal: abortController.signal,
+    });
+
+    const response = getStream(request);
+    const reader = response.body?.getReader();
+    expect(reader).toBeDefined();
+
+    const decoder = new TextDecoder();
+
+    try {
+      const firstChunk = await reader!.read();
+      expect(firstChunk.done).toBe(false);
+      const firstText = decoder.decode(firstChunk.value);
+      expect(firstText).toContain('"type":"snapshot"');
+
+      appendMessage("user", "live-event");
+
+      const secondChunk = await reader!.read();
+      expect(secondChunk.done).toBe(false);
+      const secondText = decoder.decode(secondChunk.value);
+      expect(secondText).toContain('"type":"message"');
+      expect(secondText).toContain('"text":"live-event"');
+    } finally {
+      abortController.abort();
+    }
+  });
+
+  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),
+    ).text();
+
+    expect(source).toContain('role="log"');
+    expect(source).toContain('aria-live="polite"');
+    expect(source).toContain('aria-label="Chat messages"');
+    expect(source).toContain('aria-label="Chat message input"');
+    expect(source).toContain('aria-describedby="chat-input-description"');
+    expect(source).toContain('id="chat-input-description"');
+    expect(source).toContain('aria-label="Send message"');
+  });
+});

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

@@ -0,0 +1,39 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import {
+  __resetChatStoreForTests,
+  __setSubscribeCommitHookForTests,
+  appendMessage,
+  subscribeWithSnapshot,
+} from "@/server/application/chat-store";
+
+describe("chat-store concurrency", () => {
+  beforeEach(() => {
+    __resetChatStoreForTests();
+    __setSubscribeCommitHookForTests(undefined);
+  });
+
+  it("keeps snapshot/subscription consistent when write happens during subscribe", () => {
+    let hookTriggered = false;
+
+    __setSubscribeCommitHookForTests(() => {
+      if (hookTriggered) return;
+      hookTriggered = true;
+      appendMessage("user", "racing-message");
+    });
+
+    const seen: string[] = [];
+    const subscription = subscribeWithSnapshot((event) => {
+      seen.push(event.message.text);
+    });
+
+    expect(subscription.snapshot.some((message) => message.text === "racing-message")).toBe(true);
+
+    // listener 활성화
+    const unsubscribe = subscription.commit();
+
+    appendMessage("assistant", "after-subscribe");
+    expect(seen).toContain("after-subscribe");
+
+    unsubscribe();
+  });
+});