thanh-kit 2.5.0

package/templates/hooks/post-task-review.cjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * Post-Task Review Hook
+ *
+ * Enforces mandatory two-pass code review after any code changes.
+ * Triggered after Edit/Write operations to remind the agent about review protocol.
+ *
+ * Two-Pass Review Protocol:
+ * 1. First Pass: Review unstaged changes for correctness and convention compliance
+ * 2. Second Pass: If first pass made corrections, re-review all changes
+ *
+ * Exit Codes:
+ *   0 - Success (non-blocking, outputs reminder)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Track review state per session
+const STATE_FILE = path.join(process.cwd(), '.claude', '.review-state.json');
+
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      return JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+    }
+  } catch (e) {
+    // Ignore errors, return fresh state
+  }
+  return { editCount: 0, lastReviewAt: 0, reviewPassNumber: 0 };
+}
+
+function saveState(state) {
+  try {
+    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+  } catch (e) {
+    // Ignore write errors
+  }
+}
+
+function getUnstagedChanges() {
+  try {
+    const diff = execSync('git diff --stat 2>/dev/null || echo ""', {
+      encoding: 'utf-8',
+      timeout: 5000
+    }).trim();
+    return diff;
+  } catch (e) {
+    return '';
+  }
+}
+
+function hasUnstagedChanges() {
+  try {
+    const status = execSync('git status --porcelain 2>/dev/null || echo ""', {
+      encoding: 'utf-8',
+      timeout: 5000
+    }).trim();
+    // Check for modified files (not just untracked)
+    return status.split('\n').some(line =>
+      line.startsWith(' M') || line.startsWith('M ') || line.startsWith('MM') ||
+      line.startsWith(' A') || line.startsWith('A ') || line.startsWith('AM')
+    );
+  } catch (e) {
+    return false;
+  }
+}
+
+function buildReviewReminder(state, hasChanges) {
+  if (!hasChanges) {
+    return ''; // No changes to review
+  }
+
+  const lines = [];
+
+  // Only remind every N edits to avoid spam
+  const EDIT_THRESHOLD = 3;
+
+  if (state.editCount >= EDIT_THRESHOLD) {
+    lines.push('');
+    lines.push('## Post-Task Review Protocol Reminder');
+    lines.push('');
+    lines.push('**MANDATORY:** Before completing this task, execute the two-pass review:');
+    lines.push('');
+    lines.push('### Pass 1: Initial Review');
+    lines.push('1. Run `git diff` to check unstaged changes');
+    lines.push('2. Verify changes are valid and correct for the task');
+    lines.push('3. Ensure code follows project conventions and best practices');
+    lines.push('4. Check for security vulnerabilities and edge cases');
+    lines.push('');
+    lines.push('### Pass 2: Re-Review (Conditional)');
+    lines.push('IF Pass 1 resulted in any corrections or changes:');
+    lines.push('1. Run `git diff` again to verify all changes');
+    lines.push('2. Perform full code review on updated code');
+    lines.push('3. Ensure corrections didn\'t introduce new issues');
+    lines.push('');
+    lines.push('**Execute:** `/review:post-task` or use `code-reviewer` subagent');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+async function main() {
+  try {
+    const stdin = fs.readFileSync(0, 'utf-8').trim();
+    if (!stdin) process.exit(0);
+
+    const payload = JSON.parse(stdin);
+    const toolName = payload.tool_name || '';
+
+    // Only trigger for code modification tools
+    if (!['Edit', 'Write', 'MultiEdit'].includes(toolName)) {
+      process.exit(0);
+    }
+
+    // Check if tool was successful
+    if (payload.tool_result?.error) {
+      process.exit(0); // Don't remind on failed edits
+    }
+
+    const state = loadState();
+    state.editCount++;
+
+    const hasChanges = hasUnstagedChanges();
+    const reminder = buildReviewReminder(state, hasChanges);
+
+    if (reminder) {
+      console.log(reminder);
+      state.lastReviewAt = Date.now();
+    }
+
+    saveState(state);
+    process.exit(0);
+  } catch (error) {
+    // Non-blocking - always exit 0
+    process.exit(0);
+  }
+}
+
+main();

package/templates/hooks/privacy-block.cjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+/**
+ * privacy-block.cjs - Block access to sensitive files unless user-approved
+ *
+ * PRIVACY-based blocking (separate from SIZE-based scout-block)
+ * Blocks sensitive files. LLM must get user approval and use APPROVED: prefix.
+ *
+ * Flow:
+ * 1. LLM tries: Read ".env" → BLOCKED
+ * 2. LLM asks user for permission
+ * 3. User approves
+ * 4. LLM retries: Read "APPROVED:.env" → ALLOWED
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const APPROVED_PREFIX = 'APPROVED:';
+
+// Safe file patterns - exempt from privacy checks (documentation/template files)
+const SAFE_PATTERNS = [
+  /\.example$/i,   // .env.example, config.example
+  /\.sample$/i,    // .env.sample
+  /\.template$/i,  // .env.template
+];
+
+// Privacy-sensitive patterns
+const PRIVACY_PATTERNS = [
+  /^\.env$/,              // .env
+  /^\.env\./,             // .env.local, .env.production, etc.
+  /\.env$/,               // path/to/.env
+  /\/\.env\./,            // path/to/.env.local
+  /credentials/i,         // credentials.json, etc.
+  /secrets?\.ya?ml$/i,    // secrets.yaml, secret.yml
+  /\.pem$/,               // Private keys
+  /\.key$/,               // Private keys
+  /id_rsa/,               // SSH keys
+  /id_ed25519/,           // SSH keys
+];
+
+/**
+ * Load .ck.json config to check if privacy block is disabled
+ * @returns {boolean} true if privacy block should be skipped
+ */
+function isPrivacyBlockDisabled() {
+  try {
+    const configPath = path.join(process.cwd(), '.claude', '.ck.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return config.privacyBlock === false;
+  } catch {
+    return false; // Default to enabled on error (file not found or invalid JSON)
+  }
+}
+
+/**
+ * Check if path is a safe file (example/sample/template)
+ * @param {string} testPath - Path to check
+ * @returns {boolean} true if file matches safe patterns
+ */
+function isSafeFile(testPath) {
+  if (!testPath) return false;
+  const basename = path.basename(testPath);
+  return SAFE_PATTERNS.some(p => p.test(basename));
+}
+
+/**
+ * Check if path has APPROVED: prefix
+ * @param {string} testPath - Path to check
+ * @returns {boolean} true if path starts with APPROVED:
+ */
+function hasApprovalPrefix(testPath) {
+  return testPath && testPath.startsWith(APPROVED_PREFIX);
+}
+
+/**
+ * Strip APPROVED: prefix from path, warn on suspicious paths
+ * @param {string} testPath - Path to process
+ * @returns {string} Path without APPROVED: prefix
+ */
+function stripApprovalPrefix(testPath) {
+  if (hasApprovalPrefix(testPath)) {
+    const stripped = testPath.slice(APPROVED_PREFIX.length);
+
+    // Warn on suspicious paths (path traversal or absolute)
+    if (stripped.includes('..') || path.isAbsolute(stripped)) {
+      console.error('\x1b[33mWARN:\x1b[0m Approved path is outside project:', stripped);
+    }
+
+    return stripped;
+  }
+  return testPath;
+}
+
+/**
+ * Check if path matches privacy patterns
+ * @param {string} testPath - Path to check
+ * @returns {boolean} true if path matches privacy-sensitive patterns
+ */
+function isPrivacySensitive(testPath) {
+  if (!testPath) return false;
+
+  // Strip prefix for pattern matching
+  const cleanPath = stripApprovalPrefix(testPath);
+  let normalized = cleanPath.replace(/\\/g, '/');
+
+  // Decode URI components to catch obfuscated paths (%2e = '.')
+  try {
+    normalized = decodeURIComponent(normalized);
+  } catch (e) {
+    // Invalid encoding, use as-is
+  }
+
+  // Check safe patterns first - exempt example/sample/template files
+  if (isSafeFile(normalized)) {
+    return false;
+  }
+
+  const basename = path.basename(normalized);
+
+  for (const pattern of PRIVACY_PATTERNS) {
+    if (pattern.test(basename) || pattern.test(normalized)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Extract paths from tool input
+ * @param {Object} toolInput - Tool input object with file_path, path, pattern, or command
+ * @returns {Array<{value: string, field: string}>} Array of extracted paths with field names
+ */
+function extractPaths(toolInput) {
+  const paths = [];
+  if (!toolInput) return paths;
+
+  if (toolInput.file_path) paths.push({ value: toolInput.file_path, field: 'file_path' });
+  if (toolInput.path) paths.push({ value: toolInput.path, field: 'path' });
+  if (toolInput.pattern) paths.push({ value: toolInput.pattern, field: 'pattern' });
+
+  // Check bash commands for file paths
+  if (toolInput.command) {
+    // Look for APPROVED:.env or .env patterns
+    const approvedMatch = toolInput.command.match(/APPROVED:[^\s]+/g) || [];
+    approvedMatch.forEach(p => paths.push({ value: p, field: 'command' }));
+
+    // Only look for .env if no APPROVED: version found
+    if (approvedMatch.length === 0) {
+      const envMatch = toolInput.command.match(/\.env[^\s]*/g) || [];
+      envMatch.forEach(p => paths.push({ value: p, field: 'command' }));
+
+      // Also check bash variable assignments (FILE=.env, ENV_FILE=.env.local)
+      const varAssignments = toolInput.command.match(/\w+=[^\s]*\.env[^\s]*/g) || [];
+      varAssignments.forEach(a => {
+        const value = a.split('=')[1];
+        if (value) paths.push({ value, field: 'command' });
+      });
+
+      // Check command substitution containing sensitive patterns - extract .env from inside
+      const cmdSubst = toolInput.command.match(/\$\([^)]*?(\.env[^\s)]*)[^)]*\)/g) || [];
+      for (const subst of cmdSubst) {
+        const inner = subst.match(/\.env[^\s)]*/);
+        if (inner) paths.push({ value: inner[0], field: 'command' });
+      }
+    }
+  }
+
+  return paths.filter(p => p.value);
+}
+
+/**
+ * Format block message with approval instructions
+ * @param {string} filePath - Blocked file path
+ * @returns {string} Formatted block message
+ */
+function formatBlockMessage(filePath) {
+  const basename = path.basename(filePath);
+  return `
+\x1b[36mNOTE:\x1b[0m This is not an error - this block protects sensitive data.
+
+\x1b[33mPRIVACY BLOCK\x1b[0m: Sensitive file access requires user approval
+
+  \x1b[33mFile:\x1b[0m ${filePath}
+
+  This file may contain secrets (API keys, passwords, tokens).
+
+  \x1b[34mAction required:\x1b[0m
+  Ask user: "I need to read ${basename} which may contain sensitive data. Approve?"
+
+  \x1b[32mIf YES:\x1b[0m Retry with prefix: APPROVED:${filePath}
+  \x1b[31mIf NO:\x1b[0m  Do NOT retry. Continue without this file.
+`;
+}
+
+/**
+ * Format approval notice
+ * @param {string} filePath - Approved file path
+ * @returns {string} Formatted approval notice
+ */
+function formatApprovalNotice(filePath) {
+  return `\x1b[32m✓\x1b[0m Privacy: User-approved access to ${path.basename(filePath)}`;
+}
+
+// Main
+async function main() {
+  // Check if privacy block is disabled via .ck.json
+  if (isPrivacyBlockDisabled()) {
+    process.exit(0); // Disabled, allow all
+  }
+
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let hookData;
+  try {
+    hookData = JSON.parse(input);
+  } catch (e) {
+    process.exit(0); // Invalid JSON, allow
+  }
+
+  const { tool_input: toolInput } = hookData;
+  const paths = extractPaths(toolInput);
+
+  // Check each path
+  for (const { value: testPath } of paths) {
+    if (!isPrivacySensitive(testPath)) continue;
+
+    // Check for approval prefix
+    if (hasApprovalPrefix(testPath)) {
+      // User approved - allow with notice
+      console.error(formatApprovalNotice(testPath));
+      continue; // Check other paths
+    }
+
+    // No approval - block
+    console.error(formatBlockMessage(testPath));
+    process.exit(2); // Block
+  }
+
+  process.exit(0); // Allow
+}
+
+main().catch(() => process.exit(0));
+
+// Export functions for unit testing
+if (typeof module !== 'undefined') {
+  module.exports = {
+    isSafeFile,
+    isPrivacyBlockDisabled,
+    isPrivacySensitive,
+    hasApprovalPrefix,
+    stripApprovalPrefix,
+    extractPaths,
+  };
+}

package/templates/hooks/scout-block/broad-pattern-detector.cjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * broad-pattern-detector.cjs - Detect overly broad glob patterns
+ *
+ * Prevents LLMs from filling context by using patterns like "all files"
+ * at project root, which returns ALL files of a type.
+ *
+ * Detection Strategy:
+ * 1. Pattern breadth: recursive glob at start = recursive everywhere
+ * 2. Path depth: Root or shallow paths are high-risk
+ * 3. Combined: Broad pattern + high-level path = BLOCK
+ */
+
+const path = require('path');
+
+// Patterns that recursively match everywhere when at root
+// These are dangerous because they return ALL matching files
+const BROAD_PATTERN_REGEXES = [
+  // ** - all files everywhere (no filter at all)
+  /^\*\*$/,
+  // * - all files in root
+  /^\*$/,
+  // **/* - all files everywhere
+  /^\*\*\/\*$/,
+  // **/. - all dotfiles everywhere
+  /^\*\*\/\.\*$/,
+  // **/*.ext - all files with extension (catches .ts, .py, .java, etc.)
+  /^\*\*\/\*\.\w+$/,
+  // **/*.{ext,ext2} - all files with multiple extensions
+  /^\*\*\/\*\.\{[^}]+\}$/,
+  // **/name.ext - all files with specific name anywhere
+  /^\*\*\/[\w-]+\.\w+$/,
+  // *.ext at root (matches all in root, but combined with deep search)
+  /^\*\.\w+$/,
+  // *.{ext,ext2} at root
+  /^\*\.\{[^}]+\}$/,
+];
+
+// Common source directories that indicate a more specific search
+const SPECIFIC_DIRS = [
+  'src', 'lib', 'app', 'apps', 'packages', 'components', 'pages',
+  'api', 'server', 'client', 'web', 'mobile', 'shared', 'common',
+  'utils', 'helpers', 'services', 'hooks', 'store', 'routes',
+  'models', 'controllers', 'views', 'tests', '__tests__', 'spec'
+];
+
+// High-risk paths (project/worktree roots)
+const HIGH_RISK_INDICATORS = [
+  // Worktree paths
+  /\/worktrees\/[^/]+\/?$/,
+  // Project roots (contain package.json, etc.)
+  /^\.?\/?$/,
+  // Shallow paths (just one directory deep)
+  /^[^/]+\/?$/
+];
+
+/**
+ * Check if a glob pattern is overly broad
+ *
+ * @param {string} pattern - The glob pattern to check
+ * @returns {boolean}
+ */
+function isBroadPattern(pattern) {
+  if (!pattern || typeof pattern !== 'string') return false;
+
+  const normalized = pattern.trim();
+
+  // Check against known broad patterns
+  for (const regex of BROAD_PATTERN_REGEXES) {
+    if (regex.test(normalized)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if pattern contains a specific subdirectory.
+ * Scoped patterns like "src/..." are OK because they target specific dirs.
+ *
+ * @param {string} pattern - The glob pattern
+ * @returns {boolean}
+ */
+function hasSpecificDirectory(pattern) {
+  if (!pattern) return false;
+
+  // Check if pattern starts with a specific directory
+  for (const dir of SPECIFIC_DIRS) {
+    if (pattern.startsWith(`${dir}/`) || pattern.startsWith(`./${dir}/`)) {
+      return true;
+    }
+  }
+
+  // Check for any non-glob directory prefix
+  // e.g., "mydir/..." has a specific directory
+  const firstSegment = pattern.split('/')[0];
+  if (firstSegment && !firstSegment.includes('*') && firstSegment !== '.') {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if the base path is at a high-level (risky) location
+ *
+ * @param {string} basePath - The path where glob will run
+ * @param {string} cwd - Current working directory
+ * @returns {boolean}
+ */
+function isHighLevelPath(basePath, cwd) {
+  // No path specified = uses CWD (often project root)
+  if (!basePath) return true;
+
+  const normalized = basePath.replace(/\\/g, '/');
+
+  // Check high-risk indicators
+  for (const regex of HIGH_RISK_INDICATORS) {
+    if (regex.test(normalized)) {
+      return true;
+    }
+  }
+
+  // Check path depth - shallow paths are higher risk
+  const segments = normalized.split('/').filter(s => s && s !== '.');
+  if (segments.length <= 1) {
+    return true;
+  }
+
+  // If path doesn't contain a specific directory, it's high-level
+  const hasSpecific = SPECIFIC_DIRS.some(dir =>
+    normalized.includes(`/${dir}/`) || normalized.includes(`/${dir}`) ||
+    normalized.startsWith(`${dir}/`) || normalized === dir
+  );
+
+  return !hasSpecific;
+}
+
+/**
+ * Generate suggestions for more specific patterns
+ *
+ * @param {string} pattern - The broad pattern
+ * @returns {string[]}
+ */
+function suggestSpecificPatterns(pattern) {
+  const suggestions = [];
+
+  // Extract the extension/file part from the pattern
+  let ext = '';
+  const extMatch = pattern.match(/\*\.(\{[^}]+\}|\w+)$/);
+  if (extMatch) {
+    ext = extMatch[1];
+  }
+
+  // Suggest common directories
+  const commonDirs = ['src', 'lib', 'app', 'components'];
+  for (const dir of commonDirs) {
+    if (ext) {
+      suggestions.push(`${dir}/**/*.${ext}`);
+    } else {
+      suggestions.push(`${dir}/**/*`);
+    }
+  }
+
+  // If it's a TypeScript pattern, add specific suggestions
+  if (pattern.includes('.ts') || pattern.includes('{ts')) {
+    suggestions.unshift('src/**/*.ts', 'src/**/*.tsx');
+  }
+
+  // If it's a JavaScript pattern
+  if (pattern.includes('.js') || pattern.includes('{js')) {
+    suggestions.unshift('src/**/*.js', 'lib/**/*.js');
+  }
+
+  return suggestions.slice(0, 4); // Return top 4 suggestions
+}
+
+/**
+ * Main detection function - check if a Glob tool call is problematic
+ *
+ * @param {Object} toolInput - The tool_input from hook JSON
+ * @param {string} toolInput.pattern - The glob pattern
+ * @param {string} [toolInput.path] - Optional base path
+ * @returns {Object} { blocked: boolean, reason?: string, suggestions?: string[] }
+ */
+function detectBroadPatternIssue(toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') {
+    return { blocked: false };
+  }
+
+  const { pattern, path: basePath } = toolInput;
+
+  // No pattern = nothing to check
+  if (!pattern) {
+    return { blocked: false };
+  }
+
+  // Pattern has a specific directory = OK
+  if (hasSpecificDirectory(pattern)) {
+    return { blocked: false };
+  }
+
+  // Check if pattern is broad
+  if (!isBroadPattern(pattern)) {
+    return { blocked: false };
+  }
+
+  // Check if path is high-level
+  if (!isHighLevelPath(basePath)) {
+    return { blocked: false };
+  }
+
+  // Broad pattern at high-level path = BLOCK
+  return {
+    blocked: true,
+    reason: `Pattern '${pattern}' is too broad for ${basePath || 'project root'}`,
+    pattern: pattern,
+    suggestions: suggestSpecificPatterns(pattern)
+  };
+}
+
+/**
+ * Format error message for broad pattern detection
+ *
+ * @param {Object} result - Result from detectBroadPatternIssue
+ * @param {string} claudeDir - Path to .claude directory
+ * @returns {string}
+ */
+function formatBroadPatternError(result, claudeDir) {
+  const { reason, pattern, suggestions } = result;
+
+  const lines = [
+    '',
+    '\x1b[36mNOTE:\x1b[0m This is not an error - this block is intentional to optimize context.',
+    '',
+    '\x1b[31mBLOCKED\x1b[0m: Overly broad glob pattern detected',
+    '',
+    `  \x1b[33mPattern:\x1b[0m  ${pattern}`,
+    `  \x1b[33mReason:\x1b[0m   Would return ALL matching files, filling context`,
+    '',
+    '  \x1b[34mUse more specific patterns:\x1b[0m',
+  ];
+
+  for (const suggestion of suggestions || []) {
+    lines.push(`    • ${suggestion}`);
+  }
+
+  lines.push('');
+  lines.push('  \x1b[2mTip: Target specific directories to avoid context overflow\x1b[0m');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  isBroadPattern,
+  hasSpecificDirectory,
+  isHighLevelPath,
+  suggestSpecificPatterns,
+  detectBroadPatternIssue,
+  formatBroadPatternError,
+  BROAD_PATTERN_REGEXES,
+  SPECIFIC_DIRS,
+  HIGH_RISK_INDICATORS
+};