ports-manager 1.0.0

package/src/cli.js

@@ -0,0 +1,278 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadConfig, mergeConfig } = require('./config');
+const { detectFolders, classifyProject, scanBackend } = require('./detect');
+const { allocatePorts, buildSpecs } = require('./runtime');
+const { createCorsShim } = require('./cors');
+const { runProcesses } = require('./process-manager');
+const { startProxy } = require('./proxy');
+const { generateIdeFiles, isIdeTerminal } = require('./ide');
+const { launchInBridge, stopBridge } = require('./bridge-client');
+const pkg = require('../package.json');
+
+const HELP = `ports-manager [options]
+
+Detect and run a paired frontend/backend JavaScript project.
+
+  --frontend-dir PATH      Override frontend/client directory
+  --backend-dir PATH       Override backend/server directory
+  --frontend-port PORT     Request frontend port
+  --backend-port PORT      Request backend port
+  --proxy-port PORT        Request same-origin proxy port
+  --range MIN-MAX          Port search range (default 4000-4999)
+  --ban PORTS              Ban comma-separated ports
+  --cors / --no-cors-shim  Enable/disable the CORS preload shim
+  --force-cors             Inject shim even when CORS is heuristically detected
+  --cors-credentials BOOL  Whether shim emits credential support
+  --proxy                  Enable same-origin proxy mode
+  --api-prefix PATH        Backend proxy prefix (default /api)
+  --wait-for-backend[=MS]  Wait before frontend (bare form: 10000ms)
+  --ide-terminals[=MODE]   auto, off, tasks, extension (bare form: auto)
+  --with-keybinding        Generate a user-keybindings reference file
+  --keybinding KEY         Reference shortcut (default ctrl+alt+p)
+  --config PATH            Explicit JSON config
+  --dry-run                Inspect and allocate without writes/processes
+  --stop                   Ask the bridge to stop this workspace's terminals
+  --help                    Show help
+  --version, -v             Show version and author
+`;
+
+function valueFor(argv, index, name) {
+  const argument = argv[index];
+  const equals = argument.indexOf('=');
+  if (equals !== -1) return { value: argument.slice(equals + 1), consumed: 0 };
+  if (index + 1 >= argv.length || argv[index + 1].startsWith('--')) {
+    throw new Error(`${name} requires a value`);
+  }
+  return { value: argv[index + 1], consumed: 1 };
+}
+
+function integer(value, name) {
+  if (!/^\d+$/.test(value)) throw new Error(`${name} must be an integer`);
+  return Number(value);
+}
+
+function boolean(value, name) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  throw new Error(`${name} must be true or false`);
+}
+
+function parseArgs(argv) {
+  const options = { bannedPorts: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    const name = argument.split('=')[0];
+    if (name === '--help' || name === '-h') options.help = true;
+    else if (name === '--version' || name === '-v') options.version = true;
+    else if (name === '--dry-run') options.dryRun = true;
+    else if (name === '--stop') options.stop = true;
+    else if (name === '--proxy') options.proxy = true;
+    else if (name === '--no-proxy') options.proxy = false;
+    else if (name === '--cors') options.cors = true;
+    else if (name === '--no-cors') options.cors = false;
+    else if (name === '--no-cors-shim') options.cors = false;
+    else if (name === '--force-cors') options.forceCors = true;
+    else if (name === '--with-keybinding') options.withKeybinding = true;
+    else if (name === '--no-cors-credentials') options.corsCredentials = false;
+    else if (name === '--internal-proxy') {
+      options.internalProxy = true;
+    } else if (name === '--ide-terminals') {
+      if (argument.includes('=')) options.ideTerminals = argument.slice(argument.indexOf('=') + 1) || 'auto';
+      else if (argv[index + 1] && !argv[index + 1].startsWith('--') &&
+          ['off', 'auto', 'tasks', 'extension'].includes(argv[index + 1])) {
+        options.ideTerminals = argv[++index];
+      } else options.ideTerminals = 'auto';
+    } else if (name === '--wait-for-backend') {
+      if (argument.includes('=')) options.waitForBackend = integer(argument.split('=').slice(1).join('='), name);
+      else if (argv[index + 1] && /^\d+$/.test(argv[index + 1])) options.waitForBackend = integer(argv[++index], name);
+      else options.waitForBackend = 10000;
+    } else {
+      const mapping = {
+        '--frontend': 'frontend', '--backend': 'backend',
+        '--frontend-dir': 'frontend', '--backend-dir': 'backend', '--config': 'configPath',
+        '--api-prefix': 'apiPrefix', '--keybinding': 'keybinding',
+        '--frontend-port': 'frontendPort', '--backend-port': 'backendPort',
+        '--proxy-port': 'proxyPort', '--cors-credentials': 'corsCredentials',
+        '--port-range': 'portRange', '--range': 'portRange',
+        '--ban-port': 'banPort', '--ban': 'ban',
+        '--proxy-frontend-port': 'proxyFrontendPort', '--proxy-backend-port': 'proxyBackendPort'
+      };
+      const key = mapping[name];
+      if (!key) throw new Error(`unknown option: ${argument}`);
+      const found = valueFor(argv, index, name);
+      index += found.consumed;
+      if (['frontendPort', 'backendPort', 'proxyPort', 'proxyFrontendPort', 'proxyBackendPort'].includes(key)) {
+        options[key] = integer(found.value, name);
+      } else if (key === 'corsCredentials') {
+        options[key] = boolean(found.value, name);
+      } else if (key === 'banPort') {
+        options.bannedPorts.push(integer(found.value, name));
+      } else if (key === 'ban') {
+        const ports = found.value.split(',').map((value) => value.trim()).filter(Boolean);
+        if (!ports.length) throw new Error('--ban requires a comma-separated port list');
+        options.bannedPorts.push(...ports.map((value) => integer(value, name)));
+      } else if (key === 'portRange') {
+        const match = found.value.match(/^(\d+)-(\d+)$/);
+        if (!match) throw new Error('--port-range must be MIN-MAX');
+        options.portRange = [Number(match[1]), Number(match[2])];
+      } else options[key] = found.value;
+    }
+  }
+  if (!options.bannedPorts.length) delete options.bannedPorts;
+  return options;
+}
+
+function proxySpec(root, ports, apiPrefix) {
+  return {
+    name: 'Proxy',
+    cwd: root,
+    command: 'node',
+    args: [
+      path.resolve(__dirname, '../bin/ports-manager.js'), '--internal-proxy',
+      '--proxy-port', String(ports.proxy), '--proxy-frontend-port', String(ports.frontend),
+      '--proxy-backend-port', String(ports.backend), '--api-prefix', apiPrefix
+    ],
+    env: {},
+    color: 'yellow'
+  };
+}
+
+async function runProxyOnly(options) {
+  for (const key of ['proxyPort', 'proxyFrontendPort', 'proxyBackendPort']) {
+    if (!options[key]) throw new Error(`internal proxy missing ${key}`);
+  }
+  const proxy = await startProxy({
+    port: options.proxyPort,
+    frontendPort: options.proxyFrontendPort,
+    backendPort: options.proxyBackendPort,
+    apiPrefix: options.apiPrefix || '/api'
+  });
+  await new Promise((resolve) => {
+    const finish = async () => {
+      await proxy.close();
+      resolve();
+    };
+    process.once('SIGINT', finish);
+    process.once('SIGTERM', finish);
+  });
+}
+
+function printPlan(root, frontend, backend, ports, config, corsEnabled) {
+  console.log(`Root:     ${root}`);
+  console.log(`Backend:  ${backend.framework} / npm run ${backend.script} / ${ports.backend}`);
+  console.log(`Frontend: ${frontend.framework} / npm run ${frontend.script} / ${ports.frontend}`);
+  if (config.proxy) console.log(`Proxy:    http://127.0.0.1:${ports.proxy}${config.apiPrefix}`);
+  console.log(`CORS shim: ${corsEnabled ? 'enabled' : 'skipped'}`);
+}
+
+async function main(argv = process.argv.slice(2), cwd = process.cwd()) {
+  const options = parseArgs(argv);
+  if (options.help) return console.log(HELP);
+  if (options.version) {
+    return console.log(`ports-manager v${pkg.version}\nMuhammad Saad Amin (SENODROOM)`);
+  }
+  if (options.internalProxy) return runProxyOnly(options);
+
+  const root = path.resolve(cwd);
+  const tag = `ports-manager:${root}`;
+  if (options.stop) {
+    await stopBridge(tag);
+    console.log('Requested closure of Ports Manager terminals for this workspace.');
+    return;
+  }
+  const loaded = await loadConfig(root, options.configPath);
+  const config = mergeConfig(loaded.config, options);
+  const folders = detectFolders(root, config);
+  const frontend = classifyProject(folders.frontend, 'frontend');
+  const backend = classifyProject(folders.backend, 'backend');
+  const scan = scanBackend(backend);
+  const corsEnabled = config.cors && (config.forceCors || !scan.corsDetected);
+  if (scan.corsDetected && config.cors && !config.forceCors) {
+    console.log('Existing CORS support detected heuristically; skipping preload shim (use --force-cors to override).');
+  }
+  if (!scan.hasEnvPort) {
+    console.warn('Warning: static scan did not find process.env.PORT in likely backend entry files; runtime behavior may differ.');
+  }
+  if (scan.literals.length) {
+    console.warn(`Warning: possible literal listen port(s) ${scan.literals.join(', ')} found; this heuristic may include inactive code.`);
+  }
+  if (frontend.framework === 'generic') {
+    console.warn('Warning: generic frontend receives PORT and API URL cannot be inferred; configure env values if needed.');
+  }
+
+  const allocated = await allocatePorts(config, config.proxy ? 3 : 2);
+  const ports = { backend: allocated[0], frontend: allocated[1], proxy: allocated[2] };
+  const ideMode = config.ideTerminals;
+  const inIde = isIdeTerminal();
+  let effectiveIdeMode = ideMode;
+  if (ideMode !== 'off' && !inIde) {
+    console.log('IDE terminal mode requested outside a corroborated VS Code/Cursor terminal; using inline mode.');
+    effectiveIdeMode = 'off';
+  }
+  const durableShim = path.join(root, '.vscode', 'ports-manager-cors-preload.cjs');
+  const shimPath = corsEnabled
+    ? (effectiveIdeMode === 'off' ? (options.dryRun ? '<dry-run-cors-shim>' : null) : durableShim)
+    : null;
+  let temporaryShim;
+  if (corsEnabled && effectiveIdeMode === 'off' && !options.dryRun) {
+    temporaryShim = createCorsShim();
+  }
+  const specs = buildSpecs(frontend, backend, ports, config,
+    temporaryShim ? temporaryShim.filename : shimPath);
+  const pSpec = config.proxy ? proxySpec(root, ports, config.apiPrefix) : null;
+  printPlan(root, frontend, backend, ports, config, corsEnabled);
+  if (options.dryRun) {
+    console.log('Dry run: no files written and no processes started.');
+    return;
+  }
+
+  if (effectiveIdeMode === 'extension' || effectiveIdeMode === 'auto') {
+    if (corsEnabled) {
+      fs.mkdirSync(path.dirname(durableShim), { recursive: true });
+      fs.writeFileSync(durableShim, require('./cors').SHIM_SOURCE, 'utf8');
+    }
+    try {
+      await launchInBridge(specs, pSpec, tag);
+      console.log('Started tagged terminals through the Ports Manager bridge.');
+      return;
+    } catch (error) {
+      if (effectiveIdeMode === 'extension') throw error;
+      console.log(`Bridge unavailable (${error.message}); generating VS Code tasks instead.`);
+      effectiveIdeMode = 'tasks';
+    }
+  }
+  if (effectiveIdeMode === 'tasks') {
+    const generated = generateIdeFiles(root, specs, pSpec, {
+      keybinding: config.keybinding,
+      needsShim: corsEnabled,
+      withKeybinding: config.withKeybinding
+    });
+    console.log(`Generated ${generated.tasksFile}. Run “Ports Manager: Run All” from Tasks: Run Task.`);
+    if (generated.keybindingsFile) {
+      console.log(`Suggested shortcut ${config.keybinding} is in ${generated.keybindingsFile}; copy it into Preferences: Open Keyboard Shortcuts (JSON).`);
+      console.log('VS Code/Cursor does not apply workspace keybindings files automatically.');
+    }
+    return;
+  }
+
+  let proxy;
+  try {
+    if (config.proxy) proxy = await startProxy({
+      port: ports.proxy, frontendPort: ports.frontend, backendPort: ports.backend,
+      apiPrefix: config.apiPrefix
+    });
+    const code = await runProcesses(specs, {
+      waitForBackend: config.waitForBackend,
+      backendPort: ports.backend
+    });
+    process.exitCode = code;
+  } finally {
+    if (proxy) await proxy.close();
+    if (temporaryShim) temporaryShim.cleanup();
+  }
+}
+
+module.exports = { HELP, main, parseArgs, proxySpec, runProxyOnly };

package/src/config.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { cosmiconfig } = require('cosmiconfig');
+
+const DEFAULTS = Object.freeze({
+  pairs: [['frontend', 'backend'], ['client', 'server']],
+  portRange: [4000, 4999],
+  bannedPorts: [3000, 5000],
+  cors: true,
+  forceCors: false,
+  corsCredentials: true,
+  proxy: false,
+  apiPrefix: '/api',
+  ideTerminals: 'off',
+  waitForBackend: 0,
+  withKeybinding: false,
+  keybinding: 'ctrl+alt+p',
+  env: {}
+});
+
+const allowedKeys = new Set([
+  'pairs', 'frontend', 'backend', 'frontendPort', 'backendPort', 'proxyPort', 'portRange',
+  'bannedPorts', 'cors', 'forceCors', 'corsCredentials', 'proxy', 'apiPrefix',
+  'ideTerminals', 'waitForBackend', 'withKeybinding', 'keybinding', 'env'
+]);
+
+function normalizeConfig(input) {
+  const config = { ...input };
+  if (config.cors && typeof config.cors === 'object' && !Array.isArray(config.cors)) {
+    const cors = config.cors;
+    config.cors = cors.mode !== 'off' && cors.enabled !== false;
+    if (cors.credentials !== undefined) config.corsCredentials = cors.credentials;
+  }
+  if (config.proxy && typeof config.proxy === 'object' && !Array.isArray(config.proxy)) {
+    config.proxy = config.proxy.enabled === true;
+  }
+  if (config.ideTerminals && typeof config.ideTerminals === 'object' &&
+      !Array.isArray(config.ideTerminals)) {
+    const ide = config.ideTerminals;
+    config.ideTerminals = ide.mode || 'off';
+    if (ide.withKeybinding !== undefined) config.withKeybinding = ide.withKeybinding;
+    if (ide.keybinding !== undefined) config.keybinding = ide.keybinding;
+  }
+  return config;
+}
+
+function assertPort(value, name) {
+  if (!Number.isInteger(value) || value < 1 || value > 65535) {
+    throw new Error(`${name} must be an integer from 1 to 65535`);
+  }
+}
+
+function validateConfig(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('configuration must be a JSON object');
+  }
+  for (const key of Object.keys(config)) {
+    if (!allowedKeys.has(key)) throw new Error(`unknown configuration key: ${key}`);
+  }
+  if (config.pairs !== undefined) {
+    if (!Array.isArray(config.pairs) || config.pairs.length === 0 ||
+        config.pairs.some((pair) => !Array.isArray(pair) || pair.length !== 2 ||
+          pair.some((name) => typeof name !== 'string' || !name.trim()))) {
+      throw new Error('pairs must be a non-empty array of [frontend, backend] directory names');
+    }
+  }
+  for (const key of ['frontendPort', 'backendPort', 'proxyPort']) {
+    if (config[key] !== undefined) assertPort(config[key], key);
+  }
+  if (config.portRange !== undefined) {
+    if (!Array.isArray(config.portRange) || config.portRange.length !== 2) {
+      throw new Error('portRange must be [minimum, maximum]');
+    }
+    config.portRange.forEach((port, index) => assertPort(port, `portRange[${index}]`));
+    if (config.portRange[0] > config.portRange[1]) throw new Error('portRange minimum exceeds maximum');
+  }
+  if (config.bannedPorts !== undefined) {
+    if (!Array.isArray(config.bannedPorts)) throw new Error('bannedPorts must be an array');
+    config.bannedPorts.forEach((port, index) => assertPort(port, `bannedPorts[${index}]`));
+  }
+  for (const key of ['cors', 'forceCors', 'corsCredentials', 'proxy', 'withKeybinding']) {
+    if (config[key] !== undefined && typeof config[key] !== 'boolean') {
+      throw new Error(`${key} must be boolean`);
+    }
+  }
+  if (config.apiPrefix !== undefined &&
+      (typeof config.apiPrefix !== 'string' || !config.apiPrefix.startsWith('/'))) {
+    throw new Error('apiPrefix must be a string beginning with /');
+  }
+  if (config.ideTerminals !== undefined &&
+      !['off', 'auto', 'tasks', 'extension'].includes(config.ideTerminals)) {
+    throw new Error('ideTerminals must be off, auto, tasks, or extension');
+  }
+  if (config.waitForBackend !== undefined &&
+      (!Number.isInteger(config.waitForBackend) || config.waitForBackend < 0)) {
+    throw new Error('waitForBackend must be a non-negative integer (milliseconds)');
+  }
+  if (config.env !== undefined &&
+      (!config.env || typeof config.env !== 'object' || Array.isArray(config.env))) {
+    throw new Error('env must be an object');
+  }
+  return config;
+}
+
+async function loadConfig(cwd, explicitPath) {
+  let loaded = {};
+  let filepath;
+  if (explicitPath) {
+    filepath = path.resolve(cwd, explicitPath);
+    let raw;
+    try {
+      raw = fs.readFileSync(filepath, 'utf8');
+    } catch (error) {
+      throw new Error(`cannot read config ${filepath}: ${error.message}`);
+    }
+    try {
+      loaded = JSON.parse(raw);
+    } catch (error) {
+      throw new Error(`invalid JSON in ${filepath}: ${error.message}`);
+    }
+  } else {
+    const explorer = cosmiconfig('ports-manager', {
+      searchPlaces: ['ports-manager.config.json', '.ports-managerrc', '.ports-managerrc.json']
+    });
+    const result = await explorer.search(cwd);
+    if (result) {
+      loaded = result.config;
+      filepath = result.filepath;
+    }
+  }
+  loaded = normalizeConfig(loaded);
+  validateConfig(loaded);
+  return { config: loaded, filepath };
+}
+
+function mergeConfig(fileConfig, cliConfig) {
+  fileConfig = normalizeConfig(fileConfig);
+  const result = { ...DEFAULTS, ...fileConfig };
+  for (const [key, value] of Object.entries(cliConfig)) {
+    if (allowedKeys.has(key) && value !== undefined) result[key] = value;
+  }
+  result.bannedPorts = [...new Set([
+    3000, 5000, ...(fileConfig.bannedPorts || []), ...(cliConfig.bannedPorts || [])
+  ])];
+  validateConfig(result);
+  return result;
+}
+
+module.exports = { DEFAULTS, loadConfig, mergeConfig, normalizeConfig, validateConfig };

package/src/cors.js

@@ -0,0 +1,55 @@
+'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 };

package/src/detect.js

@@ -0,0 +1,114 @@
+'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
+};