rb-portless 0.3.1 → 0.4.0.dev.20260630.0d72797

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0df8dbb4c256aa152a22a8dff868be693a0cb35290f1576098ad6bb68b248f7f
-  data.tar.gz: 2a96b1f4877a39d1df935fba7d467066acf08970ce508c44dbc5873c1190c645
+  metadata.gz: 8938cad2e70c50e9e39f2078fe9a8590b6f0324a136cd1da9f5a9258a0604c4f
+  data.tar.gz: 5fe88139d39e877e53b0adf46a87bd20ee361b23f3f858ca74d2039df3ee0562
 SHA512:
-  metadata.gz: f2cf340182dfe22b8ee7cadd2d250a7c4f3c5949a8ff7d0767651e64b706c6927b66e32d9d3c30218f94580879037fa5c4aeb0792c423447e7fd621ac5f6329f
-  data.tar.gz: 71b881128b1a4250ae1d7b65823ca2d582a9fff5597b4cc982293d4e7e22135d6cb90352076159d8c3579f1c2be96efb7e70d130670a26c86a1f8006cedfcd30
+  metadata.gz: e49cc73d6937721e37c41c4489755252c1cc815f1b687b2187a62c6e1a12c3c496d9f3eaf24a948957488ef0b8928f21862c4920225b707988938d53fb0f51bb
+  data.tar.gz: b4ef3864d39837cb27896997d22c24e4ee496c004bfa0a296a534ead61ed1a555936457e55600bcccc942ca41d776c9456ab4bd3dacfd81c7809719b1768bdd1

data/README.md

@@ -112,17 +112,36 @@ anything, same as portless), and each degrades gracefully if the tool is absent:
 | Command | Does |
 | --- | --- |
 | `run <cmd>` | run a dev server through the proxy |
+| `<name> <cmd>` | shorthand for `run --name <name> <cmd>` |
 | `proxy start \| stop` | manage the proxy daemon |
 | `trust` | install the local CA into the OS trust store |
 | `service install \| uninstall \| status` | bind the privileged port at boot (launchd/systemd) |
-| `alias <name> <port>` | a static route (Docker, Postgres, …) |
-| `get <name>` | print a name's URL (for `$(rb-portless get api)`) |
-| `list` | show active routes |
+| `alias <name> <port> [--force]` | a static route (Docker, Postgres, …); `--remove` to drop it |
+| `get <name> [--no-worktree]` | print a name's URL (for `$(rb-portless get api)`) |
+| `list` | show active routes (with any tailscale/ngrok URLs) |
 | `hosts sync \| clean` | manage `/etc/hosts` (Safari / non-`.localhost` TLDs) |
 | `doctor` | diagnose setup |
-| `prune` | reap stale routes |
+| `prune [--force]` | reap stale routes and kill the orphaned dev server (`--force` = SIGKILL) |
 | `clean` | stop the proxy, untrust the CA, remove all state |
 
+Every subcommand takes `--help`. `rb-portless <cmd> --help` prints command-specific
+help.
+
+### Run flags
+
+| Flag | Does |
+| --- | --- |
+| `--name <name>` | override the inferred hostname |
+| `--app-port <n>` | pin the backend port (else a random 4000–4999) |
+| `--force` | take over a route already held by another `run` |
+| `--lan [--ip <addr>]` | also serve on the LAN as `<name>.local` (mDNS) |
+| `--ngrok` / `--tailscale` / `--funnel` | share publicly |
+
+In a **git worktree** linked off a non-default branch, the branch name is prepended
+as a subdomain — `feature/auth` → `https://auth.<name>.localhost` — so every worktree
+gets a distinct URL. Pass `--no-worktree` (on `get`) to skip it. Set **`PORTLESS=0`**
+(`false`/`skip`) to run the command directly without the proxy.
+
 ## Rails
 
 Rails is first-class: it respects `PORT` and trusts the loopback proxy, so

data/lib/portless/banner.rb

@@ -32,12 +32,10 @@ module Portless
 
     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?
+    # ── colours (target stderr, where the banner is printed) ──
+    def bold(str)  = Colors.bold(str, io: $stderr)
+    def dim(str)   = Colors.dim(str, io: $stderr)
+    def cyan(str)  = Colors.cyan(str, io: $stderr)
+    def green(str) = Colors.green(str, io: $stderr)
   end
 end

data/lib/portless/cli.rb

@@ -16,17 +16,24 @@ module Portless
     end
 
     def run
-      return print_version if flag?("--version", "-v")
-      return print_help if @argv.empty? || flag?("--help", "-h")
+      first = @argv.first
+      return print_version if %w[--version -v].include?(first)
+      return print_help if @argv.empty? || %w[--help -h].include?(first)
 
-      command = @argv.first
-      command = "run" unless COMMANDS.include?(command)
-      send("cmd_#{command}", rest(command))
+      if COMMANDS.include?(first)
+        return command_help(first) if %w[--help -h].include?(@argv[1])
+
+        send("cmd_#{first}", rest(first))
+      elsif first.start_with?("--")
+        cmd_run(@argv)        # leading flags (incl. --name) → run mode
+      else
+        cmd_named(@argv)      # `rb-portless <name> <command…>` shorthand
+      end
     rescue Portless::NonInteractiveError => e
-      warn "rb-portless: #{e.message}"
+      warn error_line(e.message)
       exit 2
     rescue Portless::Error => e
-      warn "rb-portless: #{e.message}"
+      warn error_line(e.message)
       exit 1
     end
 
@@ -42,54 +49,73 @@ module Portless
       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.
+    # `rb-portless <name> <command…>`: run the command under the hostname <name>
+    # (portless's named-app shorthand). The first non-flag token is the name.
+    def cmd_named(args)
+      options, rest = parse_run(args)
+      name = rest.shift
+      if rest.empty?
+        raise Error, "no command given — try `rb-portless run #{name}` or `rb-portless #{name} <command>`"
+      end
+
+      options[:name] = name
+      Runner.new(command: rest, options: options).run
+    end
+
+    # Pull known flags out of the run args from anywhere before `--` (mirrors
+    # portless's global-flag stripping), leaving the command to execute. Flags:
+    # --lan/--ip, sharing (--ngrok/--tailscale/--funnel), --name, --force,
+    # --app-port. Everything after `--` is the command verbatim.
     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
+      command = []
+      i = 0
+      while i < args.length
+        case args[i]
+        when "--"          then command.concat(args[i + 1..]); break
+        when "--lan"       then options[:lan] = true
+        when "--ip"        then options[:ip] = args[i += 1]
+        when "--ngrok"     then options[:ngrok] = true
+        when "--tailscale" then options[:tailscale] = true
+        when "--funnel"    then options[:funnel] = true
+        when "--force"     then options[:force] = true
+        when "--name"      then options[:name] = args[i += 1]
+        when "--app-port"  then options[:app_port] = parse_port!(args[i += 1], "--app-port")
+        else command << args[i]
         end
+        i += 1
       end
-      [ options, rest ]
+      [ options, command ]
     end
 
     def cmd_proxy(args)
-      action = args.first
-      case action
+      case args.first
       when "start"
         Daemon.start(tls: tls_flag(args), port: int_flag(args, "--port"), foreground: flag?("--foreground"))
-      when "stop"
-        Daemon.stop
-      else
-        warn "usage: rb-portless proxy start|stop"
-        exit 1
+      when "stop" then Daemon.stop
+      when nil    then command_help("proxy")
+      else invalid_action!("proxy start|stop")
       end
     end
 
     def cmd_trust(_args)
       if Trust.trusted?
-        puts "rb-portless: CA already trusted"
+        info "CA already trusted"
       else
         Trust.install!
-        puts "rb-portless: local CA trusted"
+        ok "local CA trusted"
       end
     end
 
     def cmd_list(_args)
       routes = RouteStore.new.routes
-      if routes.empty?
-        puts "rb-portless: no active routes"
-      else
-        routes.each { |r| puts format("%-40s → :%d", r.hostname, r.port) }
+      return puts(Colors.dim("rb-portless: no active routes")) if routes.empty?
+
+      routes.each do |r|
+        tag = r.alias? ? "alias" : "pid #{r.pid}"
+        puts "#{Colors.cyan(r.hostname.ljust(40))} → :#{r.port}  #{Colors.dim("(#{tag})")}"
+        puts "    #{Colors.dim('↳ tailnet')} #{Colors.green(r.tailscale)}" if r.tailscale
+        puts "    #{Colors.dim('↳ ngrok  ')} #{Colors.green(r.ngrok)}" if r.ngrok
       end
     end
 
@@ -98,40 +124,46 @@ module Portless
       when "sync"
         hostnames = RouteStore.new.routes.map(&:hostname).uniq
         with_hosts_write([ "hosts", "sync" ]) { Hosts.sync(hostnames) }
-        puts "rb-portless: synced #{hostnames.size} host(s) to #{Hosts.file}"
+        ok "synced #{hostnames.size} host(s) to #{Hosts.file}"
       when "clean"
         with_hosts_write([ "hosts", "clean" ]) { Hosts.clean }
-        puts "rb-portless: cleaned #{Hosts.file}"
-      else
-        warn "usage: rb-portless hosts sync|clean"
-        exit 1
+        ok "cleaned #{Hosts.file}"
+      when nil then command_help("hosts")
+      else invalid_action!("hosts sync|clean")
       end
     end
 
     def cmd_alias(args)
       if args.first == "--remove"
         name = args[1] or abort_usage("alias --remove <name>")
-        RouteStore.new.remove(hostname_for(name))
-        puts "rb-portless: removed alias #{hostname_for(name)}"
+        host = hostname_for(name)
+        raise Error, "no alias found for #{host}" unless RouteStore.new.remove(host, owner_pid: 0)
+        ok "removed alias #{host}"
       else
-        name, port = args
-        abort_usage("alias <name> <port>") unless name && port
-        RouteStore.new.add(hostname: hostname_for(name), port: Integer(port), pid: 0, force: true)
-        puts "rb-portless: #{hostname_for(name)} → :#{port}"
+        name, port = args.reject { |a| a.start_with?("--") }
+        abort_usage("alias <name> <port> [--force]") unless name && port
+        host = hostname_for(name)
+        port = parse_port!(port, "port")
+        RouteStore.new.add(hostname: host, port: port, pid: 0, force: args.include?("--force"))
+        ok "#{host} → :#{port}"
       end
     end
 
     def cmd_get(args)
-      name = args.first or abort_usage("get <name>")
+      worktree = !args.include?("--no-worktree")
+      name = args.find { |a| !a.start_with?("--") } or abort_usage("get <name> [--no-worktree]")
       config = Config.load
-      puts "#{config.tls ? 'https' : 'http'}://#{hostname_for(name)}"
+      host = hostname_for(name)
+      host = "#{config.worktree_prefix}.#{host}" if worktree && config.worktree_prefix
+      puts "#{config.tls ? 'https' : 'http'}://#{host}"
     end
 
-    def cmd_prune(_args)
-      store = RouteStore.new
-      before = store.routes.size
-      store.prune
-      puts "rb-portless: pruned #{before - store.routes.size} stale route(s)"
+    def cmd_prune(args)
+      force = args.include?("--force")
+      pruned = RouteStore.new.prune
+      killed = pruned.sum { |r| PortOwner.kill(r.port, force: force) }
+      note = killed.positive? ? ", killed #{killed} orphan process(es)" : ""
+      ok "pruned #{pruned.size} stale route(s)#{note}"
     end
 
     def cmd_clean(_args)
@@ -140,10 +172,13 @@ module Portless
       begin; with_hosts_write([ "hosts", "clean" ]) { Hosts.clean }; rescue StandardError; end
       require "fileutils"
       FileUtils.rm_rf(State.dir)
-      puts "rb-portless: removed all state"
+      ok "removed all state"
     end
 
-    def cmd_doctor(_args)
+    def cmd_doctor(args)
+      extra = args.reject { |a| %w[--help -h].include?(a) }
+      raise Error, "unknown argument #{extra.first.inspect}" unless extra.empty?
+
       port = Health.discover_port
       routes = RouteStore.new.routes
       report = [
@@ -151,12 +186,14 @@ module Portless
         [ "state dir", File.directory?(State.dir), State.dir ],
         [ "proxy running", !port.nil?, port ? "on :#{port}" : "not running" ],
         [ "CA generated", File.exist?(State.ca_cert), nil ],
-        [ "CA trusted", safe { Trust.trusted? }, Constants::MACOS ? nil : "macOS only for now" ],
+        [ "CA trusted", safe { Trust.trusted? }, safe { Trust.trusted? } ? nil : "run `rb-portless trust`" ],
         [ "routes", true, "#{routes.size} active" ]
       ]
-      report.each do |label, ok, note|
-        puts "  #{ok ? '✓' : '✗'} #{label}#{note ? " — #{note}" : ''}"
+      report.each do |label, pass, note|
+        mark = pass ? Colors.green("✓") : Colors.red("✗")
+        puts "  #{mark} #{label}#{note ? " — #{Colors.dim(note)}" : ''}"
       end
+      exit 1 if report.any? { |_label, pass, _note| !pass }
     end
 
     def cmd_service(args)
@@ -164,9 +201,8 @@ module Portless
       when "install" then Service.install(tls: tls_flag(args), port: int_flag(args, "--port"))
       when "uninstall" then Service.uninstall
       when "status" then Service.status
-      else
-        warn "usage: rb-portless service install|uninstall|status"
-        exit 1
+      when nil then command_help("service")
+      else invalid_action!("service install|uninstall|status")
       end
     end
 
@@ -189,10 +225,23 @@ module Portless
     end
 
     def abort_usage(usage)
-      warn "usage: rb-portless #{usage}"
+      warn error_line("usage: rb-portless #{usage}")
+      exit 1
+    end
+
+    # An *unknown* sub-action is an error (exit 1); a bare subcommand prints its
+    # help and exits 0 (handled by the `when nil` arms). Mirrors portless's
+    # `exit(help || !args[1] ? 0 : 1)`.
+    def invalid_action!(usage)
+      warn error_line("usage: rb-portless #{usage}")
       exit 1
     end
 
+    # ── Output (colour no-ops when not a TTY / NO_COLOR) ──────────────────
+    def ok(msg)   = puts Colors.green("rb-portless: #{msg}")
+    def info(msg) = puts "rb-portless: #{msg}"
+    def error_line(msg) = Colors.red("rb-portless: #{msg}", io: $stderr)
+
     # ── Flag helpers ──────────────────────────────────────────────────────
     def tls_flag(args)
       return false if args.include?("--no-tls")
@@ -205,6 +254,14 @@ module Portless
       i ? Integer(args[i + 1], exception: false) : nil
     end
 
+    # Parse + validate a port in 1–65535, with a clean error (never a backtrace).
+    def parse_port!(value, label)
+      port = Integer(value.to_s, exception: false)
+      raise Error, "invalid #{label} #{value.inspect} — must be 1-65535" unless port&.between?(1, 65_535)
+
+      port
+    end
+
     def rest(command)
       @argv.first == command ? @argv[1..] : @argv
     end
@@ -217,26 +274,85 @@ module Portless
 
     def print_help
       puts <<~HELP
-        rb-portless #{Portless::VERSION} — named .localhost URLs for local dev
+        #{Colors.bold("rb-portless #{Portless::VERSION}")} — named .localhost URLs for local dev
 
-        Usage:
+        #{Colors.blue('Usage:')}
           rb-portless run <command>        run a dev server through the proxy
           rb-portless run                  run the `apps` map, or the dev script
+          rb-portless <name> <command>     run <command> at https://<name>.localhost
+          rb-portless get <name>           print a service's URL (--no-worktree)
+          rb-portless alias <name> <port>  static route for an unmanaged service
           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)
           rb-portless list                 show active routes
           rb-portless doctor               diagnose setup
-          rb-portless clean | prune        tear down / reap orphans
+          rb-portless clean | prune        tear down / reap orphans (--force kills)
           rb-portless service install      bind the privileged port at boot
 
-        run flags:
+        #{Colors.blue('run flags:')}
+          --name <name>                    override the inferred hostname
+          --app-port <n>                   fix the backend port (else auto)
+          --force                          take over a route owned by another run
           --lan [--ip <addr>]              also serve on the LAN (<name>.local)
           --ngrok                          share publicly via ngrok
           --tailscale | --funnel           share via your tailnet / Funnel
 
+        In a linked git worktree on a non-default branch, the branch name is
+        prepended as a subdomain (auth.<name>.localhost). PORTLESS=0 runs the
+        command directly without the proxy.
+
         HTTPS is the default (https://<name>.localhost). Config: portless.json.
       HELP
     end
+
+    # Per-command help (`rb-portless <cmd> --help`, or a bare subcommand). Kept
+    # as plain data so the renderer can colourise it for the terminal.
+    HELP = {
+      "run"     => { summary: "Run a dev server through the proxy.",
+                     usage: [ "run <command>", "run   (the apps map, or bin/dev / bin/rails server)" ],
+                     flags: [ [ "--name <name>", "override the inferred hostname" ],
+                              [ "--app-port <n>", "fix the backend port (else auto)" ],
+                              [ "--force", "take over a route held by another run" ],
+                              [ "--lan [--ip <addr>]", "also serve on the LAN" ],
+                              [ "--ngrok | --tailscale | --funnel", "share publicly" ] ],
+                     example: "rb-portless run bin/dev" },
+      "get"     => { summary: "Print a service's URL (for scripts / env vars).",
+                     usage: [ "get <name> [--no-worktree]" ],
+                     flags: [ [ "--no-worktree", "skip the git-worktree subdomain prefix" ] ],
+                     example: "DB_URL=$(rb-portless get db)" },
+      "alias"   => { summary: "Static route for a service portless doesn't manage.",
+                     usage: [ "alias <name> <port> [--force]", "alias --remove <name>" ],
+                     flags: [ [ "--force", "overwrite an existing route" ] ],
+                     example: "rb-portless alias postgres 5432   # -> https://postgres.localhost" },
+      "proxy"   => { summary: "Manage the proxy daemon.",
+                     usage: [ "proxy start [--no-tls] [--port <n>]", "proxy stop" ] },
+      "trust"   => { summary: "Trust the local CA so HTTPS works without warnings.",
+                     usage: [ "trust" ] },
+      "hosts"   => { summary: "Manage the /etc/hosts block (Safari / non-.localhost TLDs).",
+                     usage: [ "hosts sync", "hosts clean" ] },
+      "list"    => { summary: "Show active routes.", usage: [ "list" ] },
+      "doctor"  => { summary: "Diagnose the setup (read-only).", usage: [ "doctor" ] },
+      "clean"   => { summary: "Remove all state: stop proxy, untrust CA, clear routes & hosts.",
+                     usage: [ "clean" ] },
+      "prune"   => { summary: "Reap routes whose owner died; kill the orphaned dev server.",
+                     usage: [ "prune [--force]" ],
+                     flags: [ [ "--force", "SIGKILL the orphan instead of SIGTERM" ] ] },
+      "service" => { summary: "Install the proxy as an OS startup service (binds 443 at boot).",
+                     usage: [ "service install [--no-tls] [--port <n>]", "service uninstall", "service status" ] }
+    }.freeze
+
+    def command_help(name)
+      h = HELP.fetch(name)
+      out = [ "", "  #{Colors.bold("rb-portless #{name}")} — #{h[:summary]}", "", "  #{Colors.blue('Usage:')}" ]
+      h[:usage].each { |u| out << "    #{Colors.cyan("rb-portless #{u}")}" }
+      if h[:flags]
+        out << "" << "  #{Colors.blue('Flags:')}"
+        h[:flags].each { |flag, desc| out << "    #{Colors.cyan(flag.ljust(34))} #{desc}" }
+      end
+      out << "" << "  #{Colors.dim("Example: #{h[:example]}")}" if h[:example]
+      out << ""
+      puts out.join("\n")
+    end
   end
 end

data/lib/portless/colors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Portless
+  # ANSI colours for CLI output. A no-op when the target stream isn't a TTY (so
+  # piped/redirected output stays clean) or when NO_COLOR is set. Mirrors
+  # portless's `colors` helper.
+  module Colors
+    extend self
+
+    CODES = { bold: 1, dim: 90, gray: 90, red: 31, green: 32, yellow: 33, blue: 34, cyan: 36 }.freeze
+
+    CODES.each_key do |name|
+      define_method(name) { |str, io: $stdout| paint(name, str, io: io) }
+    end
+
+    def paint(name, str, io: $stdout)
+      return str.to_s unless enabled?(io)
+
+      "\e[#{CODES.fetch(name)}m#{str}\e[0m"
+    end
+
+    def enabled?(io)
+      ENV["NO_COLOR"].to_s.empty? && io.respond_to?(:tty?) && io.tty?
+    end
+  end
+end

data/lib/portless/config.rb

@@ -24,9 +24,22 @@ module Portless
     end
 
     # The full hostname an app registers (e.g. "shirabe.org.localhost" when tld is
-    # set to that, or "<name>.localhost" by default).
-    def hostname
-      tld.split(".").include?(name) ? tld : "#{name}.#{tld}"
+    # set to that, or "<name>.localhost" by default). `name` overrides the base
+    # (used by --name); `worktree:` prepends the git-worktree branch prefix so a
+    # linked worktree gets its own URL (`auth.<name>.localhost`).
+    def hostname(name = nil, worktree: true)
+      base = name ? sanitize_label(name) : @name
+      host = tld.split(".").include?(base) ? tld : "#{base}.#{tld}"
+      prefix = worktree ? worktree_prefix : nil
+      prefix ? "#{prefix}.#{host}" : host
+    end
+
+    # The git-worktree subdomain prefix for this project dir (nil if none).
+    # Memoized — it shells out to git.
+    def worktree_prefix
+      return @worktree_prefix if defined?(@worktree_prefix)
+
+      @worktree_prefix = Worktree.prefix(@dir)
     end
 
     # Real/reserved TLDs that can intercept live traffic or clash with mDNS.

data/lib/portless/multi.rb

@@ -35,7 +35,8 @@ module Portless
 
     def start_app(name, command, proxy_port)
       port = FreePort.find
-      hostname = "#{name}.#{@config.tld}"
+      prefix = @config.worktree_prefix
+      hostname = "#{prefix ? "#{prefix}.#{name}" : 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").

data/lib/portless/port_owner.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Portless
+  # Best-effort "who is listening on this TCP port" — used by `prune` to reap an
+  # orphaned dev server whose owning CLI process already died but whose backend
+  # port is still held. Shells out to lsof (present on macOS + most Linux);
+  # silently no-ops when it's unavailable. Mirrors portless's port-kill in prune.
+  module PortOwner
+    module_function
+
+    def listeners(port)
+      return [] unless Portless.which("lsof")
+
+      out = IO.popen([ "lsof", "-ti", "tcp:#{Integer(port)}", "-sTCP:LISTEN" ], err: File::NULL, &:read)
+      out.split.filter_map { |p| Integer(p, exception: false) }
+    rescue StandardError
+      []
+    end
+
+    # Signal every listener on `port` (TERM, or KILL with force). Never signals
+    # ourselves. Returns how many processes were signalled.
+    def kill(port, force: false)
+      sig = force ? "KILL" : "TERM"
+      listeners(port).count do |pid|
+        next false if pid == Process.pid
+
+        Process.kill(sig, pid)
+        true
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/portless/route_store.rb

@@ -9,7 +9,7 @@ module Portless
   # directory mutex (atomic mkdir), and the proxy watches it. Dead-pid entries
   # are reaped on every load. Mirrors portless's RouteStore.
   class RouteStore
-    Route = Struct.new(:hostname, :port, :pid, keyword_init: true) do
+    Route = Struct.new(:hostname, :port, :pid, :tailscale, :ngrok, keyword_init: true) do
       def alias? = pid.to_i.zero? # pid 0 = static alias (never reaped)
     end
 
@@ -22,39 +22,58 @@ module Portless
     end
 
     def routes
-      load.map { |h| Route.new(hostname: h["hostname"], port: h["port"], pid: h["pid"]) }
+      load.map do |h|
+        Route.new(hostname: h["hostname"], port: h["port"], pid: h["pid"],
+                  tailscale: h["tailscale"], ngrok: h["ngrok"])
+      end
     end
 
     # Register (or replace) a route. Conflicts with a *live* different owner raise
-    # unless force, which SIGTERMs the incumbent. Alias routes use pid 0.
-    def add(hostname:, port:, pid:, force: false)
+    # unless force, which SIGTERMs the incumbent. Alias routes use pid 0. Public
+    # share URLs (tailscale/ngrok), when present, are recorded so `list` can show
+    # them while the run is active.
+    def add(hostname:, port:, pid:, force: false, tailscale: nil, ngrok: nil)
       with_lock do
         all = load.reject { |r| dead?(r["pid"]) }
         existing = all.find { |r| r["hostname"] == hostname }
         if existing && existing["pid"].to_i != pid.to_i && !dead?(existing["pid"])
-          raise Error, "#{hostname} is already served by pid #{existing['pid']}" unless force
+          unless force
+            raise RouteConflictError,
+                  "#{hostname} is already served by pid #{existing['pid']} — pass --force to take it over"
+          end
           terminate(existing["pid"])
         end
         all.reject! { |r| r["hostname"] == hostname }
-        all << { "hostname" => hostname, "port" => port, "pid" => pid }
+        entry = { "hostname" => hostname, "port" => port, "pid" => pid }
+        entry["tailscale"] = tailscale if tailscale
+        entry["ngrok"] = ngrok if ngrok
+        all << entry
         write(all)
       end
     end
 
     # Remove a route only if still owned by `owner_pid` (so a force-replaced
-    # predecessor doesn't delete the successor's route on its way out).
+    # predecessor doesn't delete the successor's route on its way out). Returns
+    # whether anything was actually removed.
     def remove(hostname, owner_pid: nil)
       with_lock do
-        all = load
-        all.reject! do |r|
+        before = load
+        after = before.reject do |r|
           r["hostname"] == hostname && (owner_pid.nil? || r["pid"].to_i == owner_pid.to_i)
         end
-        write(all)
+        write(after)
+        after.size < before.size
       end
     end
 
+    # Drop dead-pid routes and return them (so callers can reap the orphaned
+    # process still holding the backend port). Alias routes (pid 0) are kept.
     def prune
-      with_lock { write(load.reject { |r| dead?(r["pid"]) }) }
+      with_lock do
+        dead, alive = load.partition { |r| dead?(r["pid"]) }
+        write(alive)
+        dead.map { |r| Route.new(hostname: r["hostname"], port: r["port"], pid: r["pid"]) }
+      end
     end
 
     private

data/lib/portless/runner.rb

@@ -12,26 +12,30 @@ module Portless
       @command = Array(command)
       @config = config
       @route_store = route_store
-      @options = options # :lan, :ip, :ngrok, :tailscale, :funnel
+      @options = options # :lan, :ip, :ngrok, :tailscale, :funnel, :name, :force, :app_port
     end
 
     def run
       command = resolved_command
       raise Error, "nothing to run — pass a command, e.g. rb-portless run bin/dev" if command.empty?
 
-      port = @config.app_port&.to_i || FreePort.find
+      # PORTLESS=0|false|skip → run the command straight through, no proxy/route.
+      return exec(*command) if Portless.skip_proxy?
+
+      port = @options[:app_port] || @config.app_port&.to_i || FreePort.find
       command = Frameworks.inject(command, port) # --port/--host for vite/astro/etc.
-      hostname = @config.hostname
+      hostname = @config.hostname(@options[:name])
 
       warn "rb-portless: #{@config.tld_warning}" if @config.tld_warning
       ensure_trusted
       proxy_port = Daemon.ensure_running(tls: @config.tls)
-      @route_store.add(hostname: hostname, port: port, pid: Process.pid, force: true)
+      @route_store.add(hostname: hostname, port: port, pid: Process.pid, force: @options[:force])
 
       url = display_url(hostname, proxy_port)
       rows = [ [ "Local", url, :cyan ] ]
       rows.concat(lan_rows(port, proxy_port))
       rows.concat(share_rows(hostname, port))
+      record_share_urls(hostname, port) # so `rb-portless list` shows the public URLs
       Banner.app(rows: rows, backend_port: port)
 
       status = supervise(command, port, url)
@@ -53,7 +57,7 @@ module Portless
       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)
+      @route_store.add(hostname: @lan_host, port: backend_port, pid: Process.pid, force: @options[:force])
       @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 ] ]
@@ -72,6 +76,15 @@ module Portless
       rows
     end
 
+    # Re-register the route with the public share URLs once tunnels are up, so a
+    # `list` from another terminal surfaces them while this run is active.
+    def record_share_urls(hostname, port)
+      return unless @ngrok || @tailscale
+
+      @route_store.add(hostname: hostname, port: port, pid: Process.pid,
+                       tailscale: @tailscale&.dig(:url), ngrok: @ngrok&.dig(:url))
+    end
+
     def teardown
       Mdns.unpublish(@mdns_pid)
       @route_store.remove(@lan_host, owner_pid: Process.pid) if @lan_host

data/lib/portless/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Portless
-  VERSION = "0.3.1"
+  VERSION = "0.4.0.dev.20260630.0d72797"
 end

data/lib/portless/worktree.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Portless
+  # Git-worktree-aware hostname prefix. In a *linked* worktree (one created via
+  # `git worktree add`, not the root checkout) sitting on a non-default branch,
+  # the branch's last path segment becomes a subdomain prefix so each worktree
+  # gets its own URL — `feature/auth` → `auth.<name>.localhost`. Returns nil in
+  # the root worktree, on main/master, on detached HEAD, or outside git.
+  # Mirrors portless's detectWorktreePrefix (git-CLI path).
+  module Worktree
+    module_function
+
+    DEFAULT_BRANCHES = %w[main master].freeze
+
+    def prefix(dir = Dir.pwd)
+      Portless.which("git") ? via_cli(dir) : via_filesystem(dir)
+    rescue StandardError
+      nil
+    end
+
+    # Authoritative path: ask git directly.
+    def via_cli(dir)
+      list = git(dir, "worktree", "list", "--porcelain")
+      return nil if list.nil?
+      return nil if list.lines.count { |l| l.start_with?("worktree ") } <= 1
+
+      # Only a *linked* worktree gets a prefix: there --git-dir differs from
+      # --git-common-dir; in the root worktree they're the same path.
+      git_dir = git(dir, "rev-parse", "--git-dir")
+      common  = git(dir, "rev-parse", "--git-common-dir")
+      return nil if git_dir.nil? || common.nil?
+      return nil if File.expand_path(git_dir, dir) == File.expand_path(common, dir)
+
+      branch_to_prefix(git(dir, "rev-parse", "--abbrev-ref", "HEAD"))
+    end
+
+    # Fallback when the git binary isn't available: walk up for a `.git` *file*
+    # (worktrees use a file, not a dir) whose gitdir points into /worktrees/, and
+    # read the branch from that gitdir's HEAD. Submodules (/modules/) are ignored.
+    def via_filesystem(dir)
+      current = File.expand_path(dir)
+      loop do
+        git_path = File.join(current, ".git")
+        return nil if File.directory?(git_path) # root checkout, not a worktree
+
+        if File.file?(git_path)
+          gitdir = File.read(git_path)[/^gitdir:\s*(.+)$/, 1]
+          return nil unless gitdir&.match?(%r{[/\\]worktrees[/\\][^/\\]+$})
+
+          head = File.read(File.join(File.expand_path(gitdir, current), "HEAD"))
+          return branch_to_prefix(head[%r{^ref: refs/heads/(.+)$}, 1])
+        end
+
+        parent = File.dirname(current)
+        return nil if parent == current
+
+        current = parent
+      end
+    end
+
+    # Last `/`-segment of the branch, sanitized; nil for default/detached HEAD.
+    def branch_to_prefix(branch)
+      return nil if branch.nil? || branch.empty? || branch == "HEAD"
+      return nil if DEFAULT_BRANCHES.include?(branch)
+
+      label = branch.split("/").last.to_s.downcase.gsub(/[^a-z0-9-]+/, "-").gsub(/\A-+|-+\z/, "")
+      label.empty? ? nil : label
+    end
+
+    def git(dir, *args)
+      out = IO.popen([ "git", "-C", dir, *args ], err: File::NULL, &:read)
+      $?.success? ? out.strip : nil
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/rb-portless.rb

@@ -4,9 +4,12 @@
 # of Vercel's portless). See AGENTS.md for the architecture map.
 require_relative "portless/version"
 require_relative "portless/constants"
+require_relative "portless/colors"
 require_relative "portless/state"
+require_relative "portless/worktree"
 require_relative "portless/config"
 require_relative "portless/free_port"
+require_relative "portless/port_owner"
 require_relative "portless/route_store"
 require_relative "portless/health"
 require_relative "portless/privilege"
@@ -33,6 +36,14 @@ module Portless
   # Raised when a privileged action can't run non-interactively (no TTY / CI).
   class NonInteractiveError < Error; end
 
+  # Raised when a hostname is already served by a different live owner and the
+  # caller didn't pass --force. Mirrors portless's RouteConflictError.
+  class RouteConflictError < Error; end
+
+  # `PORTLESS=0|false|skip` runs the command straight through, no proxy/route —
+  # the bypass portless documents for CI or one-off plain runs.
+  def self.skip_proxy? = %w[0 false skip].include?(ENV["PORTLESS"].to_s.downcase)
+
   # 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)) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rb-portless
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0.dev.20260630.0d72797
 platform: ruby
 authors:
 - David Afonso
@@ -59,6 +59,7 @@ files:
 - lib/portless/banner.rb
 - lib/portless/certs.rb
 - lib/portless/cli.rb
+- lib/portless/colors.rb
 - lib/portless/config.rb
 - lib/portless/constants.rb
 - lib/portless/daemon.rb
@@ -69,6 +70,7 @@ files:
 - lib/portless/lan_ip.rb
 - lib/portless/mdns.rb
 - lib/portless/multi.rb
+- lib/portless/port_owner.rb
 - lib/portless/privilege.rb
 - lib/portless/proxy.rb
 - lib/portless/rails.rb
@@ -82,6 +84,7 @@ files:
 - lib/portless/state.rb
 - lib/portless/trust.rb
 - lib/portless/version.rb
+- lib/portless/worktree.rb
 - lib/rb-portless.rb
 homepage: https://github.com/davafons/rb-portless
 licenses: