fchek 1.0.0

package/lib/deps.js

@@ -0,0 +1,374 @@
+'use strict';
+
+/**
+ * deps.js — dependency graph + dead code / unused imports
+ *
+ * Python  → pydeps (graph) + vulture (dead code) + ruff (unused imports)
+ * Rust    → cargo-udeps (unused deps) + cargo-machete
+ * JS/TS   → madge (graph + circular) + depcheck (unused)
+ * Go      → go mod tidy --dry-run + deadcode (golang.org/x/tools/cmd/deadcode)
+ */
+
+const { spawnSync, execSync } = require('child_process');
+const path   = require('path');
+const fs     = require('fs');
+const { output, ok, fail } = require('./output');
+
+const HELP = `
+fchek deps <file_or_dir> [--graph] [--unused-only]
+
+Show dependency graph and detect dead code / unused imports.
+Hard to keep in your head across a whole project — let the tool do it.
+
+Supported:
+  .py / dir    → pydeps (graph) + vulture (dead code) + ruff (unused imports)
+  .rs / Cargo  → cargo-udeps + cargo-machete (unused Cargo.toml deps)
+  .js / .ts    → madge (circular deps) + depcheck (unused npm packages)
+  go.mod / .go → go mod tidy + deadcode
+
+Options:
+  --graph        Also output the dependency graph (can be large)
+  --unused-only  Show only unused/dead items, skip full graph
+
+Examples:
+  fchek deps main.py
+  fchek deps src/
+  fchek deps .           (Rust or JS project in cwd)
+  fchek deps . --unused-only
+`.trim();
+
+const DEFAULT_TIMEOUT = 120_000;
+
+function commandExists(cmd) {
+  try {
+    execSync(process.platform === 'win32' ? `where ${cmd}` : `which ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+// ─── Python ──────────────────────────────────────────────────────────────────
+
+function depsPython(target, showGraph, unusedOnly, timeoutMs) {
+  const py = commandExists('python3') ? 'python3' : 'python';
+  const results = { lang: 'python', target, unused_imports: [], dead_code: [], graph: null };
+  const tools_used = [];
+
+  // 1. ruff — unused imports (fast, always available if ruff installed)
+  if (commandExists('ruff')) {
+    tools_used.push('ruff');
+    const ruffRes = spawnSync(
+      'ruff', ['check', '--select=F401', '--output-format=json', target],
+      { encoding: 'utf8', timeout: 30_000 }
+    );
+    try {
+      const issues = JSON.parse(ruffRes.stdout || '[]');
+      results.unused_imports = issues.map(i => ({
+        file:    i.filename,
+        line:    i.location?.row,
+        symbol:  i.message,
+        code:    i.code,
+      }));
+    } catch {}
+  }
+
+  // 2. vulture — dead code detection
+  if (commandExists('vulture')) {
+    tools_used.push('vulture');
+    const vRes = spawnSync('vulture', [target, '--min-confidence=60'], {
+      encoding: 'utf8', timeout: timeoutMs
+    });
+    const lines = (vRes.stdout || '').split('\n').filter(Boolean);
+    results.dead_code = lines.slice(0, 40).map(line => {
+      // Format: path/file.py:42: unused function 'foo' (60% confidence)
+      const m = line.match(/^(.+):(\d+):\s+(.+)$/);
+      return m ? { file: m[1], line: parseInt(m[2]), issue: m[3] } : { raw: line };
+    });
+  } else {
+    results.dead_code_note = 'vulture not found. Install: pip install vulture';
+  }
+
+  // 3. pydeps — full import graph (optional, slow)
+  if (showGraph && commandExists('pydeps')) {
+    tools_used.push('pydeps');
+    const outJson = '/tmp/fchek_pydeps.json';
+    const pRes = spawnSync(
+      'pydeps', [target, '--show-deps', '--no-output', '--json', outJson],
+      { encoding: 'utf8', timeout: timeoutMs }
+    );
+    try {
+      if (fs.existsSync(outJson)) {
+        results.graph = JSON.parse(fs.readFileSync(outJson, 'utf8'));
+        try { fs.unlinkSync(outJson); } catch {}
+      }
+    } catch {}
+  } else if (showGraph) {
+    results.graph_note = 'pydeps not found. Install: pip install pydeps';
+  }
+
+  output(ok({ ...results, tools_used }));
+}
+
+// ─── Rust ─────────────────────────────────────────────────────────────────────
+
+function depsRust(target, showGraph, timeoutMs) {
+  if (!commandExists('cargo')) {
+    return output(fail('cargo not found. Install Rust: https://rustup.rs'));
+  }
+
+  const cwd = path.resolve(target === '.' ? process.cwd() : target);
+  const tools_used = [];
+  const results = { lang: 'rust', target: cwd, unused_deps: [], dead_code: [] };
+
+  // cargo-machete — much faster than cargo-udeps, no nightly needed
+  if (commandExists('cargo-machete') || (() => {
+    const r = spawnSync('cargo', ['machete', '--version'], { encoding: 'utf8', timeout: 5000 });
+    return r.status === 0;
+  })()) {
+    tools_used.push('cargo-machete');
+    const res = spawnSync('cargo', ['machete'], { encoding: 'utf8', cwd, timeout: timeoutMs });
+    const raw = (res.stdout || '') + (res.stderr || '');
+    // Parse: "The following packages are not used: serde, regex"
+    const m = raw.match(/not used[:\s]+([^\n]+)/i);
+    if (m) {
+      results.unused_deps = m[1].split(/,\s*/).map(s => s.trim()).filter(Boolean);
+    }
+    results.machete_raw = raw.slice(0, 2000);
+  } else {
+    results.unused_deps_note = 'cargo-machete not found. Install: cargo install cargo-machete';
+  }
+
+  // cargo-udeps — deeper analysis (requires nightly)
+  if (commandExists('cargo') && !results.unused_deps.length) {
+    const udepsRes = spawnSync('cargo', ['+nightly', 'udeps'], { encoding: 'utf8', cwd, timeout: timeoutMs });
+    if (udepsRes.status === 0) {
+      tools_used.push('cargo-udeps');
+      results.udeps_raw = (udepsRes.stdout || '').slice(0, 2000);
+    }
+  }
+
+  // Dependency graph via cargo tree
+  if (showGraph) {
+    tools_used.push('cargo-tree');
+    const treeRes = spawnSync('cargo', ['tree', '--prefix=depth'], { encoding: 'utf8', cwd, timeout: 30_000 });
+    results.graph_raw = (treeRes.stdout || '').slice(0, 5000);
+  }
+
+  output(ok({ ...results, tools_used }));
+}
+
+// ─── JS/TS ────────────────────────────────────────────────────────────────────
+
+function depsJs(target, showGraph, timeoutMs) {
+  const cwd = path.resolve(target === '.' ? process.cwd() : target);
+  const tools_used = [];
+  const results = { lang: 'javascript', target: cwd };
+
+  // madge — import graph + circular dependency detection
+  if (commandExists('madge')) {
+    tools_used.push('madge');
+
+    // Circular deps
+    const circRes = spawnSync('madge', ['--circular', '--json', cwd], {
+      encoding: 'utf8', timeout: timeoutMs
+    });
+    try {
+      const circular = JSON.parse(circRes.stdout || '[]');
+      results.circular_deps = circular.slice(0, 20);
+      results.circular_count = circular.length;
+    } catch {
+      results.circular_deps = [];
+    }
+
+    // Full graph (optional)
+    if (showGraph) {
+      const graphRes = spawnSync('madge', ['--json', cwd], { encoding: 'utf8', timeout: timeoutMs });
+      try {
+        results.graph = JSON.parse(graphRes.stdout || '{}');
+      } catch {}
+    }
+  } else {
+    results.circular_deps_note = 'madge not found. Install: npm install -g madge';
+  }
+
+  // depcheck — unused npm packages
+  if (commandExists('depcheck')) {
+    tools_used.push('depcheck');
+    const dcRes = spawnSync('depcheck', ['--json'], { encoding: 'utf8', cwd, timeout: timeoutMs });
+    try {
+      const dc = JSON.parse(dcRes.stdout || '{}');
+      results.unused_packages    = dc.dependencies || [];
+      results.unused_dev_packages = dc.devDependencies || [];
+      results.missing_packages   = Object.keys(dc.missing || {});
+    } catch {}
+  } else {
+    results.unused_packages_note = 'depcheck not found. Install: npm install -g depcheck';
+  }
+
+  output(ok({ ...results, tools_used }));
+}
+
+// ─── C# / .NET ────────────────────────────────────────────────────────────────
+
+function depsCSharp(target, timeoutMs) {
+  if (!commandExists('dotnet')) {
+    return output(fail('dotnet not found. Install .NET SDK: https://dotnet.microsoft.com/download'));
+  }
+
+  const cwd = path.resolve(fs.statSync(target).isDirectory() ? target : path.dirname(target));
+
+  // Find .csproj or .sln
+  let projDir = cwd;
+  let foundProj = false;
+  for (let i = 0; i < 6; i++) {
+    try {
+      if (fs.readdirSync(projDir).some(f => f.endsWith('.csproj') || f.endsWith('.sln'))) {
+        foundProj = true;
+        break;
+      }
+    } catch {}
+    const parent = path.dirname(projDir);
+    if (parent === projDir) break;
+    projDir = parent;
+  }
+
+  if (!foundProj) {
+    return output(fail(
+      'No .csproj or .sln found.\n' +
+      'Create a project first: dotnet new console -o MyApp\n' +
+      'Then run: fchek deps <project_folder>'
+    ));
+  }
+
+  const tools_used = [];
+  const results = { lang: 'csharp', target: projDir };
+
+  // dotnet list package -- lists all NuGet packages
+  const listRes = spawnSync('dotnet', ['list', projDir, 'package'], {
+    encoding: 'utf8', cwd: projDir, timeout: 30000,
+  });
+  tools_used.push('dotnet list package');
+
+  const packages = [];
+  const lines = (listRes.stdout || '').split('\n');
+  for (const line of lines) {
+    // Format: "   > PackageName    requestedVersion    resolvedVersion"
+    const m = line.match(/>\s+(\S+)\s+(\S+)\s+(\S+)/);
+    if (m) packages.push({ name: m[1], requested: m[2], resolved: m[3] });
+  }
+  results.packages = packages;
+  results.package_count = packages.length;
+
+  // dotnet list package --outdated
+  const outdatedRes = spawnSync('dotnet', ['list', projDir, 'package', '--outdated'], {
+    encoding: 'utf8', cwd: projDir, timeout: 60000,
+  });
+  const outdated = [];
+  for (const line of (outdatedRes.stdout || '').split('\n')) {
+    const m = line.match(/>\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)/);
+    if (m) outdated.push({ name: m[1], current: m[3], latest: m[4] });
+  }
+  results.outdated_packages = outdated;
+  results.outdated_count = outdated.length;
+
+  // dotnet list package --vulnerable (requires .NET 7+)
+  const vulnRes = spawnSync('dotnet', ['list', projDir, 'package', '--vulnerable'], {
+    encoding: 'utf8', cwd: projDir, timeout: 60000,
+  });
+  const vulnerable = [];
+  for (const line of (vulnRes.stdout || '').split('\n')) {
+    const m = line.match(/>\s+(\S+)\s+(\S+)\s+(\S+)/);
+    if ((m && line.toLowerCase().includes('critical')) || line.toLowerCase().includes('high')) {
+      vulnerable.push({ raw: line.trim() });
+    }
+  }
+  results.vulnerable_packages = vulnerable;
+
+  output(ok({ ...results, tools_used }));
+}
+
+// ─── Go ───────────────────────────────────────────────────────────────────────
+
+function depsGo(target, timeoutMs) {
+  if (!commandExists('go')) {
+    return output(fail('go not found. Install: https://go.dev'));
+  }
+
+  const cwd = path.resolve(target === '.' ? process.cwd() : path.dirname(target));
+  const tools_used = ['go mod'];
+  const results = { lang: 'go', target: cwd };
+
+  // go mod tidy --dry-run (Go 1.21+)
+  const tidyRes = spawnSync('go', ['mod', 'tidy', '-v'], { encoding: 'utf8', cwd, timeout: timeoutMs });
+  results.mod_tidy_output = ((tidyRes.stdout || '') + (tidyRes.stderr || '')).slice(0, 2000);
+
+  // go list -m all — list all modules
+  const listRes = spawnSync('go', ['list', '-m', 'all'], { encoding: 'utf8', cwd, timeout: 30_000 });
+  results.all_modules = (listRes.stdout || '').trim().split('\n').filter(Boolean).slice(0, 50);
+
+  // deadcode tool (golang.org/x/tools/cmd/deadcode)
+  if (commandExists('deadcode')) {
+    tools_used.push('deadcode');
+    const dcRes = spawnSync('deadcode', ['-test', './...'], { encoding: 'utf8', cwd, timeout: timeoutMs });
+    results.dead_functions = ((dcRes.stdout || '') + (dcRes.stderr || '')).trim().split('\n').filter(Boolean).slice(0, 30);
+  } else {
+    results.dead_code_note = 'deadcode not found. Install: go install golang.org/x/tools/cmd/deadcode@latest';
+  }
+
+  output(ok({ ...results, tools_used }));
+}
+
+// ─── Entry point ─────────────────────────────────────────────────────────────
+
+async function run(args) {
+  if (args.length === 0 || args[0] === '--help') {
+    console.log(HELP);
+    return;
+  }
+
+  const target      = args[0];
+  const showGraph   = args.includes('--graph');
+
+  if (!fs.existsSync(target)) {
+    return output(fail(`Not found: ${target}`));
+  }
+
+  const ext  = path.extname(target).toLowerCase();
+  const stat = fs.statSync(target);
+  const isDir = stat.isDirectory();
+
+  // Detect language
+  if (ext === '.py' || (isDir && fs.existsSync(path.join(target, '__init__.py')))) {
+    return depsPython(target, showGraph, false, DEFAULT_TIMEOUT);
+  }
+  if (ext === '.rs' || isDir && fs.existsSync(path.join(target, 'Cargo.toml')) || target === '.') {
+    // Check for Cargo.toml first
+    if (fs.existsSync(path.join(path.resolve(target), 'Cargo.toml')) || ext === '.rs') {
+      return depsRust(target, showGraph, DEFAULT_TIMEOUT);
+    }
+  }
+  if (['.js', '.ts', '.mjs'].includes(ext) || (isDir && fs.existsSync(path.join(target, 'package.json')))) {
+    return depsJs(target, showGraph, DEFAULT_TIMEOUT);
+  }
+  if (ext === '.go' || (isDir && fs.existsSync(path.join(target, 'go.mod')))) {
+    return depsGo(target, DEFAULT_TIMEOUT);
+  }
+  if (ext === '.cs' || (isDir && fs.readdirSync(path.resolve(target)).some(f => f.endsWith('.csproj') || f.endsWith('.sln')))) {
+    return depsCSharp(target, DEFAULT_TIMEOUT);
+  }
+  // Fallback for "." — try all
+  if (target === '.') {
+    const cwd = process.cwd();
+    if (fs.existsSync(path.join(cwd, 'Cargo.toml')))   return depsRust('.', showGraph, DEFAULT_TIMEOUT);
+    if (fs.existsSync(path.join(cwd, 'package.json'))) return depsJs('.', showGraph, DEFAULT_TIMEOUT);
+    if (fs.existsSync(path.join(cwd, 'go.mod')))       return depsGo('.', DEFAULT_TIMEOUT);
+    if (fs.existsSync(path.join(cwd, 'global.json')) || fs.readdirSync(cwd).some(f => f.endsWith('.csproj') || f.endsWith('.sln'))) {
+      return depsCSharp('.', DEFAULT_TIMEOUT);
+    }
+    // Python: look for py files
+    return depsPython('.', showGraph, false, DEFAULT_TIMEOUT);
+  }
+
+  output(fail(`Cannot detect language for: ${target}. Supported: .py .rs .js .ts .go .cs`));
+}
+
+module.exports = { run };

package/lib/docker.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const { output, ok, fail } = require('./output');
+
+const HELP = `
+fchek docker list [--all]
+fchek docker logs <container> [--tail=<num>]
+
+Docker container assistant.
+list: Show running containers. Use --all to show all containers.
+logs: Fetch logs of a container. Customize tail length using --tail (default 50).
+`.trim();
+
+function isDockerInstalled() {
+  try {
+    execSync('docker --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function run(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(HELP);
+    return;
+  }
+
+  if (!isDockerInstalled()) {
+    output(fail('Docker is not installed or not in PATH', 'docker'));
+    return;
+  }
+
+  const action = args[0];
+  if (!action || !['list', 'logs'].includes(action)) {
+    output(fail('Invalid docker command. Use "list" or "logs"', 'docker'));
+    return;
+  }
+
+  if (action === 'list') {
+    const isAll = args.includes('--all') || args.includes('-a');
+    const cmd = `docker ps ${isAll ? '-a' : ''} --format "{{json .}}"`;
+    try {
+      const out = execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+      const containers = out.split('\n')
+        .map(line => line.trim())
+        .filter(Boolean)
+        .map(line => {
+          try {
+            return JSON.parse(line);
+          } catch {
+            return { raw: line };
+          }
+        });
+      output(ok({ containers }, 'docker'));
+    } catch (err) {
+      output(fail(`Failed to list containers (is Docker daemon running?): ${err.message}`, 'docker'));
+    }
+  } else if (action === 'logs') {
+    const container = args[1];
+    if (!container || container.startsWith('-')) {
+      output(fail('Please specify a container name or ID', 'docker'));
+      return;
+    }
+
+    let tail = '50';
+    for (const arg of args) {
+      if (arg.startsWith('--tail=')) {
+        tail = arg.split('=')[1];
+      }
+    }
+
+    const cmd = `docker logs --tail ${tail} ${container}`;
+    try {
+      const out = execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+      output(ok({ container, logs: out }, 'docker'));
+    } catch (err) {
+      output(fail(`Failed to get logs for container ${container}: ${err.message}`, 'docker'));
+    }
+  }
+}
+
+module.exports = { run };

package/lib/doctor.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const os   = require('os');
+const { output, ok } = require('./output');
+
+const HELP = `
+fchek doctor
+
+Check the environment: Node.js version, OS, and all external tools needed by fchek.
+Run this first to see what is installed and what needs to be set up.
+`.trim();
+
+const TOOLS = [
+  // ── profile ──────────────────────────────────────────
+  { name: 'py-spy',      cmd: 'py-spy --version',       for: 'profile (Python)',    install: 'pip install py-spy',                platform: ['linux','darwin','win32'] },
+  { name: 'python3',     cmd: 'python3 --version',      for: 'profile / coverage',  install: 'https://python.org',               platform: ['linux','darwin','win32'], alt: 'python --version' },
+  { name: 'valgrind',    cmd: 'valgrind --version',      for: 'profile (C/C++)',     install: 'apt install valgrind',              platform: ['linux'] },
+
+  // ── race ─────────────────────────────────────────────
+  { name: 'gcc',         cmd: 'gcc --version',           for: 'race / coverage (C)', install: 'apt install build-essential',       platform: ['linux','darwin'] },
+  { name: 'g++',         cmd: 'g++ --version',           for: 'race (C++)',          install: 'apt install build-essential',       platform: ['linux','darwin'] },
+  { name: 'clang++',     cmd: 'clang++ --version',       for: 'race (macOS/clang)',  install: 'xcode-select --install',            platform: ['darwin'] },
+
+  // ── coverage ─────────────────────────────────────────
+  { name: 'coverage',    cmd: 'coverage --version',      for: 'coverage (Python)',   install: 'pip install coverage',              platform: ['linux','darwin','win32'] },
+  { name: 'gcov',        cmd: 'gcov --version',          for: 'coverage (C/C++)',    install: 'apt install gcc',                   platform: ['linux'] },
+  { name: 'c8',          cmd: 'c8 --version',            for: 'coverage (JS/TS)',    install: 'npm install -g c8',                 platform: ['linux','darwin','win32'] },
+
+  // ── bench ─────────────────────────────────────────────
+  { name: 'node',        cmd: 'node --version',          for: 'bench (JS)',          install: 'https://nodejs.org',               platform: ['linux','darwin','win32'] },
+  { name: 'ts-node',     cmd: 'ts-node --version',       for: 'bench (TypeScript)',  install: 'npm install -g ts-node',            platform: ['linux','darwin','win32'] },
+
+  // ── lint ─────────────────────────────────────────────
+  { name: 'ruff',        cmd: 'ruff --version',          for: 'lint (Python)',       install: 'pip install ruff',                  platform: ['linux','darwin','win32'] },
+  { name: 'eslint',      cmd: 'eslint --version',        for: 'lint (JS/TS)',        install: 'npm install -g eslint',             platform: ['linux','darwin','win32'] },
+  { name: 'clang-format',cmd: 'clang-format --version',  for: 'lint (C/C++)',        install: 'apt install clang-format',          platform: ['linux','darwin'] },
+  { name: 'clang-tidy',  cmd: 'clang-tidy --version',    for: 'lint (C/C++)',        install: 'apt install clang-tidy',            platform: ['linux','darwin'] },
+  { name: 'gofmt',       cmd: 'gofmt --help',            for: 'lint (Go)',           install: 'https://go.dev',                   platform: ['linux','darwin','win32'] },
+
+  // ── deps ─────────────────────────────────────────────
+  { name: 'vulture',     cmd: 'vulture --version',       for: 'deps (Python dead code)', install: 'pip install vulture',           platform: ['linux','darwin','win32'] },
+  { name: 'pydeps',      cmd: 'pydeps --help',           for: 'deps graph (Python)', install: 'pip install pydeps',               platform: ['linux','darwin','win32'] },
+  { name: 'madge',       cmd: 'madge --version',         for: 'deps (JS/TS circular)', install: 'npm install -g madge',           platform: ['linux','darwin','win32'] },
+  { name: 'depcheck',    cmd: 'depcheck --version',      for: 'deps unused (JS/TS)', install: 'npm install -g depcheck',          platform: ['linux','darwin','win32'] },
+  { name: 'deadcode',    cmd: 'deadcode --help',         for: 'deps dead code (Go)', install: 'go install golang.org/x/tools/cmd/deadcode@latest', platform: ['linux','darwin','win32'] },
+
+  // ── fuzz ─────────────────────────────────────────────
+  { name: 'afl-fuzz',    cmd: 'afl-fuzz --help',        for: 'fuzz (C/C++)',        install: 'apt install afl++',                 platform: ['linux','darwin'] },
+  { name: 'cargo',       cmd: 'cargo --version',        for: 'bench/coverage/fuzz (Rust)', install: 'https://rustup.rs',         platform: ['linux','darwin','win32'] },
+
+  // ── goto / LSP ────────────────────────────────────────
+  { name: 'clangd',      cmd: 'clangd --version',       for: 'goto (C/C++ LSP)',    install: 'apt install clangd',               platform: ['linux','darwin','win32'] },
+  { name: 'rust-analyzer', cmd: 'rust-analyzer --version', for: 'goto (Rust LSP)', install: 'rustup component add rust-analyzer', platform: ['linux','darwin','win32'] },
+  { name: 'pyright',     cmd: 'pyright --version',      for: 'goto (Python LSP)',   install: 'pip install pyright',              platform: ['linux','darwin','win32'] },
+  { name: 'typescript-language-server', cmd: 'typescript-language-server --version', for: 'goto (TS/JS LSP)', install: 'npm install -g typescript-language-server typescript', platform: ['linux','darwin','win32'] },
+
+  // ── C# / .NET ─────────────────────────────────────────────────────────────────
+  { name: 'dotnet',     cmd: 'dotnet --version',    for: 'run / convention / context (C#)', install: 'https://dotnet.microsoft.com/download', platform: ['linux','darwin','win32'] },
+  { name: 'omnisharp',  cmd: 'omnisharp --version', for: 'goto (C# LSP)',                   install: 'dotnet tool install -g omnisharp',      platform: ['linux','darwin','win32'], alt: 'OmniSharp --version' },
+  { name: 'reportgenerator', cmd: 'reportgenerator --version', for: 'coverage HTML report (C#)', install: 'dotnet tool install -g dotnet-reportgenerator-globaltool', platform: ['linux','darwin','win32'] },
+
+  // ── secrets ───────────────────────────────────────────────────────────────────
+  { name: 'gitleaks',   cmd: 'gitleaks version',    for: 'secrets (best coverage)',  install: 'https://github.com/gitleaks/gitleaks#installing', platform: ['linux','darwin','win32'] },
+  { name: 'trufflehog', cmd: 'trufflehog --version',for: 'secrets (alternative)',    install: 'pip install trufflehog',       platform: ['linux','darwin','win32'] },
+
+  // ── run ───────────────────────────────────────────────────────────────────────
+  { name: 'ts-node',    cmd: 'ts-node --version',   for: 'run (TypeScript files)',   install: 'npm install -g ts-node',       platform: ['linux','darwin','win32'] },
+  { name: 'ruby',       cmd: 'ruby --version',      for: 'run (.rb files)',          install: 'https://www.ruby-lang.org',    platform: ['linux','darwin','win32'] },
+
+  // ── Windows tools ─────────────────────────────────────────────────────────────
+  { name: 'powershell', cmd: 'powershell -Command "$PSVersionTable.PSVersion.ToString()"', for: 'screenshot/launch/winlog/registry/process', install: 'Built-in on Windows', platform: ['win32'] },
+  { name: 'dotnet',     cmd: 'dotnet --version',    for: 'run/lint/coverage (C#/.NET)',    install: 'https://dotnet.microsoft.com/download', platform: ['linux','darwin','win32'] },
+  { name: 'reportgenerator', cmd: 'reportgenerator --version', for: 'coverage HTML (C#)', install: 'dotnet tool install -g dotnet-reportgenerator-globaltool', platform: ['linux','darwin','win32'] },
+  { name: 'git',        cmd: 'git --version',       for: 'git status/diff/commit',        install: 'https://git-scm.com',                   platform: ['linux','darwin','win32'] },
+
+  // ── deps-check ────────────────────────────────────────────────────────────────
+  // deps-check uses https module directly (no external tool needed)
+];
+
+function checkTool(tool, platform) {
+  if (!tool.platform.includes(platform)) {
+    return { name: tool.name, status: 'skipped', reason: `Not applicable on ${platform}`, for: tool.for };
+  }
+
+  let version = null;
+  let found   = false;
+
+  for (const cmd of [tool.cmd, tool.alt].filter(Boolean)) {
+    try {
+      const out = execSync(cmd, { encoding: 'utf8', stdio: ['ignore','pipe','ignore'], timeout: 5000 });
+      version = out.trim().split('\n')[0].slice(0, 80);
+      found   = true;
+      break;
+    } catch {}
+  }
+
+  return {
+    name:    tool.name,
+    status:  found ? 'ok' : 'missing',
+    version: version || null,
+    for:     tool.for,
+    install: found ? undefined : tool.install,
+  };
+}
+
+async function run(args) {
+  if (args[0] === '--help') { console.log(HELP); return; }
+
+  const platform = os.platform();
+  const nodeVer  = process.version;
+  const nodeMajor = parseInt(nodeVer.slice(1), 10);
+
+  const results  = TOOLS.map(t => checkTool(t, platform));
+  const missing  = results.filter(r => r.status === 'missing');
+  const present  = results.filter(r => r.status === 'ok');
+  const skipped  = results.filter(r => r.status === 'skipped');
+
+  const platformWarnings = [];
+  if (platform === 'win32') {
+    platformWarnings.push('race and fuzz (C/C++) require WSL on Windows. Install: wsl --install');
+    platformWarnings.push('valgrind and afl++ are not available on native Windows.');
+    platformWarnings.push('AFL++ fuzzing: use WSL or Docker.');
+  }
+  if (platform === 'darwin') {
+    platformWarnings.push('valgrind does not support macOS >= 10.15. Use AddressSanitizer via clang for race detection.');
+    platformWarnings.push('AFL++ on macOS may require: brew install afl++ and SIP adjustments.');
+  }
+
+  output(ok({
+    environment: {
+      platform,
+      node_version: nodeVer,
+      node_ok:      nodeMajor >= 18,
+      node_warning: nodeMajor < 18 ? 'Node.js >= 18 required' : null,
+    },
+    tools:   results,
+    summary: {
+      total:   results.length,
+      ok:      present.length,
+      missing: missing.length,
+      skipped: skipped.length,
+    },
+    platform_warnings: platformWarnings,
+    missing_installs:  missing.map(m => ({ tool: m.name, for: m.for, install: m.install })),
+  }));
+}
+
+module.exports = { run };