dev-env-doctor 0.0.0-stage → 0.1.0

package/src/commands/doctor.js

@@ -0,0 +1,18 @@
+import { runDiagnostics } from '../core/runner.js';
+import { formatHuman, toJson, colorEnabled } from '../core/reporter.js';
+import { hasFailures } from '../core/diagnostics.js';
+import { EXIT } from '../core/exit-codes.js';
+import { resolveProjectRoot } from '../utils/paths.js';
+
+/** Shared handler for doctor, node, packages, env and services. Returns an exit code. */
+export async function diagnoseCommand(categories, opts, { version }) {
+  const root = resolveProjectRoot(opts.cwd);
+  const report = await runDiagnostics(root, { categories, verbose: opts.verbose });
+  if (opts.json) {
+    process.stdout.write(toJson(report, { version }));
+  } else {
+    process.stdout.write(formatHuman(report, { verbose: opts.verbose, color: colorEnabled({ color: opts.color && !opts.ci }) }));
+  }
+  const failOn = opts.failOn ?? report.config.failOn ?? 'fail';
+  return hasFailures(report.results, failOn) ? EXIT.DIAGNOSTIC_FAILURE : EXIT.OK;
+}

package/src/commands/fix.js

@@ -0,0 +1,83 @@
+import { runDiagnostics } from '../core/runner.js';
+import { EXIT } from '../core/exit-codes.js';
+import { STATUS } from '../core/diagnostics.js';
+import { collectFixes } from '../fixes/index.js';
+import { describeListener } from '../checks/ports.js';
+import { getPlatformAdapter } from '../platform/index.js';
+import { resolveProjectRoot } from '../utils/paths.js';
+import { isInteractive, askConfirm, askSelect } from '../utils/prompt.js';
+
+export function formatFix(fix, index) {
+  const lines = [
+    `${index + 1}. ${fix.problem}`,
+    `   Why it matters:  ${fix.why}`,
+    `   Proposed change: ${fix.change}`,
+    `   Modifies files:  ${fix.modifiesFiles ? 'yes' : 'no'}`,
+    `   Terminates a process: ${fix.terminatesProcess ? 'yes' : 'no'}`,
+    `   Expected outcome: ${fix.expected}`,
+  ];
+  if (fix.preview) {
+    lines.push('   Preview:');
+    for (const line of fix.preview.trimEnd().split('\n')) lines.push(`     ${line}`);
+  }
+  return lines.join('\n');
+}
+
+export async function fixCommand(opts, { out = process.stdout } = {}) {
+  const root = resolveProjectRoot(opts.cwd);
+  const adapter = getPlatformAdapter();
+  const { results } = await runDiagnostics(root, { adapter });
+  const fixes = collectFixes(results, root);
+  const write = (text = '') => out.write(`${text}\n`);
+
+  write('Dev Doctor fix');
+  if (fixes.length === 0) {
+    write('No automatic fixes available.');
+    const manual = [...new Set(results.filter((r) => r.hint && r.status === STATUS.FAIL).map((r) => r.hint))];
+    if (manual.length > 0) {
+      write('', 'Manual steps:');
+      manual.forEach((m, i) => write(`  ${i + 1}. ${m}`));
+    }
+    return EXIT.OK;
+  }
+
+  write('');
+  fixes.forEach((fix, i) => write(formatFix(fix, i) + '\n'));
+  if (opts.dryRun) {
+    write('Dry run: no changes were made.');
+    return EXIT.OK;
+  }
+
+  const interactive = isInteractive({ ci: opts.ci });
+  if (!interactive && !opts.yes) {
+    write('Not running interactively; no changes were made. Re-run with --yes to apply these fixes.');
+    return EXIT.DIAGNOSTIC_FAILURE;
+  }
+
+  const ctx = {
+    adapter,
+    interactive,
+    // Interactive: terminatePortProcess asks its own confirmation. Non-interactive: --yes was given.
+    yes: !interactive,
+    confirm: askConfirm,
+    choose: (targets) => askSelect('Which process should be terminated?', targets.map((t) => ({ name: describeListener(t), value: t }))),
+  };
+
+  let failed = 0;
+  for (const fix of fixes) {
+    if (interactive && !fix.terminatesProcess && !(await askConfirm(`Apply: ${fix.change}?`))) {
+      write(`Skipped: ${fix.problem}`);
+      continue;
+    }
+    const applied = await fix.apply(ctx);
+    if (!applied.ok) {
+      failed++;
+      write(`FAIL  ${applied.message}`);
+      continue;
+    }
+    const verified = await fix.verify(ctx);
+    if (!verified.ok) failed++;
+    write(`${verified.ok ? 'PASS' : 'FAIL'}  ${applied.message}; ${verified.message}`);
+  }
+  return failed > 0 ? EXIT.DIAGNOSTIC_FAILURE : EXIT.OK;
+}

package/src/commands/ports.js

@@ -0,0 +1,70 @@
+import { inspectPorts, portResults, parsePort, DEFAULT_PORTS, describeListener, formatProcessDetails } from '../checks/ports.js';
+import { STATUS, hasFailures } from '../core/diagnostics.js';
+import { formatHuman, toJson, colorEnabled } from '../core/reporter.js';
+import { terminatePortProcess, parsePid } from '../core/terminate.js';
+import { portsWorkflow } from '../core/port-workflow.js';
+import { EXIT } from '../core/exit-codes.js';
+import { getPlatformAdapter } from '../platform/index.js';
+import { loadConfig } from '../utils/config.js';
+import { resolveProjectRoot } from '../utils/paths.js';
+import { isInteractive, askConfirm, askSelect } from '../utils/prompt.js';
+
+const isSuccess = (outcome) => outcome.status === 'released' || outcome.status === 'free';
+
+export async function portsCommand(portArgs, opts, { version }) {
+  const root = resolveProjectRoot(opts.cwd);
+  const adapter = getPlatformAdapter();
+  // Never prompt when stdin/stderr are not terminals, in CI, or when JSON is requested.
+  const interactive = isInteractive({ ci: opts.ci }) && !opts.json;
+  // Human-readable progress goes to stderr when stdout carries JSON.
+  const log = (text) => (opts.json ? process.stderr : process.stdout).write(`${text}\n`);
+
+  const terminate = (port, pid) => terminatePortProcess(port, {
+    adapter,
+    pid,
+    projectRoot: root,
+    interactive,
+    yes: opts.yes,
+    force: opts.force,
+    confirm: askConfirm,
+    log,
+    choose: (targets) => askSelect(`Port ${port} has several listeners. Which process should be stopped?`, [
+      ...targets.map((t) => ({ name: describeListener(t), value: t })),
+      { name: 'Cancel', value: null },
+    ]),
+  });
+
+  if (opts.kill !== undefined) {
+    const port = parsePort(opts.kill);
+    const pid = opts.pid === undefined ? undefined : parsePid(opts.pid);
+    const outcome = await terminate(port, pid);
+    if (opts.json) process.stdout.write(JSON.stringify(outcome, null, 2) + '\n');
+    else log(outcome.message);
+    return isSuccess(outcome) ? EXIT.OK : EXIT.DIAGNOSTIC_FAILURE;
+  }
+
+  const explicit = portArgs.map(parsePort);
+  const config = loadConfig(root);
+  const ports = [...new Set(explicit.length > 0 ? explicit : (config.ports ?? DEFAULT_PORTS).map(parsePort))];
+  const inspections = await inspectPorts(ports, { adapter, describe: true, projectRoot: root });
+  const results = portResults(inspections, { occupiedStatus: explicit.length > 0 ? STATUS.FAIL : STATUS.WARN });
+  const report = { project: null, results };
+
+  if (opts.json) {
+    process.stdout.write(toJson(report, { version }));
+    return hasFailures(results) ? EXIT.DIAGNOSTIC_FAILURE : EXIT.OK;
+  }
+
+  process.stdout.write(formatHuman(report, { verbose: opts.verbose, color: colorEnabled({ color: opts.color && !opts.ci }) }));
+  // A single requested port gets a focused view of every listener.
+  if (ports.length === 1 && inspections[0].listeners.length > 0) {
+    for (const l of inspections[0].listeners) log(`\n${formatProcessDetails(ports[0], l).join('\n')}`);
+  }
+
+  if (interactive) {
+    log('');
+    await portsWorkflow(inspections, { select: askSelect, log, terminate });
+  }
+  // The exit code reflects the report above.
+  return hasFailures(results) ? EXIT.DIAGNOSTIC_FAILURE : EXIT.OK;
+}

package/src/core/diagnostics.js

@@ -0,0 +1,24 @@
+export const STATUS = Object.freeze({
+  PASS: 'pass',
+  WARN: 'warn',
+  FAIL: 'fail',
+  INFO: 'info',
+});
+
+/**
+ * A diagnostic result. Checks only return data; reporters decide how to show it.
+ * extra may hold: details (string[]), hint (string), fixId (string), fixData (object), data (object).
+ */
+export function result(category, status, title, extra = {}) {
+  return { category, status, title, ...extra };
+}
+
+export function summarize(results) {
+  const summary = { pass: 0, warn: 0, fail: 0, info: 0 };
+  for (const r of results) summary[r.status] += 1;
+  return summary;
+}
+
+export function hasFailures(results, failOn = 'fail') {
+  return results.some((r) => r.status === STATUS.FAIL || (failOn === 'warn' && r.status === STATUS.WARN));
+}

package/src/core/exit-codes.js

@@ -0,0 +1,6 @@
+// 0: no failures, 1: diagnostics found failures, 2: the tool itself could not run.
+export const EXIT = Object.freeze({
+  OK: 0,
+  DIAGNOSTIC_FAILURE: 1,
+  ERROR: 2,
+});

package/src/core/port-workflow.js

@@ -0,0 +1,39 @@
+import { describeListener, formatProcessDetails } from '../checks/ports.js';
+
+/**
+ * Interactive follow-up after a ports report: pick a process (when several), then Inspect / Stop / Skip.
+ * Only call this from an interactive terminal. `terminate(port, pid)` runs the safe termination flow.
+ * Returns the termination outcome, or null when nothing was stopped.
+ */
+export async function portsWorkflow(inspections, { select, log, terminate }) {
+  const candidates = inspections.flatMap((i) => i.listeners.filter((l) => l.pid).map((listener) => ({ port: i.port, listener })));
+  if (candidates.length === 0) return null;
+
+  let chosen = candidates[0];
+  if (candidates.length > 1) {
+    chosen = await select('Several ports are occupied. Which process do you want to work with?', [
+      ...candidates.map((c) => ({ name: `Port ${c.port}: ${describeListener(c.listener)}`, value: c })),
+      { name: 'Skip', value: null },
+    ]);
+    if (!chosen) return null;
+  }
+
+  const { port, listener } = chosen;
+  for (;;) {
+    const action = await select(`Port ${port} is used by ${describeListener(listener)}. What do you want to do?`, [
+      { name: 'Inspect process', value: 'inspect' },
+      { name: 'Stop process', value: 'stop' },
+      { name: 'Skip', value: 'skip' },
+    ]);
+    if (action === 'inspect') {
+      log(formatProcessDetails(port, listener).join('\n'));
+      continue;
+    }
+    if (action === 'stop') {
+      const outcome = await terminate(port, listener.pid);
+      log(outcome.message);
+      return outcome;
+    }
+    return null;
+  }
+}

package/src/core/reporter.js

@@ -0,0 +1,54 @@
+import { Chalk } from 'chalk';
+import { STATUS, summarize } from './diagnostics.js';
+import { redact } from '../utils/redact.js';
+
+export { redact };
+
+const LABELS = { [STATUS.PASS]: 'PASS', [STATUS.WARN]: 'WARN', [STATUS.FAIL]: 'FAIL', [STATUS.INFO]: 'INFO' };
+
+export function colorEnabled({ color = true, stream = process.stdout, env = process.env } = {}) {
+  if (!color || 'NO_COLOR' in env) return false;
+  if (env.FORCE_COLOR && env.FORCE_COLOR !== '0') return true;
+  return Boolean(stream.isTTY);
+}
+
+export function formatHuman(report, { verbose = false, color = false } = {}) {
+  const c = new Chalk({ level: color ? 1 : 0 });
+  const paint = { pass: c.green, warn: c.yellow, fail: c.red, info: c.cyan };
+  const lines = [c.bold('Dev Doctor')];
+  if (report.project) lines.push(`Project: ${report.project.name}${report.project.type !== 'Unknown' ? ` (${report.project.type})` : ''}`);
+
+  const categories = [...new Set(report.results.map((r) => r.category))];
+  for (const category of categories) {
+    lines.push('', c.bold(category));
+    for (const r of report.results.filter((x) => x.category === category)) {
+      lines.push(`  ${paint[r.status](LABELS[r.status].padEnd(4))}  ${redact(r.title)}`);
+      const showDetails = verbose || r.status === STATUS.FAIL;
+      if (showDetails) for (const d of r.details ?? []) lines.push(c.dim(`        ${redact(d)}`));
+    }
+  }
+
+  const s = summarize(report.results);
+  lines.push('', c.bold('Summary'), `  ${s.fail} error${s.fail === 1 ? '' : 's'}, ${s.warn} warning${s.warn === 1 ? '' : 's'}, ${s.pass} passed`);
+
+  const steps = [...new Set(report.results.filter((r) => r.hint && (r.status === STATUS.FAIL || r.status === STATUS.WARN)).map((r) => r.hint))];
+  if (steps.length > 0) {
+    lines.push('', c.bold('Recommended next steps:'));
+    steps.forEach((step, i) => lines.push(`  ${i + 1}. ${redact(step)}`));
+  }
+  return lines.join('\n') + '\n';
+}
+
+export function toJson(report, { version } = {}) {
+  const results = report.results.map(({ category, status, title, details, hint, fixId, data }) => ({
+    category, status, title, details: details ?? [], hint: hint ?? null, fixAvailable: Boolean(fixId), ...(data ? { data } : {}),
+  }));
+  const payload = {
+    tool: 'dev-doctor',
+    version,
+    project: report.project ? { name: report.project.name, type: report.project.type, root: report.project.root } : null,
+    summary: summarize(report.results),
+    results,
+  };
+  return redact(JSON.stringify(payload, null, 2)) + '\n';
+}

package/src/core/runner.js

@@ -0,0 +1,34 @@
+import { STATUS } from './diagnostics.js';
+import { loadProject, checkProject } from '../checks/project.js';
+import { checkNode } from '../checks/node-version.js';
+import { checkPackages } from '../checks/packages.js';
+import { checkEnvironment } from '../checks/environment.js';
+import { checkPorts, detectProjectPorts, DEFAULT_PORTS } from '../checks/ports.js';
+import { checkServices, discoverServices } from '../checks/services.js';
+import { getPlatformAdapter } from '../platform/index.js';
+import { loadConfig } from '../utils/config.js';
+
+export const ALL_CATEGORIES = ['project', 'node', 'packages', 'env', 'ports', 'services'];
+
+/** Run the selected read-only checks. Never modifies anything. */
+export async function runDiagnostics(root, { categories = ALL_CATEGORIES, verbose = false, adapter = getPlatformAdapter() } = {}) {
+  const config = loadConfig(root);
+  const project = loadProject(root);
+  const results = [];
+  const run = (name) => categories.includes(name);
+
+  if (run('project')) results.push(...checkProject(project));
+  if (run('node')) results.push(...(await checkNode(project)));
+  if (run('packages')) results.push(...(await checkPackages(project)));
+  if (run('env')) results.push(...(await checkEnvironment(root)));
+  if (run('ports')) {
+    const projectPorts = detectProjectPorts(project, config);
+    const ports = projectPorts.length > 0 ? projectPorts : DEFAULT_PORTS;
+    // Ports the project itself uses are failures when taken; generic common ports only warn.
+    const occupiedStatus = projectPorts.length > 0 ? STATUS.FAIL : STATUS.WARN;
+    results.push(...(await checkPorts(ports, { adapter, describe: verbose, occupiedStatus })));
+  }
+  if (run('services')) results.push(...(await checkServices(discoverServices(project, config))));
+
+  return { project, config, results };
+}

package/src/core/terminate.js

@@ -0,0 +1,140 @@
+import path from 'node:path';
+import { inspectPort, describeListener, formatProcessDetails, parsePort } from '../checks/ports.js';
+import { DevDoctorError } from '../utils/errors.js';
+
+// Never terminate these, even when they hold a port.
+const PROTECTED_NAMES = new Set([
+  'launchd', 'kernel_task', 'windowserver', 'loginwindow', 'systemd', 'init', 'sshd', 'dockerd',
+  'system', 'system idle process', 'smss.exe', 'csrss.exe', 'wininit.exe', 'winlogon.exe',
+  'services.exe', 'lsass.exe', 'svchost.exe', 'explorer.exe', 'dwm.exe',
+]);
+
+export function parsePid(value) {
+  const text = String(value).trim();
+  const pid = Number(text);
+  if (!/^\d+$/.test(text) || !Number.isSafeInteger(pid) || pid < 1 || pid > 0x7fffffff) {
+    throw new DevDoctorError(`Invalid process ID "${value}": expected a positive integer`);
+  }
+  return pid;
+}
+
+/** Returns a reason string if the process must not be terminated, otherwise null. */
+export function killSafetyReason(listener, { currentPid = process.pid, parentPid = process.ppid } = {}) {
+  const { pid } = listener;
+  if (!Number.isInteger(pid) || pid <= 4) return 'it is a system process';
+  if (pid === currentPid) return 'it is dev-doctor itself';
+  if (pid === parentPid) return 'it is the shell or process that started dev-doctor';
+  const name = path.basename(String(listener.name ?? '')).toLowerCase();
+  if (PROTECTED_NAMES.has(name)) return `"${listener.name}" is a protected system process`;
+  return null;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Poll until the port is free or the target process has exited, or the timeout passes. */
+async function waitAfterSignal(port, pid, deps, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const i = await inspectPort(port, deps);
+    if (i.state === 'free') return;
+    if (!(await deps.adapter.isRunning(pid))) return;
+    if (Date.now() >= deadline) return;
+    await sleep(200);
+  }
+}
+
+/**
+ * Terminate the process listening on a port, safely:
+ * - the target must be unambiguous (single listener, --pid, or an interactive choice) and pass safety rules;
+ * - explicit confirmation (or --yes when non-interactive);
+ * - re-check the target right before signalling; graceful first;
+ * - force only as a separate, explicit step (--force or a second confirmation) while the same PID still holds the port;
+ * - "released" is only reported after a fresh check finds the port free.
+ * Returns { port, pid, status: 'released'|'free'|'cancelled'|'refused'|'failed', message }.
+ */
+export async function terminatePortProcess(portValue, options) {
+  const { adapter, bind, interactive, yes = false, force = false, confirm, choose, waitMs = 3000, safety, projectRoot } = options;
+  const log = options.log ?? (() => {});
+  const port = parsePort(portValue);
+  const requestedPid = options.pid === undefined || options.pid === null ? null : parsePid(options.pid);
+  const deps = { adapter, bind };
+  let target = null;
+  const done = (status, message) => ({ port, pid: target?.pid ?? requestedPid, status, message });
+
+  const inspection = await inspectPort(port, { ...deps, describe: true, projectRoot });
+  if (inspection.state === 'free') return done('free', `Port ${port} is already free; nothing was terminated`);
+  const candidates = inspection.listeners;
+  if (candidates.length === 0 || candidates.some((l) => !l.pid)) {
+    return done('refused', `Port ${port} is in use, but its owning process cannot be identified reliably${inspection.error ? ` (${inspection.error})` : ''}. Nothing was terminated; dev-doctor does not request elevated permissions.`);
+  }
+
+  if (requestedPid !== null) {
+    target = candidates.find((l) => l.pid === requestedPid) ?? null;
+    if (!target) return done('refused', `PID ${requestedPid} is not listening on port ${port} (listeners: ${candidates.map(describeListener).join(', ')}). Nothing was terminated.`);
+  } else if (candidates.length === 1) {
+    target = candidates[0];
+  } else if (!interactive) {
+    return done('refused', `Port ${port} is used by ${candidates.length} processes (${candidates.map(describeListener).join(', ')}). Re-run with --pid <pid> to choose one.`);
+  } else {
+    target = await choose(candidates);
+    if (!target) return done('cancelled', 'No process selected; nothing was terminated');
+  }
+
+  const label = describeListener(target);
+  const unsafe = killSafetyReason(target, safety);
+  if (unsafe) return done('refused', `Refusing to terminate ${label}: ${unsafe}`);
+
+  log(formatProcessDetails(port, target).join('\n'));
+  if (interactive && !yes) {
+    if (!(await confirm(`Stop ${label} listening on port ${port}?`))) return done('cancelled', 'Cancelled; nothing was terminated');
+  } else if (!interactive && !yes) {
+    return done('refused', `Not running interactively. Re-run with --yes to stop ${label}.`);
+  }
+
+  // The process may have exited, or the port changed hands, while we were asking.
+  const before = await inspectPort(port, deps);
+  if (!before.listeners.some((l) => l.pid === target.pid)) {
+    if (before.state === 'free') return done('free', `${label} exited before it was stopped; port ${port} is now free (verified)`);
+    return done('refused', `${label} is no longer listening on port ${port}; the port is now held by ${before.listeners.map(describeListener).join(', ') || 'an unidentified process'}. Nothing was terminated.`);
+  }
+
+  const verify = async (action) => {
+    const after = await inspectPort(port, deps);
+    if (after.state === 'free') return done('released', `${action} ${label}; port ${port} was released (verified by a fresh check)`);
+    const running = await adapter.isRunning(target.pid);
+    const holdsPort = after.listeners.some((l) => l.pid === target.pid);
+    if (!running || !holdsPort) {
+      const others = after.listeners.filter((l) => l.pid !== target.pid).map(describeListener).join(', ') || 'an unidentified process';
+      return done('failed', `${label} ${running ? 'is no longer listening' : 'exited'}, but port ${port} is still in use by ${others}. Nothing else was terminated.`);
+    }
+    return null; // still running and still holding the port
+  };
+
+  const graceful = await adapter.killProcess(target.pid, { force: false });
+  if (!graceful.ok && graceful.reason === 'permission') {
+    return done('failed', `Permission denied stopping ${label}. dev-doctor does not use sudo; stop it yourself if appropriate.`);
+  }
+  // On Windows, console processes cannot be asked to stop gracefully; they are still running and go to the force step.
+  const noGraceful = !graceful.ok && graceful.reason === 'graceful-unsupported';
+  if (!graceful.ok && !noGraceful && graceful.reason !== 'not-found') return done('failed', `Could not stop ${label}: ${graceful.message ?? graceful.reason}`);
+
+  if (!noGraceful) {
+    await waitAfterSignal(port, target.pid, deps, waitMs);
+    const afterGraceful = await verify(graceful.ok ? 'Stopped' : 'Process had already exited:');
+    if (afterGraceful) return afterGraceful;
+  }
+
+  // Same PID is still running and still holds the port: force only as an explicit, separate action.
+  const situation = noGraceful ? 'cannot be stopped gracefully (console process on Windows)' : 'is still running after a graceful stop request';
+  let allowForce = force;
+  if (!allowForce && interactive) allowForce = await confirm(`${label} ${situation}. Force terminate it?`);
+  if (!allowForce) {
+    return done('failed', `${label} ${situation}; port ${port} is still in use. Re-run with --force to force terminate it.`);
+  }
+
+  const forced = await adapter.killProcess(target.pid, { force: true });
+  if (!forced.ok && forced.reason === 'permission') return done('failed', `Permission denied force terminating ${label}.`);
+  if (!forced.ok && forced.reason !== 'not-found') return done('failed', `Could not force terminate ${label}: ${forced.message ?? forced.reason}`);
+  await waitAfterSignal(port, target.pid, deps, waitMs);
+  return (await verify('Force terminated')) ?? done('failed', `${label} is still running after force termination; port ${port} is still in use.`);
+}

package/src/fixes/index.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import { safeProjectPath, readTextIfExists } from '../utils/paths.js';
+import { checkEnvironment, isEnvGitignored } from '../checks/environment.js';
+import { inspectPort } from '../checks/ports.js';
+import { terminatePortProcess } from '../core/terminate.js';
+
+/**
+ * Build the fixes offered for a set of diagnostic results.
+ * Each fix: { id, problem, why, change, preview, modifiesFiles, terminatesProcess, expected, apply(ctx), verify(ctx) }.
+ * apply returns { ok, message }; verify returns { ok, message }.
+ */
+export function collectFixes(results, root) {
+  const fixes = [];
+  for (const r of results) {
+    if (r.fixId === 'create-env') fixes.push(createEnvFix(r, root));
+    else if (r.fixId === 'gitignore-env') fixes.push(gitignoreFix(r, root));
+    else if (r.fixId === 'kill-port') fixes.push(killPortFix(r));
+  }
+  return fixes;
+}
+
+function createEnvFix(r, root) {
+  const { template, keys } = r.fixData;
+  // Keys only, with empty values: never copy template values or invent credentials.
+  const content = `# Created by dev-doctor from ${template}. Fill in your own values.\n${keys.map((k) => `${k}=`).join('\n')}\n`;
+  return {
+    id: 'create-env',
+    problem: r.title,
+    why: 'Tools such as dotenv, Vite and Next.js load variables from .env; without it the app may fail to start.',
+    change: `Create .env with the ${keys.length} key names from ${template}, all with empty values`,
+    preview: content,
+    modifiesFiles: true,
+    terminatesProcess: false,
+    expected: '.env exists and lists every expected key; you still need to fill in the values',
+    async apply() {
+      const file = safeProjectPath(root, '.env');
+      try {
+        fs.writeFileSync(file, content, { flag: 'wx' }); // 'wx' fails if .env already exists: never overwrite.
+      } catch (error) {
+        if (error.code === 'EEXIST') return { ok: false, message: '.env already exists; it was not modified' };
+        throw error;
+      }
+      return { ok: true, message: 'Created .env' };
+    },
+    async verify() {
+      const results = await checkEnvironment(root);
+      const stillMissing = results.some((x) => x.fixId === 'create-env');
+      return stillMissing ? { ok: false, message: '.env is still missing' } : { ok: true, message: '.env now exists' };
+    },
+  };
+}
+
+function gitignoreFix(r, root) {
+  return {
+    id: 'gitignore-env',
+    problem: r.title,
+    why: 'Without a .gitignore entry, secrets in .env can be committed and pushed by accident.',
+    change: 'Append ".env" to .gitignore (created if missing)',
+    preview: '+ .env\n',
+    modifiesFiles: true,
+    terminatesProcess: false,
+    expected: 'git ignores .env (files already committed still need "git rm --cached .env")',
+    async apply() {
+      const file = safeProjectPath(root, '.gitignore');
+      const current = readTextIfExists(file) ?? '';
+      const prefix = current && !current.endsWith('\n') ? '\n' : '';
+      fs.appendFileSync(file, `${prefix}.env\n`);
+      return { ok: true, message: 'Added .env to .gitignore' };
+    },
+    async verify() {
+      const ok = isEnvGitignored(readTextIfExists(safeProjectPath(root, '.gitignore')));
+      return { ok, message: ok ? '.env is listed in .gitignore' : '.env is still not ignored' };
+    },
+  };
+}
+
+function killPortFix(r) {
+  const { port } = r.fixData;
+  return {
+    id: 'kill-port',
+    problem: r.title,
+    why: `Your dev server cannot start on port ${port} while another process is listening on it.`,
+    change: `Ask the process on port ${port} to stop (graceful first; force only if you confirm)`,
+    preview: null,
+    modifiesFiles: false,
+    terminatesProcess: true,
+    expected: `Port ${port} becomes available`,
+    async apply(ctx) {
+      const outcome = await terminatePortProcess(port, ctx);
+      return { ok: outcome.status === 'released' || outcome.status === 'free', message: outcome.message };
+    },
+    async verify(ctx) {
+      const i = await inspectPort(port, ctx);
+      return { ok: i.state === 'free', message: i.state === 'free' ? `Port ${port} is free` : `Port ${port} is still in use` };
+    },
+  };
+}

package/src/platform/darwin.js

@@ -0,0 +1,25 @@
+import { runCommand } from '../utils/process-info.js';
+import { UtilityMissingError } from '../utils/errors.js';
+import { lsofListeners, describeUnixProcess, killUnix, isRunningUnix } from './unix.js';
+
+/** Working directory via `lsof -a -p PID -d cwd -Fn`; only visible for your own processes without root. */
+export async function darwinCwd(pid, run = runCommand) {
+  const r = await run('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn']);
+  if (r.missing) return { reason: 'lsof not found' };
+  const line = r.stdout.split(/\r?\n/).find((l) => l.startsWith('n'));
+  return line ? { cwd: line.slice(1) } : { reason: 'not accessible (permission denied or another user)' };
+}
+
+export function createDarwinAdapter({ run = runCommand, kill } = {}) {
+  return {
+    platform: 'darwin',
+    async findListeners(port) {
+      const listeners = await lsofListeners(port, run);
+      if (listeners === null) throw new UtilityMissingError('lsof');
+      return listeners;
+    },
+    describeProcess: (pid) => describeUnixProcess(pid, { run, getCwd: (p) => darwinCwd(p, run) }),
+    isRunning: async (pid) => isRunningUnix(pid, kill),
+    killProcess: async (pid, { force = false } = {}) => killUnix(pid, force, kill),
+  };
+}

package/src/platform/index.js

@@ -0,0 +1,10 @@
+import { createDarwinAdapter } from './darwin.js';
+import { createLinuxAdapter } from './linux.js';
+import { createWin32Adapter } from './win32.js';
+
+export function getPlatformAdapter(platform = process.platform, options = {}) {
+  if (platform === 'win32') return createWin32Adapter(options);
+  if (platform === 'darwin') return createDarwinAdapter(options);
+  // Linux and other Unix-like systems.
+  return createLinuxAdapter(options);
+}

package/src/platform/linux.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs/promises';
+import { runCommand } from '../utils/process-info.js';
+import { UtilityMissingError } from '../utils/errors.js';
+import { lsofListeners, describeUnixProcess, killUnix, isRunningUnix } from './unix.js';
+
+/** Working directory from /proc/PID/cwd. /proc/PID/environ is never read. */
+export async function linuxCwd(pid, readlink = fs.readlink) {
+  try {
+    return { cwd: await readlink(`/proc/${pid}/cwd`) };
+  } catch (error) {
+    if (error.code === 'EACCES' || error.code === 'EPERM') return { reason: 'permission denied' };
+    if (error.code === 'ENOENT') return { reason: 'process has exited' };
+    return { reason: 'not available' };
+  }
+}
+
+/** Parse `ss -ltnpH` output. Process info is absent when the socket belongs to another user. */
+export function parseSs(output) {
+  const listeners = [];
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const columns = line.trim().split(/\s+/);
+    const address = columns[3] ?? null;
+    const users = [...line.matchAll(/\("([^"]*)",pid=(\d+)/g)];
+    if (users.length === 0) {
+      listeners.push({ pid: null, name: null, addresses: [address] });
+      continue;
+    }
+    for (const [, name, pid] of users) listeners.push({ pid: Number(pid), name, addresses: [address] });
+  }
+  return listeners;
+}
+
+export function createLinuxAdapter({ run = runCommand, kill, readlink } = {}) {
+  return {
+    platform: 'linux',
+    async findListeners(port) {
+      const r = await run('ss', ['-ltnpH', `sport = :${port}`]);
+      if (!r.missing && r.ok) return parseSs(r.stdout);
+      const listeners = await lsofListeners(port, run);
+      if (listeners === null) throw new UtilityMissingError('ss or lsof');
+      return listeners;
+    },
+    describeProcess: (pid) => describeUnixProcess(pid, { run, getCwd: (p) => linuxCwd(p, readlink) }),
+    isRunning: async (pid) => isRunningUnix(pid, kill),
+    killProcess: async (pid, { force = false } = {}) => killUnix(pid, force, kill),
+  };
+}