ports-manager 1.0.0

package/src/ide.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parse } = require('jsonc-parser');
+const { SHIM_SOURCE } = require('./cors');
+
+const OWNED_PREFIX = 'Ports Manager:';
+
+function isIdeTerminal(env = process.env) {
+  return env.TERM_PROGRAM === 'vscode';
+}
+
+function readJsonc(filename, fallback) {
+  if (!fs.existsSync(filename)) return fallback;
+  const errors = [];
+  const value = parse(fs.readFileSync(filename, 'utf8'), errors, { allowTrailingComma: true });
+  if (errors.length || value === undefined) throw new Error(`cannot parse ${filename} as JSON with comments`);
+  return value;
+}
+
+function taskFromSpec(label, spec) {
+  return {
+    label: `${OWNED_PREFIX} ${label}`,
+    type: 'process',
+    command: spec.command,
+    args: spec.args,
+    options: { cwd: spec.cwd, env: spec.env },
+    presentation: {
+      reveal: 'always',
+      panel: 'dedicated',
+      group: 'ports-manager',
+      clear: true
+    },
+    isBackground: true,
+    problemMatcher: []
+  };
+}
+
+function mergeTasks(existing, specs, proxySpec) {
+  const document = existing && typeof existing === 'object' ? existing : {};
+  const unrelated = Array.isArray(document.tasks)
+    ? document.tasks.filter((task) => !task || typeof task.label !== 'string' || !task.label.startsWith(OWNED_PREFIX))
+    : [];
+  const owned = [
+    taskFromSpec('Backend', specs.backend),
+    taskFromSpec('Frontend', specs.frontend)
+  ];
+  if (proxySpec) owned.push(taskFromSpec('Proxy', proxySpec));
+  owned.push({
+    label: `${OWNED_PREFIX} Run All`,
+    dependsOn: owned.map((task) => task.label),
+    dependsOrder: 'parallel',
+    problemMatcher: [],
+    runOptions: { reevaluateOnRerun: true }
+  });
+  return { ...document, version: document.version || '2.0.0', tasks: [...unrelated, ...owned] };
+}
+
+function mergeKeybindings(existing, key = 'ctrl+alt+p') {
+  const entries = Array.isArray(existing) ? existing : [];
+  const unrelated = entries.filter((entry) => entry && entry.portsManagerOwned !== true);
+  return [...unrelated, {
+    key,
+    command: 'workbench.action.tasks.runTask',
+    args: `${OWNED_PREFIX} Run All`,
+    portsManagerOwned: true
+  }];
+}
+
+function generateIdeFiles(root, specs, proxySpec, options = {}) {
+  const { keybinding = 'ctrl+alt+p', needsShim = false, withKeybinding = false } = options;
+  const vscode = path.join(root, '.vscode');
+  fs.mkdirSync(vscode, { recursive: true });
+  const tasksFile = path.join(vscode, 'tasks.json');
+  const keybindingsFile = path.join(vscode, 'ports-manager-keybindings.json');
+  if (needsShim) {
+    const shimFile = path.join(vscode, 'ports-manager-cors-preload.cjs');
+    fs.writeFileSync(shimFile, SHIM_SOURCE, 'utf8');
+  }
+  const tasks = mergeTasks(readJsonc(tasksFile, { version: '2.0.0', tasks: [] }), specs, proxySpec);
+  fs.writeFileSync(tasksFile, `${JSON.stringify(tasks, null, 2)}\n`, 'utf8');
+  if (withKeybinding) {
+    const keybindings = mergeKeybindings(readJsonc(keybindingsFile, []), keybinding);
+    fs.writeFileSync(keybindingsFile, `${JSON.stringify(keybindings, null, 2)}\n`, 'utf8');
+  }
+  return { tasksFile, keybindingsFile: withKeybinding ? keybindingsFile : null };
+}
+
+function shellQuote(value, platform = process.platform) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./\\:@%+=,-]+$/.test(text)) return text;
+  if (platform === 'win32') {
+    if (text.includes('"')) throw new Error('cannot safely quote a double quote for an unknown Windows terminal shell');
+    return `"${text}"`;
+  }
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+function terminalCommand(spec, platform = process.platform) {
+  return [spec.command, ...spec.args].map((part) => shellQuote(part, platform)).join(' ');
+}
+
+module.exports = {
+  OWNED_PREFIX, generateIdeFiles, isIdeTerminal, mergeKeybindings, mergeTasks,
+  readJsonc, shellQuote, taskFromSpec, terminalCommand
+};

package/src/index.js

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

package/src/process-manager.js

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

package/src/proxy.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const http = require('node:http');
+
+function loadProxyFactory() {
+  try {
+    return require('http-proxy-middleware').createProxyMiddleware;
+  } catch {
+    throw new Error('proxy mode requires http-proxy-middleware; reinstall optional dependencies with npm install');
+  }
+}
+
+function startProxy({ port, frontendPort, backendPort, apiPrefix }, logger = console) {
+  const createProxyMiddleware = loadProxyFactory();
+  const onError = (error, req, res) => {
+    logger.error(`[Proxy] ${error.message}`);
+    if (res && !res.headersSent) {
+      res.writeHead(502, { 'Content-Type': 'text/plain' });
+      res.end('Ports Manager proxy target unavailable');
+    }
+  };
+  const backend = createProxyMiddleware({
+    target: `http://127.0.0.1:${backendPort}`,
+    changeOrigin: true,
+    ws: true,
+    on: { error: onError }
+  });
+  const frontend = createProxyMiddleware({
+    target: `http://127.0.0.1:${frontendPort}`,
+    changeOrigin: true,
+    ws: true,
+    on: { error: onError }
+  });
+  const server = http.createServer((req, res) => {
+    const selected = req.url === apiPrefix || req.url.startsWith(`${apiPrefix}/`) ? backend : frontend;
+    selected(req, res, (error) => onError(error || new Error('proxy request was not handled'), req, res));
+  });
+  server.on('upgrade', (req, socket, head) => {
+    const selected = req.url === apiPrefix || req.url.startsWith(`${apiPrefix}/`) ? backend : frontend;
+    selected.upgrade(req, socket, head);
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      logger.log(`[Proxy] http://127.0.0.1:${port} (${apiPrefix} -> backend)`);
+      resolve({
+        close: () => new Promise((done) => server.close(done)),
+        server
+      });
+    });
+  });
+}
+
+module.exports = { startProxy };

package/src/runtime.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const net = require('node:net');
+
+function isPortFree(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once('error', () => resolve(false));
+    server.listen({ port, host, exclusive: true }, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+async function allocatePorts(config, count) {
+  const [minimum, maximum] = config.portRange;
+  const banned = new Set([3000, 5000, ...config.bannedPorts]);
+  const requested = [config.backendPort, config.frontendPort, config.proxyPort].slice(0, count);
+  const result = [];
+  for (const requestedPort of requested) {
+    if (requestedPort === undefined) {
+      let selected;
+      for (let port = minimum; port <= maximum; port += 1) {
+        if (!banned.has(port) && !result.includes(port) && await isPortFree(port)) {
+          selected = port;
+          break;
+        }
+      }
+      if (!selected) throw new Error(`no free ports in range ${minimum}-${maximum}`);
+      result.push(selected);
+    } else {
+      if (banned.has(requestedPort)) throw new Error(`port ${requestedPort} is banned`);
+      if (result.includes(requestedPort)) throw new Error(`port ${requestedPort} was requested more than once`);
+      if (!await isPortFree(requestedPort)) throw new Error(`requested port ${requestedPort} is unavailable`);
+      result.push(requestedPort);
+    }
+  }
+  return result;
+}
+
+function renderEnv(env, values) {
+  return Object.fromEntries(Object.entries(env || {}).map(([key, value]) => {
+    if (typeof value !== 'string') return [key, String(value)];
+    return [key, value.replace(/\{(frontendPort|backendPort|proxyPort|apiPrefix)\}/g,
+      (_, name) => String(values[name] ?? ''))];
+  }));
+}
+
+function buildSpecs(frontend, backend, ports, config, corsShim) {
+  const values = {
+    backendPort: ports.backend,
+    frontendPort: ports.frontend,
+    proxyPort: ports.proxy,
+    apiPrefix: config.apiPrefix
+  };
+  const backendUrl = config.proxy
+    ? `http://127.0.0.1:${ports.proxy}${config.apiPrefix}`
+    : `http://127.0.0.1:${ports.backend}`;
+  const configuredEnv = config.env || {};
+  const commonEnv = renderEnv(Object.fromEntries(Object.entries(configuredEnv)
+    .filter(([key]) => key !== 'frontend' && key !== 'backend')), values);
+  const backendEnv = {
+    ...commonEnv,
+    ...renderEnv(configuredEnv.backend, values),
+    PORT: String(ports.backend)
+  };
+  if (corsShim) {
+    backendEnv.PORTS_MANAGER_CORS_ORIGIN = `http://127.0.0.1:${config.proxy ? ports.proxy : ports.frontend}`;
+    backendEnv.PORTS_MANAGER_CORS_CREDENTIALS = String(config.corsCredentials);
+    backendEnv.NODE_OPTIONS = appendNodeRequire(process.env.NODE_OPTIONS || '', corsShim);
+  }
+
+  const frontendEnv = {
+    ...commonEnv,
+    ...renderEnv(configuredEnv.frontend, values)
+  };
+  const npm = npmInvocation();
+  const frontendArgs = [...npm.argsPrefix, 'run', frontend.script];
+  if (frontend.framework === 'cra') {
+    frontendEnv.PORT = String(ports.frontend);
+    frontendEnv.REACT_APP_API_URL = backendUrl;
+  } else if (frontend.framework === 'vite') {
+    frontendArgs.push('--', '--port', String(ports.frontend), '--strictPort');
+    frontendEnv.VITE_API_URL = backendUrl;
+  } else if (frontend.framework === 'next') {
+    frontendArgs.push('--', '-p', String(ports.frontend));
+    frontendEnv.NEXT_PUBLIC_API_URL = backendUrl;
+  } else {
+    frontendEnv.PORT = String(ports.frontend);
+  }
+
+  return {
+    backend: {
+      name: 'Backend', cwd: backend.directory, command: npm.command,
+      args: [...npm.argsPrefix, 'run', backend.script],
+      env: backendEnv, color: 'cyan'
+    },
+    frontend: {
+      name: 'Frontend', cwd: frontend.directory, command: npm.command, args: frontendArgs,
+      env: frontendEnv, color: 'magenta'
+    }
+  };
+}
+
+function npmInvocation() {
+  if (process.platform === 'win32') {
+    return {
+      command: process.env.ComSpec || 'cmd.exe',
+      argsPrefix: ['/d', '/s', '/c', 'npm.cmd']
+    };
+  }
+  return { command: 'npm', argsPrefix: [] };
+}
+
+function appendNodeRequire(existing, shimPath) {
+  const escaped = shimPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return `${existing ? `${existing} ` : ''}--require "${escaped}"`;
+}
+
+module.exports = { allocatePorts, appendNodeRequire, buildSpecs, isPortFree, npmInvocation, renderEnv };

package/tsconfig.bridge.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "node16",
+    "moduleResolution": "node16",
+    "outDir": "dist/bridge",
+    "rootDir": "bridge",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "sourceMap": true
+  },
+  "include": [
+    "bridge/src/**/*.ts",
+    "bridge/test/**/*.ts"
+  ]
+}