grimoire-framework 1.0.0

package/.grimoire/development/scripts/story-update-hook.js

@@ -0,0 +1,259 @@
+// File: common/utils/story-update-hook.js
+
+const { updateTaskDescription, updateStoryStatus, addTaskComment } = require('../../infrastructure/scripts/clickup-helpers');
+const yaml = require('js-yaml');
+
+/**
+ * Detects changes between two versions of story markdown content
+ *
+ * @param {string} oldContent - Previous markdown content
+ * @param {string} newContent - Current markdown content
+ * @returns {object} Changes detected
+ */
+function detectChanges(oldContent, newContent) {
+  // Handle null/undefined content
+  if (!oldContent) oldContent = '';
+  if (!newContent) newContent = '';
+
+  const changes = {
+    status: { changed: false },
+    tasksCompleted: [],
+    filesAdded: [],
+    devNotesAdded: false,
+    acceptanceCriteriaChanged: false,
+  };
+
+  // Parse frontmatter to get status
+  const oldStatus = extractStatus(oldContent);
+  const newStatus = extractStatus(newContent);
+
+  if (oldStatus !== newStatus) {
+    changes.status = {
+      changed: true,
+      from: oldStatus,
+      to: newStatus,
+    };
+  } else {
+    changes.status = {
+      changed: false,
+      from: oldStatus,
+      to: newStatus,
+    };
+  }
+
+  // Detect completed tasks
+  const oldTasks = extractTasks(oldContent);
+  const newTasks = extractTasks(newContent);
+
+  newTasks.forEach(task => {
+    if (task.completed) {
+      const wasCompleted = oldTasks.some(
+        oldTask => oldTask.text === task.text && oldTask.completed,
+      );
+      if (!wasCompleted) {
+        changes.tasksCompleted.push(task.text);
+      }
+    }
+  });
+
+  // Detect added files
+  const oldFiles = extractFileList(oldContent);
+  const newFiles = extractFileList(newContent);
+
+  changes.filesAdded = newFiles.filter(file => !oldFiles.includes(file));
+
+  // Detect dev notes changes
+  const oldDevNotes = extractSection(oldContent, '## Dev Notes');
+  const newDevNotes = extractSection(newContent, '## Dev Notes');
+
+  if (oldDevNotes !== newDevNotes && newDevNotes.length > oldDevNotes.length) {
+    changes.devNotesAdded = true;
+    changes.devNotesContent = newDevNotes.substring(oldDevNotes.length).trim();
+  }
+
+  // Detect acceptance criteria changes
+  const oldAC = extractSection(oldContent, '## Acceptance Criteria');
+  const newAC = extractSection(newContent, '## Acceptance Criteria');
+
+  if (oldAC !== newAC) {
+    changes.acceptanceCriteriaChanged = true;
+  }
+
+  return changes;
+}
+
+/**
+ * Extract status from frontmatter
+ */
+function extractStatus(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) return undefined;
+
+  try {
+    const frontmatter = yaml.load(frontmatterMatch[1]);
+    return frontmatter.status;
+  } catch (_error) {
+    return undefined;
+  }
+}
+
+/**
+ * Extract tasks from markdown
+ */
+function extractTasks(content) {
+  const taskMatches = content.matchAll(/^- \[([ x])\] (.+)$/gm);
+  return Array.from(taskMatches).map(match => ({
+    completed: match[1] === 'x',
+    text: match[2],
+  }));
+}
+
+/**
+ * Extract file list from File List section
+ */
+function extractFileList(content) {
+  const fileListSection = extractSection(content, '## File List');
+  if (!fileListSection) return [];
+
+  const fileMatches = fileListSection.matchAll(/^- (.+\.(?:js|ts|jsx|tsx|json|yaml|md|test\.js))$/gm);
+  return Array.from(fileMatches).map(match => match[1]);
+}
+
+/**
+ * Extract a markdown section by heading
+ */
+function extractSection(content, heading) {
+  // Try with double newline first (standard format)
+  let regex = new RegExp(`${heading}\\n\\n([\\s\\S]*?)(?=\\n##|$)`);
+  let match = content.match(regex);
+
+  // If no match, try with single newline
+  if (!match) {
+    regex = new RegExp(`${heading}\\n([\\s\\S]*?)(?=\\n##|$)`);
+    match = content.match(regex);
+  }
+
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Generate changelog markdown from changes
+ */
+function generateChangelog(changes) {
+  if (!hasChanges(changes)) {
+    return '';
+  }
+
+  const timestamp = new Date().toISOString();
+  let markdown = `**Story Updated: ${timestamp}**\n\n**Changes:**\n`;
+
+  if (changes.status.changed) {
+    markdown += `- Status: ${changes.status.from} → ${changes.status.to}\n`;
+  }
+
+  if (changes.tasksCompleted.length > 0) {
+    markdown += '- Completed tasks:\n';
+    changes.tasksCompleted.forEach(task => {
+      markdown += `  • ${task}\n`;
+    });
+  }
+
+  if (changes.filesAdded.length > 0) {
+    markdown += '- Files added:\n';
+    changes.filesAdded.forEach(file => {
+      markdown += `  • ${file}\n`;
+    });
+  }
+
+  if (changes.devNotesAdded) {
+    markdown += '- Dev notes updated\n';
+  }
+
+  if (changes.acceptanceCriteriaChanged) {
+    markdown += '- Acceptance criteria modified\n';
+  }
+
+  return markdown;
+}
+
+/**
+ * Check if there are any changes
+ */
+function hasChanges(changes) {
+  return changes.status.changed ||
+         changes.tasksCompleted.length > 0 ||
+         changes.filesAdded.length > 0 ||
+         changes.devNotesAdded ||
+         changes.acceptanceCriteriaChanged;
+}
+
+/**
+ * Sync story changes to ClickUp
+ */
+async function syncStoryToClickUp(storyFile, changes) {
+  // Extract ClickUp metadata
+  const taskId = storyFile?.metadata?.clickup_task_id;
+  if (!taskId) {
+    console.warn('Story has no ClickUp metadata, skipping sync');
+    return;
+  }
+
+  // Only sync if there are actual changes
+  if (!hasChanges(changes)) {
+    return;
+  }
+
+  // Update status if changed
+  if (changes.status.changed) {
+    await updateStoryStatus(taskId, changes.status.to);
+  }
+
+  // Update task description if acceptance criteria changed
+  if (changes.acceptanceCriteriaChanged) {
+    await updateTaskDescription(taskId, storyFile.content);
+  }
+
+  // Add changelog comment
+  const changelog = generateChangelog(changes);
+  if (changelog) {
+    await addTaskComment(taskId, changelog);
+  }
+}
+
+/**
+ * Update frontmatter timestamp
+ */
+function updateFrontmatterTimestamp(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) {
+    return content; // No frontmatter, return unchanged
+  }
+
+  try {
+    const frontmatter = yaml.load(frontmatterMatch[1]);
+
+    // Format timestamp without milliseconds to match expected format
+    const now = new Date();
+    const timestamp = now.toISOString().split('.')[0]; // Remove milliseconds and 'Z'
+    frontmatter.last_updated = timestamp;
+
+    // Dump YAML
+    let newFrontmatterYaml = yaml.dump(frontmatter);
+
+    // Remove quotes from timestamp value (YAML adds them to ISO date strings)
+    newFrontmatterYaml = newFrontmatterYaml.replace(/last_updated: ["']([^"']+)["']/, 'last_updated: $1');
+
+    const contentAfterFrontmatter = content.substring(frontmatterMatch[0].length);
+
+    return `---\n${newFrontmatterYaml}---${contentAfterFrontmatter}`;
+  } catch (_error) {
+    return content; // Failed to parse, return unchanged
+  }
+}
+
+module.exports = {
+  detectChanges,
+  generateChangelog,
+  syncStoryToClickUp,
+  updateFrontmatterTimestamp,
+};

package/.grimoire/development/scripts/task-identifier-resolver.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+/**
+ * Task Identifier Resolver
+ * Story: 6.1.7.1 - Task Content Completion
+ * Purpose: Resolve {TODO: task identifier} placeholders in all 114 task files
+ * 
+ * Converts filenames to camelCase format (e.g., dev-develop-story.md → devDevelopStory())
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Configuration
+const TASKS_DIR = path.join(__dirname, '../tasks');
+const TODO_PATTERN = /task: \{TODO: task identifier\}/g;
+const BACKUP_SUFFIX = '.pre-task-id-fix';
+
+// Utility: Convert kebab-case filename to camelCase function name
+function filenameToCamelCase(filename) {
+  // Remove .md extension
+  const nameWithoutExt = filename.replace('.md', '');
+  
+  // Split by hyphen and convert to camelCase
+  const parts = nameWithoutExt.split('-');
+  const camelCase = parts
+    .map((part, index) => {
+      if (index === 0) return part; // First part stays lowercase
+      return part.charAt(0).toUpperCase() + part.slice(1);
+    })
+    .join('');
+  
+  return `${camelCase}()`;
+}
+
+// Utility: Create backup of file
+function createBackup(filePath) {
+  const backupPath = filePath + BACKUP_SUFFIX;
+  fs.copyFileSync(filePath, backupPath);
+  return backupPath;
+}
+
+// Main: Process single task file
+function processTaskFile(filename) {
+  const filePath = path.join(TASKS_DIR, filename);
+  
+  // Skip backup files
+  if (filename.includes('backup') || filename.includes('.legacy')) {
+    return { skipped: true, reason: 'backup/legacy file' };
+  }
+  
+  // Read file content
+  const content = fs.readFileSync(filePath, 'utf8');
+  
+  // Check if TODO exists
+  if (!TODO_PATTERN.test(content)) {
+    return { skipped: true, reason: 'no TODO placeholder found' };
+  }
+  
+  // Generate camelCase identifier
+  const taskIdentifier = filenameToCamelCase(filename);
+  
+  // Create backup
+  createBackup(filePath);
+  
+  // Replace TODO with actual identifier
+  const updatedContent = content.replace(
+    TODO_PATTERN,
+    `task: ${taskIdentifier}`,
+  );
+  
+  // Write updated content
+  fs.writeFileSync(filePath, updatedContent, 'utf8');
+  
+  return {
+    processed: true,
+    filename,
+    identifier: taskIdentifier,
+  };
+}
+
+// Main: Process all task files
+function main() {
+  console.log('🚀 Task Identifier Resolver\n');
+  console.log(`📂 Processing tasks in: ${TASKS_DIR}\n`);
+  
+  // Get all .md files
+  const files = fs.readdirSync(TASKS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .sort();
+  
+  console.log(`📝 Found ${files.length} task files\n`);
+  
+  const results = {
+    processed: [],
+    skipped: [],
+    errors: [],
+  };
+  
+  // Process each file
+  files.forEach(filename => {
+    try {
+      const result = processTaskFile(filename);
+      
+      if (result.processed) {
+        results.processed.push(result);
+        console.log(`✅ ${result.filename} → ${result.identifier}`);
+      } else if (result.skipped) {
+        results.skipped.push({ filename, reason: result.reason });
+      }
+    } catch (error) {
+      results.errors.push({ filename, error: error.message });
+      console.error(`❌ ${filename}: ${error.message}`);
+    }
+  });
+  
+  // Summary
+  console.log('\n' + '='.repeat(60));
+  console.log('📊 Summary:');
+  console.log(`   ✅ Processed: ${results.processed.length}`);
+  console.log(`   ⏭️  Skipped: ${results.skipped.length}`);
+  console.log(`   ❌ Errors: ${results.errors.length}`);
+  console.log('='.repeat(60) + '\n');
+  
+  // Save report
+  const reportPath = path.join(__dirname, '../../.ai/task-1.1-identifier-resolution-report.json');
+  fs.writeFileSync(reportPath, JSON.stringify(results, null, 2), 'utf8');
+  console.log(`📄 Report saved: ${reportPath}\n`);
+  
+  return results;
+}
+
+// Execute if run directly
+if (require.main === module) {
+  try {
+    const results = main();
+    process.exit(results.errors.length > 0 ? 1 : 0);
+  } catch (error) {
+    console.error('💥 Fatal error:', error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { filenameToCamelCase, processTaskFile };
+

package/.grimoire/development/scripts/template-engine.js

@@ -0,0 +1,240 @@
+/**
+ * Template Engine for grimoire-FULLSTACK
+ * Handles variable substitution, conditionals, and loops for component generation
+ * @module template-engine
+ */
+
+const fs = require('fs-extra');
+const _path = require('path');
+
+class TemplateEngine {
+  constructor() {
+    this.variablePattern = /\{\{([^}]+)\}\}/g;
+    this.conditionalPattern = /\{\{#IF_([^}]+)\}\}([\s\S]*?)\{\{\/IF_\1\}\}/g;
+    this.loopPattern = /\{\{#EACH_([^}]+)\}\}([\s\S]*?)\{\{\/EACH_\1\}\}/g;
+    this.escapePattern = /\\\{\{([^}]+)\}\}/g;
+  }
+
+  /**
+   * Process a template string with given variables
+   * @param {string} template - The template string
+   * @param {Object} variables - Variables to substitute
+   * @returns {string} Processed template
+   */
+  process(template, variables = {}) {
+    // First, handle escaped braces
+    let processed = template.replace(this.escapePattern, '{{$1}}');
+    
+    // Process loops
+    processed = this.processLoops(processed, variables);
+    
+    // Process conditionals
+    processed = this.processConditionals(processed, variables);
+    
+    // Process simple variables
+    processed = this.processVariables(processed, variables);
+    
+    // Restore escaped braces
+    processed = processed.replace(/\{\{ESCAPED_BRACE_(LEFT|RIGHT)\}\}/g, (match, side) => 
+      side === 'LEFT' ? '{{' : '}}'
+    );
+    
+    return processed;
+  }
+
+  /**
+   * Process loop constructs in template
+   * @private
+   * @param {string} template - Template string
+   * @param {Object} variables - Variables object
+   * @returns {string} Processed template
+   */
+  processLoops(template, variables) {
+    return template.replace(this.loopPattern, (match, loopVar, content) => {
+      const items = this.resolveVariable(loopVar, variables);
+      
+      // Handle non-array values gracefully
+      if (!Array.isArray(items)) {
+        console.warn(`[TemplateEngine] Expected array for loop variable '${loopVar}', got ${typeof items}`);
+        return '';
+      }
+      
+      return items.map((item, index) => {
+        // Create proper loop context with item and metadata
+        const loopVars = {
+          ...variables,
+          ITEM: item,
+          INDEX: index,
+          FIRST: index === 0,
+          LAST: index === items.length - 1,
+          [loopVar.replace('_', '')]: item
+        };
+        
+        // Process nested loops and conditionals
+        let processedContent = this.processLoops(content, loopVars);
+        processedContent = this.processConditionals(processedContent, loopVars);
+        processedContent = this.processVariables(processedContent, loopVars);
+        
+        return processedContent;
+      }).join('');
+    });
+  }
+
+  /**
+   * Process conditional constructs in template
+   * @private
+   */
+  processConditionals(template, variables) {
+    return template.replace(this.conditionalPattern, (match, condition, content) => {
+      const value = this.resolveVariable(condition, variables);
+      
+      // Check for truthy value
+      if (value && (Array.isArray(value) ? value.length > 0 : true)) {
+        return content;
+      }
+      return '';
+    });
+  }
+
+  /**
+   * Process simple variable substitutions
+   * @private
+   */
+  processVariables(template, variables) {
+    return template.replace(this.variablePattern, (match, varName) => {
+      const value = this.resolveVariable(varName.trim(), variables);
+      return value !== undefined ? String(value) : match;
+    });
+  }
+
+  /**
+   * Resolve a variable name to its value
+   * @private
+   */
+  resolveVariable(varName, variables) {
+    // Handle nested paths like "user.name"
+    const parts = varName.split('.');
+    let value = variables;
+    
+    for (const part of parts) {
+      if (value && typeof value === 'object') {
+        value = value[part];
+      } else {
+        return undefined;
+      }
+    }
+    
+    return value;
+  }
+
+  /**
+   * Validate that a template has all required placeholders
+   * @param {string} template - Template to validate
+   * @param {string[]} requiredVars - List of required variable names
+   * @returns {Object} Validation result with {valid: boolean, missing: string[]}
+   */
+  validateTemplate(template, requiredVars = []) {
+    const foundVars = new Set();
+    const missing = [];
+    
+    // Extract all variable names from template
+    let match;
+    const allPatterns = [
+      this.variablePattern,
+      /\{\{#IF_([^}]+)\}\}/g,
+      /\{\{#EACH_([^}]+)\}\}/g
+    ];
+    
+    for (const pattern of allPatterns) {
+      pattern.lastIndex = 0; // Reset regex
+      while ((match = pattern.exec(template)) !== null) {
+        foundVars.add(match[1].trim());
+      }
+    }
+    
+    // Check for missing required variables
+    for (const reqVar of requiredVars) {
+      if (!foundVars.has(reqVar)) {
+        missing.push(reqVar);
+      }
+    }
+    
+    return {
+      valid: missing.length === 0,
+      missing,
+      found: Array.from(foundVars)
+    };
+  }
+
+  /**
+   * Load and process a template file
+   * @param {string} templatePath - Path to template file
+   * @param {Object} variables - Variables to substitute
+   * @returns {Promise<string>} Processed template
+   */
+  async loadAndProcess(templatePath, variables = {}) {
+    const template = await fs.readFile(templatePath, 'utf8');
+    return this.process(template, variables);
+  }
+
+  /**
+   * Escape special characters in user input to prevent injection
+   * @param {string} input - User input to escape
+   * @returns {string} Escaped input
+   */
+  escapeInput(input) {
+    if (typeof input !== 'string') return input;
+    
+    // Escape template syntax
+    return input
+      .replace(/\{\{/g, '\\{{')
+      .replace(/\}\}/g, '\\}}')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
+  /**
+   * Get all available variables from a template
+   * @param {string} template - Template to analyze
+   * @returns {Object} Object with variables categorized by type
+   */
+  getTemplateVariables(template) {
+    const variables = {
+      simple: [],
+      conditionals: [],
+      loops: []
+    };
+    
+    // Extract simple variables
+    let match;
+    this.variablePattern.lastIndex = 0;
+    while ((match = this.variablePattern.exec(template)) !== null) {
+      if (!match[1].startsWith('#') && !match[1].startsWith('/')) {
+        variables.simple.push(match[1].trim());
+      }
+    }
+    
+    // Extract conditionals
+    const conditionalStartPattern = /\{\{#IF_([^}]+)\}\}/g;
+    while ((match = conditionalStartPattern.exec(template)) !== null) {
+      variables.conditionals.push(match[1].trim());
+    }
+    
+    // Extract loops
+    const loopStartPattern = /\{\{#EACH_([^}]+)\}\}/g;
+    while ((match = loopStartPattern.exec(template)) !== null) {
+      variables.loops.push(match[1].trim());
+    }
+    
+    // Remove duplicates
+    for (const key in variables) {
+      variables[key] = [...new Set(variables[key])];
+    }
+    
+    return variables;
+  }
+}
+
+module.exports = TemplateEngine;