Add portless for local-dev HTTPS subdomains (#799)

* Add portless for local-dev HTTPS subdomains

Replaces port-juggling on bun run dev:* with stable named URLs:
web at https://releases.localhost, workers at
https://{api,mcp,discovery}.releases.localhost. Each script wraps the
underlying tool with `portless <name>` and forwards the assigned PORT
to wrangler / next so the proxy can route to the ephemeral port.

* Add PORTLESS_NAME override and document portless dev setup

Switches dev:* scripts from the positional `portless <name>` form to
`portless run --name <name>`, which preserves worktree-prefix detection
per the CLI help. The name now expands `${PORTLESS_NAME:-releases}` so
a single env var swaps the base across all four services. AGENTS.md
gets a Local development section covering subdomains, worktrees, the
override, and the wrangler --port wiring.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: zachdunn

AGENTS.md

@@ -19,6 +19,14 @@ Changelog indexer and registry for AI agents and developers. The user-facing CLI
 - Format: `bun run format:check`
 - **Evals (`tests/evals/`) are manual and on-demand only.** They call AI APIs, cost money, and take minutes. `bun run eval:evaluation` is the only in-repo suite (URL evaluation, ~30s). Parsing + discovery evals live in the OSS CLI repo.
 
+## Local development
+
+The four `dev:*` scripts (`dev:web`, `dev:api`, `dev:mcp`, `dev:discovery`) run each service through [portless](https://github.com/vercel-labs/portless) so they're reachable on stable HTTPS subdomains instead of port numbers — `https://releases.localhost` for the web frontend, `https://{api,mcp,discovery}.releases.localhost` for the workers. First run trusts a local CA and starts a daemon on port 443; subsequent runs reuse it. Apps mapping lives in `portless.json` for direct `portless` invocations from a workspace dir; the actual dev scripts pass `--name` explicitly so `portless run` picks up the override even outside a workspace.
+
+- **Worktrees:** linked git worktrees are detected automatically and the branch name is prepended (`feat-x.releases.localhost`, `feat-x.api.releases.localhost`, …) so multiple checkouts coexist without collision. No config needed — this is built into `portless run`.
+- **Override:** set `PORTLESS_NAME=foo` to swap the base name across all four services in one go (`foo.localhost`, `api.foo.localhost`, …). Useful when sharing a machine, demoing on a custom domain, or sidestepping a stuck route. Worktree prefixing still applies on top.
+- **Ports:** wrangler is invoked with `--port $PORT --ip 127.0.0.1` so it binds to the ephemeral port portless assigns; Next.js gets `--port $PORT` via `bun run dev`. Don't hard-code dev ports in wrangler.jsonc — portless's auto-assignment is what avoids conflicts when multiple services run simultaneously.
+
 ## Workspaces and carved-out packages
 
 Root `package.json` declares `workers/api`, `web`, and `packages/*` as workspaces. `workers/discovery/`, `workers/mcp/`, and `workers/webhooks/` are intentionally excluded — wrangler manages their dependencies independently.

bun.lock

@@ -5,10 +5,10 @@
   "description": "Changelog indexer and registry for AI agents and developers",
   "type": "module",
   "scripts": {
-    "dev:web": "cd web && bun run dev",
-    "dev:api": "wrangler dev --config workers/api/wrangler.jsonc",
-    "dev:discovery": "wrangler dev --config workers/discovery/wrangler.jsonc",
-    "dev:mcp": "wrangler dev --config workers/mcp/wrangler.jsonc",
+    "dev:web": "cd web && portless run --name ${PORTLESS_NAME:-releases} bun run dev -- --port $PORT",
+    "dev:api": "portless run --name api.${PORTLESS_NAME:-releases} wrangler dev --config workers/api/wrangler.jsonc --port $PORT --ip 127.0.0.1",
+    "dev:discovery": "portless run --name discovery.${PORTLESS_NAME:-releases} wrangler dev --config workers/discovery/wrangler.jsonc --port $PORT --ip 127.0.0.1",
+    "dev:mcp": "portless run --name mcp.${PORTLESS_NAME:-releases} wrangler dev --config workers/mcp/wrangler.jsonc --port $PORT --ip 127.0.0.1",
     "deploy:api": "wrangler deploy --config workers/api/wrangler.jsonc",
     "deploy:discovery": "wrangler deploy --config workers/discovery/wrangler.jsonc",
     "deploy:mcp": "wrangler deploy --config workers/mcp/wrangler.jsonc",
@@ -89,6 +89,7 @@
     "husky": "^9.1.7",
     "lint-staged": "^17.0.2",
     "oxlint": "^1.63.0",
+    "portless": "^0.12.0",
     "prettier": "^3.8.3",
     "typescript": "^6.0.3",
     "wrangler": "^4.88.0"

package.json

@@ -0,0 +1,9 @@
+{
+  "name": "releases",
+  "apps": {
+    "web": { "name": "releases" },
+    "workers/api": { "name": "api.releases" },
+    "workers/mcp": { "name": "mcp.releases" },
+    "workers/discovery": { "name": "discovery.releases" }
+  }
+}