cc-safe-setup 2.7.0 → 2.9.0

package/MIGRATION.md

@@ -0,0 +1,224 @@
+# Migrating from Permissions-Only to Hooks
+
+You've been using `permissions.allow` and `permissions.deny` to control Claude Code. It works — until it doesn't. This guide shows how to add hooks for the things permissions can't do.
+
+## Why Migrate?
+
+Permissions are binary: allow or deny. Hooks are programmable: inspect the command, check context, decide dynamically.
+
+| What you want | Permissions | Hooks |
+|---|---|---|
+| Allow `git status` | `Bash(git status:*)` | Same, or auto-approve hook |
+| Block `rm -rf /` but allow `rm -rf node_modules` | Can't — it's all or nothing | `destructive-guard.sh` checks the path |
+| Block `git push --force` but allow `git push` | Can't | `branch-guard.sh` checks flags |
+| Block `git add .env` but allow `git add src/` | Can't | `secret-guard.sh` checks the target |
+| Auto-approve `cd /path && git log` | Can't — compound command | `cd-git-allow.sh` parses both parts |
+| Warn when context is running low | Not a permission concept | `context-monitor.sh` tracks usage |
+
+## Step 1: Audit Your Current Setup
+
+```bash
+npx cc-safe-setup --audit
+```
+
+This scores your current settings (0-100) and shows what's missing.
+
+Or paste your `settings.json` into the [web tool](https://yurukusa.github.io/cc-safe-setup/) — no npm required.
+
+## Step 2: Keep Your Permissions, Add Hooks
+
+**You don't need to remove your existing permissions.** Hooks and permissions work together:
+
+1. Permissions run first (allow/deny the tool call)
+2. If allowed, PreToolUse hooks run (can block with exit 2)
+3. Tool executes
+4. PostToolUse hooks run (can warn about issues)
+
+This means you can keep your working `allow` rules and layer hooks on top for the edge cases.
+
+### Before (permissions only)
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(npm:*)",
+      "Bash(node:*)",
+      "Read(*)",
+      "Edit(*)",
+      "Write(*)"
+    ]
+  }
+}
+```
+
+**Problem:** `Bash(git:*)` allows `git push --force origin main`. No way to block it without also blocking `git push origin feature-branch`.
+
+### After (permissions + hooks)
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(npm:*)",
+      "Bash(node:*)",
+      "Read(*)",
+      "Edit(*)",
+      "Write(*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "~/.claude/hooks/destructive-guard.sh" },
+          { "type": "command", "command": "~/.claude/hooks/branch-guard.sh" },
+          { "type": "command", "command": "~/.claude/hooks/secret-guard.sh" },
+          { "type": "command", "command": "~/.claude/hooks/comment-strip.sh" },
+          { "type": "command", "command": "~/.claude/hooks/cd-git-allow.sh" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "~/.claude/hooks/syntax-check.sh" }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "~/.claude/hooks/context-monitor.sh" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "~/.claude/hooks/api-error-alert.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Result:** `git push origin feature-branch` still works. `git push --force` and `git push origin main` are blocked. `rm -rf node_modules` works. `rm -rf /` is blocked. All without changing your `allow` rules.
+
+## Step 3: Install Everything Automatically
+
+```bash
+npx cc-safe-setup
+```
+
+This creates the hook scripts and merges the config into your existing settings.json. Your current `permissions` are preserved.
+
+## Step 4: Verify
+
+```bash
+npx cc-safe-setup --verify
+```
+
+Tests each hook with sample inputs. If something fails:
+
+```bash
+npx cc-safe-setup --doctor
+```
+
+This checks jq installation, file permissions, shebang lines, and common misconfigurations.
+
+## Common Migration Patterns
+
+### "I use `Bash(*)` to auto-approve everything"
+
+You're trading speed for safety. Keep `Bash(*)` but add hooks to catch the dangerous commands:
+
+```bash
+npx cc-safe-setup
+```
+
+Now `Bash(*)` auto-approves commands, but hooks still run and block dangerous ones. Best of both worlds.
+
+### "I use `dontAsk` mode"
+
+Same approach. `dontAsk` skips permission prompts but **hooks still fire**. Install hooks and you're protected.
+
+### "I use `bypassPermissions`"
+
+**Warning:** `bypassPermissions` skips **everything** including hooks. Switch to `dontAsk` instead — same UX (no prompts) but hooks still protect you.
+
+### "I have deny rules for specific commands"
+
+Deny rules work but are fragile. `deny: ["Bash(rm -rf:*)"]` doesn't catch `rm -r -f` or `sudo rm -rf`. A hook can use regex to catch all variants.
+
+You can keep your deny rules as a first line of defense and add hooks as a second layer.
+
+## Hook Development Reference
+
+### How hooks receive data
+
+Hooks read JSON from stdin:
+
+```json
+{
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "git push origin main"
+  }
+}
+```
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Allow (or no opinion) |
+| 2 | **Block** — command does not execute |
+| Other | Error (treated as allow) |
+
+### Returning data
+
+Hooks can modify the input or make permission decisions by writing JSON to stdout:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "permissionDecisionReason": "auto-approved by hook"
+  }
+}
+```
+
+### Testing a hook manually
+
+```bash
+echo '{"tool_input":{"command":"rm -rf /"}}' | bash ~/.claude/hooks/destructive-guard.sh
+echo $?  # Should be 2 (blocked)
+```
+
+## Monitor Your Hooks
+
+Watch what's being blocked in real time:
+
+```bash
+npx cc-safe-setup --watch
+```
+
+After a few sessions, generate custom hooks from your block patterns:
+
+```bash
+npx cc-safe-setup --learn
+```
+
+## Resources
+
+- [Official Hooks Documentation](https://docs.anthropic.com/en/docs/claude-code/hooks)
+- [COOKBOOK.md](https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md) — 19 hook recipes
+- [cc-safe-setup](https://github.com/yurukusa/cc-safe-setup) — automated setup
+- [Web Audit Tool](https://yurukusa.github.io/cc-safe-setup/) — browser-based setup generator

package/README.md

@@ -78,6 +78,10 @@ Safe to run multiple times. Existing settings are preserved. A backup is created
 
 **Verify hooks work:** `npx cc-safe-setup --verify` — sends test inputs to each hook and confirms they block/allow correctly.
 
+**Troubleshoot:** `npx cc-safe-setup --doctor` — diagnoses why hooks aren't working (jq, permissions, paths, shebang).
+
+**Live monitor:** `npx cc-safe-setup --watch` — real-time dashboard of blocked commands during autonomous sessions.
+
 **Uninstall:** `npx cc-safe-setup --uninstall` — removes all hooks and cleans settings.json.
 
 **Requires:** [jq](https://jqlang.github.io/jq/) for JSON parsing (`brew install jq` / `apt install jq`).
@@ -204,11 +208,16 @@ Or browse all available examples in [`examples/`](examples/):
 
 **[SAFETY_CHECKLIST.md](SAFETY_CHECKLIST.md)** — Copy-paste checklist for before/during/after autonomous sessions.
 
+## Migration Guide
+
+**[MIGRATION.md](MIGRATION.md)** — Step-by-step guide for moving from permissions-only to permissions + hooks. Keep your existing config, add safety layers on top.
+
 ## Learn More
 
-- [Official Hooks Reference](https://code.claude.com/docs/en/hooks) — Claude Code hooks documentation
-- [Hooks Cookbook](https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md) — 18 ready-to-use recipes from real GitHub Issues
+- [Official Hooks Reference](https://docs.anthropic.com/en/docs/claude-code/hooks) — Claude Code hooks documentation
+- [Hooks Cookbook](https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md) — 19 ready-to-use recipes from real GitHub Issues
 - [Japanese guide (Qiita)](https://qiita.com/yurukusa/items/a9714b33f5d974e8f1e8) — この記事の日本語解説
+- [Hook Test Runner](https://github.com/yurukusa/cc-hook-test) — `npx cc-hook-test <hook.sh>` to auto-test any hook
 - [The incident that inspired this tool](https://github.com/anthropics/claude-code/issues/36339) — NTFS junction rm -rf
 
 ## FAQ

package/index.mjs

@@ -74,6 +74,10 @@ const SCAN = process.argv.includes('--scan');
 const FULL = process.argv.includes('--full');
 const DOCTOR = process.argv.includes('--doctor');
 const WATCH = process.argv.includes('--watch');
+const EXPORT = process.argv.includes('--export');
+const IMPORT_IDX = process.argv.findIndex(a => a === '--import');
+const IMPORT_FILE = IMPORT_IDX !== -1 ? process.argv[IMPORT_IDX + 1] : null;
+const STATS = process.argv.includes('--stats');
 
 if (HELP) {
   console.log(`
@@ -94,6 +98,9 @@ if (HELP) {
     npx cc-safe-setup --learn      Learn from your block history
     npx cc-safe-setup --doctor     Diagnose why hooks aren't working
     npx cc-safe-setup --watch      Live dashboard of blocked commands
+    npx cc-safe-setup --stats      Block statistics and patterns report
+    npx cc-safe-setup --export     Export hooks config for team sharing
+    npx cc-safe-setup --import <file>  Import hooks from exported config
     npx cc-safe-setup --help       Show this help
 
   Hooks installed:
@@ -742,6 +749,253 @@ async function fullSetup() {
   console.log();
 }
 
+async function stats() {
+  const LOG_PATH = join(HOME, '.claude', 'blocked-commands.log');
+
+  console.log();
+  console.log(c.bold + '  cc-safe-setup --stats' + c.reset);
+  console.log(c.dim + '  Block statistics from your hook history' + c.reset);
+  console.log();
+
+  if (!existsSync(LOG_PATH)) {
+    console.log(c.dim + '  No blocked-commands.log found. Hooks haven\'t blocked anything yet.' + c.reset);
+    console.log(c.dim + '  This is normal if you just installed hooks.' + c.reset);
+    console.log();
+    process.exit(0);
+  }
+
+  const lines = readFileSync(LOG_PATH, 'utf-8').split('\n').filter(l => l.trim());
+  if (lines.length === 0) {
+    console.log(c.dim + '  Log is empty. No blocks recorded yet.' + c.reset);
+    console.log();
+    process.exit(0);
+  }
+
+  // Parse log entries: [timestamp] BLOCKED: reason | cmd: command
+  const entries = [];
+  const reasonCounts = {};
+  const hourCounts = {};
+  const dayCounts = {};
+  const commandPatterns = {};
+
+  for (const line of lines) {
+    const match = line.match(/^\[([^\]]+)\]\s*BLOCKED:\s*(.+?)\s*\|\s*cmd:\s*(.+)$/);
+    if (!match) continue;
+
+    const [, ts, reason, cmd] = match;
+    const date = new Date(ts);
+    const day = ts.split('T')[0];
+    const hour = date.getHours();
+
+    entries.push({ ts, reason: reason.trim(), cmd: cmd.trim(), date, day, hour });
+
+    // Count reasons
+    const r = reason.trim();
+    reasonCounts[r] = (reasonCounts[r] || 0) + 1;
+
+    // Count by hour
+    hourCounts[hour] = (hourCounts[hour] || 0) + 1;
+
+    // Count by day
+    dayCounts[day] = (dayCounts[day] || 0) + 1;
+
+    // Categorize commands
+    const cmdLower = cmd.toLowerCase();
+    let pattern = 'other';
+    if (cmdLower.includes('rm ')) pattern = 'rm (delete)';
+    else if (cmdLower.includes('git push')) pattern = 'git push';
+    else if (cmdLower.includes('git reset')) pattern = 'git reset';
+    else if (cmdLower.includes('git clean')) pattern = 'git clean';
+    else if (cmdLower.includes('git add')) pattern = 'git add (secrets)';
+    else if (cmdLower.includes('remove-item')) pattern = 'PowerShell delete';
+    else if (cmdLower.includes('git checkout') || cmdLower.includes('git switch')) pattern = 'git checkout --force';
+    commandPatterns[pattern] = (commandPatterns[pattern] || 0) + 1;
+  }
+
+  if (entries.length === 0) {
+    console.log(c.dim + '  No parseable entries in log.' + c.reset);
+    console.log();
+    process.exit(0);
+  }
+
+  // Summary
+  const firstDate = entries[0].day;
+  const lastDate = entries[entries.length - 1].day;
+  const daySpan = Object.keys(dayCounts).length;
+
+  console.log(c.bold + '  Summary' + c.reset);
+  console.log('  Total blocks: ' + c.bold + entries.length + c.reset);
+  console.log('  Period: ' + firstDate + ' to ' + lastDate + ' (' + daySpan + ' days)');
+  console.log('  Average: ' + (entries.length / Math.max(daySpan, 1)).toFixed(1) + ' blocks/day');
+  console.log();
+
+  // Top reasons
+  console.log(c.bold + '  Top Block Reasons' + c.reset);
+  const sortedReasons = Object.entries(reasonCounts).sort((a, b) => b[1] - a[1]);
+  const maxReasonCount = sortedReasons[0]?.[1] || 1;
+  for (const [reason, count] of sortedReasons.slice(0, 8)) {
+    const bar = '█'.repeat(Math.ceil(count / maxReasonCount * 20));
+    const pct = ((count / entries.length) * 100).toFixed(0);
+    console.log('  ' + c.red + bar + c.reset + ' ' + count + ' (' + pct + '%) ' + reason);
+  }
+  console.log();
+
+  // Command categories
+  console.log(c.bold + '  Command Categories' + c.reset);
+  const sortedPatterns = Object.entries(commandPatterns).sort((a, b) => b[1] - a[1]);
+  for (const [pattern, count] of sortedPatterns) {
+    const pct = ((count / entries.length) * 100).toFixed(0);
+    console.log('  ' + c.yellow + count.toString().padStart(4) + c.reset + ' ' + pattern + ' (' + pct + '%)');
+  }
+  console.log();
+
+  // Activity by hour
+  console.log(c.bold + '  Blocks by Hour' + c.reset);
+  const maxHour = Math.max(...Object.values(hourCounts), 1);
+  for (let h = 0; h < 24; h++) {
+    const count = hourCounts[h] || 0;
+    if (count === 0) continue;
+    const bar = '▓'.repeat(Math.ceil(count / maxHour * 15));
+    console.log('  ' + h.toString().padStart(2) + ':00 ' + c.blue + bar + c.reset + ' ' + count);
+  }
+  console.log();
+
+  // Recent blocks (last 5)
+  console.log(c.bold + '  Recent Blocks' + c.reset);
+  for (const entry of entries.slice(-5)) {
+    const time = entry.ts.replace(/T/, ' ').replace(/\+.*/, '');
+    console.log('  ' + c.dim + time + c.reset + ' ' + entry.reason);
+    console.log('    ' + c.dim + entry.cmd.slice(0, 100) + c.reset);
+  }
+  console.log();
+}
+
+async function exportConfig() {
+  console.log();
+  console.log(c.bold + '  cc-safe-setup --export' + c.reset);
+  console.log(c.dim + '  Exporting hooks config for team sharing...' + c.reset);
+  console.log();
+
+  if (!existsSync(SETTINGS_PATH)) {
+    console.log(c.red + '  No settings.json found. Run npx cc-safe-setup first.' + c.reset);
+    process.exit(1);
+  }
+
+  const settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8'));
+  const hooks = settings.hooks || {};
+
+  // Collect installed hook scripts
+  const exportData = {
+    version: '1.0',
+    generator: 'cc-safe-setup',
+    exported_at: new Date().toISOString(),
+    hooks: {},
+    scripts: {},
+  };
+
+  // Copy hook configuration
+  exportData.hooks = JSON.parse(JSON.stringify(hooks));
+
+  // Read and embed script contents
+  const scriptPaths = new Set();
+  for (const trigger of Object.keys(hooks)) {
+    for (const entry of hooks[trigger]) {
+      for (const h of (entry.hooks || [])) {
+        if (h.type === 'command' && h.command) {
+          let scriptPath = h.command.replace(/^(bash|sh|node)\s+/, '').split(/\s+/)[0];
+          scriptPath = scriptPath.replace(/^~/, HOME);
+          if (existsSync(scriptPath)) {
+            const relName = scriptPath.replace(HOME, '~');
+            exportData.scripts[relName] = readFileSync(scriptPath, 'utf-8');
+            scriptPaths.add(relName);
+          }
+        }
+      }
+    }
+  }
+
+  const outputFile = 'cc-safe-setup-export.json';
+  writeFileSync(outputFile, JSON.stringify(exportData, null, 2));
+
+  console.log(c.green + '  ✓ Exported to ' + outputFile + c.reset);
+  console.log(c.dim + '  Contains: ' + Object.keys(exportData.hooks).length + ' trigger types, ' + scriptPaths.size + ' hook scripts' + c.reset);
+  console.log();
+  console.log(c.dim + '  Share this file with your team. They can import with:' + c.reset);
+  console.log(c.bold + '  npx cc-safe-setup --import ' + outputFile + c.reset);
+  console.log();
+}
+
+async function importConfig(file) {
+  console.log();
+  console.log(c.bold + '  cc-safe-setup --import ' + file + c.reset);
+  console.log(c.dim + '  Importing hooks config...' + c.reset);
+  console.log();
+
+  if (!existsSync(file)) {
+    console.log(c.red + '  File not found: ' + file + c.reset);
+    process.exit(1);
+  }
+
+  let exportData;
+  try {
+    exportData = JSON.parse(readFileSync(file, 'utf-8'));
+  } catch (e) {
+    console.log(c.red + '  Invalid JSON in ' + file + c.reset);
+    process.exit(1);
+  }
+
+  if (!exportData.hooks || !exportData.scripts) {
+    console.log(c.red + '  Invalid export file (missing hooks or scripts section)' + c.reset);
+    process.exit(1);
+  }
+
+  // Install scripts
+  mkdirSync(HOOKS_DIR, { recursive: true });
+  let installed = 0;
+
+  for (const [relPath, content] of Object.entries(exportData.scripts)) {
+    const absPath = relPath.replace(/^~/, HOME);
+    const dir = dirname(absPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(absPath, content);
+    chmodSync(absPath, 0o755);
+    console.log(c.green + '  ✓ ' + c.reset + relPath);
+    installed++;
+  }
+
+  // Merge hooks into settings.json
+  let settings = {};
+  if (existsSync(SETTINGS_PATH)) {
+    try {
+      settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8'));
+    } catch {}
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  for (const [trigger, entries] of Object.entries(exportData.hooks)) {
+    if (!settings.hooks[trigger]) settings.hooks[trigger] = [];
+    // Add entries that don't already exist (by command path)
+    const existing = new Set(
+      settings.hooks[trigger].flatMap(e => (e.hooks || []).map(h => h.command))
+    );
+    for (const entry of entries) {
+      const newCommands = (entry.hooks || []).filter(h => !existing.has(h.command));
+      if (newCommands.length > 0) {
+        settings.hooks[trigger].push({ ...entry, hooks: newCommands });
+      }
+    }
+  }
+
+  mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+
+  console.log();
+  console.log(c.bold + c.green + '  ✓ Imported ' + installed + ' hook scripts' + c.reset);
+  console.log(c.dim + '  Restart Claude Code to activate.' + c.reset);
+  console.log();
+}
+
 async function watch() {
   const { spawn } = await import('child_process');
   const { createReadStream, watchFile } = await import('fs');
@@ -1173,6 +1427,9 @@ async function main() {
   if (FULL) return fullSetup();
   if (DOCTOR) return doctor();
   if (WATCH) return watch();
+  if (STATS) return stats();
+  if (EXPORT) return exportConfig();
+  if (IMPORT_FILE) return importConfig(IMPORT_FILE);
 
   console.log();
   console.log(c.bold + '  cc-safe-setup' + c.reset);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-safe-setup",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "One command to make Claude Code safe for autonomous operation. 8 built-in hooks + 26 installable examples. Destructive blocker, branch guard, database wipe protection, case-insensitive FS guard, and more.",
   "main": "index.mjs",
   "bin": {