ports-manager 1.0.0 → 1.0.1

package/src/leases.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const LEASE_DIR = path.join(os.homedir() || os.tmpdir(), '.ports-manager');
+const LEASE_FILE = path.join(LEASE_DIR, 'leases.json');
+const LOCK_FILE = path.join(LEASE_DIR, 'leases.lock');
+const STALE_LOCK_MS = 10000;
+
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but belongs to another user.
+    return error.code === 'EPERM';
+  }
+}
+
+function ensureDirectory() {
+  fs.mkdirSync(LEASE_DIR, { recursive: true });
+}
+
+/**
+ * Best-effort exclusive lock. The lease file is a secondary guard (allocation also
+ * holds real listening sockets), so a lock we cannot take is not worth failing over.
+ */
+function withLock(action) {
+  ensureDirectory();
+  const deadline = Date.now() + 2000;
+  let handle;
+  while (!handle) {
+    try {
+      handle = fs.openSync(LOCK_FILE, 'wx');
+    } catch (error) {
+      if (error.code !== 'EEXIST') return action();
+      let stale = true;
+      try {
+        stale = Date.now() - fs.statSync(LOCK_FILE).mtimeMs > STALE_LOCK_MS;
+      } catch {
+        stale = true;
+      }
+      if (stale) {
+        try {
+          fs.unlinkSync(LOCK_FILE);
+        } catch {
+          /* another process won the race; retry */
+        }
+      } else if (Date.now() > deadline) {
+        return action();
+      }
+    }
+  }
+  try {
+    return action();
+  } finally {
+    fs.closeSync(handle);
+    try {
+      fs.unlinkSync(LOCK_FILE);
+    } catch {
+      /* already removed */
+    }
+  }
+}
+
+function parse(raw) {
+  const parsed = JSON.parse(raw);
+  return Array.isArray(parsed) ? parsed : [];
+}
+
+/** Reads leases, dropping any whose owning process has exited. */
+function readLeases() {
+  let entries;
+  try {
+    entries = parse(fs.readFileSync(LEASE_FILE, 'utf8'));
+  } catch {
+    return [];
+  }
+  return entries.filter((entry) => entry && Number.isInteger(entry.port) && alive(entry.pid));
+}
+
+function writeLeases(entries) {
+  ensureDirectory();
+  const temporary = `${LEASE_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(entries, null, 2)}\n`, 'utf8');
+  fs.renameSync(temporary, LEASE_FILE);
+}
+
+/** Ports currently leased by other live ports-manager instances. */
+function heldPorts() {
+  try {
+    return new Set(readLeases().filter((entry) => entry.pid !== process.pid).map((entry) => entry.port));
+  } catch {
+    return new Set();
+  }
+}
+
+/** Records this process as the owner of `ports`, replacing any earlier claim of ours. */
+function acquire(ports, root) {
+  try {
+    return withLock(() => {
+      const entries = readLeases().filter((entry) => entry.pid !== process.pid);
+      const startedAt = new Date().toISOString();
+      for (const port of ports) {
+        if (Number.isInteger(port)) entries.push({ port, pid: process.pid, root, startedAt });
+      }
+      writeLeases(entries);
+      return true;
+    });
+  } catch {
+    return false;
+  }
+}
+
+function release() {
+  try {
+    return withLock(() => {
+      writeLeases(readLeases().filter((entry) => entry.pid !== process.pid));
+      return true;
+    });
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { LEASE_FILE, acquire, alive, heldPorts, readLeases, release, withLock };

package/src/preflight.js

@@ -0,0 +1,214 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+/** Wrappers that prefix the real dev binary; the token after them matters too. */
+const WRAPPERS = new Set(['cross-env', 'dotenv', 'env-cmd', 'npx', 'pnpm', 'yarn', 'bun', 'run', 'exec']);
+/** Always present, so never worth reporting as missing. */
+const ALWAYS_AVAILABLE = new Set(['node', 'npm', 'npm.cmd', 'sh', 'bash', 'cmd', 'echo', 'set', 'wait']);
+
+const PACKAGE_MANAGERS = {
+  npm: { lockfile: 'package-lock.json', install: ['install'] },
+  pnpm: { lockfile: 'pnpm-lock.yaml', install: ['install'] },
+  yarn: { lockfile: 'yarn.lock', install: ['install'] },
+  bun: { lockfile: 'bun.lockb', install: ['install'] }
+};
+
+/** Windows needs an interpreter for `.cmd` shims; spawn cannot exec them directly. */
+function commandInvocation(name) {
+  if (process.platform === 'win32') {
+    return { command: process.env.ComSpec || 'cmd.exe', argsPrefix: ['/d', '/s', '/c', `${name}.cmd`] };
+  }
+  return { command: name, argsPrefix: [] };
+}
+
+function npmInvocation() {
+  return commandInvocation('npm');
+}
+
+function ancestors(directory) {
+  const chain = [];
+  let current = path.resolve(directory);
+  while (true) {
+    chain.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) return chain;
+    current = parent;
+  }
+}
+
+/** Every node_modules/.bin from `directory` up to the filesystem root (handles hoisted installs). */
+function binDirectories(directory) {
+  return ancestors(directory)
+    .map((entry) => path.join(entry, 'node_modules', '.bin'))
+    .filter((entry) => fs.existsSync(entry));
+}
+
+function detectPackageManager(directory) {
+  for (const entry of ancestors(directory)) {
+    const manifest = path.join(entry, 'package.json');
+    if (fs.existsSync(manifest)) {
+      try {
+        const declared = JSON.parse(fs.readFileSync(manifest, 'utf8')).packageManager;
+        const name = typeof declared === 'string' ? declared.split('@')[0] : null;
+        if (name && PACKAGE_MANAGERS[name]) return name;
+      } catch {
+        /* unreadable manifest; fall through to lockfile detection */
+      }
+    }
+    for (const [name, meta] of Object.entries(PACKAGE_MANAGERS)) {
+      if (fs.existsSync(path.join(entry, meta.lockfile))) return name;
+    }
+  }
+  return 'npm';
+}
+
+function splitSegments(script) {
+  return String(script || '').split(/&&|\|\||;|(?<!\|)\|(?!\|)/g);
+}
+
+function stripQuotes(token) {
+  return token.replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Binaries an npm script needs before it can run. Skips `KEY=value` prefixes, looks past
+ * known wrappers, and ignores paths and always-available commands.
+ */
+function requiredBinaries(script) {
+  const found = [];
+  for (const segment of splitSegments(script)) {
+    const tokens = segment.trim().split(/\s+/).map(stripQuotes).filter(Boolean);
+    let index = 0;
+    let considered = 0;
+    while (index < tokens.length && considered < 2) {
+      const token = tokens[index];
+      index += 1;
+      // Skip flags and `KEY=value` prefixes, both leading and cross-env style.
+      if (token.startsWith('-') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) continue;
+      considered += 1;
+      const bare = path.basename(token);
+      if (token.includes('/') || token.includes('\\') || bare !== token) break;
+      if (ALWAYS_AVAILABLE.has(token)) break;
+      if (!found.includes(token)) found.push(token);
+      if (!WRAPPERS.has(token)) break;
+    }
+  }
+  return found;
+}
+
+function executableCandidates(directory, name) {
+  const suffixes = process.platform === 'win32' ? ['.cmd', '.exe', '.bat', '.ps1', ''] : [''];
+  return suffixes.map((suffix) => path.join(directory, `${name}${suffix}`));
+}
+
+/** Resolves `name` against local .bin directories first, then PATH. */
+function resolveBinary(name, directory) {
+  for (const binDirectory of binDirectories(directory)) {
+    for (const candidate of executableCandidates(binDirectory, name)) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  const pathEntries = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const entry of pathEntries) {
+    for (const candidate of executableCandidates(entry, name)) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function packageInstalled(name, directory) {
+  return ancestors(directory)
+    .some((entry) => fs.existsSync(path.join(entry, 'node_modules', name, 'package.json')));
+}
+
+/**
+ * Declared dependencies with nothing on disk. A partially installed `node_modules` passes
+ * a dev-binary check and then dies at require time, which is worth catching before we
+ * start anything. optionalDependencies are skipped — absence there is legitimate.
+ */
+function missingPackages(pkg, directory) {
+  const declared = [...Object.keys(pkg.dependencies || {}), ...Object.keys(pkg.devDependencies || {})];
+  return declared.filter((name) => !packageInstalled(name, directory));
+}
+
+/**
+ * Verifies a project can actually start: dependencies present and every binary its dev
+ * script invokes resolvable. This is the check whose absence produced a bare
+ * `'vite' is not recognized` from cmd.exe with no explanation.
+ */
+function checkProject(project) {
+  const script = (project.pkg.scripts || {})[project.script] || '';
+  const hasNodeModules = fs.existsSync(path.join(project.directory, 'node_modules')) ||
+    binDirectories(project.directory).length > 0;
+  const missing = requiredBinaries(script)
+    .filter((name) => !resolveBinary(name, project.directory));
+  const missingDeps = missingPackages(project.pkg, project.directory);
+  return {
+    role: project.role,
+    directory: project.directory,
+    script,
+    hasNodeModules,
+    missing,
+    missingDeps,
+    packageManager: detectPackageManager(project.directory),
+    ok: missing.length === 0 && missingDeps.length === 0
+  };
+}
+
+function installDependencies(check, logger = console) {
+  const meta = PACKAGE_MANAGERS[check.packageManager] || PACKAGE_MANAGERS.npm;
+  const invocation = commandInvocation(check.packageManager);
+  const args = [...invocation.argsPrefix, ...meta.install];
+  logger.log(`[${check.role}] running \`${check.packageManager} ${meta.install.join(' ')}\` in ${check.directory}`);
+  return new Promise((resolve) => {
+    const child = spawn(invocation.command, args, {
+      cwd: check.directory,
+      env: process.env,
+      stdio: 'inherit',
+      shell: false
+    });
+    child.once('error', (error) => {
+      logger.error(`[${check.role}] install failed to start: ${error.message}`);
+      resolve(1);
+    });
+    child.once('exit', (code) => resolve(code === null ? 1 : code));
+  });
+}
+
+function summarize(check) {
+  if (!check.hasNodeModules) return 'dependencies are not installed';
+  const parts = [];
+  if (check.missing.length) parts.push(`${check.missing.map((name) => `\`${name}\``).join(', ')} not found`);
+  if (check.missingDeps.length) {
+    const shown = check.missingDeps.slice(0, 3).join(', ');
+    const extra = check.missingDeps.length > 3 ? ` and ${check.missingDeps.length - 3} more` : '';
+    parts.push(`${check.missingDeps.length} package(s) missing from node_modules (${shown}${extra})`);
+  }
+  return parts.join('; ') || 'dependencies are incomplete';
+}
+
+function describeFailure(check) {
+  return [
+    `${check.role}: ${summarize(check)} in ${check.directory}`,
+    `  fix: cd ${check.directory} && ${check.packageManager} install`
+  ].join('\n');
+}
+
+module.exports = {
+  PACKAGE_MANAGERS,
+  binDirectories,
+  checkProject,
+  commandInvocation,
+  describeFailure,
+  detectPackageManager,
+  installDependencies,
+  missingPackages,
+  npmInvocation,
+  requiredBinaries,
+  resolveBinary,
+  summarize
+};

package/src/process-manager.js

@@ -1,97 +1,187 @@
-'use strict';
-
-const { spawn } = require('node:child_process');
-const treeKill = require('tree-kill');
-const chalk = require('chalk');
-const { isPortFree } = require('./runtime');
-
-function pipeLines(stream, output, prefix, color) {
-  let pending = '';
-  stream.on('data', (chunk) => {
-    pending += chunk.toString();
-    const lines = pending.split(/\r?\n/);
-    pending = lines.pop();
-    for (const line of lines) output.write(`${chalk[color](`[${prefix}]`)} ${line}\n`);
-  });
-  stream.on('end', () => {
-    if (pending) output.write(`${chalk[color](`[${prefix}]`)} ${pending}\n`);
-  });
-}
-
-function spawnSpec(spec) {
-  const child = spawn(spec.command, spec.args, {
-    cwd: spec.cwd,
-    env: { ...process.env, ...spec.env },
-    windowsHide: false,
-    stdio: ['inherit', 'pipe', 'pipe'],
-    shell: false
-  });
-  pipeLines(child.stdout, process.stdout, spec.name, spec.color);
-  pipeLines(child.stderr, process.stderr, spec.name, spec.color);
-  return child;
-}
-
-async function waitForListening(port, timeout) {
-  const deadline = Date.now() + timeout;
-  while (Date.now() < deadline) {
-    if (!await isPortFree(port)) return true;
-    await new Promise((resolve) => setTimeout(resolve, 100));
-  }
-  return false;
-}
-
-function killTree(pid, signal = 'SIGTERM') {
-  return new Promise((resolve) => {
-    if (!pid) return resolve();
-    treeKill(pid, signal, () => resolve());
-  });
-}
-
-async function runProcesses(specs, options = {}) {
-  const children = [];
-  let stopping = false;
-  let resolveDone;
-  const done = new Promise((resolve) => { resolveDone = resolve; });
-
-  const stop = async (code = 0) => {
-    if (stopping) return;
-    stopping = true;
-    await Promise.all(children.filter((child) => child.exitCode === null)
-      .map((child) => killTree(child.pid)));
-    resolveDone(code);
-  };
-
-  const register = (spec) => {
-    const child = spawnSpec(spec);
-    children.push(child);
-    child.once('error', (error) => {
-      console.error(`[${spec.name}] failed to launch: ${error.message}`);
-      stop(1);
-    });
-    child.once('exit', (code, signal) => {
-      if (!stopping) {
-        console.error(`[${spec.name}] exited (${signal || `code ${code}`}); stopping the other services.`);
-        stop(code || 1);
-      }
-    });
-  };
-
-  register(specs.backend);
-  if (options.waitForBackend > 0) {
-    const ready = await waitForListening(options.backendPort, options.waitForBackend);
-    if (!ready) {
-      console.warn(`[Ports Manager] Backend did not listen within ${options.waitForBackend}ms; starting frontend anyway.`);
-    }
-  }
-  register(specs.frontend);
-
-  const onSignal = () => stop(0);
-  process.once('SIGINT', onSignal);
-  process.once('SIGTERM', onSignal);
-  const code = await done;
-  process.removeListener('SIGINT', onSignal);
-  process.removeListener('SIGTERM', onSignal);
-  return code;
-}
-
-module.exports = { killTree, pipeLines, runProcesses, spawnSpec, waitForListening };
+'use strict';
+
+const { spawn } = require('node:child_process');
+const treeKill = require('tree-kill');
+const chalk = require('chalk');
+const { isPortFree } = require('./runtime');
+
+/** A child dying this quickly almost always means it never really started. */
+const FAST_EXIT_MS = 15000;
+const RECENT_LINES = 10;
+
+function pipeLines(stream, output, prefix, color, recent) {
+  let pending = '';
+  stream.on('data', (chunk) => {
+    pending += chunk.toString();
+    const lines = pending.split(/\r?\n/);
+    pending = lines.pop();
+    for (const line of lines) {
+      if (recent) {
+        recent.push(line);
+        if (recent.length > RECENT_LINES) recent.shift();
+      }
+      output.write(`${chalk[color](`[${prefix}]`)} ${line}\n`);
+    }
+  });
+  stream.on('end', () => {
+    if (pending) output.write(`${chalk[color](`[${prefix}]`)} ${pending}\n`);
+  });
+}
+
+function spawnSpec(spec, recent) {
+  const child = spawn(spec.command, spec.args, {
+    cwd: spec.cwd,
+    env: { ...process.env, ...spec.env },
+    windowsHide: false,
+    stdio: ['inherit', 'pipe', 'pipe'],
+    shell: false
+  });
+  pipeLines(child.stdout, process.stdout, spec.name, spec.color, recent);
+  pipeLines(child.stderr, process.stderr, spec.name, spec.color, recent);
+  return child;
+}
+
+/**
+ * Turns a raw shell error into something actionable. A bare
+ * `'vite' is not recognized as an internal or external command` tells the user nothing
+ * about which directory is missing its dependencies.
+ */
+function explainExit(spec, recent) {
+  const text = recent.join('\n');
+  const notRecognized = text.match(/'([^']+)' is not recognized as an internal or external command/) ||
+    text.match(/([\w.@/-]+): (?:command )?not found/) ||
+    text.match(/spawn ([\w.@/-]+) ENOENT/);
+  if (notRecognized) {
+    return [
+      `${spec.name} could not run \`${notRecognized[1]}\` — it is not installed in ${spec.cwd}.`,
+      `  fix: cd ${spec.cwd} && npm install   (or re-run ports-manager without --no-install)`
+    ];
+  }
+  // ESM says "Cannot find package", CommonJS says "Cannot find module".
+  const missingModule = text.match(/Cannot find (?:module|package) ['"]([^'"]+)['"]/);
+  if (missingModule) {
+    return [
+      `${spec.name} is missing the package \`${missingModule[1]}\`; its node_modules is incomplete.`,
+      `  fix: cd ${spec.cwd} && npm install`
+    ];
+  }
+  const inUse = text.match(/EADDRINUSE[^\n]*?(\d{2,5})/);
+  if (inUse) {
+    return [
+      `${spec.name} could not bind port ${inUse[1]} — something else took it after allocation.`,
+      '  fix: re-run ports-manager, or pin a port with --backend-port / --frontend-port'
+    ];
+  }
+  if (/ERR_MODULE_NOT_FOUND|ERR_REQUIRE_ESM/.test(text)) {
+    return [`${spec.name} failed to load its entry module; see the output above.`];
+  }
+  // Unrecognized, but clearly not healthy — say that rather than guessing at a cause.
+  if (/\b(error|failed|exception|ECONNREFUSED)\b/i.test(text)) {
+    return [`${spec.name} reported an error while starting; see its output above.`];
+  }
+  return null;
+}
+
+async function waitForListening(port, timeout, shouldAbort = () => false) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    if (shouldAbort()) return false;
+    if (!await isPortFree(port)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  return false;
+}
+
+function killTree(pid, signal = 'SIGTERM') {
+  return new Promise((resolve) => {
+    if (!pid) return resolve();
+    treeKill(pid, signal, () => resolve());
+  });
+}
+
+async function runProcesses(specs, options = {}) {
+  const children = [];
+  const output = new Map();
+  const startedAt = new Map();
+  let stopping = false;
+  let resolveDone;
+  const done = new Promise((resolve) => { resolveDone = resolve; });
+
+  const stop = async (code = 0) => {
+    if (stopping) return;
+    stopping = true;
+    await Promise.all(children.filter((child) => child.exitCode === null)
+      .map((child) => killTree(child.pid)));
+    resolveDone(code);
+  };
+
+  const register = (spec) => {
+    const recent = [];
+    output.set(spec.name, recent);
+    startedAt.set(spec.name, Date.now());
+    const child = spawnSpec(spec, recent);
+    children.push(child);
+    child.once('error', (error) => {
+      console.error(`[${spec.name}] failed to launch: ${error.message}`);
+      stop(1);
+    });
+    child.once('exit', (code, signal) => {
+      if (stopping) return;
+      const elapsed = Date.now() - startedAt.get(spec.name);
+      console.error(`\n[${spec.name}] exited (${signal || `code ${code}`}).`);
+      if (code && elapsed < FAST_EXIT_MS) {
+        const explanation = explainExit(spec, recent);
+        if (explanation) for (const line of explanation) console.error(line);
+      }
+      console.error('Stopping the other services.');
+      stop(code || 1);
+    });
+  };
+
+  register(specs.backend);
+  if (options.waitForBackend > 0) {
+    const ready = await waitForListening(options.backendPort, options.waitForBackend, () => stopping);
+    if (!ready && !stopping) {
+      console.warn(`[Ports Manager] Backend did not listen within ${options.waitForBackend}ms; starting frontend anyway.`);
+    }
+  }
+  if (!stopping) register(specs.frontend);
+
+  // Verify what actually happened instead of guessing from a static scan beforehand.
+  // Attached immediately so a failure here can never surface as an unhandled rejection.
+  const verify = (async () => {
+    const timeout = options.verifyTimeout ?? 45000;
+    let backendUp = await waitForListening(options.backendPort, timeout, () => stopping);
+    if (stopping) return;
+    if (!backendUp) {
+      console.warn(`\n[Ports Manager] Backend has not bound port ${options.backendPort} after ${Math.round(timeout / 1000)}s.`);
+      // A watcher (tsx watch, nodemon) survives a crash, so the process is still alive and
+      // the real cause is only visible in its output.
+      const explanation = explainExit(specs.backend, output.get(specs.backend.name) || []);
+      if (explanation) for (const line of explanation) console.warn(line);
+      else {
+        console.warn('  Check the backend output above for an error first. If it looks healthy, it may');
+        console.warn(`  be ignoring PORT — set PORT in its .env or pass --backend-port ${options.backendPort}.`);
+      }
+      // A slow dependency (a database handshake, say) can still come good.
+      backendUp = await waitForListening(options.backendPort, timeout, () => stopping);
+      if (stopping) return;
+      if (backendUp) console.log(`[Ports Manager] Backend came up on port ${options.backendPort}.`);
+    }
+    const frontendUp = options.frontendPort
+      ? await waitForListening(options.frontendPort, timeout, () => stopping)
+      : true;
+    if (!stopping && options.onReady) options.onReady({ backendUp, frontendUp });
+  })().catch(() => {});
+
+  const onSignal = () => stop(0);
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+  const code = await done;
+  await verify.catch(() => {});
+  process.removeListener('SIGINT', onSignal);
+  process.removeListener('SIGTERM', onSignal);
+  return code;
+}
+
+module.exports = { explainExit, killTree, pipeLines, runProcesses, spawnSpec, waitForListening };