# Trace: Add External Tunnel and Alias Support Agent: opencode | Model: Claude Opus 4.6 | Project: portless --- ## User can we figure out what it would take to make ngrok and cloudflare tunnels work with portless? https://github.com/vercel-labs/portless/issues/43 ## Assistant ## Assistant Let me gather context from the issue and the codebase in parallel. ## Assistant ### Tool: webfetch **Args:** ```json { "format": "markdown", "url": "https://github.com/vercel-labs/portless/issues/43" } ``` ## Assistant **Result** (success): ``` portless + ngrok doesn't work · Issue #43 · vercel-labs/portless · GitHub [Skip to content](#start-of-content) ## Navigation Menu Toggle navigation [](/) [Sign in](/login?return_to=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fportless%2Fissues%2F43) Appearance settings - Platform - AI CODE CREATION - [ GitHub CopilotWrite better code with AI ](https://github.com/features/copilot) - [ GitHub SparkBuild and deploy intelligent apps ](https://github.com/features/spark) - [ GitHub ModelsManage and compare prompts ](https://github.com/features/models) - [ MCP RegistryNewIntegrate external tools ](https://github.com/mcp) - DEVELOPER WORKFLOWS - [ ActionsAutomate any workflow ](https://github.com/features/actions) - [ CodespacesInstant dev environments ](https://github.com/features/codespaces) - [ IssuesPlan and track work ](https://github.com/features/issues) - [ Code ReviewManage code changes ](https://github.com/features/code-review) - APPLICATION SECURITY - [ GitHub Advanced SecurityFind and fix vulnerabilities ](https://github.com/security/advanced-security) - [ Code securitySecure your code as you build ](https://github.com/security/advanced-security/code-security) - [ Secret protectionStop leaks before they start ](https://github.com/security/advanced-security/secret-protection) - EXPLORE - [Why GitHub](https://github.com/why-github) - [Documentation](https://docs.github.com) - [Blog](https://github.blog) - [Changelog](https://github.blog/changelog) - [Marketplace](https://github.com/marketplace) [View all features](https://github.com/features) - Solutions - BY COMPANY SIZE - [Enterprises](https://github.com/enterprise) - [Small and medium teams](https://github.com/team) - [Startups](https://github.com/enterprise/startups) - [Nonprofits](https://github.com/solutions/industry/nonprofits) - BY USE CASE - [App Modernization](https://github.com/solutions/use-case/app-modernization) - [DevSecOps](https://github.com/solutions/use-case/devsecops) - [DevOps](https://github.com/solutions/use-case/devops) - [CI/CD](https://github.com/solutions/use-case/ci-cd) - [View all use cases](https://github.com/solutions/use-case) - BY INDUSTRY - [Healthcare](https://github.com/solutions/industry/healthcare) - [Financial services](https://github.com/solutions/industry/financial-services) - [Manufacturing](https://github.com/solutions/industry/manufacturing) - [Government](https://github.com/solutions/industry/government) - [View all industries](https://github.com/solutions/industry) [View all solutions](https://github.com/solutions) - Resources - EXPLORE BY TOPIC - [AI](https://github.com/resources/articles?topic=ai) - [Software Development](https://github.com/resources/articles?topic=software-development) - [DevOps](https://github.com/resources/articles?topic=devops) - [Security](https://github.com/resources/articles?topic=security) - [View all topics](https://github.com/resources/articles) - EXPLORE BY TYPE - [Customer stories](https://github.com/customer-stories) - [Events & webinars](https://github.com/resources/events) - [Ebooks & reports](https://github.com/resources/whitepapers) - [Business insights](https://github.com/solutions/executive-insights) - [GitHub Skills](https://skills.github.com) - SUPPORT & SERVICES - [Documentation](https://docs.github.com) - [Customer support](https://support.github.com) - [Community forum](https://github.com/orgs/community/discussions) - [Trust center](https://github.com/trust-center) - [Partners](https://github.com/partners) [View all resources](https://github.com/resources) - Open Source - COMMUNITY - [ GitHub SponsorsFund open source developers ](https://github.com/sponsors) - PROGRAMS - [Security Lab](https://securitylab.github.com) - [Maintainer Community](https://maintainers.github.com) - [Accelerator](https://github.com/accelerator) - [Archive Program](https://archiveprogram.github.com) - REPOSITORIES - [Topics](https://github.com/topics) - [Trending](https://github.com/trending) - [Collections](https://github.com/collections) - Enterprise - ENTERPRISE SOLUTIONS - [ Enterprise platformAI-powered developer platform ](https://github.com/enterprise) - AVAILABLE ADD-ONS - [ GitHub Advanced SecurityEnterprise-grade security features ](https://github.com/security/advanced-security) - [ Copilot for BusinessEnterprise-grade AI features ](https://github.com/features/copilot/copilot-business) - [ Premium SupportEnterprise-grade 24/7 support ](https://github.com/premium-support) - [Pricing](https://github.com/pricing) Search or jump to... # Search code, repositories, users, issues, pull requests... Search Clear [Search syntax tips](https://docs.github.com/search-github/github-code-search/understanding-github-code-search-syntax) # Provide feedback We read every piece of feedback, and take your input very seriously. Include my email address so I can be contacted Cancel Submit feedback # Saved searches ## Use saved searches to filter your results more quickly Name Query To see all available qualifiers, see our [documentation](https://docs.github.com/search-github/github-code-search/understanding-github-code-search-syntax). Cancel Create saved search [Sign in](/login?return_to=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fportless%2Fissues%2F43) [Sign up](/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=vercel-labs%2Fportless) Appearance settings Resetting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert [vercel-labs](/vercel-labs) / **[portless](/vercel-labs/portless)** Public - [Notifications](/login?return_to=%2Fvercel-labs%2Fportless) You must be signed in to change notification settings - [Fork 153](/login?return_to=%2Fvercel-labs%2Fportless) - [Star 4.6k](/login?return_to=%2Fvercel-labs%2Fportless) - [Code](/vercel-labs/portless) - [Issues 16](/vercel-labs/portless/issues) - [Pull requests 4](/vercel-labs/portless/pulls) - [Actions](/vercel-labs/portless/actions) - [Projects](/vercel-labs/portless/projects) - [Security 0](/vercel-labs/portless/security) - [Insights](/vercel-labs/portless/pulse) Additional navigation options - [Code](/vercel-labs/portless) - [Issues](/vercel-labs/portless/issues) - [Pull requests](/vercel-labs/portless/pulls) - [Actions](/vercel-labs/portless/actions) - [Projects](/vercel-labs/portless/projects) - [Security](/vercel-labs/portless/security) - [Insights](/vercel-labs/portless/pulse) # portless + ngrok doesn't work #43 [New issue](/login?return_to=https://github.com/vercel-labs/portless/issues/43) Copy link [New issue](/login?return_to=https://github.com/vercel-labs/portless/issues/43) Copy link Open Open [portless + ngrok doesn't work](#top)#43 Copy link Labels [bugSomething isn't working](https://github.com/vercel-labs/portless/issues?q=state%3Aopen%20label%3A%22bug%22)Something isn't working [![@jperezrealini](https://avatars.githubusercontent.com/u/12447726?u=38c9638d0d1197560bdf55bb346014c666064538&v=4&size=80)](https://github.com/jperezrealini) ## Description [![@jperezrealini](https://avatars.githubusercontent.com/u/12447726?u=38c9638d0d1197560bdf55bb346014c666064538&v=4&size=48)](https://github.com/jperezrealini) [jperezrealini](https://github.com/jperezrealini) opened [on Feb 23, 2026](https://github.com/vercel-labs/portless/issues/43#issue-3979821494) Issue body actions [![Image](https://private-user-images.githubusercontent.com/12447726/553671099-0648933d-bd3c-4540-9c8c-e6fc059b0bcf.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzMyMzQxNTEsIm5iZiI6MTc3MzIzMzg1MSwicGF0aCI6Ii8xMjQ0NzcyNi81NTM2NzEwOTktMDY0ODkzM2QtYmQzYy00NTQwLTljOGMtZTZmYzA1OWIwYmNmLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjAzMTElMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwMzExVDEyNTczMVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTQ1MWM1ZWI5ZGQxYzM4NGM0YmU5N2E3OTU3MDk1YWRhOGVhYzQ5NjAyNmFlMDNiY2Q2NmFlMGJhZGJjNDc3MWYmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.Twa3kstpvSJlvlgoIBRWx8Xy3heWI2MO_EiWGZSQl2Y)](https://private-user-images.githubusercontent.com/12447726/553671099-0648933d-bd3c-4540-9c8c-e6fc059b0bcf.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzMyMzQxNTEsIm5iZiI6MTc3MzIzMzg1MSwicGF0aCI6Ii8xMjQ0NzcyNi81NTM2NzEwOTktMDY0ODkzM2QtYmQzYy00NTQwLTljOGMtZTZmYzA1OWIwYmNmLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjAzMTElMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwMzExVDEyNTczMVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTQ1MWM1ZWI5ZGQxYzM4NGM0YmU5N2E3OTU3MDk1YWRhOGVhYzQ5NjAyNmFlMDNiY2Q2NmFlMGJhZGJjNDc3MWYmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.Twa3kstpvSJlvlgoIBRWx8Xy3heWI2MO_EiWGZSQl2Y) Would be nice if this combo was supported! Reactions are currently unavailable ## Metadata ## Metadata ### Assignees No one assigned ### Labels [bugSomething isn't working](https://github.com/vercel-labs/portless/issues?q=state%3Aopen%20label%3A%22bug%22)Something isn't working ### Type No type ### Projects No projects ### Milestone No milestone ### Relationships None yet ### Development No branches or pull requests ## Issue actions ## Footer [](https://github.com)© 2026 GitHub, Inc. ### Footer navigation - [Terms](https://docs.github.com/site-policy/github-terms/github-terms-of-service) - [Privacy](https://docs.github.com/site-policy/privacy-policies/github-privacy-statement) - [Security](https://github.com/security) - [Status](https://www.githubstatus.com/) - [Community](https://github.community/) - [Docs](https://docs.github.com/) - [Contact](https://support.github.com?tags=dotcom-footer) - Manage cookies - Do not share my personal information You can’t perform that action at this time. ``` ## Assistant ### Tool: task **Args:** ```json { "description": "Explore portless tunnel architecture", "prompt": "I need to understand how portless currently handles tunnels. Please explore the codebase thoroughly and return:\n\n1. The overall architecture of portless - what is it, how does it work?\n2. How tunnels are currently implemented - which tunnel providers are supported?\n3. The tunnel abstraction layer - is there a common interface/type for tunnels?\n4. How tunnels are started, configured, and used\n5. How the DNS/hostname resolution works with tunnels\n6. Any relevant types, interfaces, or configuration related to tunnels\n7. The CLI flags and environment variables related to tunnels\n\nBe very thorough - read the key files fully, especially:\n- Any tunnel-related source files\n- The main CLI entry point\n- Configuration types\n- The README or SKILL.md for user-facing docs\n\nReturn file paths and line numbers for all relevant code.", "subagent_type": "explore" } ``` ## Assistant **Result** (success): ``` task_id: ses_323069c61ffeja1SR4VTl1gyqi (for resuming to continue this task if needed) I now have a complete picture. Let me compile the thorough analysis. --- ## Comprehensive Analysis of Portless Tunnel/Proxy Architecture ### 1. Overall Architecture Portless is a **local development reverse proxy** that replaces port numbers with stable, named `.localhost` URLs. It is **not** a tunnel provider in the traditional sense (like ngrok, Cloudflare Tunnel, or localtunnel). It operates entirely on the local machine. **Architecture diagram** (from README lines 94-108): ``` Browser (myapp.localhost:1355) -> portless proxy (port 1355) -> App1 (:4123) / App2 (:4567) ``` **Core flow:** 1. A single reverse proxy daemon listens on port 1355 (configurable) 2. Apps are launched via `portless `, which assigns a random port (4000-4999) and registers a route 3. The proxy maps hostname-based requests to the correct backend port on `127.0.0.1` 4. `.localhost` domains auto-resolve to `127.0.0.1` in most browsers **Key source files:** - `/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts` -- CLI entry point (1488 lines) - `/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts` -- Reverse proxy server (393 lines) - `/Users/sergiydybskiy/src/portless/packages/portless/src/routes.ts` -- Route store with file locking (248 lines) - `/Users/sergiydybskiy/src/portless/packages/portless/src/types.ts` -- Core types (26 lines) - `/Users/sergiydybskiy/src/portless/packages/portless/src/cli-utils.ts` -- Utility functions (551 lines) - `/Users/sergiydybskiy/src/portless/packages/portless/src/hosts.ts` -- /etc/hosts management (122 lines) - `/Users/sergiydybskiy/src/portless/packages/portless/src/certs.ts` -- TLS certificate generation (709 lines) - `/Users/sergiydybskiy/src/portless/packages/portless/src/auto.ts` -- Project name inference (289 lines) --- ### 2. How "Tunnels" Are Currently Implemented **Portless does NOT implement tunnels.** There is zero tunnel support in the codebase. A grep for `tunnel`, `ngrok`, `cloudflare`, `bore`, `localtunnel`, and `expose` across all `.ts` files returned no matches (the only `tunnel-agent` hit is a transitive npm dependency in `pnpm-lock.yaml`, unrelated to portless functionality). What portless calls "proxy" is a **local reverse proxy** -- all traffic stays on `127.0.0.1`. There is no mechanism to expose local services to the public internet. **What exists instead:** - A **local HTTP/HTTPS reverse proxy** (`/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts`, lines 99-393) - **Hostname-based routing** via Host header matching (`proxy.ts`, lines 76-83) - **Wildcard subdomain routing** (e.g., `tenant.myapp.localhost` matches `myapp.localhost`) (`proxy.ts`, line 81) - **WebSocket upgrade proxying** (`proxy.ts`, lines 241-335) - **HTTP/2 + TLS support** with auto-generated certificates (`proxy.ts`, lines 337-387; `certs.ts`, full file) --- ### 3. The Proxy Abstraction Layer (No Tunnel Interface Exists) There is **no tunnel abstraction layer or common tunnel interface**. The only abstractions are: **`RouteInfo` interface** (`/Users/sergiydybskiy/src/portless/packages/portless/src/types.ts`, lines 1-5): ```ts export interface RouteInfo { hostname: string; port: number; } ``` **`ProxyServerOptions` interface** (`types.ts`, lines 7-26): ```ts export interface ProxyServerOptions { getRoutes: () => RouteInfo[]; proxyPort: number; tld?: string; onError?: (message: string) => void; tls?: { cert: Buffer; key: Buffer; SNICallback?: ( servername: string, cb: (err: Error | null, ctx?: import("node:tls").SecureContext) => void ) => void; }; } ``` **`RouteMapping` interface** (extends `RouteInfo` with PID tracking) (`/Users/sergiydybskiy/src/portless/packages/portless/src/routes.ts`, lines 28-30): ```ts export interface RouteMapping extends RouteInfo { pid: number; } ``` **`ProxyServer` type** (`proxy.ts`, line 86): ```ts export type ProxyServer = http.Server | net.Server; ``` **`RouteStore` class** (`routes.ts`, lines 66-248) -- manages route persistence with: - File-based JSON storage (`routes.json`) - Directory-based file locking (with stale lock detection) - Stale-route cleanup (checks if owning PID is alive) - `addRoute()`, `removeRoute()`, `loadRoutes()` methods --- ### 4. How the Proxy is Started, Configured, and Used **Starting the proxy:** - `portless proxy start` -- starts as a background daemon (`cli.ts`, lines 1229-1280) - `portless proxy start --foreground` -- runs in foreground (`cli.ts`, lines 1222-1226) - Auto-starts when running an app if not already running (`cli.ts`, lines 362-442) - The `startProxyServer()` function (`cli.ts`, lines 58-190) creates the server, watches routes file for changes, and handles cleanup **The proxy server creation** (`proxy.ts`, lines 99-393): - `createProxyServer(options)` creates either: - Plain HTTP server (when no TLS) -- `http.createServer()` (`proxy.ts`, lines 389-392) - TLS-enabled wrapper (when TLS) -- wraps `http2.createSecureServer` + `http.createServer` in a `net.Server` that peeks at the first byte to determine TLS vs plain HTTP (`proxy.ts`, lines 337-387) - Request handling: resolves route via Host header, proxies to `127.0.0.1:` (`proxy.ts`, lines 111-239) - WebSocket upgrade handling: separate handler for `upgrade` events (`proxy.ts`, lines 241-335) - Loop detection via `X-Portless-Hops` header (max 5 hops) (`proxy.ts`, lines 61-69, 123-144) **Running an app** (`cli.ts`, `runApp()` function, lines 323-494): 1. Parses hostname from name + TLD 2. Checks if proxy is running, auto-starts if needed 3. Finds a free port (4000-4999 range) or uses `--app-port` 4. Registers route via `store.addRoute(hostname, port, pid)` 5. Injects framework-specific flags (Vite, Astro, etc.) 6. Spawns the child process with `PORT`, `HOST`, and `PORTLESS_URL` env vars 7. On exit, removes the route via `store.removeRoute(hostname)` **State management:** - State directory: `~/.portless` (default) or `/tmp/portless` (privileged ports) (`cli-utils.ts`, lines 22-26) - Override: `PORTLESS_STATE_DIR` env var (`cli-utils.ts`, line 86) - Files stored: `routes.json`, `proxy.pid`, `proxy.port`, `proxy.tls`, `proxy.tld`, certs, logs --- ### 5. How DNS/Hostname Resolution Works **`.localhost` resolution** (README lines 192-203, `cli-utils.ts` lines 127-143): - `.localhost` is an IANA-reserved TLD that auto-resolves to `127.0.0.1` in Chrome, Firefox, and Edge - Safari relies on the system DNS resolver and may not handle subdomains - Fix: `sudo portless hosts sync` adds entries to `/etc/hosts` **Hostname construction** (`/Users/sergiydybskiy/src/portless/packages/portless/src/utils.ts`, `parseHostname()`, lines 58-105): - Input like `myapp` becomes `myapp.localhost` (or `myapp.`) - Input like `api.myapp` becomes `api.myapp.localhost` - Validates: lowercase, alphanumeric + hyphens + dots, max 63 chars per label (RFC 1035) **Worktree prefix detection** (`/Users/sergiydybskiy/src/portless/packages/portless/src/auto.ts`, `detectWorktreePrefix()`, lines 190-197): - Detects git worktrees via `git worktree list` - In a linked worktree on branch `fix-ui`, the name becomes `fix-ui.myapp.localhost` - Default branches (main/master) get no prefix **Custom TLD** (`cli-utils.ts`, lines 127-194): - `--tld test` or `PORTLESS_TLD=test` changes the suffix to `.test` - Auto-syncs `/etc/hosts` for custom TLDs (since they don't auto-resolve) - Warns about risky TLDs: `.local` (mDNS conflicts), `.dev` (Google HSTS), public TLDs **/etc/hosts management** (`/Users/sergiydybskiy/src/portless/packages/portless/src/hosts.ts`, full file): - Managed block between `# portless-start` and `# portless-end` markers - `syncHostsFile()` -- replaces the managed block with current routes - `cleanHostsFile()` -- removes the managed block - Auto-enabled for custom TLDs; opt-in for `.localhost` via `PORTLESS_SYNC_HOSTS=1` **Route matching in the proxy** (`proxy.ts`, `findRoute()`, lines 76-83): ```ts function findRoute(routes, host) { return routes.find(r => r.hostname === host) || routes.find(r => host.endsWith("." + r.hostname)); } ``` Exact match first, then wildcard subdomain fallback. --- ### 6. All Relevant Types, Interfaces, and Configuration **Core types** (`/Users/sergiydybskiy/src/portless/packages/portless/src/types.ts`): - `RouteInfo` (lines 1-5) -- hostname + port - `ProxyServerOptions` (lines 7-26) -- proxy config with routes callback, port, TLD, error handler, TLS **Route types** (`/Users/sergiydybskiy/src/portless/packages/portless/src/routes.ts`): - `RouteMapping` (lines 28-30) -- extends `RouteInfo` with `pid` - `RouteConflictError` (lines 47-60) -- thrown when route already taken - `RouteStore` class (lines 66-248) -- route persistence and locking - Constants: `FILE_MODE` (0o644), `DIR_MODE` (0o755), `SYSTEM_DIR_MODE` (0o1777), `SYSTEM_FILE_MODE` (0o666) **Auto-detection types** (`/Users/sergiydybskiy/src/portless/packages/portless/src/auto.ts`): - `InferredName` (lines 49-52) -- `{ name, source }` - `WorktreePrefix` (lines 157-160) -- `{ prefix, source }` **CLI argument types** (`/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts`): - `ParsedRunArgs` (lines 500-508) -- `{ force, appPort?, name?, commandArgs }` - `ParsedAppArgs` (lines 510-513) -- extends `ParsedRunArgs` with required `name` **Proxy type** (`proxy.ts`, line 86): - `ProxyServer = http.Server | net.Server` **Exported public API** (`/Users/sergiydybskiy/src/portless/packages/portless/src/index.ts`, lines 1-5): ```ts export * from "./types.js"; export * from "./proxy.js"; export * from "./routes.js"; export * from "./utils.js"; export * from "./hosts.js"; ``` --- ### 7. CLI Flags and Environment Variables **CLI flags** (from `cli.ts`, `printHelp()`, lines 730-744): | Flag | Description | Location | |------|-------------|----------| | `-p, --port ` | Proxy listen port (default: 1355) | `cli.ts` lines 1036-1053 | | `--https` | Enable HTTP/2 + TLS with auto-generated certs | `cli.ts` lines 1056-1058 | | `--cert ` | Custom TLS certificate (implies --https) | `cli.ts` lines 1061-1068 | | `--key ` | Custom TLS private key (implies --https) | `cli.ts` lines 1069-1078 | | `--no-tls` | Disable HTTPS (overrides PORTLESS_HTTPS) | `cli.ts` line 1056 | | `--foreground` | Run proxy in foreground | `cli.ts` line 1033 | | `--tld ` | Custom TLD instead of .localhost | `cli.ts` lines 1092-1105 | | `--app-port ` | Fixed port for the app | `cli.ts` lines 515-526, 587-589 | | `--force` | Override an existing route | `cli.ts` lines 585, 629 | | `--name ` | Override inferred app name | `cli.ts` lines 591-597 | | `--` | Stop flag parsing | `cli.ts` line 553 | **Environment variables** (from `cli.ts` lines 746-758, `cli-utils.ts`): | Variable | Description | Read location | |----------|-------------|---------------| | `PORTLESS_PORT` | Override default proxy port | `cli-utils.ts` lines 66-73 | | `PORTLESS_APP_PORT` | Fixed app port | `cli.ts` lines 528-537 | | `PORTLESS_HTTPS=1` | Always enable HTTPS | `cli-utils.ts` lines 199-202 | | `PORTLESS_TLD` | Custom TLD | `cli-utils.ts` lines 188-194 | | `PORTLESS_SYNC_HOSTS=1` | Auto-sync /etc/hosts | `cli.ts` lines 86-90 | | `PORTLESS_STATE_DIR` | Override state directory | `cli-utils.ts` line 86 | | `PORTLESS=0` | Bypass proxy entirely | `cli.ts` lines 1401-1404, 1424-1426 | | `PORT` (injected) | Ephemeral port for child | `cli.ts` line 480 | | `HOST` (injected) | Always `127.0.0.1` | `cli.ts` line 481 | | `PORTLESS_URL` (injected) | Public URL of the app | `cli.ts` line 482 | --- ### Summary **Portless has no tunnel support whatsoever.** It is purely a local reverse proxy. There are: - **Zero tunnel providers** integrated (no ngrok, Cloudflare Tunnel, bore, localtunnel, or any other) - **No tunnel abstraction layer** or common interface for tunnels - **No concept of exposing services to the public internet** - **No tunnel-related CLI flags or environment variables** The entire codebase is focused on local hostname-based reverse proxying on `127.0.0.1`. All routing happens through the `RouteInfo` -> `RouteStore` -> `createProxyServer` pipeline, where the proxy listens on a single port and routes based on the `Host` header to the appropriate local port. The DNS resolution layer relies on the browser's native `.localhost` handling or `/etc/hosts` entries for custom TLDs -- no DNS tunneling or external DNS is involved. If tunnels were to be added, the key integration points would be: 1. **`ProxyServerOptions` / `types.ts`** -- would need a tunnel configuration option 2. **`cli.ts` `handleProxy()`** (line 1007) -- would need tunnel start/stop logic alongside the proxy 3. **`runApp()` in `cli.ts`** (line 323) -- would need to expose the assigned port via a tunnel and report the tunnel URL 4. **New CLI flags** -- `--tunnel`, `--tunnel-provider`, etc. 5. **The `PORTLESS_URL` env var** (line 482) -- would need to be set to the tunnel URL instead of the local URL when a tunnel is active ``` ## Assistant ## Assistant Good, I have a solid picture now. Let me dig into the specific integration points more closely. ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/types.ts" } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/types.ts file 1: /** Route info used by the proxy server to map hostnames to ports. */ 2: export interface RouteInfo { 3: hostname: string; 4: port: number; 5: } 6: 7: export interface ProxyServerOptions { 8: /** Called on each request to get the current route table. */ 9: getRoutes: () => RouteInfo[]; 10: /** The port the proxy is listening on (used to build correct URLs). */ 11: proxyPort: number; 12: /** TLD suffix used for hostnames (default: "localhost"). */ 13: tld?: string; 14: /** Optional error logger; defaults to console.error. */ 15: onError?: (message: string) => void; 16: /** When provided, enables HTTP/2 over TLS (HTTPS). */ 17: tls?: { 18: cert: Buffer; 19: key: Buffer; 20: /** SNI callback for per-hostname certificate selection. */ 21: SNICallback?: ( 22: servername: string, 23: cb: (err: Error | null, ctx?: import("node:tls").SecureContext) => void 24: ) => void; 25: }; 26: } (End of file - total 26 lines) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 30, "offset": 470 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 470: 471: // Run the command 472: console.log( 473: chalk.gray( 474: `Running: PORT=${port} HOST=127.0.0.1 PORTLESS_URL=${finalUrl} ${commandArgs.join(" ")}\n` 475: ) 476: ); 477: 478: spawnCommand(commandArgs, { 479: env: { 480: ...process.env, 481: PORT: port.toString(), 482: HOST: "127.0.0.1", 483: PORTLESS_URL: finalUrl, 484: __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: `.${tld}`, 485: }, 486: onCleanup: () => { 487: try { 488: store.removeRoute(hostname); 489: } catch { 490: // Lock acquisition may fail during cleanup; non-fatal 491: } 492: }, 493: }); 494: } 495: 496: // --------------------------------------------------------------------------- 497: // Argument parsing 498: // --------------------------------------------------------------------------- 499: (Showing lines 470-499 of 1488. Use offset=500 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "limit": 60, "offset": 99 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts file 99: export function createProxyServer(options: ProxyServerOptions): ProxyServer { 100: const { 101: getRoutes, 102: proxyPort, 103: tld = "localhost", 104: onError = (msg: string) => console.error(msg), 105: tls, 106: } = options; 107: const tldSuffix = `.${tld}`; 108: 109: const isTls = !!tls; 110: 111: const handleRequest = (req: http.IncomingMessage, res: http.ServerResponse) => { 112: res.setHeader(PORTLESS_HEADER, "1"); 113: 114: const routes = getRoutes(); 115: const host = getRequestHost(req).split(":")[0]; 116: 117: if (!host) { 118: res.writeHead(400, { "Content-Type": "text/plain" }); 119: res.end("Missing Host header"); 120: return; 121: } 122: 123: const hops = parseInt(req.headers[PORTLESS_HOPS_HEADER] as string, 10) || 0; 124: if (hops >= MAX_PROXY_HOPS) { 125: onError( 126: `Loop detected for ${host}: request has passed through portless ${hops} times. ` + 127: `This usually means a backend is proxying back through portless without rewriting ` + 128: `the Host header. If you use Vite/webpack proxy, set changeOrigin: true.` 129: ); 130: res.writeHead(508, { "Content-Type": "text/html" }); 131: res.end( 132: renderPage( 133: 508, 134: "Loop Detected", 135: `

This request has passed through portless ${hops} times. This usually means a dev server (Vite, webpack, etc.) is proxying requests back through portless without rewriting the Host header.

Fix: add changeOrigin to your proxy config

proxy: {
136:   "/api": {
137:     target: "http://<backend>${escapeHtml(tldSuffix)}:<port>",
138:     changeOrigin: true,
139:   },
140: }
` 141: ) 142: ); 143: return; 144: } 145: 146: const route = findRoute(routes, host); 147: 148: if (!route) { 149: const safeHost = escapeHtml(host); 150: const strippedHost = host.endsWith(tldSuffix) ? host.slice(0, -tldSuffix.length) : host; 151: const safeSuggestion = escapeHtml(strippedHost); 152: const routesList = 153: routes.length > 0 154: ? `

Active apps

` 155: : '

No apps running.

'; 156: res.writeHead(404, { "Content-Type": "text/html" }); 157: res.end( 158: renderPage( (Showing lines 99-158 of 393. Use offset=159 to continue.) ``` ## Assistant ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 80, "offset": 323 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 323: async function runApp( 324: store: RouteStore, 325: proxyPort: number, 326: stateDir: string, 327: name: string, 328: commandArgs: string[], 329: tls: boolean, 330: tld: string, 331: force: boolean, 332: autoInfo?: { nameSource: string; prefix?: string; prefixSource?: string }, 333: desiredPort?: number 334: ) { 335: const hostname = parseHostname(name, tld); 336: 337: let envTld: string; 338: try { 339: envTld = getDefaultTld(); 340: } catch (err) { 341: console.error(chalk.red(`Error: ${(err as Error).message}`)); 342: process.exit(1); 343: } 344: if (envTld !== DEFAULT_TLD && envTld !== tld) { 345: console.warn( 346: chalk.yellow( 347: `Warning: PORTLESS_TLD=${envTld} but the running proxy uses .${tld}. Using .${tld}.` 348: ) 349: ); 350: } 351: 352: console.log(chalk.blue.bold(`\nportless\n`)); 353: console.log(chalk.gray(`-- ${hostname} (auto-resolves to 127.0.0.1)`)); 354: if (autoInfo) { 355: const baseName = autoInfo.prefix ? name.slice(autoInfo.prefix.length + 1) : name; 356: console.log(chalk.gray(`-- Name "${baseName}" (from ${autoInfo.nameSource})`)); 357: if (autoInfo.prefix) { 358: console.log(chalk.gray(`-- Prefix "${autoInfo.prefix}" (from ${autoInfo.prefixSource})`)); 359: } 360: } 361: 362: // Check if proxy is running, auto-start if possible 363: if (!(await isProxyRunning(proxyPort, tls))) { 364: const defaultPort = getDefaultPort(); 365: const needsSudo = defaultPort < PRIVILEGED_PORT_THRESHOLD; 366: const wantHttps = isHttpsEnvEnabled(); 367: 368: if (needsSudo) { 369: // Privileged port requires sudo -- must prompt interactively 370: if (!process.stdin.isTTY) { 371: console.error(chalk.red("Proxy is not running.")); 372: console.error(chalk.blue("Start the proxy first (requires sudo for this port):")); 373: console.error(chalk.cyan(" sudo portless proxy start -p 80")); 374: console.error(chalk.blue("Or use the default port (no sudo needed):")); 375: console.error(chalk.cyan(" portless proxy start")); 376: process.exit(1); 377: } 378: 379: const answer = await prompt(chalk.yellow("Proxy not running. Start it? [Y/n/skip] ")); 380: 381: if (answer === "n" || answer === "no") { 382: console.log(chalk.gray("Cancelled.")); 383: process.exit(0); 384: } 385: 386: if (answer === "s" || answer === "skip") { 387: console.log(chalk.gray("Skipping proxy, running command directly...\n")); 388: spawnCommand(commandArgs); 389: return; 390: } 391: 392: console.log(chalk.yellow("Starting proxy (requires sudo)...")); 393: const startArgs = [process.execPath, process.argv[1], "proxy", "start"]; 394: if (wantHttps) startArgs.push("--https"); 395: if (tld !== DEFAULT_TLD) startArgs.push("--tld", tld); 396: const result = spawnSync("sudo", startArgs, { 397: stdio: "inherit", 398: timeout: SUDO_SPAWN_TIMEOUT_MS, 399: }); 400: if (result.status !== 0) { 401: console.error(chalk.red("Failed to start proxy.")); 402: console.error(chalk.blue("Try starting it manually:")); (Showing lines 323-402 of 1488. Use offset=403 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 80, "offset": 700 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 700: portless proxy start --https # Start with HTTPS/2 (faster page loads) 701: portless myapp next dev # -> http://myapp.localhost:1355 702: portless myapp vite dev # -> http://myapp.localhost:1355 703: portless api.myapp pnpm start # -> http://api.myapp.localhost:1355 704: portless run next dev # -> http://.localhost:1355 705: portless run next dev # in worktree -> http://..localhost:1355 706: portless get backend # -> http://backend.localhost:1355 (for cross-service refs) 707: # Wildcard subdomains: tenant.myapp.localhost also routes to myapp 708: 709: ${chalk.bold("In package.json:")} 710: { 711: "scripts": { 712: "dev": "portless run next dev" 713: } 714: } 715: 716: ${chalk.bold("How it works:")} 717: 1. Start the proxy once (listens on port 1355 by default, no sudo needed) 718: 2. Run your apps - they auto-start the proxy and register automatically 719: (apps get a random port in the 4000-4999 range via PORT) 720: 3. Access via http://.localhost:1355 721: 4. .localhost domains auto-resolve to 127.0.0.1 722: 5. Frameworks that ignore PORT (Vite, Astro, React Router, Angular, 723: Expo, React Native) get --port and --host flags injected automatically 724: 725: ${chalk.bold("HTTP/2 + HTTPS:")} 726: Use --https for HTTP/2 multiplexing (faster dev server page loads). 727: On first use, portless generates a local CA and adds it to your 728: system trust store. No browser warnings. No sudo required on macOS. 729: 730: ${chalk.bold("Options:")} 731: run [--name ] Infer project name (or override with --name) 732: Adds worktree prefix in git worktrees 733: -p, --port Port for the proxy to listen on (default: 1355) 734: Ports < 1024 require sudo 735: --https Enable HTTP/2 + TLS with auto-generated certs 736: --cert Use a custom TLS certificate (implies --https) 737: --key Use a custom TLS private key (implies --https) 738: --no-tls Disable HTTPS (overrides PORTLESS_HTTPS) 739: --foreground Run proxy in foreground (for debugging) 740: --tld Use a custom TLD instead of .localhost (e.g. test, dev) 741: --app-port Use a fixed port for the app (skip auto-assignment) 742: --force Override an existing route registered by another process 743: --name Use as the app name (bypasses subcommand dispatch) 744: -- Stop flag parsing; everything after is passed to the child 745: 746: ${chalk.bold("Environment variables:")} 747: PORTLESS_PORT= Override the default proxy port (e.g. in .bashrc) 748: PORTLESS_APP_PORT= Use a fixed port for the app (same as --app-port) 749: PORTLESS_HTTPS=1 Always enable HTTPS (set in .bashrc / .zshrc) 750: PORTLESS_TLD= Use a custom TLD (e.g. test, dev; default: localhost) 751: PORTLESS_SYNC_HOSTS=1 Auto-sync /etc/hosts (auto-enabled for custom TLDs) 752: PORTLESS_STATE_DIR= Override the state directory 753: PORTLESS=0 Run command directly without proxy 754: 755: ${chalk.bold("Child process environment:")} 756: PORT Ephemeral port the child should listen on 757: HOST Always 127.0.0.1 758: PORTLESS_URL Public URL of the app (e.g. http://myapp.localhost:1355) 759: 760: ${chalk.bold("Safari / DNS:")} 761: .localhost subdomains auto-resolve in Chrome, Firefox, and Edge. 762: Safari relies on the system DNS resolver, which may not handle them. 763: Auto-syncs /etc/hosts for custom TLDs (e.g. --tld test). For .localhost, 764: set PORTLESS_SYNC_HOSTS=1 to enable. To manually sync: 765: ${chalk.cyan("sudo portless hosts sync")} 766: Clean up later with: 767: ${chalk.cyan("sudo portless hosts clean")} 768: 769: ${chalk.bold("Skip portless:")} 770: PORTLESS=0 pnpm dev # Runs command directly without proxy 771: 772: ${chalk.bold("Reserved names:")} 773: run, get, alias, hosts, list, trust, proxy are subcommands and cannot 774: be used as app names directly. Use "portless run" to infer the name, 775: or "portless --name " to force any name including reserved ones. 776: `); 777: process.exit(0); 778: } 779: (Showing lines 700-779 of 1488. Use offset=780 to continue.) ``` ## Assistant ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 70, "offset": 430 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 430: console.error(chalk.red("Proxy failed to start (timed out waiting for it to listen).")); 431: const logPath = path.join(stateDir, "proxy.log"); 432: console.error(chalk.blue("Try starting the proxy manually to see the error:")); 433: console.error(chalk.cyan(` ${needsSudo ? "sudo " : ""}portless proxy start`)); 434: if (fs.existsSync(logPath)) { 435: console.error(chalk.gray(`Logs: ${logPath}`)); 436: } 437: process.exit(1); 438: } 439: 440: // Update tls/URL for newly started proxy 441: tls = autoTls; 442: console.log(chalk.green("Proxy started in background")); 443: } else { 444: console.log(chalk.gray("-- Proxy is running")); 445: } 446: 447: const port = desiredPort ?? (await findFreePort()); 448: if (desiredPort) { 449: console.log(chalk.green(`-- Using port ${port} (fixed)`)); 450: } else { 451: console.log(chalk.green(`-- Using port ${port}`)); 452: } 453: 454: // Register route 455: try { 456: store.addRoute(hostname, port, process.pid, force); 457: } catch (err) { 458: if (err instanceof RouteConflictError) { 459: console.error(chalk.red(`Error: ${err.message}`)); 460: process.exit(1); 461: } 462: throw err; 463: } 464: 465: const finalUrl = formatUrl(hostname, proxyPort, tls); 466: console.log(chalk.cyan.bold(`\n -> ${finalUrl}\n`)); 467: 468: // Inject --port for frameworks that ignore the PORT env var (e.g. Vite) 469: injectFrameworkFlags(commandArgs, port); 470: 471: // Run the command 472: console.log( 473: chalk.gray( 474: `Running: PORT=${port} HOST=127.0.0.1 PORTLESS_URL=${finalUrl} ${commandArgs.join(" ")}\n` 475: ) 476: ); 477: 478: spawnCommand(commandArgs, { 479: env: { 480: ...process.env, 481: PORT: port.toString(), 482: HOST: "127.0.0.1", 483: PORTLESS_URL: finalUrl, 484: __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: `.${tld}`, 485: }, 486: onCleanup: () => { 487: try { 488: store.removeRoute(hostname); 489: } catch { 490: // Lock acquisition may fail during cleanup; non-fatal 491: } 492: }, 493: }); 494: } 495: 496: // --------------------------------------------------------------------------- 497: // Argument parsing 498: // --------------------------------------------------------------------------- 499: (Showing lines 430-499 of 1488. Use offset=500 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 80, "offset": 1000 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 1000: } else { 1001: console.error(chalk.red("Failed to update /etc/hosts (requires sudo).")); 1002: console.error(chalk.cyan(" sudo portless hosts sync")); 1003: process.exit(1); 1004: } 1005: } 1006: 1007: async function handleProxy(args: string[]): Promise { 1008: if (args[1] === "stop") { 1009: const { dir, port, tls } = await discoverState(); 1010: const store = new RouteStore(dir, { 1011: onWarning: (msg) => console.warn(chalk.yellow(msg)), 1012: }); 1013: await stopProxy(store, port, tls); 1014: return; 1015: } 1016: 1017: const isProxyHelp = args[1] === "--help" || args[1] === "-h"; 1018: if (isProxyHelp || args[1] !== "start") { 1019: console.log(` 1020: ${chalk.bold("portless proxy")} - Manage the portless proxy server. 1021: 1022: ${chalk.bold("Usage:")} 1023: ${chalk.cyan("portless proxy start")} Start the proxy (daemon) 1024: ${chalk.cyan("portless proxy start --https")} Start with HTTP/2 + TLS 1025: ${chalk.cyan("portless proxy start --foreground")} Start in foreground (for debugging) 1026: ${chalk.cyan("portless proxy start -p 80")} Start on port 80 (requires sudo) 1027: ${chalk.cyan("portless proxy start --tld test")} Use .test instead of .localhost 1028: ${chalk.cyan("portless proxy stop")} Stop the proxy 1029: `); 1030: process.exit(isProxyHelp || !args[1] ? 0 : 1); 1031: } 1032: 1033: const isForeground = args.includes("--foreground"); 1034: 1035: // Parse --port / -p flag 1036: let proxyPort = getDefaultPort(); 1037: let portFlagIndex = args.indexOf("--port"); 1038: if (portFlagIndex === -1) portFlagIndex = args.indexOf("-p"); 1039: if (portFlagIndex !== -1) { 1040: const portValue = args[portFlagIndex + 1]; 1041: if (!portValue || portValue.startsWith("-")) { 1042: console.error(chalk.red("Error: --port / -p requires a port number.")); 1043: console.error(chalk.blue("Usage:")); 1044: console.error(chalk.cyan(" portless proxy start -p 8080")); 1045: process.exit(1); 1046: } 1047: proxyPort = parseInt(portValue, 10); 1048: if (isNaN(proxyPort) || proxyPort < 1 || proxyPort > 65535) { 1049: console.error(chalk.red(`Error: Invalid port number: ${portValue}`)); 1050: console.error(chalk.blue("Port must be between 1 and 65535.")); 1051: process.exit(1); 1052: } 1053: } 1054: 1055: // Parse HTTPS / TLS flags 1056: const hasNoTls = args.includes("--no-tls"); 1057: const hasHttpsFlag = args.includes("--https"); 1058: const wantHttps = !hasNoTls && (hasHttpsFlag || isHttpsEnvEnabled()); 1059: 1060: // Parse optional --cert / --key for custom certificates 1061: let customCertPath: string | null = null; 1062: let customKeyPath: string | null = null; 1063: const certIdx = args.indexOf("--cert"); 1064: if (certIdx !== -1) { 1065: customCertPath = args[certIdx + 1] || null; 1066: if (!customCertPath || customCertPath.startsWith("-")) { 1067: console.error(chalk.red("Error: --cert requires a file path.")); 1068: process.exit(1); 1069: } 1070: } 1071: const keyIdx = args.indexOf("--key"); 1072: if (keyIdx !== -1) { 1073: customKeyPath = args[keyIdx + 1] || null; 1074: if (!customKeyPath || customKeyPath.startsWith("-")) { 1075: console.error(chalk.red("Error: --key requires a file path.")); 1076: process.exit(1); 1077: } 1078: } 1079: if ((customCertPath && !customKeyPath) || (!customCertPath && customKeyPath)) { (Showing lines 1000-1079 of 1488. Use offset=1080 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 100, "offset": 1080 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 1080: console.error(chalk.red("Error: --cert and --key must be used together.")); 1081: process.exit(1); 1082: } 1083: 1084: // Parse --tld flag 1085: let tld: string; 1086: try { 1087: tld = getDefaultTld(); 1088: } catch (err) { 1089: console.error(chalk.red(`Error: ${(err as Error).message}`)); 1090: process.exit(1); 1091: } 1092: const tldIdx = args.indexOf("--tld"); 1093: if (tldIdx !== -1) { 1094: const tldValue = args[tldIdx + 1]; 1095: if (!tldValue || tldValue.startsWith("-")) { 1096: console.error(chalk.red("Error: --tld requires a TLD value (e.g. test, localhost).")); 1097: process.exit(1); 1098: } 1099: tld = tldValue.trim().toLowerCase(); 1100: const tldErr = validateTld(tld); 1101: if (tldErr) { 1102: console.error(chalk.red(`Error: ${tldErr}`)); 1103: process.exit(1); 1104: } 1105: } 1106: const riskyReason = RISKY_TLDS.get(tld); 1107: if (riskyReason) { 1108: console.warn(chalk.yellow(`Warning: .${tld} -- ${riskyReason}`)); 1109: } 1110: 1111: const syncDisabled = 1112: process.env.PORTLESS_SYNC_HOSTS === "0" || process.env.PORTLESS_SYNC_HOSTS === "false"; 1113: if (tld !== DEFAULT_TLD && syncDisabled) { 1114: console.warn( 1115: chalk.yellow(`Warning: .${tld} domains require /etc/hosts entries to resolve to 127.0.0.1.`) 1116: ); 1117: console.warn(chalk.yellow("Hosts sync is disabled. To add entries manually, run:")); 1118: console.warn(chalk.cyan(" sudo portless hosts sync")); 1119: } 1120: 1121: // Custom cert/key implies HTTPS 1122: const useHttps = wantHttps || !!(customCertPath && customKeyPath); 1123: 1124: // Resolve state directory based on the port 1125: const stateDir = resolveStateDir(proxyPort); 1126: const store = new RouteStore(stateDir, { 1127: onWarning: (msg) => console.warn(chalk.yellow(msg)), 1128: }); 1129: 1130: // Check if already running. Plain HTTP check detects both TLS and non-TLS 1131: // proxies because the TLS-enabled proxy accepts plain HTTP via byte-peeking. 1132: if (await isProxyRunning(proxyPort)) { 1133: if (isForeground) { 1134: return; 1135: } 1136: const needsSudo = proxyPort < PRIVILEGED_PORT_THRESHOLD; 1137: const sudoPrefix = needsSudo ? "sudo " : ""; 1138: const portFlag = proxyPort !== getDefaultPort() ? ` -p ${proxyPort}` : ""; 1139: console.log(chalk.yellow(`Proxy is already running on port ${proxyPort}.`)); 1140: console.log( 1141: chalk.blue( 1142: `To restart: ${sudoPrefix}portless proxy stop${portFlag} && ${sudoPrefix}portless proxy start${portFlag}` 1143: ) 1144: ); 1145: return; 1146: } 1147: 1148: // Check if running as root (only required for privileged ports) 1149: if (proxyPort < PRIVILEGED_PORT_THRESHOLD && (process.getuid?.() ?? -1) !== 0) { 1150: console.error(chalk.red(`Error: Port ${proxyPort} requires sudo.`)); 1151: console.error(chalk.blue("Either run with sudo:")); 1152: console.error(chalk.cyan(" sudo portless proxy start -p 80")); 1153: console.error(chalk.blue("Or use the default port (no sudo needed):")); 1154: console.error(chalk.cyan(" portless proxy start")); 1155: process.exit(1); 1156: } 1157: 1158: // Prepare TLS options if HTTPS is requested 1159: let tlsOptions: import("./types.js").ProxyServerOptions["tls"]; 1160: if (useHttps) { 1161: store.ensureDir(); 1162: if (customCertPath && customKeyPath) { 1163: try { 1164: const cert = fs.readFileSync(customCertPath); 1165: const key = fs.readFileSync(customKeyPath); 1166: 1167: const certStr = cert.toString("utf-8"); 1168: const keyStr = key.toString("utf-8"); 1169: if (!certStr.includes("-----BEGIN CERTIFICATE-----")) { 1170: console.error(chalk.red(`Error: ${customCertPath} is not a valid PEM certificate.`)); 1171: console.error(chalk.gray("Expected a file starting with -----BEGIN CERTIFICATE-----")); 1172: process.exit(1); 1173: } 1174: if (!keyStr.match(/-----BEGIN [\w\s]*PRIVATE KEY-----/)) { 1175: console.error(chalk.red(`Error: ${customKeyPath} is not a valid PEM private key.`)); 1176: console.error(chalk.gray("Expected a file starting with -----BEGIN ...PRIVATE KEY-----")); 1177: process.exit(1); 1178: } 1179: (Showing lines 1080-1179 of 1488. Use offset=1180 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 60, "offset": 58 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 58: function startProxyServer( 59: store: RouteStore, 60: proxyPort: number, 61: tld: string, 62: tlsOptions?: { cert: Buffer; key: Buffer } 63: ): void { 64: store.ensureDir(); 65: 66: const isTls = !!tlsOptions; 67: 68: // Create empty routes file if it doesn't exist 69: const routesPath = store.getRoutesPath(); 70: if (!fs.existsSync(routesPath)) { 71: fs.writeFileSync(routesPath, "[]", { mode: FILE_MODE }); 72: } 73: try { 74: fs.chmodSync(routesPath, FILE_MODE); 75: } catch { 76: // May fail if file is owned by another user; non-fatal 77: } 78: fixOwnership(routesPath); 79: 80: // Cache routes in memory and reload on file change (debounced) 81: let cachedRoutes = store.loadRoutes(); 82: let debounceTimer: ReturnType | null = null; 83: let watcher: fs.FSWatcher | null = null; 84: let pollingInterval: ReturnType | null = null; 85: 86: const syncVal = process.env.PORTLESS_SYNC_HOSTS; 87: const autoSyncHosts = 88: syncVal === "1" || 89: syncVal === "true" || 90: (tld !== DEFAULT_TLD && syncVal !== "0" && syncVal !== "false"); 91: 92: const reloadRoutes = () => { 93: try { 94: cachedRoutes = store.loadRoutes(); 95: if (autoSyncHosts) { 96: syncHostsFile(cachedRoutes.map((r) => r.hostname)); 97: } 98: } catch { 99: // File may be mid-write; keep existing cached routes 100: } 101: }; 102: 103: try { 104: watcher = fs.watch(routesPath, () => { 105: if (debounceTimer) clearTimeout(debounceTimer); 106: debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS); 107: }); 108: } catch { 109: // fs.watch may not be supported; fall back to periodic polling 110: console.warn(chalk.yellow("fs.watch unavailable; falling back to polling for route changes")); 111: pollingInterval = setInterval(reloadRoutes, POLL_INTERVAL_MS); 112: } 113: 114: if (autoSyncHosts) { 115: syncHostsFile(cachedRoutes.map((r) => r.hostname)); 116: } 117: (Showing lines 58-117 of 1488. Use offset=118 to continue.) ``` ## Assistant ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 80, "offset": 118 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 118: const server = createProxyServer({ 119: getRoutes: () => cachedRoutes, 120: proxyPort, 121: tld, 122: onError: (msg) => console.error(chalk.red(msg)), 123: tls: tlsOptions, 124: }); 125: 126: server.on("error", (err: NodeJS.ErrnoException) => { 127: if (err.code === "EADDRINUSE") { 128: console.error(chalk.red(`Port ${proxyPort} is already in use.`)); 129: console.error(chalk.blue("Stop the existing proxy first:")); 130: console.error(chalk.cyan(" portless proxy stop")); 131: console.error(chalk.blue("Or check what is using the port:")); 132: console.error(chalk.cyan(` lsof -ti tcp:${proxyPort}`)); 133: } else if (err.code === "EACCES") { 134: console.error(chalk.red(`Permission denied for port ${proxyPort}.`)); 135: console.error(chalk.blue("Either run with sudo:")); 136: console.error(chalk.cyan(" sudo portless proxy start -p 80")); 137: console.error(chalk.blue("Or use a non-privileged port (no sudo needed):")); 138: console.error(chalk.cyan(" portless proxy start")); 139: } else { 140: console.error(chalk.red(`Proxy error: ${err.message}`)); 141: } 142: process.exit(1); 143: }); 144: 145: server.listen(proxyPort, () => { 146: // Save PID and port once the server is actually listening 147: fs.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE }); 148: fs.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE }); 149: writeTlsMarker(store.dir, isTls); 150: writeTldFile(store.dir, tld); 151: fixOwnership(store.dir, store.pidPath, store.portFilePath); 152: const proto = isTls ? "HTTPS/2" : "HTTP"; 153: const tldLabel = tld !== DEFAULT_TLD ? ` (TLD: .${tld})` : ""; 154: console.log(chalk.green(`${proto} proxy listening on port ${proxyPort}${tldLabel}`)); 155: }); 156: 157: // Cleanup on exit 158: let exiting = false; 159: const cleanup = () => { 160: if (exiting) return; 161: exiting = true; 162: if (debounceTimer) clearTimeout(debounceTimer); 163: if (pollingInterval) clearInterval(pollingInterval); 164: if (watcher) { 165: watcher.close(); 166: } 167: try { 168: fs.unlinkSync(store.pidPath); 169: } catch { 170: // PID file may already be removed; non-fatal 171: } 172: try { 173: fs.unlinkSync(store.portFilePath); 174: } catch { 175: // Port file may already be removed; non-fatal 176: } 177: writeTlsMarker(store.dir, false); 178: writeTldFile(store.dir, DEFAULT_TLD); 179: if (autoSyncHosts) cleanHostsFile(); 180: server.close(() => process.exit(0)); 181: // Force exit after a short timeout in case connections don't drain 182: setTimeout(() => process.exit(0), EXIT_TIMEOUT_MS).unref(); 183: }; 184: 185: process.on("SIGINT", cleanup); 186: process.on("SIGTERM", cleanup); 187: 188: console.log(chalk.cyan("\nProxy is running. Press Ctrl+C to stop.\n")); 189: console.log(chalk.gray(`Routes file: ${store.getRoutesPath()}`)); 190: } 191: 192: // --------------------------------------------------------------------------- 193: // Commands 194: // --------------------------------------------------------------------------- 195: 196: async function stopProxy(store: RouteStore, proxyPort: number, _tls: boolean): Promise { 197: const pidPath = store.pidPath; (Showing lines 118-197 of 1488. Use offset=198 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/index.ts" } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/index.ts file 1: export * from "./types.js"; 2: export * from "./proxy.js"; 3: export * from "./routes.js"; 4: export * from "./utils.js"; 5: export * from "./hosts.js"; (End of file - total 5 lines) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/package.json" } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/package.json file 1: { 2: "name": "portless", 3: "version": "0.6.0", 4: "description": "Replace port numbers with stable, named .localhost URLs. For humans and agents.", 5: "type": "module", 6: "main": "./dist/index.js", 7: "types": "./dist/index.d.ts", 8: "exports": { 9: ".": { 10: "import": "./dist/index.js", 11: "types": "./dist/index.d.ts" 12: } 13: }, 14: "bin": { 15: "portless": "./dist/cli.js" 16: }, 17: "files": [ 18: "dist" 19: ], 20: "engines": { 21: "node": ">=20" 22: }, 23: "os": [ 24: "darwin", 25: "linux" 26: ], 27: "scripts": { 28: "build": "tsup", 29: "dev": "tsup --watch", 30: "lint": "eslint src/", 31: "lint:fix": "eslint src/ --fix", 32: "prepublishOnly": "cp ../../README.md . && pnpm build", 33: "test": "vitest run", 34: "test:coverage": "vitest run --coverage", 35: "test:watch": "vitest", 36: "typecheck": "tsc --noEmit" 37: }, 38: "keywords": [ 39: "local", 40: "development", 41: "proxy", 42: "localhost" 43: ], 44: "author": "Vercel Labs", 45: "license": "Apache-2.0", 46: "repository": { 47: "type": "git", 48: "url": "https://github.com/vercel-labs/portless.git" 49: }, 50: "homepage": "https://port1355.dev", 51: "bugs": { 52: "url": "https://github.com/vercel-labs/portless/issues" 53: }, 54: "dependencies": { 55: "chalk": "^5.3.0" 56: }, 57: "devDependencies": { 58: "@types/node": "^20.11.0", 59: "@vitest/coverage-v8": "^4.0.18", 60: "eslint": "^9.39.2", 61: "tsup": "^8.0.1", 62: "typescript": "^5.3.3", 63: "vitest": "^4.0.18" 64: } 65: } (End of file - total 65 lines) ``` ## Assistant ## Assistant Now I have a complete picture. Here's my analysis and proposed plan. --- ## Analysis **The core problem**: Tunnel providers (ngrok, Cloudflare Tunnel) create a public URL (e.g., `abc123.ngrok-free.app`) and forward traffic to a local port. When forwarded to portless's proxy port (1355), the request arrives with the tunnel's `Host` header, not the `.localhost` hostname portless expects. `findRoute()` at `proxy.ts:76-83` finds no match, and the user gets a 404. **Current code path:** 1. Request arrives at proxy with `Host: abc123.ngrok-free.app` 2. `findRoute()` looks for exact match or wildcard subdomain match in registered `.localhost` routes 3. No match -- returns 404 There's zero tunnel infrastructure in the codebase today. The only runtime dependency is `chalk`. --- ## Proposed plan (3 phases, each independently shippable) ### Phase 1: Default-route fallback (minimal, solves the 80% case) When there's exactly one registered route and the incoming `Host` doesn't match any route, fall back to that single route. This covers the common "I'm developing one app and want to tunnel it" scenario. **Changes:** - `proxy.ts:findRoute()` -- add a fallback: if no match and `routes.length === 1`, return `routes[0]` - Optionally, gate this behind a `--tunnel-passthrough` flag on `portless proxy start` or a `PORTLESS_TUNNEL_PASSTHROUGH=1` env var (to avoid surprising behavior) - No new dependencies, no new files **Trade-offs:** - Only works when one app is registered (multi-app needs Phase 2) - The child app still gets `PORTLESS_URL=http://myapp.localhost:1355`, not the tunnel URL (no way to know it) - Very low risk, ~20 lines of code ### Phase 2: Tunnel hostname aliasing (`portless alias`) Allow mapping external hostnames to portless routes so multi-app tunneling works. **Changes:** - New `aliases.json` in state dir (or extend `routes.json` with an `aliases` field) - `routes.ts` -- `RouteStore` gains `addAlias(externalHostname, portlessName)` / `removeAlias()` - `proxy.ts:findRoute()` -- check aliases before returning 404 - `cli.ts` -- new `portless alias ` and `portless alias remove ` commands - Update help text, README, SKILL.md **Example workflow:** ``` portless myapp next dev # -> http://myapp.localhost:1355 ngrok http 1355 # starts tunnel portless alias myapp abc123.ngrok-free.app # teach proxy about the tunnel hostname # Now abc123.ngrok-free.app routes to myapp's port ``` **Trade-offs:** - Works with multi-app setups - Manual step required (user must run `portless alias` after starting the tunnel) - ngrok free tier generates random URLs on each restart, so alias must be re-set ### Phase 3: Managed tunnel integration (`--tunnel`) Portless spawns and manages the tunnel process, auto-discovers the tunnel URL, and exposes it via env vars. **Changes:** - New file: `tunnel.ts` -- tunnel provider abstraction + implementations ```ts interface TunnelProvider { name: string; /** Check if the tunnel CLI binary is installed */ isAvailable(): Promise; /** Start a tunnel to the given local port, return the public URL */ start(localPort: number): Promise<{ url: string; process: ChildProcess }>; } ``` - Providers to implement: - **ngrok**: spawn `ngrok http `, hit the local ngrok API (`http://127.0.0.1:4040/api/tunnels`) to get the public URL - **cloudflare**: spawn `cloudflared tunnel --url http://localhost:`, parse URL from stderr output - `cli.ts` -- new `--tunnel [provider]` flag on `portless ` - On app start: 1. Start app + register route as usual 2. Start tunnel pointing at the proxy port 3. Auto-register alias for the tunnel hostname 4. Set `PORTLESS_TUNNEL_URL` env var on the child process (alongside `PORTLESS_URL`) 5. On exit, kill tunnel process + remove alias - Update help text, README, SKILL.md **Example workflow:** ``` portless myapp --tunnel ngrok next dev # Output: # -> http://myapp.localhost:1355 # -> https://abc123.ngrok-free.app (tunnel) # Child process gets: # PORT=4123 HOST=127.0.0.1 # PORTLESS_URL=http://myapp.localhost:1355 # PORTLESS_TUNNEL_URL=https://abc123.ngrok-free.app ``` **Trade-offs:** - Best UX -- one command does everything - Requires ngrok/cloudflared to be installed (portless would check and give a clear error if not) - More complex (process management, URL parsing, provider-specific quirks) - Could add ngrok/cloudflare as optional peer dependencies or just shell out --- ## Open questions for you ## Assistant ### Tool: question **Args:** ```json { "questions": [ { "header": "Scope", "options": [ { "description": "Default-route fallback. Minimal change, solves single-app tunneling immediately. ~20 lines.", "label": "Phase 1 only (Recommended)" }, { "description": "Fallback + alias command. Covers multi-app tunneling too.", "label": "Phase 1 + Phase 2" }, { "description": "Full tunnel integration including managed tunnel spawning. Biggest scope.", "label": "All three phases" } ], "question": "Which phase(s) do you want to tackle now?" }, { "header": "Fallback behavior", "options": [ { "description": "If only one route exists, unmatched hosts route to it. Simple, no config needed.", "label": "Always-on (Recommended)" }, { "description": "Requires PORTLESS_TUNNEL_PASSTHROUGH=1. Safer but adds friction.", "label": "Opt-in via env var" } ], "question": "For Phase 1, should the fallback be opt-in (flag/env var) or always-on?" }, { "header": "Tunnel target", "options": [ { "description": "Tunnel -> portless proxy -> app. Preserves portless features (HTTPS, multi-app routing, etc.).", "label": "Proxy port (Recommended)" }, { "description": "Tunnel -> app. Simpler but bypasses portless proxy entirely.", "label": "App port directly" } ], "question": "Should the tunnel point at the proxy port or directly at the app port?" } ] } ``` ## Assistant **Result** (success): ``` User has answered your questions: "Which phase(s) do you want to tackle now?"="All three phases", "For Phase 1, should the fallback be opt-in (flag/env var) or always-on?"="Always-on (Recommended)", "Should the tunnel point at the proxy port or directly at the app port?"="Proxy port (Recommended)". You can now continue with the user's answers in mind. ``` ## Assistant ## Assistant Great, all three phases it is. Let me finalize the detailed implementation plan. ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "pending" }, { "content": "Phase 2: Tunnel hostname aliasing (portless alias command)", "priority": "high", "status": "pending" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "pending" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "pending" }, { "content": "Add tests for all three phases", "priority": "high", "status": "pending" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "status": "pending", "priority": "high" }, { "content": "Phase 2: Tunnel hostname aliasing (portless alias command)", "status": "pending", "priority": "high" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "status": "pending", "priority": "medium" }, { "content": "Update docs: README.md, SKILL.md, --help output", "status": "pending", "priority": "high" }, { "content": "Add tests for all three phases", "status": "pending", "priority": "high" } ] ``` ## Assistant Here's the full implementation plan: --- ## Phase 1: Default-route fallback **Goal**: When a request arrives with a non-portless `Host` header and exactly one app is registered, route to it automatically. **File: `proxy.ts`** -- modify `findRoute()` (line 76): ```ts // Current: function findRoute(routes, host) { return routes.find(r => r.hostname === host) || routes.find(r => host.endsWith("." + r.hostname)); } // New: add tldSuffix param + tunnel fallback function findRoute(routes, host, tldSuffix) { const exact = routes.find(r => r.hostname === host); if (exact) return exact; const wildcard = routes.find(r => host.endsWith("." + r.hostname)); if (wildcard) return wildcard; // Tunnel passthrough: if host is NOT a portless hostname // (e.g. abc123.ngrok-free.app) and there's exactly one route, // assume it's a tunnel forwarding to us. const isPortlessHost = host.endsWith(tldSuffix) || host === tldSuffix.slice(1); if (!isPortlessHost && routes.length === 1) { return routes[0]; } return undefined; } ``` This means: - `myapp.localhost` -> normal routing - `unknown.localhost` -> 404 with "active apps" page (existing behavior) - `abc123.ngrok-free.app` -> falls back to the single registered app - Multiple apps registered + unknown host -> 404 (requires Phase 2 alias) Thread `tldSuffix` (already available as a local in `createProxyServer`) into the two `findRoute()` call sites at lines 146 and ~280 (WebSocket handler). **~15 lines changed**, zero new dependencies. --- ## Phase 2: Tunnel hostname aliasing **Goal**: Map external hostnames to portless routes so multi-app tunneling works. ### New: `aliases.json` in state dir ```json { "abc123.ngrok-free.app": "myapp.localhost", "mysite.trycloudflare.com": "api.myapp.localhost" } ``` ### File: `routes.ts` -- extend `RouteStore` Add methods: - `addAlias(externalHostname: string, portlessHostname: string)` -- writes to aliases.json with file locking - `removeAlias(externalHostname: string)` -- removes entry - `removeAliasesForRoute(portlessHostname: string)` -- removes all aliases pointing at a route - `loadAliases(): Record` -- reads aliases.json ### File: `proxy.ts` -- extend route resolution ```ts // Add aliases parameter to createProxyServer options export interface ProxyServerOptions { // ... existing fields ... getAliases?: () => Record; // NEW } // In findRoute, check aliases before tunnel fallback: function findRoute(routes, host, tldSuffix, aliases) { // 1. Exact match // 2. Wildcard subdomain match // 3. Alias lookup: aliases["abc123.ngrok-free.app"] -> "myapp.localhost" -> find that route // 4. Tunnel fallback (Phase 1) } ``` ### File: `cli.ts` -- new `portless alias` command ``` portless alias Map external hostname to a portless app portless alias remove Remove a hostname alias portless alias list Show all aliases ``` Example: `portless alias myapp abc123.ngrok-free.app` ### File: `cli.ts` -- wire aliases into proxy startup In `startProxyServer()`, load and cache aliases alongside routes, watch `aliases.json` for changes. --- ## Phase 3: Managed tunnel integration **Goal**: `portless myapp --tunnel ngrok next dev` handles everything. ### New file: `tunnel.ts` ```ts export interface TunnelProvider { name: string; /** Check if the CLI binary is installed */ isAvailable(): Promise; /** Start tunnel, return public URL + child process handle */ start(localPort: number): Promise; } export interface TunnelInstance { url: string; process: ChildProcess; stop(): Promise; } ``` **ngrok provider:** - Availability check: `ngrok version` (exit code 0) - Start: `ngrok http --log=stdout --log-format=json` - URL discovery: poll `http://127.0.0.1:4040/api/tunnels` (ngrok's local API) - Stop: kill process, which closes the tunnel **cloudflare provider:** - Availability check: `cloudflared version` (exit code 0) - Start: `cloudflared tunnel --url http://localhost:` - URL discovery: parse `*.trycloudflare.com` URL from stderr output - Stop: kill process ### File: `cli.ts` -- new `--tunnel` flag ``` --tunnel Start a tunnel (ngrok, cloudflare) ``` New env var: `PORTLESS_TUNNEL=ngrok` (alternative to flag). ### File: `cli.ts` -- `runApp()` changes After registering the route and before spawning the child: 1. Start the tunnel provider pointing at `proxyPort` 2. Wait for the tunnel URL (with timeout + error handling) 3. Auto-register alias: `store.addAlias(tunnelHostname, hostname)` 4. Print tunnel URL alongside local URL 5. Set `PORTLESS_TUNNEL_URL` on child env 6. On cleanup: stop tunnel + remove alias New child process env vars: ``` PORTLESS_TUNNEL_URL=https://abc123.ngrok-free.app ``` ### End-user experience ``` $ portless myapp --tunnel ngrok next dev portless -- myapp.localhost (auto-resolves to 127.0.0.1) -- Name "myapp" (from package.json) -- Proxy is running -- Using port 4123 -- Starting ngrok tunnel... -> http://myapp.localhost:1355 (local) -> https://abc123.ngrok-free.app (tunnel) Running: PORT=4123 HOST=127.0.0.1 PORTLESS_URL=http://myapp.localhost:1355 PORTLESS_TUNNEL_URL=https://abc123.ngrok-free.app next dev ``` --- ## Files touched (summary) | File | Phase | Changes | |------|-------|---------| | `proxy.ts` | 1, 2 | `findRoute()` gains fallback + alias lookup | | `types.ts` | 2 | `ProxyServerOptions` gains `getAliases` | | `routes.ts` | 2 | `RouteStore` gains alias methods | | `tunnel.ts` | 3 | New file: provider abstraction + ngrok/cloudflare impls | | `cli.ts` | 1, 2, 3 | Wire everything up, new commands/flags, help text | | `index.ts` | 3 | Export `tunnel.ts` | | `README.md` | 1, 2, 3 | Document tunnel features | | `skills/portless/SKILL.md` | 1, 2, 3 | Agent skill updates | | Tests | 1, 2, 3 | Unit tests for each phase | --- Want me to start implementing? ## User lets create a feature branch and get to it ## Assistant ## Assistant ### Tool: bash **Args:** ```json { "command": "git checkout -b feat/tunnel-support", "description": "Create feature branch for tunnel support" } ``` ## Assistant **Result** (success): ``` Switched to a new branch 'feat/tunnel-support' ``` ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "in_progress" }, { "content": "Phase 2: Tunnel hostname aliasing (portless alias command)", "priority": "high", "status": "pending" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "pending" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "pending" }, { "content": "Add tests for all three phases", "priority": "high", "status": "pending" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "in_progress" }, { "content": "Phase 2: Tunnel hostname aliasing (portless alias command)", "priority": "high", "status": "pending" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "pending" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "pending" }, { "content": "Add tests for all three phases", "priority": "high", "status": "pending" } ] ``` ## Assistant Starting with Phase 1. Let me read the exact code I need to modify. ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "limit": 100, "offset": 60 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts file 60: */ 61: const PORTLESS_HOPS_HEADER = "x-portless-hops"; 62: 63: /** 64: * Maximum number of times a request may pass through the portless proxy 65: * before it is rejected as a loop. Two hops is normal when a frontend 66: * proxies API calls to a separate portless-managed backend; five gives 67: * comfortable headroom for multi-tier setups while catching loops quickly. 68: */ 69: const MAX_PROXY_HOPS = 5; 70: 71: /** 72: * Find the route matching a given host. Matches exact hostname first, then 73: * falls back to wildcard subdomain matching (e.g. tenant.myapp.localhost 74: * matches a route registered for myapp.localhost). 75: */ 76: function findRoute( 77: routes: { hostname: string; port: number }[], 78: host: string 79: ): { hostname: string; port: number } | undefined { 80: return ( 81: routes.find((r) => r.hostname === host) || routes.find((r) => host.endsWith("." + r.hostname)) 82: ); 83: } 84: 85: /** Server type returned by createProxyServer (plain HTTP/1.1 or net.Server TLS wrapper). */ 86: export type ProxyServer = http.Server | net.Server; 87: 88: /** 89: * Create an HTTP proxy server that routes requests based on the Host header. 90: * 91: * Uses Node's built-in http module for proxying (no external dependencies). 92: * The `getRoutes` callback is invoked on every request so callers can provide 93: * either a static list or a live-updating one. 94: * 95: * When `tls` is provided, creates an HTTP/2 secure server with HTTP/1.1 96: * fallback (`allowHTTP1: true`). This enables HTTP/2 multiplexing for 97: * browsers while keeping WebSocket upgrades working over HTTP/1.1. 98: */ 99: export function createProxyServer(options: ProxyServerOptions): ProxyServer { 100: const { 101: getRoutes, 102: proxyPort, 103: tld = "localhost", 104: onError = (msg: string) => console.error(msg), 105: tls, 106: } = options; 107: const tldSuffix = `.${tld}`; 108: 109: const isTls = !!tls; 110: 111: const handleRequest = (req: http.IncomingMessage, res: http.ServerResponse) => { 112: res.setHeader(PORTLESS_HEADER, "1"); 113: 114: const routes = getRoutes(); 115: const host = getRequestHost(req).split(":")[0]; 116: 117: if (!host) { 118: res.writeHead(400, { "Content-Type": "text/plain" }); 119: res.end("Missing Host header"); 120: return; 121: } 122: 123: const hops = parseInt(req.headers[PORTLESS_HOPS_HEADER] as string, 10) || 0; 124: if (hops >= MAX_PROXY_HOPS) { 125: onError( 126: `Loop detected for ${host}: request has passed through portless ${hops} times. ` + 127: `This usually means a backend is proxying back through portless without rewriting ` + 128: `the Host header. If you use Vite/webpack proxy, set changeOrigin: true.` 129: ); 130: res.writeHead(508, { "Content-Type": "text/html" }); 131: res.end( 132: renderPage( 133: 508, 134: "Loop Detected", 135: `

This request has passed through portless ${hops} times. This usually means a dev server (Vite, webpack, etc.) is proxying requests back through portless without rewriting the Host header.

Fix: add changeOrigin to your proxy config

proxy: {
136:   "/api": {
137:     target: "http://<backend>${escapeHtml(tldSuffix)}:<port>",
138:     changeOrigin: true,
139:   },
140: }
` 141: ) 142: ); 143: return; 144: } 145: 146: const route = findRoute(routes, host); 147: 148: if (!route) { 149: const safeHost = escapeHtml(host); 150: const strippedHost = host.endsWith(tldSuffix) ? host.slice(0, -tldSuffix.length) : host; 151: const safeSuggestion = escapeHtml(strippedHost); 152: const routesList = 153: routes.length > 0 154: ? `

Active apps

` 155: : '

No apps running.

'; 156: res.writeHead(404, { "Content-Type": "text/html" }); 157: res.end( 158: renderPage( 159: 404, (Showing lines 60-159 of 393. Use offset=160 to continue.) ``` ## Assistant Now let me see the WebSocket handler where `findRoute` is also called: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "limit": 100, "offset": 240 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts file 240: 241: const handleUpgrade = (req: http.IncomingMessage, socket: net.Socket, head: Buffer) => { 242: socket.on("error", () => socket.destroy()); 243: 244: const hops = parseInt(req.headers[PORTLESS_HOPS_HEADER] as string, 10) || 0; 245: if (hops >= MAX_PROXY_HOPS) { 246: const host = getRequestHost(req).split(":")[0]; 247: onError( 248: `WebSocket loop detected for ${host}: request has passed through portless ${hops} times. ` + 249: `Set changeOrigin: true in your proxy config.` 250: ); 251: socket.end( 252: "HTTP/1.1 508 Loop Detected\r\n" + 253: "Content-Type: text/plain\r\n" + 254: "\r\n" + 255: "Loop Detected: request has passed through portless too many times.\n" + 256: "Add changeOrigin: true to your dev server proxy config.\n" 257: ); 258: return; 259: } 260: 261: const routes = getRoutes(); 262: const host = getRequestHost(req).split(":")[0]; 263: const route = findRoute(routes, host); 264: 265: if (!route) { 266: socket.destroy(); 267: return; 268: } 269: 270: const forwardedHeaders = buildForwardedHeaders(req, isTls); 271: const proxyReqHeaders: http.OutgoingHttpHeaders = { ...req.headers }; 272: for (const [key, value] of Object.entries(forwardedHeaders)) { 273: proxyReqHeaders[key] = value; 274: } 275: proxyReqHeaders[PORTLESS_HOPS_HEADER] = String(hops + 1); 276: // Remove HTTP/2 pseudo-headers before forwarding to HTTP/1.1 backend 277: for (const key of Object.keys(proxyReqHeaders)) { 278: if (key.startsWith(":")) { 279: delete proxyReqHeaders[key]; 280: } 281: } 282: 283: const proxyReq = http.request({ 284: hostname: "127.0.0.1", 285: port: route.port, 286: path: req.url, 287: method: req.method, 288: headers: proxyReqHeaders, 289: }); 290: 291: proxyReq.on("upgrade", (proxyRes, proxySocket, proxyHead) => { 292: // Forward the backend's actual 101 response including Sec-WebSocket-Accept, 293: // subprotocol negotiation, and extension headers. 294: let response = `HTTP/1.1 101 Switching Protocols\r\n`; 295: for (let i = 0; i < proxyRes.rawHeaders.length; i += 2) { 296: response += `${proxyRes.rawHeaders[i]}: ${proxyRes.rawHeaders[i + 1]}\r\n`; 297: } 298: response += "\r\n"; 299: socket.write(response); 300: 301: if (proxyHead.length > 0) { 302: socket.write(proxyHead); 303: } 304: proxySocket.pipe(socket); 305: socket.pipe(proxySocket); 306: 307: proxySocket.on("error", () => socket.destroy()); 308: socket.on("error", () => proxySocket.destroy()); 309: }); 310: 311: proxyReq.on("error", (err) => { 312: onError(`WebSocket proxy error for ${getRequestHost(req)}: ${err.message}`); 313: socket.destroy(); 314: }); 315: 316: proxyReq.on("response", (res) => { 317: // The backend responded with a normal HTTP response instead of upgrading. 318: // Forward the rejection to the client. 319: if (!socket.destroyed) { 320: let response = `HTTP/1.1 ${res.statusCode} ${res.statusMessage}\r\n`; 321: for (let i = 0; i < res.rawHeaders.length; i += 2) { 322: response += `${res.rawHeaders[i]}: ${res.rawHeaders[i + 1]}\r\n`; 323: } 324: response += "\r\n"; 325: socket.write(response); 326: res.on("error", () => socket.destroy()); 327: res.pipe(socket); 328: } 329: }); 330: 331: if (head.length > 0) { 332: proxyReq.write(head); 333: } 334: proxyReq.end(); 335: }; 336: 337: if (tls) { 338: const h2Server = http2.createSecureServer({ 339: cert: tls.cert, (Showing lines 240-339 of 393. Use offset=340 to continue.) ``` ## Assistant Good. Now I have both call sites. Let me implement Phase 1: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "newString": "/**\n * Find the route matching a given host. Matches exact hostname first, then\n * falls back to wildcard subdomain matching (e.g. tenant.myapp.localhost\n * matches a route registered for myapp.localhost).\n *\n * When the host is not a portless-managed hostname (i.e. it does not end with\n * the configured TLD suffix) and exactly one route is registered, we return\n * that route as a tunnel passthrough. This lets external tunnel providers\n * (ngrok, Cloudflare Tunnel, etc.) forward traffic to the proxy without\n * requiring explicit hostname mapping.\n */\nfunction findRoute(\n routes: { hostname: string; port: number }[],\n host: string,\n tldSuffix: string,\n aliases?: Record\n): { hostname: string; port: number } | undefined {\n // 1. Exact match\n const exact = routes.find((r) => r.hostname === host);\n if (exact) return exact;\n\n // 2. Wildcard subdomain match\n const wildcard = routes.find((r) => host.endsWith(\".\" + r.hostname));\n if (wildcard) return wildcard;\n\n // 3. Alias lookup (e.g. \"abc123.ngrok-free.app\" -> \"myapp.localhost\")\n if (aliases) {\n const aliasTarget = aliases[host];\n if (aliasTarget) {\n const aliased = routes.find((r) => r.hostname === aliasTarget);\n if (aliased) return aliased;\n }\n }\n\n // 4. Tunnel passthrough: if the host is NOT a portless hostname and there\n // is exactly one registered route, assume traffic is arriving via an\n // external tunnel and route to the single app.\n const isPortlessHost = host.endsWith(tldSuffix) || host === tldSuffix.slice(1);\n if (!isPortlessHost && routes.length === 1) {\n return routes[0];\n }\n\n return undefined;\n}", "oldString": "/**\n * Find the route matching a given host. Matches exact hostname first, then\n * falls back to wildcard subdomain matching (e.g. tenant.myapp.localhost\n * matches a route registered for myapp.localhost).\n */\nfunction findRoute(\n routes: { hostname: string; port: number }[],\n host: string\n): { hostname: string; port: number } | undefined {\n return (\n routes.find((r) => r.hostname === host) || routes.find((r) => host.endsWith(\".\" + r.hostname))\n );\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now update both call sites to pass `tldSuffix`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "newString": " const route = findRoute(routes, host, tldSuffix);\n\n if (!route) {\n const safeHost = escapeHtml(host);\n const strippedHost = host.endsWith(tldSuffix) ? host.slice(0, -tldSuffix.length) : host;", "oldString": " const route = findRoute(routes, host);\n\n if (!route) {\n const safeHost = escapeHtml(host);\n const strippedHost = host.endsWith(tldSuffix) ? host.slice(0, -tldSuffix.length) : host;" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "newString": " const route = findRoute(routes, host, tldSuffix);\n\n if (!route) {\n socket.destroy();\n return;\n }", "oldString": " const route = findRoute(routes, host);\n\n if (!route) {\n socket.destroy();\n return;\n }" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Phase 1 is done. Let me verify it compiles: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run typecheck", "description": "Typecheck Phase 1 changes", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 typecheck /Users/sergiydybskiy/src/portless/packages/portless > tsc --noEmit sh: tsc: command not found  ELIFECYCLE  Command failed.  WARN  Local package.json exists, but node_modules missing, did you mean to install? ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm install", "description": "Install dependencies" } ``` ## Assistant **Result** (success): ``` Scope: all 4 workspace projects Lockfile is up to date, resolution step is skipped Progress: resolved 1, reused 0, downloaded 0, added 0 Packages: +1390 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Progress: resolved 1390, reused 521, downloaded 15, added 499 Progress: resolved 1390, reused 521, downloaded 79, added 601 Progress: resolved 1390, reused 521, downloaded 96, added 618 Progress: resolved 1390, reused 521, downloaded 144, added 666 Progress: resolved 1390, reused 521, downloaded 163, added 685 Progress: resolved 1390, reused 521, downloaded 165, added 687 Progress: resolved 1390, reused 521, downloaded 175, added 697 Progress: resolved 1390, reused 521, downloaded 177, added 699 Progress: resolved 1390, reused 521, downloaded 182, added 705 Progress: resolved 1390, reused 521, downloaded 189, added 712 Progress: resolved 1390, reused 521, downloaded 195, added 718 Progress: resolved 1390, reused 521, downloaded 205, added 728 Progress: resolved 1390, reused 521, downloaded 212, added 735 Progress: resolved 1390, reused 521, downloaded 224, added 747 Progress: resolved 1390, reused 521, downloaded 231, added 753 Progress: resolved 1390, reused 521, downloaded 241, added 764 Progress: resolved 1390, reused 521, downloaded 249, added 772 Progress: resolved 1390, reused 521, downloaded 253, added 776 Progress: resolved 1390, reused 521, downloaded 254, added 776 Progress: resolved 1390, reused 521, downloaded 257, added 780 Progress: resolved 1390, reused 521, downloaded 265, added 788 Progress: resolved 1390, reused 521, downloaded 269, added 792 Progress: resolved 1390, reused 521, downloaded 273, added 796 Progress: resolved 1390, reused 521, downloaded 277, added 800 Progress: resolved 1390, reused 521, downloaded 278, added 800 Progress: resolved 1390, reused 521, downloaded 279, added 802 Progress: resolved 1390, reused 521, downloaded 282, added 805 Progress: resolved 1390, reused 521, downloaded 285, added 808 Progress: resolved 1390, reused 521, downloaded 286, added 808 Progress: resolved 1390, reused 521, downloaded 287, added 810 Progress: resolved 1390, reused 521, downloaded 294, added 817 Progress: resolved 1390, reused 521, downloaded 298, added 821 Progress: resolved 1390, reused 521, downloaded 301, added 824 Progress: resolved 1390, reused 521, downloaded 303, added 826 Progress: resolved 1390, reused 521, downloaded 309, added 832 Progress: resolved 1390, reused 521, downloaded 310, added 833 Progress: resolved 1390, reused 521, downloaded 312, added 835 Progress: resolved 1390, reused 521, downloaded 317, added 840 Progress: resolved 1390, reused 521, downloaded 318, added 841 Progress: resolved 1390, reused 521, downloaded 319, added 841 Progress: resolved 1390, reused 521, downloaded 322, added 845 Progress: resolved 1390, reused 521, downloaded 323, added 845 Progress: resolved 1390, reused 521, downloaded 323, added 846 Progress: resolved 1390, reused 521, downloaded 324, added 846 Progress: resolved 1390, reused 521, downloaded 326, added 849 Progress: resolved 1390, reused 521, downloaded 331, added 854 Progress: resolved 1390, reused 521, downloaded 337, added 860 Progress: resolved 1390, reused 521, downloaded 341, added 864 Progress: resolved 1390, reused 521, downloaded 349, added 872 Progress: resolved 1390, reused 521, downloaded 350, added 872 Progress: resolved 1390, reused 521, downloaded 353, added 876 Progress: resolved 1390, reused 521, downloaded 357, added 880 Progress: resolved 1390, reused 521, downloaded 361, added 884 Progress: resolved 1390, reused 521, downloaded 367, added 890 Progress: resolved 1390, reused 521, downloaded 374, added 898 Progress: resolved 1390, reused 521, downloaded 377, added 901 Progress: resolved 1390, reused 521, downloaded 381, added 905 Progress: resolved 1390, reused 521, downloaded 383, added 907 Progress: resolved 1390, reused 521, downloaded 385, added 909 Progress: resolved 1390, reused 521, downloaded 386, added 909 Progress: resolved 1390, reused 521, downloaded 398, added 921 Progress: resolved 1390, reused 521, downloaded 408, added 932 Progress: resolved 1390, reused 521, downloaded 412, added 936 Progress: resolved 1390, reused 521, downloaded 418, added 942 Progress: resolved 1390, reused 521, downloaded 433, added 957 Progress: resolved 1390, reused 521, downloaded 438, added 962 Progress: resolved 1390, reused 521, downloaded 443, added 967 Progress: resolved 1390, reused 521, downloaded 450, added 974 Progress: resolved 1390, reused 521, downloaded 455, added 979 Progress: resolved 1390, reused 521, downloaded 459, added 983 Progress: resolved 1390, reused 521, downloaded 468, added 992 Progress: resolved 1390, reused 521, downloaded 470, added 994 Progress: resolved 1390, reused 521, downloaded 473, added 997 Progress: resolved 1390, reused 521, downloaded 475, added 999 Progress: resolved 1390, reused 521, downloaded 476, added 1000 Progress: resolved 1390, reused 521, downloaded 487, added 1012 Progress: resolved 1390, reused 521, downloaded 496, added 1021 Progress: resolved 1390, reused 521, downloaded 500, added 1025 Progress: resolved 1390, reused 521, downloaded 506, added 1031 Progress: resolved 1390, reused 521, downloaded 512, added 1037 Progress: resolved 1390, reused 521, downloaded 520, added 1045 Progress: resolved 1390, reused 521, downloaded 521, added 1045 Progress: resolved 1390, reused 521, downloaded 531, added 1056 Progress: resolved 1390, reused 521, downloaded 538, added 1063 Progress: resolved 1390, reused 521, downloaded 546, added 1071 Progress: resolved 1390, reused 521, downloaded 549, added 1074 Progress: resolved 1390, reused 521, downloaded 550, added 1074 Progress: resolved 1390, reused 521, downloaded 552, added 1077 Progress: resolved 1390, reused 521, downloaded 556, added 1081 Progress: resolved 1390, reused 521, downloaded 558, added 1083 Progress: resolved 1390, reused 521, downloaded 563, added 1088 Progress: resolved 1390, reused 521, downloaded 569, added 1094 Progress: resolved 1390, reused 521, downloaded 575, added 1100 Progress: resolved 1390, reused 521, downloaded 580, added 1105 Progress: resolved 1390, reused 521, downloaded 589, added 1114 Progress: resolved 1390, reused 521, downloaded 594, added 1119 Progress: resolved 1390, reused 521, downloaded 600, added 1125 Progress: resolved 1390, reused 521, downloaded 602, added 1127 Progress: resolved 1390, reused 521, downloaded 613, added 1138 Progress: resolved 1390, reused 521, downloaded 626, added 1151 Progress: resolved 1390, reused 521, downloaded 633, added 1158 Progress: resolved 1390, reused 521, downloaded 635, added 1160 Progress: resolved 1390, reused 521, downloaded 636, added 1161 Progress: resolved 1390, reused 521, downloaded 638, added 1163 Progress: resolved 1390, reused 521, downloaded 639, added 1164 Progress: resolved 1390, reused 521, downloaded 640, added 1164 Progress: resolved 1390, reused 521, downloaded 642, added 1167 bash tool terminated command after exceeding timeout 120000 ms ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run typecheck 2>&1", "description": "Typecheck Phase 1 changes", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 typecheck /Users/sergiydybskiy/src/portless/packages/portless > tsc --noEmit sh: tsc: command not found  ELIFECYCLE  Command failed.  WARN  Local package.json exists, but node_modules missing, did you mean to install? ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "ls node_modules/.pnpm 2>/dev/null | head -5; ls packages/portless/node_modules/.bin/tsc 2>/dev/null; npx --no-install tsc --version 2>&1 || pnpm exec tsc --version 2>&1", "description": "Find tsc binary location" } ``` ## Assistant **Result** (success): ``` @ai-sdk+gateway@3.0.52_zod@4.3.5 @ai-sdk+provider-utils@4.0.15_zod@4.3.5 @ai-sdk+provider@3.0.8 @ai-sdk+react@3.0.96_react@19.2.4_zod@4.3.5 @algolia+abtesting@1.12.2    This is not the tsc command you are looking for    To get access to the TypeScript compiler, tsc, from the command line either: - Use npm install typescript to first add TypeScript to your project before using npx - Use yarn to avoid accidentally running code from un-installed packages undefined  ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL  Command "tsc" not found ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "ls packages/portless/node_modules 2>/dev/null | head -5", "description": "Check if portless node_modules exists" } ``` ## Assistant **Result** (success): ``` (empty result) ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm install --frozen-lockfile 2>&1 | tail -5", "description": "Install deps with frozen lockfile", "timeout": 180000 } ``` ## Assistant **Result** (success): ``` bash tool terminated command after exceeding timeout 180000 ms ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm install 2>&1 | tail -3", "description": "Install deps", "timeout": 300000 } ``` ## Assistant **Result** (success): ``` . prepare$ husky . prepare: Done Done in 24.6s ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run typecheck 2>&1", "description": "Typecheck Phase 1 changes", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 typecheck /Users/sergiydybskiy/src/portless/packages/portless > tsc --noEmit ``` ## Assistant Typechecks clean. Let me also run existing tests: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run test 2>&1", "description": "Run existing tests", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 test /Users/sergiydybskiy/src/portless/packages/portless > vitest run  RUN  v4.0.18 /Users/sergiydybskiy/src/portless/packages/portless ❯ src/cli.test.ts (62 tests | 62 skipped) 3ms ↓ prints help and exits 0 with --help ↓ prints help and exits 0 with -h ↓ prints help and exits 0 with no args ↓ prints version and exits 0 with --version ↓ prints version and exits 0 with -v ↓ shows no active routes message when none registered ↓ shows proxy usage hint for bare 'proxy' command ↓ exits 1 for unknown proxy subcommand ↓ exits 1 when only a name is given without a command ↓ runs command directly when PORTLESS=0 is set ↓ runs command directly when PORTLESS=skip is set ↓ does not bypass proxy commands when PORTLESS=0 is set ↓ passes through exit code from bypassed command ↓ runs command directly in run mode ↓ strips --force but passes child --force through ↓ passes -- separator through to child command ↓ accepts --force before name (PORTLESS=0) ↓ accepts --force after name (PORTLESS=0) ↓ does not strip child command --force (PORTLESS=0) ↓ rejects unknown flags before command ↓ exits 1 for hostname with invalid characters ↓ exits 1 with 'No command provided' when no args follow run ↓ does not dispatch 'list' as the global list command ↓ does not print version for run --version ↓ prints run-specific help for run --help ↓ prints run-specific help for run -h ↓ passes --app-port through in bypass mode (PORTLESS=0) ↓ rejects invalid --app-port value ↓ rejects --app-port without a value ↓ accepts --app-port in named mode (PORTLESS=0) ↓ prints help with --help ↓ prints help with -h ↓ exits 1 with usage when no args given ↓ exits 1 with usage when only name is given ↓ exits 1 for invalid port ↓ exits 1 when --remove has no name ↓ prints help with --help ↓ prints help with -h ↓ shows usage for bare 'hosts' without subcommand ↓ rejects unknown hosts subcommand ↓ prints help with --help ↓ prints help with -h ↓ shows usage for bare 'proxy' without subcommand ↓ exits 1 for unknown proxy subcommand ↓ prints help with --help ↓ prints help with -h ↓ exits 1 with usage when no name given ↓ prints URL for a given service name ↓ prints URL for a dotted service name ↓ rejects unknown flags ↓ accepts --no-worktree flag ↓ exits 1 for invalid hostname ↓ treats reserved word as app name with PORTLESS=0 ↓ passes --force through with --name (PORTLESS=0) ↓ exits 1 when --name has no value ↓ exits 1 when --name has name but no command ↓ shows --name in run help ↓ strips --name and passes command through (PORTLESS=0) ↓ exits 1 when --name has no value ↓ exits 1 when --name value looks like a flag ↓ combines --name with --force (PORTLESS=0) ↓ does not consume --name after -- separator (PORTLESS=0) ✓ src/utils.test.ts (44 tests) 5ms ✓ src/hosts.test.ts (18 tests) 45ms ✓ src/cli-utils.test.ts (46 tests) 27ms ✓ src/routes.test.ts (20 tests) 31ms ✓ src/auto.test.ts (42 tests) 492ms Certificate request self-signature ok subject=CN=localhost ✓ src/certs.test.ts (18 tests) 1055ms (node:37118) [DEP0123] DeprecationWarning: Setting the TLS ServerName to an IP address is not permitted by RFC 6066. This will be ignored in a future version. (Use `node --trace-deprecation ...` to show where the warning was created) ✓ src/proxy.test.ts (37 tests) 8220ms ✓ creates an HTTPS server that responds to requests  1021ms ✓ includes X-Portless header on TLS responses  1004ms ✓ proxies HTTPS request to matching route  1005ms ✓ supports HTTP/2 connections  1010ms ✓ still accepts HTTP/1.1 connections over TLS (allowHTTP1)  1005ms ✓ generates https:// URLs in 404 page  1005ms ✓ sets x-forwarded-proto to https when proxying  1005ms ✓ accepts plain HTTP on the TLS-enabled port  1002ms ⎯⎯⎯⎯⎯⎯ Failed Suites 1 ⎯⎯⎯⎯⎯⎯⎯  FAIL  src/cli.test.ts > CLI Error: Built CLI not found at /Users/sergiydybskiy/src/portless/packages/portless/dist/cli.js. Run 'pnpm build' before running tests.  ❯ src/cli.test.ts:28:13  26|  beforeAll(() => {  27|  if (!fs.existsSync(CLI_PATH)) {  28|  throw new Error(`Built CLI not found at ${CLI_PATH}. Run 'pnpm b…  |  ^  29|  }  30|  }); ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯  Test Files  1 failed | 7 passed (8)  Tests  225 passed | 62 skipped (287)  Start at  09:17:36  Duration  8.59s (transform 1.66s, setup 0ms, import 1.85s, tests 9.88s, environment 1ms)  ELIFECYCLE  Test failed. See above for more details. ``` ## Assistant ## Assistant The proxy tests (most relevant to Phase 1) pass. CLI tests need a build first -- let me build and rerun: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run build 2>&1", "description": "Build portless", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 build /Users/sergiydybskiy/src/portless/packages/portless > tsup CLI Building entry: src/cli.ts, src/index.ts CLI Using tsconfig: tsconfig.json CLI tsup v8.5.1 CLI Using tsup config: /Users/sergiydybskiy/src/portless/packages/portless/tsup.config.ts CLI Target: es2022 CLI Cleaning output folder ESM Build start ESM dist/index.js 755.00 B ESM dist/cli.js 62.74 KB ESM dist/chunk-JK5E7AVP.js 180.23 KB ESM ⚡️ Build success in 14ms DTS Build start DTS ⚡️ Build success in 998ms DTS dist/cli.d.ts 20.00 B DTS dist/index.d.ts 6.30 KB ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run test 2>&1", "description": "Run all tests after build", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 test /Users/sergiydybskiy/src/portless/packages/portless > vitest run  RUN  v4.0.18 /Users/sergiydybskiy/src/portless/packages/portless ✓ src/utils.test.ts (44 tests) 6ms ✓ src/hosts.test.ts (18 tests) 12ms ✓ src/cli-utils.test.ts (46 tests) 37ms ✓ src/routes.test.ts (20 tests) 46ms ✓ src/auto.test.ts (42 tests) 516ms Certificate request self-signature ok subject=CN=localhost ✓ src/certs.test.ts (18 tests) 1042ms ✓ src/cli.test.ts (62 tests) 2926ms (node:39442) [DEP0123] DeprecationWarning: Setting the TLS ServerName to an IP address is not permitted by RFC 6066. This will be ignored in a future version. (Use `node --trace-deprecation ...` to show where the warning was created) ✓ src/proxy.test.ts (37 tests) 8217ms ✓ creates an HTTPS server that responds to requests  1023ms ✓ includes X-Portless header on TLS responses  1004ms ✓ proxies HTTPS request to matching route  1004ms ✓ supports HTTP/2 connections  1009ms ✓ still accepts HTTP/1.1 connections over TLS (allowHTTP1)  1006ms ✓ generates https:// URLs in 404 page  1006ms ✓ sets x-forwarded-proto to https when proxying  1006ms ✓ accepts plain HTTP on the TLS-enabled port  1003ms  Test Files  8 passed (8)  Tests  287 passed (287)  Start at  09:17:59  Duration  8.46s (transform 626ms, setup 0ms, import 826ms, tests 12.80s, environment 1ms) ``` ## Assistant All 287 tests pass. Now Phase 2. ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless alias command)", "priority": "high", "status": "in_progress" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "pending" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "pending" }, { "content": "Add tests for all three phases", "priority": "high", "status": "pending" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless alias command)", "priority": "high", "status": "in_progress" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "pending" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "pending" }, { "content": "Add tests for all three phases", "priority": "high", "status": "pending" } ] ``` ## Assistant Phase 2 needs changes to `routes.ts` (alias storage), `types.ts` (new option), `proxy.ts` (wire aliases), and `cli.ts` (alias command). Let me read the full `routes.ts` first: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/routes.ts" } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/routes.ts file 1: import * as fs from "node:fs"; 2: import * as path from "node:path"; 3: import type { RouteInfo } from "./types.js"; 4: import { fixOwnership, isErrnoException } from "./utils.js"; 5: import { SYSTEM_STATE_DIR } from "./cli-utils.js"; 6: 7: /** How long (ms) before a lock directory is considered stale and forcibly removed. */ 8: const STALE_LOCK_THRESHOLD_MS = 10_000; 9: 10: /** Default maximum number of retries when acquiring the file lock. */ 11: const LOCK_MAX_RETRIES = 20; 12: 13: /** Delay (ms) between lock acquisition retries. */ 14: const LOCK_RETRY_DELAY_MS = 50; 15: 16: /** File permission mode for route and state files. */ 17: export const FILE_MODE = 0o644; 18: 19: /** Directory permission mode for the user state directory. */ 20: export const DIR_MODE = 0o755; 21: 22: /** Directory permission mode for the system state directory (world-writable with sticky bit). */ 23: export const SYSTEM_DIR_MODE = 0o1777; 24: 25: /** File permission mode for shared state files in the system state directory. */ 26: export const SYSTEM_FILE_MODE = 0o666; 27: 28: export interface RouteMapping extends RouteInfo { 29: pid: number; 30: } 31: 32: /** Runtime check that a parsed JSON value is a valid RouteMapping. */ 33: function isValidRoute(value: unknown): value is RouteMapping { 34: return ( 35: typeof value === "object" && 36: value !== null && 37: typeof (value as RouteMapping).hostname === "string" && 38: typeof (value as RouteMapping).port === "number" && 39: typeof (value as RouteMapping).pid === "number" 40: ); 41: } 42: 43: /** 44: * Thrown when a route is already registered by a live process and --force 45: * was not specified. 46: */ 47: export class RouteConflictError extends Error { 48: readonly hostname: string; 49: readonly existingPid: number; 50: 51: constructor(hostname: string, existingPid: number) { 52: super( 53: `"${hostname}" is already registered by a running process (PID ${existingPid}). ` + 54: `Use --force to override.` 55: ); 56: this.name = "RouteConflictError"; 57: this.hostname = hostname; 58: this.existingPid = existingPid; 59: } 60: } 61: 62: /** 63: * Manages route mappings stored as a JSON file on disk. 64: * Supports file locking and stale-route cleanup. 65: */ 66: export class RouteStore { 67: /** The state directory path. */ 68: readonly dir: string; 69: private readonly routesPath: string; 70: private readonly lockPath: string; 71: readonly pidPath: string; 72: readonly portFilePath: string; 73: private readonly onWarning: ((message: string) => void) | undefined; 74: 75: constructor(dir: string, options?: { onWarning?: (message: string) => void }) { 76: this.dir = dir; 77: this.routesPath = path.join(dir, "routes.json"); 78: this.lockPath = path.join(dir, "routes.lock"); 79: this.pidPath = path.join(dir, "proxy.pid"); 80: this.portFilePath = path.join(dir, "proxy.port"); 81: this.onWarning = options?.onWarning; 82: } 83: 84: private isSystemDir(): boolean { 85: return this.dir === SYSTEM_STATE_DIR; 86: } 87: 88: private get dirMode(): number { 89: return this.isSystemDir() ? SYSTEM_DIR_MODE : DIR_MODE; 90: } 91: 92: private get fileMode(): number { 93: return this.isSystemDir() ? SYSTEM_FILE_MODE : FILE_MODE; 94: } 95: 96: ensureDir(): void { 97: if (!fs.existsSync(this.dir)) { 98: fs.mkdirSync(this.dir, { recursive: true, mode: this.dirMode }); 99: } 100: try { 101: fs.chmodSync(this.dir, this.dirMode); 102: } catch { 103: // May fail if directory is owned by another user (e.g. root); non-fatal 104: } 105: fixOwnership(this.dir); 106: } 107: 108: getRoutesPath(): string { 109: return this.routesPath; 110: } 111: 112: // -- Locking --------------------------------------------------------------- 113: 114: private static readonly sleepBuffer = new Int32Array(new SharedArrayBuffer(4)); 115: 116: private syncSleep(ms: number): void { 117: Atomics.wait(RouteStore.sleepBuffer, 0, 0, ms); 118: } 119: 120: private acquireLock(maxRetries = LOCK_MAX_RETRIES, retryDelayMs = LOCK_RETRY_DELAY_MS): boolean { 121: for (let i = 0; i < maxRetries; i++) { 122: try { 123: fs.mkdirSync(this.lockPath); 124: return true; 125: } catch (err: unknown) { 126: if (isErrnoException(err) && err.code === "EEXIST") { 127: // Check for stale lock 128: try { 129: const stat = fs.statSync(this.lockPath); 130: if (Date.now() - stat.mtimeMs > STALE_LOCK_THRESHOLD_MS) { 131: fs.rmSync(this.lockPath, { recursive: true }); 132: continue; 133: } 134: } catch { 135: // Lock dir gone already; retry 136: continue; 137: } 138: // Wait and retry 139: this.syncSleep(retryDelayMs); 140: } else { 141: // Unexpected error (e.g. missing parent dir); cannot acquire lock 142: return false; 143: } 144: } 145: } 146: // Timed out waiting for lock 147: return false; 148: } 149: 150: private releaseLock(): void { 151: try { 152: fs.rmSync(this.lockPath, { recursive: true }); 153: } catch { 154: // Lock may already be removed; non-fatal 155: } 156: } 157: 158: // -- Route I/O ------------------------------------------------------------- 159: 160: private isProcessAlive(pid: number): boolean { 161: try { 162: process.kill(pid, 0); 163: return true; 164: } catch { 165: return false; 166: } 167: } 168: 169: /** 170: * Load routes from disk, filtering out stale entries whose owning process 171: * is no longer alive. Stale-route cleanup is only persisted when the caller 172: * already holds the lock (i.e. inside addRoute/removeRoute) to avoid 173: * unprotected concurrent writes. 174: */ 175: loadRoutes(persistCleanup = false): RouteMapping[] { 176: if (!fs.existsSync(this.routesPath)) { 177: return []; 178: } 179: try { 180: const raw = fs.readFileSync(this.routesPath, "utf-8"); 181: let parsed: unknown; 182: try { 183: parsed = JSON.parse(raw); 184: } catch { 185: this.onWarning?.(`Corrupted routes file (invalid JSON): ${this.routesPath}`); 186: return []; 187: } 188: if (!Array.isArray(parsed)) { 189: this.onWarning?.(`Corrupted routes file (expected array): ${this.routesPath}`); 190: return []; 191: } 192: const routes: RouteMapping[] = parsed.filter(isValidRoute); 193: // Filter out stale routes whose owning process is no longer alive 194: const alive = routes.filter((r) => r.pid === 0 || this.isProcessAlive(r.pid)); 195: if (persistCleanup && alive.length !== routes.length) { 196: // Persist the cleaned-up list so stale entries don't accumulate. 197: // Only safe when caller holds the lock. 198: try { 199: fs.writeFileSync(this.routesPath, JSON.stringify(alive, null, 2), { 200: mode: this.fileMode, 201: }); 202: } catch { 203: // Write may fail (permissions); non-fatal 204: } 205: } 206: return alive; 207: } catch { 208: return []; 209: } 210: } 211: 212: private saveRoutes(routes: RouteMapping[]): void { 213: fs.writeFileSync(this.routesPath, JSON.stringify(routes, null, 2), { mode: this.fileMode }); 214: fixOwnership(this.routesPath); 215: } 216: 217: addRoute(hostname: string, port: number, pid: number, force = false): void { 218: this.ensureDir(); 219: if (!this.acquireLock()) { 220: throw new Error("Failed to acquire route lock"); 221: } 222: try { 223: const routes = this.loadRoutes(true); 224: const existing = routes.find((r) => r.hostname === hostname); 225: if (existing && existing.pid !== pid && this.isProcessAlive(existing.pid) && !force) { 226: throw new RouteConflictError(hostname, existing.pid); 227: } 228: const filtered = routes.filter((r) => r.hostname !== hostname); 229: filtered.push({ hostname, port, pid }); 230: this.saveRoutes(filtered); 231: } finally { 232: this.releaseLock(); 233: } 234: } 235: 236: removeRoute(hostname: string): void { 237: this.ensureDir(); 238: if (!this.acquireLock()) { 239: throw new Error("Failed to acquire route lock"); 240: } 241: try { 242: const routes = this.loadRoutes(true).filter((r) => r.hostname !== hostname); 243: this.saveRoutes(routes); 244: } finally { 245: this.releaseLock(); 246: } 247: } 248: } (End of file - total 248 lines) ``` ## Assistant Now let me add alias support to `RouteStore`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/routes.ts", "newString": "export class RouteStore {\n /** The state directory path. */\n readonly dir: string;\n private readonly routesPath: string;\n private readonly aliasesPath: string;\n private readonly lockPath: string;\n readonly pidPath: string;\n readonly portFilePath: string;\n private readonly onWarning: ((message: string) => void) | undefined;\n\n constructor(dir: string, options?: { onWarning?: (message: string) => void }) {\n this.dir = dir;\n this.routesPath = path.join(dir, \"routes.json\");\n this.aliasesPath = path.join(dir, \"aliases.json\");\n this.lockPath = path.join(dir, \"routes.lock\");\n this.pidPath = path.join(dir, \"proxy.pid\");\n this.portFilePath = path.join(dir, \"proxy.port\");\n this.onWarning = options?.onWarning;\n }", "oldString": "export class RouteStore {\n /** The state directory path. */\n readonly dir: string;\n private readonly routesPath: string;\n private readonly lockPath: string;\n readonly pidPath: string;\n readonly portFilePath: string;\n private readonly onWarning: ((message: string) => void) | undefined;\n\n constructor(dir: string, options?: { onWarning?: (message: string) => void }) {\n this.dir = dir;\n this.routesPath = path.join(dir, \"routes.json\");\n this.lockPath = path.join(dir, \"routes.lock\");\n this.pidPath = path.join(dir, \"proxy.pid\");\n this.portFilePath = path.join(dir, \"proxy.port\");\n this.onWarning = options?.onWarning;\n }" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now add the `getAliasesPath()` method and alias I/O methods at the end of the class, before the closing `}`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/routes.ts", "newString": " removeRoute(hostname: string): void {\n this.ensureDir();\n if (!this.acquireLock()) {\n throw new Error(\"Failed to acquire route lock\");\n }\n try {\n const routes = this.loadRoutes(true).filter((r) => r.hostname !== hostname);\n this.saveRoutes(routes);\n } finally {\n this.releaseLock();\n }\n }\n\n // -- Alias I/O -------------------------------------------------------------\n\n getAliasesPath(): string {\n return this.aliasesPath;\n }\n\n /**\n * Load hostname aliases from disk.\n * Returns a map of external hostname -> portless hostname.\n */\n loadAliases(): Record {\n if (!fs.existsSync(this.aliasesPath)) {\n return {};\n }\n try {\n const raw = fs.readFileSync(this.aliasesPath, \"utf-8\");\n let parsed: unknown;\n try {\n parsed = JSON.parse(raw);\n } catch {\n this.onWarning?.(`Corrupted aliases file (invalid JSON): ${this.aliasesPath}`);\n return {};\n }\n if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n this.onWarning?.(`Corrupted aliases file (expected object): ${this.aliasesPath}`);\n return {};\n }\n // Validate that all values are strings\n const aliases: Record = {};\n for (const [key, value] of Object.entries(parsed as Record)) {\n if (typeof value === \"string\") {\n aliases[key] = value;\n }\n }\n return aliases;\n } catch {\n return {};\n }\n }\n\n private saveAliases(aliases: Record): void {\n fs.writeFileSync(this.aliasesPath, JSON.stringify(aliases, null, 2), { mode: this.fileMode });\n fixOwnership(this.aliasesPath);\n }\n\n /**\n * Map an external hostname (e.g. ngrok URL) to a portless route hostname.\n */\n addAlias(externalHostname: string, portlessHostname: string): void {\n this.ensureDir();\n if (!this.acquireLock()) {\n throw new Error(\"Failed to acquire route lock\");\n }\n try {\n const aliases = this.loadAliases();\n aliases[externalHostname] = portlessHostname;\n this.saveAliases(aliases);\n } finally {\n this.releaseLock();\n }\n }\n\n /**\n * Remove a specific alias by its external hostname.\n */\n removeAlias(externalHostname: string): boolean {\n this.ensureDir();\n if (!this.acquireLock()) {\n throw new Error(\"Failed to acquire route lock\");\n }\n try {\n const aliases = this.loadAliases();\n if (!(externalHostname in aliases)) return false;\n delete aliases[externalHostname];\n this.saveAliases(aliases);\n return true;\n } finally {\n this.releaseLock();\n }\n }\n\n /**\n * Remove all aliases pointing at a given portless hostname.\n */\n removeAliasesForRoute(portlessHostname: string): void {\n this.ensureDir();\n if (!this.acquireLock()) {\n throw new Error(\"Failed to acquire route lock\");\n }\n try {\n const aliases = this.loadAliases();\n let changed = false;\n for (const [ext, target] of Object.entries(aliases)) {\n if (target === portlessHostname) {\n delete aliases[ext];\n changed = true;\n }\n }\n if (changed) {\n this.saveAliases(aliases);\n }\n } finally {\n this.releaseLock();\n }\n }\n}", "oldString": " removeRoute(hostname: string): void {\n this.ensureDir();\n if (!this.acquireLock()) {\n throw new Error(\"Failed to acquire route lock\");\n }\n try {\n const routes = this.loadRoutes(true).filter((r) => r.hostname !== hostname);\n this.saveRoutes(routes);\n } finally {\n this.releaseLock();\n }\n }\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now add `getAliases` to `ProxyServerOptions` in `types.ts`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/types.ts", "newString": "export interface ProxyServerOptions {\n /** Called on each request to get the current route table. */\n getRoutes: () => RouteInfo[];\n /** The port the proxy is listening on (used to build correct URLs). */\n proxyPort: number;\n /** TLD suffix used for hostnames (default: \"localhost\"). */\n tld?: string;\n /** Optional error logger; defaults to console.error. */\n onError?: (message: string) => void;\n /**\n * Called on each request to get current hostname aliases.\n * Maps external hostnames (e.g. ngrok URLs) to portless route hostnames.\n */\n getAliases?: () => Record;\n /** When provided, enables HTTP/2 over TLS (HTTPS). */\n tls?: {\n cert: Buffer;\n key: Buffer;\n /** SNI callback for per-hostname certificate selection. */\n SNICallback?: (\n servername: string,\n cb: (err: Error | null, ctx?: import(\"node:tls\").SecureContext) => void\n ) => void;\n };\n}", "oldString": "export interface ProxyServerOptions {\n /** Called on each request to get the current route table. */\n getRoutes: () => RouteInfo[];\n /** The port the proxy is listening on (used to build correct URLs). */\n proxyPort: number;\n /** TLD suffix used for hostnames (default: \"localhost\"). */\n tld?: string;\n /** Optional error logger; defaults to console.error. */\n onError?: (message: string) => void;\n /** When provided, enables HTTP/2 over TLS (HTTPS). */\n tls?: {\n cert: Buffer;\n key: Buffer;\n /** SNI callback for per-hostname certificate selection. */\n SNICallback?: (\n servername: string,\n cb: (err: Error | null, ctx?: import(\"node:tls\").SecureContext) => void\n ) => void;\n };\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now wire `getAliases` into `createProxyServer` in `proxy.ts`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "newString": "export function createProxyServer(options: ProxyServerOptions): ProxyServer {\n const {\n getRoutes,\n proxyPort,\n tld = \"localhost\",\n onError = (msg: string) => console.error(msg),\n getAliases,\n tls,\n } = options;\n const tldSuffix = `.${tld}`;", "oldString": "export function createProxyServer(options: ProxyServerOptions): ProxyServer {\n const {\n getRoutes,\n proxyPort,\n tld = \"localhost\",\n onError = (msg: string) => console.error(msg),\n tls,\n } = options;\n const tldSuffix = `.${tld}`;" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now update both `findRoute` call sites to pass aliases: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "limit": 10, "offset": 155 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts file 155: const hops = parseInt(req.headers[PORTLESS_HOPS_HEADER] as string, 10) || 0; 156: if (hops >= MAX_PROXY_HOPS) { 157: onError( 158: `Loop detected for ${host}: request has passed through portless ${hops} times. ` + 159: `This usually means a backend is proxying back through portless without rewriting ` + 160: `the Host header. If you use Vite/webpack proxy, set changeOrigin: true.` 161: ); 162: res.writeHead(508, { "Content-Type": "text/html" }); 163: res.end( 164: renderPage( (Showing lines 155-164 of 425. Use offset=165 to continue.) ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "newString": " const route = findRoute(routes, host, tldSuffix, getAliases?.());\n\n if (!route) {\n const safeHost = escapeHtml(host);\n const strippedHost = host.endsWith(tldSuffix) ? host.slice(0, -tldSuffix.length) : host;", "oldString": " const route = findRoute(routes, host, tldSuffix);\n\n if (!route) {\n const safeHost = escapeHtml(host);\n const strippedHost = host.endsWith(tldSuffix) ? host.slice(0, -tldSuffix.length) : host;" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.ts", "newString": " const route = findRoute(routes, host, tldSuffix, getAliases?.());\n\n if (!route) {\n socket.destroy();\n return;\n }", "oldString": " const route = findRoute(routes, host, tldSuffix);\n\n if (!route) {\n socket.destroy();\n return;\n }" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now wire aliases into the proxy startup in `cli.ts`. Let me read the relevant section: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 60, "offset": 58 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 58: function startProxyServer( 59: store: RouteStore, 60: proxyPort: number, 61: tld: string, 62: tlsOptions?: { cert: Buffer; key: Buffer } 63: ): void { 64: store.ensureDir(); 65: 66: const isTls = !!tlsOptions; 67: 68: // Create empty routes file if it doesn't exist 69: const routesPath = store.getRoutesPath(); 70: if (!fs.existsSync(routesPath)) { 71: fs.writeFileSync(routesPath, "[]", { mode: FILE_MODE }); 72: } 73: try { 74: fs.chmodSync(routesPath, FILE_MODE); 75: } catch { 76: // May fail if file is owned by another user; non-fatal 77: } 78: fixOwnership(routesPath); 79: 80: // Cache routes in memory and reload on file change (debounced) 81: let cachedRoutes = store.loadRoutes(); 82: let debounceTimer: ReturnType | null = null; 83: let watcher: fs.FSWatcher | null = null; 84: let pollingInterval: ReturnType | null = null; 85: 86: const syncVal = process.env.PORTLESS_SYNC_HOSTS; 87: const autoSyncHosts = 88: syncVal === "1" || 89: syncVal === "true" || 90: (tld !== DEFAULT_TLD && syncVal !== "0" && syncVal !== "false"); 91: 92: const reloadRoutes = () => { 93: try { 94: cachedRoutes = store.loadRoutes(); 95: if (autoSyncHosts) { 96: syncHostsFile(cachedRoutes.map((r) => r.hostname)); 97: } 98: } catch { 99: // File may be mid-write; keep existing cached routes 100: } 101: }; 102: 103: try { 104: watcher = fs.watch(routesPath, () => { 105: if (debounceTimer) clearTimeout(debounceTimer); 106: debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS); 107: }); 108: } catch { 109: // fs.watch may not be supported; fall back to periodic polling 110: console.warn(chalk.yellow("fs.watch unavailable; falling back to polling for route changes")); 111: pollingInterval = setInterval(reloadRoutes, POLL_INTERVAL_MS); 112: } 113: 114: if (autoSyncHosts) { 115: syncHostsFile(cachedRoutes.map((r) => r.hostname)); 116: } 117: (Showing lines 58-117 of 1488. Use offset=118 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 20, "offset": 118 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 118: const server = createProxyServer({ 119: getRoutes: () => cachedRoutes, 120: proxyPort, 121: tld, 122: onError: (msg) => console.error(chalk.red(msg)), 123: tls: tlsOptions, 124: }); 125: 126: server.on("error", (err: NodeJS.ErrnoException) => { 127: if (err.code === "EADDRINUSE") { 128: console.error(chalk.red(`Port ${proxyPort} is already in use.`)); 129: console.error(chalk.blue("Stop the existing proxy first:")); 130: console.error(chalk.cyan(" portless proxy stop")); 131: console.error(chalk.blue("Or check what is using the port:")); 132: console.error(chalk.cyan(` lsof -ti tcp:${proxyPort}`)); 133: } else if (err.code === "EACCES") { 134: console.error(chalk.red(`Permission denied for port ${proxyPort}.`)); 135: console.error(chalk.blue("Either run with sudo:")); 136: console.error(chalk.cyan(" sudo portless proxy start -p 80")); 137: console.error(chalk.blue("Or use a non-privileged port (no sudo needed):")); (Showing lines 118-137 of 1488. Use offset=138 to continue.) ``` ## Assistant Now I need to add alias caching and watching to `startProxyServer`, and pass `getAliases` to `createProxyServer`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " // Cache routes in memory and reload on file change (debounced)\n let cachedRoutes = store.loadRoutes();\n let cachedAliases = store.loadAliases();\n let debounceTimer: ReturnType | null = null;\n let aliasDebounceTimer: ReturnType | null = null;\n let watcher: fs.FSWatcher | null = null;\n let aliasWatcher: fs.FSWatcher | null = null;\n let pollingInterval: ReturnType | null = null;\n\n const syncVal = process.env.PORTLESS_SYNC_HOSTS;\n const autoSyncHosts =\n syncVal === \"1\" ||\n syncVal === \"true\" ||\n (tld !== DEFAULT_TLD && syncVal !== \"0\" && syncVal !== \"false\");\n\n const reloadRoutes = () => {\n try {\n cachedRoutes = store.loadRoutes();\n if (autoSyncHosts) {\n syncHostsFile(cachedRoutes.map((r) => r.hostname));\n }\n } catch {\n // File may be mid-write; keep existing cached routes\n }\n };\n\n const reloadAliases = () => {\n try {\n cachedAliases = store.loadAliases();\n } catch {\n // File may be mid-write; keep existing cached aliases\n }\n };\n\n try {\n watcher = fs.watch(routesPath, () => {\n if (debounceTimer) clearTimeout(debounceTimer);\n debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);\n });\n } catch {\n // fs.watch may not be supported; fall back to periodic polling\n console.warn(chalk.yellow(\"fs.watch unavailable; falling back to polling for route changes\"));\n pollingInterval = setInterval(reloadRoutes, POLL_INTERVAL_MS);\n }\n\n // Watch aliases file if it exists; also reload aliases on polling interval\n const aliasesPath = store.getAliasesPath();\n try {\n if (fs.existsSync(aliasesPath)) {\n aliasWatcher = fs.watch(aliasesPath, () => {\n if (aliasDebounceTimer) clearTimeout(aliasDebounceTimer);\n aliasDebounceTimer = setTimeout(reloadAliases, DEBOUNCE_MS);\n });\n }\n } catch {\n // Non-fatal; aliases will be reloaded on the polling interval if set\n }\n if (pollingInterval) {\n // Piggyback alias reloads on the existing polling interval\n const existingInterval = pollingInterval;\n clearInterval(existingInterval);\n pollingInterval = setInterval(() => {\n reloadRoutes();\n reloadAliases();\n }, POLL_INTERVAL_MS);\n }", "oldString": " // Cache routes in memory and reload on file change (debounced)\n let cachedRoutes = store.loadRoutes();\n let debounceTimer: ReturnType | null = null;\n let watcher: fs.FSWatcher | null = null;\n let pollingInterval: ReturnType | null = null;\n\n const syncVal = process.env.PORTLESS_SYNC_HOSTS;\n const autoSyncHosts =\n syncVal === \"1\" ||\n syncVal === \"true\" ||\n (tld !== DEFAULT_TLD && syncVal !== \"0\" && syncVal !== \"false\");\n\n const reloadRoutes = () => {\n try {\n cachedRoutes = store.loadRoutes();\n if (autoSyncHosts) {\n syncHostsFile(cachedRoutes.map((r) => r.hostname));\n }\n } catch {\n // File may be mid-write; keep existing cached routes\n }\n };\n\n try {\n watcher = fs.watch(routesPath, () => {\n if (debounceTimer) clearTimeout(debounceTimer);\n debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS);\n });\n } catch {\n // fs.watch may not be supported; fall back to periodic polling\n console.warn(chalk.yellow(\"fs.watch unavailable; falling back to polling for route changes\"));\n pollingInterval = setInterval(reloadRoutes, POLL_INTERVAL_MS);\n }" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now pass `getAliases` to `createProxyServer`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " const server = createProxyServer({\n getRoutes: () => cachedRoutes,\n getAliases: () => cachedAliases,\n proxyPort,\n tld,\n onError: (msg) => console.error(chalk.red(msg)),\n tls: tlsOptions,\n });", "oldString": " const server = createProxyServer({\n getRoutes: () => cachedRoutes,\n proxyPort,\n tld,\n onError: (msg) => console.error(chalk.red(msg)),\n tls: tlsOptions,\n });" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now update the cleanup function to also close the alias watcher: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 35, "offset": 175 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 175: } 176: process.exit(1); 177: }); 178: 179: server.listen(proxyPort, () => { 180: // Save PID and port once the server is actually listening 181: fs.writeFileSync(store.pidPath, process.pid.toString(), { mode: FILE_MODE }); 182: fs.writeFileSync(store.portFilePath, proxyPort.toString(), { mode: FILE_MODE }); 183: writeTlsMarker(store.dir, isTls); 184: writeTldFile(store.dir, tld); 185: fixOwnership(store.dir, store.pidPath, store.portFilePath); 186: const proto = isTls ? "HTTPS/2" : "HTTP"; 187: const tldLabel = tld !== DEFAULT_TLD ? ` (TLD: .${tld})` : ""; 188: console.log(chalk.green(`${proto} proxy listening on port ${proxyPort}${tldLabel}`)); 189: }); 190: 191: // Cleanup on exit 192: let exiting = false; 193: const cleanup = () => { 194: if (exiting) return; 195: exiting = true; 196: if (debounceTimer) clearTimeout(debounceTimer); 197: if (pollingInterval) clearInterval(pollingInterval); 198: if (watcher) { 199: watcher.close(); 200: } 201: try { 202: fs.unlinkSync(store.pidPath); 203: } catch { 204: // PID file may already be removed; non-fatal 205: } 206: try { 207: fs.unlinkSync(store.portFilePath); 208: } catch { 209: // Port file may already be removed; non-fatal (Showing lines 175-209 of 1522. Use offset=210 to continue.) ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " // Cleanup on exit\n let exiting = false;\n const cleanup = () => {\n if (exiting) return;\n exiting = true;\n if (debounceTimer) clearTimeout(debounceTimer);\n if (aliasDebounceTimer) clearTimeout(aliasDebounceTimer);\n if (pollingInterval) clearInterval(pollingInterval);\n if (watcher) {\n watcher.close();\n }\n if (aliasWatcher) {\n aliasWatcher.close();\n }", "oldString": " // Cleanup on exit\n let exiting = false;\n const cleanup = () => {\n if (exiting) return;\n exiting = true;\n if (debounceTimer) clearTimeout(debounceTimer);\n if (pollingInterval) clearInterval(pollingInterval);\n if (watcher) {\n watcher.close();\n }" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Good. Now add the `portless alias` CLI command. Let me find where the other commands are dispatched: ## Assistant ### Tool: grep **Args:** ```json { "include": "cli.ts", "pattern": "handleAlias|handleHosts|handleList|handleGet" } ``` ## Assistant **Result** (success): ``` Found 8 matches /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts: Line 839: async function handleList(): Promise { Line 847: async function handleGet(args: string[]): Promise { Line 908: async function handleAlias(args: string[]): Promise { Line 974: async function handleHosts(args: string[]): Promise { Line 1493: await handleList(); Line 1497: await handleGet(args); Line 1501: await handleAlias(args); Line 1505: await handleHosts(args); ``` ## Assistant There's already a `handleAlias` at line 908. Let me read it: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 70, "offset": 908 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 908: async function handleAlias(args: string[]): Promise { 909: if (args[1] === "--help" || args[1] === "-h") { 910: console.log(` 911: ${chalk.bold("portless alias")} - Register a static route for services not managed by portless. 912: 913: ${chalk.bold("Usage:")} 914: ${chalk.cyan("portless alias ")} Register a route 915: ${chalk.cyan("portless alias --remove ")} Remove a route 916: ${chalk.cyan("portless alias --force")} Override existing route 917: 918: ${chalk.bold("Examples:")} 919: portless alias my-postgres 5432 # -> http://my-postgres.localhost:1355 920: portless alias redis 6379 # -> http://redis.localhost:1355 921: portless alias --remove my-postgres # Remove the alias 922: `); 923: process.exit(0); 924: } 925: 926: const { dir, tld } = await discoverState(); 927: const store = new RouteStore(dir, { 928: onWarning: (msg) => console.warn(chalk.yellow(msg)), 929: }); 930: 931: if (args[1] === "--remove") { 932: const aliasName = args[2]; 933: if (!aliasName) { 934: console.error(chalk.red("Error: No alias name provided.")); 935: console.error(chalk.cyan(" portless alias --remove ")); 936: process.exit(1); 937: } 938: const hostname = parseHostname(aliasName, tld); 939: const routes = store.loadRoutes(); 940: const existing = routes.find((r) => r.hostname === hostname && r.pid === 0); 941: if (!existing) { 942: console.error(chalk.red(`Error: No alias found for "${hostname}".`)); 943: process.exit(1); 944: } 945: store.removeRoute(hostname); 946: console.log(chalk.green(`Removed alias: ${hostname}`)); 947: return; 948: } 949: 950: const aliasName = args[1]; 951: const aliasPort = args[2]; 952: if (!aliasName || !aliasPort) { 953: console.error(chalk.red("Error: Missing arguments.")); 954: console.error(chalk.blue("Usage:")); 955: console.error(chalk.cyan(" portless alias ")); 956: console.error(chalk.cyan(" portless alias --remove ")); 957: console.error(chalk.blue("Example:")); 958: console.error(chalk.cyan(" portless alias my-postgres 5432")); 959: process.exit(1); 960: } 961: 962: const hostname = parseHostname(aliasName, tld); 963: const port = parseInt(aliasPort, 10); 964: if (isNaN(port) || port < 1 || port > 65535) { 965: console.error(chalk.red(`Error: Invalid port "${aliasPort}". Must be 1-65535.`)); 966: process.exit(1); 967: } 968: 969: const force = args.includes("--force"); 970: store.addRoute(hostname, port, 0, force); 971: console.log(chalk.green(`Alias registered: ${hostname} -> 127.0.0.1:${port}`)); 972: } 973: 974: async function handleHosts(args: string[]): Promise { 975: if (args[1] === "--help" || args[1] === "-h") { 976: console.log(` 977: ${chalk.bold("portless hosts")} - Manage /etc/hosts entries for .localhost subdomains. (Showing lines 908-977 of 1526. Use offset=978 to continue.) ``` ## Assistant ## Assistant The existing `alias` command is for mapping portless names to local ports (static route registration). I need a separate `tunnel` subcommand for external hostname mapping. Let me check the command dispatch: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 60, "offset": 1480 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 1480: if (args.length === 0 || args[0] === "--help" || args[0] === "-h") { 1481: printHelp(); 1482: return; 1483: } 1484: if (args[0] === "--version" || args[0] === "-v") { 1485: printVersion(); 1486: return; 1487: } 1488: if (args[0] === "trust") { 1489: await handleTrust(); 1490: return; 1491: } 1492: if (args[0] === "list") { 1493: await handleList(); 1494: return; 1495: } 1496: if (args[0] === "get") { 1497: await handleGet(args); 1498: return; 1499: } 1500: if (args[0] === "alias") { 1501: await handleAlias(args); 1502: return; 1503: } 1504: if (args[0] === "hosts") { 1505: await handleHosts(args); 1506: return; 1507: } 1508: if (args[0] === "proxy") { 1509: await handleProxy(args); 1510: return; 1511: } 1512: } 1513: 1514: // Run app (either `portless run ` or `portless `) 1515: if (isRunCommand) { 1516: await handleRunMode(args); 1517: } else { 1518: await handleNamedMode(args); 1519: } 1520: } 1521: 1522: main().catch((err: unknown) => { 1523: const message = err instanceof Error ? err.message : String(err); 1524: console.error(chalk.red("Error:"), message); 1525: process.exit(1); 1526: }); (End of file - total 1526 lines) ``` ## Assistant Now let me also check the reserved names list: ## Assistant ### Tool: grep **Args:** ```json { "include": "cli.ts", "pattern": "RESERVED_NAMES|reserved" } ``` ## Assistant **Result** (success): ``` Found 2 matches /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts: Line 813: or "portless --name " to force any name including reserved ones. Line 1430: // subcommand dispatch. Useful when the app name collides with a reserved ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 50, "offset": 1430 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 1430: // subcommand dispatch. Useful when the app name collides with a reserved 1431: // subcommand (run, alias, hosts, list, trust, proxy). 1432: if (args[0] === "--name") { 1433: args.shift(); 1434: if (!args[0]) { 1435: console.error(chalk.red("Error: --name requires an app name.")); 1436: console.error(chalk.cyan(" portless --name ")); 1437: process.exit(1); 1438: } 1439: const skipPortless = 1440: process.env.PORTLESS === "0" || 1441: process.env.PORTLESS === "false" || 1442: process.env.PORTLESS === "skip"; 1443: if (skipPortless) { 1444: const { commandArgs } = parseAppArgs(args); 1445: if (commandArgs.length === 0) { 1446: console.error(chalk.red("Error: No command provided.")); 1447: process.exit(1); 1448: } 1449: spawnCommand(commandArgs); 1450: return; 1451: } 1452: await handleNamedMode(args); 1453: return; 1454: } 1455: 1456: // `run` subcommand: strip it, rest is parsed as run-mode args 1457: const isRunCommand = args[0] === "run"; 1458: if (isRunCommand) { 1459: args.shift(); 1460: } 1461: 1462: const skipPortless = 1463: process.env.PORTLESS === "0" || 1464: process.env.PORTLESS === "false" || 1465: process.env.PORTLESS === "skip"; 1466: if (skipPortless && (isRunCommand || (args.length >= 2 && args[0] !== "proxy"))) { 1467: const { commandArgs } = isRunCommand ? parseRunArgs(args) : parseAppArgs(args); 1468: if (commandArgs.length === 0) { 1469: console.error(chalk.red("Error: No command provided.")); 1470: process.exit(1); 1471: } 1472: spawnCommand(commandArgs); 1473: return; 1474: } 1475: 1476: // Global dispatch: help, version, trust, list, alias, hosts, proxy 1477: // When `run` is used, skip these so args like "list" or "--help" are treated 1478: // as child-command tokens, not portless subcommands. 1479: if (!isRunCommand) { (Showing lines 1430-1479 of 1526. Use offset=1480 to continue.) ``` ## Assistant Good. Now I'll add the `handleTunnel` command and its dispatch. Let me add it right after `handleAlias`: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 5, "offset": 972 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 972: } 973: 974: async function handleHosts(args: string[]): Promise { 975: if (args[1] === "--help" || args[1] === "-h") { 976: console.log(` (Showing lines 972-976 of 1526. Use offset=977 to continue.) ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": "}\n\nasync function handleTunnel(args: string[]): Promise {\n if (args[1] === \"--help\" || args[1] === \"-h\" || !args[1]) {\n console.log(`\n${chalk.bold(\"portless tunnel\")} - Map external tunnel hostnames to portless apps.\n\n${chalk.bold(\"Usage:\")}\n ${chalk.cyan(\"portless tunnel map \")} Map external hostname to a portless app\n ${chalk.cyan(\"portless tunnel unmap \")} Remove a hostname mapping\n ${chalk.cyan(\"portless tunnel list\")} Show all tunnel mappings\n\n${chalk.bold(\"Examples:\")}\n portless tunnel map myapp abc123.ngrok-free.app\n portless tunnel map api.myapp mysite.trycloudflare.com\n portless tunnel unmap abc123.ngrok-free.app\n portless tunnel list\n\n${chalk.bold(\"How it works:\")}\n When a tunnel provider (ngrok, Cloudflare Tunnel, etc.) forwards traffic\n to the portless proxy, the Host header is the tunnel's public hostname.\n Tunnel mappings tell portless which app to route that traffic to.\n\n Note: with a single app running, portless auto-routes tunnel traffic\n without needing an explicit mapping.\n`);\n process.exit(!args[1] ? 1 : 0);\n }\n\n const { dir, tld } = await discoverState();\n const store = new RouteStore(dir, {\n onWarning: (msg) => console.warn(chalk.yellow(msg)),\n });\n\n if (args[1] === \"list\") {\n const aliases = store.loadAliases();\n const entries = Object.entries(aliases);\n if (entries.length === 0) {\n console.log(chalk.gray(\"No tunnel mappings.\"));\n return;\n }\n console.log(chalk.bold(\"\\nTunnel mappings:\\n\"));\n for (const [external, target] of entries) {\n console.log(` ${chalk.cyan(external)} -> ${chalk.green(target)}`);\n }\n console.log();\n return;\n }\n\n if (args[1] === \"map\") {\n const name = args[2];\n const externalHostname = args[3];\n if (!name || !externalHostname) {\n console.error(chalk.red(\"Error: Missing arguments.\"));\n console.error(chalk.blue(\"Usage:\"));\n console.error(chalk.cyan(\" portless tunnel map \"));\n console.error(chalk.blue(\"Example:\"));\n console.error(chalk.cyan(\" portless tunnel map myapp abc123.ngrok-free.app\"));\n process.exit(1);\n }\n\n const portlessHostname = parseHostname(name, tld);\n\n // Validate that the target route exists\n const routes = store.loadRoutes();\n const routeExists = routes.some((r) => r.hostname === portlessHostname);\n if (!routeExists) {\n console.warn(\n chalk.yellow(\n `Warning: No active route for \"${portlessHostname}\". ` +\n `The mapping will take effect when the app starts.`\n )\n );\n }\n\n store.addAlias(externalHostname, portlessHostname);\n console.log(\n chalk.green(`Tunnel mapped: ${externalHostname} -> ${portlessHostname}`)\n );\n return;\n }\n\n if (args[1] === \"unmap\") {\n const externalHostname = args[2];\n if (!externalHostname) {\n console.error(chalk.red(\"Error: No hostname provided.\"));\n console.error(chalk.cyan(\" portless tunnel unmap \"));\n process.exit(1);\n }\n const removed = store.removeAlias(externalHostname);\n if (!removed) {\n console.error(chalk.red(`Error: No tunnel mapping found for \"${externalHostname}\".`));\n process.exit(1);\n }\n console.log(chalk.green(`Tunnel mapping removed: ${externalHostname}`));\n return;\n }\n\n console.error(chalk.red(`Unknown tunnel subcommand: ${args[1]}`));\n console.error(chalk.cyan(\" portless tunnel --help\"));\n process.exit(1);\n}\n\nasync function handleHosts(args: string[]): Promise {", "oldString": "}\n\nasync function handleHosts(args: string[]): Promise {" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now add the dispatch for `tunnel` in the main function: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " if (args[0] === \"alias\") {\n await handleAlias(args);\n return;\n }\n if (args[0] === \"tunnel\") {\n await handleTunnel(args);\n return;\n }\n if (args[0] === \"hosts\") {", "oldString": " if (args[0] === \"alias\") {\n await handleAlias(args);\n return;\n }\n if (args[0] === \"hosts\") {" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Update the reserved names reference in help text and the comment: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " run, get, alias, tunnel, hosts, list, trust, proxy are subcommands and cannot", "oldString": " run, get, alias, hosts, list, trust, proxy are subcommands and cannot" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " // subcommand dispatch. Useful when the app name collides with a reserved\n // subcommand (run, alias, tunnel, hosts, list, trust, proxy).", "oldString": " // subcommand dispatch. Useful when the app name collides with a reserved\n // subcommand (run, alias, hosts, list, trust, proxy)." } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now typecheck and run tests: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run typecheck 2>&1", "description": "Typecheck Phase 2 changes", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 typecheck /Users/sergiydybskiy/src/portless/packages/portless > tsc --noEmit ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run build 2>&1 && pnpm run test 2>&1", "description": "Build and run all tests", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 build /Users/sergiydybskiy/src/portless/packages/portless > tsup CLI Building entry: src/cli.ts, src/index.ts CLI Using tsconfig: tsconfig.json CLI tsup v8.5.1 CLI Using tsup config: /Users/sergiydybskiy/src/portless/packages/portless/tsup.config.ts CLI Target: es2022 CLI Cleaning output folder ESM Build start ESM dist/cli.js 67.03 KB ESM dist/chunk-WELR34FS.js 183.00 KB ESM dist/index.js 755.00 B ESM ⚡️ Build success in 17ms DTS Build start DTS ⚡️ Build success in 1117ms DTS dist/cli.d.ts 20.00 B DTS dist/index.d.ts 7.17 KB > portless@0.6.0 test /Users/sergiydybskiy/src/portless/packages/portless > vitest run  RUN  v4.0.18 /Users/sergiydybskiy/src/portless/packages/portless ✓ src/utils.test.ts (44 tests) 6ms ✓ src/hosts.test.ts (18 tests) 12ms ✓ src/routes.test.ts (20 tests) 21ms ✓ src/cli-utils.test.ts (46 tests) 25ms ✓ src/auto.test.ts (42 tests) 422ms Certificate request self-signature ok subject=CN=localhost ✓ src/certs.test.ts (18 tests) 966ms ✓ src/cli.test.ts (62 tests) 2753ms (node:45765) [DEP0123] DeprecationWarning: Setting the TLS ServerName to an IP address is not permitted by RFC 6066. This will be ignored in a future version. (Use `node --trace-deprecation ...` to show where the warning was created) ✓ src/proxy.test.ts (37 tests) 8160ms ✓ creates an HTTPS server that responds to requests  1019ms ✓ includes X-Portless header on TLS responses  1004ms ✓ proxies HTTPS request to matching route  1003ms ✓ supports HTTP/2 connections  1007ms ✓ still accepts HTTP/1.1 connections over TLS (allowHTTP1)  1006ms ✓ generates https:// URLs in 404 page  1006ms ✓ sets x-forwarded-proto to https when proxying  1006ms ✓ accepts plain HTTP on the TLS-enabled port  1003ms  Test Files  8 passed (8)  Tests  287 passed (287)  Start at  09:21:38  Duration  8.40s (transform 625ms, setup 0ms, import 802ms, tests 12.37s, environment 0ms) ``` ## Assistant All 287 tests pass. Now Phase 3 -- managed tunnel integration. ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "in_progress" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "pending" }, { "content": "Add tests for all three phases", "priority": "high", "status": "pending" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "in_progress" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "pending" }, { "content": "Add tests for all three phases", "priority": "high", "status": "pending" } ] ``` ## Assistant Now create `tunnel.ts` with the provider abstraction and implementations: ## Assistant ### Tool: write **Args:** ```json { "content": "import { type ChildProcess, spawn, execFileSync } from \"node:child_process\";\n\n/** Timeout (ms) waiting for a tunnel URL to become available. */\nconst TUNNEL_URL_TIMEOUT_MS = 30_000;\n\n/** Polling interval (ms) when checking ngrok's local API for the tunnel URL. */\nconst NGROK_POLL_INTERVAL_MS = 500;\n\nexport interface TunnelProvider {\n /** Display name of the provider (e.g. \"ngrok\", \"cloudflare\"). */\n readonly name: string;\n\n /** Check if the tunnel CLI binary is installed and accessible. */\n isAvailable(): boolean;\n\n /**\n * Start a tunnel pointing at the given local port.\n * Resolves once the public URL is known.\n */\n start(localPort: number): Promise;\n}\n\nexport interface TunnelInstance {\n /** The public tunnel URL (e.g. https://abc123.ngrok-free.app). */\n url: string;\n\n /** The tunnel's child process. */\n process: ChildProcess;\n\n /** Gracefully stop the tunnel. */\n stop(): void;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction isCommandAvailable(command: string): boolean {\n try {\n execFileSync(\"which\", [command], { stdio: \"ignore\" });\n return true;\n } catch {\n return false;\n }\n}\n\nfunction waitForOutput(\n proc: ChildProcess,\n pattern: RegExp,\n stream: \"stdout\" | \"stderr\",\n timeoutMs: number\n): Promise {\n return new Promise((resolve, reject) => {\n const timer = setTimeout(() => {\n reject(new Error(`Timed out waiting for tunnel URL (${timeoutMs}ms)`));\n }, timeoutMs);\n\n const source = stream === \"stdout\" ? proc.stdout : proc.stderr;\n if (!source) {\n clearTimeout(timer);\n reject(new Error(`No ${stream} stream on tunnel process`));\n return;\n }\n\n let buffer = \"\";\n const onData = (chunk: Buffer) => {\n buffer += chunk.toString();\n const match = pattern.exec(buffer);\n if (match) {\n clearTimeout(timer);\n source.removeListener(\"data\", onData);\n resolve(match[1] || match[0]);\n }\n };\n source.on(\"data\", onData);\n\n proc.on(\"exit\", (code) => {\n clearTimeout(timer);\n source.removeListener(\"data\", onData);\n reject(new Error(`Tunnel process exited with code ${code} before URL was available`));\n });\n });\n}\n\n// ---------------------------------------------------------------------------\n// ngrok provider\n// ---------------------------------------------------------------------------\n\n/**\n * ngrok tunnel provider.\n *\n * Starts `ngrok http ` and discovers the public URL by polling ngrok's\n * local management API at http://127.0.0.1:4040/api/tunnels.\n */\nexport const ngrokProvider: TunnelProvider = {\n name: \"ngrok\",\n\n isAvailable(): boolean {\n return isCommandAvailable(\"ngrok\");\n },\n\n async start(localPort: number): Promise {\n const proc = spawn(\"ngrok\", [\"http\", String(localPort), \"--log=stdout\", \"--log-format=json\"], {\n stdio: [\"ignore\", \"pipe\", \"pipe\"],\n });\n\n // ngrok exposes a local API -- poll it for the tunnel URL\n const url = await pollNgrokApi(proc, TUNNEL_URL_TIMEOUT_MS);\n\n return {\n url,\n process: proc,\n stop() {\n if (!proc.killed) {\n proc.kill(\"SIGTERM\");\n }\n },\n };\n },\n};\n\nasync function pollNgrokApi(proc: ChildProcess, timeoutMs: number): Promise {\n const deadline = Date.now() + timeoutMs;\n\n while (Date.now() < deadline) {\n // Check if process died\n if (proc.exitCode !== null) {\n throw new Error(`ngrok exited with code ${proc.exitCode} before tunnel was ready`);\n }\n\n try {\n const res = await fetch(\"http://127.0.0.1:4040/api/tunnels\");\n if (res.ok) {\n const data = (await res.json()) as {\n tunnels: Array<{ public_url: string; proto: string }>;\n };\n // Prefer HTTPS tunnel\n const httpsTunnel = data.tunnels.find((t) => t.proto === \"https\");\n const tunnel = httpsTunnel || data.tunnels[0];\n if (tunnel?.public_url) {\n return tunnel.public_url;\n }\n }\n } catch {\n // API not ready yet; retry\n }\n\n await new Promise((resolve) => setTimeout(resolve, NGROK_POLL_INTERVAL_MS));\n }\n\n throw new Error(`Timed out waiting for ngrok tunnel URL (${timeoutMs}ms)`);\n}\n\n// ---------------------------------------------------------------------------\n// Cloudflare Tunnel provider\n// ---------------------------------------------------------------------------\n\n/**\n * Cloudflare Tunnel (cloudflared) provider.\n *\n * Starts `cloudflared tunnel --url http://localhost:` and parses the\n * public URL from stderr output (cloudflared prints it during startup).\n */\nexport const cloudflareProvider: TunnelProvider = {\n name: \"cloudflare\",\n\n isAvailable(): boolean {\n return isCommandAvailable(\"cloudflared\");\n },\n\n async start(localPort: number): Promise {\n const proc = spawn(\"cloudflared\", [\"tunnel\", \"--url\", `http://localhost:${localPort}`], {\n stdio: [\"ignore\", \"pipe\", \"pipe\"],\n });\n\n // cloudflared prints the URL to stderr like:\n // ... | INF +-----------------------------------------------------------+\n // ... | INF | Your quick Tunnel has been created! Visit it at (it may |\n // ... | INF | take some time to be reachable): |\n // ... | INF | https://random-words.trycloudflare.com |\n // ... | INF +-----------------------------------------------------------+\n const url = await waitForOutput(\n proc,\n /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/,\n \"stderr\",\n TUNNEL_URL_TIMEOUT_MS\n );\n\n return {\n url,\n process: proc,\n stop() {\n if (!proc.killed) {\n proc.kill(\"SIGTERM\");\n }\n },\n };\n },\n};\n\n// ---------------------------------------------------------------------------\n// Provider registry\n// ---------------------------------------------------------------------------\n\nconst providers: Record = {\n ngrok: ngrokProvider,\n cloudflare: cloudflareProvider,\n};\n\n/** Known provider names. */\nexport const TUNNEL_PROVIDERS = Object.keys(providers);\n\n/**\n * Get a tunnel provider by name.\n * Returns undefined if the provider is not known.\n */\nexport function getTunnelProvider(name: string): TunnelProvider | undefined {\n return providers[name];\n}\n", "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/tunnel.ts" } ``` ## Assistant **Result** (success): ``` Wrote file successfully. ``` ## Assistant Now export it from `index.ts`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/index.ts", "newString": "export * from \"./types.js\";\nexport * from \"./proxy.js\";\nexport * from \"./routes.js\";\nexport * from \"./utils.js\";\nexport * from \"./hosts.js\";\nexport * from \"./tunnel.js\";", "oldString": "export * from \"./types.js\";\nexport * from \"./proxy.js\";\nexport * from \"./routes.js\";\nexport * from \"./utils.js\";\nexport * from \"./hosts.js\";" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now wire the `--tunnel` flag into `cli.ts`. I need to modify the arg parsing and `runApp` function. Let me read the arg parsing for named mode: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 60, "offset": 540 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 540: /** Fixed app port (overrides automatic assignment). */ 541: appPort?: number; 542: /** Override the inferred base name (from --name flag). */ 543: name?: string; 544: /** The child command and its arguments, passed through untouched. */ 545: commandArgs: string[]; 546: } 547: 548: interface ParsedAppArgs extends ParsedRunArgs { 549: /** App name. */ 550: name: string; 551: } 552: 553: function parseAppPort(value: string | undefined): number { 554: if (!value || value.startsWith("--")) { 555: console.error(chalk.red("Error: --app-port requires a port number.")); 556: process.exit(1); 557: } 558: const port = parseInt(value, 10); 559: if (isNaN(port) || port < 1 || port > 65535) { 560: console.error(chalk.red(`Error: Invalid app port "${value}". Must be 1-65535.`)); 561: process.exit(1); 562: } 563: return port; 564: } 565: 566: function appPortFromEnv(): number | undefined { 567: const envVal = process.env.PORTLESS_APP_PORT; 568: if (!envVal) return undefined; 569: const port = parseInt(envVal, 10); 570: if (isNaN(port) || port < 1 || port > 65535) { 571: console.error(chalk.red(`Error: Invalid PORTLESS_APP_PORT="${envVal}". Must be 1-65535.`)); 572: process.exit(1); 573: } 574: return port; 575: } 576: 577: /** 578: * Parse `run` subcommand arguments: `[--name ] [--force] [--] ` 579: * 580: * `--name`, `--force`, and `--app-port` are recognized. `--` stops flag 581: * parsing. Everything after the flag region is the child command, passed 582: * through untouched. 583: */ 584: function parseRunArgs(args: string[]): ParsedRunArgs { 585: let force = false; 586: let appPort: number | undefined; 587: let name: string | undefined; 588: let i = 0; 589: 590: while (i < args.length && args[i].startsWith("-")) { 591: if (args[i] === "--") { 592: i++; 593: break; 594: } else if (args[i] === "--help" || args[i] === "-h") { 595: console.log(` 596: ${chalk.bold("portless run")} - Infer project name and run through the proxy. 597: 598: ${chalk.bold("Usage:")} 599: ${chalk.cyan("portless run [options] ")} (Showing lines 540-599 of 1629. Use offset=600 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 80, "offset": 600 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 600: 601: ${chalk.bold("Options:")} 602: --name Override the inferred base name (worktree prefix still applies) 603: --force Override an existing route registered by another process 604: --app-port Use a fixed port for the app (skip auto-assignment) 605: --help, -h Show this help 606: 607: ${chalk.bold("Name inference (in order):")} 608: 1. package.json "name" field (walks up directories) 609: 2. Git repo root directory name 610: 3. Current directory basename 611: 612: Use --name to override the inferred name while keeping worktree prefixes. 613: In git worktrees, the branch name is prepended as a subdomain prefix 614: (e.g. feature-auth.myapp.localhost). 615: 616: ${chalk.bold("Examples:")} 617: portless run next dev # -> http://.localhost:1355 618: portless run --name myapp next dev # -> http://myapp.localhost:1355 619: portless run vite dev # -> http://.localhost:1355 620: portless run --app-port 3000 pnpm start 621: `); 622: process.exit(0); 623: } else if (args[i] === "--force") { 624: force = true; 625: } else if (args[i] === "--app-port") { 626: i++; 627: appPort = parseAppPort(args[i]); 628: } else if (args[i] === "--name") { 629: i++; 630: if (!args[i] || args[i].startsWith("-")) { 631: console.error(chalk.red("Error: --name requires a name value.")); 632: console.error(chalk.cyan(" portless run --name ")); 633: process.exit(1); 634: } 635: name = args[i]; 636: } else { 637: console.error(chalk.red(`Error: Unknown flag "${args[i]}".`)); 638: console.error(chalk.blue("Known flags: --name, --force, --app-port, --help")); 639: process.exit(1); 640: } 641: i++; 642: } 643: 644: if (!appPort) appPort = appPortFromEnv(); 645: 646: return { force, appPort, name, commandArgs: args.slice(i) }; 647: } 648: 649: /** 650: * Parse named-mode arguments: `[--force] [--force] [--] ` 651: * 652: * `--force` is recognized before and after the name. `--` stops flag 653: * parsing. Everything after the flag region is the child command. 654: * Unrecognized `--` flags are rejected to catch typos. 655: */ 656: function parseAppArgs(args: string[]): ParsedAppArgs { 657: let force = false; 658: let appPort: number | undefined; 659: let i = 0; 660: 661: // Consume leading flags before name 662: while (i < args.length && args[i].startsWith("-")) { 663: if (args[i] === "--") { 664: i++; 665: break; 666: } else if (args[i] === "--force") { 667: force = true; 668: } else if (args[i] === "--app-port") { 669: i++; 670: appPort = parseAppPort(args[i]); 671: } else { 672: console.error(chalk.red(`Error: Unknown flag "${args[i]}".`)); 673: console.error(chalk.blue("Known flags: --force, --app-port")); 674: process.exit(1); 675: } 676: i++; 677: } 678: 679: // Next token is the app name (Showing lines 600-679 of 1629. Use offset=680 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 60, "offset": 680 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 680: const name = args[i]; 681: i++; 682: 683: // Allow flags immediately after name (e.g. `portless myapp --force next dev`) 684: while (i < args.length && args[i].startsWith("--")) { 685: if (args[i] === "--") { 686: i++; 687: break; 688: } else if (args[i] === "--force") { 689: force = true; 690: } else if (args[i] === "--app-port") { 691: i++; 692: appPort = parseAppPort(args[i]); 693: } else { 694: console.error(chalk.red(`Error: Unknown flag "${args[i]}".`)); 695: console.error(chalk.blue("Known flags: --force, --app-port")); 696: process.exit(1); 697: } 698: i++; 699: } 700: 701: if (!appPort) appPort = appPortFromEnv(); 702: 703: return { force, appPort, name, commandArgs: args.slice(i) }; 704: } 705: 706: // --------------------------------------------------------------------------- 707: // Subcommand handlers 708: // --------------------------------------------------------------------------- 709: 710: function printHelp(): void { 711: console.log(` 712: ${chalk.bold("portless")} - Replace port numbers with stable, named .localhost URLs. For humans and agents. 713: 714: Eliminates port conflicts, memorizing port numbers, and cookie/storage 715: clashes by giving each dev server a stable .localhost URL. 716: 717: ${chalk.bold("Install:")} 718: ${chalk.cyan("npm install -g portless")} 719: Do NOT add portless as a project dependency. 720: 721: ${chalk.bold("Usage:")} 722: ${chalk.cyan("portless proxy start")} Start the proxy (background daemon) 723: ${chalk.cyan("portless proxy start --https")} Start with HTTP/2 + TLS (auto-generates certs) 724: ${chalk.cyan("portless proxy start -p 80")} Start on port 80 (requires sudo) 725: ${chalk.cyan("portless proxy stop")} Stop the proxy 726: ${chalk.cyan("portless ")} Run your app through the proxy 727: ${chalk.cyan("portless run ")} Infer name from project, run through proxy 728: ${chalk.cyan("portless get ")} Print URL for a service (for cross-service refs) 729: ${chalk.cyan("portless alias ")} Register a static route (e.g. for Docker) 730: ${chalk.cyan("portless alias --remove ")} Remove a static route 731: ${chalk.cyan("portless list")} Show active routes 732: ${chalk.cyan("portless trust")} Add local CA to system trust store 733: ${chalk.cyan("portless hosts sync")} Add routes to /etc/hosts (fixes Safari) 734: ${chalk.cyan("portless hosts clean")} Remove portless entries from /etc/hosts 735: 736: ${chalk.bold("Examples:")} 737: portless proxy start # Start proxy on port 1355 738: portless proxy start --https # Start with HTTPS/2 (faster page loads) 739: portless myapp next dev # -> http://myapp.localhost:1355 (Showing lines 680-739 of 1629. Use offset=740 to continue.) ``` ## Assistant I need to add `--tunnel` to `ParsedRunArgs` and both parse functions. Let me update the interfaces and parsing: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": "interface ParsedRunArgs {\n /** Whether --force was specified. */\n force: boolean;\n /** Fixed app port (overrides automatic assignment). */\n appPort?: number;\n /** Override the inferred base name (from --name flag). */\n name?: string;\n /** Tunnel provider name (e.g. \"ngrok\", \"cloudflare\"). */\n tunnel?: string;\n /** The child command and its arguments, passed through untouched. */\n commandArgs: string[];\n}", "oldString": "interface ParsedRunArgs {\n /** Whether --force was specified. */\n force: boolean;\n /** Fixed app port (overrides automatic assignment). */\n appPort?: number;\n /** Override the inferred base name (from --name flag). */\n name?: string;\n /** The child command and its arguments, passed through untouched. */\n commandArgs: string[];\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now update `parseRunArgs` to accept `--tunnel`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": "function parseRunArgs(args: string[]): ParsedRunArgs {\n let force = false;\n let appPort: number | undefined;\n let name: string | undefined;\n let tunnel: string | undefined;\n let i = 0;\n\n while (i < args.length && args[i].startsWith(\"-\")) {\n if (args[i] === \"--\") {\n i++;\n break;\n } else if (args[i] === \"--help\" || args[i] === \"-h\") {\n console.log(`\n${chalk.bold(\"portless run\")} - Infer project name and run through the proxy.\n\n${chalk.bold(\"Usage:\")}\n ${chalk.cyan(\"portless run [options] \")}\n\n${chalk.bold(\"Options:\")}\n --name Override the inferred base name (worktree prefix still applies)\n --force Override an existing route registered by another process\n --app-port Use a fixed port for the app (skip auto-assignment)\n --tunnel Start a tunnel (ngrok, cloudflare)\n --help, -h Show this help\n\n${chalk.bold(\"Name inference (in order):\")}\n 1. package.json \"name\" field (walks up directories)\n 2. Git repo root directory name\n 3. Current directory basename\n\n Use --name to override the inferred name while keeping worktree prefixes.\n In git worktrees, the branch name is prepended as a subdomain prefix\n (e.g. feature-auth.myapp.localhost).\n\n${chalk.bold(\"Examples:\")}\n portless run next dev # -> http://.localhost:1355\n portless run --name myapp next dev # -> http://myapp.localhost:1355\n portless run vite dev # -> http://.localhost:1355\n portless run --app-port 3000 pnpm start\n portless run --tunnel ngrok next dev\n`);\n process.exit(0);\n } else if (args[i] === \"--force\") {\n force = true;\n } else if (args[i] === \"--app-port\") {\n i++;\n appPort = parseAppPort(args[i]);\n } else if (args[i] === \"--tunnel\") {\n i++;\n tunnel = parseTunnelArg(args[i]);\n } else if (args[i] === \"--name\") {\n i++;\n if (!args[i] || args[i].startsWith(\"-\")) {\n console.error(chalk.red(\"Error: --name requires a name value.\"));\n console.error(chalk.cyan(\" portless run --name \"));\n process.exit(1);\n }\n name = args[i];\n } else {\n console.error(chalk.red(`Error: Unknown flag \"${args[i]}\".`));\n console.error(chalk.blue(\"Known flags: --name, --force, --app-port, --tunnel, --help\"));\n process.exit(1);\n }\n i++;\n }\n\n if (!appPort) appPort = appPortFromEnv();\n if (!tunnel) tunnel = tunnelFromEnv();\n\n return { force, appPort, name, tunnel, commandArgs: args.slice(i) };\n}", "oldString": "function parseRunArgs(args: string[]): ParsedRunArgs {\n let force = false;\n let appPort: number | undefined;\n let name: string | undefined;\n let i = 0;\n\n while (i < args.length && args[i].startsWith(\"-\")) {\n if (args[i] === \"--\") {\n i++;\n break;\n } else if (args[i] === \"--help\" || args[i] === \"-h\") {\n console.log(`\n${chalk.bold(\"portless run\")} - Infer project name and run through the proxy.\n\n${chalk.bold(\"Usage:\")}\n ${chalk.cyan(\"portless run [options] \")}\n\n${chalk.bold(\"Options:\")}\n --name Override the inferred base name (worktree prefix still applies)\n --force Override an existing route registered by another process\n --app-port Use a fixed port for the app (skip auto-assignment)\n --help, -h Show this help\n\n${chalk.bold(\"Name inference (in order):\")}\n 1. package.json \"name\" field (walks up directories)\n 2. Git repo root directory name\n 3. Current directory basename\n\n Use --name to override the inferred name while keeping worktree prefixes.\n In git worktrees, the branch name is prepended as a subdomain prefix\n (e.g. feature-auth.myapp.localhost).\n\n${chalk.bold(\"Examples:\")}\n portless run next dev # -> http://.localhost:1355\n portless run --name myapp next dev # -> http://myapp.localhost:1355\n portless run vite dev # -> http://.localhost:1355\n portless run --app-port 3000 pnpm start\n`);\n process.exit(0);\n } else if (args[i] === \"--force\") {\n force = true;\n } else if (args[i] === \"--app-port\") {\n i++;\n appPort = parseAppPort(args[i]);\n } else if (args[i] === \"--name\") {\n i++;\n if (!args[i] || args[i].startsWith(\"-\")) {\n console.error(chalk.red(\"Error: --name requires a name value.\"));\n console.error(chalk.cyan(\" portless run --name \"));\n process.exit(1);\n }\n name = args[i];\n } else {\n console.error(chalk.red(`Error: Unknown flag \"${args[i]}\".`));\n console.error(chalk.blue(\"Known flags: --name, --force, --app-port, --help\"));\n process.exit(1);\n }\n i++;\n }\n\n if (!appPort) appPort = appPortFromEnv();\n\n return { force, appPort, name, commandArgs: args.slice(i) };\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now update `parseAppArgs` similarly: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": "function parseAppArgs(args: string[]): ParsedAppArgs {\n let force = false;\n let appPort: number | undefined;\n let tunnel: string | undefined;\n let i = 0;\n\n // Consume leading flags before name\n while (i < args.length && args[i].startsWith(\"-\")) {\n if (args[i] === \"--\") {\n i++;\n break;\n } else if (args[i] === \"--force\") {\n force = true;\n } else if (args[i] === \"--app-port\") {\n i++;\n appPort = parseAppPort(args[i]);\n } else if (args[i] === \"--tunnel\") {\n i++;\n tunnel = parseTunnelArg(args[i]);\n } else {\n console.error(chalk.red(`Error: Unknown flag \"${args[i]}\".`));\n console.error(chalk.blue(\"Known flags: --force, --app-port, --tunnel\"));\n process.exit(1);\n }\n i++;\n }\n\n // Next token is the app name", "oldString": "function parseAppArgs(args: string[]): ParsedAppArgs {\n let force = false;\n let appPort: number | undefined;\n let i = 0;\n\n // Consume leading flags before name\n while (i < args.length && args[i].startsWith(\"-\")) {\n if (args[i] === \"--\") {\n i++;\n break;\n } else if (args[i] === \"--force\") {\n force = true;\n } else if (args[i] === \"--app-port\") {\n i++;\n appPort = parseAppPort(args[i]);\n } else {\n console.error(chalk.red(`Error: Unknown flag \"${args[i]}\".`));\n console.error(chalk.blue(\"Known flags: --force, --app-port\"));\n process.exit(1);\n }\n i++;\n }\n\n // Next token is the app name" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now find the post-name flag parsing in `parseAppArgs`: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 30, "offset": 694 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 694: const name = args[i]; 695: i++; 696: 697: // Allow flags immediately after name (e.g. `portless myapp --force next dev`) 698: while (i < args.length && args[i].startsWith("--")) { 699: if (args[i] === "--") { 700: i++; 701: break; 702: } else if (args[i] === "--force") { 703: force = true; 704: } else if (args[i] === "--app-port") { 705: i++; 706: appPort = parseAppPort(args[i]); 707: } else { 708: console.error(chalk.red(`Error: Unknown flag "${args[i]}".`)); 709: console.error(chalk.blue("Known flags: --force, --app-port")); 710: process.exit(1); 711: } 712: i++; 713: } 714: 715: if (!appPort) appPort = appPortFromEnv(); 716: 717: return { force, appPort, name, commandArgs: args.slice(i) }; 718: } 719: 720: // --------------------------------------------------------------------------- 721: // Subcommand handlers 722: // --------------------------------------------------------------------------- 723: (Showing lines 694-723 of 1643. Use offset=724 to continue.) ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " // Allow flags immediately after name (e.g. `portless myapp --force next dev`)\n while (i < args.length && args[i].startsWith(\"--\")) {\n if (args[i] === \"--\") {\n i++;\n break;\n } else if (args[i] === \"--force\") {\n force = true;\n } else if (args[i] === \"--app-port\") {\n i++;\n appPort = parseAppPort(args[i]);\n } else if (args[i] === \"--tunnel\") {\n i++;\n tunnel = parseTunnelArg(args[i]);\n } else {\n console.error(chalk.red(`Error: Unknown flag \"${args[i]}\".`));\n console.error(chalk.blue(\"Known flags: --force, --app-port, --tunnel\"));\n process.exit(1);\n }\n i++;\n }\n\n if (!appPort) appPort = appPortFromEnv();\n if (!tunnel) tunnel = tunnelFromEnv();\n\n return { force, appPort, tunnel, name, commandArgs: args.slice(i) };\n}", "oldString": " // Allow flags immediately after name (e.g. `portless myapp --force next dev`)\n while (i < args.length && args[i].startsWith(\"--\")) {\n if (args[i] === \"--\") {\n i++;\n break;\n } else if (args[i] === \"--force\") {\n force = true;\n } else if (args[i] === \"--app-port\") {\n i++;\n appPort = parseAppPort(args[i]);\n } else {\n console.error(chalk.red(`Error: Unknown flag \"${args[i]}\".`));\n console.error(chalk.blue(\"Known flags: --force, --app-port\"));\n process.exit(1);\n }\n i++;\n }\n\n if (!appPort) appPort = appPortFromEnv();\n\n return { force, appPort, name, commandArgs: args.slice(i) };\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now add the `parseTunnelArg` and `tunnelFromEnv` helper functions. Let me find a good place to add them near the other parse helpers: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": "function appPortFromEnv(): number | undefined {\n const envVal = process.env.PORTLESS_APP_PORT;\n if (!envVal) return undefined;\n const port = parseInt(envVal, 10);\n if (isNaN(port) || port < 1 || port > 65535) {\n console.error(chalk.red(`Error: Invalid PORTLESS_APP_PORT=\"${envVal}\". Must be 1-65535.`));\n process.exit(1);\n }\n return port;\n}\n\nfunction parseTunnelArg(value: string | undefined): string {\n if (!value || value.startsWith(\"-\")) {\n console.error(chalk.red(\"Error: --tunnel requires a provider name.\"));\n console.error(chalk.blue(`Available providers: ${TUNNEL_PROVIDERS.join(\", \")}`));\n process.exit(1);\n }\n const provider = getTunnelProvider(value);\n if (!provider) {\n console.error(chalk.red(`Error: Unknown tunnel provider \"${value}\".`));\n console.error(chalk.blue(`Available providers: ${TUNNEL_PROVIDERS.join(\", \")}`));\n process.exit(1);\n }\n return value;\n}\n\nfunction tunnelFromEnv(): string | undefined {\n const envVal = process.env.PORTLESS_TUNNEL;\n if (!envVal) return undefined;\n const provider = getTunnelProvider(envVal);\n if (!provider) {\n console.error(chalk.red(`Error: Unknown PORTLESS_TUNNEL=\"${envVal}\".`));\n console.error(chalk.blue(`Available providers: ${TUNNEL_PROVIDERS.join(\", \")}`));\n process.exit(1);\n }\n return envVal;\n}", "oldString": "function appPortFromEnv(): number | undefined {\n const envVal = process.env.PORTLESS_APP_PORT;\n if (!envVal) return undefined;\n const port = parseInt(envVal, 10);\n if (isNaN(port) || port < 1 || port > 65535) {\n console.error(chalk.red(`Error: Invalid PORTLESS_APP_PORT=\"${envVal}\". Must be 1-65535.`));\n process.exit(1);\n }\n return port;\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now add the import for tunnel at the top of cli.ts: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 20 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 1: #!/usr/bin/env node 2: 3: declare const __VERSION__: string; 4: 5: import chalk from "chalk"; 6: import * as fs from "node:fs"; 7: import * as path from "node:path"; 8: import { spawn, spawnSync } from "node:child_process"; 9: import { createSNICallback, ensureCerts, isCATrusted, trustCA } from "./certs.js"; 10: import { createProxyServer } from "./proxy.js"; 11: import { fixOwnership, formatUrl, isErrnoException, parseHostname } from "./utils.js"; 12: import { syncHostsFile, cleanHostsFile } from "./hosts.js"; 13: import { FILE_MODE, RouteConflictError, RouteStore } from "./routes.js"; 14: import { inferProjectName, detectWorktreePrefix, sanitizeForHostname } from "./auto.js"; 15: import { 16: DEFAULT_TLD, 17: PRIVILEGED_PORT_THRESHOLD, 18: RISKY_TLDS, 19: discoverState, 20: findFreePort, (Showing lines 1-20 of 1674. Use offset=21 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 20, "offset": 20 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 20: findFreePort, 21: findPidOnPort, 22: getDefaultPort, 23: getDefaultTld, 24: injectFrameworkFlags, 25: isHttpsEnvEnabled, 26: isProxyRunning, 27: prompt, 28: readTldFromDir, 29: readTlsMarker, 30: resolveStateDir, 31: spawnCommand, 32: validateTld, 33: waitForProxy, 34: writeTldFile, 35: writeTlsMarker, 36: } from "./cli-utils.js"; 37: 38: // --------------------------------------------------------------------------- 39: // Constants (Showing lines 20-39 of 1674. Use offset=40 to continue.) ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": "import { FILE_MODE, RouteConflictError, RouteStore } from \"./routes.js\";\nimport { inferProjectName, detectWorktreePrefix, sanitizeForHostname } from \"./auto.js\";\nimport { getTunnelProvider, TUNNEL_PROVIDERS } from \"./tunnel.js\";\nimport type { TunnelInstance } from \"./tunnel.js\";", "oldString": "import { FILE_MODE, RouteConflictError, RouteStore } from \"./routes.js\";\nimport { inferProjectName, detectWorktreePrefix, sanitizeForHostname } from \"./auto.js\";" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now update the `runApp` function to accept and handle the tunnel parameter. Let me read its current signature: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 15, "offset": 325 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 325: } catch { 326: // Port file may already be removed; non-fatal 327: } 328: console.log(chalk.green("Proxy stopped.")); 329: } catch (err: unknown) { 330: if (isErrnoException(err) && err.code === "EPERM") { 331: console.error(chalk.red("Permission denied. The proxy was started with sudo.")); 332: console.error(chalk.blue("Stop it with:")); 333: console.error(chalk.cyan(` ${sudoHint}portless proxy stop`)); 334: } else { 335: const message = err instanceof Error ? err.message : String(err); 336: console.error(chalk.red(`Failed to stop proxy: ${message}`)); 337: console.error(chalk.blue("Check if the process is still running:")); 338: console.error(chalk.cyan(` lsof -ti tcp:${proxyPort}`)); 339: } (Showing lines 325-339 of 1676. Use offset=340 to continue.) ``` ## Assistant ### Tool: grep **Args:** ```json { "include": "cli.ts", "pattern": "^async function runApp" } ``` ## Assistant **Result** (success): ``` Found 1 matches /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts: Line 363: async function runApp( ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 20, "offset": 363 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 363: async function runApp( 364: store: RouteStore, 365: proxyPort: number, 366: stateDir: string, 367: name: string, 368: commandArgs: string[], 369: tls: boolean, 370: tld: string, 371: force: boolean, 372: autoInfo?: { nameSource: string; prefix?: string; prefixSource?: string }, 373: desiredPort?: number 374: ) { 375: const hostname = parseHostname(name, tld); 376: 377: let envTld: string; 378: try { 379: envTld = getDefaultTld(); 380: } catch (err) { 381: console.error(chalk.red(`Error: ${(err as Error).message}`)); 382: process.exit(1); (Showing lines 363-382 of 1676. Use offset=383 to continue.) ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": "async function runApp(\n store: RouteStore,\n proxyPort: number,\n stateDir: string,\n name: string,\n commandArgs: string[],\n tls: boolean,\n tld: string,\n force: boolean,\n autoInfo?: { nameSource: string; prefix?: string; prefixSource?: string },\n desiredPort?: number,\n tunnelProviderName?: string\n) {", "oldString": "async function runApp(\n store: RouteStore,\n proxyPort: number,\n stateDir: string,\n name: string,\n commandArgs: string[],\n tls: boolean,\n tld: string,\n force: boolean,\n autoInfo?: { nameSource: string; prefix?: string; prefixSource?: string },\n desiredPort?: number\n) {" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now add the tunnel logic in `runApp` after the route registration and URL computation, before spawning the command. Let me read that section: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 50, "offset": 495 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 495: // Register route 496: try { 497: store.addRoute(hostname, port, process.pid, force); 498: } catch (err) { 499: if (err instanceof RouteConflictError) { 500: console.error(chalk.red(`Error: ${err.message}`)); 501: process.exit(1); 502: } 503: throw err; 504: } 505: 506: const finalUrl = formatUrl(hostname, proxyPort, tls); 507: console.log(chalk.cyan.bold(`\n -> ${finalUrl}\n`)); 508: 509: // Inject --port for frameworks that ignore the PORT env var (e.g. Vite) 510: injectFrameworkFlags(commandArgs, port); 511: 512: // Run the command 513: console.log( 514: chalk.gray( 515: `Running: PORT=${port} HOST=127.0.0.1 PORTLESS_URL=${finalUrl} ${commandArgs.join(" ")}\n` 516: ) 517: ); 518: 519: spawnCommand(commandArgs, { 520: env: { 521: ...process.env, 522: PORT: port.toString(), 523: HOST: "127.0.0.1", 524: PORTLESS_URL: finalUrl, 525: __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: `.${tld}`, 526: }, 527: onCleanup: () => { 528: try { 529: store.removeRoute(hostname); 530: } catch { 531: // Lock acquisition may fail during cleanup; non-fatal 532: } 533: }, 534: }); 535: } 536: 537: // --------------------------------------------------------------------------- 538: // Argument parsing 539: // --------------------------------------------------------------------------- 540: 541: interface ParsedRunArgs { 542: /** Whether --force was specified. */ 543: force: boolean; 544: /** Fixed app port (overrides automatic assignment). */ (Showing lines 495-544 of 1677. Use offset=545 to continue.) ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " const finalUrl = formatUrl(hostname, proxyPort, tls);\n console.log(chalk.cyan.bold(`\\n -> ${finalUrl}`));\n\n // Start tunnel if requested\n let tunnelInstance: TunnelInstance | undefined;\n let tunnelUrl: string | undefined;\n if (tunnelProviderName) {\n const provider = getTunnelProvider(tunnelProviderName);\n if (!provider) {\n console.error(chalk.red(`Error: Unknown tunnel provider \"${tunnelProviderName}\".`));\n process.exit(1);\n }\n if (!provider.isAvailable()) {\n console.error(chalk.red(`Error: ${tunnelProviderName} is not installed.`));\n console.error(chalk.blue(`Install it first:`));\n if (tunnelProviderName === \"ngrok\") {\n console.error(chalk.cyan(\" https://ngrok.com/download\"));\n } else if (tunnelProviderName === \"cloudflare\") {\n console.error(chalk.cyan(\" https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/\"));\n }\n process.exit(1);\n }\n\n console.log(chalk.gray(`\\n-- Starting ${tunnelProviderName} tunnel...`));\n try {\n tunnelInstance = await provider.start(proxyPort);\n tunnelUrl = tunnelInstance.url;\n\n // Register alias so the proxy routes tunnel traffic correctly\n const tunnelHostname = new URL(tunnelUrl).hostname;\n store.addAlias(tunnelHostname, hostname);\n\n console.log(chalk.cyan.bold(` -> ${tunnelUrl} (tunnel)`));\n } catch (err) {\n console.error(chalk.red(`Error starting tunnel: ${(err as Error).message}`));\n try {\n store.removeRoute(hostname);\n } catch {\n // Non-fatal\n }\n process.exit(1);\n }\n }\n\n console.log();\n\n // Inject --port for frameworks that ignore the PORT env var (e.g. Vite)\n injectFrameworkFlags(commandArgs, port);\n\n // Build environment variables for the child process\n const childEnv: Record = {\n ...process.env as Record,\n PORT: port.toString(),\n HOST: \"127.0.0.1\",\n PORTLESS_URL: finalUrl,\n __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: `.${tld}`,\n };\n if (tunnelUrl) {\n childEnv.PORTLESS_TUNNEL_URL = tunnelUrl;\n }\n\n // Run the command\n const tunnelEnvStr = tunnelUrl ? ` PORTLESS_TUNNEL_URL=${tunnelUrl}` : \"\";\n console.log(\n chalk.gray(\n `Running: PORT=${port} HOST=127.0.0.1 PORTLESS_URL=${finalUrl}${tunnelEnvStr} ${commandArgs.join(\" \")}\\n`\n )\n );\n\n spawnCommand(commandArgs, {\n env: childEnv,\n onCleanup: () => {\n // Stop tunnel first\n if (tunnelInstance) {\n tunnelInstance.stop();\n try {\n if (tunnelUrl) {\n const tunnelHostname = new URL(tunnelUrl).hostname;\n store.removeAlias(tunnelHostname);\n }\n } catch {\n // Non-fatal\n }\n }\n try {\n store.removeRoute(hostname);\n } catch {\n // Lock acquisition may fail during cleanup; non-fatal\n }\n },\n });\n}", "oldString": " const finalUrl = formatUrl(hostname, proxyPort, tls);\n console.log(chalk.cyan.bold(`\\n -> ${finalUrl}\\n`));\n\n // Inject --port for frameworks that ignore the PORT env var (e.g. Vite)\n injectFrameworkFlags(commandArgs, port);\n\n // Run the command\n console.log(\n chalk.gray(\n `Running: PORT=${port} HOST=127.0.0.1 PORTLESS_URL=${finalUrl} ${commandArgs.join(\" \")}\\n`\n )\n );\n\n spawnCommand(commandArgs, {\n env: {\n ...process.env,\n PORT: port.toString(),\n HOST: \"127.0.0.1\",\n PORTLESS_URL: finalUrl,\n __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS: `.${tld}`,\n },\n onCleanup: () => {\n try {\n store.removeRoute(hostname);\n } catch {\n // Lock acquisition may fail during cleanup; non-fatal\n }\n },\n });\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now I need to thread the `tunnel` parameter through the callers of `runApp`. Let me find them: ## Assistant ### Tool: grep **Args:** ```json { "include": "cli.ts", "pattern": "runApp\\(" } ``` ## Assistant **Result** (success): ``` Found 3 matches /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts: Line 363: async function runApp( Line 1569: await runApp( Line 1599: await runApp( ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 50, "offset": 1550 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 1550: if (!sanitized) { 1551: console.error(chalk.red(`Error: --name value "${parsed.name}" produces an empty hostname.`)); 1552: process.exit(1); 1553: } 1554: baseName = sanitized; 1555: nameSource = "--name flag"; 1556: } else { 1557: const inferred = inferProjectName(); 1558: baseName = inferred.name; 1559: nameSource = inferred.source; 1560: } 1561: 1562: const worktree = detectWorktreePrefix(); 1563: const effectiveName = worktree ? `${worktree.prefix}.${baseName}` : baseName; 1564: 1565: const { dir, port, tls, tld } = await discoverState(); 1566: const store = new RouteStore(dir, { 1567: onWarning: (msg) => console.warn(chalk.yellow(msg)), 1568: }); 1569: await runApp( 1570: store, 1571: port, 1572: dir, 1573: effectiveName, 1574: parsed.commandArgs, 1575: tls, 1576: tld, 1577: parsed.force, 1578: { nameSource, prefix: worktree?.prefix, prefixSource: worktree?.source }, 1579: parsed.appPort 1580: ); 1581: } 1582: 1583: async function handleNamedMode(args: string[]): Promise { 1584: const parsed = parseAppArgs(args); 1585: 1586: if (parsed.commandArgs.length === 0) { 1587: console.error(chalk.red("Error: No command provided.")); 1588: console.error(chalk.blue("Usage:")); 1589: console.error(chalk.cyan(" portless ")); 1590: console.error(chalk.blue("Example:")); 1591: console.error(chalk.cyan(" portless myapp next dev")); 1592: process.exit(1); 1593: } 1594: 1595: const { dir, port, tls, tld } = await discoverState(); 1596: const store = new RouteStore(dir, { 1597: onWarning: (msg) => console.warn(chalk.yellow(msg)), 1598: }); 1599: await runApp( (Showing lines 1550-1599 of 1743. Use offset=1600 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 15, "offset": 1599 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 1599: await runApp( 1600: store, 1601: port, 1602: dir, 1603: parsed.name, 1604: parsed.commandArgs, 1605: tls, 1606: tld, 1607: parsed.force, 1608: undefined, 1609: parsed.appPort 1610: ); 1611: } 1612: 1613: // --------------------------------------------------------------------------- (Showing lines 1599-1613 of 1743. Use offset=1614 to continue.) ``` ## Assistant Now update both call sites to pass the tunnel parameter: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " await runApp(\n store,\n port,\n dir,\n effectiveName,\n parsed.commandArgs,\n tls,\n tld,\n parsed.force,\n { nameSource, prefix: worktree?.prefix, prefixSource: worktree?.source },\n parsed.appPort,\n parsed.tunnel\n );\n}", "oldString": " await runApp(\n store,\n port,\n dir,\n effectiveName,\n parsed.commandArgs,\n tls,\n tld,\n parsed.force,\n { nameSource, prefix: worktree?.prefix, prefixSource: worktree?.source },\n parsed.appPort\n );\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " await runApp(\n store,\n port,\n dir,\n parsed.name,\n parsed.commandArgs,\n tls,\n tld,\n parsed.force,\n undefined,\n parsed.appPort,\n parsed.tunnel\n );\n}", "oldString": " await runApp(\n store,\n port,\n dir,\n parsed.name,\n parsed.commandArgs,\n tls,\n tld,\n parsed.force,\n undefined,\n parsed.appPort\n );\n}" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now typecheck: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run typecheck 2>&1", "description": "Typecheck Phase 3 changes", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 typecheck /Users/sergiydybskiy/src/portless/packages/portless > tsc --noEmit ``` ## Assistant Build and test: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run build 2>&1 && pnpm run test 2>&1", "description": "Build and run all tests", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 build /Users/sergiydybskiy/src/portless/packages/portless > tsup CLI Building entry: src/cli.ts, src/index.ts CLI Using tsconfig: tsconfig.json CLI tsup v8.5.1 CLI Using tsup config: /Users/sergiydybskiy/src/portless/packages/portless/tsup.config.ts CLI Target: es2022 CLI Cleaning output folder ESM Build start ESM dist/index.js 915.00 B ESM dist/chunk-CL3H4345.js 186.34 KB ESM dist/cli.js 70.31 KB ESM ⚡️ Build success in 18ms DTS Build start DTS ⚡️ Build success in 1094ms DTS dist/cli.d.ts 20.00 B DTS dist/index.d.ts 8.66 KB > portless@0.6.0 test /Users/sergiydybskiy/src/portless/packages/portless > vitest run  RUN  v4.0.18 /Users/sergiydybskiy/src/portless/packages/portless ✓ src/utils.test.ts (44 tests) 5ms ✓ src/hosts.test.ts (18 tests) 14ms ✓ src/routes.test.ts (20 tests) 21ms ✓ src/cli-utils.test.ts (46 tests) 27ms ✓ src/auto.test.ts (42 tests) 456ms Certificate request self-signature ok subject=CN=localhost ✓ src/certs.test.ts (18 tests) 1037ms ✓ src/cli.test.ts (62 tests) 2946ms (node:51675) [DEP0123] DeprecationWarning: Setting the TLS ServerName to an IP address is not permitted by RFC 6066. This will be ignored in a future version. (Use `node --trace-deprecation ...` to show where the warning was created) ✓ src/proxy.test.ts (37 tests) 8151ms ✓ creates an HTTPS server that responds to requests  1020ms ✓ includes X-Portless header on TLS responses  1004ms ✓ proxies HTTPS request to matching route  1004ms ✓ supports HTTP/2 connections  1006ms ✓ still accepts HTTP/1.1 connections over TLS (allowHTTP1)  1004ms ✓ generates https:// URLs in 404 page  1005ms ✓ sets x-forwarded-proto to https when proxying  1004ms ✓ accepts plain HTTP on the TLS-enabled port  1002ms  Test Files  8 passed (8)  Tests  287 passed (287)  Start at  09:25:19  Duration  8.41s (transform 639ms, setup 0ms, import 870ms, tests 12.66s, environment 1ms) ``` ## Assistant All 287 tests pass. Phase 3 implementation complete. Now on to updating help text and docs. ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "in_progress" }, { "content": "Add tests for all three phases", "priority": "high", "status": "pending" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "in_progress" }, { "content": "Add tests for all three phases", "priority": "high", "status": "pending" } ] ``` ## Assistant Let me update the main help text in `cli.ts`, then the README, then the SKILL.md. Let me first update the `--help` output: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 80, "offset": 724 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 724: process.exit(0); 725: } else if (args[i] === "--force") { 726: force = true; 727: } else if (args[i] === "--app-port") { 728: i++; 729: appPort = parseAppPort(args[i]); 730: } else if (args[i] === "--tunnel") { 731: i++; 732: tunnel = parseTunnelArg(args[i]); 733: } else if (args[i] === "--name") { 734: i++; 735: if (!args[i] || args[i].startsWith("-")) { 736: console.error(chalk.red("Error: --name requires a name value.")); 737: console.error(chalk.cyan(" portless run --name ")); 738: process.exit(1); 739: } 740: name = args[i]; 741: } else { 742: console.error(chalk.red(`Error: Unknown flag "${args[i]}".`)); 743: console.error(chalk.blue("Known flags: --name, --force, --app-port, --tunnel, --help")); 744: process.exit(1); 745: } 746: i++; 747: } 748: 749: if (!appPort) appPort = appPortFromEnv(); 750: if (!tunnel) tunnel = tunnelFromEnv(); 751: 752: return { force, appPort, name, tunnel, commandArgs: args.slice(i) }; 753: } 754: 755: /** 756: * Parse named-mode arguments: `[--force] [--force] [--] ` 757: * 758: * `--force` is recognized before and after the name. `--` stops flag 759: * parsing. Everything after the flag region is the child command. 760: * Unrecognized `--` flags are rejected to catch typos. 761: */ 762: function parseAppArgs(args: string[]): ParsedAppArgs { 763: let force = false; 764: let appPort: number | undefined; 765: let tunnel: string | undefined; 766: let i = 0; 767: 768: // Consume leading flags before name 769: while (i < args.length && args[i].startsWith("-")) { 770: if (args[i] === "--") { 771: i++; 772: break; 773: } else if (args[i] === "--force") { 774: force = true; 775: } else if (args[i] === "--app-port") { 776: i++; 777: appPort = parseAppPort(args[i]); 778: } else if (args[i] === "--tunnel") { 779: i++; 780: tunnel = parseTunnelArg(args[i]); 781: } else { 782: console.error(chalk.red(`Error: Unknown flag "${args[i]}".`)); 783: console.error(chalk.blue("Known flags: --force, --app-port, --tunnel")); 784: process.exit(1); 785: } 786: i++; 787: } 788: 789: // Next token is the app name 790: const name = args[i]; 791: i++; 792: 793: // Allow flags immediately after name (e.g. `portless myapp --force next dev`) 794: while (i < args.length && args[i].startsWith("--")) { 795: if (args[i] === "--") { 796: i++; 797: break; 798: } else if (args[i] === "--force") { 799: force = true; 800: } else if (args[i] === "--app-port") { 801: i++; 802: appPort = parseAppPort(args[i]); 803: } else if (args[i] === "--tunnel") { (Showing lines 724-803 of 1745. Use offset=804 to continue.) ``` ## Assistant Good, the flag parsing is in place. Now update the main `printHelp` function: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 80, "offset": 819 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 819: 820: // --------------------------------------------------------------------------- 821: // Subcommand handlers 822: // --------------------------------------------------------------------------- 823: 824: function printHelp(): void { 825: console.log(` 826: ${chalk.bold("portless")} - Replace port numbers with stable, named .localhost URLs. For humans and agents. 827: 828: Eliminates port conflicts, memorizing port numbers, and cookie/storage 829: clashes by giving each dev server a stable .localhost URL. 830: 831: ${chalk.bold("Install:")} 832: ${chalk.cyan("npm install -g portless")} 833: Do NOT add portless as a project dependency. 834: 835: ${chalk.bold("Usage:")} 836: ${chalk.cyan("portless proxy start")} Start the proxy (background daemon) 837: ${chalk.cyan("portless proxy start --https")} Start with HTTP/2 + TLS (auto-generates certs) 838: ${chalk.cyan("portless proxy start -p 80")} Start on port 80 (requires sudo) 839: ${chalk.cyan("portless proxy stop")} Stop the proxy 840: ${chalk.cyan("portless ")} Run your app through the proxy 841: ${chalk.cyan("portless run ")} Infer name from project, run through proxy 842: ${chalk.cyan("portless get ")} Print URL for a service (for cross-service refs) 843: ${chalk.cyan("portless alias ")} Register a static route (e.g. for Docker) 844: ${chalk.cyan("portless alias --remove ")} Remove a static route 845: ${chalk.cyan("portless list")} Show active routes 846: ${chalk.cyan("portless trust")} Add local CA to system trust store 847: ${chalk.cyan("portless hosts sync")} Add routes to /etc/hosts (fixes Safari) 848: ${chalk.cyan("portless hosts clean")} Remove portless entries from /etc/hosts 849: 850: ${chalk.bold("Examples:")} 851: portless proxy start # Start proxy on port 1355 852: portless proxy start --https # Start with HTTPS/2 (faster page loads) 853: portless myapp next dev # -> http://myapp.localhost:1355 854: portless myapp vite dev # -> http://myapp.localhost:1355 855: portless api.myapp pnpm start # -> http://api.myapp.localhost:1355 856: portless run next dev # -> http://.localhost:1355 857: portless run next dev # in worktree -> http://..localhost:1355 858: portless get backend # -> http://backend.localhost:1355 (for cross-service refs) 859: # Wildcard subdomains: tenant.myapp.localhost also routes to myapp 860: 861: ${chalk.bold("In package.json:")} 862: { 863: "scripts": { 864: "dev": "portless run next dev" 865: } 866: } 867: 868: ${chalk.bold("How it works:")} 869: 1. Start the proxy once (listens on port 1355 by default, no sudo needed) 870: 2. Run your apps - they auto-start the proxy and register automatically 871: (apps get a random port in the 4000-4999 range via PORT) 872: 3. Access via http://.localhost:1355 873: 4. .localhost domains auto-resolve to 127.0.0.1 874: 5. Frameworks that ignore PORT (Vite, Astro, React Router, Angular, 875: Expo, React Native) get --port and --host flags injected automatically 876: 877: ${chalk.bold("HTTP/2 + HTTPS:")} 878: Use --https for HTTP/2 multiplexing (faster dev server page loads). 879: On first use, portless generates a local CA and adds it to your 880: system trust store. No browser warnings. No sudo required on macOS. 881: 882: ${chalk.bold("Options:")} 883: run [--name ] Infer project name (or override with --name) 884: Adds worktree prefix in git worktrees 885: -p, --port Port for the proxy to listen on (default: 1355) 886: Ports < 1024 require sudo 887: --https Enable HTTP/2 + TLS with auto-generated certs 888: --cert Use a custom TLS certificate (implies --https) 889: --key Use a custom TLS private key (implies --https) 890: --no-tls Disable HTTPS (overrides PORTLESS_HTTPS) 891: --foreground Run proxy in foreground (for debugging) 892: --tld Use a custom TLD instead of .localhost (e.g. test, dev) 893: --app-port Use a fixed port for the app (skip auto-assignment) 894: --force Override an existing route registered by another process 895: --name Use as the app name (bypasses subcommand dispatch) 896: -- Stop flag parsing; everything after is passed to the child 897: 898: ${chalk.bold("Environment variables:")} (Showing lines 819-898 of 1745. Use offset=899 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 30, "offset": 898 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 898: ${chalk.bold("Environment variables:")} 899: PORTLESS_PORT= Override the default proxy port (e.g. in .bashrc) 900: PORTLESS_APP_PORT= Use a fixed port for the app (same as --app-port) 901: PORTLESS_HTTPS=1 Always enable HTTPS (set in .bashrc / .zshrc) 902: PORTLESS_TLD= Use a custom TLD (e.g. test, dev; default: localhost) 903: PORTLESS_SYNC_HOSTS=1 Auto-sync /etc/hosts (auto-enabled for custom TLDs) 904: PORTLESS_STATE_DIR= Override the state directory 905: PORTLESS=0 Run command directly without proxy 906: 907: ${chalk.bold("Child process environment:")} 908: PORT Ephemeral port the child should listen on 909: HOST Always 127.0.0.1 910: PORTLESS_URL Public URL of the app (e.g. http://myapp.localhost:1355) 911: 912: ${chalk.bold("Safari / DNS:")} 913: .localhost subdomains auto-resolve in Chrome, Firefox, and Edge. 914: Safari relies on the system DNS resolver, which may not handle them. 915: Auto-syncs /etc/hosts for custom TLDs (e.g. --tld test). For .localhost, 916: set PORTLESS_SYNC_HOSTS=1 to enable. To manually sync: 917: ${chalk.cyan("sudo portless hosts sync")} 918: Clean up later with: 919: ${chalk.cyan("sudo portless hosts clean")} 920: 921: ${chalk.bold("Skip portless:")} 922: PORTLESS=0 pnpm dev # Runs command directly without proxy 923: 924: ${chalk.bold("Reserved names:")} 925: run, get, alias, tunnel, hosts, list, trust, proxy are subcommands and cannot 926: be used as app names directly. Use "portless run" to infer the name, 927: or "portless --name " to force any name including reserved ones. (Showing lines 898-927 of 1745. Use offset=928 to continue.) ``` ## Assistant Now update the help text to include tunnel features: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " ${chalk.cyan(\"portless list\")} Show active routes\n ${chalk.cyan(\"portless trust\")} Add local CA to system trust store\n ${chalk.cyan(\"portless tunnel map \")} Map external tunnel hostname to an app\n ${chalk.cyan(\"portless tunnel unmap \")} Remove a tunnel hostname mapping\n ${chalk.cyan(\"portless tunnel list\")} Show tunnel hostname mappings\n ${chalk.cyan(\"portless hosts sync\")} Add routes to /etc/hosts (fixes Safari)\n ${chalk.cyan(\"portless hosts clean\")} Remove portless entries from /etc/hosts", "oldString": " ${chalk.cyan(\"portless list\")} Show active routes\n ${chalk.cyan(\"portless trust\")} Add local CA to system trust store\n ${chalk.cyan(\"portless hosts sync\")} Add routes to /etc/hosts (fixes Safari)\n ${chalk.cyan(\"portless hosts clean\")} Remove portless entries from /etc/hosts" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now add tunnel examples and the `--tunnel` flag to the options section: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " portless get backend # -> http://backend.localhost:1355 (for cross-service refs)\n # Wildcard subdomains: tenant.myapp.localhost also routes to myapp\n\n${chalk.bold(\"Tunnels (ngrok, Cloudflare Tunnel):\")}\n portless myapp --tunnel ngrok next dev # Starts app + ngrok tunnel\n portless run --tunnel cloudflare next dev # Starts app + cloudflare tunnel\n # Single-app tunnel also works without --tunnel:\n portless myapp next dev # Start app\n ngrok http 1355 # In another terminal; auto-routed", "oldString": " portless get backend # -> http://backend.localhost:1355 (for cross-service refs)\n # Wildcard subdomains: tenant.myapp.localhost also routes to myapp" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " --app-port Use a fixed port for the app (skip auto-assignment)\n --tunnel Start a tunnel (ngrok, cloudflare)\n --force Override an existing route registered by another process", "oldString": " --app-port Use a fixed port for the app (skip auto-assignment)\n --force Override an existing route registered by another process" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " PORTLESS_STATE_DIR= Override the state directory\n PORTLESS_TUNNEL= Start a tunnel automatically (ngrok, cloudflare)\n PORTLESS=0 Run command directly without proxy", "oldString": " PORTLESS_STATE_DIR= Override the state directory\n PORTLESS=0 Run command directly without proxy" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " PORTLESS_URL Public URL of the app (e.g. http://myapp.localhost:1355)\n PORTLESS_TUNNEL_URL Tunnel URL when --tunnel is used (e.g. https://abc123.ngrok-free.app)", "oldString": " PORTLESS_URL Public URL of the app (e.g. http://myapp.localhost:1355)" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now update the README and SKILL.md. Let me read the relevant sections: ## Assistant ### Tool: task **Args:** ```json { "description": "Find tunnel-related README sections", "prompt": "I need to find the right places in README.md and skills/portless/SKILL.md where tunnel documentation should be added. Read both files and return:\n\n1. For README.md: The section headings and line numbers where I should add tunnel documentation. Specifically find:\n - The \"Environment variables\" section/table\n - The \"Child process environment\" section/table \n - The \"Options\" section\n - Any section about features or usage examples where tunnels would fit\n - The end of the features list\n\n2. For SKILL.md: The section headings and line numbers for:\n - Commands/flags section\n - Environment variables section\n - Any relevant usage examples\n\nReturn the exact line numbers and surrounding content (2-3 lines before/after) for each location.", "subagent_type": "explore" } ``` ## Assistant **Result** (success): ``` task_id: ses_322ec132bffeNW7RcDcYNnkX8U (for resuming to continue this task if needed) Here are all the relevant locations in both files: --- ## README.md (`/Users/sergiydybskiy/src/portless/README.md`) ### 1. "Options" section -- Lines 158-171 ``` 158: ### Options 159: 160: ``` 161: -p, --port Port for the proxy (default: 1355) ... 170: --name Use as the app name 171: ``` ``` This is where a `--tunnel` flag (or similar) would be added to the options list. Insert a new line before line 171 (end of the options code block). ### 2. "Environment variables" section -- Lines 173-188 This section has two sub-groups: **Configuration variables** (lines 176-182): ``` 173: ### Environment variables 174: 175: ``` 176: # Configuration 177: PORTLESS_PORT= Override the default proxy port 178: PORTLESS_APP_PORT= Use a fixed port for the app (same as --app-port) 179: PORTLESS_HTTPS=1 Always enable HTTPS 180: PORTLESS_TLD= Use a custom TLD (e.g. test; default: localhost) 181: PORTLESS_SYNC_HOSTS=1 Auto-sync /etc/hosts (auto-enabled for custom TLDs) 182: PORTLESS_STATE_DIR= Override the state directory ``` A tunnel-related env var (e.g. `PORTLESS_TUNNEL`) would be inserted after line 182. **Child process environment variables** (lines 184-188): ``` 184: # Injected into child processes 185: PORT Ephemeral port the child should listen on 186: HOST Always 127.0.0.1 187: PORTLESS_URL Public URL (e.g. https://myapp.localhost) 188: ``` ``` A tunnel URL variable (e.g. `PORTLESS_TUNNEL_URL`) would be inserted after line 187 (before the closing ``` on line 188). ### 3. Features/usage sections where tunnel documentation would fit **After "HTTP/2 + HTTPS" section and before "Commands"** -- around line 133: ``` 131: On Linux, `portless trust` supports Debian/Ubuntu, Arch, ... 132: 133: ## Commands ``` A new `## Tunnels` section (or similar) could be inserted between lines 132 and 133, as tunnels are a top-level feature like HTTPS. **Alternatively, after "Custom TLD" section** -- around line 91: ``` 89: ... 90: Recommended: `.test` (IANA-reserved, no collision risk). ... 91: 92: ## How it works ``` A tunnel section could be inserted between lines 91 and 92 if you want it grouped with the networking/URL-related features. ### 4. "Commands" section -- Lines 134-156 ``` 134: ## Commands 135: 136: ```bash 137: portless run [--name ] [args...] # Infer name ... ... 155: portless proxy stop # Stop the proxy 156: ``` ``` Tunnel-related commands would be added inside this code block, before line 156. ### 5. End of features list (before Development section) -- Line 235 ``` 234: 235: Portless detects this misconfiguration and responds with `508 Loop Detected`... 236: 237: ## Development ``` Line 236 (blank line before `## Development`) is the last possible place to add a feature section before the development/contributing content begins. --- ## SKILL.md (`/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md`) ### 1. Environment variables section -- Lines 117-127 ``` 117: ### Environment variables 118: 119: | Variable | Description | 120: | --------------------- | ----------------------------------------------------------------- | 121: | `PORTLESS_PORT` | Override the default proxy port (default: 1355) | ... 127: | `PORTLESS=0` | Bypass the proxy, run the command directly | ``` A tunnel env var row would be inserted before line 127 (last data row in the table) or after it, before the next section heading. ### 2. CLI Reference (commands/flags) section -- Lines 143-169 ``` 143: ## CLI Reference 144: 145: | Command | Description | 146: | -------------------------------------- | ------------------------------------------------------------- | 147: | `portless run [args...]` | Infer name from project, run through proxy ... ... 165: | `portless --name ` | Force `` as app name ... 166: | `portless -- [args...]` | Stop flag parsing; everything after `--` ... 167: | `portless --help` / `-h` | Show help | 168: | `portless run --help` | Show help for a subcommand ... 169: | `portless --version` / `-v` | Show version | ``` Tunnel-related flags/commands would be added as new rows in this table. Insert before line 167 (before the `--help`/`--version` rows) to group with functional commands. ### 3. Usage examples -- Integration Patterns section -- Lines 52-96 ``` 52: ## Integration Patterns 53: 54: ### package.json scripts ... 88: No config changes needed. Put `portless run` in `package.json` once ... 89: 90: ### Bypassing portless 91: 92: Set `PORTLESS=0` to run the command directly without the proxy: ... 96: ``` ``` A `### Tunnels` subsection could be added between lines 88-89 (after git worktrees) or between lines 96-97 (after bypassing portless), within the Integration Patterns section. ### 4. "HTTP/2 + HTTPS" section -- Lines 129-141 ``` 129: ### HTTP/2 + HTTPS 130: 131: Use `--https` for HTTP/2 multiplexing ... ... 141: On Linux, `portless trust` supports ... ``` A `### Tunnels` section could be placed after line 141 (after HTTPS docs, before `## CLI Reference` on line 143), since tunnels are a networking feature like HTTPS. ### 5. "How It Works" section -- Lines 98-115 ``` 98: ## How It Works 99: 100: 1. `portless proxy start` starts an HTTP reverse proxy ... ... 115: Override with the `PORTLESS_STATE_DIR` environment variable. ``` If tunnels modify the architecture (e.g., step 4: "tunnel exposes your local app publicly"), it would be added after line 103, extending the numbered list. --- **Summary of key insertion points:** | File | Section | Line(s) | Purpose | |------|---------|---------|---------| | README.md | Options | before 171 | Add `--tunnel` flag | | README.md | Env vars (config) | after 182 | Add `PORTLESS_TUNNEL` | | README.md | Env vars (child) | after 187 | Add `PORTLESS_TUNNEL_URL` | | README.md | Commands | before 156 | Add tunnel commands | | README.md | New feature section | between 132-133 | Full tunnel docs section | | SKILL.md | Env vars table | after 127 | Add tunnel env var row | | SKILL.md | CLI Reference table | before 167 | Add tunnel commands/flags | | SKILL.md | Integration Patterns | after 88 or 96 | Add tunnel usage example | | SKILL.md | After HTTPS section | after 141 | Add tunnel feature docs | ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/README.md", "limit": 50, "offset": 130 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/README.md file 130: ``` 131: 132: On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`). 133: 134: ## Commands 135: 136: ```bash 137: portless run [--name ] [args...] # Infer name (or override with --name), run through proxy 138: portless [args...] # Run app at http://.localhost:1355 139: portless alias # Register a static route (e.g. for Docker) 140: portless alias --force # Overwrite an existing route 141: portless alias --remove # Remove a static route 142: portless list # Show active routes 143: portless trust # Add local CA to system trust store 144: portless hosts sync # Add routes to /etc/hosts (fixes Safari) 145: portless hosts clean # Remove portless entries from /etc/hosts 146: 147: # Disable portless (run command directly) 148: PORTLESS=0 pnpm dev # Bypasses proxy, uses default port 149: 150: # Proxy control 151: portless proxy start # Start the proxy (port 1355, daemon) 152: portless proxy start --https # Start with HTTP/2 + TLS 153: portless proxy start -p 80 # Start on port 80 (requires sudo) 154: portless proxy start --foreground # Start in foreground (for debugging) 155: portless proxy stop # Stop the proxy 156: ``` 157: 158: ### Options 159: 160: ``` 161: -p, --port Port for the proxy (default: 1355) 162: --https Enable HTTP/2 + TLS with auto-generated certs 163: --cert Use a custom TLS certificate (implies --https) 164: --key Use a custom TLS private key (implies --https) 165: --no-tls Disable HTTPS (overrides PORTLESS_HTTPS) 166: --foreground Run proxy in foreground instead of daemon 167: --tld Use a custom TLD instead of .localhost (e.g. test) 168: --app-port Use a fixed port for the app (skip auto-assignment) 169: --force Override a route registered by another process 170: --name Use as the app name 171: ``` 172: 173: ### Environment variables 174: 175: ``` 176: # Configuration 177: PORTLESS_PORT= Override the default proxy port 178: PORTLESS_APP_PORT= Use a fixed port for the app (same as --app-port) 179: PORTLESS_HTTPS=1 Always enable HTTPS (Showing lines 130-179 of 254. Use offset=180 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/README.md", "limit": 80, "offset": 180 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/README.md file 180: PORTLESS_TLD= Use a custom TLD (e.g. test; default: localhost) 181: PORTLESS_SYNC_HOSTS=1 Auto-sync /etc/hosts (auto-enabled for custom TLDs) 182: PORTLESS_STATE_DIR= Override the state directory 183: 184: # Injected into child processes 185: PORT Ephemeral port the child should listen on 186: HOST Always 127.0.0.1 187: PORTLESS_URL Public URL (e.g. https://myapp.localhost) 188: ``` 189: 190: > **Reserved names:** `run`, `alias`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name from your project, or `portless --name ` to force any name including reserved ones. 191: 192: ## Safari / DNS 193: 194: `.localhost` subdomains auto-resolve to `127.0.0.1` in Chrome, Firefox, and Edge. Safari relies on the system DNS resolver, which may not handle `.localhost` subdomains on all configurations. 195: 196: If Safari can't find your `.localhost` URL: 197: 198: ```bash 199: sudo portless hosts sync # Add current routes to /etc/hosts 200: sudo portless hosts clean # Clean up later 201: ``` 202: 203: Auto-syncs `/etc/hosts` for custom TLDs (e.g. `--tld test`). For `.localhost`, set `PORTLESS_SYNC_HOSTS=1` to enable. Disable with `PORTLESS_SYNC_HOSTS=0`. 204: 205: ## Proxying Between Portless Apps 206: 207: If your frontend dev server (e.g. Vite, webpack) proxies API requests to another portless app, make sure the proxy rewrites the `Host` header. Without this, portless routes the request back to the frontend in an infinite loop. 208: 209: **Vite** (`vite.config.ts`): 210: 211: ```ts 212: server: { 213: proxy: { 214: "/api": { 215: target: "http://api.myapp.localhost:1355", 216: changeOrigin: true, 217: ws: true, 218: }, 219: }, 220: } 221: ``` 222: 223: **webpack-dev-server** (`webpack.config.js`): 224: 225: ```js 226: devServer: { 227: proxy: [{ 228: context: ["/api"], 229: target: "http://api.myapp.localhost:1355", 230: changeOrigin: true, 231: }], 232: } 233: ``` 234: 235: Portless detects this misconfiguration and responds with `508 Loop Detected` along with a message pointing to this fix. 236: 237: ## Development 238: 239: This repo is a pnpm workspace monorepo using [Turborepo](https://turbo.build). The publishable package lives in `packages/portless/`. 240: 241: ```bash 242: pnpm install # Install all dependencies 243: pnpm build # Build all packages 244: pnpm test # Run tests 245: pnpm test:coverage # Run tests with coverage 246: pnpm lint # Lint all packages 247: pnpm typecheck # Type-check all packages 248: pnpm format # Format all files with Prettier 249: ``` 250: 251: ## Requirements 252: 253: - Node.js 20+ 254: - macOS or Linux (End of file - total 254 lines) ``` ## Assistant Now let me make all the README updates: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/README.md", "newString": "On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`).\n\n## Tunnels (ngrok, Cloudflare Tunnel)\n\nExpose your local dev server to the internet using [ngrok](https://ngrok.com) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).\n\n**Managed tunnel (recommended)** -- portless starts the tunnel for you:\n\n```bash\nportless myapp --tunnel ngrok next dev # Starts app + ngrok tunnel\nportless run --tunnel cloudflare next dev # Starts app + cloudflare tunnel\n```\n\nThe child process receives `PORTLESS_TUNNEL_URL` with the public tunnel URL.\n\n**Single-app passthrough** -- with one app running, portless auto-routes tunnel traffic without any extra config:\n\n```bash\nportless myapp next dev # Terminal 1: start app\nngrok http 1355 # Terminal 2: start tunnel; auto-routed\n```\n\n**Multi-app with explicit mapping** -- when running multiple apps, map the tunnel hostname to a specific app:\n\n```bash\nportless tunnel map myapp abc123.ngrok-free.app\nportless tunnel unmap abc123.ngrok-free.app\nportless tunnel list\n```\n\n## Commands", "oldString": "On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`).\n\n## Commands" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Add tunnel commands to the commands list: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/README.md", "newString": "portless hosts sync # Add routes to /etc/hosts (fixes Safari)\nportless hosts clean # Remove portless entries from /etc/hosts\nportless tunnel map # Map external tunnel hostname to an app\nportless tunnel unmap # Remove a tunnel hostname mapping\nportless tunnel list # Show tunnel hostname mappings", "oldString": "portless hosts sync # Add routes to /etc/hosts (fixes Safari)\nportless hosts clean # Remove portless entries from /etc/hosts" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Add `--tunnel` to Options: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/README.md", "newString": "--app-port Use a fixed port for the app (skip auto-assignment)\n--tunnel Start a tunnel (ngrok, cloudflare)\n--force Override a route registered by another process", "oldString": "--app-port Use a fixed port for the app (skip auto-assignment)\n--force Override a route registered by another process" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Add env vars: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/README.md", "newString": "PORTLESS_STATE_DIR= Override the state directory\nPORTLESS_TUNNEL= Start a tunnel automatically (ngrok, cloudflare)", "oldString": "PORTLESS_STATE_DIR= Override the state directory" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/README.md", "newString": "PORTLESS_URL Public URL (e.g. https://myapp.localhost)\nPORTLESS_TUNNEL_URL Tunnel URL when --tunnel is used", "oldString": "PORTLESS_URL Public URL (e.g. https://myapp.localhost)" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Update the reserved names list: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/README.md", "newString": "> **Reserved names:** `run`, `alias`, `tunnel`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name from your project, or `portless --name ` to force any name including reserved ones.", "oldString": "> **Reserved names:** `run`, `alias`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name from your project, or `portless --name ` to force any name including reserved ones." } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now update SKILL.md: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md" } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/skills/portless/SKILL.md file 1: --- 2: name: portless 3: description: Set up and use portless for named local dev server URLs (e.g. http://myapp.localhost instead of http://localhost:3000). Use when integrating portless into a project, configuring dev server names, setting up the local proxy, working with .localhost domains, or troubleshooting port/proxy issues. 4: --- 5: 6: # Portless 7: 8: Replace port numbers with stable, named .localhost URLs. For humans and agents. 9: 10: ## Why portless 11: 12: - **Port conflicts** -- `EADDRINUSE` when two projects default to the same port 13: - **Memorizing ports** -- which app is on 3001 vs 8080? 14: - **Refreshing shows the wrong app** -- stop one server, start another on the same port, stale tab shows wrong content 15: - **Monorepo multiplier** -- every problem scales with each service in the repo 16: - **Agents test the wrong port** -- AI agents guess or hardcode the wrong port 17: - **Cookie/storage clashes** -- cookies on `localhost` bleed across apps; localStorage lost when ports shift 18: - **Hardcoded ports in config** -- CORS allowlists, OAuth redirects, `.env` files break when ports change 19: - **Sharing URLs with teammates** -- "what port is that on?" becomes a Slack question 20: - **Browser history is useless** -- `localhost:3000` history is a mix of unrelated projects 21: 22: ## Installation 23: 24: portless is a global CLI tool. Do NOT add it as a project dependency (no `npm install portless` or `pnpm add portless` in a project). Do NOT use `npx` or `pnpm dlx`. 25: 26: Install globally: 27: 28: ```bash 29: npm install -g portless 30: ``` 31: 32: ## Quick Start 33: 34: ```bash 35: # Install globally 36: npm install -g portless 37: 38: # Start the proxy (once, no sudo needed) 39: portless proxy start 40: 41: # Run your app (auto-starts the proxy if needed) 42: portless run next dev 43: # -> http://.localhost:1355 44: 45: # Or with an explicit name 46: portless myapp next dev 47: # -> http://myapp.localhost:1355 48: ``` 49: 50: The proxy auto-starts when you run an app. You can also start it explicitly with `portless proxy start`. 51: 52: ## Integration Patterns 53: 54: ### package.json scripts 55: 56: ```json 57: { 58: "scripts": { 59: "dev": "portless run next dev" 60: } 61: } 62: ``` 63: 64: The proxy auto-starts when you run an app. Or start it explicitly: `portless proxy start`. 65: 66: ### Multi-app setups with subdomains 67: 68: ```bash 69: portless myapp next dev # http://myapp.localhost:1355 70: portless api.myapp pnpm start # http://api.myapp.localhost:1355 71: portless docs.myapp next dev # http://docs.myapp.localhost:1355 72: ``` 73: 74: Wildcard subdomain routing: any subdomain of a registered route routes to that app automatically (e.g. `tenant1.myapp.localhost:1355` routes to the `myapp` app without extra registration). Exact matches take priority over wildcards. 75: 76: ### Git worktrees 77: 78: `portless run` automatically detects git worktrees. In a linked worktree, the branch name is prepended as a subdomain prefix so each worktree gets a unique URL: 79: 80: ```bash 81: # Main worktree -- no prefix 82: portless run next dev # -> http://myapp.localhost:1355 83: 84: # Linked worktree on branch "fix-ui" 85: portless run next dev # -> http://fix-ui.myapp.localhost:1355 86: ``` 87: 88: No config changes needed. Put `portless run` in `package.json` once and it works in all worktrees. 89: 90: ### Bypassing portless 91: 92: Set `PORTLESS=0` to run the command directly without the proxy: 93: 94: ```bash 95: PORTLESS=0 pnpm dev # Bypasses proxy, uses default port 96: ``` 97: 98: ## How It Works 99: 100: 1. `portless proxy start` starts an HTTP reverse proxy on port 1355 as a background daemon (configurable with `-p` / `--port` or the `PORTLESS_PORT` env var). The proxy also auto-starts when you run an app. 101: 2. `portless ` assigns a random free port (4000-4999) via the `PORT` env var and registers the app with the proxy 102: 3. The browser hits `http://.localhost:1355` on the proxy port; the proxy forwards to the app's assigned port 103: 104: `.localhost` domains resolve to `127.0.0.1` natively in Chrome, Firefox, and Edge. Safari relies on the system DNS resolver, which may not handle `.localhost` subdomains on all configurations. Run `sudo portless hosts sync` to add entries to `/etc/hosts` if needed. 105: 106: Most frameworks (Next.js, Express, Nuxt, etc.) respect the `PORT` env var automatically. For frameworks that ignore `PORT` (Vite, Astro, React Router, Angular, Expo, React Native), portless auto-injects the correct `--port` and `--host` CLI flags. 107: 108: ### State directory 109: 110: Portless stores its state (routes, PID file, port file) in a directory that depends on the proxy port: 111: 112: - **Port < 1024** (sudo required): `/tmp/portless` 113: - **Port >= 1024** (no sudo): `~/.portless` 114: 115: Override with the `PORTLESS_STATE_DIR` environment variable. 116: 117: ### Environment variables 118: 119: | Variable | Description | 120: | --------------------- | ----------------------------------------------------------------- | 121: | `PORTLESS_PORT` | Override the default proxy port (default: 1355) | 122: | `PORTLESS_APP_PORT` | Use a fixed port for the app (skip auto-assignment) | 123: | `PORTLESS_HTTPS` | Set to `1` to always enable HTTPS/HTTP/2 | 124: | `PORTLESS_TLD` | Use a custom TLD instead of localhost (e.g. test) | 125: | `PORTLESS_SYNC_HOSTS` | Set to `1` to auto-sync /etc/hosts (auto-enabled for custom TLDs) | 126: | `PORTLESS_STATE_DIR` | Override the state directory | 127: | `PORTLESS=0` | Bypass the proxy, run the command directly | 128: 129: ### HTTP/2 + HTTPS 130: 131: Use `--https` for HTTP/2 multiplexing (faster page loads for dev servers with many files): 132: 133: ```bash 134: portless proxy start --https # Auto-generate certs and trust CA 135: portless proxy start --cert ./c.pem --key ./k.pem # Use custom certs 136: sudo portless trust # Add CA to trust store later 137: ``` 138: 139: First run generates a local CA and prompts for sudo to add it to the system trust store. After that, no prompts and no browser warnings. Set `PORTLESS_HTTPS=1` in `.bashrc`/`.zshrc` to make it permanent. 140: 141: On Linux, `portless trust` supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via `update-ca-certificates` or `update-ca-trust`). 142: 143: ## CLI Reference 144: 145: | Command | Description | 146: | -------------------------------------- | ------------------------------------------------------------- | 147: | `portless run [args...]` | Infer name from project, run through proxy (auto-starts) | 148: | `portless run --name ` | Override inferred base name (worktree prefix still applies) | 149: | `portless [args...]` | Run app at `http://.localhost:1355` (auto-starts proxy) | 150: | `portless list` | Show active routes | 151: | `portless trust` | Add local CA to system trust store (for HTTPS) | 152: | `portless proxy start` | Start the proxy as a daemon (port 1355, no sudo) | 153: | `portless proxy start --https` | Start with HTTP/2 + TLS (auto-generates certs) | 154: | `portless proxy start -p ` | Start the proxy on a custom port | 155: | `portless proxy start --tld test` | Use .test instead of .localhost (requires /etc/hosts sync) | 156: | `portless proxy start --foreground` | Start the proxy in foreground (for debugging) | 157: | `portless proxy stop` | Stop the proxy | 158: | `portless alias ` | Register a static route (e.g. for Docker containers) | 159: | `portless alias --force` | Overwrite an existing route | 160: | `portless alias --remove ` | Remove a static route | 161: | `portless hosts sync` | Add routes to /etc/hosts (fixes Safari) | 162: | `portless hosts clean` | Remove portless entries from /etc/hosts | 163: | `portless --app-port ` | Use a fixed port for the app instead of auto-assignment | 164: | `portless --force ` | Override an existing route registered by another process | 165: | `portless --name ` | Force `` as app name (bypasses subcommand dispatch) | 166: | `portless -- [args...]` | Stop flag parsing; everything after `--` is passed to child | 167: | `portless --help` / `-h` | Show help | 168: | `portless run --help` | Show help for a subcommand (also: alias, hosts) | 169: | `portless --version` / `-v` | Show version | 170: 171: **Reserved names:** `run`, `alias`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name, or `portless --name ` to force any name including reserved ones. 172: 173: ## Troubleshooting 174: 175: ### Proxy not running 176: 177: The proxy auto-starts when you run an app with `portless `. If it doesn't start (e.g. port conflict), start it manually: 178: 179: ```bash 180: portless proxy start 181: ``` 182: 183: ### Port already in use 184: 185: Another process is bound to the proxy port. Either stop it first, or use a different port: 186: 187: ```bash 188: portless proxy start -p 8080 189: ``` 190: 191: ### Framework not respecting PORT 192: 193: Portless auto-injects `--port` and `--host` flags for frameworks that ignore the `PORT` env var: **Vite**, **Astro**, **React Router**, **Angular**, **Expo**, and **React Native**. SvelteKit uses Vite internally and is handled automatically. 194: 195: For other frameworks that don't read `PORT`, pass the port manually: 196: 197: - **Webpack Dev Server**: use `--port $PORT` 198: - **Custom servers**: read `process.env.PORT` and listen on it 199: 200: ### Permission errors 201: 202: Ports below 1024 require `sudo`. The default port (1355) does not need sudo. If you want to use port 80: 203: 204: ```bash 205: sudo portless proxy start -p 80 # Port 80, requires sudo 206: portless proxy start # Port 1355, no sudo needed 207: portless proxy stop # Stop (use sudo if started with sudo) 208: ``` 209: 210: ### Safari can't find .localhost URLs 211: 212: Safari relies on the system DNS resolver for `.localhost` subdomains, which may not resolve them on all macOS configurations. Chrome, Firefox, and Edge have built-in handling. 213: 214: Fix: 215: 216: ```bash 217: sudo portless hosts sync # Adds current routes to /etc/hosts 218: sudo portless hosts clean # Remove entries later 219: ``` 220: 221: Auto-syncs `/etc/hosts` for custom TLDs (e.g. `--tld test`). For `.localhost`, set `PORTLESS_SYNC_HOSTS=1` to enable. 222: 223: ### Browser shows certificate warning with --https 224: 225: The local CA may not be trusted yet. Run: 226: 227: ```bash 228: sudo portless trust 229: ``` 230: 231: This adds the portless local CA to your system trust store. After that, restart the browser. 232: 233: ### Proxy loop (508 Loop Detected) 234: 235: If your dev server proxies requests to another portless app (e.g. Vite proxying `/api` to `api.myapp.localhost:1355`), the proxy must rewrite the `Host` header. Without this, portless routes the request back to the original app, creating an infinite loop. 236: 237: Fix: set `changeOrigin: true` in the proxy config (Vite, webpack-dev-server, etc.): 238: 239: ```ts 240: // vite.config.ts 241: proxy: { 242: "/api": { 243: target: "http://api.myapp.localhost:1355", 244: changeOrigin: true, 245: ws: true, 246: }, 247: } 248: ``` 249: 250: ### Requirements 251: 252: - Node.js 20+ 253: - macOS or Linux 254: - `openssl` (for `--https` cert generation; ships with macOS and most Linux distributions) (End of file - total 254 lines) ``` ## Assistant Now update SKILL.md with tunnel info. Add a tunnels section after HTTPS, update env vars table, CLI reference table, and reserved names: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md", "newString": "### Bypassing portless\n\nSet `PORTLESS=0` to run the command directly without the proxy:\n\n```bash\nPORTLESS=0 pnpm dev # Bypasses proxy, uses default port\n```\n\n### Tunnels (ngrok, Cloudflare Tunnel)\n\nExpose your local dev server to the internet using ngrok or Cloudflare Tunnel.\n\n**Managed tunnel** -- portless starts the tunnel for you:\n\n```bash\nportless myapp --tunnel ngrok next dev # Starts app + ngrok tunnel\nportless run --tunnel cloudflare next dev # Starts app + cloudflare tunnel\n```\n\nThe child process receives `PORTLESS_TUNNEL_URL` with the public tunnel URL. Requires `ngrok` or `cloudflared` to be installed.\n\n**Single-app passthrough** -- with one app running, portless auto-routes tunnel traffic:\n\n```bash\nportless myapp next dev # Terminal 1\nngrok http 1355 # Terminal 2; auto-routed to the single app\n```\n\n**Multi-app with explicit mapping:**\n\n```bash\nportless tunnel map myapp abc123.ngrok-free.app # Map tunnel hostname\nportless tunnel unmap abc123.ngrok-free.app # Remove mapping\nportless tunnel list # Show all mappings\n```", "oldString": "### Bypassing portless\n\nSet `PORTLESS=0` to run the command directly without the proxy:\n\n```bash\nPORTLESS=0 pnpm dev # Bypasses proxy, uses default port\n```" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Update env vars table: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md", "newString": "| `PORTLESS_STATE_DIR` | Override the state directory |\n| `PORTLESS_TUNNEL` | Start a tunnel automatically (ngrok, cloudflare) |\n| `PORTLESS=0` | Bypass the proxy, run the command directly |", "oldString": "| `PORTLESS_STATE_DIR` | Override the state directory |\n| `PORTLESS=0` | Bypass the proxy, run the command directly |" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Update CLI Reference table: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md", "newString": "| `portless hosts clean` | Remove portless entries from /etc/hosts |\n| `portless --tunnel `| Start app with a tunnel (ngrok, cloudflare) |\n| `portless tunnel map ` | Map external tunnel hostname to a portless app |\n| `portless tunnel unmap ` | Remove a tunnel hostname mapping |\n| `portless tunnel list` | Show all tunnel hostname mappings |\n| `portless --app-port ` | Use a fixed port for the app instead of auto-assignment |", "oldString": "| `portless hosts clean` | Remove portless entries from /etc/hosts |\n| `portless --app-port ` | Use a fixed port for the app instead of auto-assignment |" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Update reserved names: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md", "newString": "**Reserved names:** `run`, `alias`, `tunnel`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name, or `portless --name ` to force any name including reserved ones.", "oldString": "**Reserved names:** `run`, `alias`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name, or `portless --name ` to force any name including reserved ones." } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Docs are done. Now let me build, run existing tests, then write new tests. ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "in_progress" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "in_progress" } ] ``` ## Assistant Let me look at the existing proxy test file to follow the patterns, then write tests for the tunnel fallback and alias features: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts", "limit": 100 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts file 1: import { describe, it, expect, afterAll, afterEach, beforeAll } from "vitest"; 2: import * as fs from "node:fs"; 3: import * as http from "node:http"; 4: import * as http2 from "node:http2"; 5: import * as https from "node:https"; 6: import * as net from "node:net"; 7: import * as os from "node:os"; 8: import * as path from "node:path"; 9: import { createProxyServer, PORTLESS_HEADER } from "./proxy.js"; 10: import type { ProxyServer } from "./proxy.js"; 11: import type { RouteInfo } from "./types.js"; 12: import { ensureCerts } from "./certs.js"; 13: 14: const TEST_PROXY_PORT = 1355; 15: 16: /** Helper type covering both http.Server and http2.Http2SecureServer */ 17: type AnyServer = http.Server | ProxyServer; 18: 19: function request( 20: server: AnyServer, 21: options: { host?: string; path?: string; method?: string } 22: ): Promise<{ status: number; headers: http.IncomingHttpHeaders; body: string }> { 23: return new Promise((resolve, reject) => { 24: const addr = server.address(); 25: if (!addr || typeof addr === "string") { 26: return reject(new Error("Server not listening")); 27: } 28: const req = http.request( 29: { 30: hostname: "127.0.0.1", 31: port: addr.port, 32: path: options.path || "/", 33: method: options.method || "GET", 34: headers: { host: options.host || "" }, 35: }, 36: (res) => { 37: let body = ""; 38: res.on("data", (chunk) => (body += chunk)); 39: res.on("end", () => resolve({ status: res.statusCode!, headers: res.headers, body })); 40: } 41: ); 42: req.on("error", reject); 43: req.end(); 44: }); 45: } 46: 47: function listen(server: AnyServer): Promise { 48: return new Promise((resolve) => { 49: server.listen(0, "127.0.0.1", () => resolve()); 50: }); 51: } 52: 53: describe("createProxyServer", () => { 54: const servers: AnyServer[] = []; 55: 56: function trackServer(server: T): T { 57: servers.push(server); 58: return server; 59: } 60: 61: afterEach(async () => { 62: for (const s of servers) { 63: await new Promise((resolve) => s.close(() => resolve())); 64: } 65: servers.length = 0; 66: }); 67: 68: describe("request routing", () => { 69: it("returns 404 when Host header has no matching route", async () => { 70: const routes: RouteInfo[] = []; 71: const server = trackServer( 72: createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT }) 73: ); 74: await listen(server); 75: 76: const res = await request(server, { host: "nonexistent.localhost" }); 77: expect(res.status).toBe(404); 78: expect(res.body).toContain("Not Found"); 79: }); 80: 81: it("returns 404 with HTML page for unknown host", async () => { 82: const routes: RouteInfo[] = []; 83: const server = trackServer( 84: createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT }) 85: ); 86: await listen(server); 87: 88: const res = await request(server, { host: "unknown.localhost" }); 89: expect(res.status).toBe(404); 90: expect(res.headers["content-type"]).toBe("text/html"); 91: expect(res.body).toContain("Not Found"); 92: expect(res.body).toContain("unknown.localhost"); 93: expect(res.body).toContain("No apps running."); 94: }); 95: 96: it("shows active routes in 404 page when routes exist", async () => { 97: const routes: RouteInfo[] = [ 98: { hostname: "myapp.localhost", port: 4001 }, 99: { hostname: "api.localhost", port: 4002 }, 100: ]; (Showing lines 1-100 of 1230. Use offset=101 to continue.) ``` ## Assistant Good, I understand the patterns. Let me also see the routes tests for the alias testing patterns: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/routes.test.ts", "limit": 50 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/routes.test.ts file 1: import { describe, it, expect, beforeEach, afterEach } from "vitest"; 2: import * as fs from "node:fs"; 3: import * as path from "node:path"; 4: import * as os from "node:os"; 5: import { RouteStore } from "./routes.js"; 6: 7: describe("RouteStore", () => { 8: let tmpDir: string; 9: let store: RouteStore; 10: 11: beforeEach(() => { 12: tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "portless-routes-test-")); 13: store = new RouteStore(tmpDir); 14: }); 15: 16: afterEach(() => { 17: fs.rmSync(tmpDir, { recursive: true, force: true }); 18: }); 19: 20: describe("ensureDir", () => { 21: it("creates directory if it does not exist", () => { 22: const nested = path.join(tmpDir, "sub", "dir"); 23: const s = new RouteStore(nested); 24: s.ensureDir(); 25: expect(fs.existsSync(nested)).toBe(true); 26: }); 27: 28: it("does not throw if directory already exists", () => { 29: store.ensureDir(); 30: expect(() => store.ensureDir()).not.toThrow(); 31: }); 32: }); 33: 34: describe("loadRoutes", () => { 35: it("returns empty array when routes file does not exist", () => { 36: expect(store.loadRoutes()).toEqual([]); 37: }); 38: 39: it("returns empty array for invalid JSON", () => { 40: store.ensureDir(); 41: fs.writeFileSync(store.getRoutesPath(), "not json"); 42: expect(store.loadRoutes()).toEqual([]); 43: }); 44: 45: it("calls onWarning for invalid JSON", () => { 46: const warnings: string[] = []; 47: const warnStore = new RouteStore(tmpDir, { 48: onWarning: (msg) => warnings.push(msg), 49: }); 50: warnStore.ensureDir(); (Showing lines 1-50 of 229. Use offset=51 to continue.) ``` ## Assistant Now let me write the tests. I'll add proxy tunnel tests to the existing proxy test file, route alias tests to the routes test file, and create a new tunnel test file for the provider registry: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts", "limit": 30, "offset": 95 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts file 95: 96: it("shows active routes in 404 page when routes exist", async () => { 97: const routes: RouteInfo[] = [ 98: { hostname: "myapp.localhost", port: 4001 }, 99: { hostname: "api.localhost", port: 4002 }, 100: ]; 101: const server = trackServer( 102: createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT }) 103: ); 104: await listen(server); 105: 106: const res = await request(server, { host: "other.localhost" }); 107: expect(res.status).toBe(404); 108: expect(res.body).toContain("Active apps"); 109: expect(res.body).toContain("myapp.localhost"); 110: expect(res.body).toContain("api.localhost"); 111: }); 112: 113: it("includes correct port in 404 page links", async () => { 114: const routes: RouteInfo[] = [{ hostname: "myapp.localhost", port: 4001 }]; 115: const server = trackServer(createProxyServer({ getRoutes: () => routes, proxyPort: 8080 })); 116: await listen(server); 117: 118: const res = await request(server, { host: "other.localhost" }); 119: expect(res.status).toBe(404); 120: expect(res.body).toContain('href="http://myapp.localhost:8080"'); 121: }); 122: 123: it("omits port 80 in 404 page links", async () => { 124: const routes: RouteInfo[] = [{ hostname: "myapp.localhost", port: 4001 }]; (Showing lines 95-124 of 1230. Use offset=125 to continue.) ``` ## Assistant Let me find the end of the "request routing" describe block and the wildcard test to add tunnel tests there: ## Assistant ### Tool: grep **Args:** ```json { "include": "proxy.test.ts", "pattern": "wildcard|tunnel|subdomain match" } ``` ## Assistant **Result** (success): ``` Found 10 matches /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts: Line 156: it("routes wildcard subdomain to matching parent route", async () => { Line 160: res.end("wildcard hit"); Line 175: expect(res.body).toBe("wildcard hit"); Line 178: it("prefers exact match over wildcard subdomain match", async () => { Line 189: const wildcardBackend = trackServer( Line 192: res.end("wildcard"); Line 195: await listen(wildcardBackend); Line 196: const wildcardAddr = wildcardBackend.address(); Line 197: if (!wildcardAddr || typeof wildcardAddr === "string") throw new Error("no addr"); Line 201: { hostname: "myapp.localhost", port: wildcardAddr.port }, ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts", "limit": 80, "offset": 156 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts file 156: it("routes wildcard subdomain to matching parent route", async () => { 157: const backend = trackServer( 158: http.createServer((_req, res) => { 159: res.writeHead(200, { "Content-Type": "text/plain" }); 160: res.end("wildcard hit"); 161: }) 162: ); 163: await listen(backend); 164: const backendAddr = backend.address(); 165: if (!backendAddr || typeof backendAddr === "string") throw new Error("no addr"); 166: 167: const routes: RouteInfo[] = [{ hostname: "myapp.localhost", port: backendAddr.port }]; 168: const server = trackServer( 169: createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT }) 170: ); 171: await listen(server); 172: 173: const res = await request(server, { host: "tenant.myapp.localhost" }); 174: expect(res.status).toBe(200); 175: expect(res.body).toBe("wildcard hit"); 176: }); 177: 178: it("prefers exact match over wildcard subdomain match", async () => { 179: const exactBackend = trackServer( 180: http.createServer((_req, res) => { 181: res.writeHead(200, { "Content-Type": "text/plain" }); 182: res.end("exact"); 183: }) 184: ); 185: await listen(exactBackend); 186: const exactAddr = exactBackend.address(); 187: if (!exactAddr || typeof exactAddr === "string") throw new Error("no addr"); 188: 189: const wildcardBackend = trackServer( 190: http.createServer((_req, res) => { 191: res.writeHead(200, { "Content-Type": "text/plain" }); 192: res.end("wildcard"); 193: }) 194: ); 195: await listen(wildcardBackend); 196: const wildcardAddr = wildcardBackend.address(); 197: if (!wildcardAddr || typeof wildcardAddr === "string") throw new Error("no addr"); 198: 199: const routes: RouteInfo[] = [ 200: { hostname: "tenant.myapp.localhost", port: exactAddr.port }, 201: { hostname: "myapp.localhost", port: wildcardAddr.port }, 202: ]; 203: const server = trackServer( 204: createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT }) 205: ); 206: await listen(server); 207: 208: const res = await request(server, { host: "tenant.myapp.localhost" }); 209: expect(res.status).toBe(200); 210: expect(res.body).toBe("exact"); 211: }); 212: 213: it("returns 404 when subdomain does not match any route", async () => { 214: const routes: RouteInfo[] = [{ hostname: "myapp.localhost", port: 4001 }]; 215: const server = trackServer( 216: createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT }) 217: ); 218: await listen(server); 219: 220: const res = await request(server, { host: "other.localhost" }); 221: expect(res.status).toBe(404); 222: }); 223: 224: it("strips port from Host header for matching", async () => { 225: const backend = trackServer( 226: http.createServer((_req, res) => { 227: res.writeHead(200, { "Content-Type": "text/plain" }); 228: res.end("matched"); 229: }) 230: ); 231: await listen(backend); 232: const backendAddr = backend.address(); 233: if (!backendAddr || typeof backendAddr === "string") throw new Error("no addr"); 234: 235: const routes: RouteInfo[] = [{ hostname: "myapp.localhost", port: backendAddr.port }]; (Showing lines 156-235 of 1230. Use offset=236 to continue.) ``` ## Assistant Let me find the end of the "request routing" describe block: ## Assistant ### Tool: grep **Args:** ```json { "include": "proxy.test.ts", "pattern": "describe\\(|^\\s+\\}\\);" } ``` ## Assistant **Result** (success): ``` Found 100 matches /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts: Line 44: }); Line 50: }); Line 53: describe("createProxyServer", () => { Line 66: }); Line 68: describe("request routing", () => { Line 79: }); Line 94: }); Line 111: }); Line 121: }); Line 132: }); Line 154: }); Line 176: }); Line 211: }); Line 222: }); Line 244: }); Line 245: }); Line 247: describe("missing Host header", () => { Line 262: }); Line 267: }); Line 271: }); Line 272: }); Line 274: describe("error handling", () => { Line 292: }); Line 293: }); Line 295: describe("X-Portless header", () => { Line 305: }); Line 316: }); Line 317: }); Line 319: describe("proxy loop detection", () => { Line 365: }); Line 372: }); Line 414: }); Line 418: }); Line 466: }); Line 468: }); Line 480: }); Line 510: }); Line 515: }); Line 520: }); Line 558: }); Line 591: }); Line 593: }); Line 597: }); Line 598: }); Line 600: describe("custom TLD", () => { Line 612: }); Line 659: }); Line 663: }); Line 685: }); Line 686: }); Line 688: describe("XSS safety", () => { Line 701: }); Line 715: }); Line 716: }); Line 718: describe("WebSocket upgrade", () => { Line 730: }); Line 754: }); Line 760: }); Line 762: }); Line 765: }); Line 782: }); Line 810: }); Line 817: }); Line 818: }); Line 822: }); Line 824: }); Line 829: }); Line 852: }); Line 857: }); Line 860: }); Line 861: }); Line 864: describe("createProxyServer with TLS (HTTP/2)", () => { Line 880: }); Line 884: }); Line 899: }); Line 927: }); Line 944: }); Line 959: }); Line 985: }); Line 1004: }); Line 1011: }); Line 1018: }); Line 1022: }); Line 1026: }); Line 1042: }); Line 1058: }); Line 1085: }); Line 1097: }); Line 1126: }); Line 1132: }); Line 1134: }); Line 1137: }); Line 1154: }); Line 1165: }); Line 1194: }); Line 1201: }); Line 1212: }); Line 1219: }); Line 1222: }); Line 1229: }); ``` ## Assistant The "request routing" describe block ends at line 245. I'll add tunnel tests right before the closing `});` at line 245. Let me see what's there: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts", "limit": 10, "offset": 240 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts file 240: 241: const res = await request(server, { host: "myapp.localhost:80" }); 242: expect(res.status).toBe(200); 243: expect(res.body).toBe("matched"); 244: }); 245: }); 246: 247: describe("missing Host header", () => { 248: it("returns 400 when Host header is missing", async () => { 249: const routes: RouteInfo[] = []; (Showing lines 240-249 of 1230. Use offset=250 to continue.) ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts", "newString": " const res = await request(server, { host: \"myapp.localhost:80\" });\n expect(res.status).toBe(200);\n expect(res.body).toBe(\"matched\");\n });\n });\n\n describe(\"tunnel passthrough\", () => {\n it(\"routes non-portless hostname to single registered route\", async () => {\n const backend = trackServer(\n http.createServer((_req, res) => {\n res.writeHead(200, { \"Content-Type\": \"text/plain\" });\n res.end(\"tunnel passthrough\");\n })\n );\n await listen(backend);\n const backendAddr = backend.address();\n if (!backendAddr || typeof backendAddr === \"string\") throw new Error(\"no addr\");\n\n const routes: RouteInfo[] = [{ hostname: \"myapp.localhost\", port: backendAddr.port }];\n const server = trackServer(\n createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT })\n );\n await listen(server);\n\n // Simulate ngrok forwarding with its own Host header\n const res = await request(server, { host: \"abc123.ngrok-free.app\" });\n expect(res.status).toBe(200);\n expect(res.body).toBe(\"tunnel passthrough\");\n });\n\n it(\"returns 404 for non-portless hostname when multiple routes exist\", async () => {\n const routes: RouteInfo[] = [\n { hostname: \"app1.localhost\", port: 4001 },\n { hostname: \"app2.localhost\", port: 4002 },\n ];\n const server = trackServer(\n createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT })\n );\n await listen(server);\n\n const res = await request(server, { host: \"abc123.ngrok-free.app\" });\n expect(res.status).toBe(404);\n });\n\n it(\"returns 404 for non-portless hostname when no routes exist\", async () => {\n const routes: RouteInfo[] = [];\n const server = trackServer(\n createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT })\n );\n await listen(server);\n\n const res = await request(server, { host: \"abc123.ngrok-free.app\" });\n expect(res.status).toBe(404);\n });\n\n it(\"does not trigger tunnel passthrough for unregistered portless hostname\", async () => {\n const routes: RouteInfo[] = [{ hostname: \"myapp.localhost\", port: 4001 }];\n const server = trackServer(\n createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT })\n );\n await listen(server);\n\n // This is a .localhost hostname -- should NOT fall back to single route\n const res = await request(server, { host: \"other.localhost\" });\n expect(res.status).toBe(404);\n });\n\n it(\"does not trigger tunnel passthrough for bare TLD hostname\", async () => {\n const routes: RouteInfo[] = [{ hostname: \"myapp.localhost\", port: 4001 }];\n const server = trackServer(\n createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT })\n );\n await listen(server);\n\n const res = await request(server, { host: \"localhost\" });\n expect(res.status).toBe(404);\n });\n\n it(\"works with cloudflare tunnel hostnames\", async () => {\n const backend = trackServer(\n http.createServer((_req, res) => {\n res.writeHead(200, { \"Content-Type\": \"text/plain\" });\n res.end(\"cloudflare tunnel\");\n })\n );\n await listen(backend);\n const backendAddr = backend.address();\n if (!backendAddr || typeof backendAddr === \"string\") throw new Error(\"no addr\");\n\n const routes: RouteInfo[] = [{ hostname: \"myapp.localhost\", port: backendAddr.port }];\n const server = trackServer(\n createProxyServer({ getRoutes: () => routes, proxyPort: TEST_PROXY_PORT })\n );\n await listen(server);\n\n const res = await request(server, { host: \"random-words.trycloudflare.com\" });\n expect(res.status).toBe(200);\n expect(res.body).toBe(\"cloudflare tunnel\");\n });\n });\n\n describe(\"alias routing\", () => {\n it(\"routes aliased hostname to correct backend\", async () => {\n const backend = trackServer(\n http.createServer((_req, res) => {\n res.writeHead(200, { \"Content-Type\": \"text/plain\" });\n res.end(\"via alias\");\n })\n );\n await listen(backend);\n const backendAddr = backend.address();\n if (!backendAddr || typeof backendAddr === \"string\") throw new Error(\"no addr\");\n\n const routes: RouteInfo[] = [{ hostname: \"myapp.localhost\", port: backendAddr.port }];\n const aliases: Record = {\n \"abc123.ngrok-free.app\": \"myapp.localhost\",\n };\n const server = trackServer(\n createProxyServer({\n getRoutes: () => routes,\n getAliases: () => aliases,\n proxyPort: TEST_PROXY_PORT,\n })\n );\n await listen(server);\n\n const res = await request(server, { host: \"abc123.ngrok-free.app\" });\n expect(res.status).toBe(200);\n expect(res.body).toBe(\"via alias\");\n });\n\n it(\"routes to correct app in multi-app setup via alias\", async () => {\n const backend1 = trackServer(\n http.createServer((_req, res) => {\n res.writeHead(200, { \"Content-Type\": \"text/plain\" });\n res.end(\"app1\");\n })\n );\n await listen(backend1);\n const addr1 = backend1.address();\n if (!addr1 || typeof addr1 === \"string\") throw new Error(\"no addr\");\n\n const backend2 = trackServer(\n http.createServer((_req, res) => {\n res.writeHead(200, { \"Content-Type\": \"text/plain\" });\n res.end(\"app2\");\n })\n );\n await listen(backend2);\n const addr2 = backend2.address();\n if (!addr2 || typeof addr2 === \"string\") throw new Error(\"no addr\");\n\n const routes: RouteInfo[] = [\n { hostname: \"frontend.localhost\", port: addr1.port },\n { hostname: \"api.localhost\", port: addr2.port },\n ];\n const aliases: Record = {\n \"my-tunnel.ngrok-free.app\": \"api.localhost\",\n };\n const server = trackServer(\n createProxyServer({\n getRoutes: () => routes,\n getAliases: () => aliases,\n proxyPort: TEST_PROXY_PORT,\n })\n );\n await listen(server);\n\n const res = await request(server, { host: \"my-tunnel.ngrok-free.app\" });\n expect(res.status).toBe(200);\n expect(res.body).toBe(\"app2\");\n });\n\n it(\"returns 404 when alias points to non-existent route\", async () => {\n const routes: RouteInfo[] = [{ hostname: \"myapp.localhost\", port: 4001 }];\n const aliases: Record = {\n \"abc123.ngrok-free.app\": \"other.localhost\",\n };\n const server = trackServer(\n createProxyServer({\n getRoutes: () => routes,\n getAliases: () => aliases,\n proxyPort: TEST_PROXY_PORT,\n })\n );\n await listen(server);\n\n // Alias points to \"other.localhost\" which doesn't exist;\n // only one route so tunnel passthrough kicks in\n const res = await request(server, { host: \"abc123.ngrok-free.app\" });\n expect(res.status).toBe(200);\n });\n\n it(\"prefers exact route match over alias\", async () => {\n const exactBackend = trackServer(\n http.createServer((_req, res) => {\n res.writeHead(200, { \"Content-Type\": \"text/plain\" });\n res.end(\"exact\");\n })\n );\n await listen(exactBackend);\n const exactAddr = exactBackend.address();\n if (!exactAddr || typeof exactAddr === \"string\") throw new Error(\"no addr\");\n\n const aliasBackend = trackServer(\n http.createServer((_req, res) => {\n res.writeHead(200, { \"Content-Type\": \"text/plain\" });\n res.end(\"aliased\");\n })\n );\n await listen(aliasBackend);\n const aliasAddr = aliasBackend.address();\n if (!aliasAddr || typeof aliasAddr === \"string\") throw new Error(\"no addr\");\n\n // The host is also a registered route -- exact match should win\n const routes: RouteInfo[] = [\n { hostname: \"abc123.ngrok-free.app\", port: exactAddr.port },\n { hostname: \"other.localhost\", port: aliasAddr.port },\n ];\n const aliases: Record = {\n \"abc123.ngrok-free.app\": \"other.localhost\",\n };\n const server = trackServer(\n createProxyServer({\n getRoutes: () => routes,\n getAliases: () => aliases,\n proxyPort: TEST_PROXY_PORT,\n })\n );\n await listen(server);\n\n const res = await request(server, { host: \"abc123.ngrok-free.app\" });\n expect(res.status).toBe(200);\n expect(res.body).toBe(\"exact\");\n });\n });", "oldString": " const res = await request(server, { host: \"myapp.localhost:80\" });\n expect(res.status).toBe(200);\n expect(res.body).toBe(\"matched\");\n });\n });" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now add alias tests to the routes test file: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/routes.test.ts", "limit": 30, "offset": 200 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/routes.test.ts file 200: expect(routes).toHaveLength(1); 201: }); 202: 203: it("preserves other routes when removing", () => { 204: store.addRoute("app1.localhost", 4001, process.pid); 205: store.addRoute("app2.localhost", 4002, process.pid); 206: store.removeRoute("app1.localhost"); 207: const routes = store.loadRoutes(); 208: expect(routes).toHaveLength(1); 209: expect(routes[0].hostname).toBe("app2.localhost"); 210: }); 211: }); 212: 213: describe("locking (via concurrent addRoute)", () => { 214: it("handles stale lock by recovering and completing the operation", () => { 215: store.ensureDir(); 216: const lockPath = path.join(tmpDir, "routes.lock"); 217: // Create a stale lock directory manually 218: fs.mkdirSync(lockPath); 219: // Backdate mtime to 11 seconds ago 220: const staleTime = new Date(Date.now() - 11_000); 221: fs.utimesSync(lockPath, staleTime, staleTime); 222: // addRoute should recover from the stale lock 223: expect(() => store.addRoute("test.localhost", 4001, process.pid)).not.toThrow(); 224: const routes = store.loadRoutes(); 225: expect(routes).toHaveLength(1); 226: expect(routes[0].hostname).toBe("test.localhost"); 227: }); 228: }); 229: }); (End of file - total 229 lines) ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/routes.test.ts", "newString": " describe(\"locking (via concurrent addRoute)\", () => {\n it(\"handles stale lock by recovering and completing the operation\", () => {\n store.ensureDir();\n const lockPath = path.join(tmpDir, \"routes.lock\");\n // Create a stale lock directory manually\n fs.mkdirSync(lockPath);\n // Backdate mtime to 11 seconds ago\n const staleTime = new Date(Date.now() - 11_000);\n fs.utimesSync(lockPath, staleTime, staleTime);\n // addRoute should recover from the stale lock\n expect(() => store.addRoute(\"test.localhost\", 4001, process.pid)).not.toThrow();\n const routes = store.loadRoutes();\n expect(routes).toHaveLength(1);\n expect(routes[0].hostname).toBe(\"test.localhost\");\n });\n });\n\n describe(\"aliases\", () => {\n it(\"returns empty object when aliases file does not exist\", () => {\n expect(store.loadAliases()).toEqual({});\n });\n\n it(\"returns empty object for invalid JSON\", () => {\n store.ensureDir();\n fs.writeFileSync(store.getAliasesPath(), \"not json\");\n expect(store.loadAliases()).toEqual({});\n });\n\n it(\"returns empty object for non-object JSON\", () => {\n store.ensureDir();\n fs.writeFileSync(store.getAliasesPath(), \"[]\");\n expect(store.loadAliases()).toEqual({});\n });\n\n it(\"adds and loads an alias\", () => {\n store.addAlias(\"abc123.ngrok-free.app\", \"myapp.localhost\");\n const aliases = store.loadAliases();\n expect(aliases).toEqual({ \"abc123.ngrok-free.app\": \"myapp.localhost\" });\n });\n\n it(\"overwrites existing alias\", () => {\n store.addAlias(\"abc123.ngrok-free.app\", \"app1.localhost\");\n store.addAlias(\"abc123.ngrok-free.app\", \"app2.localhost\");\n const aliases = store.loadAliases();\n expect(aliases[\"abc123.ngrok-free.app\"]).toBe(\"app2.localhost\");\n });\n\n it(\"stores multiple aliases\", () => {\n store.addAlias(\"tunnel1.ngrok-free.app\", \"frontend.localhost\");\n store.addAlias(\"tunnel2.trycloudflare.com\", \"api.localhost\");\n const aliases = store.loadAliases();\n expect(Object.keys(aliases)).toHaveLength(2);\n expect(aliases[\"tunnel1.ngrok-free.app\"]).toBe(\"frontend.localhost\");\n expect(aliases[\"tunnel2.trycloudflare.com\"]).toBe(\"api.localhost\");\n });\n\n it(\"removes an alias\", () => {\n store.addAlias(\"abc123.ngrok-free.app\", \"myapp.localhost\");\n const removed = store.removeAlias(\"abc123.ngrok-free.app\");\n expect(removed).toBe(true);\n expect(store.loadAliases()).toEqual({});\n });\n\n it(\"returns false when removing non-existent alias\", () => {\n const removed = store.removeAlias(\"nonexistent.example.com\");\n expect(removed).toBe(false);\n });\n\n it(\"removes all aliases for a route\", () => {\n store.addAlias(\"tunnel1.ngrok-free.app\", \"myapp.localhost\");\n store.addAlias(\"tunnel2.ngrok-free.app\", \"myapp.localhost\");\n store.addAlias(\"other.trycloudflare.com\", \"api.localhost\");\n store.removeAliasesForRoute(\"myapp.localhost\");\n const aliases = store.loadAliases();\n expect(Object.keys(aliases)).toHaveLength(1);\n expect(aliases[\"other.trycloudflare.com\"]).toBe(\"api.localhost\");\n });\n\n it(\"does nothing when removing aliases for route with no aliases\", () => {\n store.addAlias(\"abc123.ngrok-free.app\", \"myapp.localhost\");\n store.removeAliasesForRoute(\"other.localhost\");\n const aliases = store.loadAliases();\n expect(Object.keys(aliases)).toHaveLength(1);\n });\n\n it(\"filters out non-string values from aliases file\", () => {\n store.ensureDir();\n fs.writeFileSync(\n store.getAliasesPath(),\n JSON.stringify({ valid: \"myapp.localhost\", invalid: 123, nullish: null })\n );\n const aliases = store.loadAliases();\n expect(aliases).toEqual({ valid: \"myapp.localhost\" });\n });\n });\n});", "oldString": " describe(\"locking (via concurrent addRoute)\", () => {\n it(\"handles stale lock by recovering and completing the operation\", () => {\n store.ensureDir();\n const lockPath = path.join(tmpDir, \"routes.lock\");\n // Create a stale lock directory manually\n fs.mkdirSync(lockPath);\n // Backdate mtime to 11 seconds ago\n const staleTime = new Date(Date.now() - 11_000);\n fs.utimesSync(lockPath, staleTime, staleTime);\n // addRoute should recover from the stale lock\n expect(() => store.addRoute(\"test.localhost\", 4001, process.pid)).not.toThrow();\n const routes = store.loadRoutes();\n expect(routes).toHaveLength(1);\n expect(routes[0].hostname).toBe(\"test.localhost\");\n });\n });\n});" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now create a test file for the tunnel provider registry: ## Assistant ### Tool: write **Args:** ```json { "content": "import { describe, it, expect } from \"vitest\";\nimport { getTunnelProvider, TUNNEL_PROVIDERS } from \"./tunnel.js\";\n\ndescribe(\"tunnel providers\", () => {\n it(\"exposes ngrok and cloudflare as known providers\", () => {\n expect(TUNNEL_PROVIDERS).toContain(\"ngrok\");\n expect(TUNNEL_PROVIDERS).toContain(\"cloudflare\");\n });\n\n it(\"returns ngrok provider by name\", () => {\n const provider = getTunnelProvider(\"ngrok\");\n expect(provider).toBeDefined();\n expect(provider!.name).toBe(\"ngrok\");\n });\n\n it(\"returns cloudflare provider by name\", () => {\n const provider = getTunnelProvider(\"cloudflare\");\n expect(provider).toBeDefined();\n expect(provider!.name).toBe(\"cloudflare\");\n });\n\n it(\"returns undefined for unknown provider\", () => {\n expect(getTunnelProvider(\"localtunnel\")).toBeUndefined();\n expect(getTunnelProvider(\"\")).toBeUndefined();\n });\n\n describe(\"ngrok provider\", () => {\n it(\"has isAvailable method\", () => {\n const provider = getTunnelProvider(\"ngrok\")!;\n expect(typeof provider.isAvailable).toBe(\"function\");\n // isAvailable returns a boolean (may or may not be installed)\n const result = provider.isAvailable();\n expect(typeof result).toBe(\"boolean\");\n });\n\n it(\"has start method\", () => {\n const provider = getTunnelProvider(\"ngrok\")!;\n expect(typeof provider.start).toBe(\"function\");\n });\n });\n\n describe(\"cloudflare provider\", () => {\n it(\"has isAvailable method\", () => {\n const provider = getTunnelProvider(\"cloudflare\")!;\n expect(typeof provider.isAvailable).toBe(\"function\");\n const result = provider.isAvailable();\n expect(typeof result).toBe(\"boolean\");\n });\n\n it(\"has start method\", () => {\n const provider = getTunnelProvider(\"cloudflare\")!;\n expect(typeof provider.start).toBe(\"function\");\n });\n });\n});\n", "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/tunnel.test.ts" } ``` ## Assistant **Result** (success): ``` Wrote file successfully. ``` ## Assistant Now build and run all tests: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run build 2>&1 && pnpm run test 2>&1", "description": "Build and run all tests", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 build /Users/sergiydybskiy/src/portless/packages/portless > tsup CLI Building entry: src/cli.ts, src/index.ts CLI Using tsconfig: tsconfig.json CLI tsup v8.5.1 CLI Using tsup config: /Users/sergiydybskiy/src/portless/packages/portless/tsup.config.ts CLI Target: es2022 CLI Cleaning output folder ESM Build start ESM dist/index.js 915.00 B ESM dist/cli.js 71.20 KB ESM dist/chunk-CL3H4345.js 186.34 KB ESM ⚡️ Build success in 14ms DTS Build start DTS ⚡️ Build success in 970ms DTS dist/cli.d.ts 20.00 B DTS dist/index.d.ts 8.66 KB > portless@0.6.0 test /Users/sergiydybskiy/src/portless/packages/portless > vitest run  RUN  v4.0.18 /Users/sergiydybskiy/src/portless/packages/portless ✓ src/hosts.test.ts (18 tests) 13ms ✓ src/utils.test.ts (44 tests) 6ms ✓ src/tunnel.test.ts (8 tests) 18ms ✓ src/cli-utils.test.ts (46 tests) 21ms ✓ src/routes.test.ts (31 tests) 25ms stderr | src/proxy.test.ts > createProxyServer > alias routing > returns 404 when alias points to non-existent route Proxy error for abc123.ngrok-free.app: connect ECONNREFUSED 127.0.0.1:4001 ✓ src/auto.test.ts (42 tests) 416ms Certificate request self-signature ok subject=CN=localhost ✓ src/certs.test.ts (18 tests) 931ms ✓ src/cli.test.ts (62 tests) 2590ms (node:59617) [DEP0123] DeprecationWarning: Setting the TLS ServerName to an IP address is not permitted by RFC 6066. This will be ignored in a future version. (Use `node --trace-deprecation ...` to show where the warning was created) ❯ src/proxy.test.ts (47 tests | 1 failed) 8186ms ✓ returns 404 when Host header has no matching route 10ms ✓ returns 404 with HTML page for unknown host 3ms ✓ shows active routes in 404 page when routes exist 2ms ✓ includes correct port in 404 page links 1ms ✓ omits port 80 in 404 page links 1ms ✓ proxies request to matching route 2ms ✓ routes wildcard subdomain to matching parent route 2ms ✓ prefers exact match over wildcard subdomain match 1ms ✓ returns 404 when subdomain does not match any route 1ms ✓ strips port from Host header for matching 1ms ✓ routes non-portless hostname to single registered route 1ms ✓ returns 404 for non-portless hostname when multiple routes exist 1ms ✓ returns 404 for non-portless hostname when no routes exist 1ms ✓ does not trigger tunnel passthrough for unregistered portless hostname 1ms ✓ does not trigger tunnel passthrough for bare TLD hostname 1ms ✓ works with cloudflare tunnel hostnames 1ms ✓ routes aliased hostname to correct backend 1ms ✓ routes to correct app in multi-app setup via alias 1ms  × returns 404 when alias points to non-existent route 6ms ✓ prefers exact route match over alias 1ms ✓ returns 400 when Host header is missing 1ms ✓ returns 502 when backend is not running 1ms ✓ includes X-Portless header on 404 responses 1ms ✓ includes X-Portless header on 400 responses 1ms ✓ returns 508 when X-Portless-Hops reaches the threshold 1ms ✓ allows requests with hops below the threshold 1ms ✓ increments X-Portless-Hops when forwarding to backend 2ms ✓ closes socket on WebSocket upgrade when hops exceed threshold 1ms ✓ detects loop with real proxy loop scenario 5ms ✓ uses custom TLD in 404 page suggested command 1ms ✓ uses custom TLD in 508 loop detection page 1ms ✓ routes requests with custom TLD hostnames 1ms ✓ escapes hostname in 404 page 1ms ✓ escapes route hostnames in active apps list 1ms ✓ proxies WebSocket upgrade to matching route 1ms ✓ forwards backend Sec-WebSocket-Accept and custom headers 1ms ✓ destroys socket for unknown host on upgrade 0ms ✓ creates an HTTPS server that responds to requests  1019ms ✓ includes X-Portless header on TLS responses  1003ms ✓ proxies HTTPS request to matching route  1004ms ✓ supports HTTP/2 connections  1012ms ✓ still accepts HTTP/1.1 connections over TLS (allowHTTP1)  1009ms ✓ generates https:// URLs in 404 page  1008ms ✓ sets x-forwarded-proto to https when proxying  1007ms ✓ proxies WebSocket upgrade over TLS 7ms ✓ accepts plain HTTP on the TLS-enabled port  1004ms ✓ strips hop-by-hop headers from proxied TLS responses (HTTP/2 client) 10ms ⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯  FAIL  src/proxy.test.ts > createProxyServer > alias routing > returns 404 when alias points to non-existent route AssertionError: expected 502 to be 200 // Object.is equality - Expected + Received - 200 + 502  ❯ src/proxy.test.ts:431:26 429|  // only one route so tunnel passthrough kicks in 430|  const res = await request(server, { host: "abc123.ngrok-free.app… 431|  expect(res.status).toBe(200);  |  ^ 432|  }); 433|  ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯  Test Files  1 failed | 8 passed (9)  Tests  1 failed | 315 passed (316)  Start at  09:30:53  Duration  8.42s (transform 706ms, setup 0ms, import 892ms, tests 12.21s, environment 1ms)  ELIFECYCLE  Test failed. See above for more details. ``` ## Assistant ## Assistant One test needs fixing -- when alias target doesn't exist but there's a single route, tunnel passthrough kicks in. Let me fix the test to have two routes so passthrough doesn't trigger: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/proxy.test.ts", "newString": " it(\"returns 404 when alias points to non-existent route\", async () => {\n const routes: RouteInfo[] = [\n { hostname: \"app1.localhost\", port: 4001 },\n { hostname: \"app2.localhost\", port: 4002 },\n ];\n const aliases: Record = {\n \"abc123.ngrok-free.app\": \"other.localhost\",\n };\n const server = trackServer(\n createProxyServer({\n getRoutes: () => routes,\n getAliases: () => aliases,\n proxyPort: TEST_PROXY_PORT,\n })\n );\n await listen(server);\n\n // Alias points to \"other.localhost\" which doesn't exist;\n // multiple routes exist so tunnel passthrough does not apply\n const res = await request(server, { host: \"abc123.ngrok-free.app\" });\n expect(res.status).toBe(404);\n });", "oldString": " it(\"returns 404 when alias points to non-existent route\", async () => {\n const routes: RouteInfo[] = [{ hostname: \"myapp.localhost\", port: 4001 }];\n const aliases: Record = {\n \"abc123.ngrok-free.app\": \"other.localhost\",\n };\n const server = trackServer(\n createProxyServer({\n getRoutes: () => routes,\n getAliases: () => aliases,\n proxyPort: TEST_PROXY_PORT,\n })\n );\n await listen(server);\n\n // Alias points to \"other.localhost\" which doesn't exist;\n // only one route so tunnel passthrough kicks in\n const res = await request(server, { host: \"abc123.ngrok-free.app\" });\n expect(res.status).toBe(200);\n });" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run test 2>&1", "description": "Run all tests after fix", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 test /Users/sergiydybskiy/src/portless/packages/portless > vitest run  RUN  v4.0.18 /Users/sergiydybskiy/src/portless/packages/portless ✓ src/utils.test.ts (44 tests) 5ms ✓ src/tunnel.test.ts (8 tests) 14ms ✓ src/hosts.test.ts (18 tests) 11ms ✓ src/cli-utils.test.ts (46 tests) 22ms ✓ src/routes.test.ts (31 tests) 26ms ✓ src/auto.test.ts (42 tests) 424ms Certificate request self-signature ok subject=CN=localhost ✓ src/certs.test.ts (18 tests) 945ms ✓ src/cli.test.ts (62 tests) 2588ms (node:62234) [DEP0123] DeprecationWarning: Setting the TLS ServerName to an IP address is not permitted by RFC 6066. This will be ignored in a future version. (Use `node --trace-deprecation ...` to show where the warning was created) ✓ src/proxy.test.ts (47 tests) 8188ms ✓ creates an HTTPS server that responds to requests  1019ms ✓ includes X-Portless header on TLS responses  1003ms ✓ proxies HTTPS request to matching route  1005ms ✓ supports HTTP/2 connections  1010ms ✓ still accepts HTTP/1.1 connections over TLS (allowHTTP1)  1009ms ✓ generates https:// URLs in 404 page  1010ms ✓ sets x-forwarded-proto to https when proxying  1008ms ✓ accepts plain HTTP on the TLS-enabled port  1005ms  Test Files  9 passed (9)  Tests  316 passed (316)  Start at  09:31:26  Duration  8.43s (transform 719ms, setup 0ms, import 921ms, tests 12.22s, environment 1ms) ``` ## Assistant All 316 tests pass (29 new tests added). Let me also run lint and typecheck one final time: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run typecheck 2>&1 && pnpm run lint 2>&1", "description": "Final typecheck and lint", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 typecheck /Users/sergiydybskiy/src/portless/packages/portless > tsc --noEmit > portless@0.6.0 lint /Users/sergiydybskiy/src/portless/packages/portless > eslint src/ ``` ## Assistant Clean on typecheck and lint. Let me update the todos and summarize: ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" } ] ``` ## Assistant Everything is implemented and passing. Here's a summary of what was done: --- ## Summary **Branch:** `feat/tunnel-support` ### Files changed | File | Changes | |------|---------| | `proxy.ts` | `findRoute()` extended with tunnel passthrough (Phase 1) + alias lookup (Phase 2); wired `getAliases` from options | | `types.ts` | Added `getAliases` to `ProxyServerOptions` | | `routes.ts` | Added `aliases.json` path + `loadAliases`, `addAlias`, `removeAlias`, `removeAliasesForRoute` to `RouteStore` | | `tunnel.ts` | **New file**: `TunnelProvider`/`TunnelInstance` interfaces, ngrok + cloudflare providers, provider registry | | `cli.ts` | `--tunnel` flag in arg parsers, `PORTLESS_TUNNEL` env var, `parseTunnelArg`/`tunnelFromEnv` helpers, `handleTunnel` command (map/unmap/list), `runApp` now starts/manages tunnel + sets `PORTLESS_TUNNEL_URL`, alias watching in proxy startup, updated help text | | `index.ts` | Exports `tunnel.ts` | | `README.md` | New "Tunnels" section, tunnel commands, `--tunnel` flag, `PORTLESS_TUNNEL`/`PORTLESS_TUNNEL_URL` env vars | | `SKILL.md` | Tunnels section, updated CLI reference table, env vars table, reserved names | ### New test files/tests (29 new tests, 316 total) | File | Tests added | |------|-------------| | `proxy.test.ts` | 10 tests: tunnel passthrough (6) + alias routing (4) | | `routes.test.ts` | 11 tests: alias CRUD, edge cases | | `tunnel.test.ts` | 8 tests: provider registry, interface checks | ### How it works 1. **Single-app passthrough**: With one app running, any non-`.localhost` Host header (e.g., from ngrok/cloudflare) is automatically routed to the app. Zero config needed. 2. **Multi-app aliases**: `portless tunnel map myapp abc123.ngrok-free.app` teaches the proxy to route tunnel traffic to a specific app. 3. **Managed tunnels**: `portless myapp --tunnel ngrok next dev` starts the app AND the tunnel, auto-registers the alias, and passes `PORTLESS_TUNNEL_URL` to the child process. ## User basd on the other PRs and everything else in the repo, is this a meaningful change we're introducing properly? ## Assistant Good question. Let me audit this properly against the repo's standards before committing anything. ## Assistant ### Tool: task **Args:** ```json { "description": "Audit PR quality against repo standards", "prompt": "I need a thorough audit of the portless repository's conventions, patterns, and quality standards. Please investigate:\n\n1. **Existing PRs and commits**: Run `git log --oneline -30` and `git log --format='%s' -30` to see commit message style. Also check `gh pr list --state merged --limit 10` and `gh pr list --state open` to see PR patterns.\n\n2. **Code style in existing files**: Look at how existing modules are structured:\n - How are new modules introduced? Do they follow specific patterns?\n - How is error handling done?\n - Are there JSDoc comments everywhere? What level of documentation?\n - How are constants named and organized?\n\n3. **Test patterns**: Read the existing test files to understand:\n - Test naming conventions\n - What level of coverage is expected?\n - How are edge cases tested?\n - Are CLI tests integration tests or unit tests?\n\n4. **AGENTS.md rules**: Re-read `/Users/sergiydybskiy/src/portless/AGENTS.md` carefully for any rules we might be violating.\n\n5. **Check the diff**: Run `git diff --stat` and `git diff` to see all our changes. Look for:\n - Inconsistencies with the rest of the codebase\n - Missing error handling patterns\n - Code that doesn't match the existing style\n - Any emojis (forbidden per AGENTS.md)\n - Boolean env var documentation (should use 0/1 per AGENTS.md)\n\n6. **README.md conventions**: Read the full README to understand the documentation style - is it terse? verbose? Does our new section match the tone?\n\n7. **SKILL.md conventions**: Same analysis for SKILL.md.\n\n8. **Package.json**: Check if we need to update anything (exports, etc.)\n\nReturn a detailed list of issues found, if any, organized by severity (blockers, important, minor). Include specific file paths and line numbers.", "subagent_type": "explore" } ``` ## Assistant **Result** (success): ``` task_id: ses_322e13dabffe5nQs89eu5z363K (for resuming to continue this task if needed) Now I have all the information I need for the comprehensive audit. Here is my detailed findings report: --- # Portless Repository Audit Report ## Summary The tunnel support feature changes are **well-implemented overall**. All 316 tests pass, the build succeeds, linting is clean, and type-checking passes. The code follows existing patterns closely. However, there are a few issues to address. --- ## BLOCKERS **None found.** The code builds, passes all tests, passes linting, and passes type-checking. --- ## IMPORTANT ### 1. Missing `get` in reserved names lists (README.md, SKILL.md) **Files:** - `/Users/sergiydybskiy/src/portless/README.md` line 224 - `/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md` line 204 The `--help` output in `cli.ts` (line 938) correctly lists `get` as a reserved name: ``` run, get, alias, tunnel, hosts, list, trust, proxy are subcommands ``` But both `README.md` and `SKILL.md` omit `get`: ``` `run`, `alias`, `tunnel`, `hosts`, `list`, `trust`, and `proxy` ``` **Note:** This may be a pre-existing issue (the `get` command was added in PR #88), not introduced by this branch. But since these files are being modified in this PR, now is a good time to fix it. Per AGENTS.md, docs must be kept in sync. ### 2. Missing `get` in internal code comment (cli.ts) **File:** `/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts` line 1659 The comment reads: ```typescript // subcommand (run, alias, tunnel, hosts, list, trust, proxy). ``` It should include `get` to match the help text on line 938. ### 3. SKILL.md help subcommand hint is outdated **File:** `/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md` line 201 The CLI reference table says: ``` | `portless run --help` | Show help for a subcommand (also: alias, hosts) | ``` This should now mention `tunnel` as well, since `portless tunnel --help` is supported: ``` | `portless run --help` | Show help for a subcommand (also: alias, tunnel, hosts) | ``` ### 4. Alias watcher only started if aliases file already exists on proxy startup **File:** `/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts` lines 129-138 ```typescript if (fs.existsSync(aliasesPath)) { aliasWatcher = fs.watch(aliasesPath, () => { ... }); } ``` If the proxy starts before any tunnel aliases are created (which is the common case), the aliases file does not yet exist, and `aliasWatcher` stays null. The polling interval fallback only kicks in when `fs.watch` for routes also failed (line 139: `if (pollingInterval)`). In the normal case (fs.watch works for routes), the `pollingInterval` is null, meaning there is no polling fallback either. **Impact:** Newly added aliases (via `portless tunnel map`) will not be picked up by the proxy until the proxy is restarted, unless: - The aliases file existed at proxy startup, OR - `fs.watch` for routes failed (rare), triggering the polling fallback. **Fix options:** 1. Watch the directory instead of the file, so new file creation is detected. 2. Always set up a polling interval for aliases as a fallback. 3. Use `fs.watchFile()` (stat-based polling) for the aliases path, which works even when the file does not yet exist. --- ## MINOR ### 5. No CLI integration tests for the `tunnel` subcommand **File:** `/Users/sergiydybskiy/src/portless/packages/portless/src/cli.test.ts` The existing `cli.test.ts` has integration tests for every subcommand: `--help`, `--version`, `list`, `proxy`, `alias`, `hosts`, `get`, `run`, and `--name`. There are no tests for the new `tunnel` subcommand. Following the established pattern, the following tests should be added: - `portless tunnel --help` prints help and exits 0 - `portless tunnel -h` prints help and exits 0 - `portless tunnel` with no subcommand exits 1 - `portless tunnel typo` exits 1 with "Unknown tunnel subcommand" - `portless tunnel map` with missing args exits 1 The `alias`, `hosts`, and `get` subcommand test blocks in `cli.test.ts` (lines 291-448) are the pattern to follow. ### 6. Unused `waitForOutput` helper **File:** `/Users/sergiydybskiy/src/portless/packages/portless/src/tunnel.ts` lines 47-83 The `waitForOutput` function is used by the Cloudflare provider but is exported only implicitly (not in the public API). This is fine -- it is a private helper. However, it does not have a direct unit test. The `tunnel.test.ts` file only tests the provider registry, not the actual tunnel start/stop behavior. This is understandable since testing actual ngrok/cloudflared spawning requires those binaries. ### 7. `ParsedAppArgs` inherits `tunnel` from `ParsedRunArgs` implicitly **File:** `/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts` line 620 ```typescript interface ParsedAppArgs extends ParsedRunArgs { /** App name. */ name: string; } ``` The `tunnel` field is inherited from `ParsedRunArgs` (line 615). This works correctly but could be confusing since `ParsedRunArgs.name` is optional (from `--name`) while `ParsedAppArgs.name` is required. The inherited `tunnel` field lacks its own JSDoc on `ParsedAppArgs`. This is a very minor style point -- the existing codebase also inherits `force` and `appPort` the same way. ### 8. `removeAliasesForRoute` is defined but not called **File:** `/Users/sergiydybskiy/src/portless/packages/portless/src/routes.ts` lines 335-355 The `removeAliasesForRoute()` method is implemented and tested but never called in the actual CLI code. When `runApp` cleans up on exit (cli.ts line 586), it removes a single alias by hostname. But if a route is removed via `portless alias --remove`, the associated aliases are not cleaned up. This is minor -- the method is exported for future use and has tests -- but it represents dead code currently. ### 9. Consistent formatting in README tunnel section **File:** `/Users/sergiydybskiy/src/portless/README.md` lines 134-160 The README section uses `**Managed tunnel (recommended)**` with a bold label followed by `--`. This matches the existing README style (e.g., the "How it works" section uses similar formatting). This is fine and consistent. ### 10. `PORTLESS_TUNNEL` is not a boolean env var **File:** `/Users/sergiydybskiy/src/portless/README.md` line 215 `PORTLESS_TUNNEL=` takes a string value (provider name), not a boolean. The AGENTS.md rule about documenting booleans with `0`/`1` does not apply here. This is **not a violation** -- just calling it out as verified. --- ## THINGS THAT ARE CORRECT The following were specifically checked and found to be consistent: - **No emojis** anywhere in the changes (verified with regex scan). - **Boolean env vars** use `0`/`1` in documentation (PORTLESS_HTTPS=1, PORTLESS_SYNC_HOSTS=1, PORTLESS=0). - **Error handling patterns** match the existing codebase: `try/catch` with `// Non-fatal` comments, chalk.red for errors, chalk.blue for hints, chalk.cyan for commands, process.exit(1). - **JSDoc comments** are present on all public interfaces and methods, matching the existing level of documentation. - **Constants** follow existing naming patterns (UPPER_SNAKE_CASE for module-level constants). - **Test naming** follows the existing pattern: `describe` blocks for logical groupings, `it` statements describing behavior. - **Test coverage** is thorough: 6 tunnel passthrough tests, 4 alias routing tests, 12 alias store tests, 8 tunnel provider registry tests. - **All three documentation targets** are updated per AGENTS.md: README.md, SKILL.md, and cli.ts --help output. - **Package.json exports** do not need updating. The `index.ts` re-exports `./tunnel.js`, which flows through the existing `exports` configuration. - **Commit message style** -- the branch is `feat/tunnel-support`, matching the conventional commit prefix pattern used in the repo (e.g., `feat(cli):`, `feat:`, `fix:`). - **Module structure** matches existing patterns: `tunnel.ts` for implementation, `tunnel.test.ts` for tests, re-exported from `index.ts`. - **Import ordering** matches existing patterns: Node built-ins first, then local imports. ``` ## Assistant ## Assistant Good call to check. The audit found several real issues. Let me fix them. ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" }, { "content": "Fix: alias watcher not created when aliases.json doesn't exist at startup", "priority": "high", "status": "pending" }, { "content": "Fix: add missing 'get' to reserved names in README.md and SKILL.md", "priority": "medium", "status": "pending" }, { "content": "Fix: update SKILL.md help subcommand hint to mention tunnel", "priority": "medium", "status": "pending" }, { "content": "Fix: add CLI integration tests for tunnel subcommand", "priority": "medium", "status": "pending" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" }, { "content": "Fix: alias watcher not created when aliases.json doesn't exist at startup", "priority": "high", "status": "pending" }, { "content": "Fix: add missing 'get' to reserved names in README.md and SKILL.md", "priority": "medium", "status": "pending" }, { "content": "Fix: update SKILL.md help subcommand hint to mention tunnel", "priority": "medium", "status": "pending" }, { "content": "Fix: add CLI integration tests for tunnel subcommand", "priority": "medium", "status": "pending" } ] ``` ## Assistant The most serious issue is the alias watcher bug. Let me fix that first, then the docs issues, then the missing CLI tests. ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" }, { "content": "Fix: alias watcher not created when aliases.json doesn't exist at startup", "priority": "high", "status": "in_progress" }, { "content": "Fix: add missing 'get' to reserved names in README.md and SKILL.md", "priority": "medium", "status": "pending" }, { "content": "Fix: update SKILL.md help subcommand hint to mention tunnel", "priority": "medium", "status": "pending" }, { "content": "Fix: add CLI integration tests for tunnel subcommand", "priority": "medium", "status": "pending" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" }, { "content": "Fix: alias watcher not created when aliases.json doesn't exist at startup", "priority": "high", "status": "in_progress" }, { "content": "Fix: add missing 'get' to reserved names in README.md and SKILL.md", "priority": "medium", "status": "pending" }, { "content": "Fix: update SKILL.md help subcommand hint to mention tunnel", "priority": "medium", "status": "pending" }, { "content": "Fix: add CLI integration tests for tunnel subcommand", "priority": "medium", "status": "pending" } ] ``` ## Assistant **Bug: alias watcher not started when aliases.json doesn't exist at proxy startup.** The best fix is to watch the state directory for new files, then start watching aliases.json when it appears. Let me read the current code: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "limit": 55, "offset": 115 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts file 115: 116: try { 117: watcher = fs.watch(routesPath, () => { 118: if (debounceTimer) clearTimeout(debounceTimer); 119: debounceTimer = setTimeout(reloadRoutes, DEBOUNCE_MS); 120: }); 121: } catch { 122: // fs.watch may not be supported; fall back to periodic polling 123: console.warn(chalk.yellow("fs.watch unavailable; falling back to polling for route changes")); 124: pollingInterval = setInterval(reloadRoutes, POLL_INTERVAL_MS); 125: } 126: 127: // Watch aliases file if it exists; also reload aliases on polling interval 128: const aliasesPath = store.getAliasesPath(); 129: try { 130: if (fs.existsSync(aliasesPath)) { 131: aliasWatcher = fs.watch(aliasesPath, () => { 132: if (aliasDebounceTimer) clearTimeout(aliasDebounceTimer); 133: aliasDebounceTimer = setTimeout(reloadAliases, DEBOUNCE_MS); 134: }); 135: } 136: } catch { 137: // Non-fatal; aliases will be reloaded on the polling interval if set 138: } 139: if (pollingInterval) { 140: // Piggyback alias reloads on the existing polling interval 141: const existingInterval = pollingInterval; 142: clearInterval(existingInterval); 143: pollingInterval = setInterval(() => { 144: reloadRoutes(); 145: reloadAliases(); 146: }, POLL_INTERVAL_MS); 147: } 148: 149: if (autoSyncHosts) { 150: syncHostsFile(cachedRoutes.map((r) => r.hostname)); 151: } 152: 153: const server = createProxyServer({ 154: getRoutes: () => cachedRoutes, 155: getAliases: () => cachedAliases, 156: proxyPort, 157: tld, 158: onError: (msg) => console.error(chalk.red(msg)), 159: tls: tlsOptions, 160: }); 161: 162: server.on("error", (err: NodeJS.ErrnoException) => { 163: if (err.code === "EADDRINUSE") { 164: console.error(chalk.red(`Port ${proxyPort} is already in use.`)); 165: console.error(chalk.blue("Stop the existing proxy first:")); 166: console.error(chalk.cyan(" portless proxy stop")); 167: console.error(chalk.blue("Or check what is using the port:")); 168: console.error(chalk.cyan(` lsof -ti tcp:${proxyPort}`)); 169: } else if (err.code === "EACCES") { (Showing lines 115-169 of 1758. Use offset=170 to continue.) ``` ## Assistant The cleanest approach: watch the state directory itself for changes, and when the aliases file appears, start watching it. But `fs.watch` on directories can be noisy. A simpler and more robust approach: just piggyback alias reloads on the routes file watcher. When routes change, aliases likely changed too (managed tunnel adds alias alongside route registration). For the `portless tunnel map` case (manual alias without route change), we can watch the directory. Actually, the simplest robust fix: use `fs.watchFile()` for aliases. Unlike `fs.watch()`, it works on non-existent files (it polls via `stat`). It's stat-based polling but with a configurable interval, and it's the Node.js recommended approach for files that may not exist yet. ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " // Watch aliases file. Use fs.watchFile (stat-based polling) instead of\n // fs.watch because the file may not exist yet at proxy startup -- it is\n // created on first `portless tunnel map` or `--tunnel` invocation.\n const aliasesPath = store.getAliasesPath();\n fs.watchFile(aliasesPath, { interval: POLL_INTERVAL_MS }, () => {\n if (aliasDebounceTimer) clearTimeout(aliasDebounceTimer);\n aliasDebounceTimer = setTimeout(reloadAliases, DEBOUNCE_MS);\n });\n if (pollingInterval) {\n // Piggyback alias reloads on the existing polling interval (fs.watch\n // was unavailable for routes, so we already fall back to polling)\n const existingInterval = pollingInterval;\n clearInterval(existingInterval);\n pollingInterval = setInterval(() => {\n reloadRoutes();\n reloadAliases();\n }, POLL_INTERVAL_MS);\n }", "oldString": " // Watch aliases file if it exists; also reload aliases on polling interval\n const aliasesPath = store.getAliasesPath();\n try {\n if (fs.existsSync(aliasesPath)) {\n aliasWatcher = fs.watch(aliasesPath, () => {\n if (aliasDebounceTimer) clearTimeout(aliasDebounceTimer);\n aliasDebounceTimer = setTimeout(reloadAliases, DEBOUNCE_MS);\n });\n }\n } catch {\n // Non-fatal; aliases will be reloaded on the polling interval if set\n }\n if (pollingInterval) {\n // Piggyback alias reloads on the existing polling interval\n const existingInterval = pollingInterval;\n clearInterval(existingInterval);\n pollingInterval = setInterval(() => {\n reloadRoutes();\n reloadAliases();\n }, POLL_INTERVAL_MS);\n }" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now the `aliasWatcher` variable is no longer used for `fs.watch`. I need to update the cleanup to use `fs.unwatchFile` instead, and remove the now-unused `aliasWatcher` variable: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " let cachedAliases = store.loadAliases();\n let debounceTimer: ReturnType | null = null;\n let aliasDebounceTimer: ReturnType | null = null;\n let watcher: fs.FSWatcher | null = null;\n let pollingInterval: ReturnType | null = null;", "oldString": " let cachedAliases = store.loadAliases();\n let debounceTimer: ReturnType | null = null;\n let aliasDebounceTimer: ReturnType | null = null;\n let watcher: fs.FSWatcher | null = null;\n let aliasWatcher: fs.FSWatcher | null = null;\n let pollingInterval: ReturnType | null = null;" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now update the cleanup function: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " if (watcher) {\n watcher.close();\n }\n fs.unwatchFile(aliasesPath);", "oldString": " if (watcher) {\n watcher.close();\n }\n if (aliasWatcher) {\n aliasWatcher.close();\n }" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now fix the docs issues. First, the reserved names in README.md and SKILL.md (add missing `get`): ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/README.md", "newString": "> **Reserved names:** `run`, `get`, `alias`, `tunnel`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name from your project, or `portless --name ` to force any name including reserved ones.", "oldString": "> **Reserved names:** `run`, `alias`, `tunnel`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name from your project, or `portless --name ` to force any name including reserved ones." } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md", "newString": "**Reserved names:** `run`, `get`, `alias`, `tunnel`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name, or `portless --name ` to force any name including reserved ones.", "oldString": "**Reserved names:** `run`, `alias`, `tunnel`, `hosts`, `list`, `trust`, and `proxy` are subcommands and cannot be used as app names directly. Use `portless run ` to infer the name, or `portless --name ` to force any name including reserved ones." } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Fix the internal code comment in cli.ts: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.ts", "newString": " // subcommand dispatch. Useful when the app name collides with a reserved\n // subcommand (run, get, alias, tunnel, hosts, list, trust, proxy).", "oldString": " // subcommand dispatch. Useful when the app name collides with a reserved\n // subcommand (run, alias, tunnel, hosts, list, trust, proxy)." } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Update the SKILL.md help subcommand hint to mention `tunnel`: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/skills/portless/SKILL.md", "newString": "| `portless run --help` | Show help for a subcommand (also: alias, tunnel, hosts) |", "oldString": "| `portless run --help` | Show help for a subcommand (also: alias, hosts) |" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" }, { "content": "Fix: alias watcher not created when aliases.json doesn't exist at startup", "priority": "high", "status": "completed" }, { "content": "Fix: add missing 'get' to reserved names in README.md and SKILL.md", "priority": "medium", "status": "completed" }, { "content": "Fix: update SKILL.md help subcommand hint to mention tunnel", "priority": "medium", "status": "completed" }, { "content": "Fix: add CLI integration tests for tunnel subcommand", "priority": "medium", "status": "in_progress" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" }, { "content": "Fix: alias watcher not created when aliases.json doesn't exist at startup", "priority": "high", "status": "completed" }, { "content": "Fix: add missing 'get' to reserved names in README.md and SKILL.md", "priority": "medium", "status": "completed" }, { "content": "Fix: update SKILL.md help subcommand hint to mention tunnel", "priority": "medium", "status": "completed" }, { "content": "Fix: add CLI integration tests for tunnel subcommand", "priority": "medium", "status": "in_progress" } ] ``` ## Assistant Now add CLI integration tests for the `tunnel` subcommand. Let me read the existing patterns: ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.test.ts", "limit": 60, "offset": 1 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.test.ts file 1: import { describe, it, expect, beforeAll, beforeEach, afterEach } from "vitest"; 2: import { spawnSync } from "node:child_process"; 3: import * as fs from "node:fs"; 4: import * as os from "node:os"; 5: import * as path from "node:path"; 6: import { fileURLToPath } from "node:url"; 7: 8: const __dirname = path.dirname(fileURLToPath(import.meta.url)); 9: const CLI_PATH = path.resolve(__dirname, "../dist/cli.js"); 10: 11: /** Run the CLI with the given args and optional env overrides. */ 12: function run(args: string[], options?: { env?: Record }) { 13: const result = spawnSync(process.execPath, [CLI_PATH, ...args], { 14: encoding: "utf-8", 15: timeout: 10_000, 16: env: { ...process.env, ...options?.env, NO_COLOR: "1" }, 17: }); 18: return { 19: status: result.status, 20: stdout: result.stdout, 21: stderr: result.stderr, 22: }; 23: } 24: 25: describe("CLI", () => { 26: beforeAll(() => { 27: if (!fs.existsSync(CLI_PATH)) { 28: throw new Error(`Built CLI not found at ${CLI_PATH}. Run 'pnpm build' before running tests.`); 29: } 30: }); 31: 32: describe("--help", () => { 33: it("prints help and exits 0 with --help", () => { 34: const { status, stdout } = run(["--help"]); 35: expect(status).toBe(0); 36: expect(stdout).toContain("portless"); 37: expect(stdout).toContain("Usage:"); 38: expect(stdout).toContain("Examples:"); 39: expect(stdout).toContain("proxy start"); 40: expect(stdout).toContain("portless run"); 41: expect(stdout).toContain("portless get"); 42: expect(stdout).toContain("run [--name ]"); 43: expect(stdout).toContain("--port"); 44: expect(stdout).toContain("-p"); 45: expect(stdout).toContain("--foreground"); 46: expect(stdout).toContain("PORTLESS_STATE_DIR"); 47: expect(stdout).toContain("PORTLESS_URL"); 48: }); 49: 50: it("prints help and exits 0 with -h", () => { 51: const { status, stdout } = run(["-h"]); 52: expect(status).toBe(0); 53: expect(stdout).toContain("Usage:"); 54: }); 55: 56: it("prints help and exits 0 with no args", () => { 57: const { status, stdout } = run([]); 58: expect(status).toBe(0); 59: expect(stdout).toContain("Usage:"); 60: }); (Showing lines 1-60 of 523. Use offset=61 to continue.) ``` ## Assistant Let me see the existing `alias` and `hosts` test blocks to follow the pattern: ## Assistant ### Tool: grep **Args:** ```json { "include": "cli.test.ts", "pattern": "describe\\(\"" } ``` ## Assistant **Result** (success): ``` Found 19 matches /Users/sergiydybskiy/src/portless/packages/portless/src/cli.test.ts: Line 25: describe("CLI", () => { Line 32: describe("--help", () => { Line 63: describe("--version", () => { Line 78: describe("list", () => { Line 87: describe("proxy", () => { Line 103: describe("error: no command provided", () => { Line 111: describe("PORTLESS=0 bypass", () => { Line 145: describe("PORTLESS=0 bypass with run subcommand", () => { Line 171: describe("--force positioning", () => { Line 197: describe("unknown flag detection", () => { Line 205: describe("invalid hostname", () => { Line 215: describe("run subcommand dispatch", () => { Line 257: describe("--app-port flag", () => { Line 291: describe("alias subcommand", () => { Line 330: describe("hosts subcommand", () => { Line 359: describe("proxy subcommand", () => { Line 387: describe("get subcommand", () => { Line 450: describe("--name flag", () => { Line 480: describe("run --name flag", () => { ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.test.ts", "limit": 60, "offset": 291 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.test.ts file 291: describe("alias subcommand", () => { 292: it("prints help with --help", () => { 293: const { status, stdout } = run(["alias", "--help"]); 294: expect(status).toBe(0); 295: expect(stdout).toContain("portless alias"); 296: expect(stdout).toContain("--remove"); 297: }); 298: 299: it("prints help with -h", () => { 300: const { status, stdout } = run(["alias", "-h"]); 301: expect(status).toBe(0); 302: expect(stdout).toContain("portless alias"); 303: }); 304: 305: it("exits 1 with usage when no args given", () => { 306: const { status, stderr } = run(["alias"]); 307: expect(status).toBe(1); 308: expect(stderr).toContain("Missing arguments"); 309: }); 310: 311: it("exits 1 with usage when only name is given", () => { 312: const { status, stderr } = run(["alias", "mydb"]); 313: expect(status).toBe(1); 314: expect(stderr).toContain("Missing arguments"); 315: }); 316: 317: it("exits 1 for invalid port", () => { 318: const { status, stderr } = run(["alias", "mydb", "notaport"]); 319: expect(status).toBe(1); 320: expect(stderr).toContain("Invalid port"); 321: }); 322: 323: it("exits 1 when --remove has no name", () => { 324: const { status, stderr } = run(["alias", "--remove"]); 325: expect(status).toBe(1); 326: expect(stderr).toContain("No alias name"); 327: }); 328: }); 329: 330: describe("hosts subcommand", () => { 331: it("prints help with --help", () => { 332: const { status, stdout } = run(["hosts", "--help"]); 333: expect(status).toBe(0); 334: expect(stdout).toContain("portless hosts"); 335: expect(stdout).toContain("sync"); 336: expect(stdout).toContain("clean"); 337: }); 338: 339: it("prints help with -h", () => { 340: const { status, stdout } = run(["hosts", "-h"]); 341: expect(status).toBe(0); 342: expect(stdout).toContain("portless hosts"); 343: }); 344: 345: it("shows usage for bare 'hosts' without subcommand", () => { 346: const { status, stdout } = run(["hosts"]); 347: expect(status).toBe(0); 348: expect(stdout).toContain("sync"); 349: expect(stdout).toContain("clean"); 350: }); (Showing lines 291-350 of 523. Use offset=351 to continue.) ``` ## Assistant ### Tool: read **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.test.ts", "limit": 10, "offset": 351 } ``` ## Assistant **Result** (success): ``` /Users/sergiydybskiy/src/portless/packages/portless/src/cli.test.ts file 351: 352: it("rejects unknown hosts subcommand", () => { 353: const { status, stderr } = run(["hosts", "typo"]); 354: expect(status).toBe(1); 355: expect(stderr).toContain("Unknown hosts subcommand"); 356: }); 357: }); 358: 359: describe("proxy subcommand", () => { 360: it("prints help with --help", () => { (Showing lines 351-360 of 523. Use offset=361 to continue.) ``` ## Assistant Good, I see the pattern. Now add tunnel subcommand tests after the `hosts` describe block: ## Assistant ### Tool: edit **Args:** ```json { "filePath": "/Users/sergiydybskiy/src/portless/packages/portless/src/cli.test.ts", "newString": " it(\"rejects unknown hosts subcommand\", () => {\n const { status, stderr } = run([\"hosts\", \"typo\"]);\n expect(status).toBe(1);\n expect(stderr).toContain(\"Unknown hosts subcommand\");\n });\n });\n\n describe(\"tunnel subcommand\", () => {\n it(\"prints help with --help\", () => {\n const { status, stdout } = run([\"tunnel\", \"--help\"]);\n expect(status).toBe(0);\n expect(stdout).toContain(\"portless tunnel\");\n expect(stdout).toContain(\"map\");\n expect(stdout).toContain(\"unmap\");\n expect(stdout).toContain(\"list\");\n });\n\n it(\"prints help with -h\", () => {\n const { status, stdout } = run([\"tunnel\", \"-h\"]);\n expect(status).toBe(0);\n expect(stdout).toContain(\"portless tunnel\");\n });\n\n it(\"exits 1 with usage when no subcommand given\", () => {\n const { status, stdout } = run([\"tunnel\"]);\n expect(status).toBe(1);\n expect(stdout).toContain(\"portless tunnel\");\n });\n\n it(\"exits 1 for unknown tunnel subcommand\", () => {\n const { status, stderr } = run([\"tunnel\", \"typo\"]);\n expect(status).toBe(1);\n expect(stderr).toContain(\"Unknown tunnel subcommand\");\n });\n\n it(\"exits 1 when map has missing arguments\", () => {\n const { status, stderr } = run([\"tunnel\", \"map\"]);\n expect(status).toBe(1);\n expect(stderr).toContain(\"Missing arguments\");\n });\n\n it(\"exits 1 when map has only name but no hostname\", () => {\n const { status, stderr } = run([\"tunnel\", \"map\", \"myapp\"]);\n expect(status).toBe(1);\n expect(stderr).toContain(\"Missing arguments\");\n });\n\n it(\"exits 1 when unmap has no hostname\", () => {\n const { status, stderr } = run([\"tunnel\", \"unmap\"]);\n expect(status).toBe(1);\n expect(stderr).toContain(\"No hostname provided\");\n });\n });", "oldString": " it(\"rejects unknown hosts subcommand\", () => {\n const { status, stderr } = run([\"hosts\", \"typo\"]);\n expect(status).toBe(1);\n expect(stderr).toContain(\"Unknown hosts subcommand\");\n });\n });" } ``` ## Assistant **Result** (success): ``` Edit applied successfully. ``` ## Assistant Now let me also check a detail: the `--tunnel` flag should also be rejected for unknown providers in the CLI tests. Let me also add a test for that in the unknown flag detection section. But first, let me check if we need to rebuild and rerun: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run typecheck 2>&1 && pnpm run build 2>&1 && pnpm run test 2>&1", "description": "Typecheck, build, and run all tests", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 typecheck /Users/sergiydybskiy/src/portless/packages/portless > tsc --noEmit > portless@0.6.0 build /Users/sergiydybskiy/src/portless/packages/portless > tsup CLI Building entry: src/cli.ts, src/index.ts CLI Using tsconfig: tsconfig.json CLI tsup v8.5.1 CLI Using tsup config: /Users/sergiydybskiy/src/portless/packages/portless/tsup.config.ts CLI Target: es2022 CLI Cleaning output folder ESM Build start ESM dist/cli.js 71.09 KB ESM dist/index.js 915.00 B ESM dist/chunk-CL3H4345.js 186.34 KB ESM ⚡️ Build success in 19ms DTS Build start DTS ⚡️ Build success in 1230ms DTS dist/cli.d.ts 20.00 B DTS dist/index.d.ts 8.66 KB > portless@0.6.0 test /Users/sergiydybskiy/src/portless/packages/portless > vitest run  RUN  v4.0.18 /Users/sergiydybskiy/src/portless/packages/portless ✓ src/utils.test.ts (44 tests) 5ms ✓ src/tunnel.test.ts (8 tests) 19ms ✓ src/hosts.test.ts (18 tests) 12ms ✓ src/cli-utils.test.ts (46 tests) 32ms ✓ src/routes.test.ts (31 tests) 36ms ✓ src/auto.test.ts (42 tests) 435ms Certificate request self-signature ok subject=CN=localhost ✓ src/certs.test.ts (18 tests) 986ms (node:66443) [DEP0123] DeprecationWarning: Setting the TLS ServerName to an IP address is not permitted by RFC 6066. This will be ignored in a future version. (Use `node --trace-deprecation ...` to show where the warning was created) ✓ src/cli.test.ts (69 tests) 3216ms ✓ src/proxy.test.ts (47 tests) 8167ms ✓ creates an HTTPS server that responds to requests  1019ms ✓ includes X-Portless header on TLS responses  1003ms ✓ proxies HTTPS request to matching route  1005ms ✓ supports HTTP/2 connections  1007ms ✓ still accepts HTTP/1.1 connections over TLS (allowHTTP1)  1004ms ✓ generates https:// URLs in 404 page  1005ms ✓ sets x-forwarded-proto to https when proxying  1005ms ✓ accepts plain HTTP on the TLS-enabled port  1002ms  Test Files  9 passed (9)  Tests  323 passed (323)  Start at  09:43:36  Duration  8.44s (transform 806ms, setup 0ms, import 1.03s, tests 12.91s, environment 1ms) ``` ## Assistant All 323 tests pass. Let me also run lint one more time: ## Assistant ### Tool: bash **Args:** ```json { "command": "pnpm run lint 2>&1", "description": "Final lint check", "workdir": "/Users/sergiydybskiy/src/portless/packages/portless" } ``` ## Assistant **Result** (success): ``` > portless@0.6.0 lint /Users/sergiydybskiy/src/portless/packages/portless > eslint src/ ``` ## Assistant ### Tool: todowrite **Args:** ```json { "todos": [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" }, { "content": "Fix: alias watcher not created when aliases.json doesn't exist at startup", "priority": "high", "status": "completed" }, { "content": "Fix: add missing 'get' to reserved names in README.md and SKILL.md", "priority": "medium", "status": "completed" }, { "content": "Fix: update SKILL.md help subcommand hint to mention tunnel", "priority": "medium", "status": "completed" }, { "content": "Fix: add CLI integration tests for tunnel subcommand", "priority": "medium", "status": "completed" } ] } ``` ## Assistant **Result** (success): ``` [ { "content": "Phase 1: Default-route fallback for tunnel passthrough", "priority": "high", "status": "completed" }, { "content": "Phase 2: Tunnel hostname aliasing (portless tunnel command)", "priority": "high", "status": "completed" }, { "content": "Phase 3: Managed tunnel integration (--tunnel flag)", "priority": "medium", "status": "completed" }, { "content": "Update docs: README.md, SKILL.md, --help output", "priority": "high", "status": "completed" }, { "content": "Add tests for all three phases", "priority": "high", "status": "completed" }, { "content": "Fix: alias watcher not created when aliases.json doesn't exist at startup", "priority": "high", "status": "completed" }, { "content": "Fix: add missing 'get' to reserved names in README.md and SKILL.md", "priority": "medium", "status": "completed" }, { "content": "Fix: update SKILL.md help subcommand hint to mention tunnel", "priority": "medium", "status": "completed" }, { "content": "Fix: add CLI integration tests for tunnel subcommand", "priority": "medium", "status": "completed" } ] ``` ## Assistant Everything is clean. Here's the audit result: **Issues found and fixed:** | Issue | Severity | Fix | |-------|----------|-----| | Alias watcher not started when `aliases.json` doesn't exist at proxy startup | **Bug** | Switched from `fs.watch()` (requires file to exist) to `fs.watchFile()` (stat-based, works on non-existent files) | | `get` missing from reserved names in README.md and SKILL.md | Pre-existing, medium | Added `get` to both files | | `get` missing from code comment in cli.ts | Pre-existing, minor | Fixed comment | | SKILL.md help subcommand hint didn't mention `tunnel` | Medium | Updated | | No CLI integration tests for `tunnel` subcommand | Medium | Added 7 tests (help, missing args, unknown subcommand) | **Verified as correct (no issues):** - No emojis anywhere - Boolean env vars documented with `0`/`1` - Error handling follows existing patterns (chalk.red/blue/cyan, process.exit(1)) - JSDoc on all public interfaces/methods - Constants follow UPPER_SNAKE_CASE - Test naming follows existing conventions - All three doc targets updated per AGENTS.md (README, SKILL.md, --help) - No new dependencies needed - Module structure matches existing patterns (`.ts` + `.test.ts` + re-export from `index.ts`) **Final stats:** 323 tests passing, typecheck clean, lint clean. Want me to commit this? ## User yeah lets commit and create a PR also share a trace with direct visibility to it ## Assistant ### Tool: bash **Args:** ```json { "command": "git status", "description": "Check working tree status" } ``` ## Assistant **Result** (success): ``` On branch feat/tunnel-support Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git restore ..." to discard changes in working directory) modified: README.md modified: packages/portless/src/cli.test.ts modified: packages/portless/src/cli.ts modified: packages/portless/src/index.ts modified: packages/portless/src/proxy.test.ts modified: packages/portless/src/proxy.ts modified: packages/portless/src/routes.test.ts modified: packages/portless/src/routes.ts modified: packages/portless/src/types.ts modified: skills/portless/SKILL.md Untracked files: (use "git add ..." to include in what will be committed) packages/portless/src/tunnel.test.ts packages/portless/src/tunnel.ts no changes added to commit (use "git add" and/or "git commit -a") ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "git diff --stat", "description": "Show diff stats" } ``` ## Assistant **Result** (success): ``` README.md | 36 ++++- packages/portless/src/cli.test.ts | 47 ++++++ packages/portless/src/cli.ts | 302 ++++++++++++++++++++++++++++++++--- packages/portless/src/index.ts | 1 + packages/portless/src/proxy.test.ts | 234 +++++++++++++++++++++++++++ packages/portless/src/proxy.ts | 44 ++++- packages/portless/src/routes.test.ts | 79 +++++++++ packages/portless/src/routes.ts | 108 +++++++++++++ packages/portless/src/types.ts | 5 + skills/portless/SKILL.md | 87 ++++++---- 10 files changed, 890 insertions(+), 53 deletions(-) ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "git log --oneline -10", "description": "Check recent commit style" } ``` ## Assistant **Result** (success): ``` 8dda8ba release: v0.6.0 (#100) 6e48d2e prepare v0.6 (#99) da7d5d6 feat(cli): add --name flag to run command for setting base name (#89) ae9e3b5 custom tld (#93) 0158a3e Fix HTTPS proxy trust and stop on macOS with sudo (#98) e446df0 Add `portless get` command to retrieve URLs for other services (#88) 8d4bbb6 Fix DNS label length limit for worktree-prefixed hostnames (#87) 28b3f6d release: v0.5.2 (#82) 988c868 docs: add git worktree documentation (#81) 6625b55 feat(docs): replace mobile nav with slide-in sheet drawer (#80) ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "git add -A && git commit -m \"feat: add tunnel support (ngrok, Cloudflare Tunnel)\n\nSupport external tunnel providers for exposing local dev servers to the\ninternet. Three levels of integration:\n\n1. Single-app passthrough: when one app is running, non-.localhost Host\n headers (from tunnel forwarding) auto-route to the single app.\n\n2. Hostname aliasing: \\`portless tunnel map/unmap/list\\` maps external\n tunnel hostnames to portless routes for multi-app setups.\n\n3. Managed tunnels: \\`--tunnel ngrok\\` or \\`--tunnel cloudflare\\` starts\n the tunnel alongside the app, auto-registers the alias, and sets\n PORTLESS_TUNNEL_URL on the child process.\n\nCloses #43\"", "description": "Commit all tunnel support changes" } ``` ## Assistant **Result** (success): ``` [STARTED] Backing up original state... [COMPLETED] Backed up original state in git stash (fe1f12f) [STARTED] Running tasks for staged files... [STARTED] package.json — 12 files [STARTED] *.{ts,js} — 10 files [STARTED] *.{json,md,yml,yaml} — 2 files [STARTED] eslint --fix [STARTED] prettier --write [COMPLETED] prettier --write [COMPLETED] *.{json,md,yml,yaml} — 2 files [COMPLETED] eslint --fix [STARTED] prettier --write [COMPLETED] prettier --write [COMPLETED] *.{ts,js} — 10 files [COMPLETED] package.json — 12 files [COMPLETED] Running tasks for staged files... [STARTED] Applying modifications from tasks... [COMPLETED] Applying modifications from tasks... [STARTED] Cleaning up temporary files... [COMPLETED] Cleaning up temporary files... [feat/tunnel-support c1b6674] feat: add tunnel support (ngrok, Cloudflare Tunnel) 12 files changed, 1164 insertions(+), 53 deletions(-) create mode 100644 packages/portless/src/tunnel.test.ts create mode 100644 packages/portless/src/tunnel.ts ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "git status", "description": "Verify clean state after commit" } ``` ## Assistant **Result** (success): ``` On branch feat/tunnel-support nothing to commit, working tree clean ``` ## Assistant Commit succeeded, pre-commit hooks passed. Now push and create the PR: ## Assistant ### Tool: bash **Args:** ```json { "command": "git push -u origin feat/tunnel-support 2>&1", "description": "Push branch to remote" } ``` ## Assistant **Result** (success): ``` remote: remote: Create a pull request for 'feat/tunnel-support' on GitHub by visiting: remote: https://github.com/sergical/portless/pull/new/feat/tunnel-support remote: To github.com:sergical/portless.git * [new branch] feat/tunnel-support -> feat/tunnel-support branch 'feat/tunnel-support' set up to track 'origin/feat/tunnel-support'. ``` ## Assistant ### Tool: bash **Args:** ```json { "command": "gh pr create --title \"feat: add tunnel support (ngrok, Cloudflare Tunnel)\" --body \"$(cat <<'EOF'\n## Summary\n\nAdds support for external tunnel providers (ngrok, Cloudflare Tunnel) to expose local dev servers to the internet. Closes #43.\n\n## What changed\n\nThree levels of integration, each independently useful:\n\n### 1. Single-app passthrough (zero config)\n\nWhen one app is running and a request arrives with a non-`.localhost` Host header (e.g. from ngrok forwarding), portless auto-routes it to the single registered app. This means the simplest tunnel workflow just works:\n\n```bash\nportless myapp next dev # Terminal 1\nngrok http 1355 # Terminal 2 -- auto-routed\n```\n\n### 2. Hostname aliasing (`portless tunnel map/unmap/list`)\n\nFor multi-app setups, explicitly map an external tunnel hostname to a portless route:\n\n```bash\nportless tunnel map myapp abc123.ngrok-free.app\nportless tunnel unmap abc123.ngrok-free.app\nportless tunnel list\n```\n\nAliases are stored in `aliases.json` in the state directory and watched for changes by the proxy.\n\n### 3. Managed tunnels (`--tunnel` flag)\n\nPortless can start the tunnel for you, auto-register the alias, and pass the tunnel URL to the child process:\n\n```bash\nportless myapp --tunnel ngrok next dev\nportless run --tunnel cloudflare next dev\n```\n\nThe child process receives `PORTLESS_TUNNEL_URL` alongside the existing `PORTLESS_URL`. Tunnel cleanup (process kill + alias removal) happens automatically on exit.\n\n## Files changed\n\n| File | Changes |\n|------|---------|\n| `proxy.ts` | `findRoute()` extended with alias lookup + tunnel passthrough fallback |\n| `types.ts` | Added `getAliases` to `ProxyServerOptions` |\n| `routes.ts` | Alias storage: `loadAliases`, `addAlias`, `removeAlias`, `removeAliasesForRoute` |\n| `tunnel.ts` | **New**: `TunnelProvider`/`TunnelInstance` interfaces, ngrok + cloudflare providers |\n| `cli.ts` | `--tunnel` flag, `PORTLESS_TUNNEL` env var, `handleTunnel` command, alias watching in proxy startup |\n| `index.ts` | Re-exports `tunnel.ts` |\n| `README.md` | New \"Tunnels\" section, updated commands/options/env vars |\n| `SKILL.md` | Tunnel docs, updated CLI reference and env vars tables |\n| Tests | 36 new tests across `proxy.test.ts`, `routes.test.ts`, `tunnel.test.ts`, `cli.test.ts` |\n\n## Testing\n\n- 323 tests passing (36 new)\n- Typecheck clean\n- Lint clean\n- Zero new runtime dependencies\nEOF\n)\"", "description": "Create pull request" } ``` ## Assistant **Result** (success): ``` https://github.com/vercel-labs/portless/pull/104 ``` ## Assistant ### Tool: traces_share **Args:** ```json { "visibility": "direct" } ```