portless 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,4 +1,6 @@
+import * as node_tls from 'node:tls';
 import * as http from 'node:http';
+import * as net from 'node:net';
 
 /** Route info used by the proxy server to map hostnames to ports. */
 interface RouteInfo {
@@ -12,18 +14,31 @@ interface ProxyServerOptions {
     proxyPort: number;
     /** Optional error logger; defaults to console.error. */
     onError?: (message: string) => void;
+    /** When provided, enables HTTP/2 over TLS (HTTPS). */
+    tls?: {
+        cert: Buffer;
+        key: Buffer;
+        /** SNI callback for per-hostname certificate selection. */
+        SNICallback?: (servername: string, cb: (err: Error | null, ctx?: node_tls.SecureContext) => void) => void;
+    };
 }
 
 /** Response header used to identify a portless proxy (for health checks). */
 declare const PORTLESS_HEADER = "X-Portless";
+/** Server type returned by createProxyServer (plain HTTP/1.1 or net.Server TLS wrapper). */
+type ProxyServer = http.Server | net.Server;
 /**
  * Create an HTTP proxy server that routes requests based on the Host header.
  *
  * Uses Node's built-in http module for proxying (no external dependencies).
  * The `getRoutes` callback is invoked on every request so callers can provide
  * either a static list or a live-updating one.
+ *
+ * When `tls` is provided, creates an HTTP/2 secure server with HTTP/1.1
+ * fallback (`allowHTTP1: true`). This enables HTTP/2 multiplexing for
+ * browsers while keeping WebSocket upgrades working over HTTP/1.1.
  */
-declare function createProxyServer(options: ProxyServerOptions): http.Server;
+declare function createProxyServer(options: ProxyServerOptions): ProxyServer;
 
 /** File permission mode for route and state files. */
 declare const FILE_MODE = 420;
@@ -37,7 +52,8 @@ interface RouteMapping extends RouteInfo {
  * Supports file locking and stale-route cleanup.
  */
 declare class RouteStore {
-    private readonly dir;
+    /** The state directory path. */
+    readonly dir: string;
     private readonly routesPath;
     private readonly lockPath;
     readonly pidPath: string;
@@ -72,13 +88,14 @@ declare function isErrnoException(err: unknown): err is NodeJS.ErrnoException;
  */
 declare function escapeHtml(str: string): string;
 /**
- * Format a .localhost URL, including the port only when it is not 80 (standard HTTP).
+ * Format a .localhost URL. Omits the port when it matches the protocol default
+ * (80 for HTTP, 443 for HTTPS).
  */
-declare function formatUrl(hostname: string, proxyPort: number): string;
+declare function formatUrl(hostname: string, proxyPort: number, tls?: boolean): string;
 /**
  * Parse and normalize a hostname input for use as a .localhost subdomain.
  * Strips protocol prefixes, validates characters, and appends .localhost if needed.
  */
 declare function parseHostname(input: string): string;
 
-export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServerOptions, type RouteInfo, type RouteMapping, RouteStore, createProxyServer, escapeHtml, formatUrl, isErrnoException, parseHostname };
+export { DIR_MODE, FILE_MODE, PORTLESS_HEADER, type ProxyServer, type ProxyServerOptions, type RouteInfo, type RouteMapping, RouteStore, createProxyServer, escapeHtml, formatUrl, isErrnoException, parseHostname };

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   formatUrl,
   isErrnoException,
   parseHostname
-} from "./chunk-Y5OVKUR4.js";
+} from "./chunk-VRBD6YAY.js";
 export {
   DIR_MODE,
   FILE_MODE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portless",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,6 @@
   "files": [
     "dist"
   ],
-  "packageManager": "pnpm@9.15.4",
   "engines": {
     "node": ">=20"
   },
@@ -25,21 +24,6 @@
     "darwin",
     "linux"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
-    "prepublishOnly": "pnpm build",
-    "pretest": "pnpm build",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "prepare": "husky"
-  },
   "keywords": [
     "local",
     "development",
@@ -60,24 +44,21 @@
     "chalk": "^5.3.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
     "@types/node": "^20.11.0",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.2",
-    "eslint-config-prettier": "^10.1.8",
-    "husky": "^9.1.7",
-    "lint-staged": "^16.2.7",
-    "prettier": "^3.8.1",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",
-    "typescript-eslint": "^8.55.0",
     "vitest": "^4.0.18"
   },
-  "lint-staged": {
-    "*.{ts,js}": [
-      "eslint --fix",
-      "prettier --write"
-    ],
-    "*.{json,md,yml,yaml}": "prettier --write"
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/README.md

@@ -1,131 +0,0 @@
-# portless
-
-Replace port numbers with stable, named .localhost URLs. For humans and agents.
-
-```diff
-- "dev": "next dev"              # http://localhost:3000
-+ "dev": "portless myapp next dev"  # http://myapp.localhost:1355
-```
-
-## Quick Start
-
-```bash
-# Install
-npm install -g portless
-
-# Start the proxy (once, no sudo needed)
-portless proxy start
-
-# Run your app (auto-starts the proxy if needed)
-portless myapp next dev
-# -> http://myapp.localhost:1355
-```
-
-> The proxy auto-starts when you run an app. You can also start it explicitly with `portless proxy start`.
-
-## Why
-
-Local dev with port numbers is fragile:
-
-- **Port conflicts** -- two projects default to the same port and you get `EADDRINUSE`
-- **Memorizing ports** -- was the API on 3001 or 8080?
-- **Refreshing shows the wrong app** -- stop one server, start another on the same port, and your open tab now shows something completely different
-- **Monorepo multiplier** -- every problem above scales with each service in the repo
-- **Agents test the wrong port** -- AI coding agents guess or hardcode the wrong port, especially in monorepos
-- **Cookie and storage clashes** -- cookies set on `localhost` bleed across apps on different ports; localStorage is lost when ports shift
-- **Hardcoded ports in config** -- CORS allowlists, OAuth redirect URIs, and `.env` files all break when ports change
-- **Sharing URLs with teammates** -- "what port is that on?" becomes a Slack question
-- **Browser history is useless** -- your history for `localhost:3000` is a jumble of unrelated projects
-
-Portless fixes all of this by giving each dev server a stable, named `.localhost` URL that both humans and agents can rely on.
-
-## Usage
-
-```bash
-# Basic
-portless myapp next dev
-# -> http://myapp.localhost:1355
-
-# Subdomains
-portless api.myapp pnpm start
-# -> http://api.myapp.localhost:1355
-
-portless docs.myapp next dev
-# -> http://docs.myapp.localhost:1355
-```
-
-### In package.json
-
-```json
-{
-  "scripts": {
-    "dev": "portless myapp next dev"
-  }
-}
-```
-
-The proxy auto-starts when you run an app. Or start it explicitly: `portless proxy start`.
-
-## How It Works
-
-```mermaid
-flowchart TD
-    Browser["Browser\nmyapp.localhost:1355"]
-    Proxy["portless proxy\n(port 1355)"]
-    App1[":4123\nmyapp"]
-    App2[":4567\napi"]
-
-    Browser -->|port 1355| Proxy
-    Proxy --> App1
-    Proxy --> App2
-```
-
-1. **Start the proxy** -- auto-starts when you run an app, or start explicitly with `portless proxy start`
-2. **Run apps** -- `portless <name> <command>` assigns a free port and registers with the proxy
-3. **Access via URL** -- `http://<name>.localhost:1355` routes through the proxy to your app
-
-Apps are assigned a random port (4000-4999) via the `PORT` environment variable. Most frameworks (Next.js, Vite, etc.) respect this automatically.
-
-## Commands
-
-```bash
-portless <name> <cmd> [args...]  # Run app at http://<name>.localhost:1355
-portless list                    # Show active routes
-
-# Disable portless (run command directly)
-PORTLESS=0 pnpm dev              # Bypasses proxy, uses default port
-# Also accepts PORTLESS=skip
-
-# Proxy control
-portless proxy start             # Start the proxy (port 1355, daemon)
-portless proxy start -p 80       # Start on port 80 (requires sudo)
-portless proxy start --foreground  # Start in foreground (for debugging)
-portless proxy stop              # Stop the proxy
-
-# Options
--p, --port <number>              # Port for the proxy (default: 1355)
-                                 # Ports < 1024 require sudo
---foreground                     # Run proxy in foreground instead of daemon
-
-# Environment variables
-PORTLESS_PORT=<number>           # Override the default proxy port
-PORTLESS_STATE_DIR=<path>        # Override the state directory
-
-# Info
-portless --help                  # Show help
-portless --version               # Show version
-```
-
-## State Directory
-
-Portless stores its state (routes, PID file, port file) in a directory that depends on the proxy port:
-
-- **Port < 1024** (sudo required): `/tmp/portless` -- shared between root and user processes
-- **Port >= 1024** (no sudo): `~/.portless` -- user-scoped, no root involvement
-
-Override with the `PORTLESS_STATE_DIR` environment variable if needed.
-
-## Requirements
-
-- Node.js 20+
-- macOS or Linux