ask-local 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b2c1d943d3bbfb315651a8bd50deb3519f325822e894f1c4040d30b7523cb46
-  data.tar.gz: 9ad93192b70b62cae5292b5a1784bd9086e4103dba7d4f2a07aa83b7327bf795
+  metadata.gz: 7cab052002c8e0c03a4ed39fd2ff9b4d43474b6e2b969cd5ba0a5e5122c0229b
+  data.tar.gz: 600b5127b34523e88d1fe8a08434309fd7690ab33217f7eb33fbf18b4d3f851b
 SHA512:
-  metadata.gz: 74920fa209896d3a66f67245c6757f45f9c23793147dabfdf7e1f088f0c6af9fcb41442f44dcd1657816617aa88eaa318a5c57fde6035dc767704812bef7f0ff
-  data.tar.gz: c65585ddefac14be0b4898f3e5af9b96f370826bb11b43bc2f2ace9ce3dd350b1f8ba6b0a6b6bd45f2f43eecf1a34f4831bb1fff439087b01ce6ef1da379d169
+  metadata.gz: 8451f072fa059698ec390057df2cc0945da03cb5bab03ef4e29cd0f93f437eba827df542814538d84464b1cb805e297d8ee104b36063c5a34ca761003a760922
+  data.tar.gz: 9442146768560787bea3d9e1b024bdcd292db6af7a0611e029e6398c9863fb46589e58c7ca0e05950a71f0787e90df075f2c1c18984e9671638cd0348239e7c1

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,18 +8,54 @@ 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
 ```
 
-## How it works
+## 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.
+
+## The one-file model
+
+Every app declares `config/local.yml` (Kamal-style) — the single source
+of truth for service name, proxy TLD/host, processes, and env:
+
+```yaml
+service: myapp
+proxy:
+  tld: localhost
+processes:
+  web:
+    cmd: bundle exec puma -b tcp://127.0.0.1:$PORT config.ru
+    proxy: true
+  worker:
+    cmd: bundle exec sidekiq
+    proxy: false
+```
+
+`ask-local init` creates the file (migrating an existing Procfile);
+Rails apps need no extra gem — ask-local injects `RAILS_DEVELOPMENT_HOSTS`
+so the proxied hostname is allowed automatically. `ask-local`
+then boots every process, assigns each a `$PORT`, injects
+`ASK_LOCAL_URL`, registers routes for HTTP processes, supervises the
+whole tree, and cleans up when one exits.
 
-1. `ask-local` infers your app name (Rails module, gemspec,
-   `package.json`, git root, or directory) and boots it — managed Rack
-   apps on a unix socket (zero TCP ports), anything else via `PORT`.
-2. Registers `hostname -> backend -> pid` in `~/.ask-local/routes.json`.
-3. The reverse proxy (HTTPS on 443, per-host certs from a local CA)
-   routes by `Host` header to your app.
+Variants are file overlays: `config/local.<variant>.yml` deep-merges on
+top of `config/local.yml`, selected by `ASK_LOCAL_VARIANT` (Kamal's
+destination pattern).
 
 `.localhost` resolves to loopback natively in Chrome, Firefox, and Edge —
 no DNS server, no `/etc/resolver`. Safari may need `ask-local hosts sync`.
@@ -94,7 +130,7 @@ Procfile lines that are compound (`&&`, `||`, `|`, `;`) are refused with
 guidance rather than silently mis-injected.
 
 For Rails integration (hosts, Action Cable origins, Procfile rewrite,
-generators), see `ask-local-rails`.
+generators) — deprecated; core covers Rails now.
 
 ## WebSockets
 
@@ -133,7 +169,7 @@ Run-mode (TCP) routes and static aliases are never supervised.
 
 | Gem | How ask-local helps |
 |---|---|
-| `ask-rails` | `ask_local:install` equivalent wiring: `config.hosts` patterns, `allowed_request_origins` for Cable, mailer/OmniAuth hosts from `ASK_LOCAL_URL` |
+| `ask-rails` | ask-local core injects `RAILS_DEVELOPMENT_HOSTS`; Cable origins + helpers live in the deprecated ask-local-rails |
 | `ask-rails-harness` | Its 9 Rails tools (routes, models, DB, logs) run against the app the proxy serves; `DevUrl` gives the agent the stable URL instead of a guessed port |
 | `ask-app-server` | The JSON-RPC/stdio session host sits behind `https://api.<app>.localhost`; editor/IDE clients use `ask-local get` output |
 | `ask-mcp` | MCP servers get named URLs per service (`mcp.<app>.localhost`), no port coordination across servers |
@@ -190,6 +226,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

@@ -3,109 +3,143 @@
 module Ask
   module Local
     class CLI
-      # Boot commands: bare `ask-local`, `run`, and `<name> <cmd>`.
-      # Owns managed/run boot orchestration, Procfile resolution, and the
-      # foreground supervision loop.
+      # Boot commands: `ask-local`, `ask-local start`, `ask-local run`.
+      # The config file is mandatory — missing file prints the fix and exits.
+      # `boot_all` fans out over every process declared in config/local.yml.
+      # No inference, no Procfile at boot, no single-process default.
       module BootCommand
-        # Frameworks that ignore $PORT get explicit flags (portless lesson:
-        # Vite/Astro/Expo need --port; Jekyll/Middleman/Bridgetown do too).
-        # Only injects when the user hasn't already set a port.
         PORT_IGNORING = %w[jekyll middleman bridgetown].freeze
 
         module_function
 
+        # Bare `ask-local` / `ask-local start` / `ask-local run`.
+        # Reads config/local.yml via the resolver, ensures the proxy,
+        # boots every process, supervises the tree, cleans up on exit.
         def run_inferred(ctx, args)
-          opts = ctx.parse_flags(args, %i[name service variant tld branch proc force])
-          resolved = Resolver.resolve(Dir.pwd, name: opts[:name],
-            service: opts[:service], variant: opts[:variant],
-            tlds: opts[:tld], use_branch: opts[:branch])
-          hostnames = Resolver.hostnames(resolved)
+          variant = ENV["ASK_LOCAL_VARIANT"]
+          opts = ctx.parse_flags(args, %i[variant tld force])
+          resolved = resolve!(ctx, variant: opts[:variant] || variant, tld: opts[:tld])
           ensure_proxy!(ctx)
-          framework = Framework.detect(Dir.pwd)
-          runner = Runner.new(store: ctx.store)
-          if Framework.managed?(framework) && opts[:rest].empty?
-            boot_managed(ctx, runner, resolved, hostnames, opts)
-          else
-            command = opts[:rest].empty? ? default_command(framework, opts[:proc]) : opts[:rest]
-            boot_run(ctx, runner, resolved, hostnames, command, opts)
-          end
+          boot_all(ctx, resolved, opts)
         end
 
         def run_explicit(ctx, args)
-          opts = ctx.parse_flags(args, %i[name service variant tld branch proc force])
-          resolved = Resolver.resolve(Dir.pwd, name: opts[:name],
-            service: opts[:service], variant: opts[:variant],
-            tlds: opts[:tld], use_branch: opts[:branch])
-          hostnames = Resolver.hostnames(resolved)
-          ensure_proxy!(ctx)
-          framework = Framework.detect(Dir.pwd)
-          command = opts[:rest].empty? ? default_command(framework, opts[:proc]) : opts[:rest]
-          boot_run(ctx, Runner.new(store: ctx.store), resolved, hostnames, command, opts)
+          run_inferred(ctx, args)
         end
 
-        def run_named(ctx, name, args)
-          opts = ctx.parse_flags(args, %i[force app_port])
-          resolved = Resolver.resolve(Dir.pwd, name: name)
-          hostnames = Resolver.hostnames(resolved)
-          ensure_proxy!(ctx)
-          if opts[:rest].empty?
-            $stderr.puts "Error: no command given for #{name}."
+        def run_named(ctx, name, _args)
+          $stderr.puts "Error: `ask-local #{name}` is no longer supported."
+          $stderr.puts "  All processes come from config/local.yml. Run `ask-local init` to create one."
+          exit 1
+        end
+
+        # Core boot loop: iterate processes from config/local.yml,
+        # classify HTTP vs background, spawn each, register routes for
+        # HTTP processes, then supervise the tree.
+        def boot_all(ctx, resolved, opts)
+          service = resolved.app
+          tld = resolved.tld
+          host = resolved.host
+          processes = resolved.processes
+
+          if processes.empty?
+            $stderr.puts "Error: no processes in config/local.yml. Add at least one."
             exit 1
           end
-          boot_run(ctx, Runner.new(store: ctx.store), resolved, hostnames, opts[:rest], opts)
-        end
 
-        def boot_managed(ctx, runner, resolved, hostnames, opts)
-          primary = hostnames.first
-          url = Hostname.url(primary, port: ctx.proxy_port, tls: ctx.proxy_tls)
-          puts "ask-local"
-          puts "-- #{hostnames.join(", ")}"
-          app = runner.boot_managed(name: resolved.app, hostname: primary,
-            url: url, dir: Dir.pwd, force: opts[:force])
-          register_all(ctx, hostnames, app, force: opts[:force], spec: { "dir" => File.expand_path(Dir.pwd) })
-          puts "\n  -> #{url}\n"
-          ctx.report_unresolved(hostnames)
-          trap_cleanup(ctx, hostnames)
-          supervise_backend(ctx, hostnames, app)
-        end
+          primary = Resolver.primary_proc(resolved)
+          if primary.nil?
+            $stderr.puts "Error: no HTTP process (proxy: true) found in config/local.yml."
+            exit 1
+          end
+
+          runner = Runner.new(store: ctx.store)
+          children = []
+          routes_registered = []
 
-        def boot_run(ctx, runner, resolved, hostnames, command, opts)
-          primary = hostnames.first
-          url = Hostname.url(primary, port: ctx.proxy_port, tls: ctx.proxy_tls)
-          puts "ask-local"
-          puts "-- #{hostnames.join(", ")}"
-          port = opts[:app_port] || Ports.find_free
-          command = inject_port_flags(command, port)
-          app = runner.boot_run(name: resolved.app, hostname: primary, url: url,
-            dir: Dir.pwd, command: command, port: port, force: opts[:force])
-          register_all(ctx, hostnames, app, force: opts[:force])
-          puts "\n  -> #{url}\n"
-          puts "Running: PORT=#{app.target.split(":").last} ASK_LOCAL_URL=#{url} #{command.join(" ")}"
-          ctx.report_unresolved(hostnames)
-          trap_cleanup(ctx, hostnames)
-          supervise_backend(ctx, hostnames, app)
+          puts "ask-local (#{service})"
+          puts "--"
+
+          processes.each do |proc_name, entry|
+            next if entry["proxy"] == false
+
+            hostname = Resolver.hostname_for(resolved, proc_name)
+            next unless hostname
+
+            url = Hostname.url(hostname, port: ctx.proxy_port, tls: ctx.proxy_tls)
+            hostnames = [hostname]
+            puts "  [#{proc_name}] #{url}"
+
+            # Each process cmd runs through the shell so $PORT (and other
+            # env refs) expand — same trust boundary as a Procfile line
+            # (repo code, not user input). Compound lines are refused.
+            cmd = entry["cmd"].to_s
+            if cmd.match?(Ask::Local::Procfile::COMPOUND)
+              $stderr.puts "  [#{proc_name}] ERROR: compound line (&&, ||, |, ;) — run explicitly: ask-local run -- #{cmd}"
+              next
+            end
+
+            port = opts[:app_port] || Ports.find_free
+            shell_cmd = ["sh", "-c", cmd]
+            # Always allow the proxied hostname in Rails dev (Rails ignores
+            # this env var when not a Rails app — safe for every framework).
+            app = runner.boot_run(name: proc_name, hostname: hostname, url: url,
+              dir: Dir.pwd, command: shell_cmd, port: port, force: opts[:force],
+              rails_dev_host: hostname)
+            register_all(ctx, hostnames, app, force: opts[:force],
+              spec: { "dir" => File.expand_path(Dir.pwd), "proc" => proc_name })
+            routes_registered << { hostnames: hostnames, app: app }
+
+            puts "  -> #{url}"
+          end
+
+          background = processes.select { |_, v| v["proxy"] == false }
+          unless background.empty?
+            puts "  [background] #{background.keys.join(', ')}"
+          end
+
+          puts
+          ctx.report_unresolved(routes_registered.flat_map { |r| r[:hostnames] })
+
+          # Supervisor: exit when ANY child dies (loud cleanup).
+          all_pids = routes_registered.map { |r| r[:app].pid }
+          trap_cleanup(ctx, routes_registered.flat_map { |r| r[:hostnames] }, all_pids)
+          supervise_tree(ctx, routes_registered.flat_map { |r| r[:hostnames] }, all_pids)
+        end
+
+        def build_env(ctx, resolved, entry)
+          env = {}
+          # Merge config env.clear
+          config_env = resolved.secrets || {}
+          entry_env = entry["env"] || {}
+          (entry_env["clear"] || {}).each { |k, v| env[k] = v }
+          # Merge secrets from config/local.secrets
+          secret_keys = entry_env["secret"] || []
+          secret_keys.each do |k|
+            env[k] = config_env[k] if config_env.key?(k)
+          end
+          # Host env (dotenv from .env) already in ENV
+          env
         end
 
-        # Foreground loop: exit (cleaning up) when the backend dies, so a
-        # crashed app never leaves a stale route behind. Backends are
-        # spawned detached (so Ctrl+C in the CLI never SIGINTs the app),
-        # which rules out Process.wait — detached children are already
-        # reaped. Poll liveness at 2Hz: prompt enough for crash cleanup
-        # without spinning.
-        def supervise_backend(ctx, hostnames, app)
-          until !ProxyControl.pid_alive?(app.pid)
+        def supervise_tree(ctx, hostnames, pids)
+          loop do
             sleep 0.5
+            if pids.any? { |pid| !ProxyControl.pid_alive?(pid) }
+              puts "\nA process exited — cleaning up all routes."
+              cleanup_routes(ctx, hostnames)
+              # Kill remaining children
+              pids.each do |pid|
+                Process.kill("TERM", pid) rescue nil
+              end
+              exit 0
+            end
           end
-          puts "\nBackend exited — cleaning up."
-          cleanup_routes(ctx, hostnames)
-          exit 0
         end
 
         def inject_port_flags(command, port)
           return command if command.empty?
           return command if command.any? { |a| a.match?(/\A(-p|--port)(=|\z)/) }
-          # A literal $PORT already present (e.g. Procfile `web: x --port $PORT`,
-          # foreman --port passthrough): injecting again would double-set it.
           return command if command.any? { |a| a.include?("$PORT") }
 
           bin = File.basename(command.first.to_s)
@@ -113,85 +147,33 @@ module Ask
             (command.length > 2 && PORT_IGNORING.include?(File.basename(command[2].to_s)))
           return command unless needs_flags
 
-          flags = ["--port", port.to_s, "--host", "127.0.0.1"]
-          flags.concat(jekyll_livereload_flags(port)) if jekyll_command?(command)
-          command + flags
-        end
-
-        # Jekyll's livereload runs its own server on a second port
-        # (default 35729) serving the livereload.js WebSocket. It cannot go
-        # through the proxy (one route = one backend), so pin it next to the
-        # main port and document the direct URL. Only when the app enables
-        # livereload in _config.yml; explicit user flags always win.
-        JEKYLL_LIVERELOAD_DEFAULT_PORT = 35_729
-
-        def jekyll_command?(command)
-          command.any? { |a| File.basename(a.to_s) == "jekyll" }
-        end
-
-        def jekyll_livereload_flags(port)
-          return [] unless File.file?("_config.yml")
-          return [] unless File.read("_config.yml").match?(/^\s*livereload:\s*true/i)
-          return [] if port + 1 > Ports::MAX_PORT
-
-          ["--livereload-port", (port + 1).to_s]
-        rescue SystemCallError
-          []
-        end
-
-        def default_command(framework, proc_name = nil)
-          case framework
-          when :procfile
-            procfile_command(proc_name) || raise(Error,
-              proc_name ? "Procfile has no '#{proc_name}' process, or its line is " \
-                "compound (&&, ||, |, ;) — ask-local cannot inject PORT safely. " \
-                "Run explicitly instead: ask-local run -- <command>" :
-                "Procfile.dev first line is compound (&&, ||, |, ;) or unreadable — " \
-                "ask-local cannot inject PORT safely. Run explicitly instead: " \
-                "ask-local run -- <command>")
-          when :jekyll then %w[bundle exec jekyll serve]
-          when :bridgetown then %w[bin/bridgetown start]
-          when :middleman then %w[bundle exec middleman server]
-          else raise(Error, "No command given and no bootable app detected. Usage: ask-local run -- <command>")
-          end
+          command + ["--port", port.to_s, "--host", "127.0.0.1"]
         end
 
-        # First process by default; --proc <name> picks a specific line
-        # (the overmind `-P web` convention teams already use).
-        #
-        # Trust boundary: the Procfile line is repo code, so `sh -c` is
-        # safe here the way it would not be for user-supplied input.
+        # Legacy procfile parsing for backwards compat.
         def procfile_command(process = nil)
-          path = File.file?("Procfile.dev") ? "Procfile.dev" : "Procfile"
-          lines = File.readlines(path).map(&:strip).reject { |l| l.empty? || l.start_with?("#") }
-          chosen =
-            if process
-              lines.find { |l| l.start_with?("#{process}:") }
-            else
-              lines.first
-            end
-          return nil unless chosen
-
-          cmd = chosen.split(":", 2).last.to_s.strip
-          # Refuse compound lines we cannot safely inject PORT into.
-          return nil if cmd.match?(/&&|\|\||[|;]/)
-
-          ["sh", "-c", cmd]
-        end
-
-        def trap_cleanup(ctx, hostnames)
+          path = ::Ask::Local::Procfile.find_file(Dir.pwd)
+          return nil unless path
+          lines = ::Ask::Local::Procfile.parse_file(path)
+          line = if process
+                   lines.find { |l| l.name == process }
+                 else
+                   lines.first
+                 end
+          return nil unless line
+          line.compound ? nil : ["sh", "-c", line.command]
+        end
+
+        def trap_cleanup(ctx, hostnames, pids = [])
           %w[INT TERM].each do |sig|
             trap(sig) do
               cleanup_routes(ctx, hostnames)
+              pids.each { |pid| Process.kill("TERM", pid) rescue nil }
               exit 0
             end
           end
         end
 
-        # Primary hostname is registered by the runner; secondaries (extra
-        # TLDs) share the same backend. Every hostname gets a backend sidecar
-        # so `ask-local stop` finds the process from any of them, and the
-        # daemon supervisor needs the spec on every hostname.
         def register_all(ctx, hostnames, app, force:, spec: nil)
           hostnames[1..].each do |h|
             ctx.store.add_route(h, app.target, Process.pid, kind: app.kind,
@@ -207,8 +189,6 @@ module Ask
           nil
         end
 
-        # Foreground boot semantics (portless model): leaving = routes gone
-        # AND backend stopped. No orphans on Ctrl+C, TERM, or clean exit.
         def cleanup_routes(ctx, hostnames)
           hostnames.each do |h|
             begin
@@ -225,28 +205,39 @@ module Ask
           end
         end
 
+        def resolve!(ctx, variant: nil, tld: nil)
+          # The resolver calls Config.load, which raises ConfigError if
+          # config/local.yml is missing — exactly what we want.
+          Ask::Local::Resolver.resolve(Dir.pwd, variant: variant, tld: tld)
+        end
+
         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 ask-local proxy start -p <port>"
+            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."
+            $stderr.puts "  Run this once: ask-local setup"
+            $stderr.puts "  Or start the proxy by hand: sudo ask-local proxy start"
+            exit 1
+          end
+          puts "Starting proxy#{privileged ? " (sudo)" : ""}..."
+          begin
+            Ask::Local::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 "  Fix once: ask-local setup"
             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)
         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 "  Fix once: ask-local setup"
           exit 1
         end
       end