@rafter-security/cli 0.8.3 → 0.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -795,6 +795,62 @@ function continueMcp() {
795
795
  },
796
796
  };
797
797
  }
798
+ /**
799
+ * Hermes MCP server entry (~/.hermes/config.yaml).
800
+ *
801
+ * Hermes uses a YAML config with a snake_case `mcp_servers:` block (unlike the
802
+ * camelCase `mcpServers` of Cursor/Windsurf/Claude Code). Per-server schema is
803
+ * {command, args, env}. MCP-only v0 — hooks deferred pending confirmation
804
+ * Hermes exposes a hook surface (sable-gyw).
805
+ */
806
+ function hermesMcp() {
807
+ const home = os.homedir();
808
+ const configPath = path.join(home, ".hermes", "config.yaml");
809
+ const readYaml = () => {
810
+ if (!fs.existsSync(configPath))
811
+ return {};
812
+ try {
813
+ const loaded = yaml.load(fs.readFileSync(configPath, "utf-8"));
814
+ if (loaded && typeof loaded === "object" && !Array.isArray(loaded)) {
815
+ return loaded;
816
+ }
817
+ }
818
+ catch { /* unparseable — treat as empty */ }
819
+ return {};
820
+ };
821
+ return {
822
+ id: "hermes.mcp",
823
+ platform: "hermes",
824
+ kind: "mcp",
825
+ description: "Hermes MCP server entry (~/.hermes/config.yaml)",
826
+ detectDir: path.join(home, ".hermes"),
827
+ path: configPath,
828
+ isInstalled: () => {
829
+ const servers = readYaml().mcp_servers;
830
+ return !!(servers && typeof servers === "object" && !Array.isArray(servers) && servers.rafter);
831
+ },
832
+ install: () => {
833
+ const dir = path.join(home, ".hermes");
834
+ if (!fs.existsSync(dir))
835
+ fs.mkdirSync(dir, { recursive: true });
836
+ const cfg = readYaml();
837
+ if (!cfg.mcp_servers || typeof cfg.mcp_servers !== "object" || Array.isArray(cfg.mcp_servers)) {
838
+ cfg.mcp_servers = {};
839
+ }
840
+ cfg.mcp_servers.rafter = { ...RAFTER_MCP_ENTRY };
841
+ fs.writeFileSync(configPath, yaml.dump(cfg), "utf-8");
842
+ },
843
+ uninstall: () => {
844
+ if (!fs.existsSync(configPath))
845
+ return;
846
+ const cfg = readYaml();
847
+ const servers = cfg.mcp_servers;
848
+ if (servers && typeof servers === "object" && !Array.isArray(servers) && removeKey(servers, "rafter")) {
849
+ fs.writeFileSync(configPath, yaml.dump(cfg), "utf-8");
850
+ }
851
+ },
852
+ };
853
+ }
798
854
  /**
799
855
  * Aider read-only context: writes RAFTER.md and adds it to .aider.conf.yml `read:`.
800
856
  *
@@ -942,6 +998,7 @@ export function getComponentRegistry() {
942
998
  continueRules(),
943
999
  continueMcp(),
944
1000
  aiderRead(),
1001
+ hermesMcp(),
945
1002
  openclawSkill(),
946
1003
  ];
947
1004
  }
@@ -8,7 +8,7 @@ import os from "os";
8
8
  import { execSync } from "child_process";
9
9
  import { fileURLToPath } from "url";
10
10
  import { createRequire } from "module";
11
- import { createInterface } from "readline";
11
+ import { askYesNo } from "../../utils/prompt.js";
12
12
  import { fmt } from "../../utils/formatter.js";
13
13
  import { injectInstructionFile } from "./instruction-block.js";
14
14
  import yaml from "js-yaml";
@@ -133,6 +133,11 @@ function printDryRunPlan(plan) {
133
133
  W(path.join(plan.root, "RAFTER.md"), "rafter:start/end marker block");
134
134
  W(path.join(plan.root, ".aider.conf.yml"), "appends RAFTER.md to read: list; strips legacy mcp-server-command line");
135
135
  }
136
+ if (plan.wantHermes) {
137
+ console.log();
138
+ console.log("Hermes (--with-hermes):");
139
+ W(path.join(plan.root, ".hermes", "config.yaml"), "mcp_servers.rafter entry merged into existing YAML");
140
+ }
136
141
  if (plan.wantOpenClaw) {
137
142
  console.log();
138
143
  console.log("OpenClaw (--with-openclaw):");
@@ -718,6 +723,46 @@ function installContinueDevMcp(root) {
718
723
  *
719
724
  * Returns true on success.
720
725
  */
726
+ /**
727
+ * Install MCP server config for Hermes (<root>/.hermes/config.yaml).
728
+ *
729
+ * Hermes uses a YAML config with an `mcp_servers:` block (snake_case, unlike
730
+ * Cursor/Windsurf/Claude Code which use `mcpServers` camelCase). Schema per
731
+ * server is {command, args, env}. We use js-yaml (already a dep, used by
732
+ * installAiderRead and elsewhere) to merge in the rafter entry while
733
+ * preserving any existing servers.
734
+ *
735
+ * Hooks (preToolUse/postToolUse equivalents) deferred to a follow-on bead
736
+ * pending confirmation Hermes exposes a hook surface — landing MCP-only as
737
+ * v0 mirrors how Gemini and Continue.dev were initially shipped.
738
+ */
739
+ function installHermesMcp(root) {
740
+ const hermesDir = path.join(root, ".hermes");
741
+ const configPath = path.join(hermesDir, "config.yaml");
742
+ if (!fs.existsSync(hermesDir)) {
743
+ fs.mkdirSync(hermesDir, { recursive: true });
744
+ }
745
+ let config = {};
746
+ if (fs.existsSync(configPath)) {
747
+ const raw = fs.readFileSync(configPath, "utf-8");
748
+ try {
749
+ const loaded = yaml.load(raw);
750
+ if (loaded && typeof loaded === "object" && !Array.isArray(loaded)) {
751
+ config = loaded;
752
+ }
753
+ }
754
+ catch {
755
+ console.log(fmt.warning(`Existing Hermes config.yaml was not valid YAML, creating new one`));
756
+ }
757
+ }
758
+ if (!config.mcp_servers || typeof config.mcp_servers !== "object" || Array.isArray(config.mcp_servers)) {
759
+ config.mcp_servers = {};
760
+ }
761
+ config.mcp_servers.rafter = { ...RAFTER_MCP_ENTRY };
762
+ fs.writeFileSync(configPath, yaml.dump(config), "utf-8");
763
+ console.log(fmt.success(`Installed Rafter MCP server to ${configPath}`));
764
+ return true;
765
+ }
721
766
  function installAiderRead(root) {
722
767
  const rafterMdPath = path.join(root, "RAFTER.md");
723
768
  const configPath = path.join(root, ".aider.conf.yml");
@@ -875,20 +920,6 @@ function registerGeminiSkills(skillsDir) {
875
920
  }
876
921
  }
877
922
  }
878
- async function askYesNo(question, defaultYes = true) {
879
- const rl = createInterface({ input: process.stdin, output: process.stderr });
880
- const suffix = defaultYes ? "[Y/n]" : "[y/N]";
881
- return new Promise((resolve) => {
882
- rl.question(` ${question} ${suffix} `, (answer) => {
883
- rl.close();
884
- const trimmed = answer.trim().toLowerCase();
885
- if (trimmed === "")
886
- resolve(defaultYes);
887
- else
888
- resolve(trimmed === "y" || trimmed === "yes");
889
- });
890
- });
891
- }
892
923
  export function createInitCommand() {
893
924
  return new Command("init")
894
925
  .description("Initialize agent security system")
@@ -901,6 +932,7 @@ export function createInitCommand() {
901
932
  .option("--with-cursor", "Install Cursor integration")
902
933
  .option("--with-windsurf", "Install Windsurf integration")
903
934
  .option("--with-continue", "Install Continue.dev integration")
935
+ .option("--with-hermes", "Install Hermes integration")
904
936
  .option("--with-betterleaks", "Download and install Betterleaks binary")
905
937
  .option("--all", "Install all detected integrations and download Betterleaks")
906
938
  .option("-i, --interactive", "Guided setup — prompts for each detected integration")
@@ -931,6 +963,7 @@ export function createInitCommand() {
931
963
  const hasWindsurf = scope === "user" && fs.existsSync(path.join(os.homedir(), ".codeium", "windsurf"));
932
964
  const hasContinueDev = scope === "user" && fs.existsSync(path.join(os.homedir(), ".continue"));
933
965
  const hasAider = scope === "user" && fs.existsSync(path.join(os.homedir(), ".aider.conf.yml"));
966
+ const hasHermes = scope === "user" && fs.existsSync(path.join(os.homedir(), ".hermes"));
934
967
  // Resolve opt-in flags (--all enables all detected, --interactive prompts).
935
968
  // In --local scope, --all is restricted to platforms that have a project-local
936
969
  // config story (claudeCode, codex, gemini, cursor). The rest require user scope.
@@ -953,6 +986,10 @@ export function createInitCommand() {
953
986
  // Aider can install at --local scope (writes RAFTER.md + .aider.conf.yml
954
987
  // in cwd) since rf-du2o.
955
988
  let wantAider = opts.withAider || opts.all;
989
+ // Hermes: MCP-only v0 (no hooks confirmed yet). User scope only — Hermes
990
+ // reads ~/.hermes/config.yaml; the project-local install story isn't
991
+ // established. Excluded from --all in --local for the same reason.
992
+ let wantHermes = opts.withHermes || (opts.all && !opts.local);
956
993
  let wantBetterleaks = opts.withBetterleaks || (opts.all && !opts.local);
957
994
  // Interactive mode: prompt for each detected integration
958
995
  if (opts.interactive && !opts.all) {
@@ -975,6 +1012,8 @@ export function createInitCommand() {
975
1012
  wantContinue = await askYesNo("Install Continue.dev MCP server?");
976
1013
  if (hasAider && !wantAider)
977
1014
  wantAider = await askYesNo("Install Aider MCP server?");
1015
+ if (hasHermes && !wantHermes)
1016
+ wantHermes = await askYesNo("Install Hermes MCP server?");
978
1017
  if (!wantBetterleaks)
979
1018
  wantBetterleaks = await askYesNo("Download Betterleaks binary (enhanced scanning)?");
980
1019
  console.log();
@@ -997,6 +1036,8 @@ export function createInitCommand() {
997
1036
  detected.push("Continue.dev");
998
1037
  if (hasAider)
999
1038
  detected.push("Aider");
1039
+ if (hasHermes)
1040
+ detected.push("Hermes");
1000
1041
  if (detected.length > 0) {
1001
1042
  console.log(fmt.info(`Detected environments: ${detected.join(", ")}`));
1002
1043
  }
@@ -1022,6 +1063,8 @@ export function createInitCommand() {
1022
1063
  console.log(fmt.warning("Continue.dev requested but not detected (~/.continue not found)"));
1023
1064
  if (wantAider && !hasAider)
1024
1065
  console.log(fmt.warning("Aider requested but not detected (~/.aider.conf.yml not found)"));
1066
+ if (wantHermes && !hasHermes)
1067
+ console.log(fmt.warning("Hermes requested but not detected (~/.hermes not found)"));
1025
1068
  }
1026
1069
  // --dry-run: print every file path the command would touch, then
1027
1070
  // exit before any filesystem write happens (rf-hrtd). The plan is
@@ -1039,6 +1082,7 @@ export function createInitCommand() {
1039
1082
  wantWindsurf: wantWindsurf && (hasWindsurf || opts.local),
1040
1083
  wantContinue: wantContinue && (hasContinueDev || opts.local),
1041
1084
  wantAider: wantAider && (hasAider || opts.local),
1085
+ wantHermes: wantHermes && hasHermes,
1042
1086
  wantBetterleaks,
1043
1087
  riskLevel: opts.riskLevel,
1044
1088
  });
@@ -1138,7 +1182,7 @@ export function createInitCommand() {
1138
1182
  const result = await skillManager.installRafterSkillVerbose();
1139
1183
  openclawOk = result.ok;
1140
1184
  if (result.ok) {
1141
- console.log(fmt.success("Installed Rafter Security skill to ~/.openclaw/skills/rafter-security.md"));
1185
+ console.log(fmt.success(`Installed Rafter Security skill to ${result.destPath}`));
1142
1186
  manager.set("agent.environments.openclaw.enabled", true);
1143
1187
  }
1144
1188
  else {
@@ -1290,6 +1334,20 @@ export function createInitCommand() {
1290
1334
  console.error(fmt.error(`Failed to install Aider integration: ${e}`));
1291
1335
  }
1292
1336
  }
1337
+ // Install Hermes integration if opted in (sable-gyw).
1338
+ // User scope only — Hermes reads ~/.hermes/config.yaml. MCP-only v0;
1339
+ // hooks deferred pending confirmation Hermes exposes a hook surface.
1340
+ let hermesOk = false;
1341
+ if (wantHermes && hasHermes) {
1342
+ try {
1343
+ hermesOk = installHermesMcp(root);
1344
+ if (hermesOk)
1345
+ manager.set("agent.environments.hermes.enabled", true);
1346
+ }
1347
+ catch (e) {
1348
+ console.error(fmt.error(`Failed to install Hermes integration: ${e}`));
1349
+ }
1350
+ }
1293
1351
  // Install global instruction files for platforms that support them.
1294
1352
  // Cursor is intentionally absent — Cursor uses per-skill rules + the
1295
1353
  // rafter sub-agent installed in the Cursor branch above (rf-svn3).
@@ -1348,6 +1406,8 @@ export function createInitCommand() {
1348
1406
  console.log(" rafter agent init --with-continue # Continue.dev only");
1349
1407
  if (hasAider)
1350
1408
  console.log(" rafter agent init --with-aider # Aider only");
1409
+ if (hasHermes)
1410
+ console.log(" rafter agent init --with-hermes # Hermes only");
1351
1411
  }
1352
1412
  else {
1353
1413
  console.log("No agent environments detected. Install an agent tool and re-run with --with-<tool>.");
@@ -1,6 +1,9 @@
1
1
  import { Command } from "commander";
2
2
  import { RegexScanner } from "../../scanners/regex-scanner.js";
3
3
  import { BetterleaksScanner } from "../../scanners/betterleaks.js";
4
+ import { unionScanResults } from "../../scanners/union.js";
5
+ import { BinaryManager, BETTERLEAKS_VERSION } from "../../utils/binary-manager.js";
6
+ import { askYesNo } from "../../utils/prompt.js";
4
7
  import { ConfigManager } from "../../core/config-manager.js";
5
8
  import { AuditLogger } from "../../core/audit-logger.js";
6
9
  import { applySuppressions, loadSuppressions, policyIgnoreToSuppressions, } from "../../core/custom-patterns.js";
@@ -10,6 +13,7 @@ import os from "os";
10
13
  import path from "path";
11
14
  import { fmt } from "../../utils/formatter.js";
12
15
  import { createRequire } from "module";
16
+ import { minimatch } from "minimatch";
13
17
  const _require = createRequire(import.meta.url);
14
18
  const { version: CLI_VERSION } = _require("../../../package.json");
15
19
  function loadBaselineEntries() {
@@ -24,6 +28,72 @@ function loadBaselineEntries() {
24
28
  return [];
25
29
  }
26
30
  }
31
+ /**
32
+ * Does `relPath` (forward-slash relative path) match an `exclude_paths`
33
+ * entry from `.rafter.yml`?
34
+ *
35
+ * sable-yz0 — single source of truth for `scan.exclude_paths` semantics
36
+ * across both scan engines and the staged / diff modes. Rules (any one
37
+ * matches → exclude):
38
+ *
39
+ * 1. Exact match: `relPath === pattern` (the pattern is the full file path)
40
+ * 2. Directory-prefix: `relPath` starts with `pattern + "/"` (the pattern
41
+ * is a directory; everything under it is excluded). Trailing "/" on
42
+ * the pattern is ignored — `scripts/` and `scripts` mean the same.
43
+ * 3. Dir-name anywhere: any segment of `relPath` equals `pattern` (preserves
44
+ * the historical RegexScanner walker behavior — `node_modules` skips
45
+ * `pkg/foo/node_modules/...` too).
46
+ * 4. Glob: if `pattern` contains `* ? [`, run it through minimatch with
47
+ * `dot:true, matchBase:true`. Same defaults as `policyIgnoreToSuppressions`.
48
+ */
49
+ function pathMatchesExcludePattern(relPath, pattern) {
50
+ const rel = relPath.replace(/\\/g, "/");
51
+ const p = pattern.replace(/\\/g, "/").replace(/\/+$/, "");
52
+ if (!p)
53
+ return false;
54
+ if (rel === p)
55
+ return true;
56
+ if (rel.startsWith(p + "/"))
57
+ return true;
58
+ if (rel.split("/").includes(p))
59
+ return true;
60
+ if (/[*?[]/.test(p)) {
61
+ if (minimatch(rel, p, { dot: true, matchBase: true }))
62
+ return true;
63
+ // Auto-anchor relative globs so `foo/**` matches anywhere in the tree.
64
+ if (!p.startsWith("/") && !p.startsWith("**")) {
65
+ if (minimatch(rel, "**/" + p, { dot: true }))
66
+ return true;
67
+ }
68
+ }
69
+ return false;
70
+ }
71
+ /**
72
+ * Strip findings whose file path matches any `scan.exclude_paths` entry.
73
+ * Called at the `scanDirectory` chokepoint so both the betterleaks and
74
+ * patterns engines get the same filter (and the same semantics).
75
+ *
76
+ * `scanRoot` is the absolute directory the scan was rooted at; finding
77
+ * paths are converted to scan-root-relative before matching, so users
78
+ * write `components/common/Mermaid.tsx` in their `.rafter.yml`, not the
79
+ * absolute path on the CI runner.
80
+ */
81
+ export function applyExcludePaths(results, excludePaths, scanRoot) {
82
+ if (!excludePaths || excludePaths.length === 0)
83
+ return results;
84
+ const root = path.resolve(scanRoot).replace(/\\/g, "/");
85
+ return results.filter((r) => {
86
+ const abs = path.resolve(r.file).replace(/\\/g, "/");
87
+ let rel = abs;
88
+ if (abs === root) {
89
+ rel = "";
90
+ }
91
+ else if (abs.startsWith(root + "/")) {
92
+ rel = abs.slice(root.length + 1);
93
+ }
94
+ return !excludePaths.some((pat) => pathMatchesExcludePattern(rel, pat));
95
+ });
96
+ }
27
97
  function applyBaseline(results, entries) {
28
98
  if (entries.length === 0)
29
99
  return results;
@@ -50,6 +120,7 @@ export function createScanCommand() {
50
120
  .option("--watch", "Watch for file changes and re-scan on change")
51
121
  .option("--history", "Scan git history for secrets (requires betterleaks engine)")
52
122
  .option("--no-gitignore", "Scan files even if .gitignore would exclude them (default: respect .gitignore)")
123
+ .option("--no-auto-update", "Do not auto-update a stale managed betterleaks binary; fall back to the patterns engine instead")
53
124
  .action(async (scanPath, opts) => {
54
125
  // Validate flags before doing any work.
55
126
  const validEngines = ["auto", "betterleaks", "patterns"];
@@ -99,7 +170,7 @@ export function createScanCommand() {
99
170
  return;
100
171
  }
101
172
  // Determine scan engine
102
- const engine = await selectEngine(opts.engine || "auto", opts.quiet || false);
173
+ const engine = await selectEngine(opts.engine || "auto", opts.quiet || false, autoUpdateEnabled(opts, scanCfg));
103
174
  // Determine if path is file or directory
104
175
  const stats = fs.statSync(resolvedPath);
105
176
  let results;
@@ -134,7 +205,7 @@ export function createSecretsCommand() {
134
205
  * Order matters — first match wins, and policy rules are checked first so an
135
206
  * explicit reason wins over a bare .rafterignore line covering the same finding.
136
207
  */
137
- function collectSuppressions(policyIgnore) {
208
+ export function collectSuppressions(policyIgnore) {
138
209
  return [...policyIgnoreToSuppressions(policyIgnore), ...loadSuppressions()];
139
210
  }
140
211
  /**
@@ -212,6 +283,9 @@ function outputScanResults(results, opts, context, exitOnFindings = true, suppre
212
283
  line: m.line ?? null,
213
284
  column: m.column ?? null,
214
285
  redacted: m.redacted || "",
286
+ // sable-j85 — present only for `auto`-mode (both-engine) scans, so
287
+ // consumers can tell which engine surfaced each finding.
288
+ ...(m.engines ? { engines: m.engines } : {}),
215
289
  })),
216
290
  }));
217
291
  const out = {
@@ -293,7 +367,7 @@ async function scanDiffFiles(ref, opts, scanCfg, baselineEntries = [], scanPath,
293
367
  cwd,
294
368
  stdio: ["pipe", "pipe", "ignore"],
295
369
  }).trim();
296
- const engine = await selectEngine(opts.engine || "auto", opts.quiet || false);
370
+ const engine = await selectEngine(opts.engine || "auto", opts.quiet || false, autoUpdateEnabled(opts, scanCfg));
297
371
  const allResults = [];
298
372
  for (const file of changedFiles) {
299
373
  const filePath = path.resolve(repoRoot, file);
@@ -305,7 +379,11 @@ async function scanDiffFiles(ref, opts, scanCfg, baselineEntries = [], scanPath,
305
379
  const results = await scanFile(filePath, engine, scanCfg);
306
380
  allResults.push(...results);
307
381
  }
308
- outputScanResults(applyBaseline(allResults, baselineEntries), opts, `files changed since ${ref}`, true, suppressions);
382
+ // sable-yz0 — honor scan.exclude_paths in --diff mode too (was previously
383
+ // dropped). Use the repo root as scanRoot so user-relative paths in
384
+ // .rafter.yml resolve consistently with the directory-scan behavior.
385
+ const filteredDiff = applyExcludePaths(allResults, scanCfg?.excludePaths, repoRoot);
386
+ outputScanResults(applyBaseline(filteredDiff, baselineEntries), opts, `files changed since ${ref}`, true, suppressions);
309
387
  }
310
388
  catch (error) {
311
389
  if (error.status === 128) {
@@ -339,7 +417,7 @@ async function scanStagedFiles(opts, scanCfg, baselineEntries = [], scanPath, su
339
417
  cwd,
340
418
  stdio: ["pipe", "pipe", "ignore"],
341
419
  }).trim();
342
- const engine = await selectEngine(opts.engine || "auto", opts.quiet || false);
420
+ const engine = await selectEngine(opts.engine || "auto", opts.quiet || false, autoUpdateEnabled(opts, scanCfg));
343
421
  const allResults = [];
344
422
  for (const file of stagedFiles) {
345
423
  const filePath = path.resolve(repoRoot, file);
@@ -351,7 +429,9 @@ async function scanStagedFiles(opts, scanCfg, baselineEntries = [], scanPath, su
351
429
  const results = await scanFile(filePath, engine, scanCfg);
352
430
  allResults.push(...results);
353
431
  }
354
- outputScanResults(applyBaseline(allResults, baselineEntries), opts, "staged files", true, suppressions);
432
+ // sable-yz0 — honor scan.exclude_paths in --staged mode too.
433
+ const filteredStaged = applyExcludePaths(allResults, scanCfg?.excludePaths, repoRoot);
434
+ outputScanResults(applyBaseline(filteredStaged, baselineEntries), opts, "staged files", true, suppressions);
355
435
  }
356
436
  catch (error) {
357
437
  if (error.status === 128) {
@@ -362,9 +442,22 @@ async function scanStagedFiles(opts, scanCfg, baselineEntries = [], scanPath, su
362
442
  }
363
443
  }
364
444
  /**
365
- * Select scan engine based on availability and user preference
445
+ * Select scan engine based on availability and user preference.
446
+ *
447
+ * `auto` (the default) resolves to `both` whenever betterleaks is available
448
+ * and usable — rafter then runs both engines and unions their findings
449
+ * (sable-j85), so a miss in one (betterleaks 1.1.x does not detect AWS access
450
+ * keys — sable-h2y) is still caught by the other. It degrades to
451
+ * `patterns`-only when betterleaks is absent or a stale binary can't be
452
+ * refreshed. Explicit `--engine betterleaks` / `--engine patterns` stay
453
+ * single-engine.
454
+ *
455
+ * `autoUpdate` (default true) controls sable-o4k behavior: when the resolved
456
+ * engine is betterleaks but the managed binary is stale, auto-update it before
457
+ * scanning. The caller resolves this from `--no-auto-update` and the
458
+ * `scan.auto_update_betterleaks` config key.
366
459
  */
367
- async function selectEngine(preference, quiet) {
460
+ async function selectEngine(preference, quiet, autoUpdate = true) {
368
461
  if (preference === "patterns") {
369
462
  return "patterns";
370
463
  }
@@ -377,21 +470,104 @@ async function selectEngine(preference, quiet) {
377
470
  }
378
471
  return "patterns";
379
472
  }
380
- return "betterleaks";
473
+ return ensureBetterleaksUsable(quiet, autoUpdate);
381
474
  }
382
475
  if (preference !== "auto") {
383
476
  console.error(`Invalid engine: ${preference}. Valid values: auto, betterleaks, patterns`);
384
477
  process.exit(2);
385
478
  }
386
- // Auto mode: try Betterleaks, fall back to patterns
479
+ // Auto mode: run BOTH engines when betterleaks is usable; otherwise patterns.
387
480
  const bl = new BetterleaksScanner();
388
481
  const available = await bl.isAvailable();
389
- return available ? "betterleaks" : "patterns";
482
+ if (!available)
483
+ return "patterns";
484
+ const usable = await ensureBetterleaksUsable(quiet, autoUpdate);
485
+ return usable === "betterleaks" ? "both" : "patterns";
486
+ }
487
+ /**
488
+ * sable-o4k — guard against a stale rafter-managed betterleaks binary silently
489
+ * returning zero findings (a leftover binary from an older rafter parses fine
490
+ * with `version` but emits a JSON shape the current parser rejects).
491
+ *
492
+ * When the managed binary is stale we auto-update it to the pinned version
493
+ * (default on; opt out with `--no-auto-update` or `scan.auto_update_betterleaks:
494
+ * false`). In an interactive TTY we confirm first. If the update is disabled,
495
+ * declined, or fails, we degrade to the patterns engine and print a CTA rather
496
+ * than scanning with a binary that yields nothing.
497
+ */
498
+ async function ensureBetterleaksUsable(quiet, autoUpdate) {
499
+ const bm = new BinaryManager();
500
+ if (!(await bm.isManagedBetterleaksStale()))
501
+ return "betterleaks";
502
+ const current = await bm.getBetterleaksVersion();
503
+ const cta = "Fix manually with: rafter agent update-betterleaks";
504
+ const stale = `Stale betterleaks binary (${current}; expected v${BETTERLEAKS_VERSION})`;
505
+ if (!autoUpdate) {
506
+ if (!quiet) {
507
+ console.error(fmt.warning(`${stale}. Auto-update is off — using the patterns engine for this scan. ${cta}`));
508
+ }
509
+ return "patterns";
510
+ }
511
+ // Only prompt when there's a human at a TTY; otherwise auto-update proceeds
512
+ // (default on) so non-interactive runs aren't left with a broken engine.
513
+ if (process.stdin.isTTY && !quiet) {
514
+ const ok = await askYesNo(`${stale}. Update it now?`, true);
515
+ if (!ok) {
516
+ console.error(fmt.warning(`Skipped — using the patterns engine for this scan. ${cta}`));
517
+ return "patterns";
518
+ }
519
+ }
520
+ if (!quiet)
521
+ console.error(fmt.info(`Updating betterleaks to v${BETTERLEAKS_VERSION}...`));
522
+ try {
523
+ await bm.downloadBetterleaks((m) => { if (!quiet)
524
+ console.error(` ${m}`); }, BETTERLEAKS_VERSION);
525
+ if (!quiet)
526
+ console.error(fmt.success(`Betterleaks updated to v${BETTERLEAKS_VERSION}.`));
527
+ return "betterleaks";
528
+ }
529
+ catch (e) {
530
+ if (!quiet) {
531
+ const msg = e instanceof Error ? e.message : String(e);
532
+ console.error(fmt.warning(`Betterleaks update failed (${msg}) — using the patterns engine for this scan. ${cta}`));
533
+ }
534
+ return "patterns";
535
+ }
536
+ }
537
+ /**
538
+ * Resolve whether stale-binary auto-update is enabled, from the CLI flag
539
+ * (`--no-auto-update` → `opts.autoUpdate === false`) and the
540
+ * `scan.auto_update_betterleaks` config key. Either opting out disables it.
541
+ */
542
+ export function autoUpdateEnabled(opts, scanCfg) {
543
+ return opts.autoUpdate !== false && scanCfg?.autoUpdateBetterleaks !== false;
390
544
  }
391
545
  /**
392
546
  * Scan a file with selected engine
393
547
  */
394
548
  async function scanFile(filePath, engine, scanCfg) {
549
+ const runPatterns = () => {
550
+ const scanner = new RegexScanner(scanCfg?.customPatterns);
551
+ const result = scanner.scanFile(filePath);
552
+ return result.matches.length > 0 ? [result] : [];
553
+ };
554
+ if (engine === "both") {
555
+ // sable-j85 — kick off betterleaks (async subprocess) first, run the
556
+ // synchronous regex scan while it works, then union. A betterleaks failure
557
+ // degrades to patterns-only rather than losing the scan.
558
+ const blPromise = (async () => {
559
+ try {
560
+ const result = await new BetterleaksScanner().scanFile(filePath);
561
+ return result.matches.length > 0 ? [result] : [];
562
+ }
563
+ catch {
564
+ console.error(fmt.warning("Betterleaks scan failed, using patterns only for this run"));
565
+ return [];
566
+ }
567
+ })();
568
+ const patternsResults = runPatterns();
569
+ return unionScanResults(await blPromise, patternsResults);
570
+ }
395
571
  if (engine === "betterleaks") {
396
572
  try {
397
573
  const bl = new BetterleaksScanner();
@@ -400,16 +576,10 @@ async function scanFile(filePath, engine, scanCfg) {
400
576
  }
401
577
  catch (e) {
402
578
  console.error(fmt.warning("Betterleaks scan failed, falling back to patterns"));
403
- const scanner = new RegexScanner(scanCfg?.customPatterns);
404
- const result = scanner.scanFile(filePath);
405
- return result.matches.length > 0 ? [result] : [];
579
+ return runPatterns();
406
580
  }
407
581
  }
408
- else {
409
- const scanner = new RegexScanner(scanCfg?.customPatterns);
410
- const result = scanner.scanFile(filePath);
411
- return result.matches.length > 0 ? [result] : [];
412
- }
582
+ return runPatterns();
413
583
  }
414
584
  /**
415
585
  * Scan a directory with selected engine
@@ -418,27 +588,57 @@ async function scanDirectory(dirPath, engine, scanCfg, history, respectGitignore
418
588
  // respectGitignore default is true. The patterns engine honors it via
419
589
  // RegexScanner.scanDirectory; betterleaks honors it natively (gitleaks
420
590
  // ancestry — reads .gitignore unless --no-git is set).
421
- if (engine === "betterleaks") {
591
+ const runPatterns = () => {
592
+ const scanner = new RegexScanner(scanCfg?.customPatterns);
593
+ return scanner.scanDirectory(dirPath, {
594
+ excludePaths: scanCfg?.excludePaths,
595
+ respectGitignore,
596
+ });
597
+ };
598
+ let results;
599
+ if (engine === "both") {
600
+ // sable-j85 — start betterleaks (async subprocess) first, walk the tree
601
+ // with the synchronous patterns engine while it runs, then union. The
602
+ // exclude-paths post-filter below applies to the merged set.
603
+ const blPromise = (async () => {
604
+ try {
605
+ return await new BetterleaksScanner().scanDirectory(dirPath, { useGit: history ?? false });
606
+ }
607
+ catch {
608
+ console.error(fmt.warning("Betterleaks scan failed, using patterns only for this run"));
609
+ return [];
610
+ }
611
+ })();
612
+ const patternsResults = runPatterns();
613
+ results = unionScanResults(await blPromise, patternsResults);
614
+ }
615
+ else if (engine === "betterleaks") {
422
616
  try {
423
617
  const bl = new BetterleaksScanner();
424
- return await bl.scanDirectory(dirPath, { useGit: history ?? false });
618
+ results = await bl.scanDirectory(dirPath, { useGit: history ?? false });
425
619
  }
426
620
  catch (e) {
427
621
  console.error(fmt.warning("Betterleaks scan failed, falling back to patterns"));
428
- const scanner = new RegexScanner(scanCfg?.customPatterns);
429
- return scanner.scanDirectory(dirPath, {
430
- excludePaths: scanCfg?.excludePaths,
431
- respectGitignore,
432
- });
622
+ results = runPatterns();
433
623
  }
434
624
  }
435
625
  else {
436
- const scanner = new RegexScanner(scanCfg?.customPatterns);
437
- return scanner.scanDirectory(dirPath, {
438
- excludePaths: scanCfg?.excludePaths,
439
- respectGitignore,
440
- });
626
+ results = runPatterns();
441
627
  }
628
+ // sable-yz0 — post-filter by `.rafter.yml scan.exclude_paths`. Two bugs
629
+ // motivated this chokepoint:
630
+ // 1. The betterleaks happy-path above never received excludePaths,
631
+ // so `auto`-engine scans (the default when betterleaks is on disk)
632
+ // silently ignored user policy.
633
+ // 2. The patterns engine's walker only matches `excludePaths` entries
634
+ // against single directory NAMES (`entry.name`), so a customer
635
+ // writing `components/common/Mermaid.tsx` (file path) or
636
+ // `supabase/migrations/foo.sql` (multi-segment path) got no
637
+ // filtering at all.
638
+ // The post-filter applies the same path-aware semantics to BOTH engines
639
+ // (exact path, directory-prefix, dir-name-anywhere, glob via minimatch),
640
+ // catching whatever leaks through the walker-level optimization.
641
+ return applyExcludePaths(results, scanCfg?.excludePaths, dirPath);
442
642
  }
443
643
  /**
444
644
  * Watch a path for changes and re-scan on each change
@@ -446,7 +646,7 @@ async function scanDirectory(dirPath, engine, scanCfg, history, respectGitignore
446
646
  async function watchAndScan(watchPath, opts, scanCfg, suppressions = []) {
447
647
  const { watch } = await import("chokidar");
448
648
  const logger = new AuditLogger();
449
- const engine = await selectEngine(opts.engine || "auto", opts.quiet || false);
649
+ const engine = await selectEngine(opts.engine || "auto", opts.quiet || false, autoUpdateEnabled(opts, scanCfg));
450
650
  if (!opts.quiet) {
451
651
  console.error(fmt.info(`Watching ${watchPath} for changes (${engine}). Press Ctrl+C to exit.`));
452
652
  }