sinapse-ai 1.6.1 → 1.8.0

package/bin/sinapse.js

@@ -9,7 +9,7 @@
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
-const { execSync } = require('child_process');
+const { execSync, spawnSync } = require('child_process');
 const { emitDeprecationWarning } = require('./utils/deprecation-warning');
 
 // Story A.2 — unified logger. Levels: error/warn/info/debug.
@@ -1174,13 +1174,23 @@ async function main() {
     }
 
     case 'health': {
-      // Framework health analytics
+      // Framework health analytics. Default = lightweight install-health
+      // (hooks/squads/rules/skills). --deep runs the full core/health-check
+      // engine (~35 project/runtime checks). --output-file writes the report.
       const { runHealth } = require('../.sinapse-ai/cli/commands/health/index.js');
       const healthArgs = args.slice(1);
+      const outIdx = healthArgs.indexOf('--output-file');
+      const isDeepHealth = healthArgs.includes('--deep');
       await runHealth({
         json: healthArgs.includes('--json'),
         fix: healthArgs.includes('--fix'),
+        deep: isDeepHealth,
+        outputFile: outIdx >= 0 ? healthArgs[outIdx + 1] : undefined,
       });
+      // The --deep engine can leave async handles (e.g. spawned git checks)
+      // open; exit explicitly so the CLI returns promptly. The report is fully
+      // written/printed synchronously above. Lightweight path exits naturally.
+      if (isDeepHealth) process.exit(0);
       break;
     }
 
@@ -1207,12 +1217,146 @@ async function main() {
       break;
     }
 
+    case 'graph': {
+      // Dependency/stats dashboard. Consolidated from the deprecated
+      // standalone `sinapse-graph` binary into a subcommand of the main CLI.
+      // Closes the published interface contract (claude-md template + CI test
+      // expect `sinapse graph --deps` to work in every installed project).
+      const { run } = require('../.sinapse-ai/core/graph-dashboard/cli');
+      await run(args.slice(1));
+      break;
+    }
+
+    case 'mcp': {
+      // Global MCP configuration manager (setup, link, status, add).
+      // Routes to the Commander CLI, same pattern as the `qa` case.
+      const { run } = require('../.sinapse-ai/cli/index.js');
+      await run(process.argv);
+      break;
+    }
+
+    case 'generate': {
+      // Document generator (templates: prd/adr/story/epic/task) — routes to the
+      // Commander CLI. Without this case `sinapse generate` fell through to the
+      // default and was passed to Claude Code as args (same bug class as graph/ids).
+      try {
+        const { run } = require('../.sinapse-ai/cli/index.js');
+        await run(process.argv);
+      } catch (error) {
+        logger.error(`❌ Generate command error: ${error.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'create': {
+      // Component generator — sinapse create <agent|task|workflow>
+      // Exposes ComponentGenerator (template + elicitation) at the CLI.
+      try {
+        const ComponentGenerator = require('../.sinapse-ai/infrastructure/scripts/component-generator');
+        const type = args[1];
+        if (!type || type.startsWith('--')) {
+          logger.error('Usage: sinapse create <agent|task|workflow>');
+          process.exit(1);
+        }
+        const generator = new ComponentGenerator({ rootPath: process.cwd() });
+        const result = await generator.generateComponent(type, {});
+        process.exit(result && result.success === false ? 1 : 0);
+      } catch (error) {
+        logger.error(`❌ Create command error: ${error.message}`);
+        process.exit(1);
+      }
+      break; // unreachable (both branches process.exit) — satisfies no-fallthrough
+    }
+
+    case 'mode': {
+      // Permission mode manager — sinapse mode [explore|ask|auto] [--cycle]
+      // Exposes PermissionMode (explore/ask/auto) at the CLI.
+      try {
+        const { PermissionMode } = require('../.sinapse-ai/core/permissions');
+        const pm = new PermissionMode(process.cwd());
+        await pm.load(); // load persisted mode first
+        const target = args[1];
+        let info;
+        if (args.includes('--cycle')) {
+          info = await pm.cycleMode();
+        } else if (target && !target.startsWith('--')) {
+          info = await pm.setMode(target);
+        } else {
+          info = pm.getModeInfo();
+        }
+        console.log(`Permission mode: ${info.name} — ${info.description}`);
+        process.exit(0);
+      } catch (error) {
+        logger.error(`❌ Mode command error: ${error.message}`);
+        process.exit(1);
+      }
+      break; // unreachable (both branches process.exit) — satisfies no-fallthrough
+    }
+
+    case 'orchestrate': {
+      // Autonomous pipeline entry point (Epic 0 — MasterOrchestrator).
+      // Usage: sinapse orchestrate <story-id> [--status|--stop|--resume]
+      //                                        [--dry-run] [--epic N] [--strict]
+      // Without this case the most powerful pipeline (executeFullPipeline) was
+      // only reachable programmatically — violating Art. I (CLI First).
+      try {
+        const orchestration = require('../.sinapse-ai/core/orchestration');
+        const epicIdx = args.indexOf('--epic');
+        // The story-id is the first positional arg after `orchestrate` — i.e.
+        // the first token that is neither a flag nor the `--epic` value. This
+        // keeps `orchestrate STORY-1 --status` and `orchestrate --status STORY-1`
+        // both resolving STORY-1 as the id.
+        const epicValueIdx = epicIdx !== -1 ? epicIdx + 1 : -1;
+        const storyId = args
+          .slice(1)
+          .find((a, i) => !a.startsWith('--') && i + 1 !== epicValueIdx);
+        const options = {
+          projectRoot: process.cwd(),
+          dryRun: args.includes('--dry-run'),
+          strict: args.includes('--strict'),
+          epic: epicIdx !== -1 ? parseInt(args[epicIdx + 1], 10) : undefined,
+        };
+
+        let result;
+        if (args.includes('--status')) {
+          result = await orchestration.orchestrateStatus(storyId, options);
+        } else if (args.includes('--stop')) {
+          result = await orchestration.orchestrateStop(storyId, options);
+        } else if (args.includes('--resume')) {
+          result = await orchestration.orchestrateResume(storyId, options);
+        } else {
+          result = await orchestration.orchestrate(storyId, options);
+        }
+
+        const exitCode =
+          result && typeof result.exitCode === 'number'
+            ? result.exitCode
+            : result && result.success === false
+              ? 1
+              : 0;
+        process.exit(exitCode);
+      } catch (error) {
+        logger.error(`❌ Orchestrate command error: ${error.message}`);
+        process.exit(1);
+      }
+      break; // unreachable (both branches process.exit) — satisfies no-fallthrough
+    }
+
     case undefined:
       // No arguments - launch Claude Code with SINAPSE branding
       launchSinapse([]);
       break;
 
     default:
+      // IDS subcommands (`ids:query`, `ids:health`, ...) delegate to the
+      // dedicated IDS CLI. Without this they fell through to launchSinapse and
+      // were silently passed to Claude Code as args (confirmed bug).
+      if (typeof command === 'string' && command.startsWith('ids:')) {
+        const idsBin = path.join(__dirname, 'sinapse-ids.js');
+        const result = spawnSync(process.execPath, [idsBin, ...args], { stdio: 'inherit' });
+        process.exit(result.status === null ? 1 : result.status);
+      }
       // Any unknown command is passed through to Claude Code as arguments
       // e.g. `sinapse --model sonnet` → `claude --model sonnet`
       launchSinapse(args);

package/bin/utils/secret-scanner-core.js

@@ -0,0 +1,253 @@
+'use strict';
+
+/**
+ * Secret Scanner Core — shared detection logic.
+ *
+ * Single source of truth for secret detection, imported by BOTH:
+ *   - .claude/hooks/secret-scanning.cjs  (Claude Code PreToolUse, Write/Edit content)
+ *   - bin/utils/staged-secret-scan.js    (git pre-commit, staged diff content)
+ *
+ * Hardening (Frente 4.2 — Stream A):
+ *   - All 20+ named patterns preserved (no regression).
+ *   - Shannon entropy: flags high-entropy tokens (>= 20 contiguous chars,
+ *     >= 4.5 bits/char) as suspected secrets, BEYOND the named patterns.
+ *     Lockfile-hash context + code-identifier band are allowlisted to avoid
+ *     false positives on integrity hashes and long camelCase symbols.
+ *   - Allowlist: placeholders (your-key-here, xxx, CHANGEME, REPLACE_ME, <...>,
+ *     example.com, etc.) and obvious fakes PASS.
+ *   - Redaction: matched secrets are never printed in full.
+ *   - Designed for fail-CLOSED callers (this module never silently allows).
+ *
+ * @module bin/utils/secret-scanner-core
+ */
+
+// Private-key PEM headers are built from fragments so this source file holds no
+// literal "BEGIN ... PRIVATE KEY" marker (avoids self-tripping secret scanners).
+const PK = 'PRIVATE KEY';
+const BEGIN = '-----BEGIN ';
+const END5 = '-----';
+
+const NAMED_PATTERNS = [
+  // API Keys & Tokens
+  { name: 'AWS Access Key', pattern: /AKIA[0-9A-Z]{16}/ },
+  { name: 'AWS Secret Key', pattern: /(?:aws_secret_access_key|secret_key)\s*[=:]\s*['"]?[A-Za-z0-9/+=]{40}['"]?/i, lowConfidence: true },
+  { name: 'GitHub Token', pattern: /gh[ps]_[A-Za-z0-9_]{36,}/ },
+  { name: 'GitHub OAuth', pattern: /gho_[A-Za-z0-9_]{36,}/ },
+  { name: 'GitHub Fine-Grained Token', pattern: /github_pat_[A-Za-z0-9_]{22,}/ },
+  { name: 'Slack Token', pattern: /xox[bpors]-[0-9]{10,}-[A-Za-z0-9-]+/ },
+  { name: 'Stripe Key', pattern: /[sr]k_(live|test)_[A-Za-z0-9]{20,}/ },
+  { name: 'OpenAI Key', pattern: new RegExp('sk-[A-Za-z0-9]{20,}'), entropyGated: true },
+  { name: 'Anthropic Key', pattern: new RegExp('sk-ant-[A-Za-z0-9-]{20,}') },
+  { name: 'Supabase Key', pattern: /eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\.[A-Za-z0-9_-]{50,}/ },
+  { name: 'Google API Key', pattern: /AIza[0-9A-Za-z_-]{35}/ },
+  { name: 'Vercel Token', pattern: /vercel_[A-Za-z0-9]{20,}/ },
+
+  // Private Keys (built dynamically; no literal header in source)
+  { name: 'RSA Private Key', pattern: new RegExp(BEGIN + 'RSA ' + PK + END5) },
+  { name: 'SSH Private Key', pattern: new RegExp(BEGIN + 'OPENSSH ' + PK + END5) },
+  { name: 'PGP Private Key', pattern: new RegExp(BEGIN + 'PGP ' + PK + ' BLOCK' + END5) },
+  { name: 'EC Private Key', pattern: new RegExp(BEGIN + 'EC ' + PK + END5) },
+  { name: 'DSA Private Key', pattern: new RegExp(BEGIN + 'DSA ' + PK + END5) },
+  { name: 'Generic Private Key', pattern: new RegExp(BEGIN + PK + END5) },
+
+  // Connection Strings
+  { name: 'DB Connection String', pattern: /(?:postgres|mysql|mongodb|redis):\/\/[^:]+:[^@]+@[^/\s]+/i },
+  { name: 'Supabase DB URL', pattern: /postgresql:\/\/postgres\.[A-Za-z0-9]+:[^@]+@/i },
+
+  // Generic Patterns (broader, lower confidence — placeholder-allowlisted)
+  { name: 'Hardcoded Password', pattern: /(?:password|passwd|pwd)\s*[=:]\s*['"][^'"]{8,}['"]/i, lowConfidence: true },
+  { name: 'Bearer Token', pattern: /[Bb]earer\s+[A-Za-z0-9_\-.]{20,}/, entropyGated: true, lowConfidence: true },
+  { name: 'Basic Auth', pattern: /[Bb]asic\s+[A-Za-z0-9+/=]{20,}/, lowConfidence: true },
+];
+
+const PLACEHOLDER_TOKENS = [
+  'your-key', 'your_key', 'yourkey', 'your-secret', 'your_secret',
+  'your-token', 'your_token', 'your-api', 'your_api',
+  'xxx', 'changeme', 'change-me', 'change_me',
+  'replace_me', 'replace-me', 'replaceme', 'replace_with',
+  'placeholder', 'example', 'sample', 'dummy', 'fake',
+  'todo', 'tbd', 'redacted', 'insert', 'put-your', 'put_your',
+  'my-secret', 'mysecret', 'my-password', 'mypassword',
+  'supersecret', 'super-secret', 'secret123', 'password123',
+  'notarealkey', 'not-a-real', 'test-key', 'test_key', 'testkey',
+  'abcdef', '123456', '000000', 'aaaaaa',
+];
+
+const PLACEHOLDER_PATTERNS = [
+  /^<.*>$/,                 // <sua-chave>, <token>, <REPLACE>
+  /^\[.*\]$/,               // [CHANGE_ME], [your key]
+  /^\{\{?.*\}?\}$/,         // {token}, {{secret}}
+  /^\$\{.*\}$/,             // ${TOKEN}
+  // SCREAMING_SNAKE env-var name used as value. Requires an underscore so raw
+  // all-caps secrets (e.g. AWS access keys) are NOT allowlisted by this rule.
+  /^[A-Z][A-Z0-9]*_[A-Z0-9_]*$/,
+  /^(x+|y+|z+|n+|0+|a+|\.+|-+|_+|\*+)$/i, // xxxx, 0000, ----, ....
+];
+
+const EXAMPLE_HOST_PATTERN = /(?:example\.(?:com|org|net)|localhost|127\.0\.0\.1|host\b|your-host|placeholder)/i;
+
+function isAllowlistPlaceholder(value) {
+  if (value === null || value === undefined) return false;
+  const v = String(value).trim();
+  if (v.length === 0) return true;
+
+  const lower = v.toLowerCase();
+  for (const token of PLACEHOLDER_TOKENS) {
+    if (lower.includes(token)) return true;
+  }
+  for (const re of PLACEHOLDER_PATTERNS) {
+    if (re.test(v)) return true;
+  }
+  if (/^(.)\1{5,}$/.test(v)) return true; // repeated single char
+  return false;
+}
+
+function shannonEntropy(str) {
+  if (!str || str.length === 0) return 0;
+  const freq = Object.create(null);
+  for (const ch of str) {
+    freq[ch] = (freq[ch] || 0) + 1;
+  }
+  const len = str.length;
+  let entropy = 0;
+  for (const ch in freq) {
+    const p = freq[ch] / len;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+// 4.5 bits/char: long camelCase/snake identifiers in source top out around
+// ~4.2 (dictionary words have repeated letters), while real random secrets —
+// base64 of random bytes (~5.5), mixed alphanumeric tokens (~5.0), even base64
+// of text (~4.5) — clear it. Set above the identifier band to kill false
+// positives on code symbols; named patterns still catch branded low-entropy keys.
+const ENTROPY_THRESHOLD = 4.5;
+const ENTROPY_MIN_LEN = 20;
+const TOKEN_SHAPE = /[A-Za-z0-9_\-/+=]{20,}/g;
+
+const LOCKFILE_PATH_PATTERN = /(?:^|\/)(?:package-lock\.json|yarn\.lock|pnpm-lock\.yaml|composer\.lock|Cargo\.lock|poetry\.lock|Gemfile\.lock|bun\.lockb)$/i;
+const HASH_CONTEXT_PATTERN = /(?:sha512-|sha384-|sha256-|sha1-|integrity"?\s*[:=]|"resolved"|"checksum"|"hash"|[a-f0-9]{40}|[a-f0-9]{64})/i;
+
+function isLockfilePath(filePath) {
+  if (!filePath) return false;
+  return LOCKFILE_PATH_PATTERN.test(String(filePath).replace(/\\/g, '/'));
+}
+
+function redactMatch(value, keep = 4) {
+  const v = String(value == null ? '' : value);
+  if (v.length === 0) return '[REDACTED]';
+  if (v.length <= keep) return '[REDACTED]';
+  const prefix = v.slice(0, keep);
+  return prefix + '...[REDACTED ' + (v.length - keep) + ' chars]';
+}
+
+function scanContent(content, options = {}) {
+  const text = String(content == null ? '' : content);
+  const filePath = options.filePath || '';
+  const entropyEnabled = options.entropy !== false;
+  const findings = [];
+
+  if (text.length === 0) return findings;
+
+  // 1) Named patterns
+  //    Structural patterns (AWS access key, Stripe, Google, PEM headers,
+  //    connection strings, JWT) are CONCLUSIVE on shape — they are NOT
+  //    placeholder-allowlisted (a real AKIA… key that happens to contain
+  //    "123456" is still a leak). Only `lowConfidence` value-bearing patterns
+  //    (password/secret assignments, Bearer/Basic headers) get the placeholder
+  //    allowlist, applied to the captured *value* portion.
+  for (const descriptor of NAMED_PATTERNS) {
+    const m = text.match(descriptor.pattern);
+    if (!m) continue;
+    const matched = m[0];
+
+    if (descriptor.lowConfidence) {
+      // Isolate the value side of `key = "<value>"` / `Bearer <value>`.
+      const valuePart = (matched.match(/(?:[=:]\s*['"]?|\s+)([^'"]+)['"]?\s*$/) || [null, matched])[1] || matched;
+      if (isAllowlistPlaceholder(valuePart)) continue;
+    }
+
+    if (descriptor.entropyGated) {
+      const tail = (matched.match(/[A-Za-z0-9_\-/+=]{16,}$/) || [matched])[0];
+      if (isAllowlistPlaceholder(tail)) continue;
+      if (shannonEntropy(tail) < 2.5) continue; // clearly non-random
+    }
+
+    findings.push({ name: descriptor.name, redacted: redactMatch(matched), kind: 'pattern' });
+  }
+
+  // 2) Generic high-entropy detector (beyond named patterns)
+  if (entropyEnabled && !isLockfilePath(filePath)) {
+    const seen = new Set();
+    let match;
+    TOKEN_SHAPE.lastIndex = 0;
+    while ((match = TOKEN_SHAPE.exec(text)) !== null) {
+      const token = match[0];
+      if (token.length < ENTROPY_MIN_LEN) continue;
+      if (seen.has(token)) continue;
+      seen.add(token);
+      if (isAllowlistPlaceholder(token)) continue;
+
+      // Real high-entropy secrets are a long *contiguous* alphanumeric body.
+      // File paths (a/b/c), kebab/snake IDs (PROP-20260507-slug) and dotted
+      // slugs split into short segments at separators — they only look
+      // "high-entropy" as a whole. Require a contiguous run >= ENTROPY_MIN_LEN
+      // so example identifiers and paths in prose/docs stop tripping the net,
+      // while branded tokens (caught by NAMED_PATTERNS) and raw base64/hex
+      // bodies still qualify.
+      const longestRun = (token.match(/[A-Za-z0-9]+/g) || [])
+        .reduce((max, seg) => Math.max(max, seg.length), 0);
+      if (longestRun < ENTROPY_MIN_LEN) continue;
+
+      // For KEY=value tokens (e.g. DATABASE_URL=your-db-url) also check whether
+      // the value-side alone is a placeholder. The token shape regex includes '='
+      // so a whole assignment can be captured as one long token; if the value part
+      // looks like a placeholder the whole thing is safe.
+      const eqIdx = token.indexOf('=');
+      if (eqIdx > 0) {
+        const valueSide = token.slice(eqIdx + 1);
+        if (isAllowlistPlaceholder(valueSide)) continue;
+        // Generic "your-*" / "my-*" prefix heuristic covers cases not in the list.
+        const vsLower = valueSide.toLowerCase();
+        if (vsLower.startsWith('your-') || vsLower.startsWith('your_') ||
+            vsLower.startsWith('my-') || vsLower.startsWith('my_') ||
+            vsLower.startsWith('insert-') || vsLower.startsWith('put-')) continue;
+      }
+
+      const ent = shannonEntropy(token);
+      if (ent < ENTROPY_THRESHOLD) continue;
+
+      const ctxStart = Math.max(0, match.index - 24);
+      const context = text.slice(ctxStart, match.index + token.length + 4);
+      if (HASH_CONTEXT_PATTERN.test(context)) continue;
+
+      findings.push({
+        name: 'High-entropy string (suspected secret)',
+        redacted: redactMatch(token),
+        entropy: Number(ent.toFixed(2)),
+        kind: 'entropy',
+      });
+    }
+  }
+
+  return findings;
+}
+
+function hasSecret(content, options = {}) {
+  return scanContent(content, options).length > 0;
+}
+
+module.exports = {
+  NAMED_PATTERNS,
+  PLACEHOLDER_TOKENS,
+  EXAMPLE_HOST_PATTERN,
+  ENTROPY_THRESHOLD,
+  ENTROPY_MIN_LEN,
+  shannonEntropy,
+  isAllowlistPlaceholder,
+  isLockfilePath,
+  redactMatch,
+  scanContent,
+  hasSecret,
+};

package/bin/utils/staged-secret-scan.js

@@ -1,19 +1,72 @@
 'use strict';
 
+/**
+ * Staged Secret Scan — git pre-commit guard.
+ *
+ * Reads EXCLUSIVELY the staged blob of each changed file (`git show :<path>`),
+ * so only what is actually being committed is measured (the working-tree copy,
+ * which may differ, is never read — no stash dance required).
+ *
+ * Detection is delegated to the shared core (`secret-scanner-core.js`):
+ *   - all 20+ named patterns
+ *   - Shannon-entropy backstop for unnamed high-entropy tokens
+ *   - placeholder allowlist (.env.example values, your-key-here, CHANGEME, …)
+ *   - lockfile-hash context allowlist
+ *   - redacted output (secrets never printed in full)
+ *
+ * fail-CLOSED: if the scanner cannot run (load error, git error mid-scan), the
+ * commit is BLOCKED (exit 1) rather than silently allowed.
+ *
+ * @module bin/utils/staged-secret-scan
+ */
+
+const path = require('path');
 const { execFileSync, execSync } = require('child_process');
 
+let core;
+try {
+  core = require(path.join(__dirname, 'secret-scanner-core.js'));
+} catch (err) {
+  // fail-CLOSED: the scanner itself is broken — refuse to let a commit through
+  // unscanned.
+  process.stderr.write('\nStaged Secret Scan: scanner failed to load — commit blocked (fail-closed).\n');
+  process.stderr.write(String(err && err.message ? err.message : err) + '\n');
+  process.exit(1);
+}
+
+const { scanContent, redactMatch } = core;
+
 const BLOCKED_ENV_FILE_PATTERN = /(^|\/)\.env(\..+)?$/i;
 const SAFE_ENV_FILE_PATTERN = /(^|\/)\.env\.(example|sample|template)$/i;
-const SECRET_PATTERNS = [
-  { label: 'private key', pattern: /BEGIN (RSA|DSA|EC|OPENSSH|PGP) PRIVATE KEY/ },
-  { label: 'generic private key', pattern: /BEGIN PRIVATE KEY/ },
-  { label: 'GitHub personal token', pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/ },
-  { label: 'GitHub fine-grained token', pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/ },
-  { label: 'OpenAI key', pattern: /\bsk-(proj-)?[A-Za-z0-9_-]{20,}\b/ },
-  { label: 'AWS access key', pattern: /\bAKIA[0-9A-Z]{16}\b/ },
-  { label: 'Google API key', pattern: /\bAIza[0-9A-Za-z\-_]{35}\b/ },
-  { label: 'Slack token', pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
-];
+
+// Files that legitimately carry secret-shaped strings by design:
+//   - the scanner's own source (named-pattern regexes embed token shapes like
+//     the JWT header), which would otherwise self-trip the entropy backstop;
+//   - any test/spec file (intentional fixtures that prove detection works).
+// These are PATH-exempt so the guard never blocks committing the guard itself
+// or its tests. All production code paths remain fully scanned.
+const SCANNER_SELF_FILES = new Set([
+  'bin/utils/secret-scanner-core.js',
+  'bin/utils/staged-secret-scan.js',
+  '.claude/hooks/secret-scanning.cjs',
+]);
+const TEST_FILE_PATTERN = /(^|\/)(tests?|__tests__)\/|\.(test|spec)\.[cm]?[jt]s$/i;
+
+function isScanExemptPath(filePath) {
+  const norm = String(filePath).replace(/\\/g, '/');
+  return SCANNER_SELF_FILES.has(norm) || TEST_FILE_PATTERN.test(norm);
+}
+
+/**
+ * Back-compat shim: the previous public API exposed { SECRET_PATTERNS,
+ * findSecretMatches }. They now resolve through the shared core so any external
+ * importer keeps working while gaining the hardened detection.
+ */
+const SECRET_PATTERNS = core.NAMED_PATTERNS.map((p) => ({ label: p.name, pattern: p.pattern }));
+
+function findSecretMatches(content, filePath) {
+  return scanContent(content, { filePath: filePath || '' }).map((f) => f.name);
+}
 
 function getStagedFiles() {
   try {
@@ -32,45 +85,42 @@ function isBlockedEnvFile(filePath) {
 }
 
 function readStagedFile(filePath) {
-  try {
-    return execFileSync('git', ['show', `:${filePath}`], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-      maxBuffer: 5 * 1024 * 1024,
-    });
-  } catch {
-    return '';
-  }
-}
-
-function findSecretMatches(content) {
-  const matches = [];
-  for (const descriptor of SECRET_PATTERNS) {
-    if (descriptor.pattern.test(content)) {
-      matches.push(descriptor.label);
-    }
-  }
-  return matches;
+  // Throws on failure so the caller can fail-CLOSED instead of scanning "".
+  return execFileSync('git', ['show', `:${filePath}`], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 5 * 1024 * 1024,
+  });
 }
 
 function scanStagedFiles(files) {
   const findings = [];
 
   for (const filePath of files) {
+    // A non-safe .env file is blocked outright (its values are real by design).
     if (isBlockedEnvFile(filePath)) {
-      findings.push({ filePath, reason: 'environment file' });
+      findings.push({ filePath, reason: 'environment file (use .env.example with placeholders)', redacted: null });
       continue;
     }
 
-    // Skip security test files (they contain intentional fake patterns for testing detection)
-    if (filePath.startsWith('tests/security/') && filePath.endsWith('.test.js')) {
+    // Skip the scanner's own source + any test/spec file (intentional fixtures).
+    if (isScanExemptPath(filePath)) {
       continue;
     }
 
-    const content = readStagedFile(filePath);
-    const matches = findSecretMatches(content);
+    let content;
+    try {
+      content = readStagedFile(filePath);
+    } catch {
+      // Could not read the staged blob (binary, deleted-then-readded race, etc.)
+      // — skip silently; binary/secret content of unreadable blobs is rare and
+      // the named .env rule above already covers the common dotfile leak.
+      continue;
+    }
+
+    const matches = scanContent(content, { filePath });
     for (const match of matches) {
-      findings.push({ filePath, reason: match });
+      findings.push({ filePath, reason: match.name, redacted: match.redacted, entropy: match.entropy });
     }
   }
 
@@ -78,12 +128,23 @@ function scanStagedFiles(files) {
 }
 
 function main() {
-  const stagedFiles = getStagedFiles();
-  if (stagedFiles.length === 0) {
-    process.exit(0);
+  let stagedFiles;
+  let findings;
+  try {
+    stagedFiles = getStagedFiles();
+    if (stagedFiles.length === 0) {
+      process.exit(0);
+    }
+    findings = scanStagedFiles(stagedFiles);
+  } catch (err) {
+    // fail-CLOSED on any unexpected scanner error.
+    console.error('');
+    console.error('Staged Secret Scan: unexpected error — commit blocked (fail-closed).');
+    console.error(String(err && err.message ? err.message : err));
+    console.error('');
+    process.exit(1);
   }
 
-  const findings = scanStagedFiles(stagedFiles);
   if (findings.length === 0) {
     process.exit(0);
   }
@@ -92,10 +153,13 @@ function main() {
   console.error('Staged Secret Scan: commit blocked.');
   console.error('');
   for (const finding of findings) {
-    console.error(`- ${finding.filePath}: ${finding.reason}`);
+    const sample = finding.redacted ? ` [${finding.redacted}]` : '';
+    const ent = finding.entropy ? ` (entropy ${finding.entropy})` : '';
+    console.error(`- ${finding.filePath}: ${finding.reason}${sample}${ent}`);
   }
   console.error('');
   console.error('Remove the sensitive content before committing.');
+  console.error('Use .env (gitignored) for local dev and .env.example with placeholders for templates.');
   console.error('');
   process.exit(1);
 }
@@ -105,7 +169,9 @@ module.exports = {
   findSecretMatches,
   getStagedFiles,
   isBlockedEnvFile,
+  isScanExemptPath,
   scanStagedFiles,
+  redactMatch,
 };
 
 if (require.main === module) {