Node Auto Debugger

Scan Node.js/Express/Next.js projects for bugs, security issues, and anti-patterns. Use when debugging a Node.js web app, running code audits, fixing client-...

Security Scan

The skill appears to do what it claims — a local static/heuristic scanner for Node.js/Next.js projects — but it will read project files and can run the project's build scripts, so exercise normal caution when running it on untrusted code.

Purpose & Capability

The name/description, SKILL.md instructions, and the included scripts/auto-debug.js are consistent: the tool scans project files for undefined vars, missing error handling, hydration issues, hardcoded secrets and can optionally run npm run build. There are no declared env vars or unrelated dependencies requested that contradict the stated purpose.

Instruction Scope

The SKILL.md and the script keep scope to the provided project directory, validating source files and package.json and (optionally) running the build. Important operational behaviors: the script recursively reads project files (including package.json and other plaintext files), detects potential secrets by regex, and will write a report file (AUTO-DEBUG-REPORT.md). It also invokes npm run build in the project directory when requested. These behaviors are expected for a code-audit/build-check tool but are sensitive (can surface secrets and will execute project-supplied build scripts).

Install Mechanism

No install spec — instruction-only with a bundled script. No remote downloads or package installs are performed by the skill itself.

Credentials

The skill declares no required environment variables or credentials. The script does not request external secrets; it reads files under the supplied project path to look for hardcoded secrets and configuration. That file-reading is proportional to the stated goal of scanning a project, but it means sensitive data in the project may be exposed in the generated report.

Persistence & Privilege

The skill is not configured as always: true and does not attempt to modify other skills or global agent settings. It writes a project-scoped report file (AUTO-DEBUG-REPORT.md), which is expected behavior for this tool.

Assessment

This tool is internally coherent and appears to do what it says, but it will read your project's source files (including package.json and any plaintext secrets), produce a report on disk, and — if you use the --build option — run npm run build which executes the project's build scripts. Only run it on projects you trust or run it inside an isolated environment (container/VM) when scanning untrusted code. Before sharing the generated AUTO-DEBUG-REPORT.md, review it for any sensitive data it may have flagged. Avoid passing a very large or root path (e.g., '/') as <project-dir> to prevent scanning unintended parts of your filesystem. If you only want static checks, run the script without the --build flag and inspect the script source yourself to confirm behavior.

Node.js Auto Debugger

Automated scanner for Node.js projects — finds bugs across backend, frontend, and config.

Quick Start

node scripts/auto-debug.js <project-dir>

Options:

• --build — Also run npm run build and capture compilation errors

What It Checks

Backend (Express/Fastify)

• Undefined variables — .push() on undeclared variables
• Missing try/catch — async route handlers without error handling
• Hardcoded secrets — API keys, private keys, passwords in source

Frontend (Next.js/React)

• Missing 'use client' — hooks or browser APIs without directive
• Hydration risks — Date.now(), Math.random() in render (should be in useEffect or useState)
• SSR crashes — window/document access outside useEffect
• Missing loading states — wagmi hooks without isLoading/isFetching

Config

• Missing next.config.js — defaults warning
• Missing build script — package.json validation

Output

Report saved to <project>/AUTO-DEBUG-REPORT.md with issues grouped by severity:

• 🔴 Critical — will crash or leak secrets
• 🟠 High — likely runtime errors
• 🟡 Medium — hydration mismatches, missing loading states
• 🟢 Low — minor issues

Exit code: 1 if any critical issues found, 0 otherwise.

Fixing Hydration Issues (Next.js)

Date.now()/new Date() in render:

// ❌ Bad — causes hydration mismatch
const now = Math.floor(Date.now() / 1000);

// ✅ Good — guard with isMounted
const [isMounted, setIsMounted] = useState(false);
useEffect(() => { setIsMounted(true); }, []);
const now = isMounted ? Math.floor(Date.now() / 1000) : 0;

Math.random() in render:

// ❌ Bad — different on server vs client
<div style={{ left: `${Math.random() * 100}%` }} />

// ✅ Good — pre-generate in useState (runs once)
const [particles] = useState(() =>
  Array.from({ length: 10 }, () => ({
    left: `${Math.random() * 100}%`,
  }))
);

window/document access:

// ❌ Bad — crashes during SSR
const width = window.innerWidth;

// ✅ Good — only after mount
const [width, setWidth] = useState(0);
useEffect(() => setWidth(window.innerWidth), []);