@hyperdrive.bot/bmad-workflow 1.0.16 → 1.0.18

package/dist/utils/listr2-helpers.d.ts

@@ -0,0 +1,216 @@
+/**
+ * listr2 Helper Functions
+ *
+ * Utility functions for creating and managing listr2 task structures
+ * used by the WorkflowReporter for visualizing workflow progress.
+ */
+/**
+ * Default terminal width constraint for output formatting
+ */
+export declare const DEFAULT_TERMINAL_WIDTH = 80;
+/**
+ * Regex pattern for detecting ANSI escape codes
+ */
+export declare const ANSI_ESCAPE_PATTERN: RegExp;
+/**
+ * Strip ANSI escape codes from text
+ *
+ * @param text - Text potentially containing ANSI codes
+ * @returns Clean text without ANSI escape sequences
+ */
+export declare const stripAnsi: (text: string) => string;
+/**
+ * Check if the current environment is a TTY
+ *
+ * @returns true if stdout is a TTY, false otherwise
+ */
+export declare const isTTY: () => boolean;
+/**
+ * Plain-text status indicators (no ANSI codes)
+ */
+export declare const PLAIN_STATUS_INDICATORS: {
+    readonly completed: "[+]";
+    readonly failed: "[X]";
+    readonly queued: "[.]";
+    readonly running: "[*]";
+};
+/**
+ * Format a plain-text phase header for non-TTY output
+ *
+ * @param phaseName - Phase name (epic, story, dev, qa)
+ * @returns Plain-text header string (e.g., "=== Phase: Epic Generation ===")
+ */
+export declare const formatPlainPhaseHeader: (phaseName: string) => string;
+/**
+ * Format a plain-text spawn marker for non-TTY output
+ *
+ * @param itemId - Item identifier
+ * @param status - Spawn status (STARTED, COMPLETED, FAILED)
+ * @param durationMs - Optional duration in milliseconds
+ * @param error - Optional error message for failed spawns
+ * @returns Plain-text marker string (e.g., "[SPAWN] story-1.001 STARTED")
+ */
+export declare const formatPlainSpawnMarker: (itemId: string, status: "COMPLETED" | "FAILED" | "STARTED", durationMs?: number, error?: string) => string;
+/**
+ * Format a plain-text summary for non-TTY output
+ *
+ * @param totalSpawns - Total number of spawns
+ * @param passedCount - Number of passed spawns
+ * @param failedCount - Number of failed spawns
+ * @param durationMs - Total duration in milliseconds
+ * @returns Plain-text summary string
+ */
+export declare const formatPlainSummary: (totalSpawns: number, passedCount: number, failedCount: number, durationMs: number) => string;
+/**
+ * Format spawn output with visual delimiters for verbose mode
+ *
+ * @param spawnId - Spawn identifier
+ * @param output - Output content from the spawn
+ * @param maxWidth - Maximum line width (default: 80)
+ * @returns Formatted output with header/footer delimiters
+ */
+export declare const formatVerboseSpawnOutput: (spawnId: string, output: string, maxWidth?: number) => string;
+/**
+ * Wrap text lines to fit within a maximum width
+ *
+ * @param text - Text to wrap
+ * @param maxWidth - Maximum line width
+ * @returns Wrapped text
+ */
+export declare const wrapLines: (text: string, maxWidth: number) => string;
+/**
+ * Phase emoji mapping for visual consistency
+ */
+export declare const PHASE_EMOJI: Record<string, string>;
+/**
+ * Phase display names for titles
+ */
+export declare const PHASE_TITLES: Record<string, string>;
+/**
+ * Action verbs for spawn labels — maps phase to what the spawn is DOING (lowercase)
+ */
+export declare const PHASE_ACTION_VERBS: Record<string, string>;
+/**
+ * Get the action verb for a phase (e.g., "Creating" for story phase)
+ */
+export declare const getPhaseActionVerb: (phaseName: string) => string;
+/**
+ * Status indicators for spawn states
+ */
+export declare const STATUS_INDICATORS: {
+    readonly completed: string;
+    readonly failed: string;
+    readonly queued: string;
+    readonly running: string;
+};
+/**
+ * Get emoji for a phase name
+ *
+ * @param phaseName - Phase name (epic, story, dev, qa)
+ * @returns Emoji string for the phase
+ */
+export declare const getPhaseEmoji: (phaseName: string) => string;
+/**
+ * Create a formatted phase title with emoji
+ *
+ * @param phaseName - Phase name (epic, story, dev, qa)
+ * @returns Formatted title string with emoji (e.g., "📋 Epic Phase")
+ */
+export declare const createPhaseTitle: (phaseName: string) => string;
+/**
+ * Create a phase task group configuration for listr2
+ *
+ * @param phaseName - Phase name (epic, story, dev, qa)
+ * @returns Object with title and phase metadata
+ */
+export declare const createPhaseTaskGroup: (phaseName: string) => {
+    emoji: string;
+    phaseName: string;
+    title: string;
+};
+/**
+ * Create a layer task group configuration for listr2
+ *
+ * @param layerIndex - Zero-based layer index
+ * @param spawnCount - Number of spawns in the layer
+ * @param totalLayers - Total number of layers in the phase
+ * @returns Object with title and layer metadata
+ */
+export declare const createLayerTaskGroup: (layerIndex: number, spawnCount: number, totalLayers: number) => {
+    layerIndex: number;
+    spawnCount: number;
+    title: string;
+    totalLayers: number;
+};
+/**
+ * Spawn status type
+ */
+export type SpawnStatus = 'completed' | 'failed' | 'queued' | 'running';
+/**
+ * Format spawn status for display
+ *
+ * @param status - Current spawn status
+ * @param durationMs - Duration in milliseconds (optional)
+ * @param itemCount - Number of items processed (optional, for completed status)
+ * @param errorMessage - Error message (optional, for failed status)
+ * @returns Formatted status string
+ */
+export declare const formatSpawnStatus: (status: SpawnStatus, durationMs?: number, itemCount?: number, errorMessage?: string) => string;
+/**
+ * Layer result summary
+ */
+export interface LayerResult {
+    durationMs: number;
+    failureCount: number;
+    layerIndex: number;
+    spawnCount: number;
+    successCount: number;
+}
+/**
+ * Format a layer summary line for collapsed display
+ *
+ * @param result - Layer execution results
+ * @returns Formatted summary string
+ */
+export declare const formatLayerSummary: (result: LayerResult) => string;
+/**
+ * Phase result summary
+ */
+export interface PhaseResult {
+    durationMs: number;
+    failureCount: number;
+    itemCount: number;
+    phaseName: string;
+    successCount: number;
+}
+/**
+ * Format a phase summary for completion display
+ *
+ * @param result - Phase execution results
+ * @returns Formatted summary string
+ */
+export declare const formatPhaseSummary: (result: PhaseResult) => string;
+/**
+ * Create a spawn task title
+ *
+ * @param itemId - Item identifier (epic number, story number, etc.)
+ * @param itemTitle - Optional item title/description
+ * @param agentType - Type of agent being spawned
+ * @returns Formatted spawn task title
+ */
+export declare const createSpawnTitle: (itemId: string, itemTitle?: string, agentType?: string) => string;
+/**
+ * Truncate a string to a maximum length with ellipsis
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length (default: 60)
+ * @returns Truncated string with ellipsis if needed
+ */
+export declare const truncateText: (text: string, maxLength?: number) => string;
+/**
+ * Format elapsed time for running tasks (updates every second)
+ *
+ * @param startTime - Start timestamp in milliseconds
+ * @returns Formatted elapsed time string
+ */
+export declare const formatElapsedTime: (startTime: number) => string;

package/dist/utils/listr2-helpers.js

@@ -0,0 +1,334 @@
+/**
+ * listr2 Helper Functions
+ *
+ * Utility functions for creating and managing listr2 task structures
+ * used by the WorkflowReporter for visualizing workflow progress.
+ */
+import chalk from 'chalk';
+import { formatDuration } from './formatters.js';
+/**
+ * Default terminal width constraint for output formatting
+ */
+export const DEFAULT_TERMINAL_WIDTH = 80;
+/**
+ * Regex pattern for detecting ANSI escape codes
+ */
+export const ANSI_ESCAPE_PATTERN = /\u001B\[[0-9;]*[a-zA-Z]/g;
+/**
+ * Strip ANSI escape codes from text
+ *
+ * @param text - Text potentially containing ANSI codes
+ * @returns Clean text without ANSI escape sequences
+ */
+export const stripAnsi = (text) => text.replaceAll(ANSI_ESCAPE_PATTERN, '');
+/**
+ * Check if the current environment is a TTY
+ *
+ * @returns true if stdout is a TTY, false otherwise
+ */
+export const isTTY = () => process.stdout.isTTY === true;
+/**
+ * Plain-text status indicators (no ANSI codes)
+ */
+export const PLAIN_STATUS_INDICATORS = {
+    completed: '[+]',
+    failed: '[X]',
+    queued: '[.]',
+    running: '[*]',
+};
+/**
+ * Format a plain-text phase header for non-TTY output
+ *
+ * @param phaseName - Phase name (epic, story, dev, qa)
+ * @returns Plain-text header string (e.g., "=== Phase: Epic Generation ===")
+ */
+export const formatPlainPhaseHeader = (phaseName) => {
+    const title = PHASE_TITLES[phaseName.toLowerCase()] || `${phaseName} Phase`;
+    return `=== Phase: ${title} ===`;
+};
+/**
+ * Format a plain-text spawn marker for non-TTY output
+ *
+ * @param itemId - Item identifier
+ * @param status - Spawn status (STARTED, COMPLETED, FAILED)
+ * @param durationMs - Optional duration in milliseconds
+ * @param error - Optional error message for failed spawns
+ * @returns Plain-text marker string (e.g., "[SPAWN] story-1.001 STARTED")
+ */
+export const formatPlainSpawnMarker = (itemId, status, durationMs, error) => {
+    const duration = durationMs === undefined ? '' : ` (${formatDuration(durationMs)})`;
+    const errorSuffix = error ? `: ${error}` : '';
+    return `[SPAWN] ${itemId} ${status}${duration}${errorSuffix}`;
+};
+/**
+ * Format a plain-text summary for non-TTY output
+ *
+ * @param totalSpawns - Total number of spawns
+ * @param passedCount - Number of passed spawns
+ * @param failedCount - Number of failed spawns
+ * @param durationMs - Total duration in milliseconds
+ * @returns Plain-text summary string
+ */
+export const formatPlainSummary = (totalSpawns, passedCount, failedCount, durationMs) => {
+    const lines = [
+        '--- Summary ---',
+        `Total: ${totalSpawns} spawns`,
+        `Passed: ${passedCount}`,
+        `Failed: ${failedCount}`,
+        `Duration: ${formatDuration(durationMs)}`,
+    ];
+    return lines.join('\n');
+};
+/**
+ * Format spawn output with visual delimiters for verbose mode
+ *
+ * @param spawnId - Spawn identifier
+ * @param output - Output content from the spawn
+ * @param maxWidth - Maximum line width (default: 80)
+ * @returns Formatted output with header/footer delimiters
+ */
+export const formatVerboseSpawnOutput = (spawnId, output, maxWidth = DEFAULT_TERMINAL_WIDTH) => {
+    // Create delimiter line that fits within maxWidth
+    const headerText = `── ${spawnId} output ──`;
+    const footerText = `── end ${spawnId} ──`;
+    // Pad the delimiter to maxWidth with dashes
+    const headerPadding = Math.max(0, maxWidth - headerText.length);
+    const footerPadding = Math.max(0, maxWidth - footerText.length);
+    const header = headerText + '─'.repeat(headerPadding);
+    const footer = footerText + '─'.repeat(footerPadding);
+    // Wrap output lines to respect width constraint
+    const wrappedLines = wrapLines(output, maxWidth);
+    return `${header}\n${wrappedLines}\n${footer}`;
+};
+/**
+ * Wrap text lines to fit within a maximum width
+ *
+ * @param text - Text to wrap
+ * @param maxWidth - Maximum line width
+ * @returns Wrapped text
+ */
+export const wrapLines = (text, maxWidth) => {
+    const lines = text.split('\n');
+    const wrappedLines = [];
+    for (const line of lines) {
+        if (line.length <= maxWidth) {
+            wrappedLines.push(line);
+        }
+        else {
+            // Simple word-based wrapping
+            let currentLine = '';
+            const words = line.split(' ');
+            for (const word of words) {
+                if (currentLine.length === 0) {
+                    currentLine = word;
+                }
+                else if (currentLine.length + 1 + word.length <= maxWidth) {
+                    currentLine += ' ' + word;
+                }
+                else {
+                    wrappedLines.push(currentLine);
+                    currentLine = word;
+                }
+            }
+            if (currentLine.length > 0) {
+                wrappedLines.push(currentLine);
+            }
+        }
+    }
+    return wrappedLines.join('\n');
+};
+/**
+ * Phase emoji mapping for visual consistency
+ */
+export const PHASE_EMOJI = {
+    dev: '🛠️',
+    epic: '📋',
+    qa: '✅',
+    story: '📝',
+};
+/**
+ * Phase display names for titles
+ */
+export const PHASE_TITLES = {
+    dev: 'Dev',
+    epic: 'Epics',
+    qa: 'QA',
+    story: 'Stories',
+};
+/**
+ * Action verbs for spawn labels — maps phase to what the spawn is DOING (lowercase)
+ */
+export const PHASE_ACTION_VERBS = {
+    dev: 'developing',
+    epic: 'generating',
+    qa: 'reviewing',
+    story: 'creating',
+};
+/**
+ * Get the action verb for a phase (e.g., "Creating" for story phase)
+ */
+export const getPhaseActionVerb = (phaseName) => PHASE_ACTION_VERBS[phaseName.toLowerCase()] || 'Processing';
+/**
+ * Status indicators for spawn states
+ */
+export const STATUS_INDICATORS = {
+    completed: chalk.bold('✓'),
+    failed: chalk.bold('✗'),
+    queued: chalk.dim('◯'),
+    running: chalk.bold('◉'),
+};
+/**
+ * Get emoji for a phase name
+ *
+ * @param phaseName - Phase name (epic, story, dev, qa)
+ * @returns Emoji string for the phase
+ */
+export const getPhaseEmoji = (phaseName) => PHASE_EMOJI[phaseName.toLowerCase()] || '⚙️';
+/**
+ * Create a formatted phase title with emoji
+ *
+ * @param phaseName - Phase name (epic, story, dev, qa)
+ * @returns Formatted title string with emoji (e.g., "📋 Epic Phase")
+ */
+export const createPhaseTitle = (phaseName) => {
+    const emoji = getPhaseEmoji(phaseName);
+    const title = PHASE_TITLES[phaseName.toLowerCase()] || `${phaseName} Phase`;
+    return `${emoji} ${title}`;
+};
+/**
+ * Create a phase task group configuration for listr2
+ *
+ * @param phaseName - Phase name (epic, story, dev, qa)
+ * @returns Object with title and phase metadata
+ */
+export const createPhaseTaskGroup = (phaseName) => ({
+    emoji: getPhaseEmoji(phaseName),
+    phaseName: phaseName.toLowerCase(),
+    title: createPhaseTitle(phaseName),
+});
+/**
+ * Create a layer task group configuration for listr2
+ *
+ * @param layerIndex - Zero-based layer index
+ * @param spawnCount - Number of spawns in the layer
+ * @param totalLayers - Total number of layers in the phase
+ * @returns Object with title and layer metadata
+ */
+export const createLayerTaskGroup = (layerIndex, spawnCount, totalLayers) => {
+    const layerNumber = layerIndex + 1;
+    const title = `Layer ${layerNumber}/${totalLayers} (${spawnCount} ${spawnCount === 1 ? 'spawn' : 'spawns'})`;
+    return {
+        layerIndex,
+        spawnCount,
+        title,
+        totalLayers,
+    };
+};
+/**
+ * Format spawn status for display
+ *
+ * @param status - Current spawn status
+ * @param durationMs - Duration in milliseconds (optional)
+ * @param itemCount - Number of items processed (optional, for completed status)
+ * @param errorMessage - Error message (optional, for failed status)
+ * @returns Formatted status string
+ */
+export const formatSpawnStatus = (status, durationMs, itemCount, errorMessage) => {
+    const indicator = STATUS_INDICATORS[status];
+    const duration = durationMs === undefined ? '' : formatDuration(durationMs);
+    switch (status) {
+        case 'completed': {
+            if (itemCount !== undefined) {
+                return duration
+                    ? `${indicator} completed (${duration}) → ${itemCount} ${itemCount === 1 ? 'item' : 'items'}`
+                    : `${indicator} completed → ${itemCount} ${itemCount === 1 ? 'item' : 'items'}`;
+            }
+            return duration ? `${indicator} completed (${duration})` : `${indicator} completed`;
+        }
+        case 'failed': {
+            return errorMessage
+                ? `${indicator} failed: ${errorMessage}`
+                : `${indicator} failed`;
+        }
+        case 'queued': {
+            return `${indicator} queued`;
+        }
+        case 'running': {
+            return duration ? `${indicator} running (${duration})` : `${indicator} running`;
+        }
+        default: {
+            return `${indicator} ${status}`;
+        }
+    }
+};
+/**
+ * Format a layer summary line for collapsed display
+ *
+ * @param result - Layer execution results
+ * @returns Formatted summary string
+ */
+export const formatLayerSummary = (result) => {
+    const layerNumber = result.layerIndex + 1;
+    const duration = formatDuration(result.durationMs);
+    const passedText = `${result.successCount}/${result.spawnCount} passed`;
+    const statusColor = result.failureCount > 0
+        ? chalk.bold
+        : result.successCount === result.spawnCount
+            ? chalk.dim
+            : chalk.underline;
+    return `Layer ${layerNumber} (${result.spawnCount} ${result.spawnCount === 1 ? 'spawn' : 'spawns'}) — completed in ${duration} [${statusColor(passedText)}]`;
+};
+/**
+ * Format a phase summary for completion display
+ *
+ * @param result - Phase execution results
+ * @returns Formatted summary string
+ */
+export const formatPhaseSummary = (result) => {
+    const emoji = getPhaseEmoji(result.phaseName);
+    const title = PHASE_TITLES[result.phaseName.toLowerCase()] || `${result.phaseName} Phase`;
+    const duration = formatDuration(result.durationMs);
+    const passedText = `${result.successCount}/${result.itemCount}`;
+    const statusIcon = result.failureCount > 0
+        ? chalk.bold('✗')
+        : result.successCount === result.itemCount
+            ? chalk.bold('✓')
+            : chalk.bold('⚠');
+    return `${emoji} ${title} ${statusIcon} — ${passedText} in ${duration}`;
+};
+/**
+ * Create a spawn task title
+ *
+ * @param itemId - Item identifier (epic number, story number, etc.)
+ * @param itemTitle - Optional item title/description
+ * @param agentType - Type of agent being spawned
+ * @returns Formatted spawn task title
+ */
+export const createSpawnTitle = (itemId, itemTitle, agentType) => {
+    const prefix = agentType ? chalk.dim(`[${agentType}]`) : '';
+    const title = itemTitle ? `${itemId}: ${itemTitle}` : itemId;
+    return prefix ? `${prefix} ${title}` : title;
+};
+/**
+ * Truncate a string to a maximum length with ellipsis
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length (default: 60)
+ * @returns Truncated string with ellipsis if needed
+ */
+export const truncateText = (text, maxLength = 60) => {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return `${text.slice(0, maxLength - 3)}...`;
+};
+/**
+ * Format elapsed time for running tasks (updates every second)
+ *
+ * @param startTime - Start timestamp in milliseconds
+ * @returns Formatted elapsed time string
+ */
+export const formatElapsedTime = (startTime) => {
+    const elapsed = Date.now() - startTime;
+    return formatDuration(elapsed);
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hyperdrive.bot/bmad-workflow",
   "description": "AI-driven development workflow orchestration CLI for BMAD projects",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "author": {
     "name": "DevSquad",
     "email": "marcelo@devsquad.email",
@@ -23,6 +23,7 @@
     "fs-extra": "^11.3.2",
     "js-yaml": "^4.1.0",
     "jsonwebtoken": "^9.0.2",
+    "listr2": "^10.1.0",
     "nodemailer": "^7.0.9",
     "ora": "^9.0.0",
     "pino": "^10.0.0",
@@ -52,10 +53,10 @@
     "eslint": "^9",
     "eslint-config-oclif": "^6",
     "eslint-config-prettier": "^10",
+    "esmock": "^2.7.3",
     "mocha": "^10.8.2",
     "oclif": "^4",
     "prettier": "^3.6.2",
-    "esmock": "^2.7.3",
     "proxyquire": "^2.1.3",
     "sinon": "^17.0.1",
     "ts-node": "^10.9.2",