rb-portless 0.1.0 → 0.3.0.dev.20260630.03ed07d

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe5a5a76f71f89027e083e3ba964520c22aef5f1a42ecefc3850e16a0ac16bb2
-  data.tar.gz: 13081e8f73114575b5a96ab27f9dec30c4949f333fa3c95ba0659f104cf16b19
+  metadata.gz: 7430efcc1364552ff11c18a40fb81497f6adb231e9b70de8dac525209baa0140
+  data.tar.gz: a7e8a061d587ae4df39feb5c419cdc4ded1f56e25c371d65e04daf39c88bc0ab
 SHA512:
-  metadata.gz: 06a5c203d83b18de91ca2248744854e71933cdb4771626d8ae7af4e9bdbc2840c98edcfcc9cc51a9b88f9b6d6d9431c733118910bfcb380c372b9ad2151916e0
-  data.tar.gz: 44412d9c53a6c2990af830497f55bfd30cc5a3f4e9cd2032a9b5347cfc6853931e0754191ecb634607cfbaffc448e3ba4b333f259ae037d759ff6b15f31ccd3c
+  metadata.gz: 479a942f43878da3fd6c9fc3ef51f45de6548aef51d69ec66442e87ae235378544b7165d070aeef22b19a4c5a57d9d60e1b1bca17d1324a2a50ddbf38e6bcd67
+  data.tar.gz: ebf5b7ba3081de166182d8548235f27b7af0cd462008f458e82b786dc87db352b4cb5e82b3f1b60c350d4ba7c2748d6494ad482a5a3217d8fb0dce65ebed8e42

data/AGENTS.md

@@ -46,6 +46,10 @@ injected as `PORT`; the proxy routes the named host to it.
 | `daemon.rb` | proxy start/stop, sudo bind, 1355 fallback | cli.ts handleProxy |
 | `service.rb` | launchd / systemd boot service | service.ts |
 | `frameworks.rb` | --port/--host injection (vite/astro/…) | cli-utils.ts |
+| `banner.rb` | the "where's my app" startup banner | cli.ts (run output) |
+| `multi.rb` | monorepo: run many apps under one proxy | workspace.ts/turbo.ts |
+| `lan_ip.rb` / `mdns.rb` | LAN IP detect + `<name>.local` mDNS publish | lan-ip.ts/mdns.ts |
+| `share/ngrok.rb` / `share/tailscale.rb` | public/tailnet sharing | ngrok.ts/tailscale.ts |
 | `runner.rb` | run cmd: port→env→spawn→register→supervise | cli.ts runApp |
 | `rails.rb` | opt-in railtie (whitelist *.localhost in dev) | — |
 | `cli.rb` | command dispatch | cli.ts main |
@@ -62,13 +66,15 @@ injected as `PORT`; the proxy routes the named host to it.
 - **Phase 3 ✅ (partial)** framework `--port`/`--host` injection, Linux CA trust,
   optional `portless/rails` railtie.
 
+- **Phase 4 ✅** startup banner; monorepo multi-app (`apps` map); LAN mode
+  (`--lan`: LanIp + mDNS `<name>.local`); public sharing (`--ngrok`/`--tailscale`/
+  `--funnel`, experimental).
+
 ### Roadmap (not yet built)
 
-- LAN mode (mDNS `.local` publishing) for phones/tablets.
-- Public sharing via `tailscale serve|funnel` and `ngrok`.
-- Monorepo multi-app (one proxy, many named apps).
 - Windows CA trust + Task Scheduler service.
 - WebSocket upgrade relay hardening + HTTP/2 to the backend.
+- mDNS LAN-IP change monitoring (re-publish on network switch).
 
 ## Conventions
 

data/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.3.0]
+
+### Fixed / hardened
+
+- **Health probes can't hang.** Added a read timeout to the TLS and plain probes
+  so a port that accepts but never answers no longer blocks `discover_port`.
+
+### Added
+
+- **Risky-TLD warning.** Warn when the configured `tld` ends in a real/reserved
+  TLD (`dev`, `app`, `local`, …) that could intercept live traffic.
+- **More tests** — `Proxy#call` is now public, so the proxy's routing + error
+  logic is unit-tested (404 / 508 loop guard / 502 dead-backend, all stamped with
+  the health header) plus health probes and privilege logic (42 tests). The
+  successful byte-forward + **WebSocket upgrade relay** (ActionCable) need a live
+  reactor and are verified end-to-end manually — async-http servers can't be torn
+  down in-process without deadlock.
+
+
+- **Startup banner.** Running a dev server through rb-portless now prints a clear
+  banner with the named URL(s) it's reachable at — not just `127.0.0.1:port`.
+- **Monorepo / multi-app.** A `portless.json` `apps` map runs several apps under
+  one proxy, each at its own `<name>.<tld>` (`rb-portless run` with no command).
+- **LAN mode (`--lan`).** Reach the app from phones/tablets on the same Wi-Fi:
+  detects the LAN IP, registers `<name>.local`, and publishes it over mDNS
+  (`dns-sd`/`avahi-publish`). `--ip` overrides the detected address.
+- **Public sharing (experimental).** `--ngrok`, `--tailscale`, `--funnel` expose
+  the app via ngrok / your tailnet (their CLIs, installed separately). When a
+  tool is missing or unconfigured, print an **actionable** message (install link,
+  `ngrok config add-authtoken`, "enable HTTPS in your tailnet DNS settings",
+  "run `tailscale up`") rather than failing silently — mirroring portless. Tailscale is **non-destructive**: it reads
+  `tailscale serve status`, picks a free HTTPS port (never clobbering your
+  existing serve/funnel config), registers with `--yes`, and removes only the
+  port it created on exit — mirroring portless's port-conflict handling.
+
+## [0.2.0]
+
+### Added
+
+- **Auto-trust on first run.** `run` now trusts the local CA automatically the
+  first time (interactive only; skipped with a hint in CI), matching portless —
+  HTTPS works with no browser warnings without a separate `trust` step.
+
 ## [0.1.0] — first release
 
 The full portless workflow for Ruby, validated end-to-end against a real Rails

data/README.md

@@ -41,12 +41,12 @@ rb-portless run -- npm run dev     # Vite/Astro/etc. get --port injected
 
 A random port (4000–4999) is injected as `PORT` (and `HOST=127.0.0.1`);
 Rails/puma respect it natively. The proxy **auto-starts** on first run: it
-generates a local CA, and binds 443 — a one-time `sudo` on macOS/Linux, exactly
-like portless (falls back to `:1355` if you decline). Run `rb-portless trust`
-once so your browser accepts the certificates.
+generates a local CA, **trusts it** (one keychain/sudo prompt, like portless),
+and binds 443 — another one-time `sudo` on macOS/Linux (falls back to `:1355` if
+you decline). After that, HTTPS just works with no browser warnings.
 
 ```bash
-rb-portless trust                  # trust the local CA (HTTPS, no warnings)
+rb-portless trust                  # re-trust manually if ever needed
 rb-portless service install        # bind 443 at boot — never prompt for sudo again
 ```
 
@@ -66,6 +66,47 @@ rb-portless service install        # bind 443 at boot — never prompt for sudo
 With a custom `tld`, every `*.shirabe.org.localhost` subdomain wildcard-routes to
 the one app — ideal for subdomain-per-tenant apps.
 
+## Multiple apps, LAN & sharing
+
+**Monorepo / multi-app** — define an `apps` map and `rb-portless run` (no command)
+starts them all, each at its own name:
+
+```jsonc
+// portless.json
+{ "apps": { "web": "bin/rails server", "api": "node api/server.js" } }
+// → https://web.localhost, https://api.localhost
+```
+
+**LAN mode** — reach the app from your phone on the same Wi-Fi. It detects the
+LAN IP, registers `<name>.local`, and publishes it over mDNS:
+
+```bash
+rb-portless run --lan bin/dev      # also → https://<name>.local
+rb-portless run --lan --ip 10.0.0.5 bin/dev   # override the detected IP
+```
+> Devices won't trust your local CA without installing it — use `--lan` with
+> `--no-tls` (set `"tls": false`) for plain HTTP, or install `~/.rb-portless/ca.pem`
+> on the device.
+
+**Public sharing** (experimental) — expose the app via ngrok or your tailnet:
+
+```bash
+rb-portless run --ngrok bin/dev        # https://xxxx.ngrok.app
+rb-portless run --tailscale bin/dev    # your-machine.tailnet.ts.net
+rb-portless run --funnel bin/dev       # tailscale Funnel (public)
+```
+
+These use the tools' own CLIs — **install them separately** (we don't bundle
+anything, same as portless), and each degrades gracefully if the tool is absent:
+- **ngrok** — install the `ngrok` CLI and configure an authtoken (free account).
+- **tailscale** — install `tailscale`, be logged into a tailnet, and enable HTTPS
+  certificates (and Funnel, for `--funnel`) in your tailnet settings.
+
+> **Your tailnet config is safe.** rb-portless reads `tailscale serve status`,
+> picks a **free** HTTPS port (never one you're already serving on), registers
+> with `--yes`, and on exit turns off **only the port it created** — it never
+> touches your existing `serve`/`funnel` setup.
+
 ## Commands
 
 | Command | Does |
@@ -104,8 +145,7 @@ end
 ```
 
 ```bash
-rb-portless trust            # one-time: trust the local CA
-rb-portless run bin/dev      # → https://myapp.localhost
+rb-portless run bin/dev      # → https://myapp.localhost (CA auto-trusted on first run)
 ```
 
 That's it. The railtie **auto-detects when you're running under `rb-portless`**
@@ -164,6 +204,29 @@ boundary). For ports < 1024 it re-execs under `sudo` so the elevated process can
 bind the socket, then hands ownership of state files back to you. See
 [`AGENTS.md`](AGENTS.md) for the full architecture.
 
+## Compared to portless (Node)
+
+The mental model is identical — `run` wraps your dev command, the proxy
+auto-starts, named `.localhost` URLs replace ports. The only Ruby-world addition
+is the one-line `require "portless/rails"` to satisfy Rails' host authorization.
+
+| | **portless (Node)** | **rb-portless (Ruby/Rails)** |
+|---|---|---|
+| Install | `npm i -g portless` | `gem install rb-portless` (or Gemfile dev group) |
+| Run a server | `portless run next dev` | `rb-portless run bin/rails server` |
+| Run the dev orchestrator | `portless` (runs `"dev"` script) | `rb-portless run bin/dev` (wraps Foreman) |
+| Bake into the project | `"dev": "portless run next dev"` → `npm run dev` | put `rb-portless run` in `bin/dev`, or use the binstub |
+| Name the URL | `portless myapp …` / `portless.json` | `portless.json` `{ "name": "myapp" }` (else dir/git root) |
+| Wildcard tenant subdomains | `tld` config | `portless.json` `{ "tld": "myapp.localhost" }` → `*.myapp.localhost` |
+| Pin the backend port | `--app-port` / `appPort` | `appPort` in `portless.json` |
+| Framework port injection | vite/astro/etc. auto | same (Rails/puma respect `PORT` natively) |
+| HTTPS trust | auto on first run (+ `portless trust`) | auto on first run (+ `rb-portless trust`) |
+| **Host allowlist** | not needed | **`gem "rb-portless", require: "portless/rails"`** (Rails-only) |
+| Privileged 443 bind | sudo re-exec (auto) | sudo re-exec (auto), `:1355` fallback |
+| Bind at boot (no sudo) | `portless service install` | `rb-portless service install` |
+| Inspect / manage | `portless list / doctor / clean` | `rb-portless list / doctor / clean` |
+| Static route (DB, etc.) | `portless alias pg 5432` | `rb-portless alias pg 5432` |
+
 ## Contributing
 
 ```bash

data/lib/portless/banner.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Portless
+  # The "where is my app" banner printed to stderr when a dev server starts
+  # through rb-portless — so you see the named URL, not just 127.0.0.1:port.
+  # Vite-ish layout; colours are stripped when stderr isn't a TTY. Mirrors the
+  # spirit of portless's run output.
+  module Banner
+    module_function
+
+    # rows: ordered [label, value, color] for the reachable URLs (Local,
+    # Network, Public, …); backend is the real 127.0.0.1:port behind the proxy.
+    def app(rows:, backend_port:)
+      out = [ "", "  #{bold('rb-portless')} #{dim("v#{VERSION}")}", "" ]
+      rows.each { |label, value, paint| out << row(label, send(paint || :cyan, value)) }
+      out << row("Backend", dim("127.0.0.1:#{backend_port}"))
+      out << ""
+      out << "  #{dim('ready — press Ctrl-C to stop')}"
+      out << ""
+      warn out.join("\n")
+    end
+
+    # Multi-app: one row per app (name → URL).
+    def multi(apps:)
+      out = [ "", "  #{bold('rb-portless')} #{dim("v#{VERSION}")}", "" ]
+      apps.each { |app| out << row(app.name, cyan(app.url)) }
+      out << ""
+      out << "  #{dim('ready — press Ctrl-C to stop')}"
+      out << ""
+      warn out.join("\n")
+    end
+
+    def row(label, value) = "  #{green('➜')}  #{label.to_s.ljust(8)}#{value}"
+
+    # ── colours (no-op unless stderr is a TTY) ──
+    def paint(code, str) = tty? ? "\e[#{code}m#{str}\e[0m" : str
+    def bold(str)  = paint("1", str)
+    def dim(str)   = paint("90", str)
+    def cyan(str)  = paint("36", str)
+    def green(str) = paint("32", str)
+    def tty? = $stderr.tty?
+  end
+end

data/lib/portless/cli.rb

@@ -34,7 +34,32 @@ module Portless
 
     # ── Commands ────────────────────────────────────────────────────────────
     def cmd_run(args)
-      Runner.new(command: strip_flags(args)).run
+      options, command = parse_run(args)
+      if command.empty? && Config.load.apps.any?
+        Multi.new.run # monorepo: portless.json `apps` map
+      else
+        Runner.new(command: command, options: options).run
+      end
+    end
+
+    # Consume leading rb-portless flags (--lan/--ip/--ngrok/--tailscale/--funnel),
+    # stopping at the first non-flag, an unknown flag, or `--`; the rest is the
+    # command to run.
+    def parse_run(args)
+      options = {}
+      rest = args.dup
+      while (flag = rest.first)&.start_with?("--")
+        case flag
+        when "--lan"       then options[:lan] = true; rest.shift
+        when "--ip"        then rest.shift; options[:ip] = rest.shift
+        when "--ngrok"     then options[:ngrok] = true; rest.shift
+        when "--tailscale" then options[:tailscale] = true; rest.shift
+        when "--funnel"    then options[:funnel] = true; rest.shift
+        when "--"          then rest.shift; break
+        else break
+        end
+      end
+      [ options, rest ]
     end
 
     def cmd_proxy(args)
@@ -180,11 +205,6 @@ module Portless
       i ? Integer(args[i + 1], exception: false) : nil
     end
 
-    def strip_flags(args)
-      # everything after `run`, minus our own flags
-      args.reject { |a| a.start_with?("--portless") }
-    end
-
     def todo(name, desc, _args = nil)
       warn "rb-portless #{name}: #{desc} — not yet implemented (#{Portless::VERSION})"
       exit 1
@@ -206,7 +226,7 @@ module Portless
 
         Usage:
           rb-portless run <command>        run a dev server through the proxy
-          rb-portless [<command>]          (bare) run the project's dev script
+          rb-portless run                  run the `apps` map, or the dev script
           rb-portless proxy start|stop     manage the proxy daemon
           rb-portless trust                trust the local CA (HTTPS)
           rb-portless hosts sync|clean     manage /etc/hosts (Safari fallback)
@@ -215,6 +235,11 @@ module Portless
           rb-portless clean | prune        tear down / reap orphans
           rb-portless service install      bind the privileged port at boot
 
+        run flags:
+          --lan [--ip <addr>]              also serve on the LAN (<name>.local)
+          --ngrok                          share publicly via ngrok
+          --tailscale | --funnel           share via your tailnet / Funnel
+
         HTTPS is the default (https://<name>.localhost). Config: portless.json.
       HELP
     end

data/lib/portless/config.rb

@@ -9,7 +9,7 @@ module Portless
   class Config
     DEFAULT_SCRIPT = "dev"
 
-    attr_reader :name, :tld, :script, :app_port, :tls
+    attr_reader :name, :tld, :script, :app_port, :tls, :apps
 
     def self.load(dir = Dir.pwd)
       new(read_file(dir), dir)
@@ -22,6 +22,8 @@ module Portless
       @script = data["script"] || DEFAULT_SCRIPT
       @app_port = data["appPort"] || data["app_port"]
       @tls = data.fetch("tls", true)
+      # Monorepo: { "apps": { "web": "bin/rails server", "api": "node api.js" } }.
+      @apps = (data["apps"] || {}).transform_keys { |k| sanitize_label(k) }
     end
 
     # The full hostname an app registers (e.g. "shirabe.org.localhost" when tld is
@@ -30,6 +32,17 @@ module Portless
       tld.split(".").include?(name) ? tld : "#{name}.#{tld}"
     end
 
+    # Real/reserved TLDs that can intercept live traffic or clash with mDNS.
+    RISKY_TLDS = %w[dev app page zip mov local].freeze
+
+    # A warning string if the tld looks risky, else nil. (.localhost / .test are safe.)
+    def tld_warning
+      last = tld.split(".").last
+      return unless RISKY_TLDS.include?(last)
+
+      "tld \".#{last}\" is a real/reserved TLD — prefer \".localhost\" so you don't intercept real traffic"
+    end
+
     def self.read_file(dir)
       json = File.join(dir, "portless.json")
       return JSON.parse(File.read(json)) if File.exist?(json)

data/lib/portless/health.rb

@@ -2,6 +2,7 @@
 
 require "socket"
 require "openssl"
+require "timeout"
 
 module Portless
   # "Is *our* proxy on this port?" — every proxied response carries the
@@ -26,7 +27,8 @@ module Portless
       ssl.sync_close = true
       ssl.connect
       ssl.write(REQUEST)
-      marker?(ssl.read(4096))
+      # Read timeout too — a port that accepts but never answers must not hang us.
+      marker?(Timeout.timeout(timeout) { ssl.read(4096) })
     rescue StandardError
       false
     ensure
@@ -38,7 +40,7 @@ module Portless
       Socket.tcp("127.0.0.1", port, connect_timeout: timeout) do |sock|
         sock.write(REQUEST)
         sock.close_write
-        marker?(sock.read(4096))
+        marker?(Timeout.timeout(timeout) { sock.read(4096) })
       end
     rescue StandardError
       false

data/lib/portless/lan_ip.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Portless
+  # The machine's primary private LAN IPv4 — so phones/tablets on the same Wi-Fi
+  # can reach the dev app. Pure stdlib. Mirrors portless's lan-ip.ts.
+  module LanIp
+    module_function
+
+    def detect(override = nil)
+      return override if override.to_s.strip != ""
+
+      Socket.ip_address_list
+            .find { |addr| addr.ipv4? && addr.ipv4_private? && !addr.ipv4_loopback? }
+            &.ip_address
+    end
+  end
+end

data/lib/portless/mdns.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Portless
+  # Publish `<name>.local → LAN IP` over mDNS so phones/tablets resolve it on the
+  # local network (`.localhost` only works on the dev machine). Shells out to the
+  # OS responder — `dns-sd` on macOS, `avahi-publish` on Linux — and returns the
+  # publisher pid (kill it to unpublish). A no-op (with a hint) if neither tool
+  # is present. Mirrors portless's mdns.ts.
+  module Mdns
+    module_function
+
+    def publish(hostname, ip)
+      return nil unless ip
+
+      cmd = command_for(hostname, ip)
+      unless cmd
+        warn "rb-portless: no mDNS responder (dns-sd / avahi-publish) — `#{hostname}` won't resolve on the LAN"
+        return nil
+      end
+
+      pid = Process.spawn(*cmd, out: File::NULL, err: File::NULL)
+      Process.detach(pid)
+      pid
+    rescue StandardError
+      nil
+    end
+
+    def unpublish(pid)
+      Process.kill("TERM", pid) if pid
+    rescue StandardError
+      nil
+    end
+
+    def command_for(hostname, ip)
+      if Portless.which("dns-sd")
+        # Proxy-register an A record: name type domain port host ip.
+        [ "dns-sd", "-P", hostname.sub(/\.local\z/, ""), "_http._tcp", "local", "80", hostname, ip ]
+      elsif Portless.which("avahi-publish")
+        [ "avahi-publish", "-a", "-R", hostname, ip ]
+      end
+    end
+  end
+end

data/lib/portless/multi.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Portless
+  # Run several apps under one proxy, each at its own `<name>.<tld>`, from the
+  # `apps` map in portless.json. Every app gets a free backend port, a route, and
+  # injected PORT/HOST/PORTLESS_URL; all run in their own process groups and are
+  # supervised + torn down together. Ruby sets env per-spawn, so there's no
+  # NODE_OPTIONS loader hack (cf. portless's turbo.ts).
+  class Multi
+    App = Struct.new(:name, :hostname, :port, :url, :pid, keyword_init: true)
+
+    def initialize(config: Config.load, route_store: RouteStore.new)
+      @config = config
+      @route_store = route_store
+      @apps = []
+    end
+
+    def run
+      raise Error, "no apps defined — add an \"apps\" map to portless.json" if @config.apps.empty?
+
+      ensure_trusted if @config.tls
+      proxy_port = Daemon.ensure_running(tls: @config.tls)
+      @apps = @config.apps.map { |name, command| start_app(name, command, proxy_port) }
+
+      Banner.multi(apps: @apps)
+      install_signal_handlers
+      Process.waitall
+    ensure
+      teardown
+    end
+
+    private
+
+    def start_app(name, command, proxy_port)
+      port = FreePort.find
+      hostname = "#{name}.#{@config.tld}"
+      url = display_url(hostname, proxy_port)
+      @route_store.add(hostname: hostname, port: port, pid: Process.pid, force: true)
+      # A bare command string runs through the shell (handles "bin/rails server").
+      pid = Process.spawn(child_env(port, url), command, pgroup: true)
+      App.new(name: name, hostname: hostname, port: port, url: url, pid: pid)
+    end
+
+    def install_signal_handlers
+      %w[INT TERM].each { |sig| trap(sig) { kill_all(sig) } }
+    end
+
+    def kill_all(sig)
+      @apps.each do |app|
+        Process.kill(sig, -Process.getpgid(app.pid))
+      rescue StandardError
+        nil
+      end
+    end
+
+    def teardown
+      @apps.each { |app| @route_store.remove(app.hostname, owner_pid: Process.pid) }
+      kill_all("TERM")
+    end
+
+    def child_env(port, url)
+      {
+        "PORT" => port.to_s,
+        "HOST" => "127.0.0.1",
+        "PORTLESS_URL" => url,
+        "SSL_CERT_FILE" => (File.exist?(State.ca_cert) ? State.ca_cert : nil)
+      }.compact
+    end
+
+    def display_url(hostname, proxy_port)
+      scheme = @config.tls ? "https" : "http"
+      default = @config.tls ? Constants::HTTPS_PORT : Constants::HTTP_PORT
+      suffix = proxy_port && proxy_port != default ? ":#{proxy_port}" : ""
+      "#{scheme}://#{hostname}#{suffix}"
+    end
+
+    def ensure_trusted
+      Trust.install! if Privilege.interactive? && !Trust.trusted?
+    rescue Portless::Error
+      nil
+    end
+  end
+end

data/lib/portless/proxy.rb

@@ -51,13 +51,10 @@ module Portless
         routes.find { |r| host.end_with?(".#{r.hostname}") }
     end
 
-    private
-
-    def make_server(endpoint)
-      Async::HTTP::Server.for(endpoint) { |request| handle(request) }
-    end
-
-    def handle(request)
+    # The reverse-proxy app: resolve the request's host to a backend, forward it,
+    # stamp the health header. Public so it can be mounted in a test reactor
+    # (Async::HTTP::Server.for(endpoint, &proxy.method(:call))).
+    def call(request)
       host = request_host(request)
       route = route_for(host)
       return error(404, "No app is registered for #{host}.") unless route
@@ -72,6 +69,12 @@ module Portless
       error(502, "Backend for #{host} is not responding (#{e.class}).")
     end
 
+    private
+
+    def make_server(endpoint)
+      Async::HTTP::Server.for(endpoint) { |request| call(request) }
+    end
+
     def build_forward(request, host, hops)
       headers = Protocol::HTTP::Headers.new
       request.headers.each do |key, value|

data/lib/portless/runner.rb

@@ -6,10 +6,11 @@ module Portless
   # group (forwarding signals), and deregister on exit. Rails/puma respect PORT
   # natively. Mirrors portless's runApp/spawnCommand.
   class Runner
-    def initialize(command:, config: Config.load, route_store: RouteStore.new)
+    def initialize(command:, config: Config.load, route_store: RouteStore.new, options: {})
       @command = Array(command)
       @config = config
       @route_store = route_store
+      @options = options # :lan, :ip, :ngrok, :tailscale, :funnel
     end
 
     def run
@@ -19,20 +20,88 @@ module Portless
       port = @config.app_port&.to_i || FreePort.find
       command = Frameworks.inject(command, port) # --port/--host for vite/astro/etc.
       hostname = @config.hostname
-      url = "#{@config.tls ? 'https' : 'http'}://#{hostname}"
 
-      Daemon.ensure_running(tls: @config.tls)
+      warn "rb-portless: #{@config.tld_warning}" if @config.tld_warning
+      ensure_trusted if @config.tls
+      proxy_port = Daemon.ensure_running(tls: @config.tls)
       @route_store.add(hostname: hostname, port: port, pid: Process.pid, force: true)
 
-      announce(url, port)
+      url = display_url(hostname, proxy_port)
+      rows = [ [ "Local", url, :cyan ] ]
+      rows.concat(lan_rows(port, proxy_port))
+      rows.concat(share_rows(hostname, port))
+      Banner.app(rows: rows, backend_port: port)
+
       status = supervise(command, port, url)
       exit(status)
     ensure
+      teardown
       @route_store.remove(hostname, owner_pid: Process.pid) if hostname
     end
 
     private
 
+    def display_url(hostname, proxy_port)
+      scheme = @config.tls ? "https" : "http"
+      default = @config.tls ? Constants::HTTPS_PORT : Constants::HTTP_PORT
+      suffix = proxy_port && proxy_port != default ? ":#{proxy_port}" : ""
+      "#{scheme}://#{hostname}#{suffix}"
+    end
+
+    # ── LAN mode (--lan) ──────────────────────────────────────────────────
+    # Register a `<name>.local` route, publish it over mDNS, and surface the URL
+    # so phones/tablets on the Wi-Fi can reach the app.
+    def lan_rows(backend_port, proxy_port)
+      return [] unless @options[:lan]
+
+      ip = LanIp.detect(@options[:ip])
+      return [ [ "Network", "no LAN IPv4 found", :dim ] ] unless ip
+
+      @lan_host = "#{@config.name}.local"
+      @route_store.add(hostname: @lan_host, port: backend_port, pid: Process.pid, force: true)
+      @mdns_pid = Mdns.publish(@lan_host, ip)
+      warn "rb-portless: trust #{State.ca_cert} on the device for HTTPS over the LAN" if @config.tls
+      [ [ "Network", display_url(@lan_host, proxy_port), :green ] ]
+    end
+
+    # ── Public sharing (--ngrok / --tailscale / --funnel) ─────────────────
+    def share_rows(hostname, backend_port)
+      rows = []
+      if @options[:ngrok] && (@ngrok = Share::Ngrok.start(hostname: hostname, backend_port: backend_port))
+        rows << [ "Public", @ngrok[:url], :green ]
+      end
+      if (@options[:tailscale] || @options[:funnel]) &&
+         (@tailscale = Share::Tailscale.start(backend_port: backend_port, funnel: @options[:funnel]))
+        rows << [ @options[:funnel] ? "Funnel" : "Tailnet", @tailscale[:url], :green ]
+      end
+      rows
+    end
+
+    def teardown
+      Mdns.unpublish(@mdns_pid)
+      @route_store.remove(@lan_host, owner_pid: Process.pid) if @lan_host
+      Share::Ngrok.stop(@ngrok) if @ngrok
+      Share::Tailscale.stop(@tailscale) if @tailscale
+    end
+
+    # Trust the local CA on first run (like portless), so HTTPS works without
+    # browser warnings out of the box. Interactive only — macOS prompts for
+    # keychain auth; in CI/no-TTY we skip with a hint rather than hang. Never
+    # blocks the run if trusting fails.
+    def ensure_trusted
+      return if Trust.trusted?
+
+      unless Privilege.interactive?
+        warn "rb-portless: CA not trusted — run `rb-portless trust` (HTTPS shows warnings until then)"
+        return
+      end
+
+      warn "rb-portless: trusting the local CA (first run)…"
+      Trust.install!
+    rescue Portless::Error => e
+      warn "rb-portless: couldn't auto-trust the CA (#{e.message}) — run `rb-portless trust`"
+    end
+
     # Run the child in its own process group so we can signal the whole tree,
     # forwarding INT/TERM and propagating its exit status.
     def supervise(command, port, url)
@@ -73,9 +142,5 @@ module Portless
 
       []
     end
-
-    def announce(url, port)
-      warn "rb-portless → #{url}  (backend :#{port})"
-    end
   end
 end

data/lib/portless/share/ngrok.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Portless
+  module Share
+    # Expose the local app publicly via ngrok. We point ngrok at the *backend*
+    # port directly (with the app's Host header) rather than tunnelling through
+    # our self-signed TLS proxy — simpler and avoids cert-trust issues. Returns
+    # { pid:, url: } or nil. EXPERIMENTAL. Mirrors portless's ngrok.ts.
+    module Ngrok
+      module_function
+
+      API = "http://127.0.0.1:4040/api/tunnels"
+
+      def start(hostname:, backend_port:)
+        unless Portless.which("ngrok")
+          warn "rb-portless: ngrok not found — install it (https://ngrok.com/download) to use --ngrok"
+          return nil
+        end
+
+        pid = Process.spawn("ngrok", "http", backend_port.to_s, "--host-header=#{hostname}",
+                            out: File::NULL, err: File::NULL)
+        Process.detach(pid)
+
+        if (url = poll_public_url)
+          { pid: pid, url: url }
+        else
+          stop(pid: pid)
+          warn "rb-portless: ngrok didn't produce a public URL — is your authtoken set? (`ngrok config add-authtoken <token>`)"
+          nil
+        end
+      rescue StandardError => e
+        warn "rb-portless: ngrok failed (#{e.message})"
+        nil
+      end
+
+      def stop(handle)
+        pid = handle.is_a?(Hash) ? handle[:pid] : handle
+        Process.kill("TERM", pid) if pid
+      rescue StandardError
+        nil
+      end
+
+      def poll_public_url(tries: 25)
+        tries.times do
+          sleep 0.3
+          body = fetch(API)
+          next unless body
+
+          tunnels = JSON.parse(body)["tunnels"] || []
+          url = tunnels.map { |t| t["public_url"] }.compact.find { |u| u.start_with?("https") }
+          return url if url
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def fetch(url)
+        Net::HTTP.get(URI(url))
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/portless/share/tailscale.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Portless
+  module Share
+    # Expose the local app on your tailnet (`serve`) or publicly (`funnel`) via
+    # the tailscale CLI. Returns { mode:, port:, url: } or nil. EXPERIMENTAL.
+    #
+    # SAFETY (mirrors portless's tailscale.ts): we never clobber your existing
+    # serve config — we read `tailscale serve status` for ports already in use
+    # and pick the first FREE one from the preferred list, register with `--yes`
+    # (no prompt), and on teardown turn off ONLY the port we registered.
+    module Tailscale
+      module_function
+
+      PREFERRED_SERVE_PORTS = [ 443, 8443, 8444, 8445, 8446, 8447, 8448, 8449, 8450 ].freeze
+      FUNNEL_PORTS = [ 443, 8443, 10_000 ].freeze # Funnel supports only these
+
+      def start(backend_port:, funnel: false)
+        unless Portless.which("tailscale")
+          warn "rb-portless: tailscale not found — install it (https://tailscale.com/download) to use --tailscale"
+          return nil
+        end
+
+        status = status_json
+        unless status
+          warn "rb-portless: tailscale isn't connected — run `tailscale up`, then retry"
+          return nil
+        end
+        unless capability?(status, "https")
+          warn "rb-portless: tailscale HTTPS certs aren't enabled — turn on HTTPS in your tailnet DNS settings"
+          return nil
+        end
+        if funnel && !capability?(status, "funnel")
+          warn "rb-portless: tailscale Funnel isn't enabled for this node — enable it, then retry --funnel"
+          return nil
+        end
+
+        mode = funnel ? "funnel" : "serve"
+        port = available_port(funnel: funnel)
+        unless port
+          warn "rb-portless: all tailscale Funnel ports are in use (443/8443/10000)"
+          return nil
+        end
+
+        unless system("tailscale", mode, "--bg", "--yes", "--https=#{port}",
+                      "http://127.0.0.1:#{backend_port}", out: File::NULL, err: File::NULL)
+          warn "rb-portless: `tailscale #{mode}` failed to register"
+          return nil
+        end
+
+        base = dns_name(status)
+        return (off(mode, port) and nil) unless base
+
+        { mode: mode, port: port, url: format_url(base, port) }
+      rescue StandardError => e
+        warn "rb-portless: tailscale sharing failed (#{e.message})"
+        nil
+      end
+
+      def stop(handle)
+        return unless handle && Portless.which("tailscale")
+
+        off(handle[:mode], handle[:port])
+      end
+
+      # Turn off ONLY the registration we created (scoped to our port).
+      def off(mode, port)
+        system("tailscale", mode, "--yes", "--https=#{port}", "off", out: File::NULL, err: File::NULL)
+      rescue StandardError
+        nil
+      end
+
+      # First free HTTPS port from the preferred pool, never one already in use by
+      # the user's existing serve/funnel config. nil if the funnel pool is full.
+      def available_port(funnel:)
+        used = used_serve_ports
+        pool = funnel ? FUNNEL_PORTS : PREFERRED_SERVE_PORTS
+        free = pool.find { |port| !used.include?(port) }
+        return free if free
+        return nil if funnel
+
+        port = PREFERRED_SERVE_PORTS.last + 1
+        port += 1 while used.include?(port)
+        port
+      end
+
+      # HTTPS ports the user's current serve config already occupies.
+      def used_serve_ports
+        config = JSON.parse(`tailscale serve status --json 2>/dev/null`)
+        ports = []
+        (config["Web"] || {}).each_key { |host_port| ports << Regexp.last_match(1).to_i if host_port =~ /:(\d+)\z/ }
+        (config["TCP"] || {}).each_key { |port| ports << port.to_i }
+        ports
+      rescue StandardError
+        []
+      end
+
+      def status_json
+        json = JSON.parse(`tailscale status --json 2>/dev/null`)
+        json.is_a?(Hash) ? json : nil
+      rescue StandardError
+        nil
+      end
+
+      def dns_name(status)
+        dns = status.dig("Self", "DNSName").to_s.chomp(".")
+        dns.empty? ? nil : "https://#{dns}"
+      end
+
+      # Does this node have the HTTPS / Funnel capability? (mirrors portless)
+      def capability?(status, name)
+        node = status["Self"] || {}
+        names = Array(node["Capabilities"]) + (node["CapMap"] || {}).keys
+        names.any? { |cap| down = cap.to_s.downcase; down == name || down.end_with?("/#{name}") }
+      end
+
+      def format_url(base, port)
+        base = base.chomp("/")
+        port == 443 ? base : "#{base}:#{port}"
+      end
+    end
+  end
+end

data/lib/portless/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Portless
-  VERSION = "0.1.0"
+  VERSION = "0.3.0.dev.20260630.03ed07d"
 end

data/lib/rb-portless.rb

@@ -17,7 +17,13 @@ require_relative "portless/proxy"
 require_relative "portless/daemon"
 require_relative "portless/service"
 require_relative "portless/frameworks"
+require_relative "portless/banner"
+require_relative "portless/lan_ip"
+require_relative "portless/mdns"
+require_relative "portless/share/ngrok"
+require_relative "portless/share/tailscale"
 require_relative "portless/runner"
+require_relative "portless/multi"
 require_relative "portless/cli"
 
 module Portless
@@ -25,4 +31,9 @@ module Portless
 
   # Raised when a privileged action can't run non-interactively (no TTY / CI).
   class NonInteractiveError < Error; end
+
+  # Is an executable on PATH? (For optional external tools: dns-sd, ngrok, …)
+  def self.which(bin)
+    ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, bin)) }
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rb-portless
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0.dev.20260630.03ed07d
 platform: ruby
 authors:
 - David Afonso
@@ -56,6 +56,7 @@ files:
 - LICENSE
 - README.md
 - exe/rb-portless
+- lib/portless/banner.rb
 - lib/portless/certs.rb
 - lib/portless/cli.rb
 - lib/portless/config.rb
@@ -65,6 +66,9 @@ files:
 - lib/portless/free_port.rb
 - lib/portless/health.rb
 - lib/portless/hosts.rb
+- lib/portless/lan_ip.rb
+- lib/portless/mdns.rb
+- lib/portless/multi.rb
 - lib/portless/privilege.rb
 - lib/portless/proxy.rb
 - lib/portless/rails.rb
@@ -72,6 +76,8 @@ files:
 - lib/portless/route_store.rb
 - lib/portless/runner.rb
 - lib/portless/service.rb
+- lib/portless/share/ngrok.rb
+- lib/portless/share/tailscale.rb
 - lib/portless/state.rb
 - lib/portless/trust.rb
 - lib/portless/version.rb