scc-universal 1.1.0

package/scripts/hooks/pre-tool-use.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * pre-tool-use.js — PreToolUse hook for SCC.
+ *
+ * Reads the tool use event from stdin (JSON) and:
+ *   1. Warns if deprecated `sfdx` commands are used (suggest `sf` equivalent)
+ *   2. Warns about dangerous org operations (delete, reset, deploy to prod)
+ *
+ * Claude Code sends hook input as JSON on stdin:
+ * { tool_name: "Bash", tool_input: { command: "..." } }
+ */
+
+const readline = require('readline');
+
+// Map of deprecated sfdx commands to their sf equivalents
+const SFDX_MIGRATION_MAP = {
+  'sfdx force:apex:execute': 'sf apex run',
+  'sfdx force:apex:test:run': 'sf apex run test',
+  'sfdx force:apex:class:create': 'sf apex generate class',
+  'sfdx force:lightning:component:create': 'sf lightning generate component',
+  'sfdx force:source:deploy': 'sf project deploy start',
+  'sfdx force:source:retrieve': 'sf project retrieve start',
+  'sfdx force:source:push': 'sf project deploy start',
+  'sfdx force:source:pull': 'sf project retrieve start',
+  'sfdx force:org:create': 'sf org create scratch',
+  'sfdx force:org:delete': 'sf org delete scratch',
+  'sfdx force:org:list': 'sf org list',
+  'sfdx force:org:open': 'sf org open',
+  'sfdx force:data:query': 'sf data query',
+  'sfdx force:data:record:create': 'sf data create record',
+  'sfdx force:data:record:update': 'sf data update record',
+  'sfdx force:data:record:delete': 'sf data delete record',
+  'sfdx force:data:bulk:upsert': 'sf data upsert bulk',
+  'sfdx force:package:create': 'sf package create',
+  'sfdx force:package:version:create': 'sf package version create',
+  'sfdx force:user:create': 'sf org create user',
+  'sfdx force:user:password:generate': 'sf org generate password',
+};
+
+// Patterns for dangerous operations
+const DANGEROUS_PATTERNS = [
+  {
+    pattern: /sfdx force:org:delete|sf org delete/,
+    warning: 'This will permanently delete a Salesforce org. Ensure you have selected the correct org.',
+  },
+  {
+    pattern: /--target-org\s+\S*(prod|production|prd)\S*/i,
+    warning: 'This command targets a PRODUCTION org. Double-check before proceeding.',
+  },
+  {
+    pattern: /-u\s+\S*(prod|production|prd)\S*/i,
+    warning: 'This command targets what appears to be a PRODUCTION org alias.',
+  },
+  {
+    pattern: /sf project deploy start.*--target-org\s+\S*(prod|production|prd)\S*/i,
+    warning: 'Deploying to PRODUCTION. Ensure all tests pass and you have approval.',
+  },
+  {
+    pattern: /sfdx force:data:bulk:delete|sf data delete bulk/,
+    warning: 'Bulk delete operation detected. This will permanently delete records.',
+  },
+  {
+    pattern: /sf org reset|sfdx force:org:reset/,
+    warning: 'Org reset will remove all source tracking history.',
+  },
+  {
+    pattern: /--no-track-source/,
+    warning: 'Deploying without source tracking. Changes may not be reflected in local source.',
+  },
+];
+
+function checkSfdxDeprecation(command) {
+  const warnings = [];
+  for (const [deprecated, replacement] of Object.entries(SFDX_MIGRATION_MAP)) {
+    if (command.includes(deprecated)) {
+      warnings.push({
+        type: 'deprecation',
+        message: `Deprecated command detected: \`${deprecated}\``,
+        suggestion: `Use the new SF CLI equivalent: \`${replacement}\``,
+        docs: 'https://developer.salesforce.com/tools/salesforcecli/migration',
+      });
+    }
+  }
+  return warnings;
+}
+
+function checkDangerousOps(command) {
+  const warnings = [];
+  for (const { pattern, warning } of DANGEROUS_PATTERNS) {
+    if (pattern.test(command)) {
+      warnings.push({
+        type: 'danger',
+        message: warning,
+      });
+    }
+  }
+  return warnings;
+}
+
+function processInput(input) {
+  // Only process Bash tool
+  if (input.tool_name !== 'Bash' && input.tool_name !== 'bash') {
+    return null;
+  }
+
+  const command = (input.tool_input && input.tool_input.command) || '';
+  if (!command) return null;
+
+  // Skip if command doesn't involve SF/SFDX
+  if (!command.includes('sfdx') && !command.includes('sf ') && !command.includes('sf\n')) {
+    return null;
+  }
+
+  const deprecationWarnings = checkSfdxDeprecation(command);
+  const dangerWarnings = checkDangerousOps(command);
+  const allWarnings = [...deprecationWarnings, ...dangerWarnings];
+
+  if (allWarnings.length === 0) return null;
+
+  return allWarnings;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+// Read JSON from stdin
+let rawInput = '';
+
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', line => { rawInput += line + '\n'; });
+
+rl.on('close', () => {
+  let input = {};
+  try {
+    input = JSON.parse(rawInput.trim() || '{}');
+  } catch {
+    // Not valid JSON — exit gracefully
+    process.exit(0);
+  }
+
+  const warnings = processInput(input);
+
+  if (!warnings || warnings.length === 0) {
+    process.exit(0);
+  }
+
+  // Print warnings to stderr (visible in Claude Code output)
+  console.error('\n[SCC Hook] Salesforce CLI Warnings:');
+  for (const w of warnings) {
+    if (w.type === 'deprecation') {
+      console.error(`  DEPRECATED : ${w.message}`);
+      console.error(`  MIGRATE TO : ${w.suggestion}`);
+      if (w.docs) console.error(`  DOCS       : ${w.docs}`);
+    } else if (w.type === 'danger') {
+      console.error(`  WARNING    : ${w.message}`);
+    }
+    console.error();
+  }
+
+  // Exit 0 to allow the tool use to proceed (we're just warning, not blocking)
+  process.exit(0);
+});

package/scripts/hooks/pre-write-doc-warn.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Backward-compatible doc warning hook entrypoint.
+ * Kept for consumers that still reference pre-write-doc-warn.js directly.
+ */
+
+'use strict';
+
+require('./doc-file-warning.js');

package/scripts/hooks/quality-gate.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * Quality Gate Hook
+ *
+ * Runs lightweight quality checks after file edits.
+ * For Apex files: checks for common anti-patterns using shared apex-analysis module.
+ * For LWC files: checks for common issues.
+ * Falls back to no-op when file type is unrecognized.
+ *
+ * Uses apex-analysis.js for:
+ * - Comment/string stripping (eliminates false positives)
+ * - Loop depth tracking (activeLoopDepths stack + globalBraceDepth)
+ * - Test class detection
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { preprocessApex, isTestClass, trackLoopDepth } = require('../lib/apex-analysis');
+
+const MAX_STDIN = 1024 * 1024;
+
+function log(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+
+/**
+ * Check Apex file for common anti-patterns.
+ */
+function checkApex(filePath, content) {
+  const issues = [];
+
+  // Skip test classes for security/quality checks (they don't run in production)
+  const testClass = isTestClass(content);
+
+  // Preprocess: strip comments and string literals to avoid false positives
+  const processed = preprocessApex(content);
+  const processedLines = processed.split('\n');
+  const depths = trackLoopDepth(processedLines);
+
+  // Check for SOQL/DML inside loops
+  for (let i = 0; i < processedLines.length; i++) {
+    const line = processedLines[i];
+    if (depths[i] > 0 && /\[\s*SELECT\s/i.test(line)) {
+      issues.push(`Line ${i + 1}: SOQL query inside loop — potential governor limit violation`);
+    }
+    if (depths[i] > 0) {
+      const dmlPattern = /\b(insert|update|delete|upsert)\s+/i;
+      const dbPattern = /Database\.(insert|update|delete|upsert)/i;
+      if (dmlPattern.test(line) || dbPattern.test(line)) {
+        issues.push(`Line ${i + 1}: DML operation inside loop — potential governor limit violation`);
+      }
+    }
+  }
+
+  // Check for hardcoded IDs (use raw content — IDs could be in strings)
+  if (/['"][a-zA-Z0-9]{15,18}['"]/.test(content) && /00[0-9a-zA-Z]{13,16}/.test(content)) {
+    issues.push('Hardcoded Salesforce record ID detected — use Custom Settings, Custom Metadata, or labels instead');
+  }
+
+  // Check for System.debug (configurable threshold)
+  const debugThreshold = parseInt(process.env.SCC_DEBUG_THRESHOLD, 10) || 5;
+  const debugCount = (processed.match(/System\.debug/g) || []).length;
+  if (debugCount > debugThreshold) {
+    issues.push(`${debugCount} System.debug statements found — consider removing before deployment`);
+  }
+
+  // --- Security checks (skip for test classes) ---
+  if (!testClass) {
+    // Sharing model detection
+    const beforeFirstBrace = content.split('{')[0] || '';
+    const hasSharing = /\b(with\s+sharing|without\s+sharing|inherited\s+sharing)\b/i.test(beforeFirstBrace);
+    const hasSoqlOrDml = /\[\s*SELECT\s/i.test(processed) ||
+      /\b(insert|update|delete|upsert)\s+/i.test(processed) ||
+      /Database\.(insert|update|delete|upsert|query)/i.test(processed);
+
+    if (!hasSharing && hasSoqlOrDml) {
+      issues.push('[HIGH] No sharing declaration (with sharing/without sharing/inherited sharing) on class that performs SOQL/DML');
+    }
+
+    // Privilege escalation: without sharing + @AuraEnabled/@RemoteAction
+    if (/\bwithout\s+sharing\b/i.test(beforeFirstBrace)) {
+      if (/@AuraEnabled/i.test(content) || /@RemoteAction/i.test(content)) {
+        issues.push('[HIGH] "without sharing" class exposes @AuraEnabled/@RemoteAction methods — potential privilege escalation');
+      }
+    }
+
+    // CRUD/FLS: SOQL without WITH USER_MODE or WITH SECURITY_ENFORCED
+    for (let i = 0; i < processedLines.length; i++) {
+      const line = processedLines[i];
+      if (/\[\s*SELECT\s/i.test(line) && !/WITH\s+(USER_MODE|SECURITY_ENFORCED)/i.test(line)) {
+        issues.push(`Line ${i + 1}: [LOW] SOQL query without WITH USER_MODE or WITH SECURITY_ENFORCED`);
+        break; // Only warn once to avoid noise
+      }
+    }
+
+    // DML without AccessLevel.USER_MODE
+    for (let i = 0; i < processedLines.length; i++) {
+      const line = processedLines[i];
+      if (/Database\.(insert|update|delete|upsert)\s*\(/i.test(line) &&
+          !/AccessLevel\.USER_MODE/i.test(line)) {
+        issues.push(`Line ${i + 1}: [LOW] Database DML without AccessLevel.USER_MODE`);
+        break; // Only warn once
+      }
+    }
+
+    // Dynamic SOQL warning
+    if (/Database\.(query|countQuery)\s*\(/i.test(processed)) {
+      issues.push('[LOW] Dynamic SOQL detected — ensure user-supplied values use String.escapeSingleQuotes()');
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Check LWC JavaScript for common issues.
+ */
+function checkLwc(filePath, content) {
+  const issues = [];
+
+  // Check for console.log
+  const consoleCount = (content.match(/console\.(log|warn|error|info)/g) || []).length;
+  if (consoleCount > 0) {
+    issues.push(`${consoleCount} console statement(s) found — remove before deployment`);
+  }
+
+  // Check for imperative Apex calls without error handling
+  if (/import\s+\w+\s+from\s+['"]@salesforce\/apex\//.test(content)) {
+    if (!/\.catch\(|try\s*\{|catch\s*\(/.test(content)) {
+      issues.push('Imperative Apex call detected without error handling — add .catch() or try/catch');
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Run sf scanner on a single Apex file (standard+ profile).
+ * Returns array of issue strings. Graceful no-op if scanner not installed.
+ */
+function runScannerOnFile(filePath) {
+  const profile = (process.env.SCC_HOOK_PROFILE || 'standard').toLowerCase();
+  if (profile === 'minimal') return [];
+
+  const { execSync } = require('child_process');
+  try {
+    execSync('sf scanner --version', { timeout: 5000, stdio: 'pipe' });
+  } catch {
+    return []; // Scanner not installed — skip gracefully
+  }
+
+  try {
+    const output = execSync(`sf scanner run --target "${filePath}" --format json --engine pmd`, {
+      timeout: 30000,
+      stdio: 'pipe',
+      encoding: 'utf8',
+    });
+    const violations = JSON.parse(output);
+    if (!Array.isArray(violations)) return [];
+    return violations
+      .filter(v => v.severity <= 2)
+      .slice(0, 5)
+      .map(v => {
+        const sev = v.severity === 1 ? 'CRITICAL' : 'HIGH';
+        return `[${sev}] PMD: ${v.message || v.ruleName} (line ${v.line})`;
+      });
+  } catch (err) {
+    if (err.stdout) {
+      try {
+        const violations = JSON.parse(err.stdout);
+        if (!Array.isArray(violations)) return [];
+        return violations
+          .filter(v => v.severity <= 2)
+          .slice(0, 5)
+          .map(v => {
+            const sev = v.severity === 1 ? 'CRITICAL' : 'HIGH';
+            return `[${sev}] PMD: ${v.message || v.ruleName} (line ${v.line})`;
+          });
+      } catch {
+        return [];
+      }
+    }
+    return [];
+  }
+}
+
+function maybeRunQualityGate(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return;
+
+  filePath = path.resolve(filePath);
+  const ext = path.extname(filePath).toLowerCase();
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return;
+  }
+
+  let issues = [];
+
+  if (ext === '.cls' || ext === '.trigger') {
+    issues = checkApex(filePath, content);
+    // Run sf scanner for deeper PMD analysis (standard+ profile, graceful no-op)
+    const scannerIssues = runScannerOnFile(filePath);
+    issues = issues.concat(scannerIssues);
+  } else if (ext === '.js' && filePath.includes('/lwc/')) {
+    issues = checkLwc(filePath, content);
+  }
+
+  if (issues.length > 0) {
+    log(`\n[SCC QualityGate] ${path.basename(filePath)}:`);
+    for (const issue of issues) {
+      log(`  - ${issue}`);
+    }
+    if (issues.some(i => i.includes('PMD:'))) {
+      log('  Install Salesforce Code Analyzer for enhanced checks: sf plugins install @salesforce/sfdx-scanner');
+    }
+    log('');
+  }
+}
+
+function run(rawInput) {
+  try {
+    const input = JSON.parse(rawInput);
+    const filePath = String(input.tool_input?.file_path || '');
+    maybeRunQualityGate(filePath);
+  } catch {
+    // Ignore parse errors
+  }
+  return rawInput;
+}
+
+if (require.main === module) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (raw.length < MAX_STDIN) {
+      raw += chunk.substring(0, MAX_STDIN - raw.length);
+    }
+  });
+  process.stdin.on('end', () => {
+    const result = run(raw);
+    process.stdout.write(result);
+  });
+}
+
+module.exports = { run };

package/scripts/hooks/run-with-flags-shell.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+HOOK_ID="${1:-}"
+REL_SCRIPT_PATH="${2:-}"
+PROFILES_CSV="${3:-standard,strict}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="${SCC_PLUGIN_ROOT:-$(cd "${SCRIPT_DIR}/../.." && pwd)}"
+
+# Preserve stdin for passthrough or script execution
+INPUT="$(cat)"
+
+if [[ -z "$HOOK_ID" || -z "$REL_SCRIPT_PATH" ]]; then
+  printf '%s' "$INPUT"
+  exit 0
+fi
+
+# Ask Node helper if this hook is enabled
+ENABLED="$(node "${PLUGIN_ROOT}/scripts/hooks/check-hook-enabled.js" "$HOOK_ID" "$PROFILES_CSV" 2>/dev/null || echo yes)"
+if [[ "$ENABLED" != "yes" ]]; then
+  printf '%s' "$INPUT"
+  exit 0
+fi
+
+SCRIPT_PATH="${PLUGIN_ROOT}/${REL_SCRIPT_PATH}"
+if [[ ! -f "$SCRIPT_PATH" ]]; then
+  echo "[Hook] Script not found for ${HOOK_ID}: ${SCRIPT_PATH}" >&2
+  printf '%s' "$INPUT"
+  exit 0
+fi
+
+printf '%s' "$INPUT" | "$SCRIPT_PATH"

package/scripts/hooks/run-with-flags.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * run-with-flags.js — Profile-based hook gating for SCC.
+ *
+ * Reads stdin, checks SCC_HOOK_PROFILE and SCC_DISABLED_HOOKS before running
+ * a hook script. Passes stdin through to stdout when the hook is skipped.
+ *
+ * Usage: node run-with-flags.js <hook-name> <min-profile> <script-path>
+ * Profiles: minimal < standard < strict
+ *
+ * Hook execution:
+ *   - If module exports run(input): calls run(stdin) directly (no child process)
+ *   - Otherwise: spawns 'node <script-path>' with stdin piped (legacy hooks)
+ */
+
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const PROFILE_LEVELS = { minimal: 1, standard: 2, strict: 3 };
+const MAX_STDIN = 1024 * 1024;
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        const remaining = MAX_STDIN - raw.length;
+        raw += chunk.substring(0, remaining);
+      }
+    });
+    process.stdin.on('end', () => resolve(raw));
+    process.stdin.on('error', () => resolve(raw));
+  });
+}
+
+async function main() {
+  const hookName = process.argv[2];
+  const minProfile = process.argv[3] || 'standard';
+  const scriptPath = process.argv[4];
+  const timeoutMs = parseInt(process.argv[5], 10) || 30000;
+
+  const raw = await readStdinRaw();
+
+  // Guard: missing args — pass through transparently
+  if (!hookName || !scriptPath) {
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  const currentProfile = process.env.SCC_HOOK_PROFILE || 'standard';
+  const disabledHooks = (process.env.SCC_DISABLED_HOOKS || '').split(',').map(h => h.trim().toLowerCase()).filter(Boolean);
+
+  // Skip if hook is explicitly disabled
+  if (disabledHooks.includes(hookName.toLowerCase())) {
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  // Skip if current profile is below minimum required level
+  const currentLevel = PROFILE_LEVELS[currentProfile] || 2;
+  const minLevel = PROFILE_LEVELS[minProfile] || 2;
+  if (currentLevel < minLevel) {
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  // Guard: script must exist and be a .js file
+  if (!scriptPath.endsWith('.js') || !fs.existsSync(scriptPath)) {
+    process.stderr.write(`[Hook] Script not found or invalid: ${scriptPath}\n`);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  // Source pre-check: only require() hooks that export run().
+  // Prevents executing legacy hooks' module-scope side effects (stdin listeners,
+  // process.exit calls, main() invocations) when called via require().
+  const src = fs.readFileSync(scriptPath, 'utf8');
+  const hasRunExport = /\bmodule\.exports\b/.test(src) && /\brun\b/.test(src);
+
+  let hookModule;
+  if (hasRunExport) {
+    try {
+      hookModule = require(scriptPath);
+    } catch (requireErr) {
+      process.stderr.write(`[Hook] require() failed for ${hookName}: ${requireErr.message}\n`);
+      // Fall through to spawnSync
+    }
+  }
+
+  if (hookModule && typeof hookModule.run === 'function') {
+    try {
+      const output = hookModule.run(raw);
+      if (output !== null && output !== undefined) process.stdout.write(output);
+    } catch (runErr) {
+      process.stderr.write(`[Hook] run() error for ${hookName}: ${runErr.message}\n`);
+      process.stdout.write(raw);
+    }
+    process.exit(0);
+  }
+
+  // Legacy path: spawn a child Node process for hooks without run() export
+  const result = spawnSync('node', [scriptPath], {
+    input: raw,
+    encoding: 'utf8',
+    env: process.env,
+    cwd: process.cwd(),
+    timeout: timeoutMs
+  });
+
+  if (result.error) {
+    process.stderr.write(`[Hook] Spawn error for ${hookName}: ${result.error.message}\n`);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  if (result.signal) {
+    process.stderr.write(`[Hook] ${hookName} killed by ${result.signal} (timeout: ${timeoutMs}ms)\n`);
+    process.stdout.write(raw);
+    process.exit(0);
+  }
+
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+
+  const code = Number.isInteger(result.status) ? result.status : 0;
+  process.exit(code);
+}
+
+main().catch(err => {
+  process.stderr.write(`[Hook] run-with-flags error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/session-end-marker.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Session end marker hook - outputs stdin to stdout unchanged.
+ * Exports run() for in-process execution (avoids spawnSync issues on Windows).
+ */
+
+function run(rawInput) {
+  return rawInput || '';
+}
+
+// Legacy CLI execution (when run directly)
+if (require.main === module) {
+  const MAX_STDIN = 1024 * 1024;
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (raw.length < MAX_STDIN) {
+      const remaining = MAX_STDIN - raw.length;
+      raw += chunk.substring(0, remaining);
+    }
+  });
+  process.stdin.on('end', () => {
+    process.stdout.write(raw);
+  });
+}
+
+module.exports = { run };