claude-cli-advanced-starter-pack 1.0.0

package/src/utils/template-engine.js

@@ -0,0 +1,398 @@
+/**
+ * Template Engine
+ *
+ * Handles placeholder replacement in .claude files using tech-stack.json values.
+ * Supports:
+ * - Nested property access: {{frontend.port}}, {{deployment.backend.platform}}
+ * - Conditional blocks: {{#if condition}}...{{/if}}
+ * - Equality checks: {{#if (eq path "value")}}...{{/if}}
+ * - Else blocks: {{#if condition}}...{{else}}...{{/if}}
+ * - Each loops: {{#each array}}{{this}}{{/each}}
+ * - Path variables: ${CWD}, ${HOME}
+ */
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'fs';
+import { join, extname } from 'path';
+import { homedir } from 'os';
+
+/**
+ * Get nested property from object using dot notation
+ * @param {object} obj - The object to search
+ * @param {string} path - Dot-notated path (e.g., "frontend.port")
+ * @returns {*} The value or undefined
+ */
+function getNestedValue(obj, path) {
+  return path.split('.').reduce((current, key) => {
+    return current && current[key] !== undefined ? current[key] : undefined;
+  }, obj);
+}
+
+/**
+ * Evaluate a condition expression
+ * @param {string} condition - The condition to evaluate
+ * @param {object} values - Tech stack values
+ * @returns {boolean} Whether the condition is truthy
+ */
+function evaluateCondition(condition, values) {
+  const trimmed = condition.trim();
+
+  // Handle (eq path "value") syntax
+  const eqMatch = trimmed.match(/^\(eq\s+([^\s]+)\s+["']([^"']+)["']\)$/);
+  if (eqMatch) {
+    const [, path, expected] = eqMatch;
+    const actual = getNestedValue(values, path);
+    return actual === expected;
+  }
+
+  // Handle (neq path "value") syntax
+  const neqMatch = trimmed.match(/^\(neq\s+([^\s]+)\s+["']([^"']+)["']\)$/);
+  if (neqMatch) {
+    const [, path, expected] = neqMatch;
+    const actual = getNestedValue(values, path);
+    return actual !== expected;
+  }
+
+  // Handle (not path) syntax
+  const notMatch = trimmed.match(/^\(not\s+([^\s]+)\)$/);
+  if (notMatch) {
+    const [, path] = notMatch;
+    const value = getNestedValue(values, path);
+    return !value;
+  }
+
+  // Handle (and condition1 condition2) syntax
+  const andMatch = trimmed.match(/^\(and\s+(.+)\s+(.+)\)$/);
+  if (andMatch) {
+    const [, cond1, cond2] = andMatch;
+    return evaluateCondition(cond1, values) && evaluateCondition(cond2, values);
+  }
+
+  // Handle (or condition1 condition2) syntax
+  const orMatch = trimmed.match(/^\(or\s+(.+)\s+(.+)\)$/);
+  if (orMatch) {
+    const [, cond1, cond2] = orMatch;
+    return evaluateCondition(cond1, values) || evaluateCondition(cond2, values);
+  }
+
+  // Simple path - check if value is truthy
+  const value = getNestedValue(values, trimmed);
+  return !!value && value !== 'none' && value !== '';
+}
+
+/**
+ * Process {{#each array}}...{{/each}} blocks
+ * @param {string} content - Content with each blocks
+ * @param {object} values - Tech stack values
+ * @returns {string} Processed content
+ */
+function processEachBlocks(content, values) {
+  // Match {{#each path}}content{{/each}}
+  const eachRegex = /\{\{#each\s+([^\}]+)\}\}([\s\S]*?)\{\{\/each\}\}/g;
+
+  return content.replace(eachRegex, (match, path, innerContent) => {
+    const array = getNestedValue(values, path.trim());
+
+    if (!Array.isArray(array) || array.length === 0) {
+      return '';
+    }
+
+    return array
+      .map((item, index) => {
+        let result = innerContent;
+        // Replace {{this}} with current item
+        result = result.replace(/\{\{this\}\}/g, String(item));
+        // Replace {{@index}} with current index
+        result = result.replace(/\{\{@index\}\}/g, String(index));
+        // Replace {{@first}} with boolean
+        result = result.replace(/\{\{@first\}\}/g, String(index === 0));
+        // Replace {{@last}} with boolean
+        result = result.replace(/\{\{@last\}\}/g, String(index === array.length - 1));
+        return result;
+      })
+      .join('');
+  });
+}
+
+/**
+ * Process {{#if condition}}...{{else}}...{{/if}} blocks
+ * @param {string} content - Content with conditional blocks
+ * @param {object} values - Tech stack values
+ * @returns {string} Processed content
+ */
+function processConditionalBlocks(content, values) {
+  // Process from innermost to outermost to handle nested conditionals
+  let result = content;
+  let previousResult;
+
+  // Keep processing until no more changes (handles nested blocks)
+  do {
+    previousResult = result;
+
+    // Match {{#if condition}}...{{else}}...{{/if}} or {{#if condition}}...{{/if}}
+    // Non-greedy match for innermost blocks first
+    const ifElseRegex = /\{\{#if\s+([^\}]+)\}\}([\s\S]*?)\{\{else\}\}([\s\S]*?)\{\{\/if\}\}/g;
+    const ifOnlyRegex = /\{\{#if\s+([^\}]+)\}\}([\s\S]*?)\{\{\/if\}\}/g;
+
+    // First handle if-else blocks
+    result = result.replace(ifElseRegex, (match, condition, ifContent, elseContent) => {
+      const isTruthy = evaluateCondition(condition, values);
+      return isTruthy ? ifContent : elseContent;
+    });
+
+    // Then handle if-only blocks (no else)
+    result = result.replace(ifOnlyRegex, (match, condition, ifContent) => {
+      const isTruthy = evaluateCondition(condition, values);
+      return isTruthy ? ifContent : '';
+    });
+  } while (result !== previousResult);
+
+  return result;
+}
+
+/**
+ * Process path variables like ${CWD} and ${HOME}
+ * @param {string} content - Content with path variables
+ * @returns {string} Content with paths resolved
+ */
+function processPathVariables(content) {
+  return content
+    .replace(/\$\{CWD\}/g, process.cwd())
+    .replace(/\$\{HOME\}/g, homedir())
+    .replace(/\$\{CLAUDE_DIR\}/g, join(process.cwd(), '.claude'));
+}
+
+/**
+ * Replace all placeholders in a string
+ * @param {string} content - Content with {{placeholder}} patterns
+ * @param {object} values - Tech stack values object
+ * @param {object} options - Options for replacement
+ * @returns {string} Content with placeholders replaced
+ */
+export function replacePlaceholders(content, values, options = {}) {
+  const { preserveUnknown = false, warnOnMissing = true, processConditionals = true } = options;
+  const warnings = [];
+
+  let result = content;
+
+  // Step 1: Process path variables (${CWD}, ${HOME}, etc.)
+  result = processPathVariables(result);
+
+  // Step 2: Process {{#each}} blocks
+  result = processEachBlocks(result, values);
+
+  // Step 3: Process {{#if}}...{{/if}} conditional blocks
+  if (processConditionals) {
+    result = processConditionalBlocks(result, values);
+  }
+
+  // Step 4: Replace simple {{path.to.value}} placeholders
+  result = result.replace(/\{\{([^#\/][^}]*)\}\}/g, (match, path) => {
+    const trimmedPath = path.trim();
+
+    // Skip special syntax that wasn't processed
+    if (trimmedPath.startsWith('#') || trimmedPath.startsWith('/') || trimmedPath.startsWith('@')) {
+      return match;
+    }
+
+    const value = getNestedValue(values, trimmedPath);
+
+    if (value === undefined || value === null || value === '') {
+      if (warnOnMissing && !trimmedPath.includes('PLACEHOLDER')) {
+        warnings.push(`Missing value for: ${trimmedPath}`);
+      }
+      return preserveUnknown ? match : `{{${trimmedPath}}}`; // Keep placeholder
+    }
+
+    // Handle arrays
+    if (Array.isArray(value)) {
+      return value.join(', ');
+    }
+
+    // Handle objects - return JSON
+    if (typeof value === 'object') {
+      return JSON.stringify(value, null, 2);
+    }
+
+    return String(value);
+  });
+
+  return { content: result, warnings };
+}
+
+/**
+ * Process a single file
+ * @param {string} filePath - Path to the file
+ * @param {object} values - Tech stack values
+ * @param {object} options - Processing options
+ * @returns {object} Result with stats
+ */
+export function processFile(filePath, values, options = {}) {
+  const { dryRun = false, verbose = false } = options;
+
+  const originalContent = readFileSync(filePath, 'utf8');
+  const { content: newContent, warnings } = replacePlaceholders(originalContent, values, options);
+
+  const placeholderCount = (originalContent.match(/\{\{[^}]+\}\}/g) || []).length;
+  const replacedCount = placeholderCount - (newContent.match(/\{\{[^}]+\}\}/g) || []).length;
+
+  const result = {
+    file: filePath,
+    placeholders: placeholderCount,
+    replaced: replacedCount,
+    remaining: placeholderCount - replacedCount,
+    warnings,
+    changed: originalContent !== newContent,
+  };
+
+  if (!dryRun && result.changed) {
+    writeFileSync(filePath, newContent, 'utf8');
+  }
+
+  return result;
+}
+
+/**
+ * Process all template files in a directory
+ * @param {string} dirPath - Directory path
+ * @param {object} values - Tech stack values
+ * @param {object} options - Processing options
+ * @returns {object[]} Array of results
+ */
+export function processDirectory(dirPath, values, options = {}) {
+  const {
+    extensions = ['.md', '.json', '.js', '.ts', '.yml', '.yaml'],
+    recursive = true,
+    exclude = ['node_modules', '.git', 'dist', 'build'],
+  } = options;
+
+  const results = [];
+
+  function walkDir(dir) {
+    const entries = readdirSync(dir);
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+
+      // Skip excluded directories
+      if (exclude.includes(entry)) continue;
+
+      const stat = statSync(fullPath);
+
+      if (stat.isDirectory() && recursive) {
+        walkDir(fullPath);
+      } else if (stat.isFile()) {
+        const ext = extname(entry);
+        if (extensions.includes(ext)) {
+          results.push(processFile(fullPath, values, options));
+        }
+      }
+    }
+  }
+
+  walkDir(dirPath);
+  return results;
+}
+
+/**
+ * Generate a tech-stack.json from detected values
+ * @param {object} detected - Detected tech stack
+ * @param {object} userOverrides - User-provided overrides
+ * @returns {object} Merged tech stack
+ */
+export function generateTechStack(detected, userOverrides = {}) {
+  // Deep merge function
+  function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+      if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+        result[key] = deepMerge(result[key] || {}, source[key]);
+      } else if (source[key] !== undefined && source[key] !== null) {
+        result[key] = source[key];
+      }
+    }
+    return result;
+  }
+
+  return deepMerge(detected, userOverrides);
+}
+
+/**
+ * Flatten nested object to dot-notation keys
+ * @param {object} obj - Object to flatten
+ * @param {string} prefix - Current key prefix
+ * @returns {object} Flattened object
+ */
+export function flattenObject(obj, prefix = '') {
+  const result = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    const newKey = prefix ? `${prefix}.${key}` : key;
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      Object.assign(result, flattenObject(value, newKey));
+    } else {
+      result[newKey] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get all unique placeholders from content
+ * @param {string} content - Content to scan
+ * @returns {string[]} Array of placeholder paths
+ */
+export function extractPlaceholders(content) {
+  const matches = content.match(/\{\{([^}]+)\}\}/g) || [];
+  const placeholders = matches.map((m) => m.replace(/\{\{|\}\}/g, '').trim());
+  return [...new Set(placeholders)];
+}
+
+/**
+ * Validate a tech-stack.json against required placeholders
+ * @param {object} techStack - Tech stack values
+ * @param {string[]} requiredPlaceholders - Required placeholder paths
+ * @returns {object} Validation result
+ */
+export function validateTechStack(techStack, requiredPlaceholders) {
+  const missing = [];
+  const present = [];
+
+  for (const placeholder of requiredPlaceholders) {
+    const value = getNestedValue(techStack, placeholder);
+    if (value === undefined || value === null || value === '') {
+      missing.push(placeholder);
+    } else {
+      present.push(placeholder);
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    present,
+    coverage: present.length / requiredPlaceholders.length,
+  };
+}
+
+export {
+  evaluateCondition,
+  processConditionalBlocks,
+  processEachBlocks,
+  processPathVariables,
+};
+
+export default {
+  replacePlaceholders,
+  processFile,
+  processDirectory,
+  generateTechStack,
+  flattenObject,
+  extractPlaceholders,
+  validateTechStack,
+  evaluateCondition,
+  processConditionalBlocks,
+  processEachBlocks,
+  processPathVariables,
+};

package/src/utils/validate-templates.js

@@ -0,0 +1,223 @@
+/**
+ * Template Validation Scanner
+ *
+ * Scans template files for hardcoded values that should be parameterized.
+ * Ensures 100% platform agnosticism by detecting project-specific values.
+ */
+
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+import chalk from 'chalk';
+
+/**
+ * Forbidden patterns - hardcoded values that should never appear in templates
+ * These are examples of project-specific values that must use placeholders
+ */
+const FORBIDDEN_PATTERNS = [
+  // Railway IDs (example patterns)
+  { pattern: /[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/g, name: 'UUID (potential service/project ID)' },
+
+  // Hardcoded ngrok usage without conditional
+  { pattern: /ngrok\s+http\s+\d+(?!\s*\}\})/g, name: 'Hardcoded ngrok command' },
+
+  // Specific project names that look hardcoded
+  { pattern: /--project-name=[a-z][a-z0-9-]+(?![\s]*\}\})/g, name: 'Hardcoded project name' },
+
+  // Hardcoded GitHub usernames/orgs (not in placeholders)
+  { pattern: /--owner\s+[a-zA-Z][a-zA-Z0-9-]+(?!\s*\}\})/g, name: 'Hardcoded GitHub owner' },
+
+  // Hardcoded API keys (patterns)
+  { pattern: /dev-key-[a-z0-9]+/gi, name: 'Hardcoded API key' },
+  { pattern: /api[_-]?key["\s:=]+[a-zA-Z0-9_-]{20,}/gi, name: 'Potential API key' },
+
+  // Hardcoded ports that should be configurable
+  { pattern: /localhost:\d{4}(?!\s*\}\})/g, name: 'Hardcoded localhost port' },
+
+  // Hardcoded URLs that look project-specific
+  { pattern: /https?:\/\/[a-z0-9-]+\.(railway|vercel|netlify)\.app/gi, name: 'Hardcoded deployment URL' },
+
+  // Specific SSH hosts
+  { pattern: /ssh\s+[a-z]+@\d+\.\d+\.\d+\.\d+/g, name: 'Hardcoded SSH host' },
+
+  // Hardcoded email addresses
+  { pattern: /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}(?!\s*\}\})/gi, name: 'Hardcoded email address' },
+];
+
+/**
+ * Allowed patterns - these are OK even if they match forbidden patterns
+ */
+const ALLOWED_PATTERNS = [
+  // Template placeholders
+  /\{\{[^}]+\}\}/g,
+
+  // Documentation examples marked as such
+  /<example>[\s\S]*?<\/example>/g,
+
+  // Code comments explaining placeholders
+  /\/\/.*placeholder/gi,
+  /\/\*[\s\S]*?placeholder[\s\S]*?\*\//gi,
+
+  // Generic localhost for documentation
+  /localhost:5173|localhost:8000|localhost:3000/g,
+
+  // Schema URLs
+  /https:\/\/json-schema\.org/g,
+  /https:\/\/github\.com\/[^/]+\/[^/]+\/tech-stack\.schema/g,
+];
+
+/**
+ * Check if a match is within an allowed context
+ */
+function isInAllowedContext(content, matchIndex, matchLength) {
+  // Get surrounding context
+  const start = Math.max(0, matchIndex - 50);
+  const end = Math.min(content.length, matchIndex + matchLength + 50);
+  const context = content.substring(start, end);
+
+  // Check if it's inside a placeholder
+  const beforeMatch = content.substring(Math.max(0, matchIndex - 10), matchIndex);
+  const afterMatch = content.substring(matchIndex + matchLength, Math.min(content.length, matchIndex + matchLength + 10));
+
+  if (beforeMatch.includes('{{') && afterMatch.includes('}}')) {
+    return true;
+  }
+
+  // Check if it's in a conditional block with placeholders
+  if (context.includes('{{#if') || context.includes('{{deployment.') || context.includes('{{versionControl.')) {
+    return true;
+  }
+
+  // Check if it's marked as an example
+  if (context.toLowerCase().includes('example') || context.includes('<placeholder>')) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Scan a single file for forbidden patterns
+ */
+export function scanFile(filePath) {
+  const content = readFileSync(filePath, 'utf8');
+  const violations = [];
+
+  for (const { pattern, name } of FORBIDDEN_PATTERNS) {
+    // Reset regex
+    pattern.lastIndex = 0;
+
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      // Check if this match is in an allowed context
+      if (!isInAllowedContext(content, match.index, match[0].length)) {
+        // Get line number
+        const lineNumber = content.substring(0, match.index).split('\n').length;
+
+        violations.push({
+          file: filePath,
+          line: lineNumber,
+          match: match[0],
+          pattern: name,
+          context: content.substring(
+            Math.max(0, match.index - 20),
+            Math.min(content.length, match.index + match[0].length + 20)
+          ).replace(/\n/g, '\\n'),
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Scan all template files in a directory
+ */
+export function scanDirectory(dirPath, options = {}) {
+  const {
+    extensions = ['.md', '.js', '.ts', '.json', '.yml', '.yaml'],
+    exclude = ['node_modules', '.git', 'dist', 'build'],
+    recursive = true,
+  } = options;
+
+  const violations = [];
+
+  function walkDir(dir) {
+    const entries = readdirSync(dir);
+
+    for (const entry of entries) {
+      if (exclude.includes(entry)) continue;
+
+      const fullPath = join(dir, entry);
+      const stat = statSync(fullPath);
+
+      if (stat.isDirectory() && recursive) {
+        walkDir(fullPath);
+      } else if (stat.isFile()) {
+        const ext = extname(entry);
+        if (extensions.includes(ext)) {
+          violations.push(...scanFile(fullPath));
+        }
+      }
+    }
+  }
+
+  walkDir(dirPath);
+  return violations;
+}
+
+/**
+ * Format violations for display
+ */
+export function formatViolations(violations) {
+  if (violations.length === 0) {
+    return chalk.green('✓ No hardcoded values detected');
+  }
+
+  let output = chalk.red(`\n✗ Found ${violations.length} potential hardcoded value(s):\n\n`);
+
+  // Group by file
+  const byFile = {};
+  for (const v of violations) {
+    if (!byFile[v.file]) byFile[v.file] = [];
+    byFile[v.file].push(v);
+  }
+
+  for (const [file, fileViolations] of Object.entries(byFile)) {
+    output += chalk.yellow(`  ${file}\n`);
+
+    for (const v of fileViolations) {
+      output += chalk.dim(`    Line ${v.line}: `) + chalk.red(v.pattern) + '\n';
+      output += chalk.dim(`      Match: "${v.match}"\n`);
+      output += chalk.dim(`      Context: ...${v.context}...\n`);
+      output += '\n';
+    }
+  }
+
+  output += chalk.dim('\nSuggestion: Replace hardcoded values with {{placeholder}} syntax.\n');
+  output += chalk.dim('Example: --project-name={{deployment.frontend.projectName}}\n');
+
+  return output;
+}
+
+/**
+ * Run validation as CLI tool
+ */
+export async function runValidation(targetPath) {
+  console.log(chalk.cyan('Template Validation Scanner'));
+  console.log(chalk.dim('Checking for hardcoded values...\n'));
+
+  const violations = scanDirectory(targetPath);
+
+  console.log(formatViolations(violations));
+
+  return violations.length === 0;
+}
+
+export default {
+  scanFile,
+  scanDirectory,
+  formatViolations,
+  runValidation,
+  FORBIDDEN_PATTERNS,
+};