cerber-core 1.0.0

package/solo/scripts/cerber-docs-sync.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+
+/**
+ * Cerber SOLO - Documentation Sync Validator
+ * 
+ * Extends Cerber Core with automation for solo developers
+ * 
+ * Validates:
+ * - Extract API endpoints from code
+ * - Compare with README
+ * - Find ENV vars in code vs docs
+ * - Detect stale documentation
+ * 
+ * @author Stefan Pitek
+ * @copyright 2026 Stefan Pitek
+ * @license MIT
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+console.log('📚 Cerber SOLO - Documentation Sync Validator\n');
+
+const issues = [];
+
+/**
+ * Extract API endpoints from code
+ */
+function extractAPIEndpoints() {
+  console.log('🔍 Extracting API endpoints from code...\n');
+  
+  try {
+    // Find app.get, app.post, router.get, router.post patterns
+    const patterns = [
+      'app\\.get\\(',
+      'app\\.post\\(',
+      'app\\.put\\(',
+      'app\\.delete\\(',
+      'router\\.get\\(',
+      'router\\.post\\(',
+      'router\\.put\\(',
+      'router\\.delete\\('
+    ];
+    
+    const endpoints = new Set();
+    
+    patterns.forEach(pattern => {
+      try {
+        const cmd = `grep -r "${pattern}" --include="*.ts" --include="*.js" . 2>/dev/null || true`;
+        const results = execSync(cmd, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 });
+        
+        if (results) {
+          // Extract endpoint paths
+          const pathRegex = /['"]([\/][^'"]+)['"]/g;
+          let match;
+          while ((match = pathRegex.exec(results)) !== null) {
+            endpoints.add(match[1]);
+          }
+        }
+      } catch (error) {
+        // Continue on error
+      }
+    });
+    
+    if (endpoints.size > 0) {
+      console.log(`  ✅ Found ${endpoints.size} API endpoints in code:`);
+      Array.from(endpoints).slice(0, 10).forEach(endpoint => {
+        console.log(`     ${endpoint}`);
+      });
+      if (endpoints.size > 10) {
+        console.log(`     ... and ${endpoints.size - 10} more`);
+      }
+    } else {
+      console.log('  ℹ️  No API endpoints found in code');
+    }
+    
+    return endpoints;
+  } catch (error) {
+    console.log(`  ⚠️  Error extracting endpoints: ${error.message}`);
+    return new Set();
+  }
+}
+
+/**
+ * Check if endpoints are documented in README
+ */
+function checkEndpointsInReadme(endpoints) {
+  console.log('\n📖 Checking README for endpoint documentation...\n');
+  
+  const readmePath = path.join(process.cwd(), 'README.md');
+  
+  if (!fs.existsSync(readmePath)) {
+    console.log('  ⚠️  No README.md found');
+    issues.push({
+      type: 'missing-readme',
+      severity: 'high',
+      message: 'README.md not found'
+    });
+    return;
+  }
+  
+  try {
+    const readme = fs.readFileSync(readmePath, 'utf8');
+    const undocumented = [];
+    
+    endpoints.forEach(endpoint => {
+      if (!readme.includes(endpoint)) {
+        undocumented.push(endpoint);
+      }
+    });
+    
+    if (undocumented.length > 0) {
+      console.log(`  ⚠️  ${undocumented.length} endpoints not documented in README:`);
+      undocumented.slice(0, 5).forEach(endpoint => {
+        console.log(`     - ${endpoint}`);
+      });
+      if (undocumented.length > 5) {
+        console.log(`     ... and ${undocumented.length - 5} more`);
+      }
+      
+      issues.push({
+        type: 'undocumented-endpoints',
+        severity: 'moderate',
+        message: `${undocumented.length} endpoints missing from README`,
+        endpoints: undocumented
+      });
+    } else if (endpoints.size > 0) {
+      console.log('  ✅ All endpoints are documented in README');
+    }
+  } catch (error) {
+    console.log(`  ❌ Error reading README: ${error.message}`);
+  }
+}
+
+/**
+ * Extract environment variables from code
+ */
+function extractEnvVars() {
+  console.log('\n🔐 Extracting environment variables from code...\n');
+  
+  try {
+    const cmd = `grep -r "process\\.env\\." --include="*.ts" --include="*.js" . 2>/dev/null || true`;
+    const results = execSync(cmd, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 });
+    
+    const envVars = new Set();
+    const envRegex = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+    
+    let match;
+    while ((match = envRegex.exec(results)) !== null) {
+      envVars.add(match[1]);
+    }
+    
+    if (envVars.size > 0) {
+      console.log(`  ✅ Found ${envVars.size} environment variables in code:`);
+      Array.from(envVars).slice(0, 10).forEach(varName => {
+        console.log(`     ${varName}`);
+      });
+      if (envVars.size > 10) {
+        console.log(`     ... and ${envVars.size - 10} more`);
+      }
+    } else {
+      console.log('  ℹ️  No environment variables found');
+    }
+    
+    return envVars;
+  } catch (error) {
+    console.log(`  ⚠️  Error extracting env vars: ${error.message}`);
+    return new Set();
+  }
+}
+
+/**
+ * Check if env vars are documented
+ */
+function checkEnvVarsInDocs(envVars) {
+  console.log('\n📝 Checking environment variable documentation...\n');
+  
+  const readmePath = path.join(process.cwd(), 'README.md');
+  const envExamplePath = path.join(process.cwd(), '.env.example');
+  
+  let readme = '';
+  let envExample = '';
+  
+  if (fs.existsSync(readmePath)) {
+    readme = fs.readFileSync(readmePath, 'utf8');
+  }
+  
+  if (fs.existsSync(envExamplePath)) {
+    envExample = fs.readFileSync(envExamplePath, 'utf8');
+  }
+  
+  const undocumented = [];
+  const missingFromExample = [];
+  
+  envVars.forEach(varName => {
+    if (!readme.includes(varName)) {
+      undocumented.push(varName);
+    }
+    if (!envExample.includes(varName)) {
+      missingFromExample.push(varName);
+    }
+  });
+  
+  if (undocumented.length > 0) {
+    console.log(`  ⚠️  ${undocumented.length} env vars not in README:`);
+    undocumented.slice(0, 5).forEach(varName => {
+      console.log(`     - ${varName}`);
+    });
+    if (undocumented.length > 5) {
+      console.log(`     ... and ${undocumented.length - 5} more`);
+    }
+    
+    issues.push({
+      type: 'undocumented-env-vars',
+      severity: 'low',
+      message: `${undocumented.length} env vars not documented`,
+      vars: undocumented
+    });
+  }
+  
+  if (missingFromExample.length > 0) {
+    console.log(`\n  ⚠️  ${missingFromExample.length} env vars not in .env.example:`);
+    missingFromExample.slice(0, 5).forEach(varName => {
+      console.log(`     - ${varName}`);
+    });
+    if (missingFromExample.length > 5) {
+      console.log(`     ... and ${missingFromExample.length - 5} more`);
+    }
+    
+    issues.push({
+      type: 'missing-env-example',
+      severity: 'moderate',
+      message: `${missingFromExample.length} env vars not in .env.example`,
+      vars: missingFromExample
+    });
+  }
+  
+  if (undocumented.length === 0 && missingFromExample.length === 0 && envVars.size > 0) {
+    console.log('  ✅ All env vars are documented');
+  }
+}
+
+/**
+ * Check for TODO and FIXME comments
+ */
+function checkTodoComments() {
+  console.log('\n📌 Checking for TODO/FIXME comments...\n');
+  
+  try {
+    const cmd = `grep -rn "TODO\\|FIXME" --include="*.ts" --include="*.js" --include="*.md" . 2>/dev/null || true`;
+    const results = execSync(cmd, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 });
+    
+    if (results) {
+      const lines = results.split('\n').filter(line => line.trim());
+      console.log(`  ℹ️  Found ${lines.length} TODO/FIXME comments:`);
+      lines.slice(0, 5).forEach(line => {
+        console.log(`     ${line.substring(0, 80)}${line.length > 80 ? '...' : ''}`);
+      });
+      if (lines.length > 5) {
+        console.log(`     ... and ${lines.length - 5} more`);
+      }
+    } else {
+      console.log('  ✅ No TODO/FIXME comments found');
+    }
+  } catch (error) {
+    // Continue on error
+  }
+}
+
+// Run all checks
+const endpoints = extractAPIEndpoints();
+checkEndpointsInReadme(endpoints);
+
+const envVars = extractEnvVars();
+checkEnvVarsInDocs(envVars);
+
+checkTodoComments();
+
+// Summary
+console.log('\n' + '='.repeat(60));
+
+if (issues.length > 0) {
+  console.log('\n📋 Documentation Sync Report\n');
+  console.log(`Issues found: ${issues.length}\n`);
+  
+  issues.forEach((issue, idx) => {
+    const severityEmoji = issue.severity === 'high' ? '🔴' : 
+                          issue.severity === 'moderate' ? '🟡' : '🔵';
+    console.log(`${idx + 1}. ${severityEmoji} [${issue.severity.toUpperCase()}] ${issue.message}`);
+  });
+  
+  console.log('\n💡 Recommended Actions:');
+  console.log('   1. Update README.md with missing endpoints');
+  console.log('   2. Add missing vars to .env.example');
+  console.log('   3. Document environment variables');
+  console.log('   4. Run: npm run cerber:repair (to auto-sync .env.example)');
+} else {
+  console.log('\n✅ Documentation is in sync!\n');
+}
+
+console.log('\n' + '='.repeat(60));
+
+process.exit(issues.length > 0 ? 1 : 0);

package/solo/scripts/cerber-flags-check.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+/**
+ * Cerber SOLO - Feature Flags Checker
+ * 
+ * Extends Cerber Core with automation for solo developers
+ * 
+ * Features:
+ * - List active flags
+ * - Detect expired flags
+ * - Per-environment status
+ * - Cleanup suggestions
+ * 
+ * @author Stefan Pitek
+ * @copyright 2026 Stefan Pitek
+ * @license MIT
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+console.log('🚩 Cerber SOLO - Feature Flags Checker\n');
+
+/**
+ * Find feature flag files
+ */
+function findFeatureFlagFiles() {
+  const possiblePaths = [
+    'solo/lib/feature-flags.ts',
+    'src/lib/feature-flags.ts',
+    'lib/feature-flags.ts',
+    'src/config/feature-flags.ts',
+    'config/feature-flags.ts',
+    'src/features/flags.ts'
+  ];
+  
+  const found = [];
+  
+  possiblePaths.forEach(p => {
+    const fullPath = path.join(process.cwd(), p);
+    if (fs.existsSync(fullPath)) {
+      found.push(fullPath);
+    }
+  });
+  
+  return found;
+}
+
+/**
+ * Parse feature flags from file
+ */
+function parseFeatureFlags(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const flags = [];
+    
+    // Look for flag definitions (simplified parsing)
+    const flagRegex = /['"]([a-z-_]+)['"]\s*:\s*{[\s\S]*?enabled:\s*(true|false)[\s\S]*?}/gi;
+    let match;
+    
+    while ((match = flagRegex.exec(content)) !== null) {
+      flags.push({
+        name: match[1],
+        enabled: match[2] === 'true',
+        source: filePath
+      });
+    }
+    
+    // Also look for simple boolean flags
+    const simpleFlagRegex = /export\s+const\s+([A-Z_]+)\s*=\s*(true|false)/gi;
+    
+    while ((match = simpleFlagRegex.exec(content)) !== null) {
+      flags.push({
+        name: match[1],
+        enabled: match[2] === 'true',
+        source: filePath
+      });
+    }
+    
+    return flags;
+  } catch (error) {
+    console.log(`⚠️  Error parsing ${filePath}: ${error.message}`);
+    return [];
+  }
+}
+
+/**
+ * Check for expired flags
+ */
+function checkExpiredFlags(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const expired = [];
+    
+    // Look for expiresAt dates
+    const expiryRegex = /expiresAt:\s*['"](\d{4}-\d{2}-\d{2})['"]/g;
+    let match;
+    
+    const now = new Date();
+    
+    while ((match = expiryRegex.exec(content)) !== null) {
+      const expiryDate = new Date(match[1]);
+      
+      if (expiryDate < now) {
+        // Find flag name near this expiry
+        const before = content.substring(Math.max(0, match.index - 200), match.index);
+        const nameMatch = before.match(/['"]([a-z-_]+)['"]\s*:\s*{[^}]*$/i);
+        
+        if (nameMatch) {
+          expired.push({
+            name: nameMatch[1],
+            expiryDate: match[1]
+          });
+        }
+      }
+    }
+    
+    return expired;
+  } catch (error) {
+    return [];
+  }
+}
+
+/**
+ * Find flag usage in codebase
+ */
+function findFlagUsage(flagName) {
+  try {
+    const { execSync } = require('child_process');
+    const cmd = `grep -r "${flagName}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" . 2>/dev/null | wc -l`;
+    const count = parseInt(execSync(cmd, { encoding: 'utf8' }).trim());
+    return count;
+  } catch (error) {
+    return 0;
+  }
+}
+
+// Find and analyze feature flags
+const flagFiles = findFeatureFlagFiles();
+
+if (flagFiles.length === 0) {
+  console.log('ℹ️  No feature flag files found\n');
+  console.log('Expected locations:');
+  console.log('  - solo/lib/feature-flags.ts');
+  console.log('  - src/lib/feature-flags.ts');
+  console.log('  - src/config/feature-flags.ts\n');
+  console.log('💡 Create feature-flags.ts to use this checker');
+  process.exit(0);
+}
+
+console.log(`📁 Found ${flagFiles.length} feature flag file(s):\n`);
+
+let totalFlags = 0;
+let enabledFlags = 0;
+let disabledFlags = 0;
+let allExpiredFlags = [];
+
+flagFiles.forEach(file => {
+  const relativePath = path.relative(process.cwd(), file);
+  console.log(`   ${relativePath}`);
+  
+  const flags = parseFeatureFlags(file);
+  const expired = checkExpiredFlags(file);
+  
+  totalFlags += flags.length;
+  
+  flags.forEach(flag => {
+    if (flag.enabled) {
+      enabledFlags++;
+    } else {
+      disabledFlags++;
+    }
+  });
+  
+  allExpiredFlags = allExpiredFlags.concat(expired);
+});
+
+console.log();
+
+if (totalFlags === 0) {
+  console.log('ℹ️  No feature flags detected in files\n');
+  console.log('💡 Define flags in your feature-flags.ts file:\n');
+  console.log('   export const FLAGS = {');
+  console.log('     "new-feature": { enabled: true, description: "..." },');
+  console.log('     "beta-ui": { enabled: false, description: "..." }');
+  console.log('   };\n');
+  process.exit(0);
+}
+
+// Summary
+console.log('📊 Feature Flags Summary\n');
+console.log(`   Total flags: ${totalFlags}`);
+console.log(`   ✅ Enabled: ${enabledFlags}`);
+console.log(`   ❌ Disabled: ${disabledFlags}\n`);
+
+// Expired flags
+if (allExpiredFlags.length > 0) {
+  console.log('⏰ Expired Flags (cleanup recommended)\n');
+  allExpiredFlags.forEach(flag => {
+    console.log(`   🔴 ${flag.name} (expired: ${flag.expiryDate})`);
+  });
+  console.log();
+}
+
+// Environment detection
+console.log('🌍 Environment Detection\n');
+const env = process.env.NODE_ENV || 'development';
+console.log(`   Current environment: ${env}\n`);
+
+// Recommendations
+console.log('💡 Recommendations\n');
+
+if (allExpiredFlags.length > 0) {
+  console.log('   1. Remove expired feature flags from code');
+  console.log('   2. Clean up flag-related code branches');
+}
+
+if (disabledFlags > enabledFlags * 2) {
+  console.log('   3. Review disabled flags - can any be removed?');
+}
+
+if (totalFlags > 20) {
+  console.log('   4. Consider flag cleanup - you have many flags');
+}
+
+console.log();
+console.log('='.repeat(60));
+
+process.exit(allExpiredFlags.length > 0 ? 1 : 0);