cc-safe-setup 10.7.0 → 10.9.0

package/README.md

@@ -6,7 +6,7 @@
 
 **One command to make Claude Code safe for autonomous operation.** [日本語](docs/README.ja.md)
 
-8 built-in + 104 examples = **118 hooks**. 38 CLI commands. 531 tests. 5 languages. [**Hub**](https://yurukusa.github.io/cc-safe-setup/hub.html) · [Cheat Sheet](https://yurukusa.github.io/cc-safe-setup/hooks-cheatsheet.html) · [Builder](https://yurukusa.github.io/cc-safe-setup/builder.html) · [FAQ](https://yurukusa.github.io/cc-safe-setup/faq.html) · [Examples](https://yurukusa.github.io/cc-safe-setup/by-example.html) · [Matrix](https://yurukusa.github.io/cc-safe-setup/matrix.html) · [Playground](https://yurukusa.github.io/cc-hook-registry/playground.html)
+8 built-in + 104 examples = **118 hooks**. 39 CLI commands. 531 tests. 5 languages. [**Hub**](https://yurukusa.github.io/cc-safe-setup/hub.html) · [Cheat Sheet](https://yurukusa.github.io/cc-safe-setup/hooks-cheatsheet.html) · [Builder](https://yurukusa.github.io/cc-safe-setup/builder.html) · [FAQ](https://yurukusa.github.io/cc-safe-setup/faq.html) · [Examples](https://yurukusa.github.io/cc-safe-setup/by-example.html) · [Matrix](https://yurukusa.github.io/cc-safe-setup/matrix.html) · [Playground](https://yurukusa.github.io/cc-hook-registry/playground.html)
 
 ```bash
 npx cc-safe-setup

package/index.mjs

@@ -108,6 +108,8 @@ const COMPARE = COMPARE_IDX !== -1 ? { a: process.argv[COMPARE_IDX + 1], b: proc
 const REPLAY = process.argv.includes('--replay');
 const CREATE_IDX = process.argv.findIndex(a => a === '--create');
 const CREATE_DESC = CREATE_IDX !== -1 ? process.argv.slice(CREATE_IDX + 1).join(' ') : null;
+const WHY_IDX = process.argv.findIndex(a => a === '--why');
+const WHY_HOOK = WHY_IDX !== -1 ? process.argv[WHY_IDX + 1] : null;
 
 if (HELP) {
   console.log(`
@@ -139,6 +141,7 @@ if (HELP) {
     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 --create "<desc>"  Generate a custom hook from description
+    npx cc-safe-setup --why <hook>     Why this hook exists (real incident + issue link)
     npx cc-safe-setup --replay         Replay blocked commands timeline (demo/review)
     npx cc-safe-setup --guard "<rule>"  Instantly enforce a rule (generate + install + activate)
     npx cc-safe-setup --diff-hooks <path>  Compare hooks between two settings files
@@ -365,6 +368,21 @@ function examples() {
       'git-config-guard.sh': 'Block git config --global modifications',
       'case-sensitive-guard.sh': 'Detect case-insensitive FS collisions (exFAT/NTFS/HFS+)',
       'compound-command-approver.sh': 'Auto-approve safe compound commands (cd && git log)',
+      'uncommitted-work-guard.sh': 'Block destructive git with uncommitted changes',
+      'no-deploy-friday.sh': 'Block deploys on Fridays',
+      'work-hours-guard.sh': 'Restrict risky operations outside business hours',
+      'symlink-guard.sh': 'Detect symlink/junction traversal in rm targets',
+      'env-source-guard.sh': 'Block sourcing .env files into shell',
+      'strict-allowlist.sh': 'Only allow explicitly permitted commands',
+      'overwrite-guard.sh': 'Warn before overwriting existing files',
+      'memory-write-guard.sh': 'Log writes to ~/.claude/ directory',
+      'worktree-guard.sh': 'Warn on destructive git in worktrees',
+      'no-curl-upload.sh': 'Warn on curl POST/upload commands',
+      'no-port-bind.sh': 'Warn on network port binding',
+      'docker-prune-guard.sh': 'Warn before docker system prune',
+      'pip-venv-guard.sh': 'Warn on pip install outside venv',
+      'no-git-amend-push.sh': 'Warn on amending pushed commits',
+      'typosquat-guard.sh': 'Detect npm/pip typosquatting attacks',
     },
     'Auto-Approve': {
       'auto-approve-build.sh': 'Auto-approve npm/yarn/cargo/go build, test, lint',
@@ -372,6 +390,12 @@ function examples() {
       'auto-approve-git-read.sh': 'Auto-approve git status/log/diff even with -C flags',
       'auto-approve-python.sh': 'Auto-approve pytest, mypy, ruff, black, isort',
       'auto-approve-ssh.sh': 'Auto-approve safe SSH commands (uptime, whoami)',
+      'auto-approve-go.sh': 'Auto-approve go build/test/vet/fmt',
+      'auto-approve-cargo.sh': 'Auto-approve cargo build/test/clippy',
+      'auto-approve-make.sh': 'Auto-approve make build/test/lint',
+      'auto-approve-gradle.sh': 'Auto-approve gradle/gradlew build/test',
+      'auto-approve-maven.sh': 'Auto-approve mvn compile/test/verify',
+      'permission-cache.sh': 'Auto-approve previously approved commands in session',
     },
     'Quality': {
       'branch-name-check.sh': 'Warn on non-conventional branch names',
@@ -381,6 +405,28 @@ function examples() {
       'large-file-guard.sh': 'Warn when Write creates files over 500KB',
       'todo-check.sh': 'Warn when committing files with TODO/FIXME markers',
       'verify-before-commit.sh': 'Block commit unless tests passed recently',
+      'test-deletion-guard.sh': 'Warn when removing test assertions',
+      'fact-check-gate.sh': 'Warn when docs reference unread source files',
+      'conflict-marker-guard.sh': 'Block commits with merge conflict markers',
+      'commit-quality-gate.sh': 'Warn on vague commit messages',
+      'commit-scope-guard.sh': 'Warn when committing 15+ files at once',
+      'require-issue-ref.sh': 'Warn when commit lacks issue reference',
+      'no-console-log.sh': 'Warn on console.log in production code',
+      'no-eval.sh': 'Warn on eval() usage (security risk)',
+      'no-wildcard-import.sh': 'Warn on import * patterns',
+      'no-todo-ship.sh': 'Warn on TODO/FIXME in commits',
+      'test-coverage-guard.sh': 'Warn when code grows without tests',
+      'ci-skip-guard.sh': 'Warn on [skip ci] and --no-verify',
+      'debug-leftover-guard.sh': 'Detect debugger/pdb/binding.pry in staged code',
+      'typescript-strict-guard.sh': 'Warn when tsconfig strict mode disabled',
+      'sensitive-regex-guard.sh': 'Detect ReDoS-vulnerable regex patterns',
+      'git-author-guard.sh': 'Verify git author is configured',
+      'git-blame-context.sh': 'Show file ownership before major edits',
+      'import-cycle-warn.sh': 'Detect circular import patterns',
+      'env-drift-guard.sh': 'Detect .env vs .env.example mismatch',
+      'package-script-guard.sh': 'Warn when package.json scripts change',
+      'lockfile-guard.sh': 'Warn when lockfiles modified in commits',
+      'git-lfs-guard.sh': 'Suggest Git LFS for large files',
     },
     'Recovery': {
       'auto-checkpoint.sh': 'Auto-commit after edits for rollback protection',
@@ -410,6 +456,28 @@ function examples() {
       'max-file-count-guard.sh': 'Warn when 20+ files created per session',
       'protect-claudemd.sh': 'Block edits to CLAUDE.md and settings files',
       'reinject-claudemd.sh': 'Re-inject CLAUDE.md rules after compaction',
+      'token-budget-guard.sh': 'Block when estimated cost exceeds budget',
+      'output-length-guard.sh': 'Warn when tool output exceeds 50KB',
+      'error-memory-guard.sh': 'Block retries of already-failed commands',
+      'parallel-edit-guard.sh': 'Detect concurrent edits to same file',
+      'large-read-guard.sh': 'Warn before catting large files',
+      'context-snapshot.sh': 'Auto-save session state before context loss',
+      'compact-reminder.sh': 'Suggest /compact after N tool calls',
+      'revert-helper.sh': 'Show undo command when session ends',
+      'hardcoded-secret-detector.sh': 'Detect AWS keys, passwords, JWT in code',
+      'prompt-injection-guard.sh': 'Detect injection patterns in tool output',
+      'verify-before-done.sh': 'Warn when committing without running tests',
+      'disk-space-guard.sh': 'Warn when disk space is low',
+      'changelog-reminder.sh': 'Remind to update CHANGELOG on version bump',
+      'rate-limit-guard.sh': 'Detect rapid-fire tool calls',
+      'stale-env-guard.sh': 'Warn when .env is 90+ days old',
+      'node-version-guard.sh': 'Detect .nvmrc version mismatch',
+      'auto-stash-before-pull.sh': 'Warn before pull/merge with dirty tree',
+      'license-check.sh': 'Note missing license headers in source files',
+      'backup-before-refactor.sh': 'Auto-stash before large refactors',
+      'file-size-limit.sh': 'Block creating files over 1MB',
+      'branch-naming-convention.sh': 'Enforce feat/fix/chore branch prefixes',
+      'pr-description-check.sh': 'Ensure PRs have description body',
     },
   };
 
@@ -857,6 +925,70 @@ async function fullSetup() {
   console.log();
 }
 
+async function why(hookName) {
+  const WHY_DATA = {
+    'destructive-guard': { issue: '#36339', incident: 'User lost entire C:\\Users directory — rm -rf followed NTFS junctions', url: 'https://github.com/anthropics/claude-code/issues/36339' },
+    'branch-guard': { issue: '#36640', incident: 'Autonomous Claude pushed untested code to main at 3am', url: 'https://github.com/anthropics/claude-code/issues/36640' },
+    'secret-guard': { issue: '#16561', incident: 'API keys committed to public repo via git add .', url: 'https://github.com/anthropics/claude-code/issues/16561' },
+    'block-database-wipe': { issue: '#37405', incident: 'Production database wiped by migrate:fresh', url: 'https://github.com/anthropics/claude-code/issues/37405' },
+    'uncommitted-work-guard': { issue: '#37888', incident: 'Claude destroyed uncommitted work twice in same session', url: 'https://github.com/anthropics/claude-code/issues/37888' },
+    'test-deletion-guard': { issue: '#38050', incident: 'Claude deleted failing tests instead of fixing code', url: 'https://github.com/anthropics/claude-code/issues/38050' },
+    'fact-check-gate': { issue: '#38057', incident: 'Claude wrote false claims in technical docs without reading source', url: 'https://github.com/anthropics/claude-code/issues/38057' },
+    'token-budget-guard': { issue: '#38029', incident: 'Session consumed $342 in tokens without user knowing', url: 'https://github.com/anthropics/claude-code/issues/38029' },
+    'protect-dotfiles': { issue: '#37478', incident: '.bashrc and environment files overwritten', url: 'https://github.com/anthropics/claude-code/issues/37478' },
+    'scope-guard': { issue: '#36233', incident: 'Entire Mac filesystem deleted by out-of-scope operation', url: 'https://github.com/anthropics/claude-code/issues/36233' },
+    'case-sensitive-guard': { issue: '#37875', incident: 'exFAT case collision caused data loss via rm -rf', url: 'https://github.com/anthropics/claude-code/issues/37875' },
+    'prompt-injection-guard': { issue: '#38046', incident: 'Prompt injection found in /insights output', url: 'https://github.com/anthropics/claude-code/issues/38046' },
+    'overwrite-guard': { issue: '#37595', incident: '/export overwrites existing files without warning', url: 'https://github.com/anthropics/claude-code/issues/37595' },
+    'memory-write-guard': { issue: '#38040', incident: 'No way to see what Claude writes to ~/.claude/', url: 'https://github.com/anthropics/claude-code/issues/38040' },
+    'context-monitor': { issue: '#6527', incident: 'Sessions silently lost all state after 150+ tool calls', url: 'https://github.com/anthropics/claude-code/issues/6527' },
+    'comment-strip': { issue: '#29582', incident: 'Bash comments in hook commands broke permission matching', url: 'https://github.com/anthropics/claude-code/issues/29582' },
+    'cd-git-allow': { issue: '#32985', incident: 'cd+git compounds spammed permission prompts endlessly', url: 'https://github.com/anthropics/claude-code/issues/32985' },
+    'strict-allowlist': { issue: '#37471', incident: 'Denylist model creates arms race — Claude finds bypasses', url: 'https://github.com/anthropics/claude-code/issues/37471' },
+    'error-memory-guard': { issue: 'common', incident: 'Claude retries the same failing command 10+ times' },
+    'typosquat-guard': { issue: 'supply-chain', incident: 'Misspelled package names can install malware' },
+  };
+
+  console.log();
+  if (!hookName) {
+    console.log(c.bold + '  cc-safe-setup --why <hook-name>' + c.reset);
+    console.log(c.dim + '  Show why a hook exists — the real incident that inspired it.' + c.reset);
+    console.log();
+    console.log('  Examples:');
+    console.log(c.dim + '    npx cc-safe-setup --why destructive-guard' + c.reset);
+    console.log(c.dim + '    npx cc-safe-setup --why token-budget-guard' + c.reset);
+    console.log();
+    console.log(`  ${Object.keys(WHY_DATA).length} hooks have documented incidents.`);
+    return;
+  }
+
+  const name = hookName.replace('.sh', '');
+  const data = WHY_DATA[name];
+  if (!data) {
+    console.log(c.yellow + `  No incident documented for "${name}".` + c.reset);
+    console.log(c.dim + '  This hook may have been created proactively.' + c.reset);
+    console.log();
+    console.log(c.dim + `  Hooks with documented incidents: ${Object.keys(WHY_DATA).join(', ')}` + c.reset);
+    return;
+  }
+
+  console.log(c.bold + `  Why "${name}" exists` + c.reset);
+  console.log();
+  console.log(c.red + '  Incident:' + c.reset);
+  console.log('  ' + data.incident);
+  console.log();
+  if (data.url) {
+    console.log(c.blue + '  Source:' + c.reset);
+    console.log('  ' + data.url);
+  }
+  if (data.issue && data.issue !== 'common' && data.issue !== 'supply-chain') {
+    console.log(c.dim + `  GitHub Issue: ${data.issue}` + c.reset);
+  }
+  console.log();
+  console.log(c.dim + '  Install: npx cc-safe-setup --install-example ' + name + c.reset);
+  console.log();
+}
+
 async function replay() {
   console.log();
   console.log(c.bold + '  cc-safe-setup --replay' + c.reset);
@@ -3986,6 +4118,7 @@ async function main() {
   if (FULL) return fullSetup();
   if (DOCTOR) return doctor();
   if (WATCH) return watch();
+  if (WHY_IDX !== -1) return why(WHY_HOOK);
   if (REPLAY) return replay();
   if (GUARD_IDX !== -1) return guard(GUARD_DESC);
   if (DIFF_HOOKS_IDX !== -1) return diffHooks(DIFF_HOOKS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-safe-setup",
-  "version": "10.7.0",
+  "version": "10.9.0",
   "description": "One command to make Claude Code safe. 59 hooks (8 built-in + 51 examples). 26 CLI commands: dashboard, create, audit, lint, diff, migrate, compare, generate-ci. 284 tests.",
   "main": "index.mjs",
   "bin": {