claude-autopm 2.3.0 → 2.5.0

package/lib/services/EpicService.js

@@ -40,26 +40,28 @@ class EpicService {
    * Create a new EpicService instance
    *
    * @param {Object} options - Configuration options
-   * @param {PRDService} options.prdService - PRDService instance for parsing
+   * @param {PRDService} options.prdService - PRDService instance for parsing (optional for CLI operations)
    * @param {ConfigManager} [options.configManager] - Optional ConfigManager instance
    * @param {Object} [options.provider] - Optional AI provider instance for streaming
+   * @param {string} [options.epicsDir] - Path to epics directory (default: .claude/epics)
+   * @param {string} [options.defaultStatus] - Default epic status (default: backlog)
    */
   constructor(options = {}) {
-    if (!options.prdService) {
-      throw new Error('PRDService instance is required');
-    }
-
-    if (!(options.prdService instanceof PRDService)) {
-      throw new Error('prdService must be an instance of PRDService');
-    }
-
-    this.prdService = options.prdService;
+    // PRDService is optional now - only required for PRD parsing operations
+    this.prdService = options.prdService || null;
 
     // Store ConfigManager if provided (for future use)
     this.configManager = options.configManager || undefined;
 
     // Store provider if provided (for streaming operations)
     this.provider = options.provider || undefined;
+
+    // CLI operation options
+    this.options = {
+      epicsDir: options.epicsDir || '.claude/epics',
+      defaultStatus: options.defaultStatus || 'backlog',
+      ...options
+    };
   }
 
   // ==========================================
@@ -312,6 +314,10 @@ class EpicService {
    * // }
    */
   analyzePRD(prdContent) {
+    if (!this.prdService) {
+      throw new Error('PRDService instance is required for PRD analysis operations');
+    }
+
     const frontmatter = this.prdService.parseFrontmatter(prdContent);
     const sections = this.prdService.extractPrdContent(prdContent);
 
@@ -321,6 +327,59 @@ class EpicService {
     };
   }
 
+  /**
+   * Parse YAML frontmatter from markdown content
+   *
+   * Extracts key-value pairs from YAML frontmatter block.
+   * Returns null if frontmatter is missing or malformed.
+   *
+   * @param {string} content - Markdown content with frontmatter
+   * @returns {Object|null} Parsed frontmatter object or null
+   */
+  parseFrontmatter(content) {
+    if (!content || typeof content !== 'string') {
+      return null;
+    }
+
+    // Match frontmatter block: ---\n...\n--- or ---\n---
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/) ||
+                             content.match(/^---\n---/);
+
+    if (!frontmatterMatch) {
+      return null;
+    }
+
+    // Empty frontmatter (---\n---)
+    if (!frontmatterMatch[1] && content.startsWith('---\n---')) {
+      return {};
+    }
+
+    const frontmatter = {};
+    const lines = (frontmatterMatch[1] || '').split('\n');
+
+    for (const line of lines) {
+      // Skip empty lines
+      if (!line.trim()) {
+        continue;
+      }
+
+      // Find first colon to split key and value
+      const colonIndex = line.indexOf(':');
+      if (colonIndex === -1) {
+        continue; // Skip lines without colons
+      }
+
+      const key = line.substring(0, colonIndex).trim();
+      const value = line.substring(colonIndex + 1).trim();
+
+      if (key) {
+        frontmatter[key] = value;
+      }
+    }
+
+    return frontmatter;
+  }
+
   /**
    * Determine dependencies between features
    *
@@ -604,6 +663,221 @@ ${prdContent}`;
       yield chunk;
     }
   }
+
+  // ==========================================
+  // 6. CLI OPERATIONS (I/O Methods)
+  // ==========================================
+
+  /**
+   * List all epics with metadata
+   *
+   * @returns {Promise<Array<Object>>} Array of epic objects
+   */
+  async listEpics() {
+    const fs = require('fs-extra');
+    const path = require('path');
+
+    const epicsDir = path.join(process.cwd(), this.options.epicsDir);
+
+    // Check if epics directory exists
+    const dirExists = await fs.pathExists(epicsDir);
+    if (!dirExists) {
+      return [];
+    }
+
+    // Read all epic directories
+    let epicDirs;
+    try {
+      const items = await fs.readdir(epicsDir, { withFileTypes: true });
+      epicDirs = items
+        .filter(dirent => dirent.isDirectory())
+        .map(dirent => dirent.name);
+    } catch (error) {
+      return [];
+    }
+
+    const epics = [];
+
+    for (const epicDir of epicDirs) {
+      const epicPath = path.join(epicsDir, epicDir);
+      const epicFilePath = path.join(epicPath, 'epic.md');
+
+      // Skip directories without epic.md file
+      const fileExists = await fs.pathExists(epicFilePath);
+      if (!fileExists) {
+        continue;
+      }
+
+      let metadata;
+      try {
+        const content = await fs.readFile(epicFilePath, 'utf8');
+        metadata = this.parseFrontmatter(content);
+      } catch (error) {
+        // Skip files that can't be read
+        continue;
+      }
+
+      // Apply defaults
+      const name = (metadata && metadata.name) || epicDir;
+      const status = (metadata && metadata.status) || this.options.defaultStatus;
+      const progress = (metadata && metadata.progress) || '0%';
+      const github = (metadata && metadata.github) || '';
+      const created = (metadata && metadata.created) || '';
+
+      // Count tasks
+      const taskCount = await this.countTasks(epicPath);
+
+      // Extract GitHub issue number
+      const githubIssue = this.extractGitHubIssue(github);
+
+      epics.push({
+        name,
+        status,
+        progress,
+        github,
+        githubIssue,
+        created,
+        taskCount,
+        epicDir,
+        epicPath: path.join(epicPath, 'epic.md')
+      });
+    }
+
+    return epics;
+  }
+
+  /**
+   * Get detailed epic information
+   *
+   * @param {string} epicName - Epic directory name
+   * @returns {Promise<Object>} Epic data with metadata and task count
+   * @throws {Error} If epic not found
+   */
+  async getEpic(epicName) {
+    const fs = require('fs-extra');
+
+    const epicPath = this.getEpicPath(epicName);
+    const epicFilePath = this.getEpicFilePath(epicName);
+
+    // Check if epic exists
+    const exists = await fs.pathExists(epicFilePath);
+    if (!exists) {
+      throw new Error(`Epic not found: ${epicName}`);
+    }
+
+    // Read epic content
+    const content = await fs.readFile(epicFilePath, 'utf8');
+    const metadata = this.parseFrontmatter(content);
+
+    // Apply defaults
+    const name = (metadata && metadata.name) || epicName;
+    const status = (metadata && metadata.status) || this.options.defaultStatus;
+    const progress = (metadata && metadata.progress) || '0%';
+    const github = (metadata && metadata.github) || '';
+    const created = (metadata && metadata.created) || '';
+
+    // Count tasks
+    const taskCount = await this.countTasks(epicPath);
+
+    // Extract GitHub issue
+    const githubIssue = this.extractGitHubIssue(github);
+
+    return {
+      name,
+      status,
+      progress,
+      github,
+      githubIssue,
+      created,
+      taskCount,
+      epicDir: epicName,
+      epicPath: epicFilePath,
+      content
+    };
+  }
+
+  /**
+   * Validate epic structure and completeness
+   *
+   * @param {string} epicName - Epic directory name
+   * @returns {Promise<Object>} Validation result: { valid: boolean, issues: string[] }
+   * @throws {Error} If epic not found
+   */
+  async validateEpicStructure(epicName) {
+    const fs = require('fs-extra');
+
+    const epicFilePath = this.getEpicFilePath(epicName);
+
+    // Check if epic exists
+    const exists = await fs.pathExists(epicFilePath);
+    if (!exists) {
+      throw new Error(`Epic not found: ${epicName}`);
+    }
+
+    const issues = [];
+
+    // Read epic content
+    const content = await fs.readFile(epicFilePath, 'utf8');
+
+    // Check for frontmatter
+    const frontmatter = this.parseFrontmatter(content);
+    if (!frontmatter) {
+      issues.push('Missing frontmatter');
+    } else {
+      // Check for required fields
+      if (!frontmatter.name) {
+        issues.push('Missing name in frontmatter');
+      }
+      if (!frontmatter.status) {
+        issues.push('Missing status in frontmatter');
+      }
+    }
+
+    return {
+      valid: issues.length === 0,
+      issues
+    };
+  }
+
+  /**
+   * Count task files in epic directory
+   *
+   * @param {string} epicPath - Path to epic directory
+   * @returns {Promise<number>} Number of task files
+   */
+  async countTasks(epicPath) {
+    const fs = require('fs-extra');
+
+    try {
+      const files = await fs.readdir(epicPath);
+      // Count files that match pattern [0-9]*.md
+      return files.filter(file => /^\d+\.md$/.test(file)).length;
+    } catch (error) {
+      return 0;
+    }
+  }
+
+  /**
+   * Get full path to epic directory
+   *
+   * @param {string} epicName - Epic directory name
+   * @returns {string} Full path to epic directory
+   */
+  getEpicPath(epicName) {
+    const path = require('path');
+    return path.join(process.cwd(), this.options.epicsDir, epicName);
+  }
+
+  /**
+   * Get full path to epic.md file
+   *
+   * @param {string} epicName - Epic directory name
+   * @returns {string} Full path to epic.md file
+   */
+  getEpicFilePath(epicName) {
+    const path = require('path');
+    return path.join(this.getEpicPath(epicName), 'epic.md');
+  }
 }
 
 module.exports = EpicService;