task-o-matic 0.0.13 → 0.0.15

package/dist/types/results.d.ts

@@ -1,16 +1,50 @@
 import { Task, TaskAIMetadata, DocumentationDetection } from "./index";
-export interface OperationResult<T = any> {
-    success: boolean;
-    data?: T;
-    error?: string;
+/**
+ * Generic operation result using discriminated union pattern.
+ * Prevents invalid states like { success: true, error: "..." }
+ *
+ * Note: This type uses discriminated unions for operations that may return
+ * either success or failure. Most task operations throw exceptions on error
+ * instead of returning error results.
+ *
+ * @example
+ * ```typescript
+ * const result: OperationResult<Task> =
+ *   condition
+ *     ? { success: true, data: task }
+ *     : { success: false, error: "Task not found" };
+ *
+ * if (result.success) {
+ *   console.log(result.data.title); // ✓ TypeScript knows data exists
+ * } else {
+ *   console.error(result.error); // ✓ TypeScript knows error exists
+ * }
+ * ```
+ */
+export type OperationResult<T = any> = {
+    success: true;
+    data: T;
     stats?: Record<string, any>;
     metadata?: Record<string, any>;
-}
+} | {
+    success: false;
+    error: string;
+    stats?: Record<string, any>;
+    metadata?: Record<string, any>;
+};
+/**
+ * Result of task creation operation.
+ * Always returns success; throws exception on error.
+ */
 export interface CreateTaskResult {
     success: true;
     task: Task;
     aiMetadata?: TaskAIMetadata;
 }
+/**
+ * Result of task enhancement operation.
+ * Always returns success; throws exception on error.
+ */
 export interface EnhanceTaskResult {
     success: true;
     task: Task;
@@ -33,6 +67,10 @@ export interface EnhanceTaskResult {
         confidence: number;
     };
 }
+/**
+ * Result of task splitting operation.
+ * Always returns success; throws exception on error.
+ */
 export interface SplitTaskResult {
     success: true;
     task: Task;
@@ -54,6 +92,10 @@ export interface SplitTaskResult {
         confidence?: number;
     };
 }
+/**
+ * Result of task planning operation.
+ * Always returns success; throws exception on error.
+ */
 export interface PlanTaskResult {
     success: true;
     task: Task;
@@ -73,6 +115,10 @@ export interface PlanTaskResult {
         aiModel: string;
     };
 }
+/**
+ * Result of task documentation operation.
+ * Always returns success; throws exception on error.
+ */
 export interface DocumentTaskResult {
     success: true;
     task: Task;
@@ -82,13 +128,21 @@ export interface DocumentTaskResult {
         duration: number;
     };
 }
+/**
+ * Result of task deletion operation.
+ * Always returns success; throws exception on error.
+ */
 export interface DeleteTaskResult {
     success: true;
     deleted: Task[];
     orphanedSubtasks: Task[];
 }
+/**
+ * Result of PRD parsing operation.
+ * Always returns success; throws exception on error.
+ */
 export interface PRDParseResult {
-    success: boolean;
+    success: true;
     prd: {
         overview: string;
         objectives: string[];

package/dist/types/results.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../src/types/results.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../src/types/results.ts"],"names":[],"mappings":"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"}

package/dist/utils/ai-operation-utility.d.ts

@@ -0,0 +1,142 @@
+import type { ToolSet } from "ai";
+import { AIConfig, StreamingOptions, RetryConfig } from "../types";
+import { BaseOperations } from "../lib/ai-service/base-operations";
+export interface AIOperationResult<T> {
+    result: T;
+    metrics: {
+        duration: number;
+        tokenUsage?: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+        timeToFirstToken?: number;
+    };
+}
+export interface AIOperationOptions {
+    streamingOptions?: StreamingOptions;
+    retryConfig?: Partial<RetryConfig>;
+    aiConfig?: Partial<AIConfig>;
+    enableFilesystemTools?: boolean;
+    context?: Record<string, unknown>;
+    maxRetries?: number;
+}
+/**
+ * AIOperationUtility - Centralized utility for AI operations with metrics and error handling
+ *
+ * Extends BaseOperations to inherit core AI functionality (streamText, model provider, etc.)
+ * and adds standardized metrics collection, error handling, and retry logic.
+ *
+ * @example
+ * ```typescript
+ * const utility = new AIOperationUtility();
+ *
+ * // Execute operation with metrics
+ * const result = await utility.executeAIOperation(
+ *   "Task breakdown",
+ *   async () => performBreakdown(task),
+ *   {
+ *     maxRetries: 3,
+ *     streamingOptions: { onChunk: console.log }
+ *   }
+ * );
+ *
+ * console.log(result.metrics.duration);
+ * console.log(result.metrics.timeToFirstToken);
+ * ```
+ */
+export declare class AIOperationUtility extends BaseOperations {
+    /**
+     * Execute an AI operation with standardized metrics, error handling, and streaming support
+     *
+     * This method wraps AI operations to provide:
+     * - Automatic retry logic with configurable attempts
+     * - Metrics collection (duration, token usage, time to first token)
+     * - Error handling with TaskOMaticError wrapping
+     * - Streaming support with metrics capture
+     *
+     * @param operationName - Human-readable name for the operation (used in errors)
+     * @param operation - The async operation to execute
+     * @param options - Configuration options for retry, streaming, and AI config
+     * @returns Promise resolving to AIOperationResult with result and metrics
+     * @throws {TaskOMaticError} If operation fails after all retry attempts
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await utility.executeAIOperation(
+     *     "Task enhancement",
+     *     async () => enhanceTask(task),
+     *     { maxRetries: 2 }
+     *   );
+     *   console.log(`Operation took ${result.metrics.duration}ms`);
+     * } catch (error) {
+     *   if (error instanceof TaskOMaticError) {
+     *     console.error(error.getDetails());
+     *   }
+     * }
+     * ```
+     */
+    executeAIOperation<T>(operationName: string, operation: () => Promise<T>, options?: AIOperationOptions): Promise<AIOperationResult<T>>;
+    /**
+     * Standardized streaming text operation with tool support
+     *
+     * This method provides a unified interface for AI text generation with:
+     * - Optional tool integration (filesystem, MCP, etc.)
+     * - Streaming support with callbacks
+     * - Context7 documentation caching
+     * - Metrics collection
+     * - Error handling
+     *
+     * @param systemPrompt - System prompt for the AI
+     * @param userMessage - User message/prompt
+     * @param config - Optional AI configuration overrides
+     * @param streamingOptions - Optional streaming callbacks
+     * @param tools - Optional tool set to provide to the AI
+     * @returns Promise resolving to the generated text
+     *
+     * @example
+     * ```typescript
+     * const result = await utility.streamTextWithTools(
+     *   "You are a helpful assistant",
+     *   "Explain quantum computing",
+     *   undefined,
+     *   { onChunk: (chunk) => console.log(chunk) },
+     *   filesystemTools
+     * );
+     * ```
+     */
+    streamTextWithTools(systemPrompt: string, userMessage: string, config?: Partial<AIConfig>, streamingOptions?: StreamingOptions, tools?: ToolSet): Promise<string>;
+    /**
+     * Wrap streaming options to capture metrics
+     *
+     * @private
+     */
+    private wrapStreamingOptions;
+    /**
+     * Create streaming configuration with Context7 handling and callbacks
+     *
+     * This method creates a unified streaming configuration that:
+     * - Always handles Context7 tool-result events (even without streaming UI)
+     * - Forwards text-delta events to onChunk callback
+     * - Forwards reasoning-delta events to onReasoning callback
+     * - Handles errors with onError callback
+     * - Provides onFinish callback with completion data
+     *
+     * @private
+     */
+    private createStreamingConfig;
+    /**
+     * Extract token usage from AI result
+     *
+     * @private
+     */
+    private extractTokenUsageFromResult;
+    /**
+     * Get error message from any error type
+     *
+     * @private
+     */
+    private getErrorMessage;
+}
+//# sourceMappingURL=ai-operation-utility.d.ts.map

package/dist/utils/ai-operation-utility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-operation-utility.d.ts","sourceRoot":"","sources":["../../src/utils/ai-operation-utility.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAGnE,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC;IACV,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE;YACX,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;YACnB,KAAK,EAAE,MAAM,CAAC;SACf,CAAC;QACF,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,kBAAmB,SAAQ,cAAc;IACpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,kBAAkB,CAAC,CAAC,EACxB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAmEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,mBAAmB,CACvB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC1B,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,KAAK,CAAC,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,CAAC;IAgClB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAsD7B;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;IAiBnC;;;;OAIG;IACH,OAAO,CAAC,eAAe;CASxB"}

package/dist/utils/ai-operation-utility.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIOperationUtility = void 0;
+const ai_1 = require("ai");
+const base_operations_1 = require("../lib/ai-service/base-operations");
+const task_o_matic_error_1 = require("./task-o-matic-error");
+/**
+ * AIOperationUtility - Centralized utility for AI operations with metrics and error handling
+ *
+ * Extends BaseOperations to inherit core AI functionality (streamText, model provider, etc.)
+ * and adds standardized metrics collection, error handling, and retry logic.
+ *
+ * @example
+ * ```typescript
+ * const utility = new AIOperationUtility();
+ *
+ * // Execute operation with metrics
+ * const result = await utility.executeAIOperation(
+ *   "Task breakdown",
+ *   async () => performBreakdown(task),
+ *   {
+ *     maxRetries: 3,
+ *     streamingOptions: { onChunk: console.log }
+ *   }
+ * );
+ *
+ * console.log(result.metrics.duration);
+ * console.log(result.metrics.timeToFirstToken);
+ * ```
+ */
+class AIOperationUtility extends base_operations_1.BaseOperations {
+    /**
+     * Execute an AI operation with standardized metrics, error handling, and streaming support
+     *
+     * This method wraps AI operations to provide:
+     * - Automatic retry logic with configurable attempts
+     * - Metrics collection (duration, token usage, time to first token)
+     * - Error handling with TaskOMaticError wrapping
+     * - Streaming support with metrics capture
+     *
+     * @param operationName - Human-readable name for the operation (used in errors)
+     * @param operation - The async operation to execute
+     * @param options - Configuration options for retry, streaming, and AI config
+     * @returns Promise resolving to AIOperationResult with result and metrics
+     * @throws {TaskOMaticError} If operation fails after all retry attempts
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await utility.executeAIOperation(
+     *     "Task enhancement",
+     *     async () => enhanceTask(task),
+     *     { maxRetries: 2 }
+     *   );
+     *   console.log(`Operation took ${result.metrics.duration}ms`);
+     * } catch (error) {
+     *   if (error instanceof TaskOMaticError) {
+     *     console.error(error.getDetails());
+     *   }
+     * }
+     * ```
+     */
+    async executeAIOperation(operationName, operation, options = {}) {
+        const startTime = Date.now();
+        let timeToFirstToken;
+        // Create wrapped streaming options to capture metrics
+        const wrappedStreamingOptions = this.wrapStreamingOptions(options.streamingOptions, startTime, (time) => {
+            timeToFirstToken = time;
+        });
+        try {
+            // Execute with retry logic
+            const result = await this.retryHandler.executeWithRetry(async () => {
+                // Execute operation - note: operations should use the streaming options
+                // passed through the closure, not directly from options
+                return await operation();
+            }, {
+                maxAttempts: options.maxRetries || options.retryConfig?.maxAttempts || 2,
+                ...options.retryConfig,
+            }, operationName);
+            const duration = Date.now() - startTime;
+            return {
+                result,
+                metrics: {
+                    duration,
+                    timeToFirstToken,
+                    tokenUsage: this.extractTokenUsageFromResult(result),
+                },
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const typedError = error instanceof Error ? error : new Error(String(error));
+            // THROW error instead of returning it
+            throw new task_o_matic_error_1.TaskOMaticError(`AI operation failed: ${operationName}`, {
+                code: "AI_OPERATION_FAILED",
+                context: JSON.stringify({
+                    operation: operationName,
+                    duration,
+                    error: this.getErrorMessage(typedError),
+                }),
+                cause: typedError,
+                suggestions: [
+                    "Check AI configuration",
+                    "Verify network connectivity",
+                    "Review operation parameters",
+                    "Check API keys and endpoints",
+                ],
+                metadata: {
+                    operationName,
+                    duration,
+                    attemptedRetries: options.maxRetries || 2,
+                },
+            });
+        }
+    }
+    /**
+     * Standardized streaming text operation with tool support
+     *
+     * This method provides a unified interface for AI text generation with:
+     * - Optional tool integration (filesystem, MCP, etc.)
+     * - Streaming support with callbacks
+     * - Context7 documentation caching
+     * - Metrics collection
+     * - Error handling
+     *
+     * @param systemPrompt - System prompt for the AI
+     * @param userMessage - User message/prompt
+     * @param config - Optional AI configuration overrides
+     * @param streamingOptions - Optional streaming callbacks
+     * @param tools - Optional tool set to provide to the AI
+     * @returns Promise resolving to the generated text
+     *
+     * @example
+     * ```typescript
+     * const result = await utility.streamTextWithTools(
+     *   "You are a helpful assistant",
+     *   "Explain quantum computing",
+     *   undefined,
+     *   { onChunk: (chunk) => console.log(chunk) },
+     *   filesystemTools
+     * );
+     * ```
+     */
+    async streamTextWithTools(systemPrompt, userMessage, config, streamingOptions, tools) {
+        const aiConfig = this.mergeAIConfig(config);
+        const model = this.modelProvider.getModel(aiConfig);
+        // Create streaming configuration with Context7 handling and callbacks
+        const streamConfig = this.createStreamingConfig(streamingOptions);
+        const result = await (0, ai_1.streamText)({
+            model,
+            tools: tools || {},
+            system: systemPrompt,
+            messages: [{ role: "user", content: userMessage }],
+            maxRetries: 0,
+            ...streamConfig,
+            ...(aiConfig.provider === "openrouter" &&
+                aiConfig.reasoning &&
+                aiConfig.reasoning.maxTokens
+                ? {
+                    providerOptions: {
+                        openrouter: {
+                            reasoning: {
+                                max_tokens: aiConfig.reasoning.maxTokens,
+                            },
+                        },
+                    },
+                }
+                : {}),
+        });
+        return await result.text;
+    }
+    /**
+     * Wrap streaming options to capture metrics
+     *
+     * @private
+     */
+    wrapStreamingOptions(streamingOptions, startTime, onFirstToken) {
+        if (!streamingOptions) {
+            return undefined;
+        }
+        let firstTokenCaptured = false;
+        return {
+            ...streamingOptions,
+            onChunk: (chunk) => {
+                if (!firstTokenCaptured && chunk.trim()) {
+                    onFirstToken(Date.now() - startTime);
+                    firstTokenCaptured = true;
+                }
+                streamingOptions.onChunk?.(chunk);
+            },
+            onFinish: (result) => {
+                streamingOptions.onFinish?.(result);
+            },
+            onReasoning: (reasoning) => {
+                streamingOptions.onReasoning?.(reasoning);
+            },
+            onError: (error) => {
+                streamingOptions.onError?.(error);
+            },
+        };
+    }
+    /**
+     * Create streaming configuration with Context7 handling and callbacks
+     *
+     * This method creates a unified streaming configuration that:
+     * - Always handles Context7 tool-result events (even without streaming UI)
+     * - Forwards text-delta events to onChunk callback
+     * - Forwards reasoning-delta events to onReasoning callback
+     * - Handles errors with onError callback
+     * - Provides onFinish callback with completion data
+     *
+     * @private
+     */
+    createStreamingConfig(streamingOptions) {
+        return {
+            onChunk: streamingOptions?.onChunk || streamingOptions?.onReasoning
+                ? (event) => {
+                    // Handle Context7 tool results ALWAYS (critical for caching)
+                    if (event.chunk?.type === "tool-result" &&
+                        event.chunk?.toolName === "get-library-docs") {
+                        const docs = event.chunk.output;
+                        if (docs && typeof docs === "object" && "content" in docs) {
+                            this.context7Client.saveContext7Documentation(event.chunk.input?.context7CompatibleLibraryID || "unknown", docs.content, event.chunk.input?.topic || "general");
+                        }
+                        else if (docs && typeof docs === "string") {
+                            this.context7Client.saveContext7Documentation(event.chunk.input?.context7CompatibleLibraryID || "unknown", docs, event.chunk.input?.topic || "general");
+                        }
+                    }
+                    // Forward text deltas to user callback
+                    if (event.chunk?.type === "text-delta") {
+                        streamingOptions?.onChunk?.(event.chunk.text);
+                    }
+                    // Forward reasoning deltas to user callback
+                    if (event.chunk?.type === "reasoning-delta") {
+                        streamingOptions?.onReasoning?.(event.chunk.text);
+                    }
+                }
+                : undefined,
+            onFinish: streamingOptions?.onFinish
+                ? (event) => {
+                    streamingOptions.onFinish({
+                        text: event.text,
+                        finishReason: event.finishReason,
+                        usage: event.usage,
+                        isAborted: false,
+                    });
+                }
+                : undefined,
+            onError: streamingOptions?.onError
+                ? (event) => {
+                    streamingOptions.onError(event.error);
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Extract token usage from AI result
+     *
+     * @private
+     */
+    extractTokenUsageFromResult(result) {
+        if (result && result.usage) {
+            return {
+                prompt: result.usage.prompt_tokens || 0,
+                completion: result.usage.completion_tokens || 0,
+                total: result.usage.total_tokens || 0,
+            };
+        }
+        return undefined;
+    }
+    /**
+     * Get error message from any error type
+     *
+     * @private
+     */
+    getErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        else if (typeof error === "string") {
+            return error;
+        }
+        else {
+            return "Unknown error";
+        }
+    }
+}
+exports.AIOperationUtility = AIOperationUtility;

package/dist/utils/ai-service-factory.d.ts

@@ -21,4 +21,14 @@ export declare function getModelProvider(): ModelProvider;
 export declare function getStorage(): TaskRepository;
 export declare function getContextBuilder(): ContextBuilder;
 export declare function resetServiceInstances(): void;
+/**
+ * FOR TESTING ONLY: Inject mock instances
+ * This allows tests to provide mock implementations without complex module mocking
+ */
+export declare function injectTestInstances(instances: {
+    storage?: TaskRepository;
+    aiOperations?: AIOperations;
+    modelProvider?: ModelProvider;
+    contextBuilder?: ContextBuilder;
+}): void;
 //# sourceMappingURL=ai-service-factory.d.ts.map

package/dist/utils/ai-service-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-service-factory.d.ts","sourceRoot":"","sources":["../../src/utils/ai-service-factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,EAAiB,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAOD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAgB,eAAe,IAAI,YAAY,CAK9C;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAED,wBAAgB,UAAU,IAAI,cAAc,CAkB3C;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAMlD;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C"}
+{"version":3,"file":"ai-service-factory.d.ts","sourceRoot":"","sources":["../../src/utils/ai-service-factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,EAAiB,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAMpE,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAOD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAgB,eAAe,IAAI,YAAY,CAK9C;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAED,wBAAgB,UAAU,IAAI,cAAc,CAsB3C;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAMlD;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE;IAC7C,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC,GAAG,IAAI,CAKP"}

package/dist/utils/ai-service-factory.js

@@ -6,12 +6,14 @@ exports.getModelProvider = getModelProvider;
 exports.getStorage = getStorage;
 exports.getContextBuilder = getContextBuilder;
 exports.resetServiceInstances = resetServiceInstances;
+exports.injectTestInstances = injectTestInstances;
 const file_system_1 = require("../lib/storage/file-system");
 const context_builder_1 = require("../lib/context-builder");
 const fs_1 = require("fs");
 const config_1 = require("../lib/config");
 const ai_operations_1 = require("../lib/ai-service/ai-operations");
 const model_provider_1 = require("../lib/ai-service/model-provider");
+const task_o_matic_error_1 = require("./task-o-matic-error");
 let aiOperations = null;
 let modelProvider = null;
 let storage = null;
@@ -60,7 +62,9 @@ function getStorage() {
         const taskOMaticDir = config_1.configManager.getTaskOMaticDir();
         // Note: This check relies on FS. Web apps should call initializeServices first.
         if (!(0, fs_1.existsSync)(taskOMaticDir)) {
-            throw new Error(`Not a task-o-matic project. Run 'task-o-matic init' first.`);
+            throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.CONFIGURATION_ERROR, "Not a task-o-matic project. Run 'task-o-matic init' first.", {
+                suggestions: ["Run `task-o-matic init` in your project root."],
+            });
         }
         storage = new file_system_1.FileSystemStorage();
     }
@@ -79,3 +83,17 @@ function resetServiceInstances() {
     storage = null;
     contextBuilder = null;
 }
+/**
+ * FOR TESTING ONLY: Inject mock instances
+ * This allows tests to provide mock implementations without complex module mocking
+ */
+function injectTestInstances(instances) {
+    if (instances.storage)
+        storage = instances.storage;
+    if (instances.aiOperations)
+        aiOperations = instances.aiOperations;
+    if (instances.modelProvider)
+        modelProvider = instances.modelProvider;
+    if (instances.contextBuilder)
+        contextBuilder = instances.contextBuilder;
+}

package/dist/utils/cli-validators.d.ts

@@ -6,7 +6,7 @@
  * @param field2 - Second field name in options
  * @param field1Label - Display label for first field (defaults to field1)
  * @param field2Label - Display label for second field (defaults to field2)
- * @throws Error if neither or both fields are provided
+ * @throws TaskOMaticError if neither or both fields are provided
  *
  * @example
  * ```typescript
@@ -26,7 +26,7 @@ export interface FieldSpec {
  *
  * @param options - The command options object
  * @param fields - Array of field specifications
- * @throws Error if none or multiple fields are provided
+ * @throws TaskOMaticError if none or multiple fields are provided
  *
  * @example
  * ```typescript

package/dist/utils/cli-validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-validators.d.ts","sourceRoot":"","sources":["../../src/utils/cli-validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,MAAe,EAC5B,WAAW,GAAE,MAAe,GAC3B,IAAI,CAcN;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,GAAG,EACZ,GAAG,MAAM,EAAE,SAAS,EAAE,GACrB,IAAI,CAWN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKtD"}
+{"version":3,"file":"cli-validators.d.ts","sourceRoot":"","sources":["../../src/utils/cli-validators.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,MAAe,EAC5B,WAAW,GAAE,MAAe,GAC3B,IAAI,CAgBN;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,GAAG,EACZ,GAAG,MAAM,EAAE,SAAS,EAAE,GACrB,IAAI,CAiBN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKtD"}