task-o-matic-core 0.1.0

package/dist/services/tasks.js

@@ -0,0 +1,1150 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskService = exports.TaskService = void 0;
+exports.getTaskService = getTaskService;
+const ai_service_factory_1 = require("../utils/ai-service-factory");
+const stack_formatter_1 = require("../utils/stack-formatter");
+const ai_config_builder_1 = require("../utils/ai-config-builder");
+const hooks_1 = require("../lib/hooks");
+const logger_1 = require("../lib/logger");
+const streaming_utils_1 = require("../utils/streaming-utils");
+const error_utils_1 = require("../utils/error-utils");
+const id_generator_1 = require("../utils/id-generator");
+const task_o_matic_error_1 = require("../utils/task-o-matic-error");
+const metadata_utils_1 = require("../utils/metadata-utils");
+/**
+ * TaskService - Centralized business logic for all task operations
+ *
+ * This service provides a comprehensive API for task management with AI-powered features.
+ * It's framework-agnostic and can be used by CLI, TUI, or Web applications.
+ *
+ * @example
+ * ```typescript
+ * import { TaskService } from "task-o-matic";
+ *
+ * // Initialize with default configuration
+ * const taskService = new TaskService();
+ *
+ * // Create a task with AI enhancement
+ * const result = await taskService.createTask({
+ *   title: "Implement feature",
+ *   content: "Feature description",
+ *   aiEnhance: true,
+ *   aiOptions: {
+ *     provider: "anthropic",
+ *     model: "claude-3-5-sonnet"
+ *   }
+ * });
+ *
+ * // Or inject dependencies for testing
+ * const taskService = new TaskService({
+ *   storage: mockStorage,
+ *   aiOperations: mockAI,
+ * });
+ * ```
+ */
+class TaskService {
+    storage;
+    aiOperations;
+    modelProvider;
+    contextBuilder;
+    hooks;
+    /**
+     * Create a new TaskService
+     *
+     * @param dependencies - Optional dependencies to inject (for testing)
+     */
+    constructor(dependencies = {}) {
+        // Use injected dependencies or fall back to singletons
+        this.storage = dependencies.storage ?? (0, ai_service_factory_1.getStorage)();
+        this.aiOperations = dependencies.aiOperations ?? (0, ai_service_factory_1.getAIOperations)();
+        this.modelProvider = dependencies.modelProvider ?? (0, ai_service_factory_1.getModelProvider)();
+        this.contextBuilder = dependencies.contextBuilder ?? (0, ai_service_factory_1.getContextBuilder)();
+        this.hooks = dependencies.hooks ?? hooks_1.hooks;
+    }
+    // ============================================================================
+    // CORE CRUD OPERATIONS
+    // ============================================================================
+    /**
+     * Creates a new task with optional AI enhancement
+     *
+     * @param input - Task creation parameters
+     * @param input.title - Task title (required, 1-255 characters)
+     * @param input.content - Task content/description (optional)
+     * @param input.parentId - Parent task ID for creating subtasks
+     * @param input.effort - Estimated effort ("small" | "medium" | "large")
+     * @param input.aiEnhance - Enable AI enhancement with Context7 documentation
+     * @param input.aiOptions - AI configuration override
+     * @param input.streamingOptions - Real-time streaming options
+     *
+     * @returns Promise resolving to task creation result
+     *
+     * @throws {TaskOMaticError} If task creation fails (e.g., AI operation errors, storage errors)
+     * @throws {Error} If input validation fails
+     *
+     * @example Basic task creation
+     * ```typescript
+     * const task = await taskService.createTask({
+     *   title: "Fix authentication bug",
+     *   content: "Users cannot login with valid credentials",
+     *   aiEnhance: false
+     * });
+     * ```
+     *
+     * @example Task with AI enhancement
+     * ```typescript
+     * try {
+     *   const enhancedTask = await taskService.createTask({
+     *     title: "Design authentication system",
+     *     content: "Implement OAuth2 + JWT authentication",
+     *     aiEnhance: true,
+     *     streamingOptions: {
+     *       onChunk: (chunk) => console.log("AI:", chunk)
+     *     }
+     *   });
+     *   console.log("Enhanced content:", enhancedTask.task.content);
+     * } catch (error) {
+     *   if (error instanceof TaskOMaticError) {
+     *     console.error("AI enhancement failed:", error.getDetails());
+     *   }
+     * }
+     * ```
+     *
+     * @example Creating subtasks
+     * ```typescript
+     * const subtask = await taskService.createTask({
+     *   title: "Implement OAuth2 flow",
+     *   parentId: "1",
+     *   effort: "medium"
+     * });
+     * ```
+     */
+    async createTask(input) {
+        const startTime = Date.now();
+        let content = input.content;
+        let aiMetadata;
+        if (input.aiEnhance) {
+            this.hooks.emit("task:progress", {
+                message: "Building context for task...",
+                type: "progress",
+            });
+            // Build context with error handling (Bug fix 2.2)
+            let context;
+            try {
+                context = await this.contextBuilder.buildContextForNewTask(input.title, input.content);
+            }
+            catch (error) {
+                // Log warning but don't fail task creation
+                logger_1.logger.warn(`Warning: Could not build context: ${(0, error_utils_1.getErrorMessage)(error)}`);
+                // Continue with empty context
+                context = { stack: undefined, existingResearch: {} };
+            }
+            const stackInfo = (0, stack_formatter_1.formatStackInfo)(context.stack);
+            const enhancementAIConfig = (0, ai_config_builder_1.buildAIConfig)(input.aiOptions);
+            this.hooks.emit("task:progress", {
+                message: "Enhancing task with AI documentation...",
+                type: "progress",
+            });
+            const taskDescription = input.content ?? "";
+            // Generate temporary ID for AI operations (Bug fix 2.6)
+            const tempTaskId = id_generator_1.TaskIDGenerator.generate();
+            content = await this.aiOperations.enhanceTaskWithDocumentation(tempTaskId, input.title, taskDescription, stackInfo, input.streamingOptions, undefined, enhancementAIConfig, context.existingResearch);
+            const aiConfig = this.modelProvider.getAIConfig();
+            aiMetadata = {
+                taskId: "",
+                aiGenerated: true,
+                aiPrompt: "Enhance task with relevant documentation using Context7 tools",
+                confidence: 0.9,
+                aiProvider: aiConfig.provider,
+                aiModel: aiConfig.model,
+                generatedAt: Date.now(),
+            };
+        }
+        this.hooks.emit("task:progress", {
+            message: "Saving task...",
+            type: "progress",
+        });
+        const task = await this.storage.createTask({
+            title: input.title,
+            description: input.content ?? "",
+            content,
+            parentId: input.parentId,
+            estimatedEffort: input.effort,
+        }, aiMetadata);
+        this.hooks.emit("task:progress", {
+            type: "completed",
+            message: "Task created successfully",
+        });
+        // Emit task:created event
+        await this.hooks.emit("task:created", { task });
+        return { success: true, task, aiMetadata };
+    }
+    /**
+     * List tasks with optional filtering
+     *
+     * @param filters - Filter criteria
+     * @param filters.status - Filter by task status ("todo", "in-progress", "completed")
+     * @param filters.tag - Filter by task tag
+     *
+     * @returns Promise resolving to array of matching tasks
+     *
+     * @example
+     * ```typescript
+     * // List all tasks
+     * const allTasks = await taskService.listTasks({});
+     *
+     * // List only completed tasks
+     * const completedTasks = await taskService.listTasks({ status: "completed" });
+     *
+     * // List tasks with specific tag
+     * const frontendTasks = await taskService.listTasks({ tag: "frontend" });
+     * ```
+     */
+    async listTasks(filters) {
+        const storage = this.storage;
+        const topLevelTasks = await storage.getTopLevelTasks();
+        let filteredTasks = topLevelTasks;
+        if (filters.status) {
+            filteredTasks = filteredTasks.filter((task) => task.status === filters.status);
+        }
+        if (filters.tag) {
+            const tagToFilter = filters.tag; // Type narrowing
+            filteredTasks = filteredTasks.filter((task) => task.tags && task.tags.includes(tagToFilter));
+        }
+        return filteredTasks;
+    }
+    async getTask(id) {
+        return await this.storage.getTask(id);
+    }
+    async getTaskContent(id) {
+        return await this.storage.getTaskContent(id);
+    }
+    async getTaskAIMetadata(id) {
+        return await this.storage.getTaskAIMetadata(id);
+    }
+    async getSubtasks(id) {
+        return await this.storage.getSubtasks(id);
+    }
+    async updateTask(id, updates) {
+        const storage = this.storage;
+        const existingTask = await storage.getTask(id);
+        if (!existingTask) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(id);
+        }
+        // Validate status transitions
+        if (updates.status) {
+            // Allow same-status transitions as no-ops (needed for retry flows)
+            if (updates.status === existingTask.status) {
+                // Remove status from updates - it's already correct
+                delete updates.status;
+            }
+            else {
+                const validTransitions = {
+                    todo: ["in-progress", "completed"],
+                    "in-progress": ["completed", "todo"],
+                    completed: ["todo", "in-progress"],
+                };
+                if (!validTransitions[existingTask.status].includes(updates.status)) {
+                    throw (0, task_o_matic_error_1.formatInvalidStatusTransitionError)(existingTask.status, updates.status);
+                }
+            }
+        }
+        const finalUpdates = { ...updates };
+        // Handle tags: convert comma-separated string to array and merge
+        if (typeof updates.tags === "string") {
+            const newTags = updates.tags.split(",").map((tag) => tag.trim());
+            const existingTags = existingTask.tags || [];
+            finalUpdates.tags = [...new Set([...existingTags, ...newTags])];
+        }
+        const updatedTask = await storage.updateTask(id, finalUpdates);
+        if (!updatedTask) {
+            throw (0, task_o_matic_error_1.formatStorageError)(`updateTask ${id}`);
+        }
+        // Emit task:updated event
+        await this.hooks.emit("task:updated", {
+            task: updatedTask,
+            changes: finalUpdates,
+        });
+        // Emit task:status-changed event if status changed
+        if (updates.status && updates.status !== existingTask.status) {
+            await this.hooks.emit("task:status-changed", {
+                task: updatedTask,
+                oldStatus: existingTask.status,
+                newStatus: updates.status,
+            });
+        }
+        return updatedTask;
+    }
+    async setTaskStatus(id, status) {
+        return await this.updateTask(id, { status });
+    }
+    async deleteTask(id, options = {}) {
+        const { cascade, force } = options;
+        const storage = this.storage;
+        const taskToDelete = await storage.getTask(id);
+        if (!taskToDelete) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(id);
+        }
+        const deleted = [];
+        const orphanedSubtasks = [];
+        // Get subtasks before deletion
+        const subtasks = await storage.getSubtasks(id);
+        if (subtasks.length > 0 && !cascade) {
+            if (!force) {
+                throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.TASK_OPERATION_FAILED, `Cannot delete task with ${subtasks.length} subtasks`, {
+                    context: `Task ${id} has ${subtasks.length} subtasks`,
+                    suggestions: [
+                        "Use --cascade flag to delete task and all subtasks",
+                        "Use --force flag to delete task and orphan subtasks",
+                        "Delete subtasks first, then delete parent task",
+                    ],
+                    metadata: { taskId: id, subtaskCount: subtasks.length },
+                });
+            }
+            // Orphan subtasks by removing parent reference
+            for (const subtask of subtasks) {
+                await storage.updateTask(subtask.id, { parentId: undefined });
+                orphanedSubtasks.push(subtask);
+            }
+        }
+        else if (cascade) {
+            // Recursively delete subtasks
+            for (const subtask of subtasks) {
+                const result = await this.deleteTask(subtask.id, {
+                    cascade: true,
+                    force: true,
+                });
+                deleted.push(...result.deleted);
+                orphanedSubtasks.push(...result.orphanedSubtasks);
+            }
+        }
+        // Delete the main task
+        const success = await storage.deleteTask(id);
+        if (success) {
+            deleted.push(taskToDelete);
+            // Emit task:deleted event
+            await this.hooks.emit("task:deleted", { taskId: id });
+        }
+        return { success: true, deleted, orphanedSubtasks };
+    }
+    // ============================================================================
+    // TAG OPERATIONS
+    // ============================================================================
+    async addTags(id, tags) {
+        const storage = this.storage;
+        const task = await storage.getTask(id);
+        if (!task) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(id);
+        }
+        const existingTags = task.tags || [];
+        const newTags = tags.filter((tag) => !existingTags.includes(tag));
+        if (newTags.length === 0) {
+            return task; // No new tags to add
+        }
+        const updatedTags = [...existingTags, ...newTags];
+        const updatedTask = await storage.updateTask(id, { tags: updatedTags });
+        if (!updatedTask) {
+            throw (0, task_o_matic_error_1.formatStorageError)(`add tags to task ${id}`);
+        }
+        return updatedTask;
+    }
+    async removeTags(id, tags) {
+        const storage = this.storage;
+        const task = await storage.getTask(id);
+        if (!task) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(id);
+        }
+        const existingTags = task.tags || [];
+        const updatedTags = existingTags.filter((tag) => !tags.includes(tag));
+        if (updatedTags.length === existingTags.length) {
+            return task; // No tags removed
+        }
+        const updatedTask = await storage.updateTask(id, { tags: updatedTags });
+        if (!updatedTask) {
+            throw (0, task_o_matic_error_1.formatStorageError)(`remove tags from task ${id}`);
+        }
+        return updatedTask;
+    }
+    // ============================================================================
+    // TASK NAVIGATION
+    // ============================================================================
+    /**
+     * Get the next task based on priority and filtering criteria
+     *
+     * @param filters - Filter and priority criteria
+     * @param filters.status - Filter by task status
+     * @param filters.tag - Filter by task tag
+     * @param filters.effort - Filter by estimated effort
+     * @param filters.priority - Priority strategy ("newest", "oldest", "effort", or default)
+     *
+     * @returns Promise resolving to the highest priority task or null if none found
+     *
+     * @example
+     * ```typescript
+     * // Get the next task by default priority (task ID order)
+     * const nextTask = await taskService.getNextTask({});
+     *
+     * // Get the newest task with "todo" status
+     * const newestTodo = await taskService.getNextTask({
+     *   status: "todo",
+     *   priority: "newest"
+     * });
+     *
+     * // Get the highest effort task with specific tag
+     * const highEffortTask = await taskService.getNextTask({
+     *   tag: "backend",
+     *   priority: "effort"
+     * });
+     * ```
+     */
+    async getNextTask(filters) {
+        const storage = this.storage;
+        const allTasks = await storage.getTasks();
+        // Filter by status and other criteria
+        let filteredTasks = allTasks.filter((task) => {
+            if (filters.status && task.status !== filters.status)
+                return false;
+            if (filters.tag && (!task.tags || !task.tags.includes(filters.tag)))
+                return false;
+            if (filters.effort && task.estimatedEffort !== filters.effort)
+                return false;
+            return true;
+        });
+        if (filteredTasks.length === 0)
+            return null;
+        // Sort based on priority
+        switch (filters.priority) {
+            case "newest":
+                return filteredTasks.sort((a, b) => b.createdAt - a.createdAt)[0];
+            case "oldest":
+                return filteredTasks.sort((a, b) => a.createdAt - b.createdAt)[0];
+            case "effort":
+                const effortOrder = { small: 1, medium: 2, large: 3 };
+                return filteredTasks.sort((a, b) => (effortOrder[a.estimatedEffort || "medium"] || 2) -
+                    (effortOrder[b.estimatedEffort || "medium"] || 2))[0];
+            default:
+                // Default: task ID order (1, 1.1, 1.2, 2, 2.1, etc.)
+                return filteredTasks.sort((a, b) => a.id.localeCompare(b.id))[0];
+        }
+    }
+    async getTaskTree(rootId) {
+        const storage = this.storage;
+        if (rootId) {
+            // Return tree starting from specific task
+            const rootTask = await storage.getTask(rootId);
+            if (!rootTask) {
+                throw (0, task_o_matic_error_1.formatTaskNotFoundError)(rootId);
+            }
+            // Get all subtasks recursively
+            const getAllSubtasks = async (task) => {
+                const subtasks = await storage.getSubtasks(task.id);
+                const allSubtasks = [];
+                for (const subtask of subtasks) {
+                    allSubtasks.push(subtask);
+                    const deeperSubtasks = await getAllSubtasks(subtask);
+                    allSubtasks.push(...deeperSubtasks);
+                }
+                return allSubtasks;
+            };
+            const subtasks = await getAllSubtasks(rootTask);
+            return [rootTask, ...subtasks];
+        }
+        else {
+            // Return all top-level tasks and their subtasks
+            return await storage.getTasks();
+        }
+    }
+    // ============================================================================
+    // AI OPERATIONS
+    // ============================================================================
+    /**
+     * Enhance a task with AI-generated documentation using Context7
+     *
+     * Uses AI to enrich the task description with relevant documentation,
+     * code examples, and best practices from Context7 documentation sources.
+     *
+     * @param taskId - ID of the task to enhance
+     * @param aiOptions - Optional AI configuration overrides
+     * @param streamingOptions - Optional streaming callbacks for real-time feedback
+     * @returns Promise resolving to enhancement result with metrics
+     *
+     * @throws {Error} If task not found
+     * @throws {TaskOMaticError} If AI enhancement fails
+     *
+     * @example Basic enhancement
+     * ```typescript
+     * const result = await taskService.enhanceTask("1");
+     * console.log("Enhanced content:", result.enhancedContent);
+     * console.log("Took:", result.stats.duration, "ms");
+     * ```
+     *
+     * @example With streaming
+     * ```typescript
+     * try {
+     *   const result = await taskService.enhanceTask("1", undefined, {
+     *     onChunk: (chunk) => process.stdout.write(chunk)
+     *   });
+     *   console.log("\nEnhancement complete!");
+     * } catch (error) {
+     *   if (error instanceof TaskOMaticError) {
+     *     console.error("Enhancement failed:", error.getDetails());
+     *   }
+     * }
+     * ```
+     */
+    async enhanceTask(taskId, aiOptions, streamingOptions) {
+        const startTime = Date.now();
+        this.hooks.emit("task:progress", {
+            message: "Starting task enhancement...",
+            type: "started",
+        });
+        const task = await this.storage.getTask(taskId);
+        if (!task) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
+        }
+        this.hooks.emit("task:progress", {
+            message: "Building context...",
+            type: "progress",
+        });
+        const context = await this.contextBuilder.buildContext(taskId);
+        const stackInfo = (0, stack_formatter_1.formatStackInfo)(context.stack);
+        const enhancementAIConfig = (0, ai_config_builder_1.buildAIConfig)(aiOptions);
+        this.hooks.emit("task:progress", {
+            message: "Calling AI for enhancement...",
+            type: "progress",
+        });
+        // Use utility to wrap streaming options and capture metrics (DRY fix 1.1)
+        const aiStartTime = Date.now();
+        const { options: metricsStreamingOptions, getMetrics } = (0, streaming_utils_1.createMetricsStreamingOptions)(streamingOptions, aiStartTime);
+        const enhancedContent = await this.aiOperations.enhanceTaskWithDocumentation(task.id, task.title, task.description ?? "", stackInfo, metricsStreamingOptions, undefined, enhancementAIConfig, context.existingResearch);
+        // Extract metrics after AI call
+        const { tokenUsage, timeToFirstToken } = getMetrics();
+        this.hooks.emit("task:progress", {
+            message: "Saving enhanced content...",
+            type: "progress",
+        });
+        const originalLength = task.description?.length || 0;
+        if (enhancedContent.length > 200) {
+            const contentFile = await this.storage.saveEnhancedTaskContent(task.id, enhancedContent);
+            await this.storage.updateTask(task.id, {
+                contentFile,
+                description: task.description +
+                    "\n\n🤖 AI-enhanced with Context7 documentation available.",
+            });
+        }
+        else {
+            await this.storage.updateTask(task.id, { description: enhancedContent });
+        }
+        const aiConfig = this.modelProvider.getAIConfig();
+        const aiMetadata = {
+            taskId: task.id,
+            aiGenerated: true,
+            aiPrompt: "Enhance task with Context7 documentation using MCP tools",
+            confidence: 0.9,
+            aiProvider: aiConfig.provider,
+            aiModel: aiConfig.model,
+            enhancedAt: Date.now(),
+        };
+        await this.storage.saveTaskAIMetadata(aiMetadata);
+        const duration = Date.now() - startTime;
+        this.hooks.emit("task:progress", {
+            message: "Task enhancement completed",
+            type: "completed",
+        });
+        return {
+            success: true,
+            task,
+            enhancedContent,
+            stats: {
+                originalLength,
+                enhancedLength: enhancedContent.length,
+                duration,
+                tokenUsage,
+                timeToFirstToken,
+                cost: undefined, // Cost calculation can be added later
+            },
+            metadata: {
+                aiProvider: aiConfig.provider,
+                aiModel: aiConfig.model,
+                confidence: 0.9,
+            },
+        };
+    }
+    /**
+     * Split a task into subtasks using AI
+     *
+     * Analyzes the task and breaks it down into smaller, actionable subtasks
+     * with estimated effort. Can optionally use filesystem tools to understand
+     * project structure when creating subtasks.
+     *
+     * @param taskId - ID of the task to split
+     * @param aiOptions - Optional AI configuration overrides
+     * @param promptOverride - Optional custom prompt
+     * @param messageOverride - Optional custom message
+     * @param streamingOptions - Optional streaming callbacks
+     * @param enableFilesystemTools - Enable filesystem analysis for context
+     * @returns Promise resolving to split result with created subtasks
+     *
+     * @throws {Error} If task not found or already has subtasks
+     * @throws {TaskOMaticError} If AI operation fails
+     *
+     * @example Basic task splitting
+     * ```typescript
+     * const result = await taskService.splitTask("1");
+     * console.log(`Created ${result.subtasks.length} subtasks`);
+     * result.subtasks.forEach(subtask => {
+     *   console.log(`- ${subtask.title} (${subtask.estimatedEffort})`);
+     * });
+     * ```
+     *
+     * @example With filesystem tools for code analysis
+     * ```typescript
+     * try {
+     *   const result = await taskService.splitTask(
+     *     "1",
+     *     undefined,
+     *     undefined,
+     *     undefined,
+     *     { onChunk: (chunk) => console.log(chunk) },
+     *     true // Enable filesystem tools
+     *   );
+     *   console.log("AI analyzed codebase to create subtasks");
+     * } catch (error) {
+     *   if (error instanceof TaskOMaticError) {
+     *     console.error("Split failed:", error.suggestions);
+     *   }
+     * }
+     * ```
+     */
+    async splitTask(taskId, aiOptions, promptOverride, messageOverride, streamingOptions, enableFilesystemTools) {
+        const startTime = Date.now();
+        this.hooks.emit("task:progress", {
+            message: "Starting task breakdown...",
+            type: "started",
+        });
+        const task = await this.storage.getTask(taskId);
+        if (!task) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
+        }
+        // Check if task already has subtasks
+        const existingSubtasks = await this.storage.getSubtasks(taskId);
+        if (existingSubtasks.length > 0) {
+            throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.TASK_OPERATION_FAILED, `Task already has ${existingSubtasks.length} subtasks`, {
+                context: `Task "${task.title}" (${taskId}) already has subtasks`,
+                suggestions: [
+                    "Use existing subtasks instead of splitting again",
+                    "Delete existing subtasks first if you want to re-split",
+                    "Consider editing existing subtasks instead",
+                ],
+                metadata: { taskId, subtaskCount: existingSubtasks.length },
+            });
+        }
+        this.hooks.emit("task:progress", {
+            message: "Building context...",
+            type: "progress",
+        });
+        // Build comprehensive context
+        const context = await this.contextBuilder.buildContext(taskId);
+        const stackInfo = (0, stack_formatter_1.formatStackInfo)(context.stack);
+        // Get full task content
+        const fullContent = context.task.fullContent || task.description || "";
+        const breakdownAIConfig = (0, ai_config_builder_1.buildAIConfig)(aiOptions);
+        this.hooks.emit("task:progress", {
+            message: "Calling AI to break down task...",
+            type: "progress",
+        });
+        // Use utility to wrap streaming options and capture metrics (DRY fix 1.1)
+        const aiStartTime = Date.now();
+        const { options: metricsStreamingOptions, getMetrics } = (0, streaming_utils_1.createMetricsStreamingOptions)(streamingOptions, aiStartTime);
+        // Use AI service to break down the task with enhanced context
+        const subtaskData = await this.aiOperations.breakdownTask(task, breakdownAIConfig, promptOverride, messageOverride, metricsStreamingOptions, undefined, fullContent, stackInfo, existingSubtasks, enableFilesystemTools);
+        // Extract metrics after AI call
+        const { tokenUsage, timeToFirstToken } = getMetrics();
+        this.hooks.emit("task:progress", {
+            message: `Creating ${subtaskData.length} subtasks...`,
+            type: "progress",
+        });
+        // Create subtasks and save AI metadata for each (Bug fix 2.3)
+        const createdSubtasks = [];
+        const aiConfig = this.modelProvider.getAIConfig();
+        const splitTimestamp = Date.now();
+        for (let i = 0; i < subtaskData.length; i++) {
+            const subtask = subtaskData[i];
+            this.hooks.emit("task:progress", {
+                message: `Creating subtask ${i + 1}/${subtaskData.length}: ${subtask.title}`,
+                type: "progress",
+            });
+            // console.log(
+            //   `[DEBUG] Creating subtask ${i + 1}:`,
+            //   JSON.stringify(subtask, null, 2)
+            // );
+            try {
+                const result = await this.createTask({
+                    title: subtask.title,
+                    content: subtask.content,
+                    effort: subtask.estimatedEffort,
+                    parentId: taskId,
+                });
+                createdSubtasks.push(result.task);
+                // Save AI metadata for each subtask (Bug fix 2.3)
+                const subtaskMetadata = {
+                    ...(0, metadata_utils_1.createBaseAIMetadata)(result.task.id, aiConfig, promptOverride, "Split task into meaningful subtasks with full context and existing subtask awareness", 0.9),
+                    splitAt: splitTimestamp,
+                    parentTaskId: taskId,
+                    subtaskIndex: i + 1,
+                };
+                await (0, ai_service_factory_1.getStorage)().saveTaskAIMetadata(subtaskMetadata);
+            }
+            catch (err) {
+                logger_1.logger.error(`[DEBUG] Failed to create subtask ${i + 1}: ${err}`);
+                throw err;
+            }
+        }
+        // Save AI metadata for parent task as well
+        const parentMetadata = {
+            ...(0, metadata_utils_1.createBaseAIMetadata)(task.id, aiConfig, promptOverride, "Split task into meaningful subtasks with full context and existing subtask awareness", 0.9),
+            splitAt: splitTimestamp,
+            subtasksCreated: createdSubtasks.length,
+        };
+        await (0, ai_service_factory_1.getStorage)().saveTaskAIMetadata(parentMetadata);
+        const duration = Date.now() - startTime;
+        this.hooks.emit("task:progress", {
+            message: `Task split into ${createdSubtasks.length} subtasks`,
+            type: "completed",
+        });
+        return {
+            success: true,
+            task,
+            subtasks: createdSubtasks,
+            stats: {
+                subtasksCreated: createdSubtasks.length,
+                duration,
+                tokenUsage,
+                timeToFirstToken,
+                cost: undefined, // Cost calculation can be added later
+            },
+            metadata: {
+                aiProvider: aiConfig.provider,
+                aiModel: aiConfig.model,
+                confidence: 0.9,
+            },
+        };
+    }
+    /**
+     * Analyze and fetch documentation for a task using Context7
+     *
+     * Analyzes the task content to identify required libraries and documentation,
+     * then fetches relevant documentation from Context7. Caches documentation
+     * for future use.
+     *
+     * @param taskId - ID of the task to document
+     * @param force - Force re-fetch even if documentation exists
+     * @param aiOptions - Optional AI configuration overrides
+     * @param streamingOptions - Optional streaming callbacks
+     * @returns Promise resolving to documentation analysis result
+     *
+     * @throws {Error} If task not found or content is empty
+     * @throws {TaskOMaticError} If AI operation fails
+     *
+     * @example Analyze documentation needs
+     * ```typescript
+     * const result = await taskService.documentTask("1");
+     * if (result.documentation) {
+     *   console.log("Documentation fetched:");
+     *   console.log(result.documentation.recap);
+     *   console.log("Libraries:", result.documentation.libraries);
+     * }
+     * ```
+     *
+     * @example Force refresh documentation
+     * ```typescript
+     * try {
+     *   const result = await taskService.documentTask("1", true);
+     *   console.log(`Analyzed ${result.analysis.libraries.length} libraries`);
+     * } catch (error) {
+     *   if (error instanceof TaskOMaticError) {
+     *     console.error("Documentation fetch failed:", error.getDetails());
+     *   }
+     * }
+     * ```
+     */
+    async documentTask(taskId, force = false, aiOptions, streamingOptions) {
+        const startTime = Date.now();
+        this.hooks.emit("task:progress", {
+            message: "Analyzing documentation needs...",
+            type: "started",
+        });
+        const task = await this.storage.getTask(taskId);
+        if (!task) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
+        }
+        if (task.documentation && !force) {
+            if (this.contextBuilder.isDocumentationFresh(task.documentation)) {
+                this.hooks.emit("task:progress", {
+                    message: "Documentation is fresh, skipping analysis",
+                    type: "info",
+                });
+                return {
+                    success: true,
+                    task,
+                    documentation: task.documentation,
+                    stats: {
+                        duration: Date.now() - startTime,
+                    },
+                };
+            }
+        }
+        this.hooks.emit("task:progress", {
+            message: "Building context...",
+            type: "progress",
+        });
+        const context = await this.contextBuilder.buildContext(taskId);
+        const stackInfo = (0, stack_formatter_1.formatStackInfo)(context.stack);
+        const analysisAIConfig = (0, ai_config_builder_1.buildAIConfig)(aiOptions);
+        // Get full task content
+        const fullContent = context.task.fullContent || task.description;
+        if (!fullContent) {
+            throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, "Task content is empty", {
+                context: `Task ${taskId} has no content to enhance`,
+                suggestions: [
+                    "Add content to the task before enhancing",
+                    "Provide task description or details",
+                ],
+                metadata: { taskId },
+            });
+        }
+        // Get existing documentations from all tasks
+        const tasks = await this.storage.getTasks();
+        const documentations = tasks.map((task) => task.documentation);
+        this.hooks.emit("task:progress", {
+            message: "Calling AI to analyze documentation needs...",
+            type: "progress",
+        });
+        // First analyze what documentation is needed
+        const analysis = await this.aiOperations.analyzeDocumentationNeeds(task.id, task.title, fullContent, stackInfo, streamingOptions, undefined, analysisAIConfig, documentations);
+        let documentation;
+        if (analysis.libraries.length > 0) {
+            this.hooks.emit("task:progress", {
+                message: `Fetching documentation for ${analysis.libraries.length} libraries...`,
+                type: "progress",
+            });
+            // Build research object from actual libraries
+            const research = {};
+            for (const lib of analysis.libraries) {
+                const sanitizedLibrary = this.storage.sanitizeForFilename(lib.name);
+                const sanitizedQuery = this.storage.sanitizeForFilename(lib.searchQuery);
+                const docFile = `docs/${sanitizedLibrary}/${sanitizedQuery}.md`;
+                if (!research[lib.name]) {
+                    research[lib.name] = [];
+                }
+                research[lib.name].push({
+                    query: lib.searchQuery,
+                    doc: docFile,
+                });
+            }
+            this.hooks.emit("task:progress", {
+                message: "Generating documentation recap...",
+                type: "progress",
+            });
+            const recap = await this.aiOperations.generateDocumentationRecap(analysis.libraries, analysis.toolResults?.map((tr) => ({
+                library: tr.toolName,
+                content: JSON.stringify(tr.output),
+            })) || [], streamingOptions);
+            documentation = {
+                lastFetched: Date.now(),
+                libraries: analysis.libraries.map((lib) => lib.context7Id),
+                recap,
+                files: analysis.files || [],
+                research,
+            };
+            this.hooks.emit("task:progress", {
+                message: "Saving documentation...",
+                type: "progress",
+            });
+            await this.storage.updateTask(taskId, { documentation });
+        }
+        const duration = Date.now() - startTime;
+        this.hooks.emit("task:progress", {
+            message: "Documentation analysis completed",
+            type: "completed",
+        });
+        return {
+            success: true,
+            task,
+            analysis,
+            documentation,
+            stats: {
+                duration,
+            },
+        };
+    }
+    /**
+     * Generate an implementation plan for a task using AI
+     *
+     * Creates a detailed implementation plan with steps, considerations,
+     * and technical approach. Uses filesystem and Context7 tools to understand
+     * the project context and provide relevant suggestions.
+     *
+     * @param taskId - ID of the task to plan
+     * @param aiOptions - Optional AI configuration overrides
+     * @param streamingOptions - Optional streaming callbacks
+     * @returns Promise resolving to plan result with generated plan text
+     *
+     * @throws {Error} If task not found
+     * @throws {TaskOMaticError} If AI operation fails
+     *
+     * @example Basic implementation planning
+     * ```typescript
+     * const result = await taskService.planTask("1");
+     * console.log("Implementation Plan:");
+     * console.log(result.plan);
+     * console.log(`Generated in ${result.stats.duration}ms`);
+     * ```
+     *
+     * @example With streaming for real-time plan generation
+     * ```typescript
+     * try {
+     *   const result = await taskService.planTask("1", undefined, {
+     *     onChunk: (chunk) => {
+     *       // Display plan as it's generated
+     *       process.stdout.write(chunk);
+     *     }
+     *   });
+     *   console.log("\n\nPlan saved to:", `plans/${result.task.id}.md`);
+     * } catch (error) {
+     *   if (error instanceof TaskOMaticError) {
+     *     console.error("Planning failed:", error.getDetails());
+     *   }
+     * }
+     * ```
+     */
+    async planTask(taskId, aiOptions, streamingOptions) {
+        const startTime = Date.now();
+        this.hooks.emit("task:progress", {
+            message: "Creating implementation plan...",
+            type: "started",
+        });
+        const task = await this.storage.getTask(taskId);
+        if (!task) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
+        }
+        const aiService = this.aiOperations;
+        const planAIConfig = (0, ai_config_builder_1.buildAIConfig)(aiOptions);
+        this.hooks.emit("task:progress", {
+            message: "Building task context...",
+            type: "progress",
+        });
+        // Build task context and details
+        let taskContext = `Task ID: ${task.id}\nTitle: ${task.title}\n`;
+        let taskDetails = `Description: ${task.description || "No description"}\n`;
+        // If this is a subtask, include parent task context
+        if (task.parentId) {
+            const parentTask = await (0, ai_service_factory_1.getStorage)().getTask(task.parentId);
+            if (parentTask) {
+                taskContext += `Parent Task ID: ${parentTask.id}\nParent Task Title: ${parentTask.title}\n`;
+                taskDetails += `Parent Task Description: ${parentTask.description || "No description"}\n`;
+            }
+        }
+        // If this is a task with subtasks, get subtask details
+        const subtasks = await (0, ai_service_factory_1.getStorage)().getSubtasks(taskId);
+        if (subtasks.length > 0) {
+            taskDetails += `\nSubtasks:\n`;
+            subtasks.forEach((subtask, index) => {
+                taskDetails += `${index + 1}. ${subtask.title} (${subtask.id})\n`;
+                taskDetails += `   ${subtask.description || "No description"}\n\n`;
+            });
+        }
+        this.hooks.emit("task:progress", {
+            message: "Calling AI to create plan...",
+            type: "progress",
+        });
+        // Use utility to wrap streaming options and capture metrics (DRY fix 1.1)
+        const aiStartTime = Date.now();
+        const { options: metricsStreamingOptions, getMetrics } = (0, streaming_utils_1.createMetricsStreamingOptions)(streamingOptions, aiStartTime);
+        const plan = await aiService.planTask(taskContext, taskDetails, planAIConfig, undefined, undefined, metricsStreamingOptions);
+        // Extract metrics after AI call
+        const { tokenUsage, timeToFirstToken } = getMetrics();
+        this.hooks.emit("task:progress", {
+            message: "Saving plan...",
+            type: "progress",
+        });
+        // Save the plan to storage
+        await this.storage.savePlan(taskId, plan);
+        const duration = Date.now() - startTime;
+        this.hooks.emit("task:progress", {
+            message: "Implementation plan created",
+            type: "completed",
+        });
+        const aiConfig = this.modelProvider.getAIConfig();
+        return {
+            success: true,
+            task,
+            plan,
+            stats: {
+                duration,
+                tokenUsage,
+                timeToFirstToken,
+                cost: undefined, // Cost calculation can be added later
+            },
+            metadata: {
+                aiProvider: aiConfig.provider,
+                aiModel: aiConfig.model,
+            },
+        };
+    }
+    // ============================================================================
+    // DOCUMENTATION OPERATIONS
+    // ============================================================================
+    async getTaskDocumentation(taskId) {
+        return this.storage.getTaskDocumentation(taskId);
+    }
+    async addTaskDocumentationFromFile(taskId, filePath) {
+        const task = await this.getTask(taskId);
+        if (!task) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
+        }
+        try {
+            const { readFileSync, existsSync } = await Promise.resolve().then(() => __importStar(require("fs")));
+            const { resolve } = await Promise.resolve().then(() => __importStar(require("path")));
+            const resolvedPath = resolve(filePath);
+            if (!existsSync(resolvedPath)) {
+                throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.STORAGE_ERROR, `Documentation file not found: ${filePath}`, {
+                    context: `Tried to load documentation from ${resolvedPath}`,
+                    suggestions: [
+                        "Check that the file path is correct",
+                        "Ensure the file exists",
+                        "Use an absolute path or path relative to current directory",
+                    ],
+                    metadata: { filePath, resolvedPath },
+                });
+            }
+            const content = readFileSync(resolvedPath, "utf-8");
+            const savedPath = await this.storage.saveTaskDocumentation(taskId, content);
+            return {
+                filePath: savedPath,
+                task,
+            };
+        }
+        catch (error) {
+            // Re-throw if already a TaskOMaticError
+            if (error instanceof task_o_matic_error_1.TaskOMaticError) {
+                throw error;
+            }
+            // Wrap other errors
+            throw (0, task_o_matic_error_1.formatStorageError)("saveTaskDocumentation", error instanceof Error ? error : undefined);
+        }
+    }
+    async setTaskPlan(taskId, planText, planFilePath) {
+        const task = await this.getTask(taskId);
+        if (!task) {
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
+        }
+        let plan;
+        if (planFilePath) {
+            try {
+                const { readFileSync, existsSync } = await Promise.resolve().then(() => __importStar(require("fs")));
+                const { resolve } = await Promise.resolve().then(() => __importStar(require("path")));
+                const resolvedPath = resolve(planFilePath);
+                if (!existsSync(resolvedPath)) {
+                    throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.STORAGE_ERROR, `Plan file not found: ${planFilePath}`, {
+                        context: `Tried to load plan from ${resolvedPath}`,
+                        suggestions: [
+                            "Check that the file path is correct",
+                            "Ensure the file exists",
+                            "Use an absolute path or path relative to current directory",
+                        ],
+                        metadata: { planFilePath, resolvedPath },
+                    });
+                }
+                plan = readFileSync(resolvedPath, "utf-8");
+            }
+            catch (error) {
+                // Re-throw if already a TaskOMaticError
+                if (error instanceof task_o_matic_error_1.TaskOMaticError) {
+                    throw error;
+                }
+                // Wrap other errors
+                throw (0, task_o_matic_error_1.formatStorageError)("readFileSync", error instanceof Error ? error : undefined);
+            }
+        }
+        else if (planText) {
+            plan = planText;
+        }
+        else {
+            throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, "Either planText or planFilePath must be provided", {
+                context: "setTaskPlan requires either planText or planFilePath parameter",
+                suggestions: [
+                    "Provide planText parameter with the plan content",
+                    "Provide planFilePath parameter with path to plan file",
+                ],
+                metadata: { taskId },
+            });
+        }
+        await this.storage.savePlan(taskId, plan);
+        const planFile = `plans/${taskId}.md`;
+        return {
+            planFile,
+            task,
+        };
+    }
+    // ============================================================================
+    // PLAN OPERATIONS
+    // ============================================================================
+    async getTaskPlan(taskId) {
+        return this.storage.getPlan(taskId);
+    }
+    async listTaskPlans() {
+        return this.storage.listPlans();
+    }
+    async deleteTaskPlan(taskId) {
+        return this.storage.deletePlan(taskId);
+    }
+}
+exports.TaskService = TaskService;
+// Lazy singleton instance - only created when first accessed
+let taskServiceInstance;
+function getTaskService() {
+    if (!taskServiceInstance) {
+        taskServiceInstance = new TaskService();
+    }
+    return taskServiceInstance;
+}
+// Backward compatibility: export as const but use getter
+exports.taskService = new Proxy({}, {
+    get(target, prop) {
+        return getTaskService()[prop];
+    },
+});