rb-portless 0.5.2 → 0.17.0.0.dev.20261116.68cf72b

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. checksums.yaml +4 -4
  2. data/AGENTS.md +129 -110
  3. data/CHANGELOG.md +88 -0
  4. data/README.md +101 -210
  5. data/exe/rb-portless +14 -2
  6. data/lib/portless/args.rb +104 -0
  7. data/lib/portless/auto.rb +167 -0
  8. data/lib/portless/certs.rb +350 -118
  9. data/lib/portless/clean_utils.rb +221 -0
  10. data/lib/portless/cli.rb +921 -316
  11. data/lib/portless/cloudflare.rb +45 -0
  12. data/lib/portless/colors.rb +19 -6
  13. data/lib/portless/commands.rb +39 -0
  14. data/lib/portless/compose.rb +805 -0
  15. data/lib/portless/config.rb +293 -63
  16. data/lib/portless/constants.rb +30 -16
  17. data/lib/portless/daemon.rb +1378 -138
  18. data/lib/portless/doctor.rb +280 -0
  19. data/lib/portless/fonts.rb +12 -0
  20. data/lib/portless/frameworks.rb +380 -25
  21. data/lib/portless/free_port.rb +34 -16
  22. data/lib/portless/health.rb +18 -77
  23. data/lib/portless/help.rb +468 -0
  24. data/lib/portless/hosts.rb +108 -25
  25. data/lib/portless/hosts_sync_auth.rb +68 -0
  26. data/lib/portless/lan_ip.rb +90 -7
  27. data/lib/portless/mcp.rb +705 -0
  28. data/lib/portless/mdns.rb +113 -24
  29. data/lib/portless/multi.rb +308 -40
  30. data/lib/portless/pages.rb +319 -0
  31. data/lib/portless/port_owner.rb +147 -18
  32. data/lib/portless/privilege.rb +160 -20
  33. data/lib/portless/process_group.rb +157 -0
  34. data/lib/portless/proxy.rb +992 -267
  35. data/lib/portless/route_store.rb +443 -122
  36. data/lib/portless/run_support.rb +147 -52
  37. data/lib/portless/runner.rb +322 -98
  38. data/lib/portless/service.rb +631 -72
  39. data/lib/portless/share/tailscale.rb +240 -96
  40. data/lib/portless/state.rb +234 -25
  41. data/lib/portless/trust.rb +281 -125
  42. data/lib/portless/tunnel.rb +335 -0
  43. data/lib/portless/turbo.rb +73 -0
  44. data/lib/portless/utils.rb +232 -0
  45. data/lib/portless/version.rb +1 -1
  46. data/lib/portless/workspace.rb +140 -0
  47. data/lib/rb-portless.rb +21 -8
  48. metadata +81 -18
  49. data/lib/portless/banner.rb +0 -49
  50. data/lib/portless/rails.rb +0 -74
  51. data/lib/portless/rails_hosts.rb +0 -93
  52. data/lib/portless/share/ngrok.rb +0 -69
  53. data/lib/portless/worktree.rb +0 -79
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8a45c842e40387472fcb2ea9bb452cdd1015566db6de7ee653824f881a522af1
4
- data.tar.gz: 6b3c996607326c31b3abfb1fd8916cf3abe81ead74af7de13be36a8cc07bd119
3
+ metadata.gz: abf80865d767fd88a6b7962226801e1824c3fb97137d58823a49f1aa5fea40ad
4
+ data.tar.gz: 9e7cad5392ea7a0188216b10c548b3ef50a7467de39ad543d0b7af0c993c0e4c
5
5
  SHA512:
6
- metadata.gz: 593a5feaabae0a2781acd89831eeecb3ac03c99bc0e721c7626eeaf8f3a6c2b2f836d7160f04dffabae9645825753970bfd6545495a730c298a5f6eca9f06a71
7
- data.tar.gz: 607dd39cc15026cbddcc0af63d5f6a4f21b536511a34174df10517e1ff0807db3d1bea0df7c5005a9c5aed3c60cddad83df2edb6f6c91aa840d9bb5042da7b94
6
+ metadata.gz: 194ad18fdd4aa15b60a08a0014fcf0c938c767ec4328c49b810fd81fadb4bfaaa1ecbdad28426bc4408d24ce4034d4d46bcb3e044123239104d131f0ac5d63d3
7
+ data.tar.gz: adf76209a013ce0f028c2737943aa7c12f500e39b2f9f820fa21211949776f092c5eed473a0aef9c765e0f51e896f07a56743a376819fc0126ae9f2a5456f035
data/AGENTS.md CHANGED
@@ -1,118 +1,137 @@
1
1
  # AGENTS.md — rb-portless
2
2
 
3
- A native-Ruby port of Vercel's **portless** (`references/portless`, a Node/TS
4
- monorepo). Goal: feature parity, HTTPS by default, framework-agnostic (Rails is
5
- the first test target). This file is the map; read it before changing things.
6
-
7
- ## What it does
8
-
9
- `rb-portless run <cmd>` runs a dev server through a local reverse proxy reachable
10
- at `https://<name>.localhost` — no port numbers. A random backend port is
11
- injected as `PORT`; the proxy routes the named host to it.
12
-
13
- ## Core mechanisms (ported from portless — keep these invariants)
14
-
15
- - **No daemon IPC.** All coordination is files in `~/.rb-portless` (overridable
16
- via `PORTLESS_STATE_DIR`): `routes.json` (host→port→pid) under a `mkdir` lock,
17
- plus `proxy.pid`/`proxy.port`/CA files. The proxy watches `routes.json`.
18
- - **Privileged port = re-exec under sudo.** For ports < 1024, re-run the CLI via
19
- `sudo env PORTLESS_*=… ruby <cli> proxy start …`; the elevated process binds
20
- the socket and chowns state files back to `SUDO_UID`. Fall back to `:1355` if
21
- sudo is denied and no explicit port was given. Refuse in CI/no-TTY.
22
- - **Health header.** Every proxied response carries `X-Portless-Rb`; a HEAD probe
23
- is how we tell *our* proxy from any other process on a port.
24
- - **Wildcard routing.** A route `name.localhost` also serves `*.name.localhost`
25
- (exact match first, then `host.end_with?(".#{route}")`). Critical for
26
- subdomain-per-tenant apps (e.g. `*.shirabe.org.localhost`).
27
- - **Per-host SNI certs.** `*.localhost` wildcard certs are invalid at the
28
- reserved-TLD boundary, so mint a leaf per hostname on the TLS SNI callback,
29
- cached on disk + in memory.
30
- - **Loopback by default; LAN is opt-in twice.** The proxy binds `127.0.0.1` +
31
- `::1` unless started `--lan` (persisted in `proxy.lan`). Even then only
32
- routes carrying `lan: true` (registered by `run --lan`) are served to
33
- off-loopback clients — one daemon serves every project, so without that
34
- gate one app's `--lan` would expose all of them. Gating fails closed: an
35
- unreadable peer address counts as remote. The 404 page's app listing is
36
- suppressed for LAN clients (it would enumerate your projects).
3
+ A native-Ruby port of Vercel's **portless** (upstream clone: `references/portless`,
4
+ gitignored; `git clone https://github.com/vercel-labs/portless references/portless`).
5
+ This file is the map; read it before changing things.
6
+
7
+ ## Goal: exact parity, nothing more
8
+
9
+ rb-portless does exactly what upstream portless does — same commands, flags, env vars,
10
+ config schema, routing, JSON shapes, exit codes, and output (with `portless` →
11
+ `rb-portless` in command examples). No rb-portless-only features: project-specific
12
+ needs (Rails tenant subdomains, etc.) live in a separate project. When the two
13
+ differ, match upstream. Port upstream changes by reading the TS function first and
14
+ writing the Ruby one with the same name in snake_case, so the two stay diffable.
15
+
16
+ Deliberate divergences (naming only, so both tools coexist):
17
+
18
+ - Executable/gem `rb-portless`, Ruby module `Portless`.
19
+ - State dir `~/.rb-portless` (`PORTLESS_STATE_DIR` overrides). File names inside it
20
+ match upstream.
21
+ - Hosts block markers `# rb-portless-start/end`; service ids `rb.portless.proxy` /
22
+ `rb-portless.service`; CA common name and page footer say "rb-portless".
23
+ - The child env also gets `SSL_CERT_FILE` (system roots + local CA, `ca_bundle.rb`) under
24
+ the same conditions as `NODE_EXTRA_CA_CERTS` — the Ruby analogue, so Ruby clients
25
+ trust sibling `.localhost` HTTPS apps.
26
+ - The child runs in `Bundler.unbundled_env` (plumbing, not a feature).
27
+ - `GEM_HOME`/`GEM_PATH` cross `sudo env` and go into the boot service env when set
28
+ (`Privilege.ruby_env`), so a gem under a custom GEM_HOME loads as root.
29
+ - `doctor` reports the Ruby runtime (`rubyVersion` in `--json`, "Ruby" in text) where
30
+ upstream reports Node.js.
31
+
32
+ Known limits of the async-http stack (not choices; don't "fix" them by hand-rolling HTTP):
33
+ empty bodies are framed as `content-length: 0` (responses, and bodiless requests sent to
34
+ the backend), and empty responses carry no `connection: keep-alive`; a rejected
35
+ WebSocket upgrade gets async-http's own `connection: close` instead of the backend's;
36
+ "socket hang up" is ECONNRESET/EPIPE/EOF/`Protocol::HTTP::RefusedError`; WebSocket over
37
+ HTTP/2 extended CONNECT reaches the backend with async-http's lowercase `connection: upgrade`;
38
+ no `100 Continue` interim response; malformed requests differ in detail (duplicate `Host`
39
+ → 400, absolute-URI request lines route by the URI authority, no `Date` header or 5 s
40
+ idle keep-alive timeout, lowercase h1 response header names, duplicate headers not
41
+ joined); there is one loopback dialer per concurrency model (`Proxy.create_loopback_connection` on
42
+ fibers for the proxy, `Utils.create_loopback_connection` on threads for probes) where
43
+ upstream has one `createLoopbackConnection`.
44
+
45
+ Not ported (yet): Windows CA trust + Task Scheduler service, the legacy `/tmp/portless`
46
+ state migration.
47
+
48
+ Agent skills (`skills/`) are upstream's `skills/portless` and `skills/oauth`, rewritten
49
+ for Ruby/Rails as `rb-portless` and `rb-portless-oauth` (different names so they install
50
+ next to upstream's). Same section order as upstream; keep behaviour claims in sync with
51
+ the code, and port upstream skill edits when you port the feature they describe.
52
+
53
+ ## Versioning
54
+
55
+ The version mirrors the upstream release we match, plus a fourth segment for our own
56
+ fixes: `0.17.0.0` = parity with upstream 0.17.0, `0.17.0.1` = first local fix on top.
57
+ Only claim an upstream version once its features are in. `script/upstream/PIN` is the exact
58
+ upstream commit we match; when it is past the release tag, say so in the CHANGELOG.
59
+
60
+ ## Core mechanisms (upstream invariants)
61
+
62
+ - **No daemon IPC.** Coordination is files in the state dir: `routes.json` (upstream
63
+ `RouteMapping` array, camelCase keys, written atomically under a `mkdir` lock; dead
64
+ owners filtered on read, kept as `retired` for `prune`), plus the `proxy.*` markers
65
+ (`pid`, `port`, `start`, `tls`, `tlds`, `lan` = LAN IP, `unprivileged`,
66
+ `custom-cert`, `hosts-sync-token`). The daemon polls `routes.json` (upstream:
67
+ `fs.watch`).
68
+ - **Privileged ports.** Probe-bind first; only on `EACCES` re-run under
69
+ `sudo env PORTLESS_*=…`. Declined sudo exits with a recovery command (no fallback
70
+ port). `--unprivileged` binds without sudo and accepts loopback peers only.
71
+ - **Health header** `X-Portless: 1` on every response; a probe for it tells our proxy from
72
+ any other process on the port. Loops are counted with `x-portless-hops` (508 at 5).
73
+ - **Routing** is strict by default; `--wildcard` falls back to the most specific
74
+ registered parent. Hosts outside the configured TLDs get 421.
75
+ - **Per-host SNI certs**, minted only for names under the configured TLDs, cached on
76
+ disk and in memory.
77
+ - **Loopback by default.** `--lan` makes LAN a proxy mode: binds `0.0.0.0` + `::`,
78
+ forces `.local`, publishes every route over mDNS, re-checks the LAN IP every 5 s.
79
+ - **State-dir safety.** Commands refuse a state dir another user can change; root-side
80
+ writes never follow symlinks.
81
+
82
+ ## Upstream test suite (test/upstream)
83
+
84
+ `test/upstream/` mirrors upstream's tests one to one: `packages/portless/src/foo-bar.test.ts`
85
+ → `test/upstream/foo_bar_test.rb`, `tests/e2e/src/foo.test.ts` → `test/upstream/e2e/foo_test.rb`.
86
+ Each upstream `describe`/`it` is a Minitest::Spec `describe`/`it` with the **identical string**,
87
+ and the body ports the upstream body: same setup, same inputs, same assertions, adapted to
88
+ the Ruby API (snake_case names, Ruby exceptions, our naming divergences). `it.each`/`it.for`
89
+ keep the template string once and loop the rows. Never weaken an assertion to make it pass:
90
+ a failing ported test is a parity bug in `lib/`, fix the code. Upstream tests that cannot
91
+ apply (Windows-only) go in `test/upstream/skips.yml` with a reason. Ruby-only tests (CA
92
+ bundle, keychain safety, our e2e harness) stay in `test/*_test.rb`.
93
+
94
+ - `script/upstream/check_tests [--list] [--file x] [--ref sha]` — every upstream test has its
95
+ Ruby twin in the right file, nothing extra (`rake upstream:check`).
96
+ - `script/upstream/sync [--fetch] [--to ref]` — commits, source files → Ruby files to update
97
+ (`script/upstream/map.yml`), tests added/removed since `script/upstream/PIN`
98
+ (`rake upstream:sync`). Its header lists the release workflow; `--bump ref` moves PIN once
99
+ the mirror matches.
100
+ - `test/differential/run.rb` — same commands against both CLIs, output diffed.
37
101
 
38
102
  ## Module map (`lib/portless/`)
39
103
 
40
- | File | Role | portless source |
41
- | --- | --- | --- |
42
- | `constants.rb` | ports, thresholds, state-dir, header, markers | cli-utils.ts |
43
- | `state.rb` | state-dir paths + chown-back-to-SUDO_UID | utils.ts |
44
- | `config.rb` | portless.json + name/tld inference | config.ts, auto.ts |
45
- | `free_port.rb` | random 4000–4999 finder (skip bad ports) | cli-utils.ts findFreePort |
46
- | `route_store.rb` | routes.json + dir-lock + dead-pid reap | routes.ts |
47
- | `health.rb` | X-Portless-Rb probe + discoverState | cli-utils.ts |
48
- | `privilege.rb` | needs-sudo, sudo re-exec, 1355 fallback | cli.ts handleProxy |
49
- | `hosts.rb` | /etc/hosts marked-block sync/clean | hosts.ts |
50
- | `certs.rb` | OpenSSL CA + per-host SNI leaf certs | certs.ts |
51
- | `trust.rb` | OS trust store install/remove | certs.ts trustCA |
52
- | `proxy.rb` | async-http reverse proxy (h1/h2/tls/ws) | proxy.ts |
53
- | `daemon.rb` | proxy start/stop, sudo bind, 1355 fallback | cli.ts handleProxy |
54
- | `service.rb` | launchd / systemd boot service | service.ts |
55
- | `frameworks.rb` | --port/--host injection (vite/astro/…) | cli-utils.ts |
56
- | `banner.rb` | the "where's my app" startup banner | cli.ts (run output) |
57
- | `multi.rb` | monorepo: run many apps under one proxy | workspace.ts/turbo.ts |
58
- | `lan_ip.rb` / `mdns.rb` | LAN IP detect + `<name>.local` mDNS publish | lan-ip.ts/mdns.ts |
59
- | `share/ngrok.rb` / `share/tailscale.rb` | public/tailnet sharing | ngrok.ts/tailscale.ts |
60
- | `runner.rb` | run cmd: port→env→spawn→register→supervise | cli.ts runApp |
61
- | `rails.rb` | opt-in railtie (whitelist *.localhost in dev) | — |
62
- | `cli.rb` | command dispatch | cli.ts main |
63
-
64
- ## Status
65
-
66
- - **Phase 0 ✅** scaffold + coordination layer (config, state, free_port,
67
- route_store, health, privilege, hosts) + CLI dispatch.
68
- - **Phase 1 ✅** HTTPS proxy on async-http (TLS+SNI, h1+wildcard routing,
69
- X-Forwarded-*, loop guard), certs + macOS trust, runner, sudo bind + 1355
70
- fallback. **Verified against shirabe** at `https://*.shirabe.org.localhost`.
71
- - **Phase 2 ✅** HTTP/2, full command surface (doctor/clean/prune/alias/get/hosts),
72
- boot service (launchd/systemd), daemon lifecycle.
73
- - **Phase 3 ✅ (partial)** framework `--port`/`--host` injection, Linux CA trust,
74
- Firefox/Chrome NSS trust (`certutil` into each profile + `~/.pki/nssdb`),
75
- optional `portless/rails` railtie.
76
-
77
- - **Phase 4 ✅** startup banner; monorepo multi-app (`apps` map); LAN mode
78
- (`--lan`: LanIp + mDNS `<name>.local`); public sharing (`--ngrok`/`--tailscale`/
79
- `--funnel`, experimental).
80
-
81
- - **Phase 5 ✅** end-to-end tests (`test/e2e_*_test.rb`, modeled on portless's
82
- `tests/e2e`): a real proxy daemon on a high port + live backends. Cover
83
- TLS/SNI, wildcard subdomains, X-Forwarded-*, HTTP/2, the WebSocket relay,
84
- `run` lifecycle, and a real Rails app booted with the railtie.
85
-
86
- ### Roadmap (not yet built)
87
-
88
- Deliberately skipped for now (revisit on demand):
89
-
90
- - Windows CA trust + Task Scheduler service (no Windows machine to verify).
91
- - Custom certs (`proxy start --cert/--key` upstream) — niche; the local CA
92
- covers the normal flow.
93
- - HTTP/2 to the backend, mDNS LAN-IP re-publish on network change, and a
94
- brief backend retry-while-booting — low practical value in dev.
95
- - `PORTLESS_SYNC_HOSTS` auto hosts-sync (we keep `hosts sync` manual).
96
-
97
- ### Test backlog
98
-
99
- - CLI arg edge cases (`alias` add/remove, `get`, `doctor` exit codes) and the
100
- bin/dev → bin/rails resolved-command fallback.
101
-
102
- ### Known divergences from portless (deliberate)
103
-
104
- - Wildcard subdomain fallback is always on (upstream defaults strict, opt-in
105
- via `--wildcard`) — subdomain-per-tenant Rails apps are the headline here.
106
- - `portless.json` schema: `tld`/`tls` are ours; upstream keys `script`,
107
- `proxy`, path-keyed `apps`, and package.json config don't apply to Ruby.
108
- - Health header is `x-rb-portless: <version>` (upstream: `X-Portless: 1`);
109
- the version value drives the stale-proxy handshake.
104
+ | File | Upstream source |
105
+ | --- | --- |
106
+ | `cli.rb`, `commands.rb`, `help.rb` | cli.ts dispatch, commands.ts, help text |
107
+ | `args.rb` | args.ts (strict flag parsing, `UsageError` → exit 2) |
108
+ | `utils.rb` | utils.ts / cli-utils.ts shared helpers (ports, URLs, TLDs, env) |
109
+ | `config.rb`, `auto.rb` | config.ts, auto.ts (name inference, worktree prefix) |
110
+ | `workspace.rb`, `turbo.rb`, `multi.rb` | workspace.ts, turbo.ts, multi-app run |
111
+ | `runner.rb`, `run_support.rb`, `process_group.rb` | cli.ts runApp, child env, spawn/signals |
112
+ | `frameworks.rb`, `free_port.rb` | cli-utils.ts port/host injection, findFreePort |
113
+ | `route_store.rb` | routes.ts |
114
+ | `proxy.rb`, `pages.rb`, `fonts.rb` | proxy.ts, pages.ts, fonts.ts |
115
+ | `certs.rb`, `trust.rb`, `ca_bundle.rb` | certs.ts (+ Ruby CA bundle) |
116
+ | `daemon.rb` | cli.ts handleProxy/stopProxy/ensureProxyRunning, cli-utils.ts discoverState |
117
+ | `state.rb`, `privilege.rb`, `port_owner.rb` | utils.ts state dir + safety, elevation, port owners |
118
+ | `health.rb` | cli-utils.ts proxy probes |
119
+ | `hosts.rb`, `hosts_sync_auth.rb` | hosts.ts, hosts-sync-auth.ts |
120
+ | `lan_ip.rb`, `mdns.rb` | lan-ip.ts, mdns.ts |
121
+ | `tunnel.rb`, `cloudflare.rb`, `share/tailscale.rb` | tunnel.ts (ngrok), cloudflare.ts, tailscale.ts |
122
+ | `service.rb` | service.ts (launchd/systemd) |
123
+ | `clean_utils.rb`, `doctor.rb` | clean-utils.ts, cli.ts doctor |
124
+ | `mcp.rb` | mcp.ts |
125
+ | `compose.rb` | compose.ts |
110
126
 
111
127
  ## Conventions
112
128
 
113
- - Stdlib-first; the only runtime deps are `async` + `async-http` (for h1/h2/tls/ws).
114
- - Minitest + fixtures-free tests in `test/`; isolate state via `PORTLESS_STATE_DIR`.
115
- The e2e layer (`test/e2e_helper.rb`) spawns the real daemon on a free high
116
- port (no sudo) — Rails-stack gems in the Gemfile are test-only.
117
- - Mirror portless's naming/structure so the two stay diffable against
118
- `references/portless`.
129
+ - Stdlib-first; runtime deps are `async` + `async-http` (h1/h2/TLS/WebSocket).
130
+ - Minitest in `test/`. `bundle exec rake` runs every file in parallel (`script/test_parallel`,
131
+ ~5 min, bounded by `test/upstream/cli_test.rb`) plus the mirror check; `rake test` is serial. `test_helper.rb` points `HOME` and `PORTLESS_STATE_DIR` at a temp
132
+ dir and puts shims for `security`/`sudo`/`certutil` first on `PATH`, so no test can touch
133
+ `~/.rb-portless`, the keychain, or `/etc/hosts`. Never undo that in a test. Port upstream's unit tests
134
+ alongside the code. The e2e layer (`test/e2e_helper.rb`) runs the real daemon on a
135
+ free high port with `--skip-trust` and `PORTLESS_SYNC_HOSTS=0` (no sudo, no keychain,
136
+ no `/etc/hosts`).
137
+ - Use jj in this repo (see the user's global instructions).
data/CHANGELOG.md CHANGED
@@ -4,6 +4,94 @@ All notable changes to this project are documented here. The format follows
4
4
  [Keep a Changelog](https://keepachangelog.com/), and the project adheres to
5
5
  [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## [0.17.0.0] — 2026-11-16
8
+
9
+ rb-portless now tracks Vercel portless exactly. Versions mirror the upstream
10
+ release we match, plus a fourth segment for our own fixes: this release matches
11
+ portless 0.17.0 plus the unreleased upstream commits up to `73f789e` (`--json` on
12
+ `list`/`get`/`doctor`, exit code 2 for usage errors, strict flag parsing, `clean`
13
+ confirmation, shorter help). Commands, flags, environment variables, `portless.json` /
14
+ `package.json` config, routing, JSON output, exit codes and messages follow
15
+ upstream. The only differences are names (`rb-portless`, `~/.rb-portless`, hosts
16
+ markers, service ids) so both tools can be installed side by side, plus
17
+ `SSL_CERT_FILE` for Ruby children. See README.md.
18
+
19
+ ### Breaking
20
+
21
+ - **Ruby 3.3 or later** is required (Ruby 3.2 is end-of-life, and the async-http
22
+ releases rb-portless needs no longer support it), with async 2.46+ and
23
+ async-http 0.105+ (older releases hang WebSocket-over-HTTP/2 tunnels to HTTPS
24
+ backends on Linux).
25
+ - **Rails railtie removed** (`require "portless/rails"`). Allow `*.localhost`
26
+ in `config.hosts` yourself.
27
+ - **Routing is strict by default.** An unregistered subdomain now gets a 404.
28
+ Start the proxy with `--wildcard` (or `PORTLESS_WILDCARD=1`) for the old
29
+ subdomain fallback; it now picks the most specific registered parent.
30
+ - **`portless.json` keys `tld`, `tls` and `app_port`, and the name→command
31
+ `apps` map, are gone.** Use `proxy start --tld` / `PORTLESS_TLD`, `--no-tls` /
32
+ `PORTLESS_HTTPS=0`, `--app-port` / `PORTLESS_APP_PORT`, and path-keyed `apps`.
33
+ - **No `:1355` fallback.** Declining sudo now exits with the command to recover
34
+ (`--unprivileged`, or a port of your own).
35
+ - **`proxy restart` removed**, and `run --lan` no longer restarts the proxy; a
36
+ running proxy with different settings prints upstream's mismatch message.
37
+ - **The bare-run fallback to `bin/dev` / `bin/rails server` is gone.** A bare
38
+ `rb-portless` runs the `package.json` dev script, as upstream does.
39
+ - **Health header is `X-Portless: 1`** (was `x-rb-portless: <version>`), and the
40
+ stale-proxy restart prompt is gone. Restart the proxy after upgrading.
41
+ - **Startup banner** replaced by upstream's run output.
42
+ - **Firefox/Chrome NSS trust** (`certutil`) removed; trust matches upstream.
43
+ - `routes.json` uses upstream's schema. Restart running apps after upgrading.
44
+
45
+ ### Security
46
+
47
+ - **LAN mode exposes every running app, as upstream does.** `--lan` is a proxy
48
+ mode: it binds `0.0.0.0` and `::`, switches to `.local`, and publishes every
49
+ route over mDNS. The 0.5.1 per-route `lan: true` gate and the hidden 404 app
50
+ list for LAN clients are removed. Without `--lan` the proxy stays loopback-only.
51
+ - Certificates are minted only for names under the configured TLDs (any SNI
52
+ name used to get a cert), and hosts outside them get 421 instead of a 404
53
+ listing your apps.
54
+ - `proxy stop` verifies the recorded pid is the proxy before signalling it, and
55
+ state dirs other users can change are refused. Root-side state writes never
56
+ follow symlinks.
57
+ - The test suite no longer adds CAs to the login keychain (a test started the
58
+ proxy without `--skip-trust`).
59
+
60
+ ### Added
61
+
62
+ - `mcp` (stdio MCP server, `--tools core|proxy|diagnostics|all`), `compose`
63
+ (Docker Compose routes), `--cloudflare`, `alias --upstream` and `alias --tld`,
64
+ `--unprivileged`, multiple and multi-label TLDs, `--wildcard`, `--https`,
65
+ `--cert/--key`, `--skip-trust`, `proxy stop -p`, `--json` for `list`/`get`/
66
+ `doctor`, `clean --yes`, `run --prefix` / `PORTLESS_PREFIX`, the `worktree`
67
+ config, `--script`, `package.json` `"portless"` config, workspace and Turbo
68
+ multi-app runs, hosts sync owned by the daemon, styled error pages, plain HTTP
69
+ on the TLS port redirected to HTTPS, backend connection pooling with parallel
70
+ IPv4/IPv6 dialing, and routes handed to self-daemonizing servers.
71
+ - Agent skills, ported from upstream's `skills/` for Ruby and Rails:
72
+ `rb-portless` (setup, Rails `config.hosts` / `PORT` / `bin/dev`, troubleshooting)
73
+ and `rb-portless-oauth` (OmniAuth/Devise redirect URIs). Install with
74
+ `npx skills add davafons/rb-portless`.
75
+
76
+ ### Fixed
77
+
78
+ - Routes whose owner died were still served; a corrupt `routes.json` lost every
79
+ route on the next write.
80
+ - `run` consumed its own flags anywhere in the command (`run vite --force` lost
81
+ `--force`) and ran unknown flags as the command. Usage errors exit 2.
82
+ - `get` dropped the proxy port and the TLD of dotted names.
83
+ - `--port` was added to `vite build` / `astro build` and duplicated after a
84
+ user's `--port`.
85
+ - Multi-app (workspace) runs didn't set `SSL_CERT_FILE` for their children.
86
+ - mDNS advertised port 80 instead of the proxy port; tailscale teardown could
87
+ remove a funnel it didn't create; the state dir under sudo now resolves through
88
+ `SUDO_USER`.
89
+
90
+ ### Not ported
91
+
92
+ - Windows CA trust and the Windows boot service, and the legacy `/tmp/portless`
93
+ state migration.
94
+
7
95
  ## [0.5.2] — 2026-09-08
8
96
 
9
97
  ### Fixed