start-vibing 2.0.9 → 2.0.10

package/template/.claude/hooks/SETUP.md

@@ -1,126 +1,126 @@
-# Workflow Enforcement Hooks - Setup Guide
-
-## Overview
-
-This system provides agent selection guidance by analyzing prompts and suggesting the best agent for the task. It includes a **universal hook runner** that supports multiple runtimes with automatic fallback.
-
-## Runtime Support
-
-The hooks use a universal runner (`run-hook.ts`) that automatically detects and uses the first available runtime:
-
-| Priority | Runtime    | Extension | Notes                      |
-| -------- | ---------- | --------- | -------------------------- |
-| 1        | python3    | .py       | Primary (user's preferred) |
-| 2        | python     | .py       | Fallback                   |
-| 3        | bun        | .ts       | TypeScript fallback        |
-| 4        | npx tsx    | .ts       | Final fallback             |
-
-**If no runtime is available**, the hooks return a safe default (approve/continue) to avoid blocking the user.
-
-## Files
-
-| File                      | Purpose                                                 |
-| ------------------------- | ------------------------------------------------------- |
-| `run-hook.ts`             | Universal runner with runtime detection                 |
-| `run-hook.sh`             | Shell wrapper for Unix/Linux/Mac                        |
-| `run-hook.cmd`            | Batch wrapper for Windows                               |
-| `user-prompt-submit.py`   | Analyzes prompts and suggests agents (Python)           |
-| `user-prompt-submit.ts`   | Same as above (TypeScript fallback)                     |
-| `stop-validator.py`       | Validates before task completion (Python)               |
-| `stop-validator.ts`       | Same as above (TypeScript fallback)                     |
-| `check-documentation.py`  | Verifies file documentation (Python)                    |
-
-## Claude Code Configuration
-
-The hooks are configured in `.claude/settings.json`:
-
-```json
-{
-	"hooks": {
-		"UserPromptSubmit": [
-			{
-				"matcher": "",
-				"hooks": [
-					{
-						"type": "command",
-						"command": "bun .claude/hooks/run-hook.ts user-prompt-submit",
-						"timeout": 10
-					}
-				]
-			}
-		],
-		"Stop": [
-			{
-				"hooks": [
-					{
-						"type": "command",
-						"command": "bun .claude/hooks/run-hook.ts stop-validator",
-						"timeout": 30
-					}
-				]
-			}
-		]
-	}
-}
-```
-
-## How It Works
-
-1. Claude Code calls `bun .claude/hooks/run-hook.ts <hook-name>`
-2. `run-hook.ts` checks for available runtimes in priority order
-3. First available runtime executes the corresponding hook file (.py or .ts)
-4. If no runtime is available, returns safe default to avoid blocking
-
-## Environment Variables
-
-| Variable             | Default       | Description            |
-| -------------------- | ------------- | ---------------------- |
-| `CLAUDE_PROJECT_DIR` | `os.getcwd()` | Project root directory |
-
-## Troubleshooting
-
-### Hooks not executing
-
-1. Verify Bun is in PATH: `bun --version`
-2. If Python is preferred, verify: `python3 --version` or `python --version`
-3. Check `.claude/settings.json` hooks configuration
-4. Ensure hook files exist in `.claude/hooks/`
-
-### "python: not found" error
-
-This error occurs when Python is not installed or not in PATH. The universal runner will automatically fallback to TypeScript hooks run by Bun.
-
-**Solutions:**
-
-1. **Install Python** (recommended for full functionality):
-   - Windows: `winget install Python.Python.3.12` or download from python.org
-   - Linux: `apt install python3` or `dnf install python3`
-   - Mac: `brew install python3`
-
-2. **Use Bun only** (already configured):
-   - TypeScript fallback hooks are automatically used when Python is unavailable
-   - No additional setup required
-
-### Runtime detection failed
-
-If you see `[run-hook] No runtime available`:
-
-1. Ensure at least one runtime is installed: python3, python, bun, or Node.js
-2. Verify the runtime is in your system PATH
-3. For Bun: `curl -fsSL https://bun.sh/install | bash`
-4. For Node.js (npx tsx): Install from nodejs.org
-
-## Testing Hooks
-
-Test the hook runner manually:
-
-```bash
-# Test with Bun
-echo '{}' | bun .claude/hooks/run-hook.ts user-prompt-submit
-
-# Test with Python (if available)
-echo '{}' | python3 .claude/hooks/user-prompt-submit.py
-
-# Test stop-validator
-echo '{}' | bun .claude/hooks/run-hook.ts stop-validator
-```
+# Workflow Enforcement Hooks - Setup Guide
+
+## Overview
+
+This system provides agent selection guidance by analyzing prompts and suggesting the best agent for the task. It includes a **universal hook runner** that supports multiple runtimes with automatic fallback.
+
+## Runtime Support
+
+The hooks use a universal runner (`run-hook.ts`) that automatically detects and uses the first available runtime:
+
+| Priority | Runtime | Extension | Notes                      |
+| -------- | ------- | --------- | -------------------------- |
+| 1        | python3 | .py       | Primary (user's preferred) |
+| 2        | python  | .py       | Fallback                   |
+| 3        | bun     | .ts       | TypeScript fallback        |
+| 4        | npx tsx | .ts       | Final fallback             |
+
+**If no runtime is available**, the hooks return a safe default (approve/continue) to avoid blocking the user.
+
+## Files
+
+| File                     | Purpose                                       |
+| ------------------------ | --------------------------------------------- |
+| `run-hook.ts`            | Universal runner with runtime detection       |
+| `run-hook.sh`            | Shell wrapper for Unix/Linux/Mac              |
+| `run-hook.cmd`           | Batch wrapper for Windows                     |
+| `user-prompt-submit.py`  | Analyzes prompts and suggests agents (Python) |
+| `user-prompt-submit.ts`  | Same as above (TypeScript fallback)           |
+| `stop-validator.py`      | Validates before task completion (Python)     |
+| `stop-validator.ts`      | Same as above (TypeScript fallback)           |
+| `check-documentation.py` | Verifies file documentation (Python)          |
+
+## Claude Code Configuration
+
+The hooks are configured in `.claude/settings.json`:
+
+```json
+{
+	"hooks": {
+		"UserPromptSubmit": [
+			{
+				"matcher": "",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "bun .claude/hooks/run-hook.ts user-prompt-submit",
+						"timeout": 10
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "bun .claude/hooks/run-hook.ts stop-validator",
+						"timeout": 30
+					}
+				]
+			}
+		]
+	}
+}
+```
+
+## How It Works
+
+1. Claude Code calls `bun .claude/hooks/run-hook.ts <hook-name>`
+2. `run-hook.ts` checks for available runtimes in priority order
+3. First available runtime executes the corresponding hook file (.py or .ts)
+4. If no runtime is available, returns safe default to avoid blocking
+
+## Environment Variables
+
+| Variable             | Default       | Description            |
+| -------------------- | ------------- | ---------------------- |
+| `CLAUDE_PROJECT_DIR` | `os.getcwd()` | Project root directory |
+
+## Troubleshooting
+
+### Hooks not executing
+
+1. Verify Bun is in PATH: `bun --version`
+2. If Python is preferred, verify: `python3 --version` or `python --version`
+3. Check `.claude/settings.json` hooks configuration
+4. Ensure hook files exist in `.claude/hooks/`
+
+### "python: not found" error
+
+This error occurs when Python is not installed or not in PATH. The universal runner will automatically fallback to TypeScript hooks run by Bun.
+
+**Solutions:**
+
+1. **Install Python** (recommended for full functionality):
+    - Windows: `winget install Python.Python.3.12` or download from python.org
+    - Linux: `apt install python3` or `dnf install python3`
+    - Mac: `brew install python3`
+
+2. **Use Bun only** (already configured):
+    - TypeScript fallback hooks are automatically used when Python is unavailable
+    - No additional setup required
+
+### Runtime detection failed
+
+If you see `[run-hook] No runtime available`:
+
+1. Ensure at least one runtime is installed: python3, python, bun, or Node.js
+2. Verify the runtime is in your system PATH
+3. For Bun: `curl -fsSL https://bun.sh/install | bash`
+4. For Node.js (npx tsx): Install from nodejs.org
+
+## Testing Hooks
+
+Test the hook runner manually:
+
+```bash
+# Test with Bun
+echo '{}' | bun .claude/hooks/run-hook.ts user-prompt-submit
+
+# Test with Python (if available)
+echo '{}' | python3 .claude/hooks/user-prompt-submit.py
+
+# Test stop-validator
+echo '{}' | bun .claude/hooks/run-hook.ts stop-validator
+```

package/template/.claude/hooks/run-hook.ts

@@ -1,172 +1,176 @@
-#!/usr/bin/env node
-/**
- * Universal Hook Runner
- *
- * Runs hooks with multiple runtime fallbacks:
- * 1. python3 (primary - user's preferred)
- * 2. python (fallback)
- * 3. npx tsx (TypeScript execution)
- *
- * Usage: npx tsx run-hook.ts <hook-name>
- * The hook-name should be without extension (e.g., "stop-validator")
- */
-
-import { spawnSync } from 'child_process';
-import { existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-// Get hooks directory - handle both ESM and CJS contexts
-const getHooksDir = (): string => {
-  try {
-    if (typeof import.meta.url !== 'undefined') {
-      return dirname(fileURLToPath(import.meta.url));
-    }
-  } catch {
-    // Fallback for environments where import.meta is not available
-  }
-  return process.cwd();
-};
-
-const HOOKS_DIR = getHooksDir();
-
-function checkRuntime(cmd: string): boolean {
-  try {
-    const result = spawnSync(cmd, ['--version'], {
-      stdio: 'pipe',
-      shell: true,
-      timeout: 5000,
-      windowsHide: true
-    });
-    return result.status === 0;
-  } catch {
-    return false;
-  }
-}
-
-function runWithRuntime(cmd: string, args: string[], input: string): { success: boolean; output: string; error?: string } {
-  try {
-    const result = spawnSync(cmd, args, {
-      input,
-      shell: true,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: 30000,
-      windowsHide: true,
-      encoding: 'utf8'
-    });
-
-    return {
-      success: result.status === 0,
-      output: result.stdout?.toString() || '',
-      error: result.stderr?.toString() || undefined
-    };
-  } catch (err) {
-    return {
-      success: false,
-      output: '',
-      error: err instanceof Error ? err.message : 'Unknown error'
-    };
-  }
-}
-
-async function runHook(hookName: string, stdinData: string): Promise<void> {
-  const tsPath = join(HOOKS_DIR, `${hookName}.ts`);
-  const pyPath = join(HOOKS_DIR, `${hookName}.py`);
-
-  // Runtime detection order - Python FIRST, then fallbacks
-  const runtimes: Array<{ name: string; cmd: string; ext: string }> = [
-    { name: 'python3', cmd: 'python3', ext: '.py' },
-    { name: 'python', cmd: 'python', ext: '.py' },
-    { name: 'bun-ts', cmd: 'bun', ext: '.ts' },
-    { name: 'npx-tsx', cmd: 'npx tsx', ext: '.ts' }
-  ];
-
-  for (const runtime of runtimes) {
-    const hookPath = runtime.ext === '.ts' ? tsPath : pyPath;
-
-    if (!existsSync(hookPath)) {
-      continue;
-    }
-
-    if (!checkRuntime(runtime.cmd.split(' ')[0])) {
-      continue;
-    }
-
-    const result = runWithRuntime(runtime.cmd, [hookPath], stdinData);
-
-    if (result.success || !result.error?.includes('not found')) {
-      // Runtime worked (success or runtime-specific failure)
-      process.stdout.write(result.output);
-      if (result.error && !result.success) {
-        process.stderr.write(result.error);
-      }
-      process.exit(result.success ? 0 : 1);
-    }
-    // Runtime not available, try next
-  }
-
-  // No runtime available - return safe default
-  console.error(`[run-hook] No runtime available to run hook: ${hookName}`);
-  console.error('[run-hook] Please install one of: python3, python, bun, or Node.js');
-  const safeDefault = JSON.stringify({
-    decision: 'approve',
-    continue: true,
-    reason: 'Hook runtime not available, allowing by default'
-  });
-  process.stdout.write(safeDefault);
-  process.exit(0);
-}
-
-async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
-  return new Promise((resolve) => {
-    const timeout = setTimeout(() => {
-      process.stdin.destroy();
-      resolve('{}');
-    }, timeoutMs);
-
-    let data = '';
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', (chunk: string) => {
-      data += chunk;
-    });
-    process.stdin.on('end', () => {
-      clearTimeout(timeout);
-      resolve(data || '{}');
-    });
-    process.stdin.on('error', () => {
-      clearTimeout(timeout);
-      resolve('{}');
-    });
-
-    // Handle case where stdin is empty/closed immediately
-    if (process.stdin.readableEnded) {
-      clearTimeout(timeout);
-      resolve('{}');
-    }
-  });
-}
-
-// Main
-async function main(): Promise<void> {
-  const hookName = process.argv[2];
-  if (!hookName) {
-    console.error('Usage: bun run-hook.ts <hook-name>');
-    process.exit(1);
-  }
-
-  // Read stdin with timeout to avoid hanging
-  const stdinData = await readStdinWithTimeout(2000);
-  await runHook(hookName, stdinData);
-}
-
-main().catch((err) => {
-  console.error('[run-hook] Fatal error:', err);
-  // Return safe default on error
-  const safeDefault = JSON.stringify({
-    decision: 'approve',
-    continue: true,
-    reason: 'Hook runner error, allowing by default'
-  });
-  process.stdout.write(safeDefault);
-  process.exit(0);
-});
+#!/usr/bin/env node
+/**
+ * Universal Hook Runner
+ *
+ * Runs hooks with multiple runtime fallbacks:
+ * 1. python3 (primary - user's preferred)
+ * 2. python (fallback)
+ * 3. npx tsx (TypeScript execution)
+ *
+ * Usage: npx tsx run-hook.ts <hook-name>
+ * The hook-name should be without extension (e.g., "stop-validator")
+ */
+
+import { spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// Get hooks directory - handle both ESM and CJS contexts
+const getHooksDir = (): string => {
+	try {
+		if (typeof import.meta.url !== 'undefined') {
+			return dirname(fileURLToPath(import.meta.url));
+		}
+	} catch {
+		// Fallback for environments where import.meta is not available
+	}
+	return process.cwd();
+};
+
+const HOOKS_DIR = getHooksDir();
+
+function checkRuntime(cmd: string): boolean {
+	try {
+		const result = spawnSync(cmd, ['--version'], {
+			stdio: 'pipe',
+			shell: true,
+			timeout: 5000,
+			windowsHide: true,
+		});
+		return result.status === 0;
+	} catch {
+		return false;
+	}
+}
+
+function runWithRuntime(
+	cmd: string,
+	args: string[],
+	input: string
+): { success: boolean; output: string; error?: string } {
+	try {
+		const result = spawnSync(cmd, args, {
+			input,
+			shell: true,
+			stdio: ['pipe', 'pipe', 'pipe'],
+			timeout: 30000,
+			windowsHide: true,
+			encoding: 'utf8',
+		});
+
+		return {
+			success: result.status === 0,
+			output: result.stdout?.toString() || '',
+			error: result.stderr?.toString() || undefined,
+		};
+	} catch (err) {
+		return {
+			success: false,
+			output: '',
+			error: err instanceof Error ? err.message : 'Unknown error',
+		};
+	}
+}
+
+async function runHook(hookName: string, stdinData: string): Promise<void> {
+	const tsPath = join(HOOKS_DIR, `${hookName}.ts`);
+	const pyPath = join(HOOKS_DIR, `${hookName}.py`);
+
+	// Runtime detection order - Python FIRST, then fallbacks
+	const runtimes: Array<{ name: string; cmd: string; ext: string }> = [
+		{ name: 'python3', cmd: 'python3', ext: '.py' },
+		{ name: 'python', cmd: 'python', ext: '.py' },
+		{ name: 'bun-ts', cmd: 'bun', ext: '.ts' },
+		{ name: 'npx-tsx', cmd: 'npx tsx', ext: '.ts' },
+	];
+
+	for (const runtime of runtimes) {
+		const hookPath = runtime.ext === '.ts' ? tsPath : pyPath;
+
+		if (!existsSync(hookPath)) {
+			continue;
+		}
+
+		if (!checkRuntime(runtime.cmd.split(' ')[0])) {
+			continue;
+		}
+
+		const result = runWithRuntime(runtime.cmd, [hookPath], stdinData);
+
+		if (result.success || !result.error?.includes('not found')) {
+			// Runtime worked (success or runtime-specific failure)
+			process.stdout.write(result.output);
+			if (result.error && !result.success) {
+				process.stderr.write(result.error);
+			}
+			process.exit(result.success ? 0 : 1);
+		}
+		// Runtime not available, try next
+	}
+
+	// No runtime available - return safe default
+	console.error(`[run-hook] No runtime available to run hook: ${hookName}`);
+	console.error('[run-hook] Please install one of: python3, python, bun, or Node.js');
+	const safeDefault = JSON.stringify({
+		decision: 'approve',
+		continue: true,
+		reason: 'Hook runtime not available, allowing by default',
+	});
+	process.stdout.write(safeDefault);
+	process.exit(0);
+}
+
+async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
+	return new Promise((resolve) => {
+		const timeout = setTimeout(() => {
+			process.stdin.destroy();
+			resolve('{}');
+		}, timeoutMs);
+
+		let data = '';
+		process.stdin.setEncoding('utf8');
+		process.stdin.on('data', (chunk: string) => {
+			data += chunk;
+		});
+		process.stdin.on('end', () => {
+			clearTimeout(timeout);
+			resolve(data || '{}');
+		});
+		process.stdin.on('error', () => {
+			clearTimeout(timeout);
+			resolve('{}');
+		});
+
+		// Handle case where stdin is empty/closed immediately
+		if (process.stdin.readableEnded) {
+			clearTimeout(timeout);
+			resolve('{}');
+		}
+	});
+}
+
+// Main
+async function main(): Promise<void> {
+	const hookName = process.argv[2];
+	if (!hookName) {
+		console.error('Usage: bun run-hook.ts <hook-name>');
+		process.exit(1);
+	}
+
+	// Read stdin with timeout to avoid hanging
+	const stdinData = await readStdinWithTimeout(2000);
+	await runHook(hookName, stdinData);
+}
+
+main().catch((err) => {
+	console.error('[run-hook] Fatal error:', err);
+	// Return safe default on error
+	const safeDefault = JSON.stringify({
+		decision: 'approve',
+		continue: true,
+		reason: 'Hook runner error, allowing by default',
+	});
+	process.stdout.write(safeDefault);
+	process.exit(0);
+});