aios-core 2.1.0

package/.aios-core/development/scripts/story-index-generator.js

@@ -0,0 +1,337 @@
+/**
+ * Story Index Generator for AIOS Framework
+ *
+ * Scans docs/stories/ directory and generates comprehensive story index
+ * with metadata extraction, epic grouping, and markdown table formatting.
+ *
+ * @module story-index-generator
+ * @version 1.0.0
+ * @created 2025-01-16 (Story 6.1.2.6)
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Status emoji mapping
+ */
+const STATUS_EMOJI = {
+  'Draft': '📝',
+  'Approved': '✅',
+  'Ready for Dev': '🚀',
+  'In Progress': '⚙️',
+  'Ready for Review': '👀',
+  'Completed': '✅',
+  'On Hold': '⏸️',
+  'Cancelled': '❌',
+};
+
+/**
+ * Priority emoji mapping
+ */
+const PRIORITY_EMOJI = {
+  'Critical': '🔴',
+  'High': '🟠',
+  'Medium': '🟡',
+  'Low': '🟢',
+};
+
+/**
+ * Extracts metadata from story markdown file
+ *
+ * @param {string} filePath - Path to story file
+ * @returns {Promise<Object|null>} Story metadata or null if parsing fails
+ */
+async function extractStoryMetadata(filePath) {
+  try {
+    const content = await fs.readFile(filePath, 'utf8');
+    const lines = content.split('\n');
+
+    const metadata = {
+      filePath,
+      fileName: path.basename(filePath),
+    };
+
+    // Extract from YAML frontmatter or metadata section
+    let inYamlBlock = false;
+    let inMetadataSection = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+
+      // YAML frontmatter detection
+      if (line === '---' && i < 10) {
+        inYamlBlock = !inYamlBlock;
+        continue;
+      }
+
+      // Metadata section detection
+      if (line.startsWith('## Metadata') || line.startsWith('# Metadata')) {
+        inMetadataSection = true;
+        continue;
+      }
+
+      if (line.startsWith('## ') || line.startsWith('# ')) {
+        inMetadataSection = false;
+      }
+
+      if (inYamlBlock || inMetadataSection) {
+        // Extract key-value pairs
+        const match = line.match(/^[-*]?\s*\*?\*?([A-Za-z\s]+)\*?\*?:\s*(.+)$/);
+        if (match) {
+          const key = match[1].trim().toLowerCase().replace(/\s+/g, '_');
+          const value = match[2].trim().replace(/^`|`$/g, '');
+
+          // Map to standard fields
+          if (key === 'story_id' || key === 'id') metadata.storyId = value;
+          if (key === 'title') metadata.title = value;
+          if (key === 'epic') metadata.epic = value;
+          if (key === 'status') metadata.status = value;
+          if (key === 'priority') metadata.priority = value;
+          if (key === 'owner' || key === 'assigned_to') metadata.owner = value;
+          if (key === 'estimate' || key === 'effort') metadata.estimate = value;
+          if (key === 'created') metadata.created = value;
+          if (key === 'updated') metadata.updated = value;
+        }
+      }
+
+      // Stop after metadata section
+      if (i > 100) break;
+    }
+
+    // Extract title from first H1 if not in metadata
+    if (!metadata.title) {
+      const h1Match = content.match(/^#\s+(.+)$/m);
+      if (h1Match) {
+        metadata.title = h1Match[1].trim();
+      }
+    }
+
+    // Extract story ID from filename if not in metadata
+    if (!metadata.storyId) {
+      const idMatch = metadata.fileName.match(/story-?([\d.]+)/i);
+      if (idMatch) {
+        metadata.storyId = idMatch[1];
+      }
+    }
+
+    return metadata;
+  } catch (error) {
+    console.error(`Failed to extract metadata from ${filePath}:`, error.message);
+    return null;
+  }
+}
+
+/**
+ * Scans stories directory recursively
+ *
+ * @param {string} dirPath - Directory path to scan
+ * @param {Array} stories - Accumulated stories array
+ * @returns {Promise<Array>} Array of story metadata objects
+ */
+async function scanStoriesDirectory(dirPath, stories = []) {
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+
+      if (entry.isDirectory()) {
+        // Recursively scan subdirectories
+        await scanStoriesDirectory(fullPath, stories);
+      } else if (entry.isFile() && entry.name.match(/\.md$/i)) {
+        // Process markdown files
+        const metadata = await extractStoryMetadata(fullPath);
+        if (metadata && metadata.storyId) {
+          stories.push(metadata);
+        }
+      }
+    }
+
+    return stories;
+  } catch (error) {
+    console.error(`Failed to scan directory ${dirPath}:`, error.message);
+    return stories;
+  }
+}
+
+/**
+ * Groups stories by epic
+ *
+ * @param {Array} stories - Array of story metadata
+ * @returns {Object} Stories grouped by epic
+ */
+function groupStoriesByEpic(stories) {
+  const grouped = {};
+
+  stories.forEach(story => {
+    const epic = story.epic || 'Unassigned';
+    if (!grouped[epic]) {
+      grouped[epic] = [];
+    }
+    grouped[epic].push(story);
+  });
+
+  // Sort stories within each epic by story ID
+  Object.keys(grouped).forEach(epic => {
+    grouped[epic].sort((a, b) => {
+      const aId = a.storyId.split('.').map(Number);
+      const bId = b.storyId.split('.').map(Number);
+
+      for (let i = 0; i < Math.max(aId.length, bId.length); i++) {
+        const aNum = aId[i] || 0;
+        const bNum = bId[i] || 0;
+        if (aNum !== bNum) return aNum - bNum;
+      }
+      return 0;
+    });
+  });
+
+  return grouped;
+}
+
+/**
+ * Generates markdown table row for story
+ *
+ * @param {Object} story - Story metadata
+ * @param {string} baseDir - Base directory for relative paths
+ * @returns {string} Markdown table row
+ */
+function generateStoryRow(story, baseDir = 'docs/stories') {
+  const statusEmoji = STATUS_EMOJI[story.status] || '❓';
+  const priorityEmoji = story.priority ? PRIORITY_EMOJI[story.priority] : '';
+
+  // Create relative path for link
+  const relativePath = path.relative(baseDir, story.filePath).replace(/\\/g, '/');
+  const link = `[${story.title || story.fileName}](${relativePath})`;
+
+  return `| ${story.storyId} | ${link} | ${statusEmoji} ${story.status || 'Unknown'} | ${priorityEmoji} ${story.priority || 'N/A'} | ${story.owner || 'Unassigned'} | ${story.estimate || 'TBD'} |`;
+}
+
+/**
+ * Generates complete story index markdown
+ *
+ * @param {Array} stories - Array of story metadata
+ * @returns {string} Complete markdown content
+ */
+function generateIndexMarkdown(stories) {
+  const grouped = groupStoriesByEpic(stories);
+  const epics = Object.keys(grouped).sort();
+
+  let markdown = `# Story Index
+
+**Generated:** ${new Date().toISOString()}
+**Total Stories:** ${stories.length}
+**Epics:** ${epics.length}
+
+---
+
+## 📊 Summary by Status
+
+`;
+
+  // Status summary
+  const statusCounts = {};
+  stories.forEach(story => {
+    const status = story.status || 'Unknown';
+    statusCounts[status] = (statusCounts[status] || 0) + 1;
+  });
+
+  Object.entries(statusCounts)
+    .sort((a, b) => b[1] - a[1])
+    .forEach(([status, count]) => {
+      const emoji = STATUS_EMOJI[status] || '❓';
+      markdown += `- ${emoji} **${status}**: ${count}\n`;
+    });
+
+  markdown += '\n---\n\n## 📚 Stories by Epic\n\n';
+
+  // Stories grouped by epic
+  epics.forEach(epic => {
+    const epicStories = grouped[epic];
+    markdown += `### ${epic} (${epicStories.length} stories)\n\n`;
+    markdown += '| Story ID | Title | Status | Priority | Owner | Estimate |\n';
+    markdown += '|----------|-------|--------|----------|-------|----------|\n';
+
+    epicStories.forEach(story => {
+      markdown += generateStoryRow(story) + '\n';
+    });
+
+    markdown += '\n';
+  });
+
+  markdown += '---\n\n';
+  markdown += '## 🔍 Legend\n\n';
+  markdown += '### Status\n';
+  Object.entries(STATUS_EMOJI).forEach(([status, emoji]) => {
+    markdown += `- ${emoji} **${status}**\n`;
+  });
+  markdown += '\n### Priority\n';
+  Object.entries(PRIORITY_EMOJI).forEach(([priority, emoji]) => {
+    markdown += `- ${emoji} **${priority}**\n`;
+  });
+
+  markdown += '\n---\n\n';
+  markdown += '*Auto-generated by AIOS Story Index Generator (Story 6.1.2.6)*\n';
+  markdown += '*Update: Run `npm run stories:index` or `node .aios-core/scripts/story-index-generator.js docs/stories`*\n';
+
+  return markdown;
+}
+
+/**
+ * Generates story index file
+ *
+ * @param {string} storiesDir - Path to stories directory
+ * @param {string} outputPath - Path to output index file
+ * @returns {Promise<Object>} Generation results
+ */
+async function generateStoryIndex(storiesDir = 'docs/stories', outputPath = null) {
+  const output = outputPath || path.join(storiesDir, 'index.md');
+
+  console.log(`📚 Scanning stories in: ${storiesDir}`);
+
+  const stories = await scanStoriesDirectory(storiesDir);
+
+  console.log(`✅ Found ${stories.length} stories`);
+
+  const markdown = generateIndexMarkdown(stories);
+
+  await fs.writeFile(output, markdown, 'utf8');
+
+  console.log(`✅ Story index generated: ${output}`);
+
+  return {
+    totalStories: stories.length,
+    outputPath: output,
+    stories,
+  };
+}
+
+// CLI execution support
+if (require.main === module) {
+  const storiesDir = process.argv[2] || 'docs/stories';
+  const outputPath = process.argv[3] || null;
+
+  generateStoryIndex(storiesDir, outputPath)
+    .then(result => {
+      console.log('\n📊 Generation Complete!');
+      console.log(`Total Stories: ${result.totalStories}`);
+      console.log(`Output: ${result.outputPath}`);
+      process.exit(0);
+    })
+    .catch(error => {
+      console.error('❌ Generation failed:', error);
+      process.exit(1);
+    });
+}
+
+module.exports = {
+  generateStoryIndex,
+  extractStoryMetadata,
+  scanStoriesDirectory,
+  groupStoriesByEpic,
+  generateIndexMarkdown,
+  generateStoryRow,
+  STATUS_EMOJI,
+  PRIORITY_EMOJI,
+};

package/.aios-core/development/scripts/story-manager.js

@@ -0,0 +1,375 @@
+// File: common/utils/story-manager.js
+
+/**
+ * Story Manager - Handles story file operations and ClickUp synchronization
+ *
+ * This module provides utilities for:
+ * - Reading and parsing story .md files
+ * - Saving story files with automatic ClickUp sync
+ * - Managing story frontmatter and metadata
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('js-yaml');
+const { syncStoryToClickUp, detectChanges } = require('./story-update-hook');
+
+/**
+ * Resolves the ClickUp MCP tool
+ * Tries tool-resolver first (for tests), falls back to global references
+ */
+async function getClickUpTool() {
+  try {
+    // Try using tool-resolver (test environment or future production)
+    const { resolveTool } = require('../../infrastructure/scripts/tool-resolver');
+    return await resolveTool('clickup');
+  } catch (error) {
+    // Fall back to global references (current production pattern)
+    return {
+      createTask: global.mcp__clickup__create_task,
+      updateTask: global.mcp__clickup__update_task,
+      getTask: global.mcp__clickup__get_task,
+    };
+  }
+}
+
+/**
+ * Parses a story markdown file into structured data
+ *
+ * @param {string} storyFilePath - Absolute path to story .md file
+ * @returns {Promise<object>} Parsed story content
+ */
+async function parseStoryFile(storyFilePath) {
+  const fileContent = await fs.readFile(storyFilePath, 'utf-8');
+
+  // Extract frontmatter
+  const frontmatterMatch = fileContent.match(/^---\n([\s\S]*?)\n---/);
+  const frontmatter = frontmatterMatch ? yaml.load(frontmatterMatch[1]) : {};
+
+  // Extract full markdown (without frontmatter)
+  const fullMarkdown = frontmatterMatch
+    ? fileContent.substring(frontmatterMatch[0].length).trim()
+    : fileContent.trim();
+
+  // Parse story sections
+  const statusMatch = fileContent.match(/\*\*Status:\*\* (.+)/);
+  const status = statusMatch ? statusMatch[1] : 'Draft';
+
+  // Parse tasks (checkbox items)
+  const taskMatches = fileContent.matchAll(/^- \[([ x])\] (.+)$/gm);
+  const tasks = Array.from(taskMatches).map(match => ({
+    completed: match[1] === 'x',
+    text: match[2],
+  }));
+
+  // Extract File List section
+  const fileListMatch = fileContent.match(/### File List\n\n([\s\S]*?)(?=\n##|$)/);
+  const fileList = fileListMatch ? fileListMatch[1].trim().split('\n') : [];
+
+  // Extract Dev Notes section
+  const devNotesMatch = fileContent.match(/## Dev Notes\n\n([\s\S]*?)(?=\n##|$)/);
+  const devNotes = devNotesMatch ? devNotesMatch[1].trim() : '';
+
+  // Extract Acceptance Criteria section
+  const acMatch = fileContent.match(/## Acceptance Criteria\n\n([\s\S]*?)(?=\n##|$)/);
+  const acceptanceCriteria = acMatch ? acMatch[1].trim() : '';
+
+  return {
+    frontmatter,
+    fullMarkdown,
+    status,
+    tasks,
+    fileList,
+    devNotes,
+    acceptanceCriteria,
+  };
+}
+
+/**
+ * Saves a story file and triggers ClickUp synchronization
+ *
+ * @param {string} storyFilePath - Absolute path to story .md file
+ * @param {string} content - New story content
+ * @param {boolean} skipSync - Skip ClickUp sync (default: false)
+ * @returns {Promise<object>} Save and sync result
+ */
+async function saveStoryFile(storyFilePath, content, skipSync = false) {
+  try {
+    // Read previous version for change detection
+    let previousContentString = '';
+    try {
+      previousContentString = await fs.readFile(storyFilePath, 'utf-8');
+    } catch (error) {
+      // File might not exist yet (new story)
+      console.log('No previous version found - creating new story file');
+    }
+
+    // Write new content
+    await fs.writeFile(storyFilePath, content, 'utf-8');
+    console.log(`✅ Story file saved: ${path.basename(storyFilePath)}`);
+
+    // Skip sync if requested or no previous version
+    if (skipSync || !previousContentString) {
+      return { saved: true, synced: false, reason: skipSync ? 'skip_requested' : 'new_file' };
+    }
+
+    // Detect changes between previous and current content
+    const changes = detectChanges(previousContentString, content);
+
+    // Extract metadata from current content
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    const frontmatter = frontmatterMatch ? yaml.load(frontmatterMatch[1]) : {};
+
+    // Create storyFile object for sync
+    const storyFile = {
+      metadata: {
+        clickup_task_id: frontmatter?.clickup?.task_id,
+      },
+      content: content,
+    };
+
+    // Sync to ClickUp if there are changes
+    await syncStoryToClickUp(storyFile, changes);
+
+    const hasChanges = changes.status.changed ||
+                      changes.tasksCompleted.length > 0 ||
+                      changes.filesAdded.length > 0 ||
+                      changes.devNotesAdded ||
+                      changes.acceptanceCriteriaChanged;
+
+    if (hasChanges) {
+      console.log('✅ Story synced to ClickUp');
+      return { saved: true, synced: true, changes: Object.keys(changes).filter(k => changes[k] && changes[k] !== false).length };
+    } else {
+      console.log('ℹ️ No sync needed: no changes detected');
+      return { saved: true, synced: false, reason: 'no_changes' };
+    }
+
+  } catch (error) {
+    console.error(`Error saving story file: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Updates frontmatter in a story file
+ *
+ * @param {string} storyFilePath - Absolute path to story .md file
+ * @param {object} updates - Frontmatter fields to update
+ * @returns {Promise<object>} Updated frontmatter object
+ */
+async function updateFrontmatter(storyFilePath, updates) {
+  const fileContent = await fs.readFile(storyFilePath, 'utf-8');
+
+  // Extract existing frontmatter
+  const frontmatterMatch = fileContent.match(/^---\n([\s\S]*?)\n---/);
+  const existingFrontmatter = frontmatterMatch ? yaml.load(frontmatterMatch[1]) : {};
+
+  // Merge updates
+  const updatedFrontmatter = { ...existingFrontmatter, ...updates };
+
+  // Serialize back to YAML
+  const newFrontmatterYaml = yaml.dump(updatedFrontmatter);
+
+  // Replace frontmatter in file content
+  const contentWithoutFrontmatter = frontmatterMatch
+    ? fileContent.substring(frontmatterMatch[0].length)
+    : fileContent;
+
+  const newContent = `---\n${newFrontmatterYaml}---${contentWithoutFrontmatter}`;
+
+  // Save without triggering sync (to avoid recursion)
+  await saveStoryFile(storyFilePath, newContent, true);
+
+  // Return the updated frontmatter
+  return updatedFrontmatter;
+}
+
+/**
+ * Updates the last_sync timestamp in story frontmatter
+ *
+ * @param {string} storyFilePath - Absolute path to story .md file
+ * @returns {Promise<void>}
+ */
+async function updateFrontmatterTimestamp(storyFilePath) {
+  const timestamp = new Date().toISOString();
+  await updateFrontmatter(storyFilePath, {
+    clickup: {
+      last_sync: timestamp,
+    },
+  });
+}
+
+/**
+ * Creates a story task in ClickUp as a subtask of an Epic
+ *
+ * Implements AC2: Story Creation as ClickUp Subtask
+ * Creates story with correct parent relationship, tags, and custom fields
+ *
+ * @param {object} options - Story creation options
+ * @param {number} options.epicNum - Epic number
+ * @param {number} options.storyNum - Story number
+ * @param {number} [options.subStoryNum] - Optional substory number for nested stories
+ * @param {string} options.title - Story title
+ * @param {string} options.epicTaskId - Parent Epic task ID
+ * @param {string} options.listName - ClickUp list name (typically "Backlog")
+ * @param {string} options.storyContent - Full story markdown content
+ * @param {string} [options.storyFilePath] - Path to story file (auto-generated if not provided)
+ * @returns {Promise<object>} Created task info: { taskId, url }
+ * @throws {Error} If ClickUp task creation fails or validation fails
+ */
+async function createStoryInClickUp({
+  epicNum,
+  storyNum,
+  subStoryNum = null,
+  title,
+  epicTaskId,
+  listName,
+  storyContent,
+  storyFilePath,
+}) {
+  // Validation
+  if (typeof epicNum !== 'number') {
+    throw new Error('epic_number must be a number');
+  }
+  if (typeof storyNum !== 'number' && isNaN(Number(storyNum))) {
+    throw new Error('story_number must be numeric');
+  }
+
+  // Format story identifier
+  const storyId = subStoryNum
+    ? `${epicNum}.${subStoryNum}.${storyNum}`
+    : `${epicNum}.${storyNum}`;
+
+  const storyName = `Story ${storyId}: ${title}`;
+
+  // Generate tags: ["story", "epic-{epicNum}", "story-{storyId}"]
+  const tags = ['story', `epic-${epicNum}`, `story-${storyId}`];
+
+  // Auto-generate file path if not provided
+  const filePath = storyFilePath || `docs/stories/${storyId}.${title.toLowerCase().replace(/\s+/g, '-')}.md`;
+
+  // Prepare custom fields
+  const customFields = [
+    { id: 'epic_number', value: epicNum },
+    { id: 'story_number', value: storyId },
+    { id: 'story_file_path', value: filePath },
+    { id: 'story-status', value: 'Draft' },
+  ];
+
+  try {
+    console.log(`Creating story ${storyName} in ClickUp...`);
+
+    // Get ClickUp tool
+    const clickUpTool = await getClickUpTool();
+
+    // Create task with parent relationship
+    const result = await clickUpTool.createTask({
+      listName: listName,
+      name: storyName,
+      parent: epicTaskId,  // Creates as subtask
+      markdown_description: storyContent,
+      tags: tags,
+      custom_fields: customFields,
+    });
+
+    console.log(`✅ Story created in ClickUp: ${result.id}`);
+
+    return {
+      taskId: result.id,
+      url: result.url || `https://app.clickup.com/t/${result.id}`,
+    };
+
+  } catch (error) {
+    console.error('Error creating story in ClickUp:', error);
+    throw new Error(`Failed to create story in ClickUp: ${error.message}`);
+  }
+}
+
+/**
+ * Sync story to configured PM tool (adapter-aware)
+ * @param {string} storyPath - Path to story YAML file
+ * @returns {Promise<{success: boolean, url?: string, error?: string}>}
+ */
+async function syncStoryToPM(storyPath) {
+  try {
+    const { getPMAdapter } = require('../../infrastructure/scripts/pm-adapter-factory');
+    const adapter = getPMAdapter();
+
+    console.log(`📤 Syncing to ${adapter.getName()}...`);
+
+    const result = await adapter.syncStory(storyPath);
+
+    if (result.success) {
+      console.log('✅ Story synced successfully');
+      if (result.url) {
+        console.log(`   URL: ${result.url}`);
+      }
+    } else {
+      console.error(`❌ Sync failed: ${result.error}`);
+    }
+
+    return result;
+  } catch (error) {
+    console.error('Error syncing story:', error);
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Pull story updates from configured PM tool (adapter-aware)
+ * @param {string} storyId - Story ID (e.g., "3.20")
+ * @returns {Promise<{success: boolean, updates?: object, error?: string}>}
+ */
+async function pullStoryFromPM(storyId) {
+  try {
+    const { getPMAdapter, isPMToolConfigured } = require('../../infrastructure/scripts/pm-adapter-factory');
+
+    if (!isPMToolConfigured()) {
+      console.log('ℹ️  Local-only mode: No PM tool configured');
+      return {
+        success: true,
+        updates: null,
+      };
+    }
+
+    const adapter = getPMAdapter();
+
+    console.log(`📥 Pulling from ${adapter.getName()}...`);
+
+    const result = await adapter.pullStory(storyId);
+
+    if (result.success) {
+      if (result.updates) {
+        console.log('📥 Updates found:', result.updates);
+      } else {
+        console.log('✅ Story is up to date');
+      }
+    } else {
+      console.error(`❌ Pull failed: ${result.error}`);
+    }
+
+    return result;
+  } catch (error) {
+    console.error('Error pulling story:', error);
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+module.exports = {
+  parseStoryFile,
+  saveStoryFile,
+  updateFrontmatter,
+  updateStoryFrontmatter: updateFrontmatter,  // Alias for test compatibility
+  updateFrontmatterTimestamp,
+  createStoryInClickUp,
+  // PM adapter-aware functions (Story 3.20)
+  syncStoryToPM,
+  pullStoryFromPM,
+};