{"_id":"@aman-gupta-16/env-doctor","name":"@aman-gupta-16/env-doctor","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aman-gupta-16/env-doctor","version":"1.0.0","description":"Node.js Environment Diagnostic CLI to scan projects, discover configuration requirements, validate env vars, detect inconsistencies, and explain problems.","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","bin":{"env-doctor":"bin/env-doctor.js"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","prepublishOnly":"npm run build && npm test"},"keywords":["env","environment","dotenv","diagnostics","cli","validation","docker","ci","node-version","developer-tools"],"author":{"name":"Antigravity Team"},"license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"fast-glob":"^3.3.3","semver":"^7.7.1"},"devDependencies":{"@types/node":"^22.13.5","@types/semver":"^7.5.8","tsup":"^8.4.0","typescript":"^5.7.3","vitest":"^3.0.7"},"gitHead":"54977cd32486ba40817bc20c052c78f3a0e3d0bd","_id":"@aman-gupta-16/env-doctor@1.0.0","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-404GGZ6Bqge+Vn0HqfSfevLznGT1YXZCS1E6ip9+E9fMELOqT5Q1GySo9/6+UYQ1wgRNhKb0lDffQi7A4MQCLA==","shasum":"33ccf8bf12dc9a4f9b25bc50d6c0739117dec099","tarball":"https://registry.npmjs.org/@aman-gupta-16/env-doctor/-/env-doctor-1.0.0.tgz","fileCount":16,"unpackedSize":451535,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGAGDcTcbXaqHQygT0FWfTPBvske7CrVcTlykPo0H5KcAiAfjnRBs8Krk1yVSNUFBU4oOULC8SsSqeHJNDa5QRuELA=="}]},"_npmUser":{"name":"aman-gupta-16","email":"aman.gupta.work.16@gmail.com"},"directories":{},"maintainers":[{"name":"aman-gupta-16","email":"aman.gupta.work.16@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/env-doctor_1.0.0_1788353541934_0.9634744411488565"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T12:52:21.787Z","1.0.0":"2026-09-02T12:52:22.083Z","modified":"2026-09-02T12:52:22.309Z"},"maintainers":[{"name":"aman-gupta-16","email":"aman.gupta.work.16@gmail.com"}],"description":"Node.js Environment Diagnostic CLI to scan projects, discover configuration requirements, validate env vars, detect inconsistencies, and explain problems.","keywords":["env","environment","dotenv","diagnostics","cli","validation","docker","ci","node-version","developer-tools"],"author":{"name":"Antigravity Team"},"license":"MIT","readme":"# 🩺 `env-doctor` — Node.js Environment Diagnostic CLI\n\n> Diagnose why a Node.js project works on one machine/environment but fails on another.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)\n\n`env-doctor` scans your project codebase, configuration files, Docker specifications, and CI workflows to discover environment variable requirements, validate constraints, detect lockfile conflicts, check Node.js version alignment, and explain problems in a clean, developer-friendly way.\n\n---\n\n## 1. What `env-doctor` Does\n\n`env-doctor` goes far beyond a basic `.env` parser. It performs full project diagnostics by analyzing:\n\n- **Source Code**: AST/Regex scanning for `process.env.VAR`, `process.env['VAR']`, `const { VAR } = process.env`, and `import.meta.env.VAR` across JS, TS, JSX, TSX, Vue, and Svelte files.\n- **Environment Files**: Interrogates `.env`, `.env.local`, `.env.development`, `.env.production`, `.env.test`, `.env.example`, `.env.sample`.\n- **Node.js Engine Verification**: Validates runtime Node.js version against `package.json` (`engines.node`), `.nvmrc`, and `.node-version`.\n- **Package Manager Conflict Detection**: Identifies lockfile clashes (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`).\n- **Docker Integration**: Extracts environment dependencies from `Dockerfile` and `docker-compose.yml` / `compose.yaml`.\n- **CI Workflow Diagnostics**: Audits GitHub Actions (`.github/workflows/*.yml`), GitLab CI (`.gitlab-ci.yml`), and CircleCI (`.circleci/config.yml`).\n- **Secret Protection**: Guaranteed zero secret disclosure. Values are never printed or stored.\n\n---\n\n## 2. Why It Exists\n\n* \"It works on my machine!\" is often caused by subtle missing environment variables, mismatched Node engines, or conflicting lockfiles.\n* Onboarding new developers to a project frequently breaks due to undocumented `.env` requirements.\n* CI pipelines fail unexpectedly when secrets or environment variables aren't documented in `.env.example`.\n\n`env-doctor` provides instant, local, offline diagnosis to fix environment issues before they hit production.\n\n---\n\n## 3. Installation\n\nRun directly with `npx` (no installation required):\n\n```bash\nnpx env-doctor\n```\n\nOr install globally / as a dev dependency:\n\n```bash\n# Global installation\nnpm install -g env-doctor\n\n# Or per project\nnpm install --save-dev env-doctor\n```\n\n---\n\n## 4. Quick Start\n\nRun `env-doctor` in the root of your Node.js project:\n\n```bash\nnpx env-doctor\n```\n\n### CLI Options\n\n| Flag | Short | Description |\n| --- | --- | --- |\n| `--help` | `-h` | Display help menu |\n| `--version` | `-v` | Display package version |\n| `--json` | | Output machine-readable JSON report |\n| `--ci` | | CI mode: concise output, no colors, exits non-zero on errors |\n| `--verbose` | | Show detailed line numbers and callsite traces |\n| `--fix` | | Safely apply auto-fixes (e.g. sync missing keys into `.env.example`) |\n| `--cwd <path>` | | Target directory to analyze (defaults to `process.cwd()`) |\n\n---\n\n## 5. Example Output\n\n```text\n🩺 Environment Doctor\n\nProject\n────────────────────────────────────\nName          my-api\nNode.js       22.14.0\nPackage mgr   npm\nEnvironment   development\n\nEnvironment Variables\n────────────────────────────────────\n✓ DATABASE_URL\n✓ JWT_SECRET\n✗ REDIS_URL             Missing\n⚠ AWS_REGION            Defined but unused\n\nConfiguration\n────────────────────────────────────\n✓ .env\n⚠ .env differs from .env.example\n\nDependencies\n────────────────────────────────────\n✓ package.json\n✓ node_modules\n\n────────────────────────────────────\n\n2 problems found\n1 warning\n\nRun `env-doctor --verbose` for details.\n```\n\n---\n\n## 6. Supported Environment Files\n\n`env-doctor` automatically discovers and respects:\n- `.env`\n- `.env.local`\n- `.env.development`\n- `.env.production`\n- `.env.test`\n- `.env.example`\n- `.env.sample`\n\n---\n\n## 7. `.env.example` Validation & `--fix`\n\n`env-doctor` compares active local environment variables against template files.\n\n- Detects variables defined in `.env` or referenced in code that are missing from `.env.example`.\n- Running `npx env-doctor --fix` safely appends missing keys to `.env.example` with empty defaults without ever exposing secrets or altering existing `.env` files.\n\n---\n\n## 8. Node.js Version Checks\n\nReads version constraints from:\n- `package.json` (`\"engines\": { \"node\": \">=20\" }`)\n- `.nvmrc`\n- `.node-version`\n\nIf the active Node.js runtime does not satisfy the constraint, `env-doctor` reports a version mismatch error.\n\n---\n\n## 9. Package Manager Conflict Detection\n\nScans for multiple lockfiles in the same repository (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`). Warns when multiple package managers are detected to prevent inconsistent node_modules trees.\n\n---\n\n## 10. Docker Awareness\n\nParses `Dockerfile` and `docker-compose.yml`/`compose.yaml` files for `${VAR_NAME}` references and `ENV`/`ARG` definitions, comparing Docker requirements against local environment availability.\n\n---\n\n## 11. CI Awareness\n\nInspects `.github/workflows/*.yml`, `.gitlab-ci.yml`, and `.circleci/config.yml` to ensure variables referenced in CI pipelines (such as `${{ secrets.KEY }}`) are documented in `.env.example`.\n\n---\n\n## 12. Configuration\n\n`env-doctor` can be configured via `.env-doctor.json` or within `package.json` under the `\"envDoctor\"` key.\n\nExample `.env-doctor.json`:\n\n```json\n{\n  \"required\": [\n    \"DATABASE_URL\",\n    \"JWT_SECRET\",\n    \"REDIS_URL\"\n  ],\n  \"rules\": {\n    \"PORT\": {\n      \"type\": \"number\"\n    },\n    \"NODE_ENV\": {\n      \"allowed\": [\"development\", \"test\", \"production\"]\n    }\n  },\n  \"ignoreDirs\": [\"node_modules\", \".git\", \"dist\", \"build\", \"coverage\", \".next\"],\n  \"ignoreVars\": [\"NODE_ENV\", \"PATH\"]\n}\n```\n\n---\n\n## 13. JSON Output\n\nRequest machine-readable output for programmatic consumption:\n\n```bash\nnpx env-doctor --json\n```\n\nOutput format:\n\n```json\n{\n  \"project\": {\n    \"name\": \"my-api\"\n  },\n  \"runtime\": {\n    \"node\": \"22.14.0\",\n    \"packageManager\": \"npm\",\n    \"environment\": \"development\"\n  },\n  \"variables\": {\n    \"defined\": [\"DATABASE_URL\"],\n    \"missing\": [\"REDIS_URL\"],\n    \"unused\": [\"AWS_REGION\"],\n    \"empty\": [],\n    \"suspicious\": []\n  },\n  \"errors\": 1,\n  \"warnings\": 1,\n  \"status\": \"failed\"\n}\n```\n\n---\n\n## 14. CI Usage\n\nIntegrate `env-doctor` into GitHub Actions or any CI/CD pipeline:\n\n```yaml\nname: Environment Diagnostic Check\n\non: [push, pull_request]\n\njobs:\n  env-check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n      - run: npx env-doctor --ci\n```\n\n**Exit Codes:**\n- `0`: All checks passed clean (or warnings only).\n- `1`: Environment diagnostic errors found (missing required env vars, Node mismatch).\n- `2`: CLI argument or configuration syntax error.\n\n---\n\n## 15. Security & Privacy\n\nSecurity is built into `env-doctor` at the fundamental design level:\n\n- 🔒 **Zero Secret Exposure**: Secret values are **NEVER** logged, output, serialized, or transmitted.\n- 📴 **100% Offline**: Zero network requests or telemetry.\n- 🛡️ **Safe Fix**: `--fix` never overwrites secrets or deletes variables.\n\n---\n\n## 16. Limitations & Future Roadmap\n\nCurrent scope focus: Node.js, JavaScript, TypeScript, Docker, CI, and key package managers.\n\n**Roadmap:**\n- **v1.x**: Safe `--fix` expansion, Redis/Database dry socket connectivity checks, custom plugin validation rules.\n- **v2.x**: Multi-environment snapshot comparison, team cloud sync schemas.\n\n---\n\n## 17. Contributing\n\nContributions are welcome! Please submit issues or pull requests on GitHub.\n\n```bash\n# Clone repository\ngit clone https://github.com/aman-projects/env-doctor.git\ncd env-doctor\n\n# Install dependencies\nnpm install\n\n# Run build and test suite\nnpm run build\nnpm test\n```\n\n---\n\n## License\n\n[MIT](LICENSE) © Antigravity Team\n","readmeFilename":"README.md","_rev":"1-ea4359b29358eb50960214831823edc3"}