unbound-cli 0.8.2 → 0.9.1

package/src/commands/onboard.js

@@ -26,6 +26,7 @@ function register(program) {
     .requiredOption('--api-key <key>', 'User API key (for tool setup and login)')
     .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
     .option('--domain <url>', 'Backend URL for discovery (defaults to configured backend)')
+    .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (Cursor skipped automatically)')
     .addOption(new Option('--backend-url <url>', 'Override backend URL for setup scripts (dev only)').hideHelp())
     .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addOption(new Option('--gateway-url <url>', 'Override gateway URL for setup scripts (dev only)').hideHelp())
@@ -46,6 +47,7 @@ For admin device enrollment via MDM, use \`unbound onboard-mdm\` instead.
 
 Examples:
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --backfill
   $ sudo unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
 `)
     .action(async (opts) => {
@@ -79,7 +81,9 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing tool bundle');
-        const ok = await runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl });
+        const ok = await runSetupAllBundle(apiKey, {
+          backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
+        });
         if (!ok) return;
         setupSucceeded = true;
 
@@ -112,6 +116,7 @@ Examples:
     .requiredOption('--admin-api-key <key>', 'Admin API key for MDM enrollment')
     .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
     .option('--domain <url>', 'Backend URL for discovery (defaults to configured backend)')
+    .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (Cursor skipped automatically)')
     .addOption(new Option('--backend-url <url>', 'Override backend URL for setup scripts (dev only)').hideHelp())
     .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addOption(new Option('--gateway-url <url>', 'Override gateway URL for setup scripts (dev only)').hideHelp())
@@ -127,6 +132,7 @@ For end-user onboarding (non-MDM), use \`unbound onboard\` instead.
 
 Examples:
   $ sudo unbound onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>
+  $ sudo unbound onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY> --backfill
 `)
     .action(async (opts) => {
       let setupSucceeded = false;
@@ -148,7 +154,9 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing MDM tool bundle');
-        const ok = await runMdmSetupAllBundle(opts.adminApiKey, { backendUrl, gatewayUrl });
+        const ok = await runMdmSetupAllBundle(opts.adminApiKey, {
+          backendUrl, gatewayUrl, backfill: !!opts.backfill,
+        });
         if (!ok) return;
         setupSucceeded = true;
 

package/src/commands/setup.js

@@ -212,20 +212,42 @@ async function runPythonScriptWindows(scriptPath, args, { capture }) {
  * own defaults. `mdm: true` skips --domain (frontend URL) since MDM scripts
  * have no browser-auth flow.
  */
-function buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, mdm } = {}) {
+function buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, mdm, backfill } = {}) {
   let args = `--api-key ${shellEscape(apiKey)}`;
   if (backendUrl) args += ` --backend-url ${shellEscape(backendUrl)}`;
   if (gatewayUrl) args += ` --gateway-url ${shellEscape(gatewayUrl)}`;
   if (!mdm && frontendUrl) args += ` --domain ${shellEscape(frontendUrl)}`;
   if (clear) args += ' --clear';
+  if (backfill) args += ' --backfill';
   return args;
 }
 
+// Backfill only applies to the hooks variants of Claude Code / Codex; gateway
+// mode and Cursor have no local transcripts to seed.
+function scriptSupportsBackfill(scriptPath) {
+  return scriptPath.includes('/hooks/') && (
+    scriptPath.startsWith('claude-code/') || scriptPath.startsWith('codex/')
+  );
+}
+
+// Surfaces an early note when --backfill was requested for a tool that can't
+// use it. The setup scripts no-op safely too, but earlier user signal is better UX.
+function noteBackfillUnsupported(label, scriptPath) {
+  if (scriptPath.startsWith('cursor/')) {
+    output.info(`${label} backfill is not supported (no historical transcript data on disk). Continuing without backfill for ${label}.`);
+    return;
+  }
+  if (scriptPath.includes('/gateway/')) {
+    output.info(`--backfill is not supported in gateway mode for ${label}. Continuing without backfill for ${label}.`);
+    return;
+  }
+}
+
 /**
  * Runs a Python setup script from the setup repo with inherited stdio (live output).
  */
-async function runSetupScript(scriptPath, apiKey, { clear = false, backendUrl, frontendUrl, gatewayUrl } = {}) {
-  const args = buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear });
+async function runSetupScript(scriptPath, apiKey, { clear = false, backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
+  const args = buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, backfill });
   console.log('');
   if (isWindowsNative()) {
     await runPythonScriptWindows(scriptPath, args, { capture: false });
@@ -318,6 +340,7 @@ function register(program) {
     .option('--subscription', 'Use subscription mode for Claude Code / Codex (hooks only)')
     .option('--gateway', 'Use gateway mode for Claude Code / Codex (Unbound as AI provider)')
     .option('--all', 'Set up the default bundle: Cursor, Claude Code (hooks), Codex (hooks)')
+    .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (subscription/hooks mode only; Cursor unsupported)')
     .addOption(new Option('--backend-url <url>', 'Override backend URL for setup scripts (dev only)').hideHelp())
     .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addOption(new Option('--gateway-url <url>', 'Override gateway URL for setup scripts (dev only)').hideHelp())
@@ -349,6 +372,10 @@ Examples:
   $ unbound setup --all                                    Set up the default bundle
   $ unbound setup --all --api-key <key>                    Login + set up the bundle
 
+  Seed historical sessions (Claude Code / Codex subscription mode only):
+  $ unbound setup claude-code --subscription --backfill   Install hooks AND backfill local history
+  $ unbound setup codex --subscription --backfill         Install hooks AND backfill local history
+
   One-step login and setup:
   $ unbound setup cursor --api-key <key>                   Login + set up Cursor
   $ unbound setup cursor claude-code-gateway --api-key <key>
@@ -414,10 +441,18 @@ automatically to authenticate before proceeding.
           const selectedTools = SETUP_TOOLS.filter(t => selected.includes(t.value));
           console.log('');
 
-          const interactiveArgs = buildScriptArgs(apiKey, urlOpts);
-          const ok = await runBatch(selectedTools, (tool) =>
-            runScriptPiped(tool.script, interactiveArgs)
-          );
+          if (opts.backfill) {
+            for (const tool of selectedTools) {
+              if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+            }
+          }
+          const ok = await runBatch(selectedTools, (tool) => {
+            const toolArgs = buildScriptArgs(apiKey, {
+              ...urlOpts,
+              backfill: opts.backfill && scriptSupportsBackfill(tool.script),
+            });
+            return runScriptPiped(tool.script, toolArgs);
+          });
           if (!ok) return;
 
           console.log('');
@@ -481,7 +516,10 @@ automatically to authenticate before proceeding.
           const toolName = tools[0];
 
           if (SETUP_TOOL_MAP[toolName]) {
-            await runSetupScript(SETUP_TOOL_MAP[toolName].script, apiKey, { clear: opts.clear, ...urlOpts });
+            const { script, label } = SETUP_TOOL_MAP[toolName];
+            const backfill = opts.backfill && scriptSupportsBackfill(script);
+            if (opts.backfill && !backfill) noteBackfillUnsupported(label, script);
+            await runSetupScript(script, apiKey, { clear: opts.clear, backfill, ...urlOpts });
           } else if (MODE_TOOLS[toolName]) {
             const mode = MODE_TOOLS[toolName];
             if (opts.clear) {
@@ -495,7 +533,10 @@ automatically to authenticate before proceeding.
                 useSubscription = choice === 'subscription';
               }
               const resolved = useSubscription ? mode.subscription : mode.gateway;
-              await runSetupScript(SETUP_TOOL_MAP[resolved].script, apiKey, urlOpts);
+              const { script, label } = SETUP_TOOL_MAP[resolved];
+              const backfill = opts.backfill && scriptSupportsBackfill(script);
+              if (opts.backfill && !backfill) noteBackfillUnsupported(label, script);
+              await runSetupScript(script, apiKey, { ...urlOpts, backfill });
             }
           } else if (INSTRUCTION_TOOLS[toolName]) {
             output.keyValue(INSTRUCTION_TOOLS[toolName].values(apiKey, frontendUrl));
@@ -533,10 +574,19 @@ automatically to authenticate before proceeding.
         // Run automated tools with spinners
         if (resolvedScripts.length > 0) {
           console.log('');
-          const args = buildScriptArgs(apiKey, { ...urlOpts, clear: opts.clear });
-          const ok = await runBatch(resolvedScripts, (tool) =>
-            runScriptPiped(tool.script, args)
-          , { clear: opts.clear });
+          if (opts.backfill) {
+            for (const tool of resolvedScripts) {
+              if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+            }
+          }
+          const ok = await runBatch(resolvedScripts, (tool) => {
+            const toolArgs = buildScriptArgs(apiKey, {
+              ...urlOpts,
+              clear: opts.clear,
+              backfill: opts.backfill && scriptSupportsBackfill(tool.script),
+            });
+            return runScriptPiped(tool.script, toolArgs);
+          }, { clear: opts.clear });
           if (!ok) return;
         }
 
@@ -572,6 +622,7 @@ automatically to authenticate before proceeding.
     .requiredOption('--admin-api-key <key>', 'Admin API key for MDM enrollment')
     .option('--clear', 'Remove Unbound configuration for the specified tools')
     .option('--all', 'Set up all available tools')
+    .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (subscription/hooks mode only; Cursor unsupported)')
     .addHelpText('after', `
 Available tools:
   cursor                    Cursor IDE
@@ -590,6 +641,8 @@ Examples:
   $ sudo unbound setup mdm --admin-api-key KEY cursor claude-code-subscription codex-subscription
   $ sudo unbound setup mdm --admin-api-key KEY --all
   $ sudo unbound setup mdm --admin-api-key KEY --clear cursor codex-subscription
+  $ sudo unbound setup mdm --admin-api-key KEY claude-code-subscription --backfill
+                                                           Install hooks AND backfill local history
 `)
     .action(async (tools, opts, command) => {
       try {
@@ -650,16 +703,24 @@ Examples:
         const resolvedTools = toolNames.map(name => ({ name, ...MDM_TOOLS[name] }));
         console.log('');
 
-        const args = buildScriptArgs(opts.adminApiKey, {
-          backendUrl,
-          gatewayUrl,
-          clear: globalOpts.clear,
-          mdm: true,
-        });
+        if (globalOpts.backfill) {
+          for (const tool of resolvedTools) {
+            if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+          }
+        }
 
         const ok = await runBatch(
           resolvedTools,
-          (tool) => runScriptPiped(tool.script, args),
+          (tool) => {
+            const toolArgs = buildScriptArgs(opts.adminApiKey, {
+              backendUrl,
+              gatewayUrl,
+              clear: globalOpts.clear,
+              mdm: true,
+              backfill: globalOpts.backfill && scriptSupportsBackfill(tool.script),
+            });
+            return runScriptPiped(tool.script, toolArgs);
+          },
           { clear: globalOpts.clear }
         );
         if (!ok) return;
@@ -678,10 +739,24 @@ Examples:
  * Assumes the caller has already ensured the user is logged in.
  * Returns true on success, false on failure.
  */
-async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl } = {}) {
+async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
   const resolvedTools = ALL_TOOLS.map(name => ({ name, ...SETUP_TOOL_MAP[name] }));
-  const args = buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl });
-  return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
+  if (backfill) {
+    for (const tool of resolvedTools) {
+      if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+    }
+  }
+  // Build args per-tool so --backfill only goes to tools whose script
+  // actually supports it (Claude Code hooks and Codex hooks). Cursor would
+  // print "not supported"; passing the flag to gateway-mode scripts would
+  // error out — `scriptSupportsBackfill` checks for both.
+  return runBatch(resolvedTools, (tool) => {
+    const args = buildScriptArgs(apiKey, {
+      backendUrl, frontendUrl, gatewayUrl,
+      backfill: backfill && scriptSupportsBackfill(tool.script),
+    });
+    return runScriptPiped(tool.script, args);
+  });
 }
 
 /**
@@ -689,10 +764,20 @@ async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl }
  * Caller must ensure the process is running as root.
  * Returns true on success, false on failure.
  */
-async function runMdmSetupAllBundle(adminApiKey, { backendUrl, gatewayUrl } = {}) {
+async function runMdmSetupAllBundle(adminApiKey, { backendUrl, gatewayUrl, backfill = false } = {}) {
   const resolvedTools = MDM_ALL_TOOLS.map(name => ({ name, ...MDM_TOOLS[name] }));
-  const args = buildScriptArgs(adminApiKey, { backendUrl, gatewayUrl, mdm: true });
-  return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
+  if (backfill) {
+    for (const tool of resolvedTools) {
+      if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+    }
+  }
+  return runBatch(resolvedTools, (tool) => {
+    const args = buildScriptArgs(adminApiKey, {
+      backendUrl, gatewayUrl, mdm: true,
+      backfill: backfill && scriptSupportsBackfill(tool.script),
+    });
+    return runScriptPiped(tool.script, args);
+  });
 }
 
 module.exports = {

package/src/index.js

@@ -181,6 +181,7 @@ require('./commands/setup').register(program);
 require('./commands/discover').register(program);
 require('./commands/onboard').register(program);
 require('./commands/chat').register(program);
+require('./commands/oacb').register(program);
 
 // config command for managing CLI settings
 const configCmd = program

package/test/oacb.test.js

@@ -0,0 +1,307 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  validateTier,
+  isVersionSupported,
+  computeGaps,
+  mergeOverrides,
+  computeDeepDiff,
+  buildOacbHookEntries,
+  ruleIdFromPattern,
+  classifyRule,
+  hasOacbHook,
+} = require('../src/commands/oacb').__test__;
+
+// ─── validateTier ─────────────────────────────────────────────────────────────
+
+test('validateTier: accepts all four valid tiers', () => {
+  for (const t of ['shadow', 'baseline', 'strict', 'paranoid']) {
+    assert.doesNotThrow(() => validateTier(t));
+  }
+});
+
+test('validateTier: rejects unknown tier', () => {
+  assert.throws(() => validateTier('custom'), /Invalid tier/);
+});
+
+test('validateTier: rejects empty string', () => {
+  assert.throws(() => validateTier(''), /Invalid tier/);
+});
+
+// ─── isVersionSupported ───────────────────────────────────────────────────────
+
+test('isVersionSupported: supported version returns true', () => {
+  assert.equal(isVersionSupported('2.1.83'), true);
+  assert.equal(isVersionSupported('2.5.0'), true);
+  assert.equal(isVersionSupported('2.99.0'), true);
+});
+
+test('isVersionSupported: version below floor returns false', () => {
+  assert.equal(isVersionSupported('2.1.82'), false);
+  assert.equal(isVersionSupported('2.0.99'), false);
+  assert.equal(isVersionSupported('1.99.0'), false);
+});
+
+test('isVersionSupported: v3+ returns false', () => {
+  assert.equal(isVersionSupported('3.0.0'), false);
+  assert.equal(isVersionSupported('3.1.0'), false);
+});
+
+test('isVersionSupported: non-semver string returns false', () => {
+  assert.equal(isVersionSupported(''), false);
+  assert.equal(isVersionSupported('latest'), false);
+});
+
+test('isVersionSupported: handles version prefix in claude --version output', () => {
+  // `claude --version` may return "2.3.7" or "claude 2.3.7" — match by first semver
+  assert.equal(isVersionSupported('claude 2.3.7'), true);
+  assert.equal(isVersionSupported('claude 1.0.0'), false);
+});
+
+// ─── ruleIdFromPattern / classifyRule ────────────────────────────────────────
+
+test('ruleIdFromPattern: RM pattern', () => {
+  assert.equal(ruleIdFromPattern('Bash(rm -rf /*)'), 'OACB-RM-001');
+});
+
+test('ruleIdFromPattern: TF pattern', () => {
+  assert.equal(ruleIdFromPattern('Bash(terraform destroy *)'), 'OACB-TF-001');
+});
+
+test('ruleIdFromPattern: credential read pattern', () => {
+  assert.equal(ruleIdFromPattern('Read(**/.aws/credentials)'), 'OACB-READ-001');
+});
+
+test('classifyRule: rm maps to ASI02', () => {
+  assert.equal(classifyRule('Bash(rm -rf /*)'), 'ASI02');
+});
+
+test('classifyRule: credential read maps to ASI07', () => {
+  assert.equal(classifyRule('Read(**/.env)'), 'ASI07');
+});
+
+// ─── mergeOverrides ───────────────────────────────────────────────────────────
+
+test('mergeOverrides: scalar override wins', () => {
+  const base = { a: 1, b: 2 };
+  const override = { b: 99 };
+  assert.deepEqual(mergeOverrides(base, override), { a: 1, b: 99 });
+});
+
+test('mergeOverrides: array union (no duplicates)', () => {
+  const base = { deny: ['A', 'B'] };
+  const override = { deny: ['B', 'C'] };
+  const result = mergeOverrides(base, override);
+  assert.deepEqual(result.deny.sort(), ['A', 'B', 'C']);
+});
+
+test('mergeOverrides: nested object recurses', () => {
+  const base = { permissions: { deny: ['A'], defaultMode: 'acceptEdits' } };
+  const override = { permissions: { deny: ['B'], defaultMode: 'auto' } };
+  const result = mergeOverrides(base, override);
+  assert.deepEqual(result.permissions.deny.sort(), ['A', 'B']);
+  assert.equal(result.permissions.defaultMode, 'auto');
+});
+
+test('mergeOverrides: _oacbMeta key is skipped', () => {
+  const base = { a: 1 };
+  const override = { a: 2, _oacbMeta: { tier: 'baseline' } };
+  const result = mergeOverrides(base, override);
+  assert.equal(result.a, 2);
+  assert.equal(result._oacbMeta, undefined);
+});
+
+test('mergeOverrides: does not mutate base', () => {
+  const base = { deny: ['A'] };
+  mergeOverrides(base, { deny: ['B'] });
+  assert.deepEqual(base.deny, ['A']);
+});
+
+// ─── computeDeepDiff ─────────────────────────────────────────────────────────
+
+test('computeDeepDiff: identical objects produce empty diff', () => {
+  const obj = { permissions: { deny: ['A'] }, autoMode: { environment: [] } };
+  assert.deepEqual(computeDeepDiff(obj, obj), {});
+});
+
+test('computeDeepDiff: added key', () => {
+  const a = { x: 1 };
+  const b = { x: 1, y: 2 };
+  assert.deepEqual(computeDeepDiff(a, b), { y: { added: 2 } });
+});
+
+test('computeDeepDiff: removed key', () => {
+  const a = { x: 1, y: 2 };
+  const b = { x: 1 };
+  assert.deepEqual(computeDeepDiff(a, b), { y: { removed: 2 } });
+});
+
+test('computeDeepDiff: changed scalar', () => {
+  assert.deepEqual(computeDeepDiff({ a: 1 }, { a: 2 }), { a: { from: 1, to: 2 } });
+});
+
+test('computeDeepDiff: array diff shows added/removed items', () => {
+  const a = { deny: ['A', 'B'] };
+  const b = { deny: ['A', 'C'] };
+  const diff = computeDeepDiff(a, b);
+  assert.deepEqual(diff.deny.added, ['C']);
+  assert.deepEqual(diff.deny.removed, ['B']);
+});
+
+test('computeDeepDiff: _-prefixed keys are skipped', () => {
+  const a = { _oacb: { tier: 'shadow' }, x: 1 };
+  const b = { _oacb: { tier: 'baseline' }, x: 1 };
+  assert.deepEqual(computeDeepDiff(a, b), {});
+});
+
+// ─── computeGaps ─────────────────────────────────────────────────────────────
+
+const BASELINE_FIXTURE = {
+  _oacb: { tier: 'baseline' },
+  permissions: {
+    deny: ['Bash(rm -rf /*)', 'Bash(terraform destroy *)'],
+    disableBypassPermissionsMode: 'disable',
+  },
+  autoMode: {},
+  hooks: {
+    PreToolUse: [
+      {
+        matcher: 'Bash',
+        hooks: [{ type: 'command', command: '/usr/local/share/oacb/hooks/oacb-enforce.sh', timeout: 5000 }],
+      },
+    ],
+  },
+};
+
+test('computeGaps: fully-compliant settings → no gaps', () => {
+  const current = {
+    permissions: {
+      deny: ['Bash(rm -rf /*)', 'Bash(terraform destroy *)'],
+      disableBypassPermissionsMode: 'disable',
+    },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: `${os.homedir()}/.claude/hooks/oacb-enforce.sh` }] },
+      ],
+    },
+  };
+  assert.deepEqual(computeGaps(current, BASELINE_FIXTURE), []);
+});
+
+test('computeGaps: missing deny rule reports a gap', () => {
+  const current = {
+    permissions: {
+      deny: ['Bash(rm -rf /*)'], // missing terraform destroy
+      disableBypassPermissionsMode: 'disable',
+    },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: `${os.homedir()}/.claude/hooks/oacb-enforce.sh` }] },
+      ],
+    },
+  };
+  const gaps = computeGaps(current, BASELINE_FIXTURE);
+  assert.ok(gaps.some(g => g.ruleId === 'OACB-TF-001'), 'expected OACB-TF-001 gap');
+});
+
+test('computeGaps: missing hook reports OACB-HOOK-001', () => {
+  const current = {
+    permissions: { deny: ['Bash(rm -rf /*)', 'Bash(terraform destroy *)'], disableBypassPermissionsMode: 'disable' },
+    hooks: {}, // no hooks
+  };
+  const gaps = computeGaps(current, BASELINE_FIXTURE);
+  assert.ok(gaps.some(g => g.ruleId === 'OACB-HOOK-001'), 'expected OACB-HOOK-001 gap');
+});
+
+test('computeGaps: wrong disableBypassPermissionsMode reports OACB-BYPASS-001', () => {
+  const current = {
+    permissions: {
+      deny: ['Bash(rm -rf /*)', 'Bash(terraform destroy *)'],
+      disableBypassPermissionsMode: 'enable', // wrong
+    },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: `${os.homedir()}/.claude/hooks/oacb-enforce.sh` }] },
+      ],
+    },
+  };
+  const gaps = computeGaps(current, BASELINE_FIXTURE);
+  assert.ok(gaps.some(g => g.ruleId === 'OACB-BYPASS-001'), 'expected OACB-BYPASS-001 gap');
+});
+
+test('computeGaps: empty current settings reports multiple gaps', () => {
+  const gaps = computeGaps({}, BASELINE_FIXTURE);
+  assert.ok(gaps.length > 0, 'expected gaps for empty settings');
+});
+
+test('computeGaps: deduplicates gap by rule ID', () => {
+  // Both rm patterns map to OACB-RM-001 — should report it only once
+  const baseline = {
+    _oacb: { tier: 'baseline' },
+    permissions: {
+      deny: ['Bash(rm -rf /*)', 'Bash(rm -rf ~*)', 'Bash(rm -fr /*)'],
+      disableBypassPermissionsMode: 'disable',
+    },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: '/usr/local/share/oacb/hooks/oacb-enforce.sh' }] },
+      ],
+    },
+  };
+  const current = {
+    permissions: { deny: [], disableBypassPermissionsMode: 'disable' },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: `${os.homedir()}/.claude/hooks/oacb-enforce.sh` }] },
+      ],
+    },
+  };
+  const gaps = computeGaps(current, baseline);
+  const rmGaps = gaps.filter(g => g.ruleId === 'OACB-RM-001');
+  assert.equal(rmGaps.length, 1, 'OACB-RM-001 should appear exactly once');
+});
+
+// ─── buildOacbHookEntries ─────────────────────────────────────────────────────
+
+test('buildOacbHookEntries: hook paths are rewritten to ~/.claude/hooks/', () => {
+  const hooks = buildOacbHookEntries(BASELINE_FIXTURE);
+  const hookCmd = hooks.PreToolUse[0].hooks[0].command;
+  const expectedPath = path.join(os.homedir(), '.claude', 'hooks', 'oacb-enforce.sh');
+  assert.equal(hookCmd, expectedPath);
+});
+
+test('buildOacbHookEntries: does not mutate original baseline', () => {
+  const originalCmd = BASELINE_FIXTURE.hooks.PreToolUse[0].hooks[0].command;
+  buildOacbHookEntries(BASELINE_FIXTURE);
+  assert.equal(BASELINE_FIXTURE.hooks.PreToolUse[0].hooks[0].command, originalCmd);
+});
+
+test('buildOacbHookEntries: returns all hook events from baseline', () => {
+  const hooks = buildOacbHookEntries(BASELINE_FIXTURE);
+  assert.ok(Array.isArray(hooks.PreToolUse), 'PreToolUse should be present');
+});
+
+// ─── hasOacbHook ─────────────────────────────────────────────────────────────
+
+test('hasOacbHook: detects hook present in settings', () => {
+  const settings = {
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: '/Users/test/.claude/hooks/oacb-enforce.sh' }] },
+      ],
+    },
+  };
+  assert.equal(hasOacbHook(settings, 'PreToolUse', 'oacb-enforce.sh'), true);
+});
+
+test('hasOacbHook: returns false when hook not present', () => {
+  const settings = { hooks: { PreToolUse: [] } };
+  assert.equal(hasOacbHook(settings, 'PreToolUse', 'oacb-enforce.sh'), false);
+});
+
+test('hasOacbHook: returns false when event not present', () => {
+  assert.equal(hasOacbHook({}, 'PreToolUse', 'oacb-enforce.sh'), false);
+});