doctor-dev

Local setup diagnostics for Node.js and TypeScript projects.

doctor-dev is a local CLI that scans the current project folder and prints a practical setup health report.

It is built for the boring problems that waste real debugging time: missing scripts, mixed lock files, unsafe .env files, missing .env.example, weak .gitignore rules, invalid JSON, and basic TypeScript config gaps.

No account. No dashboard. No telemetry. No upload. Just a local terminal report.

Quick Start

Run it in any JavaScript or TypeScript project:

npx doctor-dev

The CLI scans the folder you run it from:

process.cwd()

Example Report

Dev Setup Doctor

Project Summary
  Project: example-project
  Framework: Next.js
  Package manager: npm
  TypeScript: detected with tsconfig.json

Health Score: 78/100

Passed Checks
  [pass] package.json: package.json found and parsed successfully.
  [pass] Package manager: npm lock file found (package-lock.json).

Warnings
  [warning] .env.example: .env.example is missing.
  [warning] test script: package.json is missing a test script.

Failed Checks
  [fail] .env: .env exists but is not ignored by .gitignore.

Recommended Actions
  1. Create .env.example and document required variable names without secret values.
  2. Add a test script if this project has automated tests.
  3. Add .env to .gitignore before committing local environment files.

What It Checks

doctor-dev focuses on setup health for MVP v1.

| Area | Checks | | --- | --- | | package.json | Missing file, invalid JSON, project name, scripts, dependencies | | Framework | Next.js, React/Vite, Nest.js, Expo, Express, React, TypeScript, unknown Node.js | | Package manager | npm, pnpm, yarn, bun lock files | | Scripts | dev, build, start, test | | Environment files | .env, .env.local, .env.example | | .gitignore | node_modules, .env, .env.local, dist, .next | | TypeScript | tsconfig.json, compilerOptions, strict, outDir, rootDir |

Health Score

The score starts at 100.

Warnings and failures subtract points:

| Severity | Penalty | | --- | ---: | | critical | -25 | | high | -15 | | medium | -8 | | low | -3 |

The minimum score is 0.

Privacy And Security

doctor-dev is local-only.

It does not:

• upload files
• call external APIs
• collect telemetry
• send reports anywhere
• print .env values
• modify project files
• run automatic fixes

Environment files are checked by existence only. Secret values are never printed.

Local Development

npm install
npm run dev

Useful project commands:

npm run typecheck
npm test
npm run build
npm run check
npm exec -- doctor-dev

npm run check runs typecheck, tests, and build.

Package Contents

Before publishing a new version:

npm pack --dry-run

The published package is intentionally small: compiled dist/ output, package.json, and this README.

MVP Scope

MVP v1 is a local CLI only.

Not included yet:

• AI analysis
• web dashboard
• backend API
• database
• authentication
• GitHub App or GitHub Action
• telemetry or analytics
• report upload
• automatic fixes
• JSON or markdown export

Those can be added later, but only after the local setup report is solid.

License

MIT