ask-local 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9b2c40e96d2ccde2095d698a79684a3dec1335afe9ac4acc1773405f520002d
-  data.tar.gz: a2a63d630679488b6236a499bb954fa2cf70028c2f00d5dd34c2f76a21ef057b
+  metadata.gz: 4407cbb75f7a6a5347fd2b71963a4229dc925c7d36438ae885c25c04759c94a6
+  data.tar.gz: 3ac24692630768264da89e9ce37e75403cbb3e2686ce1c18d6b1a99483d9c85d
 SHA512:
-  metadata.gz: dc721fac709387e593ed445f03080e994fcd2614ec5ff74e92ba4ccccf17dea61d59029ab187eaffe1eca52a088c817a36d86cdf7e7c13a8d3fd5878d8284f7a
-  data.tar.gz: 16c12424f982fc3db86c2fd210cae69e7890abc22c3f1cdd8c747cfac9ab2c15952c431ee72557144d5dfccd8bc9c95aebe0ab94b6cb3b30c95faa33329a8b5a
+  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,14 +28,66 @@ 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
+## Port 443: one-time setup, then never again
 
-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.
+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
+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.
+
+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`.
@@ -110,7 +162,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
 
@@ -149,7 +201,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 |