node-project-scanner

Professional CLI to scan, run, and build Node.js / JavaScript projects with smart port control.

Short command: nps

Features

• Dashboard TUI — projects list, summary, and detail panels (basic info, package status, scripts, system)
• Fast incremental scan — projects stream in while directories are walked
• Lazy enrichment — filesystem meta, install status, and package stats load per project
• Recursive package.json discovery across monorepos
• Auto-detect builders: Next.js, Vite, Nuxt, SvelteKit, Astro, Remix, Gatsby, Angular, and more
• Detect package manager: npm, pnpm, yarn, bun
• Port detection from .env files and scripts
• Port confirm dialog before launch with kill-port support
• Configurable Node heap memory (M / nps memory)
• Reinit — clean node_modules, build artifacts, and reinstall (U / nps reinit)
• Grouped action menu — Enter opens Run → Package → Tooling → Scripts sections
• Hybrid UI: blessed split-panel TUI with ANSI fallback
• Scriptable subcommands for CI and automation

See CHANGELOG.md for release notes.

Install

npm install -g node-project-scanner

Or run with npx (no install):

npx node-project-scanner scan .
npx node-project-scanner run my-app --port 3005

Or install locally:

git clone <repo>
cd node-project-scanner
npm install
npm link

Usage

Interactive (default)

nps
nps ~/projects
nps . --exclude legacy,archive
nps --no-tui

TUI shortcuts

| Key | Action | |-----|--------| | Enter | Grouped action menu (Run → Package → Tooling → Scripts) | | D | Run dev | | S | Run start | | B | Run build | | I | Install dependencies | | U | Reinit (clean artifacts + reinstall) | | C | CI install (frozen lockfile) | | K | Kill process on project port | | M | Node memory (GB) | | T | Open terminal in project folder (Windows / macOS / Linux) | | E | Open folder in file manager (Explorer / Finder / xdg-open) | | O | More actions (all scripts) | | R | Rescan | | / | Search / filter | | ? | Help | | Q | Quit |

Port confirm dialog (shown before launch when a script uses a port)

| Key | Action | |-----|--------| | Enter | Launch with the port shown in the field | | K | Kill the process using the detected port, then auto-fill that port | | Esc | Cancel |

The port field auto-fills:

• Port free → detected port (e.g. 3000)
• Port in use → next free port (e.g. 3001)
• After kill → original detected port (e.g. 3000), then press Enter to launch

Action menu (Enter on a project)

| Section | Actions | |---------|---------| | Run | dev, start, build | | Package | install, reinit, ci (frozen lockfile) | | Tooling | test, lint, preview, … | | Scripts | any other package.json scripts |

Commands

# Scan + interactive picker (select, run, build) — in a real terminal
nps scan .
npx node-project-scanner scan .

# Table only (no picker)
nps scan . --list-only

# JSON output
nps list . --json
nps scan . --json

# Project info
nps info my-app
nps info web-admin ~/projects

# Run with port override
nps run my-app
nps run my-app --port 3005
nps run my-app --script start -p 4000
nps run my-app --port 3000 --kill-port

# Free a busy port
nps kill-port 3000

# Build
nps build my-app

# Install & CI
nps install my-app
nps reinit my-app
nps run my-app --script reinit
nps run my-app --script ci
nps run my-app --script test

List icons: ✓ deps installed · ○ missing · · checking · name shows folder - package when they differ.

Memory: nps memory or M in TUI — sets Node heap limit (saved in ~/.nps/config.json).

Current tool version: nps --version (see CHANGELOG.md)

Port handling

• Detects PORT from .env, .env.local, .env.development
• Parses --port / -p from npm scripts
• Sets PORT env var and forwards builder-specific CLI flags
• Shows a confirm dialog before launch with port status and URL
• When the detected port is busy, suggests the next free port in basic info and the confirm dialog
• Auto-fills the port field: detected port when free, next free when busy, original port after kill
• Kill stuck processes on a port (nps kill-port, --kill-port, K in TUI, or K in the port confirm dialog)
• Basic info panel shows live port status and updates after kill (available / in use / Use Port)
• Reliable on Windows, macOS, and Linux — finds listeners on 0.0.0.0 and kills the process tree (taskkill on Windows, pkill/kill on Unix)

Local development

npm install
npm start              # launch interactive UI
node bin/nps.mjs scan  # scan current directory
npm link               # link globally as `nps`

Test

npm test

Publish to npm

Prerequisites

• Node.js 18+
• npm account (npm login)
• Package name node-project-scanner available on the registry (or scoped name if you change package.json)

Pre-publish checklist

1. Tests — npm test must pass (runs smoke tests).
2. Version — bump package.json version and add a dated entry in CHANGELOG.md.
3. Docs — README highlights and command list match the release.
4. Dry run — inspect the tarball without publishing:

npm pack --dry-run

Published files are controlled by the files field in package.json: bin, src, README.md, CHANGELOG.md, LICENSE.

Publish

npm test
npm login
npm publish --access public

prepublishOnly runs automatically before publish (node bin/nps.mjs --version) as a quick sanity check.

After publish

npm view node-project-scanner version
npx node-project-scanner@latest --version

Users install globally:

npm install -g node-project-scanner
nps --version

Latest (2.0.1): project list shows folder - package when names differ. 2.0.0: --doctor health check, --update self-update. Full notes in CHANGELOG.md.

Requirements

• Node.js 18+
• Windows, macOS, and Linux
• Works best in a real terminal (TTY) for interactive mode

License

MIT