@macpaw/cctk 1.0.0-beta.1

package/templates/claude/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('node:path');
+
+// ANSI color codes
+const COLORS = {
+  red: '\u001B[31m',
+  yellow: '\u001B[33m',
+  blue: '\u001B[34m',
+  cyan: '\u001B[36m',
+  bold: '\u001B[1m',
+  dim: '\u001B[2m',
+  reset: '\u001B[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 .cctkignore config path
+ *
+ * @param {string} claudeDir - Path to .claude directory
+ * @returns {string}
+ */
+function formatConfigPath(claudeDir) {
+  if (claudeDir) {
+    return path.join(claudeDir, '.cctkignore');
+  }
+
+  return '.claude/.cctkignore';
+}
+
+/**
+ * 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,
+    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/claude/hooks/scout-block/path-extractor.cjs

@@ -0,0 +1,359 @@
+#!/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.replaceAll(/["'][^"']*["']/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.replaceAll('\\', '/');
+
+  // 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/claude/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 .cctkignore parsing and path matching.
+ * Supports negation patterns (!) for allowlisting.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const Ignore = require('./vendor/ignore');
+
+// Default patterns if .cctkignore 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 .cctkignore file
+ * Falls back to DEFAULT_PATTERNS if file doesn't exist or is empty
+ *
+ * @param {string} ckignorePath - Path to .cctkignore file
+ * @returns {string[]} Array of patterns
+ */
+function loadPatterns(ckignorePath) {
+  if (!ckignorePath || !fs.existsSync(ckignorePath)) {
+    return DEFAULT_PATTERNS;
+  }
+
+  try {
+    const content = fs.readFileSync(ckignorePath, 'utf8');
+    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 .cctkignore:', 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 .cctkignore
+ * @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}`, `!**/${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}`, `**/${p}/**`, p, `${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.replaceAll('\\', '/');
+
+  // 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 .cctkignore
+ * @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.replaceAll('**', '').replaceAll('*', '');
+
+    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,
+};