dev-env-doctor 0.0.0-stage → 0.1.0

package/src/checks/node-version.js

@@ -0,0 +1,65 @@
+import path from 'node:path';
+import semver from 'semver';
+import { result, STATUS } from '../core/diagnostics.js';
+import { readTextIfExists } from '../utils/paths.js';
+import { getToolVersion } from '../utils/process-info.js';
+
+const CATEGORY = 'Node.js';
+const ALIAS = /^(lts\/|lts$|node$|stable$|latest$|current$|system$)/i;
+
+/** Compare the running Node.js version with a .nvmrc / .node-version value. */
+export function checkVersionFile(file, value, current) {
+  const wanted = value.trim().replace(/^v/i, '');
+  if (!wanted) return result(CATEGORY, STATUS.WARN, `${file} is empty`);
+  if (ALIAS.test(wanted)) {
+    return result(CATEGORY, STATUS.INFO, `${file} uses alias "${wanted}"; cannot verify offline`);
+  }
+  const hint = `Switch Node.js versions, e.g. "nvm use" or "fnm use" (reads ${file}).`;
+  if (semver.valid(wanted)) {
+    if (semver.eq(current, wanted)) return result(CATEGORY, STATUS.PASS, `Node.js ${current} matches ${file} (${wanted})`);
+    if (semver.major(current) === semver.major(wanted)) {
+      return result(CATEGORY, STATUS.WARN, `Node.js ${current} differs from ${file} (${wanted})`, { hint });
+    }
+    return result(CATEGORY, STATUS.FAIL, `Node.js ${current} does not match ${file} (${wanted})`, { hint });
+  }
+  if (semver.validRange(wanted)) {
+    if (semver.satisfies(current, wanted)) return result(CATEGORY, STATUS.PASS, `Node.js ${current} matches ${file} (${wanted})`);
+    return result(CATEGORY, STATUS.FAIL, `Node.js ${current} does not match ${file} (${wanted})`, { hint });
+  }
+  return result(CATEGORY, STATUS.WARN, `${file} contains an unrecognized version "${wanted}"`);
+}
+
+export function checkEngines(range, current) {
+  if (!semver.validRange(range)) {
+    return result(CATEGORY, STATUS.WARN, `engines.node "${range}" is not a valid version range`);
+  }
+  if (semver.satisfies(current, range)) {
+    return result(CATEGORY, STATUS.PASS, `Node.js ${current} satisfies engines.node (${range})`);
+  }
+  return result(CATEGORY, STATUS.FAIL, `Node.js ${current} does not satisfy engines.node (${range})`, {
+    hint: `Install and use a Node.js version matching "${range}" (e.g. with nvm, fnm or volta).`,
+  });
+}
+
+export async function checkNode(project, { nodeVersion = process.version, getVersion = getToolVersion } = {}) {
+  const current = semver.clean(nodeVersion) ?? nodeVersion;
+  const results = [result(CATEGORY, STATUS.INFO, `Node.js ${current}`)];
+
+  const npmVersion = await getVersion('npm');
+  results.push(npmVersion
+    ? result(CATEGORY, STATUS.INFO, `npm ${npmVersion}`)
+    : result(CATEGORY, STATUS.WARN, 'npm was not found on PATH', { hint: 'Reinstall Node.js or fix your PATH so npm is available.' }));
+
+  const range = project.packageJson?.engines?.node;
+  if (typeof range === 'string') results.push(checkEngines(range, current));
+
+  for (const file of ['.nvmrc', '.node-version']) {
+    const text = readTextIfExists(path.join(project.root, file), 1024);
+    if (text !== null) results.push(checkVersionFile(file, text.split(/\r?\n/)[0], current));
+  }
+
+  if (typeof range !== 'string' && results.length === 2) {
+    results.push(result(CATEGORY, STATUS.INFO, 'No required Node.js version declared (engines.node, .nvmrc, .node-version)'));
+  }
+  return results;
+}

package/src/checks/packages.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { result, STATUS } from '../core/diagnostics.js';
+import { exists } from '../utils/paths.js';
+import { getToolVersion } from '../utils/process-info.js';
+
+const CATEGORY = 'Packages';
+
+export const LOCKFILES = [
+  ['package-lock.json', 'npm'],
+  ['npm-shrinkwrap.json', 'npm'],
+  ['yarn.lock', 'yarn'],
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['bun.lockb', 'bun'],
+  ['bun.lock', 'bun'],
+];
+
+const KNOWN_MANAGERS = new Set(['npm', 'yarn', 'pnpm', 'bun']);
+
+export function findLockfiles(root) {
+  return LOCKFILES.filter(([file]) => exists(path.join(root, file))).map(([file, manager]) => ({ file, manager }));
+}
+
+function mtime(file) {
+  try {
+    return fs.statSync(file).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+export async function checkPackages(project, { getVersion = getToolVersion } = {}) {
+  const pkg = project.packageJson;
+  if (!pkg) return [];
+  const { root } = project;
+  const results = [];
+
+  const lockfiles = findLockfiles(root);
+  const lockManagers = [...new Set(lockfiles.map((l) => l.manager))];
+  const declared = typeof pkg.packageManager === 'string' ? pkg.packageManager.split('@')[0] : null;
+  const manager = (declared && KNOWN_MANAGERS.has(declared) ? declared : null) ?? (lockManagers.length === 1 ? lockManagers[0] : 'npm');
+  const install = `${manager} install`;
+
+  if (lockManagers.length > 1) {
+    results.push(result(CATEGORY, STATUS.WARN, 'Multiple lockfiles detected', {
+      details: lockfiles.map((l) => `${l.file} (${l.manager})`),
+      hint: `Agree on one package manager (likely ${manager}) and remove the other lockfiles yourself.`,
+    }));
+  } else if (lockfiles.length === 0) {
+    results.push(result(CATEGORY, STATUS.WARN, 'No lockfile found', { hint: `Run "${install}" and commit the generated lockfile.` }));
+  } else {
+    results.push(result(CATEGORY, STATUS.PASS, `Lockfile: ${lockfiles.map((l) => l.file).join(', ')} (${lockManagers[0]})`));
+  }
+
+  if (declared && lockManagers.length > 0 && !lockManagers.includes(declared)) {
+    results.push(result(CATEGORY, STATUS.WARN, `packageManager is "${declared}" but the lockfile belongs to ${lockManagers.join(', ')}`));
+  }
+
+  const version = await getVersion(manager);
+  if (version) {
+    results.push(result(CATEGORY, STATUS.PASS, `${manager} ${version} is available`));
+  } else {
+    results.push(result(CATEGORY, STATUS.FAIL, `${manager} is used by this project but was not found`, {
+      hint: manager === 'npm' ? 'Reinstall Node.js to restore npm.' : `Install ${manager} (e.g. "corepack enable") and try again.`,
+    }));
+  }
+
+  const names = Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) });
+  if (names.length === 0) {
+    results.push(result(CATEGORY, STATUS.INFO, 'No dependencies declared'));
+    return results;
+  }
+  if (exists(path.join(root, '.pnp.cjs'))) {
+    results.push(result(CATEGORY, STATUS.INFO, "Yarn Plug'n'Play detected; node_modules checks skipped"));
+    return results;
+  }
+
+  const nodeModules = path.join(root, 'node_modules');
+  if (!exists(nodeModules)) {
+    results.push(result(CATEGORY, STATUS.FAIL, 'Dependencies are not installed (node_modules not found)', { hint: `Run "${install}".` }));
+    return results;
+  }
+
+  const missing = names.filter((name) => !exists(path.join(nodeModules, name, 'package.json')));
+  if (missing.length > 0) {
+    results.push(result(CATEGORY, STATUS.FAIL, `${missing.length} of ${names.length} dependencies are not installed`, {
+      details: missing.slice(0, 10).concat(missing.length > 10 ? [`...and ${missing.length - 10} more`] : []),
+      hint: `Run "${install}".`,
+    }));
+  } else {
+    results.push(result(CATEGORY, STATUS.PASS, `All ${names.length} declared dependencies are installed`));
+  }
+
+  // npm writes node_modules/.package-lock.json on install; an older one means the lockfile changed since.
+  const lockTime = mtime(path.join(root, 'package-lock.json'));
+  const installTime = mtime(path.join(nodeModules, '.package-lock.json'));
+  if (lockTime && installTime && lockTime > installTime + 1000) {
+    results.push(result(CATEGORY, STATUS.WARN, 'package-lock.json changed since dependencies were last installed', { hint: 'Run "npm install".' }));
+  }
+  return results;
+}

package/src/checks/ports.js

@@ -0,0 +1,197 @@
+import net from 'node:net';
+import path from 'node:path';
+import { result, STATUS } from '../core/diagnostics.js';
+import { DevDoctorError } from '../utils/errors.js';
+import { parseEnv } from '../utils/env-parser.js';
+import { readTextIfExists } from '../utils/paths.js';
+import { redactCommandLine } from '../utils/redact.js';
+import { allDependencies } from './project.js';
+
+const CATEGORY = 'Ports';
+
+export const DEFAULT_PORTS = [3000, 3001, 4200, 5000, 5173, 8000, 8080];
+
+const FRAMEWORK_PORTS = [
+  ['next', 3000], ['react-scripts', 3000], ['nuxt', 3000], ['vite', 5173], ['@angular/core', 4200], ['astro', 4321],
+];
+
+export function parsePort(value) {
+  const text = String(value).trim();
+  const port = Number(text);
+  if (!/^\d+$/.test(text) || !Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new DevDoctorError(`Invalid port "${value}": expected an integer between 1 and 65535`);
+  }
+  return port;
+}
+
+/** Ports this project is likely to use: config, PORT in .env, script flags, framework defaults. */
+export function detectProjectPorts(project, config = {}) {
+  const ports = new Set();
+  for (const p of config.ports ?? []) ports.add(parsePort(p));
+
+  const envText = readTextIfExists(path.join(project.root, '.env'));
+  const envPort = envText ? parseEnv(envText).entries.get('PORT')?.value : undefined;
+  if (envPort && /^\d+$/.test(envPort) && Number(envPort) <= 65535 && Number(envPort) > 0) ports.add(Number(envPort));
+
+  const pkg = project.packageJson;
+  for (const script of Object.values(pkg?.scripts ?? {})) {
+    if (typeof script !== 'string') continue;
+    for (const match of script.matchAll(/(?:--port[= ]|\s-p\s+)(\d{2,5})\b/g)) {
+      const port = Number(match[1]);
+      if (port > 0 && port <= 65535) ports.add(port);
+    }
+  }
+  const deps = allDependencies(pkg);
+  for (const [dep, port] of FRAMEWORK_PORTS) {
+    if (deps[dep]) {
+      ports.add(port);
+      break;
+    }
+  }
+  return [...ports].sort((a, b) => a - b);
+}
+
+function listenOnce(port, host) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once('error', (error) => resolve(error.code));
+    server.listen({ port, host, exclusive: true }, () => server.close(() => resolve('free')));
+  });
+}
+
+/** Try to bind the port. Returns 'free', 'in-use' or 'denied'. */
+export async function bindTest(port) {
+  for (const host of ['127.0.0.1', '::']) {
+    const outcome = await listenOnce(port, host);
+    if (outcome === 'EADDRINUSE') return 'in-use';
+    if (outcome === 'EACCES') return 'denied';
+    // EADDRNOTAVAIL / EAFNOSUPPORT: that address family is unavailable; try the next one.
+  }
+  return 'free';
+}
+
+/** Merge IPv4/IPv6 entries of the same process. */
+export function dedupeListeners(listeners) {
+  const byKey = new Map();
+  for (const l of listeners) {
+    const key = l.pid ?? 'unknown';
+    const existing = byKey.get(key);
+    if (existing) {
+      existing.addresses = [...new Set([...existing.addresses, ...l.addresses])];
+      existing.name ??= l.name;
+    } else {
+      byKey.set(key, { ...l, addresses: [...new Set(l.addresses)] });
+    }
+  }
+  return [...byKey.values()];
+}
+
+function isInside(dir, root) {
+  const rel = path.relative(root, dir);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/** 'current' when the process runs in (or from) the project, 'other' when it clearly does not, else 'unknown'. */
+export function projectAssociation(details, projectRoot) {
+  if (!projectRoot) return 'unknown';
+  if (details.cwd) return isInside(details.cwd, projectRoot) ? 'current' : 'other';
+  if (details.command && details.command.includes(projectRoot)) return 'current';
+  return 'unknown';
+}
+
+/** Inspect one port: { port, state: 'free'|'in-use'|'denied', listeners, error? } */
+export async function inspectPort(port, { adapter, bind = bindTest, describe = false, projectRoot = null } = {}) {
+  let listeners = [];
+  let error = null;
+  try {
+    listeners = dedupeListeners(await adapter.findListeners(port));
+  } catch (e) {
+    error = e.message;
+  }
+  if (describe) {
+    for (const l of listeners) {
+      if (!l.pid) continue;
+      const details = await adapter.describeProcess(l.pid);
+      // Command lines are redacted here so secrets never reach any reporter or JSON.
+      Object.assign(l, details, { name: l.name ?? details.name ?? null, command: redactCommandLine(details.command ?? null) });
+      l.project = projectAssociation(l, projectRoot);
+    }
+  }
+  if (listeners.length > 0) return { port, state: 'in-use', listeners, error };
+  const state = await bind(port);
+  return { port, state, listeners: [], error };
+}
+
+export function describeListener(l) {
+  if (!l.pid) return 'an inaccessible process';
+  return `${l.name ?? 'unknown process'} (PID ${l.pid})`;
+}
+
+const ASSOCIATION = { current: 'current project', other: 'another project or location', unknown: 'unknown' };
+
+function field(l, name, value) {
+  if (value !== null && value !== undefined) return String(value);
+  return `unavailable${l.unavailable?.[name] ? ` (${l.unavailable[name]})` : ''}`;
+}
+
+/** Focused, multi-line description of one listener; missing data is labelled, never invented. */
+export function formatProcessDetails(port, l) {
+  if (!l.pid) return [`Port ${port}: owning process is not accessible (PID unavailable)`];
+  const lines = [
+    `Port:              ${port}`,
+    `PID:               ${l.pid}`,
+    `Name:              ${field(l, 'name', l.name)}`,
+    `Command:           ${field(l, 'command', l.command)}`,
+    `Parent PID:        ${field(l, 'ppid', l.ppid)}`,
+    `Working directory: ${field(l, 'cwd', l.cwd)}`,
+    `Project:           ${ASSOCIATION[l.project] ?? 'unknown'}`,
+    `Listening on:      ${l.addresses.join(', ') || 'unavailable'}`,
+  ];
+  if (l.user) lines.splice(3, 0, `User:              ${l.user}`);
+  if (l.exists === false) lines.push('Note:              the process exited while it was being inspected');
+  return lines;
+}
+
+export function portResults(inspections, { occupiedStatus = STATUS.FAIL } = {}) {
+  return inspections.map((i) => {
+    const details = [];
+    if (i.error) details.push(i.error);
+    for (const l of i.listeners) {
+      details.push(`PID ${l.pid ?? '?'}  ${l.name ?? '?'}  ${l.addresses.join(', ')}${l.user ? `  user: ${l.user}` : ''}`);
+      if (l.command) details.push(`  ${l.command}`);
+      if (l.cwd) details.push(`  cwd: ${l.cwd}${l.project ? ` (${ASSOCIATION[l.project]})` : ''}`);
+    }
+    const data = { port: i.port, state: i.state, listeners: i.listeners };
+
+    if (i.state === 'free') return result(CATEGORY, STATUS.PASS, `Port ${i.port} is available`, { details, data });
+    if (i.state === 'denied') {
+      return result(CATEGORY, STATUS.INFO, `Port ${i.port} needs elevated privileges to test`, { details, data });
+    }
+    const known = i.listeners.filter((l) => l.pid);
+    if (known.length === 0) {
+      return result(CATEGORY, occupiedStatus, `Port ${i.port} is in use (process details not accessible)`, {
+        details,
+        data,
+        hint: `Port ${i.port} is held by a process you cannot inspect; it may belong to another user or need elevated permissions.`,
+      });
+    }
+    return result(CATEGORY, occupiedStatus, `Port ${i.port} is occupied by ${known.map(describeListener).join(', ')}`, {
+      details,
+      data,
+      hint: `Inspect the process using port ${i.port}, or stop it with "dev-doctor ports --kill ${i.port}".`,
+      // Only offer termination for ports the project needs, not for generic common ports.
+      ...(occupiedStatus === STATUS.FAIL ? { fixId: 'kill-port', fixData: { port: i.port } } : {}),
+    });
+  });
+}
+
+export async function inspectPorts(ports, options = {}) {
+  const inspections = [];
+  for (const port of ports) inspections.push(await inspectPort(port, options));
+  return inspections;
+}
+
+export async function checkPorts(ports, { occupiedStatus, ...options } = {}) {
+  return portResults(await inspectPorts(ports, options), { occupiedStatus });
+}

package/src/checks/project.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { result, STATUS } from '../core/diagnostics.js';
+
+const CATEGORY = 'Project';
+
+// Order matters: frameworks before the libraries they build on.
+const PROJECT_TYPES = [
+  ['next', 'Next.js'],
+  ['nuxt', 'Nuxt'],
+  ['@angular/core', 'Angular'],
+  ['@sveltejs/kit', 'SvelteKit'],
+  ['@remix-run/react', 'Remix'],
+  ['astro', 'Astro'],
+  ['vite', 'Vite'],
+  ['react-scripts', 'Create React App'],
+  ['@nestjs/core', 'NestJS'],
+  ['express', 'Express'],
+  ['fastify', 'Fastify'],
+  ['react', 'React'],
+  ['vue', 'Vue'],
+  ['svelte', 'Svelte'],
+];
+
+export function allDependencies(pkg) {
+  return { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+}
+
+export function detectProjectType(pkg) {
+  if (!pkg) return 'Unknown';
+  const deps = allDependencies(pkg);
+  for (const [dep, type] of PROJECT_TYPES) {
+    if (deps[dep]) return type;
+  }
+  return 'Node.js';
+}
+
+/** Load package.json without executing anything. */
+export function loadProject(root) {
+  const file = path.join(root, 'package.json');
+  const project = { root, name: path.basename(root), packageJson: null, packageJsonExists: false, packageJsonError: null, type: 'Unknown' };
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return project;
+  }
+  project.packageJsonExists = true;
+  try {
+    const pkg = JSON.parse(text);
+    if (typeof pkg !== 'object' || pkg === null || Array.isArray(pkg)) throw new Error('package.json must contain a JSON object');
+    project.packageJson = pkg;
+    if (typeof pkg.name === 'string' && pkg.name) project.name = pkg.name;
+    project.type = detectProjectType(pkg);
+  } catch (error) {
+    project.packageJsonError = error.message;
+  }
+  return project;
+}
+
+export function checkProject(project) {
+  if (!project.packageJsonExists) {
+    return [result(CATEGORY, STATUS.FAIL, 'package.json not found', { hint: 'Run dev-doctor from your project root, or create package.json with "npm init".' })];
+  }
+  if (project.packageJsonError) {
+    return [result(CATEGORY, STATUS.FAIL, 'package.json is not valid JSON', { details: [project.packageJsonError], hint: 'Fix the syntax error in package.json.' })];
+  }
+  return [result(CATEGORY, STATUS.PASS, `package.json is valid (${project.type} project)`)];
+}

package/src/checks/services.js

@@ -0,0 +1,162 @@
+import net from 'node:net';
+import path from 'node:path';
+import { result, STATUS } from '../core/diagnostics.js';
+import { parseEnv } from '../utils/env-parser.js';
+import { exists, readTextIfExists } from '../utils/paths.js';
+import { runCommand } from '../utils/process-info.js';
+import { allDependencies } from './project.js';
+import { LOCAL_FILES } from './environment.js';
+
+const CATEGORY = 'Services';
+
+export const COMPOSE_FILES = ['compose.yaml', 'compose.yml', 'docker-compose.yaml', 'docker-compose.yml'];
+
+export const SERVICES = {
+  postgres: {
+    label: 'PostgreSQL', port: 5432, schemes: ['postgres:', 'postgresql:'], images: /postgres|postgis/i,
+    deps: ['pg', 'postgres', 'pg-promise'], urlKeys: ['DATABASE_URL', 'POSTGRES_URL', 'PG_URL'], hostKey: 'PGHOST', portKey: 'PGPORT',
+  },
+  mongodb: {
+    label: 'MongoDB', port: 27017, schemes: ['mongodb:', 'mongodb+srv:'], images: /mongo/i,
+    deps: ['mongodb', 'mongoose'], urlKeys: ['DATABASE_URL', 'MONGODB_URI', 'MONGODB_URL', 'MONGO_URL', 'MONGO_URI'], hostKey: 'MONGO_HOST', portKey: 'MONGO_PORT',
+  },
+  redis: {
+    label: 'Redis', port: 6379, schemes: ['redis:', 'rediss:'], images: /redis|valkey/i,
+    deps: ['redis', 'ioredis'], urlKeys: ['REDIS_URL'], hostKey: 'REDIS_HOST', portKey: 'REDIS_PORT',
+  },
+};
+
+/** Merge local env files (later files win) and the process environment. Values are used only to find host/port. */
+function loadEnvValues(root, env) {
+  const values = new Map();
+  for (const file of LOCAL_FILES) {
+    const text = readTextIfExists(path.join(root, file));
+    if (text === null) continue;
+    for (const [key, { value }] of parseEnv(text).entries) values.set(key, value);
+  }
+  for (const [key, value] of Object.entries(env)) values.set(key, value);
+  return values;
+}
+
+function endpointFromUrl(value, spec) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (!spec.schemes.includes(url.protocol)) return null;
+  if (url.protocol === 'mongodb+srv:') return { srv: true };
+  // Multi-host strings like "mongodb://a:1,b:2" are reduced to the first host by URL parsing.
+  return { host: url.hostname.replace(/^\[|\]$/g, '') || 'localhost', port: Number(url.port) || spec.port };
+}
+
+/** Work out which services the project appears to need and where they should be. */
+export function discoverServices(project, config = {}, { env = process.env } = {}) {
+  const { root } = project;
+  const values = loadEnvValues(root, env);
+  const deps = allDependencies(project.packageJson);
+  const composeFile = COMPOSE_FILES.find((f) => exists(path.join(root, f))) ?? null;
+  const composeText = composeFile ? readTextIfExists(path.join(root, composeFile)) ?? '' : '';
+  const images = [...composeText.matchAll(/^\s*image:\s*["']?([^\s"'#]+)/gm)].map((m) => m[1]);
+  const serviceConfig = config.services ?? {};
+
+  const docker = { required: false, reasons: [] };
+  if (composeFile) docker.reasons.push(composeFile);
+  if (exists(path.join(root, 'Dockerfile'))) docker.reasons.push('Dockerfile');
+  docker.required = serviceConfig.docker === undefined ? docker.reasons.length > 0 : Boolean(serviceConfig.docker);
+  if (serviceConfig.docker) docker.reasons.push('.dev-doctor.json');
+
+  const services = [];
+  for (const [id, spec] of Object.entries(SERVICES)) {
+    const configured = serviceConfig[id];
+    if (configured === false) continue;
+    const reasons = [];
+    let endpoint = null;
+
+    if (configured && typeof configured === 'object') {
+      reasons.push('.dev-doctor.json');
+      endpoint = { host: configured.host ?? 'localhost', port: Number(configured.port) || spec.port };
+    }
+    for (const key of spec.urlKeys) {
+      const value = values.get(key);
+      const found = value ? endpointFromUrl(value, spec) : null;
+      if (found) {
+        reasons.push(key);
+        endpoint ??= found;
+        break;
+      }
+    }
+    if (values.get(spec.hostKey) || values.get(spec.portKey)) {
+      reasons.push(spec.hostKey);
+      endpoint ??= { host: values.get(spec.hostKey) || 'localhost', port: Number(values.get(spec.portKey)) || spec.port };
+    }
+    if (images.some((image) => spec.images.test(image))) reasons.push(composeFile);
+    const dep = spec.deps.find((d) => deps[d]);
+    if (dep) reasons.push(`dependency "${dep}"`);
+
+    if (reasons.length === 0) continue;
+    services.push({ id, label: spec.label, reasons, endpoint: endpoint ?? { host: 'localhost', port: spec.port } });
+  }
+  return { docker, services };
+}
+
+export function tcpCheck(host, port, timeout = 2000) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port });
+    const finish = (ok) => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeout, () => finish(false));
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+  });
+}
+
+export async function checkServices(discovery, { run = runCommand, tcp = tcpCheck } = {}) {
+  const results = [];
+  const { docker, services } = discovery;
+  const why = (reasons) => [`Detected from ${reasons.join(', ')}`];
+
+  const cli = await run('docker', ['--version'], { timeout: 5000 });
+  if (!cli.ok) {
+    if (docker.required) {
+      results.push(result(CATEGORY, STATUS.FAIL, 'Docker CLI not found', { details: why(docker.reasons), hint: 'Install Docker Desktop or Docker Engine.' }));
+    } else {
+      results.push(result(CATEGORY, STATUS.INFO, 'Docker CLI not found (not required by this project)'));
+    }
+  } else {
+    const daemon = await run('docker', ['info', '--format', '{{.ServerVersion}}'], { timeout: 8000 });
+    if (daemon.ok) {
+      results.push(result(CATEGORY, STATUS.PASS, `Docker daemon is running (${daemon.stdout.trim()})`));
+    } else {
+      results.push(result(CATEGORY, docker.required ? STATUS.FAIL : STATUS.WARN, 'Docker daemon is not running', {
+        details: docker.required ? why(docker.reasons) : [],
+        hint: 'Start Docker Desktop or the Docker service.',
+      }));
+    }
+  }
+
+  for (const service of services) {
+    const { endpoint } = service;
+    if (endpoint.srv) {
+      results.push(result(CATEGORY, STATUS.INFO, `${service.label} uses an SRV connection string; TCP check skipped`, { details: why(service.reasons) }));
+      continue;
+    }
+    const where = `${endpoint.host}:${endpoint.port}`;
+    if (await tcp(endpoint.host, endpoint.port)) {
+      results.push(result(CATEGORY, STATUS.PASS, `${service.label} is reachable at ${where}`, {
+        details: [...why(service.reasons), 'TCP connection only; authentication and queries were not verified'],
+      }));
+    } else {
+      results.push(result(CATEGORY, STATUS.WARN, `${service.label} is not reachable at ${where}`, {
+        details: why(service.reasons),
+        hint: `Verify ${service.label} is running if this project needs it${discovery.docker.reasons.some((r) => r.includes('compose')) ? ' (e.g. "docker compose up -d")' : ''}.`,
+      }));
+    }
+  }
+
+  if (services.length === 0) results.push(result(CATEGORY, STATUS.INFO, 'No database services detected'));
+  return results;
+}

package/src/cli.js

@@ -0,0 +1,81 @@
+import { createRequire } from 'node:module';
+import { Command, Option, CommanderError } from 'commander';
+import { diagnoseCommand } from './commands/doctor.js';
+import { portsCommand } from './commands/ports.js';
+import { fixCommand } from './commands/fix.js';
+import { EXIT } from './core/exit-codes.js';
+import { DevDoctorError } from './utils/errors.js';
+
+const { version } = createRequire(import.meta.url)('../package.json');
+
+function addCommonOptions(command) {
+  return command
+    .option('--cwd <path>', 'project directory to inspect', process.cwd())
+    .option('--json', 'print machine-readable JSON to stdout')
+    .option('-v, --verbose', 'show more details')
+    .option('--ci', 'CI mode: no prompts, no colors, non-zero exit on failures')
+    .addOption(new Option('--fail-on <level>', 'exit non-zero on this level or worse').choices(['fail', 'warn']))
+    .option('--no-color', 'disable colored output');
+}
+
+export function buildProgram(setExit) {
+  const program = new Command();
+  program
+    .name('dev-doctor')
+    .description('Diagnose and safely fix common local development environment problems.')
+    .version(version, '-V, --version')
+    .exitOverride()
+    .addHelpText('after', '\nExit codes:\n  0  no failures\n  1  diagnostics found failures (or a requested action did not succeed)\n  2  dev-doctor could not run (invalid input or unexpected error)');
+
+  const diagnose = (categories) => async (opts) => setExit(await diagnoseCommand(categories, opts, { version }));
+
+  addCommonOptions(program.command('doctor', { isDefault: true }).description('run the full diagnostic suite (default)'))
+    .action(diagnose(['project', 'node', 'packages', 'env', 'ports', 'services']));
+  addCommonOptions(program.command('node').description('check the Node.js version against project requirements'))
+    .action(diagnose(['node']));
+  addCommonOptions(program.command('packages').description('check package.json, lockfiles and installed dependencies'))
+    .action(diagnose(['project', 'packages']));
+  addCommonOptions(program.command('env').description('compare .env files with .env.example and code references (keys only)'))
+    .action(diagnose(['env']));
+  addCommonOptions(program.command('services').description('check Docker and PostgreSQL/MongoDB/Redis TCP availability'))
+    .action(diagnose(['services']));
+
+  addCommonOptions(program.command('ports').description('show which processes are listening on ports'))
+    .argument('[ports...]', 'ports to check (default: common development ports)')
+    .option('--kill <port>', 'stop the process listening on <port> (asks for confirmation)')
+    .option('--pid <pid>', 'with --kill: the exact process to stop when several listen on the port')
+    .option('-y, --yes', 'confirm stopping without a prompt (required when non-interactive)')
+    .option('--force', 'with --kill: force terminate if the same process is still running after a graceful stop')
+    .action(async (ports, opts) => setExit(await portsCommand(ports, opts, { version })));
+
+  program.command('fix')
+    .description('diagnose, then preview and apply safe fixes with confirmation')
+    .option('--cwd <path>', 'project directory to inspect', process.cwd())
+    .option('--dry-run', 'only show the available fixes')
+    .option('-y, --yes', 'apply fixes without prompts (required when non-interactive)')
+    .option('--ci', 'CI mode: never prompt')
+    .action(async (opts) => setExit(await fixCommand(opts)));
+
+  return program;
+}
+
+export async function main(argv) {
+  const setExit = (code) => {
+    process.exitCode = code;
+  };
+  try {
+    await buildProgram(setExit).parseAsync(argv);
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      // Help and version exit with 0; usage errors (already printed by commander) with 2.
+      process.exitCode = error.exitCode === 0 ? EXIT.OK : EXIT.ERROR;
+      return;
+    }
+    if (error instanceof DevDoctorError) {
+      process.stderr.write(`dev-doctor: ${error.message}\n`);
+    } else {
+      process.stderr.write(`dev-doctor: unexpected error: ${error?.message ?? error}\n`);
+    }
+    process.exitCode = EXIT.ERROR;
+  }
+}