@stella-studio/ck 1.0.0

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

@@ -0,0 +1,260 @@
+#!/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 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
+};

package/.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('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/.claude/hooks/scout-block/path-extractor.cjs

@@ -0,0 +1,265 @@
+#!/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.
+ */
+
+// Flags that indicate the following value should NOT be checked as a path
+// These are "exclude" semantics - the user is explicitly skipping these paths
+const EXCLUDE_FLAGS = [
+  '--exclude', '--ignore', '--skip', '--prune',
+  '-x',           // tar exclude shorthand
+  '-path',        // find -path (used with -prune)
+  '--exclude-dir' // grep --exclude-dir
+];
+
+/**
+ * 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);
+
+  // Track if next token should be skipped (value after exclude flag)
+  let skipNextToken = false;
+
+  for (const token of tokens) {
+    // Skip value after exclude flags (--exclude node_modules format)
+    if (skipNextToken) {
+      skipNextToken = false;
+      continue;
+    }
+
+    // Skip flags and shell operators
+    if (isSkippableToken(token)) {
+      // Check if this is an exclude flag that takes a separate value
+      // --exclude=value format already handled (whole token starts with -)
+      // --exclude value format needs to skip the next token
+      if (EXCLUDE_FLAGS.includes(token)) {
+        skipNextToken = true;
+      }
+      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,
+  EXCLUDE_FLAGS
+};