ports-manager 1.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ports-manager",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "author": "Muhammad Saad Amin",
   "description": "Run paired frontend/backend projects on free ports, with the frontend automatically wired to wherever the backend landed and CORS handled for you.",
   "main": "./src/index.js",

package/src/detect.js

@@ -230,10 +230,15 @@ function scanCorsEnvNames(project) {
   });
 }
 
-/** Frontend env names that carry a backend URL, e.g. VITE_API_BASE or REACT_APP_API_URL. */
-function scanFrontendApiEnvNames(project) {
+/**
+ * Frontend env names carrying a backend URL, with the literal each usage falls back to.
+ * The fallback matters: `import.meta.env.VITE_API_URL || 'http://localhost:5000'` tells us
+ * which service that name refers to, so we can retarget the right one and leave a name
+ * pointing at some other service alone.
+ */
+function scanFrontendApiCandidates(project) {
   const source = collectSources(project.directory).map((entry) => entry.source).join('\n');
-  const names = new Set();
+  const found = new Map();
   const patterns = [
     /import\.meta\.env\.(VITE_[A-Z0-9_]+)/g,
     /import\.meta\.env\[['"`](VITE_[A-Z0-9_]+)['"`]\]/g,
@@ -241,10 +246,24 @@ function scanFrontendApiEnvNames(project) {
   ];
   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]);
+      const name = match[1];
+      if (!/API|BACKEND|SERVER|BASE_URL/.test(name)) continue;
+      if (!found.has(name)) found.set(name, null);
     }
   }
-  return [...names];
+  for (const name of found.keys()) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const fallback = source.match(
+      new RegExp(`env(?:\\.${escaped}|\\[['"\`]${escaped}['"\`]\\])\\s*(?:\\|\\||\\?\\?)\\s*['"\`]([^'"\`]+)['"\`]`)
+    );
+    if (fallback) found.set(name, fallback[1]);
+  }
+  return [...found].map(([name, fallback]) => ({ name, fallback }));
+}
+
+/** Frontend env names that carry a backend URL, e.g. VITE_API_BASE or REACT_APP_API_URL. */
+function scanFrontendApiEnvNames(project) {
+  return scanFrontendApiCandidates(project).map((entry) => entry.name);
 }
 
 /** Whether the frontend already proxies API calls itself (Vite server.proxy, CRA `proxy`). */
@@ -276,6 +295,7 @@ module.exports = {
   readDotEnv,
   readPackage,
   scanCorsEnvNames,
+  scanFrontendApiCandidates,
   scanFrontendApiEnvNames,
   validProject
 };

package/src/wiring.js

@@ -3,7 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const {
-  findViteConfig, hasDevProxy, readDotEnv, scanCorsEnvNames, scanFrontendApiEnvNames
+  findViteConfig, hasDevProxy, readDotEnv, scanCorsEnvNames, scanFrontendApiCandidates
 } = require('./detect');
 const { alive } = require('./leases');
 
@@ -69,19 +69,73 @@ function retargetProxy(proxy, options) {
   return { proxy: next, changed, kept };
 }
 
+/**
+ * Adds origins to a CSP's connect-src.
+ *
+ * A frontend that pins the backend origin in a `<meta http-equiv="Content-Security-Policy">`
+ * blocks the request in the browser before it is ever sent, so relocating the backend fails
+ * with no server-side symptom at all. Origins are only ever added, never removed.
+ *
+ * Self-contained: stringified into the generated Vite config.
+ */
+function extendCspConnectSrc(policy, origins) {
+  const directives = String(policy).split(';').map((part) => part.trim()).filter(Boolean);
+  const index = directives.findIndex((part) => /^connect-src\b/i.test(part));
+  if (index === -1) {
+    if (!directives.some((part) => /^default-src\b/i.test(part))) return policy;
+    directives.push(`connect-src 'self' ${origins.join(' ')}`);
+    return directives.join('; ');
+  }
+  const existing = directives[index].split(/\s+/);
+  const missing = origins.filter((origin) => !existing.includes(origin));
+  if (!missing.length) return policy;
+  directives[index] = `${directives[index]} ${missing.join(' ')}`;
+  return directives.join('; ');
+}
+
+/** Loopback origins a browser may need to reach a backend on `port`. */
+function devOriginsFor(port) {
+  return [
+    `http://localhost:${port}`, `http://127.0.0.1:${port}`,
+    `ws://localhost:${port}`, `ws://127.0.0.1:${port}`
+  ];
+}
+
 /**
  * A Vite config that extends the project's own and repoints its API proxy at the allocated
  * backend port. Without this, relocating the backend leaves the frontend calling a dead port.
  */
-function viteOverrideSource({ userConfig, frontendPort, backendPort, naturalBackendPort, apiPrefix }) {
+function viteOverrideSource({
+  userConfig, frontendPort, backendPort, naturalBackendPort, apiPrefix, cspOrigins = []
+}) {
   return `// Generated by ports-manager. Recreated on every run; safe to delete.
 import { defineConfig, mergeConfig } from 'vite';
 import base from './${userConfig}';
 
 const OPTIONS = ${JSON.stringify({ backendPort, naturalBackendPort, apiPrefix })};
+const CSP_ORIGINS = ${JSON.stringify(cspOrigins)};
 
 ${retargetProxy.toString()}
 
+${extendCspConnectSrc.toString()}
+
+// Dev-only: the served HTML is rewritten in memory, index.html is never touched.
+const cspPlugin = {
+  name: 'ports-manager-csp',
+  transformIndexHtml(html) {
+    if (!CSP_ORIGINS.length) return html;
+    return html.replace(
+      /(<meta\b[^>]*http-equiv=["']Content-Security-Policy["'][^>]*content=["'])([^"']*)(["'])/i,
+      (match, before, policy, after) => {
+        const updated = extendCspConnectSrc(policy, CSP_ORIGINS);
+        if (updated === policy) return match;
+        console.log('[ports-manager] CSP connect-src extended with ' + CSP_ORIGINS.join(' '));
+        return before + updated + after;
+      }
+    );
+  }
+};
+
 export default defineConfig(async (env) => {
   const resolved = typeof base === 'function' ? await base(env) : await base;
   const server = (resolved && resolved.server) || {};
@@ -95,6 +149,7 @@ export default defineConfig(async (env) => {
   }
   const proxy = Object.keys(result.proxy).length ? result.proxy : undefined;
   return mergeConfig(resolved, {
+    plugins: [cspPlugin],
     server: { port: ${frontendPort}, strictPort: true, ...(proxy ? { proxy } : {}) }
   });
 });
@@ -124,6 +179,42 @@ function corsEnvFor(backend, origin) {
   return { env, names, notes };
 }
 
+function pointsAtPort(value, port) {
+  if (typeof value !== 'string' || !Number.isInteger(port)) return false;
+  try {
+    const url = new URL(value);
+    return ['localhost', '127.0.0.1', '0.0.0.0', '::1', '[::1]'].includes(url.hostname) &&
+      Number(url.port) === port;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Picks which frontend API variables to retarget, using the same rule as the proxy rewrite:
+ * only ones currently aimed at the backend's natural port. A project with both
+ * VITE_API_URL (this backend) and VITE_AI_API_URL (a different service) must not have the
+ * second one repointed at the first.
+ */
+function resolveFrontendApiEnv(frontend, naturalBackendPort, backendUrl) {
+  const candidates = scanFrontendApiCandidates(frontend);
+  const configured = readDotEnv(frontend.directory);
+  const env = {};
+  const skipped = [];
+  for (const { name, fallback } of candidates) {
+    // What this variable resolves to today: the .env value, else the in-code fallback.
+    const current = configured[name] !== undefined ? configured[name] : fallback;
+    if (pointsAtPort(current, naturalBackendPort)) env[name] = backendUrl;
+    else if (current) skipped.push(name);
+  }
+  // A lone API variable with no value configured anywhere can only mean this backend.
+  // With two or more, guessing risks pointing one service at another, so we do not.
+  if (!Object.keys(env).length && candidates.length === 1 && !skipped.length) {
+    env[candidates[0].name] = backendUrl;
+  }
+  return { env, skipped, candidates: candidates.map((entry) => entry.name) };
+}
+
 /**
  * How the frontend will reach the backend, given that both may have moved. Order of
  * preference: extend the frontend's own dev proxy (same-origin, native HMR), then a
@@ -165,10 +256,18 @@ function planWiring({ frontend, backend, ports, config, naturalBackendPort }) {
     : originFor(ports.backend);
 
   if (!sameOrigin) {
-    const apiNames = scanFrontendApiEnvNames(frontend);
-    for (const name of apiNames) frontendEnv[name] = backendUrl;
-    if (apiNames.length) notes.push(`frontend API env: ${apiNames.map((n) => `${n}=${backendUrl}`).join(', ')}`);
-    else notes.push('frontend has no dev proxy and no API env var; it may hardcode the backend URL');
+    const api = resolveFrontendApiEnv(frontend, naturalBackendPort, backendUrl);
+    Object.assign(frontendEnv, api.env);
+    const assigned = Object.keys(api.env);
+    if (assigned.length) {
+      notes.push(`frontend API env: ${assigned.map((n) => `${n}=${backendUrl}`).join(', ')}`);
+    }
+    for (const skipped of api.skipped) notes.push(`left ${skipped} alone (points elsewhere)`);
+    if (!assigned.length && !api.candidates.length) {
+      notes.push('frontend has no dev proxy and no API env var; it may hardcode the backend URL');
+    } else if (!assigned.length) {
+      notes.push(`no frontend API variable pointed at the backend; set one of ${api.candidates.join(', ')} manually`);
+    }
   }
 
   // CORS work is only meaningful when the browser will actually cross origins.
@@ -192,6 +291,8 @@ function planWiring({ frontend, backend, ports, config, naturalBackendPort }) {
     corsEnvNames: cors.names,
     notes,
     viteConfig,
+    // Only needed when the browser will actually reach a second origin.
+    cspOrigins: sameOrigin ? [] : devOriginsFor(ports.backend),
     overrideFile: mode === 'vite-retarget' ? path.join(frontend.directory, overrideName) : null,
     describe() {
       if (mode === 'proxy') return `same-origin proxy on ${ports.proxy} (${apiPrefix} -> backend)`;
@@ -234,7 +335,8 @@ function applyWiring(plan, frontend, ports, config) {
     frontendPort: ports.frontend,
     backendPort: ports.backend,
     naturalBackendPort: Number.isInteger(plan.naturalBackendPort) ? plan.naturalBackendPort : null,
-    apiPrefix: config.apiPrefix
+    apiPrefix: config.apiPrefix,
+    cspOrigins: plan.cspOrigins
   });
   fs.writeFileSync(plan.overrideFile, source, 'utf8');
   return () => {
@@ -252,6 +354,9 @@ module.exports = {
   viteOverrideName,
   applyWiring,
   corsEnvFor,
+  devOriginsFor,
+  extendCspConnectSrc,
+  resolveFrontendApiEnv,
   planWiring,
   proxyAvailable,
   retargetProxy,