@task-mcp/shared 1.0.28 → 1.0.30

package/src/utils/env.ts

@@ -0,0 +1,41 @@
+/**
+ * Environment detection utilities
+ */
+
+/**
+ * Check if running in test environment.
+ * Detects: NODE_ENV=test, BUN_TEST (set by bun test), VITEST, JEST_WORKER_ID
+ */
+export function isTestEnv(): boolean {
+  return (
+    process.env.NODE_ENV === "test" ||
+    process.env["BUN_TEST"] !== undefined ||
+    process.env["VITEST"] !== undefined ||
+    process.env["JEST_WORKER_ID"] !== undefined
+  );
+}
+
+/**
+ * Check if debug mode is enabled via environment variable
+ */
+export function isDebugEnabled(): boolean {
+  const debugEnv = process.env["TASK_MCP_DEBUG"];
+  return debugEnv === "true" || debugEnv === "1";
+}
+
+/**
+ * Check if verbose logging should be suppressed.
+ *
+ * Logs are suppressed if:
+ * - In test environment AND
+ * - TASK_MCP_DEBUG is not set AND
+ * - TASK_MCP_TEST_VERBOSE is not set
+ *
+ * Set TASK_MCP_TEST_VERBOSE=true to enable logs in specific tests.
+ */
+export function shouldSuppressLogs(): boolean {
+  if (!isTestEnv()) return false;
+  if (isDebugEnabled()) return false;
+  if (process.env["TASK_MCP_TEST_VERBOSE"] === "true") return false;
+  return true;
+}

package/src/utils/hierarchy.ts

@@ -1,4 +1,5 @@
 import type { Task } from "../schemas/task.js";
+import { shouldSuppressLogs } from "./env.js";
 
 /**
  * Maximum allowed hierarchy depth (0-indexed)
@@ -34,9 +35,11 @@ export function getTaskLevel(tasks: Task[], taskId: string): number {
   while (currentTask.parentId) {
     const parent = taskMap.get(currentTask.parentId);
     if (!parent) {
-      console.warn(
-        `[task-mcp] Orphaned parent reference: task "${currentTask.id}" references non-existent parent "${currentTask.parentId}"`
-      );
+      if (!shouldSuppressLogs()) {
+        console.warn(
+          `[task-mcp] Detached parent reference: task "${currentTask.id}" references non-existent parent "${currentTask.parentId}"`
+        );
+      }
       break;
     }
     level++;
@@ -217,13 +220,18 @@ export function buildTaskTree(
       return { task, children: [] };
     }
 
-    const newVisited = new Set(visited);
-    newVisited.add(task.id);
+    // Mark as visited (O(1) instead of copying the Set)
+    visited.add(task.id);
 
     const children = childrenMap.get(task.id) || [];
+    const childNodes = children.map((child) => buildNode(child, depth + 1, visited));
+
+    // Restore visited state after processing children (backtracking)
+    visited.delete(task.id);
+
     return {
       task,
-      children: children.map((child) => buildNode(child, depth + 1, newVisited)),
+      children: childNodes,
     };
   }
 
@@ -235,8 +243,9 @@ export function buildTaskTree(
     return [buildNode(rootTask, 0, new Set())];
   }
 
-  // Return all root tasks (no parent)
-  const rootTasks = tasks.filter((t) => !t.parentId);
+  // Return all root tasks (no parent OR parent not in filtered tasks)
+  // This ensures orphaned subtasks (whose parent was filtered out) are still visible
+  const rootTasks = tasks.filter((t) => !t.parentId || !taskMap.has(t.parentId));
   return rootTasks.map((task) => buildNode(task, 0, new Set()));
 }
 

package/src/utils/index.ts

@@ -42,6 +42,8 @@ export {
   MAX_HIERARCHY_DEPTH,
   getTaskLevel,
   validateHierarchyDepth,
+  validateHierarchy,
+  type HierarchyValidationResult,
   getAncestorIds,
   getDescendantIds,
   getChildTasks,
@@ -127,6 +129,29 @@ export {
   formatDependencies,
   // Banner
   banner,
+  // Status symbols (checkbox style)
+  STATUS_SYMBOLS,
+  formatStatusSymbol,
+  // Priority badge (P0-P3 style)
+  PRIORITY_LEVELS,
+  formatPriorityBadge,
+  // Section renderer (GitHub CLI style)
+  renderSection,
+  renderSections,
+  type SectionItem,
+  type SectionOptions,
+  // Alert box
+  renderAlert,
+  type AlertSeverity,
+  type AlertOptions,
+  // Stats row
+  renderStats,
+  type StatItem,
+  // Due date formatter
+  formatDueDate,
+  // Task line formatter
+  formatTaskLine,
+  type TaskLineOptions,
 } from "./terminal-ui.js";
 
 // Workspace detection
@@ -140,3 +165,26 @@ export {
   detectWorkspace,
   detectWorkspaceSync,
 } from "./workspace.js";
+
+// Plan parser
+export {
+  parsePlan,
+  type ParsedPlanTask,
+  type ParsePlanOptions,
+  type ParsePlanResult,
+} from "./plan-parser.js";
+
+// Intent extractor (auto-generate intent from title/description)
+export { extractIntent, generateFallbackIntent, getIntent } from "./intent-extractor.js";
+
+// Semantic clustering (task similarity for session resumption)
+export {
+  tokenize,
+  jaccardSimilarity,
+  calculateTaskSimilarity,
+  findRelatedTasks,
+  clusterTasks,
+} from "./clustering.js";
+
+// Environment detection
+export { isTestEnv, isDebugEnabled, shouldSuppressLogs } from "./env.js";

package/src/utils/intent-extractor.test.ts

@@ -0,0 +1,84 @@
+import { describe, test, expect } from "bun:test";
+import { extractIntent, generateFallbackIntent, getIntent } from "./intent-extractor.js";
+
+describe("extractIntent", () => {
+  test("extracts intent from fix patterns", () => {
+    expect(extractIntent("Fix login bug")).toBe("Fix issue or bug");
+    expect(extractIntent("Debug authentication issue")).toBe("Fix issue or bug");
+    expect(extractIntent("로그인 버그 수정")).toBe("Fix issue or bug");
+  });
+
+  test("extracts intent from implement patterns", () => {
+    expect(extractIntent("Implement user authentication")).toBe("Implement new functionality");
+    expect(extractIntent("Create new dashboard")).toBe("Implement new functionality");
+    expect(extractIntent("사용자 인증 구현")).toBe("Implement new functionality");
+  });
+
+  test("extracts intent from refactor patterns", () => {
+    expect(extractIntent("Refactor database layer")).toBe("Improve code quality");
+    expect(extractIntent("API 리팩토링")).toBe("Improve code quality");
+  });
+
+  test("extracts intent from add patterns", () => {
+    expect(extractIntent("Add dark mode support")).toBe("Extend with new feature");
+    expect(extractIntent("다크 모드 추가")).toBe("Extend with new feature");
+  });
+
+  test("extracts intent from update patterns", () => {
+    expect(extractIntent("Update dependencies")).toBe("Modify existing behavior");
+    expect(extractIntent("의존성 업데이트")).toBe("Modify existing behavior");
+  });
+
+  test("extracts intent from remove patterns", () => {
+    expect(extractIntent("Remove deprecated code")).toBe("Remove or clean up");
+    expect(extractIntent("레거시 코드 삭제")).toBe("Remove or clean up");
+  });
+
+  test("extracts intent from test patterns", () => {
+    expect(extractIntent("Test payment flow")).toBe("Verify functionality");
+    expect(extractIntent("결제 플로우 테스트")).toBe("Verify functionality");
+  });
+
+  test("extracts intent from description when title has no match", () => {
+    expect(extractIntent("API endpoints", "Fix the bug in user endpoint")).toBe("Fix issue or bug");
+  });
+
+  test("returns undefined when no pattern matches", () => {
+    expect(extractIntent("Random task title")).toBeUndefined();
+    expect(extractIntent("Something else")).toBeUndefined();
+  });
+});
+
+describe("generateFallbackIntent", () => {
+  test("generates intent from verb-like first word", () => {
+    expect(generateFallbackIntent("Get user data")).toBe("Get operation");
+    expect(generateFallbackIntent("Run tests")).toBe("Run operation");
+  });
+
+  test("generates fallback for non-verb titles", () => {
+    expect(generateFallbackIntent("Dashboard redesign")).toBe("Complete: Dashboard redesign");
+    // Test truncation for titles > 50 chars
+    const longTitle =
+      "This is a very long task title that definitely exceeds fifty characters limit";
+    expect(generateFallbackIntent(longTitle)).toContain("...");
+  });
+});
+
+describe("getIntent", () => {
+  test("returns extracted intent when pattern matches", () => {
+    expect(getIntent("Fix bug")).toBe("Fix issue or bug");
+    expect(getIntent("Implement feature")).toBe("Implement new functionality");
+  });
+
+  test("returns fallback when autoGenerate is true", () => {
+    expect(getIntent("Random task")).toBe("Complete: Random task");
+  });
+
+  test("returns undefined when autoGenerate is false and no match", () => {
+    expect(getIntent("Random task", undefined, false)).toBeUndefined();
+  });
+
+  test("uses description for extraction", () => {
+    expect(getIntent("Task", "Fix the authentication bug")).toBe("Fix issue or bug");
+  });
+});

package/src/utils/intent-extractor.ts

@@ -0,0 +1,156 @@
+/**
+ * Intent Extractor
+ *
+ * Extracts intent from task title/description using pattern matching.
+ * Provides fallback intent generation when workContext.intent is not provided.
+ */
+
+interface IntentPattern {
+  patterns: RegExp[];
+  intent: string;
+}
+
+const INTENT_PATTERNS: IntentPattern[] = [
+  // Fix/Bug patterns
+  {
+    patterns: [/^fix\b/i, /^debug\b/i, /^resolve\b/i, /버그/, /수정/, /고치/],
+    intent: "Fix issue or bug",
+  },
+  // Implementation patterns
+  {
+    patterns: [/^implement\b/i, /^create\b/i, /^build\b/i, /구현/, /만들/],
+    intent: "Implement new functionality",
+  },
+  // Refactoring patterns
+  {
+    patterns: [/^refactor\b/i, /^restructure\b/i, /^reorganize\b/i, /리팩/, /개선/],
+    intent: "Improve code quality",
+  },
+  // Add/Extend patterns
+  {
+    patterns: [/^add\b/i, /^extend\b/i, /^include\b/i, /추가/, /확장/],
+    intent: "Extend with new feature",
+  },
+  // Update/Modify patterns
+  {
+    patterns: [/^update\b/i, /^modify\b/i, /^change\b/i, /업데이트/, /변경/],
+    intent: "Modify existing behavior",
+  },
+  // Remove/Delete patterns
+  {
+    patterns: [/^remove\b/i, /^delete\b/i, /^clean\b/i, /삭제/, /제거/],
+    intent: "Remove or clean up",
+  },
+  // Test patterns
+  {
+    patterns: [/^test\b/i, /^verify\b/i, /^validate\b/i, /테스트/, /검증/],
+    intent: "Verify functionality",
+  },
+  // Documentation patterns
+  {
+    patterns: [/^document\b/i, /^write doc/i, /문서/, /docs/i],
+    intent: "Document or explain",
+  },
+  // Research/Analysis patterns
+  {
+    patterns: [/^research\b/i, /^analyze\b/i, /^investigate\b/i, /조사/, /분석/],
+    intent: "Research or analyze",
+  },
+  // Migration patterns
+  {
+    patterns: [/^migrate\b/i, /^upgrade\b/i, /^convert\b/i, /마이그레이션/, /전환/],
+    intent: "Migrate or upgrade",
+  },
+  // Setup/Config patterns
+  {
+    patterns: [/^setup\b/i, /^configure\b/i, /^initialize\b/i, /설정/, /초기화/],
+    intent: "Setup or configure",
+  },
+  // Review patterns
+  {
+    patterns: [/^review\b/i, /^check\b/i, /^audit\b/i, /리뷰/, /검토/],
+    intent: "Review or audit",
+  },
+];
+
+/**
+ * Extract intent from task title and description
+ *
+ * @param title - Task title
+ * @param description - Optional task description
+ * @returns Extracted intent or undefined if no pattern matches
+ */
+export function extractIntent(title: string, description?: string): string | undefined {
+  const text = title.toLowerCase();
+
+  // Try to match patterns against title
+  for (const { patterns, intent } of INTENT_PATTERNS) {
+    for (const pattern of patterns) {
+      if (pattern.test(text)) {
+        return intent;
+      }
+    }
+  }
+
+  // If no match found in title, try description
+  if (description) {
+    const descText = description.toLowerCase();
+    for (const { patterns, intent } of INTENT_PATTERNS) {
+      for (const pattern of patterns) {
+        if (pattern.test(descText)) {
+          return intent;
+        }
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Generate a fallback intent based on title structure
+ *
+ * Used when no pattern matches but we still want some intent
+ */
+export function generateFallbackIntent(title: string): string {
+  // Extract first verb-like word
+  const words = title.split(/\s+/);
+  const firstWord = words[0]?.toLowerCase() || "";
+
+  // If it looks like a verb (common task action words)
+  const verbPatterns =
+    /^(get|set|make|do|run|use|find|show|hide|load|save|send|fetch|call|start|stop|enable|disable)/i;
+  if (verbPatterns.test(firstWord)) {
+    return `${firstWord.charAt(0).toUpperCase() + firstWord.slice(1)} operation`;
+  }
+
+  // Default: use truncated title as intent
+  const truncatedTitle = title.length > 50 ? title.slice(0, 47) + "..." : title;
+  return `Complete: ${truncatedTitle}`;
+}
+
+/**
+ * Get intent for a task, extracting from content or generating fallback
+ *
+ * @param title - Task title
+ * @param description - Optional task description
+ * @param autoGenerate - Whether to generate fallback if no pattern matches (default: true)
+ * @returns Intent string
+ */
+export function getIntent(
+  title: string,
+  description?: string,
+  autoGenerate: boolean = true
+): string | undefined {
+  const extracted = extractIntent(title, description);
+
+  if (extracted) {
+    return extracted;
+  }
+
+  if (autoGenerate) {
+    return generateFallbackIntent(title);
+  }
+
+  return undefined;
+}

package/src/utils/natural-language.test.ts

@@ -255,6 +255,33 @@ describe("parseTaskInput", () => {
       const result = parseTaskInput("간단한 작업 !medium #task");
       expect(result.workContext).toBeUndefined();
     });
+
+    test("parses done: before :: to prevent intent capturing done:", () => {
+      // Regression test: done: should be extracted before intent (::)
+      const result = parseTaskInput(
+        "API 리팩토링 :: 성능 개선 done:테스트통과,코드리뷰 @thorough #backend !high"
+      );
+      expect(result.title).toBe("API 리팩토링");
+      expect(result.workContext?.intent).toBe("성능 개선");
+      expect(result.workContext?.acceptanceCriteria).toEqual(["테스트통과", "코드리뷰"]);
+      expect(result.workContext?.qualityLevel).toBe("thorough");
+      expect(result.priority).toBe("high");
+      expect(result.tags).toEqual(["backend"]);
+    });
+
+    test("parses done: without intent", () => {
+      const result = parseTaskInput("테스트 작성 done:유닛테스트,통합테스트 !high");
+      expect(result.title).toBe("테스트 작성");
+      expect(result.workContext?.acceptanceCriteria).toEqual(["유닛테스트", "통합테스트"]);
+      expect(result.workContext?.intent).toBeUndefined();
+    });
+
+    test("parses intent without done:", () => {
+      const result = parseTaskInput("리팩토링 :: 가독성 향상 !medium");
+      expect(result.title).toBe("리팩토링");
+      expect(result.workContext?.intent).toBe("가독성 향상");
+      expect(result.workContext?.acceptanceCriteria).toBeUndefined();
+    });
   });
 });
 

package/src/utils/natural-language.ts

@@ -316,7 +316,16 @@ export function parseTaskInput(input: string): TaskCreateInput {
   const result: TaskCreateInput = { title: "" };
   const workContext: Partial<WorkContext> = {};
 
-  // Extract intent first (:: separator)
+  // Extract acceptanceCriteria FIRST (done:xxx,yyy or done:xxx)
+  // Must be before intent extraction to prevent done: from being captured as intent
+  // Format: "done:criterion1,criterion2" or "done:single criterion"
+  const doneMatch = remaining.match(/done:([^\s@#!~^:]+(?:,[^\s@#!~^:]+)*)/i);
+  if (doneMatch) {
+    workContext.acceptanceCriteria = doneMatch[1]!.split(",").map((c) => c.trim());
+    remaining = remaining.replace(doneMatch[0], " ").trim();
+  }
+
+  // Extract intent (:: separator)
   // Format: "Task title :: intent description"
   const intentMatch = remaining.match(/\s*::\s*(.+?)(?=\s+[@#!~^]|$)/);
   if (intentMatch) {
@@ -324,14 +333,6 @@ export function parseTaskInput(input: string): TaskCreateInput {
     remaining = remaining.replace(intentMatch[0], " ").trim();
   }
 
-  // Extract acceptanceCriteria (done:xxx,yyy or done:xxx)
-  // Format: "done:criterion1,criterion2" or "done:single criterion"
-  const doneMatch = remaining.match(/done:([^\s@#!~^]+(?:,[^\s@#!~^]+)*)/i);
-  if (doneMatch) {
-    workContext.acceptanceCriteria = doneMatch[1]!.split(",").map((c) => c.trim());
-    remaining = remaining.replace(doneMatch[0], " ").trim();
-  }
-
   // Extract qualityLevel (@quick, @thorough, etc.) - before contexts
   // These are reserved keywords that become qualityLevel, not contexts
   const qualityLevelKeywords = Object.keys(QUALITY_LEVEL_KEYWORDS);