@claude-code-hooks/cli 0.1.6 → 0.1.8

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.6",
+  "version": "0.1.8",
   "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.10",
+    "@claude-code-hooks/notification": "0.1.5"
   },
   "keywords": [
     "claude",

package/src/cli.js

@@ -24,7 +24,8 @@ import {
   CONFIG_FILENAME,
   configFilePath,
   readProjectConfig,
-  writeProjectConfig
+  writeProjectConfig,
+  removeLegacyClaudeSoundHooks
 } from '@claude-code-hooks/core';
 
 import { buildSettingsSnippet } from './snippet.js';
@@ -43,7 +44,7 @@ function dieCancelled(msg = 'Cancelled') {
 
 function usage(exitCode = 0) {
   process.stdout.write(`\
-claude-code-hooks\n\nUsage:\n  npx @claude-code-hooks/cli@latest\n\nNotes:\n  - This wizard can update your Claude Code settings (global) or generate project-only config + snippet.\n`);
+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`);
   process.exit(exitCode);
 }
 
@@ -66,7 +67,7 @@ async function ensureProjectOnlyConfig(projectDir, selected, perPackageConfig) {
 
 async function maybeWriteSnippet(projectDir, snippetObj) {
   const ok = await confirm({
-    message: `Write snippet file to ${pc.bold(path.join(projectDir, 'claude-code-hooks.snippet.json'))}?`,
+    message: `Write snippet file (${pc.bold('claude-code-hooks.snippet.json')}) to this project?`,
     initialValue: false
   });
   if (isCancel(ok)) return;
@@ -92,20 +93,20 @@ async function main() {
 
   while (true) {
     action = await select({
-      message: `${pc.dim('Step 1/5')}  Action`,
+      message: `${pc.dim('Step 1/5')}  Choose an action`,
       options: [
-        { value: 'setup', label: 'Setup / enable packages' },
-        { value: 'uninstall', label: 'Uninstall / remove managed hooks' },
+        { 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')}  Target`,
+      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 snippet` },
+        { value: 'projectOnly', label: `Project-only: write ${pc.bold(CONFIG_FILENAME)} + print a snippet` },
         { value: '__back__', label: 'Back' }
       ]
     });
@@ -113,18 +114,18 @@ async function main() {
     if (target === '__back__') continue;
 
     selected = await multiselect({
-      message: `${pc.dim('Step 3/5')}  Packages`,
+      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 on events' },
-        { value: 'notification', label: '@claude-code-hooks/notification', hint: 'OS notifications on events' }
+        { 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 proceed = await confirm({ message: 'Continue to configure selected packages?', initialValue: true });
+    const proceed = await confirm({ message: 'Configure these packages now?', initialValue: true });
     if (isCancel(proceed)) dieCancelled();
     if (!proceed) continue;
 
@@ -136,8 +137,20 @@ async function main() {
 
   // ── 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 on events', notification: 'OS notifications on events' }[k] || '')}`).join('\n'),
-    `${pc.dim('Step 4/5')}  Configure`
+    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' });
@@ -179,8 +192,8 @@ async function main() {
     'Review'
   );
 
-  const ok = await confirm({ message: 'Apply?', initialValue: true });
-  if (isCancel(ok) || !ok) dieCancelled('No changes written');
+  const ok = await confirm({ message: 'Apply changes?', initialValue: true });
+  if (isCancel(ok) || !ok) dieCancelled('No changes made');
 
   if (target === 'projectOnly') {
     // Write project config
@@ -209,7 +222,7 @@ async function main() {
 
     s.stop('Done');
 
-    note(JSON.stringify(snippetObj, null, 2), 'Paste into ~/.claude/settings.json');
+    note(JSON.stringify(snippetObj, null, 2), 'Paste into ~/.claude/settings.json (global)');
     await maybeWriteSnippet(projectDir, snippetObj);
 
     outro(`Project config written: ${pc.bold(configFilePath(projectDir))}`);
@@ -235,6 +248,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.