thanh-kit 2.5.0

package/templates/hooks/scout-block/error-formatter.cjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * error-formatter.cjs - Rich, actionable error messages for scout-block
+ *
+ * Follows CLI UX best practices: Problem + Reason + Solution
+ * Supports ANSI colors with NO_COLOR env var respect.
+ */
+
+const path = require('path');
+
+// ANSI color codes
+const COLORS = {
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  reset: '\x1b[0m'
+};
+
+/**
+ * Check if terminal supports colors
+ * Respects NO_COLOR standard and FORCE_COLOR
+ *
+ * @returns {boolean}
+ */
+function supportsColor() {
+  // Respect NO_COLOR standard (https://no-color.org/)
+  if (process.env.NO_COLOR !== undefined) return false;
+
+  // Respect FORCE_COLOR
+  if (process.env.FORCE_COLOR !== undefined) return true;
+
+  // Check if stderr is TTY (we output errors to stderr)
+  return process.stderr.isTTY || false;
+}
+
+/**
+ * Apply color to text if supported
+ *
+ * @param {string} text - Text to colorize
+ * @param {string} color - Color name from COLORS
+ * @returns {string}
+ */
+function colorize(text, color) {
+  if (!supportsColor()) return text;
+  const colorCode = COLORS[color] || '';
+  return `${colorCode}${text}${COLORS.reset}`;
+}
+
+/**
+ * Get .ckignore config path
+ *
+ * @param {string} claudeDir - Path to .claude directory
+ * @returns {string}
+ */
+function formatConfigPath(claudeDir) {
+  if (claudeDir) {
+    return path.join(claudeDir, '.ckignore');
+  }
+  return '.claude/.ckignore';
+}
+
+/**
+ * Format a blocked path error with actionable guidance
+ *
+ * Pattern: What went wrong → Why → How to fix → Where to configure
+ *
+ * @param {Object} details - Error details
+ * @param {string} details.path - The blocked path
+ * @param {string} details.pattern - The pattern that matched
+ * @param {string} details.tool - The tool that was blocked
+ * @param {string} details.claudeDir - Path to .claude directory
+ * @returns {string}
+ */
+function formatBlockedError(details) {
+  const { path: blockedPath, pattern, tool, claudeDir } = details;
+  const configPath = formatConfigPath(claudeDir);
+
+  // Truncate path if too long
+  const displayPath = blockedPath.length > 60
+    ? '...' + blockedPath.slice(-57)
+    : blockedPath;
+
+  const lines = [
+    '',
+    colorize('NOTE:', 'cyan') + ' This is not an error - this block is intentional to optimize context.',
+    '',
+    colorize('BLOCKED', 'red') + `: Access to '${displayPath}' denied`,
+    '',
+    `  ${colorize('Pattern:', 'yellow')}  ${pattern}`,
+    `  ${colorize('Tool:', 'yellow')}     ${tool || 'unknown'}`,
+    '',
+    `  ${colorize('To allow, add to', 'blue')} ${configPath}:`,
+    `    !${pattern}`,
+    '',
+    `  ${colorize('Config:', 'dim')} ${configPath}`,
+    ''
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a simple error message (one line, for piped output)
+ *
+ * @param {string} pattern - The pattern that matched
+ * @param {string} blockedPath - The path that was blocked
+ * @returns {string}
+ */
+function formatSimpleError(pattern, blockedPath) {
+  return `ERROR: Blocked pattern '${pattern}' matched path: ${blockedPath}`;
+}
+
+/**
+ * Format error for machine-readable output (exit code 2)
+ * Used when stderr is not a TTY
+ *
+ * @param {Object} details - Error details
+ * @returns {string}
+ */
+function formatMachineError(details) {
+  const { path: blockedPath, pattern, tool, claudeDir } = details;
+  const configPath = formatConfigPath(claudeDir);
+
+  return JSON.stringify({
+    error: 'BLOCKED',
+    path: blockedPath,
+    pattern: pattern,
+    tool: tool,
+    config: configPath,
+    fix: `Add '!${pattern}' to ${configPath} to allow this path`
+  });
+}
+
+/**
+ * Format a warning message (non-blocking)
+ *
+ * @param {string} message - Warning message
+ * @returns {string}
+ */
+function formatWarning(message) {
+  return colorize('WARN:', 'yellow') + ' ' + message;
+}
+
+module.exports = {
+  formatBlockedError,
+  formatSimpleError,
+  formatMachineError,
+  formatWarning,
+  formatConfigPath,
+  supportsColor,
+  colorize,
+  COLORS
+};

package/templates/hooks/scout-block/path-extractor.cjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * path-extractor.cjs - Extract paths from Claude Code tool inputs
+ *
+ * Extracts file_path, path, pattern params and parses Bash commands
+ * to find all path-like arguments.
+ */
+
+/**
+ * Extract all paths from a tool_input object
+ * Handles: file_path, path, pattern params and command strings
+ *
+ * @param {Object} toolInput - The tool_input from hook JSON
+ * @returns {string[]} Array of extracted paths
+ */
+function extractFromToolInput(toolInput) {
+  const paths = [];
+
+  if (!toolInput || typeof toolInput !== 'object') {
+    return paths;
+  }
+
+  // Direct path params (Read, Edit, Write, Grep, Glob tools)
+  const directParams = ['file_path', 'path', 'pattern'];
+  for (const param of directParams) {
+    if (toolInput[param] && typeof toolInput[param] === 'string') {
+      const normalized = normalizeExtractedPath(toolInput[param]);
+      if (normalized) paths.push(normalized);
+    }
+  }
+
+  // Extract from Bash command if present
+  if (toolInput.command && typeof toolInput.command === 'string') {
+    const cmdPaths = extractFromCommand(toolInput.command);
+    paths.push(...cmdPaths);
+  }
+
+  return paths.filter(Boolean);
+}
+
+/**
+ * Extract path-like segments from a Bash command string
+ * Handles quoted paths and filters out non-path tokens
+ *
+ * @param {string} command - The command string
+ * @returns {string[]} Array of extracted paths
+ */
+function extractFromCommand(command) {
+  if (!command || typeof command !== 'string') {
+    return [];
+  }
+
+  const paths = [];
+
+  // First, extract quoted strings (preserve spaces in paths)
+  const quotedPattern = /["']([^"']+)["']/g;
+  let match;
+  while ((match = quotedPattern.exec(command)) !== null) {
+    if (looksLikePath(match[1])) {
+      paths.push(normalizeExtractedPath(match[1]));
+    }
+  }
+
+  // Remove quoted strings for unquoted path extraction
+  const withoutQuotes = command.replace(/["'][^"']*["']/g, ' ');
+
+  // Split on whitespace and extract path-like tokens
+  const tokens = withoutQuotes.split(/\s+/).filter(Boolean);
+
+  for (const token of tokens) {
+    // Skip flags and shell operators
+    if (isSkippableToken(token)) continue;
+
+    // Priority check: if token IS a blocked directory name exactly, include it
+    // This handles cases like "cd build" where "build" is both a command word
+    // and a blocked directory name
+    if (isBlockedDirName(token)) {
+      paths.push(normalizeExtractedPath(token));
+      continue;
+    }
+
+    // Skip common non-path command words
+    if (isCommandKeyword(token)) continue;
+
+    // Check if it looks like a path
+    if (looksLikePath(token)) {
+      paths.push(normalizeExtractedPath(token));
+    }
+  }
+
+  return paths;
+}
+
+// Common blocked directory names that should be extracted even if they
+// match command keywords (e.g., "build" is both a subcommand and a dir name)
+// Keep in sync with DEFAULT_PATTERNS in pattern-matcher.cjs
+const BLOCKED_DIR_NAMES = [
+  'node_modules', '__pycache__', '.git', 'dist', 'build',
+  '.next', '.nuxt', '.venv', 'venv', 'vendor', 'target', 'coverage'
+];
+
+/**
+ * Check if token is exactly a blocked directory name
+ * This takes priority over command keyword filtering
+ *
+ * @param {string} token - Token to check
+ * @returns {boolean}
+ */
+function isBlockedDirName(token) {
+  return BLOCKED_DIR_NAMES.includes(token);
+}
+
+/**
+ * Check if a string looks like a file path
+ *
+ * @param {string} str - String to check
+ * @returns {boolean}
+ */
+function looksLikePath(str) {
+  if (!str || str.length < 2) return false;
+
+  // Contains path separator
+  if (str.includes('/') || str.includes('\\')) return true;
+
+  // Starts with relative path indicator
+  if (str.startsWith('./') || str.startsWith('../')) return true;
+
+  // Has file extension (likely a file)
+  if (/\.\w{1,6}$/.test(str)) return true;
+
+  // Contains common blocked directory names
+  if (/node_modules|__pycache__|\.git|dist|build/.test(str)) return true;
+
+  // Looks like a directory path
+  if (/^[a-zA-Z0-9_-]+\//.test(str)) return true;
+
+  return false;
+}
+
+/**
+ * Check if token should be skipped (flags, operators)
+ *
+ * @param {string} token - Token to check
+ * @returns {boolean}
+ */
+function isSkippableToken(token) {
+  // Flags
+  if (token.startsWith('-')) return true;
+
+  // Shell operators
+  if (['|', '||', '&&', '>', '>>', '<', '<<', '&', ';'].includes(token)) return true;
+  if (token.startsWith('|') || token.startsWith('>') || token.startsWith('<')) return true;
+  if (token.startsWith('&')) return true;
+
+  // Numeric values
+  if (/^\d+$/.test(token)) return true;
+
+  return false;
+}
+
+/**
+ * Check if token is a common command keyword (not a path)
+ *
+ * @param {string} token - Token to check
+ * @returns {boolean}
+ */
+function isCommandKeyword(token) {
+  const keywords = [
+    // Shell commands
+    'echo', 'cat', 'ls', 'cd', 'rm', 'cp', 'mv', 'find', 'grep', 'head', 'tail',
+    'wc', 'du', 'tree', 'touch', 'mkdir', 'rmdir', 'pwd', 'which', 'env', 'export',
+    'source', 'bash', 'sh', 'zsh', 'true', 'false', 'test', 'xargs', 'tee', 'sort',
+    'uniq', 'cut', 'tr', 'sed', 'awk', 'diff', 'chmod', 'chown', 'ln', 'file',
+
+    // Package managers and their subcommands
+    'npm', 'pnpm', 'yarn', 'bun', 'npx', 'pnpx', 'bunx', 'node',
+    'run', 'build', 'test', 'lint', 'dev', 'start', 'install', 'ci', 'exec',
+    'add', 'remove', 'update', 'publish', 'pack', 'init', 'create',
+
+    // Build tools
+    'tsc', 'esbuild', 'vite', 'webpack', 'rollup', 'turbo', 'nx',
+    'jest', 'vitest', 'mocha', 'eslint', 'prettier',
+
+    // Git
+    'git', 'commit', 'push', 'pull', 'merge', 'rebase', 'checkout', 'branch',
+    'status', 'log', 'diff', 'add', 'reset', 'stash', 'fetch', 'clone',
+
+    // Docker
+    'docker', 'compose', 'up', 'down', 'ps', 'logs', 'exec', 'container', 'image',
+
+    // Misc
+    'sudo', 'time', 'timeout', 'watch', 'make', 'cargo', 'python', 'python3', 'pip',
+    'ruby', 'gem', 'go', 'rust', 'java', 'javac', 'mvn', 'gradle'
+  ];
+
+  return keywords.includes(token.toLowerCase());
+}
+
+/**
+ * Normalize an extracted path
+ * - Remove surrounding quotes
+ * - Normalize path separators to forward slash
+ *
+ * @param {string} path - Path to normalize
+ * @returns {string} Normalized path
+ */
+function normalizeExtractedPath(path) {
+  if (!path) return '';
+
+  let normalized = path.trim();
+
+  // Remove surrounding quotes
+  if ((normalized.startsWith('"') && normalized.endsWith('"')) ||
+      (normalized.startsWith("'") && normalized.endsWith("'"))) {
+    normalized = normalized.slice(1, -1);
+  }
+
+  // Normalize path separators to forward slash
+  normalized = normalized.replace(/\\/g, '/');
+
+  // Remove trailing slash for consistency
+  if (normalized.endsWith('/') && normalized.length > 1) {
+    normalized = normalized.slice(0, -1);
+  }
+
+  return normalized;
+}
+
+module.exports = {
+  extractFromToolInput,
+  extractFromCommand,
+  looksLikePath,
+  isSkippableToken,
+  isCommandKeyword,
+  isBlockedDirName,
+  normalizeExtractedPath,
+  BLOCKED_DIR_NAMES
+};

package/templates/hooks/scout-block/pattern-matcher.cjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * pattern-matcher.cjs - Gitignore-spec compliant pattern matching
+ *
+ * Uses 'ignore' package for .ckignore parsing and path matching.
+ * Supports negation patterns (!) for allowlisting.
+ */
+
+const Ignore = require('./vendor/ignore');
+const fs = require('fs');
+const path = require('path');
+
+// Default patterns if .ckignore doesn't exist or is empty
+// Only includes directories with HEAVY file counts (1000+ files typical)
+const DEFAULT_PATTERNS = [
+  // JavaScript/TypeScript - package dependencies & build outputs
+  'node_modules',
+  'dist',
+  'build',
+  '.next',
+  '.nuxt',
+  // Python - virtualenvs & cache
+  '__pycache__',
+  '.venv',
+  'venv',
+  // Go/PHP - vendor dependencies
+  'vendor',
+  // Rust/Java - compiled outputs
+  'target',
+  // Version control
+  '.git',
+  // Test coverage (can be large with reports)
+  'coverage',
+];
+
+/**
+ * Load patterns from .ckignore file
+ * Falls back to DEFAULT_PATTERNS if file doesn't exist or is empty
+ *
+ * @param {string} ckignorePath - Path to .ckignore file
+ * @returns {string[]} Array of patterns
+ */
+function loadPatterns(ckignorePath) {
+  if (!ckignorePath || !fs.existsSync(ckignorePath)) {
+    return DEFAULT_PATTERNS;
+  }
+
+  try {
+    const content = fs.readFileSync(ckignorePath, 'utf-8');
+    const patterns = content
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line && !line.startsWith('#'));
+
+    return patterns.length > 0 ? patterns : DEFAULT_PATTERNS;
+  } catch (error) {
+    console.error('WARN: Failed to read .ckignore:', error.message);
+    return DEFAULT_PATTERNS;
+  }
+}
+
+/**
+ * Create a matcher from patterns
+ * Normalizes patterns to match anywhere in the path tree
+ *
+ * @param {string[]} patterns - Array of patterns from .ckignore
+ * @returns {Object} Matcher object with ig instance and pattern info
+ */
+function createMatcher(patterns) {
+  const ig = Ignore();
+
+  // Normalize patterns to match anywhere in path tree
+  // e.g., "node_modules" becomes "**\/node_modules" and "**\/node_modules/**"
+  const normalizedPatterns = [];
+
+  for (const p of patterns) {
+    if (p.startsWith('!')) {
+      // Negation pattern - un-ignore
+      const inner = p.slice(1);
+      if (inner.includes('/') || inner.includes('*')) {
+        // Already has path or glob - use as-is
+        normalizedPatterns.push(p);
+      } else {
+        // Simple dir name - match anywhere
+        normalizedPatterns.push(`!**/${inner}`);
+        normalizedPatterns.push(`!**/${inner}/**`);
+      }
+    } else {
+      // Block pattern
+      if (p.includes('/') || p.includes('*')) {
+        // Already has path or glob - use as-is
+        normalizedPatterns.push(p);
+      } else {
+        // Simple dir name - match the dir and contents anywhere
+        normalizedPatterns.push(`**/${p}`);
+        normalizedPatterns.push(`**/${p}/**`);
+        // Also match at root
+        normalizedPatterns.push(p);
+        normalizedPatterns.push(`${p}/**`);
+      }
+    }
+  }
+
+  ig.add(normalizedPatterns);
+
+  return {
+    ig,
+    patterns: normalizedPatterns,
+    original: patterns
+  };
+}
+
+/**
+ * Check if a path should be blocked
+ *
+ * @param {Object} matcher - Matcher object from createMatcher
+ * @param {string} testPath - Path to test
+ * @returns {Object} { blocked: boolean, pattern?: string }
+ */
+function matchPath(matcher, testPath) {
+  if (!testPath || typeof testPath !== 'string') {
+    return { blocked: false };
+  }
+
+  // Normalize path separators (Windows backslash to forward slash)
+  let normalized = testPath.replace(/\\/g, '/');
+
+  // Remove leading ./ if present
+  if (normalized.startsWith('./')) {
+    normalized = normalized.slice(2);
+  }
+
+  // Check if path is ignored (blocked)
+  const blocked = matcher.ig.ignores(normalized);
+
+  if (blocked) {
+    // Find which original pattern matched for error message
+    const matchedPattern = findMatchingPattern(matcher.original, normalized);
+    return { blocked: true, pattern: matchedPattern };
+  }
+
+  return { blocked: false };
+}
+
+/**
+ * Find which original pattern matched (for error messages)
+ *
+ * @param {string[]} originalPatterns - Original patterns from .ckignore
+ * @param {string} path - The path that was blocked
+ * @returns {string} The pattern that matched
+ */
+function findMatchingPattern(originalPatterns, path) {
+  for (const p of originalPatterns) {
+    if (p.startsWith('!')) continue; // Skip negations
+
+    // Simple substring check for common cases
+    const pattern = p.replace(/\*\*/g, '').replace(/\*/g, '');
+    if (pattern && path.includes(pattern)) {
+      return p;
+    }
+
+    // For more complex patterns, use ignore to test individually
+    const tempIg = Ignore();
+    if (p.includes('/') || p.includes('*')) {
+      tempIg.add(p);
+    } else {
+      tempIg.add([`**/${p}`, `**/${p}/**`, p, `${p}/**`]);
+    }
+
+    if (tempIg.ignores(path)) {
+      return p;
+    }
+  }
+
+  return originalPatterns.find(p => !p.startsWith('!')) || 'unknown';
+}
+
+module.exports = {
+  loadPatterns,
+  createMatcher,
+  matchPath,
+  findMatchingPattern,
+  DEFAULT_PATTERNS
+};