cc-safe-setup 3.8.0 → 4.0.0

package/README.md

@@ -224,6 +224,8 @@ Or browse all available examples in [`examples/`](examples/):
 - **session-handoff.sh** — Auto-save git state and session info to `~/.claude/session-handoff.md` on session end
 - **diff-size-guard.sh** — Warn/block when committing too many files at once (default: warn at 10, block at 50)
 - **dependency-audit.sh** — Warn when installing packages not in manifest (npm/pip/cargo supply chain awareness)
+- **cost-tracker.sh** — Estimate session token cost and warn at thresholds ($1, $5)
+- **read-before-edit.sh** — Warn when editing files not recently read (prevents old_string mismatches)
 
 ## Safety Checklist
 

package/docs/ROADMAP.md

@@ -0,0 +1,83 @@
+# cc-safe-setup Roadmap
+
+## Current: v3.8.1
+
+- 8 built-in hooks + 38 examples
+- 21 CLI commands
+- 5 web tools (audit, cheatsheet, ecosystem, cookbook, hook builder)
+- 173 tests, CI green
+- 2,500+ daily npm downloads
+
+## Next Major: v4.0 (planned)
+
+### --dashboard: Real-Time Terminal Dashboard
+
+A single screen showing everything about your Claude Code safety:
+
+```
+┌─ cc-safe-setup dashboard ─────────────────────────┐
+│                                                     │
+│  Hooks: 26 active (8 built-in + 18 examples)       │
+│  Score: 85/100 (Grade A)                            │
+│  Context: ~60% remaining                            │
+│  Cost: ~$1.47 (142 tool calls, Opus)                │
+│                                                     │
+│  ── Recent Blocks ──────────────────────────────── │
+│  14:23  rm -rf ~/projects (destructive-guard)       │
+│  14:21  git push --force (branch-guard)             │
+│  14:18  git add .env (secret-guard)                 │
+│                                                     │
+│  ── Hook Performance ───────────────────────────── │
+│  destructive-guard  15ms ████████                   │
+│  branch-guard        7ms ████                       │
+│  secret-guard        5ms ███                        │
+│                                                     │
+│  ── Today ──────────────────────────────────────── │
+│  Blocks: 12 | Warns: 5 | Approves: 34              │
+│  Top reason: rm on sensitive path (5)               │
+└─────────────────────────────────────────────────────┘
+```
+
+**Implementation notes:**
+- ANSI escape codes only (no blessed/ink dependencies)
+- Reads blocked-commands.log + context-monitor state + cost-tracker state
+- Refreshes every 2 seconds
+- Ctrl+C to exit
+- Works in any terminal (iTerm, VS Code, Windows Terminal, WSL)
+
+### Hook Marketplace (concept)
+
+Community-contributed hooks discoverable from CLI:
+
+```bash
+npx cc-safe-setup --search "database"
+npx cc-safe-setup --install-remote user/hook-name
+```
+
+Would require a registry (GitHub-based, no server). Defer to v5.0.
+
+### Hook Composition
+
+Chain hooks with conditions:
+
+```json
+{
+  "hooks": [{
+    "if": "branch === 'main'",
+    "then": "block-all-writes.sh",
+    "else": "allow-all.sh"
+  }]
+}
+```
+
+Requires Claude Code API changes. Not feasible with current hook system.
+
+## Done (Session 39)
+
+- --create, --lint, --diff, --share, --benchmark, --doctor, --watch, --stats
+- --export/--import, --audit --json
+- 38 examples including cost-tracker, loop-detector, session-handoff
+- Hook Builder web tool
+- Interactive COOKBOOK
+- 6 documentation files + Japanese README
+- CONTRIBUTING.md for external contributors

package/examples/cost-tracker.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# ================================================================
+# cost-tracker.sh — Estimate session token cost
+# ================================================================
+# PURPOSE:
+#   Claude Code doesn't show token costs. This hook tracks
+#   tool calls and estimates cumulative cost, warning at thresholds.
+#
+# TRIGGER: PostToolUse
+# MATCHER: ""
+#
+# HOW IT WORKS:
+#   Counts tool calls as a proxy for token usage.
+#   Average tool call ≈ 2K tokens input + 1K output.
+#   Opus: $15/M input, $75/M output
+#   Sonnet: $3/M input, $15/M output
+#
+# CONFIGURATION:
+#   CC_COST_MODEL=opus   (default) or sonnet
+#   CC_COST_WARN=1.00    warn at $1 (default)
+#   CC_COST_BLOCK=5.00   warn at $5 (default, doesn't block)
+# ================================================================
+
+COUNTER_FILE="/tmp/cc-cost-tracker-calls"
+LAST_WARN="/tmp/cc-cost-tracker-warned"
+
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+MODEL="${CC_COST_MODEL:-opus}"
+WARN="${CC_COST_WARN:-1.00}"
+BLOCK="${CC_COST_BLOCK:-5.00}"
+
+# Estimate: ~2K input + ~1K output tokens per tool call
+if [ "$MODEL" = "opus" ]; then
+    # Opus: $15/M in, $75/M out → ~$0.105 per tool call
+    COST=$(echo "scale=2; $COUNT * 0.105" | bc 2>/dev/null || echo "0")
+else
+    # Sonnet: $3/M in, $15/M out → ~$0.021 per tool call
+    COST=$(echo "scale=2; $COUNT * 0.021" | bc 2>/dev/null || echo "0")
+fi
+
+# Graduated warnings (with cooldown)
+WARNED=$(cat "$LAST_WARN" 2>/dev/null || echo "0")
+
+if [ "$(echo "$COST >= $BLOCK" | bc 2>/dev/null)" = "1" ] && [ "$WARNED" != "block" ]; then
+    echo "COST: ~\$${COST} estimated ($COUNT tool calls, $MODEL)" >&2
+    echo "Consider finishing current task and compacting." >&2
+    echo "block" > "$LAST_WARN"
+elif [ "$(echo "$COST >= $WARN" | bc 2>/dev/null)" = "1" ] && [ "$WARNED" = "0" ]; then
+    echo "COST: ~\$${COST} estimated ($COUNT tool calls, $MODEL)" >&2
+    echo "warn" > "$LAST_WARN"
+fi
+
+exit 0

package/index.mjs

@@ -84,6 +84,7 @@ const DIFF_IDX = process.argv.findIndex(a => a === '--diff');
 const DIFF_FILE = DIFF_IDX !== -1 ? process.argv[DIFF_IDX + 1] : null;
 const SHARE = process.argv.includes('--share');
 const BENCHMARK = process.argv.includes('--benchmark');
+const DASHBOARD = process.argv.includes('--dashboard');
 const CREATE_IDX = process.argv.findIndex(a => a === '--create');
 const CREATE_DESC = CREATE_IDX !== -1 ? process.argv.slice(CREATE_IDX + 1).join(' ') : null;
 
@@ -105,6 +106,7 @@ if (HELP) {
     npx cc-safe-setup --audit --json  Machine-readable output for CI/CD
     npx cc-safe-setup --scan       Detect tech stack, recommend hooks
     npx cc-safe-setup --learn      Learn from your block history
+    npx cc-safe-setup --dashboard     Real-time status dashboard
     npx cc-safe-setup --benchmark     Measure hook execution time
     npx cc-safe-setup --share         Generate shareable URL for your setup
     npx cc-safe-setup --diff <file>   Compare your settings with another file
@@ -356,6 +358,8 @@ function examples() {
       'commit-quality-gate.sh': 'Warn on vague or too-long commit messages',
       'diff-size-guard.sh': 'Warn/block on large diffs (10+ files warn, 50+ block)',
       'dependency-audit.sh': 'Warn on new package installs not in manifest',
+      'cost-tracker.sh': 'Estimate session token cost ($1 warn, $5 alert)',
+      'read-before-edit.sh': 'Warn when editing files not recently read',
     },
   };
 
@@ -786,6 +790,74 @@ async function fullSetup() {
   console.log();
 }
 
+async function dashboard() {
+  const { createReadStream, watchFile } = await import('fs');
+  const { createInterface: createRL } = await import('readline');
+
+  const BLOCK_LOG = join(HOME, '.claude', 'blocked-commands.log');
+  const COST_FILE = '/tmp/cc-cost-tracker-calls';
+  const CONTEXT_FILE = '/tmp/cc-context-pct';
+
+  const clear = () => process.stdout.write('\x1b[2J\x1b[H');
+
+  // Count hooks
+  let hookCount = 0;
+  let exampleCount = 0;
+  if (existsSync(SETTINGS_PATH)) {
+    try {
+      const s = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8'));
+      for (const entries of Object.values(s.hooks || {})) {
+        hookCount += entries.reduce((n, e) => n + (e.hooks || []).length, 0);
+      }
+    } catch {}
+  }
+  exampleCount = existsSync(join(HOOKS_DIR)) ?
+    (await import('fs')).readdirSync(HOOKS_DIR).filter(f => f.endsWith('.sh')).length : 0;
+
+  function render() {
+    clear();
+
+    // Header
+    console.log(c.bold + '  cc-safe-setup --dashboard' + c.reset + '  ' + c.dim + new Date().toLocaleTimeString() + c.reset);
+    console.log('  ' + '─'.repeat(50));
+
+    // Status row
+    const context = existsSync(CONTEXT_FILE) ? readFileSync(CONTEXT_FILE, 'utf-8').trim() + '%' : '?';
+    const calls = existsSync(COST_FILE) ? readFileSync(COST_FILE, 'utf-8').trim() : '0';
+    const cost = (parseInt(calls) * 0.105).toFixed(2);
+
+    console.log('  Hooks: ' + c.green + hookCount + c.reset + ' registered  |  Scripts: ' + exampleCount);
+    console.log('  Context: ' + c.yellow + context + c.reset + '  |  Cost: ~$' + cost + ' (' + calls + ' calls)');
+    console.log('  ' + '─'.repeat(50));
+
+    // Recent blocks
+    console.log(c.bold + '  Recent Blocks' + c.reset);
+    if (existsSync(BLOCK_LOG)) {
+      const lines = readFileSync(BLOCK_LOG, 'utf-8').split('\n').filter(l => l.trim());
+      const recent = lines.slice(-5);
+      for (const line of recent) {
+        const m = line.match(/^\[([^\]]+)\]\s*BLOCKED:\s*(.+?)\s*\|/);
+        if (m) {
+          const time = m[1].replace(/T/, ' ').replace(/\+.*/, '').slice(11, 16);
+          console.log('  ' + c.dim + time + c.reset + '  ' + c.red + m[2].trim() + c.reset);
+        }
+      }
+      if (recent.length === 0) console.log(c.dim + '  (none)' + c.reset);
+    } else {
+      console.log(c.dim + '  (no log yet)' + c.reset);
+    }
+
+    console.log('  ' + '─'.repeat(50));
+    console.log(c.dim + '  Refreshing every 3s. Ctrl+C to exit.' + c.reset);
+  }
+
+  render();
+  setInterval(render, 3000);
+
+  // Keep alive
+  await new Promise(() => {});
+}
+
 async function benchmark() {
   const { spawnSync } = await import('child_process');
 
@@ -2073,6 +2145,7 @@ async function main() {
   if (FULL) return fullSetup();
   if (DOCTOR) return doctor();
   if (WATCH) return watch();
+  if (DASHBOARD) return dashboard();
   if (BENCHMARK) return benchmark();
   if (SHARE) return share();
   if (DIFF_FILE) return diff(DIFF_FILE);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-safe-setup",
-  "version": "3.8.0",
+  "version": "4.0.0",
   "description": "One command to make Claude Code safe for autonomous operation. 8 built-in + 36 examples. 21 commands: create, audit, lint, diff, share, benchmark, watch, learn. 2,500+ daily npm downloads.",
   "main": "index.mjs",
   "bin": {