@activemind/scd 1.4.0

package/lib/commands/configure.js

@@ -0,0 +1,200 @@
+'use strict';
+const { RESET, BOLD, DIM, RED, GREEN, CYAN } = require('../output-constants');
+// lib/commands/configure.js
+
+module.exports = { register };
+
+function register(program) {
+  program
+    .command('configure')
+    .description('Manage global configuration (API key etc.)')
+    .option('--show',             'Show current global configuration')
+    .option('--central-url <url>',  'Set scd-server URL (enables push queue)')
+    .option('--clear-central-url',  'Remove scd-server URL (disables push queue)')
+    .option('--token <token>',         'Set scd-server API token')
+    .option('--clear-token',           'Remove scd-server API token')
+    .option('--server-timeout <value>', 'Set server API timeout (e.g. 15s, 30s). Default: 30s')
+    .option('--deep-timeout <value>',   'Set deep analysis timeout (e.g. 10m, 20m). Default: 20m')
+    .option('--trust-level <value>',    'Set global default trust level (maximum_privacy|balanced|maximum_analysis)')
+    .option('--scan-mode <value>',      'Set global default scan mode (full|fast)')
+    .option('--block-on-high <value>',  'Set global default block-on-high (true|false)')
+    .option('--block-on-critical <value>', 'Set global default block-on-critical (true|false)')
+    .action((opts) => {
+      const { getCentralUrl, setCentralUrl, removeCentralUrl, getCentralToken, setCentralToken, removeCentralToken,
+              getServerTimeout, setServerTimeout, getDeepTimeout, setDeepTimeout, parseTimeoutArg,
+              GLOBAL_CONFIG } =
+        require('../global-config');
+
+
+      // ── --central-url <url> ───────────────────────────────────────────────
+      if (opts.centralUrl) {
+        const url = opts.centralUrl.trim();
+        if (!url.startsWith('http://') && !url.startsWith('https://')) {
+          console.error(`\n${RED}✗ Invalid URL – must start with http:// or https://${RESET}\n`);
+          process.exit(1);
+        }
+        setCentralUrl(url);
+        const savedUrl = getCentralUrl();
+        console.log(`\n${GREEN}✓ Central URL saved${RESET} → ${DIM}${savedUrl}${RESET}`);
+        if (savedUrl !== url) {
+          console.log(`  ${DIM}(normalized from ${url})${RESET}`);
+        }
+        console.log(`  ${DIM}Push queue enabled – events will sync on each scd command.${RESET}\n`);
+        process.exit(0);
+      }
+
+      // ── --clear-central-url ───────────────────────────────────────────────
+      if (opts.clearCentralUrl) {
+        const removed = removeCentralUrl();
+        if (removed) {
+          console.log(`\n${GREEN}✓ Central URL removed${RESET} – push queue disabled.\n`);
+        } else {
+          console.log(`\n${DIM}No central URL configured.${RESET}\n`);
+        }
+        process.exit(0);
+      }
+
+      // ── --token <token> ───────────────────────────────────────────────────
+      if (opts.token) {
+        const token = opts.token.trim();
+        if (!token.startsWith('scd-')) {
+          console.error(`\n${RED}✗ Invalid token format – scd-server tokens start with scd-${RESET}\n`);
+          process.exit(1);
+        }
+        setCentralToken(token);
+        console.log(`\n${GREEN}✓ Token saved${RESET} → ${DIM}${GLOBAL_CONFIG}${RESET}`);
+        console.log(`  ${DIM}${token.slice(0, 12)}...${RESET}\n`);
+        process.exit(0);
+      }
+
+      // ── --clear-token ─────────────────────────────────────────────────────
+      if (opts.clearToken) {
+        const removed = removeCentralToken();
+        if (removed) {
+          console.log(`\n${GREEN}✓ Token removed${RESET} from ${DIM}${GLOBAL_CONFIG}${RESET}\n`);
+        } else {
+          console.log(`\n${DIM}No token to remove.${RESET}\n`);
+        }
+        process.exit(0);
+      }
+
+      // ── --server-timeout <value> ─────────────────────────────────────────
+      if (opts.serverTimeout !== undefined) {
+        try {
+          const ms = parseTimeoutArg(opts.serverTimeout);
+          setServerTimeout(ms);
+          const fmt = ms >= 60000 ? `${Math.round(ms/60000)}m` : `${Math.round(ms/1000)}s`;
+          console.log(`\n${GREEN}✓ Server timeout set to ${fmt} (${ms}ms)${RESET}\n`);
+        } catch (err) {
+          console.error(`\n${RED}❌ ${err.message}${RESET}\n`);
+          process.exit(1);
+        }
+        process.exit(0);
+      }
+
+      // ── --deep-timeout <value> ────────────────────────────────────────────
+      if (opts.deepTimeout !== undefined) {
+        try {
+          const ms = parseTimeoutArg(opts.deepTimeout);
+          setDeepTimeout(ms);
+          const fmt = ms >= 60000 ? `${Math.round(ms/60000)}m` : `${Math.round(ms/1000)}s`;
+          console.log(`\n${GREEN}✓ Deep analysis timeout set to ${fmt} (${ms}ms)${RESET}\n`);
+        } catch (err) {
+          console.error(`\n${RED}❌ ${err.message}${RESET}\n`);
+          process.exit(1);
+        }
+        process.exit(0);
+      }
+
+      // ── global repo defaults ─────────────────────────────────────────────
+      const VALID_TRUST  = ['maximum_privacy', 'balanced', 'maximum_analysis'];
+      const VALID_MODES  = ['full', 'fast'];
+
+      if (opts.trustLevel !== undefined) {
+        if (!VALID_TRUST.includes(opts.trustLevel)) {
+          console.error(`\n${RED}✗ Invalid trust level. Use: ${VALID_TRUST.join(' | ')}${RESET}\n`);
+          process.exit(1);
+        }
+        require('../global-config').set('REPO_TRUST_LEVEL', opts.trustLevel);
+        console.log(`\n${GREEN}✓ Global default trust_level set to ${opts.trustLevel}${RESET}\n`);
+        process.exit(0);
+      }
+
+      if (opts.scanMode !== undefined) {
+        if (!VALID_MODES.includes(opts.scanMode)) {
+          console.error(`\n${RED}✗ Invalid scan mode. Use: full | fast${RESET}\n`);
+          process.exit(1);
+        }
+        require('../global-config').set('REPO_SCAN_MODE', opts.scanMode);
+        console.log(`\n${GREEN}✓ Global default scan_mode set to ${opts.scanMode}${RESET}\n`);
+        process.exit(0);
+      }
+
+      if (opts.blockOnHigh !== undefined) {
+        const val = opts.blockOnHigh.toLowerCase();
+        if (val !== 'true' && val !== 'false') {
+          console.error(`\n${RED}✗ Invalid value. Use: true | false${RESET}\n`);
+          process.exit(1);
+        }
+        require('../global-config').set('REPO_BLOCK_ON_HIGH', val);
+        console.log(`\n${GREEN}✓ Global default block_on_high set to ${val}${RESET}\n`);
+        process.exit(0);
+      }
+
+      if (opts.blockOnCritical !== undefined) {
+        const val = opts.blockOnCritical.toLowerCase();
+        if (val !== 'true' && val !== 'false') {
+          console.error(`\n${RED}✗ Invalid value. Use: true | false${RESET}\n`);
+          process.exit(1);
+        }
+        require('../global-config').set('REPO_BLOCK_ON_CRITICAL', val);
+        console.log(`\n${GREEN}✓ Global default block_on_critical set to ${val}${RESET}\n`);
+        process.exit(0);
+      }
+
+      // ── --show (default if no flags) ──────────────────────────────────────
+      const centralUrl = getCentralUrl();
+      const gc         = require('../global-config');
+
+      console.log(`\n${CYAN}${BOLD}Secure Code by Design – Global configuration${RESET}\n`);
+      console.log(`  Central URL:  ${centralUrl ? GREEN + centralUrl : DIM + '(not set – push queue disabled)'}${RESET}`);
+      console.log('');
+      if (centralUrl) {
+        const token   = getCentralToken();
+        const { queueSize, staleCount } = require('../push-queue');
+        const pending = queueSize();
+        const stale   = staleCount();
+        console.log(`  Token:        ${token ? DIM + token.slice(0, 12) + '...' + RESET : RED + '(not set)' + RESET}`);
+        console.log(`  Queue:        ${DIM}${pending} pending event(s)${stale > 0 ? '  ' + RED + stale + ' stale' + RESET : ''}${RESET}`);
+        const fmtMs  = ms => ms >= 60000 ? `${Math.round(ms/60000)}m` : `${Math.round(ms/1000)}s`;
+        console.log(`  Server timeout: ${DIM}${fmtMs(getServerTimeout())}${RESET}  Deep timeout: ${DIM}${fmtMs(getDeepTimeout())}${RESET}`);
+        console.log('');
+        console.log(`  ${DIM}Clear URL:       scd configure --clear-central-url${RESET}`);
+        if (token) {
+          console.log(`  ${DIM}Clear token:     scd configure --clear-token${RESET}`);
+        } else {
+          console.log(`  ${DIM}Set token:       scd configure --token <token>${RESET}`);
+        }
+      } else {
+        console.log(`  ${DIM}Set server URL:  scd configure --central-url https://your-server:3000${RESET}`);
+        console.log(`  ${DIM}Then set token:  scd configure --token <token>${RESET}`);
+      }
+
+      // Show global repo defaults
+      const REPO_KEYS = ['trust_level','scan_mode','block_on_critical','block_on_high'];
+      const CODE_DEFAULTS = { trust_level: 'balanced', scan_mode: 'full', block_on_critical: true, block_on_high: true };
+      const hasAny = REPO_KEYS.some(k => gc.get('REPO_' + k.toUpperCase()) !== undefined);
+      console.log(`  ${BOLD}Global repo defaults${RESET} ${DIM}(fallback for all repos unless overridden in config.yml)${RESET}`);
+      for (const key of REPO_KEYS) {
+        const raw = gc.get('REPO_' + key.toUpperCase());
+        const val = raw !== undefined ? raw : String(CODE_DEFAULTS[key]);
+        const src = raw !== undefined ? GREEN + val + RESET : DIM + val + ' (code default)' + RESET;
+        console.log(`  ${DIM}${key.padEnd(20)}${RESET}${src}`);
+      }
+      console.log('');
+      console.log(`  ${DIM}Change global repo defaults with: scd configure --trust-level <value>${RESET}`);
+      console.log(`  ${DIM}                                  scd configure --scan-mode <fast|full>${RESET}`);
+      console.log(`  ${DIM}                                  scd configure --block-on-high <true|false>${RESET}`);
+      console.log('');
+    });
+}

package/lib/commands/doctor.js

@@ -0,0 +1,14 @@
+'use strict';
+// lib/commands/doctor.js
+
+module.exports = { register };
+
+function register(program) {
+  program
+    .command('doctor')
+    .description('Check installation health')
+    .action(async () => {
+      const { doctor } = require('../doctor');
+      await doctor();
+    });
+}

package/lib/commands/exceptions.js

@@ -0,0 +1,19 @@
+'use strict';
+// lib/commands/exceptions.js
+
+module.exports = { register };
+
+function register(program) {
+  program
+    .command('exceptions')
+    .description('List exceptions and ignores in the local store')
+    .option('--list <status>', 'Filter by status: pending | approved | rejected | all (default: all)')
+    .action(async (opts) => {
+      const { listExceptions } = require('../exception-manager');
+      const { getRepoRoot } = require('../config');
+      const { warnIfOutdated } = require('../cli-helpers');
+      const repoRoot = getRepoRoot();
+      listExceptions(repoRoot, opts.list || 'all');
+      warnIfOutdated();
+    });
+}

package/lib/commands/export-findings.js

@@ -0,0 +1,46 @@
+'use strict';
+// lib/commands/export-findings.js
+
+module.exports = { register };
+
+function register(program) {
+  program
+    .command('export-findings')
+    .description('Export findings from a scan for external review')
+    .option('--scan <id>',        'Scan ID to export (default: latest scan)')
+    .option('--severity <level>', 'Filter by severity: critical, high, medium, exposure')
+    .option('--rule <id>',        'Filter to a specific rule ID')
+    .option('--deep-only',        'Export only findings that have a deep analysis result')
+    .option('--output <path>',    'Output file path (default: ~/.scd/repos/{id}/exports/scd-findings-{scanId}.json)')
+    .action(async (opts) => {
+      const path  = require('path');
+      const store = require('../store');
+      const { exportFindings } = require('../export-findings');
+      const { loadCache }      = require('../scan-cache');
+      const { getRepoRoot }    = require('../config');
+      const repoRoot = getRepoRoot();
+
+      // Resolve scan ID first so we can use it in the default filename
+      let resolvedScanId = opts.scan || null;
+      if (!resolvedScanId) {
+        const latest = loadCache(repoRoot);
+        if (latest) resolvedScanId = latest.scanId;
+      }
+
+      const defaultName = 'scd-findings-' + (resolvedScanId || 'scan') + '.json';
+      const outputPath  = opts.output
+        ? path.resolve(process.cwd(), opts.output)
+        : store.exportPath(repoRoot, defaultName);
+
+      await exportFindings({
+        repoRoot,
+        scanId:               opts.scan     || null,
+        severity:             opts.severity || null,
+        rule:                 opts.rule     || null,
+        deepOnly:             !!opts.deepOnly,
+        outputPath,
+        includeRuleInternals: false,
+        command:              'export-findings',
+      });
+    });
+}

package/lib/commands/findings.js

@@ -0,0 +1,306 @@
+'use strict';
+const { RESET, BOLD, DIM, RED, GREEN, YELLOW, BLUE, CYAN } = require('../output-constants');
+// lib/commands/findings.js
+
+module.exports = { register, findingsAction };
+
+async function findingsAction(findingId, opts) {
+      const { loadCache, loadScan, cacheAge } = require('../scan-cache');
+      const { getRepoRoot } = require('../config');
+      const { warnIfOutdated } = require('../cli-helpers');
+      const repoRoot = getRepoRoot();
+
+
+      const SEV_ICON  = { CRITICAL: '🔴', HIGH: '🟠', MEDIUM: '🟡', EXPOSURE: '🔷', INFO: '⬜' };
+      const SEV_COLOR = { CRITICAL: RED, HIGH: YELLOW, MEDIUM: YELLOW, EXPOSURE: BLUE, INFO: DIM };
+
+      // Load scan data
+      let scan = null;
+      let isHistoric = false;
+      if (opts.scan) {
+        scan = loadScan(repoRoot, opts.scan);
+        isHistoric = true;
+        if (!scan) {
+          console.error(`\nRED❌ Scan not found: ${opts.scan}${RESET}`);
+          console.error(`${DIM}   Run scd repo scans to list available scans${RESET}\n`);
+          process.exit(1);
+        }
+      } else {
+        scan = loadCache(repoRoot);
+        if (!scan) {
+          console.error(`\nRED❌ No scan found for this repo.${RESET}`);
+          console.error(`${DIM}   Run scd scan first${RESET}\n`);
+          process.exit(1);
+        }
+      }
+
+      // ── --show-suppressed mode ─────────────────────────────────────────────
+      // Entirely separate display path — suppressed findings are a different data
+      // set with different fields (base_severity, context_modifiers, suppress_reason).
+      if (opts.showSuppressed) {
+        const suppressed = scan.suppressed_findings || [];
+        const scanAge    = scan.scanDate ? cacheAge(scan.scanDate) : 'unknown';
+        const scanLabel  = opts.scan ? `Scan ${scan.scanId}` : 'Last scan';
+
+        console.log(`\n${BOLD}Suppressed Findings${RESET}  ${DIM}${scanLabel} · ${scanAge} · suppressed by file context${RESET}`);
+        console.log(`${DIM}  These findings were detected but suppressed — their effective severity fell below threshold.${RESET}`);
+        console.log(`${DIM}${'─'.repeat(64)}${RESET}\n`);
+
+        if (suppressed.length === 0) {
+          console.log(`${DIM}  No suppressed findings in this scan.${RESET}\n`);
+          return;
+        }
+
+        // Apply --rule filter if given
+        let toShow = suppressed;
+        if (opts.rule) {
+          toShow = toShow.filter(f => f.ruleId === opts.rule);
+        }
+
+        // Group by file
+        const byFile = {};
+        for (const f of toShow) {
+          if (!byFile[f.filePath]) byFile[f.filePath] = [];
+          byFile[f.filePath].push(f);
+        }
+
+        for (const [filePath, fileFindings] of Object.entries(byFile).sort()) {
+          console.log(`  ${BOLD}${filePath}${RESET}`);
+          for (const f of fileFindings) {
+            const baseSev  = f.base_severity || '?';
+            const basIcon  = SEV_ICON[baseSev]  || '⬜';
+            const basColor = SEV_COLOR[baseSev] || DIM;
+            const fid      = f.findingId ? `  ${DIM}${f.findingId}${RESET}` : '';
+            const line     = f.line      ? `:${f.line}` : '';
+            // Show base severity (what the rule said) → suppressed
+            console.log(`    ${basIcon}  ${basColor}${f.name}${RESET}  ${DIM}${f.ruleId}${line}${RESET}${fid}  ${DIM}[suppressed]${RESET}`);
+            if (f.snippet && f.snippet !== '[REDACTED]') {
+              const snip = f.snippet.trim().slice(0, 80);
+              console.log(`       ${DIM}${snip}${snip.length === 80 ? '…' : ''}${RESET}`);
+            }
+            // File context that drove suppression
+            if (f.file_context) {
+              const fc = f.file_context;
+              const fcParts = [fc.file_type];
+              if (fc.test_framework) fcParts.push(fc.test_framework);
+              if (fc.language)       fcParts.push(fc.language);
+              console.log(`       ${DIM}context: ${fcParts.join(' · ')}${RESET}`);
+            }
+            // Show each modifier that contributed
+            if (f.context_modifiers && f.context_modifiers.length > 0) {
+              for (const m of f.context_modifiers) {
+                console.log(`       ${DIM}modifier: ${m.signal}  (${m.modifier})${RESET}`);
+              }
+            }
+            // Suppress reason
+            if (f.suppress_reason) {
+              console.log(`       ${DIM}reason: ${f.suppress_reason}${RESET}`);
+            }
+            console.log('');
+          }
+          console.log('');
+        }
+
+        console.log(`${DIM}  ${toShow.length} suppressed finding(s)${RESET}`);
+        console.log(`${DIM}  Base severity shown — effective score fell to ≤ 0 after context modifiers.${RESET}\n`);
+        return;
+      }
+
+      // ── Normal findings mode ───────────────────────────────────────────────
+
+      let findings = scan.findings || [];
+      const showAll      = opts.all || opts.excepted || !!findingId; // single finding searches all
+      const showExcepted = opts.excepted;
+      const showVerbose  = opts.verbose || !!findingId; // single finding always verbose
+      const scanAge      = scan.scanDate ? cacheAge(scan.scanDate) : 'unknown';
+
+      // Re-evaluate exception status against current config.yml — a finding may have been
+      // accepted/ignored since the last scan without re-running the scan.
+      if (!isHistoric && repoRoot) {
+        try {
+          const { loadConfig, isExcepted } = require('../config');
+          const cfg = loadConfig(repoRoot);
+          findings = findings.map(f => {
+            if (f.excepted) return f; // already marked excepted in cache
+            const lineContent = f.snippet && f.snippet !== '[REDACTED]' ? f.snippet : null;
+            const result = isExcepted(cfg, f, lineContent);
+            if (result.excepted) return { ...f, excepted: true };
+            if (result.rejected) return { ...f, rejected: true };
+            return f;
+          });
+        } catch { /* non-fatal — fall back to cached values */ }
+      }
+
+      // If a specific findingId was given, filter to that one finding and show verbose
+      if (findingId) {
+        findings = findings.filter(f => f.findingId === findingId);
+        if (findings.length === 0) {
+          console.error(`\nRED❌ Finding ${findingId} not found in this scan.${RESET}`);
+          console.error(`${DIM}   Run scd findings to see all finding IDs${RESET}\n`);
+          process.exit(1);
+        }
+      }
+
+      // Apply --open filter (default) — exclude excepted and resolved
+      if (!showAll) {
+        findings = findings.filter(f => !f.excepted && !f.resolved);
+      }
+
+      // Apply --excepted filter
+      if (showExcepted) {
+        findings = findings.filter(f => f.excepted);
+      }
+
+      // Apply --severity filter
+      if (opts.severity) {
+        const sev = opts.severity.toUpperCase();
+        findings = findings.filter(f => f.severity === sev);
+      }
+
+      // Apply --rule filter
+      if (opts.rule) {
+        findings = findings.filter(f => f.ruleId === opts.rule);
+      }
+
+      // Header
+      const scanLabel = opts.scan ? `Scan ${scan.scanId}` : `Last scan`;
+      const modeLabel = findingId
+        ? `finding ${findingId}`
+        : showExcepted ? 'excepted findings' : showAll ? 'all findings' : 'open findings only';
+      console.log(`\n${BOLD}Findings${RESET}  ${DIM}${scanLabel} · ${scanAge} · ${modeLabel}${RESET}`);
+      if (!showAll) {
+        console.log(`${DIM}  Showing unhandled findings. Use --all to include excepted and resolved.${RESET}`);
+      }
+      if (isHistoric && opts.open) {
+        console.log(`${YELLOW}  Note: --open on a historic scan reflects exception status at scan time.${RESET}`);
+      }
+      // Hint about suppressed findings if any exist in this scan
+      const suppressedCount = (scan.suppressed_findings || []).length;
+      if (suppressedCount > 0) {
+        console.log(`${DIM}  ${suppressedCount} finding(s) suppressed by file context  ·  scd findings --show-suppressed${RESET}`);
+      }
+      console.log(`${DIM}${'─'.repeat(64)}${RESET}\n`);
+
+      if (findings.length === 0) {
+        if (showExcepted) {
+          console.log(`${DIM}  No excepted findings in this scan.${RESET}\n`);
+        } else if (!showAll) {
+          console.log(`${GREEN}  ✅ No open findings.${RESET}${opts.severity || opts.rule ? '' : ' All findings are excepted or resolved.'}\n`);
+        } else {
+          console.log(`${DIM}  No findings match the current filters.${RESET}\n`);
+        }
+        return;
+      }
+
+      // Group by file
+      const byFile = {};
+      for (const f of findings) {
+        if (!byFile[f.filePath]) byFile[f.filePath] = [];
+        byFile[f.filePath].push(f);
+      }
+
+      const SEV_ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, EXPOSURE: 3, INFO: 4 };
+
+      for (const [filePath, filefindings] of Object.entries(byFile).sort()) {
+        console.log(`  ${BOLD}${filePath}${RESET}`);
+        const sorted = [...filefindings].sort((a, b) =>
+          (SEV_ORDER[a.severity] ?? 9) - (SEV_ORDER[b.severity] ?? 9)
+        );
+        for (const f of sorted) {
+          const icon  = SEV_ICON[f.severity]  || '⬜';
+          const color = SEV_COLOR[f.severity] || DIM;
+          const fid   = f.findingId ? `  ${DIM}${f.findingId}${RESET}` : '';
+          const exc   = f.excepted  ? `  ${DIM}[excepted]${RESET}` : '';
+          const res   = f.resolved  ? `  ${DIM}[resolved]${RESET}` : '';
+          const line  = f.line      ? `:${f.line}` : '';
+          // Show severity downgrade hint when context modifiers reduced severity
+          const sevDowngrade = (f.base_severity && f.base_severity !== f.severity)
+            ? `  ${DIM}↓ ${f.base_severity} → ${f.severity}${RESET}`
+            : '';
+          console.log(`    ${icon}  ${color}${f.name}${RESET}  ${DIM}${f.ruleId}${line}${RESET}${fid}${exc}${res}${sevDowngrade}`);
+          if (f.snippet && f.snippet !== '[REDACTED]') {
+            const snip = f.snippet.trim().slice(0, 80);
+            console.log(`       ${DIM}${snip}${snip.length === 80 ? '…' : ''}${RESET}`);
+          }
+          if (showVerbose) {
+            if (f.why) {
+              console.log(`\n       ${BOLD}Problem${RESET}`);
+              const whyWords = f.why.split(' ');
+              let whyLine = '       ';
+              for (const word of whyWords) {
+                if (whyLine.length + word.length > 79) { console.log(whyLine); whyLine = '       ' + word + ' '; }
+                else whyLine += word + ' ';
+              }
+              if (whyLine.trim()) console.log(whyLine);
+            }
+            if (f.scenario) {
+              console.log(`\n       ${BOLD}Scenario${RESET}`);
+              // Word-wrap at 72 chars
+              const words = f.scenario.split(' ');
+              let line2 = '       ';
+              for (const word of words) {
+                if (line2.length + word.length > 79) {
+                  console.log(line2);
+                  line2 = '       ' + word + ' ';
+                } else {
+                  line2 += word + ' ';
+                }
+              }
+              if (line2.trim()) console.log(line2);
+            }
+            if (f.fix) {
+              console.log(`\n       ${BOLD}Fix${RESET}`);
+              const words = f.fix.split(' ');
+              let line2 = '       ';
+              for (const word of words) {
+                if (line2.length + word.length > 79) {
+                  console.log(line2);
+                  line2 = '       ' + word + ' ';
+                } else {
+                  line2 += word + ' ';
+                }
+              }
+              if (line2.trim()) console.log(line2);
+            }
+            // Show context modifiers in verbose mode when severity was adjusted
+            if (f.context_modifiers && f.context_modifiers.length > 0) {
+              console.log(`\n       ${BOLD}File context${RESET}`);
+              for (const m of f.context_modifiers) {
+                console.log(`       ${DIM}${m.signal}  (${m.modifier})${RESET}`);
+              }
+            }
+            console.log('');
+          }
+        }
+        console.log('');
+      }
+
+      // Summary + hints
+      const counts = {};
+      for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
+      const parts = ['CRITICAL','HIGH','MEDIUM','EXPOSURE']
+        .filter(s => counts[s])
+        .map(s => `${SEV_ICON[s]} ${counts[s]} ${s.toLowerCase()}`);
+      console.log(`${DIM}  ${findings.length} finding(s)${parts.length ? ': ' + parts.join('  ') : ''}${RESET}`);
+      if (!showAll && !showExcepted && findings.length > 0) {
+        console.log(`${DIM}  scd accept <finding-id> --reason "..."   or   scd ignore <finding-id> --reason "..."${RESET}`);
+      }
+      console.log('');
+      warnIfOutdated();
+}
+
+function register(program) {
+  program
+    .command('findings [findingId]')
+    .description('List findings from the last scan (default: open/unhandled only)')
+    .option('--all',              'Show all findings including excepted and resolved')
+    .option('--severity <level>', 'Filter by severity: critical, high, medium, exposure')
+    .option('--rule <id>',        'Filter by rule ID (e.g. JS-ERR-002)')
+    .option('--scan <id>',        'Load a specific scan by ID instead of last scan')
+    .option('--excepted',         'Show only excepted findings')
+    .option('--show-suppressed',  'Show findings suppressed by file context (test files, vendor code, etc.)')
+    .option('--verbose',          'Show problem description, attack scenario, and fix for each finding')
+    .action(async (findingId, opts) => {
+      await findingsAction(findingId, opts);
+    });
+}

package/lib/commands/ignore.js

@@ -0,0 +1,28 @@
+'use strict';
+const { RESET, DIM, RED } = require('../output-constants');
+// lib/commands/ignore.js
+
+module.exports = { register };
+
+function register(program) {
+  program
+    .command('ignore [findingId]')
+    .description('Ignore a finding (requires team-lead approval via scd-server)')
+    .option('--reason <text>', 'Reason for ignoring this finding (required)')
+    .option('--tag <tag>',     'Optional tag for filtering (e.g. false_positive, out_of_scope, third_party)')
+    .action(async (findingId, opts) => {
+      const { addExceptionById } = require('../exception-manager');
+      const { getRepoRoot } = require('../config');
+      const repoRoot = getRepoRoot();
+      if (!findingId) {
+        console.error(RED + '❌ Finding ID required. Run scd findings to see IDs.' + RESET);
+        console.error(DIM + '   Usage: scd ignore <finding-id> --reason "..."' + RESET);
+        process.exit(1);
+      }
+      if (!opts.reason) {
+        console.error(RED + '❌ --reason is required.' + RESET);
+        process.exit(1);
+      }
+      await addExceptionById(repoRoot, findingId, opts, 'ignore');
+    });
+}

package/lib/commands/init.js

@@ -0,0 +1,16 @@
+'use strict';
+// lib/commands/init.js
+
+module.exports = { register };
+
+function register(program) {
+  program
+    .command('init')
+    .description('Initialise Secure Code by Design in this repo and install git hooks')
+    .action(async () => {
+      const { initRepo } = require('../init-repo');
+      const { getRepoRoot } = require('../config');
+      const repoRoot = getRepoRoot();
+      await initRepo(repoRoot);
+    });
+}

package/lib/commands/insights.js

@@ -0,0 +1,24 @@
+'use strict';
+const { RESET } = require('../output-constants');
+// lib/commands/insights.js
+
+module.exports = { register };
+
+function register(program) {
+  program
+    .command('insights')
+    .description('Analyze behavioral patterns and knowledge gaps from the audit log')
+    .option('--days <n>', 'Analyze the last N days (default: 90)', '90')
+    .action(async (opts) => {
+      const { analyzeInsights } = require('../insights-analyzer');
+      const { renderInsights }  = require('../insights-output');
+      const { getRepoRoot }     = require('../config');
+      const repoRoot            = getRepoRoot();
+      const days                = Math.max(1, parseInt(opts.days) || 90);
+
+      console.log(`\nDIM↺ Analyzing audit log (last ${days} days)…${RESET}`);
+
+      const analysis = await analyzeInsights(repoRoot, { days });
+      renderInsights(analysis);
+    });
+}

package/lib/commands/install.js

@@ -0,0 +1,15 @@
+'use strict';
+// lib/commands/install.js
+
+module.exports = { register };
+
+function register(program) {
+  const { Command } = require('commander');
+  const cmd = new Command('install')
+    .description('Install global git hooks on this machine')
+    .action(async () => {
+      const { install } = require('../installer');
+      await install();
+    });
+  program.addCommand(cmd);
+}