task-o-matic-core 0.1.0

package/src/utils/file-utils.ts

@@ -0,0 +1,197 @@
+import { existsSync, writeFileSync, mkdirSync, readFileSync } from "fs";
+import { access, constants } from "fs/promises";
+import { join, dirname } from "path";
+import {
+  createStandardError,
+  TaskOMaticErrorCodes,
+} from "./task-o-matic-error";
+import { configManager } from "../lib/config";
+
+/**
+ * Validates that a file exists at the given path (synchronous).
+ * Throws an error with a custom message if the file doesn't exist.
+ *
+ * @param filePath - Path to the file to validate
+ * @param customMessage - Optional custom error message
+ * @throws TaskOMaticError if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * validateFileExists("./config.json", "Configuration file not found");
+ * // Throws: TaskOMaticError with code INVALID_INPUT if file doesn't exist
+ * ```
+ */
+export function validateFileExists(
+  filePath: string,
+  customMessage?: string
+): void {
+  if (!existsSync(filePath)) {
+    throw createStandardError(
+      TaskOMaticErrorCodes.INVALID_INPUT,
+      customMessage || `File not found: ${filePath}`,
+      {
+        suggestions: ["Verify the file path is correct."],
+      }
+    );
+  }
+}
+
+/**
+ * Validates that a file exists at the given path (asynchronous).
+ * Throws an error with a custom message if the file doesn't exist.
+ *
+ * @param filePath - Path to the file to validate
+ * @param customMessage - Optional custom error message
+ * @throws TaskOMaticError if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * await validateFileExistsAsync("./data.json");
+ * // Throws: TaskOMaticError with code INVALID_INPUT if file doesn't exist
+ * ```
+ */
+export async function validateFileExistsAsync(
+  filePath: string,
+  customMessage?: string
+): Promise<void> {
+  try {
+    await access(filePath, constants.F_OK);
+  } catch {
+    throw createStandardError(
+      TaskOMaticErrorCodes.INVALID_INPUT,
+      customMessage || `File not found: ${filePath}`,
+      {
+        suggestions: ["Verify the file path is correct."],
+      }
+    );
+  }
+}
+
+/**
+ * Checks if a file exists at the given path (synchronous).
+ * Returns true if file exists, false otherwise.
+ * Unlike validateFileExists, this doesn't throw an error.
+ *
+ * @param filePath - Path to check
+ * @returns true if file exists, false otherwise
+ */
+export function fileExists(filePath: string): boolean {
+  return existsSync(filePath);
+}
+
+/**
+ * Checks if a file exists at the given path (asynchronous).
+ * Returns true if file exists, false otherwise.
+ * Unlike validateFileExistsAsync, this doesn't throw an error.
+ *
+ * @param filePath - Path to check
+ * @returns Promise resolving to true if file exists, false otherwise
+ */
+export async function fileExistsAsync(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Saves a file to the PRD directory, ensuring the directory exists.
+ * If no output directory is specified, uses `.task-o-matic/prd/` by default.
+ *
+ * @param content - Content to write to the file
+ * @param filename - Filename (defaults to "prd.md")
+ * @param outputDir - Optional output directory override
+ * @returns Full path to the saved file
+ * @throws TaskOMaticError if file saving fails
+ *
+ * @example
+ * ```typescript
+ * // Save to default location (.task-o-matic/prd/prd.md)
+ * const path = savePRDFile("# My PRD\n...");
+ *
+ * // Save with custom filename
+ * const path = savePRDFile("# My PRD\n...", "custom-prd.md");
+ *
+ * // Save to custom directory
+ * const path = savePRDFile("# My PRD\n...", "prd.md", "./docs");
+ * ```
+ */
+export function savePRDFile(
+  content: string,
+  filename: string = "prd.md",
+  outputDir?: string
+): string {
+  const taskOMaticDir = configManager.getTaskOMaticDir();
+  const prdDir = outputDir || join(taskOMaticDir, "prd");
+
+  if (!existsSync(prdDir)) {
+    mkdirSync(prdDir, { recursive: true });
+  }
+
+  const path = join(prdDir, filename);
+  writeFileSync(path, content);
+
+  return path;
+}
+
+/**
+ * Saves a stack configuration to a JSON file.
+ * If no output path is specified, saves to `.task-o-matic/stack.json`.
+ *
+ * @param config - BTSConfig object to save
+ * @param outputPath - Optional custom output path
+ * @returns Full path to the saved file
+ *
+ * @example
+ * ```typescript
+ * // Save to default location
+ * const path = saveStackFile(config);
+ *
+ * // Save to custom location
+ * const path = saveStackFile(config, "./my-project/stack.json");
+ * ```
+ */
+export function saveStackFile(config: object, outputPath?: string): string {
+  const taskOMaticDir = configManager.getTaskOMaticDir();
+  const stackPath = outputPath || join(taskOMaticDir, "stack.json");
+
+  const dir = dirname(stackPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  writeFileSync(stackPath, JSON.stringify(config, null, 2));
+  return stackPath;
+}
+
+/**
+ * Loads a stack configuration from a JSON file.
+ * If no input path is specified, loads from `.task-o-matic/stack.json`.
+ *
+ * @param inputPath - Optional custom input path
+ * @returns The parsed BTSConfig object, or null if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * // Load from default location
+ * const config = loadStackFile();
+ *
+ * // Load from custom location
+ * const config = loadStackFile("./my-project/stack.json");
+ * ```
+ */
+export function loadStackFile<T = Record<string, unknown>>(
+  inputPath?: string
+): T | null {
+  const taskOMaticDir = configManager.getTaskOMaticDir();
+  const stackPath = inputPath || join(taskOMaticDir, "stack.json");
+
+  if (!existsSync(stackPath)) {
+    return null;
+  }
+
+  const content = readFileSync(stackPath, "utf-8");
+  return JSON.parse(content) as T;
+}

package/src/utils/id-generator.ts

@@ -0,0 +1,168 @@
+import { randomBytes } from "crypto";
+import {
+  createStandardError,
+  TaskOMaticErrorCodes,
+} from "./task-o-matic-error";
+
+/**
+ * Generates unique task IDs with consistent format.
+ * Uses timestamp + random hex for uniqueness.
+ */
+export class TaskIDGenerator {
+  /**
+   * Generates a unique task ID with format: prefix-timestamp-random
+   *
+   * @param prefix - Prefix for the ID (default: "task")
+   * @returns Unique task ID
+   *
+   * @example
+   * ```typescript
+   * const id = TaskIDGenerator.generate();
+   * // Returns: "task-1733750400000-a1b2c3d4"
+   *
+   * const customId = TaskIDGenerator.generate("subtask");
+   * // Returns: "subtask-1733750400000-e5f6g7h8"
+   * ```
+   */
+  static generate(prefix: string = "task"): string {
+    const timestamp = Date.now();
+    const random = randomBytes(4).toString("hex");
+    return `${prefix}-${timestamp}-${random}`;
+  }
+
+  /**
+   * Validates a task ID format.
+   * Accepts three formats:
+   * - Timestamped: "task-1234567890-abcd1234"
+   * - Hierarchical: "1.2.3"
+   * - Numeric: "123"
+   *
+   * @param id - Task ID to validate
+   * @returns true if ID format is valid
+   *
+   * @example
+   * ```typescript
+   * TaskIDGenerator.validate("task-1234-abcd"); // true
+   * TaskIDGenerator.validate("1.2.3"); // true
+   * TaskIDGenerator.validate("123"); // true
+   * TaskIDGenerator.validate("invalid!"); // false
+   * ```
+   */
+  static validate(id: string): boolean {
+    if (!id || typeof id !== "string") {
+      return false;
+    }
+
+    // Format 1: Timestamped (task-timestamp-random)
+    const timestampedPattern = /^[a-z]+-\d+-[a-f0-9]{8}$/;
+    if (timestampedPattern.test(id)) {
+      return true;
+    }
+
+    // Format 2: Hierarchical (1.2.3)
+    const hierarchicalPattern = /^[\d.]+$/;
+    if (hierarchicalPattern.test(id)) {
+      return true;
+    }
+
+    // Format 3: Numeric (123)
+    const numericPattern = /^\d+$/;
+    if (numericPattern.test(id)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Checks if an ID is unique within a set of existing IDs.
+   *
+   * @param id - ID to check
+   * @param existingIds - Set of existing IDs
+   * @returns true if ID is unique
+   */
+  static isUnique(id: string, existingIds: Set<string>): boolean {
+    return !existingIds.has(id);
+  }
+
+  /**
+   * Generates a unique ID that doesn't exist in the provided set.
+   * Retries up to maxAttempts times if collisions occur.
+   *
+   * @param existingIds - Set of existing IDs to avoid
+   * @param prefix - Prefix for the ID
+   * @param maxAttempts - Maximum number of generation attempts
+   * @returns Unique task ID
+   * @throws TaskOMaticError if unable to generate unique ID after maxAttempts
+   */
+  static generateUnique(
+    existingIds: Set<string>,
+    prefix: string = "task",
+    maxAttempts: number = 10
+  ): string {
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const id = this.generate(prefix);
+      if (this.isUnique(id, existingIds)) {
+        return id;
+      }
+    }
+
+    throw createStandardError(
+      TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+      `Failed to generate unique ID after ${maxAttempts} attempts`,
+      {
+        context: `Could not find a unique ID with prefix '${prefix}' after ${maxAttempts} attempts.`,
+        suggestions: [
+          "Increase maxAttempts if you have a very large number of tasks.",
+        ],
+      }
+    );
+  }
+
+  /**
+   * Generates a hierarchical child ID from a parent ID.
+   * If parent is "1.2", generates "1.2.1", "1.2.2", etc.
+   *
+   * @param parentId - Parent task ID
+   * @param childIndex - Index of the child (1-based)
+   * @returns Child task ID
+   *
+   * @example
+   * ```typescript
+   * TaskIDGenerator.generateChildId("1", 1); // "1.1"
+   * TaskIDGenerator.generateChildId("1.2", 3); // "1.2.3"
+   * ```
+   */
+  static generateChildId(parentId: string, childIndex: number): string {
+    return `${parentId}.${childIndex}`;
+  }
+
+  /**
+   * Parses a hierarchical ID to extract parent ID and child index.
+   *
+   * @param id - Hierarchical task ID
+   * @returns Object with parentId and childIndex, or null if not hierarchical
+   *
+   * @example
+   * ```typescript
+   * TaskIDGenerator.parseHierarchicalId("1.2.3");
+   * // Returns: { parentId: "1.2", childIndex: 3 }
+   * ```
+   */
+  static parseHierarchicalId(
+    id: string
+  ): { parentId: string; childIndex: number } | null {
+    const parts = id.split(".");
+    if (parts.length < 2) {
+      return null;
+    }
+
+    const childIndex = parseInt(parts[parts.length - 1], 10);
+    if (isNaN(childIndex)) {
+      return null;
+    }
+
+    const parentId = parts.slice(0, -1).join(".");
+    return { parentId, childIndex };
+  }
+}

package/src/utils/metadata-utils.ts

@@ -0,0 +1,48 @@
+import { AIConfig } from "../types";
+
+/**
+ * Creates base AI metadata object with common fields.
+ * Caller can extend with operation-specific fields.
+ *
+ * @param taskId - The ID of the task
+ * @param aiConfig - AI configuration used for the operation
+ * @param promptOverride - Optional custom prompt override
+ * @param defaultPrompt - Default prompt if no override provided
+ * @param confidence - Confidence score (0-1) for the AI operation
+ * @returns Base metadata object
+ *
+ * @example
+ * ```typescript
+ * const baseMetadata = createBaseAIMetadata(
+ *   "task-123",
+ *   { provider: "anthropic", model: "claude-sonnet-4.5" },
+ *   undefined,
+ *   "Split task into subtasks",
+ *   0.9
+ * );
+ *
+ * // Extend with operation-specific fields
+ * const subtaskMetadata = {
+ *   ...baseMetadata,
+ *   parentTaskId: "parent-123",
+ *   subtaskIndex: 1
+ * };
+ * ```
+ */
+export function createBaseAIMetadata(
+  taskId: string,
+  aiConfig: Partial<AIConfig>,
+  promptOverride?: string,
+  defaultPrompt: string = "AI-generated task",
+  confidence: number = 0.9
+) {
+  return {
+    taskId,
+    aiGenerated: true,
+    aiPrompt: promptOverride || defaultPrompt,
+    confidence,
+    aiProvider: aiConfig.provider,
+    aiModel: aiConfig.model,
+    generatedAt: Date.now(),
+  };
+}

package/src/utils/model-executor-parser.ts

@@ -0,0 +1,80 @@
+import { ExecutorTool, ModelAttemptConfig } from "../types";
+import {
+  createStandardError,
+  TaskOMaticErrorCodes,
+} from "./task-o-matic-error";
+
+/**
+ * Valid executor tools
+ */
+export const VALID_EXECUTORS: ExecutorTool[] = [
+  "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" }, ...]
+ * ```
+ */
+export function parseTryModels(value: string): ModelAttemptConfig[] {
+  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 (!VALID_EXECUTORS.includes(executor as ExecutorTool)) {
+        throw createStandardError(
+          TaskOMaticErrorCodes.INVALID_INPUT,
+          `Invalid executor "${executor}" in --try-models. Must be one of: ${VALID_EXECUTORS.join(
+            ", "
+          )}`
+        );
+      }
+
+      return {
+        executor: executor as ExecutorTool,
+        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
+ * }
+ * ```
+ */
+export function validateExecutor(executor: string): executor is ExecutorTool {
+  return VALID_EXECUTORS.includes(executor as ExecutorTool);
+}

package/src/utils/model-parser.ts

@@ -0,0 +1,58 @@
+import { isValidAIProvider } from "../lib/validation";
+
+// Helper to parse model string ([provider:]model[;reasoning[=budget]])
+export function parseModelString(modelStr: string): {
+  provider?: string;
+  model: string;
+  reasoning?: string;
+} {
+  let processingStr = modelStr;
+  let reasoning: string | undefined;
+
+  // 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 (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/src/utils/stack-formatter.ts

@@ -0,0 +1,53 @@
+import type { BTSFrontend } from "../types/index.js";
+
+export interface StackInfo {
+  frontend: BTSFrontend | BTSFrontend[];
+  backend: string;
+  database: string;
+  orm: string;
+  auth: string;
+  addons: string[];
+}
+
+export function formatStackInfo(stack: StackInfo | null | undefined): string {
+  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(", ");
+}
+
+export function formatStackForContext(stack: StackInfo | null | undefined): string {
+  if (!stack) {
+    return "";
+  }
+
+  const frontendStr = Array.isArray(stack.frontend)
+    ? stack.frontend.join(" + ")
+    : stack.frontend;
+
+  return `Technology Stack: ${frontendStr} + ${stack.backend} + ${stack.database}`;
+}

package/src/utils/storage-utils.ts

@@ -0,0 +1,94 @@
+import { Task } from "../types/index.js";
+import {
+  createStandardError,
+  formatTaskNotFoundError,
+  TaskOMaticErrorCodes,
+} from "./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
+ * ```
+ */
+export function requireTask(task: Task | null, taskId: string): Task {
+  if (!task) {
+    throw 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
+ */
+export function requireTasks(
+  tasks: (Task | null)[],
+  context: string = "tasks"
+): Task[] {
+  const validTasks: Task[] = [];
+  const missingIds: string[] = [];
+
+  tasks.forEach((task, index) => {
+    if (!task) {
+      missingIds.push(`index ${index}`);
+    } else {
+      validTasks.push(task);
+    }
+  });
+
+  if (missingIds.length > 0) {
+    throw createStandardError(
+      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)
+ * ```
+ */
+export function filterNullTasks(tasks: (Task | null)[]): Task[] {
+  return tasks.filter((task): task is 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
+ */
+export function validateTaskId(taskId: string): void {
+  if (!taskId || typeof taskId !== "string" || !taskId.trim()) {
+    throw createStandardError(
+      TaskOMaticErrorCodes.INVALID_INPUT,
+      "Invalid task ID: must be a non-empty string"
+    );
+  }
+}