ask-local 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cab052002c8e0c03a4ed39fd2ff9b4d43474b6e2b969cd5ba0a5e5122c0229b
-  data.tar.gz: 600b5127b34523e88d1fe8a08434309fd7690ab33217f7eb33fbf18b4d3f851b
+  metadata.gz: 4407cbb75f7a6a5347fd2b71963a4229dc925c7d36438ae885c25c04759c94a6
+  data.tar.gz: 3ac24692630768264da89e9ce37e75403cbb3e2686ce1c18d6b1a99483d9c85d
 SHA512:
-  metadata.gz: 8451f072fa059698ec390057df2cc0945da03cb5bab03ef4e29cd0f93f437eba827df542814538d84464b1cb805e297d8ee104b36063c5a34ca761003a760922
-  data.tar.gz: 9442146768560787bea3d9e1b024bdcd292db6af7a0611e029e6398c9863fb46589e58c7ca0e05950a71f0787e90df075f2c1c18984e9671638cd0348239e7c1
+  metadata.gz: '0419a2e0b1b62733f3687fffc1eafee535380aaa636a04d77814fc229b92521369fefe7b394f73533686b85a4c5975bc6e3837d985b3a387efff9b43dcd4f6d9'
+  data.tar.gz: b88ce440466e46a9c47af5a6ac4072d4ffc4ef774b17c4e07e531c4f9698b284edd364ec09d3467d05caa31eebadcd29a93796d7f01e400df4ea97787670a306

data/CHANGELOG.md

@@ -1,69 +1,77 @@
 # Changelog
 
-## [0.1.1] — 2026-09-06
+## [0.2.1] — 2026-09-08
 
-Patch release focused on workstation setup, URL correctness, and proxy reliability.
+Patch release focused on making `ask-local setup` dependable end-to-end:
+it now installs the 443 service and *finishes* (hosts + doctor), works
+passwordless for agents, survives first-run edge cases, and shows what it
+is doing while it works.
 
-### Added — `ask-local setup` & `ask-local start`
+### Fixed
 
-- `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.
+- **`setup` no longer stops after installing the service.** The elevated
+  install used to `exit` mid-flow, so `/etc/hosts` was never synced and
+  `doctor` never ran despite the "setup complete" promise. Install and
+  uninstall now return booleans and the CLI owns the exit codes, so
+  `setup` always reaches the hosts and doctor steps. (`service uninstall`
+  also crashed outright — it called its handler without the required
+  context argument.)
+- **A stale user-owned plist is healed on install.** `File.write` keeps
+  an existing file's owner, so a leftover plist from an older version
+  stayed user-owned and launchd refused it forever with "Bootstrap
+  failed: 5". Install now chowns the plist to root explicitly (launchd
+  and systemd).
+- **The TLS proxy survives plaintext probes.** The health probe sends
+  plain HTTP before TLS; an unhandled `SSL_accept` error used to kill
+  the acceptor thread, and with both acceptors gone the daemon exited
+  before the readiness probe ever succeeded. A plaintext connection is
+  now just one dropped connection.
+- `clean` referenced the CA common name unqualified (NameError) — fixed.
+- `setup --no-service` printed a duplicate "2/3" step — numbered 1/4–4/4.
 
-### Added — DNS-rebinding & log hygiene
+### Added
 
-- 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.
+- `ask-local sudoers` — prints the scoped NOPASSWD rules so agents and
+  CI can install and run the 443 service without a TTY. Non-interactive
+  elevation uses `sudo -n` (never prompts) and points at the grant when
+  it is missing; interactive failures just say re-run.
+- The root install syncs `/etc/hosts` under elevation, so Safari works
+  the moment setup finishes. `setup`'s hosts step verifies the block is
+  already present instead of failing unprivileged on re-runs, and
+  `ask-local hosts sync` re-runs itself elevated when the direct write
+  needs root.
+- The CA is trusted into the System keychain silently while elevated
+  (all users, no GUI popup); unprivileged trust keeps the login
+  keychain.
+- Progress UX: the root half of the install prints stage lines as it
+  works, and the proxy-start wait shows a rotating spinner on a terminal
+  (dots elsewhere), resolving to a clean "proxy is up" line.
 
-### Fixed
+### Changed
 
-- **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.
+- launchctl uses the modern system-domain verbs
+  (`bootstrap`/`bootout`/`enable`/`kickstart` — the puma-dev/portless
+  pattern); the legacy `load`/`unload` are rejected by current macOS.
+  The best-effort pre-install bootout is silenced — its "Boot-out
+  failed: 5" noise on a first install looked like a failure.
+- Every privileged execution path (sudo re-exec, launchctl, systemctl,
+  `security`) flows through one injectable `Command` seam, so the test
+  suite never shells out to real privileged commands.
 
-### Tests — new coverage for this patch
+### Tests
 
-- `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.
+- Hermetic and CI-safe suite: no real sudo/security/launchctl in tests;
+  exact-argument expectations on the `Command` seam, source-pinned
+  regressions for the launchctl verbs, root-owned plist and stage
+  progress.
+- New coverage: setup runs the real elevation path to "Setup complete"
+  (regression for the mid-flow exit), hosts-step write/verify/skip
+  behavior, `Hosts.synced?`, terminal spinner vs. off-tty dots, e2e
+  proof that a TLS daemon survives the plaintext probe, and both
+  elevation-failure hint paths. 182 unit + 23 e2e, all green.
 
-## [0.2.0] — Unreleased
+
+## [0.2.0] — 2026-09-07
 
 ### Changed
 
@@ -129,6 +137,71 @@ Patch release focused on workstation setup, URL correctness, and proxy reliabili
   file checks now resolve against `destination_root`.
 - Port-flag injection no longer double-sets an explicit `$PORT`.
 
+
+## [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.1.0]
 
 ### Added

data/README.md

@@ -28,6 +28,38 @@ 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.
 
+## Port 443: one-time setup, then never again
+
+Binding 443 is privileged, so ask-local installs a **root-owned launchd
+service** (macOS) or systemd unit (Linux) that binds 443 at boot — the
+same model as puma-dev and portless. Installing it needs sudo **once per
+machine**; after that, every `ask-local` run in any project gets a clean
+`https://<app>.localhost` with no elevation and no prompt.
+
+**Human (interactive):** run setup once — it trusts the CA, installs the
+service, syncs hosts, and verifies:
+
+```bash
+ask-local setup
+```
+
+**Agent / CI (no TTY):** the same commands fail fast with guidance,
+because sudo needs a terminal. To pre-provision a machine or image so
+agents can install the service without a prompt, install the scoped
+passwordless-sudo rules once (as an admin):
+
+```bash
+ask-local sudoers > /tmp/ask-local.sudoers
+sudo install -o root -g wheel -m 440 /tmp/ask-local.sudoers /etc/sudoers.d/ask-local   # macOS
+sudo install -o root -g root -m 440 /tmp/ask-local.sudoers /etc/sudoers.d/ask-local   # Linux
+```
+
+`ask-local sudoers` prints rules scoped to ask-local's own service
+re-exec — the gem's exact ruby + bin path with the `service install
+--internal` / `service uninstall --internal` subcommands — never a bare
+interpreter. Re-run it after upgrading the gem if the install path
+changes. To undo: `sudo rm /etc/sudoers.d/ask-local`.
+
 ## The one-file model
 
 Every app declares `config/local.yml` (Kamal-style) — the single source

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

@@ -223,7 +223,10 @@ module Ask
           privileged = port < 1024 && !ProxyControl.root?
           if privileged && !ctx.interactive?
             $stderr.puts "Error: proxy is not running and port #{port} needs root."
-            $stderr.puts "  Run this once: ask-local setup"
+            $stderr.puts "  Human: run this once — ask-local setup"
+            $stderr.puts "  Agent/CI: pre-provision passwordless sudo once —"
+            $stderr.puts "    ask-local sudoers > /tmp/ask-local.sudoers"
+            $stderr.puts "    sudo install -o root -g wheel -m 440 /tmp/ask-local.sudoers /etc/sudoers.d/ask-local"
             $stderr.puts "  Or start the proxy by hand: sudo ask-local proxy start"
             exit 1
           end

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

@@ -41,6 +41,15 @@ module Ask
             hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
             if Hosts.sync(hostnames)
               puts "Synced #{hostnames.length} hostname(s) to /etc/hosts."
+            elsif !ProxyControl.root? && !hostnames.empty?
+              # /etc/hosts is root-owned; once the root service is
+              # installed the guidance is "run ask-local hosts sync" — so
+              # make that command work by re-running it elevated.
+              puts "Writing /etc/hosts needs root — re-running elevated..."
+              state = Certs.state_dir
+              cmd = ["env", "ASK_LOCAL_STATE_DIR=#{state}", RbConfig.ruby,
+                ProxyControl.bin_path, "hosts", "sync"]
+              exit(elevate(cmd) ? 0 : 1)
             else
               $stderr.puts "Could not write /etc/hosts (try sudo)."
               exit 1
@@ -136,31 +145,111 @@ module Ask
         def service(ctx, args)
           sub = args.first
           case sub
-          when "install" then service_install(ctx, args)
-          when "uninstall" then service_uninstall
+          when "install" then exit(service_install(ctx, args) ? 0 : 1)
+          when "uninstall" then exit(service_uninstall(ctx) ? 0 : 1)
           when "status" then service_status(ctx)
           else raise Error, "Usage: ask-local service [install|uninstall|status]"
           end
         end
 
+        # Print the scoped passwordless-sudo rules that let `service install`
+        # (and only it) run without a prompt. The service re-execs the whole
+        # gem under sudo, so the safe NOPASSWD grants exactly the gem path +
+        # subcommand for the current user — never a bare interpreter. This is
+        # how agents and repeat machines get clean :443 without a TTY.
+        #
+        #   macOS: sudo install -o root -g wheel -m 440 <(ask-local sudoers) /etc/sudoers.d/ask-local
+        #   Linux: sudo install -o root -g root -m 440 <(ask-local sudoers) /etc/sudoers.d/ask-local
+        def sudoers(_ctx, _args)
+          require "etc"
+          ruby = RbConfig.ruby
+          bin = ProxyControl.bin_path
+          user = ENV.fetch("USER", Etc.getlogin)
+          puts <<~SUDOERS
+            # ask-local: let #{user} install/run the privileged proxy on port 443
+            # without a password prompt. Scoped to ask-local's own service
+            # re-exec — the gem path above, not a bare interpreter.
+            #{user} ALL=(root) NOPASSWD: #{ruby} #{bin} service install --internal
+            #{user} ALL=(root) NOPASSWD: #{ruby} #{bin} service uninstall --internal
+          SUDOERS
+        end
+
         # Root-owned LaunchDaemon binding 80/443 at boot (puma-dev model).
-        # Re-execs under sudo; the proxy runs with the invoking user's state
-        # dir so routes registered by unprivileged CLIs are shared
-        # (portless pattern). A root proxy can also write /etc/hosts.
+        # Non-root runs re-exec under sudo once (--internal marks the root
+        # half); the proxy runs with the invoking user's state dir so
+        # routes registered by unprivileged CLIs are shared. The root half
+        # can also write /etc/hosts.
+        #
+        # Non-interactive runs (agents, CI) use `sudo -n`: never prompts,
+        # succeeds only when the scoped NOPASSWD grant from `ask-local
+        # sudoers` is installed, and fails fast with guidance otherwise.
+        # Interactive runs use plain sudo (one password, then the service
+        # is installed for good).
+        #
+        # Returns true when the service is installed. No exit here: the
+        # bare `service install` CLI exits in `service`, while `setup`
+        # keeps going (hosts sync, doctor) after a successful install.
         def service_install(ctx, args)
-          if !ProxyControl.root? && !args.include?("--internal")
+          if ProxyControl.root?
+            install_service!(ctx)
+          elsif args.include?("--internal")
+            raise Error, "`service install --internal` is the root half of the sudo re-exec — run `ask-local service install`"
+          else
             puts "Installing system service (sudo required)..."
             state = Certs.state_dir
-            ok = system("sudo", "env", "ASK_LOCAL_STATE_DIR=#{state}",
+            cmd = ["env", "ASK_LOCAL_STATE_DIR=#{state}",
               RbConfig.ruby, ProxyControl.bin_path,
-              "service", "install", "--internal")
-            exit(ok ? 0 : 1)
+              "service", "install", "--internal"]
+            elevate(cmd)
           end
+        end
+
+        def install_service!(ctx)
           case RUBY_PLATFORM
           when /darwin/ then install_launchd(ctx)
-          when /linux/ then print_linux_unit
+          when /linux/ then install_systemd
           else raise Error, "Service install not supported on #{RUBY_PLATFORM}"
           end
+          # Root can write /etc/hosts, so sync the routes registered so
+          # far while elevated — Safari works the moment setup finishes
+          # (Chrome resolves *.localhost natively).
+          sync_hosts_from_routes(ctx)
+          true
+        end
+
+        def sync_hosts_from_routes(ctx)
+          hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
+          if hostnames.empty?
+            puts "    No routes registered yet — hosts sync will happen on the next boot."
+          elsif Ask::Local::Hosts.sync(hostnames)
+            puts "    Synced #{hostnames.length} hostname(s) to /etc/hosts."
+          else
+            warn "    could not write /etc/hosts (run `sudo ask-local hosts sync` later)"
+          end
+        end
+
+        # Run a privileged command via sudo. Interactive: plain sudo (one
+        # prompt). Non-interactive: `sudo -n` — no prompt ever; requires the
+        # NOPASSWD grant from `ask-local sudoers`. On failure prints the
+        # provisioning hint so agents/CI know exactly what to install.
+        def elevate(cmd)
+          interactive = $stdin.tty? && ENV["CI"].nil?
+          sudo_args = interactive ? ["sudo"] : ["sudo", "-n"]
+          ok = Command.run(*sudo_args, *cmd)
+          return true if ok
+
+          # An interactive sudo failure is auth or the elevated command
+          # itself (whose error is already on screen) — re-run and read it.
+          # The scoped-grant hint only helps passwordless non-interactive
+          # runs, where a missing NOPASSWD rule is the usual cause.
+          if interactive
+            $stderr.puts "sudo failed — re-run `ask-local setup` to try again."
+          else
+            $stderr.puts "sudo failed — install the scoped grant once:"
+            $stderr.puts "  ask-local sudoers > /tmp/ask-local.sudoers"
+            $stderr.puts "  sudo install -o root -g wheel -m 440 /tmp/ask-local.sudoers /etc/sudoers.d/ask-local"
+          end
+          false
         end
 
         def user_home_for_service
@@ -206,17 +295,62 @@ module Ask
           path = File.join(dir, "dev.ask.local.plist")
           File.write(path, plist)
           File.chmod(0o644, path)
-          Ownership.chown_service_files(path)
-          system("launchctl", "unload", path) rescue nil
-          system("launchctl", "load", path) or raise Error, "launchctl load failed"
+          # launchd requires /Library/LaunchDaemons plists to be
+          # root-owned; we are root here (sudo re-exec). Enforce it
+          # explicitly: File.write keeps an existing file's owner, so a
+          # stale user-owned plist from an older version would otherwise
+          # survive the overwrite and bootstrap fails with error 5.
+          # Trust the CA into the System keychain while elevated: silent
+          # (no GUI popup) and trusted for every user on the machine.
+          File.chown(0, 0, path) if Process.uid.zero?
+          ensure_system_ca_trust
+          puts "    Registering the launchd service on port 443..."
+          launchctl_bootstrap(path)
           puts "Installed root LaunchDaemon on port 443 (state: #{state_dir})."
-          puts "Restart your machine or run: sudo launchctl load #{path}"
         end
 
-        def print_linux_unit
+        # Root-only CA trust: the System keychain (all users, no prompt).
+        # Safe to call repeatedly — once the marker is set it is a no-op.
+        # Prints before doing work: the System keychain add can take a few
+        # seconds, and this runs in the root half of setup where silence
+        # reads as a hang.
+        def ensure_system_ca_trust
+          return if Certs.trusted?(Certs.state_dir)
+
+          puts "    Trusting the CA into the System keychain..."
+          result = Trust.trust
+          warn "    CA trust warning: #{result[:error]}" unless result[:trusted]
+        end
+
+        # Modern launchctl system-domain verbs. The legacy `launchctl load`
+        # is rejected by current macOS with error 5 (Input/output error) —
+        # and worse, it can print that error while still exiting 0, so the
+        # old code "succeeded" without the service actually running.
+        # bootstrap/bootout are the supported verbs (same as puma-dev and
+        # portless); extracted so the command sequence is unit-testable.
+        def launchctl_bootstrap(path)
+          # Best-effort: booting out a service that was never loaded prints
+          # "Boot-out failed: 5" — nothing to clear then, so keep it quiet.
+          # Any real leftover is removed silently; bootstrap errors below
+          # stay loud.
+          Command.run("launchctl", "bootout", "system", path, out: File::NULL, err: File::NULL)
+          unless Command.run("launchctl", "bootstrap", "system", path)
+            raise Error, "launchctl bootstrap failed — check the plist at #{path}"
+          end
+          Command.run("launchctl", "enable", "system/dev.ask.local")
+          Command.run("launchctl", "kickstart", "-k", "system/dev.ask.local")
+        end
+
+        def launchctl_bootout(path)
+          Command.run("launchctl", "bootout", "system", path)
+        end
+
+        # Pure unit-file builder (testable without root). Binds 80/443 at
+        # boot; the proxy runs with the invoking user's state dir.
+        def systemd_unit
           home = user_home_for_service
           state_dir = ENV["ASK_LOCAL_STATE_DIR"] || File.join(home, ".ask-local")
-          puts <<~UNIT
+          <<~UNIT
             # /etc/systemd/system/ask-local.service  (binds 80/443 at boot)
             [Unit]
             After=network.target
@@ -228,28 +362,46 @@ module Ask
 
             [Install]
             WantedBy=multi-user.target
-
-            Install with: sudo cp ask-local.service /etc/systemd/system/ && sudo systemctl enable --now ask-local
-            (Run that install command with sudo so the service is root-owned.)
           UNIT
         end
 
-        def service_uninstall(_ctx)
+        # Install + start the systemd unit (mirrors portless). We are root
+        # here (sudo re-exec). The unit is written root-owned, then enabled
+        # and started.
+        def install_systemd
+          unit_path = "/etc/systemd/system/ask-local.service"
+          File.write(unit_path, systemd_unit)
+          File.chmod(0o644, unit_path)
+          File.chown(0, 0, unit_path) if Process.uid.zero?
+          puts "    Registering the systemd service on port 443..."
+          Command.run("systemctl", "daemon-reload") or raise Error, "systemctl daemon-reload failed"
+          Command.run("systemctl", "enable", "--now", "ask-local") or raise Error, "systemctl enable failed"
+          puts "Installed systemd service ask-local on port 443."
+        end
+
+        def service_uninstall(ctx)
           if !ProxyControl.root?
+            puts "Removing system service (sudo required)..."
             state = Certs.state_dir
-            ok = system("sudo", "env", "ASK_LOCAL_STATE_DIR=#{state}",
-              RbConfig.ruby, ProxyControl.bin_path, "service", "uninstall", "--internal")
-            exit(ok ? 0 : 1)
+            cmd = ["env", "ASK_LOCAL_STATE_DIR=#{state}",
+              RbConfig.ruby, ProxyControl.bin_path, "service", "uninstall", "--internal"]
+            return elevate(cmd)
           end
           case RUBY_PLATFORM
           when /darwin/
             path = "/Library/LaunchDaemons/dev.ask.local.plist"
-            system("launchctl", "unload", path) rescue nil
+            launchctl_bootout(path)
             FileUtils.rm_f(path)
             puts "Removed root LaunchDaemon."
+          when /linux/
+            Command.run("systemctl", "disable", "--now", "ask-local")
+            Command.run("systemctl", "daemon-reload")
+            FileUtils.rm_f("/etc/systemd/system/ask-local.service")
+            puts "Removed systemd service ask-local."
           else
-            puts "Remove /etc/systemd/system/ask-local.service, then: sudo systemctl disable --now ask-local"
+            raise Error, "Service uninstall not supported on #{RUBY_PLATFORM}"
           end
+          true
         end
 
         def service_status(ctx)
@@ -336,52 +488,64 @@ module Ask
 
               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
+                Default: install the root proxy service on 443 — runs under
+                sudo ONCE, trusting the CA system-wide in the same step
+                (no separate GUI authorization popup).
+                --no-service: trust the CA at user level, then run a sudo
+                daemon instead (no boot persistence; ephemeral machines).
 
-              --no-service skips the root service and starts a sudo daemon
-              instead (no boot persistence; good for ephemeral machines).
+              Both finish by syncing /etc/hosts and verifying with doctor.
             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
+          puts "Note: setup takes a few seconds while the 443 service installs and starts."
 
-          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.")
+          no_service = args.include?("--no-service")
+          steps = no_service ? 4 : 3
+
+          if no_service
+            step("1/#{steps} 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
-          else
-            step("2/4 Starting proxy sudo daemon on port 443") do
+            step("2/#{steps} 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
+          else
+            step("1/#{steps} Installing proxy service on port 443 (trusts CA)") do
+              # Runs under sudo once; inside, the CA is trusted into the
+              # System keychain silently (no GUI popup) and the launchd
+              # service is bootstrapped. One password entry, that's all.
+              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
           end
 
-          step("3/4 Syncing /etc/hosts") do
+          step("#{no_service ? 3 : 2}/#{steps} Syncing /etc/hosts") do
             hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
-            unless Ask::Local::Hosts.sync(hostnames)
+            next if hostnames.empty?
+
+            # The root service install already synced under elevation; a
+            # plain re-run must not fail rewriting /etc/hosts unprivileged
+            # when the block is already in place.
+            unless Ask::Local::Hosts.synced?(hostnames) || 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
+          step("#{no_service ? 4 : 3}/#{steps} 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."
@@ -405,12 +569,24 @@ module Ask
           exit 1
         end
 
+        # The two ways to get a privileged proxy on 443: a human runs setup
+        # once (interactive sudo), or an agent/CI image is pre-provisioned
+        # with the scoped NOPASSWD rules from `ask-local sudoers`.
+        def privileged_port_hint
+          [
+            "Human: run this once — ask-local setup",
+            "Agent/CI: pre-provision passwordless sudo once —",
+            "  ask-local sudoers > /tmp/ask-local.sudoers",
+            "  sudo install -o root -g wheel -m 440 /tmp/ask-local.sudoers /etc/sudoers.d/ask-local"
+          ]
+        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, [])
+          return false unless service_install(ctx, [])
           wait_for_ours(ctx, 443, tls: true)
         rescue Error, SystemCallError => e
           warn "    service install failed: #{e.message}"
@@ -422,6 +598,9 @@ module Ask
           port, tls = 443, true
           unless ctx.interactive?
             warn "    no TTY available for the sudo prompt."
+            warn "    Agent/CI: pre-provision passwordless sudo once —"
+            warn "      ask-local sudoers > /tmp/ask-local.sudoers"
+            warn "      sudo install -o root -g wheel -m 440 /tmp/ask-local.sudoers /etc/sudoers.d/ask-local"
             return false
           end
           ProxyControl.spawn_daemon(store: ctx.store, port: port, tls: tls, sudo: true)
@@ -431,14 +610,44 @@ module Ask
           false
         end
 
+        # Poll until our proxy answers on the port. The freshly installed
+        # service takes a few seconds to boot, so show motion instead of a
+        # frozen prompt: a spinner on a terminal, dots elsewhere. Silent
+        # when the proxy is already up.
         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
+          terminal = $stdout.respond_to?(:tty?) && $stdout.tty?
+          waiting = false
+          frame = 0
+          ok = false
+          loop do
+            if ProxyControl.ours?(port, tls: tls)
+              ok = true
+              break
+            end
+            break if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
 
+            unless waiting
+              print terminal ? "    starting the proxy on port #{port} " : "    (starting the proxy on port #{port}"
+              waiting = true
+            end
+            if terminal
+              print %w[| / - \\][frame % 4], "\b"
+            else
+              print "."
+            end
+            $stdout.flush
+            frame += 1
             sleep 0.5
           end
-          true
+          if waiting
+            if terminal
+              puts(ok ? "\r    proxy is up on port #{port}." : "\r    still not up on port #{port}.")
+            else
+              puts ")"
+            end
+          end
+          ok
         end
 
         # ask-local start — one-setup-and-go: idempotent workstation setup
@@ -501,8 +710,7 @@ module Ask
           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")
+              abort_setup("Proxy is not running and port 443 needs root to bind.", *privileged_port_hint)
             end
             ok =
               if ProxyControl.root?
@@ -519,9 +727,7 @@ module Ask
                 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`.")
+              abort_setup("Proxy is not running and could not be started on port 443.", *privileged_port_hint)
             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 setup start init].freeze
+      SUBCOMMANDS = %w[run get alias hosts list doctor trust clean prune proxy service sudoers kamal stop restart log status open setup start init].freeze
 
       def self.run(argv)
         new.run(argv)
@@ -44,6 +44,7 @@ module Ask
         when "prune" then RoutesCommand.prune(ctx, args)
         when "proxy" then SystemCommand.proxy(ctx, args)
         when "service" then SystemCommand.service(ctx, args)
+        when "sudoers" then SystemCommand.sudoers(ctx, args)
         when "setup" then SystemCommand.setup(ctx, args)
         when "init" then SystemCommand.init(ctx, args)
         when "start" then SystemCommand.start(ctx, args)
@@ -83,6 +84,7 @@ module Ask
             ask-local prune                  Remove stale routes
             ask-local proxy start|stop       Control the proxy
             ask-local service install|status|uninstall   OS startup service
+            ask-local sudoers                Print scoped passwordless-sudo rules for port 443
             ask-local hosts sync|clean       Manage /etc/hosts entries
             ask-local kamal <variant>        Preview-deploy snippet for Kamal
             ask-local stop                   Stop this app's backend + routes

data/lib/ask/local/command.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ask
+  module Local
+    # Injectable command runner for privileged/child-process work.
+    #
+    # Every system()/Open3 call that tests must control goes through here
+    # (elevation re-exec, launchctl, systemctl, security). Unit tests stub
+    # Command.run / Command.capture2 so they never shell out — no real
+    # sudo prompt, no keychain mutation, hermetic and CI-safe. The real
+    # implementations are the thin wrappers below.
+    #
+    # A plain class (not module_function): Mocha stubs class methods
+    # reliably, whereas module_function singletons dodge the stub and the
+    # real command would run.
+    class Command
+      # True when the command exited 0. Mirrors Kernel#system semantics.
+      def self.run(*args)
+        system(*args)
+      end
+
+      # [stdout, Process::Status] — mirrors Open3.capture2.
+      def self.capture2(*args)
+        Open3.capture2(*args)
+      end
+    end
+  end
+end

data/lib/ask/local/hosts.rb

@@ -56,6 +56,14 @@ module Ask
         false
       end
 
+      # True when /etc/hosts already carries exactly the managed block for
+      # these hostnames. The root service install syncs under elevation;
+      # plain re-runs of setup must not fail trying to rewrite it
+      # unprivileged when nothing changed.
+      def synced?(hostnames, path = PATH)
+        read(path).include?(managed_block(hostnames))
+      end
+
       def clean(path = PATH)
         content = read(path)
         updated = content.sub(/#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}\n?/m, "")

data/lib/ask/local/ownership.rb

@@ -50,13 +50,6 @@ module Ask
       def chown_state_dir(dir)
         fix(dir)
       end
-
-      # The LaunchDaemon plist root writes into /Library/LaunchDaemons:
-      # root-owned is correct there, but record it so `service status`
-      # can explain the split.
-      def chown_service_files(*paths)
-        fix(*paths)
-      end
     end
   end
 end

data/lib/ask/local/proxy.rb

@@ -64,6 +64,7 @@ module Ask
         servers.each { |s| s.listen(@port) }
         @port = servers.first.addr[1]
         Ownership.chown_state_dir(@store.dir)
+        ensure_system_ca_trust if Process.uid.zero?
         trap("INT") { stop(servers) }
         trap("TERM") do
           @supervisor&.shutdown
@@ -91,7 +92,7 @@ module Ask
                     release
                   end
                 end
-              rescue IOError, SystemCallError
+              rescue OpenSSL::SSL::SSLError, IOError, SystemCallError
                 break unless @running
               end
             end
@@ -124,6 +125,16 @@ module Ask
 
       private
 
+      # A root proxy (launchd service or sudo daemon) is the one process
+      # that can trust the CA into the System keychain silently — no GUI
+      # popup. Idempotent: the state-dir marker makes repeat boots a no-op.
+      def ensure_system_ca_trust
+        return if Certs.trusted?(@state_dir)
+
+        result = Trust.trust(@state_dir)
+        @on_error.call("CA trust warning: #{result[:error]}") unless result[:trusted]
+      end
+
       def admit?
         @inflight_mutex.synchronize do
           return false if @inflight >= @max_connections

data/lib/ask/local/trust.rb

@@ -32,14 +32,24 @@ module Ask
       end
 
       def trust_macos(cert_path)
-        keychain = login_keychain
-        _out, status = Open3.capture2("security", "add-trusted-cert",
-          "-r", "trustRoot", "-k", keychain, cert_path)
-        raise CertError, "security add-trusted-cert failed" unless status.success?
+        if Process.uid.zero?
+          # Running elevated (service install / root proxy): add to the
+          # System keychain with the admin (-d) domain. Root can modify it
+          # silently — no GUI authorization popup, and every user's
+          # browsers trust the proxy.
+          _out, status = Command.capture2("security", "add-trusted-cert",
+            "-d", "-r", "trustRoot", "-k", "/Library/Keychains/System.keychain", cert_path)
+          raise CertError, "security add-trusted-cert (system) failed" unless status.success?
+        else
+          keychain = login_keychain
+          _out, status = Command.capture2("security", "add-trusted-cert",
+            "-r", "trustRoot", "-k", keychain, cert_path)
+          raise CertError, "security add-trusted-cert failed" unless status.success?
+        end
       end
 
       def login_keychain
-        out, status = Open3.capture2("security", "default-keychain")
+        out, status = Command.capture2("security", "default-keychain")
         if status.success? && (m = out.match(/"(.+)"/))
           m[1]
         else
@@ -51,7 +61,7 @@ module Ask
         dest_dir, update_cmd = linux_ca_config
         FileUtils.mkdir_p(dest_dir)
         FileUtils.cp(cert_path, File.join(dest_dir, "ask-local-ca.crt"))
-        _out, status = Open3.capture2(update_cmd)
+        _out, status = Command.capture2(update_cmd)
         raise CertError, "#{update_cmd} failed" unless status.success?
       end
 
@@ -73,7 +83,7 @@ module Ask
       end
 
       def trust_windows(cert_path)
-        _out, status = Open3.capture2("certutil", "-addstore", "-user", "Root", cert_path)
+        _out, status = Command.capture2("certutil", "-addstore", "-user", "Root", cert_path)
         raise CertError, "certutil failed" unless status.success?
       end
 
@@ -86,12 +96,12 @@ module Ask
         errors = []
         case platform
         when :macos
-          Open3.capture2("security", "remove-trusted-cert", paths[:cert])
+          Command.capture2("security", "remove-trusted-cert", paths[:cert])
           # delete-certificate fails silently when no match remains; loop
           # to clear duplicate CN entries from each keychain.
           [login_keychain, "/Library/Keychains/System.keychain"].each do |kc|
             5.times do
-              Open3.capture2("security", "delete-certificate", "-c", CA_COMMON_NAME, kc)
+              Command.capture2("security", "delete-certificate", "-c", Certs::CA_COMMON_NAME, kc)
             end
           rescue SystemCallError
             nil
@@ -100,9 +110,9 @@ module Ask
           dest_dir, update_cmd = linux_ca_config
           dest = File.join(dest_dir, "ask-local-ca.crt")
           FileUtils.rm_f(dest) if File.file?(dest)
-          Open3.capture2(update_cmd)
+          Command.capture2(update_cmd)
         when :windows
-          Open3.capture2("certutil", "-delstore", "-user", "Root", CA_COMMON_NAME)
+          Command.capture2("certutil", "-delstore", "-user", "Root", Certs::CA_COMMON_NAME)
         end
         trusted_after = begin
           Certs.trusted?(dir)

data/lib/ask/local/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Local
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/ask-local.rb

@@ -9,6 +9,7 @@ require_relative "ask/local/variant"
 require_relative "ask/local/framework"
 require_relative "ask/local/config"
 require_relative "ask/local/ownership"
+require_relative "ask/local/command"
 require_relative "ask/local/log"
 require_relative "ask/local/route_store"
 require_relative "ask/local/certs"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-local
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -89,6 +89,7 @@ files:
 - lib/ask/local/cli/context.rb
 - lib/ask/local/cli/routes.rb
 - lib/ask/local/cli/system.rb
+- lib/ask/local/command.rb
 - lib/ask/local/config.rb
 - lib/ask/local/doctor.rb
 - lib/ask/local/errors.rb