task-o-matic 0.0.13 → 0.0.15

package/dist/utils/task-o-matic-error.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskOMaticErrorCodes = exports.TaskOMaticError = void 0;
+exports.createStandardError = createStandardError;
+exports.formatStandardError = formatStandardError;
+exports.isTaskOMaticError = isTaskOMaticError;
+exports.formatTaskNotFoundError = formatTaskNotFoundError;
+exports.formatInvalidStatusTransitionError = formatInvalidStatusTransitionError;
+exports.formatStorageError = formatStorageError;
+exports.formatAIOperationError = formatAIOperationError;
+exports.wrapErrorForBackwardCompatibility = wrapErrorForBackwardCompatibility;
+const error_utils_1 = require("./error-utils");
+/**
+ * TaskOMaticError - Standardized error class for TaskOMatic
+ *
+ * Provides consistent error handling with context, suggestions, and typing.
+ * All errors in the system should use this class or one of the helper functions
+ * to ensure consistent error reporting and debugging experience.
+ *
+ * @example Basic usage
+ * ```typescript
+ * throw new TaskOMaticError("Task not found", {
+ *   code: "TASK_NOT_FOUND",
+ *   context: "Attempted to retrieve task ID: 123",
+ *   suggestions: [
+ *     "Verify the task ID is correct",
+ *     "Check if the task was deleted"
+ *   ]
+ * });
+ * ```
+ *
+ * @example With cause chain
+ * ```typescript
+ * try {
+ *   await storage.getTask(id);
+ * } catch (error) {
+ *   throw new TaskOMaticError("Failed to retrieve task", {
+ *     code: "STORAGE_ERROR",
+ *     cause: error instanceof Error ? error : new Error(String(error)),
+ *     context: `Task ID: ${id}`,
+ *     suggestions: ["Check storage permissions", "Verify storage is initialized"]
+ *   });
+ * }
+ * ```
+ *
+ * @example With metadata
+ * ```typescript
+ * throw new TaskOMaticError("AI operation timed out", {
+ *   code: "AI_OPERATION_FAILED",
+ *   metadata: {
+ *     operation: "task-breakdown",
+ *     duration: 30000,
+ *     retryAttempts: 3
+ *   },
+ *   suggestions: ["Increase timeout", "Check AI service status"]
+ * });
+ * ```
+ */
+class TaskOMaticError extends Error {
+    /**
+     * Error code for categorization
+     */
+    code;
+    /**
+     * Additional context information
+     */
+    context;
+    /**
+     * Actionable suggestions for resolving the error
+     */
+    suggestions;
+    /**
+     * Original error that caused this error (if applicable)
+     */
+    cause;
+    /**
+     * Timestamp when the error occurred
+     */
+    timestamp;
+    /**
+     * Additional metadata for debugging
+     */
+    metadata;
+    /**
+     * Create a new TaskOMaticError
+     *
+     * @param message - Error message
+     * @param options - Additional error options
+     */
+    constructor(message, options) {
+        super(message);
+        this.name = "TaskOMaticError";
+        this.code = options.code;
+        this.context = options.context;
+        this.suggestions = options.suggestions;
+        this.cause = options.cause;
+        this.timestamp = Date.now();
+        this.metadata = options.metadata;
+        // Maintain proper stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TaskOMaticError);
+        }
+    }
+    /**
+     * Get full error details as a formatted string
+     */
+    getDetails() {
+        let details = `[${this.code}] ${this.message}`;
+        if (this.context) {
+            details += `\nContext: ${this.context}`;
+        }
+        if (this.suggestions && this.suggestions.length > 0) {
+            details += `\nSuggestions:\n- ${this.suggestions.join("\n- ")}`;
+        }
+        if (this.cause) {
+            details += `\nCaused by: ${this.cause.message}`;
+        }
+        if (this.metadata && Object.keys(this.metadata).length > 0) {
+            details += `\nMetadata: ${JSON.stringify(this.metadata, null, 2)}`;
+        }
+        return details;
+    }
+    /**
+     * Get error details as a structured object
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            suggestions: this.suggestions,
+            cause: this.cause?.message,
+            timestamp: this.timestamp,
+            metadata: this.metadata,
+            stack: this.stack,
+        };
+    }
+}
+exports.TaskOMaticError = TaskOMaticError;
+/**
+ * Standard error codes for TaskOMatic
+ */
+exports.TaskOMaticErrorCodes = {
+    // General errors
+    UNEXPECTED_ERROR: "TASK_O_MATIC_001",
+    INVALID_INPUT: "TASK_O_MATIC_002",
+    CONFIGURATION_ERROR: "TASK_O_MATIC_003",
+    // Task-related errors
+    TASK_NOT_FOUND: "TASK_O_MATIC_101",
+    TASK_ALREADY_EXISTS: "TASK_O_MATIC_102",
+    INVALID_TASK_STATUS: "TASK_O_MATIC_103",
+    TASK_OPERATION_FAILED: "TASK_O_MATIC_104",
+    // Storage errors
+    STORAGE_ERROR: "TASK_O_MATIC_201",
+    STORAGE_NOT_INITIALIZED: "TASK_O_MATIC_202",
+    STORAGE_INTEGRITY_ERROR: "TASK_O_MATIC_203",
+    // AI operation errors
+    AI_OPERATION_FAILED: "TASK_O_MATIC_301",
+    AI_CONFIGURATION_ERROR: "TASK_O_MATIC_302",
+    AI_RATE_LIMIT: "TASK_O_MATIC_303",
+    // Workflow errors
+    WORKFLOW_VALIDATION_ERROR: "TASK_O_MATIC_401",
+    WORKFLOW_EXECUTION_ERROR: "TASK_O_MATIC_402",
+    // PRD errors
+    PRD_PARSING_ERROR: "TASK_O_MATIC_501",
+    PRD_GENERATION_ERROR: "TASK_O_MATIC_502",
+    PRD_VALIDATION_ERROR: "TASK_O_MATIC_503",
+};
+/**
+ * Create a standardized error with context and suggestions
+ *
+ * Helper function to create TaskOMaticError instances with proper error codes
+ * from the TaskOMaticErrorCodes constants.
+ *
+ * @param code - Error code from TaskOMaticErrorCodes
+ * @param message - Human-readable error message
+ * @param options - Additional error options
+ * @returns Configured TaskOMaticError instance
+ *
+ * @example
+ * ```typescript
+ * throw createStandardError(
+ *   TaskOMaticErrorCodes.TASK_NOT_FOUND,
+ *   "Task with ID '123' not found",
+ *   {
+ *     context: "User attempted to retrieve non-existent task",
+ *     suggestions: ["Verify task ID", "List all tasks to see available IDs"]
+ *   }
+ * );
+ * ```
+ */
+function createStandardError(code, message, options = {}) {
+    return new TaskOMaticError(message, {
+        code,
+        context: options.context,
+        suggestions: options.suggestions,
+        cause: options.cause,
+        metadata: options.metadata,
+    });
+}
+/**
+ * Format an existing error into a TaskOMaticError with context and suggestions
+ *
+ * Useful for wrapping caught errors with additional context while preserving
+ * the original error as the cause.
+ *
+ * @param error - Original error to wrap
+ * @param code - Error code from TaskOMaticErrorCodes
+ * @param options - Additional error options
+ * @returns TaskOMaticError wrapping the original error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await dangerousOperation();
+ * } catch (error) {
+ *   throw formatStandardError(
+ *     error,
+ *     TaskOMaticErrorCodes.STORAGE_ERROR,
+ *     {
+ *       context: "Failed during task persistence",
+ *       suggestions: ["Check disk space", "Verify write permissions"]
+ *     }
+ *   );
+ * }
+ * ```
+ */
+function formatStandardError(error, code, options = {}) {
+    const message = (0, error_utils_1.getErrorMessage)(error);
+    const cause = error instanceof Error ? error : undefined;
+    return new TaskOMaticError(message, {
+        code,
+        context: options.context,
+        suggestions: options.suggestions,
+        cause,
+        metadata: options.metadata,
+    });
+}
+/**
+ * Type guard for TaskOMaticError
+ */
+function isTaskOMaticError(error) {
+    return error instanceof TaskOMaticError;
+}
+/**
+ * Common error formatting functions
+ */
+function formatTaskNotFoundError(taskId) {
+    return createStandardError(exports.TaskOMaticErrorCodes.TASK_NOT_FOUND, `Task with ID "${taskId}" not found`, {
+        context: `The task "${taskId}" could not be found in the storage.`,
+        suggestions: [
+            "Verify the task ID is correct",
+            "Check if the task was deleted",
+            "List all tasks to see available IDs",
+        ],
+    });
+}
+function formatInvalidStatusTransitionError(fromStatus, toStatus) {
+    return createStandardError(exports.TaskOMaticErrorCodes.INVALID_TASK_STATUS, `Invalid status transition from "${fromStatus}" to "${toStatus}"`, {
+        context: `Task status transitions must follow the workflow: todo -> in-progress -> completed.`,
+        suggestions: [
+            "Use a valid status transition",
+            "Check the current task status",
+            "Review the workflow documentation",
+        ],
+    });
+}
+function formatStorageError(operation, cause) {
+    return createStandardError(exports.TaskOMaticErrorCodes.STORAGE_ERROR, `Storage operation "${operation}" failed`, {
+        context: `The storage operation "${operation}" could not be completed.`,
+        suggestions: [
+            "Check storage permissions",
+            "Verify storage configuration",
+            "Review storage logs for details",
+        ],
+        cause,
+    });
+}
+function formatAIOperationError(operation, cause) {
+    return createStandardError(exports.TaskOMaticErrorCodes.AI_OPERATION_FAILED, `AI operation "${operation}" failed`, {
+        context: `The AI operation "${operation}" could not be completed.`,
+        suggestions: [
+            "Check AI configuration",
+            "Verify API keys and endpoints",
+            "Review AI service status",
+            "Check rate limits",
+        ],
+        cause,
+    });
+}
+/**
+ * Backward compatibility wrapper
+ * Maintains existing error handling patterns while using new error system
+ */
+function wrapErrorForBackwardCompatibility(error, context) {
+    if (isTaskOMaticError(error)) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error((0, error_utils_1.formatError)(error, context));
+}

package/docs/agents/cli.md

@@ -1,191 +1,100 @@
-# Task-O-Matic CLI Agent Guide
+# Task-O-Matic Agent Guide
 
-You are an AI agent with access to the Task-O-Matic CLI tool for managing development tasks. This guide provides comprehensive usage patterns and command reference for autonomous development workflows.
+Concise reference for AI agents using Task-O-Matic in autonomous workflows.
 
-## Core Commands Reference
+## Core Workflow Commands
 
 ### Task Management
-```bash
-# Get next task to work on (prioritizes subtasks over parent tasks)
-task-o-matic tasks get-next [--status todo] [--tag <tag>] [--effort <small|medium|large>]
-
-# Show detailed task information  
-task-o-matic tasks show --id <task-id>
-
-# Update task status
-task-o-matic tasks status --id <task-id> --status <todo|in-progress|completed>
-
-# List all tasks with optional filtering
-task-o-matic tasks list [--status <status>] [--tag <tag>]
-
-# Create new tasks
-task-o-matic tasks create --title "Task Title" [--content "Description"] [--effort <small|medium|large>] [--parent-id <id>] [--ai-enhance] [--stream]
-
-# Split tasks into subtasks using AI
-task-o-matic tasks split --task-id <id> [--tools] [--stream] [--ai-provider <provider>]
-
-# Update task details
-task-o-matic tasks update --id <task-id> [--title "New Title"] [--description "New Description"] [--status <status>] [--effort <effort>]
-
-# Delete tasks
-task-o-matic tasks delete --id <task-id> --force [--cascade]
-```
-
-### Planning & Documentation
-```bash
-# Generate AI implementation plans for tasks
-task-o-matic tasks plan --id <task-id> [--stream] [--ai-provider <provider>]
-
-# View existing implementation plans
-task-o-matic tasks get-plan --id <task-id>
-
-# Set manual implementation plan
-task-o-matic tasks set-plan --id <task-id> --plan "Plan text" [or --plan-file <path>]
-
-# Generate AI task documentation with project context
-task-o-matic tasks document --task-id <task-id> [--force] [--stream] [--ai-provider <provider>]
-
-# Get existing task documentation
-task-o-matic tasks get-documentation --id <task-id>
 
-# Add documentation from external file
-task-o-matic tasks add-documentation --id <task-id> --doc-file <path> [--overwrite]
-```
-
-### PRD Management
 ```bash
-# Parse PRD into structured tasks
-task-o-matic prd parse --file <prd-file> [--tools] [--stream] [--ai-provider <provider>]
+# List tasks (filter by status or tag)
+task-o-matic tasks list [-s <status>] [-t <tag>]
 
-# Improve PRD based on feedback
-task-o-matic prd rework --file <prd-file> --feedback "Feedback text" [--tools] [--output <output-file>] [--stream]
-```
+# Get next task to work on (prioritizes subtasks)
+task-o-matic tasks get-next [-s <status>] [-t <tag>]
 
-### Project Initialization
-```bash
-# Initialize task-o-matic in current directory
-task-o-matic init init
+# Update task status
+task-o-matic tasks status -i <task-id> -s <todo|in-progress|completed>
 
-# Configure AI providers
-task-o-matic config set --provider <openai|anthropic|openrouter> --model <model-name> [--api-key <key>]
+# Add documentation from file
+task-o-matic tasks add-documentation -i <task-id> --doc-file <path>
 ```
 
-## Autonomous Development Workflow
+## Typical Agent Workflow
 
-### Primary Work Loop
 ```bash
-# 1. Get next available task (subtasks have priority)
-TASK_ID=$(task-o-matic tasks get-next --status todo | grep -oE '[a-f0-9-]{36}')
-
-# 2. Show task details and mark as in-progress
-task-o-matic tasks show --id $TASK_ID
-task-o-matic tasks status --id $TASK_ID --status in-progress
-
-# 3. Generate implementation plan with project context
-task-o-matic tasks plan --id $TASK_ID --stream
-
-# 4. Check for existing documentation or create it
-task-o-matic tasks get-documentation --id $TASK_ID || \
-task-o-matic tasks document --task-id $TASK_ID --stream
+# 1. Get next task
+TASK=$(task-o-matic tasks get-next -s todo)
 
-# 5. Execute implementation (use your development tools)
-# - Read project files using filesystem access
-# - Implement code changes
-# - Add tests if needed
+# 2. Mark as in-progress
+task-o-matic tasks status -i $TASK_ID -s in-progress
 
-# 6. Validate implementation
-npm run check-types    # Fix any type errors
-npm run build         # Fix any build errors  
-npm test             # Fix any test failures
+# 3. Implement the task
+# (use your development tools)
 
-# 7. Commit changes with descriptive message
-git add .
-git commit -m "$(task-o-matic tasks show --id $TASK_ID | grep Title | cut -d: -f2-) - completed"
+# 4. Validate
+npm run check-types && npm run build && npm test
 
-# 8. Mark task as completed
-task-o-matic tasks status --id $TASK_ID --status completed
+# 5. Mark as completed
+task-o-matic tasks status -i $TASK_ID -s completed
 
-# 9. Repeat - get next task
-task-o-matic tasks get-next
+# 6. Repeat
 ```
 
-## Advanced Features
+## Bootstrap Options
 
-### AI-Enhanced Operations
-Use `--tools` flag to enable filesystem tools for AI operations:
+### Web Projects
 ```bash
-# Parse PRD with project context awareness
-task-o-matic prd parse --file prd.md --tools --stream
-
-# Split tasks with understanding of current codebase
-task-o-matic tasks split --task-id <id> --tools --stream
-
-# Rework PRD considering current implementation
-task-o-matic prd rework --file prd.md --feedback "Add auth" --tools --stream
+task-o-matic init init --project-name my-app --frontend next --backend hono
 ```
 
-### Getting Help
+### Multi-Frontend Monorepo
 ```bash
-# Get help for main commands
-task-o-matic --help
+# Web + Native + CLI + TUI
+task-o-matic init init --project-name my-app --frontend "next native-uniwind cli tui" --backend hono
 
-# Get help for specific command groups
-task-o-matic tasks --help
-task-o-matic prd --help
-task-o-matic config --help
+# Web + Native
+task-o-matic init init --project-name my-app --frontend "next native-bare" --backend hono
 
-# Get help for specific commands
-task-o-matic tasks create --help
-task-o-matic tasks split --help
+# Web + CLI
+task-o-matic init init --project-name my-app --frontend "next cli" --backend hono
 ```
 
-### AI Provider Configuration
+### Single Frontend Projects
 ```bash
-# Configure different AI providers
-task-o-matic config set --provider openai --model gpt-4 --api-key <your-key>
-task-o-matic config set --provider anthropic --model claude-3-sonnet-20240229 --api-key <your-key>
-task-o-matic config set --provider openrouter --model anthropic/claude-3.5-sonnet --api-key <your-key>
+# CLI only
+task-o-matic init init --project-name my-cli --frontend cli --cli-deps full
 
-# Use different providers per command
-task-o-matic tasks plan --id <task-id> --ai-provider anthropic --ai-model claude-3-sonnet-20240229
-```
+# TUI only
+task-o-matic init init --project-name my-tui --frontend tui --tui-framework solid
 
-## Best Practices for AI Agents
+# Native only
+task-o-matic init init --project-name my-mobile --frontend native-uniwind --backend hono
+```
 
-### Task Prioritization
-1. **Always work on subtasks first** - `get-next` automatically prioritizes them
-2. **Mark parent tasks as in-progress** when starting their subtasks
-3. **Complete subtasks before marking parent as complete**
+### Frontend Options
+- **Web**: next, tanstack-router, react-router, nuxt, svelte, solid
+- **Native**: native-bare, native-uniwind, native-unistyles
+- **Custom**: cli, tui
 
-### Quality Assurance
-1. **Always validate before completion**: type-check → build → test → commit
-2. **Use streaming output** (`--stream`) to monitor AI operations in real-time
-3. **Enable filesystem tools** (`--tools`) when context awareness is beneficial
+### CLI Dependency Levels
+- **minimal**: commander + chalk only
+- **standard**: + inquirer + dotenv (default)
+- **full**: + mocha + tsx (testing)
+- **task-o-matic**: + AI SDK (Vercel AI)
 
-### Error Recovery
-- **Type errors**: Fix immediately, re-run `npm run check-types`
-- **Build errors**: Fix immediately, re-run `npm run build`  
-- **Test failures**: Fix immediately, re-run `npm test`
-- **Task confusion**: Use `task-o-matic tasks show --id <id>` for clarification
+### TUI Framework Options
+- **solid**: Solid.js (default, recommended)
+- **vue**: Vue.js
+- **react**: React
 
-### Continuous Development
-- **Never stop the loop**: Immediately get next task after completing current one
-- **Maintain clean git history**: One commit per completed task
-- **Use descriptive commit messages**: Include task title and completion status
-- **Leverage AI enhancements**: Use `--ai-enhance`, `--tools`, and `--stream` flags appropriately
+## Getting Help
 
-## Command Discovery
-When you need to discover available commands or options:
+All commands support `--help`:
 ```bash
-# Explore available commands
 task-o-matic --help
-
-# Explore command groups  
 task-o-matic tasks --help
-task-o-matic prd --help
-
-# Get detailed help for specific commands
-task-o-matic tasks [command] --help
+task-o-matic tasks list --help
 ```
 
-This comprehensive reference enables autonomous AI agents to effectively use Task-O-Matic CLI for continuous development workflows with proper task management, planning, documentation, and quality assurance.
+Full command reference: `docs/task-o-matic_help.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-o-matic",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "AI-powered task management CLI",
   "keywords": [
     "task-management",
@@ -50,7 +50,7 @@
     "dev:mcp": "tsx src/mcp/server.ts",
     "start": "node dist/cli/bin.js",
     "check-types": "tsc --noEmit --skipLibCheck",
-    "test": "mocha -r tsx/cjs src/test/**/*.test.ts",
+    "test": "mocha -r tsx/cjs src/test/test-setup.ts src/test/**/*.test.ts",
     "prepare": "npm run build && chmod +x dist/cli/bin.js",
     "prepublishOnly": "bun run build && chmod +x dist/cli/bin.js && bun test"
   },