@task-mcp/shared 1.0.28 → 1.0.30

package/src/utils/plan-parser.ts

@@ -0,0 +1,466 @@
+import type { Priority, WorkContext } from "../schemas/task.js";
+import { extractMetadata } from "./natural-language.js";
+
+/**
+ * Parsed task from plan text
+ */
+export interface ParsedPlanTask {
+  title: string;
+  description?: string;
+  level: number; // 0 = root phase, 1 = section, 2 = task, 3 = subtask
+  tempId: string;
+  parentTempId?: string;
+  dependsOn?: string[];
+  workContext?: Partial<WorkContext>;
+  priority?: Priority;
+  tags?: string[];
+}
+
+/**
+ * Options for parsing plan text
+ */
+export interface ParsePlanOptions {
+  /** Default priority for tasks without explicit priority (default: medium) */
+  defaultPriority?: Priority;
+  /** Parse natural language patterns like !high, #tag (default: true) */
+  parseNaturalLanguage?: boolean;
+  /** Infer dependencies from 'depends on', 'after' patterns (default: true) */
+  inferDependencies?: boolean;
+}
+
+/**
+ * Result of parsing plan text
+ */
+export interface ParsePlanResult {
+  tasks: ParsedPlanTask[];
+  phases: string[];
+  warnings: string[];
+}
+
+/**
+ * Maximum input length to prevent DoS
+ */
+const MAX_PLAN_LENGTH = 50000;
+
+/**
+ * Preprocess input to remove code blocks and YAML frontmatter
+ */
+function preprocessInput(input: string): string {
+  let result = input;
+
+  // Remove YAML frontmatter (--- at start of file)
+  // Must be at the very beginning of the document
+  const frontmatterMatch = result.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (frontmatterMatch) {
+    result = result.slice(frontmatterMatch[0].length);
+  }
+
+  // Remove fenced code blocks (``` or ~~~)
+  // Matches both backticks and tildes, with optional language identifier
+  result = result.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?\n\1$/gm, "");
+
+  // Also handle code blocks that might not have matching closing fence
+  // (replace opening fence and content until next fence or end)
+  result = result.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?=\n(`{3,}|~{3,})|$)/gm, (match) => {
+    // Only remove if it looks like a code block (has content)
+    if (match.includes("\n")) {
+      return "";
+    }
+    return match;
+  });
+
+  return result;
+}
+
+/**
+ * Parse markdown/structured text into hierarchical tasks
+ *
+ * Parsing rules:
+ * - `# Header` → Top-level phase (level 0)
+ * - `## SubHeader` → Section (level 1)
+ * - `- Item` → Task (level based on indentation)
+ * - `depends on X`, `after X` → Dependency inference
+ * - `!high`, `#tag` → Natural language patterns
+ *
+ * @example
+ * ```typescript
+ * const result = parsePlan(`
+ * # Phase 1: Setup
+ * - Create database schema !high
+ *   - Define user table
+ *   - Define session table
+ * - Setup API endpoints (depends on database)
+ * `);
+ * ```
+ */
+export function parsePlan(input: string, options: ParsePlanOptions = {}): ParsePlanResult {
+  if (input.length > MAX_PLAN_LENGTH) {
+    return {
+      tasks: [],
+      phases: [],
+      warnings: [`Input exceeds maximum length of ${MAX_PLAN_LENGTH} characters`],
+    };
+  }
+
+  const {
+    defaultPriority = "medium",
+    parseNaturalLanguage = true,
+    inferDependencies = true,
+  } = options;
+
+  // Preprocess to remove code blocks and YAML frontmatter
+  const processedInput = preprocessInput(input);
+  const lines = processedInput.split("\n");
+  const tasks: ParsedPlanTask[] = [];
+  const phases: string[] = [];
+  const warnings: string[] = [];
+
+  let taskCounter = 0;
+  let currentPhase: { tempId: string; title: string } | null = null;
+  let currentSection: { tempId: string; level: number } | null = null;
+  const parentStack: Array<{ tempId: string; level: number; indent: number }> = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines
+    if (!trimmed) continue;
+
+    // Parse H1 headers as phases (level 0)
+    const h1Match = trimmed.match(/^#\s+(.+)$/);
+    if (h1Match) {
+      const phaseTitle = h1Match[1]!.trim();
+      const tempId = `phase-${++taskCounter}`;
+      currentPhase = { tempId, title: phaseTitle };
+      phases.push(phaseTitle);
+
+      // Extract metadata if enabled
+      let title = phaseTitle;
+      let priority: Priority | undefined;
+      let tags: string[] | undefined;
+
+      if (parseNaturalLanguage) {
+        const metadata = extractMetadata(phaseTitle);
+        title = metadata.remaining || phaseTitle;
+        priority = metadata.priority;
+        tags = metadata.tags;
+      }
+
+      tasks.push({
+        title,
+        level: 0,
+        tempId,
+        priority: priority ?? "high",
+        ...(tags && tags.length > 0 && { tags }),
+      });
+
+      // Reset section and parent stack
+      currentSection = null;
+      parentStack.length = 0;
+      continue;
+    }
+
+    // Parse H2 headers as sections (level 1)
+    const h2Match = trimmed.match(/^##\s+(.+)$/);
+    if (h2Match) {
+      const sectionTitle = h2Match[1]!.trim();
+      const tempId = `section-${++taskCounter}`;
+
+      let title = sectionTitle;
+      let priority: Priority | undefined;
+      let tags: string[] | undefined;
+
+      if (parseNaturalLanguage) {
+        const metadata = extractMetadata(sectionTitle);
+        title = metadata.remaining || sectionTitle;
+        priority = metadata.priority;
+        tags = metadata.tags;
+      }
+
+      tasks.push({
+        title,
+        level: 1,
+        tempId,
+        ...(currentPhase && { parentTempId: currentPhase.tempId }),
+        priority: priority ?? defaultPriority,
+        ...(tags && tags.length > 0 && { tags }),
+      });
+
+      currentSection = { tempId, level: 1 };
+      parentStack.length = 0;
+      continue;
+    }
+
+    // Parse list items as tasks
+    const listMatch = line.match(/^(\s*)[-*]\s+(.+)$/);
+    if (listMatch) {
+      const indent = listMatch[1]!.length;
+      const content = listMatch[2]!.trim();
+      const tempId = `task-${++taskCounter}`;
+
+      // Determine parent based on indentation
+      let parentTempId: string | undefined;
+      let level: number;
+
+      // Pop parents from stack that have same or greater indentation
+      while (parentStack.length > 0 && parentStack[parentStack.length - 1]!.indent >= indent) {
+        parentStack.pop();
+      }
+
+      if (parentStack.length > 0) {
+        // Use the last item on stack as parent
+        const parent = parentStack[parentStack.length - 1]!;
+        parentTempId = parent.tempId;
+        level = Math.min(parent.level + 1, 3); // Max depth 3
+      } else if (currentSection) {
+        parentTempId = currentSection.tempId;
+        level = 2;
+      } else if (currentPhase) {
+        parentTempId = currentPhase.tempId;
+        level = 1;
+      } else {
+        level = 0;
+      }
+
+      // Extract metadata from content
+      let title = content;
+      let priority: Priority | undefined;
+      let tags: string[] | undefined;
+      let dependsOn: string[] | undefined;
+
+      if (parseNaturalLanguage) {
+        const metadata = extractMetadata(content);
+        title = metadata.remaining || content;
+        priority = metadata.priority;
+        tags = metadata.tags;
+      }
+
+      // Infer dependencies from text
+      if (inferDependencies) {
+        dependsOn = inferDependenciesFromText(title, tasks);
+        // Clean up dependency text from title
+        title = cleanDependencyText(title);
+      }
+
+      // Extract description from remaining parentheses (not dependency-related)
+      const descExtracted = extractDescription(title);
+      title = descExtracted.title;
+      const description = descExtracted.description;
+
+      const task: ParsedPlanTask = {
+        title,
+        level,
+        tempId,
+        ...(parentTempId && { parentTempId }),
+        ...(description && { description }),
+        priority: priority ?? defaultPriority,
+        ...(tags && tags.length > 0 && { tags }),
+        ...(dependsOn && dependsOn.length > 0 && { dependsOn }),
+      };
+
+      tasks.push(task);
+
+      // Push to parent stack for potential children
+      parentStack.push({ tempId, level, indent });
+      continue;
+    }
+
+    // Parse numbered list items
+    const numberedMatch = line.match(/^(\s*)(\d+)[.)]\s+(.+)$/);
+    if (numberedMatch) {
+      const indent = numberedMatch[1]!.length;
+      const content = numberedMatch[3]!.trim();
+      const tempId = `task-${++taskCounter}`;
+
+      // Same logic as unordered lists
+      while (parentStack.length > 0 && parentStack[parentStack.length - 1]!.indent >= indent) {
+        parentStack.pop();
+      }
+
+      let parentTempId: string | undefined;
+      let level: number;
+
+      if (parentStack.length > 0) {
+        const parent = parentStack[parentStack.length - 1]!;
+        parentTempId = parent.tempId;
+        level = Math.min(parent.level + 1, 3);
+      } else if (currentSection) {
+        parentTempId = currentSection.tempId;
+        level = 2;
+      } else if (currentPhase) {
+        parentTempId = currentPhase.tempId;
+        level = 1;
+      } else {
+        level = 0;
+      }
+
+      let title = content;
+      let priority: Priority | undefined;
+      let tags: string[] | undefined;
+      let dependsOn: string[] | undefined;
+
+      if (parseNaturalLanguage) {
+        const metadata = extractMetadata(content);
+        title = metadata.remaining || content;
+        priority = metadata.priority;
+        tags = metadata.tags;
+      }
+
+      if (inferDependencies) {
+        dependsOn = inferDependenciesFromText(title, tasks);
+        title = cleanDependencyText(title);
+      }
+
+      // Extract description from remaining parentheses
+      const descExtracted = extractDescription(title);
+      title = descExtracted.title;
+      const description = descExtracted.description;
+
+      tasks.push({
+        title,
+        level,
+        tempId,
+        ...(parentTempId && { parentTempId }),
+        ...(description && { description }),
+        priority: priority ?? defaultPriority,
+        ...(tags && tags.length > 0 && { tags }),
+        ...(dependsOn && dependsOn.length > 0 && { dependsOn }),
+      });
+
+      parentStack.push({ tempId, level, indent });
+      continue;
+    }
+  }
+
+  return { tasks, phases, warnings };
+}
+
+/**
+ * Infer dependencies from text patterns like "depends on X", "after X"
+ */
+function inferDependenciesFromText(content: string, existingTasks: ParsedPlanTask[]): string[] {
+  const deps: string[] = [];
+  const lower = content.toLowerCase();
+
+  // Pattern: (depends on|after|requires|following) "phrase" or phrase
+  const patterns = [
+    /\(?\s*depends?\s+on\s+(.+?)\s*\)?/gi,
+    /\(?\s*after\s+(.+?)\s*\)?/gi,
+    /\(?\s*requires?\s+(.+?)\s*\)?/gi,
+    /\(?\s*following\s+(.+?)\s*\)?/gi,
+    /\(?\s*blocked\s+by\s+(.+?)\s*\)?/gi,
+  ];
+
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(lower)) !== null) {
+      const depPhrase = match[1]!.trim();
+
+      // Try to find matching task by title
+      const found = existingTasks.find((t) => {
+        const taskTitle = t.title.toLowerCase();
+        return (
+          taskTitle.includes(depPhrase) ||
+          depPhrase.includes(taskTitle) ||
+          fuzzyMatch(taskTitle, depPhrase)
+        );
+      });
+
+      if (found && !deps.includes(found.tempId)) {
+        deps.push(found.tempId);
+      }
+    }
+  }
+
+  return deps;
+}
+
+/**
+ * Simple fuzzy matching for dependency detection
+ */
+function fuzzyMatch(a: string, b: string): boolean {
+  // Remove common words and compare
+  const stopWords = ["the", "a", "an", "to", "for", "of", "in", "on", "at"];
+  const normalize = (s: string) =>
+    s
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => !stopWords.includes(w))
+      .join(" ");
+
+  const aNorm = normalize(a);
+  const bNorm = normalize(b);
+
+  // Check if significant overlap
+  const aWords = aNorm.split(" ");
+  const bWords = bNorm.split(" ");
+
+  const matches = aWords.filter((w) => bWords.includes(w));
+  return matches.length >= Math.min(2, Math.min(aWords.length, bWords.length));
+}
+
+/**
+ * Remove dependency text from title
+ */
+function cleanDependencyText(title: string): string {
+  return title
+    .replace(/\(?\s*depends?\s+on\s+.+?\s*\)?/gi, "")
+    .replace(/\(?\s*after\s+.+?\s*\)?/gi, "")
+    .replace(/\(?\s*requires?\s+.+?\s*\)?/gi, "")
+    .replace(/\(?\s*following\s+.+?\s*\)?/gi, "")
+    .replace(/\(?\s*blocked\s+by\s+.+?\s*\)?/gi, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Extract description from title
+ *
+ * Patterns supported:
+ * - "제목: 설명" → colon separator
+ * - "제목 -- 설명" → double dash separator
+ * - "제목 (설명)" → parentheses (after dependency cleanup)
+ *
+ * @example
+ * extractDescription("API 구현: 라우팅, 인증 담당")
+ * // → { title: "API 구현", description: "라우팅, 인증 담당" }
+ *
+ * extractDescription("API 구현 (라우팅, 인증 담당)")
+ * // → { title: "API 구현", description: "라우팅, 인증 담당" }
+ */
+function extractDescription(title: string): { title: string; description?: string } {
+  // Pattern 1: Colon separator (but not time like "10:30")
+  // Match "제목: 설명" but not "10:30" or "http://..."
+  const colonMatch = title.match(/^(.+?):\s+([^/].{5,})$/);
+  if (colonMatch && !/^\d+:\d+/.test(colonMatch[2]!)) {
+    return {
+      title: colonMatch[1]!.trim(),
+      description: colonMatch[2]!.trim(),
+    };
+  }
+
+  // Pattern 2: Double dash separator "제목 -- 설명"
+  const dashMatch = title.match(/^(.+?)\s+--\s+(.+)$/);
+  if (dashMatch) {
+    return {
+      title: dashMatch[1]!.trim(),
+      description: dashMatch[2]!.trim(),
+    };
+  }
+
+  // Pattern 3: Parentheses at end (only if not dependency-like)
+  // Already cleaned by cleanDependencyText, so remaining () is description
+  const parenMatch = title.match(/^(.+?)\s*\(([^)]+)\)\s*$/);
+  if (parenMatch) {
+    const content = parenMatch[2]!.trim();
+    // Skip if looks like a short annotation (single word, abbreviation)
+    if (content.length > 3 && content.includes(" ")) {
+      return {
+        title: parenMatch[1]!.trim(),
+        description: content,
+      };
+    }
+  }
+
+  return { title };
+}

package/src/utils/projection.test.ts

@@ -45,7 +45,7 @@ const createInboxItem = (overrides: Partial<InboxItem> = {}): InboxItem => ({
 });
 
 describe("formatTask", () => {
-  test("concise format returns only 4 essential fields", () => {
+  test("concise format returns essential fields plus description for context", () => {
     const task = createTask();
     const result = formatTask(task, "concise");
 
@@ -54,11 +54,12 @@ describe("formatTask", () => {
       title: "Test Task",
       status: "pending",
       priority: "medium",
+      description: "This is a test task with a long description",
     });
-    expect(Object.keys(result)).toHaveLength(4);
+    expect(Object.keys(result)).toHaveLength(5);
   });
 
-  test("standard format returns 8 common fields", () => {
+  test("standard format returns common fields including description", () => {
     const task = createTask();
     const result = formatTask(task, "standard");
 
@@ -67,6 +68,7 @@ describe("formatTask", () => {
       title: "Test Task",
       status: "pending",
       priority: "medium",
+      description: "This is a test task with a long description",
       dueDate: "2025-01-15",
       tags: ["test", "unit"],
       contexts: ["work"],
@@ -94,6 +96,57 @@ describe("formatTask", () => {
     expect(result).not.toHaveProperty("dueDate");
     expect(result).not.toHaveProperty("tags");
   });
+
+  test("concise format includes workContext fields (intent, methodology, quality, patterns, criteria)", () => {
+    const task = createTask({
+      workContext: {
+        intent: "Migrate API layer to service pattern",
+        methodology: "TDD + iterative refactoring",
+        qualityLevel: "thorough",
+        patterns: {
+          parallelExecution: true,
+          testFirst: true,
+        },
+        acceptanceCriteria: ["All tests pass", "No type errors"],
+      },
+    });
+    const result = formatTask(task, "concise");
+
+    expect(result).toHaveProperty("intent", "Migrate API layer to service pattern");
+    expect(result).toHaveProperty("methodology", "TDD + iterative refactoring");
+    expect(result).toHaveProperty("quality", "thorough");
+    expect(result).toHaveProperty("patterns", { parallelExecution: true, testFirst: true });
+    expect(result).toHaveProperty("criteria", ["All tests pass", "No type errors"]);
+  });
+
+  test("standard format includes full workContext with patterns and criteria", () => {
+    const task = createTask({
+      workContext: {
+        intent: "Refactor module",
+        methodology: "Analyze → Extract → Test",
+        qualityLevel: "standard",
+        patterns: {
+          parallelExecution: true,
+          testFirst: true,
+          reviewRequired: false,
+        },
+        acceptanceCriteria: ["Tests pass", "No regressions"],
+      },
+    });
+    const result = formatTask(task, "standard");
+
+    expect(result).toHaveProperty("workContext");
+    const wc = (result as { workContext?: unknown }).workContext as Record<string, unknown>;
+    expect(wc["intent"]).toBe("Refactor module");
+    expect(wc["methodology"]).toBe("Analyze → Extract → Test");
+    expect(wc["qualityLevel"]).toBe("standard");
+    expect(wc["patterns"]).toEqual({
+      parallelExecution: true,
+      testFirst: true,
+      reviewRequired: false,
+    });
+    expect(wc["acceptanceCriteria"]).toEqual(["Tests pass", "No regressions"]);
+  });
 });
 
 describe("formatTasks", () => {
@@ -107,6 +160,7 @@ describe("formatTasks", () => {
       title: "Test Task",
       status: "pending",
       priority: "medium",
+      description: "This is a test task with a long description",
     });
   });
 
@@ -404,8 +458,8 @@ describe("token efficiency", () => {
     const conciseSize = JSON.stringify(concise).length;
     const fullSize = JSON.stringify(full).length;
 
-    // Concise should be at least 50% smaller
-    expect(conciseSize).toBeLessThan(fullSize * 0.5);
+    // Concise should be at least 40% smaller (now includes description for session context)
+    expect(conciseSize).toBeLessThan(fullSize * 0.6);
   });
 
   test("concise list is significantly smaller than full list", () => {
@@ -424,7 +478,7 @@ describe("token efficiency", () => {
     const conciseSize = JSON.stringify(concise).length;
     const fullSize = JSON.stringify(full).length;
 
-    // For list of 20 tasks, concise should be 70%+ smaller
-    expect(conciseSize).toBeLessThan(fullSize * 0.4);
+    // For list of 20 tasks, concise should be 40%+ smaller (now includes description)
+    expect(conciseSize).toBeLessThan(fullSize * 0.6);
   });
 });

package/src/utils/projection.ts

@@ -36,13 +36,43 @@ export function formatTask(task: Task, format: ResponseFormat): TaskSummary | Ta
         status: task.status,
         priority: task.priority,
       };
-      // Include intent + qualityLevel for quick context understanding
+      // Include description for session context (truncated for token efficiency)
+      // Skip if intent exists and provides enough context
+      if (task.description) {
+        const hasIntent = !!task.workContext?.intent;
+        // With intent: shorter description (100 chars), without: fuller context (200 chars)
+        const maxLen = hasIntent ? 100 : 200;
+        summary.description = truncate(task.description, maxLen);
+      }
+      // Include workContext fields for session resumption
       if (task.workContext?.intent) {
         summary.intent = task.workContext.intent;
       }
+      if (task.workContext?.methodology) {
+        summary.methodology = task.workContext.methodology;
+      }
       if (task.workContext?.qualityLevel) {
         summary.quality = task.workContext.qualityLevel;
       }
+      // Include patterns for execution guidance
+      if (task.workContext?.patterns) {
+        const p = task.workContext.patterns;
+        const patterns: {
+          parallelExecution?: boolean;
+          testFirst?: boolean;
+          reviewRequired?: boolean;
+        } = {};
+        if (p.parallelExecution !== undefined) patterns.parallelExecution = p.parallelExecution;
+        if (p.testFirst !== undefined) patterns.testFirst = p.testFirst;
+        if (p.reviewRequired !== undefined) patterns.reviewRequired = p.reviewRequired;
+        if (Object.keys(patterns).length > 0) {
+          summary.patterns = patterns;
+        }
+      }
+      // Include acceptance criteria for completion validation
+      if (task.workContext?.acceptanceCriteria?.length) {
+        summary.criteria = task.workContext.acceptanceCriteria;
+      }
       return summary;
     }
 
@@ -53,6 +83,7 @@ export function formatTask(task: Task, format: ResponseFormat): TaskSummary | Ta
         title: task.title,
         status: task.status,
         priority: task.priority,
+        ...(task.description !== undefined && { description: task.description }),
         ...(task.dueDate !== undefined && { dueDate: task.dueDate }),
         ...(task.tags !== undefined && { tags: task.tags }),
         ...(task.contexts !== undefined && { contexts: task.contexts }),
@@ -65,6 +96,18 @@ export function formatTask(task: Task, format: ResponseFormat): TaskSummary | Ta
           ...(wc.intent !== undefined && { intent: wc.intent }),
           ...(wc.methodology !== undefined && { methodology: wc.methodology }),
           ...(wc.qualityLevel !== undefined && { qualityLevel: wc.qualityLevel }),
+          ...(wc.patterns !== undefined && {
+            patterns: {
+              ...(wc.patterns.parallelExecution !== undefined && {
+                parallelExecution: wc.patterns.parallelExecution,
+              }),
+              ...(wc.patterns.testFirst !== undefined && { testFirst: wc.patterns.testFirst }),
+              ...(wc.patterns.reviewRequired !== undefined && {
+                reviewRequired: wc.patterns.reviewRequired,
+              }),
+            },
+          }),
+          ...(wc.acceptanceCriteria?.length && { acceptanceCriteria: wc.acceptanceCriteria }),
         };
       }
       return result;