@kmgeon/taskflow 0.1.3

package/src/features/example/components/example-status.tsx

@@ -0,0 +1,160 @@
+'use client';
+
+import { useState } from 'react';
+import type { FormEvent } from 'react';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { useExampleQuery } from '@/features/example/hooks/useExampleQuery';
+
+const statusBadge = (
+  label: string,
+  tone: 'success' | 'error' | 'idle',
+) => {
+  const toneStyles: Record<typeof tone, string> = {
+    success: 'bg-emerald-500/10 text-emerald-300 border-emerald-400/40',
+    error: 'bg-rose-500/10 text-rose-300 border-rose-400/40',
+    idle: 'bg-slate-500/10 text-slate-200 border-slate-400/30',
+  };
+
+  return (
+    <span
+      className={`inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-medium ${toneStyles[tone]}`}
+    >
+      {label}
+    </span>
+  );
+};
+
+export const ExampleStatus = () => {
+  const [inputValue, setInputValue] = useState('');
+  const [exampleId, setExampleId] = useState('');
+  const query = useExampleQuery(exampleId);
+
+  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const trimmed = inputValue.trim();
+
+    if (!trimmed) {
+      setExampleId('');
+      return;
+    }
+
+    if (trimmed === exampleId) {
+      void query.refetch();
+      return;
+    }
+
+    setExampleId(trimmed);
+  };
+
+  return (
+    <section className="mx-auto flex w-full max-w-3xl flex-col gap-6">
+      <header className="space-y-2 text-slate-100">
+        <h1 className="text-3xl font-semibold tracking-tight">Backend Health Check</h1>
+        <p className="text-sm text-slate-300">
+          예시 API(`/api/example/:id`)가 정상 동작하는지 확인합니다. Supabase 예시
+          레코드의 UUID를 입력하면 React Query를 통해 백엔드 응답을 확인할 수
+          있습니다.
+        </p>
+      </header>
+
+      <form
+        onSubmit={handleSubmit}
+        className="flex flex-col gap-3 rounded-xl border border-slate-800 bg-slate-950/60 p-4 md:flex-row md:items-center"
+      >
+        <div className="flex-1 space-y-1">
+          <label className="text-xs uppercase tracking-wide text-slate-400">
+            Example UUID
+          </label>
+          <Input
+            value={inputValue}
+            onChange={(event) => setInputValue(event.target.value)}
+            placeholder="00000000-0000-0000-0000-000000000000"
+            className="bg-slate-900/70 text-slate-100 placeholder:text-slate-600"
+          />
+        </div>
+        <Button
+          type="submit"
+          variant="secondary"
+          className="mt-2 h-12 rounded-lg border border-slate-600 bg-slate-800 text-slate-100 hover:bg-slate-700 md:mt-6"
+        >
+          조회하기
+        </Button>
+      </form>
+
+      <article className="space-y-3 rounded-xl border border-slate-800 bg-slate-950/60 p-6 text-slate-100">
+        <div className="flex items-center justify-between">
+          <h2 className="text-lg font-semibold">현재 상태</h2>
+          {exampleId
+            ? query.status === 'pending'
+              ? statusBadge('Fetching', 'idle')
+              : query.status === 'error'
+                ? statusBadge('Error', 'error')
+                : statusBadge('Success', 'success')
+            : statusBadge('Idle', 'idle')}
+        </div>
+
+        {!exampleId && (
+          <p className="text-sm text-slate-300">
+            UUID를 입력하고 조회하기 버튼을 누르면 결과가 이곳에 표시됩니다.
+          </p>
+        )}
+
+        {exampleId && query.status === 'pending' && (
+          <p className="text-sm text-slate-300">Supabase에서 데이터를 가져오는 중...</p>
+        )}
+
+        {query.status === 'error' && (
+          <div className="space-y-2 rounded-lg border border-rose-400/30 bg-rose-500/5 p-4">
+            <p className="text-sm font-medium text-rose-300">요청 실패</p>
+            <p className="text-xs text-rose-200/80">
+              {query.error instanceof Error
+                ? query.error.message
+                : '알 수 없는 에러가 발생했습니다.'}
+            </p>
+          </div>
+        )}
+
+        {query.data && (
+          <div className="space-y-3 rounded-lg border border-emerald-400/30 bg-emerald-500/5 p-4 text-sm text-emerald-100">
+            <div>
+              <p className="text-xs uppercase tracking-wide text-emerald-300">ID</p>
+              <p className="font-mono text-xs md:text-sm">{query.data.id}</p>
+            </div>
+            <div>
+              <p className="text-xs uppercase tracking-wide text-emerald-300">
+                이름
+              </p>
+              <p>{query.data.fullName}</p>
+            </div>
+            <div>
+              <p className="text-xs uppercase tracking-wide text-emerald-300">
+                소개
+              </p>
+              <p>{query.data.bio ?? '—'}</p>
+            </div>
+            <div>
+              <p className="text-xs uppercase tracking-wide text-emerald-300">
+                아바타
+              </p>
+              <a
+                href={query.data.avatarUrl}
+                target="_blank"
+                rel="noreferrer"
+                className="underline"
+              >
+                {query.data.avatarUrl}
+              </a>
+            </div>
+            <div>
+              <p className="text-xs uppercase tracking-wide text-emerald-300">
+                업데이트 시각
+              </p>
+              <p>{query.data.updatedAt}</p>
+            </div>
+          </div>
+        )}
+      </article>
+    </section>
+  );
+};

package/src/features/example/hooks/useExampleQuery.ts

@@ -0,0 +1,23 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import { apiClient, extractApiErrorMessage } from '@/lib/remote/api-client';
+import { ExampleResponseSchema } from '@/features/example/lib/dto';
+
+const fetchExample = async (id: string) => {
+  try {
+    const { data } = await apiClient.get(`/api/example/${id}`);
+    return ExampleResponseSchema.parse(data);
+  } catch (error) {
+    const message = extractApiErrorMessage(error, 'Failed to fetch example.');
+    throw new Error(message);
+  }
+};
+
+export const useExampleQuery = (id: string) =>
+  useQuery({
+    queryKey: ['example', id],
+    queryFn: () => fetchExample(id),
+    enabled: Boolean(id),
+    staleTime: 60 * 1000,
+  });

package/src/features/example/lib/dto.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { ExampleResponseSchema } from './dto';
+
+describe('ExampleResponseSchema', () => {
+  it('should validate a correct example response', () => {
+    const validData = {
+      id: '123e4567-e89b-12d3-a456-426614174000',
+      fullName: 'Test User',
+      avatarUrl: 'https://example.com/avatar.jpg',
+      bio: 'This is a test bio',
+      updatedAt: '2024-01-01T00:00:00Z',
+    };
+
+    const result = ExampleResponseSchema.safeParse(validData);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual(validData);
+    }
+  });
+
+  it('should allow null bio', () => {
+    const validData = {
+      id: '123e4567-e89b-12d3-a456-426614174000',
+      fullName: 'Test User',
+      avatarUrl: 'https://example.com/avatar.jpg',
+      bio: null,
+      updatedAt: '2024-01-01T00:00:00Z',
+    };
+
+    const result = ExampleResponseSchema.safeParse(validData);
+
+    expect(result.success).toBe(true);
+  });
+
+  it('should reject invalid data structure', () => {
+    const invalidData = {
+      id: 123, // should be string
+      fullName: 'Test User',
+    };
+
+    const result = ExampleResponseSchema.safeParse(invalidData);
+
+    expect(result.success).toBe(false);
+  });
+
+  it('should reject missing required fields', () => {
+    const invalidData = {
+      id: 'test-id',
+      // missing fullName, avatarUrl, updatedAt
+    };
+
+    const result = ExampleResponseSchema.safeParse(invalidData);
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/features/example/lib/dto.ts

@@ -0,0 +1,5 @@
+export {
+  ExampleParamsSchema,
+  ExampleResponseSchema,
+  type ExampleResponse,
+} from '@/features/example/backend/schema';

package/src/features/kanban/backend/__tests__/sse-broadcaster.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { getSseBroadcaster, resetBroadcaster, type SseEvent } from "../sse-broadcaster";
+import { ensureRepo, createTask, updateTask, deleteTask } from "@/features/taskflow/lib/repository";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  resetBroadcaster();
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "sse-test-"));
+  await ensureRepo(tmpDir);
+});
+
+afterEach(async () => {
+  const broadcaster = getSseBroadcaster();
+  await broadcaster.destroy();
+  resetBroadcaster();
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("SseBroadcaster", () => {
+  it("should be a singleton", () => {
+    const a = getSseBroadcaster();
+    const b = getSseBroadcaster();
+    expect(a).toBe(b);
+  });
+
+  it("should reset properly", () => {
+    const a = getSseBroadcaster();
+    resetBroadcaster();
+    const b = getSseBroadcaster();
+    expect(a).not.toBe(b);
+  });
+
+  it("should subscribe and unsubscribe listeners", () => {
+    const broadcaster = getSseBroadcaster();
+    const listener = vi.fn();
+
+    const unsub = broadcaster.subscribe(listener);
+    expect(broadcaster.subscriberCount).toBe(1);
+
+    unsub();
+    expect(broadcaster.subscriberCount).toBe(0);
+  });
+
+  it("should support multiple subscribers", () => {
+    const broadcaster = getSseBroadcaster();
+    const l1 = vi.fn();
+    const l2 = vi.fn();
+    const l3 = vi.fn();
+
+    const u1 = broadcaster.subscribe(l1);
+    const u2 = broadcaster.subscribe(l2);
+    const u3 = broadcaster.subscribe(l3);
+
+    expect(broadcaster.subscriberCount).toBe(3);
+
+    u2();
+    expect(broadcaster.subscriberCount).toBe(2);
+
+    u1();
+    u3();
+    expect(broadcaster.subscriberCount).toBe(0);
+  });
+
+  it("should broadcast file change events to subscribers", async () => {
+    const broadcaster = getSseBroadcaster();
+    broadcaster.init(tmpDir);
+
+    const events: SseEvent[] = [];
+    broadcaster.subscribe((e) => events.push(e));
+
+    // Create a task file — triggers chokidar "add"
+    await createTask(tmpDir, { title: "SSE test task", priority: 5 });
+
+    // Wait for chokidar + throttle (awaitWriteFinish 100ms + throttle 300ms + margin)
+    await new Promise((r) => setTimeout(r, 1000));
+
+    // Should have received at least one event
+    expect(events.length).toBeGreaterThanOrEqual(1);
+    const taskEvent = events.find((e) => e.type === "created" || e.type === "updated");
+    // created or updated depending on timing
+    expect(taskEvent || events.find((e) => e.type === "index")).toBeTruthy();
+  });
+
+  it("should throttle rapid events", async () => {
+    const broadcaster = getSseBroadcaster();
+    broadcaster.init(tmpDir);
+
+    const events: SseEvent[] = [];
+    broadcaster.subscribe((e) => {
+      if (e.path) events.push(e);
+    });
+
+    // Rapid create 5 tasks
+    for (let i = 0; i < 5; i++) {
+      await createTask(tmpDir, { title: `Rapid ${i}` });
+    }
+
+    // Wait for chokidar awaitWriteFinish + throttle to settle
+    await new Promise((r) => setTimeout(r, 1500));
+
+    // Throttling should produce fewer events than raw file operations
+    // (5 creates × 2 files each = 10 raw events, throttle collapses them)
+    expect(events.length).toBeGreaterThan(0);
+    expect(events.length).toBeLessThan(15);
+  });
+
+  it("should remove broken listeners gracefully", () => {
+    const broadcaster = getSseBroadcaster();
+    broadcaster.init(tmpDir);
+
+    const brokenListener = () => {
+      throw new Error("broken");
+    };
+    const goodListener = vi.fn();
+
+    broadcaster.subscribe(brokenListener);
+    broadcaster.subscribe(goodListener);
+
+    expect(broadcaster.subscriberCount).toBe(2);
+  });
+
+  it("should clean up on destroy", async () => {
+    const broadcaster = getSseBroadcaster();
+    broadcaster.init(tmpDir);
+
+    const listener = vi.fn();
+    broadcaster.subscribe(listener);
+
+    await broadcaster.destroy();
+
+    expect(broadcaster.subscriberCount).toBe(0);
+  });
+});

package/src/features/kanban/backend/__tests__/sse-event-format.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import type { SseEvent, SseEventType } from "../sse-broadcaster";
+
+describe("SseEvent format", () => {
+  it("should have required fields for task events", () => {
+    const event: SseEvent = {
+      type: "created",
+      id: "001",
+      path: ".taskflow/tasks/task-001.md",
+      ts: Date.now(),
+    };
+
+    expect(event.type).toBe("created");
+    expect(event.id).toBe("001");
+    expect(event.path).toContain("task-001.md");
+    expect(typeof event.ts).toBe("number");
+  });
+
+  it("should allow optional id for index events", () => {
+    const event: SseEvent = {
+      type: "index",
+      path: ".taskflow/index/TASKS.md",
+      ts: Date.now(),
+    };
+
+    expect(event.type).toBe("index");
+    expect(event.id).toBeUndefined();
+  });
+
+  it("should serialize to valid JSON", () => {
+    const event: SseEvent = {
+      type: "updated",
+      id: "002",
+      path: ".taskflow/tasks/task-002.md",
+      ts: 1710979200000,
+    };
+
+    const json = JSON.stringify(event);
+    const parsed = JSON.parse(json);
+
+    expect(parsed.type).toBe("updated");
+    expect(parsed.id).toBe("002");
+    expect(parsed.ts).toBe(1710979200000);
+  });
+
+  it("should cover all event types", () => {
+    const types: SseEventType[] = ["created", "updated", "deleted", "index"];
+    expect(types).toHaveLength(4);
+
+    for (const type of types) {
+      const event: SseEvent = { type, path: "test", ts: Date.now() };
+      expect(event.type).toBe(type);
+    }
+  });
+});

package/src/features/kanban/backend/route.ts

@@ -0,0 +1,55 @@
+import type { Hono } from "hono";
+import { z } from "zod";
+import {
+  listTasks,
+  readTask,
+  updateTask,
+  ensureRepo,
+} from "@/features/taskflow/lib/repository";
+import { TASK_STATUSES } from "@/features/taskflow/types";
+
+const statusBodySchema = z.object({
+  to: z.enum(TASK_STATUSES),
+});
+
+export const registerTaskRoutes = (app: Hono<any>) => {
+  const projectRoot = process.cwd();
+
+  app.get("/api/tasks", async (c) => {
+    await ensureRepo(projectRoot);
+    const tasks = await listTasks(projectRoot);
+    return c.json(tasks);
+  });
+
+  app.get("/api/tasks/:id", async (c) => {
+    const id = c.req.param("id");
+    const task = await readTask(projectRoot, id);
+
+    if (!task) {
+      return c.json({ error: { code: "NOT_FOUND", message: `Task ${id} not found` } }, 404);
+    }
+
+    return c.json(task);
+  });
+
+  app.post("/api/tasks/:id/status", async (c) => {
+    const id = c.req.param("id");
+    const body = await c.req.json();
+    const parsed = statusBodySchema.safeParse(body);
+
+    if (!parsed.success) {
+      return c.json(
+        { error: { code: "INVALID_BODY", message: "Invalid status", details: parsed.error.format() } },
+        400,
+      );
+    }
+
+    try {
+      const updated = await updateTask(projectRoot, id, { status: parsed.data.to });
+      return c.json(updated);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return c.json({ error: { code: "UPDATE_FAILED", message } }, 404);
+    }
+  });
+};

package/src/features/kanban/backend/sse-broadcaster.ts

@@ -0,0 +1,142 @@
+import path from "node:path";
+import { watch, type FSWatcher } from "chokidar";
+import { getTasksDir, getIndexFilePath, extractTaskId } from "@/features/taskflow/constants";
+
+// ── SSE Event Types ──
+
+export type SseEventType = "created" | "updated" | "deleted" | "index";
+
+export interface SseEvent {
+  type: SseEventType;
+  id?: string;
+  path: string;
+  ts: number;
+}
+
+export type SseListener = (event: SseEvent) => void;
+
+// ── Broadcaster ──
+
+const THROTTLE_MS = 300;
+const KEEPALIVE_INTERVAL_MS = 30_000;
+
+class SseBroadcaster {
+  private listeners = new Set<SseListener>();
+  private watcher: FSWatcher | null = null;
+  private lastEmit = 0;
+  private pendingEvent: SseEvent | null = null;
+  private throttleTimer: ReturnType<typeof setTimeout> | null = null;
+  private keepAliveTimer: ReturnType<typeof setInterval> | null = null;
+  private initialized = false;
+
+  init(projectRoot: string): void {
+    if (this.initialized) return;
+    this.initialized = true;
+
+    const tasksDir = getTasksDir(projectRoot);
+    const indexPath = getIndexFilePath(projectRoot);
+
+    this.watcher = watch(
+      [path.join(tasksDir, "task-*.md"), indexPath],
+      {
+        ignoreInitial: true,
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+      },
+    );
+
+    this.watcher.on("add", (fp) => this.handleFsEvent("created", fp, indexPath));
+    this.watcher.on("change", (fp) => this.handleFsEvent("updated", fp, indexPath));
+    this.watcher.on("unlink", (fp) => this.handleFsEvent("deleted", fp, indexPath));
+
+    this.keepAliveTimer = setInterval(() => {
+      this.broadcast({ type: "index", path: "", ts: Date.now() });
+    }, KEEPALIVE_INTERVAL_MS);
+  }
+
+  subscribe(listener: SseListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  get subscriberCount(): number {
+    return this.listeners.size;
+  }
+
+  async destroy(): Promise<void> {
+    if (this.throttleTimer) clearTimeout(this.throttleTimer);
+    if (this.keepAliveTimer) clearInterval(this.keepAliveTimer);
+    if (this.watcher) await this.watcher.close();
+    this.listeners.clear();
+    this.initialized = false;
+    this.watcher = null;
+  }
+
+  private handleFsEvent(fsEvent: "created" | "updated" | "deleted", filePath: string, indexPath: string): void {
+    const isIndex = path.resolve(filePath) === path.resolve(indexPath);
+
+    const event: SseEvent = {
+      type: isIndex ? "index" : fsEvent,
+      id: isIndex ? undefined : (extractTaskId(path.basename(filePath)) ?? undefined),
+      path: filePath,
+      ts: Date.now(),
+    };
+
+    this.throttledBroadcast(event);
+  }
+
+  private throttledBroadcast(event: SseEvent): void {
+    const now = Date.now();
+    const elapsed = now - this.lastEmit;
+
+    if (elapsed >= THROTTLE_MS) {
+      this.lastEmit = now;
+      this.broadcast(event);
+      return;
+    }
+
+    // Throttle: replace pending event (latest wins)
+    this.pendingEvent = event;
+
+    if (!this.throttleTimer) {
+      this.throttleTimer = setTimeout(() => {
+        this.throttleTimer = null;
+        if (this.pendingEvent) {
+          this.lastEmit = Date.now();
+          this.broadcast(this.pendingEvent);
+          this.pendingEvent = null;
+        }
+      }, THROTTLE_MS - elapsed);
+    }
+  }
+
+  private broadcast(event: SseEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Remove broken listeners
+        this.listeners.delete(listener);
+      }
+    }
+  }
+}
+
+// ── Singleton ──
+
+let instance: SseBroadcaster | null = null;
+
+export function getSseBroadcaster(): SseBroadcaster {
+  if (!instance) {
+    instance = new SseBroadcaster();
+  }
+  return instance;
+}
+
+export function resetBroadcaster(): void {
+  if (instance) {
+    instance.destroy();
+    instance = null;
+  }
+}

package/src/features/kanban/backend/sse-route.ts

@@ -0,0 +1,43 @@
+import type { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { getSseBroadcaster, type SseEvent } from "./sse-broadcaster";
+
+export const registerSseRoute = (app: Hono<any>) => {
+  const projectRoot = process.cwd();
+
+  app.get("/api/sse", (c) => {
+    const broadcaster = getSseBroadcaster();
+    broadcaster.init(projectRoot);
+
+    return streamSSE(c, async (stream) => {
+      // Send initial connection event
+      await stream.writeSSE({
+        event: "connected",
+        data: JSON.stringify({ ts: Date.now(), subscribers: broadcaster.subscriberCount + 1 }),
+      });
+
+      let closed = false;
+
+      const unsubscribe = broadcaster.subscribe((event: SseEvent) => {
+        if (closed) return;
+        stream.writeSSE({
+          event: "task-change",
+          data: JSON.stringify(event),
+        }).catch(() => {
+          closed = true;
+        });
+      });
+
+      // Keep stream alive until client disconnects
+      stream.onAbort(() => {
+        closed = true;
+        unsubscribe();
+      });
+
+      // Block until aborted
+      await new Promise<void>((resolve) => {
+        stream.onAbort(resolve);
+      });
+    });
+  });
+};