NodeDoctor

Your smart Node.js system health doctor.

NodeDoctor scans your machine for Node.js projects, measures node_modules and .next disk usage, detects package managers, and helps you safely clean or reinstall dependencies — from the CLI or an interactive terminal UI.

Repository: github.com/Foisalislambd/NodeDoctor

Table of contents

• Features
• Install
• Quick start
• CLI reference
• Interactive UI (TUI)
• Safety system
• How scanning works
• Development
• Architecture
• Requirements
• License

Features

| Feature | Description | |---------|-------------| | System scan | Finds projects via package.json in common dev folders | | Disk analysis | Async size measurement for node_modules and .next | | Package managers | Detects npm, yarn, pnpm, bun from lockfiles | | Safety layer | Risk levels (LOW / MEDIUM / HIGH), blocked system paths | | Dry-run | Preview destructive actions without changes | | Interactive TUI | Keyboard-driven UI with search, paths, and actions | | Fast scanning | fdir crawler + bounded parallel I/O |

Install

From npm

The package is published as @foisal/nodedoctor (scoped name required — nodedoctor is too similar to the existing node-doctor package on npm).

npm install -g @foisal/nodedoctor

After install, run nodedoctor or nd in your terminal (command names are unchanged).

From source

git clone https://github.com/Foisalislambd/NodeDoctor.git
cd NodeDoctor
npm install
npm run build
npm link

After linking, run nodedoctor or nd (same as the global install).

Quick start

# Open interactive UI (default when you run nodedoctor with no args)
nodedoctor

# Full health check: scan + recommendations
nodedoctor doctor

# Scan default dev folders under your home directory
nodedoctor scan

# Scan specific folders
nodedoctor scan C:\Users\you\projects D:\work

# View analysis from last scan
nodedoctor analyze

# Top 20 largest projects (node_modules + .next)
nodedoctor biggest

# Preview safe cleanup
nodedoctor clean --dry-run

# Clean stale node_modules (90+ days idle)
nodedoctor clean --stale

# Clean stale .next caches
nodedoctor clean --next --stale

# Reinstall a project
nodedoctor reinstall ./my-app

CLI reference

Default command

Running nodedoctor with no subcommand opens the interactive TUI.

Commands

| Command | Description | |---------|-------------| | scan [paths...] | Discover projects and measure node_modules + .next | | analyze | Health summary from cached scan | | biggest | List largest projects by total cache size | | clean | Remove node_modules or .next with safety checks | | reinstall <path> | Delete node_modules and reinstall dependencies | | doctor | Quick scan + recommendations | | ui / tui | Open interactive terminal UI | | cache-path | Show where scan cache is stored | | --help | Show help | | --version | Show version |

scan options

| Flag | Description | |------|-------------| | --all | Include current directory + all default home dev roots |

Examples:

nodedoctor scan
nodedoctor scan ~/projects
nodedoctor scan --all

biggest options

| Flag | Description | |------|-------------| | -n, --limit <number> | Number of projects to show (default: 20) |

clean options

| Flag | Description | |------|-------------| | --dry-run | Preview only — nothing deleted | | --force | Skip confirmations (use carefully) | | --stale | Only caches not modified in 90+ days | | --min-mb <n> | Minimum size in MB | | --all | All eligible non-global, non-high-risk projects | | --next | Clean .next instead of node_modules |

Default behavior (no flags): stale node_modules, non-global, non-high-risk only.

Examples:

nodedoctor clean --dry-run
nodedoctor clean --stale
nodedoctor clean --all --dry-run
nodedoctor clean --next --stale
nodedoctor clean --min-mb 500 --next

reinstall options

| Flag | Description | |------|-------------| | --dry-run | Preview only | | --force | Skip confirmations |

nodedoctor reinstall C:\path\to\project
nodedoctor reinstall ./my-app --dry-run

Interactive UI (TUI)

Launch:

nodedoctor
# or
nodedoctor ui

Screens

1. Welcome — First run; press Enter to scan
2. Projects — Scrollable list with sizes, risk, and paths
3. Actions — Delete node_modules, delete .next, reinstall, details
4. Confirm — Warning + dry-run; HIGH risk requires typing DELETE

Keyboard shortcuts

| Key | Action | |-----|--------| | ↑ / ↓ or j / k | Move selection | | Enter / Space | Open actions menu | | / | Search by name or path | | R | Rescan | | Q / Esc | Quit (from project list) | | Esc | Back (from actions / details / confirm) |

What you see per project

• Total size — node_modules + .next
• Risk — LOW / MEDIUM / HIGH
• Path — Full folder path when selected
• Tags — .next, global where applicable

Safety system

NodeDoctor is built to prevent accidents.

| Risk | Behavior | |------|----------| | LOW | Standard yes/no confirmation (CLI) | | MEDIUM | Confirmation + warnings (outside home, large cache, etc.) | | HIGH | Must type DELETE to confirm; global node_modules blocked |

Automatically blocked

• Windows: Windows, System32, Program Files, etc.
• Global npm prefix node_modules
• System root drives

Always preview first

nodedoctor clean --dry-run
nodedoctor reinstall ./app --dry-run

How scanning works

By default, NodeDoctor scans common folders under your home directory:

Desktop, Documents, Projects, code, GitHub, dev, and similar paths (see src/utils/paths.ts).

For each package.json found (skipping nested node_modules):

1. Detect package manager from lockfiles
2. Measure node_modules size (if present)
3. Measure .next size (if present — Next.js)
4. Assign risk score
5. Cache results locally (nodedoctor cache-path)

nodedoctor scan --all   # Also scan cwd + all default roots

Development

git clone https://github.com/Foisalislambd/NodeDoctor.git
cd NodeDoctor
npm install

| Script | Description | |--------|-------------| | npm run build | Compile TypeScript to dist/ | | npm start | Run CLI (node dist/cli.js) | | npm run dev | Watch + rebuild + launch TUI | | npm run build:watch | Watch + rebuild only | | npm run typecheck | TypeScript check without emit |

Architecture

src/
├── cli.ts                 # CLI entry (commander)
├── cli/commands/          # scan, analyze, clean, doctor, …
├── cli/display.ts         # Terminal tables & summaries
├── core/
│   ├── scanner.ts         # Filesystem crawl
│   ├── project-meta.ts    # Per-project metadata + risk
│   ├── analyzer.ts        # Health summaries
│   ├── disk-usage.ts      # Async directory sizing
│   ├── package-manager.ts # npm/yarn/pnpm/bun
│   └── global-prefix.ts   # Global npm path
├── safety/                # Path guard + confirmations
├── services/actions.ts    # Delete / reinstall
├── store/cache.ts         # Scan persistence (conf)
└── tui/                   # Ink React terminal UI
    ├── App.tsx
    └── components/

Requirements

• Node.js 18+
• npm (for global prefix detection; projects may use yarn/pnpm/bun)

Contributing

Issues and pull requests are welcome on GitHub:

https://github.com/Foisalislambd/NodeDoctor/issues

License

MIT