scene-capability-engine 3.0.0

package/lib/templates/template-applicator.js

@@ -0,0 +1,249 @@
+/**
+ * TemplateApplicator - Applies templates to create new Specs
+ * 
+ * Handles file copying, variable substitution, and frontmatter removal.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { FileSystemError } = require('./template-error');
+
+class TemplateApplicator {
+  constructor() {
+    this.requiredFiles = ['requirements.md', 'design.md', 'tasks.md'];
+  }
+
+  /**
+   * Applies a template to create a new Spec
+   * 
+   * @param {string} specName - Spec name (e.g., 'user-authentication')
+   * @param {string} templatePath - Path to template directory
+   * @param {string} targetDir - Target Spec directory
+   * @param {Object} options - Application options
+   * @param {boolean} options.force - Overwrite existing files
+   * @param {Object} options.variables - Custom variables
+   * @returns {Promise<Object>} Application result
+   */
+  async applyTemplate(specName, templatePath, targetDir, options = {}) {
+    const { force = false, variables = {} } = options;
+
+    const result = {
+      success: true,
+      filesCreated: [],
+      filesSkipped: [],
+      errors: []
+    };
+
+    // Check if template exists
+    if (!await fs.pathExists(templatePath)) {
+      throw new FileSystemError(
+        'Template directory does not exist',
+        { templatePath }
+      );
+    }
+
+    // Check if target directory exists
+    if (await fs.pathExists(targetDir) && !force) {
+      throw new FileSystemError(
+        'Target directory already exists',
+        {
+          targetDir,
+          suggestion: 'Use --force to overwrite or choose a different name'
+        }
+      );
+    }
+
+    // Create target directory
+    await fs.ensureDir(targetDir);
+
+    // Prepare variables
+    const allVariables = this._prepareVariables(specName, variables);
+
+    // Copy and transform files
+    for (const file of this.requiredFiles) {
+      const sourcePath = path.join(templatePath, file);
+      const targetPath = path.join(targetDir, file);
+
+      if (!await fs.pathExists(sourcePath)) {
+        result.errors.push(`Template missing file: ${file}`);
+        continue;
+      }
+
+      try {
+        // Read source file
+        let content = await fs.readFile(sourcePath, 'utf8');
+
+        // Remove frontmatter
+        content = this.removeFrontmatter(content);
+
+        // Transform variables
+        content = this.transformVariables(content, allVariables);
+
+        // Normalize line endings
+        content = this.normalizeLineEndings(content);
+
+        // Write target file
+        await fs.writeFile(targetPath, content, 'utf8');
+
+        result.filesCreated.push(file);
+      } catch (error) {
+        result.errors.push(`Failed to process ${file}: ${error.message}`);
+        result.success = false;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Prepares variables for substitution
+   * 
+   * @param {string} specName - Spec name
+   * @param {Object} customVariables - Custom variables
+   * @returns {Object} All variables
+   * @private
+   */
+  _prepareVariables(specName, customVariables = {}) {
+    const now = new Date();
+    
+    // Convert kebab-case to Title Case (preserve hyphens for numbers)
+    const specNameTitle = specName
+      .split('-')
+      .map(word => {
+        // If word is all digits, keep it as is
+        if (/^\d+$/.test(word)) {
+          return word;
+        }
+        // Otherwise capitalize first letter
+        return word.charAt(0).toUpperCase() + word.slice(1);
+      })
+      .join(' ');
+
+    const defaultVariables = {
+      SPEC_NAME: specName,
+      SPEC_NAME_TITLE: specNameTitle,
+      DATE: now.toISOString().split('T')[0],
+      YEAR: now.getFullYear().toString(),
+      AUTHOR: this._getAuthorName(),
+      PROJECT_NAME: this._getProjectName()
+    };
+
+    return { ...defaultVariables, ...customVariables };
+  }
+
+  /**
+   * Gets author name from Git config
+   * 
+   * @returns {string} Author name
+   * @private
+   */
+  _getAuthorName() {
+    try {
+      const { execSync } = require('child_process');
+      const name = execSync('git config user.name', { encoding: 'utf8' }).trim();
+      return name || 'Unknown';
+    } catch (error) {
+      return 'Unknown';
+    }
+  }
+
+  /**
+   * Gets project name from package.json or directory
+   * 
+   * @returns {string} Project name
+   * @private
+   */
+  _getProjectName() {
+    try {
+      const packagePath = path.join(process.cwd(), 'package.json');
+      if (fs.existsSync(packagePath)) {
+        const pkg = require(packagePath);
+        return pkg.name || path.basename(process.cwd());
+      }
+    } catch (error) {
+      // Ignore
+    }
+    
+    return path.basename(process.cwd());
+  }
+
+  /**
+   * Removes YAML frontmatter from content
+   * 
+   * @param {string} content - File content
+   * @returns {string} Content without frontmatter
+   */
+  removeFrontmatter(content) {
+    // Normalize line endings first
+    const normalized = content.replace(/\r\n/g, '\n');
+    // Remove frontmatter
+    return normalized.replace(/^---\n[\s\S]*?\n---\n/, '');
+  }
+
+  /**
+   * Transforms variables in content
+   * 
+   * @param {string} content - File content
+   * @param {Object} variables - Variables to substitute
+   * @returns {string} Transformed content
+   */
+  transformVariables(content, variables) {
+    let result = content;
+
+    for (const [key, value] of Object.entries(variables)) {
+      const placeholder = `{{${key}}}`;
+      result = result.split(placeholder).join(value);
+    }
+
+    return result;
+  }
+
+  /**
+   * Normalizes line endings to LF
+   * 
+   * @param {string} content - File content
+   * @returns {string} Content with LF line endings
+   */
+  normalizeLineEndings(content) {
+    return content.replace(/\r\n/g, '\n');
+  }
+
+  /**
+   * Handles file conflict
+   * 
+   * @param {string} targetPath - Target file path
+   * @param {string} strategy - Conflict strategy ('overwrite', 'skip', 'rename')
+   * @returns {Promise<string>} Resolved target path
+   */
+  async handleConflict(targetPath, strategy = 'skip') {
+    if (!await fs.pathExists(targetPath)) {
+      return targetPath;
+    }
+
+    switch (strategy) {
+      case 'overwrite':
+        return targetPath;
+      
+      case 'skip':
+        return null;
+      
+      case 'rename':
+        let counter = 1;
+        let newPath = targetPath;
+        const ext = path.extname(targetPath);
+        const base = targetPath.slice(0, -ext.length);
+        
+        while (await fs.pathExists(newPath)) {
+          newPath = `${base}-${counter}${ext}`;
+          counter++;
+        }
+        
+        return newPath;
+      
+      default:
+        return targetPath;
+    }
+  }
+}
+
+module.exports = TemplateApplicator;

package/lib/templates/template-creator.js

@@ -0,0 +1,256 @@
+/**
+ * TemplateCreator - Main orchestrator for template creation workflow
+ */
+
+const SpecReader = require('./spec-reader');
+const ContentGeneralizer = require('./content-generalizer');
+const MetadataCollector = require('./metadata-collector');
+const FrontmatterGenerator = require('./frontmatter-generator');
+const TemplateValidator = require('./template-validator');
+const TemplateExporter = require('./template-exporter');
+
+class TemplateCreator {
+  constructor(options = {}) {
+    this.options = options;
+    this.specReader = new SpecReader();
+    this.contentGeneralizer = new ContentGeneralizer();
+    this.metadataCollector = new MetadataCollector(options);
+    this.frontmatterGenerator = new FrontmatterGenerator();
+    this.templateValidator = new TemplateValidator();
+    this.templateExporter = new TemplateExporter();
+  }
+
+  /**
+   * Creates a template from an existing Spec
+   * @param {Object} options - Creation options
+   * @returns {Promise<Object>} Creation result
+   */
+  async createTemplate(options) {
+    const {
+      spec,
+      output,
+      preview = false,
+      dryRun = false,
+      interactive = true
+    } = options;
+
+    try {
+      console.log('🚀 Starting template creation...\n');
+
+      // Step 1: Read and validate Spec
+      console.log('📖 Step 1: Reading Spec...');
+      const specInfo = await this.specReader.findSpec(spec);
+      console.log(`   Found: ${specInfo.name}`);
+
+      const validation = await this.specReader.validateSpecStructure(specInfo.path);
+      if (!validation.valid) {
+        throw new Error(`Missing required files: ${validation.missingFiles.join(', ')}`);
+      }
+      console.log(`   ✓ All required files present\n`);
+
+      const fileContents = await this.specReader.readSpecFiles(specInfo.path);
+      const specMetadata = this.specReader.extractSpecMetadata(specInfo.path, fileContents);
+
+      // Step 2: Generalize content
+      console.log('🔄 Step 2: Generalizing content...');
+      const generalizationResult = this.contentGeneralizer.generalize(fileContents, specMetadata);
+      console.log(`   Replacements: ${generalizationResult.summary.totalReplacements}`);
+      console.log(`   Flags: ${generalizationResult.summary.totalFlags}\n`);
+
+      // Step 3: Collect metadata
+      console.log('📝 Step 3: Collecting metadata...');
+      const metadata = await this.metadataCollector.collectMetadata(specMetadata, interactive);
+      console.log(`   ✓ Metadata collected\n`);
+
+      // Step 4: Generate frontmatter
+      console.log('📄 Step 4: Generating frontmatter...');
+      const frontmatter = this.frontmatterGenerator.generateFrontmatter(metadata);
+      const filesWithFrontmatter = {};
+      
+      for (const [filename, fileData] of Object.entries(generalizationResult.files)) {
+        if (fileData.generalized) {
+          filesWithFrontmatter[filename] = this.frontmatterGenerator.addFrontmatter(
+            fileData.generalized,
+            frontmatter
+          );
+        }
+      }
+      console.log(`   ✓ Frontmatter added to all files\n`);
+
+      // Step 5: Validate template
+      console.log('✅ Step 5: Validating template...');
+      const validationResult = await this.validateTemplate(filesWithFrontmatter, metadata);
+      console.log(`   Quality Score: ${validationResult.score}/100`);
+      console.log(`   Errors: ${validationResult.errors.length}`);
+      console.log(`   Warnings: ${validationResult.warnings.length}\n`);
+
+      if (validationResult.errors.length > 0) {
+        console.log('❌ Validation Errors:');
+        validationResult.errors.forEach(error => console.log(`   - ${error}`));
+        console.log('');
+      }
+
+      if (validationResult.warnings.length > 0) {
+        console.log('⚠️  Validation Warnings:');
+        validationResult.warnings.forEach(warning => console.log(`   - ${warning}`));
+        console.log('');
+      }
+
+      // Step 6: Preview (if requested)
+      if (preview) {
+        console.log('👀 Preview:');
+        this.showPreview(fileContents, generalizationResult);
+        console.log('');
+      }
+
+      // Step 7: Export template
+      if (dryRun) {
+        console.log('🏃 Dry run mode - skipping export\n');
+        return {
+          success: true,
+          dryRun: true,
+          metadata,
+          validationResult
+        };
+      }
+
+      console.log('📦 Step 6: Exporting template...');
+      const exportResult = await this.templateExporter.exportTemplate(
+        {
+          metadata,
+          files: filesWithFrontmatter,
+          validationResult,
+          generalizationResult
+        },
+        output
+      );
+
+      console.log(`   ✓ Template exported to: ${exportResult.outputDir}\n`);
+
+      // Final summary
+      console.log('✨ Template creation complete!\n');
+      console.log('📁 Files created:');
+      exportResult.filesCreated.forEach(file => console.log(`   - ${file}`));
+      console.log('');
+      console.log('📖 Next steps:');
+      console.log(`   1. Review the template in: ${exportResult.outputDir}`);
+      console.log(`   2. Check REVIEW_CHECKLIST.md for items to verify`);
+      console.log(`   3. Test the template: kse spec create test --template ${metadata.name}`);
+      console.log(`   4. Follow SUBMISSION_GUIDE.md to submit to repository`);
+      console.log('');
+
+      return exportResult;
+
+    } catch (error) {
+      console.error(`\n❌ Error: ${error.message}\n`);
+      throw error;
+    }
+  }
+
+  /**
+   * Validates template
+   * @param {Object} files - Template files
+   * @param {Object} metadata - Template metadata
+   * @returns {Promise<Object>} Validation result
+   */
+  async validateTemplate(files, metadata) {
+    const errors = [];
+    const warnings = [];
+    let score = 100;
+
+    // Validate frontmatter in each file
+    for (const [filename, content] of Object.entries(files)) {
+      if (!content) continue;
+
+      // Check for frontmatter
+      if (!content.trim().startsWith('---')) {
+        errors.push(`${filename}: Missing YAML frontmatter`);
+        score -= 10;
+        continue;
+      }
+
+      // Validate YAML syntax
+      const yamlValidation = this.frontmatterGenerator.validateYaml(
+        content.split('---')[1]
+      );
+      if (!yamlValidation.valid) {
+        errors.push(`${filename}: Invalid YAML frontmatter - ${yamlValidation.errors.join(', ')}`);
+        score -= 10;
+      }
+
+      // Check for remaining project-specific content (high confidence patterns)
+      const projectSpecificPatterns = [
+        /\.kiro\/specs\/\d+-\d+-[a-z-]+/g,  // Specific spec paths
+        /kiro-spec-engine/g,  // Project name (unless it's the template itself)
+      ];
+
+      projectSpecificPatterns.forEach(pattern => {
+        const matches = content.match(pattern);
+        if (matches && matches.length > 3) {  // Allow a few occurrences
+          warnings.push(`${filename}: Possible project-specific content: ${matches[0]}`);
+          score -= 2;
+        }
+      });
+
+      // Check for template variable syntax
+      const malformedVariables = content.match(/\{\{[^}]*\}\}(?!\})/g);
+      if (malformedVariables) {
+        malformedVariables.forEach(v => {
+          if (!/^\{\{[A-Z_]+\}\}$/.test(v)) {
+            warnings.push(`${filename}: Malformed template variable: ${v}`);
+            score -= 1;
+          }
+        });
+      }
+    }
+
+    // Validate metadata
+    const metadataValidation = this.metadataCollector.validateMetadata(metadata);
+    if (!metadataValidation.valid) {
+      errors.push(...metadataValidation.errors);
+      score -= 15;
+    }
+
+    // Ensure score doesn't go below 0
+    score = Math.max(0, score);
+
+    return {
+      valid: errors.length === 0,
+      score,
+      errors,
+      warnings,
+      breakdown: {
+        structure: errors.length === 0 ? 30 : 15,
+        frontmatter: errors.filter(e => e.includes('frontmatter')).length === 0 ? 20 : 10,
+        variables: warnings.filter(w => w.includes('variable')).length === 0 ? 20 : 15,
+        content: warnings.filter(w => w.includes('project-specific')).length === 0 ? 20 : 15,
+        references: 10
+      }
+    };
+  }
+
+  /**
+   * Shows preview of changes
+   * @param {Object} originalContent - Original Spec content
+   * @param {Object} generalizationResult - Generalization result
+   */
+  showPreview(originalContent, generalizationResult) {
+    for (const [filename, fileData] of Object.entries(generalizationResult.files)) {
+      console.log(`\n📄 ${filename}:`);
+      console.log(`   Replacements: ${fileData.replacements.length}`);
+      
+      fileData.replacements.forEach(r => {
+        console.log(`   - ${r.pattern} → ${r.variable} (${r.count} times)`);
+      });
+
+      if (fileData.flags.length > 0) {
+        console.log(`   Flags: ${fileData.flags.length}`);
+        fileData.flags.forEach(f => {
+          console.log(`   - Line ${f.line}: ${f.message} - "${f.content}"`);
+        });
+      }
+    }
+  }
+}
+
+module.exports = TemplateCreator;

package/lib/templates/template-error.js

@@ -0,0 +1,143 @@
+/**
+ * Template Error Classes
+ * 
+ * Provides specialized error types for template operations with
+ * context-specific error messages and troubleshooting suggestions.
+ */
+
+/**
+ * Base error class for all template-related errors
+ */
+class TemplateError extends Error {
+  constructor(type, message, details = {}) {
+    super(message);
+    this.name = 'TemplateError';
+    this.type = type;
+    this.details = details;
+    this.suggestions = this.generateSuggestions();
+    
+    // Maintain proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  
+  /**
+   * Generate context-specific troubleshooting suggestions
+   * @returns {string[]} Array of suggestion strings
+   */
+  generateSuggestions() {
+    switch (this.type) {
+      case 'network':
+        return [
+          'Check your internet connection',
+          'Verify the repository URL is correct',
+          'Try again later if the service is temporarily unavailable',
+          'Check if you need to configure proxy settings'
+        ];
+      
+      case 'validation':
+        return [
+          'Review the template structure requirements',
+          'Check the YAML frontmatter syntax',
+          'Ensure all required fields are present',
+          'Refer to CONTRIBUTING.md for template format'
+        ];
+      
+      case 'filesystem':
+        return [
+          'Check file permissions',
+          'Ensure sufficient disk space',
+          'Verify the path is correct',
+          'Try running with elevated permissions if needed'
+        ];
+      
+      case 'git':
+        return [
+          'Ensure Git is installed and in PATH',
+          'Check repository URL is accessible',
+          'Verify Git credentials if repository is private',
+          'Try clearing the cache and re-downloading'
+        ];
+      
+      default:
+        return [
+          'Check the error details above',
+          'Refer to documentation for troubleshooting',
+          'Report this issue if the problem persists'
+        ];
+    }
+  }
+  
+  /**
+   * Format error for display to user
+   * @returns {string} Formatted error message
+   */
+  format() {
+    let output = `\n❌ ${this.message}\n`;
+    
+    if (Object.keys(this.details).length > 0) {
+      output += '\nDetails:\n';
+      for (const [key, value] of Object.entries(this.details)) {
+        output += `  ${key}: ${value}\n`;
+      }
+    }
+    
+    if (this.suggestions.length > 0) {
+      output += '\nSuggestions:\n';
+      this.suggestions.forEach((suggestion, index) => {
+        output += `  ${index + 1}. ${suggestion}\n`;
+      });
+    }
+    
+    return output;
+  }
+}
+
+/**
+ * Network-related errors (download, clone, pull)
+ */
+class NetworkError extends TemplateError {
+  constructor(message, details = {}) {
+    super('network', message, details);
+    this.name = 'NetworkError';
+  }
+}
+
+/**
+ * Template validation errors
+ */
+class ValidationError extends TemplateError {
+  constructor(message, details = {}) {
+    super('validation', message, details);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * File system operation errors
+ */
+class FileSystemError extends TemplateError {
+  constructor(message, details = {}) {
+    super('filesystem', message, details);
+    this.name = 'FileSystemError';
+  }
+}
+
+/**
+ * Git operation errors
+ */
+class GitError extends TemplateError {
+  constructor(message, details = {}) {
+    super('git', message, details);
+    this.name = 'GitError';
+  }
+}
+
+module.exports = {
+  TemplateError,
+  NetworkError,
+  ValidationError,
+  FileSystemError,
+  GitError
+};