task-o-matic 0.0.13 → 0.0.15

package/dist/utils/cli-validators.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateMutuallyExclusive = validateMutuallyExclusive;
 exports.validateOneRequired = validateOneRequired;
 exports.parseCsvOption = parseCsvOption;
+const task_o_matic_error_1 = require("./task-o-matic-error");
 /**
  * Validate that exactly one of two mutually exclusive options is provided
  *
@@ -11,7 +12,7 @@ exports.parseCsvOption = parseCsvOption;
  * @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
@@ -22,10 +23,10 @@ function validateMutuallyExclusive(options, field1, field2, field1Label = field1
     const has1 = Boolean(options[field1]);
     const has2 = Boolean(options[field2]);
     if (!has1 && !has2) {
-        throw new Error(`Either --${field1Label} or --${field2Label} must be specified`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, `Either --${field1Label} or --${field2Label} must be specified`);
     }
     if (has1 && has2) {
-        throw new Error(`Cannot specify both --${field1Label} and --${field2Label}`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, `Cannot specify both --${field1Label} and --${field2Label}`);
     }
 }
 /**
@@ -33,7 +34,7 @@ function validateMutuallyExclusive(options, field1, field2, field1Label = field1
  *
  * @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
@@ -48,11 +49,11 @@ function validateOneRequired(options, ...fields) {
     const provided = fields.filter((f) => Boolean(options[f.name]));
     if (provided.length === 0) {
         const labels = fields.map((f) => `--${f.label}`).join(", ");
-        throw new Error(`One of ${labels} must be specified`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, `One of ${labels} must be specified`);
     }
     if (provided.length > 1) {
         const labels = provided.map((f) => `--${f.label}`).join(", ");
-        throw new Error(`Cannot specify multiple options: ${labels}`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, `Cannot specify multiple options: ${labels}`);
     }
 }
 /**

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

@@ -0,0 +1,70 @@
+/**
+ * Extracts a readable error message from an unknown error value.
+ * Handles Error objects, strings, objects with message property, and unknown types.
+ *
+ * @param error - The error value to extract message from
+ * @returns A string error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   throw new Error("Something went wrong");
+ * } catch (error) {
+ *   console.log(getErrorMessage(error)); // "Something went wrong"
+ * }
+ * ```
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Formats an error with optional context information.
+ * Useful for adding context to error messages when rethrowing.
+ *
+ * @param error - The error value
+ * @param context - Optional context string to prepend to the error message
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetchData();
+ * } catch (error) {
+ *   throw new Error(formatError(error, "Failed to fetch data"));
+ *   // Result: "Failed to fetch data: Connection timeout"
+ * }
+ * ```
+ */
+export declare function formatError(error: unknown, context?: string): string;
+/**
+ * Creates an error with a formatted message including context.
+ *
+ * @param error - The original error
+ * @param context - Context to add to the error
+ * @returns A new TaskOMaticError instance with formatted message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await operation();
+ * } catch (error) {
+ *   throw createContextError(error, "Operation failed");
+ * }
+ * ```
+ */
+export declare function createContextError(error: unknown, context: string): import("./task-o-matic-error").TaskOMaticError;
+/**
+ * Type guard to check if an error is an Error instance.
+ *
+ * @param error - Value to check
+ * @returns true if error is an Error instance
+ */
+export declare function isError(error: unknown): error is Error;
+/**
+ * Safely converts any value to an Error instance.
+ * If the value is already an Error, returns it unchanged.
+ * Otherwise, creates a new Error with the string representation.
+ *
+ * @param error - Value to convert
+ * @returns An Error instance
+ */
+export declare function toError(error: unknown): import("./task-o-matic-error").TaskOMaticError;
+//# sourceMappingURL=error-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.d.ts","sourceRoot":"","sources":["../../src/utils/error-utils.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAkBtD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,GACd,OAAO,sBAAsB,EAAE,eAAe,CAMhD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAEtD;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,OAAO,GACb,OAAO,sBAAsB,EAAE,eAAe,CAYhD"}

package/dist/utils/error-utils.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getErrorMessage = getErrorMessage;
+exports.formatError = formatError;
+exports.createContextError = createContextError;
+exports.isError = isError;
+exports.toError = toError;
+const task_o_matic_error_1 = require("./task-o-matic-error");
+/**
+ * Extracts a readable error message from an unknown error value.
+ * Handles Error objects, strings, objects with message property, and unknown types.
+ *
+ * @param error - The error value to extract message from
+ * @returns A string error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   throw new Error("Something went wrong");
+ * } catch (error) {
+ *   console.log(getErrorMessage(error)); // "Something went wrong"
+ * }
+ * ```
+ */
+function getErrorMessage(error) {
+    // Error instance
+    if (error instanceof Error) {
+        return error.message;
+    }
+    // String error
+    if (typeof error === "string") {
+        return error;
+    }
+    // Object with message property
+    if (error && typeof error === "object" && "message" in error) {
+        return String(error.message);
+    }
+    // Unknown type - convert to string
+    return "Unknown error occurred";
+}
+/**
+ * Formats an error with optional context information.
+ * Useful for adding context to error messages when rethrowing.
+ *
+ * @param error - The error value
+ * @param context - Optional context string to prepend to the error message
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetchData();
+ * } catch (error) {
+ *   throw new Error(formatError(error, "Failed to fetch data"));
+ *   // Result: "Failed to fetch data: Connection timeout"
+ * }
+ * ```
+ */
+function formatError(error, context) {
+    const message = getErrorMessage(error);
+    return context ? `${context}: ${message}` : message;
+}
+/**
+ * Creates an error with a formatted message including context.
+ *
+ * @param error - The original error
+ * @param context - Context to add to the error
+ * @returns A new TaskOMaticError instance with formatted message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await operation();
+ * } catch (error) {
+ *   throw createContextError(error, "Operation failed");
+ * }
+ * ```
+ */
+function createContextError(error, context) {
+    return (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.UNEXPECTED_ERROR, formatError(error, context), { cause: error instanceof Error ? error : undefined });
+}
+/**
+ * Type guard to check if an error is an Error instance.
+ *
+ * @param error - Value to check
+ * @returns true if error is an Error instance
+ */
+function isError(error) {
+    return error instanceof Error;
+}
+/**
+ * Safely converts any value to an Error instance.
+ * If the value is already an Error, returns it unchanged.
+ * Otherwise, creates a new Error with the string representation.
+ *
+ * @param error - Value to convert
+ * @returns An Error instance
+ */
+function toError(error) {
+    if (error instanceof Error) {
+        return (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.UNEXPECTED_ERROR, error.message, { cause: error });
+    }
+    return (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.UNEXPECTED_ERROR, getErrorMessage(error));
+}

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

@@ -0,0 +1,49 @@
+/**
+ * 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 declare function validateFileExists(filePath: string, customMessage?: string): void;
+/**
+ * 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 declare function validateFileExistsAsync(filePath: string, customMessage?: string): Promise<void>;
+/**
+ * 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 declare function fileExists(filePath: string): boolean;
+/**
+ * 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 declare function fileExistsAsync(filePath: string): Promise<boolean>;
+//# sourceMappingURL=file-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAUN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE"}

package/dist/utils/file-utils.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateFileExists = validateFileExists;
+exports.validateFileExistsAsync = validateFileExistsAsync;
+exports.fileExists = fileExists;
+exports.fileExistsAsync = fileExistsAsync;
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const task_o_matic_error_1 = require("./task-o-matic-error");
+/**
+ * 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
+ * ```
+ */
+function validateFileExists(filePath, customMessage) {
+    if (!(0, fs_1.existsSync)(filePath)) {
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.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
+ * ```
+ */
+async function validateFileExistsAsync(filePath, customMessage) {
+    try {
+        await (0, promises_1.access)(filePath, promises_1.constants.F_OK);
+    }
+    catch {
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.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
+ */
+function fileExists(filePath) {
+    return (0, fs_1.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
+ */
+async function fileExistsAsync(filePath) {
+    try {
+        await (0, promises_1.access)(filePath, promises_1.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/id-generator.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Generates unique task IDs with consistent format.
+ * Uses timestamp + random hex for uniqueness.
+ */
+export declare 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): string;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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, maxAttempts?: number): string;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/utils/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAE,MAAe,GAAG,MAAM;IAMhD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IA0BpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO;IAI9D;;;;;;;;;OASG;IACH,MAAM,CAAC,cAAc,CACnB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,MAAM,GAAE,MAAe,EACvB,WAAW,GAAE,MAAW,GACvB,MAAM;IAoBT;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAIpE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,mBAAmB,CACxB,EAAE,EAAE,MAAM,GACT;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAcnD"}

package/dist/utils/id-generator.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskIDGenerator = void 0;
+const crypto_1 = require("crypto");
+const task_o_matic_error_1 = require("./task-o-matic-error");
+/**
+ * Generates unique task IDs with consistent format.
+ * Uses timestamp + random hex for uniqueness.
+ */
+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 = "task") {
+        const timestamp = Date.now();
+        const random = (0, crypto_1.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) {
+        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, existingIds) {
+        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, prefix = "task", maxAttempts = 10) {
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const id = this.generate(prefix);
+            if (this.isUnique(id, existingIds)) {
+                return id;
+            }
+        }
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.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, childIndex) {
+        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) {
+        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 };
+    }
+}
+exports.TaskIDGenerator = TaskIDGenerator;

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

@@ -12,7 +12,7 @@ export declare const VALID_EXECUTORS: ExecutorTool[];
  *
  * @param value - Comma-separated model/executor specifications
  * @returns Array of model attempt configurations
- * @throws Error if an invalid executor is specified
+ * @throws TaskOMaticError if an invalid executor is specified
  *
  * @example
  * ```typescript

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

@@ -1 +1 @@
-{"version":3,"file":"model-executor-parser.d.ts","sourceRoot":"","sources":["../../src/utils/model-executor-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,YAAY,EAKzC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE,CA2BlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,YAAY,CAE3E"}
+{"version":3,"file":"model-executor-parser.d.ts","sourceRoot":"","sources":["../../src/utils/model-executor-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAM5D;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,YAAY,EAKzC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE,CA4BlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,YAAY,CAE3E"}

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

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

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

@@ -1,5 +1,6 @@
+import type { BTSFrontend } from "../types/index.js";
 export interface StackInfo {
-    frontend: string;
+    frontend: BTSFrontend | BTSFrontend[];
     backend: string;
     database: string;
     orm: string;

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

@@ -1 +1 @@
-{"version":3,"file":"stack-formatter.d.ts","sourceRoot":"","sources":["../../src/utils/stack-formatter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,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,CAyB3E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAMjF"}
+{"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"}