@task-mcp/shared 1.0.3 → 1.0.6

package/src/schemas/task.ts

@@ -42,6 +42,43 @@ export const Recurrence = type({
 });
 export type Recurrence = typeof Recurrence.infer;
 
+// Complexity factors that contribute to task difficulty
+export const ComplexityFactor = type(
+  "'cross_cutting' | 'state_management' | 'error_handling' | 'performance' | 'security' | 'external_dependency' | 'data_migration' | 'breaking_change' | 'unclear_requirements' | 'coordination'"
+);
+export type ComplexityFactor = typeof ComplexityFactor.infer;
+
+// Complexity analysis result (populated by Claude)
+export const ComplexityAnalysis = type({
+  "score?": "number", // 1-10 complexity score
+  "factors?": ComplexityFactor.array(),
+  "suggestedSubtasks?": "number", // 0-10 recommended subtask count
+  "rationale?": "string",
+  "analyzedAt?": "string",
+});
+export type ComplexityAnalysis = typeof ComplexityAnalysis.infer;
+
+// Tech area categories for ordering
+export const TechArea = type(
+  "'schema' | 'backend' | 'frontend' | 'infra' | 'devops' | 'test' | 'docs' | 'refactor'"
+);
+export type TechArea = typeof TechArea.infer;
+
+// Risk level for changes
+export const RiskLevel = type("'low' | 'medium' | 'high' | 'critical'");
+export type RiskLevel = typeof RiskLevel.infer;
+
+// Tech stack analysis result (populated by Claude)
+export const TechStackAnalysis = type({
+  "areas?": TechArea.array(),
+  "hasBreakingChange?": "boolean",
+  "riskLevel?": RiskLevel,
+  "affectedComponents?": "string[]",
+  "rationale?": "string",
+  "analyzedAt?": "string",
+});
+export type TechStackAnalysis = typeof TechStackAnalysis.infer;
+
 // Core Task schema
 export const Task = type({
   id: "string",
@@ -51,6 +88,10 @@ export const Task = type({
   priority: Priority,
   projectId: "string",
 
+  // Hierarchy (subtask support)
+  "parentId?": "string", // Parent task ID for subtasks
+  "level?": "number", // Hierarchy depth (0=root, 1=subtask, 2=sub-subtask, max 3)
+
   // Dependencies
   "dependencies?": Dependency.array(),
 
@@ -78,6 +119,10 @@ export const Task = type({
   "slack?": "number", // Minutes of slack time
   "earliestStart?": "number", // Minutes from project start
   "latestStart?": "number",
+
+  // Analysis fields (populated by Claude)
+  "complexity?": ComplexityAnalysis,
+  "techStack?": TechStackAnalysis,
 });
 export type Task = typeof Task.infer;
 
@@ -87,6 +132,7 @@ export const TaskCreateInput = type({
   "description?": "string",
   "projectId?": "string",
   "priority?": Priority,
+  "parentId?": "string", // Parent task ID for creating subtasks
   "dependencies?": Dependency.array(),
   "estimate?": TimeEstimate,
   "dueDate?": "string",
@@ -104,6 +150,7 @@ export const TaskUpdateInput = type({
   "status?": TaskStatus,
   "priority?": Priority,
   "projectId?": "string",
+  "parentId?": "string", // Parent task ID for moving task in hierarchy
   "dependencies?": Dependency.array(),
   "estimate?": TimeEstimate,
   "actualMinutes?": "number",
@@ -112,5 +159,8 @@ export const TaskUpdateInput = type({
   "contexts?": "string[]",
   "tags?": "string[]",
   "recurrence?": Recurrence,
+  // Analysis fields
+  "complexity?": ComplexityAnalysis,
+  "techStack?": TechStackAnalysis,
 });
 export type TaskUpdateInput = typeof TaskUpdateInput.infer;

package/src/utils/date.ts

@@ -67,10 +67,26 @@ export function parseRelativeDate(input: string): Date | null {
     return d;
   }
 
-  // Try parsing as ISO date
+  // Try parsing as YYYY-MM-DD format (local timezone, no UTC shift)
+  const isoDateMatch = input.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (isoDateMatch) {
+    const [, yearStr, monthStr, dayStr] = isoDateMatch;
+    const year = parseInt(yearStr!, 10);
+    const month = parseInt(monthStr!, 10) - 1; // 0-indexed
+    const day = parseInt(dayStr!, 10);
+    const d = new Date(year, month, day);
+    // Validate the date is valid (e.g., not Feb 30)
+    if (d.getFullYear() === year && d.getMonth() === month && d.getDate() === day) {
+      return d;
+    }
+  }
+
+  // Try parsing other date formats (fallback)
   const parsed = new Date(input);
   if (!isNaN(parsed.getTime())) {
-    return parsed;
+    // For non-YYYY-MM-DD formats, normalize to local midnight
+    const d = new Date(parsed.getFullYear(), parsed.getMonth(), parsed.getDate());
+    return d;
   }
 
   return null;

package/src/utils/hierarchy.ts

@@ -0,0 +1,224 @@
+import type { Task } from "../schemas/task.js";
+
+/**
+ * Maximum allowed hierarchy depth (0-indexed)
+ * 0 = root task
+ * 1 = subtask
+ * 2 = sub-subtask
+ * 3 = sub-sub-subtask (maximum)
+ */
+export const MAX_HIERARCHY_DEPTH = 3;
+
+/**
+ * Calculates the hierarchy level of a task.
+ * Level 0 = root task (no parent)
+ * Level 1 = direct subtask
+ * Level 2 = sub-subtask
+ * etc.
+ *
+ * @param tasks - Array of all tasks
+ * @param taskId - ID of the task to get level for
+ * @returns The hierarchy level (0 for root), or -1 if task not found
+ */
+export function getTaskLevel(tasks: Task[], taskId: string): number {
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+  const task = taskMap.get(taskId);
+
+  if (!task) {
+    return -1;
+  }
+
+  let level = 0;
+  let currentTask = task;
+
+  while (currentTask.parentId) {
+    const parent = taskMap.get(currentTask.parentId);
+    if (!parent) {
+      break; // Parent not found, stop traversal
+    }
+    level++;
+    currentTask = parent;
+
+    // Safety check to prevent infinite loops
+    if (level > MAX_HIERARCHY_DEPTH + 1) {
+      break;
+    }
+  }
+
+  return level;
+}
+
+/**
+ * Validates whether adding a child task under the given parent
+ * would exceed the maximum hierarchy depth.
+ *
+ * @param tasks - Array of all tasks
+ * @param parentId - ID of the proposed parent task
+ * @returns true if a child can be added, false if it would exceed max depth
+ */
+export function validateHierarchyDepth(
+  tasks: Task[],
+  parentId: string
+): boolean {
+  const parentLevel = getTaskLevel(tasks, parentId);
+
+  if (parentLevel === -1) {
+    return false; // Parent task not found
+  }
+
+  // Child would be at parentLevel + 1
+  // If parent is at level 3, child would be at level 4 which exceeds max
+  return parentLevel < MAX_HIERARCHY_DEPTH;
+}
+
+/**
+ * Gets all ancestor task IDs for a given task (from immediate parent to root).
+ *
+ * @param tasks - Array of all tasks
+ * @param taskId - ID of the task
+ * @returns Array of ancestor task IDs, ordered from immediate parent to root
+ */
+export function getAncestorIds(tasks: Task[], taskId: string): string[] {
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+  const task = taskMap.get(taskId);
+
+  if (!task) {
+    return [];
+  }
+
+  const ancestors: string[] = [];
+  let currentTask = task;
+
+  while (currentTask.parentId) {
+    ancestors.push(currentTask.parentId);
+    const parent = taskMap.get(currentTask.parentId);
+    if (!parent) {
+      break;
+    }
+    currentTask = parent;
+
+    // Safety check
+    if (ancestors.length > MAX_HIERARCHY_DEPTH + 1) {
+      break;
+    }
+  }
+
+  return ancestors;
+}
+
+/**
+ * Gets all descendant task IDs for a given task (children, grandchildren, etc.).
+ *
+ * @param tasks - Array of all tasks
+ * @param taskId - ID of the parent task
+ * @returns Array of descendant task IDs
+ */
+export function getDescendantIds(tasks: Task[], taskId: string): string[] {
+  const descendants: string[] = [];
+  const childrenMap = new Map<string, Task[]>();
+
+  // Build parent -> children map
+  for (const task of tasks) {
+    if (task.parentId) {
+      const children = childrenMap.get(task.parentId) || [];
+      children.push(task);
+      childrenMap.set(task.parentId, children);
+    }
+  }
+
+  // BFS to collect all descendants
+  const queue = [taskId];
+  while (queue.length > 0) {
+    const currentId = queue.shift()!;
+    const children = childrenMap.get(currentId) || [];
+    for (const child of children) {
+      descendants.push(child.id);
+      queue.push(child.id);
+    }
+  }
+
+  return descendants;
+}
+
+/**
+ * Gets direct children of a task.
+ *
+ * @param tasks - Array of all tasks
+ * @param taskId - ID of the parent task
+ * @returns Array of direct child tasks
+ */
+export function getChildTasks(tasks: Task[], taskId: string): Task[] {
+  return tasks.filter((t) => t.parentId === taskId);
+}
+
+/**
+ * Gets the root task of a hierarchy.
+ *
+ * @param tasks - Array of all tasks
+ * @param taskId - ID of any task in the hierarchy
+ * @returns The root task, or null if not found
+ */
+export function getRootTask(tasks: Task[], taskId: string): Task | null {
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+  let currentTask = taskMap.get(taskId);
+
+  if (!currentTask) {
+    return null;
+  }
+
+  while (currentTask.parentId) {
+    const parent = taskMap.get(currentTask.parentId);
+    if (!parent) {
+      break;
+    }
+    currentTask = parent;
+  }
+
+  return currentTask;
+}
+
+/**
+ * Builds a tree structure from flat task list.
+ *
+ * @param tasks - Array of all tasks
+ * @param rootId - Optional root task ID (if not provided, returns all root tasks)
+ * @returns Tree structure with children arrays
+ */
+export interface TaskTreeNode {
+  task: Task;
+  children: TaskTreeNode[];
+}
+
+export function buildTaskTree(tasks: Task[], rootId?: string): TaskTreeNode[] {
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+  const childrenMap = new Map<string, Task[]>();
+
+  // Build parent -> children map
+  for (const task of tasks) {
+    if (task.parentId) {
+      const children = childrenMap.get(task.parentId) || [];
+      children.push(task);
+      childrenMap.set(task.parentId, children);
+    }
+  }
+
+  function buildNode(task: Task): TaskTreeNode {
+    const children = childrenMap.get(task.id) || [];
+    return {
+      task,
+      children: children.map(buildNode),
+    };
+  }
+
+  if (rootId) {
+    const rootTask = taskMap.get(rootId);
+    if (!rootTask) {
+      return [];
+    }
+    return [buildNode(rootTask)];
+  }
+
+  // Return all root tasks (no parent)
+  const rootTasks = tasks.filter((t) => !t.parentId);
+  return rootTasks.map(buildNode);
+}

package/src/utils/id.test.ts

@@ -0,0 +1,281 @@
+import { describe, test, expect } from "bun:test";
+import {
+  generateId,
+  generateTaskId,
+  generateProjectId,
+  generateInboxId,
+  isValidTaskId,
+  isValidProjectId,
+  isValidInboxId,
+  validateTaskId,
+  validateProjectId,
+  validateInboxId,
+  assertValidTaskId,
+  assertValidProjectId,
+  assertValidInboxId,
+  InvalidIdError,
+} from "./id.js";
+
+describe("ID Generation", () => {
+  describe("generateId", () => {
+    test("generates ID without prefix", () => {
+      const id = generateId();
+      expect(id.length).toBe(12);
+      expect(/^[a-z0-9]+$/.test(id)).toBe(true);
+    });
+
+    test("generates ID with prefix", () => {
+      const id = generateId("test");
+      expect(id).toMatch(/^test_[a-z0-9]+$/);
+    });
+
+    test("generates unique IDs", () => {
+      const ids = new Set(Array.from({ length: 100 }, () => generateId("test")));
+      expect(ids.size).toBe(100);
+    });
+  });
+
+  describe("generateTaskId", () => {
+    test("generates task ID with correct prefix", () => {
+      const id = generateTaskId();
+      expect(id).toMatch(/^task_[a-z0-9]+$/);
+    });
+  });
+
+  describe("generateProjectId", () => {
+    test("generates project ID with correct prefix", () => {
+      const id = generateProjectId();
+      expect(id).toMatch(/^proj_[a-z0-9]+$/);
+    });
+  });
+
+  describe("generateInboxId", () => {
+    test("generates inbox ID with correct prefix", () => {
+      const id = generateInboxId();
+      expect(id).toMatch(/^inbox_[a-z0-9]+$/);
+    });
+  });
+});
+
+describe("Simple ID Validation (boolean)", () => {
+  describe("isValidTaskId", () => {
+    test("returns true for valid task IDs", () => {
+      expect(isValidTaskId("task_abc123")).toBe(true);
+      expect(isValidTaskId("task_a")).toBe(true);
+      expect(isValidTaskId("task_123")).toBe(true);
+      expect(isValidTaskId("task_abc123def456")).toBe(true);
+    });
+
+    test("returns false for invalid task IDs", () => {
+      expect(isValidTaskId("")).toBe(false);
+      expect(isValidTaskId("task_")).toBe(false);
+      expect(isValidTaskId("abc123")).toBe(false);
+      expect(isValidTaskId("proj_abc123")).toBe(false);
+      expect(isValidTaskId("task_ABC123")).toBe(false);
+      expect(isValidTaskId("task_abc-123")).toBe(false);
+      expect(isValidTaskId("task_abc.123")).toBe(false);
+      expect(isValidTaskId("task_abc/123")).toBe(false);
+      expect(isValidTaskId("task_abc 123")).toBe(false);
+    });
+  });
+
+  describe("isValidProjectId", () => {
+    test("returns true for valid project IDs", () => {
+      expect(isValidProjectId("proj_abc123")).toBe(true);
+      expect(isValidProjectId("proj_a")).toBe(true);
+    });
+
+    test("returns false for invalid project IDs", () => {
+      expect(isValidProjectId("")).toBe(false);
+      expect(isValidProjectId("project_abc123")).toBe(false);
+      expect(isValidProjectId("task_abc123")).toBe(false);
+    });
+  });
+
+  describe("isValidInboxId", () => {
+    test("returns true for valid inbox IDs", () => {
+      expect(isValidInboxId("inbox_abc123")).toBe(true);
+      expect(isValidInboxId("inbox_a")).toBe(true);
+    });
+
+    test("returns false for invalid inbox IDs", () => {
+      expect(isValidInboxId("")).toBe(false);
+      expect(isValidInboxId("in_abc123")).toBe(false);
+      expect(isValidInboxId("task_abc123")).toBe(false);
+    });
+  });
+});
+
+describe("Detailed ID Validation", () => {
+  describe("validateTaskId", () => {
+    test("returns valid: true for valid task IDs", () => {
+      expect(validateTaskId("task_abc123")).toEqual({ valid: true });
+      expect(validateTaskId("task_a1b2c3")).toEqual({ valid: true });
+    });
+
+    test("returns error for null/undefined", () => {
+      const result = validateTaskId(null);
+      expect(result.valid).toBe(false);
+      expect(result.reason).toContain("required");
+
+      const result2 = validateTaskId(undefined);
+      expect(result2.valid).toBe(false);
+    });
+
+    test("returns error for non-string", () => {
+      const result = validateTaskId(123);
+      expect(result.valid).toBe(false);
+      expect(result.reason).toContain("string");
+      expect(result.reason).toContain("number");
+    });
+
+    test("returns error for empty string", () => {
+      const result = validateTaskId("");
+      expect(result.valid).toBe(false);
+      expect(result.reason).toContain("empty");
+    });
+
+    test("returns error for missing prefix", () => {
+      const result = validateTaskId("abc123");
+      expect(result.valid).toBe(false);
+      expect(result.reason).toContain("task_");
+    });
+
+    test("returns error for wrong prefix", () => {
+      const result = validateTaskId("proj_abc123");
+      expect(result.valid).toBe(false);
+      expect(result.reason).toContain("task_");
+    });
+
+    test("returns error for invalid characters", () => {
+      const result = validateTaskId("task_abc-123");
+      expect(result.valid).toBe(false);
+      expect(result.reason).toContain("invalid characters");
+    });
+  });
+
+  describe("validateProjectId", () => {
+    test("returns valid: true for valid project IDs", () => {
+      expect(validateProjectId("proj_abc123")).toEqual({ valid: true });
+    });
+
+    test("returns error for missing prefix", () => {
+      const result = validateProjectId("project_abc");
+      expect(result.valid).toBe(false);
+      expect(result.reason).toContain("proj_");
+    });
+  });
+
+  describe("validateInboxId", () => {
+    test("returns valid: true for valid inbox IDs", () => {
+      expect(validateInboxId("inbox_abc123")).toEqual({ valid: true });
+    });
+
+    test("returns error for missing prefix", () => {
+      const result = validateInboxId("in_abc");
+      expect(result.valid).toBe(false);
+      expect(result.reason).toContain("inbox_");
+    });
+  });
+});
+
+describe("Assert Functions", () => {
+  describe("assertValidTaskId", () => {
+    test("does not throw for valid ID", () => {
+      expect(() => assertValidTaskId("task_abc123")).not.toThrow();
+    });
+
+    test("throws InvalidIdError for invalid ID", () => {
+      expect(() => assertValidTaskId("")).toThrow(InvalidIdError);
+      expect(() => assertValidTaskId("abc123")).toThrow(InvalidIdError);
+      expect(() => assertValidTaskId(null)).toThrow(InvalidIdError);
+    });
+
+    test("InvalidIdError contains correct properties", () => {
+      try {
+        assertValidTaskId("invalid");
+      } catch (error) {
+        expect(error).toBeInstanceOf(InvalidIdError);
+        if (error instanceof InvalidIdError) {
+          expect(error.idType).toBe("task");
+          expect(error.invalidValue).toBe("invalid");
+          expect(error.reason).toBeDefined();
+          expect(error.message).toContain("task");
+        }
+      }
+    });
+  });
+
+  describe("assertValidProjectId", () => {
+    test("does not throw for valid ID", () => {
+      expect(() => assertValidProjectId("proj_abc123")).not.toThrow();
+    });
+
+    test("throws InvalidIdError for invalid ID", () => {
+      expect(() => assertValidProjectId("project_abc")).toThrow(InvalidIdError);
+    });
+  });
+
+  describe("assertValidInboxId", () => {
+    test("does not throw for valid ID", () => {
+      expect(() => assertValidInboxId("inbox_abc123")).not.toThrow();
+    });
+
+    test("throws InvalidIdError for invalid ID", () => {
+      expect(() => assertValidInboxId("in_abc")).toThrow(InvalidIdError);
+    });
+  });
+});
+
+describe("InvalidIdError", () => {
+  test("extends Error", () => {
+    const error = new InvalidIdError("task", "bad_id", "test reason");
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(InvalidIdError);
+  });
+
+  test("has correct name", () => {
+    const error = new InvalidIdError("task", "bad_id", "test reason");
+    expect(error.name).toBe("InvalidIdError");
+  });
+
+  test("has correct message format", () => {
+    const error = new InvalidIdError("task", "bad_id", "test reason");
+    expect(error.message).toBe("Invalid task ID: test reason");
+  });
+
+  test("exposes idType, invalidValue, and reason", () => {
+    const error = new InvalidIdError("project", "wrong", "missing prefix");
+    expect(error.idType).toBe("project");
+    expect(error.invalidValue).toBe("wrong");
+    expect(error.reason).toBe("missing prefix");
+  });
+});
+
+describe("Security: ID Injection Prevention", () => {
+  test("rejects path traversal attempts", () => {
+    expect(validateTaskId("task_../etc/passwd").valid).toBe(false);
+    expect(validateTaskId("task_..%2F..%2Fetc").valid).toBe(false);
+  });
+
+  test("rejects null bytes", () => {
+    expect(validateTaskId("task_abc\0def").valid).toBe(false);
+  });
+
+  test("rejects SQL injection attempts", () => {
+    expect(validateTaskId("task_'; DROP TABLE tasks;--").valid).toBe(false);
+    expect(validateTaskId("task_1 OR 1=1").valid).toBe(false);
+  });
+
+  test("rejects script injection attempts", () => {
+    expect(validateTaskId("task_<script>alert(1)</script>").valid).toBe(false);
+  });
+
+  test("only allows safe alphanumeric characters", () => {
+    // The regex ^task_[a-z0-9]+$ only allows lowercase letters and numbers
+    expect(validateTaskId("task_abc123").valid).toBe(true);
+    expect(validateTaskId("task_UPPERCASE").valid).toBe(false);
+    expect(validateTaskId("task_with_underscore").valid).toBe(false);
+    expect(validateTaskId("task_with-dash").valid).toBe(false);
+  });
+});