@hasna/hooks 0.0.6 → 0.1.0

package/hooks/hook-slacknotify/src/hook.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: slacknotify
+ *
+ * Stop hook that sends a Slack webhook notification when Claude Code
+ * finishes working in a project.
+ *
+ * Configuration:
+ * - Environment variable: SLACK_WEBHOOK_URL
+ * - Or ~/.claude/settings.json key: slackNotifyConfig.webhookUrl
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  hook_event_name: string;
+  transcript_path?: string;
+}
+
+interface HookOutput {
+  continue: boolean;
+}
+
+interface SlackNotifyConfig {
+  webhookUrl?: string;
+  enabled?: boolean;
+}
+
+const CONFIG_KEY = "slackNotifyConfig";
+
+function readStdinJson(): HookInput | null {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input) return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+function respond(output: HookOutput): void {
+  console.log(JSON.stringify(output));
+}
+
+function getConfig(): SlackNotifyConfig {
+  // Try global settings
+  const settingsPath = join(homedir(), ".claude", "settings.json");
+  try {
+    if (existsSync(settingsPath)) {
+      const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      if (settings[CONFIG_KEY]) {
+        return settings[CONFIG_KEY] as SlackNotifyConfig;
+      }
+    }
+  } catch {
+    // Settings file unreadable, fall through
+  }
+  return {};
+}
+
+function getWebhookUrl(): string | null {
+  // Priority 1: environment variable
+  const envUrl = process.env.SLACK_WEBHOOK_URL;
+  if (envUrl) return envUrl;
+
+  // Priority 2: settings.json config
+  const config = getConfig();
+  if (config.webhookUrl) return config.webhookUrl;
+
+  return null;
+}
+
+async function sendSlackNotification(webhookUrl: string, cwd: string): Promise<void> {
+  const projectName = cwd.split("/").filter(Boolean).pop() || cwd;
+
+  const payload = {
+    text: `Claude Code finished in ${projectName}`,
+    blocks: [
+      {
+        type: "section",
+        text: {
+          type: "mrkdwn",
+          text: `*Claude Code* finished working in \`${cwd}\``,
+        },
+      },
+    ],
+  };
+
+  try {
+    const response = await fetch(webhookUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      console.error(
+        `[hook-slacknotify] Slack webhook returned ${response.status}: ${response.statusText}`
+      );
+    }
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    console.error(`[hook-slacknotify] Failed to send Slack notification: ${errMsg}`);
+  }
+}
+
+export async function run(): Promise<void> {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond({ continue: true });
+    return;
+  }
+
+  // Check if hook is explicitly disabled
+  const config = getConfig();
+  if (config.enabled === false) {
+    respond({ continue: true });
+    return;
+  }
+
+  const webhookUrl = getWebhookUrl();
+
+  if (!webhookUrl) {
+    console.error(
+      "[hook-slacknotify] No Slack webhook URL configured. " +
+        "Set SLACK_WEBHOOK_URL env var or add slackNotifyConfig.webhookUrl to ~/.claude/settings.json"
+    );
+    respond({ continue: true });
+    return;
+  }
+
+  await sendSlackNotification(webhookUrl, input.cwd);
+  respond({ continue: true });
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-soundnotify/README.md

@@ -0,0 +1,63 @@
+# hook-soundnotify
+
+Claude Code hook that plays a sound when Claude finishes a session.
+
+## Event
+
+**Stop** — fires when Claude's session ends.
+
+## What It Does
+
+Plays a system sound to notify you that Claude has finished working. Useful when you tab away and want an audible alert.
+
+### Platform Support
+
+| Platform | Player | Default Sound |
+|----------|--------|---------------|
+| macOS | `afplay` | `/System/Library/Sounds/Glass.aiff` |
+| Linux | `paplay` / `aplay` | `/usr/share/sounds/freedesktop/stereo/complete.oga` |
+
+### Configuration
+
+Set `HOOKS_SOUND_FILE` environment variable to use a custom sound:
+
+```bash
+export HOOKS_SOUND_FILE="/path/to/your/sound.wav"
+```
+
+## Installation
+
+Add to your `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run hooks/hook-soundnotify/src/hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Output
+
+Always `{ "continue": true }` — sound plays asynchronously (fire-and-forget) and never blocks session exit.
+
+## How It Works
+
+1. Looks for a sound file (env var > platform default)
+2. Spawns the audio player as a detached child process
+3. Immediately returns without waiting for playback to finish
+4. The sound plays in the background after Claude exits
+
+## License
+
+MIT

package/hooks/hook-soundnotify/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-soundnotify",
+  "version": "0.1.0",
+  "description": "Claude Code hook that plays a sound when Claude finishes",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}

package/hooks/hook-soundnotify/src/hook.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: soundnotify
+ *
+ * Stop hook that plays a system sound when Claude finishes a session.
+ *
+ * Platform support:
+ * - macOS: afplay (built-in)
+ * - Linux: paplay (PulseAudio) or aplay (ALSA) fallback
+ *
+ * Configuration:
+ * - HOOKS_SOUND_FILE env var: path to a custom sound file
+ *
+ * Runs async (fire-and-forget) — does not block session exit.
+ * Always outputs { continue: true }.
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { spawn } from "child_process";
+import { platform } from "os";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+}
+
+interface HookOutput {
+  continue: true;
+}
+
+/**
+ * Default sound files per platform
+ */
+const DEFAULT_SOUNDS: Record<string, string> = {
+  darwin: "/System/Library/Sounds/Glass.aiff",
+  linux: "/usr/share/sounds/freedesktop/stereo/complete.oga",
+};
+
+/**
+ * Fallback sound files for Linux
+ */
+const LINUX_FALLBACK_SOUNDS: string[] = [
+  "/usr/share/sounds/freedesktop/stereo/complete.oga",
+  "/usr/share/sounds/freedesktop/stereo/bell.oga",
+  "/usr/share/sounds/freedesktop/stereo/message.oga",
+];
+
+/**
+ * Read and parse JSON from stdin
+ */
+function readStdinJson(): HookInput | null {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input) return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find an available sound file
+ */
+function findSoundFile(): string | null {
+  // Check env var first
+  const envSound = process.env.HOOKS_SOUND_FILE;
+  if (envSound && existsSync(envSound)) {
+    return envSound;
+  }
+
+  const os = platform();
+
+  if (os === "darwin") {
+    const defaultSound = DEFAULT_SOUNDS.darwin;
+    if (existsSync(defaultSound)) {
+      return defaultSound;
+    }
+    return null;
+  }
+
+  if (os === "linux") {
+    for (const sound of LINUX_FALLBACK_SOUNDS) {
+      if (existsSync(sound)) {
+        return sound;
+      }
+    }
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Get the appropriate audio player command for the current platform
+ */
+function getPlayerCommand(soundFile: string): { cmd: string; args: string[] } | null {
+  const os = platform();
+
+  if (os === "darwin") {
+    return { cmd: "afplay", args: [soundFile] };
+  }
+
+  if (os === "linux") {
+    // Prefer paplay for PulseAudio, fallback to aplay for ALSA
+    if (soundFile.endsWith(".oga") || soundFile.endsWith(".ogg")) {
+      return { cmd: "paplay", args: [soundFile] };
+    }
+    return { cmd: "aplay", args: [soundFile] };
+  }
+
+  return null;
+}
+
+/**
+ * Play the sound asynchronously (fire-and-forget)
+ */
+function playSound(soundFile: string): void {
+  const player = getPlayerCommand(soundFile);
+  if (!player) {
+    console.error(`[hook-soundnotify] No audio player available for ${platform()}`);
+    return;
+  }
+
+  try {
+    const child = spawn(player.cmd, player.args, {
+      stdio: "ignore",
+      detached: true,
+    });
+
+    // Unref so the process doesn't keep the parent alive
+    child.unref();
+
+    console.error(`[hook-soundnotify] Playing: ${soundFile}`);
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    console.error(`[hook-soundnotify] Failed to play sound: ${errMsg}`);
+  }
+}
+
+/**
+ * Output hook response
+ */
+function respond(): void {
+  const output: HookOutput = { continue: true };
+  console.log(JSON.stringify(output));
+}
+
+/**
+ * Main hook execution
+ */
+export function run(): void {
+  // Read stdin (we don't really need the input, but follow the protocol)
+  readStdinJson();
+
+  const soundFile = findSoundFile();
+
+  if (!soundFile) {
+    console.error("[hook-soundnotify] No sound file found, skipping");
+    respond();
+    return;
+  }
+
+  // Fire-and-forget — play sound async
+  playSound(soundFile);
+
+  // Always continue
+  respond();
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-taskgate/README.md

@@ -0,0 +1,62 @@
+# hook-taskgate
+
+Claude Code hook that validates task completion before allowing a task to be marked done.
+
+## Event
+
+**TaskCompleted** — fires when Claude attempts to mark a task as complete.
+
+## What It Does
+
+A lightweight gate that checks whether a task is actually done:
+
+- **Task mentions "test" or "tests"** — verifies that test files exist in the project (looks for `*.test.*`, `*.spec.*`, `test_*`, `*_test.*`, or `test/`/`tests/`/`__tests__/` directories)
+- **Task mentions "lint" or "format"** — approves (cannot verify externally)
+- **All other tasks** — approves by default
+
+This hook is designed as a starting point. Extend the validation logic in `src/hook.ts` for your own project needs.
+
+## Installation
+
+Add to your `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "TaskCompleted": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun run hooks/hook-taskgate/src/hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Output
+
+- `{ "decision": "approve" }` — task passes validation
+- `{ "decision": "block", "reason": "..." }` — task fails validation, provides reason
+
+## Extending
+
+To add custom validation, edit `src/hook.ts` and add checks in the `run()` function before the default approve. For example:
+
+```typescript
+// Block tasks mentioning "deploy" unless a deploy script exists
+if (/\bdeploy\b/.test(description)) {
+  if (!existsSync(join(cwd, "deploy.sh"))) {
+    respond({ decision: "block", reason: "No deploy.sh found" });
+    return;
+  }
+}
+```
+
+## License
+
+MIT

package/hooks/hook-taskgate/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-taskgate",
+  "version": "0.1.0",
+  "description": "Claude Code hook that validates task completion before marking done",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}

package/hooks/hook-taskgate/src/hook.ts

@@ -0,0 +1,169 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: taskgate
+ *
+ * TaskCompleted hook that validates a task is actually complete before
+ * allowing it to be marked done. Lightweight gate designed to be
+ * extended by users with custom validation logic.
+ *
+ * Current checks:
+ * - If task mentions "test" or "tests", verifies test files exist in cwd
+ * - If task mentions "lint" or "format", approves (can't verify externally)
+ * - For all other tasks, approves by default
+ */
+
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { join } from "path";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+}
+
+interface HookOutput {
+  decision: "approve" | "block";
+  reason?: string;
+}
+
+/**
+ * Read and parse JSON from stdin
+ */
+function readStdinJson(): HookInput | null {
+  try {
+    const input = readFileSync(0, "utf-8").trim();
+    if (!input) return null;
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Recursively check if any test files exist in a directory
+ * Looks for common test file patterns: *.test.*, *.spec.*, test_*, *_test.*
+ */
+function hasTestFiles(dir: string, depth: number = 0): boolean {
+  if (depth > 4) return false; // Don't recurse too deep
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const name = entry.name;
+
+      // Skip node_modules, .git, dist, build, etc.
+      if (entry.isDirectory()) {
+        if (["node_modules", ".git", "dist", "build", ".next", "coverage", "__pycache__"].includes(name)) {
+          continue;
+        }
+
+        // Check common test directories
+        if (["test", "tests", "__tests__", "spec", "specs"].includes(name)) {
+          return true;
+        }
+
+        // Recurse into subdirectories
+        if (hasTestFiles(join(dir, name), depth + 1)) {
+          return true;
+        }
+      }
+
+      // Check test file patterns
+      if (entry.isFile()) {
+        const lower = name.toLowerCase();
+        if (
+          lower.includes(".test.") ||
+          lower.includes(".spec.") ||
+          lower.startsWith("test_") ||
+          lower.endsWith("_test.py") ||
+          lower.endsWith("_test.go") ||
+          lower.endsWith("_test.ts") ||
+          lower.endsWith("_test.js")
+        ) {
+          return true;
+        }
+      }
+    }
+  } catch {
+    // Directory read failed — can't verify, so don't block
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Extract task description from tool_input
+ */
+function getTaskDescription(toolInput: Record<string, unknown>): string {
+  // Try common field names for task description
+  const candidates = [
+    toolInput.description,
+    toolInput.task,
+    toolInput.title,
+    toolInput.summary,
+    toolInput.content,
+    toolInput.text,
+  ];
+
+  for (const candidate of candidates) {
+    if (candidate && typeof candidate === "string") {
+      return candidate;
+    }
+  }
+
+  // Fallback: stringify the whole input
+  return JSON.stringify(toolInput).toLowerCase();
+}
+
+/**
+ * Output hook response
+ */
+function respond(output: HookOutput): void {
+  console.log(JSON.stringify(output));
+}
+
+/**
+ * Main hook execution
+ */
+export function run(): void {
+  const input = readStdinJson();
+
+  if (!input) {
+    respond({ decision: "approve" });
+    return;
+  }
+
+  const description = getTaskDescription(input.tool_input || {}).toLowerCase();
+  const cwd = input.cwd;
+
+  // Check: if the task mentions tests, verify test files exist
+  if (/\btests?\b/.test(description)) {
+    if (!hasTestFiles(cwd)) {
+      console.error("[hook-taskgate] Task mentions tests but no test files found in project");
+      respond({
+        decision: "block",
+        reason: "Task mentions tests but no test files were found in the project. Please create test files before marking this task as complete.",
+      });
+      return;
+    }
+    console.error("[hook-taskgate] Task mentions tests — test files found, approved");
+  }
+
+  // Check: if the task mentions lint/format, approve (can't verify externally)
+  if (/\b(lint|linting|format|formatting)\b/.test(description)) {
+    console.error("[hook-taskgate] Task mentions lint/format — approved (cannot verify externally)");
+    respond({ decision: "approve" });
+    return;
+  }
+
+  // Default: approve all other tasks
+  respond({ decision: "approve" });
+}
+
+if (import.meta.main) {
+  run();
+}

package/hooks/hook-tddguard/README.md

@@ -0,0 +1,50 @@
+# hook-tddguard
+
+Claude Code hook that enforces Test-Driven Development by blocking implementation file edits unless a corresponding test file exists.
+
+## Overview
+
+Before allowing edits to implementation files, this hook checks whether a corresponding test file exists. If no test file is found, the edit is blocked with a message to write tests first.
+
+## Event
+
+- **PreToolUse** (matcher: `Edit|Write`)
+
+## Behavior
+
+- **Test files** (`*.test.ts`, `*.spec.ts`, `*_test.py`, `test_*.py`, `*_test.go`) are always approved
+- **Config files** (`*.json`, `*.md`, `*.yml`, `*.yaml`, `*.toml`, `*.css`, `*.html`) are always approved
+- **Implementation files** are checked for a corresponding test file:
+  - Same directory: `foo.test.ts`, `foo.spec.ts`
+  - `__tests__/` subdirectory
+  - `tests/` subdirectory
+  - Python: `test_foo.py`, `foo_test.py`
+  - Go: `foo_test.go`
+- If no test file exists, the edit is **blocked**
+
+## Supported Languages
+
+| Language | Test File Patterns |
+|----------|--------------------|
+| TypeScript/JavaScript | `*.test.ts`, `*.spec.ts`, `*.test.js`, `*.spec.js` |
+| Python | `test_*.py`, `*_test.py` |
+| Go | `*_test.go` |
+| Java | `*Test.java` |
+| Ruby | `*_test.rb`, `*_spec.rb` |
+
+## Example
+
+```
+# Editing src/utils.ts without src/utils.test.ts existing:
+# → BLOCKED: "Write tests first (TDD). No test file found for utils.ts."
+
+# Editing src/utils.test.ts:
+# → APPROVED (always)
+
+# Editing src/utils.ts WITH src/utils.test.ts existing:
+# → APPROVED
+```
+
+## License
+
+MIT

package/hooks/hook-tddguard/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-tddguard",
+  "version": "0.1.0",
+  "description": "Claude Code hook that enforces TDD by blocking implementation edits without corresponding test files",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "MIT"
+}