@claude-code-hooks/cli 0.1.7 → 0.1.9

package/README.md

@@ -0,0 +1,238 @@
+# @claude-code-hooks/cli
+
+> Part of the [claude-code-hooks](../../README.md) monorepo.
+
+Umbrella wizard CLI to set up and manage `@claude-code-hooks` packages for Claude Code (sound, notification, security, secrets).
+
+![CLI install and usage demo](https://github.com/beefiker/claude-code-hooks/raw/main/images/claude-code-hooks-cli.gif)
+
+## Install / run
+
+From anywhere:
+
+```bash
+npx @claude-code-hooks/cli@latest
+```
+
+You'll be prompted to choose which packages to configure and where to write settings:
+
+- Project (shared): `.claude/settings.json`
+- Project (local): `.claude/settings.local.json`
+- Global: `~/.claude/settings.json`
+
+Then you can enable/disable each package (sound, notification, security, secrets) and customize their options.
+
+---
+
+## @claude-code-hooks/sound
+
+Cross-platform CLI (macOS, Windows, Linux) that configures **Claude Code Hooks** to play **bundled sounds**.
+
+![claude-sound CLI](https://github.com/beefiker/claude-code-hooks/raw/main/packages/sound/assets/images/how-to-use.gif)
+
+- Setup UI: `npx @claude-code-hooks/sound@latest`
+- Hook runner: `npx --yes @claude-code-hooks/sound@latest play --event <Event> --sound <SoundId> --managed-by @claude-code-hooks/sound`
+
+### Install / run
+
+```bash
+npx @claude-code-hooks/sound@latest
+```
+
+You'll be prompted to choose where to write settings, then enable/disable events and choose a sound per event. Selecting a sound plays a quick preview. Choose **Create my own** to generate custom text-to-speech sounds, or **Import from file** to add your own MP3/WAV files.
+
+### Commands
+
+```bash
+claude-sound list-events
+claude-sound list-sounds
+claude-sound play --sound ring1
+claude-sound import <path>   # Import MP3/WAV into ~/.claude-sound/sounds/
+```
+
+### Uninstall / remove hooks
+
+Run the setup again and choose **Remove all claude-sound hooks**, then **Apply**. Or manually delete any hook handlers whose command contains:
+
+```
+--managed-by @claude-code-hooks/sound
+```
+
+### Create my own (text-to-speech)
+
+When picking a sound, choose **Create my own** to generate custom sounds from text. Supports English (default) and Korean. See [packages/sound/docs/TTS.md](../sound/docs/TTS.md) for details.
+
+### Import from file
+
+Choose **Import from file** and enter a path to an MP3 or WAV file. Or use the CLI:
+
+```bash
+claude-sound import ./my-notification.mp3
+```
+
+Supported formats: MP3, WAV. Max file size: 5MB.
+
+### Platform support
+
+| Platform | Audio player | Notes |
+|----------|--------------|-------|
+| **macOS** | `afplay` | Built-in, no setup needed |
+| **Windows** | `ffplay`, `mpv`, `mpg123`, or PowerShell | Install [ffmpeg](https://ffmpeg.org/) or [mpv](https://mpv.io/) for best support. PowerShell plays WAV only. |
+| **Linux** | `ffplay`, `mpv`, `mpg123`, `aplay`, etc. | Install ffmpeg or mpv for MP3 support. |
+
+---
+
+## @claude-code-hooks/notification
+
+**Zero-dependency** CLI that sends OS-level notifications from Claude Code hooks.
+
+- **macOS**: `osascript` (`display notification`)
+- **Linux**: `notify-send` (libnotify)
+- **Windows**: PowerShell toast via Windows Runtime types (no external modules)
+
+Falls back to stdout when no GUI environment is detected (SSH, headless, CI).
+
+### Install / run
+
+```bash
+npx --yes @claude-code-hooks/notification@latest --event Stop
+```
+
+### CLI options
+
+```
+--title <text>     Notification title (default: derived from --event or "Claude Code")
+--message <text>   Notification body  (default: derived from --event or stdin JSON)
+--event <name>     Hook event name (e.g. Stop, Notification, TaskCompleted)
+--dry-run          Build the command but don't execute it (prints JSON to stdout)
+```
+
+### Usage as a Claude Code hook
+
+Add to your Claude Code `settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --yes @claude-code-hooks/notification@latest --event Stop",
+            "timeout": 8
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Hook event types
+
+| Event | Description |
+|-------|-------------|
+| `SessionStart` | Session begins |
+| `Stop` | Claude stops generating |
+| `TaskCompleted` | Task is complete |
+| `Notification` | Claude wants your attention |
+| `PostToolUseFailure` | After a tool fails |
+| ... and more |
+
+### Platform support
+
+| Platform | Method | Requirements |
+|----------|--------|--------------|
+| **macOS** | `osascript` | Built-in |
+| **Linux** | `notify-send` | Install `libnotify-bin` (apt) or `libnotify` (pacman/dnf) |
+| **Windows** | PowerShell toast | Built-in PowerShell 5+ |
+| **Other/Headless** | stdout | Prints `[notification] Title: Message` to stdout |
+
+---
+
+## @claude-code-hooks/security
+
+Warns (or optionally **blocks**) risky commands/tool invocations. Heuristic and lightweight: scans for suspicious patterns like `rm -rf`, `curl | bash`, writes to `~/.ssh`, etc.
+
+### Install / run
+
+```bash
+npx @claude-code-hooks/security@latest
+```
+
+### Project config: claude-code-hooks.config.json
+
+```json
+{
+  "security": {
+    "mode": "warn",
+    "enabledEvents": ["PreToolUse", "PermissionRequest"],
+    "ignore": { "regex": [] },
+    "allow": { "regex": [] }
+  }
+}
+```
+
+- `allow.regex`: if any pattern matches, **all risks are suppressed**
+- `ignore.regex`: if any pattern matches, risks are suppressed and a dim note is printed
+
+### Modes
+
+- `warn` (default): prints warnings to stderr, exits 0
+- `block`: exits 2 when a risk is detected (**PreToolUse only**; `PermissionRequest` stays advisory)
+
+### Commands
+
+```bash
+claude-security list-events
+claude-security run --event PreToolUse --mode warn
+claude-security doctor
+```
+
+---
+
+## @claude-code-hooks/secrets
+
+Warns when **secret-like tokens** appear in tool inputs — and optionally scans **staged git files** before commits.
+
+### Install / run
+
+```bash
+npx @claude-code-hooks/secrets@latest
+```
+
+### Project config: claude-code-hooks.config.json
+
+```json
+{
+  "secrets": {
+    "mode": "warn",
+    "enabledEvents": ["PreToolUse", "PermissionRequest"],
+    "scanGitCommit": false,
+    "ignore": { "regex": [] },
+    "allow": { "regex": [] }
+  }
+}
+```
+
+- `scanGitCommit`: when `true`, intercepts `git commit` and scans staged files for secret patterns
+
+### Modes
+
+- `warn` (default): prints warnings to stderr, exits 0
+- `block`: exits 2 **only for HIGH confidence** findings (private key material)
+
+### What it detects
+
+- **HIGH**: `-----BEGIN (RSA|OPENSSH|EC|PGP|DSA|ENCRYPTED) PRIVATE KEY-----`
+- **MED**: OpenAI `sk-...`, GitHub `ghp_...` / `github_pat_...`, AWS `AKIA...`, Slack `xox*`, Google `AIza...`, Stripe `sk_live_...`, npm `npm_...`, PyPI `pypi-...`, DB URLs with credentials, etc.
+
+### Commands
+
+```bash
+claude-secrets list-events
+claude-secrets run --event PreToolUse --mode warn
+claude-secrets doctor
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-code-hooks/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Wizard CLI to set up and manage @claude-code-hooks packages for Claude Code.",
   "license": "MIT",
   "homepage": "https://github.com/beefiker/claude-code-hooks/tree/main/packages/cli",
@@ -27,11 +27,11 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@claude-code-hooks/core": "0.1.2",
-    "@claude-code-hooks/security": "0.1.4",
-    "@claude-code-hooks/secrets": "0.1.5",
-    "@claude-code-hooks/sound": "0.2.8",
-    "@claude-code-hooks/notification": "0.1.2"
+    "@claude-code-hooks/core": "0.1.3",
+    "@claude-code-hooks/security": "0.1.7",
+    "@claude-code-hooks/secrets": "0.1.8",
+    "@claude-code-hooks/sound": "0.2.11",
+    "@claude-code-hooks/notification": "0.1.5"
   },
   "keywords": [
     "claude",

package/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import process from 'node:process';
+import readline from 'node:readline';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
@@ -16,6 +17,11 @@ import {
   spinner
 } from '@clack/prompts';
 
+// Enable keypress events so we can intercept Backspace
+if (process.stdin.isTTY) {
+  readline.emitKeypressEvents(process.stdin);
+}
+
 import {
   ansi as pc,
   configPathForScope,
@@ -24,7 +30,8 @@ import {
   CONFIG_FILENAME,
   configFilePath,
   readProjectConfig,
-  writeProjectConfig
+  writeProjectConfig,
+  removeLegacyClaudeSoundHooks
 } from '@claude-code-hooks/core';
 
 import { buildSettingsSnippet } from './snippet.js';
@@ -41,6 +48,30 @@ function dieCancelled(msg = 'Cancelled') {
   process.exit(0);
 }
 
+/**
+ * Run a prompt with Backspace = go back. When Backspace is pressed, aborts and returns
+ * { wentBack: true }. ESC still exits. Caller must handle wentBack by continuing the loop.
+ * @param {AbortController} controller
+ * @param {() => Promise<T>} runPrompt - async function that runs the prompt (receives no args)
+ * @returns {Promise<{ result: T; wentBack: boolean }>}
+ */
+async function withBackspaceBack(controller, runPrompt) {
+  let wentBack = false;
+  const handler = (_str, key) => {
+    if (key?.name === 'backspace') {
+      wentBack = true;
+      controller.abort();
+    }
+  };
+  process.stdin.on('keypress', handler);
+  try {
+    const result = await runPrompt();
+    return { result, wentBack };
+  } finally {
+    process.stdin.off('keypress', handler);
+  }
+}
+
 function usage(exitCode = 0) {
   process.stdout.write(`\
 claude-code-hooks\n\nUsage:\n  claude-code-hooks\n  npx @claude-code-hooks/cli@latest\n\nWhat it does:\n  - Update Claude Code settings (global), or generate a project-only config + pasteable snippet.\n`);
@@ -84,116 +115,189 @@ async function main() {
   const projectDir = process.cwd();
 
   intro('claude-code-hooks');
+  note(`${pc.dim('ESC')} to exit  •  ${pc.dim('Backspace')} to go back`, 'Navigation');
 
-  // ── Step 1–3: action, target, packages (with simple back navigation) ──
+  // ── Step 1–3: action, target, packages (Backspace = go to previous step) ──
   let action;
   let target;
   let selected;
+  let step = 1;
+  /** @type {{ security: unknown; secrets: unknown; sound: unknown; notification: unknown }} */
+  let perPackage = { security: null, secrets: null, sound: null, notification: null };
 
-  while (true) {
-    action = await select({
-      message: `${pc.dim('Step 1/5')}  Choose an action`,
-      options: [
-        { value: 'setup', label: 'Install / update packages' },
-        { value: 'uninstall', label: 'Uninstall (remove managed hooks)' },
-        { value: 'exit', label: 'Exit' }
-      ]
-    });
-    if (isCancel(action) || action === 'exit') dieCancelled('Bye');
-
-    target = await select({
-      message: `${pc.dim('Step 2/5')}  Choose a target`,
-      options: [
-        { value: 'global', label: `Global (default): ${pc.dim('~/.claude/settings.json')}` },
-        { value: 'projectOnly', label: `Project-only: write ${pc.bold(CONFIG_FILENAME)} + print a snippet` },
-        { value: '__back__', label: 'Back' }
-      ]
-    });
-    if (isCancel(target)) dieCancelled();
-    if (target === '__back__') continue;
-
-    selected = await multiselect({
-      message: `${pc.dim('Step 3/5')}  Select packages`,
-      options: [
-        { value: 'security', label: '@claude-code-hooks/security', hint: 'Warn/block risky commands' },
-        { value: 'secrets', label: '@claude-code-hooks/secrets', hint: 'Detect secret-like tokens' },
-        { value: 'sound', label: '@claude-code-hooks/sound', hint: 'Play sounds for key events' },
-        { value: 'notification', label: '@claude-code-hooks/notification', hint: 'OS notifications for key events' }
-      ],
-      required: true
-    });
-    if (isCancel(selected)) dieCancelled();
+  const packageOptions = [
+    { value: 'security', label: '@claude-code-hooks/security', hint: 'Warn/block risky commands' },
+    { value: 'secrets', label: '@claude-code-hooks/secrets', hint: 'Detect secret-like tokens' },
+    { value: 'sound', label: '@claude-code-hooks/sound', hint: 'Play sounds for key events' },
+    { value: 'notification', label: '@claude-code-hooks/notification', hint: 'OS notifications for key events' }
+  ];
 
-    const proceed = await confirm({ message: 'Configure these packages now?', initialValue: true });
-    if (isCancel(proceed)) dieCancelled();
-    if (!proceed) continue;
+  while (true) {
+    if (step === 1) {
+      action = await select({
+        message: `${pc.dim('Step 1/5')}  Choose an action`,
+        options: [
+          { value: 'setup', label: 'Install / update packages' },
+          { value: 'uninstall', label: 'Uninstall (remove managed hooks)' },
+          { value: 'exit', label: 'Exit' }
+        ]
+      });
+      if (isCancel(action) || action === 'exit') dieCancelled('Bye');
+      step = 2;
+    }
+
+    if (step === 2) {
+      const targetCtrl = new AbortController();
+      const { result: targetResult, wentBack: targetBack } = await withBackspaceBack(targetCtrl, () =>
+        select({
+          message: `${pc.dim('Step 2/5')}  Choose a target`,
+          options: [
+            { value: 'global', label: `Global (default): ${pc.dim('~/.claude/settings.json')}` },
+            { value: 'projectOnly', label: `Project-only: write ${pc.bold(CONFIG_FILENAME)} + print a snippet` }
+          ],
+          signal: targetCtrl.signal
+        })
+      );
+      if (targetBack) {
+        step = 1;
+        continue;
+      }
+      if (isCancel(targetResult)) dieCancelled();
+      target = targetResult;
+      step = 3;
+    }
+
+    if (step === 3) {
+      const pkgsCtrl = new AbortController();
+      const { result: pkgsResult, wentBack: pkgsBack } = await withBackspaceBack(pkgsCtrl, () =>
+        multiselect({
+          message: `${pc.dim('Step 3/5')}  Select packages`,
+          options: packageOptions,
+          required: true,
+          signal: pkgsCtrl.signal
+        })
+      );
+      if (pkgsBack) {
+        step = 2;
+        continue;
+      }
+      if (isCancel(pkgsResult)) dieCancelled();
+      selected = pkgsResult;
+      step = 4;
+    }
+
+    if (step === 4) {
+      const proceedCtrl = new AbortController();
+      const { result: proceedResult, wentBack: proceedBack } = await withBackspaceBack(proceedCtrl, () =>
+        confirm({ message: 'Configure these packages now?', initialValue: true, signal: proceedCtrl.signal })
+      );
+      if (proceedBack) {
+        step = 3;
+        continue;
+      }
+      if (isCancel(proceedResult)) dieCancelled();
+      if (!proceedResult) {
+        step = 2;
+        continue;
+      }
+      step = 5;
+    }
+
+    if (step !== 5) continue;
+
+    // Build per-package plan/config
+    perPackage = { security: null, secrets: null, sound: null, notification: null };
+
+    const packageDescs = {
+      security: 'Warn/block risky commands',
+      secrets: 'Detect secret-like tokens',
+      sound: 'Play sounds for key events',
+      notification: 'OS notifications for key events'
+    };
+
+    const formatPackageList = (/** @type {string | null} */ highlightKey) =>
+      selected
+        .map(
+          (k) => {
+            const desc = pc.dim(packageDescs[k] || '');
+            const label = highlightKey === k ? pc.cyan(pc.bold(k)) : pc.bold(k);
+            return `${label}: ${desc}`;
+          }
+        )
+        .join('\n');
+
+    // ── Step 4/5: configure (highlight current package) ──
+    if (selected.includes('security')) {
+      note(formatPackageList('security'), `${pc.dim('Step 4/5')}  Configure packages`);
+      perPackage.security = await planSecuritySetup({ action, projectDir, ui: 'umbrella' });
+    }
+    if (selected.includes('secrets')) {
+      note(formatPackageList('secrets'), `${pc.dim('Step 4/5')}  Configure packages`);
+      perPackage.secrets = await planSecretsSetup({ action, projectDir, ui: 'umbrella' });
+    }
+    if (selected.includes('sound')) {
+      note(formatPackageList('sound'), `${pc.dim('Step 4/5')}  Configure packages`);
+      perPackage.sound = await planSoundSetup({ action, projectDir, ui: 'umbrella' });
+    }
+    if (selected.includes('notification')) {
+      note(formatPackageList('notification'), `${pc.dim('Step 4/5')}  Configure packages`);
+      perPackage.notification = await planNotificationSetup({ action, projectDir, ui: 'umbrella' });
+    }
+
+    // ── Step 5/5: review ──
+    const files = [];
+    if (target === 'global') files.push(configPathForScope('global', projectDir));
+    if (target === 'projectOnly') {
+      files.push(path.join(projectDir, CONFIG_FILENAME));
+      files.push(path.join(projectDir, 'claude-code-hooks.snippet.json (optional)'));
+    }
+
+    function summarizePlan(key, plan) {
+      if (!plan) return `${key}: (skipped)`;
+      if (action === 'uninstall') return `${key}: remove managed hooks`;
+
+      const events = plan.snippetHooks ? Object.keys(plan.snippetHooks) : [];
+      const list = events.slice(0, 5);
+      const tail = events.length > 5 ? ` +${events.length - 5} more` : '';
+      return `${key}: ${events.length} event(s)${events.length ? ` (${list.join(', ')}${tail})` : ''}`;
+    }
+
+    note(
+      [
+        `${pc.dim('Step 5/5')}  Review`,
+        '',
+        `Action: ${pc.bold(action)}`,
+        `Target: ${pc.bold(target === 'global' ? 'global settings' : 'project-only')}`,
+        '',
+        `${pc.bold('Packages')}`,
+        ...selected.map((k) => `  - ${summarizePlan(k, perPackage[k])}`),
+        '',
+        `${pc.bold('Files')}`,
+        ...files.map((f) => `  - ${f}`)
+      ].join('\n'),
+      'Review'
+    );
+
+    const applyCtrl = new AbortController();
+    const { result: applyResult, wentBack: applyBack } = await withBackspaceBack(applyCtrl, () =>
+      select({
+        message: 'Apply changes?',
+        options: [
+          { value: 'yes', label: 'Yes, apply' },
+          { value: 'cancel', label: 'Cancel (exit)' }
+        ],
+        signal: applyCtrl.signal
+      })
+    );
+    if (applyBack) {
+      step = 3;
+      continue;
+    }
+    if (isCancel(applyResult) || applyResult === 'cancel') dieCancelled('No changes made');
 
     break;
   }
 
-  // Build per-package plan/config
-  const perPackage = { security: null, secrets: null, sound: null, notification: null };
-
-  // ── Step 4/5: configure ──
-  note(
-    selected
-      .map(
-        (k) =>
-          `${pc.bold(k)}: ${pc.dim(
-            {
-              security: 'Warn/block risky commands',
-              secrets: 'Detect secret-like tokens',
-              sound: 'Play sounds for key events',
-              notification: 'OS notifications for key events'
-            }[k] || ''
-          )}`
-      )
-      .join('\n'),
-    `${pc.dim('Step 4/5')}  Configure packages`
-  );
-
-  if (selected.includes('security')) perPackage.security = await planSecuritySetup({ action, projectDir, ui: 'umbrella' });
-  if (selected.includes('secrets')) perPackage.secrets = await planSecretsSetup({ action, projectDir, ui: 'umbrella' });
-  if (selected.includes('sound')) perPackage.sound = await planSoundSetup({ action, projectDir, ui: 'umbrella' });
-  if (selected.includes('notification')) perPackage.notification = await planNotificationSetup({ action, projectDir, ui: 'umbrella' });
-
-  // ── Step 5/5: review ──
-  const files = [];
-  if (target === 'global') files.push(configPathForScope('global', projectDir));
-  if (target === 'projectOnly') {
-    files.push(path.join(projectDir, CONFIG_FILENAME));
-    files.push(path.join(projectDir, 'claude-code-hooks.snippet.json (optional)'));
-  }
-
-  function summarizePlan(key, plan) {
-    if (!plan) return `${key}: (skipped)`;
-    if (action === 'uninstall') return `${key}: remove managed hooks`;
-
-    const events = plan.snippetHooks ? Object.keys(plan.snippetHooks) : [];
-    const list = events.slice(0, 5);
-    const tail = events.length > 5 ? ` +${events.length - 5} more` : '';
-    return `${key}: ${events.length} event(s)${events.length ? ` (${list.join(', ')}${tail})` : ''}`;
-  }
-
-  note(
-    [
-      `${pc.dim('Step 5/5')}  Review`,
-      '',
-      `Action: ${pc.bold(action)}`,
-      `Target: ${pc.bold(target === 'global' ? 'global settings' : 'project-only')}`,
-      '',
-      `${pc.bold('Packages')}`,
-      ...selected.map((k) => `  - ${summarizePlan(k, perPackage[k])}`),
-      '',
-      `${pc.bold('Files')}`,
-      ...files.map((f) => `  - ${f}`)
-    ].join('\n'),
-    'Review'
-  );
-
-  const ok = await confirm({ message: 'Apply changes?', initialValue: true });
-  if (isCancel(ok) || !ok) dieCancelled('No changes made');
-
   if (target === 'projectOnly') {
     // Write project config
     const s = spinner();
@@ -247,6 +351,9 @@ async function main() {
     settings = await plan.applyToSettings(settings);
   }
 
+  // Remove legacy claude-sound hooks (from old standalone package) to avoid duplicates
+  settings = removeLegacyClaudeSoundHooks(settings);
+
   await writeJson(settingsPath, settings);
 
   // Update project config only on setup.