@boyingliu01/xp-gate 0.32.3 → 0.33.1

package/bin/xp-gate.js

@@ -295,9 +295,9 @@ const COMMANDS = {
     usage: 'xp-gate baseline <create|show|reset|diff>'
   },
   'check': {
-    description: 'Run quality gates (--list, --all, --gates <ids>, or <gate-id>)',
+    description: 'Run quality gates (--list, --all, --gates <ids>, --changed --brief, or <gate-id>)',
     run: subargs => check(subargs).then(code => process.exit(code)),
-    usage: 'xp-gate check <file_or_directory|gate_number> [--gates gates] [--all] [--list]'
+    usage: 'xp-gate check <file_or_directory|gate_number> [--gates gates] [--all] [--changed --brief] [--list]'
   },
   'principles': {
     description: 'Run Clean Code + SOLID principles checker (Gate 4 standalone)',

package/gates/common-process.ts

@@ -0,0 +1,178 @@
+/**
+ * Process-execution and tool-detection primitives shared by the gates.
+ * Split out of common.ts (Boy Scout: many-exports); re-exported there so
+ * every existing `from '../common'` import keeps working unchanged.
+ */
+import { spawnSync, SpawnSyncReturns } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+export interface ToolAvailability {
+  available: boolean;
+  path: string;
+  via: 'path' | 'npx' | 'custom' | 'none';
+}
+
+export interface ToolResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+}
+
+export interface PowerShellInfo {
+  available: boolean;
+  exe: string;
+  version: string;
+}
+
+// ── Tool Detection ──
+
+/**
+ * Cross-platform tool detection with 3-tier fallback:
+ * 1. PATH lookup (command -v equivalent)
+ * 2. npx fallback (for npm-installed tools)
+ * 3. Custom path (~/.local/bin/ on Unix)
+ */
+/** Tier 1: PATH lookup. */
+function probeToolPath(tool: string): ToolAvailability {
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const pathCheck = spawnSync(whichCmd, [tool], { encoding: 'utf-8', timeout: 5000 });
+    if (pathCheck.status === 0 && pathCheck.stdout.trim()) {
+      return { available: true, path: pathCheck.stdout.trim().split('\n')[0], via: 'path' };
+    }
+  } catch { /* probe failed → not on PATH */ }
+  return { available: false, path: '', via: 'none' };
+}
+
+/** Tier 2: npx fallback (check if tool is available via npx). */
+function probeToolNpx(tool: string, cwd?: string): ToolAvailability {
+  try {
+    const npxCheck = spawnSync('npx', ['--yes', tool, '--version'], {
+      encoding: 'utf-8',
+      timeout: 15000,
+      shell: process.platform === 'win32',
+      cwd,
+    });
+    if (npxCheck.status === 0) {
+      return { available: true, path: `npx ${tool}`, via: 'npx' };
+    }
+  } catch { /* probe failed → not reachable via npx */ }
+  return { available: false, path: '', via: 'none' };
+}
+
+export function isToolAvailable(tool: string, cwd?: string): ToolAvailability {
+  // Tier 1: PATH lookup
+  const pathProbe = probeToolPath(tool);
+  if (pathProbe.available) return pathProbe;
+
+  // Tier 2: npx fallback
+  const npxProbe = probeToolNpx(tool, cwd);
+  if (npxProbe.available) return npxProbe;
+
+  // Tier 3: Custom path (~/.local/bin/)
+  if (process.platform !== 'win32') {
+    const customPath = path.join(os.homedir(), '.local', 'bin', tool);
+    if (fs.existsSync(customPath)) {
+      return { available: true, path: customPath, via: 'custom' };
+    }
+  }
+
+  return { available: false, path: '', via: 'none' };
+}
+
+// ── Process Execution ──
+
+/**
+ * Cross-platform spawnSync wrapper with timeout and error handling.
+ * Uses spawnSync (not execSync) to avoid shell injection.
+ */
+export function runTool(
+  cmd: string,
+  args: string[],
+  opts?: { cwd?: string; env?: Record<string, string>; timeoutMs?: number; shell?: boolean }
+): ToolResult {
+  try {
+    const result: SpawnSyncReturns<string> = spawnSync(cmd, args, {
+      encoding: 'utf-8',
+      cwd: opts?.cwd || process.cwd(),
+      env: { ...process.env, ...opts?.env },
+      timeout: opts?.timeoutMs || 120_000,
+      maxBuffer: 10 * 1024 * 1024,
+      shell: opts?.shell || process.platform === 'win32',
+    });
+
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.status ?? -1,
+      timedOut: result.signal === 'SIGTERM' || (result.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT',
+    };
+  } catch (err) {
+    // spawnSync throws on ENOENT-class failures; report them as a failed run
+    // with the message on stderr instead of crashing every caller.
+    return { stdout: '', stderr: err instanceof Error ? err.message : String(err), exitCode: -1, timedOut: false };
+  }
+}
+
+// ── Git Helpers ──
+
+/**
+ * Get list of changed (staged) files via git diff --cached.
+ * Equivalent to adapter-common.sh's git diff --cached --name-only.
+ */
+export function getChangedFiles(cwd?: string): string[] {
+  try {
+    const result = spawnSync('git', ['diff', '--cached', '--name-only', '--diff-filter=ACM'], {
+      encoding: 'utf-8',
+      cwd: cwd || process.cwd(),
+      timeout: 10000,
+    });
+    if (result.status !== 0) return [];
+    return result.stdout
+      .split('\n')
+      .map(f => f.trim())
+      .filter(Boolean);
+  } catch {
+    // No git / unreadable repo → no changed files, same as a failed status.
+    return [];
+  }
+}
+
+// ── PowerShell Support ──
+
+/**
+ * Detect PowerShell executable (prefer pwsh 7+, fallback to powershell.exe 5.1).
+ * Mirrors powershell.sh's _detect_pwsh() pattern.
+ */
+/** Probe one candidate executable; null when it is not on PATH. */
+function probePowerShellCandidate(exe: string): PowerShellInfo | null {
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const check = spawnSync(whichCmd, [exe], { encoding: 'utf-8', timeout: 5000 });
+    if (check.status !== 0 || !check.stdout.trim()) return null;
+    const exePath = check.stdout.trim().split('\n')[0];
+    // Get version
+    const verResult = spawnSync(exe, ['-Command', '$PSVersionTable.PSVersion.ToString()'], {
+      encoding: 'utf-8',
+      timeout: 10000,
+      shell: process.platform === 'win32',
+    });
+    const version = verResult.status === 0 ? verResult.stdout.trim() : 'unknown';
+    return { available: true, exe: exePath, version };
+  } catch { /* probe failed → this candidate is not usable */ }
+  return null;
+}
+
+export function detectPowerShell(): PowerShellInfo {
+  const candidates = ['pwsh', 'powershell.exe', 'powershell'];
+
+  for (const exe of candidates) {
+    const found = probePowerShellCandidate(exe);
+    if (found) return found;
+  }
+
+  return { available: false, exe: '', version: '' };
+}

package/gates/common.ts

@@ -0,0 +1,208 @@
+/**
+ * Shared infrastructure for TypeScript gate modules.
+ * Provides cross-platform tool detection, process execution, audit logging,
+ * project language detection, and PowerShell project support.
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// ── Types ──
+
+export interface GateInput {
+  changedFiles: string[];
+  projectLang: string;
+  cwd?: string;
+}
+
+export interface GateOutput {
+  status: 'PASS' | 'FAIL' | 'SKIP' | 'WARN';
+  messages: string[];
+  exitCode: number;
+}
+
+// ── Process & tool primitives (split to common-process.ts for module size) ──
+
+import { runTool, type PowerShellInfo, type ToolResult } from './common-process';
+
+export {
+  type ToolAvailability,
+  type ToolResult,
+  type PowerShellInfo,
+  isToolAvailable,
+  runTool,
+  getChangedFiles,
+  detectPowerShell,
+} from './common-process';
+
+// ── Audit Logging ──
+
+const AUDIT_DIR = '.xp-gate';
+const AUDIT_FILE = 'audit.jsonl';
+
+/**
+ * Record gate execution to .xp-gate/audit.jsonl.
+ * Schema must match bash version's record_gate_audit() output.
+ */
+export function recordAudit(
+  gateId: string,
+  gateName: string,
+  status: string,
+  details: string | number,
+  startMs: number
+): void {
+  const durationMs = Date.now() - startMs;
+  const entry = {
+    timestamp: new Date().toISOString(),
+    gate: gateId,
+    name: gateName,
+    status,
+    details: String(details),
+    duration_ms: durationMs,
+  };
+
+  try {
+    if (!fs.existsSync(AUDIT_DIR)) {
+      fs.mkdirSync(AUDIT_DIR, { recursive: true });
+    }
+    fs.appendFileSync(path.join(AUDIT_DIR, AUDIT_FILE), JSON.stringify(entry) + '\n');
+  } catch {
+    // Audit logging failure should not block the gate
+  }
+}
+
+// ── Language Detection ──
+
+/** Any file in `dir` (non-recursive) matching one of the extensions. */
+function hasFileWithExtension(dir: string, extensions: string[]): boolean {
+  try {
+    const files = fs.readdirSync(dir);
+    return files.some((f) => extensions.some((ext) => f.endsWith(ext)));
+  } catch { /* unreadable dir counts as absent — same as before */ }
+  return false;
+}
+
+/** Java/Kotlin from Gradle markers: any .kt anywhere tips it to Kotlin. */
+function detectJvmLanguage(dir: string): string {
+  try {
+    const files = fs.readdirSync(dir, { recursive: true }) as string[];
+    if (files.some(f => typeof f === 'string' && f.endsWith('.kt'))) return 'kotlin';
+  } catch { /* ignore */ }
+  return 'java';
+}
+
+/** Marker-file language probes, tried in order; first hit wins. */
+const LANG_MARKERS: Array<{ lang: string; files: string[] }> = [
+  { lang: 'typescript', files: ['tsconfig.json'] },
+  { lang: 'python', files: ['pyproject.toml', 'requirements.txt', 'setup.py'] },
+  { lang: 'go', files: ['go.mod'] },
+];
+
+/** Dart vs Flutter, or null when there is no pubspec.yaml. */
+function detectDartFlutter(dir: string): string | null {
+  const pubspec = path.join(dir, 'pubspec.yaml');
+  if (!fs.existsSync(pubspec)) return null;
+  try {
+    const content = fs.readFileSync(pubspec, 'utf-8');
+    if (content.includes('flutter:') || fs.existsSync(path.join(dir, '.metadata'))) return 'flutter';
+  } catch { /* A pubspec we cannot read is still a Dart project. */ }
+  return 'dart';
+}
+
+/** JVM build files: Gradle wins over Maven, matching the original order. */
+function detectJvm(dir: string): string | null {
+  const hasGradle = fs.existsSync(path.join(dir, 'build.gradle'))
+    || fs.existsSync(path.join(dir, 'build.gradle.kts'));
+  if (hasGradle) return detectJvmLanguage(dir);
+  if (fs.existsSync(path.join(dir, 'pom.xml'))) return 'java';
+  return null;
+}
+
+/** Infrastructure-as-code by file extension, or null. */
+function detectIac(dir: string): string | null {
+  try {
+    const files = fs.readdirSync(dir);
+    if (files.some((f) => f.endsWith('.tf') || f === 'Dockerfile')) return 'iac';
+  } catch { /* An unreadable directory proves nothing. */ }
+  return null;
+}
+
+export function detectProjectLang(cwd?: string): string {
+  const dir = cwd || process.cwd();
+
+  for (const marker of LANG_MARKERS) {
+    if (marker.files.some((f) => fs.existsSync(path.join(dir, f)))) return marker.lang;
+  }
+
+  const candidates = [
+    detectJvm(dir),
+    detectDartFlutter(dir),
+    hasFileWithExtension(dir, ['.psd1', '.psm1', '.ps1']) ? 'powershell' : null,
+    hasFileWithExtension(dir, ['.sh', '.bash']) ? 'shell' : null,
+    detectIac(dir),
+  ];
+  return candidates.find((lang) => lang !== null) ?? 'unknown';
+}
+
+// ── PowerShell Support ──
+
+/**
+ * Detect PowerShell executable (prefer pwsh 7+, fallback to powershell.exe 5.1).
+/**
+ * Check if the project language is PowerShell.
+ */
+export function isPowerShellProject(projectLang: string): boolean {
+  return projectLang === 'powershell';
+}
+
+/**
+ * Run a PowerShell tool/script via the detected PowerShell executable.
+ */
+export function runPowerShellTool(
+  psInfo: PowerShellInfo,
+  command: string,
+  opts?: { cwd?: string; timeoutMs?: number }
+): ToolResult {
+  if (!psInfo.available) {
+    return { stdout: '', stderr: 'PowerShell not available', exitCode: -1, timedOut: false };
+  }
+  return runTool(psInfo.exe, ['-NoProfile', '-NonInteractive', '-Command', command], {
+    cwd: opts?.cwd,
+    timeoutMs: opts?.timeoutMs,
+  });
+}
+
+// ── Temp Directory ──
+
+/**
+ * Cross-platform temp directory (Windows: %TEMP%, Linux/macOS: /tmp).
+ */
+export function getTempDir(): string {
+  return os.tmpdir();
+}
+
+// ── File Filtering Helpers ──
+
+/** Source file extensions that lizard can analyze. */
+const LIZARD_EXTENSIONS = /\.(ts|tsx|js|jsx|py|go|java|swift|cpp|c|hpp|h|m|mm|kt)$/;
+
+/** File extensions that semgrep supports. */
+const SEMGREP_EXTENSIONS = /\.(ts|tsx|js|jsx|py|go|java|c|cpp|cs|rb|php|scala|swift)$/;
+
+/** IaC file patterns. */
+const IAC_PATTERN = /\.(tf|yaml|yml)$|Dockerfile/;
+
+/** PowerShell DSC file patterns. */
+const PS_DSC_PATTERN = /\.configuration\.ps1$|\.mof$/;
+
+export function filterSourceFiles(files: string[]): string[] {
+  return files.filter(f => LIZARD_EXTENSIONS.test(f));
+}
+
+export function filterSemgrepFiles(files: string[]): string[] {
+  return files.filter(f => SEMGREP_EXTENSIONS.test(f));
+}
+
+export function filterIaCFiles(files: string[]): string[] {
+  return files.filter(f => IAC_PATTERN.test(f) || PS_DSC_PATTERN.test(f));
+}

package/gates/gate-3.ts

@@ -0,0 +1,144 @@
+/**
+ * Gate 3: Cyclomatic Complexity Check
+ * Uses lizard for source files; PSScriptAnalyzer for PowerShell projects.
+ * TypeScript rewrite of githooks/adapters/gate-3.sh for cross-platform Node.js CLI.
+ */
+import {
+  GateInput, GateOutput, isToolAvailable, runTool, recordAudit,
+  filterSourceFiles, detectPowerShell, isPowerShellProject, runPowerShellTool,
+  getChangedFiles, detectProjectLang,
+} from './common';
+
+const CCN_THRESHOLD = 5;
+
+export function runGate3(input: GateInput): GateOutput {
+  const startMs = Date.now();
+  const messages: string[] = [];
+
+  messages.push('');
+  messages.push('→ Gate 3: Cyclomatic complexity...');
+
+  // Documentation-only projects: skip
+  if (input.projectLang === 'documentation-only') {
+    messages.push('⏭️  SKIPPED - Complexity (documentation project).');
+    recordAudit('gate-3', 'complexity', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  // PowerShell project: use PSScriptAnalyzer as alternative
+  if (isPowerShellProject(input.projectLang)) {
+    return runPowerShellComplexity(input, startMs, messages);
+  }
+
+  // Standard path: lizard
+  const tool = isToolAvailable('lizard', input.cwd);
+  if (!tool.available) {
+    messages.push('⚠️  WARN - lizard not installed, complexity check not performed');
+    messages.push('   Install with: pip install --user lizard');
+    messages.push('   Gate 3: Complexity check (WARN, tool not available)');
+    recordAudit('gate-3', 'complexity', 'WARN', 0, startMs);
+    return { status: 'WARN', messages, exitCode: 0 };
+  }
+
+  const lizardCmd = tool.via === 'npx' ? 'npx' : tool.path;
+  const lizardArgs = tool.via === 'npx' ? ['-y', 'lizard'] : [];
+
+  // Filter to source files lizard can analyze
+  const ccFiles = filterSourceFiles(input.changedFiles);
+  if (ccFiles.length === 0) {
+    messages.push('⏭️  SKIPPED - Complexity (no source files to check).');
+    recordAudit('gate-3', 'complexity', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  messages.push('Checking complexity for source files...');
+
+  // Run lizard with CCN threshold
+  const result = runTool(lizardCmd, [...lizardArgs, '-C', String(CCN_THRESHOLD), ...ccFiles], {
+    cwd: input.cwd,
+  });
+
+  const combinedOutput = result.stdout + result.stderr;
+
+  // Parse warning count from summary table: "Warning cnt   8"
+  const warningMatch = combinedOutput.match(/^Warning cnt\s+(\d+)/m);
+  const warnings = warningMatch ? parseInt(warningMatch[1], 10) : 0;
+
+  if (warnings > 0) {
+    messages.push(combinedOutput);
+    messages.push('');
+    messages.push(`❌ BLOCKED - ${warnings} functions with CCN > ${CCN_THRESHOLD} found.`);
+    messages.push(`Refactor high-complexity functions to keep below ${CCN_THRESHOLD} complexity.`);
+    recordAudit('gate-3', 'complexity', 'FAIL', warnings, startMs);
+    return { status: 'FAIL', messages, exitCode: 1 };
+  }
+
+  messages.push(`✅ PASSED - All functions within complexity threshold (${CCN_THRESHOLD}).`);
+  recordAudit('gate-3', 'complexity', 'PASS', 0, startMs);
+  return { status: 'PASS', messages, exitCode: 0 };
+}
+
+// ── CLI Entry Point ──
+if (process.argv.includes('--run')) {
+  const cwdIdx = process.argv.indexOf('--cwd');
+  const cwd = cwdIdx >= 0 ? process.argv[cwdIdx + 1] : process.cwd();
+  const changedFiles = getChangedFiles(cwd);
+  const projectLang = detectProjectLang(cwd);
+  const result = runGate3({ changedFiles, projectLang, cwd });
+  result.messages.forEach(m => console.log(m));
+  process.exit(result.exitCode);
+}
+
+/**
+ * PowerShell project complexity check using PSScriptAnalyzer.
+ * Uses PSAvoid* rules as approximate complexity indicators.
+ */
+function runPowerShellComplexity(
+  input: GateInput,
+  startMs: number,
+  messages: string[]
+): GateOutput {
+  const ps = detectPowerShell();
+  if (!ps.available) {
+    messages.push('ℹ️  No PowerShell Clean Code / SOLID tool available');
+    messages.push('⏭️  SKIPPED - Complexity (no PowerShell tool)');
+    recordAudit('gate-3', 'complexity', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  // Filter to .ps1 files
+  const psFiles = input.changedFiles.filter(f => f.endsWith('.ps1') || f.endsWith('.psm1'));
+  if (psFiles.length === 0) {
+    messages.push('⏭️  SKIPPED - Complexity (no PowerShell files to check).');
+    recordAudit('gate-3', 'complexity', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  messages.push('Checking PowerShell code quality via PSScriptAnalyzer...');
+
+  const fileList = psFiles.map(f => `'${f}'`).join(',');
+  const command = `Invoke-ScriptAnalyzer -Path ${fileList} -IncludeRule PSAvoidUsingInvokeExpression,PSAvoidGlobalAliases -ErrorAction SilentlyContinue | ConvertTo-Json`;
+  const result = runPowerShellTool(ps, command, { cwd: input.cwd });
+
+  if (result.exitCode !== 0) {
+    messages.push('⚠️  PSScriptAnalyzer check failed, skipping');
+    recordAudit('gate-3', 'complexity', 'WARN', 0, startMs);
+    return { status: 'WARN', messages, exitCode: 0 };
+  }
+
+  try {
+    const findings = result.stdout.trim() ? JSON.parse(result.stdout.trim()) : [];
+    const count = Array.isArray(findings) ? findings.length : 0;
+    if (count > 0) {
+      messages.push(`⚠️  ${count} PSScriptAnalyzer findings (warnings only for PowerShell projects)`);
+      recordAudit('gate-3', 'complexity', 'WARN', count, startMs);
+      return { status: 'WARN', messages, exitCode: 0 };
+    }
+  } catch {
+    // JSON parse failure — not a gate failure
+  }
+
+  messages.push('✅ PASSED - PowerShell code quality check passed.');
+  recordAudit('gate-3', 'complexity', 'PASS', 0, startMs);
+  return { status: 'PASS', messages, exitCode: 0 };
+}

package/gates/gate-7.ts

@@ -0,0 +1,126 @@
+/**
+ * Gate 7: IaC Security Scanning (Terraform, Kubernetes, Docker, PowerShell DSC)
+ * Detects security issues in Infrastructure as Code files.
+ * TypeScript rewrite of githooks/adapters/gate-7.sh for cross-platform Node.js CLI.
+ */
+import path from 'path';
+import fs from 'fs';
+import {
+  GateInput, GateOutput, isToolAvailable, runTool, recordAudit, filterIaCFiles,
+  getChangedFiles, detectProjectLang,
+} from './common';
+
+export function runGate7(input: GateInput): GateOutput {
+  const startMs = Date.now();
+  const cwd = input.cwd || process.cwd();
+  const messages: string[] = [];
+
+  messages.push('');
+  messages.push('→ Gate 7: IaC Security Scanning (Terraform, Kubernetes, Docker)...');
+
+  // Filter to IaC files (includes PowerShell DSC per design)
+  const iacFiles = filterIaCFiles(input.changedFiles);
+
+  if (iacFiles.length === 0) {
+    messages.push('✅ PASSED - No IaC files detected in changes.');
+    recordAudit('gate-7', 'iac-security', 'PASS', 0, startMs);
+    return { status: 'PASS', messages, exitCode: 0 };
+  }
+
+  // Check for IaC adapter script (bash path for pre-commit context)
+  const adapterPath = findIaCAdapter(cwd);
+  if (!adapterPath) {
+    messages.push('ℹ️  SKIP - IaC adapter not found');
+    messages.push('⏭️  SKIPPED - IaC security (no IaC adapter found)');
+    recordAudit('gate-7', 'iac-security', 'SKIP', 0, startMs);
+    return { status: 'SKIP', messages, exitCode: 0 };
+  }
+
+  // Run checkov if available (preferred tool)
+  const checkov = isToolAvailable('checkov', cwd);
+  if (checkov.available) {
+    return runCheckov(checkov.path, checkov.via, iacFiles, cwd, startMs, messages);
+  }
+
+  // Fallback: run the bash IaC adapter via bash
+  messages.push('⚠️  checkov not installed — falling back to bash IaC adapter');
+  messages.push('   Install: pip install checkov');
+
+  const result = runTool('bash', [adapterPath, ...iacFiles], { cwd });
+  const combinedOutput = result.stdout + result.stderr;
+
+  if (result.exitCode === 0) {
+    messages.push(combinedOutput);
+    messages.push('✅ PASSED - IaC security scan.');
+    recordAudit('gate-7', 'iac-security', 'PASS', 0, startMs);
+    return { status: 'PASS', messages, exitCode: 0 };
+  }
+
+  messages.push(combinedOutput);
+  messages.push('');
+  messages.push('❌ BLOCKED - IaC security issues detected');
+  messages.push('Fix the security issues above before committing.');
+  messages.push('Tip: Install checkov for comprehensive IaC scanning: pip install checkov');
+  recordAudit('gate-7', 'iac-security', 'FAIL', result.exitCode, startMs);
+  return { status: 'FAIL', messages, exitCode: 1 };
+}
+
+function runCheckov(
+  cmdPath: string,
+  via: string,
+  files: string[],
+  cwd: string,
+  startMs: number,
+  messages: string[]
+): GateOutput {
+  const checkovCmd = via === 'npx' ? 'npx' : cmdPath;
+  const checkovArgs = via === 'npx' ? ['-y', 'checkov'] : [];
+
+  // Detect config file
+  const configPath = path.join(cwd, '.checkov.yaml');
+  if (fs.existsSync(configPath)) {
+    checkovArgs.push('--config-file', configPath);
+  }
+
+  // Run checkov on the changed IaC files
+  checkovArgs.push('--file', ...files, '--quiet', '--compact');
+
+  const result = runTool(checkovCmd, checkovArgs, { cwd });
+  const combinedOutput = result.stdout + result.stderr;
+
+  if (result.exitCode === 0) {
+    messages.push(combinedOutput);
+    messages.push('✅ PASSED - IaC security scan.');
+    recordAudit('gate-7', 'iac-security', 'PASS', 0, startMs);
+    return { status: 'PASS', messages, exitCode: 0 };
+  }
+
+  messages.push(combinedOutput);
+  messages.push('');
+  messages.push('❌ BLOCKED - IaC security issues detected');
+  messages.push('Fix the security issues above before committing.');
+  recordAudit('gate-7', 'iac-security', 'FAIL', result.exitCode, startMs);
+  return { status: 'FAIL', messages, exitCode: 1 };
+}
+
+function findIaCAdapter(cwd: string): string | null {
+  const candidates = [
+    path.join(cwd, 'githooks', 'adapters', 'iac.sh'),
+    path.join(cwd, 'githooks', 'adapters', 'iac', 'iac.sh'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+// ── CLI Entry Point ──
+if (process.argv.includes('--run')) {
+  const cwdIdx = process.argv.indexOf('--cwd');
+  const cwd = cwdIdx >= 0 ? process.argv[cwdIdx + 1] : process.cwd();
+  const changedFiles = getChangedFiles(cwd);
+  const projectLang = detectProjectLang(cwd);
+  const result = runGate7({ changedFiles, projectLang, cwd });
+  result.messages.forEach(m => console.log(m));
+  process.exit(result.exitCode);
+}