ask-local 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b2c1d943d3bbfb315651a8bd50deb3519f325822e894f1c4040d30b7523cb46
-  data.tar.gz: 9ad93192b70b62cae5292b5a1784bd9086e4103dba7d4f2a07aa83b7327bf795
+  metadata.gz: a9b2c40e96d2ccde2095d698a79684a3dec1335afe9ac4acc1773405f520002d
+  data.tar.gz: a2a63d630679488b6236a499bb954fa2cf70028c2f00d5dd34c2f76a21ef057b
 SHA512:
-  metadata.gz: 74920fa209896d3a66f67245c6757f45f9c23793147dabfdf7e1f088f0c6af9fcb41442f44dcd1657816617aa88eaa318a5c57fde6035dc767704812bef7f0ff
-  data.tar.gz: c65585ddefac14be0b4898f3e5af9b96f370826bb11b43bc2f2ace9ce3dd350b1f8ba6b0a6b6bd45f2f43eecf1a34f4831bb1fff439087b01ce6ef1da379d169
+  metadata.gz: dc721fac709387e593ed445f03080e994fcd2614ec5ff74e92ba4ccccf17dea61d59029ab187eaffe1eca52a088c817a36d86cdf7e7c13a8d3fd5878d8284f7a
+  data.tar.gz: 16c12424f982fc3db86c2fd210cae69e7890abc22c3f1cdd8c747cfac9ab2c15952c431ee72557144d5dfccd8bc9c95aebe0ab94b6cb3b30c95faa33329a8b5a

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## [0.1.1] — 2026-09-06
+
+Patch release focused on workstation setup, URL correctness, and proxy reliability.
+
+### Added — `ask-local setup` & `ask-local start`
+
+- `ask-local setup` — one-shot workstation setup for clean
+  `https://<app>.localhost` URLs: trust the local CA, serve port 443
+  (root launchd/systemd service when possible, sudo daemon otherwise),
+  sync `/etc/hosts`, and verify with `doctor`. Each step reports
+  `==>` / `ok` and the first failure aborts with the specific fix.
+- `ask-local start` — one-setup-and-go entry point: an idempotent
+  workstation-check-then-boot (`ask-local setup` if needed, then the
+  app). `ask-local` bare is an alias for it; `ask-local setup` stays for
+  explicit re-setup.
+- `askl` — shell-friendly alias binary (`bin/askl`, same entry point as
+  `bin/ask-local`). Keep `ask-local` in logs and docs so `grep` stays
+  useful.
+
+### Added — DNS-rebinding & log hygiene
+
+- DNS-rebinding boundary: foreign `Host` headers get a bare 404 naming
+  nothing; only hosts under our own configured TLDs see the route-listing
+  404. The proxy takes `--tld` (persisted to `proxy.tlds`) so the boundary
+  follows custom domains. The `X-Ask-Local: 1` health header marks our
+  proxy responses (including 404s) for the `ours?` probe.
+- Log rotation — `proxy.log` and per-app backend logs rotate at 5MB
+  (`ASK_LOCAL_LOG_MAX_BYTES`, one generation) before each write. A new
+  `doctor` disk-usage check warns past 100MB of state.
+
+### Fixed
+
+- **Silent `:1355` URL fallback removed.** Privileged-port (443) bind
+  failure is now a hard error pointing at `ask-local setup`, never a
+  booted app on `https://app.localhost:1355` that silently corrupts
+  downstream consumers of `ASK_LOCAL_URL`. The only port-suffixed URLs
+  are the ones you explicitly ask for (`proxy start -p 1355`).
+- **Health probe `130+?` hang fixed.** The TLS probe's `connect` sat
+  outside the timeout: a TLS handshake against a foreign plain-HTTP
+  server blocked in `connect` for 60s+. Connect is now inside the
+  timeout, plain HTTP is tried first (our proxy answers plain HTTP via
+  byte-peeking even on the TLS port), and any HTTP response without our
+  header short-circuits as foreign — only silent servers wait for the
+  timeout.
+- `start` dispatch was missing from the dispatcher despite being in
+  `SUBCOMMANDS`, so `ask-local start` fell through to `run_named` with
+  "start" as an app name. The kamal-help append drifted to a 6-space
+  indent. Both are fixed and pinned by tests.
+- `base64` declared as a runtime dependency (it left the default gems in
+  Ruby 3.4).
+- Missing `require "optparse"` lost in the CLI split.
+
+### Tests — new coverage for this patch
+
+- `start_test.rb` — help, fast-path vs. needs-setup branching, and the
+  non-interactive hard-error message.
+- `setup_test.rb` — four-step orchestration (all-steps-stubbed), first-failure
+  abort with fix text, `--no-service` flag, and the three `ensure_proxy!`
+  hard-error paths (non-interactive, foreign port, spawn failure) plus
+  explicit-port URL honesty and responding-foreign-server fast classification.
+- Pinned under `bundle exec rake test` (fast unit suite); no `test:e2e`
+  needed for these.
+
 ## [0.2.0] — Unreleased
 
 ### Changed
@@ -22,10 +85,11 @@
 - Root-owned `service install` (launchd/systemd) binding 80/443 at boot
   with the invoking user's state dir; sudo re-exec when needed.
 - All root write paths chown state back to the invoking user; `doctor`
-  reports an unwritable state dir plainly.
+  reports an unwritable state dir plainly. The privileged auto-start
+  re-execs under `sudo` with the correct state dir.
 - Bounded proxy concurrency (`ASK_LOCAL_MAX_CONNECTIONS`, 503 past the
-  cap), mtime-TTL route cache, IPv4+IPv6 loopback listeners, dual-stack
-  `ours?` health check.
+  cap), mtime-based route cache (no TTL race for boot-then-curl), IPv4+IPv6
+  loopback listeners, dual-stack `ours?` health check.
 - `get` inherits variant/TLD context from the current directory
   (`get backend` in a fix-ui worktree -> fix-ui.backend.localhost);
   `--service/--variant/--tld` overrides.
@@ -37,32 +101,12 @@
 - Ships the `ask-local` agent skill (ask/skills/ask-local/SKILL.md).
 - `test:e2e` / `test:all` rake tasks; CI matrix (3.2/3.3/3.4/4.0),
   macOS e2e leg, fixture-sweep job.
-- Ownership module: root write paths chown state back to the invoking
-  user; `doctor` reports an unwritable state dir with the fix.
-- Proxy hardening: bounded concurrency (503 past the cap), mtime-TTL
-  route cache, IPv4+IPv6 loopback listeners, dual-stack health check,
-  oversize-hostname refusal.
-- `status` (effective naming context), `open [name]`, `log -f`;
-  `stop` exit codes 0/2/3; `list` shows backend liveness.
-- Sinatra-modular + foreman-`$PORT` fixtures; no-double-injection guard.
-- SKILL.md "when NOT to use" section (CI, prod, Docker networks).
-- Framework coverage: hanami2 slice layout, jekyll livereload second
-  port (`--livereload-port` pinned next to the main port when
-  `livereload: true`), roda-plugins managed boot; no-double-injection
-  guard for explicit `$PORT`.
-- Chunked request uploads pinned by test (streamed intact,
-  close-delimited).
-- README non-goals section (HTTP/2, tunnels, production) with rationale.
-- DNS-rebinding boundary: foreign Hosts get a bare 404; only our own
-  TLDs see the route-listing 404. Proxy takes `--tld` (persisted) so the
-  boundary follows custom domains.
-- Log rotation (5MB, one generation) on proxy + backend logs; `doctor`
-  disk-usage check.
-- `--json` on list/status/doctor with stable keys; `status` sources made
-  explicit (no more `(from -)`).
-- Route cache keyed on file mtime (no TTL race for boot-then-curl);
-  foreground supervision polls at 2Hz with the detached-children
-  rationale documented.
+- Ownership module, framework fixtures (sinatra-modular,
+  foreman-`$PORT`, hanami2 slice layout, jekyll livereload), SKILL.md
+  "when NOT to use" section, README non-goals, vite/Shakapacker recipe.
+- Host authorization patterns default TLDs from `ASK_LOCAL_TLD`.
+- WebSocket Upgrade end-to-end test (RFC 6455 handshake + frame echo),
+  hop-loop 508 rejection, chunked framing, and spinning-loop fix.
 
 ### Fixed
 
@@ -81,9 +125,6 @@
 - Bidirectional streaming terminates promptly on `Connection: close`
   (each pump direction closes its peer on EOF).
 - `alias --remove` now appends the default TLD.
-- `base64` declared as a runtime dependency (left the default gems in
-  Ruby 3.4).
-- Missing `require "optparse"` lost in the CLI split.
 - Install generator `source_root` pointed at a doubled path; generator
   file checks now resolve against `destination_root`.
 - Port-flag injection no longer double-sets an explicit `$PORT`.

data/README.md

@@ -8,10 +8,26 @@ Zero runtime dependencies — Ruby stdlib only (`openssl`, `socket`).
 
 ```bash
 gem install ask-local
+# Interactive shortcut: `askl` is the same binary (shell-friendly alias).
+# Keep `ask-local` in logs and docs so `grep` stays useful.
+ask-local start          # setup + boot in one go (or plain `ask-local`)
+ask-local setup          # once per machine: CA trust + port 443 + hosts + verify
 cd ~/code/myapp && ask-local
 # -> https://myapp.localhost
 ```
 
+## The no-fallback promise
+
+ask-local never silently degrades to a `:<port>` URL. Clean
+`https://<app>.localhost` requires the proxy on port 443; if 443
+cannot be bound, you get a hard error pointing at `ask-local setup`
+— never a booted app on `https://app.localhost:1355` that silently
+poisons OAuth callbacks, mailer hosts, and webhooks downstream.
+
+The only port-suffixed URLs are the ones you explicitly ask for:
+`ask-local proxy start -p 1355` (CI/sandboxes where 443 is impossible).
+There the suffix is honest, and `ASK_LOCAL_URL` carries it faithfully.
+
 ## How it works
 
 1. `ask-local` infers your app name (Rails module, gemspec,
@@ -190,6 +206,19 @@ bundle install
 bundle exec rake test
 ```
 
+## Non-goals (deliberate)
+
+- **HTTP/2.** Ruby dev servers serve a handful of requests, not Vite's
+  hundreds of unbundled files — the multiplexing win doesn't apply, and
+  ALPN/HPACK/stream state would triple the proxy's auditable surface.
+- **LAN/mDNS or tunneled sharing.** mDNS behaves differently on every
+  network; third-party tunnels need CLIs, auth state, and accounts.
+  The `kamal` preview-deploy snippet covers "show this branch to
+  someone" on real infrastructure instead.
+- **Production serving.** The proxy binds loopback only, the CA is
+  self-signed, and there is no buffering or rate limiting.
+
+
 The `ask-local-apps` fixture fleet (sibling checkout) exercises
 detection, inference, and boot across Rails variants, Roda, Sinatra,
 bare Rack, Jekyll, compound Procfiles, and a monorepo. CI runs the

data/bin/askl

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ask-local"
+
+exit Ask::Local::CLI.run(ARGV)

data/lib/ask/local/cli/boot.rb

@@ -225,28 +225,51 @@ module Ask
           end
         end
 
+        # Proxy auto-start. The URL promise is absolute: clean
+        # https://<app>.localhost with no :port suffix, which requires the
+        # proxy on port 443 (or 80 for --no-tls). There is deliberately NO
+        # silent fallback to a high port here — a fallback would boot fine
+        # and hand you https://app.localhost:1355, silently corrupting every
+        # downstream consumer of ASK_LOCAL_URL (OAuth callbacks, mailers,
+        # webhooks). If 443 cannot be bound, this is a hard error pointing
+        # at `ask-local setup`.
+        #
+        # Explicit opt-in is different: `ask-local proxy start -p 1355`
+        # means you asked for a port in the URL, and ASK_LOCAL_URL carries
+        # it faithfully. That path never flows through here.
         def ensure_proxy!(ctx)
           port = ctx.proxy_port
           tls = ctx.proxy_tls
           if ProxyControl.listening?(port)
-            if ProxyControl.ours?(port, tls: tls)
-              return
-            end
+            return if ProxyControl.ours?(port, tls: tls)
 
             $stderr.puts "Error: port #{port} is in use by another process."
+            $stderr.puts "  Stop it, or point ask-local elsewhere: ASK_LOCAL_PORT=<free-port> ask-local"
+            exit 1
           end
 
           privileged = port < 1024 && !ProxyControl.root?
           if privileged && !ctx.interactive?
-            $stderr.puts "Proxy is not running and no TTY is available for sudo."
-            $stderr.puts "Start it in a terminal: ask-local proxy start"
-            $stderr.puts "Or use an unprivileged port: ask-local proxy start -p 1355"
+            $stderr.puts "Error: proxy is not running and port #{port} needs root to bind."
+            $stderr.puts "  Run this once in a terminal (it handles sudo + service + trust):"
+            $stderr.puts "    ask-local setup"
+            $stderr.puts "  Or start the proxy by hand first:"
+            $stderr.puts "    sudo ask-local proxy start"
             exit 1
           end
           puts "Starting proxy#{privileged ? " (will prompt for sudo to bind port #{port})" : ""}..."
-          ProxyControl.spawn_daemon(store: ctx.store, port: port, tls: tls, sudo: privileged)
+          begin
+            ProxyControl.spawn_daemon(store: ctx.store, port: port, tls: tls, sudo: privileged)
+          rescue Ask::Local::ProxyNotRunningError => e
+            $stderr.puts "Error: #{e.message.lines.first&.strip}"
+            $stderr.puts "  The proxy could not bind port #{port}. To fix once and for all:"
+            $stderr.puts "    ask-local setup"
+            exit 1
+          end
         rescue Errno::EACCES
-          $stderr.puts "Error: could not bind port #{port}. Try: ask-local proxy start -p 1355"
+          $stderr.puts "Error: permission denied binding port #{port}."
+          $stderr.puts "  Run this once (it handles sudo + service + trust):"
+          $stderr.puts "    ask-local setup"
           exit 1
         end
       end

data/lib/ask/local/cli/system.rb

@@ -263,6 +263,217 @@ module Ask
           end
         end
 
+        # One-shot workstation setup: everything needed for clean
+        # https://<app>.localhost URLs, in order, with a clear fix-it
+        # message on the first failure. Run this once per machine:
+        #
+        #   ask-local setup
+        #
+        # Steps: trust the local CA -> ensure the proxy serves port 443
+        # (root service when possible, sudo daemon otherwise) -> sync
+        # /etc/hosts -> verify with doctor. After this, plain `ask-local`
+        # in any app dir just works with no :port suffix, ever.
+        def setup(ctx, args)
+          if args.include?("--help") || args.include?("-h")
+            puts <<~HELP
+              Usage: ask-local setup [--no-service]
+
+              One-shot workstation setup for clean https://<app>.localhost URLs:
+
+                1. Trust the local CA (no more browser warnings)
+                2. Serve port 443 (root service at boot, or sudo daemon now)
+                3. Sync /etc/hosts (Safari + custom TLDs)
+                4. Verify everything with doctor
+
+              --no-service skips the root service and starts a sudo daemon
+              instead (no boot persistence; good for ephemeral machines).
+            HELP
+            return
+          end
+
+          step("1/4 Trusting local CA") do
+            result = Ask::Local::Trust.trust
+            unless result[:trusted]
+              abort_setup("CA trust failed: #{result[:error]}",
+                "Run `ask-local trust` manually to see the underlying error,",
+                "then re-run `ask-local setup`.")
+            end
+          end
+
+          unless args.include?("--no-service")
+            step("2/4 Installing proxy service on port 443") do
+              unless ensure_root_service(ctx)
+                abort_setup("Could not install the proxy service.",
+                  "Fallback: `ask-local setup --no-service` for a sudo daemon",
+                  "without boot persistence.")
+              end
+            end
+          else
+            step("2/4 Starting proxy sudo daemon on port 443") do
+              unless ensure_sudo_daemon(ctx)
+                abort_setup("Could not start the proxy daemon on port 443.",
+                  "Check the log, then re-run `ask-local setup`.")
+              end
+            end
+          end
+
+          step("3/4 Syncing /etc/hosts") do
+            hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
+            unless Ask::Local::Hosts.sync(hostnames)
+              abort_setup("Could not write /etc/hosts.",
+                "Run `sudo ask-local hosts sync`, then re-run `ask-local setup`.")
+            end
+          end
+
+          step("4/4 Verifying with doctor") do
+            failed = Doctor.print(Doctor.run(store: ctx.store), out: $stdout)
+            if failed.zero?
+              puts "\nSetup complete: https://<app>.localhost URLs are ready."
+              puts "Try it: cd ~/code/myapp && ask-local"
+            else
+              abort_setup("Doctor reports #{failed} failing check(s) (see above).",
+                "Fix the reported issues, then re-run `ask-local setup`.")
+            end
+          end
+        end
+
+        def step(label)
+          puts "\n==> #{label}..."
+          yield
+          puts "    ok"
+        end
+
+        def abort_setup(problem, *fixes)
+          $stderr.puts "\nSetup failed: #{problem}"
+          fixes.each { |f| $stderr.puts "  #{f}" }
+          exit 1
+        end
+
+        # Install the root service (boot-persistent). Returns true when a
+        # proxy is up on 443 afterwards, false otherwise. Never falls back
+        # to a high port silently: a :port suffix in URLs would corrupt the
+        # stable-URL promise, so failure here is a hard error with guidance.
+        def ensure_root_service(ctx)
+          service_install(ctx, [])
+          wait_for_ours(ctx, 443, tls: true)
+        rescue Error, SystemCallError => e
+          warn "    service install failed: #{e.message}"
+          false
+        end
+
+        # Sudo daemon for 443 without boot persistence (--no-service).
+        def ensure_sudo_daemon(ctx)
+          port, tls = 443, true
+          unless ctx.interactive?
+            warn "    no TTY available for the sudo prompt."
+            return false
+          end
+          ProxyControl.spawn_daemon(store: ctx.store, port: port, tls: tls, sudo: true)
+          wait_for_ours(ctx, port, tls: tls)
+        rescue Ask::Local::ProxyNotRunningError, SystemCallError => e
+          warn "    daemon start failed: #{e.message.lines.first&.strip}"
+          false
+        end
+
+        def wait_for_ours(ctx, port, tls:, timeout: 20)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          until ProxyControl.ours?(port, tls: tls)
+            return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+            sleep 0.5
+          end
+          true
+        end
+
+        # ask-local start — one-setup-and-go: idempotent workstation setup
+        # (trust, 443, hosts) when doctor fails, then boots the app in the
+        # current directory. The single command you run day-to-day; existing
+        # bare `ask-local` keeps working via BootCommand.run_inferred, and
+        # `setup` stays for explicit re-setup.
+        def start(ctx, args)
+          if args.include?("--help") || args.include?("-h")
+            puts <<~HELP
+              Usage: ask-local start [name] [cmd...] [options]
+
+              One-setup-and-go: if the workstation isn't ready (CA, proxy,
+              hosts), runs the minimal needed setup first, then boots the
+              app in the current directory.
+
+                ask-local start              # infer name, boot -> https://<app>.localhost
+                ask-local start myapp       # explicit name
+                ask-local start -- --help   # pass --help to the app, not here
+
+              Options are passed through to the boot path:
+                --name <name> --service <svc> --variant <v> --tld <tld> --branch
+
+              Setup failures become hard errors pointing at `ask-local setup`;
+              non-interactive CI without a running proxy exits immediately.
+            HELP
+            return
+          end
+
+          # Fast path: every doctor check passes => skip setup entirely.
+          # This makes `start` as fast as `ask-local` on a ready machine.
+          if needs_workstation_setup?(ctx)
+            ensure_workstation!(ctx)
+          end
+          BootCommand.run_inferred(ctx, args)
+        end
+
+        def needs_workstation_setup?(ctx)
+          Ask::Local::Doctor.run(store: ctx.store).any? { |c| !c.ok }
+        end
+
+
+        # Quiet workstation setup for `start`: trust the CA, ensure a proxy
+        # on 443 (root service, sudo daemon fallback), and sync hosts.
+        # Each step is idempotent; only missing pieces run. Non-interactive
+        # CI without a proxy fails fast rather than prompting for sudo.
+        def ensure_workstation!(ctx)
+          # 1. CA
+          unless Ask::Local::Certs.trusted?(ctx.store.dir)
+            result = Ask::Local::Trust.trust
+            unless result[:trusted]
+              abort_setup("CA trust failed: #{result[:error]}",
+                "Run `ask-local setup` in a terminal (handles trust + service),",
+                "then re-run `ask-local start`.")
+            end
+          end
+
+          # 2. Proxy on 443
+          port = 443
+          tls = true
+          unless Ask::Local::ProxyControl.listening?(port) && ProxyControl.ours?(port, tls: tls)
+            if port < 1024 && !Ask::Local::ProxyControl.root? && !ctx.interactive?
+              abort_setup("Proxy is not running and port 443 needs root to bind.",
+                "Run this once in a terminal: ask-local setup")
+            end
+            ok =
+              if ProxyControl.root?
+                Ask::Local::CLI::SystemCommand.ensure_root_service(ctx)
+              elsif ctx.interactive?
+                begin
+                  Ask::Local::ProxyControl.spawn_daemon(store: ctx.store, port: port, tls: tls, sudo: true)
+                  wait_for_ours(ctx, port, tls: tls)
+                rescue Ask::Local::ProxyNotRunningError, SystemCallError => e
+                  warn "    daemon start failed: #{e.message.lines.first&.strip}"
+                  false
+                end
+              else
+                false
+              end
+            unless ok
+              abort_setup("Proxy is not running and could not be started on port 443.",
+                "Run `ask-local setup` in a terminal (it handles trust + service + hosts),",
+                "then re-run `ask-local start`.")
+            end
+          end
+
+          # 3. Hosts (best-effort: only needed for Safari; warn, don't fail)
+          unless Hosts.sync(ctx.store.load_routes.map { |r| r["hostname"] })
+            warn "Warning: could not write /etc/hosts (try sudo ask-local hosts sync)."
+          end
+        end
         # ask-local kamal <variant> [--app myapp] [--domain preview.example.com]
         def kamal(_ctx, args)
           opts = {}
@@ -273,11 +484,13 @@ module Ask
             case a[i]
             when "--app" then opts[:app] = a.fetch(i + 1); i += 2
             when "--domain" then opts[:domain] = a.fetch(i + 1); i += 2
+            when "--tld" then opts[:tld] = a.fetch(i + 1); i += 2
             else rest << a[i]; i += 1
             end
           end
           variant = rest.first
-          raise Error, "Usage: ask-local kamal <variant> [--app myapp] [--domain preview.example.com]" unless variant
+          raise Error, "Usage: ask-local kamal <variant> [--app myapp] [--domain preview.example.com] [--tld <tld>]" unless variant
+          tld = opts[:tld] || ENV["ASK_LOCAL_TLD"]&.split(",")&.first || "localhost"
 
           app = opts[:app] || Resolver.resolve(Dir.pwd, use_branch: false).app
           domain = opts[:domain] || ENV["ASK_LOCAL_KAMAL_DOMAIN"] || "preview.example.com"
@@ -287,6 +500,7 @@ module Ask
           puts "  ssl: true"
           puts "  hosts:"
           puts "    - #{app}-#{slug}.#{domain}"
+          puts "  # Prefer Kamal multi-host for production; single-host preview above is fine for ephemeral branches."
         end
       end
     end

data/lib/ask/local/cli.rb

@@ -11,7 +11,7 @@ module Ask
     # In non-interactive environments (no TTY or CI=1) we fail early with
     # a clear message instead of prompting (portless lesson).
     class CLI
-      SUBCOMMANDS = %w[run get alias hosts list doctor trust clean prune proxy service kamal stop restart log status open].freeze
+      SUBCOMMANDS = %w[run get alias hosts list doctor trust clean prune proxy service kamal stop restart log status open setup start].freeze
 
       def self.run(argv)
         new.run(argv)
@@ -44,6 +44,8 @@ module Ask
         when "prune" then RoutesCommand.prune(ctx, args)
         when "proxy" then SystemCommand.proxy(ctx, args)
         when "service" then SystemCommand.service(ctx, args)
+        when "setup" then SystemCommand.setup(ctx, args)
+        when "start" then SystemCommand.start(ctx, args)
         when "kamal" then SystemCommand.kamal(ctx, args)
         when "stop"
           exit RoutesCommand.stop(ctx, args)
@@ -64,7 +66,9 @@ module Ask
           ask-local - Stable named .localhost URLs for Ruby development.
 
           Usage:
-            ask-local                        Infer name, boot app -> https://<app>.localhost
+            ask-local start [name] [cmd...]  One-setup-and-go: setup if needed, then boot -> https://<app>.localhost
+            ask-local setup                One-shot workstation setup without booting (run once)
+            ask-local                        Bare form of `start` -> https://<app>.localhost
             ask-local run [cmd]              Same, with explicit command
             ask-local <name> <cmd>           Run with explicit name
             ask-local get <name>             Print URL for a service

data/lib/ask/local/proxy_control.rb

@@ -64,30 +64,51 @@ module Ask
       # where only one family answers the check must still succeed.
       # An explicit regression test pins this (health_test pinning
       # ensure_proxy's "is that ours" logic against future proxy changes).
+      #
+      # Probe order matters: plain HTTP first (our proxy byte-peeks and
+      # answers plain HTTP even on the TLS port), TLS second. A TLS-first
+      # handshake against a foreign plain-HTTP server blocks in connect
+      # waiting for a ServerHello that never comes — and connect used to
+      # sit outside the timeout, hanging ensure_proxy for over a minute.
+      #
+      # Speed: if the plain probe gets ANY HTTP response without our
+      # header, the server is definitively foreign — no TLS retry. The
+      # slow TLS retry only happens when plain yielded zero bytes
+      # (connection error, EOF, or timeout against a silent server).
       def ours?(port, tls:)
-        probe_ours(port, tls: tls, host: "127.0.0.1") ||
-          probe_ours(port, tls: tls, host: "::1")
+        ["127.0.0.1", "::1"].any? do |host|
+          case probe_once(port, tls: false, host: host)
+          when :ours then true
+          when :foreign then false
+          else tls ? probe_once(port, tls: true, host: host) == :ours : false
+          end
+        end
       end
 
-      def probe_ours(port, tls:, host:)
-        sock = TCPSocket.new(host, port)
-        if tls
-          ctx = OpenSSL::SSL::SSLContext.new
-          ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE
-          sock = OpenSSL::SSL::SSLSocket.new(sock, ctx)
-          sock.connect
-        end
-        Timeout.timeout(3) do
+      # Three outcomes: :ours (our header present), :foreign (an HTTP
+      # response without it), :unknown (no response at all).
+      def probe_once(port, tls:, host:)
+        sock = nil
+        Timeout.timeout(5) do
+          sock = TCPSocket.new(host, port)
+          if tls
+            ctx = OpenSSL::SSL::SSLContext.new
+            ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE
+            sock = OpenSSL::SSL::SSLSocket.new(sock, ctx)
+            sock.connect
+          end
           sock.write("GET / HTTP/1.1\r\nHost: ask-local-health.invalid\r\nConnection: close\r\n\r\n")
           head = +""
           while (chunk = sock.readpartial(4096))
             head << chunk
             break if head.include?("\r\n\r\n")
           end
-          head.downcase.include?("x-ask-local: 1")
+          return :unknown if head.empty?
+
+          return head.downcase.include?("x-ask-local: 1") ? :ours : :foreign
         end
       rescue SystemCallError, OpenSSL::SSL::SSLError, Timeout::Error, IOError, EOFError
-        false
+        :unknown
       ensure
         begin
           sock&.close
@@ -96,6 +117,10 @@ module Ask
         end
       end
 
+      def probe_ours(port, tls:, host:)
+        probe_once(port, tls: tls, host: host) == :ours
+      end
+
       def pid_alive?(pid)
         Process.kill(0, pid)
         true

data/lib/ask/local/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Local
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/lib/ask/skills/ask-local/SKILL.md

@@ -7,6 +7,14 @@ description: Run Ruby apps through ask-local for stable named .localhost URLs (e
 
 Never invent ports. Never parse them from logs. Every app has a stable URL.
 
+First time on a machine, run `ask-local start` in any app dir — it does
+the one-shot CA trust, port 443, and hosts sync if anything is missing,
+then boots. Prefer `ask-local setup` for
+workstation setup without booting. Every later `ask-local` or
+hosts, verify). If any command fails with a privileged-port error, do
+not work around it with `-p` — run `ask-local setup` instead. A `:port`
+suffix in a URL means someone explicitly opted into it.
+
 ## Booting apps
 
 ```bash

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-local
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -73,6 +73,7 @@ email:
 - kaka@myrrlabs.com
 executables:
 - ask-local
+- askl
 extensions: []
 extra_rdoc_files: []
 files:
@@ -80,6 +81,7 @@ files:
 - LICENSE
 - README.md
 - bin/ask-local
+- bin/askl
 - lib/ask-local.rb
 - lib/ask/local/certs.rb
 - lib/ask/local/cli.rb