@hyperdrive.bot/bmad-workflow 1.0.16 → 1.0.18

package/dist/services/scaffolding/workflow-session-scaffolder.d.ts

@@ -0,0 +1,182 @@
+/**
+ * WorkflowSessionScaffolder
+ *
+ * Creates structured session directories with spawn output files and summary reports.
+ * Provides persistent, browsable artifacts for troubleshooting and audit trails
+ * after each workflow run.
+ */
+import type pino from 'pino';
+import type { FileManager } from '../file-system/file-manager.js';
+import type { WorkflowLogFile } from '../logging/workflow-logger.js';
+/**
+ * Configuration for creating a workflow session
+ */
+export interface WorkflowSessionConfig {
+    /** Base directory for workflow sessions (e.g., 'docs/workflow-sessions') */
+    baseDir: string;
+    /** Session prefix (e.g., 'workflow', 'bmad-run') */
+    prefix: string;
+}
+/**
+ * Spawn output payload structure
+ */
+export interface SpawnOutputPayload {
+    /** Timestamp when spawn completed */
+    completedAt?: string;
+    /** Spawn output content */
+    content: string;
+    /** Spawn execution duration in milliseconds */
+    duration?: number;
+    /** Any errors from the spawn */
+    errors?: string;
+    /** Unique spawn identifier */
+    spawnId: string;
+    /** Whether the spawn succeeded */
+    success?: boolean;
+    /** Type of spawn: epic, story, or dev */
+    type: 'dev' | 'epic' | 'story';
+}
+/**
+ * Session report summary structure
+ */
+export interface SessionReportSummary {
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Session end timestamp */
+    endedAt: string;
+    /** List of errors encountered */
+    errors: Array<{
+        error: string;
+        identifier: string;
+        phase: string;
+        timestamp: string;
+    }>;
+    /** Overall success status */
+    overallSuccess: boolean;
+    /** Phase execution counts */
+    phases: {
+        developments: {
+            completed: number;
+            failed: number;
+            total: number;
+        };
+        epics: {
+            completed: number;
+            failed: number;
+            total: number;
+        };
+        stories: {
+            completed: number;
+            failed: number;
+            total: number;
+        };
+    };
+    /** Session identifier */
+    sessionId: string;
+    /** List of spawn files written */
+    spawnFiles: string[];
+    /** Session start timestamp */
+    startedAt: string;
+}
+/**
+ * Scaffolder for workflow session directory structure
+ */
+export declare class WorkflowSessionScaffolder {
+    private readonly fileManager;
+    private readonly logger;
+    private sessionDir;
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Create the session directory structure
+     *
+     * Creates:
+     * - Session root directory at `{baseDir}/{prefix}-{timestamp}/`
+     * - `spawns/` subdirectory for individual spawn output files
+     *
+     * @param config - Session configuration
+     * @returns Session directory path
+     */
+    createSessionStructure(config: WorkflowSessionConfig): Promise<string>;
+    /**
+     * Get the current session directory path
+     *
+     * @returns Session directory path or null if not created
+     */
+    getSessionDir(): null | string;
+    /**
+     * Write session report markdown file
+     *
+     * Generates SESSION_REPORT.md with execution summary, pass/fail counts,
+     * durations, and error listings.
+     *
+     * @param summary - Session execution summary
+     */
+    writeSessionReport(summary: SessionReportSummary): Promise<void>;
+    /**
+     * Write individual spawn output file
+     *
+     * Writes immediately (no buffering) to ensure partial results survive crashes.
+     *
+     * @param spawnId - Unique spawn identifier
+     * @param type - Type of spawn (epic, story, dev)
+     * @param content - Spawn output content
+     */
+    writeSpawnOutput(spawnId: string, type: 'dev' | 'epic' | 'story', content: string): Promise<void>;
+    /**
+     * Write individual spawn output file with full payload
+     *
+     * Writes immediately (no buffering) to ensure partial results survive crashes.
+     *
+     * @param payload - Full spawn output payload
+     */
+    writeSpawnOutput(payload: SpawnOutputPayload): Promise<void>;
+    /**
+     * Write workflow log YAML file
+     *
+     * Generates workflow-log.yaml machine-parseable audit trail file.
+     *
+     * @param logData - Full workflow log data (WorkflowLogFile interface)
+     */
+    writeWorkflowLog(logData: WorkflowLogFile): Promise<void>;
+    /**
+     * Build markdown content for session report
+     *
+     * @param summary - Session report summary
+     * @returns Formatted markdown content
+     * @private
+     */
+    private buildSessionReportMarkdown;
+    /**
+     * Build markdown content for spawn output file
+     *
+     * @param payload - Spawn output payload
+     * @returns Formatted markdown content
+     * @private
+     */
+    private buildSpawnMarkdown;
+    /**
+     * Capitalize first letter of a string
+     *
+     * @param str - String to capitalize
+     * @returns Capitalized string
+     * @private
+     */
+    private capitalizeFirst;
+    /**
+     * Format duration in human-readable format
+     *
+     * @param ms - Duration in milliseconds
+     * @returns Formatted duration string
+     * @private
+     */
+    private formatDuration;
+    /**
+     * Generate timestamp string for session directory name
+     *
+     * Format: YYYYMMDD-HHmmss
+     *
+     * @returns Formatted timestamp
+     * @private
+     */
+    private generateTimestamp;
+}

package/dist/services/scaffolding/workflow-session-scaffolder.js

@@ -0,0 +1,236 @@
+/**
+ * WorkflowSessionScaffolder
+ *
+ * Creates structured session directories with spawn output files and summary reports.
+ * Provides persistent, browsable artifacts for troubleshooting and audit trails
+ * after each workflow run.
+ */
+import * as yaml from 'js-yaml';
+import { join } from 'node:path';
+/**
+ * Scaffolder for workflow session directory structure
+ */
+export class WorkflowSessionScaffolder {
+    fileManager;
+    logger;
+    sessionDir = null;
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Create the session directory structure
+     *
+     * Creates:
+     * - Session root directory at `{baseDir}/{prefix}-{timestamp}/`
+     * - `spawns/` subdirectory for individual spawn output files
+     *
+     * @param config - Session configuration
+     * @returns Session directory path
+     */
+    async createSessionStructure(config) {
+        const timestamp = this.generateTimestamp();
+        const sessionDirName = `${config.prefix}-${timestamp}`;
+        const sessionDir = join(config.baseDir, sessionDirName);
+        this.logger.info({ prefix: config.prefix, sessionDir }, 'Creating workflow session structure');
+        // Create root session directory
+        await this.fileManager.createDirectory(sessionDir);
+        // Create spawns subdirectory
+        await this.fileManager.createDirectory(join(sessionDir, 'spawns'));
+        this.sessionDir = sessionDir;
+        this.logger.info({ sessionDir }, 'Workflow session structure created');
+        return sessionDir;
+    }
+    /**
+     * Get the current session directory path
+     *
+     * @returns Session directory path or null if not created
+     */
+    getSessionDir() {
+        return this.sessionDir;
+    }
+    /**
+     * Write session report markdown file
+     *
+     * Generates SESSION_REPORT.md with execution summary, pass/fail counts,
+     * durations, and error listings.
+     *
+     * @param summary - Session execution summary
+     */
+    async writeSessionReport(summary) {
+        if (!this.sessionDir) {
+            throw new Error('Session structure must be created before writing session report');
+        }
+        const reportPath = join(this.sessionDir, 'SESSION_REPORT.md');
+        this.logger.info({ reportPath, sessionId: summary.sessionId }, 'Writing session report');
+        const markdownContent = this.buildSessionReportMarkdown(summary);
+        await this.fileManager.writeFile(reportPath, markdownContent);
+        this.logger.info({ reportPath }, 'Session report written');
+    }
+    async writeSpawnOutput(spawnIdOrPayload, type, content) {
+        if (!this.sessionDir) {
+            throw new Error('Session structure must be created before writing spawn output');
+        }
+        // Normalize to payload
+        const payload = typeof spawnIdOrPayload === 'string'
+            ? {
+                content: content,
+                spawnId: spawnIdOrPayload,
+                type: type,
+            }
+            : spawnIdOrPayload;
+        const fileName = `${payload.type}-${payload.spawnId}.md`;
+        const filePath = join(this.sessionDir, 'spawns', fileName);
+        this.logger.info({ filePath, spawnId: payload.spawnId, type: payload.type }, 'Writing spawn output');
+        // Build markdown content with metadata header
+        const markdownContent = this.buildSpawnMarkdown(payload);
+        // Immediate write for crash resilience
+        await this.fileManager.writeFile(filePath, markdownContent);
+        this.logger.info({ filePath, spawnId: payload.spawnId }, 'Spawn output written');
+    }
+    /**
+     * Write workflow log YAML file
+     *
+     * Generates workflow-log.yaml machine-parseable audit trail file.
+     *
+     * @param logData - Full workflow log data (WorkflowLogFile interface)
+     */
+    async writeWorkflowLog(logData) {
+        if (!this.sessionDir) {
+            throw new Error('Session structure must be created before writing workflow log');
+        }
+        const logPath = join(this.sessionDir, 'workflow-log.yaml');
+        this.logger.info({ logPath, workflowId: logData.metadata.workflowId }, 'Writing workflow log');
+        const yamlContent = yaml.dump(logData, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+        });
+        await this.fileManager.writeFile(logPath, yamlContent);
+        this.logger.info({ logPath }, 'Workflow log written');
+    }
+    /**
+     * Build markdown content for session report
+     *
+     * @param summary - Session report summary
+     * @returns Formatted markdown content
+     * @private
+     */
+    buildSessionReportMarkdown(summary) {
+        const statusIcon = summary.overallSuccess ? '✅' : '❌';
+        const durationStr = this.formatDuration(summary.duration);
+        let md = `# Workflow Session Report\n\n`;
+        // Metadata section
+        md += `## Metadata\n\n`;
+        md += `- **Session ID:** ${summary.sessionId}\n`;
+        md += `- **Status:** ${statusIcon} ${summary.overallSuccess ? 'Completed Successfully' : 'Completed with Failures'}\n`;
+        md += `- **Started:** ${summary.startedAt}\n`;
+        md += `- **Ended:** ${summary.endedAt}\n`;
+        md += `- **Duration:** ${durationStr}\n\n`;
+        // Execution summary table
+        md += `## Execution Summary\n\n`;
+        md += `| Phase | Total | Completed | Failed | Pass Rate |\n`;
+        md += `|-------|-------|-----------|--------|------------|\n`;
+        for (const [phase, counts] of Object.entries(summary.phases)) {
+            const passRate = counts.total > 0 ? ((counts.completed / counts.total) * 100).toFixed(1) : '0.0';
+            md += `| ${this.capitalizeFirst(phase)} | ${counts.total} | ${counts.completed} | ${counts.failed} | ${passRate}% |\n`;
+        }
+        md += `\n`;
+        // Error listings (if any)
+        if (summary.errors.length > 0) {
+            md += `## Errors (${summary.errors.length})\n\n`;
+            for (const error of summary.errors) {
+                md += `### ${error.phase.toUpperCase()} - ${error.identifier}\n\n`;
+                md += `- **Timestamp:** ${error.timestamp}\n`;
+                md += `- **Error:** ${error.error}\n\n`;
+            }
+        }
+        // Spawn file inventory
+        md += `## Spawn Files\n\n`;
+        if (summary.spawnFiles.length > 0) {
+            for (const file of summary.spawnFiles) {
+                md += `- \`${file}\`\n`;
+            }
+        }
+        else {
+            md += `_No spawn files generated_\n`;
+        }
+        md += `\n---\n\n`;
+        md += `<!-- Powered by BMAD™ Core -->\n`;
+        return md;
+    }
+    /**
+     * Build markdown content for spawn output file
+     *
+     * @param payload - Spawn output payload
+     * @returns Formatted markdown content
+     * @private
+     */
+    buildSpawnMarkdown(payload) {
+        const statusIcon = payload.success === false ? '❌' : payload.success === true ? '✅' : '⏳';
+        const durationStr = payload.duration ? this.formatDuration(payload.duration) : 'N/A';
+        let md = `# ${payload.type.toUpperCase()} Spawn: ${payload.spawnId}\n\n`;
+        md += `## Metadata\n\n`;
+        md += `- **Spawn ID:** ${payload.spawnId}\n`;
+        md += `- **Type:** ${payload.type}\n`;
+        md += `- **Status:** ${statusIcon} ${payload.success === false ? 'Failed' : payload.success === true ? 'Success' : 'Unknown'}\n`;
+        md += `- **Duration:** ${durationStr}\n`;
+        if (payload.completedAt) {
+            md += `- **Completed At:** ${payload.completedAt}\n`;
+        }
+        md += `\n`;
+        if (payload.errors) {
+            md += `## Errors\n\n`;
+            md += `\`\`\`\n${payload.errors}\n\`\`\`\n\n`;
+        }
+        md += `## Output\n\n`;
+        md += `${payload.content}\n\n`;
+        md += `---\n\n`;
+        md += `<!-- Powered by BMAD™ Core -->\n`;
+        return md;
+    }
+    /**
+     * Capitalize first letter of a string
+     *
+     * @param str - String to capitalize
+     * @returns Capitalized string
+     * @private
+     */
+    capitalizeFirst(str) {
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    }
+    /**
+     * Format duration in human-readable format
+     *
+     * @param ms - Duration in milliseconds
+     * @returns Formatted duration string
+     * @private
+     */
+    formatDuration(ms) {
+        if (ms < 1000)
+            return `${ms}ms`;
+        if (ms < 60_000)
+            return `${(ms / 1000).toFixed(1)}s`;
+        if (ms < 3_600_000)
+            return `${(ms / 60_000).toFixed(1)}m`;
+        return `${(ms / 3_600_000).toFixed(1)}h`;
+    }
+    /**
+     * Generate timestamp string for session directory name
+     *
+     * Format: YYYYMMDD-HHmmss
+     *
+     * @returns Formatted timestamp
+     * @private
+     */
+    generateTimestamp() {
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = String(now.getMonth() + 1).padStart(2, '0');
+        const day = String(now.getDate()).padStart(2, '0');
+        const hours = String(now.getHours()).padStart(2, '0');
+        const minutes = String(now.getMinutes()).padStart(2, '0');
+        const seconds = String(now.getSeconds()).padStart(2, '0');
+        return `${year}${month}${day}-${hours}${minutes}${seconds}`;
+    }
+}

package/dist/utils/colors.d.ts

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

package/dist/utils/colors.js

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