@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/parsers/epic-parser.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Epic Parser Service
+ *
+ * Extracts story information from epic markdown files.
+ * Supports multiple story header formats for resilient parsing.
+ *
+ * Supported Formats:
+ * - ### Story 1.1: Initialize Project (full prefix with colon)
+ * - ### Story 1.1 - Initialize Project (full prefix with dash)
+ * - ### 1.1: Initialize Project (number only with colon)
+ * - ### 1.1. Initialize Project (number with period)
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'parser' })
+ * const parser = new EpicParser(logger)
+ * const stories = parser.parseStories(epicContent, 'epic-1.md')
+ * ```
+ */
+import type pino from 'pino';
+import type { Story } from '../../models/story.js';
+/**
+ * Epic Parser Service
+ *
+ * Parses epic markdown files to extract story information
+ * using multiple resilient patterns for different markdown formats.
+ */
+export declare class EpicParser {
+    private readonly logger;
+    /**
+     * Story header patterns in order of specificity (most specific first)
+     */
+    private readonly patterns;
+    /**
+     * Create a new EpicParser instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger: pino.Logger);
+    /**
+     * Extract epic number from filename
+     *
+     * Supports various filename formats:
+     * - `epic-2-parsing-services.md` → 2
+     * - `BMAD-ORCHESTRATOR-CLI-epic-2.md` → 2
+     * - `TENANT-LOGO-epic-1.md` → 1
+     *
+     * @param filename - Epic filename or path
+     * @returns Epic number extracted from filename
+     * @throws {ParserError} If no epic number can be extracted
+     * @example
+     * ```typescript
+     * const num = parser.parseEpicNumber('epic-2-parsing.md')
+     * // Returns: 2
+     * ```
+     */
+    parseEpicNumber(filename: string): number;
+    /**
+     * Parse stories from epic content
+     *
+     * Extracts story information using multiple pattern matching strategies.
+     * Returns stories sorted by their position in the document (natural order).
+     *
+     * Supported patterns:
+     * - `### Story 1.1: Initialize Project` (full prefix with colon)
+     * - `### Story 1.1 - Initialize Project` (full prefix with dash)
+     * - `### 1.1: Initialize Project` (number only with colon)
+     * - `### 1.1. Initialize Project` (number with period)
+     *
+     * @param epicContent - Full epic markdown content
+     * @param epicPath - Path to epic file (for error messages and epic number extraction)
+     * @returns Array of Story objects sorted by document position
+     * @throws {ParserError} When no Stories section is found or no stories are extracted
+     * @example
+     * ```typescript
+     * const stories = parser.parseStories(epicContent, 'docs/epics/epic-1-foundation.md')
+     * console.log(`Found ${stories.length} stories`)
+     * ```
+     */
+    parseStories(epicContent: string, epicPath: string): Story[];
+    /**
+     * Deduplicate matches that appear at the same position
+     *
+     * When multiple patterns match the same line, keep only the first match.
+     *
+     * @param matches - Array of story matches
+     * @returns Deduplicated array of Story objects
+     */
+    private deduplicateMatches;
+    /**
+     * Find the line number where a match appears
+     *
+     * @param lines - Array of lines from the document
+     * @param matchText - Text to find
+     * @returns Line number (0-indexed)
+     */
+    private findLineNumber;
+    /**
+     * Check if epic content has a Stories section
+     *
+     * @param content - Epic markdown content
+     * @returns True if Stories section exists
+     */
+    private hasStoriesSection;
+    /**
+     * Match a single pattern against epic content
+     *
+     * @param pattern - Pattern configuration with name and regex
+     * @param pattern.name - Pattern name
+     * @param pattern.regex - Pattern regular expression
+     * @param lines - Epic content split into lines
+     * @param content - Full epic content
+     * @param epicNumber - Epic number from filename
+     * @returns Array of matches for this pattern
+     */
+    private matchPattern;
+}

package/dist/services/parsers/epic-parser.js

@@ -0,0 +1,264 @@
+/**
+ * Epic Parser Service
+ *
+ * Extracts story information from epic markdown files.
+ * Supports multiple story header formats for resilient parsing.
+ *
+ * Supported Formats:
+ * - ### Story 1.1: Initialize Project (full prefix with colon)
+ * - ### Story 1.1 - Initialize Project (full prefix with dash)
+ * - ### 1.1: Initialize Project (number only with colon)
+ * - ### 1.1. Initialize Project (number with period)
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'parser' })
+ * const parser = new EpicParser(logger)
+ * const stories = parser.parseStories(epicContent, 'epic-1.md')
+ * ```
+ */
+import { ParserError } from '../../utils/errors.js';
+/**
+ * Epic Parser Service
+ *
+ * Parses epic markdown files to extract story information
+ * using multiple resilient patterns for different markdown formats.
+ */
+export class EpicParser {
+    logger;
+    /**
+     * Story header patterns in order of specificity (most specific first)
+     */
+    patterns = [
+        {
+            name: 'Story N.M: Title',
+            regex: /^###\s+Story\s+(\d+)\.(\d+)\s*:\s*(.+?)$/gim,
+        },
+        {
+            name: 'Story N.M - Title',
+            regex: /^###\s+Story\s+(\d+)\.(\d+)\s+-\s+(.+?)$/gim,
+        },
+        {
+            name: 'N.M: Title',
+            regex: /^###\s+(\d+)\.(\d+)\s*:\s*(.+?)$/gim,
+        },
+        {
+            name: 'N.M. Title',
+            regex: /^###\s+(\d+)\.(\d+)\s*\.\s+(.+?)$/gim,
+        },
+    ];
+    /**
+     * Create a new EpicParser instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Extract epic number from filename
+     *
+     * Supports various filename formats:
+     * - `epic-2-parsing-services.md` → 2
+     * - `BMAD-ORCHESTRATOR-CLI-epic-2.md` → 2
+     * - `TENANT-LOGO-epic-1.md` → 1
+     *
+     * @param filename - Epic filename or path
+     * @returns Epic number extracted from filename
+     * @throws {ParserError} If no epic number can be extracted
+     * @example
+     * ```typescript
+     * const num = parser.parseEpicNumber('epic-2-parsing.md')
+     * // Returns: 2
+     * ```
+     */
+    parseEpicNumber(filename) {
+        this.logger.debug({ filename }, 'Extracting epic number from filename');
+        // Extract just the filename if a path is provided
+        const basename = filename.split('/').pop() || filename;
+        // Pattern to match epic number: looks for "epic-N" or "epic N"
+        const epicPattern = /epic[-\s]?(\d+)/i;
+        const match = basename.match(epicPattern);
+        if (match && match[1]) {
+            const epicNumber = Number.parseInt(match[1], 10);
+            this.logger.debug({ epicNumber, filename }, 'Epic number extracted successfully');
+            return epicNumber;
+        }
+        // If no match, throw error
+        this.logger.error({ filename }, 'Could not extract epic number from filename');
+        throw new ParserError('Could not extract epic number from filename', {
+            filename,
+            suggestion: 'Epic filename should contain "epic-N" where N is the epic number',
+        });
+    }
+    /**
+     * Parse stories from epic content
+     *
+     * Extracts story information using multiple pattern matching strategies.
+     * Returns stories sorted by their position in the document (natural order).
+     *
+     * Supported patterns:
+     * - `### Story 1.1: Initialize Project` (full prefix with colon)
+     * - `### Story 1.1 - Initialize Project` (full prefix with dash)
+     * - `### 1.1: Initialize Project` (number only with colon)
+     * - `### 1.1. Initialize Project` (number with period)
+     *
+     * @param epicContent - Full epic markdown content
+     * @param epicPath - Path to epic file (for error messages and epic number extraction)
+     * @returns Array of Story objects sorted by document position
+     * @throws {ParserError} When no Stories section is found or no stories are extracted
+     * @example
+     * ```typescript
+     * const stories = parser.parseStories(epicContent, 'docs/epics/epic-1-foundation.md')
+     * console.log(`Found ${stories.length} stories`)
+     * ```
+     */
+    parseStories(epicContent, epicPath) {
+        this.logger.info({ epicPath }, 'Parsing stories from epic');
+        // Check if epic has a Stories section
+        if (!this.hasStoriesSection(epicContent)) {
+            this.logger.error({ epicPath }, 'No Stories section found in epic');
+            throw new ParserError('Epic file does not contain a Stories section. Expected section like: ## Stories', {
+                filePath: epicPath,
+                suggestion: 'Ensure epic has a stories section with headers like: ### Story 1.1: Title',
+            });
+        }
+        // Extract epic number from filename
+        const epicNumber = this.parseEpicNumber(epicPath);
+        this.logger.debug({ epicNumber, epicPath }, 'Extracted epic number from filename');
+        // Split content into lines for position tracking
+        const lines = epicContent.split('\n');
+        // Try each pattern and collect all matches
+        const allMatches = [];
+        for (const pattern of this.patterns) {
+            const matches = this.matchPattern(pattern, lines, epicContent, epicNumber);
+            allMatches.push(...matches);
+            if (matches.length > 0) {
+                this.logger.debug({ matches: matches.length, patternName: pattern.name }, 'Pattern matched stories');
+            }
+        }
+        // Check if any stories were found
+        if (allMatches.length === 0) {
+            this.logger.error({ epicPath }, 'No stories found in epic');
+            throw new ParserError('No stories found in epic. Expected format: `### Story 1.1: Title` or similar', {
+                filePath: epicPath,
+                suggestion: 'Ensure epic has story headers like: ### Story 1.1: Initialize Project',
+            });
+        }
+        // Sort by position (natural document order)
+        allMatches.sort((a, b) => a.position - b.position);
+        // Convert to Story interface and deduplicate by position
+        const stories = this.deduplicateMatches(allMatches);
+        this.logger.info({ epicPath, storyCount: stories.length }, 'Successfully parsed stories from epic');
+        return stories;
+    }
+    /**
+     * Deduplicate matches that appear at the same position
+     *
+     * When multiple patterns match the same line, keep only the first match.
+     *
+     * @param matches - Array of story matches
+     * @returns Deduplicated array of Story objects
+     */
+    deduplicateMatches(matches) {
+        const seenPositions = new Set();
+        const stories = [];
+        for (const match of matches) {
+            // Skip if we've already seen this position
+            if (seenPositions.has(match.position)) {
+                this.logger.debug({
+                    fullNumber: match.fullNumber,
+                    line: match.position + 1,
+                    patternName: match.patternName,
+                }, 'Skipping duplicate match at same position');
+                continue;
+            }
+            seenPositions.add(match.position);
+            stories.push({
+                epicNumber: match.epicNumber,
+                fullNumber: match.fullNumber,
+                number: match.number,
+                title: match.title,
+            });
+            this.logger.debug({
+                fullNumber: match.fullNumber,
+                line: match.position + 1,
+                patternName: match.patternName,
+                title: match.title,
+            }, 'Story matched successfully');
+        }
+        return stories;
+    }
+    /**
+     * Find the line number where a match appears
+     *
+     * @param lines - Array of lines from the document
+     * @param matchText - Text to find
+     * @returns Line number (0-indexed)
+     */
+    findLineNumber(lines, matchText) {
+        for (const [i, line] of lines.entries()) {
+            if (line.includes(matchText.trim())) {
+                return i;
+            }
+        }
+        return 0; // Fallback to start of document
+    }
+    /**
+     * Check if epic content has a Stories section
+     *
+     * @param content - Epic markdown content
+     * @returns True if Stories section exists
+     */
+    hasStoriesSection(content) {
+        // Look for Stories section header (## Stories or similar)
+        const storiesSectionPattern = /^##\s+Stories?\s*$/im;
+        return storiesSectionPattern.test(content);
+    }
+    /**
+     * Match a single pattern against epic content
+     *
+     * @param pattern - Pattern configuration with name and regex
+     * @param pattern.name - Pattern name
+     * @param pattern.regex - Pattern regular expression
+     * @param lines - Epic content split into lines
+     * @param content - Full epic content
+     * @param epicNumber - Epic number from filename
+     * @returns Array of matches for this pattern
+     */
+    matchPattern(pattern, lines, content, epicNumber) {
+        const matches = [];
+        const regex = new RegExp(pattern.regex.source, pattern.regex.flags);
+        let match;
+        // Reset regex state
+        regex.lastIndex = 0;
+        // Execute regex and collect all matches
+        while ((match = regex.exec(content)) !== null) {
+            // Extract epic number and story number from groups
+            // Groups are: [fullMatch, epicNum, storyNum, title]
+            const matchedEpicNum = Number.parseInt(match[1], 10);
+            const storyNum = Number.parseInt(match[2], 10);
+            const storyTitle = match[3].trim();
+            const fullMatch = match[0];
+            // Verify epic number matches (warn if different)
+            if (matchedEpicNum !== epicNumber) {
+                this.logger.warn({
+                    expected: epicNumber,
+                    found: matchedEpicNum,
+                    storyTitle,
+                }, 'Story epic number does not match filename epic number');
+            }
+            // Find line number of this match
+            const position = this.findLineNumber(lines, fullMatch);
+            matches.push({
+                epicNumber: matchedEpicNum,
+                fullNumber: `${matchedEpicNum}.${storyNum}`,
+                number: storyNum,
+                patternName: pattern.name,
+                position,
+                title: storyTitle,
+            });
+        }
+        return matches;
+    }
+}

package/dist/services/parsers/prd-fixer.d.ts

@@ -0,0 +1,86 @@
+/**
+ * PRD Fixer Service
+ *
+ * Uses AI to automatically reformat PRD documents that don't match
+ * the expected epic/story format. This allows the workflow to handle
+ * PRDs written in various formats by normalizing them before parsing.
+ *
+ * @example
+ * ```typescript
+ * const fixer = new PrdFixer(agentRunner, fileManager, logger)
+ * const result = await fixer.fixPrd('docs/PRD.md', content, ['docs/arch.md'])
+ * if (result.fixed) {
+ *   // PRD was reformatted and saved
+ * }
+ * ```
+ */
+import type pino from 'pino';
+import type { AIProviderRunner } from '../agents/agent-runner.js';
+import { FileManager } from '../file-system/file-manager.js';
+/**
+ * Result of a PRD fix attempt
+ */
+export interface PrdFixResult {
+    /**
+     * The content after fixing (or original if not fixed)
+     */
+    content: string;
+    /**
+     * Error message if fixing failed
+     */
+    error?: string;
+    /**
+     * Whether the PRD was successfully fixed
+     */
+    fixed: boolean;
+}
+/**
+ * PRD Fixer Service
+ *
+ * Automatically reformats PRD documents to match expected epic/story patterns
+ * using AI. Creates a backup before modifying the original file.
+ */
+export declare class PrdFixer {
+    private readonly agentRunner;
+    private readonly fileManager;
+    private readonly logger;
+    /**
+     * Create a new PrdFixer instance
+     *
+     * @param agentRunner - AI provider runner for executing fix prompts
+     * @param fileManager - File manager for reading/writing files
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(agentRunner: AIProviderRunner, fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Fix a PRD document to match expected format
+     *
+     * Uses AI to analyze and reformat the PRD content to match the expected
+     * epic/story structure. Creates a backup of the original file before
+     * overwriting with the fixed content.
+     *
+     * @param prdPath - Path to the PRD file
+     * @param originalContent - Original PRD content that failed parsing
+     * @param references - Optional reference files for context (e.g., architecture docs)
+     * @returns PrdFixResult with fixed status, content, and any errors
+     */
+    fixPrd(prdPath: string, originalContent: string, references?: string[]): Promise<PrdFixResult>;
+    /**
+     * Build the prompt for fixing the PRD
+     *
+     * @param prdPath - Path to the PRD file
+     * @param content - Original PRD content
+     * @param references - Optional reference files
+     * @returns Complete prompt string for the AI agent
+     */
+    private buildFixPrompt;
+    /**
+     * Extract the fixed PRD content from the AI response
+     *
+     * Looks for content wrapped in markdown code blocks and extracts it.
+     *
+     * @param output - Raw AI response output
+     * @returns Extracted PRD content or null if not found
+     */
+    private extractFixedContent;
+}

package/dist/services/parsers/prd-fixer.js

@@ -0,0 +1,194 @@
+/**
+ * PRD Fixer Service
+ *
+ * Uses AI to automatically reformat PRD documents that don't match
+ * the expected epic/story format. This allows the workflow to handle
+ * PRDs written in various formats by normalizing them before parsing.
+ *
+ * @example
+ * ```typescript
+ * const fixer = new PrdFixer(agentRunner, fileManager, logger)
+ * const result = await fixer.fixPrd('docs/PRD.md', content, ['docs/arch.md'])
+ * if (result.fixed) {
+ *   // PRD was reformatted and saved
+ * }
+ * ```
+ */
+/**
+ * PRD Fixer Service
+ *
+ * Automatically reformats PRD documents to match expected epic/story patterns
+ * using AI. Creates a backup before modifying the original file.
+ */
+export class PrdFixer {
+    agentRunner;
+    fileManager;
+    logger;
+    /**
+     * Create a new PrdFixer instance
+     *
+     * @param agentRunner - AI provider runner for executing fix prompts
+     * @param fileManager - File manager for reading/writing files
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(agentRunner, fileManager, logger) {
+        this.agentRunner = agentRunner;
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Fix a PRD document to match expected format
+     *
+     * Uses AI to analyze and reformat the PRD content to match the expected
+     * epic/story structure. Creates a backup of the original file before
+     * overwriting with the fixed content.
+     *
+     * @param prdPath - Path to the PRD file
+     * @param originalContent - Original PRD content that failed parsing
+     * @param references - Optional reference files for context (e.g., architecture docs)
+     * @returns PrdFixResult with fixed status, content, and any errors
+     */
+    async fixPrd(prdPath, originalContent, references) {
+        this.logger.info({ prdPath, references: references?.length ?? 0 }, 'Attempting to auto-fix PRD format');
+        try {
+            // Build the prompt for fixing the PRD
+            const prompt = this.buildFixPrompt(prdPath, originalContent, references);
+            // Execute the AI agent to fix the PRD
+            const result = await this.agentRunner.runAgent(prompt, {
+                agentType: 'prd-fixer',
+                timeout: 300_000, // 5 minutes should be enough for reformatting
+            });
+            if (!result.success) {
+                this.logger.error({ errors: result.errors, prdPath }, 'AI agent failed to fix PRD');
+                return {
+                    content: originalContent,
+                    error: `AI agent failed: ${result.errors}`,
+                    fixed: false,
+                };
+            }
+            // Extract the fixed content from the AI response
+            const fixedContent = this.extractFixedContent(result.output);
+            if (!fixedContent) {
+                this.logger.error({ prdPath }, 'Could not extract fixed content from AI response');
+                return {
+                    content: originalContent,
+                    error: 'Could not extract fixed PRD content from AI response',
+                    fixed: false,
+                };
+            }
+            // Create backup of original file
+            const backupPath = `${prdPath}.bak`;
+            await this.fileManager.writeFile(backupPath, originalContent);
+            this.logger.info({ backupPath }, 'Created backup of original PRD');
+            // Write the fixed content to the original path
+            await this.fileManager.writeFile(prdPath, fixedContent);
+            this.logger.info({ prdPath }, 'Wrote fixed PRD content');
+            return {
+                content: fixedContent,
+                fixed: true,
+            };
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ error: err.message, prdPath }, 'Failed to fix PRD');
+            return {
+                content: originalContent,
+                error: err.message,
+                fixed: false,
+            };
+        }
+    }
+    /**
+     * Build the prompt for fixing the PRD
+     *
+     * @param prdPath - Path to the PRD file
+     * @param content - Original PRD content
+     * @param references - Optional reference files
+     * @returns Complete prompt string for the AI agent
+     */
+    buildFixPrompt(prdPath, content, references) {
+        // Build reference context if provided
+        let referenceContext = '';
+        if (references && references.length > 0) {
+            referenceContext = `
+
+REFERENCE FILES FOR CONTEXT:
+${references.map((ref) => `- ${ref}`).join('\n')}
+
+Read these reference files to understand the project context and patterns.`;
+        }
+        return `You are a PRD formatting expert. Your task is to reformat a Product Requirements Document (PRD) to match the expected structure for automated workflow processing.
+
+TASK: Reformat the PRD file at "${prdPath}" to use the correct epic and story format.
+
+EXPECTED FORMAT:
+1. Epic headers MUST use this exact format: ## Epic N: Title
+   - Examples: "## Epic 1: Foundation & Setup", "## Epic 2: Core Features"
+   - The "Epic" keyword is REQUIRED
+   - The number MUST be sequential (1, 2, 3...)
+   - A colon separates the number from the title
+
+2. Story sections within epics should use:
+   - ### Stories (as a section header)
+   - Bullet points: - Story N.M: Description
+   - Example: "- Story 1.1: Initialize project structure"
+
+3. Each epic should have:
+   - A description paragraph after the header
+   - A ### Goals section with bullet points
+   - A ### Stories section with story bullet points
+
+CURRENT PRD CONTENT:
+\`\`\`markdown
+${content}
+\`\`\`
+${referenceContext}
+
+INSTRUCTIONS:
+1. Analyze the current PRD structure
+2. Identify all epics/features/phases (they might be labeled differently)
+3. Reformat them to use "## Epic N: Title" format
+4. Ensure stories are properly formatted under each epic
+5. Preserve ALL original content and meaning - only change the formatting
+6. Number epics sequentially starting from 1
+7. Number stories as N.M where N is the epic number and M is the story number within that epic
+
+OUTPUT FORMAT:
+Output ONLY the reformatted PRD content wrapped in a markdown code block.
+Do not include any explanation before or after the code block.
+The output must be a complete, valid markdown document.
+
+\`\`\`markdown
+[Your reformatted PRD here]
+\`\`\``;
+    }
+    /**
+     * Extract the fixed PRD content from the AI response
+     *
+     * Looks for content wrapped in markdown code blocks and extracts it.
+     *
+     * @param output - Raw AI response output
+     * @returns Extracted PRD content or null if not found
+     */
+    extractFixedContent(output) {
+        // Try to extract content from markdown code block
+        const codeBlockMatch = output.match(/```(?:markdown)?\s*\n([\s\S]*?)\n```/);
+        if (codeBlockMatch && codeBlockMatch[1]) {
+            const extracted = codeBlockMatch[1].trim();
+            // Validate it looks like a PRD (has at least one epic header)
+            if (/##\s+Epic\s+\d+/i.test(extracted)) {
+                return extracted;
+            }
+        }
+        // Fallback: if the output itself looks like a valid PRD
+        if (/##\s+Epic\s+\d+/i.test(output)) {
+            // Strip any leading/trailing explanation text
+            const lines = output.split('\n');
+            const prdStart = lines.findIndex((line) => line.startsWith('#'));
+            if (prdStart !== -1) {
+                return lines.slice(prdStart).join('\n').trim();
+            }
+        }
+        return null;
+    }
+}