ports-manager 1.0.0 → 1.1.0

package/.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(curl -s -m 8 \"http://localhost:3002/api/v1/health\")",
+      "Bash(curl -s -m 8 -o /dev/null -w \"http status %{http_code}\\\\n\" \"http://localhost:3002/qc-api/x\")",
+      "Bash(cp -r C:/Users/saada/AppData/Local/Temp/claude/c--Programming-ports-manager/e29f8f20-13f0-4ba0-aa60-d1a97f9d89fe/scratchpad/demo C:/Users/saada/AppData/Local/Temp/claude/c--Programming-ports-manager/e29f8f20-13f0-4ba0-aa60-d1a97f9d89fe/scratchpad/demo2)",
+      "Bash(sed -i 's/demo backend on/demo2 backend on/' C:/Users/saada/AppData/Local/Temp/claude/c--Programming-ports-manager/e29f8f20-13f0-4ba0-aa60-d1a97f9d89fe/scratchpad/demo2/backend/src/index.js)",
+      "Bash(grep -vE \"^\\\\[Frontend\\\\] *$\")",
+      "Bash(curl -s -m 8 \"http://localhost:3004/api/v1/health\")"
+    ]
+  }
+}

package/README.md

@@ -1,276 +1,278 @@
-# 🚦 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>
+# 🚦 Ports Manager
+
+<p align="center">
+  <strong>Run several MERN projects at once — each on ports that are actually free, with the frontend wired to wherever the backend landed.</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">
+</p>
+
+---
+
+## Why Ports Manager?
+
+Running a second project when `3000` and `5000` are already busy usually means editing
+`vite.config.ts`, editing `.env`, and adding a new origin to your CORS allowlist — every
+time. Ports Manager does that for you, for the duration of the run, without touching your
+source files.
+
+```bash
+cd my-project
+npx ports-manager
+```
+
+```text
+Root:      C:\work\my-project
+Backend:   express / npm run dev / port 5001
+Frontend:  vite / npm run dev / port 5175
+Wiring:    vite dev proxy retargeted to backend 5001
+CORS:      not needed (same origin)
+Open:      http://localhost:5175
+```
+
+Start the same project again — or a different one — and the second run steps aside:
+
+```text
+Backend:   express / npm run dev / port 3000 (5001 busy)
+Frontend:  vite / npm run dev / port 3001 (5175 busy)
+Wiring:    vite dev proxy retargeted to backend 3000
+Open:      http://localhost:3001
+```
+
+What it does:
+
+- 🔎 Detects your `frontend` + `backend` or `client` + `server`
+- 📦 Checks the dev binaries exist **before** starting, and installs them if they don't
+- 🎯 Prefers each project's own port, falls back only when it is taken
+- 🔗 Rewrites the frontend's dev proxy so `/api` reaches the relocated backend
+- 🛡️ Sets the CORS origin variables your backend already reads
+- 🧹 Stops both process trees cleanly on `Ctrl+C`
+
+No application source file is modified. The only file written is a temporary Vite config
+next to your own, named per process and deleted when the run ends. If you want it out of
+version control entirely, add this to `.gitignore`:
+
+```gitignore
+.ports-manager.*.vite.config.mjs
+```
+
+## Install
+
+```bash
+npm install --global ports-manager
+```
+
+Or run it without installing:
+
+```bash
+npx ports-manager
+```
+
+## 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. It prefers
+`npm run dev` and falls back to `npm start`.
+
+## How the wiring works
+
+Moving the backend is the easy half. The half that breaks apps is everything that still
+points at the old port. Ports Manager picks the best available strategy:
+
+| Frontend | Strategy | Result |
+|---|---|---|
+| Vite with a `server.proxy` | Generates a config extending yours with the proxy target repointed | Same origin, native HMR, no extra port |
+| CRA, Next.js, generic | Same-origin reverse proxy in front of both services | One URL serves the app and `/api` |
+| No proxy anywhere | Sets the API env var your source actually references | Cross-origin, CORS variables injected |
+
+The proxy rewrite is deliberately narrow. Given this config:
+
+```ts
+proxy: {
+  '/api':    { target: 'http://localhost:5001' },  // your backend
+  '/qc-api': { target: 'http://localhost:5000' }   // some other service
+}
+```
+
+only `/api` is repointed, because only it targets the backend's own port. `/qc-api` is
+left alone, and both decisions are printed at startup.
+
+## CORS
+
+When the browser talks to a single origin — the Vite proxy or the same-origin proxy —
+there is no CORS to fix, and Ports Manager says so rather than pretending to act.
+
+When requests really are cross-origin, it scans your backend for the origin variables it
+already reads (`CORS_ORIGIN`, `ALLOWED_ORIGINS`, `CLIENT_URL`, `FRONTEND_URL`, and
+similar) and sets those to the frontend's origin for the run. Only names your code
+references are set. An existing value in `.env` is extended, not replaced:
+
+```text
+CORS: injecting CORS_ORIGIN=https://app.example.com,http://localhost:3001
+```
+
+If your backend reads no recognizable variable, `--force-cors` preloads a shim that
+applies CORS headers at response-send time, overriding whatever the app set:
+
+```bash
+npx ports-manager --force-cors
+```
+
+> [!WARNING]
+> The shim is intentionally permissive and meant only for local development.
+
+## Missing dependencies
+
+A dev script naming a binary that was never installed used to fail with a bare
+`'vite' is not recognized as an internal or external command`. Ports Manager now resolves
+every binary a dev script needs before spawning anything, and installs with the package
+manager your lockfile implies (npm, pnpm, yarn, or bun):
+
+```text
+frontend: dependencies not installed
+[frontend] running `npm install` in C:\work\my-project\frontend
+```
+
+Prefer to do it yourself:
+
+```bash
+npx ports-manager --no-install
+```
+
+```text
+dependencies are missing and --no-install was given
+frontend: `vite` not found in C:\work\my-project\frontend
+  fix: cd C:\work\my-project\frontend && npm install
+```
+
+## Running several projects at once
+
+Ports are held open from the moment they are chosen until the child processes start, so a
+second instance launched at the same moment cannot pick the same one. Each instance also
+records its ports in `~/.ports-manager/leases.json`, keyed by pid, so concurrent runs
+avoid each other; entries whose process has exited are pruned automatically.
+
+## Common recipes
+
+```bash
+# Preview without installing or starting anything
+npx ports-manager --dry-run
+
+# Custom folder names
+npx ports-manager --frontend-dir apps/web --backend-dir apps/api
+
+# Restrict the search range and keep some ports free
+npx ports-manager --range 4100-4900 --ban 4200,4300
+
+# Pin one side
+npx ports-manager --backend-port 5001
+
+# Force the same-origin proxy even for Vite
+npx ports-manager --proxy --api-prefix /api
+
+# Let the backend come up first
+npx ports-manager --wait-for-backend
+```
+
+## Supported stacks
+
+| Role | Detected | Port strategy |
+|---|---|---|
+| Frontend | Vite | `--port` + `--strictPort`, plus a generated config |
+| Frontend | Create React App | `PORT` environment variable |
+| Frontend | Next.js | `-p` argument |
+| Backend | Express, Koa, Fastify, NestJS | `PORT` environment variable |
+| Either | Generic Node project | `PORT` environment variable |
+
+The natural port is read from `.env`, then the dev script, then `vite.config.*`, then a
+schema default such as `PORT: z.coerce.number().default(5001)` — so a backend that reads
+its port through a config module is handled correctly.
+
+Backends must honour `PORT`. Rather than guessing from a static scan, Ports Manager
+watches whether the port is actually bound and tells you if it was not:
+
+```text
+[Ports Manager] Backend never bound port 5001.
+  It may ignore the PORT environment variable. Set PORT in the backend .env,
+  or pin it with --backend-port 5001.
+```
+
+## Configuration
+
+Create `ports-manager.config.json` in the project root:
+
+```json
+{
+  "pairs": [["frontend", "backend"], ["client", "server"]],
+  "portRange": [3000, 5999],
+  "bannedPorts": [],
+  "apiPrefix": "/api",
+  "install": true,
+  "cors": true,
+  "proxy": null,
+  "env": {
+    "frontend": { "CUSTOM_API_URL": "http://127.0.0.1:{backendPort}" }
+  }
+}
+```
+
+`proxy` accepts `true` (always), `false` (never), or `null` (use it only when the
+frontend cannot proxy for itself). Environment values may use `{frontendPort}`,
+`{backendPort}`, `{proxyPort}`, and `{apiPrefix}`. CLI flags override the file.
+
+## CLI reference
+
+```text
+--frontend-dir PATH      Override frontend/client directory
+--backend-dir PATH       Override backend/server directory
+--frontend-port PORT     Pin the frontend port
+--backend-port PORT      Pin the backend port
+--proxy-port PORT        Pin the same-origin proxy port
+--range MIN-MAX          Port search range (default 3000-5999)
+--ban PORTS              Never use these comma-separated ports
+--proxy / --no-proxy     Force or forbid same-origin proxy mode
+--api-prefix PATH        Path routed to the backend (default /api)
+--no-install             Fail instead of installing missing dependencies
+--no-cors                Do not inject backend CORS origin variables
+--force-cors             Also preload a response-time CORS shim
+--no-cors-credentials    Shim omits Access-Control-Allow-Credentials
+--wait-for-backend[=MS]  Wait for the backend before starting the frontend
+--config PATH            Explicit JSON config
+--dry-run                Show the plan without installing or starting anything
+--version, -v            Show version and author
+--help, -h               Show all options
+```
+
+## Limitations
+
+- Next.js has no `--config` flag, so its rewrites cannot be retargeted; it uses the
+  same-origin proxy or env wiring instead.
+- CRA reads `proxy` from `package.json`, which cannot be overridden per run, so it also
+  uses the same-origin proxy.
+- Framework and natural-port detection are heuristics; pin a port when they guess wrong.
+- Monorepos and workspace layouts beyond a single `frontend`/`backend` pair are untested.
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+---
+
+<p align="center">
+  Built by <strong>Muhammad Saad Amin</strong> — <strong>SENODROOM</strong><br>
+  Released under the MIT License.
+</p>

package/package.json

@@ -1,11 +1,9 @@
 {
   "name": "ports-manager",
-  "version": "1.0.0",
-  "displayName": "Ports Manager",
-  "publisher": "SENODROOM",
+  "version": "1.1.0",
   "author": "Muhammad Saad Amin",
-  "description": "Launch paired frontend/backend projects on free ports with CORS handling and optional VS Code/Cursor terminals.",
-  "main": "./dist/bridge/src/extension.js",
+  "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",
   "exports": {
     ".": "./src/index.js"
   },
@@ -14,57 +12,30 @@
   },
   "type": "commonjs",
   "engines": {
-    "node": ">=18",
-    "vscode": "^1.85.0"
-  },
-  "categories": [
-    "Other"
-  ],
-  "activationEvents": [
-    "onStartupFinished"
-  ],
-  "contributes": {
-    "commands": [
-      {
-        "command": "ports-manager.stopAll",
-        "title": "Ports Manager: Stop All Managed Terminals"
-      }
-    ]
+    "node": ">=18"
   },
   "scripts": {
-    "compile:bridge": "tsc -p tsconfig.bridge.json",
-    "test": "npm run test:cli && npm run test:bridge",
-    "test:cli": "node --test test/core.test.js test/cors.integration.test.js test/process.integration.test.js",
-    "test:bridge": "npm run compile:bridge && node --test dist/bridge/test/server.test.js",
-    "package:vsix": "npm run compile:bridge && vsce package --allow-missing-repository",
-    "package:ovsx": "npm run package:vsix",
-    "publish:ovsx": "ovsx publish",
-    "prepack": "npm run compile:bridge",
+    "test": "node --test test/core.test.js test/wiring.test.js test/cors.integration.test.js test/process.integration.test.js",
     "start": "node bin/ports-manager.js"
   },
   "dependencies": {
     "chalk": "^4.1.2",
     "cosmiconfig": "^9.0.0",
-    "jsonc-parser": "^3.3.1",
     "tree-kill": "^1.2.2"
   },
   "optionalDependencies": {
     "http-proxy-middleware": "^3.0.5"
   },
   "devDependencies": {
-    "@types/node": "^22.10.0",
-    "@types/vscode": "^1.85.0",
-    "@vscode/vsce": "^3.2.2",
-    "ovsx": "^0.10.1",
-    "typescript": "^5.7.2"
+    "@types/node": "^22.10.0"
   },
   "keywords": [
     "ports",
     "mern",
     "cli",
-    "vscode",
-    "cursor",
     "cors",
+    "vite",
+    "proxy",
     "dev-server"
   ],
   "license": "MIT",