@kmgeon/taskflow 0.1.3

package/src/features/kanban/lib/kanban-utils.ts

@@ -0,0 +1,37 @@
+import type { Task, TaskStatus } from "@/features/taskflow/types";
+import { TASK_STATUSES } from "@/features/taskflow/types";
+
+export type ColumnMap = Record<TaskStatus, Task[]>;
+
+export function groupByStatus(tasks: Task[]): ColumnMap {
+  const columns: ColumnMap = {
+    Todo: [],
+    InProgress: [],
+    Blocked: [],
+    Done: [],
+  };
+
+  for (const task of tasks) {
+    columns[task.status].push(task);
+  }
+
+  return columns;
+}
+
+export function computeProgress(tasks: Task[]): number {
+  if (tasks.length === 0) return 0;
+  const done = tasks.filter((t) => t.status === "Done").length;
+  return Math.round((done / tasks.length) * 100);
+}
+
+export const STATUS_CONFIG: Record<
+  TaskStatus,
+  { label: string; dotColor: string; bgColor: string }
+> = {
+  Todo: { label: "Todo", dotColor: "bg-slate-400", bgColor: "bg-slate-400/10" },
+  InProgress: { label: "In Progress", dotColor: "bg-blue-500", bgColor: "bg-blue-500/10" },
+  Blocked: { label: "Blocked", dotColor: "bg-red-500", bgColor: "bg-red-500/10" },
+  Done: { label: "Done", dotColor: "bg-green-500", bgColor: "bg-green-500/10" },
+};
+
+export const COLUMN_ORDER: TaskStatus[] = [...TASK_STATUSES];

package/src/features/taskflow/constants.ts

@@ -0,0 +1,54 @@
+import path from "node:path";
+
+export const TASKFLOW_DIR = ".taskflow";
+export const TASKS_DIR = "tasks";
+export const INDEX_DIR = "index";
+export const LOGS_DIR = "logs";
+export const CACHE_DIR = "cache";
+export const INDEX_FILE = "TASKS.md";
+export const TASK_FILE_PREFIX = "task-";
+export const TASK_FILE_EXT = ".md";
+
+export function getTaskflowRoot(projectRoot: string): string {
+  return path.join(projectRoot, TASKFLOW_DIR);
+}
+
+export function getTasksDir(projectRoot: string): string {
+  return path.join(projectRoot, TASKFLOW_DIR, TASKS_DIR);
+}
+
+export function getIndexDir(projectRoot: string): string {
+  return path.join(projectRoot, TASKFLOW_DIR, INDEX_DIR);
+}
+
+export function getLogsDir(projectRoot: string): string {
+  return path.join(projectRoot, TASKFLOW_DIR, LOGS_DIR);
+}
+
+export function getCacheDir(projectRoot: string): string {
+  return path.join(projectRoot, TASKFLOW_DIR, CACHE_DIR);
+}
+
+export function getIndexFilePath(projectRoot: string): string {
+  return path.join(projectRoot, TASKFLOW_DIR, INDEX_DIR, INDEX_FILE);
+}
+
+export function getTaskFilePath(projectRoot: string, taskId: string): string {
+  return path.join(
+    projectRoot,
+    TASKFLOW_DIR,
+    TASKS_DIR,
+    `${TASK_FILE_PREFIX}${taskId}${TASK_FILE_EXT}`,
+  );
+}
+
+export function extractTaskId(filename: string): string | null {
+  const match = filename.match(/^task-(.+)\.md$/);
+  return match ? match[1] : null;
+}
+
+export const ADVISOR_DB_FILE = "advisor.db";
+
+export function getAdvisorDbPath(projectRoot: string): string {
+  return path.join(getTaskflowRoot(projectRoot), ADVISOR_DB_FILE);
+}

package/src/features/taskflow/index.ts

@@ -0,0 +1,27 @@
+export type {
+  Task,
+  TaskStatus,
+  TaskCreateInput,
+  TaskUpdateInput,
+  TaskFilter,
+  TaskSortKey,
+  TaskSortOrder,
+} from "./types";
+export { TASK_STATUSES } from "./types";
+
+export {
+  ensureRepo,
+  readTask,
+  listTasks,
+  createTask,
+  updateTask,
+  deleteTask,
+  searchTasks,
+} from "./lib/repository";
+
+export { rebuildIndex } from "./lib/index-builder";
+export { filterTasks, sortTasks } from "./lib/filter";
+export { createTaskWatcher } from "./lib/watcher";
+export type { TaskFileEvent, WatchEvent } from "./lib/watcher";
+export { detectCycles, computeReadySet, scoreTask, recommend } from "./lib/graph";
+export type { ReadyResult, BlockedTask, Recommendation, RecommendOptions } from "./lib/graph";

package/src/features/taskflow/lib/__tests__/filter.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import { filterTasks, sortTasks } from "../filter";
+import type { Task } from "../../types";
+
+const now = "2026-03-21T00:00:00.000Z";
+
+function makeTask(overrides: Partial<Task>): Task {
+  return {
+    id: "001",
+    title: "Test",
+    status: "Todo",
+    priority: 0,
+    dependencies: [],
+    createdAt: now,
+    updatedAt: now,
+    description: "",
+    ...overrides,
+  };
+}
+
+const TASKS: Task[] = [
+  makeTask({ id: "001", title: "Alpha", status: "Todo", priority: 3 }),
+  makeTask({ id: "002", title: "Bravo", status: "InProgress", priority: 5 }),
+  makeTask({ id: "003", title: "Charlie", status: "Done", priority: 1 }),
+  makeTask({ id: "004", title: "Delta", status: "Blocked", priority: 2, parentId: "001" }),
+];
+
+describe("filterTasks", () => {
+  it("should filter by single status", () => {
+    const result = filterTasks(TASKS, { status: "Todo" });
+    expect(result).toHaveLength(1);
+    expect(result[0].id).toBe("001");
+  });
+
+  it("should filter by multiple statuses", () => {
+    const result = filterTasks(TASKS, { status: ["Todo", "InProgress"] });
+    expect(result).toHaveLength(2);
+  });
+
+  it("should filter by priority", () => {
+    const result = filterTasks(TASKS, { priority: 5 });
+    expect(result).toHaveLength(1);
+    expect(result[0].id).toBe("002");
+  });
+
+  it("should filter by parentId", () => {
+    const result = filterTasks(TASKS, { parentId: "001" });
+    expect(result).toHaveLength(1);
+    expect(result[0].id).toBe("004");
+  });
+
+  it("should combine filters", () => {
+    const result = filterTasks(TASKS, { status: "Blocked", parentId: "001" });
+    expect(result).toHaveLength(1);
+    expect(result[0].id).toBe("004");
+  });
+
+  it("should return all tasks with empty filter", () => {
+    const result = filterTasks(TASKS, {});
+    expect(result).toHaveLength(4);
+  });
+});
+
+describe("sortTasks", () => {
+  it("should sort by priority ascending", () => {
+    const result = sortTasks(TASKS, "priority", "asc");
+    expect(result.map((t) => t.priority)).toEqual([1, 2, 3, 5]);
+  });
+
+  it("should sort by priority descending", () => {
+    const result = sortTasks(TASKS, "priority", "desc");
+    expect(result.map((t) => t.priority)).toEqual([5, 3, 2, 1]);
+  });
+
+  it("should sort by title ascending", () => {
+    const result = sortTasks(TASKS, "title", "asc");
+    expect(result.map((t) => t.title)).toEqual(["Alpha", "Bravo", "Charlie", "Delta"]);
+  });
+
+  it("should sort by status order", () => {
+    const result = sortTasks(TASKS, "status", "asc");
+    expect(result.map((t) => t.status)).toEqual(["Todo", "InProgress", "Blocked", "Done"]);
+  });
+
+  it("should default to priority desc", () => {
+    const result = sortTasks(TASKS);
+    expect(result[0].priority).toBe(5);
+  });
+});

package/src/features/taskflow/lib/__tests__/graph.test.ts

@@ -0,0 +1,247 @@
+import { describe, it, expect } from "vitest";
+import { detectCycles, computeReadySet, scoreTask, recommend } from "../graph";
+import type { Task } from "../../types";
+
+const now = new Date().toISOString();
+const old = new Date(Date.now() - 7 * 86_400_000).toISOString();
+
+function t(overrides: Partial<Task>): Task {
+  return {
+    id: "001",
+    title: "Task",
+    status: "Todo",
+    priority: 5,
+    dependencies: [],
+    createdAt: now,
+    updatedAt: now,
+    description: "",
+    ...overrides,
+  };
+}
+
+// ── detectCycles ──
+
+describe("detectCycles", () => {
+  it("should return empty for acyclic graph", () => {
+    const tasks = [
+      t({ id: "1", dependencies: [] }),
+      t({ id: "2", dependencies: ["1"] }),
+      t({ id: "3", dependencies: ["2"] }),
+    ];
+    expect(detectCycles(tasks)).toHaveLength(0);
+  });
+
+  it("should detect simple cycle", () => {
+    const tasks = [
+      t({ id: "1", dependencies: ["2"] }),
+      t({ id: "2", dependencies: ["1"] }),
+    ];
+    const cycles = detectCycles(tasks);
+    expect(cycles.length).toBeGreaterThan(0);
+  });
+
+  it("should detect longer cycle", () => {
+    const tasks = [
+      t({ id: "1", dependencies: ["3"] }),
+      t({ id: "2", dependencies: ["1"] }),
+      t({ id: "3", dependencies: ["2"] }),
+    ];
+    const cycles = detectCycles(tasks);
+    expect(cycles.length).toBeGreaterThan(0);
+  });
+
+  it("should handle self-cycle", () => {
+    const tasks = [t({ id: "1", dependencies: ["1"] })];
+    const cycles = detectCycles(tasks);
+    expect(cycles.length).toBeGreaterThan(0);
+  });
+
+  it("should handle no dependencies", () => {
+    const tasks = [t({ id: "1" }), t({ id: "2" }), t({ id: "3" })];
+    expect(detectCycles(tasks)).toHaveLength(0);
+  });
+
+  it("should ignore deps to non-existent tasks", () => {
+    const tasks = [t({ id: "1", dependencies: ["999"] })];
+    expect(detectCycles(tasks)).toHaveLength(0);
+  });
+});
+
+// ── computeReadySet ──
+
+describe("computeReadySet", () => {
+  it("should mark tasks with no deps as ready", () => {
+    const tasks = [
+      t({ id: "1", status: "Todo", dependencies: [] }),
+      t({ id: "2", status: "InProgress", dependencies: [] }),
+    ];
+    const { ready, blocked } = computeReadySet(tasks);
+    expect(ready).toHaveLength(2);
+    expect(blocked).toHaveLength(0);
+  });
+
+  it("should mark tasks with all deps Done as ready", () => {
+    const tasks = [
+      t({ id: "1", status: "Done", dependencies: [] }),
+      t({ id: "2", status: "Todo", dependencies: ["1"] }),
+    ];
+    const { ready } = computeReadySet(tasks);
+    expect(ready).toHaveLength(1);
+    expect(ready[0].id).toBe("2");
+  });
+
+  it("should mark tasks with pending deps as blocked", () => {
+    const tasks = [
+      t({ id: "1", status: "Todo", dependencies: [] }),
+      t({ id: "2", status: "Todo", dependencies: ["1"] }),
+    ];
+    const { ready, blocked } = computeReadySet(tasks);
+    expect(ready).toHaveLength(1);
+    expect(ready[0].id).toBe("1");
+    expect(blocked).toHaveLength(1);
+    expect(blocked[0].task.id).toBe("2");
+    expect(blocked[0].pendingDeps).toEqual(["1"]);
+  });
+
+  it("should exclude Done tasks from results", () => {
+    const tasks = [
+      t({ id: "1", status: "Done" }),
+      t({ id: "2", status: "Done" }),
+    ];
+    const { ready, blocked } = computeReadySet(tasks);
+    expect(ready).toHaveLength(0);
+    expect(blocked).toHaveLength(0);
+  });
+
+  it("should handle chain dependencies", () => {
+    const tasks = [
+      t({ id: "1", status: "Todo" }),
+      t({ id: "2", status: "Todo", dependencies: ["1"] }),
+      t({ id: "3", status: "Todo", dependencies: ["2"] }),
+    ];
+    const { ready, blocked } = computeReadySet(tasks);
+    expect(ready).toHaveLength(1);
+    expect(ready[0].id).toBe("1");
+    expect(blocked).toHaveLength(2);
+  });
+});
+
+// ── scoreTask ──
+
+describe("scoreTask", () => {
+  it("should give higher score to higher priority", () => {
+    const high = scoreTask(t({ priority: 9 }));
+    const low = scoreTask(t({ priority: 2 }));
+    expect(high).toBeGreaterThan(low);
+  });
+
+  it("should give bonus to InProgress tasks", () => {
+    const ip = scoreTask(t({ status: "InProgress", priority: 5 }));
+    const todo = scoreTask(t({ status: "Todo", priority: 5 }));
+    expect(ip).toBeGreaterThan(todo);
+  });
+
+  it("should penalize Blocked tasks", () => {
+    const blocked = scoreTask(t({ status: "Blocked", priority: 5 }));
+    const todo = scoreTask(t({ status: "Todo", priority: 5 }));
+    expect(blocked).toBeLessThan(todo);
+  });
+
+  it("should prefer recently updated tasks", () => {
+    const recent = scoreTask(t({ updatedAt: now }));
+    const stale = scoreTask(t({ updatedAt: old }));
+    expect(recent).toBeGreaterThan(stale);
+  });
+});
+
+// ── recommend ──
+
+describe("recommend", () => {
+  const tasks = [
+    t({ id: "1", status: "Done", priority: 10 }),
+    t({ id: "2", status: "Todo", priority: 8, dependencies: [] }),
+    t({ id: "3", status: "Todo", priority: 3, dependencies: [] }),
+    t({ id: "4", status: "Todo", priority: 6, dependencies: ["1"] }), // ready (dep done)
+    t({ id: "5", status: "Todo", priority: 9, dependencies: ["2"] }), // blocked (dep not done)
+    t({ id: "6", status: "InProgress", priority: 7, dependencies: [] }),
+  ];
+
+  it("should return top N ready tasks by score", () => {
+    const recs = recommend(tasks, { limit: 3 });
+    expect(recs).toHaveLength(3);
+    // Should not include Done tasks or blocked tasks
+    const ids = recs.map((r) => r.task.id);
+    expect(ids).not.toContain("1"); // Done
+    expect(ids).not.toContain("5"); // blocked
+  });
+
+  it("should default to 5 results", () => {
+    const recs = recommend(tasks);
+    expect(recs.length).toBeLessThanOrEqual(5);
+  });
+
+  it("should return all with --all", () => {
+    const recs = recommend(tasks, { all: true });
+    // Ready: 2 (no deps), 3 (no deps), 4 (dep 1 is Done), 6 (no deps) = 4
+    expect(recs.length).toBe(4);
+  });
+
+  it("should include blocked with --include-blocked", () => {
+    const recs = recommend(tasks, { includeBlocked: true, all: true });
+    const ids = recs.map((r) => r.task.id);
+    expect(ids).toContain("5"); // blocked but included
+    const blockedRec = recs.find((r) => r.task.id === "5");
+    expect(blockedRec!.pendingDeps).toEqual(["2"]);
+  });
+
+  it("should rank by score descending", () => {
+    const recs = recommend(tasks, { all: true });
+    for (let i = 0; i < recs.length - 1; i++) {
+      expect(recs[i].score).toBeGreaterThanOrEqual(recs[i + 1].score);
+    }
+  });
+
+  it("should handle empty task list", () => {
+    const recs = recommend([], { limit: 5 });
+    expect(recs).toHaveLength(0);
+  });
+
+  it("should handle all-done task list", () => {
+    const done = [
+      t({ id: "1", status: "Done" }),
+      t({ id: "2", status: "Done" }),
+    ];
+    const recs = recommend(done);
+    expect(recs).toHaveLength(0);
+  });
+});
+
+// ── Performance ──
+
+describe("performance", () => {
+  it("should handle 2000 tasks under 200ms", () => {
+    const tasks: Task[] = [];
+    for (let i = 0; i < 2000; i++) {
+      const id = String(i + 1).padStart(4, "0");
+      const deps = i > 0 && i % 10 === 0 ? [String(i).padStart(4, "0")] : [];
+      tasks.push(
+        t({
+          id,
+          title: `Task ${id}`,
+          priority: (i % 10) + 1,
+          status: i < 100 ? "Done" : "Todo",
+          dependencies: deps,
+        }),
+      );
+    }
+
+    const start = performance.now();
+    const cycles = detectCycles(tasks);
+    const recs = recommend(tasks, { limit: 10 });
+    const elapsed = performance.now() - start;
+
+    expect(cycles).toHaveLength(0);
+    expect(recs.length).toBeGreaterThan(0);
+    expect(elapsed).toBeLessThan(200);
+  });
+});

package/src/features/taskflow/lib/__tests__/repository.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {
+  ensureRepo,
+  createTask,
+  readTask,
+  listTasks,
+  updateTask,
+  deleteTask,
+  searchTasks,
+} from "../repository";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "taskflow-test-"));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("ensureRepo", () => {
+  it("should create all required directories", async () => {
+    await ensureRepo(tmpDir);
+
+    const dirs = ["tasks", "index", "logs", "cache"];
+    for (const dir of dirs) {
+      const stat = await fs.stat(path.join(tmpDir, ".taskflow", dir));
+      expect(stat.isDirectory()).toBe(true);
+    }
+  });
+
+  it("should be idempotent", async () => {
+    await ensureRepo(tmpDir);
+    await ensureRepo(tmpDir);
+
+    const stat = await fs.stat(path.join(tmpDir, ".taskflow", "tasks"));
+    expect(stat.isDirectory()).toBe(true);
+  });
+});
+
+describe("createTask", () => {
+  it("should create a task file and return the task", async () => {
+    const task = await createTask(tmpDir, { title: "First task" });
+
+    expect(task.id).toBe("001");
+    expect(task.title).toBe("First task");
+    expect(task.status).toBe("Todo");
+    expect(task.priority).toBe(0);
+  });
+
+  it("should auto-increment IDs", async () => {
+    const t1 = await createTask(tmpDir, { title: "Task 1" });
+    const t2 = await createTask(tmpDir, { title: "Task 2" });
+
+    expect(t1.id).toBe("001");
+    expect(t2.id).toBe("002");
+  });
+
+  it("should rebuild TASKS.md index", async () => {
+    await createTask(tmpDir, { title: "Indexed task" });
+
+    const indexPath = path.join(tmpDir, ".taskflow", "index", "TASKS.md");
+    const content = await fs.readFile(indexPath, "utf-8");
+
+    expect(content).toContain("Indexed task");
+    expect(content).toContain("001");
+  });
+});
+
+describe("readTask", () => {
+  it("should read an existing task", async () => {
+    const created = await createTask(tmpDir, {
+      title: "Read me",
+      description: "Some description",
+    });
+    const task = await readTask(tmpDir, created.id);
+
+    expect(task).not.toBeNull();
+    expect(task!.title).toBe("Read me");
+    expect(task!.description).toBe("Some description");
+  });
+
+  it("should return null for non-existent task", async () => {
+    await ensureRepo(tmpDir);
+    const task = await readTask(tmpDir, "999");
+    expect(task).toBeNull();
+  });
+});
+
+describe("updateTask", () => {
+  it("should update task fields", async () => {
+    const created = await createTask(tmpDir, { title: "Original" });
+    const updated = await updateTask(tmpDir, created.id, {
+      title: "Updated",
+      status: "InProgress",
+    });
+
+    expect(updated.title).toBe("Updated");
+    expect(updated.status).toBe("InProgress");
+    expect(updated.createdAt).toBe(created.createdAt);
+    expect(updated.updatedAt).not.toBe(created.updatedAt);
+  });
+
+  it("should throw for non-existent task", async () => {
+    await ensureRepo(tmpDir);
+    await expect(
+      updateTask(tmpDir, "999", { title: "Nope" }),
+    ).rejects.toThrow("Task not found");
+  });
+
+  it("should preserve createdAt on update", async () => {
+    const created = await createTask(tmpDir, { title: "Keep date" });
+    const updated = await updateTask(tmpDir, created.id, { status: "Done" });
+
+    expect(updated.createdAt).toBe(created.createdAt);
+  });
+});
+
+describe("deleteTask", () => {
+  it("should remove the task file", async () => {
+    const created = await createTask(tmpDir, { title: "Delete me" });
+    const result = await deleteTask(tmpDir, created.id);
+
+    expect(result).toBe(true);
+    expect(await readTask(tmpDir, created.id)).toBeNull();
+  });
+
+  it("should return false for non-existent task", async () => {
+    await ensureRepo(tmpDir);
+    const result = await deleteTask(tmpDir, "999");
+    expect(result).toBe(false);
+  });
+
+  it("should update index after deletion", async () => {
+    await createTask(tmpDir, { title: "Task A" });
+    const taskB = await createTask(tmpDir, { title: "Task B" });
+    await deleteTask(tmpDir, taskB.id);
+
+    const indexPath = path.join(tmpDir, ".taskflow", "index", "TASKS.md");
+    const content = await fs.readFile(indexPath, "utf-8");
+
+    expect(content).toContain("Task A");
+    expect(content).not.toContain("Task B");
+  });
+});
+
+describe("listTasks", () => {
+  it("should list all tasks", async () => {
+    await createTask(tmpDir, { title: "A" });
+    await createTask(tmpDir, { title: "B" });
+    await createTask(tmpDir, { title: "C" });
+
+    const tasks = await listTasks(tmpDir);
+    expect(tasks).toHaveLength(3);
+  });
+
+  it("should filter by status", async () => {
+    await createTask(tmpDir, { title: "Todo task", status: "Todo" });
+    await createTask(tmpDir, { title: "Done task", status: "Done" });
+
+    const todoTasks = await listTasks(tmpDir, {
+      filter: { status: "Todo" },
+    });
+    expect(todoTasks).toHaveLength(1);
+    expect(todoTasks[0].title).toBe("Todo task");
+  });
+
+  it("should sort by priority descending", async () => {
+    await createTask(tmpDir, { title: "Low", priority: 1 });
+    await createTask(tmpDir, { title: "High", priority: 5 });
+    await createTask(tmpDir, { title: "Mid", priority: 3 });
+
+    const tasks = await listTasks(tmpDir, {
+      sortKey: "priority",
+      sortOrder: "desc",
+    });
+
+    expect(tasks[0].title).toBe("High");
+    expect(tasks[1].title).toBe("Mid");
+    expect(tasks[2].title).toBe("Low");
+  });
+});
+
+describe("searchTasks", () => {
+  it("should search by title", async () => {
+    await createTask(tmpDir, { title: "Setup database" });
+    await createTask(tmpDir, { title: "Write tests" });
+
+    const results = await searchTasks(tmpDir, "database");
+    expect(results).toHaveLength(1);
+    expect(results[0].title).toBe("Setup database");
+  });
+
+  it("should search by description", async () => {
+    await createTask(tmpDir, {
+      title: "Task",
+      description: "Configure PostgreSQL connection",
+    });
+
+    const results = await searchTasks(tmpDir, "postgresql");
+    expect(results).toHaveLength(1);
+  });
+
+  it("should be case-insensitive", async () => {
+    await createTask(tmpDir, { title: "UPPERCASE TASK" });
+
+    const results = await searchTasks(tmpDir, "uppercase");
+    expect(results).toHaveLength(1);
+  });
+});
+
+describe("atomic write integrity", () => {
+  it("should handle sequential writes without corruption", async () => {
+    await ensureRepo(tmpDir);
+
+    for (let i = 0; i < 10; i++) {
+      await createTask(tmpDir, { title: `Sequential task ${i}`, priority: i });
+    }
+
+    const allTasks = await listTasks(tmpDir);
+    expect(allTasks).toHaveLength(10);
+
+    for (const task of allTasks) {
+      const read = await readTask(tmpDir, task.id);
+      expect(read).not.toBeNull();
+      expect(read!.title).toBe(task.title);
+    }
+  });
+});