ports-manager 1.0.0 → 1.0.1

package/src/cors.js

@@ -1,55 +1,95 @@
-'use strict';
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-
-const SHIM_SOURCE = String.raw`'use strict';
-const http = require('node:http');
-const originalEmit = http.Server.prototype.emit;
-http.Server.prototype.emit = function portsManagerEmit(event, req, res) {
-  if (event !== 'request' || !req || !res) {
-    return originalEmit.apply(this, arguments);
-  }
-  const requestedOrigin = req.headers && req.headers.origin;
-  const configuredOrigin = process.env.PORTS_MANAGER_CORS_ORIGIN;
-  const origin = requestedOrigin || configuredOrigin;
-  if (origin && !res.headersSent) {
-    res.setHeader('Access-Control-Allow-Origin', origin);
-    res.setHeader('Vary', mergeVary(res.getHeader('Vary'), 'Origin'));
-    if (process.env.PORTS_MANAGER_CORS_CREDENTIALS !== 'false') {
-      res.setHeader('Access-Control-Allow-Credentials', 'true');
-    }
-    res.setHeader('Access-Control-Allow-Methods',
-      req.headers['access-control-request-method'] || 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers',
-      req.headers['access-control-request-headers'] || 'Content-Type,Authorization');
-  }
-  if (req.method === 'OPTIONS') {
-    res.statusCode = 204;
-    res.setHeader('Content-Length', '0');
-    res.end();
-    return true;
-  }
-  return originalEmit.apply(this, arguments);
-};
-function mergeVary(current, value) {
-  const values = String(current || '').split(',').map((item) => item.trim()).filter(Boolean);
-  if (!values.some((item) => item.toLowerCase() === value.toLowerCase())) values.push(value);
-  return values.join(', ');
-}
-`;
-
-function createCorsShim() {
-  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'ports-manager-'));
-  const filename = path.join(directory, 'cors-preload.cjs');
-  fs.writeFileSync(filename, SHIM_SOURCE, { encoding: 'utf8', mode: 0o600 });
-  return {
-    filename,
-    cleanup() {
-      fs.rmSync(directory, { recursive: true, force: true });
-    }
-  };
-}
-
-module.exports = { SHIM_SOURCE, createCorsShim };
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+/**
+ * Last-resort CORS shim, enabled only by --force-cors.
+ *
+ * The previous version set headers before the app ran, so any app using the `cors`
+ * middleware simply overwrote them. This one patches writeHead/end so the headers are
+ * applied at send time — including stripping Access-Control-* keys passed inline to
+ * writeHead — which is the only way to win against the app's own middleware.
+ */
+const SHIM_SOURCE = String.raw`'use strict';
+const http = require('node:http');
+
+function mergeVary(current, value) {
+  const values = String(current || '').split(',').map((item) => item.trim()).filter(Boolean);
+  if (!values.some((item) => item.toLowerCase() === value.toLowerCase())) values.push(value);
+  return values.join(', ');
+}
+
+function corsHeaders(req) {
+  const origin = (req.headers && req.headers.origin) || process.env.PORTS_MANAGER_CORS_ORIGIN;
+  if (!origin) return null;
+  const headers = {
+    'Access-Control-Allow-Origin': origin,
+    'Access-Control-Allow-Methods':
+      req.headers['access-control-request-method'] || 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS',
+    'Access-Control-Allow-Headers':
+      req.headers['access-control-request-headers'] || 'Content-Type,Authorization'
+  };
+  if (process.env.PORTS_MANAGER_CORS_CREDENTIALS !== 'false') {
+    headers['Access-Control-Allow-Credentials'] = 'true';
+  }
+  return headers;
+}
+
+function applyHeaders(req, res, inlineHeaders) {
+  const headers = corsHeaders(req);
+  if (!headers) return;
+  if (inlineHeaders && typeof inlineHeaders === 'object' && !Array.isArray(inlineHeaders)) {
+    for (const key of Object.keys(inlineHeaders)) {
+      if (key.toLowerCase().indexOf('access-control-') === 0) delete inlineHeaders[key];
+    }
+  }
+  if (res.headersSent) return;
+  for (const [key, value] of Object.entries(headers)) res.setHeader(key, value);
+  res.setHeader('Vary', mergeVary(res.getHeader('Vary'), 'Origin'));
+}
+
+const originalEmit = http.Server.prototype.emit;
+http.Server.prototype.emit = function portsManagerEmit(event, req, res) {
+  if (event !== 'request' || !req || !res) {
+    return originalEmit.apply(this, arguments);
+  }
+
+  const originalWriteHead = res.writeHead;
+  res.writeHead = function patchedWriteHead(...args) {
+    const inline = args.find((value) => value && typeof value === 'object');
+    applyHeaders(req, res, inline);
+    return originalWriteHead.apply(this, args);
+  };
+
+  const originalEnd = res.end;
+  res.end = function patchedEnd(...args) {
+    applyHeaders(req, res, null);
+    return originalEnd.apply(this, args);
+  };
+
+  if (req.method === 'OPTIONS') {
+    applyHeaders(req, res, null);
+    res.statusCode = 204;
+    res.setHeader('Content-Length', '0');
+    originalEnd.call(res);
+    return true;
+  }
+  return originalEmit.apply(this, arguments);
+};
+`;
+
+function createCorsShim() {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'ports-manager-'));
+  const filename = path.join(directory, 'cors-preload.cjs');
+  fs.writeFileSync(filename, SHIM_SOURCE, { encoding: 'utf8', mode: 0o600 });
+  return {
+    filename,
+    cleanup() {
+      fs.rmSync(directory, { recursive: true, force: true });
+    }
+  };
+}
+
+module.exports = { SHIM_SOURCE, createCorsShim };

package/src/detect.js

@@ -1,114 +1,281 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-function readPackage(directory) {
-  const filename = path.join(directory, 'package.json');
-  if (!fs.existsSync(filename)) return null;
-  try {
-    return JSON.parse(fs.readFileSync(filename, 'utf8'));
-  } catch (error) {
-    throw new Error(`invalid package.json at ${filename}: ${error.message}`);
-  }
-}
-
-function validProject(directory) {
-  return fs.existsSync(directory) && fs.statSync(directory).isDirectory() && Boolean(readPackage(directory));
-}
-
-function detectFolders(cwd, overrides = {}) {
-  const pairs = overrides.pairs || [['frontend', 'backend'], ['client', 'server']];
-  const found = pairs.filter(([front, back]) =>
-    validProject(path.join(cwd, front)) && validProject(path.join(cwd, back)));
-
-  let frontend = overrides.frontend && path.resolve(cwd, overrides.frontend);
-  let backend = overrides.backend && path.resolve(cwd, overrides.backend);
-
-  if (!frontend && !backend) {
-    if (found.length > 1) {
-      throw new Error('ambiguous project layout: multiple configured folder pairs exist; use --frontend-dir and --backend-dir');
-    }
-    if (found.length === 1) {
-      frontend = path.join(cwd, found[0][0]);
-      backend = path.join(cwd, found[0][1]);
-    } else {
-      const basename = path.basename(cwd).toLowerCase();
-      for (const [front, back] of pairs) {
-        if (basename === front || basename === back) {
-          const parent = path.dirname(cwd);
-          if (validProject(path.join(parent, front)) && validProject(path.join(parent, back))) {
-            throw new Error(`run ports-manager from the parent directory: ${parent}`);
-          }
-        }
-      }
-      throw new Error('no paired frontend/backend or client/server package.json projects found');
-    }
-  } else if (!frontend || !backend) {
-    const wanted = frontend ? 'backend' : 'frontend';
-    const candidates = pairs.map((pair) => pair[wanted === 'frontend' ? 0 : 1])
-      .map((name) => path.join(cwd, name)).filter(validProject);
-    if (candidates.length !== 1) throw new Error(`cannot infer ${wanted}; specify --${wanted}-dir`);
-    if (wanted === 'frontend') frontend = candidates[0];
-    else backend = candidates[0];
-  }
-
-  if (!validProject(frontend)) throw new Error(`frontend must be a directory containing package.json: ${frontend}`);
-  if (!validProject(backend)) throw new Error(`backend must be a directory containing package.json: ${backend}`);
-  if (path.resolve(frontend) === path.resolve(backend)) throw new Error('frontend and backend must be distinct directories');
-  return { frontend, backend };
-}
-
-function hasDependency(pkg, name) {
-  return Boolean((pkg.dependencies && pkg.dependencies[name]) ||
-    (pkg.devDependencies && pkg.devDependencies[name]));
-}
-
-function classifyProject(directory, role) {
-  const pkg = readPackage(directory);
-  const scripts = pkg.scripts || {};
-  const script = scripts.dev ? 'dev' : scripts.start ? 'start' : null;
-  if (!script) throw new Error(`${directory} has neither a dev nor start script`);
-
-  let framework = 'generic';
-  if (role === 'frontend') {
-    if (hasDependency(pkg, 'react-scripts')) framework = 'cra';
-    else if (hasDependency(pkg, 'vite')) framework = 'vite';
-    else if (hasDependency(pkg, 'next')) framework = 'next';
-  } else {
-    for (const [dependency, name] of [
-      ['@nestjs/core', 'nest'], ['express', 'express'], ['koa', 'koa'], ['fastify', 'fastify']
-    ]) {
-      if (hasDependency(pkg, dependency)) {
-        framework = name;
-        break;
-      }
-    }
-  }
-  return { directory, pkg, role, framework, script };
-}
-
-function likelyEntryFiles(project) {
-  const scriptText = (project.pkg.scripts && project.pkg.scripts[project.script]) || '';
-  const entries = [];
-  const match = scriptText.match(/(?:node|nodemon|tsx|ts-node)\s+(?:--\S+\s+)*["']?([^\s"']+\.[cm]?[jt]s)/);
-  if (match) entries.push(match[1]);
-  for (const candidate of ['server.js', 'index.js', 'app.js', 'src/server.js', 'src/index.js', 'src/main.ts']) {
-    if (!entries.includes(candidate)) entries.push(candidate);
-  }
-  return entries.map((entry) => path.resolve(project.directory, entry)).filter(fs.existsSync);
-}
-
-function scanBackend(project) {
-  const files = likelyEntryFiles(project).slice(0, 3);
-  const source = files.map((file) => fs.readFileSync(file, 'utf8')).join('\n');
-  const hasEnvPort = /\bprocess\.env\.PORT\b|\bprocess\.env\[['"]PORT['"]\]/.test(source);
-  const literals = [...source.matchAll(/\.listen\s*\(\s*(\d{2,5})\b/g)].map((match) => Number(match[1]));
-  const corsDetected = /\brequire\s*\(\s*['"]cors['"]\s*\)|\bfrom\s+['"]cors['"]|\bapp\.use\s*\(\s*cors\s*\(/.test(source) ||
-    hasDependency(project.pkg, 'cors');
-  return { files, hasEnvPort, literals: [...new Set(literals)], corsDetected };
-}
-
-module.exports = {
-  classifyProject, detectFolders, hasDependency, readPackage, scanBackend, validProject
-};
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts']);
+const SKIP_DIRECTORIES = new Set([
+  'node_modules', 'dist', 'build', 'out', '.git', '.next', '.cache', 'coverage', '.vite', 'public'
+]);
+const MAX_SOURCE_FILES = 80;
+const MAX_SOURCE_BYTES = 256 * 1024;
+
+/** Origin env names backends conventionally read for their CORS allowlist. */
+const CORS_ENV_NAMES = [
+  'CORS_ORIGIN', 'CORS_ORIGINS', 'CORS_ALLOWED_ORIGINS', 'ALLOWED_ORIGINS',
+  'CLIENT_URL', 'CLIENT_ORIGIN', 'FRONTEND_URL', 'FRONTEND_ORIGIN', 'APP_URL', 'WEB_ORIGIN'
+];
+
+const VITE_CONFIG_NAMES = [
+  'vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs',
+  'vite.config.cts', 'vite.config.cjs'
+];
+
+const FRAMEWORK_DEFAULT_PORTS = { vite: 5173, cra: 3000, next: 3000, generic: 3000 };
+
+function readPackage(directory) {
+  const filename = path.join(directory, 'package.json');
+  if (!fs.existsSync(filename)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filename, 'utf8'));
+  } catch (error) {
+    throw new Error(`invalid package.json at ${filename}: ${error.message}`);
+  }
+}
+
+function validProject(directory) {
+  return fs.existsSync(directory) && fs.statSync(directory).isDirectory() && Boolean(readPackage(directory));
+}
+
+function detectFolders(cwd, overrides = {}) {
+  const pairs = overrides.pairs || [['frontend', 'backend'], ['client', 'server']];
+  const found = pairs.filter(([front, back]) =>
+    validProject(path.join(cwd, front)) && validProject(path.join(cwd, back)));
+
+  let frontend = overrides.frontend && path.resolve(cwd, overrides.frontend);
+  let backend = overrides.backend && path.resolve(cwd, overrides.backend);
+
+  if (!frontend && !backend) {
+    if (found.length > 1) {
+      throw new Error('ambiguous project layout: multiple configured folder pairs exist; use --frontend-dir and --backend-dir');
+    }
+    if (found.length === 1) {
+      frontend = path.join(cwd, found[0][0]);
+      backend = path.join(cwd, found[0][1]);
+    } else {
+      const basename = path.basename(cwd).toLowerCase();
+      for (const [front, back] of pairs) {
+        if (basename === front || basename === back) {
+          const parent = path.dirname(cwd);
+          if (validProject(path.join(parent, front)) && validProject(path.join(parent, back))) {
+            throw new Error(`run ports-manager from the parent directory: ${parent}`);
+          }
+        }
+      }
+      throw new Error('no paired frontend/backend or client/server package.json projects found');
+    }
+  } else if (!frontend || !backend) {
+    const wanted = frontend ? 'backend' : 'frontend';
+    const candidates = pairs.map((pair) => pair[wanted === 'frontend' ? 0 : 1])
+      .map((name) => path.join(cwd, name)).filter(validProject);
+    if (candidates.length !== 1) throw new Error(`cannot infer ${wanted}; specify --${wanted}-dir`);
+    if (wanted === 'frontend') frontend = candidates[0];
+    else backend = candidates[0];
+  }
+
+  if (!validProject(frontend)) throw new Error(`frontend must be a directory containing package.json: ${frontend}`);
+  if (!validProject(backend)) throw new Error(`backend must be a directory containing package.json: ${backend}`);
+  if (path.resolve(frontend) === path.resolve(backend)) throw new Error('frontend and backend must be distinct directories');
+  return { frontend, backend };
+}
+
+function hasDependency(pkg, name) {
+  return Boolean((pkg.dependencies && pkg.dependencies[name]) ||
+    (pkg.devDependencies && pkg.devDependencies[name]));
+}
+
+function classifyProject(directory, role) {
+  const pkg = readPackage(directory);
+  const scripts = pkg.scripts || {};
+  const script = scripts.dev ? 'dev' : scripts.start ? 'start' : null;
+  if (!script) throw new Error(`${directory} has neither a dev nor start script`);
+
+  let framework = 'generic';
+  if (role === 'frontend') {
+    if (hasDependency(pkg, 'react-scripts')) framework = 'cra';
+    else if (hasDependency(pkg, 'vite')) framework = 'vite';
+    else if (hasDependency(pkg, 'next')) framework = 'next';
+  } else {
+    for (const [dependency, name] of [
+      ['@nestjs/core', 'nest'], ['express', 'express'], ['koa', 'koa'], ['fastify', 'fastify']
+    ]) {
+      if (hasDependency(pkg, dependency)) {
+        framework = name;
+        break;
+      }
+    }
+  }
+  return { directory, pkg, role, framework, script, scriptText: scripts[script] || '' };
+}
+
+/**
+ * Reads a bounded sample of a project's own source. Replaces the old three-filename
+ * guess, which reported "no process.env.PORT" for any backend that reads its port
+ * through a config module.
+ */
+function collectSources(directory, limit = MAX_SOURCE_FILES) {
+  const files = [];
+  const queue = [directory];
+  while (queue.length && files.length < limit) {
+    const current = queue.shift();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (files.length >= limit) break;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRECTORIES.has(entry.name) && !entry.name.startsWith('.')) queue.push(full);
+      } else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+        try {
+          if (fs.statSync(full).size > MAX_SOURCE_BYTES) continue;
+          files.push({ file: full, source: fs.readFileSync(full, 'utf8') });
+        } catch {
+          /* unreadable file; skip */
+        }
+      }
+    }
+  }
+  return files;
+}
+
+function readDotEnv(directory) {
+  const values = {};
+  for (const name of ['.env.local', '.env.development', '.env']) {
+    const filename = path.join(directory, name);
+    let raw;
+    try {
+      raw = fs.readFileSync(filename, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of raw.split(/\r?\n/)) {
+      const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+      if (!match) continue;
+      const key = match[1];
+      if (values[key] !== undefined) continue;
+      values[key] = match[2].trim().replace(/^["']|["']$/g, '').replace(/\s+#.*$/, '');
+    }
+  }
+  return values;
+}
+
+function firstPort(patterns, source) {
+  for (const pattern of patterns) {
+    const match = source.match(pattern);
+    if (match) {
+      const port = Number(match[1]);
+      if (Number.isInteger(port) && port >= 1 && port <= 65535) return port;
+    }
+  }
+  return null;
+}
+
+function findViteConfig(directory) {
+  for (const name of VITE_CONFIG_NAMES) {
+    const filename = path.join(directory, name);
+    if (fs.existsSync(filename)) return filename;
+  }
+  return null;
+}
+
+/**
+ * The port this project would use on its own. Preferring it keeps a solo project's URLs
+ * (and OAuth redirect URIs) stable, while a second project falls back to a free port.
+ */
+function naturalPort(project) {
+  const env = readDotEnv(project.directory);
+  if (env.PORT && /^\d+$/.test(env.PORT)) return Number(env.PORT);
+
+  if (project.role === 'frontend') {
+    const fromScript = firstPort([/--port[ =]+(\d{2,5})/, /\s-p[ =]+(\d{2,5})/], project.scriptText || '');
+    if (fromScript) return fromScript;
+    const viteConfig = findViteConfig(project.directory);
+    if (viteConfig) {
+      try {
+        const fromConfig = firstPort([/\bport\s*:\s*(\d{2,5})/], fs.readFileSync(viteConfig, 'utf8'));
+        if (fromConfig) return fromConfig;
+      } catch {
+        /* unreadable config; fall through to the framework default */
+      }
+    }
+    return FRAMEWORK_DEFAULT_PORTS[project.framework] || 3000;
+  }
+
+  const source = collectSources(project.directory).map((entry) => entry.source).join('\n');
+  const fromSource = firstPort([
+    // `process.env.PORT || 5001`, and the wrapped forms: `Number(process.env.PORT) || 5001`,
+    // `parseInt(process.env.PORT ?? '5001')`.
+    /process\.env\.PORT\s*\)?\s*(?:\|\||\?\?)\s*["']?(\d{2,5})/,
+    /\bPORT\s*:\s*[^,\n]*?\.default\(\s*(\d{2,5})\s*\)/,
+    /\bPORT\s*[:=]\s*(\d{2,5})\b/,
+    /\.listen\s*\(\s*(\d{2,5})\b/
+  ], source);
+  return fromSource || 5000;
+}
+
+/**
+ * Origin env names the backend actually references. Only these get injected, so we never
+ * invent a variable the app ignores.
+ */
+function scanCorsEnvNames(project) {
+  const source = collectSources(project.directory).map((entry) => entry.source).join('\n');
+  return CORS_ENV_NAMES.filter((name) => {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`process\\.env\\.${escaped}\\b|process\\.env\\[['"\`]${escaped}['"\`]\\]|\\b${escaped}\\s*:`)
+      .test(source);
+  });
+}
+
+/** Frontend env names that carry a backend URL, e.g. VITE_API_BASE or REACT_APP_API_URL. */
+function scanFrontendApiEnvNames(project) {
+  const source = collectSources(project.directory).map((entry) => entry.source).join('\n');
+  const names = new Set();
+  const patterns = [
+    /import\.meta\.env\.(VITE_[A-Z0-9_]+)/g,
+    /import\.meta\.env\[['"`](VITE_[A-Z0-9_]+)['"`]\]/g,
+    /process\.env\.(REACT_APP_[A-Z0-9_]+|NEXT_PUBLIC_[A-Z0-9_]+)/g
+  ];
+  for (const pattern of patterns) {
+    for (const match of source.matchAll(pattern)) {
+      if (/API|BACKEND|SERVER|BASE_URL/.test(match[1])) names.add(match[1]);
+    }
+  }
+  return [...names];
+}
+
+/** Whether the frontend already proxies API calls itself (Vite server.proxy, CRA `proxy`). */
+function hasDevProxy(project) {
+  if (project.framework === 'cra' || project.framework === 'generic') {
+    return typeof project.pkg.proxy === 'string' && project.pkg.proxy.length > 0;
+  }
+  const viteConfig = findViteConfig(project.directory);
+  if (viteConfig) {
+    try {
+      return /\bproxy\s*:/.test(fs.readFileSync(viteConfig, 'utf8'));
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+module.exports = {
+  CORS_ENV_NAMES,
+  FRAMEWORK_DEFAULT_PORTS,
+  classifyProject,
+  collectSources,
+  detectFolders,
+  findViteConfig,
+  hasDependency,
+  hasDevProxy,
+  naturalPort,
+  readDotEnv,
+  readPackage,
+  scanCorsEnvNames,
+  scanFrontendApiEnvNames,
+  validProject
+};

package/src/index.js

@@ -1,9 +1,10 @@
-'use strict';
-
-module.exports = {
-  ...require('./config'),
-  ...require('./detect'),
-  ...require('./runtime'),
-  ...require('./ide'),
-  ...require('./bridge-client')
-};
+'use strict';
+
+module.exports = {
+  ...require('./config'),
+  ...require('./detect'),
+  ...require('./preflight'),
+  ...require('./runtime'),
+  ...require('./wiring'),
+  ...require('./leases')
+};