@jmruthers/pace-core 0.5.193 → 0.6.2

package/scripts/install-cursor-rules.cjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+/**
+ * Installation Script for pace-core Cursor Rules
+ * @package @jmruthers/pace-core
+ * @module Scripts/install-cursor-rules
+ * 
+ * Copies cursor rules from pace-core to consuming app's .cursor/rules/ directory.
+ * This is an opt-in script - it does NOT run automatically via postinstall.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ANSI color codes for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m'
+};
+
+// Check for safety guards
+function checkSafetyGuards() {
+  // Check environment variable
+  if (process.env.PACE_CURSOR_RULES_DISABLED === '1') {
+    console.log(`${colors.yellow}Skipping cursor rules installation: PACE_CURSOR_RULES_DISABLED=1${colors.reset}`);
+    process.exit(0);
+  }
+  
+  // Check for .git folder (safety guard for CI)
+  const cwd = process.cwd();
+  if (!fs.existsSync(path.join(cwd, '.git'))) {
+    console.log(`${colors.yellow}Skipping cursor rules installation: No .git folder found${colors.reset}`);
+    console.log(`${colors.yellow}This is a safety guard. If you want to install anyway, run with --force${colors.reset}`);
+    if (!process.argv.includes('--force')) {
+      process.exit(0);
+    }
+  }
+}
+
+// Get pace-core package path
+function getPaceCorePath() {
+  // Try to find pace-core in node_modules
+  const cwd = process.cwd();
+  const paceCorePath = path.join(cwd, 'node_modules', '@jmruthers', 'pace-core');
+  
+  if (fs.existsSync(paceCorePath)) {
+    return paceCorePath;
+  }
+  
+  // If not found, try relative to script location (for development)
+  const scriptDir = __dirname;
+  const relativePath = path.join(scriptDir, '..');
+  if (fs.existsSync(path.join(relativePath, 'cursor-rules'))) {
+    return relativePath;
+  }
+  
+  console.error(`${colors.red}Error: Could not find @jmruthers/pace-core package${colors.reset}`);
+  console.error(`${colors.red}Make sure pace-core is installed: npm install @jmruthers/pace-core${colors.reset}`);
+  process.exit(1);
+}
+
+// Get cursor rules source directory
+function getCursorRulesSource(paceCorePath) {
+  const rulesPath = path.join(paceCorePath, 'cursor-rules');
+  if (!fs.existsSync(rulesPath)) {
+    console.error(`${colors.red}Error: cursor-rules directory not found in pace-core${colors.reset}`);
+    process.exit(1);
+  }
+  return rulesPath;
+}
+
+// Get target directory (.cursor/rules in app root)
+function getCursorRulesTarget() {
+  const cwd = process.cwd();
+  const targetDir = path.join(cwd, '.cursor', 'rules');
+  return targetDir;
+}
+
+// Read rule file and extract version metadata
+function getRuleVersion(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (frontmatterMatch) {
+      const frontmatter = frontmatterMatch[1];
+      const versionMatch = frontmatter.match(/paceCoreVersion:\s*["']?([^"'\n]+)["']?/);
+      const rulesVersionMatch = frontmatter.match(/rulesVersion:\s*["']?([^"'\n]+)["']?/);
+      return {
+        paceCoreVersion: versionMatch ? versionMatch[1] : null,
+        rulesVersion: rulesVersionMatch ? rulesVersionMatch[1] : null
+      };
+    }
+  } catch (error) {
+    // Ignore errors
+  }
+  return { paceCoreVersion: null, rulesVersion: null };
+}
+
+// Check if file needs updating
+function needsUpdate(sourcePath, targetPath, force) {
+  if (force) {
+    return true;
+  }
+  
+  if (!fs.existsSync(targetPath)) {
+    return true;
+  }
+  
+  // Compare versions first (fast check)
+  const sourceVersion = getRuleVersion(sourcePath);
+  const targetVersion = getRuleVersion(targetPath);
+  
+  // If versions differ, needs update
+  if (sourceVersion.paceCoreVersion !== targetVersion.paceCoreVersion ||
+      sourceVersion.rulesVersion !== targetVersion.rulesVersion) {
+    return true;
+  }
+  
+  // If versions match but content differs, also needs update
+  // (handles cases where version metadata wasn't updated)
+  try {
+    const sourceContent = fs.readFileSync(sourcePath, 'utf8');
+    const targetContent = fs.readFileSync(targetPath, 'utf8');
+    if (sourceContent !== targetContent) {
+      return true;
+    }
+  } catch (error) {
+    // If we can't read files, assume update needed
+    return true;
+  }
+  
+  return false;
+}
+
+// Install cursor rules
+function installCursorRules(force = false) {
+  checkSafetyGuards();
+  
+  const paceCorePath = getPaceCorePath();
+  const sourceDir = getCursorRulesSource(paceCorePath);
+  const targetDir = getCursorRulesTarget();
+  
+  // Create target directory if it doesn't exist
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    console.log(`${colors.green}Created .cursor/rules/ directory${colors.reset}`);
+  }
+  
+  // Read all .mdc files from source
+  const files = fs.readdirSync(sourceDir)
+    .filter(file => file.endsWith('.mdc'))
+    .sort(); // Sort for consistent output
+  
+  if (files.length === 0) {
+    console.log(`${colors.yellow}No cursor rules found in pace-core${colors.reset}`);
+    return;
+  }
+  
+  console.log(`${colors.cyan}Installing cursor rules from pace-core...${colors.reset}\n`);
+  
+  let installed = 0;
+  let skipped = 0;
+  let updated = 0;
+  
+  files.forEach(file => {
+    const sourcePath = path.join(sourceDir, file);
+    const targetPath = path.join(targetDir, file);
+    
+    // Check if this is a pace-core rule (00-09) or app rule (50+)
+    const ruleNumber = parseInt(file.match(/^(\d+)-/)?.[1] || '99');
+    const isPaceCoreRule = ruleNumber >= 0 && ruleNumber <= 9;
+    
+    if (fs.existsSync(targetPath)) {
+      if (isPaceCoreRule) {
+        // pace-core rules should be automatically updated when they change
+        if (needsUpdate(sourcePath, targetPath, force)) {
+          // Automatically update pace-core rules when versions differ or content changed
+          fs.copyFileSync(sourcePath, targetPath);
+          console.log(`${colors.green}✓${colors.reset} Updated ${file}${force ? ' (forced)' : ''}`);
+          updated++;
+        } else {
+          console.log(`${colors.blue}○${colors.reset} ${file} is up to date`);
+          skipped++;
+        }
+      } else {
+        // App rules (50+) are never overwritten
+        console.log(`${colors.blue}○${colors.reset} ${file} is a custom rule, skipping`);
+        skipped++;
+      }
+    } else {
+      // File doesn't exist, install it
+      fs.copyFileSync(sourcePath, targetPath);
+      console.log(`${colors.green}✓${colors.reset} Installed ${file}`);
+      installed++;
+    }
+  });
+  
+  console.log(`\n${colors.bold}Installation Summary:${colors.reset}`);
+  console.log(`  ${colors.green}Installed:${colors.reset} ${installed}`);
+  console.log(`  ${colors.yellow}Updated:${colors.reset} ${updated}`);
+  console.log(`  ${colors.blue}Skipped:${colors.reset} ${skipped}`);
+  console.log(`\n${colors.cyan}Cursor rules are now available in .cursor/rules/${colors.reset}`);
+  console.log(`${colors.cyan}Restart Cursor to load the new rules.${colors.reset}`);
+}
+
+// Main execution
+function main() {
+  const force = process.argv.includes('--force');
+  
+  if (force) {
+    console.log(`${colors.yellow}Warning: --force flag is set. This will overwrite existing pace-core rules.${colors.reset}\n`);
+  }
+  
+  try {
+    installCursorRules(force);
+  } catch (error) {
+    console.error(`${colors.red}Error installing cursor rules:${colors.reset}`);
+    console.error(error.message);
+    if (error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { installCursorRules, getCursorRulesTarget };

package/scripts/utils/command-runner.js

@@ -112,19 +112,24 @@ export async function runCommand(command, args = [], options = {}) {
  * @returns {Promise<{success: boolean}>} Test execution result
  */
 export async function runStandardizedTests(packageRoot, repoRoot, timeout) {
-  logger.step('Running test suite from root (matching npm run test behavior)...');
+  try {
+    logger.step('Running test suite from root (matching npm run test behavior)...');
 
-  const result = await runCommand('npm', ['run', 'test'], {
-    cwd: repoRoot,
-    timeout,
-    showLiveOutput: true, // Show test output in CI
-  });
+    const result = await runCommand('npm', ['run', 'test'], {
+      cwd: repoRoot,
+      timeout,
+      showLiveOutput: true, // Show test output in CI
+    });
 
-  if (result.success) {
-    logger.success('All tests passed successfully');
-    return { success: true };
-  } else {
-    logger.error('Tests failed');
+    if (result.success) {
+      logger.success('All tests passed successfully');
+      return { success: true };
+    } else {
+      logger.error('Tests failed');
+      return { success: false };
+    }
+  } catch (error) {
+    logger.error(`Test execution error: ${error.message}`);
     return { success: false };
   }
 }

package/scripts/validate-formats.js

@@ -58,70 +58,75 @@ async function validateESMFormat(filePath) {
 }
 
 async function validateFormats() {
-  let allValid = true;
-  const results = [];
-  
-  console.log('📋 ESM Format Compliance Report:');
-  console.log('─'.repeat(80));
-  
-  for (const module of modules) {
-    const esmPath = join(distDir, module.esm);
+  try {
+    let allValid = true;
+    const results = [];
     
-    console.log(`\n📦 Module: ${module.name}`);
+    console.log('📋 ESM Format Compliance Report:');
+    console.log('─'.repeat(80));
     
-    // Validate ESM format
-    if (existsSync(esmPath)) {
-      const esmValidation = await validateESMFormat(esmPath);
-      const esmStatus = esmValidation.valid ? '✅' : '❌';
-      console.log(`  ESM (${module.esm}): ${esmStatus} ${(esmValidation.score * 100).toFixed(0)}% compliant`);
+    for (const module of modules) {
+      const esmPath = join(distDir, module.esm);
+      
+      console.log(`\n📦 Module: ${module.name}`);
       
-      if (!esmValidation.valid) {
-        console.log(`    Issues: ${esmValidation.issues.join(', ')}`);
+      // Validate ESM format
+      if (existsSync(esmPath)) {
+        const esmValidation = await validateESMFormat(esmPath);
+        const esmStatus = esmValidation.valid ? '✅' : '❌';
+        console.log(`  ESM (${module.esm}): ${esmStatus} ${(esmValidation.score * 100).toFixed(0)}% compliant`);
+        
+        if (!esmValidation.valid) {
+          console.log(`    Issues: ${esmValidation.issues.join(', ')}`);
+          allValid = false;
+        }
+        
+        results.push({ module: module.name, format: 'esm', ...esmValidation });
+      } else {
+        console.log(`  ESM (${module.esm}): ❌ File not found`);
         allValid = false;
       }
-      
-      results.push({ module: module.name, format: 'esm', ...esmValidation });
+    }
+    
+    // Summary
+    console.log('\n' + '='.repeat(80));
+    console.log('📊 ESM FORMAT VALIDATION SUMMARY');
+    console.log('='.repeat(80));
+    
+    const totalModules = modules.length;
+    const validESM = results.filter(r => r.format === 'esm' && r.valid).length;
+    
+    console.log(`ESM Format Compliance: ${validESM}/${totalModules} modules ✓`);
+    
+    const averageESMScore = results
+      .filter(r => r.format === 'esm')
+      .reduce((sum, r) => sum + r.score, 0) / totalModules;
+    
+    console.log(`Average ESM Compliance: ${(averageESMScore * 100).toFixed(1)}%`);
+    
+    if (allValid) {
+      console.log('✅ All ESM format validations passed!');
+      console.log('\n🎯 ESM Quality Indicators:');
+      console.log('  ✅ Proper "use client" directives in all modules');
+      console.log('  ✅ Clean ESM export syntax');
+      console.log('  ✅ No CommonJS patterns detected');
+      console.log('  ✅ Optimal for modern bundlers and tree-shaking');
     } else {
-      console.log(`  ESM (${module.esm}): ❌ File not found`);
-      allValid = false;
+      console.log('❌ Some ESM format validations failed!');
+      console.log('\n🔧 Common fixes:');
+      console.log('  - Ensure "use client" directive is present');
+      console.log('  - Use proper ESM export syntax');
+      console.log('  - Remove any CommonJS patterns (require, module.exports)');
+      console.log('  - Check tsup configuration for proper ESM output');
     }
+    
+    console.log('='.repeat(80));
+    
+    return allValid;
+  } catch (error) {
+    console.error('❌ Validation error:', error.message);
+    return false;
   }
-  
-  // Summary
-  console.log('\n' + '='.repeat(80));
-  console.log('📊 ESM FORMAT VALIDATION SUMMARY');
-  console.log('='.repeat(80));
-  
-  const totalModules = modules.length;
-  const validESM = results.filter(r => r.format === 'esm' && r.valid).length;
-  
-  console.log(`ESM Format Compliance: ${validESM}/${totalModules} modules ✓`);
-  
-  const averageESMScore = results
-    .filter(r => r.format === 'esm')
-    .reduce((sum, r) => sum + r.score, 0) / totalModules;
-  
-  console.log(`Average ESM Compliance: ${(averageESMScore * 100).toFixed(1)}%`);
-  
-  if (allValid) {
-    console.log('✅ All ESM format validations passed!');
-    console.log('\n🎯 ESM Quality Indicators:');
-    console.log('  ✅ Proper "use client" directives in all modules');
-    console.log('  ✅ Clean ESM export syntax');
-    console.log('  ✅ No CommonJS patterns detected');
-    console.log('  ✅ Optimal for modern bundlers and tree-shaking');
-  } else {
-    console.log('❌ Some ESM format validations failed!');
-    console.log('\n🔧 Common fixes:');
-    console.log('  - Ensure "use client" directive is present');
-    console.log('  - Use proper ESM export syntax');
-    console.log('  - Remove any CommonJS patterns (require, module.exports)');
-    console.log('  - Check tsup configuration for proper ESM output');
-  }
-  
-  console.log('='.repeat(80));
-  
-  return allValid;
 }
 
 // Run validation

package/scripts/validate-master.js

@@ -49,87 +49,92 @@ async function runStandardizedTestsWrapper() {
 
 // Main validation orchestrator
 async function runValidation(mode = 'standard') {
-  logger.header(`Running ${mode} validation`);
-  if (isCI()) {
-    logger.info('CI environment detected - using extended timeouts and live output');
-    logger.newline();
-  }
-  
-  const results = [];
-  const startTime = Date.now();
-  let criticalFailures = 0;
-  
-  for (const [stepKey, step] of Object.entries(validationSteps)) {
-    // Skip tests in pre-publish mode if configured to do so
-    if (mode === 'pre-publish' && step.skipInPrePublish) {
-      logger.skipped(`Skipping: ${step.name} (skipped in pre-publish mode)...`);
+  try {
+    logger.header(`Running ${mode} validation`);
+    if (isCI()) {
+      logger.info('CI environment detected - using extended timeouts and live output');
+      logger.newline();
+    }
+    
+    const results = [];
+    const startTime = Date.now();
+    let criticalFailures = 0;
+    
+    for (const [stepKey, step] of Object.entries(validationSteps)) {
+      // Skip tests in pre-publish mode if configured to do so
+      if (mode === 'pre-publish' && step.skipInPrePublish) {
+        logger.skipped(`Skipping: ${step.name} (skipped in pre-publish mode)...`);
+        results.push({
+          step: stepKey,
+          name: step.name,
+          success: true,
+          duration: 0,
+          skipped: true
+        });
+        continue;
+      }
+      
+      const stepStartTime = Date.now();
+      logger.step(`Running: ${step.name}...`);
+      
+      const result = step.customHandler
+        ? await step.customHandler()
+        : await runCommand(step.command[0], step.command.slice(1), {
+            cwd: step.cwd || packageRoot,
+            timeout: step.timeout || DEFAULT_TIMEOUT,
+          });
+      
+      const stepDuration = Date.now() - stepStartTime;
+      const status = result.success ? '✅' : '❌';
+      
+      logger.info(`${status} ${step.name} - ${stepDuration}ms`);
+      logger.newline();
+      
       results.push({
         step: stepKey,
         name: step.name,
-        success: true,
-        duration: 0,
-        skipped: true
+        success: result.success,
+        duration: stepDuration,
+        skipped: false
       });
-      continue;
+      
+      if (!result.success) {
+        criticalFailures++;
+      }
     }
     
-    const stepStartTime = Date.now();
-    logger.step(`Running: ${step.name}...`);
+    const totalDuration = Date.now() - startTime;
+    const passedSteps = results.filter(r => r.success).length;
+    const skippedSteps = results.filter(r => r.skipped).length;
     
-    const result = step.customHandler
-      ? await step.customHandler()
-      : await runCommand(step.command[0], step.command.slice(1), {
-          cwd: step.cwd || packageRoot,
-          timeout: step.timeout || DEFAULT_TIMEOUT,
-        });
-    
-    const stepDuration = Date.now() - stepStartTime;
-    const status = result.success ? '✅' : '❌';
-    
-    logger.info(`${status} ${step.name} - ${stepDuration}ms`);
+    // Summary
+    logger.header('VALIDATION SUMMARY');
+    logger.info(`Total steps: ${results.length}`);
+    logger.info(`Passed: ${passedSteps}`);
+    logger.info(`Skipped: ${skippedSteps}`);
+    logger.info(`Failed: ${criticalFailures}`);
+    logger.info(`Total duration: ${totalDuration}ms`);
     logger.newline();
     
-    results.push({
-      step: stepKey,
-      name: step.name,
-      success: result.success,
-      duration: stepDuration,
-      skipped: false
+    logger.info('Step Results:');
+    results.forEach(result => {
+      const status = result.skipped ? '⏭️' : (result.success ? '✅' : '❌');
+      const statusText = result.skipped ? 'skipped' : `${result.duration}ms`;
+      logger.info(`  ${status} ${result.step} - ${statusText}`);
     });
     
-    if (!result.success) {
-      criticalFailures++;
+    logger.newline();
+    logger.separator();
+    
+    if (criticalFailures === 0) {
+      logger.success('All validations passed!');
+      return true;
+    } else {
+      logger.error(`Validation failed! ${criticalFailures} validations failed`);
+      return false;
     }
-  }
-  
-  const totalDuration = Date.now() - startTime;
-  const passedSteps = results.filter(r => r.success).length;
-  const skippedSteps = results.filter(r => r.skipped).length;
-  
-  // Summary
-  logger.header('VALIDATION SUMMARY');
-  logger.info(`Total steps: ${results.length}`);
-  logger.info(`Passed: ${passedSteps}`);
-  logger.info(`Skipped: ${skippedSteps}`);
-  logger.info(`Failed: ${criticalFailures}`);
-  logger.info(`Total duration: ${totalDuration}ms`);
-  logger.newline();
-  
-  logger.info('Step Results:');
-  results.forEach(result => {
-    const status = result.skipped ? '⏭️' : (result.success ? '✅' : '❌');
-    const statusText = result.skipped ? 'skipped' : `${result.duration}ms`;
-    logger.info(`  ${status} ${result.step} - ${statusText}`);
-  });
-  
-  logger.newline();
-  logger.separator();
-  
-  if (criticalFailures === 0) {
-    logger.success('All validations passed!');
-    return true;
-  } else {
-    logger.error(`Validation failed! ${criticalFailures} validations failed`);
+  } catch (error) {
+    logger.error(`Validation error: ${error.message}`);
     return false;
   }
 }