task-o-matic 0.0.14 → 0.0.16

package/dist/services/tasks.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 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");
@@ -41,27 +42,128 @@ const hooks_1 = require("../lib/hooks");
 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 is framework-agnostic and can be used by CLI, TUI, or Web
+ *
+ * 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) {
-            hooks_1.hooks.emit("task:progress", {
+            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 (0, ai_service_factory_1.getContextBuilder)().buildContextForNewTask(input.title, input.content);
+                context = await this.contextBuilder.buildContextForNewTask(input.title, input.content);
             }
             catch (error) {
                 // Log warning but don't fail task creation
@@ -71,15 +173,15 @@ class TaskService {
             }
             const stackInfo = (0, stack_formatter_1.formatStackInfo)(context.stack);
             const enhancementAIConfig = (0, ai_config_builder_1.buildAIConfig)(input.aiOptions);
-            hooks_1.hooks.emit("task:progress", {
+            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 (0, ai_service_factory_1.getAIOperations)().enhanceTaskWithDocumentation(tempTaskId, input.title, taskDescription, stackInfo, input.streamingOptions, undefined, enhancementAIConfig, context.existingResearch);
-            const aiConfig = (0, ai_service_factory_1.getModelProvider)().getAIConfig();
+            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,
@@ -90,27 +192,48 @@ class TaskService {
                 generatedAt: Date.now(),
             };
         }
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Saving task...",
             type: "progress",
         });
-        const task = await (0, ai_service_factory_1.getStorage)().createTask({
+        const task = await this.storage.createTask({
             title: input.title,
             description: input.content ?? "",
             content,
             parentId: input.parentId,
             estimatedEffort: input.effort,
         }, aiMetadata);
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             type: "completed",
             message: "Task created successfully",
         });
         // Emit task:created event
-        await hooks_1.hooks.emit("task:created", { task });
+        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 = (0, ai_service_factory_1.getStorage)();
+        const storage = this.storage;
         const topLevelTasks = await storage.getTopLevelTasks();
         let filteredTasks = topLevelTasks;
         if (filters.status) {
@@ -123,22 +246,22 @@ class TaskService {
         return filteredTasks;
     }
     async getTask(id) {
-        return await (0, ai_service_factory_1.getStorage)().getTask(id);
+        return await this.storage.getTask(id);
     }
     async getTaskContent(id) {
-        return await (0, ai_service_factory_1.getStorage)().getTaskContent(id);
+        return await this.storage.getTaskContent(id);
     }
     async getTaskAIMetadata(id) {
-        return await (0, ai_service_factory_1.getStorage)().getTaskAIMetadata(id);
+        return await this.storage.getTaskAIMetadata(id);
     }
     async getSubtasks(id) {
-        return await (0, ai_service_factory_1.getStorage)().getSubtasks(id);
+        return await this.storage.getSubtasks(id);
     }
     async updateTask(id, updates) {
-        const storage = (0, ai_service_factory_1.getStorage)();
+        const storage = this.storage;
         const existingTask = await storage.getTask(id);
         if (!existingTask) {
-            throw new Error(`Task with ID ${id} not found`);
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(id);
         }
         // Validate status transitions
         if (updates.status) {
@@ -148,7 +271,7 @@ class TaskService {
                 completed: ["todo", "in-progress"],
             };
             if (!validTransitions[existingTask.status].includes(updates.status)) {
-                throw new Error(`Invalid status transition from ${existingTask.status} to ${updates.status}`);
+                throw (0, task_o_matic_error_1.formatInvalidStatusTransitionError)(existingTask.status, updates.status);
             }
         }
         const finalUpdates = { ...updates };
@@ -160,16 +283,16 @@ class TaskService {
         }
         const updatedTask = await storage.updateTask(id, finalUpdates);
         if (!updatedTask) {
-            throw new Error(`Failed to update task ${id}`);
+            throw (0, task_o_matic_error_1.formatStorageError)(`updateTask ${id}`);
         }
         // Emit task:updated event
-        await hooks_1.hooks.emit("task:updated", {
+        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 hooks_1.hooks.emit("task:status-changed", {
+            await this.hooks.emit("task:status-changed", {
                 task: updatedTask,
                 oldStatus: existingTask.status,
                 newStatus: updates.status,
@@ -182,10 +305,10 @@ class TaskService {
     }
     async deleteTask(id, options = {}) {
         const { cascade, force } = options;
-        const storage = (0, ai_service_factory_1.getStorage)();
+        const storage = this.storage;
         const taskToDelete = await storage.getTask(id);
         if (!taskToDelete) {
-            throw new Error(`Task with ID ${id} not found`);
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(id);
         }
         const deleted = [];
         const orphanedSubtasks = [];
@@ -193,7 +316,15 @@ class TaskService {
         const subtasks = await storage.getSubtasks(id);
         if (subtasks.length > 0 && !cascade) {
             if (!force) {
-                throw new Error(`Task has ${subtasks.length} subtasks. Use cascade to delete them or force to orphan them`);
+                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) {
@@ -217,7 +348,7 @@ class TaskService {
         if (success) {
             deleted.push(taskToDelete);
             // Emit task:deleted event
-            await hooks_1.hooks.emit("task:deleted", { taskId: id });
+            await this.hooks.emit("task:deleted", { taskId: id });
         }
         return { success: true, deleted, orphanedSubtasks };
     }
@@ -225,10 +356,10 @@ class TaskService {
     // TAG OPERATIONS
     // ============================================================================
     async addTags(id, tags) {
-        const storage = (0, ai_service_factory_1.getStorage)();
+        const storage = this.storage;
         const task = await storage.getTask(id);
         if (!task) {
-            throw new Error(`Task with ID ${id} not found`);
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(id);
         }
         const existingTags = task.tags || [];
         const newTags = tags.filter((tag) => !existingTags.includes(tag));
@@ -238,15 +369,15 @@ class TaskService {
         const updatedTags = [...existingTags, ...newTags];
         const updatedTask = await storage.updateTask(id, { tags: updatedTags });
         if (!updatedTask) {
-            throw new Error(`Failed to add tags to task ${id}`);
+            throw (0, task_o_matic_error_1.formatStorageError)(`add tags to task ${id}`);
         }
         return updatedTask;
     }
     async removeTags(id, tags) {
-        const storage = (0, ai_service_factory_1.getStorage)();
+        const storage = this.storage;
         const task = await storage.getTask(id);
         if (!task) {
-            throw new Error(`Task with ID ${id} not found`);
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(id);
         }
         const existingTags = task.tags || [];
         const updatedTags = existingTags.filter((tag) => !tags.includes(tag));
@@ -255,15 +386,44 @@ class TaskService {
         }
         const updatedTask = await storage.updateTask(id, { tags: updatedTags });
         if (!updatedTask) {
-            throw new Error(`Failed to remove tags from task ${id}`);
+            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 = (0, ai_service_factory_1.getStorage)();
+        const storage = this.storage;
         const allTasks = await storage.getTasks();
         // Filter by status and other criteria
         let filteredTasks = allTasks.filter((task) => {
@@ -293,12 +453,12 @@ class TaskService {
         }
     }
     async getTaskTree(rootId) {
-        const storage = (0, ai_service_factory_1.getStorage)();
+        const storage = this.storage;
         if (rootId) {
             // Return tree starting from specific task
             const rootTask = await storage.getTask(rootId);
             if (!rootTask) {
-                throw new Error(`Task with ID ${rootId} not found`);
+                throw (0, task_o_matic_error_1.formatTaskNotFoundError)(rootId);
             }
             // Get all subtasks recursively
             const getAllSubtasks = async (task) => {
@@ -322,50 +482,85 @@ class TaskService {
     // ============================================================================
     // 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();
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Starting task enhancement...",
             type: "started",
         });
-        const task = await (0, ai_service_factory_1.getStorage)().getTask(taskId);
+        const task = await this.storage.getTask(taskId);
         if (!task) {
-            throw new Error(`Task with ID ${taskId} not found`);
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
         }
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Building context...",
             type: "progress",
         });
-        const context = await (0, ai_service_factory_1.getContextBuilder)().buildContext(taskId);
+        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);
-        hooks_1.hooks.emit("task:progress", {
+        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 (0, ai_service_factory_1.getAIOperations)().enhanceTaskWithDocumentation(task.id, task.title, task.description ?? "", stackInfo, metricsStreamingOptions, undefined, enhancementAIConfig, context.existingResearch);
+        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();
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Saving enhanced content...",
             type: "progress",
         });
         const originalLength = task.description?.length || 0;
         if (enhancedContent.length > 200) {
-            const contentFile = await (0, ai_service_factory_1.getStorage)().saveEnhancedTaskContent(task.id, enhancedContent);
-            await (0, ai_service_factory_1.getStorage)().updateTask(task.id, {
+            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 (0, ai_service_factory_1.getStorage)().updateTask(task.id, { description: enhancedContent });
+            await this.storage.updateTask(task.id, { description: enhancedContent });
         }
-        const aiConfig = (0, ai_service_factory_1.getModelProvider)().getAIConfig();
+        const aiConfig = this.modelProvider.getAIConfig();
         const aiMetadata = {
             taskId: task.id,
             aiGenerated: true,
@@ -375,9 +570,9 @@ class TaskService {
             aiModel: aiConfig.model,
             enhancedAt: Date.now(),
         };
-        await (0, ai_service_factory_1.getStorage)().saveTaskAIMetadata(aiMetadata);
+        await this.storage.saveTaskAIMetadata(aiMetadata);
         const duration = Date.now() - startTime;
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Task enhancement completed",
             type: "completed",
         });
@@ -400,32 +595,86 @@ class TaskService {
             },
         };
     }
+    /**
+     * 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();
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Starting task breakdown...",
             type: "started",
         });
-        const task = await (0, ai_service_factory_1.getStorage)().getTask(taskId);
+        const task = await this.storage.getTask(taskId);
         if (!task) {
-            throw new Error(`Task with ID ${taskId} not found`);
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
         }
         // Check if task already has subtasks
-        const existingSubtasks = await (0, ai_service_factory_1.getStorage)().getSubtasks(taskId);
+        const existingSubtasks = await this.storage.getSubtasks(taskId);
         if (existingSubtasks.length > 0) {
-            throw new Error(`Task ${task.title} already has ${existingSubtasks.length} subtasks. Use existing subtasks or delete them first.`);
+            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 },
+            });
         }
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Building context...",
             type: "progress",
         });
         // Build comprehensive context
-        const context = await (0, ai_service_factory_1.getContextBuilder)().buildContext(taskId);
+        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);
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Calling AI to break down task...",
             type: "progress",
         });
@@ -433,20 +682,20 @@ class TaskService {
         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 (0, ai_service_factory_1.getAIOperations)().breakdownTask(task, breakdownAIConfig, promptOverride, messageOverride, metricsStreamingOptions, undefined, fullContent, stackInfo, existingSubtasks, enableFilesystemTools);
+        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();
-        hooks_1.hooks.emit("task:progress", {
+        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 = (0, ai_service_factory_1.getModelProvider)().getAIConfig();
+        const aiConfig = this.modelProvider.getAIConfig();
         const splitTimestamp = Date.now();
         for (let i = 0; i < subtaskData.length; i++) {
             const subtask = subtaskData[i];
-            hooks_1.hooks.emit("task:progress", {
+            this.hooks.emit("task:progress", {
                 message: `Creating subtask ${i + 1}/${subtaskData.length}: ${subtask.title}`,
                 type: "progress",
             });
@@ -459,13 +708,7 @@ class TaskService {
             createdSubtasks.push(result.task);
             // Save AI metadata for each subtask (Bug fix 2.3)
             const subtaskMetadata = {
-                taskId: result.task.id,
-                aiGenerated: true,
-                aiPrompt: promptOverride ||
-                    "Split task into meaningful subtasks with full context and existing subtask awareness",
-                confidence: 0.9,
-                aiProvider: aiConfig.provider,
-                aiModel: aiConfig.model,
+                ...(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,
@@ -474,19 +717,13 @@ class TaskService {
         }
         // Save AI metadata for parent task as well
         const parentMetadata = {
-            taskId: task.id,
-            aiGenerated: true,
-            aiPrompt: promptOverride ||
-                "Split task into meaningful subtasks with full context and existing subtask awareness",
-            confidence: 0.9,
-            aiProvider: aiConfig.provider,
-            aiModel: aiConfig.model,
+            ...(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;
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: `Task split into ${createdSubtasks.length} subtasks`,
             type: "completed",
         });
@@ -508,19 +745,57 @@ class TaskService {
             },
         };
     }
+    /**
+     * 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();
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Analyzing documentation needs...",
             type: "started",
         });
-        const task = await (0, ai_service_factory_1.getStorage)().getTask(taskId);
+        const task = await this.storage.getTask(taskId);
         if (!task) {
-            throw new Error(`Task with ID ${taskId} not found`);
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
         }
         if (task.documentation && !force) {
-            if ((0, ai_service_factory_1.getContextBuilder)().isDocumentationFresh(task.documentation)) {
-                hooks_1.hooks.emit("task:progress", {
+            if (this.contextBuilder.isDocumentationFresh(task.documentation)) {
+                this.hooks.emit("task:progress", {
                     message: "Documentation is fresh, skipping analysis",
                     type: "info",
                 });
@@ -534,38 +809,45 @@ class TaskService {
                 };
             }
         }
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Building context...",
             type: "progress",
         });
-        const context = await (0, ai_service_factory_1.getContextBuilder)().buildContext(taskId);
+        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 new Error("Task content is empty");
+            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 (0, ai_service_factory_1.getStorage)().getTasks();
+        const tasks = await this.storage.getTasks();
         const documentations = tasks.map((task) => task.documentation);
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Calling AI to analyze documentation needs...",
             type: "progress",
         });
         // First analyze what documentation is needed
-        const analysis = await (0, ai_service_factory_1.getAIOperations)().analyzeDocumentationNeeds(task.id, task.title, fullContent, stackInfo, streamingOptions, undefined, analysisAIConfig, documentations);
+        const analysis = await this.aiOperations.analyzeDocumentationNeeds(task.id, task.title, fullContent, stackInfo, streamingOptions, undefined, analysisAIConfig, documentations);
         let documentation;
         if (analysis.libraries.length > 0) {
-            hooks_1.hooks.emit("task:progress", {
+            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 = (0, ai_service_factory_1.getStorage)().sanitizeForFilename(lib.name);
-                const sanitizedQuery = (0, ai_service_factory_1.getStorage)().sanitizeForFilename(lib.searchQuery);
+                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] = [];
@@ -575,11 +857,11 @@ class TaskService {
                     doc: docFile,
                 });
             }
-            hooks_1.hooks.emit("task:progress", {
+            this.hooks.emit("task:progress", {
                 message: "Generating documentation recap...",
                 type: "progress",
             });
-            const recap = await (0, ai_service_factory_1.getAIOperations)().generateDocumentationRecap(analysis.libraries, analysis.toolResults?.map((tr) => ({
+            const recap = await this.aiOperations.generateDocumentationRecap(analysis.libraries, analysis.toolResults?.map((tr) => ({
                 library: tr.toolName,
                 content: JSON.stringify(tr.output),
             })) || [], streamingOptions);
@@ -590,14 +872,14 @@ class TaskService {
                 files: analysis.files || [],
                 research,
             };
-            hooks_1.hooks.emit("task:progress", {
+            this.hooks.emit("task:progress", {
                 message: "Saving documentation...",
                 type: "progress",
             });
-            await (0, ai_service_factory_1.getStorage)().updateTask(taskId, { documentation });
+            await this.storage.updateTask(taskId, { documentation });
         }
         const duration = Date.now() - startTime;
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Documentation analysis completed",
             type: "completed",
         });
@@ -611,19 +893,59 @@ class TaskService {
             },
         };
     }
+    /**
+     * 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();
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Creating implementation plan...",
             type: "started",
         });
-        const task = await (0, ai_service_factory_1.getStorage)().getTask(taskId);
+        const task = await this.storage.getTask(taskId);
         if (!task) {
-            throw new Error(`Task with ID ${taskId} not found`);
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
         }
-        const aiService = (0, ai_service_factory_1.getAIOperations)();
+        const aiService = this.aiOperations;
         const planAIConfig = (0, ai_config_builder_1.buildAIConfig)(aiOptions);
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Building task context...",
             type: "progress",
         });
@@ -647,7 +969,7 @@ class TaskService {
                 taskDetails += `   ${subtask.description || "No description"}\n\n`;
             });
         }
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Calling AI to create plan...",
             type: "progress",
         });
@@ -657,18 +979,18 @@ class TaskService {
         const plan = await aiService.planTask(taskContext, taskDetails, planAIConfig, undefined, undefined, metricsStreamingOptions);
         // Extract metrics after AI call
         const { tokenUsage, timeToFirstToken } = getMetrics();
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Saving plan...",
             type: "progress",
         });
         // Save the plan to storage
-        await (0, ai_service_factory_1.getStorage)().savePlan(taskId, plan);
+        await this.storage.savePlan(taskId, plan);
         const duration = Date.now() - startTime;
-        hooks_1.hooks.emit("task:progress", {
+        this.hooks.emit("task:progress", {
             message: "Implementation plan created",
             type: "completed",
         });
-        const aiConfig = (0, ai_service_factory_1.getModelProvider)().getAIConfig();
+        const aiConfig = this.modelProvider.getAIConfig();
         return {
             success: true,
             task,
@@ -689,36 +1011,48 @@ class TaskService {
     // DOCUMENTATION OPERATIONS
     // ============================================================================
     async getTaskDocumentation(taskId) {
-        return (0, ai_service_factory_1.getStorage)().getTaskDocumentation(taskId);
+        return this.storage.getTaskDocumentation(taskId);
     }
     async addTaskDocumentationFromFile(taskId, filePath) {
         const task = await this.getTask(taskId);
         if (!task) {
-            throw new Error(`Task with ID ${taskId} not found`);
+            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 new Error(`Documentation file not found: ${filePath}`);
+                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 (0, ai_service_factory_1.getStorage)().saveTaskDocumentation(taskId, content);
+            const savedPath = await this.storage.saveTaskDocumentation(taskId, content);
             return {
                 filePath: savedPath,
                 task,
             };
         }
         catch (error) {
-            // Use utility for error message extraction (DRY fix 1.3)
-            throw new Error(`Failed to add documentation from file: ${(0, error_utils_1.getErrorMessage)(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 new Error(`Task with ID ${taskId} not found`);
+            throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
         }
         let plan;
         if (planFilePath) {
@@ -727,22 +1061,41 @@ class TaskService {
                 const { resolve } = await Promise.resolve().then(() => __importStar(require("path")));
                 const resolvedPath = resolve(planFilePath);
                 if (!existsSync(resolvedPath)) {
-                    throw new Error(`Plan file not found: ${planFilePath}`);
+                    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) {
-                // Use utility for error message extraction (DRY fix 1.3)
-                throw new Error(`Failed to read plan file: ${(0, error_utils_1.getErrorMessage)(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 new Error("Either planText or planFilePath must be provided");
+            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 (0, ai_service_factory_1.getStorage)().savePlan(taskId, plan);
+        await this.storage.savePlan(taskId, plan);
         const planFile = `plans/${taskId}.md`;
         return {
             planFile,
@@ -753,15 +1106,27 @@ class TaskService {
     // PLAN OPERATIONS
     // ============================================================================
     async getTaskPlan(taskId) {
-        return (0, ai_service_factory_1.getStorage)().getPlan(taskId);
+        return this.storage.getPlan(taskId);
     }
     async listTaskPlans() {
-        return (0, ai_service_factory_1.getStorage)().listPlans();
+        return this.storage.listPlans();
     }
     async deleteTaskPlan(taskId) {
-        return (0, ai_service_factory_1.getStorage)().deletePlan(taskId);
+        return this.storage.deletePlan(taskId);
     }
 }
 exports.TaskService = TaskService;
-// Export singleton instance
-exports.taskService = new 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];
+    },
+});