@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/parsers/standalone-story-parser.js

@@ -0,0 +1,255 @@
+/**
+ * StandaloneStoryParser Service
+ *
+ * Parses standalone story files that don't follow the epic.story numbering pattern.
+ * Supports stories like JIRA tickets, bug fixes, and ad-hoc tasks.
+ *
+ * Examples:
+ * - JIRA-SIGN-10.md
+ * - bugfix-auth-timeout.md
+ * - feature-dark-mode.md
+ */
+import { basename } from 'node:path';
+import { ParserError } from '../../utils/errors.js';
+/**
+ * StandaloneStoryParser service for parsing non-epic stories
+ *
+ * Provides methods to parse standalone story files that don't follow
+ * the epic.story numbering convention. Uses filename as unique ID and
+ * optionally extracts category/prefix.
+ */
+export class StandaloneStoryParser {
+    /**
+     * FileManager instance for file operations
+     */
+    fileManager;
+    /**
+     * Logger instance for parsing operations
+     */
+    logger;
+    /**
+     * Create a new StandaloneStoryParser instance
+     *
+     * @param fileManager - FileManager service for file operations
+     * @param logger - Pino logger instance for logging parsing operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:parsers:standalone-story' })
+     * const fileManager = new FileManager(logger)
+     * const parser = new StandaloneStoryParser(fileManager, logger)
+     */
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Parse standalone story metadata from a story file
+     *
+     * Extracts ID from filename, optional category/prefix, title from H1 header,
+     * and status from either inline or section-based format. Does not require
+     * epic.story numbering pattern.
+     *
+     * @param storyPath - Path to the story markdown file
+     * @returns Standalone story metadata with ID, title, status, and optional category
+     * @throws If file cannot be read
+     * @throws {ParserError} If story structure is invalid (missing title, missing status)
+     * @example
+     * const metadata = await parser.parseStoryMetadata('docs/stories/JIRA-SIGN-10.md')
+     * console.log(metadata.id) // "JIRA-SIGN-10"
+     * console.log(metadata.category) // "JIRA-SIGN"
+     * console.log(metadata.type) // "standalone"
+     */
+    async parseStoryMetadata(storyPath) {
+        this.logger.info('Parsing standalone story metadata from: %s', storyPath);
+        // Read story file content
+        const content = await this.fileManager.readFile(storyPath);
+        // Extract ID and optional category from filename
+        const { category, id } = this.extractIdAndCategory(storyPath);
+        // Extract title from H1 header
+        const title = this.extractTitle(content, storyPath);
+        // Extract status using multiple pattern strategies
+        const status = this.extractStatus(content, storyPath);
+        this.logger.info('Successfully parsed standalone story metadata: %s (Category: %s, Status: %s)', id, category || 'none', status);
+        return {
+            category,
+            filePath: storyPath,
+            id,
+            status,
+            title,
+            type: 'standalone',
+        };
+    }
+    /**
+     * Update story status in a standalone story file
+     *
+     * Reads the story file, detects the current status format (inline or section-based),
+     * and updates the status value while preserving the original format.
+     *
+     * @param storyPath - Path to the story markdown file
+     * @param newStatus - New status value to set
+     * @throws If file cannot be read or written
+     * @throws {ParserError} If status format cannot be detected
+     * @example
+     * await parser.updateStoryStatus('docs/stories/JIRA-SIGN-10.md', 'Done')
+     */
+    async updateStoryStatus(storyPath, newStatus) {
+        this.logger.info('Updating standalone story status in %s to: %s', storyPath, newStatus);
+        // Read current story file content
+        const content = await this.fileManager.readFile(storyPath);
+        // Detect current status and format
+        const { format, oldStatus } = this.detectStatusFormat(content, storyPath);
+        // Update status based on detected format
+        let updatedContent;
+        if (format === 'inline') {
+            updatedContent = content.replace(/\*\*Status\*\*:\s*\w+/, `**Status**: ${newStatus}`);
+        }
+        else if (format === 'section-bold') {
+            updatedContent = content.replace(/^## Status\s*\n+\s*\*\*\w+\*\*/m, `## Status\n\n**${newStatus}**`);
+        }
+        else {
+            updatedContent = content.replace(/^## Status\s*\n+\s*\w+/m, `## Status\n\n${newStatus}`);
+        }
+        // Write updated content back to file
+        await this.fileManager.writeFile(storyPath, updatedContent);
+        this.logger.info('Standalone story status updated successfully: %s → %s (format: %s)', oldStatus, newStatus, format);
+    }
+    /**
+     * Detect status format (inline vs section-based) and extract current status
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Object with format type and old status value
+     * @throws {ParserError} If status format cannot be detected
+     */
+    detectStatusFormat(content, storyPath) {
+        // Check for inline format: **Status**: Draft
+        const inlineMatch = /\*\*Status\*\*:\s*(\w+)/.exec(content);
+        if (inlineMatch) {
+            return { format: 'inline', oldStatus: inlineMatch[1].trim() };
+        }
+        // Check for section with bold: ## Status\n\n**Draft**
+        const boldSectionMatch = /^## Status\s*\n+\s*\*\*(\w+)\*\*/m.exec(content);
+        if (boldSectionMatch) {
+            return { format: 'section-bold', oldStatus: boldSectionMatch[1].trim() };
+        }
+        // Check for section plain: ## Status\n\nDraft or ## Status\nDraft
+        const plainSectionMatch = /^## Status\s*\n+\s*(?!\*\*)(\w+)/m.exec(content);
+        if (plainSectionMatch) {
+            return { format: 'section', oldStatus: plainSectionMatch[1].trim() };
+        }
+        // Status format not detected
+        this.logger.error('Unable to detect status format in: %s', storyPath);
+        throw new ParserError('Unable to detect status format', {
+            filePath: storyPath,
+            suggestion: 'Ensure story has valid Status section in one of the supported formats',
+        });
+    }
+    /**
+     * Extract unique ID and optional category from filename
+     *
+     * Parses filename to create a unique ID (filename without extension)
+     * and optionally extracts category prefix. Supports patterns like:
+     * - JIRA-SIGN-10.md → id: "JIRA-SIGN-10", category: "JIRA-SIGN"
+     * - bugfix-auth.md → id: "bugfix-auth", category: "bugfix"
+     * - simple-task.md → id: "simple-task", category: undefined
+     *
+     * @param storyPath - Path to the story file
+     * @returns Object with id and optional category
+     */
+    extractIdAndCategory(storyPath) {
+        const filename = basename(storyPath, '.md');
+        // Try to extract category from common patterns:
+        // 1. PREFIX-NUMBER (e.g., JIRA-SIGN-10 → category: JIRA-SIGN)
+        // 2. PREFIX-TYPE-word (e.g., HTTP-TENANT-FIX → category: HTTP-TENANT)
+        // 3. word-word-... (e.g., bugfix-auth → category: bugfix)
+        // Pattern 1: PREFIX-PREFIX-NUMBER (e.g., JIRA-SIGN-10)
+        const prefixNumberMatch = /^([A-Z]+-[A-Z]+)-\d+$/.exec(filename);
+        if (prefixNumberMatch) {
+            this.logger.debug('Extracted category (prefix-number): %s', prefixNumberMatch[1]);
+            return { category: prefixNumberMatch[1], id: filename };
+        }
+        // Pattern 2: PREFIX-TYPE-word (e.g., HTTP-TENANT-FIX-2)
+        const multiPrefixMatch = /^([A-Z]+-[A-Z]+(?:-[A-Z]+)?)-/.exec(filename);
+        if (multiPrefixMatch) {
+            this.logger.debug('Extracted category (multi-prefix): %s', multiPrefixMatch[1]);
+            return { category: multiPrefixMatch[1], id: filename };
+        }
+        // Pattern 3: Known lowercase category prefixes (e.g., bugfix-auth, feature-dark-mode)
+        // Only match specific known categories to avoid false positives with generic names
+        const knownCategoryPrefixes = ['bugfix', 'bug', 'feature', 'hotfix', 'chore', 'refactor', 'docs', 'test', 'fix'];
+        const singlePrefixMatch = /^([a-z]+)-/.exec(filename);
+        if (singlePrefixMatch && knownCategoryPrefixes.includes(singlePrefixMatch[1])) {
+            this.logger.debug('Extracted category (known-prefix): %s', singlePrefixMatch[1]);
+            return { category: singlePrefixMatch[1], id: filename };
+        }
+        // No category detected
+        this.logger.debug('No category detected, using filename as ID: %s', filename);
+        return { id: filename };
+    }
+    /**
+     * Extract story status using multiple pattern strategies
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Extracted status value
+     * @throws {ParserError} If status cannot be found
+     */
+    extractStatus(content, storyPath) {
+        // Pattern 1: Inline format - **Status**: Draft
+        const inlineMatch = /\*\*Status\*\*:\s*(\w+)/.exec(content);
+        if (inlineMatch) {
+            const status = inlineMatch[1].trim();
+            this.logger.debug('Extracted status (inline format): %s', status);
+            return status;
+        }
+        // Pattern 2: Section with bold - ## Status\n\n**Draft**
+        const boldSectionMatch = /^## Status\s*\n+\s*\*\*(\w+)\*\*/m.exec(content);
+        if (boldSectionMatch) {
+            const status = boldSectionMatch[1].trim();
+            this.logger.debug('Extracted status (section bold format): %s', status);
+            return status;
+        }
+        // Pattern 3: Section plain - ## Status\n\nDraft
+        const plainSectionMatch = /^## Status\s*\n+\s*(?!\*\*)(\w+)/m.exec(content);
+        if (plainSectionMatch) {
+            const status = plainSectionMatch[1].trim();
+            this.logger.debug('Extracted status (section plain format): %s', status);
+            return status;
+        }
+        // Pattern 4: Fallback - any text after ## Status
+        const fallbackMatch = /^## Status\s*\n+\s*(.+?)(?:\n|$)/m.exec(content);
+        if (fallbackMatch) {
+            const rawStatus = fallbackMatch[1].replaceAll('**', '').replaceAll(/[_*]/g, '').replaceAll('---', '').trim();
+            if (rawStatus && /^\w+$/.test(rawStatus)) {
+                const status = rawStatus;
+                this.logger.debug('Extracted status (fallback format): %s', status);
+                return status;
+            }
+        }
+        // Status not found
+        this.logger.error('Story file missing Status section or field: %s', storyPath);
+        throw new ParserError('Story file missing Status section or field', {
+            filePath: storyPath,
+            suggestion: 'Ensure story has "## Status" section followed by status value',
+        });
+    }
+    /**
+     * Extract story title from H1 header
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Extracted title
+     * @throws {ParserError} If H1 header is not found
+     */
+    extractTitle(content, storyPath) {
+        const match = /^# (.+)$/m.exec(content);
+        if (!match) {
+            this.logger.error('Story file missing H1 title header: %s', storyPath);
+            throw new ParserError('Story file missing H1 title header', {
+                filePath: storyPath,
+            });
+        }
+        const title = match[1].trim();
+        this.logger.debug('Extracted title: %s', title);
+        return title;
+    }
+}

package/dist/services/parsers/story-parser-factory.d.ts

@@ -0,0 +1,81 @@
+/**
+ * StoryParserFactory
+ *
+ * Factory for creating appropriate story parser based on file naming pattern.
+ * Automatically detects whether a story follows epic.story numbering or is standalone.
+ */
+import type pino from 'pino';
+import type { StoryMetadata } from '../../models/story.js';
+import type { FileManager } from '../file-system/file-manager.js';
+/**
+ * Factory for creating story parsers
+ *
+ * Determines which parser to use based on filename pattern and provides
+ * a unified interface for parsing both epic-based and standalone stories.
+ */
+export declare class StoryParserFactory {
+    /**
+     * Cached parser instances
+     */
+    private epicParser?;
+    /**
+     * FileManager instance for file operations
+     */
+    private readonly fileManager;
+    /**
+     * Logger instance
+     */
+    private readonly logger;
+    private standaloneParser?;
+    /**
+     * Create a new StoryParserFactory
+     *
+     * @param fileManager - FileManager service
+     * @param logger - Pino logger instance
+     */
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Determine if a story file is epic-based
+     *
+     * Checks filename for epic.story numbering pattern (e.g., 2.3, 1.5).
+     * Returns true if pattern is found, false otherwise.
+     *
+     * @param storyPath - Path to story file
+     * @returns True if epic-based, false if standalone
+     * @example
+     * factory.isEpicBasedStory('BMAD-2.3-story.md') // true
+     * factory.isEpicBasedStory('JIRA-SIGN-10.md') // false
+     * factory.isEpicBasedStory('bugfix-auth.md') // false
+     */
+    isEpicBasedStory(storyPath: string): boolean;
+    /**
+     * Parse story metadata from any story file
+     *
+     * Automatically detects story type and uses appropriate parser.
+     * Returns unified StoryMetadata union type with discriminator.
+     *
+     * @param storyPath - Path to story markdown file
+     * @returns StoryMetadata (EpicStoryMetadata | StandaloneStoryMetadata)
+     * @example
+     * // Epic story
+     * const epic = await factory.parseStory('BMAD-2.3-story.md')
+     * if (epic.type === 'epic-based') {
+     *   console.log(epic.epicNumber, epic.storyNumber)
+     * }
+     *
+     * // Standalone story
+     * const standalone = await factory.parseStory('JIRA-SIGN-10.md')
+     * if (standalone.type === 'standalone') {
+     *   console.log(standalone.category)
+     * }
+     */
+    parseStory(storyPath: string): Promise<StoryMetadata>;
+    /**
+     * Get or create epic story parser instance
+     */
+    private getEpicParser;
+    /**
+     * Get or create standalone story parser instance
+     */
+    private getStandaloneParser;
+}

package/dist/services/parsers/story-parser-factory.js

@@ -0,0 +1,108 @@
+/**
+ * StoryParserFactory
+ *
+ * Factory for creating appropriate story parser based on file naming pattern.
+ * Automatically detects whether a story follows epic.story numbering or is standalone.
+ */
+import { basename } from 'node:path';
+import { StandaloneStoryParser } from './standalone-story-parser.js';
+import { StoryParser } from './story-parser.js';
+/**
+ * Factory for creating story parsers
+ *
+ * Determines which parser to use based on filename pattern and provides
+ * a unified interface for parsing both epic-based and standalone stories.
+ */
+export class StoryParserFactory {
+    /**
+     * Cached parser instances
+     */
+    epicParser;
+    /**
+     * FileManager instance for file operations
+     */
+    fileManager;
+    /**
+     * Logger instance
+     */
+    logger;
+    standaloneParser;
+    /**
+     * Create a new StoryParserFactory
+     *
+     * @param fileManager - FileManager service
+     * @param logger - Pino logger instance
+     */
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Determine if a story file is epic-based
+     *
+     * Checks filename for epic.story numbering pattern (e.g., 2.3, 1.5).
+     * Returns true if pattern is found, false otherwise.
+     *
+     * @param storyPath - Path to story file
+     * @returns True if epic-based, false if standalone
+     * @example
+     * factory.isEpicBasedStory('BMAD-2.3-story.md') // true
+     * factory.isEpicBasedStory('JIRA-SIGN-10.md') // false
+     * factory.isEpicBasedStory('bugfix-auth.md') // false
+     */
+    isEpicBasedStory(storyPath) {
+        const filename = basename(storyPath);
+        const hasEpicStoryPattern = /\d+\.\d+/.test(filename);
+        this.logger.debug('Checking if %s is epic-based: %s', filename, hasEpicStoryPattern ? 'yes' : 'no');
+        return hasEpicStoryPattern;
+    }
+    /**
+     * Parse story metadata from any story file
+     *
+     * Automatically detects story type and uses appropriate parser.
+     * Returns unified StoryMetadata union type with discriminator.
+     *
+     * @param storyPath - Path to story markdown file
+     * @returns StoryMetadata (EpicStoryMetadata | StandaloneStoryMetadata)
+     * @example
+     * // Epic story
+     * const epic = await factory.parseStory('BMAD-2.3-story.md')
+     * if (epic.type === 'epic-based') {
+     *   console.log(epic.epicNumber, epic.storyNumber)
+     * }
+     *
+     * // Standalone story
+     * const standalone = await factory.parseStory('JIRA-SIGN-10.md')
+     * if (standalone.type === 'standalone') {
+     *   console.log(standalone.category)
+     * }
+     */
+    async parseStory(storyPath) {
+        if (this.isEpicBasedStory(storyPath)) {
+            this.logger.debug('Detected epic-based story: %s', storyPath);
+            const parser = this.getEpicParser();
+            return parser.parseStoryMetadata(storyPath);
+        }
+        this.logger.debug('Detected standalone story: %s', storyPath);
+        const parser = this.getStandaloneParser();
+        return parser.parseStoryMetadata(storyPath);
+    }
+    /**
+     * Get or create epic story parser instance
+     */
+    getEpicParser() {
+        if (!this.epicParser) {
+            this.epicParser = new StoryParser(this.fileManager, this.logger);
+        }
+        return this.epicParser;
+    }
+    /**
+     * Get or create standalone story parser instance
+     */
+    getStandaloneParser() {
+        if (!this.standaloneParser) {
+            this.standaloneParser = new StandaloneStoryParser(this.fileManager, this.logger);
+        }
+        return this.standaloneParser;
+    }
+}

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

@@ -0,0 +1,122 @@
+/**
+ * StoryParser Service
+ *
+ * Extracts metadata from story files and provides utilities for updating story status.
+ * Supports multiple status formats (inline and section-based) with resilient parsing.
+ */
+import type pino from 'pino';
+import type { EpicStoryMetadata, StoryStatus } from '../../models/story.js';
+import type { FileManager } from '../file-system/file-manager.js';
+/**
+ * StoryParser service for extracting metadata from story files
+ *
+ * Provides methods to parse story files and extract key metadata including
+ * story number, title, and status. Supports resilient parsing with multiple
+ * status format patterns.
+ */
+export declare class StoryParser {
+    /**
+     * FileManager instance for file operations
+     */
+    private readonly fileManager;
+    /**
+     * Logger instance for parsing operations
+     */
+    private readonly logger;
+    /**
+     * Create a new StoryParser instance
+     *
+     * @param fileManager - FileManager service for file operations
+     * @param logger - Pino logger instance for logging parsing operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:parsers:story' })
+     * const fileManager = new FileManager(logger)
+     * const parser = new StoryParser(fileManager, logger)
+     */
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Parse epic-based story metadata from a story file
+     *
+     * Extracts story number from filename, title from H1 header, and status
+     * from either inline format (**Status**: Draft) or section-based format
+     * (## Status\n\nDraft). Validates story file structure and throws errors
+     * for malformed files.
+     *
+     * @param storyPath - Path to the story markdown file
+     * @returns Epic story metadata with number, title, status, and file path
+     * @throws If file cannot be read
+     * @throws {ParserError} If story structure is invalid (missing title, missing status, missing epic.story number)
+     * @example
+     * const metadata = await parser.parseStoryMetadata('docs/stories/BMAD-2.3-story.md')
+     * console.log(metadata.number) // "2.3"
+     * console.log(metadata.status) // "Draft"
+     * console.log(metadata.type) // "epic-based"
+     */
+    parseStoryMetadata(storyPath: string): Promise<EpicStoryMetadata>;
+    /**
+     * Update story status in a story file
+     *
+     * Reads the story file, detects the current status format (inline or section-based),
+     * and updates the status value while preserving the original format. This ensures
+     * that inline status remains inline and section-based status remains section-based.
+     *
+     * @param storyPath - Path to the story markdown file
+     * @param newStatus - New status value to set
+     * @throws If file cannot be read or written
+     * @throws {ParserError} If status format cannot be detected
+     * @example
+     * await parser.updateStoryStatus('docs/stories/BMAD-2.3-story.md', 'Ready')
+     */
+    updateStoryStatus(storyPath: string, newStatus: StoryStatus): Promise<void>;
+    /**
+     * Detect status format (inline vs section-based) and extract current status
+     *
+     * Used by updateStoryStatus to determine how to update the status value
+     * while preserving the original format.
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Object with format type and old status value
+     * @throws {ParserError} If status format cannot be detected
+     */
+    private detectStatusFormat;
+    /**
+     * Extract story status using multiple pattern strategies
+     *
+     * Tries multiple patterns to extract status (in order of specificity):
+     * 1. Inline format: **Status**: Draft
+     * 2. Section with bold: ## Status\n\n**Draft**
+     * 3. Section plain: ## Status\n\nDraft
+     * 4. Fallback: any word after Status header
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Extracted status value
+     * @throws {ParserError} If status cannot be found in any supported format
+     */
+    private extractStatus;
+    /**
+     * Extract story number from filename
+     *
+     * Parses filename to extract epic and story numbers. Supports patterns like:
+     * - BMAD-2.3-story.md → epicNumber: 2, storyNumber: 3
+     * - PREFIX-1.5-description.md → epicNumber: 1, storyNumber: 5
+     *
+     * @param storyPath - Path to the story file
+     * @returns Object with epicNumber, storyNumber, and full number string
+     * @throws {ParserError} If filename does not contain valid story number pattern
+     */
+    private extractStoryNumber;
+    /**
+     * Extract story title from H1 header
+     *
+     * Finds the first H1 header in the content and extracts the title.
+     * Removes the "Story X.Y:" prefix if present.
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Extracted title without "Story X.Y:" prefix
+     * @throws {ParserError} If H1 header is not found
+     */
+    private extractTitle;
+}