@kmgeon/taskflow 0.1.3

package/src/cli/commands/run.ts

@@ -0,0 +1,143 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Command } from "commander";
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { withCliErrorBoundary } from "../lib/error-boundary.js";
+import { findTrdFiles } from "../lib/trd.js";
+
+function setupRalphLoop(
+  projectRoot: string,
+  trdContent: string,
+  trdName: string,
+): void {
+  const prompt = `다음 TRD를 기반으로 태스크를 분해하고 모두 구현하세요.
+
+## 단계 1: 태스크 분해
+아래 TRD를 읽고 구현 가능한 단위의 태스크로 분해하세요:
+- 각 태스크는 4시간 이내에 완료 가능한 크기
+- MCP \`create_task\` 도구로 각 태스크를 생성하세요
+- group 파라미터에 "${trdName}" 을 설정하세요
+- 태스크 간 의존성을 dependencies에 명시하세요
+- 태스크 목록을 사용자에게 보여주고 승인을 받으세요
+
+## 단계 2: 순차 구현
+태스크가 생성되면 하나씩 순서대로 구현하세요:
+1. MCP \`get_next_task\`로 다음 태스크 조회 (group: "${trdName}")
+2. MCP \`set_task_status\`로 InProgress 변경
+3. 코드 구현 + 테스트 실행
+4. MCP \`set_task_status\`로 Done 변경
+5. 다음 태스크로 반복
+
+모든 태스크가 완료되면 작업 요약을 출력하세요.
+
+## TRD 내용
+
+${trdContent}`;
+
+  const ralphConfig = `---
+active: true
+iteration: 1
+session_id:
+max_iterations: 0
+completion_promise: null
+started_at: "${new Date().toISOString()}"
+---
+
+${prompt}
+`;
+
+  const claudeDir = path.join(projectRoot, ".claude");
+  fs.mkdirSync(claudeDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(claudeDir, "ralph-loop.local.md"),
+    ralphConfig,
+    "utf-8",
+  );
+}
+
+export function registerRunCommand(program: Command) {
+  program
+    .command("run")
+    .description(
+      "TRD를 선택하고 Ralph Loop으로 태스크 분해 + 자동 구현합니다",
+    )
+    .action(
+      withCliErrorBoundary(async () => {
+        const cwd = process.cwd();
+
+        // 1. TRD 파일 목록 조회
+        const trdFiles = findTrdFiles(cwd);
+
+        if (trdFiles.length === 0) {
+          console.log(
+            chalk.yellow(
+              "\n⚠ TRD 파일이 없습니다. /t-create 스킬로 먼저 TRD를 생성하세요.\n",
+            ),
+          );
+          return;
+        }
+
+        // 2. TRD 선택 UI
+        console.log(chalk.bold("\n📋 TRD 목록:\n"));
+        for (let i = 0; i < trdFiles.length; i++) {
+          const t = trdFiles[i];
+          console.log(`  ${chalk.cyan(`${i + 1})`)} ${t.name}  ${chalk.dim(`(${t.fileName})`)}`);
+        }
+        console.log();
+
+        let selectedTrd: string;
+        if (trdFiles.length === 1) {
+          const { confirm } = await inquirer.prompt<{ confirm: boolean }>([
+            {
+              type: "confirm",
+              name: "confirm",
+              message: `"${trdFiles[0].name}" TRD를 실행할까요?`,
+              default: true,
+            },
+          ]);
+          if (!confirm) return;
+          selectedTrd = trdFiles[0].filePath;
+        } else {
+          const { num } = await inquirer.prompt<{ num: number }>([
+            {
+              type: "number",
+              name: "num",
+              message: "번호를 입력하세요:",
+              validate: (v: number) =>
+                v >= 1 && v <= trdFiles.length
+                  ? true
+                  : `1~${trdFiles.length} 사이 번호를 입력하세요`,
+            },
+          ]);
+          selectedTrd = trdFiles[num - 1].filePath;
+        }
+
+        // 3. TRD 내용 읽기
+        const trdContent = fs.readFileSync(selectedTrd, "utf-8");
+        const selected = trdFiles.find((t) => t.filePath === selectedTrd)!;
+
+        console.log(
+          chalk.bold(
+            `\n🚀 "${selected.name}" TRD를 기반으로 자동 구현을 시작합니다.`,
+          ),
+        );
+
+        // 4. Ralph Loop 셋업
+        setupRalphLoop(cwd, trdContent, selected.name);
+
+        console.log(chalk.green("✔ Ralph Loop이 설정되었습니다.\n"));
+        console.log(chalk.gray("  다음 단계:"));
+        console.log(
+          chalk.gray(
+            "  Claude Code에서 아무 메시지나 입력하면 Ralph Loop이 시작됩니다.",
+          ),
+        );
+        console.log(
+          chalk.gray(
+            "  중지하려면: /ralph-loop:cancel-ralph\n",
+          ),
+        );
+      }),
+    );
+}

package/src/cli/commands/set-status.ts

@@ -0,0 +1,50 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { readTask, updateTask } from "@/features/taskflow/lib/repository";
+import { withCliErrorBoundary } from "../lib/error-boundary.js";
+import type { TaskStatus } from "@/features/taskflow/types";
+import { TASK_STATUSES } from "@/features/taskflow/types";
+
+function validateStatus(value: string): TaskStatus {
+  if (!(TASK_STATUSES as readonly string[]).includes(value)) {
+    throw new Error(
+      `유효하지 않은 상태입니다: ${value}\n  허용: ${TASK_STATUSES.join(", ")}`,
+    );
+  }
+  return value as TaskStatus;
+}
+
+export function registerSetStatusCommand(program: Command) {
+  program
+    .command("set-status")
+    .description("태스크 상태를 변경합니다")
+    .argument("<id>", "태스크 ID")
+    .requiredOption("--to <status>", "변경할 상태 (Todo, InProgress, Blocked, Done)")
+    .action(
+      withCliErrorBoundary(async (id: string, opts: { to: string }) => {
+        const projectRoot = process.cwd();
+        const newStatus = validateStatus(opts.to);
+
+        const existing = await readTask(projectRoot, id);
+        if (!existing) {
+          console.error(chalk.red(`✖ 태스크를 찾을 수 없습니다: ${id}`));
+          process.exitCode = 1;
+          return;
+        }
+
+        if (existing.status === newStatus) {
+          console.log(chalk.yellow(`이미 "${newStatus}" 상태입니다.`));
+          return;
+        }
+
+        const oldStatus = existing.status;
+        const updated = await updateTask(projectRoot, id, { status: newStatus });
+
+        console.log(
+          chalk.green(
+            `✔ [${updated.id}] ${updated.title}: ${oldStatus} → ${newStatus}`,
+          ),
+        );
+      }),
+    );
+}

package/src/cli/commands/show.ts

@@ -0,0 +1,28 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { readTask } from "@/features/taskflow/lib/repository";
+import { formatTaskDetail } from "../lib/formatter.js";
+import { withCliErrorBoundary } from "../lib/error-boundary.js";
+
+export function registerShowCommand(program: Command) {
+  program
+    .command("show")
+    .description("태스크 상세 정보를 출력합니다")
+    .argument("<id>", "태스크 ID")
+    .action(
+      withCliErrorBoundary(async (id: string) => {
+        const projectRoot = process.cwd();
+        const task = await readTask(projectRoot, id);
+
+        if (!task) {
+          console.error(chalk.red(`✖ 태스크를 찾을 수 없습니다: ${id}`));
+          process.exitCode = 1;
+          return;
+        }
+
+        console.log("");
+        console.log(formatTaskDetail(task));
+        console.log("");
+      }),
+    );
+}

package/src/cli/commands/tree.ts

@@ -0,0 +1,72 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { listTasks } from "@/features/taskflow/lib/repository";
+import { formatDependencyTree } from "../lib/formatter.js";
+import { withCliErrorBoundary } from "../lib/error-boundary.js";
+import type { Task } from "@/features/taskflow/types";
+import { getTrdGroupNames } from "../lib/trd.js";
+
+function formatGroupTree(tasks: Task[], trdGroupNames: string[]): void {
+  const groups = new Map<string, Task[]>();
+
+  // TRD 그룹을 먼저 빈 상태로 등록
+  for (const name of trdGroupNames) {
+    groups.set(name, []);
+  }
+
+  for (const task of tasks) {
+    const name = task.group ?? "(그룹 없음)";
+    let list = groups.get(name);
+    if (!list) {
+      list = [];
+      groups.set(name, list);
+    }
+    list.push(task);
+  }
+
+  for (const [name, groupTasks] of groups) {
+    const done = groupTasks.filter((t) => t.status === "Done").length;
+    const total = groupTasks.length;
+
+    console.log(chalk.bold(`\n── ${name} (${done}/${total}) ──\n`));
+    console.log(formatDependencyTree(groupTasks, {}));
+  }
+}
+
+export function registerTreeCommand(program: Command) {
+  program
+    .command("tree")
+    .description("의존성 트리를 출력합니다 (그룹별)")
+    .option("--detail [group]", "특정 그룹의 상세 트리")
+    .option("--root <id>", "특정 태스크를 루트로 지정")
+    .option("--depth <n>", "최대 깊이 제한", parseInt)
+    .action(
+      withCliErrorBoundary(
+        async (opts: { detail?: string | boolean; root?: string; depth?: number }) => {
+          const projectRoot = process.cwd();
+          const tasks = await listTasks(projectRoot);
+          const trdGroups = getTrdGroupNames(projectRoot);
+
+          if (tasks.length === 0 && trdGroups.length === 0) {
+            console.log(chalk.yellow("\n⚠ 태스크가 없습니다.\n"));
+            return;
+          }
+
+          if (opts.detail !== undefined || opts.root) {
+            const groupFilter = typeof opts.detail === "string" ? opts.detail : undefined;
+            const filtered = groupFilter
+              ? tasks.filter((t) => t.group?.includes(groupFilter))
+              : tasks;
+
+            console.log("");
+            console.log(formatDependencyTree(filtered, { rootId: opts.root, maxDepth: opts.depth }));
+            console.log("");
+            return;
+          }
+
+          formatGroupTree(tasks, trdGroups);
+          console.log(chalk.gray("\n  상세 보기: task tree --detail [그룹명]\n"));
+        },
+      ),
+    );
+}

package/src/cli/index.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import chalk from "chalk";
+import { registerInitCommand } from "./commands/init.js";
+import { registerListCommand } from "./commands/list.js";
+import { registerBoardCommand } from "./commands/board.js";
+import { registerTreeCommand } from "./commands/tree.js";
+import { registerShowCommand } from "./commands/show.js";
+import { registerSetStatusCommand } from "./commands/set-status.js";
+import { registerAskCommand } from "./commands/ask.js";
+import { registerAdvisorCommand } from "./commands/advisor.js";
+import { registerRunCommand } from "./commands/run.js";
+
+// CTRL+C 안전 종료
+process.on("SIGINT", () => {
+  console.log(chalk.yellow("\n\n👋 작업을 취소했습니다. 언제든 다시 시도해주세요!"));
+  process.exit(0);
+});
+
+const program = new Command();
+
+program
+  .name("task")
+  .description("TaskFlow — AI-powered task manager for developers")
+  .version("0.1.0");
+
+registerInitCommand(program);
+registerListCommand(program);
+registerBoardCommand(program);
+registerTreeCommand(program);
+registerShowCommand(program);
+registerSetStatusCommand(program);
+registerAskCommand(program);
+registerAdvisorCommand(program);
+registerRunCommand(program);
+
+program.parse();

package/src/cli/lib/__tests__/formatter.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect } from "vitest";
+import { truncate, formatTaskTable, formatTaskDetail } from "../formatter";
+import type { Task } from "@/features/taskflow/types";
+
+const now = new Date().toISOString();
+
+function makeTask(overrides: Partial<Task> = {}): Task {
+  return {
+    id: "001",
+    title: "Test task",
+    status: "Todo",
+    priority: 5,
+    dependencies: [],
+    createdAt: now,
+    updatedAt: now,
+    description: "",
+    ...overrides,
+  };
+}
+
+describe("truncate", () => {
+  it("should not truncate short strings", () => {
+    expect(truncate("hello", 10)).toBe("hello");
+  });
+
+  it("should truncate long strings with ellipsis", () => {
+    expect(truncate("a very long string that exceeds", 15)).toBe("a very long s..");
+  });
+
+  it("should handle exact length", () => {
+    expect(truncate("exact", 5)).toBe("exact");
+  });
+
+  it("should handle maxLen <= 3", () => {
+    expect(truncate("hello", 3)).toBe("hel");
+  });
+
+  it("should handle empty string", () => {
+    expect(truncate("", 10)).toBe("");
+  });
+});
+
+describe("formatTaskTable", () => {
+  it("should show empty message for no tasks", () => {
+    const output = formatTaskTable([]);
+    expect(output).toContain("태스크가 없습니다");
+  });
+
+  it("should render table with tasks", () => {
+    const tasks = [
+      makeTask({ id: "001", title: "Setup", priority: 8, status: "InProgress" }),
+      makeTask({ id: "002", title: "Auth", priority: 5, status: "Todo" }),
+    ];
+    const output = formatTaskTable(tasks);
+
+    // strip ANSI
+    const plain = output.replace(/\x1b\[[0-9;]*m/g, "");
+
+    expect(plain).toContain("001");
+    expect(plain).toContain("002");
+    expect(plain).toContain("Setup");
+    expect(plain).toContain("Auth");
+    expect(plain).toContain("InProgress");
+    expect(plain).toContain("Todo");
+  });
+
+  it("should show dependency count", () => {
+    const tasks = [
+      makeTask({ id: "001", dependencies: ["002", "003"] }),
+    ];
+    const output = formatTaskTable(tasks);
+    const plain = output.replace(/\x1b\[[0-9;]*m/g, "");
+    expect(plain).toContain("2");
+  });
+
+  it("should truncate long titles", () => {
+    const tasks = [
+      makeTask({ title: "This is an extremely long task title that should be truncated in the table view" }),
+    ];
+    const output = formatTaskTable(tasks);
+    const plain = output.replace(/\x1b\[[0-9;]*m/g, "");
+    expect(plain).toContain("..");
+  });
+});
+
+describe("formatTaskDetail", () => {
+  it("should display all task fields", () => {
+    const task = makeTask({
+      id: "005",
+      title: "Implement auth",
+      status: "InProgress",
+      priority: 8,
+      dependencies: ["001", "002"],
+      parentId: "000",
+      description: "OAuth2 implementation details",
+    });
+
+    const output = formatTaskDetail(task);
+    const plain = output.replace(/\x1b\[[0-9;]*m/g, "");
+
+    expect(plain).toContain("005");
+    expect(plain).toContain("Implement auth");
+    expect(plain).toContain("InProgress");
+    expect(plain).toContain("8");
+    expect(plain).toContain("001, 002");
+    expect(plain).toContain("000");
+    expect(plain).toContain("OAuth2 implementation details");
+  });
+
+  it("should show '없음' for no dependencies", () => {
+    const task = makeTask({ dependencies: [] });
+    const output = formatTaskDetail(task);
+    const plain = output.replace(/\x1b\[[0-9;]*m/g, "");
+    expect(plain).toContain("없음");
+  });
+
+  it("should omit parentId if not set", () => {
+    const task = makeTask({ parentId: undefined });
+    const output = formatTaskDetail(task);
+    const plain = output.replace(/\x1b\[[0-9;]*m/g, "");
+    expect(plain).not.toContain("상위 태스크");
+  });
+});

package/src/cli/lib/error-boundary.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { withCliErrorBoundary, humanizeError } from "./error-boundary.js";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+// ── humanizeError ──
+
+describe("humanizeError", () => {
+  it("일반 Error 메시지를 반환해야 한다", () => {
+    expect(humanizeError(new Error("뭔가 잘못됨"))).toBe("뭔가 잘못됨");
+  });
+
+  it("EACCES 코드에 대한 한국어 메시지를 반환해야 한다", () => {
+    const err = Object.assign(new Error("원본"), { code: "EACCES" });
+    const msg = humanizeError(err);
+    expect(msg).toContain("접근 권한");
+    expect(msg).toContain("EACCES");
+  });
+
+  it("ETIMEDOUT 코드에 대한 한국어 메시지를 반환해야 한다", () => {
+    const err = Object.assign(new Error("원본"), { code: "ETIMEDOUT" });
+    expect(humanizeError(err)).toContain("시간이 초과");
+  });
+
+  it("ENOSPC 코드에 대한 한국어 메시지를 반환해야 한다", () => {
+    const err = Object.assign(new Error("원본"), { code: "ENOSPC" });
+    expect(humanizeError(err)).toContain("디스크 공간");
+  });
+
+  it("ENAMETOOLONG 코드에 대한 한국어 메시지를 반환해야 한다", () => {
+    const err = Object.assign(new Error("원본"), { code: "ENAMETOOLONG" });
+    expect(humanizeError(err)).toContain("경로가 너무 깁니다");
+  });
+
+  it("알 수 없는 코드는 원본 메시지를 반환해야 한다", () => {
+    const err = Object.assign(new Error("원본 메시지"), { code: "UNKNOWN" });
+    expect(humanizeError(err)).toBe("원본 메시지");
+  });
+
+  it("Error가 아닌 값은 문자열로 변환해야 한다", () => {
+    expect(humanizeError("문자열 에러")).toBe("문자열 에러");
+    expect(humanizeError(42)).toBe("42");
+    expect(humanizeError(null)).toBe("null");
+  });
+});
+
+// ── withCliErrorBoundary ──
+
+describe("withCliErrorBoundary", () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.exitCode = undefined;
+    vi.restoreAllMocks();
+  });
+
+  it("성공 시 원래 반환값을 전달해야 한다", async () => {
+    const fn = vi.fn().mockResolvedValue("result");
+    const wrapped = withCliErrorBoundary(fn);
+    const result = await wrapped();
+    expect(result).toBe("result");
+  });
+
+  it("일반 에러 발생 시 exitCode를 1로 설정해야 한다", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("실패"));
+    const wrapped = withCliErrorBoundary(fn);
+
+    await wrapped();
+
+    expect(process.exitCode).toBe(1);
+  });
+
+  it("일반 에러 발생 시 한국어 오류 메시지를 출력해야 한다", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("실패"));
+    const wrapped = withCliErrorBoundary(fn);
+
+    await wrapped();
+
+    const allOutput = consoleSpy.mock.calls.flat().join(" ");
+    expect(allOutput).toContain("오류가 발생했습니다");
+    expect(allOutput).toContain("실패");
+    expect(allOutput).toContain("해결 방법");
+  });
+
+  it("CTRL+C (ExitPromptError) 시 exitCode를 0으로 설정해야 한다", async () => {
+    const err = new Error("User force closed");
+    err.name = "ExitPromptError";
+    const fn = vi.fn().mockRejectedValue(err);
+    const wrapped = withCliErrorBoundary(fn);
+
+    await wrapped();
+
+    expect(process.exitCode).toBe(0);
+  });
+
+  it("CTRL+C 시 친절한 종료 메시지를 출력해야 한다", async () => {
+    const logSpy = vi.spyOn(console, "log");
+    const err = new Error("User force closed");
+    err.name = "ExitPromptError";
+    const fn = vi.fn().mockRejectedValue(err);
+    const wrapped = withCliErrorBoundary(fn);
+
+    await wrapped();
+
+    const allOutput = logSpy.mock.calls.flat().join(" ");
+    expect(allOutput).toContain("취소");
+  });
+
+  it("시스템 에러 코드에 대해 한국어 메시지를 출력해야 한다", async () => {
+    const err = Object.assign(new Error("permission denied"), { code: "EACCES" });
+    const fn = vi.fn().mockRejectedValue(err);
+    const wrapped = withCliErrorBoundary(fn);
+
+    await wrapped();
+
+    const allOutput = consoleSpy.mock.calls.flat().join(" ");
+    expect(allOutput).toContain("접근 권한");
+  });
+
+  it("인자를 원래 함수에 전달해야 한다", async () => {
+    const fn = vi.fn().mockResolvedValue("ok");
+    const wrapped = withCliErrorBoundary(fn);
+
+    await wrapped("arg1", "arg2");
+
+    expect(fn).toHaveBeenCalledWith("arg1", "arg2");
+  });
+});

package/src/cli/lib/error-boundary.ts

@@ -0,0 +1,70 @@
+import chalk from "chalk";
+
+const ERROR_MESSAGES: Record<string, string> = {
+  EACCES: "파일 또는 디렉토리에 대한 접근 권한이 없습니다.",
+  EPERM: "작업에 필요한 권한이 없습니다.",
+  EROFS: "읽기 전용 파일 시스템에는 쓸 수 없습니다.",
+  ENAMETOOLONG: "파일 경로가 너무 깁니다. 프로젝트명이나 기능명을 줄여주세요.",
+  ENOSPC: "디스크 공간이 부족합니다.",
+  ETIMEDOUT: "요청 시간이 초과되었습니다. 네트워크 연결을 확인해주세요.",
+  ECONNREFUSED: "서버에 연결할 수 없습니다. 네트워크 연결을 확인해주세요.",
+  ENOTFOUND: "서버를 찾을 수 없습니다. 네트워크 연결을 확인해주세요.",
+};
+
+export function humanizeError(error: unknown): string {
+  if (error instanceof Error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code && ERROR_MESSAGES[code]) {
+      return `${ERROR_MESSAGES[code]} (${code})`;
+    }
+    return error.message;
+  }
+  return String(error);
+}
+
+export function withCliErrorBoundary<
+  T extends (...args: any[]) => Promise<any>,
+>(fn: T): T {
+  return (async (...args: any[]) => {
+    try {
+      return await fn(...args);
+    } catch (error: unknown) {
+      // CTRL+C (Inquirer ExitPromptError)는 조용히 종료
+      if (isUserCancellation(error)) {
+        console.log(chalk.yellow("\n\n👋 작업을 취소했습니다. 언제든 다시 시도해주세요!"));
+        process.exitCode = 0;
+        return;
+      }
+
+      console.error("");
+      console.error(chalk.red("✖ 오류가 발생했습니다:"));
+      console.error(chalk.red(`  ${humanizeError(error)}`));
+      console.error("");
+      console.error(chalk.gray("💡 해결 방법:"));
+      console.error(chalk.gray("  • 명령어를 다시 실행하여 재시도해주세요"));
+      console.error(chalk.gray("  • 문제가 지속되면 --help 옵션으로 사용법을 확인하세요"));
+      console.error("");
+
+      process.exitCode = 1;
+    }
+  }) as T;
+}
+
+function isUserCancellation(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+
+  // Inquirer의 ExitPromptError
+  const name = (error as Error).name;
+  if (name === "ExitPromptError") return true;
+
+  // 일반적인 사용자 취소 메시지
+  const message = (error as Error).message ?? "";
+  if (
+    message.includes("User force closed") ||
+    message.includes("prompt was closed")
+  ) {
+    return true;
+  }
+
+  return false;
+}