ship-safe 5.0.1 → 6.1.0

package/cli/commands/scan-skill.js

@@ -0,0 +1,329 @@
+/**
+ * Scan Skill Command
+ * ===================
+ *
+ * Downloads and analyzes an AI agent skill before installation.
+ * Checks for malicious patterns, permission abuse, typosquatting,
+ * and known threat intelligence indicators.
+ *
+ * USAGE:
+ *   ship-safe scan-skill <url>          Analyze a skill from URL
+ *   ship-safe scan-skill <path>         Analyze a local skill file
+ *   ship-safe scan-skill . --all        Scan all skills in openclaw.json
+ */
+
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { createHash } from 'crypto';
+import * as output from '../utils/output.js';
+import { ThreatIntel } from '../utils/threat-intel.js';
+
+// =============================================================================
+// POPULAR SKILL NAMES (for typosquatting detection)
+// =============================================================================
+
+const POPULAR_SKILLS = [
+  'web-search', 'web-browser', 'file-manager', 'code-runner',
+  'git-helper', 'database-query', 'api-tester', 'image-gen',
+  'text-to-speech', 'pdf-reader', 'email-sender', 'slack-bot',
+  'github-helper', 'docker-manager', 'kubernetes-helper',
+  'aws-helper', 'terraform-helper', 'memory-store',
+  'calculator', 'translator', 'summarizer', 'code-review',
+];
+
+// =============================================================================
+// MALICIOUS PATTERNS
+// =============================================================================
+
+const SKILL_PATTERNS = [
+  { name: 'Shell execution', regex: /(?:child_process|exec|spawn|execSync|execFile|os\.system|subprocess|shell_exec|system\()/gi, severity: 'critical' },
+  { name: 'Outbound HTTP to non-localhost', regex: /(?:fetch|axios|http\.get|requests\.get|urllib|wget|curl)\s*\(\s*['"`]https?:\/\/(?!(?:localhost|127\.0\.0\.1|::1))/gi, severity: 'high' },
+  { name: 'Data exfiltration service', regex: /(?:webhook\.site|requestbin\.com|hookbin\.com|pipedream\.net|ngrok\.io|ngrok\.app|burpcollaborator|interact\.sh)/gi, severity: 'critical' },
+  { name: 'Environment variable access', regex: /(?:process\.env|os\.environ|os\.getenv|ENV\[|System\.getenv)/gi, severity: 'medium' },
+  { name: 'File system write', regex: /(?:fs\.writeFile|fs\.appendFile|writeFileSync|open\(.+['"]w['"]|fwrite|file_put_contents)/gi, severity: 'medium' },
+  { name: 'Base64 decode + execute', regex: /(?:atob|Buffer\.from|base64\.b64decode|base64_decode)\s*\([^)]*\)\s*(?:\.|\))\s*(?:eval|exec|Function)/gi, severity: 'critical' },
+  { name: 'Dynamic code evaluation', regex: /(?:eval\s*\(|new\s+Function\s*\(|exec\s*\(|compile\s*\()/gi, severity: 'high' },
+  { name: 'Crypto operations', regex: /(?:crypto\.createCipher|crypto\.createDecipher|CryptoJS|forge\.cipher)/gi, severity: 'medium' },
+  { name: 'Network listener', regex: /(?:createServer|listen\s*\(\s*\d|bind\s*\(\s*['"]0\.0\.0\.0)/gi, severity: 'high' },
+  { name: 'Encoded payload block', regex: /[A-Za-z0-9+\/]{60,}={0,2}/g, severity: 'medium' },
+];
+
+// =============================================================================
+// MAIN COMMAND
+// =============================================================================
+
+export async function scanSkillCommand(target, options = {}) {
+  if (!target) {
+    output.error('Usage: ship-safe scan-skill <url|path>');
+    output.info('  Analyze an AI agent skill for security issues before installing it.');
+    process.exit(1);
+  }
+
+  console.log();
+  output.header('Ship Safe — Skill Security Analysis');
+  console.log();
+
+  // If --all flag, scan all skills from openclaw.json
+  if (options.all) {
+    return scanAllSkills(path.resolve(target));
+  }
+
+  // Determine if URL or local file
+  let content, skillName, source;
+
+  if (target.startsWith('http://') || target.startsWith('https://')) {
+    console.log(chalk.gray(`  Fetching skill from: ${target}`));
+    try {
+      const response = await fetch(target);
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      content = await response.text();
+      skillName = new URL(target).pathname.split('/').pop() || 'remote-skill';
+      source = target;
+    } catch (err) {
+      output.error(`Failed to fetch skill: ${err.message}`);
+      process.exit(1);
+    }
+  } else {
+    const filePath = path.resolve(target);
+    if (!fs.existsSync(filePath)) {
+      output.error(`File not found: ${filePath}`);
+      process.exit(1);
+    }
+    content = fs.readFileSync(filePath, 'utf-8');
+    skillName = path.basename(filePath);
+    source = filePath;
+  }
+
+  console.log(chalk.gray(`  Skill: ${skillName}`));
+  console.log(chalk.gray(`  Size: ${content.length} bytes`));
+  console.log();
+
+  const findings = analyzeSkill(content, skillName, source);
+
+  if (options.json) {
+    console.log(JSON.stringify({ skill: skillName, source, findings, summary: getSummary(findings) }, null, 2));
+    return;
+  }
+
+  printSkillFindings(findings, skillName);
+}
+
+// =============================================================================
+// SKILL ANALYSIS
+// =============================================================================
+
+function analyzeSkill(content, skillName, source) {
+  const findings = [];
+
+  // 1. Static pattern analysis
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const pattern of SKILL_PATTERNS) {
+      pattern.regex.lastIndex = 0;
+      if (pattern.regex.test(line)) {
+        findings.push({
+          check: 'static-analysis',
+          name: pattern.name,
+          severity: pattern.severity,
+          line: i + 1,
+          matched: line.trim().slice(0, 100),
+        });
+      }
+    }
+  }
+
+  // 2. Permission manifest audit (if JSON)
+  try {
+    const manifest = JSON.parse(content);
+    if (manifest.permissions) {
+      const dangerous = ['shell', 'exec', 'system', 'network', 'filesystem', 'admin', 'root'];
+      for (const perm of (Array.isArray(manifest.permissions) ? manifest.permissions : [])) {
+        const permStr = typeof perm === 'string' ? perm : perm.name || '';
+        if (dangerous.some(d => permStr.toLowerCase().includes(d))) {
+          findings.push({
+            check: 'permission-audit',
+            name: `Dangerous permission: ${permStr}`,
+            severity: 'high',
+            line: 0,
+            matched: `permissions: [${permStr}]`,
+          });
+        }
+      }
+    }
+
+    // Check for suspicious fields
+    if (manifest.postInstall || manifest.postinstall) {
+      findings.push({
+        check: 'permission-audit',
+        name: 'Post-install script defined',
+        severity: 'high',
+        line: 0,
+        matched: 'postInstall hook detected',
+      });
+    }
+  } catch { /* Not JSON, skip manifest audit */ }
+
+  // 3. Typosquatting detection
+  const typosquatResult = checkTyposquatting(skillName);
+  if (typosquatResult) {
+    findings.push({
+      check: 'typosquatting',
+      name: `Possible typosquat of "${typosquatResult.target}"`,
+      severity: 'high',
+      line: 0,
+      matched: `Levenshtein distance: ${typosquatResult.distance} from "${typosquatResult.target}"`,
+    });
+  }
+
+  // 4. Threat intel hash check
+  const hash = createHash('sha256').update(content).digest('hex');
+  const intelMatch = ThreatIntel.lookupHash(hash);
+  if (intelMatch) {
+    findings.push({
+      check: 'threat-intel',
+      name: `Known malicious skill: ${intelMatch.name}`,
+      severity: 'critical',
+      line: 0,
+      matched: `SHA-256: ${hash} — ${intelMatch.description}`,
+    });
+  }
+
+  // 5. Threat intel signature check
+  const sigMatches = ThreatIntel.matchSignatures(content);
+  for (const sig of sigMatches) {
+    findings.push({
+      check: 'threat-intel',
+      name: `Threat intel signature match: ${sig.description}`,
+      severity: sig.severity || 'critical',
+      line: 0,
+      matched: `Pattern: ${sig.pattern}`,
+    });
+  }
+
+  return findings;
+}
+
+// =============================================================================
+// TYPOSQUATTING
+// =============================================================================
+
+function levenshtein(a, b) {
+  const matrix = [];
+  for (let i = 0; i <= b.length; i++) matrix[i] = [i];
+  for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      matrix[i][j] = b[i - 1] === a[j - 1]
+        ? matrix[i - 1][j - 1]
+        : Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+    }
+  }
+  return matrix[b.length][a.length];
+}
+
+function checkTyposquatting(skillName) {
+  const name = skillName.toLowerCase().replace(/[^a-z0-9-]/g, '');
+  for (const popular of POPULAR_SKILLS) {
+    const distance = levenshtein(name, popular);
+    if (distance > 0 && distance <= 2 && name !== popular) {
+      return { target: popular, distance };
+    }
+  }
+  return null;
+}
+
+// =============================================================================
+// SCAN ALL SKILLS IN PROJECT
+// =============================================================================
+
+async function scanAllSkills(rootPath) {
+  const openclawPath = path.join(rootPath, 'openclaw.json');
+  if (!fs.existsSync(openclawPath)) {
+    output.warning('No openclaw.json found. Nothing to scan.');
+    return;
+  }
+
+  try {
+    const config = JSON.parse(fs.readFileSync(openclawPath, 'utf-8'));
+    const skills = config.skills || [];
+
+    if (skills.length === 0) {
+      output.info('No skills defined in openclaw.json.');
+      return;
+    }
+
+    console.log(chalk.gray(`  Found ${skills.length} skill(s) in openclaw.json`));
+    console.log();
+
+    for (const skill of skills) {
+      const url = typeof skill === 'string' ? skill : skill.source || skill.url;
+      const name = typeof skill === 'string' ? skill : skill.name || 'unnamed';
+
+      if (url && (url.startsWith('http://') || url.startsWith('https://'))) {
+        console.log(chalk.cyan(`  Scanning skill: ${name}`));
+        try {
+          const response = await fetch(url);
+          if (!response.ok) throw new Error(`HTTP ${response.status}`);
+          const content = await response.text();
+          const findings = analyzeSkill(content, name, url);
+          if (findings.length > 0) {
+            printSkillFindings(findings, name);
+          } else {
+            console.log(chalk.green(`    ✔ Clean`));
+          }
+        } catch (err) {
+          console.log(chalk.yellow(`    ⚠ Could not fetch: ${err.message}`));
+        }
+      } else {
+        console.log(chalk.gray(`    → ${name}: local skill (static analysis only)`));
+      }
+      console.log();
+    }
+  } catch (err) {
+    output.error(`Failed to parse openclaw.json: ${err.message}`);
+  }
+}
+
+// =============================================================================
+// OUTPUT
+// =============================================================================
+
+function printSkillFindings(findings, skillName) {
+  const summary = getSummary(findings);
+
+  if (findings.length === 0) {
+    console.log(chalk.green.bold(`  ✔ ${skillName}: No security issues found.`));
+    console.log();
+    return;
+  }
+
+  console.log(chalk.red.bold(`  ✘ ${skillName}: ${findings.length} issue(s) found`));
+  console.log();
+
+  for (const f of findings) {
+    const sevColor = f.severity === 'critical' ? chalk.red.bold
+      : f.severity === 'high' ? chalk.yellow
+      : chalk.blue;
+
+    console.log(`    ${sevColor(`[${f.severity.toUpperCase()}]`)} ${chalk.white(f.name)}`);
+    if (f.line > 0) console.log(chalk.gray(`      Line ${f.line}: ${f.matched}`));
+    else if (f.matched) console.log(chalk.gray(`      ${f.matched}`));
+  }
+  console.log();
+
+  if (summary.critical > 0) {
+    console.log(chalk.red.bold('    ⚠ DO NOT INSTALL this skill — critical security issues detected.'));
+    console.log();
+  }
+}
+
+function getSummary(findings) {
+  return {
+    total: findings.length,
+    critical: findings.filter(f => f.severity === 'critical').length,
+    high: findings.filter(f => f.severity === 'high').length,
+    medium: findings.filter(f => f.severity === 'medium').length,
+  };
+}

package/cli/commands/update-intel.js

@@ -0,0 +1,55 @@
+/**
+ * Update Intel Command
+ * =====================
+ *
+ * Updates the local threat intelligence feed from the remote source.
+ *
+ * USAGE:
+ *   ship-safe update-intel              Fetch latest threat intel
+ *   ship-safe update-intel --url <url>  Use custom feed URL
+ */
+
+import chalk from 'chalk';
+import * as output from '../utils/output.js';
+import { ThreatIntel } from '../utils/threat-intel.js';
+
+export async function updateIntelCommand(options = {}) {
+  console.log();
+  output.header('Ship Safe — Threat Intelligence Update');
+  console.log();
+
+  const currentStats = ThreatIntel.stats();
+  console.log(chalk.gray(`  Current version: ${currentStats.version}`));
+  console.log(chalk.gray(`  Last updated: ${currentStats.updated || 'unknown'}`));
+  console.log(chalk.gray(`  Indicators: ${currentStats.hashes} hashes, ${currentStats.servers} servers, ${currentStats.signatures} signatures`));
+  console.log();
+
+  console.log(chalk.cyan('  Checking for updates...'));
+
+  const result = await ThreatIntel.update(options.url);
+
+  if (result.error) {
+    output.error('Update failed: ' + result.error); // ship-safe-ignore
+    console.log(chalk.gray('  The local seed data will still be used for scanning.'));
+    console.log(chalk.gray('  Check your network connection and try again.'));
+    console.log();
+    return;
+  }
+
+  if (!result.updated) {
+    console.log(chalk.green('  ✔ Already up to date.'));
+    console.log();
+    return;
+  }
+
+  console.log();
+  console.log(chalk.green.bold('  ✔ Threat intelligence updated!'));
+  console.log();
+  console.log(`  ${chalk.gray('Version:')} ${result.oldVersion} → ${chalk.cyan(result.newVersion)}`);
+  if (result.stats) {
+    console.log(`  ${chalk.gray('Malicious skill hashes:')} ${result.stats.hashes}`);
+    console.log(`  ${chalk.gray('Compromised MCP servers:')} ${result.stats.servers}`);
+    console.log(`  ${chalk.gray('Config signatures:')} ${result.stats.signatures}`);
+  }
+  console.log();
+}

package/cli/commands/vibe-check.js

@@ -0,0 +1,276 @@
+/**
+ * Vibe Check Command
+ * ==================
+ *
+ * Fun, emoji-rich security check with shareable results.
+ * Same security scan as `audit`, but with personality.
+ *
+ * USAGE:
+ *   npx ship-safe vibe-check [path]     Run a vibe check
+ *   npx ship-safe vibe-check . --badge  Generate a markdown badge
+ *
+ * OUTPUT:
+ *   Big ASCII art grade, emoji severity indicators,
+ *   "vibes" rating, and a shareable one-liner.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { buildOrchestrator } from '../agents/index.js';
+import { ScoringEngine } from '../agents/scoring-engine.js';
+import { runDepsAudit } from './deps.js';
+import {
+  SECRET_PATTERNS,
+  SKIP_DIRS,
+  SKIP_EXTENSIONS,
+  SKIP_FILENAMES,
+  MAX_FILE_SIZE,
+  loadGitignorePatterns
+} from '../utils/patterns.js';
+import { isHighEntropyMatch, getConfidence } from '../utils/entropy.js';
+import fg from 'fast-glob';
+
+// =============================================================================
+// VIBES DATA
+// =============================================================================
+
+const VIBE_GRADES = {
+  A: {
+    emoji: '🛡️',
+    vibe: 'immaculate',
+    ascii: `
+    ╔═══╗
+    ║ A ║
+    ╚═══╝`,
+    message: 'Your security vibes are IMMACULATE. Ship it! 🚀',
+    color: chalk.green.bold,
+  },
+  B: {
+    emoji: '✅',
+    vibe: 'solid',
+    ascii: `
+    ╔═══╗
+    ║ B ║
+    ╚═══╝`,
+    message: 'Solid vibes. A few things to tighten up, but you\'re in good shape. 💪',
+    color: chalk.cyan.bold,
+  },
+  C: {
+    emoji: '⚠️',
+    vibe: 'mid',
+    ascii: `
+    ╔═══╗
+    ║ C ║
+    ╚═══╝`,
+    message: 'Mid vibes. Some security gaps need attention before you ship. 🔧',
+    color: chalk.yellow.bold,
+  },
+  D: {
+    emoji: '🚨',
+    vibe: 'sketchy',
+    ascii: `
+    ╔═══╗
+    ║ D ║
+    ╚═══╝`,
+    message: 'Sketchy vibes. Serious issues found — fix these before deploying. 🛑',
+    color: chalk.red.bold,
+  },
+  F: {
+    emoji: '💀',
+    vibe: 'cooked',
+    ascii: `
+    ╔═══╗
+    ║ F ║
+    ╚═══╝`,
+    message: 'You are cooked. Critical vulnerabilities everywhere. DO NOT SHIP. 🔥',
+    color: chalk.red.bold,
+  },
+};
+
+const SEV_EMOJI = {
+  critical: '💀',
+  high: '🔴',
+  medium: '🟡',
+  low: '🔵',
+};
+
+// =============================================================================
+// MAIN COMMAND
+// =============================================================================
+
+export async function vibeCheckCommand(targetPath = '.', options = {}) {
+  const absolutePath = path.resolve(targetPath);
+
+  if (!fs.existsSync(absolutePath)) {
+    console.error(chalk.red(`Path does not exist: ${absolutePath}`));
+    process.exit(1);
+  }
+
+  const projectName = path.basename(absolutePath);
+
+  console.log();
+  console.log(chalk.cyan.bold('  🎵 VIBE CHECK 🎵'));
+  console.log(chalk.gray(`  Scanning ${projectName}...`));
+  console.log();
+
+  const startTime = Date.now();
+
+  // ── Secret Scan ──────────────────────────────────────────────────────────
+  const spinner = ora({ text: 'Checking the vibes...', color: 'magenta' }).start();
+
+  const allFiles = await findFiles(absolutePath);
+  const secretFindings = [];
+
+  for (const file of allFiles) {
+    try {
+      const content = fs.readFileSync(file, 'utf-8');
+      const lines = content.split('\n');
+      for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+        const line = lines[lineNum];
+        if (/ship-safe-ignore/i.test(line)) continue;
+        for (const pattern of SECRET_PATTERNS) {
+          pattern.pattern.lastIndex = 0;
+          let match;
+          while ((match = pattern.pattern.exec(line)) !== null) {
+            if (pattern.requiresEntropyCheck && !isHighEntropyMatch(match[0])) continue;
+            secretFindings.push({
+              file, line: lineNum + 1, column: match.index + 1,
+              matched: match[0], severity: pattern.severity,
+              category: pattern.category || 'secrets',
+              rule: pattern.name, title: pattern.name.replace(/_/g, ' '),
+              description: pattern.description,
+              confidence: getConfidence(pattern, match[0]),
+            });
+          }
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  // ── Agent Scan ──────────────────────────────────────────────────────────
+  const orchestrator = buildOrchestrator();
+  const results = await orchestrator.runAll(absolutePath, { quiet: true });
+
+  // ── Dependency Audit ─────────────────────────────────────────────────────
+  let depVulns = [];
+  try {
+    const depResult = await runDepsAudit(absolutePath);
+    depVulns = depResult.vulns || [];
+  } catch { /* skip */ }
+
+  spinner.stop();
+
+  // ── Merge & Score ─────────────────────────────────────────────────────────
+  const seen = new Set();
+  const allFindings = [...secretFindings, ...results.findings].filter(f => {
+    const key = `${f.file}:${f.line}:${f.rule}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  const scoringEngine = new ScoringEngine();
+  const scoreResult = scoringEngine.compute(allFindings, depVulns);
+  const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+  // ── Display ──────────────────────────────────────────────────────────────
+  const grade = VIBE_GRADES[scoreResult.grade.letter] || VIBE_GRADES.F;
+  const score = Math.round(scoreResult.score * 10) / 10;
+
+  const critical = allFindings.filter(f => f.severity === 'critical').length;
+  const high = allFindings.filter(f => f.severity === 'high').length;
+  const medium = allFindings.filter(f => f.severity === 'medium').length;
+  const low = allFindings.filter(f => f.severity === 'low').length;
+
+  // Big grade display
+  console.log(grade.color(grade.ascii));
+  console.log();
+  console.log(grade.color(`  ${grade.emoji}  Score: ${score}/100  |  Vibes: ${grade.vibe.toUpperCase()}`));
+  console.log();
+  console.log(grade.color(`  ${grade.message}`));
+  console.log();
+
+  // Severity breakdown
+  console.log(chalk.white.bold('  Breakdown:'));
+  if (critical > 0) console.log(`    ${SEV_EMOJI.critical} Critical: ${critical}`);
+  if (high > 0) console.log(`    ${SEV_EMOJI.high} High: ${high}`);
+  if (medium > 0) console.log(`    ${SEV_EMOJI.medium} Medium: ${medium}`);
+  if (low > 0) console.log(`    ${SEV_EMOJI.low} Low: ${low}`);
+  if (depVulns.length > 0) console.log(`    📦 Dep CVEs: ${depVulns.length}`);
+  if (allFindings.length === 0 && depVulns.length === 0) {
+    console.log(`    ✨ Zero issues found!`);
+  }
+  console.log(chalk.gray(`    ⏱️  ${duration}s`));
+  console.log();
+
+  // Top 3 issues
+  if (allFindings.length > 0) {
+    console.log(chalk.white.bold('  Top issues to fix:'));
+    const top = allFindings
+      .sort((a, b) => {
+        const order = { critical: 0, high: 1, medium: 2, low: 3 };
+        return (order[a.severity] ?? 4) - (order[b.severity] ?? 4);
+      })
+      .slice(0, 3);
+    for (const f of top) {
+      const rel = path.relative(absolutePath, f.file).replace(/\\/g, '/');
+      console.log(`    ${SEV_EMOJI[f.severity] || '⚪'} ${f.title || f.rule} ${chalk.gray(`(${rel}:${f.line})`)}`);
+    }
+    console.log();
+  }
+
+  // ── Shareable one-liner ──────────────────────────────────────────────────
+  const shareLine = `${grade.emoji} ${projectName}: ${score}/100 (${scoreResult.grade.letter}) — ${grade.vibe} vibes | ${allFindings.length} findings | Scanned with Ship Safe`;
+  console.log(chalk.gray('  Share your vibes:'));
+  console.log(chalk.cyan(`  ${shareLine}`));
+  console.log();
+
+  // ── Badge ─────────────────────────────────────────────────────────────────
+  if (options.badge) {
+    const badgeColor = {
+      A: 'brightgreen', B: 'blue', C: 'yellow', D: 'orange', F: 'red',
+    }[scoreResult.grade.letter] || 'lightgrey';
+    const badgeUrl = `https://img.shields.io/badge/ship--safe-${score}%2F100_${scoreResult.grade.letter}-${badgeColor}`;
+    const badgeMd = `[![Ship Safe Score](${badgeUrl})](https://shipsafecli.com)`;
+
+    console.log(chalk.white.bold('  Markdown badge:'));
+    console.log(chalk.cyan(`  ${badgeMd}`));
+    console.log();
+
+    // Write badge to README if it exists and doesn't have one already
+    const readmePath = path.join(absolutePath, 'README.md');
+    if (fs.existsSync(readmePath)) {
+      const readme = fs.readFileSync(readmePath, 'utf-8');
+      if (!readme.includes('ship--safe')) {
+        console.log(chalk.gray('  Add this badge to your README.md to show off your security score!'));
+      }
+    }
+  }
+
+  process.exit(allFindings.length > 0 || depVulns.length > 0 ? 1 : 0);
+}
+
+// =============================================================================
+// FILE FINDER (reused from CI)
+// =============================================================================
+
+async function findFiles(rootPath) {
+  const globIgnore = Array.from(SKIP_DIRS).map(dir => `**/${dir}/**`);
+  const gitignoreGlobs = loadGitignorePatterns(rootPath);
+  globIgnore.push(...gitignoreGlobs);
+
+  const files = await fg('**/*', {
+    cwd: rootPath, absolute: true, onlyFiles: true, ignore: globIgnore, dot: true,
+  });
+
+  return files.filter(file => {
+    const ext = path.extname(file).toLowerCase();
+    if (SKIP_EXTENSIONS.has(ext)) return false;
+    if (SKIP_FILENAMES.has(path.basename(file))) return false;
+    if (path.basename(file).endsWith('.min.js') || path.basename(file).endsWith('.min.css')) return false;
+    try { if (fs.statSync(file).size > MAX_FILE_SIZE) return false; } catch { return false; }
+    return true;
+  });
+}