dev-env-doctor 0.0.0-stage → 0.1.0

package/src/platform/unix.js

@@ -0,0 +1,79 @@
+import { runCommand } from '../utils/process-info.js';
+
+/** Parse `lsof -Fpcn` output into listeners. */
+export function parseLsof(output) {
+  const listeners = [];
+  let current = null;
+  for (const line of output.split(/\r?\n/)) {
+    const field = line[0];
+    const value = line.slice(1);
+    if (field === 'p') {
+      current = { pid: Number(value), name: null, addresses: [] };
+      listeners.push(current);
+    } else if (field === 'c' && current) {
+      current.name = value;
+    } else if (field === 'n' && current) {
+      current.addresses.push(value);
+    }
+  }
+  return listeners;
+}
+
+export async function lsofListeners(port, run = runCommand) {
+  const r = await run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpcn']);
+  if (r.missing) return null;
+  // lsof exits with 1 when nothing matches.
+  return r.stdout.trim() ? parseLsof(r.stdout) : [];
+}
+
+/** Parse `ps -o ppid=,user=,command=` output. */
+export function parsePs(output) {
+  const match = /^\s*(\d+)\s+(\S+)\s*(.*)$/.exec(output.trim());
+  if (!match) return null;
+  return { ppid: Number(match[1]), user: match[2], command: match[3].trim() || null };
+}
+
+/**
+ * Process details on Unix. Every field may be null; `unavailable` says why.
+ * getCwd(pid) returns { cwd } or { reason }.
+ */
+export async function describeUnixProcess(pid, { run = runCommand, getCwd } = {}) {
+  const details = { exists: true, ppid: null, user: null, command: null, cwd: null, unavailable: {} };
+  const r = await run('ps', ['-o', 'ppid=,user=,command=', '-p', String(pid)]);
+  const parsed = r.ok ? parsePs(r.stdout) : null;
+  if (r.missing) {
+    details.unavailable.command = 'ps not found';
+  } else if (!parsed) {
+    // ps exits non-zero when the PID does not exist.
+    return { ...details, exists: false, unavailable: { command: 'process has exited' } };
+  } else {
+    Object.assign(details, parsed);
+    if (!parsed.command) details.unavailable.command = 'not accessible';
+  }
+  const cwd = await getCwd(pid);
+  if (cwd.cwd) details.cwd = cwd.cwd;
+  else details.unavailable.cwd = cwd.reason;
+  return details;
+}
+
+/** Signal 0 checks existence without affecting the process. EPERM means it exists but belongs to someone else. */
+export function isRunningUnix(pid, kill = process.kill.bind(process)) {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+/** Send a signal; returns { ok } or { ok: false, reason: 'permission' | 'not-found' | 'error' }. */
+export function killUnix(pid, force, kill = process.kill.bind(process)) {
+  try {
+    kill(pid, force ? 'SIGKILL' : 'SIGTERM');
+    return { ok: true };
+  } catch (error) {
+    if (error.code === 'EPERM') return { ok: false, reason: 'permission' };
+    if (error.code === 'ESRCH') return { ok: false, reason: 'not-found' };
+    return { ok: false, reason: 'error', message: error.message };
+  }
+}

package/src/platform/win32.js

@@ -0,0 +1,96 @@
+import { runCommand } from '../utils/process-info.js';
+import { UtilityMissingError } from '../utils/errors.js';
+
+/**
+ * Parse `netstat -ano` output. Listening sockets have a foreign port of 0;
+ * this avoids depending on the localized "LISTENING" state text.
+ */
+export function parseNetstat(output, port) {
+  const listeners = [];
+  for (const line of output.split(/\r?\n/)) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 5 || parts[0].toUpperCase() !== 'TCP') continue;
+    const [, local, foreign] = parts;
+    const pid = Number(parts[parts.length - 1]);
+    if (!local.endsWith(`:${port}`) || !foreign.endsWith(':0') || !Number.isInteger(pid)) continue;
+    listeners.push({ pid, name: null, addresses: [local] });
+  }
+  return listeners;
+}
+
+/** Parse `tasklist /FO CSV /NH` output and return the image name. */
+export function parseTasklist(output) {
+  const match = /^"([^"]+)","(\d+)"/m.exec(output);
+  return match ? match[1] : null;
+}
+
+// The PID is passed through an environment variable and cast to [int], so it is never interpolated into the script.
+const DESCRIBE_SCRIPT = [
+  '$p = [int]$env:DEV_DOCTOR_PID',
+  '$x = Get-CimInstance Win32_Process -Filter "ProcessId = $p"',
+  'if ($x) { $x | Select-Object ProcessId, ParentProcessId, Name, CommandLine | ConvertTo-Json -Compress }',
+].join('; ');
+
+/** Parse the JSON printed by DESCRIBE_SCRIPT. */
+export function parseWin32Process(output) {
+  const text = output.trim();
+  if (!text) return null;
+  try {
+    const data = JSON.parse(text);
+    return { ppid: Number.isInteger(data.ParentProcessId) ? data.ParentProcessId : null, name: data.Name ?? null, command: data.CommandLine || null };
+  } catch {
+    return null;
+  }
+}
+
+export function createWin32Adapter({ run = runCommand } = {}) {
+  return {
+    platform: 'win32',
+    async findListeners(port) {
+      const r = await run('netstat', ['-ano']);
+      if (r.missing) throw new UtilityMissingError('netstat');
+      const listeners = parseNetstat(r.stdout, port);
+      for (const listener of listeners) {
+        const t = await run('tasklist', ['/FI', `PID eq ${listener.pid}`, '/FO', 'CSV', '/NH']);
+        if (t.ok) listener.name = parseTasklist(t.stdout);
+      }
+      return listeners;
+    },
+    async describeProcess(pid) {
+      const details = { exists: true, ppid: null, user: null, command: null, cwd: null, unavailable: { cwd: 'not available on Windows', user: 'not collected on Windows' } };
+      const r = await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', DESCRIBE_SCRIPT], { timeout: 10000, env: { DEV_DOCTOR_PID: String(pid) } });
+      if (r.missing) {
+        details.unavailable.command = 'PowerShell not found';
+        return details;
+      }
+      const parsed = r.ok ? parseWin32Process(r.stdout) : null;
+      if (r.ok && !parsed) return { ...details, exists: false, unavailable: { ...details.unavailable, command: 'process has exited' } };
+      if (!parsed) {
+        details.unavailable.command = 'not available';
+        return details;
+      }
+      details.ppid = parsed.ppid;
+      details.command = parsed.command;
+      // CommandLine is empty for elevated or other users' processes.
+      if (!parsed.command) details.unavailable.command = 'not accessible (permission denied)';
+      return details;
+    },
+    async isRunning(pid) {
+      const t = await run('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH']);
+      return t.ok && parseTasklist(t.stdout) !== null;
+    },
+    async killProcess(pid, { force = false } = {}) {
+      const args = ['/PID', String(pid)];
+      if (force) args.push('/F');
+      const r = await run('taskkill', args);
+      if (r.ok) return { ok: true };
+      if (r.missing) return { ok: false, reason: 'error', message: 'taskkill not found' };
+      const text = `${r.stdout} ${r.stderr}`;
+      if (/access is denied/i.test(text)) return { ok: false, reason: 'permission' };
+      // Console programs (node.exe, python.exe, ...) have no window to close, so taskkill without /F cannot stop them.
+      if (!force && /forcefully|\/F option/i.test(text)) return { ok: false, reason: 'graceful-unsupported' };
+      if (/not found/i.test(text)) return { ok: false, reason: 'not-found' };
+      return { ok: false, reason: 'error', message: text.trim() };
+    },
+  };
+}

package/src/utils/config.js

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { readTextIfExists } from './paths.js';
+import { DevDoctorError } from './errors.js';
+
+export const CONFIG_FILE = '.dev-doctor.json';
+
+/**
+ * Optional project config:
+ * { "ports": [3000], "failOn": "fail" | "warn",
+ *   "services": { "docker": true, "postgres": { "host": "localhost", "port": 5432 }, "redis": false } }
+ */
+export function loadConfig(root) {
+  const text = readTextIfExists(path.join(root, CONFIG_FILE));
+  if (text === null) return {};
+  let config;
+  try {
+    config = JSON.parse(text);
+  } catch {
+    throw new DevDoctorError(`${CONFIG_FILE} is not valid JSON`);
+  }
+  if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+    throw new DevDoctorError(`${CONFIG_FILE} must contain a JSON object`);
+  }
+  if (config.ports !== undefined && !Array.isArray(config.ports)) {
+    throw new DevDoctorError(`${CONFIG_FILE}: "ports" must be an array`);
+  }
+  if (config.failOn !== undefined && !['fail', 'warn'].includes(config.failOn)) {
+    throw new DevDoctorError(`${CONFIG_FILE}: "failOn" must be "fail" or "warn"`);
+  }
+  return config;
+}

package/src/utils/env-parser.js

@@ -0,0 +1,64 @@
+const KEY_LINE = /^([A-Za-z_][A-Za-z0-9_.-]*)\s*=\s*(.*)$/;
+
+/**
+ * Parse dotenv-style text. Returns entries (key -> { value, line }) and issues.
+ * Issues only contain line numbers and messages, never file content.
+ */
+export function parseEnv(text) {
+  const entries = new Map();
+  const issues = [];
+  const lines = String(text).split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNo = i + 1;
+    let line = lines[i].trim();
+    if (line === '' || line.startsWith('#')) continue;
+    line = line.replace(/^export\s+/, '');
+
+    const match = KEY_LINE.exec(line);
+    if (!match) {
+      issues.push({ line: lineNo, message: 'line could not be parsed as KEY=value' });
+      continue;
+    }
+    const key = match[1];
+    let raw = match[2];
+    let value;
+
+    const quote = raw[0];
+    if (quote === '"' || quote === "'" || quote === '`') {
+      let end = raw.indexOf(quote, 1);
+      if (end !== -1) {
+        value = raw.slice(1, end);
+      } else {
+        // Multi-line quoted value: read until the closing quote.
+        const parts = [raw.slice(1)];
+        let closed = false;
+        while (i + 1 < lines.length) {
+          i++;
+          const next = lines[i];
+          end = next.indexOf(quote);
+          if (end !== -1) {
+            parts.push(next.slice(0, end));
+            closed = true;
+            break;
+          }
+          parts.push(next);
+        }
+        if (!closed) {
+          issues.push({ line: lineNo, message: `unterminated quoted value for ${key}` });
+          continue;
+        }
+        value = parts.join('\n');
+      }
+    } else {
+      const comment = raw.search(/\s#/);
+      if (comment !== -1) raw = raw.slice(0, comment);
+      value = raw.trim();
+    }
+
+    if (entries.has(key)) issues.push({ line: lineNo, message: `${key} is defined more than once` });
+    entries.set(key, { value, line: lineNo });
+  }
+
+  return { entries, issues };
+}

package/src/utils/errors.js

@@ -0,0 +1,15 @@
+/** An expected error caused by bad input or environment; shown without a stack trace. */
+export class DevDoctorError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DevDoctorError';
+  }
+}
+
+export class UtilityMissingError extends Error {
+  constructor(utility) {
+    super(`Required system utility "${utility}" was not found`);
+    this.name = 'UtilityMissingError';
+    this.utility = utility;
+  }
+}

package/src/utils/paths.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DevDoctorError } from './errors.js';
+
+export function resolveProjectRoot(cwd = process.cwd()) {
+  const root = path.resolve(cwd);
+  let stat;
+  try {
+    stat = fs.statSync(root);
+  } catch {
+    throw new DevDoctorError(`Directory not found: ${root}`);
+  }
+  if (!stat.isDirectory()) throw new DevDoctorError(`Not a directory: ${root}`);
+  return root;
+}
+
+/** Resolve a path inside the project root; refuse anything that escapes it. */
+export function safeProjectPath(root, relativePath) {
+  const target = path.resolve(root, relativePath);
+  const rel = path.relative(root, target);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new DevDoctorError(`Refusing to access a path outside the project: ${relativePath}`);
+  }
+  return target;
+}
+
+export function exists(file) {
+  try {
+    fs.accessSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readTextIfExists(file, maxBytes = 1024 * 1024) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size > maxBytes) return null;
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}

package/src/utils/process-info.js

@@ -0,0 +1,34 @@
+import { execFile } from 'node:child_process';
+
+/**
+ * Run a command with an argument array (no shell) and a timeout. Never throws.
+ * The shell option exists only for Windows .cmd shims and must be used with fixed arguments.
+ */
+export function runCommand(command, args = [], { timeout = 5000, shell = false, env } = {}) {
+  return new Promise((resolve) => {
+    execFile(command, args, { timeout, shell, env: env ? { ...process.env, ...env } : undefined, windowsHide: true, maxBuffer: 5 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (!error) {
+        resolve({ ok: true, code: 0, stdout: String(stdout), stderr: String(stderr), missing: false, timedOut: false });
+        return;
+      }
+      resolve({
+        ok: false,
+        code: typeof error.code === 'number' ? error.code : null,
+        stdout: String(stdout ?? ''),
+        stderr: String(stderr ?? ''),
+        missing: error.code === 'ENOENT',
+        timedOut: Boolean(error.killed),
+      });
+    });
+  });
+}
+
+/** Get a tool's version, e.g. `npm --version`. Returns null when it is not available. */
+export async function getToolVersion(tool, { run = runCommand, platform = process.platform } = {}) {
+  // Package managers are .cmd shims on Windows and need a shell; the arguments are constant.
+  const r = platform === 'win32'
+    ? await run(`${tool} --version`, [], { timeout: 8000, shell: true })
+    : await run(tool, ['--version'], { timeout: 8000 });
+  if (!r.ok) return null;
+  return r.stdout.trim().split(/\r?\n/)[0] || null;
+}

package/src/utils/prompt.js

@@ -0,0 +1,24 @@
+import { confirm, select } from '@inquirer/prompts';
+
+export function isInteractive({ ci = false } = {}) {
+  return Boolean(process.stdin.isTTY && process.stderr.isTTY) && !ci && !process.env.CI;
+}
+
+// Prompts are written to stderr so stdout stays clean (e.g. for --json).
+const context = { output: process.stderr };
+
+export async function askConfirm(message, defaultValue = false) {
+  try {
+    return await confirm({ message, default: defaultValue }, context);
+  } catch {
+    return false; // Ctrl+C or closed input counts as "no".
+  }
+}
+
+export async function askSelect(message, choices) {
+  try {
+    return await select({ message, choices }, context);
+  } catch {
+    return null;
+  }
+}

package/src/utils/redact.js

@@ -0,0 +1,18 @@
+const SECRET_WORDS = 'password|passwd|pwd|token|secret|api[-_]?key|apikey|auth|credential|access[-_]?key|private[-_]?key';
+
+/** Mask credentials embedded in URLs (scheme://user:pass@host). */
+export function redact(text) {
+  return String(text).replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, '$1***@');
+}
+
+/**
+ * Mask common secrets in a process command line: URL credentials, --password=x / --token x style flags,
+ * SECRET_KEY=x style assignments and Bearer/Basic tokens. Over-redaction is preferred to leaking.
+ */
+export function redactCommandLine(command) {
+  if (command === null || command === undefined) return command;
+  return redact(command)
+    .replace(new RegExp(`(--?[A-Za-z0-9_-]*(?:${SECRET_WORDS})[A-Za-z0-9_-]*)(=|\\s+)("[^"]*"|'[^']*'|\\S+)`, 'gi'), '$1$2***')
+    .replace(new RegExp(`\\b([A-Za-z0-9_]*(?:${SECRET_WORDS})[A-Za-z0-9_]*)=("[^"]*"|'[^']*'|[^\\s*]\\S*)`, 'gi'), '$1=***')
+    .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, '$1 ***');
+}