@task-mcp/shared 1.0.4 → 1.0.7

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);
+  });
+});

package/src/utils/id.ts

@@ -1,10 +1,12 @@
 /**
- * Generate a unique ID with optional prefix
+ * Generate a unique ID with optional prefix.
+ * Uses crypto.randomUUID for secure, collision-resistant ID generation.
  */
 export function generateId(prefix: string = ""): string {
-  const timestamp = Date.now().toString(36);
-  const random = Math.random().toString(36).substring(2, 8);
-  return prefix ? `${prefix}_${timestamp}${random}` : `${timestamp}${random}`;
+  // Use crypto.randomUUID for better randomness and collision resistance
+  // Format: prefix_xxxxxxxx (8 chars from UUID, sufficient for local uniqueness)
+  const uuid = crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+  return prefix ? `${prefix}_${uuid}` : uuid;
 }
 
 /**
@@ -43,3 +45,136 @@ export function isValidProjectId(id: string): boolean {
 export function isValidTaskId(id: string): boolean {
   return /^task_[a-z0-9]+$/.test(id);
 }
+
+/**
+ * Generate an inbox item ID
+ */
+export function generateInboxId(): string {
+  return generateId("inbox");
+}
+
+/**
+ * Validate an inbox ID format
+ * @returns true if valid format (inbox_[alphanumeric])
+ */
+export function isValidInboxId(id: string): boolean {
+  return /^inbox_[a-z0-9]+$/.test(id);
+}
+
+/**
+ * ID validation error with detailed context
+ */
+export class InvalidIdError extends Error {
+  constructor(
+    public readonly idType: "task" | "project" | "inbox" | "view",
+    public readonly invalidValue: unknown,
+    public readonly reason: string
+  ) {
+    super(`Invalid ${idType} ID: ${reason}`);
+    this.name = "InvalidIdError";
+  }
+}
+
+/**
+ * Validation result with reason if invalid
+ */
+export interface IdValidationResult {
+  valid: boolean;
+  reason?: string;
+}
+
+/**
+ * Validate task ID with detailed error information
+ */
+export function validateTaskId(id: unknown): IdValidationResult {
+  if (id === null || id === undefined) {
+    return { valid: false, reason: "Task ID is required" };
+  }
+  if (typeof id !== "string") {
+    return { valid: false, reason: `Task ID must be a string (received ${typeof id})` };
+  }
+  if (id.length === 0) {
+    return { valid: false, reason: "Task ID cannot be empty" };
+  }
+  if (!id.startsWith("task_")) {
+    return { valid: false, reason: "Task ID must start with 'task_' prefix" };
+  }
+  if (!/^task_[a-z0-9]+$/.test(id)) {
+    return { valid: false, reason: "Task ID contains invalid characters" };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate project ID with detailed error information
+ */
+export function validateProjectId(id: unknown): IdValidationResult {
+  if (id === null || id === undefined) {
+    return { valid: false, reason: "Project ID is required" };
+  }
+  if (typeof id !== "string") {
+    return { valid: false, reason: `Project ID must be a string (received ${typeof id})` };
+  }
+  if (id.length === 0) {
+    return { valid: false, reason: "Project ID cannot be empty" };
+  }
+  if (!id.startsWith("proj_")) {
+    return { valid: false, reason: "Project ID must start with 'proj_' prefix" };
+  }
+  if (!/^proj_[a-z0-9]+$/.test(id)) {
+    return { valid: false, reason: "Project ID contains invalid characters" };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate inbox ID with detailed error information
+ */
+export function validateInboxId(id: unknown): IdValidationResult {
+  if (id === null || id === undefined) {
+    return { valid: false, reason: "Inbox ID is required" };
+  }
+  if (typeof id !== "string") {
+    return { valid: false, reason: `Inbox ID must be a string (received ${typeof id})` };
+  }
+  if (id.length === 0) {
+    return { valid: false, reason: "Inbox ID cannot be empty" };
+  }
+  if (!id.startsWith("inbox_")) {
+    return { valid: false, reason: "Inbox ID must start with 'inbox_' prefix" };
+  }
+  if (!/^inbox_[a-z0-9]+$/.test(id)) {
+    return { valid: false, reason: "Inbox ID contains invalid characters" };
+  }
+  return { valid: true };
+}
+
+/**
+ * Assert valid task ID, throw if invalid
+ */
+export function assertValidTaskId(id: unknown): asserts id is string {
+  const result = validateTaskId(id);
+  if (!result.valid) {
+    throw new InvalidIdError("task", id, result.reason!);
+  }
+}
+
+/**
+ * Assert valid project ID, throw if invalid
+ */
+export function assertValidProjectId(id: unknown): asserts id is string {
+  const result = validateProjectId(id);
+  if (!result.valid) {
+    throw new InvalidIdError("project", id, result.reason!);
+  }
+}
+
+/**
+ * Assert valid inbox ID, throw if invalid
+ */
+export function assertValidInboxId(id: unknown): asserts id is string {
+  const result = validateInboxId(id);
+  if (!result.valid) {
+    throw new InvalidIdError("inbox", id, result.reason!);
+  }
+}

package/src/utils/index.ts

@@ -1,3 +1,47 @@
-export { generateId, generateTaskId, generateProjectId, generateViewId, isValidProjectId, isValidTaskId } from "./id.js";
+export {
+  generateId,
+  generateTaskId,
+  generateProjectId,
+  generateViewId,
+  isValidProjectId,
+  isValidTaskId,
+  generateInboxId,
+  isValidInboxId,
+  // Validation utilities with detailed error information
+  InvalidIdError,
+  type IdValidationResult,
+  validateTaskId,
+  validateProjectId,
+  validateInboxId,
+  assertValidTaskId,
+  assertValidProjectId,
+  assertValidInboxId,
+} from "./id.js";
 export { now, parseRelativeDate, formatDate, formatDisplayDate, isToday, isPastDue, isWithinDays } from "./date.js";
-export { parseTaskInput } from "./natural-language.js";
+export { parseTaskInput, parseInboxInput, parseInput, type ParseTarget, type ParsedInput } from "./natural-language.js";
+export {
+  MAX_HIERARCHY_DEPTH,
+  getTaskLevel,
+  validateHierarchyDepth,
+  getAncestorIds,
+  getDescendantIds,
+  getChildTasks,
+  getRootTask,
+  buildTaskTree,
+  type TaskTreeNode,
+} from "./hierarchy.js";
+
+// Projection utilities (token optimization)
+export {
+  projectTask,
+  projectTasks,
+  projectTasksPaginated,
+  projectProject,
+  projectProjects,
+  projectInboxItem,
+  projectInboxItems,
+  formatResponse,
+  applyPagination,
+  truncate,
+  summarizeList,
+} from "./projection.js";