task-o-matic-core 0.1.0

package/src/test/utils/ai-operation-utility.test.ts

@@ -0,0 +1,306 @@
+import * as assert from "assert";
+import { AIOperationUtility } from "../../utils/ai-operation-utility";
+import { TaskOMaticError } from "../../utils/task-o-matic-error";
+import { RetryHandler } from "../../lib/ai-service/retry-handler";
+import { ModelProvider } from "../../lib/ai-service/model-provider";
+import { Context7Client } from "../../lib/ai-service/mcp-client";
+
+/**
+ * ⚠️ CRITICAL: These tests use 100% MOCKS - ZERO real AI calls
+ * No API calls are made, no costs incurred, tests run fast
+ */
+describe("AIOperationUtility", () => {
+  let utility: AIOperationUtility;
+  let mockRetryHandler: any;
+  let mockModelProvider: any;
+  let mockContext7Client: any;
+
+  beforeEach(() => {
+    // Create utility instance
+    utility = new AIOperationUtility();
+
+    // Create mock retry handler - NO REAL RETRIES
+    mockRetryHandler = {
+      executeWithRetry: async (operation: () => Promise<any>) => {
+        // Execute immediately without real retry logic
+        return await operation();
+      },
+    };
+
+    // Create mock model provider - NO REAL AI MODELS
+    mockModelProvider = {
+      getModel: () => ({
+        // Mock AI SDK v2 compliant model
+        specificationVersion: "v2",
+        provider: "mock",
+        modelId: "mock-model",
+        doGenerate: async () => ({
+          text: "Mock response",
+          finishReason: "stop",
+          usage: {
+            promptTokens: 10,
+            completionTokens: 5,
+            totalTokens: 15,
+          },
+        }),
+        doStream: async () => ({
+          stream: (async function* () {
+            yield { type: "text-delta", textDelta: "Mock" };
+            yield { type: "text-delta", textDelta: " response" };
+          })(),
+        }),
+      }),
+      getAIConfig: () => ({
+        provider: "mock",
+        model: "mock-model",
+        apiKey: "mock-key",
+      }),
+    };
+
+    // Create mock Context7 client - NO REAL DOCUMENTATION FETCHES
+    mockContext7Client = {
+      saveContext7Documentation: () => {
+        // Mock save - no real file writes
+      },
+      getMCPTools: async () => ({}),
+    };
+
+    // Inject mocks into utility
+    (utility as any).retryHandler = mockRetryHandler;
+    (utility as any).modelProvider = mockModelProvider;
+    (utility as any).context7Client = mockContext7Client;
+  });
+
+  describe("executeAIOperation", () => {
+    it("should execute operation successfully and return result with metrics", async () => {
+      // Mock operation that returns a simple result
+      const mockResult = { data: "test result" };
+      const operation = async () => mockResult;
+
+      const result = await utility.executeAIOperation(
+        "test operation",
+        operation
+      );
+
+      assert.deepStrictEqual(result.result, mockResult);
+      assert.ok("duration" in result.metrics);
+      assert.strictEqual(typeof result.metrics.duration, "number");
+      assert.ok(result.metrics.duration >= 0);
+    });
+
+    it("should throw TaskOMaticError when operation fails", async () => {
+      // Mock operation that throws an error
+      const operation = async () => {
+        throw new Error("Mock AI failure");
+      };
+
+      try {
+        await utility.executeAIOperation("test operation", operation);
+        assert.fail("Should have thrown TaskOMaticError");
+      } catch (error) {
+        assert.ok(error instanceof TaskOMaticError);
+        assert.strictEqual((error as TaskOMaticError).code, "AI_OPERATION_FAILED");
+        assert.ok((error as TaskOMaticError).message.includes("test operation"));
+        assert.ok(Array.isArray((error as TaskOMaticError).suggestions));
+      }
+    });
+
+    it("should preserve error details in TaskOMaticError", async () => {
+      const originalError = new Error("Original error message");
+      const operation = async () => {
+        throw originalError;
+      };
+
+      try {
+        await utility.executeAIOperation("test operation", operation);
+        assert.fail("Should have thrown");
+      } catch (error) {
+        assert.ok(error instanceof TaskOMaticError);
+        const taskError = error as TaskOMaticError;
+        assert.strictEqual(taskError.cause, originalError);
+        assert.ok(taskError.context?.includes("test operation"));
+        assert.ok("operationName" in (taskError.metadata || {}));
+      }
+    });
+
+    it("should capture duration metrics correctly", async () => {
+      const operation = async () => {
+        // Simulate some work
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return { data: "result" };
+      };
+
+      const result = await utility.executeAIOperation(
+        "slow operation",
+        operation
+      );
+
+      assert.ok(result.metrics.duration >= 50);
+    });
+
+    it("should respect maxRetries option", async () => {
+      let attemptCount = 0;
+
+      // Mock retry handler that counts attempts
+      (utility as any).retryHandler = {
+        executeWithRetry: async (
+          operation: () => Promise<any>,
+          config: any
+        ) => {
+          attemptCount++;
+          assert.strictEqual(config.maxAttempts, 5);
+          return await operation();
+        },
+      };
+
+      const operation = async () => ({ data: "result" });
+
+      await utility.executeAIOperation("test", operation, { maxRetries: 5 });
+      assert.strictEqual(attemptCount, 1);
+    });
+
+    it("should extract token usage from result if available", async () => {
+      const mockResult = {
+        data: "test",
+        usage: {
+          prompt_tokens: 100,
+          completion_tokens: 50,
+          total_tokens: 150,
+        },
+      };
+
+      const operation = async () => mockResult;
+
+      const result = await utility.executeAIOperation("test", operation);
+
+      assert.deepStrictEqual(result.metrics.tokenUsage, {
+        prompt: 100,
+        completion: 50,
+        total: 150,
+      });
+    });
+
+    it("should return undefined tokenUsage if not available in result", async () => {
+      const mockResult = { data: "test" };
+      const operation = async () => mockResult;
+
+      const result = await utility.executeAIOperation("test", operation);
+
+      assert.strictEqual(result.metrics.tokenUsage, undefined);
+    });
+  });
+
+  describe("streamTextWithTools", () => {
+    it("should verify method signature exists - NO REAL AI CALL", async () => {
+      // This test verifies the method exists and has the correct signature
+      // We don't actually call it to avoid real AI calls
+      assert.strictEqual(typeof utility.streamTextWithTools, "function");
+
+      // Verify the method is accessible
+      assert.ok("streamTextWithTools" in utility);
+    });
+
+    it("should pass tools to streamText when provided - NO REAL AI CALL", async () => {
+      // This test would verify tool passing in a real scenario
+      // For now, we just verify the method accepts tools parameter
+      const mockTools = {
+        readFile: {
+          description: "Read a file",
+          parameters: {},
+          execute: async () => ({}),
+        },
+      };
+
+      // The method should not throw
+      try {
+        // We can't fully test without real AI, but we verify the signature
+        assert.strictEqual(typeof utility.streamTextWithTools, "function");
+      } catch (error) {
+        assert.fail("Should not throw with valid parameters");
+      }
+    });
+  });
+
+  describe("Error Handling", () => {
+    it("should wrap string errors in Error objects", async () => {
+      const operation = async () => {
+        throw "String error";
+      };
+
+      try {
+        await utility.executeAIOperation("test", operation);
+        assert.fail("Should have thrown");
+      } catch (error) {
+        assert.ok(error instanceof TaskOMaticError);
+        assert.ok((error as TaskOMaticError).cause instanceof Error);
+      }
+    });
+
+    it("should include suggestions in thrown errors", async () => {
+      const operation = async () => {
+        throw new Error("Network timeout");
+      };
+
+      try {
+        await utility.executeAIOperation("test", operation);
+        assert.fail("Should have thrown");
+      } catch (error) {
+        const taskError = error as TaskOMaticError;
+        assert.ok(Array.isArray(taskError.suggestions));
+        assert.ok(taskError.suggestions!.length > 0);
+        assert.ok(taskError.suggestions?.includes("Check AI configuration"));
+      }
+    });
+  });
+
+  describe("Metrics Collection", () => {
+    it("should always include duration in metrics", async () => {
+      const operation = async () => ({ data: "result" });
+
+      const result = await utility.executeAIOperation("test", operation);
+
+      assert.ok("duration" in result.metrics);
+      assert.strictEqual(typeof result.metrics.duration, "number");
+      assert.ok(result.metrics.duration >= 0);
+    });
+
+    it("should capture metrics even on error", async () => {
+      const operation = async () => {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        throw new Error("Failure");
+      };
+
+      try {
+        await utility.executeAIOperation("test", operation);
+        assert.fail("Should have thrown");
+      } catch (error) {
+        const taskError = error as TaskOMaticError;
+        assert.ok("duration" in (taskError.metadata || {}));
+        assert.ok((taskError.metadata?.duration as number) >= 10);
+      }
+    });
+  });
+
+  describe("Streaming Options", () => {
+    it("should wrap streaming options without modifying original", async () => {
+      let chunkCount = 0;
+      const originalOnChunk = (chunk: string) => {
+        chunkCount++;
+      };
+
+      const streamingOptions = {
+        onChunk: originalOnChunk,
+      };
+
+      // The wrapping happens internally, we just verify it doesn't throw
+      const operation = async () => ({ data: "result" });
+
+      await utility.executeAIOperation("test", operation, {
+        streamingOptions,
+      });
+
+      // Original callback should not be modified
+      assert.strictEqual(streamingOptions.onChunk, originalOnChunk);
+    });
+  });
+});

package/src/test/utils/error-handling.test.ts

@@ -0,0 +1,241 @@
+import * as assert from "assert";
+import {
+  TaskOMaticError,
+  TaskOMaticErrorCodes,
+  createStandardError,
+  formatStandardError,
+  isTaskOMaticError,
+  formatTaskNotFoundError,
+  formatInvalidStatusTransitionError,
+  formatStorageError,
+  formatAIOperationError,
+  wrapErrorForBackwardCompatibility,
+} from "../../utils/task-o-matic-error";
+
+describe("TaskOMaticError", () => {
+  describe("TaskOMaticError class", () => {
+    it("should create a TaskOMaticError with all properties", () => {
+      const error = new TaskOMaticError("Test error", {
+        code: TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+        context: "Test context",
+        suggestions: ["Suggestion 1", "Suggestion 2"],
+        metadata: { key: "value" },
+      });
+
+      assert.strictEqual(error.name, "TaskOMaticError");
+      assert.strictEqual(error.message, "Test error");
+      assert.strictEqual(error.code, TaskOMaticErrorCodes.UNEXPECTED_ERROR);
+      assert.strictEqual(error.context, "Test context");
+      assert.deepStrictEqual(error.suggestions, [
+        "Suggestion 1",
+        "Suggestion 2",
+      ]);
+      assert.deepStrictEqual(error.metadata, { key: "value" });
+      assert.ok(error.timestamp);
+      assert.ok(error.stack);
+    });
+
+    it("should create a TaskOMaticError with minimal properties", () => {
+      const error = new TaskOMaticError("Minimal error", {
+        code: TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+      });
+
+      assert.strictEqual(error.name, "TaskOMaticError");
+      assert.strictEqual(error.message, "Minimal error");
+      assert.strictEqual(error.code, TaskOMaticErrorCodes.UNEXPECTED_ERROR);
+      assert.ok(error.timestamp);
+    });
+
+    it("should include cause error", () => {
+      const cause = new Error("Original error");
+      const error = new TaskOMaticError("Wrapped error", {
+        code: TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+        cause,
+      });
+
+      assert.strictEqual(error.cause, cause);
+    });
+  });
+
+  describe("getDetails()", () => {
+    it("should return formatted error details", () => {
+      const error = new TaskOMaticError("Test error", {
+        code: TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+        context: "Test context",
+        suggestions: ["Suggestion 1"],
+        metadata: { key: "value" },
+      });
+
+      const details = error.getDetails();
+      assert.ok(details.includes("[TASK_O_MATIC_001]"));
+      assert.ok(details.includes("Test error"));
+      assert.ok(details.includes("Context: Test context"));
+      assert.ok(details.includes("Suggestions:"));
+      assert.ok(details.includes("Suggestion 1"));
+      assert.ok(details.includes("Metadata:"));
+    });
+  });
+
+  describe("toJSON()", () => {
+    it("should return structured error data", () => {
+      const error = new TaskOMaticError("Test error", {
+        code: TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+        context: "Test context",
+        suggestions: ["Suggestion 1"],
+        metadata: { key: "value" },
+      });
+
+      const json = error.toJSON();
+      assert.strictEqual(json.name, "TaskOMaticError");
+      assert.strictEqual(json.code, TaskOMaticErrorCodes.UNEXPECTED_ERROR);
+      assert.strictEqual(json.message, "Test error");
+      assert.strictEqual(json.context, "Test context");
+      assert.deepStrictEqual(json.suggestions, ["Suggestion 1"]);
+      assert.deepStrictEqual(json.metadata, { key: "value" });
+      assert.ok(json.timestamp);
+      assert.ok(json.stack);
+    });
+  });
+
+  describe("createStandardError()", () => {
+    it("should create a standardized error", () => {
+      const error = createStandardError(
+        TaskOMaticErrorCodes.TASK_NOT_FOUND,
+        "Task not found",
+        {
+          context: "Task search failed",
+          suggestions: ["Check task ID", "List all tasks"],
+        }
+      );
+
+      assert.ok(isTaskOMaticError(error));
+      assert.strictEqual(error.code, TaskOMaticErrorCodes.TASK_NOT_FOUND);
+      assert.strictEqual(error.message, "Task not found");
+      assert.strictEqual(error.context, "Task search failed");
+      assert.deepStrictEqual(error.suggestions, [
+        "Check task ID",
+        "List all tasks",
+      ]);
+    });
+  });
+
+  describe("formatStandardError()", () => {
+    it("should format an error with context and suggestions", () => {
+      const originalError = new Error("Original error");
+      const error = formatStandardError(
+        originalError,
+        TaskOMaticErrorCodes.STORAGE_ERROR,
+        {
+          context: "Storage operation failed",
+          suggestions: ["Check permissions", "Retry operation"],
+        }
+      );
+
+      assert.ok(isTaskOMaticError(error));
+      assert.strictEqual(error.code, TaskOMaticErrorCodes.STORAGE_ERROR);
+      assert.strictEqual(error.message, "Original error");
+      assert.strictEqual(error.context, "Storage operation failed");
+      assert.deepStrictEqual(error.suggestions, [
+        "Check permissions",
+        "Retry operation",
+      ]);
+      assert.strictEqual(error.cause, originalError);
+    });
+  });
+
+  describe("isTaskOMaticError()", () => {
+    it("should return true for TaskOMaticError instances", () => {
+      const error = new TaskOMaticError("Test", {
+        code: TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+      });
+      assert.strictEqual(isTaskOMaticError(error), true);
+    });
+
+    it("should return false for regular Errors", () => {
+      const error = new Error("Regular error");
+      assert.strictEqual(isTaskOMaticError(error), false);
+    });
+
+    it("should return false for other values", () => {
+      assert.strictEqual(isTaskOMaticError("string error"), false);
+      assert.strictEqual(isTaskOMaticError(null), false);
+      assert.strictEqual(isTaskOMaticError(undefined), false);
+    });
+  });
+
+  describe("Standard error formatters", () => {
+    it("should format task not found error", () => {
+      const error = formatTaskNotFoundError("task-123");
+      assert.ok(isTaskOMaticError(error));
+      assert.strictEqual(error.code, TaskOMaticErrorCodes.TASK_NOT_FOUND);
+      assert.ok(error.message.includes("task-123"));
+      assert.ok(error.context);
+      assert.ok(error.suggestions);
+    });
+
+    it("should format invalid status transition error", () => {
+      const error = formatInvalidStatusTransitionError("todo", "invalid");
+      assert.ok(isTaskOMaticError(error));
+      assert.strictEqual(error.code, TaskOMaticErrorCodes.INVALID_TASK_STATUS);
+      assert.ok(error.message.includes("todo"));
+      assert.ok(error.message.includes("invalid"));
+      assert.ok(error.context);
+      assert.ok(error.suggestions);
+    });
+
+    it("should format storage error", () => {
+      const cause = new Error("Storage failed");
+      const error = formatStorageError("save", cause);
+      assert.ok(isTaskOMaticError(error));
+      assert.strictEqual(error.code, TaskOMaticErrorCodes.STORAGE_ERROR);
+      assert.ok(error.message.includes("save"));
+      assert.strictEqual(error.cause, cause);
+    });
+
+    it("should format AI operation error", () => {
+      const cause = new Error("AI failed");
+      const error = formatAIOperationError("generate", cause);
+      assert.ok(isTaskOMaticError(error));
+      assert.strictEqual(error.code, TaskOMaticErrorCodes.AI_OPERATION_FAILED);
+      assert.ok(error.message.includes("generate"));
+      assert.strictEqual(error.cause, cause);
+    });
+  });
+
+  describe("wrapErrorForBackwardCompatibility()", () => {
+    it("should return TaskOMaticError unchanged", () => {
+      const error = new TaskOMaticError("Test", {
+        code: TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+      });
+      const wrapped = wrapErrorForBackwardCompatibility(error);
+      assert.strictEqual(wrapped, error);
+    });
+
+    it("should return regular Error unchanged", () => {
+      const error = new Error("Regular error");
+      const wrapped = wrapErrorForBackwardCompatibility(error);
+      assert.strictEqual(wrapped, error);
+    });
+
+    it("should convert non-Error values to Error", () => {
+      const wrapped1 = wrapErrorForBackwardCompatibility("string error");
+      assert.ok(wrapped1 instanceof Error);
+      assert.ok(wrapped1.message.includes("string error"));
+
+      const wrapped2 = wrapErrorForBackwardCompatibility({
+        message: "object error",
+      });
+      assert.ok(wrapped2 instanceof Error);
+      assert.ok(wrapped2.message.includes("object error"));
+    });
+  });
+
+  describe("Error codes", () => {
+    it("should have defined error codes", () => {
+      assert.ok(TaskOMaticErrorCodes.UNEXPECTED_ERROR);
+      assert.ok(TaskOMaticErrorCodes.TASK_NOT_FOUND);
+      assert.ok(TaskOMaticErrorCodes.STORAGE_ERROR);
+      assert.ok(TaskOMaticErrorCodes.AI_OPERATION_FAILED);
+    });
+  });
+});

package/src/test/utils/file-utils.test.ts

@@ -0,0 +1,80 @@
+import assert from "assert";
+import { join } from "path";
+import { existsSync, mkdirSync, rmdirSync, writeFileSync } from "fs";
+import { fileExists, validateFileExists, validateFileExistsAsync, fileExistsAsync, savePRDFile, saveStackFile, loadStackFile } from "../../utils/file-utils";
+import { configManager } from "../../lib/config";
+import { TaskOMaticErrorCodes } from "../../utils/task-o-matic-error";
+
+describe("File Utilities", () => {
+  let testDir: string;
+
+  before(function () {
+    testDir = join(process.cwd(), "temp-test-file-utils");
+    if (!existsSync(testDir)) {
+      mkdirSync(testDir);
+    }
+    configManager.setWorkingDirectory(testDir);
+  });
+
+  after(function () {
+    try {
+        if (existsSync(testDir)) {
+             rmdirSync(testDir, { recursive: true });
+        }
+    } catch (e) {
+        // Ignore cleanup errors
+    }
+  });
+
+  describe("Validation", () => {
+    it("validateFileExists should pass for existing file", () => {
+      const existingFile = join(testDir, "exist.txt");
+      writeFileSync(existingFile, "content");
+      assert.doesNotThrow(() => validateFileExists(existingFile));
+    });
+
+    it("validateFileExists should throw for missing file", () => {
+      const missingFile = join(testDir, "missing.txt");
+      assert.throws(() => validateFileExists(missingFile), (err: any) => {
+        return err.code === TaskOMaticErrorCodes.INVALID_INPUT;
+      });
+    });
+
+    it("validateFileExistsAsync should pass for existing file", async () => {
+      const existingFile = join(testDir, "exist-async.txt");
+      writeFileSync(existingFile, "content");
+      await validateFileExistsAsync(existingFile);
+    });
+  });
+
+  describe("Existence Check", () => {
+    it("fileExists should return true for existing file", () => {
+      const existingFile = join(testDir, "exist-check.txt");
+      writeFileSync(existingFile, "content");
+      assert.strictEqual(fileExists(existingFile), true);
+    });
+
+    it("fileExists should return false for missing file", () => {
+      const missingFile = join(testDir, "missing-check.txt");
+      assert.strictEqual(fileExists(missingFile), false);
+    });
+  });
+
+  describe("PRD File", () => {
+      it("savePRDFile should save file to default location", () => {
+          const content = "# PRD Content";
+          const path = savePRDFile(content);
+          assert.ok(existsSync(path));
+      });
+  });
+
+  describe("Stack File", () => {
+      it("saveStackFile should save and load json", () => {
+          const data = { foo: "bar" };
+          const path = saveStackFile(data);
+          assert.ok(existsSync(path));
+          const loaded = loadStackFile<{ foo: string }>();
+          assert.deepStrictEqual(loaded, data);
+      });
+  });
+});

package/src/test/utils/id-generator.test.ts

@@ -0,0 +1,44 @@
+import assert from "assert";
+import { TaskIDGenerator } from "../../utils/id-generator";
+import { TaskOMaticErrorCodes } from "../../utils/task-o-matic-error";
+
+describe("TaskIDGenerator", () => {
+  describe("generate", () => {
+    it("should generate ID with default prefix", () => {
+      const id = TaskIDGenerator.generate();
+      assert.ok(id.startsWith("task-"));
+      assert.ok(TaskIDGenerator.validate(id));
+    });
+
+    it("should generate ID with custom prefix", () => {
+      const id = TaskIDGenerator.generate("custom");
+      assert.ok(id.startsWith("custom-"));
+      assert.ok(TaskIDGenerator.validate(id));
+    });
+  });
+
+  describe("validate", () => {
+    it("should validate timestamped format", () => {
+      assert.strictEqual(TaskIDGenerator.validate("task-123456-abcdef12"), true);
+    });
+
+    it("should validate hierarchical format", () => {
+      assert.strictEqual(TaskIDGenerator.validate("1.2.3"), true);
+    });
+
+    it("should reject invalid format", () => {
+      assert.strictEqual(TaskIDGenerator.validate("invalid id"), false);
+    });
+  });
+
+  describe("Hierarchical IDs", () => {
+    it("should generate child ID", () => {
+      assert.strictEqual(TaskIDGenerator.generateChildId("1", 1), "1.1");
+    });
+
+    it("should parse hierarchical ID", () => {
+      const result = TaskIDGenerator.parseHierarchicalId("1.2.3");
+      assert.deepStrictEqual(result, { parentId: "1.2", childIndex: 3 });
+    });
+  });
+});