task-o-matic 0.0.14 → 0.0.15

package/dist/utils/model-executor-parser.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VALID_EXECUTORS = void 0;
 exports.parseTryModels = parseTryModels;
 exports.validateExecutor = validateExecutor;
+const task_o_matic_error_1 = require("./task-o-matic-error");
 /**
  * Valid executor tools
  */
@@ -21,7 +22,7 @@ exports.VALID_EXECUTORS = [
  *
  * @param value - Comma-separated model/executor specifications
  * @returns Array of model attempt configurations
- * @throws Error if an invalid executor is specified
+ * @throws TaskOMaticError if an invalid executor is specified
  *
  * @example
  * ```typescript
@@ -36,7 +37,7 @@ function parseTryModels(value) {
         if (trimmed.includes(":")) {
             const [executor, model] = trimmed.split(":");
             if (!exports.VALID_EXECUTORS.includes(executor)) {
-                throw new Error(`Invalid executor "${executor}" in --try-models. Must be one of: ${exports.VALID_EXECUTORS.join(", ")}`);
+                throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, `Invalid executor "${executor}" in --try-models. Must be one of: ${exports.VALID_EXECUTORS.join(", ")}`);
             }
             return {
                 executor: executor,

package/dist/utils/storage-utils.d.ts

@@ -6,7 +6,7 @@ import { Task } from "../types/index.js";
  * @param task - Task that may be null
  * @param taskId - ID of the task for error message
  * @returns The task if not null
- * @throws Error if task is null
+ * @throws TaskOMaticError if task is null
  *
  * @example
  * ```typescript
@@ -22,7 +22,7 @@ export declare function requireTask(task: Task | null, taskId: string): Task;
  * @param tasks - Array of tasks that may contain nulls
  * @param context - Context for error message (e.g., "subtasks", "dependencies")
  * @returns Array of tasks with nulls filtered out
- * @throws Error if any task is null
+ * @throws TaskOMaticError if any task is null
  */
 export declare function requireTasks(tasks: (Task | null)[], context?: string): Task[];
 /**
@@ -43,7 +43,7 @@ export declare function filterNullTasks(tasks: (Task | null)[]): Task[];
  * Validates that a task ID is a non-empty string.
  *
  * @param taskId - Task ID to validate
- * @throws Error if task ID is invalid
+ * @throws TaskOMaticError if task ID is invalid
  */
 export declare function validateTaskId(taskId: string): void;
 //# sourceMappingURL=storage-utils.d.ts.map

package/dist/utils/storage-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-utils.d.ts","sourceRoot":"","sources":["../../src/utils/storage-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAKnE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,EACtB,OAAO,GAAE,MAAgB,GACxB,IAAI,EAAE,CAiBR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAInD"}
+{"version":3,"file":"storage-utils.d.ts","sourceRoot":"","sources":["../../src/utils/storage-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAOzC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAKnE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,EACtB,OAAO,GAAE,MAAgB,GACxB,IAAI,EAAE,CAoBR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAOnD"}

package/dist/utils/storage-utils.js

@@ -4,6 +4,7 @@ exports.requireTask = requireTask;
 exports.requireTasks = requireTasks;
 exports.filterNullTasks = filterNullTasks;
 exports.validateTaskId = validateTaskId;
+const task_o_matic_error_1 = require("./task-o-matic-error");
 /**
  * Ensures a task is not null, throwing an error if it is.
  * Useful for enforcing null checks after storage operations.
@@ -11,7 +12,7 @@ exports.validateTaskId = validateTaskId;
  * @param task - Task that may be null
  * @param taskId - ID of the task for error message
  * @returns The task if not null
- * @throws Error if task is null
+ * @throws TaskOMaticError if task is null
  *
  * @example
  * ```typescript
@@ -22,7 +23,7 @@ exports.validateTaskId = validateTaskId;
  */
 function requireTask(task, taskId) {
     if (!task) {
-        throw new Error(`Task not found: ${taskId}`);
+        throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
     }
     return task;
 }
@@ -32,7 +33,7 @@ function requireTask(task, taskId) {
  * @param tasks - Array of tasks that may contain nulls
  * @param context - Context for error message (e.g., "subtasks", "dependencies")
  * @returns Array of tasks with nulls filtered out
- * @throws Error if any task is null
+ * @throws TaskOMaticError if any task is null
  */
 function requireTasks(tasks, context = "tasks") {
     const validTasks = [];
@@ -46,7 +47,7 @@ function requireTasks(tasks, context = "tasks") {
         }
     });
     if (missingIds.length > 0) {
-        throw new Error(`Missing ${context}: ${missingIds.join(", ")}`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.STORAGE_INTEGRITY_ERROR, `Missing ${context}: ${missingIds.join(", ")}`);
     }
     return validTasks;
 }
@@ -70,10 +71,10 @@ function filterNullTasks(tasks) {
  * Validates that a task ID is a non-empty string.
  *
  * @param taskId - Task ID to validate
- * @throws Error if task ID is invalid
+ * @throws TaskOMaticError if task ID is invalid
  */
 function validateTaskId(taskId) {
     if (!taskId || typeof taskId !== "string" || !taskId.trim()) {
-        throw new Error("Invalid task ID: must be a non-empty string");
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, "Invalid task ID: must be a non-empty string");
     }
 }

package/dist/utils/task-o-matic-error.d.ts

@@ -0,0 +1,206 @@
+/**
+ * TaskOMaticError - Standardized error class for TaskOMatic
+ *
+ * Provides consistent error handling with context, suggestions, and typing.
+ * All errors in the system should use this class or one of the helper functions
+ * to ensure consistent error reporting and debugging experience.
+ *
+ * @example Basic usage
+ * ```typescript
+ * throw new TaskOMaticError("Task not found", {
+ *   code: "TASK_NOT_FOUND",
+ *   context: "Attempted to retrieve task ID: 123",
+ *   suggestions: [
+ *     "Verify the task ID is correct",
+ *     "Check if the task was deleted"
+ *   ]
+ * });
+ * ```
+ *
+ * @example With cause chain
+ * ```typescript
+ * try {
+ *   await storage.getTask(id);
+ * } catch (error) {
+ *   throw new TaskOMaticError("Failed to retrieve task", {
+ *     code: "STORAGE_ERROR",
+ *     cause: error instanceof Error ? error : new Error(String(error)),
+ *     context: `Task ID: ${id}`,
+ *     suggestions: ["Check storage permissions", "Verify storage is initialized"]
+ *   });
+ * }
+ * ```
+ *
+ * @example With metadata
+ * ```typescript
+ * throw new TaskOMaticError("AI operation timed out", {
+ *   code: "AI_OPERATION_FAILED",
+ *   metadata: {
+ *     operation: "task-breakdown",
+ *     duration: 30000,
+ *     retryAttempts: 3
+ *   },
+ *   suggestions: ["Increase timeout", "Check AI service status"]
+ * });
+ * ```
+ */
+export declare class TaskOMaticError extends Error {
+    /**
+     * Error code for categorization
+     */
+    code: string;
+    /**
+     * Additional context information
+     */
+    context?: string;
+    /**
+     * Actionable suggestions for resolving the error
+     */
+    suggestions?: string[];
+    /**
+     * Original error that caused this error (if applicable)
+     */
+    cause?: Error;
+    /**
+     * Timestamp when the error occurred
+     */
+    timestamp: number;
+    /**
+     * Additional metadata for debugging
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Create a new TaskOMaticError
+     *
+     * @param message - Error message
+     * @param options - Additional error options
+     */
+    constructor(message: string, options: {
+        code: string;
+        context?: string;
+        suggestions?: string[];
+        cause?: Error;
+        metadata?: Record<string, unknown>;
+    });
+    /**
+     * Get full error details as a formatted string
+     */
+    getDetails(): string;
+    /**
+     * Get error details as a structured object
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        context?: string;
+        suggestions?: string[];
+        cause?: string;
+        timestamp: number;
+        metadata?: Record<string, unknown>;
+        stack?: string;
+    };
+}
+/**
+ * Standard error codes for TaskOMatic
+ */
+export declare const TaskOMaticErrorCodes: {
+    readonly UNEXPECTED_ERROR: "TASK_O_MATIC_001";
+    readonly INVALID_INPUT: "TASK_O_MATIC_002";
+    readonly CONFIGURATION_ERROR: "TASK_O_MATIC_003";
+    readonly TASK_NOT_FOUND: "TASK_O_MATIC_101";
+    readonly TASK_ALREADY_EXISTS: "TASK_O_MATIC_102";
+    readonly INVALID_TASK_STATUS: "TASK_O_MATIC_103";
+    readonly TASK_OPERATION_FAILED: "TASK_O_MATIC_104";
+    readonly STORAGE_ERROR: "TASK_O_MATIC_201";
+    readonly STORAGE_NOT_INITIALIZED: "TASK_O_MATIC_202";
+    readonly STORAGE_INTEGRITY_ERROR: "TASK_O_MATIC_203";
+    readonly AI_OPERATION_FAILED: "TASK_O_MATIC_301";
+    readonly AI_CONFIGURATION_ERROR: "TASK_O_MATIC_302";
+    readonly AI_RATE_LIMIT: "TASK_O_MATIC_303";
+    readonly WORKFLOW_VALIDATION_ERROR: "TASK_O_MATIC_401";
+    readonly WORKFLOW_EXECUTION_ERROR: "TASK_O_MATIC_402";
+    readonly PRD_PARSING_ERROR: "TASK_O_MATIC_501";
+    readonly PRD_GENERATION_ERROR: "TASK_O_MATIC_502";
+    readonly PRD_VALIDATION_ERROR: "TASK_O_MATIC_503";
+};
+type TaskOMaticErrorCode = (typeof TaskOMaticErrorCodes)[keyof typeof TaskOMaticErrorCodes];
+/**
+ * Create a standardized error with context and suggestions
+ *
+ * Helper function to create TaskOMaticError instances with proper error codes
+ * from the TaskOMaticErrorCodes constants.
+ *
+ * @param code - Error code from TaskOMaticErrorCodes
+ * @param message - Human-readable error message
+ * @param options - Additional error options
+ * @returns Configured TaskOMaticError instance
+ *
+ * @example
+ * ```typescript
+ * throw createStandardError(
+ *   TaskOMaticErrorCodes.TASK_NOT_FOUND,
+ *   "Task with ID '123' not found",
+ *   {
+ *     context: "User attempted to retrieve non-existent task",
+ *     suggestions: ["Verify task ID", "List all tasks to see available IDs"]
+ *   }
+ * );
+ * ```
+ */
+export declare function createStandardError(code: TaskOMaticErrorCode, message: string, options?: {
+    context?: string;
+    suggestions?: string[];
+    cause?: Error;
+    metadata?: Record<string, unknown>;
+}): TaskOMaticError;
+/**
+ * Format an existing error into a TaskOMaticError with context and suggestions
+ *
+ * Useful for wrapping caught errors with additional context while preserving
+ * the original error as the cause.
+ *
+ * @param error - Original error to wrap
+ * @param code - Error code from TaskOMaticErrorCodes
+ * @param options - Additional error options
+ * @returns TaskOMaticError wrapping the original error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await dangerousOperation();
+ * } catch (error) {
+ *   throw formatStandardError(
+ *     error,
+ *     TaskOMaticErrorCodes.STORAGE_ERROR,
+ *     {
+ *       context: "Failed during task persistence",
+ *       suggestions: ["Check disk space", "Verify write permissions"]
+ *     }
+ *   );
+ * }
+ * ```
+ */
+export declare function formatStandardError(error: unknown, code: TaskOMaticErrorCode, options?: {
+    context?: string;
+    suggestions?: string[];
+    metadata?: Record<string, unknown>;
+}): TaskOMaticError;
+/**
+ * Type guard for TaskOMaticError
+ */
+export declare function isTaskOMaticError(error: unknown): error is TaskOMaticError;
+/**
+ * Common error formatting functions
+ */
+export declare function formatTaskNotFoundError(taskId: string): TaskOMaticError;
+export declare function formatInvalidStatusTransitionError(fromStatus: string, toStatus: string): TaskOMaticError;
+export declare function formatStorageError(operation: string, cause?: Error): TaskOMaticError;
+export declare function formatAIOperationError(operation: string, cause?: Error): TaskOMaticError;
+/**
+ * Backward compatibility wrapper
+ * Maintains existing error handling patterns while using new error system
+ */
+export declare function wrapErrorForBackwardCompatibility(error: unknown, context?: string): Error;
+export {};
+//# sourceMappingURL=task-o-matic-error.d.ts.map

package/dist/utils/task-o-matic-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-o-matic-error.d.ts","sourceRoot":"","sources":["../../src/utils/task-o-matic-error.ts"],"names":[],"mappings":"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"}

package/dist/utils/task-o-matic-error.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskOMaticErrorCodes = exports.TaskOMaticError = void 0;
+exports.createStandardError = createStandardError;
+exports.formatStandardError = formatStandardError;
+exports.isTaskOMaticError = isTaskOMaticError;
+exports.formatTaskNotFoundError = formatTaskNotFoundError;
+exports.formatInvalidStatusTransitionError = formatInvalidStatusTransitionError;
+exports.formatStorageError = formatStorageError;
+exports.formatAIOperationError = formatAIOperationError;
+exports.wrapErrorForBackwardCompatibility = wrapErrorForBackwardCompatibility;
+const error_utils_1 = require("./error-utils");
+/**
+ * TaskOMaticError - Standardized error class for TaskOMatic
+ *
+ * Provides consistent error handling with context, suggestions, and typing.
+ * All errors in the system should use this class or one of the helper functions
+ * to ensure consistent error reporting and debugging experience.
+ *
+ * @example Basic usage
+ * ```typescript
+ * throw new TaskOMaticError("Task not found", {
+ *   code: "TASK_NOT_FOUND",
+ *   context: "Attempted to retrieve task ID: 123",
+ *   suggestions: [
+ *     "Verify the task ID is correct",
+ *     "Check if the task was deleted"
+ *   ]
+ * });
+ * ```
+ *
+ * @example With cause chain
+ * ```typescript
+ * try {
+ *   await storage.getTask(id);
+ * } catch (error) {
+ *   throw new TaskOMaticError("Failed to retrieve task", {
+ *     code: "STORAGE_ERROR",
+ *     cause: error instanceof Error ? error : new Error(String(error)),
+ *     context: `Task ID: ${id}`,
+ *     suggestions: ["Check storage permissions", "Verify storage is initialized"]
+ *   });
+ * }
+ * ```
+ *
+ * @example With metadata
+ * ```typescript
+ * throw new TaskOMaticError("AI operation timed out", {
+ *   code: "AI_OPERATION_FAILED",
+ *   metadata: {
+ *     operation: "task-breakdown",
+ *     duration: 30000,
+ *     retryAttempts: 3
+ *   },
+ *   suggestions: ["Increase timeout", "Check AI service status"]
+ * });
+ * ```
+ */
+class TaskOMaticError extends Error {
+    /**
+     * Error code for categorization
+     */
+    code;
+    /**
+     * Additional context information
+     */
+    context;
+    /**
+     * Actionable suggestions for resolving the error
+     */
+    suggestions;
+    /**
+     * Original error that caused this error (if applicable)
+     */
+    cause;
+    /**
+     * Timestamp when the error occurred
+     */
+    timestamp;
+    /**
+     * Additional metadata for debugging
+     */
+    metadata;
+    /**
+     * Create a new TaskOMaticError
+     *
+     * @param message - Error message
+     * @param options - Additional error options
+     */
+    constructor(message, options) {
+        super(message);
+        this.name = "TaskOMaticError";
+        this.code = options.code;
+        this.context = options.context;
+        this.suggestions = options.suggestions;
+        this.cause = options.cause;
+        this.timestamp = Date.now();
+        this.metadata = options.metadata;
+        // Maintain proper stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TaskOMaticError);
+        }
+    }
+    /**
+     * Get full error details as a formatted string
+     */
+    getDetails() {
+        let details = `[${this.code}] ${this.message}`;
+        if (this.context) {
+            details += `\nContext: ${this.context}`;
+        }
+        if (this.suggestions && this.suggestions.length > 0) {
+            details += `\nSuggestions:\n- ${this.suggestions.join("\n- ")}`;
+        }
+        if (this.cause) {
+            details += `\nCaused by: ${this.cause.message}`;
+        }
+        if (this.metadata && Object.keys(this.metadata).length > 0) {
+            details += `\nMetadata: ${JSON.stringify(this.metadata, null, 2)}`;
+        }
+        return details;
+    }
+    /**
+     * Get error details as a structured object
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            suggestions: this.suggestions,
+            cause: this.cause?.message,
+            timestamp: this.timestamp,
+            metadata: this.metadata,
+            stack: this.stack,
+        };
+    }
+}
+exports.TaskOMaticError = TaskOMaticError;
+/**
+ * Standard error codes for TaskOMatic
+ */
+exports.TaskOMaticErrorCodes = {
+    // General errors
+    UNEXPECTED_ERROR: "TASK_O_MATIC_001",
+    INVALID_INPUT: "TASK_O_MATIC_002",
+    CONFIGURATION_ERROR: "TASK_O_MATIC_003",
+    // Task-related errors
+    TASK_NOT_FOUND: "TASK_O_MATIC_101",
+    TASK_ALREADY_EXISTS: "TASK_O_MATIC_102",
+    INVALID_TASK_STATUS: "TASK_O_MATIC_103",
+    TASK_OPERATION_FAILED: "TASK_O_MATIC_104",
+    // Storage errors
+    STORAGE_ERROR: "TASK_O_MATIC_201",
+    STORAGE_NOT_INITIALIZED: "TASK_O_MATIC_202",
+    STORAGE_INTEGRITY_ERROR: "TASK_O_MATIC_203",
+    // AI operation errors
+    AI_OPERATION_FAILED: "TASK_O_MATIC_301",
+    AI_CONFIGURATION_ERROR: "TASK_O_MATIC_302",
+    AI_RATE_LIMIT: "TASK_O_MATIC_303",
+    // Workflow errors
+    WORKFLOW_VALIDATION_ERROR: "TASK_O_MATIC_401",
+    WORKFLOW_EXECUTION_ERROR: "TASK_O_MATIC_402",
+    // PRD errors
+    PRD_PARSING_ERROR: "TASK_O_MATIC_501",
+    PRD_GENERATION_ERROR: "TASK_O_MATIC_502",
+    PRD_VALIDATION_ERROR: "TASK_O_MATIC_503",
+};
+/**
+ * Create a standardized error with context and suggestions
+ *
+ * Helper function to create TaskOMaticError instances with proper error codes
+ * from the TaskOMaticErrorCodes constants.
+ *
+ * @param code - Error code from TaskOMaticErrorCodes
+ * @param message - Human-readable error message
+ * @param options - Additional error options
+ * @returns Configured TaskOMaticError instance
+ *
+ * @example
+ * ```typescript
+ * throw createStandardError(
+ *   TaskOMaticErrorCodes.TASK_NOT_FOUND,
+ *   "Task with ID '123' not found",
+ *   {
+ *     context: "User attempted to retrieve non-existent task",
+ *     suggestions: ["Verify task ID", "List all tasks to see available IDs"]
+ *   }
+ * );
+ * ```
+ */
+function createStandardError(code, message, options = {}) {
+    return new TaskOMaticError(message, {
+        code,
+        context: options.context,
+        suggestions: options.suggestions,
+        cause: options.cause,
+        metadata: options.metadata,
+    });
+}
+/**
+ * Format an existing error into a TaskOMaticError with context and suggestions
+ *
+ * Useful for wrapping caught errors with additional context while preserving
+ * the original error as the cause.
+ *
+ * @param error - Original error to wrap
+ * @param code - Error code from TaskOMaticErrorCodes
+ * @param options - Additional error options
+ * @returns TaskOMaticError wrapping the original error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await dangerousOperation();
+ * } catch (error) {
+ *   throw formatStandardError(
+ *     error,
+ *     TaskOMaticErrorCodes.STORAGE_ERROR,
+ *     {
+ *       context: "Failed during task persistence",
+ *       suggestions: ["Check disk space", "Verify write permissions"]
+ *     }
+ *   );
+ * }
+ * ```
+ */
+function formatStandardError(error, code, options = {}) {
+    const message = (0, error_utils_1.getErrorMessage)(error);
+    const cause = error instanceof Error ? error : undefined;
+    return new TaskOMaticError(message, {
+        code,
+        context: options.context,
+        suggestions: options.suggestions,
+        cause,
+        metadata: options.metadata,
+    });
+}
+/**
+ * Type guard for TaskOMaticError
+ */
+function isTaskOMaticError(error) {
+    return error instanceof TaskOMaticError;
+}
+/**
+ * Common error formatting functions
+ */
+function formatTaskNotFoundError(taskId) {
+    return createStandardError(exports.TaskOMaticErrorCodes.TASK_NOT_FOUND, `Task with ID "${taskId}" not found`, {
+        context: `The task "${taskId}" could not be found in the storage.`,
+        suggestions: [
+            "Verify the task ID is correct",
+            "Check if the task was deleted",
+            "List all tasks to see available IDs",
+        ],
+    });
+}
+function formatInvalidStatusTransitionError(fromStatus, toStatus) {
+    return createStandardError(exports.TaskOMaticErrorCodes.INVALID_TASK_STATUS, `Invalid status transition from "${fromStatus}" to "${toStatus}"`, {
+        context: `Task status transitions must follow the workflow: todo -> in-progress -> completed.`,
+        suggestions: [
+            "Use a valid status transition",
+            "Check the current task status",
+            "Review the workflow documentation",
+        ],
+    });
+}
+function formatStorageError(operation, cause) {
+    return createStandardError(exports.TaskOMaticErrorCodes.STORAGE_ERROR, `Storage operation "${operation}" failed`, {
+        context: `The storage operation "${operation}" could not be completed.`,
+        suggestions: [
+            "Check storage permissions",
+            "Verify storage configuration",
+            "Review storage logs for details",
+        ],
+        cause,
+    });
+}
+function formatAIOperationError(operation, cause) {
+    return createStandardError(exports.TaskOMaticErrorCodes.AI_OPERATION_FAILED, `AI operation "${operation}" failed`, {
+        context: `The AI operation "${operation}" could not be completed.`,
+        suggestions: [
+            "Check AI configuration",
+            "Verify API keys and endpoints",
+            "Review AI service status",
+            "Check rate limits",
+        ],
+        cause,
+    });
+}
+/**
+ * Backward compatibility wrapper
+ * Maintains existing error handling patterns while using new error system
+ */
+function wrapErrorForBackwardCompatibility(error, context) {
+    if (isTaskOMaticError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error((0, error_utils_1.formatError)(error, context));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-o-matic",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "AI-powered task management CLI",
   "keywords": [
     "task-management",
@@ -50,7 +50,7 @@
     "dev:mcp": "tsx src/mcp/server.ts",
     "start": "node dist/cli/bin.js",
     "check-types": "tsc --noEmit --skipLibCheck",
-    "test": "mocha -r tsx/cjs src/test/**/*.test.ts",
+    "test": "mocha -r tsx/cjs src/test/test-setup.ts src/test/**/*.test.ts",
     "prepare": "npm run build && chmod +x dist/cli/bin.js",
     "prepublishOnly": "bun run build && chmod +x dist/cli/bin.js && bun test"
   },