@task-mcp/shared 1.0.4 → 1.0.7

package/src/schemas/response-format.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+
+/**
+ * Response Format Schema
+ *
+ * Token-efficient response formats for MCP tools.
+ * Based on Anthropic's recommended patterns for reducing token usage.
+ *
+ * - concise: Minimal fields (4-6), JSON format for machine processing
+ * - standard: Common fields (7-10), balanced for most use cases
+ * - detailed: Full object, human-readable format
+ */
+
+// Response format options
+export const ResponseFormat = z.enum(["concise", "standard", "detailed"]);
+export type ResponseFormat = z.infer<typeof ResponseFormat>;
+
+// Default limits for pagination
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 100;
+
+/**
+ * Paginated response wrapper
+ */
+export interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  limit: number;
+  offset: number;
+  hasMore: boolean;
+}
+
+/**
+ * Task projection types - progressively more detailed
+ */
+
+// Concise: 4 essential fields (~30 tokens per task)
+export interface TaskSummary {
+  id: string;
+  title: string;
+  status: string;
+  priority: string;
+}
+
+// Standard: 8 common fields (~60 tokens per task)
+export interface TaskPreview extends TaskSummary {
+  dueDate?: string;
+  tags?: string[];
+  contexts?: string[];
+  parentId?: string;
+}
+
+// Detailed: Full Task object (~200+ tokens per task)
+// Use the full Task type from task.ts
+
+/**
+ * Project projection types
+ */
+
+// Concise: 4 essential fields
+export interface ProjectSummary {
+  id: string;
+  name: string;
+  status: string;
+  completionPercentage?: number;
+}
+
+// Standard: 7 common fields
+export interface ProjectPreview extends ProjectSummary {
+  description?: string;
+  totalTasks?: number;
+  completedTasks?: number;
+}
+
+/**
+ * Inbox projection types
+ */
+
+// Concise: 3 essential fields
+export interface InboxSummary {
+  id: string;
+  content: string;
+  status: string;
+}
+
+// Standard: 5 common fields
+export interface InboxPreview extends InboxSummary {
+  capturedAt: string;
+  tags?: string[];
+}
+
+/**
+ * Analysis result types - optimized for token efficiency
+ */
+
+// Critical path summary (concise format)
+export interface CriticalPathSummary {
+  totalDuration: number;
+  taskCount: number;
+  taskIds: string[];
+}
+
+// Bottleneck summary (concise format)
+export interface BottleneckSummary {
+  taskId: string;
+  title: string;
+  blockedCount: number;
+}

package/src/schemas/task.ts

@@ -1,116 +1,184 @@
-import { type } from "arktype";
+import { z } from "zod";
 
 // Priority levels
-export const Priority = type("'critical' | 'high' | 'medium' | 'low'");
-export type Priority = typeof Priority.infer;
+export const Priority = z.enum(["critical", "high", "medium", "low"]);
+export type Priority = z.infer<typeof Priority>;
 
 // Task status with clear state machine
-export const TaskStatus = type(
-  "'pending' | 'in_progress' | 'blocked' | 'completed' | 'cancelled'"
-);
-export type TaskStatus = typeof TaskStatus.infer;
+export const TaskStatus = z.enum([
+  "pending",
+  "in_progress",
+  "blocked",
+  "completed",
+  "cancelled",
+]);
+export type TaskStatus = z.infer<typeof TaskStatus>;
 
 // Dependency relationship types
-export const DependencyType = type(
-  "'blocks' | 'blocked_by' | 'related'"
-);
-export type DependencyType = typeof DependencyType.infer;
+export const DependencyType = z.enum(["blocks", "blocked_by", "related"]);
+export type DependencyType = z.infer<typeof DependencyType>;
 
 // A single dependency link
-export const Dependency = type({
-  taskId: "string",
+export const Dependency = z.object({
+  taskId: z.string(),
   type: DependencyType,
-  "reason?": "string",
+  reason: z.string().optional(),
 });
-export type Dependency = typeof Dependency.infer;
+export type Dependency = z.infer<typeof Dependency>;
 
 // Time estimation
-export const TimeEstimate = type({
-  "optimistic?": "number", // minutes
-  "expected?": "number", // minutes
-  "pessimistic?": "number", // minutes
-  "confidence?": "'low' | 'medium' | 'high'",
+export const TimeEstimate = z.object({
+  optimistic: z.number().optional(), // minutes
+  expected: z.number().optional(), // minutes
+  pessimistic: z.number().optional(), // minutes
+  confidence: z.enum(["low", "medium", "high"]).optional(),
 });
-export type TimeEstimate = typeof TimeEstimate.infer;
+export type TimeEstimate = z.infer<typeof TimeEstimate>;
 
 // 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 const Recurrence = z.object({
+  pattern: z.enum(["daily", "weekly", "monthly", "after_completion"]),
+  interval: z.number().optional(), // every N days/weeks/months
+  daysOfWeek: z.array(z.number()).optional(), // 0-6 for weekly
+  endDate: z.string().optional(),
 });
-export type Recurrence = typeof Recurrence.infer;
+export type Recurrence = z.infer<typeof Recurrence>;
+
+// Complexity factors that contribute to task difficulty
+export const ComplexityFactor = z.enum([
+  "cross_cutting",
+  "state_management",
+  "error_handling",
+  "performance",
+  "security",
+  "external_dependency",
+  "data_migration",
+  "breaking_change",
+  "unclear_requirements",
+  "coordination",
+]);
+export type ComplexityFactor = z.infer<typeof ComplexityFactor>;
+
+// Complexity analysis result (populated by Claude)
+export const ComplexityAnalysis = z.object({
+  score: z.number().optional(), // 1-10 complexity score
+  factors: z.array(ComplexityFactor).optional(),
+  suggestedSubtasks: z.number().optional(), // 0-10 recommended subtask count
+  rationale: z.string().optional(),
+  analyzedAt: z.string().optional(),
+});
+export type ComplexityAnalysis = z.infer<typeof ComplexityAnalysis>;
+
+// Tech area categories for ordering
+export const TechArea = z.enum([
+  "schema",
+  "backend",
+  "frontend",
+  "infra",
+  "devops",
+  "test",
+  "docs",
+  "refactor",
+]);
+export type TechArea = z.infer<typeof TechArea>;
+
+// Risk level for changes
+export const RiskLevel = z.enum(["low", "medium", "high", "critical"]);
+export type RiskLevel = z.infer<typeof RiskLevel>;
+
+// Tech stack analysis result (populated by Claude)
+export const TechStackAnalysis = z.object({
+  areas: z.array(TechArea).optional(),
+  hasBreakingChange: z.boolean().optional(),
+  riskLevel: RiskLevel.optional(),
+  affectedComponents: z.array(z.string()).optional(),
+  rationale: z.string().optional(),
+  analyzedAt: z.string().optional(),
+});
+export type TechStackAnalysis = z.infer<typeof TechStackAnalysis>;
 
 // Core Task schema
-export const Task = type({
-  id: "string",
-  title: "string",
-  "description?": "string",
+export const Task = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
   status: TaskStatus,
   priority: Priority,
-  projectId: "string",
+  projectId: z.string(),
+
+  // Hierarchy (subtask support)
+  parentId: z.string().nullable().optional(), // Parent task ID for subtasks (null to unlink)
+  level: z.number().optional(), // Hierarchy depth (0=root, 1=subtask, 2=sub-subtask, max 3)
 
   // Dependencies
-  "dependencies?": Dependency.array(),
+  dependencies: z.array(Dependency).optional(),
 
   // Time tracking
-  "estimate?": TimeEstimate,
-  "actualMinutes?": "number",
-  "dueDate?": "string", // ISO date string
-  "startDate?": "string", // When task can start
-  "startedAt?": "string",
-  "completedAt?": "string",
+  estimate: TimeEstimate.optional(),
+  actualMinutes: z.number().optional(),
+  dueDate: z.string().optional(), // ISO date string
+  startDate: z.string().optional(), // When task can start
+  startedAt: z.string().optional(),
+  completedAt: z.string().optional(),
 
   // Organization
-  "contexts?": "string[]", // e.g., ["focus", "review"]
-  "tags?": "string[]",
+  contexts: z.array(z.string()).optional(), // e.g., ["focus", "review"]
+  tags: z.array(z.string()).optional(),
 
   // Recurrence
-  "recurrence?": Recurrence,
+  recurrence: Recurrence.optional(),
 
   // Metadata
-  createdAt: "string",
-  updatedAt: "string",
+  createdAt: z.string(),
+  updatedAt: z.string(),
 
   // Computed fields (populated at runtime)
-  "criticalPath?": "boolean",
-  "slack?": "number", // Minutes of slack time
-  "earliestStart?": "number", // Minutes from project start
-  "latestStart?": "number",
+  criticalPath: z.boolean().optional(),
+  slack: z.number().optional(), // Minutes of slack time
+  earliestStart: z.number().optional(), // Minutes from project start
+  latestStart: z.number().optional(),
+
+  // Analysis fields (populated by Claude)
+  complexity: ComplexityAnalysis.optional(),
+  techStack: TechStackAnalysis.optional(),
 });
-export type Task = typeof Task.infer;
+export type Task = z.infer<typeof Task>;
 
 // 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 const TaskCreateInput = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  projectId: z.string().optional(),
+  priority: Priority.optional(),
+  parentId: z.string().nullable().optional(), // Parent task ID for creating subtasks (null to unlink)
+  dependencies: z.array(Dependency).optional(),
+  estimate: TimeEstimate.optional(),
+  dueDate: z.string().optional(),
+  startDate: z.string().optional(),
+  contexts: z.array(z.string()).optional(),
+  tags: z.array(z.string()).optional(),
+  recurrence: Recurrence.optional(),
 });
-export type TaskCreateInput = typeof TaskCreateInput.infer;
+export type TaskCreateInput = z.infer<typeof TaskCreateInput>;
 
 // 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 const TaskUpdateInput = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  status: TaskStatus.optional(),
+  priority: Priority.optional(),
+  projectId: z.string().optional(),
+  parentId: z.string().nullable().optional(), // Parent task ID for moving task in hierarchy (null to unlink)
+  dependencies: z.array(Dependency).optional(),
+  estimate: TimeEstimate.optional(),
+  actualMinutes: z.number().optional(),
+  dueDate: z.string().optional(),
+  startDate: z.string().optional(),
+  contexts: z.array(z.string()).optional(),
+  tags: z.array(z.string()).optional(),
+  recurrence: Recurrence.optional(),
+  // Analysis fields
+  complexity: ComplexityAnalysis.optional(),
+  techStack: TechStackAnalysis.optional(),
 });
-export type TaskUpdateInput = typeof TaskUpdateInput.infer;
+export type TaskUpdateInput = z.infer<typeof TaskUpdateInput>;

package/src/schemas/view.ts

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

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;