@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/types/task-graph.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Task Graph System Types
+ * Defines the structure for decomposing large goals into executable task graphs
+ */
+/**
+ * Individual task node in the dependency graph
+ */
+export interface TaskNode {
+    /** Optional: Agent type to use (dev, architect, qa, etc.) */
+    agentType?: string;
+    /** Array of task IDs that must complete before this task can start */
+    dependencies: string[];
+    /** Detailed description of what this task accomplishes */
+    description: string;
+    /** Estimated time in minutes for Claude agent to complete */
+    estimatedMinutes: number;
+    /** Unique task identifier (e.g., "task-001") */
+    id: string;
+    /** File path where task output will be written */
+    outputFile: string;
+    /** Whether this task can run in parallel with other tasks in the same layer */
+    parallelizable: boolean;
+    /** Full prompt for the agent to execute this task */
+    prompt: string;
+    /** Optional: Specific files this task operates on (for per-file tasks) */
+    targetFiles?: string[];
+    /** Human-readable task title */
+    title: string;
+}
+/**
+ * Complete task graph representing a decomposed goal
+ */
+export interface TaskGraph {
+    /** The original big goal being decomposed */
+    goal: string;
+    /** Master prompt template reusable across similar goals */
+    masterPrompt: string;
+    /** Metadata about the task graph */
+    metadata: TaskGraphMetadata;
+    /** Session-specific information */
+    session: {
+        createdAt: string;
+        id: string;
+        outputDirectory: string;
+    };
+    /** Array of all tasks in the graph */
+    tasks: TaskNode[];
+}
+/**
+ * Metadata about the task graph
+ */
+export interface TaskGraphMetadata {
+    /** Estimated total duration in minutes */
+    estimatedDuration: number;
+    /** Execution layers (each layer runs in parallel, layers run sequentially) */
+    executionLayers: string[][];
+    /** Maximum number of tasks that can run in parallel */
+    maxParallelism: number;
+    /** Whether per-file task generation was used */
+    perFileMode: boolean;
+    /** Whether tasks are formatted as BMAD stories */
+    storyFormat?: boolean;
+    /** Optional: Total files targeted for per-file mode */
+    totalFiles?: number;
+    /** Total number of tasks */
+    totalTasks: number;
+}
+/**
+ * Result of executing a single task
+ */
+export interface TaskExecutionResult {
+    duration: number;
+    errors?: string;
+    exitCode: number;
+    output: string;
+    success: boolean;
+    taskId: string;
+}
+/**
+ * Result of executing entire task graph
+ */
+export interface GraphExecutionResult {
+    completedTasks: number;
+    executionSummary: {
+        layerResults: LayerExecutionResult[];
+    };
+    failedTasks: number;
+    skippedTasks: number;
+    success: boolean;
+    taskResults: TaskExecutionResult[];
+    totalDuration: number;
+    totalTasks: number;
+}
+/**
+ * Result of executing a single layer
+ */
+export interface LayerExecutionResult {
+    duration: number;
+    layerIndex: number;
+    parallelTasksExecuted: number;
+    success: boolean;
+    taskIds: string[];
+}
+/**
+ * Options for task decomposition
+ */
+export interface DecomposeOptions {
+    /** BMAD agent to use for planning/decomposition */
+    agent?: string;
+    /** Optional context files to provide to the planner */
+    contextFiles?: string[];
+    /** Working directory for task execution */
+    cwd?: string;
+    /** Execute immediately without confirmation */
+    execute?: boolean;
+    /** File glob pattern for per-file mode (e.g., "src/*.js") */
+    filePattern?: string;
+    /** The big goal to decompose */
+    goal: string;
+    /** Maximum number of tasks to run in parallel */
+    maxParallel?: number;
+    /** Enable per-file task generation for file-heavy operations */
+    perFile?: boolean;
+    /** Plan only without executing */
+    planOnly?: boolean;
+    /** Format tasks as proper BMAD stories instead of simple tasks */
+    storyFormat?: boolean;
+    /** Project prefix for story IDs (e.g., "MIGRATE", "REFACTOR") - required when storyFormat is true */
+    storyPrefix?: string;
+    /** Timeout per task in milliseconds */
+    taskTimeout?: number;
+}
+/**
+ * Configuration for the decompose session
+ */
+export interface DecomposeSessionConfig {
+    createdAt: Date;
+    goal: string;
+    options: DecomposeOptions;
+    outputDir: string;
+    sessionId: string;
+}

package/dist/types/task-graph.js

@@ -0,0 +1,5 @@
+/**
+ * Task Graph System Types
+ * Defines the structure for decomposing large goals into executable task graphs
+ */
+export {};

package/dist/utils/colors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Format a success message with green color and checkmark icon
+ *
+ * @param text - Message text to format
+ * @returns Formatted string with ANSI color codes and ✓ icon
+ */
+export declare const success: (text: string) => string;
+/**
+ * Format an error message with red color and X icon
+ *
+ * @param text - Message text to format
+ * @returns Formatted string with ANSI color codes and ✗ icon
+ */
+export declare const error: (text: string) => string;
+/**
+ * Format a warning message with yellow color and warning icon
+ *
+ * @param text - Message text to format
+ * @returns Formatted string with ANSI color codes and ⚠ icon
+ */
+export declare const warning: (text: string) => string;
+/**
+ * Format an info message with blue color and info icon
+ *
+ * @param text - Message text to format
+ * @returns Formatted string with ANSI color codes and ℹ icon
+ */
+export declare const info: (text: string) => string;
+/**
+ * Highlight text with cyan color for emphasis
+ *
+ * @param text - Text to highlight
+ * @returns Formatted string with ANSI color codes
+ */
+export declare const highlight: (text: string) => string;
+/**
+ * Format text in bold style
+ *
+ * @param text - Text to make bold
+ * @returns Formatted string with ANSI bold codes
+ */
+export declare const bold: (text: string) => string;
+/**
+ * Format text in dim style (lower intensity)
+ *
+ * @param text - Text to dim
+ * @returns Formatted string with ANSI dim codes
+ */
+export declare const dim: (text: string) => string;

package/dist/utils/colors.js

@@ -0,0 +1,50 @@
+import chalk from 'chalk';
+/**
+ * Format a success message with green color and checkmark icon
+ *
+ * @param text - Message text to format
+ * @returns Formatted string with ANSI color codes and ✓ icon
+ */
+export const success = (text) => chalk.green(`✓ ${text}`);
+/**
+ * Format an error message with red color and X icon
+ *
+ * @param text - Message text to format
+ * @returns Formatted string with ANSI color codes and ✗ icon
+ */
+export const error = (text) => chalk.red(`✗ ${text}`);
+/**
+ * Format a warning message with yellow color and warning icon
+ *
+ * @param text - Message text to format
+ * @returns Formatted string with ANSI color codes and ⚠ icon
+ */
+export const warning = (text) => chalk.yellow(`⚠ ${text}`);
+/**
+ * Format an info message with blue color and info icon
+ *
+ * @param text - Message text to format
+ * @returns Formatted string with ANSI color codes and ℹ icon
+ */
+export const info = (text) => chalk.blue(`ℹ ${text}`);
+/**
+ * Highlight text with cyan color for emphasis
+ *
+ * @param text - Text to highlight
+ * @returns Formatted string with ANSI color codes
+ */
+export const highlight = (text) => chalk.cyan(text);
+/**
+ * Format text in bold style
+ *
+ * @param text - Text to make bold
+ * @returns Formatted string with ANSI bold codes
+ */
+export const bold = (text) => chalk.bold(text);
+/**
+ * Format text in dim style (lower intensity)
+ *
+ * @param text - Text to dim
+ * @returns Formatted string with ANSI dim codes
+ */
+export const dim = (text) => chalk.dim(text);

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

@@ -0,0 +1,64 @@
+/**
+ * Error Formatter Utility
+ *
+ * Provides functions to format errors into user-friendly messages with
+ * actionable suggestions and colored output.
+ */
+/**
+ * Options for error formatting
+ */
+export interface FormatErrorOptions {
+    /**
+     * Use colored output
+     * @default true
+     */
+    colored?: boolean;
+    /**
+     * Include error code in output
+     * @default true
+     */
+    showCode?: boolean;
+    /**
+     * Include stack trace in output
+     * @default false
+     */
+    verbose?: boolean;
+}
+/**
+ * Format an error into a user-friendly message
+ *
+ * Converts errors into plain English with actionable suggestions.
+ * Supports custom error types with specific formatting.
+ *
+ * @param error - Error to format
+ * @param options - Formatting options
+ * @returns Formatted error message
+ * @example
+ * const message = formatError(error, { verbose: true })
+ * console.error(message)
+ */
+export declare function formatError(error: Error, options?: FormatErrorOptions): string;
+/**
+ * Format error with stack trace for verbose logging
+ *
+ * This is a convenience function that always includes the stack trace.
+ *
+ * @param error - Error to format
+ * @returns Formatted error message with stack trace
+ * @example
+ * const message = formatErrorVerbose(error)
+ * console.error(message)
+ */
+export declare function formatErrorVerbose(error: Error): string;
+/**
+ * Format error for plain text output without colors
+ *
+ * Useful for logging to files or non-terminal outputs.
+ *
+ * @param error - Error to format
+ * @returns Formatted error message without colors
+ * @example
+ * const message = formatErrorPlain(error)
+ * fs.writeFileSync('error.log', message)
+ */
+export declare function formatErrorPlain(error: Error): string;

package/dist/utils/error-formatter.js

@@ -0,0 +1,279 @@
+/**
+ * Error Formatter Utility
+ *
+ * Provides functions to format errors into user-friendly messages with
+ * actionable suggestions and colored output.
+ */
+import chalk from 'chalk';
+import { AgentError, BaseError, ConfigurationError, FileSystemError, ParserError, ValidationError } from './errors.js';
+/**
+ * Format an error into a user-friendly message
+ *
+ * Converts errors into plain English with actionable suggestions.
+ * Supports custom error types with specific formatting.
+ *
+ * @param error - Error to format
+ * @param options - Formatting options
+ * @returns Formatted error message
+ * @example
+ * const message = formatError(error, { verbose: true })
+ * console.error(message)
+ */
+export function formatError(error, options = {}) {
+    const { colored = true, showCode = true, verbose = false } = options;
+    // Use chalk or plain text based on colored option
+    const errorStyle = colored ? chalk.red.bold : (text) => text;
+    const warningStyle = colored ? chalk.yellow : (text) => text;
+    const contextStyle = colored ? chalk.gray : (text) => text;
+    let message = '';
+    // Add error indicator
+    message += `${errorStyle('✗')} ${errorStyle('Error')}: `;
+    // Format based on error type
+    message += getFormattedErrorMessage(error, { colored });
+    // Add suggestion if available
+    if (error instanceof BaseError && error.suggestion) {
+        message += `\n${warningStyle('💡 Suggestion:')} ${error.suggestion}`;
+    }
+    // Add error code if requested
+    if (showCode && error instanceof BaseError) {
+        message += `\n${contextStyle(`[${error.code}]`)}`;
+    }
+    // Add context information
+    if (error instanceof BaseError && error.context) {
+        message += `\n${contextStyle('Context:')} ${formatContext(error.context, { colored })}`;
+    }
+    // Add stack trace in verbose mode
+    if (verbose && error.stack) {
+        message += `\n\n${contextStyle('Stack Trace:')}\n${contextStyle(error.stack)}`;
+    }
+    return message;
+}
+/**
+ * Get formatted error message based on error type
+ *
+ * @param error - Error to format
+ * @param options - Formatting options
+ * @param options.colored - Whether to use colored output
+ * @returns Formatted error message
+ * @private
+ */
+function getFormattedErrorMessage(error, options) {
+    if (error instanceof ValidationError) {
+        return formatValidationError(error, options);
+    }
+    if (error instanceof FileSystemError) {
+        return formatFileSystemError(error, options);
+    }
+    if (error instanceof AgentError) {
+        return formatAgentError(error, options);
+    }
+    if (error instanceof ConfigurationError) {
+        return formatConfigurationError(error, options);
+    }
+    if (error instanceof ParserError) {
+        return formatParserError(error, options);
+    }
+    if (error instanceof BaseError) {
+        return formatBaseError(error, options);
+    }
+    return error.message;
+}
+/**
+ * Format a validation error with specific suggestions
+ *
+ * @param error - ValidationError to format
+ * @param options - Formatting options
+ * @param options.colored - Whether to use colored output
+ * @returns Formatted error message
+ * @private
+ */
+function formatValidationError(error, options) {
+    const suggestStyle = options.colored ? chalk.yellow : (text) => text;
+    let { message } = error;
+    // Add field-specific suggestions
+    if (error.context?.field) {
+        message += `\n${suggestStyle('→')} Field: ${error.context.field}`;
+    }
+    // Add generic validation suggestion
+    message += `\n${suggestStyle('→')} Check your input and try again.`;
+    return message;
+}
+/**
+ * Format a file system error with path information
+ *
+ * @param error - FileSystemError to format
+ * @param options - Formatting options
+ * @param options.colored - Whether to use colored output
+ * @returns Formatted error message
+ * @private
+ */
+function formatFileSystemError(error, options) {
+    const suggestStyle = options.colored ? chalk.yellow : (text) => text;
+    const pathStyle = options.colored ? chalk.cyan : (text) => text;
+    let { message } = error;
+    // Add file path if available
+    if (error.context?.filePath) {
+        message += `\n${suggestStyle('→')} Path: ${pathStyle(error.context.filePath)}`;
+    }
+    // Add suggestions based on error message
+    if (error.message.includes('not found') || error.message.includes('ENOENT')) {
+        message += `\n${suggestStyle('→')} Check the path and ensure the file exists.`;
+        message += `\n${suggestStyle('→')} Verify your current working directory.`;
+    }
+    else if (error.message.includes('permission') || error.message.includes('EACCES')) {
+        message += `\n${suggestStyle('→')} Check file permissions.`;
+        message += `\n${suggestStyle('→')} Ensure you have write access to the directory.`;
+    }
+    else {
+        message += `\n${suggestStyle('→')} Check the path and file permissions.`;
+    }
+    return message;
+}
+/**
+ * Format an agent error with execution details
+ *
+ * @param error - AgentError to format
+ * @param options - Formatting options
+ * @param options.colored - Whether to use colored output
+ * @returns Formatted error message
+ * @private
+ */
+function formatAgentError(error, options) {
+    const suggestStyle = options.colored ? chalk.yellow : (text) => text;
+    const codeStyle = options.colored ? chalk.cyan : (text) => text;
+    let { message } = error;
+    // Add exit code if available
+    if (error.context?.exitCode !== undefined) {
+        message += `\n${suggestStyle('→')} Exit code: ${codeStyle(String(error.context.exitCode))}`;
+    }
+    // Add stderr if available
+    if (error.context?.stderr) {
+        const stderr = String(error.context.stderr).trim();
+        if (stderr) {
+            message += `\n${suggestStyle('→')} Error output: ${stderr.slice(0, 200)}`;
+        }
+    }
+    // Add agent type if available
+    if (error.context?.agentType) {
+        message += `\n${suggestStyle('→')} Agent: ${error.context.agentType}`;
+    }
+    // Add suggestions
+    message += `\n${suggestStyle('→')} Check Claude CLI installation and authentication.`;
+    message += `\n${suggestStyle('→')} Verify the agent prompt and arguments.`;
+    return message;
+}
+/**
+ * Format a configuration error with field information
+ *
+ * @param error - ConfigurationError to format
+ * @param options - Formatting options
+ * @param options.colored - Whether to use colored output
+ * @returns Formatted error message
+ * @private
+ */
+function formatConfigurationError(error, options) {
+    const suggestStyle = options.colored ? chalk.yellow : (text) => text;
+    const fieldStyle = options.colored ? chalk.cyan : (text) => text;
+    let { message } = error;
+    // Add field information
+    if (error.context?.field) {
+        message += `\n${suggestStyle('→')} Field: ${fieldStyle(error.context.field)}`;
+    }
+    // Add expected value if available
+    if (error.context?.expected) {
+        message += `\n${suggestStyle('→')} Expected: ${error.context.expected}`;
+    }
+    // Add suggestions
+    message += `\n${suggestStyle('→')} Check .bmad-core/core-config.yaml for correct configuration.`;
+    message += `\n${suggestStyle('→')} Run 'bmad-workflow config validate' for detailed validation.`;
+    return message;
+}
+/**
+ * Format a parser error with line information
+ *
+ * @param error - ParserError to format
+ * @param options - Formatting options
+ * @param options.colored - Whether to use colored output
+ * @returns Formatted error message
+ * @private
+ */
+function formatParserError(error, options) {
+    const suggestStyle = options.colored ? chalk.yellow : (text) => text;
+    const lineStyle = options.colored ? chalk.cyan : (text) => text;
+    let { message } = error;
+    // Add file path if available
+    if (error.context?.filePath) {
+        message += `\n${suggestStyle('→')} File: ${error.context.filePath}`;
+    }
+    // Add line number if available
+    if (error.context?.line !== undefined) {
+        message += `\n${suggestStyle('→')} Line: ${lineStyle(String(error.context.line))}`;
+    }
+    // Add expected format if available
+    if (error.context?.expectedFormat) {
+        message += `\n${suggestStyle('→')} Expected format: ${error.context.expectedFormat}`;
+    }
+    // Add generic parsing suggestion
+    message += `\n${suggestStyle('→')} Check the file format against documentation.`;
+    message += `\n${suggestStyle('→')} Ensure proper markdown structure.`;
+    return message;
+}
+/**
+ * Format a base error
+ *
+ * @param error - BaseError to format
+ * @param _options - Formatting options (not used but required for interface consistency)
+ * @param _options.colored - Whether to use colored output (not used)
+ * @returns Formatted error message
+ * @private
+ */
+function formatBaseError(error, _options) {
+    return error.message;
+}
+/**
+ * Format error context object into readable string
+ *
+ * @param context - Context object to format
+ * @param options - Formatting options
+ * @param options.colored - Whether to use colored output
+ * @returns Formatted context string
+ * @private
+ */
+function formatContext(context, options) {
+    const keyStyle = options.colored ? chalk.cyan : (text) => text;
+    return Object.entries(context)
+        .filter(([key]) => key !== 'stderr' && key !== 'exitCode' && key !== 'agentType') // Skip already formatted fields
+        .map(([key, value]) => {
+        const valueStr = typeof value === 'object' ? JSON.stringify(value) : String(value);
+        return `${keyStyle(key)}: ${valueStr}`;
+    })
+        .join(', ');
+}
+/**
+ * Format error with stack trace for verbose logging
+ *
+ * This is a convenience function that always includes the stack trace.
+ *
+ * @param error - Error to format
+ * @returns Formatted error message with stack trace
+ * @example
+ * const message = formatErrorVerbose(error)
+ * console.error(message)
+ */
+export function formatErrorVerbose(error) {
+    return formatError(error, { verbose: true });
+}
+/**
+ * Format error for plain text output without colors
+ *
+ * Useful for logging to files or non-terminal outputs.
+ *
+ * @param error - Error to format
+ * @returns Formatted error message without colors
+ * @example
+ * const message = formatErrorPlain(error)
+ * fs.writeFileSync('error.log', message)
+ */
+export function formatErrorPlain(error) {
+    return formatError(error, { colored: false });
+}