task-o-matic-core 0.1.0

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

@@ -0,0 +1,69 @@
+"use strict";
+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
+ */
+exports.VALID_EXECUTORS = [
+    "opencode",
+    "claude",
+    "gemini",
+    "codex",
+    "kilo",
+];
+/**
+ * Parse --try-models option into ModelAttemptConfig array
+ * Supports formats:
+ * - "model1,model2,model3" - just models (uses default executor)
+ * - "opencode:gpt-4o,claude:sonnet-4" - executor:model format
+ * - Mixed: "gpt-4o,claude:sonnet-4,gemini:gemini-2.0"
+ *
+ * @param value - Comma-separated model/executor specifications
+ * @returns Array of model attempt configurations
+ * @throws TaskOMaticError if an invalid executor is specified
+ *
+ * @example
+ * ```typescript
+ * parseTryModels("gpt-4o-mini,gpt-4o"); // [{ model: "gpt-4o-mini" }, { model: "gpt-4o" }]
+ * parseTryModels("opencode:gpt-4o,claude:sonnet-4"); // [{ executor: "opencode", model: "gpt-4o" }, ...]
+ * ```
+ */
+function parseTryModels(value) {
+    return value.split(",").map((item) => {
+        const trimmed = item.trim();
+        // Check if it includes executor specification (executor:model format)
+        if (trimmed.includes(":")) {
+            const [executor, model] = trimmed.split(":");
+            if (!exports.VALID_EXECUTORS.includes(executor)) {
+                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,
+                model: model.trim(),
+            };
+        }
+        // Just a model name - use default executor
+        return {
+            model: trimmed,
+        };
+    });
+}
+/**
+ * Validate that an executor name is valid
+ *
+ * @param executor - Executor name to validate
+ * @returns Type guard confirming executor is valid
+ *
+ * @example
+ * ```typescript
+ * if (validateExecutor(options.tool)) {
+ *   // TypeScript knows options.tool is ExecutorTool
+ * }
+ * ```
+ */
+function validateExecutor(executor) {
+    return exports.VALID_EXECUTORS.includes(executor);
+}

package/dist/utils/model-parser.d.ts

@@ -0,0 +1,6 @@
+export declare function parseModelString(modelStr: string): {
+    provider?: string;
+    model: string;
+    reasoning?: string;
+};
+//# sourceMappingURL=model-parser.d.ts.map

package/dist/utils/model-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-parser.d.ts","sourceRoot":"","sources":["../../src/utils/model-parser.ts"],"names":[],"mappings":"AAGA,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAkDA"}

package/dist/utils/model-parser.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseModelString = parseModelString;
+const validation_1 = require("../lib/validation");
+// Helper to parse model string ([provider:]model[;reasoning[=budget]])
+function parseModelString(modelStr) {
+    let processingStr = modelStr;
+    let reasoning;
+    // 1. Extract reasoning
+    // Format: ;reasoning or ;reasoning=1000
+    const reasoningMatch = processingStr.match(/;reasoning(?:=(\d+))?$/);
+    if (reasoningMatch) {
+        // If specific budget provided (group 1), use it.
+        // Otherwise default to "2000" as requested.
+        reasoning = reasoningMatch[1] ? reasoningMatch[1] : "2000";
+        // Remove the reasoning suffix from the string
+        processingStr = processingStr.substring(0, reasoningMatch.index);
+    }
+    // 2. Extract provider and model
+    // We look for the first colon.
+    const firstColonIndex = processingStr.indexOf(":");
+    if (firstColonIndex === -1) {
+        // No colon -> It's just a model name (provider inferred from env/defaults later)
+        return {
+            provider: undefined,
+            model: processingStr,
+            reasoning,
+        };
+    }
+    // Has colon. Check if the part before is a valid provider.
+    const potentialProvider = processingStr.substring(0, firstColonIndex);
+    const potentialModel = processingStr.substring(firstColonIndex + 1);
+    if ((0, validation_1.isValidAIProvider)(potentialProvider)) {
+        // It is a known provider
+        return {
+            provider: potentialProvider,
+            model: potentialModel,
+            reasoning,
+        };
+    }
+    // Not a known provider. Treat the whole thing as the model name.
+    // This handles cases like "google/gemini...:free" where "google/gemini..." isn't a provider key.
+    // Or just "model:with:colons".
+    return {
+        provider: undefined,
+        model: processingStr,
+        reasoning,
+    };
+}

package/dist/utils/stack-formatter.d.ts

@@ -0,0 +1,12 @@
+import type { BTSFrontend } from "../types/index.js";
+export interface StackInfo {
+    frontend: BTSFrontend | BTSFrontend[];
+    backend: string;
+    database: string;
+    orm: string;
+    auth: string;
+    addons: string[];
+}
+export declare function formatStackInfo(stack: StackInfo | null | undefined): string;
+export declare function formatStackForContext(stack: StackInfo | null | undefined): string;
+//# sourceMappingURL=stack-formatter.d.ts.map

package/dist/utils/stack-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-formatter.d.ts","sourceRoot":"","sources":["../../src/utils/stack-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CA6B3E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAUjF"}

package/dist/utils/stack-formatter.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatStackInfo = formatStackInfo;
+exports.formatStackForContext = formatStackForContext;
+function formatStackInfo(stack) {
+    if (!stack) {
+        return "Not detected";
+    }
+    const frontendStr = Array.isArray(stack.frontend)
+        ? stack.frontend.join(", ")
+        : stack.frontend;
+    const parts = [
+        `Frontend: ${frontendStr}`,
+        `Backend: ${stack.backend}`
+    ];
+    if (stack.database !== 'none') {
+        parts.push(`Database: ${stack.database}`);
+    }
+    if (stack.orm !== 'none') {
+        parts.push(`ORM: ${stack.orm}`);
+    }
+    parts.push(`Auth: ${stack.auth}`);
+    if (stack.addons.length > 0) {
+        parts.push(`Addons: ${stack.addons.join(", ")}`);
+    }
+    return parts.join(", ");
+}
+function formatStackForContext(stack) {
+    if (!stack) {
+        return "";
+    }
+    const frontendStr = Array.isArray(stack.frontend)
+        ? stack.frontend.join(" + ")
+        : stack.frontend;
+    return `Technology Stack: ${frontendStr} + ${stack.backend} + ${stack.database}`;
+}

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

@@ -0,0 +1,49 @@
+import { Task } from "../types/index.js";
+/**
+ * Ensures a task is not null, throwing an error if it is.
+ * Useful for enforcing null checks after storage operations.
+ *
+ * @param task - Task that may be null
+ * @param taskId - ID of the task for error message
+ * @returns The task if not null
+ * @throws TaskOMaticError if task is null
+ *
+ * @example
+ * ```typescript
+ * const task = await storage.getTask(taskId);
+ * const validTask = requireTask(task, taskId);
+ * console.log(validTask.title); // Safe - never null
+ * ```
+ */
+export declare function requireTask(task: Task | null, taskId: string): Task;
+/**
+ * Ensures multiple tasks are not null, throwing an error if any is null.
+ *
+ * @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 TaskOMaticError if any task is null
+ */
+export declare function requireTasks(tasks: (Task | null)[], context?: string): Task[];
+/**
+ * Filters out null tasks from an array, with type narrowing.
+ *
+ * @param tasks - Array of tasks that may contain nulls
+ * @returns Array of tasks with nulls removed
+ *
+ * @example
+ * ```typescript
+ * const tasks = await Promise.all(ids.map(id => storage.getTask(id)));
+ * const validTasks = filterNullTasks(tasks);
+ * // validTasks has type Task[] (no null)
+ * ```
+ */
+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 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

@@ -0,0 +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;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

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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.
+ *
+ * @param task - Task that may be null
+ * @param taskId - ID of the task for error message
+ * @returns The task if not null
+ * @throws TaskOMaticError if task is null
+ *
+ * @example
+ * ```typescript
+ * const task = await storage.getTask(taskId);
+ * const validTask = requireTask(task, taskId);
+ * console.log(validTask.title); // Safe - never null
+ * ```
+ */
+function requireTask(task, taskId) {
+    if (!task) {
+        throw (0, task_o_matic_error_1.formatTaskNotFoundError)(taskId);
+    }
+    return task;
+}
+/**
+ * Ensures multiple tasks are not null, throwing an error if any is null.
+ *
+ * @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 TaskOMaticError if any task is null
+ */
+function requireTasks(tasks, context = "tasks") {
+    const validTasks = [];
+    const missingIds = [];
+    tasks.forEach((task, index) => {
+        if (!task) {
+            missingIds.push(`index ${index}`);
+        }
+        else {
+            validTasks.push(task);
+        }
+    });
+    if (missingIds.length > 0) {
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.STORAGE_INTEGRITY_ERROR, `Missing ${context}: ${missingIds.join(", ")}`);
+    }
+    return validTasks;
+}
+/**
+ * Filters out null tasks from an array, with type narrowing.
+ *
+ * @param tasks - Array of tasks that may contain nulls
+ * @returns Array of tasks with nulls removed
+ *
+ * @example
+ * ```typescript
+ * const tasks = await Promise.all(ids.map(id => storage.getTask(id)));
+ * const validTasks = filterNullTasks(tasks);
+ * // validTasks has type Task[] (no null)
+ * ```
+ */
+function filterNullTasks(tasks) {
+    return tasks.filter((task) => task !== null);
+}
+/**
+ * Validates that a task ID is a non-empty string.
+ *
+ * @param taskId - Task ID to validate
+ * @throws TaskOMaticError if task ID is invalid
+ */
+function validateTaskId(taskId) {
+    if (!taskId || typeof taskId !== "string" || !taskId.trim()) {
+        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/streaming-utils.d.ts

@@ -0,0 +1,38 @@
+import { StreamingOptions } from "../types/index.js";
+/**
+ * Token usage metrics from AI operations
+ */
+export interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+export interface MetricsTracker {
+    tokenUsage: TokenUsage;
+    timeToFirstToken: number | undefined;
+}
+export interface MetricsStreamingResult {
+    options: StreamingOptions;
+    getMetrics: () => MetricsTracker;
+}
+/**
+ * Creates streaming options with automatic metrics tracking.
+ * Wraps provided streaming callbacks to capture token usage and timing metrics.
+ *
+ * @param streamingOptions - Optional base streaming options to wrap
+ * @param aiStartTime - Optional timestamp when AI operation started (for measuring time to first token)
+ * @returns Object containing wrapped streaming options and metrics getter
+ *
+ * @example
+ * ```typescript
+ * const aiStartTime = Date.now();
+ * const { options, getMetrics } = createMetricsStreamingOptions(userCallbacks, aiStartTime);
+ *
+ * await generateText({ model, prompt, ...options });
+ *
+ * const { tokenUsage, timeToFirstToken } = getMetrics();
+ * console.log(`Used ${tokenUsage.total} tokens in ${timeToFirstToken}ms`);
+ * ```
+ */
+export declare function createMetricsStreamingOptions(streamingOptions?: StreamingOptions, aiStartTime?: number): MetricsStreamingResult;
+//# sourceMappingURL=streaming-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-utils.d.ts","sourceRoot":"","sources":["../../src/utils/streaming-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,UAAU,CAAC;IACvB,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,UAAU,EAAE,MAAM,cAAc,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,WAAW,CAAC,EAAE,MAAM,GACnB,sBAAsB,CA+CxB"}

package/dist/utils/streaming-utils.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMetricsStreamingOptions = createMetricsStreamingOptions;
+/**
+ * Creates streaming options with automatic metrics tracking.
+ * Wraps provided streaming callbacks to capture token usage and timing metrics.
+ *
+ * @param streamingOptions - Optional base streaming options to wrap
+ * @param aiStartTime - Optional timestamp when AI operation started (for measuring time to first token)
+ * @returns Object containing wrapped streaming options and metrics getter
+ *
+ * @example
+ * ```typescript
+ * const aiStartTime = Date.now();
+ * const { options, getMetrics } = createMetricsStreamingOptions(userCallbacks, aiStartTime);
+ *
+ * await generateText({ model, prompt, ...options });
+ *
+ * const { tokenUsage, timeToFirstToken } = getMetrics();
+ * console.log(`Used ${tokenUsage.total} tokens in ${timeToFirstToken}ms`);
+ * ```
+ */
+function createMetricsStreamingOptions(streamingOptions, aiStartTime) {
+    let tokenUsage = { prompt: 0, completion: 0, total: 0 };
+    let timeToFirstToken = undefined;
+    const wrappedOptions = {
+        onFinish: async (result) => {
+            // Extract token usage from result
+            if (result.usage) {
+                tokenUsage = {
+                    prompt: result.usage.inputTokens || result.usage.promptTokens || 0,
+                    completion: result.usage.outputTokens || result.usage.completionTokens || 0,
+                    total: result.usage.totalTokens || 0,
+                };
+            }
+            // Call original onFinish callback if provided
+            await streamingOptions?.onFinish?.(result);
+        },
+        onChunk: (chunk) => {
+            // Measure time to first token (ignore empty/whitespace chunks)
+            if (chunk && chunk.trim() && !timeToFirstToken && aiStartTime) {
+                timeToFirstToken = Date.now() - aiStartTime;
+            }
+            // Call original onChunk callback if provided
+            streamingOptions?.onChunk?.(chunk);
+        },
+        onError: (error) => {
+            // Pass through error callback
+            streamingOptions?.onError?.(error);
+        },
+        onReasoning: (text) => {
+            // Measure time to first token (reasoning counts as response start)
+            if (text && text.trim() && !timeToFirstToken && aiStartTime) {
+                timeToFirstToken = Date.now() - aiStartTime;
+            }
+            // Pass through reasoning callback
+            streamingOptions?.onReasoning?.(text);
+        },
+    };
+    return {
+        options: wrappedOptions,
+        getMetrics: () => ({ tokenUsage, timeToFirstToken }),
+    };
+}

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":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,KAAK,CAAC,EAAE,KAAK,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC;IAkBH;;OAEG;IACH,UAAU,IAAI,MAAM;IAsBpB;;OAEG;IACH,MAAM,IAAI;QACR,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;CAaF;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;CA8BvB,CAAC;AAEX,KAAK,mBAAmB,GACtB,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,GACL,eAAe,CAQjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,mBAAmB,EACzB,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,GACL,eAAe,CAWjB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;GAEG;AAEH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAavE;AAED,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,eAAe,CAajB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,KAAK,GACZ,eAAe,CAcjB;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,KAAK,GACZ,eAAe,CAejB;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,GACf,KAAK,CAUP"}