start-vibing 2.0.19 → 2.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "2.0.19",
+	"version": "2.0.21",
 	"description": "Setup Claude Code agents, skills, and hooks in your project. Smart copy that preserves your custom domains and configurations.",
 	"type": "module",
 	"bin": {

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

@@ -3,9 +3,13 @@
  * Universal Hook Runner
  *
  * Runs hooks with multiple runtime fallbacks:
- * 1. python3 (primary - user's preferred)
- * 2. python (fallback)
- * 3. npx tsx (TypeScript execution)
+ * 1. bun (primary - fastest TypeScript execution)
+ * 2. npx tsx (TypeScript fallback)
+ * 3. python3 (Python fallback)
+ * 4. python (Python fallback)
+ *
+ * IMPORTANT: TypeScript files are the source of truth.
+ * Python files are only for environments without Node.js/Bun.
  *
  * Usage: npx tsx run-hook.ts <hook-name>
  * The hook-name should be without extension (e.g., "stop-validator")
@@ -96,11 +100,10 @@ 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
+	// Runtime detection order - TypeScript ONLY (source of truth)
+	// Python files are deprecated and should be removed
 	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: 'bun', cmd: 'bun', ext: '.ts' },
 		{ name: 'npx-tsx', cmd: 'npx tsx', ext: '.ts' },
 	];
 
@@ -130,7 +133,7 @@ async function runHook(hookName: string, stdinData: string): Promise<void> {
 
 	// 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');
+	console.error('[run-hook] Please install bun or Node.js (for npx tsx)');
 	const safeDefault = JSON.stringify({
 		decision: 'approve',
 		continue: true,
@@ -171,17 +174,22 @@ async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
 
 // Main
 async function main(): Promise<void> {
+	// Log hook invocation for debugging (writes to stderr so it doesn't affect JSON output)
+	const hookName = process.argv[2];
+	const timestamp = new Date().toISOString();
+	console.error(`[run-hook] ${timestamp} - Hook invoked: ${hookName || 'none'}`);
+
 	// Clean up deprecated files on every hook run
 	cleanupDeprecatedFiles();
 
-	const hookName = process.argv[2];
 	if (!hookName) {
-		console.error('Usage: bun run-hook.ts <hook-name>');
+		console.error('[run-hook] Usage: bun run-hook.ts <hook-name>');
 		process.exit(1);
 	}
 
 	// Read stdin with timeout to avoid hanging
 	const stdinData = await readStdinWithTimeout(2000);
+	console.error(`[run-hook] ${hookName} - stdin received, length: ${stdinData.length}`);
 	await runHook(hookName, stdinData);
 }
 

package/template/.claude/hooks/stop-validator.ts

@@ -965,11 +965,20 @@ async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
 }
 
 async function main(): Promise<void> {
+	// Debug logging - always output to stderr for visibility
+	console.error('[stop-validator] ========================================');
+	console.error('[stop-validator] Starting validation...');
+	console.error(`[stop-validator] CWD: ${process.cwd()}`);
+	console.error(`[stop-validator] PROJECT_DIR: ${PROJECT_DIR}`);
+	console.error(`[stop-validator] CLAUDE_MD exists: ${existsSync(CLAUDE_MD_PATH)}`);
+
 	let hookInput: HookInput = {};
 	try {
 		const stdin = await readStdinWithTimeout(1000);
+		console.error(`[stop-validator] stdin received: ${stdin.length} chars`);
 		if (stdin && stdin.trim()) {
 			hookInput = JSON.parse(stdin);
+			console.error(`[stop-validator] Parsed input keys: ${Object.keys(hookInput).join(', ') || 'none'}`);
 		}
 	} catch {
 		hookInput = {};
@@ -993,6 +1002,11 @@ async function main(): Promise<void> {
 	const isCleanTree = modifiedFiles.length === 0;
 
 	// Run all validations
+	console.error('[stop-validator] Running validations...');
+	console.error(`[stop-validator] Branch: ${currentBranch}, isMain: ${isMainBranch}`);
+	console.error(`[stop-validator] Modified files: ${modifiedFiles.length}`);
+	console.error(`[stop-validator] Source files: ${sourceFiles.length}`);
+
 	const errors: ValidationError[] = [];
 
 	// Validation order matters - most critical first
@@ -1036,6 +1050,11 @@ async function main(): Promise<void> {
 	// OUTPUT RESULTS
 	// ============================================================================
 
+	console.error(`[stop-validator] Validation complete. Errors found: ${errors.length}`);
+	if (errors.length > 0) {
+		console.error(`[stop-validator] Error types: ${errors.map((e) => e.type).join(', ')}`);
+	}
+
 	if (errors.length > 0) {
 		let output = `
 ################################################################################
@@ -1073,9 +1092,10 @@ Before completing, ask yourself:
 Update CLAUDE.md with any learnings from this session.
 `;
 
+		// IMPORTANT: For blocking, output to STDERR and exit with code 2
 		const result: HookResult = { decision: 'block', reason: output.trim() };
-		console.log(JSON.stringify(result));
-		process.exit(0);
+		console.error(JSON.stringify(result));
+		process.exit(2); // Exit code 2 = block and show to Claude
 	}
 
 	// All validations passed

package/template/.claude/hooks/check-documentation.py

@@ -1,268 +0,0 @@
-#!/usr/bin/env python3
-"""
-Check Documentation Hook
-
-Verifies that all modified files are properly documented.
-Runs regex search across documentation to ensure file mentions.
-
-IGNORE PATTERNS:
-- .next/
-- node_modules/
-- dist/
-- build/
-- coverage/
-- .git/
-- *.lock
-- *.log
-"""
-
-import json
-import sys
-import os
-import re
-from pathlib import Path
-from typing import List, Set, Tuple
-
-# Directories to ignore
-IGNORE_DIRS = {
-    '.next',
-    'node_modules',
-    'dist',
-    'build',
-    'coverage',
-    '.git',
-    '__pycache__',
-    '.turbo',
-    '.cache',
-    '.husky/_',
-    '.claude',   # System config
-    'packages'   # Monorepo packages
-}
-
-# File patterns to ignore
-IGNORE_PATTERNS = [
-    r'.*\.lock$',
-    r'.*\.log$',
-    r'.*\.map$',
-    r'.*\.min\.js$',
-    r'.*\.min\.css$',
-    r'package-lock\.json$',
-    r'bun\.lockb$',
-    r'\.DS_Store$',
-    r'Thumbs\.db$',
-]
-
-# Documentation directories to search
-DOC_DIRS = [
-    'docs',
-    '.claude/skills/codebase-knowledge/domains',
-    '.claude/skills/docs-tracker',
-]
-
-# Documentation file extensions
-DOC_EXTENSIONS = {'.md', '.mdx', '.txt', '.rst'}
-
-
-def should_ignore_file(file_path: str) -> bool:
-    """Check if file should be ignored from documentation check"""
-    path = Path(file_path)
-
-    # Check if in ignored directory
-    for part in path.parts:
-        if part in IGNORE_DIRS:
-            return True
-
-    # Check if matches ignore pattern
-    for pattern in IGNORE_PATTERNS:
-        if re.match(pattern, file_path):
-            return True
-
-    # Ignore documentation files themselves
-    if path.suffix in DOC_EXTENSIONS:
-        return True
-
-    # Ignore config files that don't need documentation
-    if path.name in {'.gitignore', '.eslintrc.json', '.prettierrc', 'tsconfig.json'}:
-        return True
-
-    return False
-
-
-def get_modified_files(project_dir: str) -> List[str]:
-    """Get list of modified files from git diff"""
-    import subprocess
-
-    try:
-        # Get files changed compared to main branch
-        result = subprocess.run(
-            ['git', 'diff', '--name-only', 'main...HEAD'],
-            cwd=project_dir,
-            capture_output=True,
-            text=True
-        )
-
-        if result.returncode != 0:
-            # Fallback: get staged + unstaged changes
-            result = subprocess.run(
-                ['git', 'diff', '--name-only', 'HEAD'],
-                cwd=project_dir,
-                capture_output=True,
-                text=True
-            )
-
-        files = [f.strip() for f in result.stdout.strip().split('\n') if f.strip()]
-
-        # Also get staged files
-        staged = subprocess.run(
-            ['git', 'diff', '--name-only', '--cached'],
-            cwd=project_dir,
-            capture_output=True,
-            text=True
-        )
-        staged_files = [f.strip() for f in staged.stdout.strip().split('\n') if f.strip()]
-
-        # Combine and deduplicate
-        all_files = list(set(files + staged_files))
-        return [f for f in all_files if f and not should_ignore_file(f)]
-
-    except Exception as e:
-        print(f"Error getting modified files: {e}", file=sys.stderr)
-        return []
-
-
-def search_in_docs(project_dir: str, file_path: str) -> List[str]:
-    """Search for file mentions in documentation"""
-    found_in = []
-    file_name = Path(file_path).name
-    file_stem = Path(file_path).stem
-
-    # Patterns to search for
-    patterns = [
-        re.escape(file_path),  # Full path
-        re.escape(file_name),  # Just filename
-        re.escape(file_stem),  # Filename without extension
-    ]
-
-    # Search in documentation directories
-    for doc_dir in DOC_DIRS:
-        doc_path = Path(project_dir) / doc_dir
-        if not doc_path.exists():
-            continue
-
-        for doc_file in doc_path.rglob('*'):
-            if doc_file.suffix not in DOC_EXTENSIONS:
-                continue
-            if not doc_file.is_file():
-                continue
-
-            try:
-                content = doc_file.read_text(encoding='utf-8', errors='ignore')
-                for pattern in patterns:
-                    if re.search(pattern, content, re.IGNORECASE):
-                        found_in.append(str(doc_file.relative_to(project_dir)))
-                        break
-            except Exception:
-                continue
-
-    return found_in
-
-
-def check_documentation(project_dir: str) -> Tuple[List[str], List[str]]:
-    """
-    Check if modified files are documented.
-
-    Returns:
-        Tuple of (undocumented_files, documented_files)
-    """
-    modified_files = get_modified_files(project_dir)
-    undocumented = []
-    documented = []
-
-    for file_path in modified_files:
-        found_in = search_in_docs(project_dir, file_path)
-        if found_in:
-            documented.append((file_path, found_in))
-        else:
-            undocumented.append(file_path)
-
-    return undocumented, documented
-
-
-def main():
-    """Main entry point for the hook"""
-    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
-
-    # Check if this is being called from a hook (stdin has JSON) or directly
-    try:
-        hook_input = json.load(sys.stdin)
-    except (json.JSONDecodeError, Exception):
-        hook_input = {}
-
-    undocumented, documented = check_documentation(project_dir)
-
-    if undocumented:
-        # Build error message
-        error_msg = f"""
-================================================================================
-DOCUMENTATION CHECK FAILED
-================================================================================
-
-The following {len(undocumented)} file(s) have been modified but are NOT mentioned
-in any documentation:
-
-"""
-        for f in undocumented:
-            error_msg += f"  - {f}\n"
-
-        error_msg += """
-================================================================================
-ACTION REQUIRED
-================================================================================
-
-You MUST run the documenter agent to update documentation before completing:
-
-  Task(subagent_type="documenter", prompt="Update documentation for modified files")
-
-The documenter will:
-1. Detect all changed files via git diff
-2. Update relevant domain files in .claude/skills/codebase-knowledge/domains/
-3. Update docs/CHANGELOG.md (if exists)
-4. Ensure all modified files are properly documented
-
-DOCUMENTATION IS MANDATORY. This check will BLOCK task completion until all
-modified source files are mentioned in the documentation.
-
-================================================================================
-"""
-
-        # Return as blocking error
-        result = {
-            "continue": False,
-            "error": error_msg.strip()
-        }
-        print(json.dumps(result))
-        sys.exit(1)
-
-    else:
-        # All files documented
-        success_msg = f"""
-================================================================================
-DOCUMENTATION CHECK PASSED
-================================================================================
-
-All {len(documented)} modified file(s) are properly documented.
-
-"""
-        for file_path, doc_locations in documented:
-            success_msg += f"  - {file_path} -> {', '.join(doc_locations)}\n"
-
-        result = {
-            "continue": True,
-            "systemMessage": success_msg.strip()
-        }
-        print(json.dumps(result))
-        sys.exit(0)
-
-
-if __name__ == '__main__':
-    main()