scc-universal 1.1.0

package/scripts/hooks/sfdx-validate.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * SFDX Validate Hook
+ *
+ * PreToolUse hook that validates Salesforce CLI commands before execution.
+ * Checks for:
+ * - Commands that should use --dry-run first
+ * - Destructive operations that need confirmation
+ * - Common parameter mistakes
+ */
+
+'use strict';
+
+const readline = require('readline');
+
+const MAX_STDIN = 1024 * 1024;
+
+/**
+ * Validation rules for SF CLI commands.
+ */
+const VALIDATION_RULES = [
+  {
+    pattern: /sf project deploy start(?!.*--dry-run)(?!.*--validate)/,
+    check: (cmd) => !cmd.includes('--test-level') && !cmd.includes('--dry-run'),
+    message: 'Deployment without --test-level specified. Consider adding --test-level RunLocalTests',
+    severity: 'warning',
+  },
+  {
+    pattern: /sf data delete bulk/,
+    message: 'Bulk delete operation — this permanently removes records. Use --dry-run first.',
+    severity: 'warning',
+  },
+  {
+    pattern: /sf org delete scratch/,
+    check: (cmd) => !cmd.includes('--no-prompt'),
+    message: 'Scratch org deletion — ensure you have pushed all source changes before deleting.',
+    severity: 'info',
+  },
+  {
+    pattern: /sf project deploy start.*--ignore-conflicts/,
+    message: 'Deploying with --ignore-conflicts may overwrite changes made directly in the org.',
+    severity: 'warning',
+  },
+  {
+    pattern: /sf data import tree/,
+    check: (cmd) => !cmd.includes('--plan'),
+    message: 'Data import without --plan. Consider using a plan file for repeatable imports.',
+    severity: 'info',
+  },
+  {
+    pattern: /sf package version create(?!.*--skip-validation)/,
+    check: (cmd) => !cmd.includes('--code-coverage'),
+    message: 'Package version creation — remember that managed packages require 75% code coverage.',
+    severity: 'info',
+  },
+  {
+    pattern: /sf project deploy start.*--source-dir.*destructiveChanges/i,
+    message: 'Destructive changes deployment detected. Ensure you have verified the manifest.',
+    severity: 'warning',
+  },
+];
+
+function validateCommand(command) {
+  if (!command) return [];
+
+  // Only check SF CLI commands
+  if (!command.includes('sf ') && !command.includes('sfdx ')) return [];
+
+  const warnings = [];
+  for (const rule of VALIDATION_RULES) {
+    if (rule.pattern.test(command)) {
+      if (rule.check && !rule.check(command)) continue;
+      warnings.push({
+        severity: rule.severity,
+        message: rule.message,
+      });
+    }
+  }
+  return warnings;
+}
+
+// Read JSON from stdin
+let rawInput = '';
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', line => {
+  if (rawInput.length < MAX_STDIN) {
+    rawInput += line + '\n';
+  }
+});
+
+rl.on('close', () => {
+  let input = {};
+  try {
+    input = JSON.parse(rawInput.trim() || '{}');
+  } catch {
+    process.exit(0);
+  }
+
+  if (input.tool_name !== 'Bash' && input.tool_name !== 'bash') {
+    process.exit(0);
+  }
+
+  const command = (input.tool_input && input.tool_input.command) || '';
+  const warnings = validateCommand(command);
+
+  if (warnings.length === 0) {
+    process.exit(0);
+  }
+
+  console.error('\n[SCC Validate] SF CLI Command Check:');
+  for (const w of warnings) {
+    const prefix = w.severity === 'warning' ? 'WARNING' : 'INFO';
+    console.error(`  ${prefix}: ${w.message}`);
+  }
+  console.error();
+
+  // Exit 0 — we warn but don't block
+  process.exit(0);
+});

package/scripts/hooks/stop-hook.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * stop-hook.js — Stop hook for SCC.
+ *
+ * Runs when Claude Code is about to stop/complete a session.
+ * Checks for uncommitted Apex/LWC changes and reminds about:
+ *   - Running tests before committing
+ *   - Deploying to a scratch org to verify
+ *   - Checking test coverage
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const CWD = process.cwd();
+
+/**
+ * Run a command and return { status, stdout, stderr }.
+ */
+function run(cmd, args, cwd) {
+  const result = spawnSync(cmd, args, {
+    encoding: 'utf8',
+    timeout: 10000,
+    cwd: cwd || CWD,
+    env: process.env,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error,
+  };
+}
+
+/**
+ * Get uncommitted files via git status --porcelain.
+ */
+function getUncommittedFiles() {
+  const result = run('git', ['status', '--porcelain']);
+  if (result.status !== 0 || result.error) return null;
+
+  return result.stdout
+    .split('\n')
+    .filter(line => line.trim().length > 0)
+    .map(line => {
+      const statusCode = line.slice(0, 2).trim();
+      const filePath = line.slice(3).trim();
+      return { statusCode, filePath };
+    });
+}
+
+/**
+ * Check if this is a Salesforce project.
+ */
+function isSalesforceProject(dir) {
+  let d = dir;
+  for (let i = 0; i < 5; i++) {
+    if (fs.existsSync(path.join(d, 'sfdx-project.json'))) return true;
+    const parent = path.dirname(d);
+    if (parent === d) break;
+    d = parent;
+  }
+  return false;
+}
+
+/**
+ * Classify Salesforce file types.
+ */
+function classifyFiles(files) {
+  const classified = { apex: [], lwc: [], aura: [], other: [] };
+  for (const f of files) {
+    const fp = f.filePath;
+    const ext = path.extname(fp).toLowerCase();
+    const parts = fp.split('/');
+
+    if (ext === '.cls' || ext === '.trigger') {
+      classified.apex.push(f);
+    } else if (parts.includes('lwc')) {
+      classified.lwc.push(f);
+    } else if (parts.includes('aura')) {
+      classified.aura.push(f);
+    } else {
+      classified.other.push(f);
+    }
+  }
+  return classified;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+// Only run in Salesforce projects
+if (!isSalesforceProject(CWD)) {
+  process.exit(0);
+}
+
+const uncommittedFiles = getUncommittedFiles();
+
+// Can't check git or no changes
+if (uncommittedFiles === null || uncommittedFiles.length === 0) {
+  process.exit(0);
+}
+
+const classified = classifyFiles(uncommittedFiles);
+const hasSfChanges = classified.apex.length > 0 || classified.lwc.length > 0 || classified.aura.length > 0;
+
+if (!hasSfChanges) {
+  process.exit(0);
+}
+
+// Print a summary reminder
+console.log('\n── SCC: Uncommitted Salesforce Changes ────────────────');
+
+if (classified.apex.length > 0) {
+  console.log(`\nApex changes (${classified.apex.length} file(s)):`);
+  for (const f of classified.apex.slice(0, 5)) {
+    console.log(`  ${f.statusCode}  ${f.filePath}`);
+  }
+  if (classified.apex.length > 5) console.log(`  ... and ${classified.apex.length - 5} more`);
+
+  console.log('\nApex reminders:');
+  console.log('  • Run Apex tests before committing:');
+  console.log('      sf apex run test --result-format human --code-coverage');
+  console.log('  • Ensure 75% code coverage across your org');
+  console.log('  • Deploy to scratch org to verify: sf project deploy start');
+}
+
+if (classified.lwc.length > 0) {
+  console.log(`\nLWC changes (${classified.lwc.length} file(s)):`);
+  for (const f of classified.lwc.slice(0, 5)) {
+    console.log(`  ${f.statusCode}  ${f.filePath}`);
+  }
+  if (classified.lwc.length > 5) console.log(`  ... and ${classified.lwc.length - 5} more`);
+
+  console.log('\nLWC reminders:');
+  console.log('  • Run Jest unit tests: npm run test:unit');
+  console.log('  • Validate component: sf project deploy start --dry-run');
+  console.log('  • Test in browser: sf org open');
+}
+
+if (classified.aura.length > 0) {
+  console.log(`\nAura changes (${classified.aura.length} file(s)):`);
+  for (const f of classified.aura.slice(0, 3)) {
+    console.log(`  ${f.statusCode}  ${f.filePath}`);
+  }
+}
+
+// Check if there's a package.json with test scripts (for LWC Jest)
+const packageJsonPath = path.join(CWD, 'package.json');
+let hasJestScript = false;
+if (fs.existsSync(packageJsonPath)) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    hasJestScript = !!(pkg.scripts && (pkg.scripts['test:unit'] || pkg.scripts['jest'] || pkg.scripts['test']));
+  } catch { /* ignore */ }
+}
+
+console.log('\nNext steps:');
+if (classified.apex.length > 0) {
+  console.log('  1. sf apex run test --result-format human --code-coverage');
+}
+if (classified.lwc.length > 0 && hasJestScript) {
+  console.log('  2. npm run test:unit');
+}
+console.log(`  ${classified.apex.length > 0 ? '3' : '1'}. git add . && git commit -m "feat: <your message>"`);
+console.log('────────────────────────────────────────────────────────\n');
+
+process.exit(0);

package/scripts/hooks/suggest-compact.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Strategic Compact Suggester
+ *
+ * Tracks tool call count and suggests manual /compact at logical intervals.
+ * Runs on PreToolUse to count invocations.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function getTempDir() {
+  return os.tmpdir();
+}
+
+function log(msg) {
+  process.stderr.write(`${msg}\n`);
+}
+
+async function main() {
+  const sessionId = (process.env.CLAUDE_SESSION_ID || 'default').replace(/[^a-zA-Z0-9_-]/g, '') || 'default';
+  const counterFile = path.join(getTempDir(), `scc-tool-count-${sessionId}`);
+  const rawThreshold = parseInt(process.env.COMPACT_THRESHOLD || '50', 10);
+  const threshold = Number.isFinite(rawThreshold) && rawThreshold > 0 && rawThreshold <= 10000
+    ? rawThreshold
+    : 50;
+
+  let count = 1;
+
+  try {
+    const fd = fs.openSync(counterFile, 'a+');
+    try {
+      const buf = Buffer.alloc(64);
+      const bytesRead = fs.readSync(fd, buf, 0, 64, 0);
+      if (bytesRead > 0) {
+        const parsed = parseInt(buf.toString('utf8', 0, bytesRead).trim(), 10);
+        count = (Number.isFinite(parsed) && parsed > 0 && parsed <= 1000000)
+          ? parsed + 1
+          : 1;
+      }
+      fs.ftruncateSync(fd, 0);
+      fs.writeSync(fd, String(count), 0);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    try { fs.writeFileSync(counterFile, String(count)); } catch { /* ignore */ }
+  }
+
+  if (count === threshold) {
+    log(`[SCC Compact] ${threshold} tool calls reached — consider /compact if transitioning phases`);
+  }
+
+  if (count > threshold && (count - threshold) % 25 === 0) {
+    log(`[SCC Compact] ${count} tool calls — good checkpoint for /compact if context is stale`);
+  }
+
+  process.exit(0);
+}
+
+main().catch(err => {
+  console.error('[SCC Compact] Error:', err.message);
+  process.exit(0);
+});

package/scripts/lib/agent-adapter.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * agent-adapter.js — Transforms SCC agents from Claude Code format to Cursor format.
+ *
+ * Claude Code agents use: name, description, tools, model (sonnet/opus/haiku), origin,
+ *   disallowedTools, permissionMode, maxTurns, skills, mcpServers, hooks, memory, etc.
+ * Cursor agents use: name, description, model (fast/inherit/specific ID), readonly, is_background.
+ *
+ * This adapter strips Claude-only fields, maps model aliases, and outputs
+ * clean Cursor-compatible agent .md files.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter, serializeFrontmatter, ensureDir } = require('./utils');
+
+// Fields that Cursor recognizes in agent frontmatter
+const CURSOR_ALLOWED_FIELDS = new Set([
+  'name',
+  'description',
+  'model',
+  'readonly',
+  'is_background',
+]);
+
+// Map Claude Code model aliases to Cursor equivalents
+const MODEL_MAP = {
+  sonnet: 'inherit',
+  opus: 'inherit',
+  haiku: 'fast',
+  'claude-sonnet': 'inherit',
+  'claude-opus': 'inherit',
+  'claude-haiku': 'fast',
+};
+
+/**
+ * Transform a single agent .md content string from Claude Code to Cursor format.
+ * @param {string} content - raw agent .md content
+ * @returns {string} - transformed agent .md content for Cursor
+ */
+function transformAgent(content) {
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  const cursorFm = {};
+
+  // Copy allowed fields
+  for (const key of Object.keys(frontmatter)) {
+    if (CURSOR_ALLOWED_FIELDS.has(key)) {
+      cursorFm[key] = frontmatter[key];
+    }
+  }
+
+  // Map model aliases to Cursor equivalents
+  if (cursorFm.model) {
+    const mapped = MODEL_MAP[String(cursorFm.model).toLowerCase()];
+    if (mapped) {
+      cursorFm.model = mapped;
+    }
+    // Full model IDs (e.g. claude-sonnet-4-6) pass through unchanged
+  }
+
+  return serializeFrontmatter(cursorFm, body);
+}
+
+/**
+ * Transform and write a single agent file.
+ * @param {string} srcPath - source agent .md file
+ * @param {string} destPath - destination file path
+ */
+function transformAgentFile(srcPath, destPath) {
+  if (!fs.existsSync(srcPath)) {
+    throw new Error(`Source agent file not found: ${srcPath}`);
+  }
+
+  const content = fs.readFileSync(srcPath, 'utf8');
+  const transformed = transformAgent(content);
+  ensureDir(path.dirname(destPath));
+  fs.writeFileSync(destPath, transformed, 'utf8');
+}
+
+module.exports = { transformAgent, transformAgentFile, CURSOR_ALLOWED_FIELDS, MODEL_MAP };

package/scripts/lib/apex-analysis.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * apex-analysis.js — Shared Apex static analysis utilities
+ *
+ * Provides preprocessing (comment/string stripping), loop depth tracking,
+ * and test class detection for use by governor-check.js and quality-gate.js.
+ *
+ * Architecture:
+ * - trackLoopDepth uses an activeLoopDepths stack + globalBraceDepth counter
+ *   to correctly handle if/try/catch blocks inside loops (their closing braces
+ *   don't prematurely end the enclosing loop).
+ * - Linear 6-step pipeline per line — no continue statements that could skip
+ *   brace tracking and desync globalBraceDepth.
+ *
+ * Known limitations:
+ * - do { } while(cond) — the 'do' keyword isn't followed by '(', so the loop
+ *   regex doesn't match it. Brace tracking still manages depth correctly, but
+ *   'do' itself isn't recognized as a loop start.
+ * - Class-level static initializer blocks may affect globalBraceDepth.
+ * - Anonymous inner classes with { } may affect brace counting.
+ */
+
+/**
+ * Strip comments and string literals from Apex code.
+ * Replaces removed content with whitespace to preserve line alignment.
+ *
+ * @param {string} code - Raw Apex source code
+ * @returns {string} Code with comments and strings replaced by spaces
+ */
+function preprocessApex(code) {
+  let result = code;
+  // Remove block comments (preserve newlines for line alignment)
+  result = result.replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n]/g, ' '));
+  // Remove single-line comments
+  result = result.replace(/\/\/.*$/gm, m => ' '.repeat(m.length));
+  // Remove string literals (handle escaped quotes)
+  result = result.replace(/'(?:[^'\\]|\\.)*'/g, m => ' '.repeat(m.length));
+  result = result.replace(/"(?:[^"\\]|\\.)*"/g, m => ' '.repeat(m.length));
+  return result;
+}
+
+/**
+ * Detect whether an Apex source file is a test class.
+ * Test classes don't run in production, so governor limit scanning
+ * on them creates noise.
+ *
+ * @param {string} code - Raw or preprocessed Apex source code
+ * @returns {boolean} True if the class has @IsTest annotation at class level
+ */
+function isTestClass(code) {
+  // Match @IsTest before the class keyword (class-level annotation)
+  const beforeFirstBrace = code.split('{')[0] || '';
+  return /@[Ii]s[Tt]est\b/.test(beforeFirstBrace);
+}
+
+/**
+ * Track loop depth for each line of preprocessed Apex code.
+ *
+ * Returns an array of integers where depths[i] is the loop nesting depth
+ * at line i. depths[i] > 0 means line i is inside a loop.
+ *
+ * Uses an activeLoopDepths stack bound to globalBraceDepth to correctly
+ * handle if/try/catch blocks inside loops. Uses unbracedStack counter
+ * for nested unbraced loops. Uses waitingForBody state for Allman brace style.
+ *
+ * CRITICAL: Linear 6-step pipeline — every non-empty line flows through all
+ * steps. No continue statements that could skip brace tracking.
+ *
+ * @param {string[]} processedLines - Lines from preprocessApex(code).split('\n')
+ * @returns {number[]} Array of loop depth per line
+ */
+function trackLoopDepth(processedLines) {
+  const depths = [];
+  let globalBraceDepth = 0;   // total brace depth in file
+  const activeLoopDepths = [];   // stack: globalBraceDepth where each braced loop started
+  let unbracedStack = 0;       // counter for nested unbraced loops
+  let parenDepth = 0;          // for multi-line for/while declarations
+  let pendingLoop = false;     // SCANNING_DECLARATION state
+  let waitingForBody = false;  // WAITING_FOR_BODY state
+
+  for (let i = 0; i < processedLines.length; i++) {
+    const line = processedLines[i];
+    const trimmed = line.trim();
+    let singleLineLoopBonus = 0;
+    let skipLoopDetection = false;
+
+    // Empty lines: no braces, safe to skip
+    if (!trimmed) {
+      depths.push(activeLoopDepths.length + unbracedStack);
+      continue;
+    }
+
+    // ═══════════ STEP 1: Resolve pending multi-line declarations ═══════════
+    if (pendingLoop) {
+      let closingIdx = -1;
+      for (let j = 0; j < trimmed.length; j++) {
+        if (trimmed[j] === '(') parenDepth++;
+        if (trimmed[j] === ')') {
+          parenDepth--;
+          if (parenDepth === 0) { closingIdx = j; break; }
+        }
+      }
+      if (closingIdx === -1) {
+        // Still reading declaration — inside parens, no block braces matter
+        depths.push(activeLoopDepths.length + unbracedStack);
+        continue; // safe: inside parens
+      }
+      pendingLoop = false;
+      const afterClose = trimmed.substring(closingIdx + 1).trim();
+      if (afterClose.startsWith('{') || afterClose.includes('{')) {
+        activeLoopDepths.push(globalBraceDepth);
+      } else if (/\S/.test(afterClose) && /;\s*$/.test(afterClose)) {
+        singleLineLoopBonus = 1;
+      } else if (/\S/.test(afterClose)) {
+        unbracedStack++;
+      } else {
+        waitingForBody = true;
+      }
+      skipLoopDetection = true;
+    }
+
+    // ═══════════ STEP 2: Resolve WAITING_FOR_BODY ═══════════
+    if (waitingForBody) {
+      waitingForBody = false;
+      if (trimmed.startsWith('{')) {
+        // Allman braced loop
+        activeLoopDepths.push(globalBraceDepth);
+      } else {
+        // Unbraced loop — this line IS the body (or start of it)
+        unbracedStack++;
+      }
+    }
+
+    // ═══════════ STEP 3: Detect new loop starts ═══════════
+    const loopMatch = !skipLoopDetection && trimmed.match(/\b(for|while|do)\s*\(/);
+    if (loopMatch) {
+      // Token-aware paren scan from match point (NOT lastIndexOf)
+      let localParenDepth = 0;
+      let closingIdx = -1;
+      for (let j = loopMatch.index; j < trimmed.length; j++) {
+        if (trimmed[j] === '(') localParenDepth++;
+        if (trimmed[j] === ')') {
+          localParenDepth--;
+          if (localParenDepth === 0) { closingIdx = j; break; }
+        }
+      }
+
+      if (closingIdx === -1) {
+        // Multi-line declaration — parens still open
+        parenDepth = localParenDepth;
+        pendingLoop = true;
+      } else {
+        // CRITICAL: use closingIdx from paren scan, NOT lastIndexOf(')')
+        const afterClose = trimmed.substring(closingIdx + 1).trim();
+        if (afterClose.startsWith('{') || afterClose.includes('{')) {
+          activeLoopDepths.push(globalBraceDepth);
+        } else if (/\S/.test(afterClose) && /;\s*$/.test(afterClose)) {
+          singleLineLoopBonus = 1;
+        } else if (/\S/.test(afterClose)) {
+          unbracedStack++;
+        } else {
+          waitingForBody = true;
+        }
+      }
+    }
+
+    // ═══════════ STEP 4: Record current line depth ═══════════
+    // Single-line loop bonus adds +1 for the current line only
+    depths.push(activeLoopDepths.length + unbracedStack + singleLineLoopBonus);
+
+    // ═══════════ STEP 5: Update globalBraceDepth + reconcile ═══════════
+    const opens = (trimmed.match(/\{/g) || []).length;
+    const closes = (trimmed.match(/\}/g) || []).length;
+    globalBraceDepth += (opens - closes);
+
+    // If brace depth dropped to/below where a loop started, that loop closed
+    while (
+      activeLoopDepths.length > 0 &&
+      globalBraceDepth <= activeLoopDepths[activeLoopDepths.length - 1]
+    ) {
+      activeLoopDepths.pop();
+    }
+
+    // ═══════════ STEP 6: Drain unbraced stack (LAST — after braces counted) ═══════════
+    if (unbracedStack > 0 && /;\s*$/.test(trimmed) && singleLineLoopBonus === 0) {
+      unbracedStack = 0;
+    }
+  }
+  return depths;
+}
+
+module.exports = { preprocessApex, isTestClass, trackLoopDepth };