ports-manager 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Saad Amin (SENODROOM)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# 🚦 Ports Manager
+
+<p align="center">
+  <strong>Launch your frontend and backend together — on free ports, without CORS headaches.</strong>
+</p>
+
+<p align="center">
+  <img alt="Node.js 18+" src="https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white">
+  <img alt="License MIT" src="https://img.shields.io/badge/license-MIT-blue">
+  <img alt="VS Code" src="https://img.shields.io/badge/VS%20Code-supported-007ACC?logo=visualstudiocode">
+  <img alt="Cursor" src="https://img.shields.io/badge/Cursor-supported-black">
+</p>
+
+---
+
+## Why Ports Manager?
+
+Local frontend/backend development should not require manually checking ports, editing `.env`
+files, fixing CORS, and juggling multiple terminals.
+
+Run one command from your project root:
+
+```bash
+npx ports-manager
+```
+
+Ports Manager will:
+
+- 🔎 Detect your `frontend` + `backend` or `client` + `server`
+- 🛬 Find separate free ports while always avoiding `3000` and `5000`
+- ⚛️ Configure CRA, Vite, or Next.js automatically
+- 🟢 Start Express, Koa, Fastify, NestJS, or generic Node backends
+- 🔗 Provide the backend URL to the frontend at runtime
+- 🛡️ Handle development CORS without changing application source
+- 🧹 Stop both process trees cleanly when you press `Ctrl+C`
+- 🖥️ Optionally open each app in its own VS Code/Cursor terminal
+
+No application source files are rewritten.
+
+## Quick start
+
+Your project should look like one of these:
+
+```text
+my-project/
+├── frontend/        # or client/
+│   └── package.json
+└── backend/         # or server/
+    └── package.json
+```
+
+Run Ports Manager from `my-project`, not from inside either child:
+
+```bash
+cd my-project
+npx ports-manager
+```
+
+Example output:
+
+```text
+Backend:  express / npm run dev / 4000
+Frontend: vite / npm run dev / 4001
+CORS shim: enabled
+```
+
+Ports Manager prefers `npm run dev`, then falls back to `npm start`.
+
+## Common recipes
+
+### Preview without starting anything
+
+```bash
+npx ports-manager --dry-run
+```
+
+### Use custom folder names
+
+```bash
+npx ports-manager \
+  --frontend-dir apps/web \
+  --backend-dir apps/api
+```
+
+### Choose a port range and ban extra ports
+
+```bash
+npx ports-manager --range 4100-4900 --ban 4200,4300
+```
+
+### Wait for the backend before starting the frontend
+
+```bash
+npx ports-manager --wait-for-backend
+```
+
+### Use a same-origin development proxy
+
+```bash
+npx ports-manager --proxy --api-prefix /api
+```
+
+### Open separate VS Code/Cursor terminals
+
+From an integrated terminal:
+
+```bash
+npx ports-manager --ide-terminals
+```
+
+`auto` mode uses the Ports Manager extension bridge when available. Otherwise, it
+creates dedicated VS Code tasks. Launch generated tasks through:
+
+```text
+Ctrl/Cmd+Shift+P → Tasks: Run Task → Ports Manager: Run All
+```
+
+To generate a shortcut reference:
+
+```bash
+npx ports-manager --ide-terminals=tasks --with-keybinding
+```
+
+VS Code does not apply workspace keybindings automatically. Copy the generated
+entry from `.vscode/ports-manager-keybindings.json` into **Keyboard Shortcuts
+(JSON)**.
+
+## Supported stacks
+
+| Role | Supported detection | Port strategy |
+|---|---|---|
+| Frontend | Create React App | `PORT` environment variable |
+| Frontend | Vite | `--port` + `--strictPort` |
+| Frontend | Next.js | `-p` argument |
+| Backend | Express, Koa, Fastify | `PORT` environment variable |
+| Backend | NestJS | `PORT` environment variable, best effort |
+| Either | Generic Node project | `PORT`, with a compatibility warning |
+
+The backend must read `process.env.PORT`. Ports Manager warns when its static scan
+cannot find that behavior or detects a possible literal `.listen(5000)`.
+
+## CORS and API URLs
+
+The development CORS shim is enabled by default. It is injected into the
+backend through `NODE_OPTIONS` and:
+
+- reflects the browser's `Origin`
+- supports credentials
+- handles `OPTIONS` preflight with `204`
+- preserves the existing `Vary` header
+
+If Ports Manager detects existing CORS middleware, it skips the shim. Override or
+disable that behavior with:
+
+```bash
+npx ports-manager --force-cors
+npx ports-manager --no-cors-shim
+```
+
+Framework-specific API variables are supplied automatically:
+
+- CRA: `REACT_APP_API_URL`
+- Vite: `VITE_API_URL`
+- Next.js: `NEXT_PUBLIC_API_URL`
+
+> [!WARNING]
+> The CORS shim is intentionally permissive and intended only for local
+> development. It is not a production security policy.
+
+## Configuration
+
+Create `ports-manager.config.json` in the project root:
+
+```json
+{
+  "pairs": [
+    ["frontend", "backend"],
+    ["client", "server"]
+  ],
+  "portRange": [4000, 4999],
+  "bannedPorts": [3000, 5000],
+  "apiPrefix": "/api",
+  "cors": {
+    "mode": "shim",
+    "credentials": true
+  },
+  "proxy": {
+    "enabled": false
+  },
+  "ideTerminals": {
+    "mode": "off",
+    "withKeybinding": false
+  },
+  "env": {
+    "frontend": {
+      "CUSTOM_API_URL": "http://127.0.0.1:{backendPort}"
+    }
+  }
+}
+```
+
+Environment values can use `{frontendPort}`, `{backendPort}`, `{proxyPort}`,
+and `{apiPrefix}` placeholders. CLI flags override configuration values.
+
+## CLI reference
+
+```text
+--frontend-dir PATH       Override frontend directory
+--backend-dir PATH        Override backend directory
+--frontend-port PORT      Request a specific frontend port
+--backend-port PORT       Request a specific backend port
+--proxy-port PORT         Request a specific proxy port
+--range MIN-MAX           Port search range
+--ban PORTS               Comma-separated banned ports
+--no-cors-shim            Disable the development CORS shim
+--force-cors              Override detected CORS middleware
+--proxy                   Enable the same-origin proxy
+--api-prefix PATH         Backend proxy prefix
+--wait-for-backend[=MS]   Wait for the backend to listen
+--ide-terminals[=MODE]    auto, off, tasks, or extension
+--with-keybinding         Generate a shortcut reference
+--config PATH             Use an explicit configuration file
+--dry-run                 Print the plan without writing or starting
+--stop                    Stop bridge-managed workspace terminals
+--version, -v             Show version and author
+--help, -h                Show all options
+```
+
+Run `npx ports-manager --help` for the canonical list.
+
+## VS Code/Cursor extension
+
+This repository is one package that produces both the npm CLI and an optional
+VSIX:
+
+```bash
+npm install
+npm run package:vsix
+```
+
+Install `ports-manager-1.0.0.vsix` in VS Code or Cursor. The bridge listens
+only on `127.0.0.1`, requires a random bearer token, validates request data,
+and tracks terminals by workspace.
+
+Stop managed terminals with:
+
+```bash
+npx ports-manager --stop
+```
+
+or run **Ports Manager: Stop All Managed Terminals** from the command palette.
+
+## Limitations
+
+- Port checks cannot reserve a port until the framework binds to it.
+- Framework, CORS, and hardcoded-port scans are heuristic.
+- Backends that ignore `process.env.PORT` cannot be redirected without code changes.
+- IDE task mode needs one manual task launch unless the extension bridge is installed.
+- Workspaces/monorepos and non-VS-Code-family IDEs are not currently supported.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run test:cli
+npm run test:bridge
+npm run package:vsix
+```
+
+---
+
+<p align="center">
+  Built by <strong>Muhammad Saad Amin</strong> — <strong>SENODROOM</strong><br>
+  Released under the MIT License.
+</p>

package/bin/ports-manager.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/cli').main().catch((error) => {
+  console.error(`ports-manager: ${error.message}`);
+  if (process.env.PORTS_MANAGER_DEBUG) console.error(error.stack);
+  process.exitCode = 1;
+});

package/bridge/src/extension.ts

@@ -0,0 +1,96 @@
+import * as vscode from 'vscode';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { BridgeServer, TerminalHost, TerminalSpec } from './server';
+
+let bridge: BridgeServer | undefined;
+let descriptorFile: string | undefined;
+let activeToken: string | undefined;
+
+function writeDescriptor(port: number, token: string): string {
+  const directory = path.join(os.homedir(), '.ports-manager');
+  const filename = path.join(directory, 'bridge.json');
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(directory, 0o700);
+  } catch {
+    // Windows ACLs do not map directly to POSIX modes.
+  }
+  const temporary = path.join(directory, `.bridge-${process.pid}-${crypto.randomBytes(6).toString('hex')}.tmp`);
+  const payload = JSON.stringify({
+    endpoint: `http://127.0.0.1:${port}/`,
+    token,
+    pid: process.pid
+  });
+  fs.writeFileSync(temporary, payload, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+  try {
+    fs.renameSync(temporary, filename);
+  } catch (error) {
+    if (process.platform !== 'win32') {
+      fs.rmSync(temporary, { force: true });
+      throw error;
+    }
+    fs.rmSync(filename, { force: true });
+    fs.renameSync(temporary, filename);
+  }
+  try {
+    fs.chmodSync(filename, 0o600);
+  } catch {
+    // Best effort on Windows.
+  }
+  return filename;
+}
+
+function removeOwnDescriptor(): void {
+  if (!descriptorFile || !activeToken) return;
+  try {
+    const current = JSON.parse(fs.readFileSync(descriptorFile, 'utf8')) as { token?: string };
+    if (current.token === activeToken) fs.rmSync(descriptorFile, { force: true });
+  } catch {
+    // Already removed or replaced.
+  }
+}
+
+export async function activate(context: vscode.ExtensionContext): Promise<void> {
+  const token = crypto.randomBytes(32).toString('hex');
+  activeToken = token;
+  const host: TerminalHost = {
+    create(spec: TerminalSpec) {
+      return vscode.window.createTerminal({
+        name: spec.name,
+        cwd: spec.cwd,
+        env: spec.env,
+        isTransient: true
+      });
+    }
+  };
+  bridge = new BridgeServer(token, host);
+  try {
+    const port = await bridge.listen();
+    descriptorFile = writeDescriptor(port, token);
+  } catch (error) {
+    await bridge.close();
+    bridge = undefined;
+    activeToken = undefined;
+    vscode.window.showErrorMessage(`Ports Manager bridge failed to start: ${error instanceof Error ? error.message : error}`);
+    return;
+  }
+
+  context.subscriptions.push(
+    vscode.window.onDidCloseTerminal((terminal) => bridge?.forget(terminal)),
+    vscode.commands.registerCommand('ports-manager.stopAll', () => {
+      const count = bridge?.stopAll() || 0;
+      vscode.window.showInformationMessage(`Stopped ${count} Ports Manager terminal${count === 1 ? '' : 's'}.`);
+    })
+  );
+}
+
+export async function deactivate(): Promise<void> {
+  removeOwnDescriptor();
+  if (bridge) await bridge.close();
+  bridge = undefined;
+  activeToken = undefined;
+  descriptorFile = undefined;
+}

package/bridge/src/server.ts

@@ -0,0 +1,185 @@
+import * as http from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+
+export interface TerminalSpec {
+  name: string;
+  cwd: string;
+  env: Record<string, string>;
+  command: string;
+}
+
+export interface ManagedTerminal {
+  show(preserveFocus?: boolean): void;
+  sendText(text: string, addNewLine?: boolean): void;
+  dispose(): void;
+}
+
+export interface TerminalHost {
+  create(spec: TerminalSpec): ManagedTerminal;
+}
+
+interface LaunchBody {
+  tag: string;
+  terminals: TerminalSpec[];
+}
+
+interface StopBody {
+  tag: string;
+}
+
+const MAX_BODY = 64 * 1024;
+
+function plainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function shortString(value: unknown, maximum = 4096): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= maximum;
+}
+
+export function validateLaunchBody(value: unknown): LaunchBody {
+  if (!plainObject(value) || !shortString(value.tag, 1024) ||
+      !Array.isArray(value.terminals) || value.terminals.length < 1 || value.terminals.length > 8) {
+    throw new Error('invalid terminal launch body');
+  }
+  const terminals = value.terminals.map((candidate): TerminalSpec => {
+    if (!plainObject(candidate) || !shortString(candidate.name, 200) ||
+        !shortString(candidate.cwd, 4096) || !shortString(candidate.command, 16384) ||
+        !plainObject(candidate.env)) {
+      throw new Error('invalid terminal specification');
+    }
+    const env: Record<string, string> = {};
+    for (const [key, item] of Object.entries(candidate.env)) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof item !== 'string' || item.length > 16384) {
+        throw new Error('invalid terminal environment');
+      }
+      env[key] = item;
+    }
+    return { name: candidate.name, cwd: candidate.cwd, command: candidate.command, env };
+  });
+  return { tag: value.tag, terminals };
+}
+
+function validateStopBody(value: unknown): StopBody {
+  if (!plainObject(value) || !shortString(value.tag, 1024)) throw new Error('invalid stop body');
+  return { tag: value.tag };
+}
+
+function isLoopback(address: string | undefined): boolean {
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
+
+function authorized(header: string | undefined, token: string): boolean {
+  if (!header?.startsWith('Bearer ')) return false;
+  const supplied = Buffer.from(header.slice(7));
+  const expected = Buffer.from(token);
+  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+}
+
+async function readJson(request: http.IncomingMessage): Promise<unknown> {
+  if (!String(request.headers['content-type'] || '').toLowerCase().startsWith('application/json')) {
+    throw new Error('content-type must be application/json');
+  }
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > MAX_BODY) throw new Error('request body too large');
+    chunks.push(buffer);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+function send(response: http.ServerResponse, status: number, body: object): void {
+  const payload = JSON.stringify(body);
+  response.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(payload),
+    'Cache-Control': 'no-store'
+  });
+  response.end(payload);
+}
+
+export class BridgeServer {
+  private server?: http.Server;
+  private readonly tracked = new Map<string, Set<ManagedTerminal>>();
+
+  constructor(private readonly token: string, private readonly host: TerminalHost) {}
+
+  async listen(): Promise<number> {
+    if (this.server) throw new Error('bridge already listening');
+    this.server = http.createServer((request, response) => void this.handle(request, response));
+    await new Promise<void>((resolve, reject) => {
+      this.server!.once('error', reject);
+      this.server!.listen(0, '127.0.0.1', resolve);
+    });
+    const address = this.server.address();
+    if (!address || typeof address === 'string') throw new Error('bridge failed to bind');
+    return address.port;
+  }
+
+  private async handle(request: http.IncomingMessage, response: http.ServerResponse): Promise<void> {
+    try {
+      if (!isLoopback(request.socket.remoteAddress)) return send(response, 403, { error: 'loopback only' });
+      if (!authorized(request.headers.authorization, this.token)) return send(response, 401, { error: 'unauthorized' });
+      if (request.method !== 'POST') return send(response, 405, { error: 'POST required' });
+      const body = await readJson(request);
+      if (request.url === '/terminals') {
+        const launch = validateLaunchBody(body);
+        this.stopTag(launch.tag);
+        const terminals = new Set<ManagedTerminal>();
+        try {
+          for (const spec of launch.terminals) {
+            const terminal = this.host.create(spec);
+            terminals.add(terminal);
+            terminal.show(true);
+            terminal.sendText(spec.command, true);
+          }
+        } catch (error) {
+          for (const terminal of terminals) terminal.dispose();
+          throw error;
+        }
+        this.tracked.set(launch.tag, terminals);
+        return send(response, 201, { created: terminals.size });
+      }
+      if (request.url === '/stop') {
+        const stop = validateStopBody(body);
+        const stopped = this.stopTag(stop.tag);
+        return send(response, 200, { stopped });
+      }
+      return send(response, 404, { error: 'not found' });
+    } catch (error) {
+      return send(response, 400, { error: error instanceof Error ? error.message : 'bad request' });
+    }
+  }
+
+  forget(terminal: ManagedTerminal): void {
+    for (const [tag, terminals] of this.tracked) {
+      terminals.delete(terminal);
+      if (!terminals.size) this.tracked.delete(tag);
+    }
+  }
+
+  stopTag(tag: string): number {
+    const terminals = this.tracked.get(tag);
+    if (!terminals) return 0;
+    this.tracked.delete(tag);
+    for (const terminal of terminals) terminal.dispose();
+    return terminals.size;
+  }
+
+  stopAll(): number {
+    let count = 0;
+    for (const tag of [...this.tracked.keys()]) count += this.stopTag(tag);
+    return count;
+  }
+
+  async close(): Promise<void> {
+    this.stopAll();
+    if (!this.server) return;
+    const server = this.server;
+    this.server = undefined;
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}