@task-mcp/shared 0.1.0

package/src/algorithms/topological-sort.ts

@@ -0,0 +1,204 @@
+import type { Task } from "../schemas/task.js";
+
+/**
+ * Node representation for graph algorithms
+ */
+export interface TaskNode {
+  id: string;
+  dependencies: string[]; // IDs of tasks this depends on (blocked_by)
+  priority: number; // Numeric priority for tie-breaking (higher = more important)
+  estimate: number; // Duration in minutes
+}
+
+/**
+ * Convert priority string to numeric value
+ */
+export function priorityToNumber(priority: string): number {
+  const map: Record<string, number> = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+  };
+  return map[priority] ?? 2;
+}
+
+/**
+ * Convert Task to TaskNode
+ */
+export function taskToNode(task: Task): TaskNode {
+  return {
+    id: task.id,
+    dependencies: (task.dependencies ?? [])
+      .filter((d) => d.type === "blocked_by")
+      .map((d) => d.taskId),
+    priority: priorityToNumber(task.priority),
+    estimate: task.estimate?.expected ?? 0,
+  };
+}
+
+/**
+ * Topological sort using Kahn's algorithm with priority tie-breaking
+ *
+ * Returns tasks in optimal execution order:
+ * 1. Respects dependencies (blocked_by relationships)
+ * 2. Higher priority tasks come first when dependencies allow
+ *
+ * @throws Error if circular dependency detected
+ */
+export function topologicalSort(tasks: Task[]): Task[] {
+  const nodes = tasks.map(taskToNode);
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+
+  // Calculate in-degree for each node
+  const inDegree = new Map<string, number>();
+  const adjacency = new Map<string, string[]>();
+
+  for (const node of nodes) {
+    inDegree.set(node.id, 0);
+    adjacency.set(node.id, []);
+  }
+
+  // Build graph: if A is blocked_by B, then B -> A (B must come before A)
+  for (const node of nodes) {
+    for (const depId of node.dependencies) {
+      if (nodeMap.has(depId)) {
+        const adj = adjacency.get(depId);
+        if (adj) adj.push(node.id);
+        inDegree.set(node.id, (inDegree.get(node.id) ?? 0) + 1);
+      }
+    }
+  }
+
+  // Initialize queue with nodes that have no dependencies
+  const queue: TaskNode[] = [];
+  for (const node of nodes) {
+    if (inDegree.get(node.id) === 0) {
+      queue.push(node);
+    }
+  }
+
+  // Sort by priority (higher first)
+  queue.sort((a, b) => b.priority - a.priority);
+
+  const result: Task[] = [];
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    const task = taskMap.get(current.id);
+    if (task) {
+      result.push(task);
+    }
+
+    // Update neighbors
+    for (const neighborId of adjacency.get(current.id)!) {
+      const newDegree = inDegree.get(neighborId)! - 1;
+      inDegree.set(neighborId, newDegree);
+
+      if (newDegree === 0) {
+        const neighborNode = nodeMap.get(neighborId)!;
+        queue.push(neighborNode);
+        // Re-sort to maintain priority order
+        queue.sort((a, b) => b.priority - a.priority);
+      }
+    }
+  }
+
+  // Check for cycles
+  if (result.length !== tasks.length) {
+    const remaining = tasks.filter((t) => !result.some((r) => r.id === t.id));
+    const cycleIds = remaining.map((t) => t.id).join(", ");
+    throw new Error(`Circular dependency detected among tasks: ${cycleIds}`);
+  }
+
+  return result;
+}
+
+/**
+ * Detect if adding a dependency would create a cycle
+ */
+export function wouldCreateCycle(
+  tasks: Task[],
+  fromId: string,
+  toId: string
+): boolean {
+  // Create a temporary task list with the new dependency
+  const tempTasks = tasks.map((t) => {
+    if (t.id === fromId) {
+      return {
+        ...t,
+        dependencies: [
+          ...(t.dependencies ?? []),
+          { taskId: toId, type: "blocked_by" as const },
+        ],
+      };
+    }
+    return t;
+  });
+
+  try {
+    topologicalSort(tempTasks);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Find all tasks that depend on a given task (directly or transitively)
+ */
+export function findDependents(tasks: Task[], taskId: string): Task[] {
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+  const visited = new Set<string>();
+  const result: Task[] = [];
+
+  function dfs(id: string) {
+    for (const task of tasks) {
+      const deps = (task.dependencies ?? [])
+        .filter((d) => d.type === "blocked_by")
+        .map((d) => d.taskId);
+
+      if (deps.includes(id) && !visited.has(task.id)) {
+        visited.add(task.id);
+        result.push(task);
+        dfs(task.id);
+      }
+    }
+  }
+
+  dfs(taskId);
+  return result;
+}
+
+/**
+ * Find all tasks that a given task depends on (directly or transitively)
+ */
+export function findDependencies(tasks: Task[], taskId: string): Task[] {
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+  const visited = new Set<string>();
+  const result: Task[] = [];
+
+  function dfs(id: string) {
+    const task = taskMap.get(id);
+    if (!task) return;
+
+    const deps = (task.dependencies ?? [])
+      .filter((d) => d.type === "blocked_by")
+      .map((d) => d.taskId);
+
+    for (const depId of deps) {
+      if (!visited.has(depId)) {
+        visited.add(depId);
+        const depTask = taskMap.get(depId);
+        if (depTask) {
+          result.push(depTask);
+          dfs(depId);
+        }
+      }
+    }
+  }
+
+  dfs(taskId);
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// Schemas
+export * from "./schemas/index.js";
+
+// Algorithms
+export * from "./algorithms/index.js";
+
+// Utilities
+export * from "./utils/index.js";

package/src/schemas/index.ts

@@ -0,0 +1,30 @@
+// Task schemas
+export {
+  Priority,
+  TaskStatus,
+  DependencyType,
+  Dependency,
+  TimeEstimate,
+  Recurrence,
+  Task,
+  TaskCreateInput,
+  TaskUpdateInput,
+} from "./task.js";
+
+// Project schemas
+export {
+  ProjectStatus,
+  Context,
+  Project,
+  ProjectCreateInput,
+  ProjectUpdateInput,
+} from "./project.js";
+
+// View schemas
+export {
+  SmartViewFilter,
+  SortField,
+  SortOrder,
+  SmartView,
+  BuiltInView,
+} from "./view.js";

package/src/schemas/project.ts

@@ -0,0 +1,62 @@
+import { type } from "arktype";
+import { Priority } from "./task.js";
+
+// Project status
+export const ProjectStatus = type(
+  "'active' | 'on_hold' | 'completed' | 'archived'"
+);
+export type ProjectStatus = typeof ProjectStatus.infer;
+
+// Context definition
+export const Context = type({
+  name: "string",
+  "color?": "string", // hex color
+  "description?": "string",
+});
+export type Context = typeof Context.infer;
+
+// Project schema
+export const Project = type({
+  id: "string",
+  name: "string",
+  "description?": "string",
+  status: ProjectStatus,
+
+  // Project-level settings
+  "defaultPriority?": Priority,
+  "contexts?": Context.array(),
+
+  // Metadata
+  createdAt: "string",
+  updatedAt: "string",
+  "targetDate?": "string",
+
+  // Computed stats
+  "completionPercentage?": "number",
+  "criticalPathLength?": "number", // Total minutes on critical path
+  "blockedTaskCount?": "number",
+  "totalTasks?": "number",
+  "completedTasks?": "number",
+});
+export type Project = typeof Project.infer;
+
+// Project creation input
+export const ProjectCreateInput = type({
+  name: "string",
+  "description?": "string",
+  "defaultPriority?": Priority,
+  "contexts?": Context.array(),
+  "targetDate?": "string",
+});
+export type ProjectCreateInput = typeof ProjectCreateInput.infer;
+
+// Project update input
+export const ProjectUpdateInput = type({
+  "name?": "string",
+  "description?": "string",
+  "status?": ProjectStatus,
+  "defaultPriority?": Priority,
+  "contexts?": Context.array(),
+  "targetDate?": "string",
+});
+export type ProjectUpdateInput = typeof ProjectUpdateInput.infer;

package/src/schemas/task.ts

@@ -0,0 +1,116 @@
+import { type } from "arktype";
+
+// Priority levels
+export const Priority = type("'critical' | 'high' | 'medium' | 'low'");
+export type Priority = typeof Priority.infer;
+
+// Task status with clear state machine
+export const TaskStatus = type(
+  "'pending' | 'in_progress' | 'blocked' | 'completed' | 'cancelled'"
+);
+export type TaskStatus = typeof TaskStatus.infer;
+
+// Dependency relationship types
+export const DependencyType = type(
+  "'blocks' | 'blocked_by' | 'related'"
+);
+export type DependencyType = typeof DependencyType.infer;
+
+// A single dependency link
+export const Dependency = type({
+  taskId: "string",
+  type: DependencyType,
+  "reason?": "string",
+});
+export type Dependency = typeof Dependency.infer;
+
+// Time estimation
+export const TimeEstimate = type({
+  "optimistic?": "number", // minutes
+  "expected?": "number", // minutes
+  "pessimistic?": "number", // minutes
+  "confidence?": "'low' | 'medium' | 'high'",
+});
+export type TimeEstimate = typeof TimeEstimate.infer;
+
+// Recurrence pattern
+export const Recurrence = type({
+  pattern: "'daily' | 'weekly' | 'monthly' | 'after_completion'",
+  "interval?": "number", // every N days/weeks/months
+  "daysOfWeek?": "number[]", // 0-6 for weekly
+  "endDate?": "string",
+});
+export type Recurrence = typeof Recurrence.infer;
+
+// Core Task schema
+export const Task = type({
+  id: "string",
+  title: "string",
+  "description?": "string",
+  status: TaskStatus,
+  priority: Priority,
+  projectId: "string",
+
+  // Dependencies
+  "dependencies?": Dependency.array(),
+
+  // Time tracking
+  "estimate?": TimeEstimate,
+  "actualMinutes?": "number",
+  "dueDate?": "string", // ISO date string
+  "startDate?": "string", // When task can start
+  "startedAt?": "string",
+  "completedAt?": "string",
+
+  // Organization
+  "contexts?": "string[]", // e.g., ["focus", "review"]
+  "tags?": "string[]",
+
+  // Recurrence
+  "recurrence?": Recurrence,
+
+  // Metadata
+  createdAt: "string",
+  updatedAt: "string",
+
+  // Computed fields (populated at runtime)
+  "criticalPath?": "boolean",
+  "slack?": "number", // Minutes of slack time
+  "earliestStart?": "number", // Minutes from project start
+  "latestStart?": "number",
+});
+export type Task = typeof Task.infer;
+
+// Task creation input (minimal required fields)
+export const TaskCreateInput = type({
+  title: "string",
+  "description?": "string",
+  "projectId?": "string",
+  "priority?": Priority,
+  "dependencies?": Dependency.array(),
+  "estimate?": TimeEstimate,
+  "dueDate?": "string",
+  "startDate?": "string",
+  "contexts?": "string[]",
+  "tags?": "string[]",
+  "recurrence?": Recurrence,
+});
+export type TaskCreateInput = typeof TaskCreateInput.infer;
+
+// Task update input
+export const TaskUpdateInput = type({
+  "title?": "string",
+  "description?": "string",
+  "status?": TaskStatus,
+  "priority?": Priority,
+  "projectId?": "string",
+  "dependencies?": Dependency.array(),
+  "estimate?": TimeEstimate,
+  "actualMinutes?": "number",
+  "dueDate?": "string",
+  "startDate?": "string",
+  "contexts?": "string[]",
+  "tags?": "string[]",
+  "recurrence?": Recurrence,
+});
+export type TaskUpdateInput = typeof TaskUpdateInput.infer;

package/src/schemas/view.ts

@@ -0,0 +1,46 @@
+import { type } from "arktype";
+import { Priority, TaskStatus } from "./task.js";
+
+// Smart View filter
+export const SmartViewFilter = type({
+  "statuses?": TaskStatus.array(),
+  "priorities?": Priority.array(),
+  "contexts?": "string[]",
+  "tags?": "string[]",
+  "projectIds?": "string[]",
+  "dueBefore?": "string",
+  "dueAfter?": "string",
+  "isBlocked?": "boolean",
+  "isCriticalPath?": "boolean",
+  "hasNoDependencies?": "boolean",
+  "search?": "string", // Search in title/description
+});
+export type SmartViewFilter = typeof SmartViewFilter.infer;
+
+// Sort options
+export const SortField = type(
+  "'priority' | 'dueDate' | 'createdAt' | 'criticalPath' | 'slack' | 'title'"
+);
+export type SortField = typeof SortField.infer;
+
+export const SortOrder = type("'asc' | 'desc'");
+export type SortOrder = typeof SortOrder.infer;
+
+// Smart View definition
+export const SmartView = type({
+  id: "string",
+  name: "string",
+  "description?": "string",
+  filter: SmartViewFilter,
+  "sortBy?": SortField,
+  "sortOrder?": SortOrder,
+  createdAt: "string",
+  updatedAt: "string",
+});
+export type SmartView = typeof SmartView.infer;
+
+// Built-in view names
+export const BuiltInView = type(
+  "'today' | 'this_week' | 'blocked' | 'critical_path' | 'quick_wins' | 'all'"
+);
+export type BuiltInView = typeof BuiltInView.infer;

package/src/utils/date.test.ts

@@ -0,0 +1,160 @@
+import { describe, test, expect } from "bun:test";
+import { now, parseRelativeDate, formatDate, isToday, isPastDue, isWithinDays } from "./date.js";
+
+describe("now", () => {
+  test("returns ISO timestamp string", () => {
+    const result = now();
+    expect(typeof result).toBe("string");
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+  });
+
+  test("returns current time within tolerance", () => {
+    const before = Date.now();
+    const result = now();
+    const after = Date.now();
+
+    const resultTime = new Date(result).getTime();
+    expect(resultTime).toBeGreaterThanOrEqual(before);
+    expect(resultTime).toBeLessThanOrEqual(after);
+  });
+});
+
+describe("parseRelativeDate", () => {
+  test("parses 'today'", () => {
+    const result = parseRelativeDate("today");
+    expect(result).not.toBeNull();
+    const today = new Date();
+    expect(result!.getDate()).toBe(today.getDate());
+  });
+
+  test("parses '오늘' (Korean today)", () => {
+    const result = parseRelativeDate("오늘");
+    expect(result).not.toBeNull();
+    const today = new Date();
+    expect(result!.getDate()).toBe(today.getDate());
+  });
+
+  test("parses 'tomorrow'", () => {
+    const result = parseRelativeDate("tomorrow");
+    expect(result).not.toBeNull();
+    const tomorrow = new Date();
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    expect(result!.getDate()).toBe(tomorrow.getDate());
+  });
+
+  test("parses '내일' (Korean tomorrow)", () => {
+    const result = parseRelativeDate("내일");
+    expect(result).not.toBeNull();
+    const tomorrow = new Date();
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    expect(result!.getDate()).toBe(tomorrow.getDate());
+  });
+
+  test("parses 'yesterday'", () => {
+    const result = parseRelativeDate("yesterday");
+    expect(result).not.toBeNull();
+    const yesterday = new Date();
+    yesterday.setDate(yesterday.getDate() - 1);
+    expect(result!.getDate()).toBe(yesterday.getDate());
+  });
+
+  test("parses 'next week'", () => {
+    const result = parseRelativeDate("next week");
+    expect(result).not.toBeNull();
+    const nextWeek = new Date();
+    nextWeek.setDate(nextWeek.getDate() + 7);
+    expect(result!.getDate()).toBe(nextWeek.getDate());
+  });
+
+  test("parses 'in 3 days'", () => {
+    const result = parseRelativeDate("in 3 days");
+    expect(result).not.toBeNull();
+    const future = new Date();
+    future.setDate(future.getDate() + 3);
+    expect(result!.getDate()).toBe(future.getDate());
+  });
+
+  test("parses '5일 후' (Korean days later)", () => {
+    const result = parseRelativeDate("5일 후");
+    expect(result).not.toBeNull();
+    const future = new Date();
+    future.setDate(future.getDate() + 5);
+    expect(result!.getDate()).toBe(future.getDate());
+  });
+
+  test("parses weekday names", () => {
+    const result = parseRelativeDate("monday");
+    expect(result).not.toBeNull();
+    expect(result!.getDay()).toBe(1); // Monday = 1
+  });
+
+  test("parses ISO date string", () => {
+    const result = parseRelativeDate("2025-12-31");
+    expect(result).not.toBeNull();
+    expect(result!.getFullYear()).toBe(2025);
+    expect(result!.getMonth()).toBe(11); // December = 11
+    expect(result!.getDate()).toBe(31);
+  });
+
+  test("returns null for invalid input", () => {
+    const result = parseRelativeDate("invalid date string");
+    expect(result).toBeNull();
+  });
+});
+
+describe("formatDate", () => {
+  test("formats date as YYYY-MM-DD", () => {
+    const date = new Date("2025-06-15T10:30:00");
+    expect(formatDate(date)).toBe("2025-06-15");
+  });
+});
+
+describe("isToday", () => {
+  test("returns true for today", () => {
+    expect(isToday(new Date())).toBe(true);
+  });
+
+  test("returns false for tomorrow", () => {
+    const tomorrow = new Date();
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    expect(isToday(tomorrow)).toBe(false);
+  });
+
+  test("accepts string input", () => {
+    expect(isToday(new Date().toISOString())).toBe(true);
+  });
+});
+
+describe("isPastDue", () => {
+  test("returns true for yesterday", () => {
+    const yesterday = new Date();
+    yesterday.setDate(yesterday.getDate() - 1);
+    expect(isPastDue(yesterday)).toBe(true);
+  });
+
+  test("returns false for tomorrow", () => {
+    const tomorrow = new Date();
+    tomorrow.setDate(tomorrow.getDate() + 1);
+    expect(isPastDue(tomorrow)).toBe(false);
+  });
+});
+
+describe("isWithinDays", () => {
+  test("returns true for date within range", () => {
+    const inThreeDays = new Date();
+    inThreeDays.setDate(inThreeDays.getDate() + 3);
+    expect(isWithinDays(inThreeDays, 7)).toBe(true);
+  });
+
+  test("returns false for date outside range", () => {
+    const inTenDays = new Date();
+    inTenDays.setDate(inTenDays.getDate() + 10);
+    expect(isWithinDays(inTenDays, 7)).toBe(false);
+  });
+
+  test("returns false for past date", () => {
+    const yesterday = new Date();
+    yesterday.setDate(yesterday.getDate() - 1);
+    expect(isWithinDays(yesterday, 7)).toBe(false);
+  });
+});