@stella-studio/ck 1.0.0

package/.claude/hooks/lib/project-detector.cjs

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+/**
+ * project-detector.cjs - Project and environment detection logic
+ *
+ * Extracted from session-init.cjs for reuse in both Claude hooks and OpenCode plugins.
+ * Detects project type, package manager, framework, and runtime versions.
+ *
+ * @module project-detector
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync, execFileSync } = require('child_process');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SAFE EXECUTION HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Safely execute shell command with optional timeout
+ * @param {string} cmd - Command to execute
+ * @param {number} [timeoutMs=5000] - Timeout in milliseconds
+ * @returns {string|null} Output or null on error
+ */
+function execSafe(cmd, timeoutMs = 5000) {
+  try {
+    return execSync(cmd, {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Safely execute a binary with arguments (no shell interpolation)
+ * @param {string} binary - Path to the executable
+ * @param {string[]} args - Arguments array
+ * @param {number} [timeoutMs=2000] - Timeout in milliseconds
+ * @returns {string|null} Output or null on error
+ */
+function execFileSafe(binary, args, timeoutMs = 2000) {
+  try {
+    return execFileSync(binary, args, {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PYTHON DETECTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Validate that a path is a file and doesn't contain shell metacharacters
+ * @param {string} p - Path to validate
+ * @returns {boolean}
+ */
+function isValidPythonPath(p) {
+  if (!p || typeof p !== 'string') return false;
+  if (/[;&|`$(){}[\]<>!#*?]/.test(p)) return false;
+  try {
+    const stat = fs.statSync(p);
+    return stat.isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Build platform-specific Python paths for fast filesystem check
+ * @returns {string[]} Array of potential Python paths
+ */
+function getPythonPaths() {
+  const paths = [];
+
+  if (process.env.PYTHON_PATH) {
+    paths.push(process.env.PYTHON_PATH);
+  }
+
+  if (process.platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA;
+    const programFiles = process.env.ProgramFiles || 'C:\\Program Files';
+    const programFilesX86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
+
+    if (localAppData) {
+      paths.push(path.join(localAppData, 'Microsoft', 'WindowsApps', 'python.exe'));
+      paths.push(path.join(localAppData, 'Microsoft', 'WindowsApps', 'python3.exe'));
+      for (const ver of ['313', '312', '311', '310', '39']) {
+        paths.push(path.join(localAppData, 'Programs', 'Python', `Python${ver}`, 'python.exe'));
+      }
+    }
+
+    for (const ver of ['313', '312', '311', '310', '39']) {
+      paths.push(path.join(programFiles, `Python${ver}`, 'python.exe'));
+      paths.push(path.join(programFilesX86, `Python${ver}`, 'python.exe'));
+    }
+
+    paths.push('C:\\Python313\\python.exe');
+    paths.push('C:\\Python312\\python.exe');
+    paths.push('C:\\Python311\\python.exe');
+    paths.push('C:\\Python310\\python.exe');
+    paths.push('C:\\Python39\\python.exe');
+  } else {
+    paths.push('/usr/bin/python3');
+    paths.push('/usr/local/bin/python3');
+    paths.push('/opt/homebrew/bin/python3');
+    paths.push('/opt/homebrew/bin/python');
+    paths.push('/usr/bin/python');
+    paths.push('/usr/local/bin/python');
+  }
+
+  return paths;
+}
+
+/**
+ * Find Python binary using fast filesystem check
+ * @returns {string|null} Python binary path or null
+ */
+function findPythonBinary() {
+  const paths = getPythonPaths();
+  for (const p of paths) {
+    if (isValidPythonPath(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Get Python version with optimized detection
+ * @returns {string|null} Python version string or null
+ */
+function getPythonVersion() {
+  const pythonPath = findPythonBinary();
+  if (pythonPath) {
+    const result = execFileSafe(pythonPath, ['--version']);
+    if (result) return result;
+  }
+
+  const commands = ['python3', 'python'];
+  for (const cmd of commands) {
+    const result = execFileSafe(cmd, ['--version']);
+    if (result) return result;
+  }
+
+  return null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// GIT DETECTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get git remote URL
+ * @returns {string|null}
+ */
+function getGitRemoteUrl() {
+  return execSafe('git config --get remote.origin.url');
+}
+
+/**
+ * Get current git branch
+ * @returns {string|null}
+ */
+function getGitBranch() {
+  return execSafe('git branch --show-current');
+}
+
+/**
+ * Get git repository root
+ * @returns {string|null}
+ */
+function getGitRoot() {
+  return execSafe('git rev-parse --show-toplevel');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PROJECT DETECTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Detect project type based on workspace indicators
+ * @param {string} [configOverride] - Manual override from config
+ * @returns {'monorepo' | 'library' | 'single-repo'}
+ */
+function detectProjectType(configOverride) {
+  if (configOverride && configOverride !== 'auto') return configOverride;
+
+  if (fs.existsSync('pnpm-workspace.yaml')) return 'monorepo';
+  if (fs.existsSync('lerna.json')) return 'monorepo';
+
+  if (fs.existsSync('package.json')) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+      if (pkg.workspaces) return 'monorepo';
+      if (pkg.main || pkg.exports) return 'library';
+    } catch (e) { /* ignore */ }
+  }
+
+  return 'single-repo';
+}
+
+/**
+ * Detect package manager from lock files
+ * @param {string} [configOverride] - Manual override from config
+ * @returns {'npm' | 'pnpm' | 'yarn' | 'bun' | null}
+ */
+function detectPackageManager(configOverride) {
+  if (configOverride && configOverride !== 'auto') return configOverride;
+
+  if (fs.existsSync('bun.lockb')) return 'bun';
+  if (fs.existsSync('pnpm-lock.yaml')) return 'pnpm';
+  if (fs.existsSync('yarn.lock')) return 'yarn';
+  if (fs.existsSync('package-lock.json')) return 'npm';
+
+  return null;
+}
+
+/**
+ * Detect framework from package.json dependencies
+ * @param {string} [configOverride] - Manual override from config
+ * @returns {string|null}
+ */
+function detectFramework(configOverride) {
+  if (configOverride && configOverride !== 'auto') return configOverride;
+  if (!fs.existsSync('package.json')) return null;
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    if (deps['next']) return 'next';
+    if (deps['nuxt']) return 'nuxt';
+    if (deps['astro']) return 'astro';
+    if (deps['@remix-run/node'] || deps['@remix-run/react']) return 'remix';
+    if (deps['svelte'] || deps['@sveltejs/kit']) return 'svelte';
+    if (deps['vue']) return 'vue';
+    if (deps['react']) return 'react';
+    if (deps['express']) return 'express';
+    if (deps['fastify']) return 'fastify';
+    if (deps['hono']) return 'hono';
+    if (deps['elysia']) return 'elysia';
+
+    return null;
+  } catch (e) {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CODING LEVEL
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get coding level style name mapping
+ * @param {number} level - Coding level (0-5)
+ * @returns {string} Style name
+ */
+function getCodingLevelStyleName(level) {
+  const styleMap = {
+    0: 'coding-level-0-eli5',
+    1: 'coding-level-1-junior',
+    2: 'coding-level-2-mid',
+    3: 'coding-level-3-senior',
+    4: 'coding-level-4-lead',
+    5: 'coding-level-5-god'
+  };
+  return styleMap[level] || 'coding-level-5-god';
+}
+
+/**
+ * Get coding level guidelines by reading from output-styles .md files
+ * @param {number} level - Coding level (-1 to 5)
+ * @param {string} [configDir] - Config directory path
+ * @returns {string|null} Guidelines text or null if disabled
+ */
+function getCodingLevelGuidelines(level, configDir) {
+  if (level === -1 || level === null || level === undefined) return null;
+
+  const styleName = getCodingLevelStyleName(level);
+  const basePath = configDir || path.join(process.cwd(), '.claude');
+  const stylePath = path.join(basePath, 'output-styles', `${styleName}.md`);
+
+  try {
+    if (!fs.existsSync(stylePath)) return null;
+    const content = fs.readFileSync(stylePath, 'utf8');
+    const withoutFrontmatter = content.replace(/^---[\s\S]*?---\n*/, '').trim();
+    return withoutFrontmatter;
+  } catch (e) {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONTEXT OUTPUT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Build context summary for output (compact, single line)
+ * @param {Object} config - Loaded config
+ * @param {Object} detections - Project detections
+ * @param {{ path: string|null, resolvedBy: string|null }} resolved - Plan resolution
+ * @param {string|null} gitRoot - Git repository root
+ * @returns {string}
+ */
+function buildContextOutput(config, detections, resolved, gitRoot) {
+  const lines = [`Project: ${detections.type || 'unknown'}`];
+  if (detections.pm) lines.push(`PM: ${detections.pm}`);
+  lines.push(`Plan naming: ${config.plan.namingFormat}`);
+
+  if (gitRoot && gitRoot !== process.cwd()) {
+    lines.push(`Root: ${gitRoot}`);
+  }
+
+  if (resolved.path) {
+    if (resolved.resolvedBy === 'session') {
+      lines.push(`Plan: ${resolved.path}`);
+    } else {
+      lines.push(`Suggested: ${resolved.path}`);
+    }
+  }
+
+  return lines.join(' | ');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN ENTRY POINT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Detect all project information
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.configOverrides] - Override auto-detection
+ * @returns {{
+ *   type: 'monorepo' | 'library' | 'single-repo',
+ *   packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun' | null,
+ *   framework: string | null,
+ *   pythonVersion: string | null,
+ *   nodeVersion: string,
+ *   gitBranch: string | null,
+ *   gitRoot: string | null,
+ *   gitUrl: string | null,
+ *   osPlatform: string,
+ *   user: string,
+ *   locale: string,
+ *   timezone: string
+ * }}
+ */
+function detectProject(options = {}) {
+  const { configOverrides = {} } = options;
+
+  return {
+    type: detectProjectType(configOverrides.type),
+    packageManager: detectPackageManager(configOverrides.packageManager),
+    framework: detectFramework(configOverrides.framework),
+    pythonVersion: getPythonVersion(),
+    nodeVersion: process.version,
+    gitBranch: getGitBranch(),
+    gitRoot: getGitRoot(),
+    gitUrl: getGitRemoteUrl(),
+    osPlatform: process.platform,
+    user: process.env.USERNAME || process.env.USER || process.env.LOGNAME || os.userInfo().username,
+    locale: process.env.LANG || '',
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
+  };
+}
+
+/**
+ * Build static environment info object
+ * @param {string} [configDir] - Config directory path
+ * @returns {Object} Static environment info
+ */
+function buildStaticEnv(configDir) {
+  return {
+    nodeVersion: process.version,
+    pythonVersion: getPythonVersion(),
+    osPlatform: process.platform,
+    gitUrl: getGitRemoteUrl(),
+    gitBranch: getGitBranch(),
+    gitRoot: getGitRoot(),
+    user: process.env.USERNAME || process.env.USER || process.env.LOGNAME || os.userInfo().username,
+    locale: process.env.LANG || '',
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    configDir: configDir || path.join(process.cwd(), '.claude')
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Main entry points
+  detectProject,
+  buildStaticEnv,
+
+  // Detection functions
+  detectProjectType,
+  detectPackageManager,
+  detectFramework,
+
+  // Python detection
+  getPythonVersion,
+  findPythonBinary,
+  getPythonPaths,
+  isValidPythonPath,
+
+  // Git detection
+  getGitRemoteUrl,
+  getGitBranch,
+  getGitRoot,
+
+  // Coding level
+  getCodingLevelStyleName,
+  getCodingLevelGuidelines,
+
+  // Output
+  buildContextOutput,
+
+  // Helpers
+  execSafe,
+  execFileSafe
+};

package/.claude/hooks/lib/scout-checker.cjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * scout-checker.cjs - Facade for scout-block modules
+ *
+ * Provides unified interface to scout-block/* modules for reuse in both
+ * Claude hooks and OpenCode plugins.
+ *
+ * @module scout-checker
+ */
+
+const path = require('path');
+
+// Import scout-block modules
+const { loadPatterns, createMatcher, matchPath } = require('../scout-block/pattern-matcher.cjs');
+const { extractFromToolInput } = require('../scout-block/path-extractor.cjs');
+const { detectBroadPatternIssue } = require('../scout-block/broad-pattern-detector.cjs');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// COMMAND PATTERNS
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Build command allowlist - these are allowed even if they contain blocked paths
+// Handles flags and filters: npm build, pnpm --filter web run build, yarn workspace app build
+const BUILD_COMMAND_PATTERN = /^(npm|pnpm|yarn|bun)\s+([^\s]+\s+)*(run\s+)?(build|test|lint|dev|start|install|ci|add|remove|update|publish|pack|init|create|exec)/;
+
+// Tool commands - go, cargo, make, mvn/mvnw, gradle/gradlew, dotnet, docker, bazel, cmake, sbt, flutter, swift, ant, ninja, meson
+const TOOL_COMMAND_PATTERN = /^(\.\/)?(npx|pnpx|bunx|tsc|esbuild|vite|webpack|rollup|turbo|nx|jest|vitest|mocha|eslint|prettier|go|cargo|make|mvn|mvnw|gradle|gradlew|dotnet|docker|podman|kubectl|helm|terraform|ansible|bazel|cmake|sbt|flutter|swift|ant|ninja|meson)/;
+
+// Allow execution from .venv/bin/ or venv/bin/ (Unix) and .venv/Scripts/ or venv/Scripts/ (Windows)
+const VENV_EXECUTABLE_PATTERN = /(^|[\/\\])\.?venv[\/\\](bin|Scripts)[\/\\]/;
+
+// Allow Python venv creation commands (cross-platform):
+// - python/python3 -m venv (Unix/macOS/Windows)
+// - py -m venv (Windows py launcher, supports -3, -3.11, etc.)
+// - uv venv (fast Rust-based Python package manager)
+// - virtualenv (legacy but still widely used)
+const VENV_CREATION_PATTERN = /^(python3?|py)\s+(-[\w.]+\s+)*-m\s+venv\s+|^uv\s+venv(\s|$)|^virtualenv\s+/;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a command is a build/tooling command (should be allowed)
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isBuildCommand(command) {
+  if (!command || typeof command !== 'string') return false;
+  const trimmed = command.trim();
+  return BUILD_COMMAND_PATTERN.test(trimmed) || TOOL_COMMAND_PATTERN.test(trimmed);
+}
+
+/**
+ * Check if command executes from a .venv bin directory
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isVenvExecutable(command) {
+  if (!command || typeof command !== 'string') return false;
+  return VENV_EXECUTABLE_PATTERN.test(command);
+}
+
+/**
+ * Check if command creates a Python virtual environment
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isVenvCreationCommand(command) {
+  if (!command || typeof command !== 'string') return false;
+  return VENV_CREATION_PATTERN.test(command.trim());
+}
+
+/**
+ * Check if command should be allowed (build, venv executable, or venv creation)
+ * @param {string} command - The command to check
+ * @returns {boolean}
+ */
+function isAllowedCommand(command) {
+  return isBuildCommand(command) || isVenvExecutable(command) || isVenvCreationCommand(command);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN ENTRY POINT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a tool call accesses blocked directories or uses overly broad patterns
+ *
+ * @param {Object} params
+ * @param {string} params.toolName - Name of tool (Bash, Glob, Read, etc.)
+ * @param {Object} params.toolInput - Tool input with file_path, path, pattern, command
+ * @param {Object} [params.options]
+ * @param {string} [params.options.ckignorePath] - Path to .ckignore file
+ * @param {string} [params.options.claudeDir] - Path to .claude or .opencode directory
+ * @param {boolean} [params.options.checkBroadPatterns] - Check for overly broad glob patterns (default: true)
+ * @returns {{
+ *   blocked: boolean,
+ *   path?: string,
+ *   pattern?: string,
+ *   reason?: string,
+ *   isBroadPattern?: boolean,
+ *   suggestions?: string[],
+ *   isAllowedCommand?: boolean
+ * }}
+ */
+function checkScoutBlock({ toolName, toolInput, options = {} }) {
+  const {
+    ckignorePath,
+    claudeDir = path.join(process.cwd(), '.claude'),
+    checkBroadPatterns = true
+  } = options;
+
+  // Check if it's a build command or venv executable (allowed regardless of paths)
+  if (toolInput.command && isAllowedCommand(toolInput.command)) {
+    return { blocked: false, isAllowedCommand: true };
+  }
+
+  // Check for overly broad glob patterns (Glob tool)
+  if (checkBroadPatterns && (toolName === 'Glob' || toolInput.pattern)) {
+    const broadResult = detectBroadPatternIssue(toolInput);
+    if (broadResult.blocked) {
+      return {
+        blocked: true,
+        isBroadPattern: true,
+        pattern: toolInput.pattern,
+        reason: broadResult.reason || 'Pattern too broad - may fill context with too many files',
+        suggestions: broadResult.suggestions || []
+      };
+    }
+  }
+
+  // Resolve .ckignore path
+  const resolvedCkignorePath = ckignorePath || path.join(claudeDir, '.ckignore');
+
+  // Load patterns and create matcher
+  const patterns = loadPatterns(resolvedCkignorePath);
+  const matcher = createMatcher(patterns);
+
+  // Extract paths from tool input
+  const extractedPaths = extractFromToolInput(toolInput);
+
+  // If no paths extracted, allow operation
+  if (extractedPaths.length === 0) {
+    return { blocked: false };
+  }
+
+  // Check each path against patterns
+  for (const extractedPath of extractedPaths) {
+    const result = matchPath(matcher, extractedPath);
+    if (result.blocked) {
+      return {
+        blocked: true,
+        path: extractedPath,
+        pattern: result.pattern,
+        reason: `Path matches blocked pattern: ${result.pattern}`
+      };
+    }
+  }
+
+  // All paths allowed
+  return { blocked: false };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Main entry point
+  checkScoutBlock,
+
+  // Command checkers
+  isBuildCommand,
+  isVenvExecutable,
+  isVenvCreationCommand,
+  isAllowedCommand,
+
+  // Re-export scout-block modules for direct access
+  loadPatterns,
+  createMatcher,
+  matchPath,
+  extractFromToolInput,
+  detectBroadPatternIssue,
+
+  // Patterns (for testing)
+  BUILD_COMMAND_PATTERN,
+  TOOL_COMMAND_PATTERN,
+  VENV_EXECUTABLE_PATTERN,
+  VENV_CREATION_PATTERN
+};