start-vibing 2.0.2 → 2.0.4

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

@@ -0,0 +1,158 @@
+#!/usr/bin/env bun
+/**
+ * Universal Hook Runner
+ *
+ * Runs hooks with multiple runtime fallbacks:
+ * 1. python3 (primary - user's preferred)
+ * 2. python (fallback)
+ * 3. Bun TypeScript (fallback if Python not available)
+ * 4. npx tsx (final fallback)
+ *
+ * Usage: bun 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(() => resolve('{}'), timeoutMs);
+
+    Bun.stdin.text().then((text) => {
+      clearTimeout(timeout);
+      resolve(text || '{}');
+    }).catch(() => {
+      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);
+});

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

@@ -0,0 +1,339 @@
+#!/usr/bin/env bun
+/**
+ * Stop Validator Hook - TypeScript version (fallback when Python not available)
+ *
+ * VALIDATES:
+ * 1. NOT on main branch (unless no source changes)
+ * 2. All modified files are documented
+ * 3. Documenter agent was executed for source changes
+ *
+ * BLOCKS completion if validations fail.
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, basename, extname } from 'path';
+
+const IGNORE_DIRS = new Set([
+  '.next', 'node_modules', 'dist', 'build', 'coverage',
+  '.git', '__pycache__', '.turbo', '.cache', '.husky',
+  'packages'
+]);
+
+const IGNORE_PATTERNS = [
+  '.lock', '.log', '.map', '.min.js', '.min.css',
+  'package-lock.json', 'bun.lockb', '.DS_Store', 'Thumbs.db'
+];
+
+const DOC_EXTENSIONS = new Set(['.md', '.mdx', '.txt', '.rst']);
+
+const SOURCE_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs',
+  '.java', '.kt', '.swift', '.vue', '.svelte'
+]);
+
+const SYSTEM_CONFIG_PATTERNS = [
+  'CLAUDE.md',
+  '.claude/',
+  'PROJECT.md',
+  '.env.example',
+];
+
+function shouldIgnoreFile(filePath: string): boolean {
+  const parts = filePath.split(/[/\\]/);
+
+  for (const part of parts) {
+    if (IGNORE_DIRS.has(part)) return true;
+  }
+
+  for (const pattern of IGNORE_PATTERNS) {
+    if (filePath.includes(pattern)) return true;
+  }
+
+  return false;
+}
+
+function isSourceFile(filePath: string): boolean {
+  const ext = extname(filePath);
+  return SOURCE_EXTENSIONS.has(ext) && !shouldIgnoreFile(filePath);
+}
+
+function isSystemConfigFile(filePath: string): boolean {
+  return SYSTEM_CONFIG_PATTERNS.some(pattern => filePath.includes(pattern));
+}
+
+function getCurrentBranch(projectDir: string): string {
+  try {
+    const result = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return result.trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+function getModifiedFiles(projectDir: string): string[] {
+  try {
+    const staged = execSync('git diff --name-only --cached', {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim().split('\n').filter(Boolean);
+
+    const unstaged = execSync('git diff --name-only', {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim().split('\n').filter(Boolean);
+
+    const untracked = execSync('git ls-files --others --exclude-standard', {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim().split('\n').filter(Boolean);
+
+    return [...new Set([...staged, ...unstaged, ...untracked])].filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function* walkDir(dir: string): Generator<string> {
+  if (!existsSync(dir)) return;
+
+  const entries = readdirSync(dir);
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    try {
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        yield* walkDir(fullPath);
+      } else if (stat.isFile()) {
+        yield fullPath;
+      }
+    } catch {
+      continue;
+    }
+  }
+}
+
+function searchInDocs(projectDir: string, filePath: string): boolean {
+  const fileName = basename(filePath);
+  const fileStem = basename(filePath, extname(filePath));
+
+  const docDirs = [
+    join(projectDir, 'docs'),
+    join(projectDir, '.claude', 'skills', 'codebase-knowledge', 'domains'),
+  ];
+
+  for (const docDir of docDirs) {
+    if (!existsSync(docDir)) continue;
+
+    for (const docFile of walkDir(docDir)) {
+      const ext = extname(docFile);
+      if (!DOC_EXTENSIONS.has(ext)) continue;
+
+      try {
+        const content = readFileSync(docFile, 'utf8');
+        if (content.includes(fileName) || content.includes(fileStem) || content.includes(filePath)) {
+          return true;
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  return false;
+}
+
+function validateDocumentation(projectDir: string, modifiedFiles: string[]): { undocumented: string[], documented: string[] } {
+  const undocumented: string[] = [];
+  const documented: string[] = [];
+
+  for (const filePath of modifiedFiles) {
+    if (!isSourceFile(filePath)) continue;
+
+    if (searchInDocs(projectDir, filePath)) {
+      documented.push(filePath);
+    } else {
+      undocumented.push(filePath);
+    }
+  }
+
+  return { undocumented, documented };
+}
+
+interface HookInput {
+  stop_hook_active?: boolean;
+}
+
+interface HookResult {
+  decision: 'approve' | 'block';
+  reason: string;
+}
+
+async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => resolve('{}'), timeoutMs);
+
+    Bun.stdin.text().then((text) => {
+      clearTimeout(timeout);
+      resolve(text || '{}');
+    }).catch(() => {
+      clearTimeout(timeout);
+      resolve('{}');
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  const projectDir = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+
+  let hookInput: HookInput = {};
+  try {
+    const stdin = await readStdinWithTimeout(1000);
+    if (stdin && stdin.trim()) {
+      hookInput = JSON.parse(stdin);
+    }
+  } catch {
+    hookInput = {};
+  }
+
+  // Prevent infinite loops
+  if (hookInput.stop_hook_active) {
+    const result: HookResult = { decision: 'approve', reason: 'Stop hook cycle detected, allowing exit' };
+    console.log(JSON.stringify(result));
+    process.exit(0);
+  }
+
+  const currentBranch = getCurrentBranch(projectDir);
+  const modifiedFiles = getModifiedFiles(projectDir);
+  const sourceFiles = modifiedFiles.filter(isSourceFile);
+  const systemConfigFiles = modifiedFiles.filter(isSystemConfigFile);
+
+  const errors: Array<{ type: string; message: string }> = [];
+
+  // Check 1: ANY changes on main branch are FORBIDDEN
+  if ((currentBranch === 'main' || currentBranch === 'master') && modifiedFiles.length > 0) {
+    const fileList = modifiedFiles.slice(0, 15).map(f => `  - ${f}`).join('\n');
+    const more = modifiedFiles.length > 15 ? '\n  ... and more' : '';
+
+    errors.push({
+      type: 'DIRECT_MAIN_COMMIT',
+      message: `
+BLOCKED: Attempting to work directly on '${currentBranch}' branch!
+
+You have ${modifiedFiles.length} modified file(s):
+${fileList}${more}
+
+REQUIRED ACTION:
+1. Create a feature branch: git checkout -b feature/[name]
+2. Or fix/chore branch: git checkout -b fix/[name] or git checkout -b chore/[name]
+3. Continue your work on the new branch
+4. Create PR to merge back to main
+
+NEVER make ANY changes directly on main. ALL work must be done on branches.
+`
+    });
+  }
+
+  // Check 2: Documentation for source files
+  if (sourceFiles.length > 0) {
+    const { undocumented } = validateDocumentation(projectDir, sourceFiles);
+
+    if (undocumented.length > 0) {
+      const fileList = undocumented.slice(0, 15).map(f => `  - ${f}`).join('\n');
+      const more = undocumented.length > 15 ? '\n  ... and more' : '';
+
+      errors.push({
+        type: 'MISSING_DOCUMENTATION',
+        message: `
+BLOCKED: ${undocumented.length} source file(s) are NOT documented!
+
+Undocumented files:
+${fileList}${more}
+
+REQUIRED ACTION:
+Run the documenter agent to update documentation:
+
+  Task(subagent_type="documenter", prompt="Update documentation for all modified files")
+
+The documenter will:
+1. Detect changed files via git diff
+2. Update domain files in .claude/skills/codebase-knowledge/domains/
+3. Update docs/CHANGELOG.md
+4. Ensure all modified files are mentioned in documentation
+
+DOCUMENTATION IS MANDATORY before task completion.
+`
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    let errorOutput = `
+================================================================================
+STOP VALIDATOR - BLOCKING TASK COMPLETION
+================================================================================
+`;
+    for (const err of errors) {
+      errorOutput += `
+--- ${err.type} ---
+${err.message}
+`;
+    }
+
+    errorOutput += `
+================================================================================
+FIX THE ABOVE ISSUES BEFORE COMPLETING THE TASK
+================================================================================
+`;
+
+    const result: HookResult = { decision: 'block', reason: errorOutput.trim() };
+    console.log(JSON.stringify(result));
+    process.exit(0);
+  }
+
+  // All validations passed
+  let nextStepMessage: string;
+  if (modifiedFiles.length > 0) {
+    nextStepMessage = `
+================================================================================
+✓ ALL VALIDATIONS PASSED
+================================================================================
+
+Branch: ${currentBranch}
+Modified files: ${modifiedFiles.length} (source: ${sourceFiles.length}, config: ${systemConfigFiles.length})
+
+MANDATORY NEXT STEP:
+You MUST now commit, push, and create a PR:
+
+1. git add -A
+2. git commit with conventional commit message
+3. git push -u origin ${currentBranch}
+4. gh pr create to main branch
+
+DO NOT ask the user - just execute the commit-manager flow.
+
+================================================================================
+`;
+  } else {
+    nextStepMessage = `All validations passed. Branch: ${currentBranch}, no files modified.`;
+  }
+
+  const result: HookResult = { decision: 'approve', reason: nextStepMessage.trim() };
+  console.log(JSON.stringify(result));
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Hook error:', err);
+  // On error, allow to continue to not block user
+  const result: HookResult = { decision: 'approve', reason: 'Hook error, allowing by default' };
+  console.log(JSON.stringify(result));
+  process.exit(0);
+});