ruby_everywhere 0.3.0 → 0.5.0

data/lib/everywhere/dock.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require_relative "ui"
+require_relative "console"
+require_relative "dock/state"
+require_relative "dock/footer"
+require_relative "dock/screen"
+
+module Everywhere
+  # The pinned status bar at the bottom of `every dev`.
+  #
+  # The old key menu was printed once, before the loop, and was gone from the
+  # screen within seconds of the Rails server starting to log. The dock keeps
+  # the keymap — and what each target is actually doing — permanently visible,
+  # while the logs scroll normally above it.
+  #
+  # It installs itself as Console's sink, so every write in the process (CLI
+  # chrome, relayed server output, filtered build output) is framed by an erase
+  # and a repaint. See Dock::Screen for why it repaints rather than reserving
+  # rows with a scroll region.
+  class Dock
+    TICK = 0.2
+
+    KEYS = [
+      ["d", "desktop"],
+      ["i", "iOS"],
+      ["a", "Android"],
+      ["b", "browser"],
+      ["l", "logs"],
+      ["r", "restart"],
+      ["?", "help"],
+      ["q", "quit"]
+    ].freeze
+
+    HELP = [
+      ["d", "relaunch the desktop shell (opens it if it isn't running)"],
+      ["i", "rebuild, reinstall and relaunch on the iOS Simulator"],
+      ["a", "rebuild, reinstall and relaunch on the Android emulator"],
+      ["b", "open the app in your default browser"],
+      ["l", "start/stop streaming iOS Simulator logs"],
+      ["r", "restart the dev server only"],
+      ["?", "hide this help"],
+      ["q", "quit (Ctrl-C works too)"]
+    ].freeze
+
+    # A dock needs room to be worth having, and a terminal that understands
+    # cursor movement. NO_COLOR is deliberately NOT a disqualifier: it governs
+    # SGR, not cursor control, and the footer's glyphs carry the meaning on
+    # their own.
+    MIN_ROWS = 12
+    MIN_COLS = 40
+
+    def self.open(targets, io: $stdout, keys: true, size: nil)
+      return Null.new(targets, keys: keys) unless drawable?(io, size)
+
+      new(targets, io: io, keys: keys, size: size).tap(&:install)
+    end
+
+    def self.drawable?(io, size)
+      return false if ENV["EVERY_NO_DOCK"]
+      return false unless io.respond_to?(:tty?) && io.tty?
+      return false if ENV["TERM"].to_s.empty? || ENV["TERM"] == "dumb"
+
+      rows, cols = size || Screen.new(io: io).size
+      rows >= MIN_ROWS && cols >= MIN_COLS
+    end
+
+    def initialize(targets, io: $stdout, keys: true, size: nil)
+      @state = State.new(targets)
+      @screen = Screen.new(io: io, size: size)
+      @keys = keys
+      @help = false
+      @frame = 0
+      @dirty = true
+      @open = false
+    end
+
+    attr_reader :state
+
+    def install
+      @open = true
+      @screen.open
+      Console.dock = self
+      trap_resize
+      start_ticker
+      self
+    end
+
+    # --- state --------------------------------------------------------------
+
+    def set(key, state, detail: nil)
+      @state.set(key, state, detail: detail)
+      @dirty = true
+      refresh
+    end
+
+    def detail(key, text)
+      @state.detail(key, text)
+      @dirty = true
+    end
+
+    def toggle_help
+      @help = !@help
+      @dirty = true
+      refresh
+    end
+
+    # The dock draws the keymap permanently, so there is nothing to announce.
+    # Null overrides this to print the one-shot hint the old command used.
+    def announce_keys = nil
+
+    # --- drawing ------------------------------------------------------------
+
+    # Called by Console, which already holds the lock. Content must end at
+    # column 1, or the erase math for the next frame is off by a row.
+    def emit(text)
+      body = text.end_with?("\n") ? text : "#{text}\n"
+      @screen.frame(body, footer_rows)
+      @dirty = false
+    end
+
+    def refresh
+      Console.synchronize do
+        next unless @open
+
+        @screen.frame("", footer_rows)
+        @dirty = false
+      end
+    end
+
+    # Wipe the footer and leave it wiped — for stderr, or an interactive child
+    # that needs the screen to itself.
+    def clear = @screen.clear
+
+    def close
+      return unless @open
+
+      # Order matters: drop the flag so the ticker stops drawing, let it finish
+      # the frame it may be mid-way through, and only then unhook and restore.
+      @open = false
+      @ticker&.join(TICK * 2)
+      @ticker&.kill
+      Console.dock = nil
+      Console.synchronize { @screen.close }
+    end
+
+    private
+
+    # One column short of the terminal on purpose. A row filled to the last
+    # column leaves the cursor in a pending-wrap state whose handling varies
+    # between terminals, and a footer row that wraps costs the erase math a row.
+    def footer_rows
+      lines = Footer.render(@state.targets,
+                            cols: [@screen.cols - 1, 1].max,
+                            keys: (@keys ? KEYS : nil),
+                            frame: @frame,
+                            elapsed: ->(target) { @state.elapsed(target) },
+                            rule: @screen.rows >= 24)
+      @help ? lines + help_rows : lines
+    end
+
+    def help_rows
+      width = HELP.map { |key, _| key.length }.max
+      HELP.map { |key, desc| "  #{UI.bold(key.ljust(width))}  #{UI.dim(desc)}" }
+    end
+
+    # An idle dev session should emit zero bytes per second, so only redraw when
+    # something changed or a spinner is actually turning.
+    def start_ticker
+      @ticker = Thread.new do
+        Thread.current.name = "dock"
+        Thread.current.report_on_exception = false
+        while @open
+          sleep TICK
+          next unless @open
+
+          # Screen#size re-reads the ioctl every frame, so a resize needs
+          # nothing more than a redraw.
+          if @resized
+            @resized = false
+            @dirty = true
+          end
+          busy = @state.busy?
+          @frame += 1 if busy
+          refresh if busy || @dirty
+        end
+      rescue StandardError
+        # A dock that can't draw must never be the reason a dev session dies.
+        @open = false
+        Console.dock = nil
+      end
+    end
+
+    # Trap handlers must not take a lock (Ruby raises ThreadError when the lock
+    # is held in trap context), so this only sets a flag; the ticker draws.
+    def trap_resize
+      Signal.trap("WINCH") { @resized = true }
+    rescue ArgumentError, StandardError
+      nil
+    end
+
+    # The headless stand-in: same API, no escape sequences ever. Used for CI,
+    # pipes, `| tee`, dumb terminals and windows too small to spare the rows.
+    # It narrates transitions as ordinary lines so a piped log still reads.
+    #
+    # Note it never installs itself as Console's sink — output keeps going
+    # straight to $stdout, exactly as it did before the dock existed.
+    class Null
+      def initialize(targets, keys: true)
+        @state = State.new(targets)
+        @keys = keys
+      end
+
+      attr_reader :state
+
+      def install = self
+
+      def set(key, state, detail: nil)
+        target = @state.set(key, state, detail: detail) or return
+        UI.step("#{target.label} → #{[state, detail].compact.join(" ")}")
+      end
+
+      def detail(_key, _text) = nil
+      def toggle_help = nil
+      def emit(text) = nil
+      def refresh = nil
+      def clear = nil
+      def close = nil
+
+      # The one-shot keymap the old command printed, kept for headless runs.
+      def announce_keys
+        return unless @keys
+
+        UI.note(KEYS.map { |key, desc| "#{UI.bold(key)} #{desc}" }.join(" · "), marker: "⌨", color: :cyan)
+      end
+    end
+  end
+end

data/lib/everywhere/emulator.rb

@@ -0,0 +1,405 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "android_sdk"
+require_relative "shellout"
+require_relative "ui"
+
+module Everywhere
+  # Thin wrappers around `adb` and `emulator` — just enough to boot a virtual
+  # device, put the stamped APK on it and launch it. The Android counterpart of
+  # Simulator, method for method, so `every dev` reads the same either way.
+  #
+  # Every binary comes from AndroidSdk, never from PATH: Android Studio
+  # provisions adb and the emulator and exports neither, so a machine that can
+  # build Android apps all day has no `adb` on PATH (see AndroidSdk's preamble).
+  module Emulator
+    module_function
+
+    # Phase 0 measured a headless cold boot of Medium_Phone_API_35 at 16s to
+    # sys.boot_completed, and a windowed cold boot — which is what we default
+    # to, see #boot_argv — at roughly two minutes. Four minutes is generous
+    # enough to cover a slower machine or an AVD whose Quick Boot snapshot is
+    # being rebuilt, without pretending a genuinely wedged emulator will
+    # eventually come good.
+    BOOT_TIMEOUT = 240
+
+    POLL_INTERVAL = 1
+
+    # The emulator's alias for the host's own loopback interface: inside the
+    # guest, 127.0.0.1 is the *guest*, and 10.0.2.2 is the machine running it.
+    # Rung 2 of the dev-URL ladder (plan §2.3).
+    LOOPBACK_ALIAS = "10.0.2.2"
+
+    # Hosts that mean "this machine" in a dev URL and therefore mean the wrong
+    # machine once the URL is loaded inside the guest. 0.0.0.0 is here because
+    # a server bound to every interface is often *printed* as http://0.0.0.0:3000.
+    LOOPBACK_HOSTS = ["127.0.0.1", "localhost", "::1", "0.0.0.0"].freeze
+
+    # The shell template's launcher activity, FULLY QUALIFIED on purpose.
+    #
+    # `am start -n <applicationId>/<activity>` resolves a leading dot against the
+    # applicationId — but the template's manifest says `android:name=".MainActivity"`,
+    # which Gradle resolves against the *namespace*, and the namespace is frozen
+    # at com.rubyeverywhere.shell precisely so an app can rename its bundle id
+    # freely. The two are different packages for every real app, so any relative
+    # spelling here is wrong the moment applicationId != namespace.
+    # (The Hotwire demo's `.main.MainActivity` is a fact about the demo, whose
+    # applicationId happens to equal its namespace. It does not transfer.)
+    DEFAULT_ACTIVITY = "com.rubyeverywhere.shell.MainActivity"
+
+    # --- devices --------------------------------------------------------------
+
+    # Serial of a device we can actually talk to, or nil.
+    #
+    # Emulators come first because they are what `every dev --android` boots and
+    # what the dev-URL ladder can rewrite for; a plugged-in phone is still
+    # accepted after them, since someone with a device attached and no emulator
+    # running clearly meant that device.
+    def booted_serial
+      ready = devices.select { |d| d[:state] == "device" }
+      (ready.find { |d| emulator?(d[:serial]) } || ready.first)&.fetch(:serial)
+    end
+
+    # Parsed `adb devices -l`. Lines look like:
+    #
+    #   List of devices attached
+    #   emulator-5554   device product:sdk_gphone64_arm64 model:… transport_id:1
+    #   emulator-5556   offline
+    #   3A2B1C0D4E      unauthorized usb:1-1
+    #
+    # `device` is the only state that can take a command. `offline` is a device
+    # the daemon has seen but can't talk to — an emulator still coming up, or one
+    # that wedged — and `unauthorized` is a phone whose owner hasn't tapped
+    # "Allow USB debugging" yet. Both are kept in the list (so callers can say
+    # *why* nothing is usable) but neither is ever picked by #booted_serial:
+    # installing against them fails with a message that reads like our bug.
+    def devices
+      exe = AndroidSdk.adb or return []
+
+      out, status = Shellout.capture(exe, "devices", "-l")
+      return [] unless status&.success?
+
+      out.lines.filter_map do |line|
+        # Skip the header and adb's own "* daemon started successfully" notes.
+        next if line.start_with?("List of devices", "*")
+
+        serial, state, = line.split
+        next unless serial && state&.match?(/\A[a-z]+\z/)
+
+        { serial: serial, state: state }
+      end
+    end
+
+    # adb names emulators after their console port (emulator-5554); physical
+    # devices carry a hardware serial. That prefix is the standard test and it's
+    # what decides whether the 10.0.2.2 rewrite is even meaningful.
+    def emulator?(serial) = serial.to_s.start_with?("emulator-")
+
+    # --- booting --------------------------------------------------------------
+
+    # Reuse a running device, else boot an AVD and wait for it to be usable.
+    # Returns the serial.
+    def boot_default!(avd: nil, headless: false, timeout: BOOT_TIMEOUT)
+      if (serial = booted_serial)
+        UI.step("reusing #{UI.bold(serial)}")
+        return serial
+      end
+
+      name = avd || AndroidSdk.avds!.last
+      UI.step("booting emulator #{UI.bold(name)}#{headless ? UI.dim(" (headless)") : ""}")
+      spawn_emulator(boot_argv(name, headless: headless))
+
+      deadline = Time.now + timeout
+      bounded_wait(adb_argv(nil, "wait-for-device"), timeout: timeout)
+      serial = booted_serial or
+        UI.die!("emulator #{name} never registered with adb — try booting it from Android " \
+                "Studio's Device Manager to see what it says")
+      wait_until_booted(serial, timeout: [deadline - Time.now, POLL_INTERVAL].max)
+      serial
+    end
+
+    # WINDOWED BY DEFAULT, deliberately, even though headless boots roughly
+    # eight times faster (16s vs ~2m in the Phase 0 measurements).
+    #
+    # The emulator window *is* the feedback surface of this dev loop — you press
+    # `a` to look at your app. A headless boot installs and launches a shell you
+    # cannot see, which is indistinguishable from a build that silently failed;
+    # that is not hypothetical, it is what happened the first time this was run
+    # by hand. The slow boot is a one-time cost per session, paid while other
+    # work (the Gradle build) is happening anyway, and Quick Boot amortises it
+    # away on every subsequent run. Invisibility is a cost paid *every* time,
+    # and it is paid in "is this broken?".
+    #
+    # `headless: true` stays available for CI and for anyone who really does
+    # only want logs.
+    #
+    # Notably absent: `-no-snapshot`. The spike passed it to force honest cold
+    # boots for measurement; for a dev loop the opposite is wanted — Quick Boot
+    # restores a saved state in seconds instead of running Android's whole
+    # startup again. `-no-audio` stays regardless: the emulator grabbing the
+    # host's audio device is a well-known source of hangs on macOS, and a web
+    # shell has nothing to play.
+    def boot_argv(avd, headless: false)
+      argv = [AndroidSdk.emulator!, "-avd", avd, "-no-boot-anim", "-no-audio"]
+      argv << "-no-window" if headless
+      argv
+    end
+
+    # `adb wait-for-device` returns as soon as the daemon can talk to the
+    # device, which Phase 0 clocked at 8s — a full 8s before the system is
+    # actually usable. So it's the *start* of the wait, not the end: what says
+    # "ready" is sys.boot_completed flipping to 1.
+    def wait_until_booted(serial, timeout: BOOT_TIMEOUT)
+      deadline = Time.now + timeout
+      bounded_wait(adb_argv(serial, "wait-for-device"), timeout: timeout)
+
+      until Time.now > deadline
+        return serial if boot_completed?(serial)
+
+        sleep POLL_INTERVAL
+      end
+      UI.die!("emulator #{serial} never finished booting " \
+              "(sys.boot_completed still unset after #{UI.elapsed(timeout)})")
+    end
+
+    def boot_completed?(serial)
+      out, status = Shellout.capture(*adb_argv(serial, "shell", "getprop", "sys.boot_completed"))
+      status&.success? && out.strip == "1"
+    end
+
+    # --- app lifecycle --------------------------------------------------------
+
+    # `-r` reinstalls over an existing copy, keeping its data — the fast path,
+    # and the one `every dev --android` takes on every press of `a`.
+    #
+    # It has one failure that no amount of retrying fixes: an APK signed by a
+    # different key than the copy already on the device is rejected with
+    # INSTALL_FAILED_UPDATE_INCOMPATIBLE, which is routine the first time a
+    # machine builds an app someone else's debug keystore installed. The only
+    # cure is removing the old package, so we do that once, out loud, rather
+    # than making the user decode the error.
+    #
+    # Old adb builds printed `Failure [...]` and still exited 0, so the output
+    # is checked as well as the status.
+    def install(serial, apk, application_id: nil)
+      out, status = capture_install(serial, apk)
+      return if status&.success? && !out.include?("Failure [")
+
+      if application_id && out.include?("INSTALL_FAILED_UPDATE_INCOMPATIBLE")
+        UI.warn "#{application_id} is installed with a different signing key — reinstalling " \
+                "from scratch #{UI.dim("(its app data is dropped)")}"
+        uninstall(serial, application_id)
+        out, status = capture_install(serial, apk)
+        return if status&.success? && !out.include?("Failure [")
+      end
+
+      UI.die!("adb install failed: #{out.strip}")
+    end
+
+    def capture_install(serial, apk)
+      Shellout.capture(*adb_argv(serial, "install", "-r", apk))
+    end
+
+    # Not fatal: "not installed for user 0" is the normal answer on a clean
+    # device, and every caller only wants the package gone.
+    def uninstall(serial, application_id)
+      _out, status = Shellout.capture(*adb_argv(serial, "uninstall", application_id))
+      !!status&.success?
+    end
+
+    # `am start` reports an unknown component as `Error: Activity class {…} does
+    # not exist.` on stdout *and still exits 0*, so the output is what decides.
+    def launch(serial, application_id, activity: DEFAULT_ACTIVITY)
+      component = "#{application_id}/#{activity}"
+      out, status = Shellout.capture(*adb_argv(serial, "shell", "am", "start", "-n", component))
+      return if started?(out, status)
+
+      # The APK on the device is the authority on its own launcher activity, so
+      # rather than dying on a stale constant, ask it. This costs one round trip
+      # only on the failure path, and it means moving MainActivity in the
+      # template can never silently break the dev loop again — which is exactly
+      # how this broke the first time.
+      resolved = launcher_activity(serial, application_id)
+      if resolved && resolved != activity
+        retry_component = "#{application_id}/#{resolved}"
+        retry_out, retry_status = Shellout.capture(
+          *adb_argv(serial, "shell", "am", "start", "-n", retry_component)
+        )
+        if started?(retry_out, retry_status)
+          UI.warn "launched #{resolved} — #{activity} is stale, update Emulator::DEFAULT_ACTIVITY"
+          return
+        end
+      end
+
+      UI.die!("couldn't launch #{component}: #{out.strip}")
+    end
+
+    # `am start` reports an unknown component on stdout and STILL exits 0, so a
+    # bare exit status is not an answer.
+    def started?(out, status)
+      !!status&.success? && !out.to_s.match?(/^Error:/)
+    end
+
+    # The launcher activity the installed APK actually declares. `cmd package
+    # resolve-activity --brief` prints `<package>/<activity>` on its last line;
+    # anything else (old adb, no match) answers nil so the caller can fail with
+    # the original, more useful error.
+    def launcher_activity(serial, application_id)
+      out, status = Shellout.capture(*adb_argv(serial, "shell", "cmd", "package", "resolve-activity",
+                                               "--brief", application_id))
+      return unless status&.success?
+
+      line = out.to_s.lines.map(&:strip).reject(&:empty?).last
+      return unless line&.include?("/")
+
+      package, activity = line.split("/", 2)
+      activity if package == application_id && !activity.to_s.empty?
+    end
+
+    # The app's process id on the device, or nil when it isn't running. `pidof`
+    # exits non-zero and prints nothing in that case, which is exactly the
+    # distinction `every logs --android` needs to make.
+    def pid_of(serial, application_id)
+      out, status = Shellout.capture(*adb_argv(serial, "shell", "pidof", application_id))
+      pid = out.to_s.split.first
+      pid if status&.success? && pid&.match?(/\A\d+\z/)
+    end
+
+    # Forward the device's <port> back to the host's <port>. Returns whether it
+    # took, because that answer *is* rung 1 of the dev-URL ladder below.
+    #
+    # It succeeds with nothing listening on the host port (verified in Phase 0),
+    # so it can run before the dev server is up. On success adb prints the port
+    # number to stdout — a wrapper that read non-empty output as failure would
+    # get this exactly backwards.
+    def reverse(serial, port)
+      _out, status = Shellout.capture(*adb_argv(serial, "reverse", "tcp:#{port}", "tcp:#{port}"))
+      !!status&.success?
+    end
+
+    # --- the dev-URL ladder (plan §2.3) --------------------------------------
+
+    # Resolve the URL the Android shell should be pointed at, given the URL the
+    # dev server is on *from the host's point of view*. Returns a URL string;
+    # `every dev --android` stamps whatever comes back into the debug build.
+    #
+    # Three rungs, so a failure at any one degrades instead of dead-ending:
+    #
+    #   0. `override` (--dev-url / --host) short-circuits everything. Someone who
+    #      typed an address knows something we don't — typically that the app is
+    #      being opened on a physical phone over the LAN.
+    #   1. `adb reverse tcp:<port> tcp:<port>`. Preferred, because it leaves the
+    #      URL *literally correct*: 127.0.0.1:3000 on the device is 127.0.0.1:3000
+    #      on the host, so cookies, redirects, OAuth callbacks and anything the
+    #      app prints all keep matching. Works on emulators and physical devices
+    #      alike.
+    #   2. The 10.0.2.2 rewrite, if reverse failed and the target is an emulator.
+    #      Automatic and announced — the user is told the URL changed and why,
+    #      because a silently different origin is a genuinely confusing thing to
+    #      debug an hour later.
+    #
+    # If none apply (a physical device, reverse failed, no override) the URL is
+    # returned unchanged with a warning naming the fix, rather than aborting a
+    # dev loop that is otherwise fine.
+    #
+    #   Emulator.dev_url("http://127.0.0.1:3000/", serial: "emulator-5554")
+    #   #=> "http://127.0.0.1:3000/"   (rung 1)  or  "http://10.0.2.2:3000/" (rung 2)
+    def dev_url(url, serial:, port: nil, override: nil)
+      unless override.to_s.empty?
+        UI.step("dev URL #{UI.cyan(override)} #{UI.dim("(explicit override)")}")
+        return override
+      end
+
+      # A URL that doesn't point at this machine needs no help: a LAN address or
+      # a deployed https:// origin is already reachable from the device.
+      return url unless loopback?(url)
+
+      port ||= port_of(url)
+      return url if port && reverse(serial, port)
+
+      rewritten = rewrite_loopback(url)
+      if emulator?(serial) && rewritten != url
+        UI.warn "adb reverse failed — pointing the shell at #{UI.cyan(rewritten)} instead " \
+                "#{UI.dim("(#{LOOPBACK_ALIAS} is the emulator's alias for this machine)")}"
+        return rewritten
+      end
+
+      UI.warn "adb reverse failed and #{serial || "this target"} isn't an emulator — " \
+              "#{UI.cyan(url)} will resolve to the device itself; pass a LAN address " \
+              "(--dev-url http://<this machine's IP>:#{port}) with the dev server bound to 0.0.0.0"
+      url
+    end
+
+    def loopback?(url) = LOOPBACK_HOSTS.include?(host_of(url))
+
+    def rewrite_loopback(url)
+      uri = URI.parse(url.to_s)
+      return url unless LOOPBACK_HOSTS.include?(uri.host)
+
+      uri.host = LOOPBACK_ALIAS
+      uri.to_s
+    rescue URI::InvalidURIError
+      url
+    end
+
+    def host_of(url)
+      URI.parse(url.to_s).host
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def port_of(url)
+      URI.parse(url.to_s).port
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    # --- plumbing -------------------------------------------------------------
+
+    # Every adb invocation goes through here so the `-s <serial>` targeting is
+    # never forgotten — an unqualified adb command with two devices attached
+    # fails with "more than one device", and with one emulator plus a phone it
+    # silently does the right thing on the wrong one. A nil serial means "any
+    # device", which is only ever wanted while waiting for the first one.
+    def adb_argv(serial, *args)
+      [AndroidSdk.adb!, *(serial ? ["-s", serial.to_s] : []), *args]
+    end
+
+    # The emulator has to outlive `every dev` the way the iOS Simulator app
+    # does — quitting the CLI should not tear down a device you were using — so
+    # it leads its own process group and is detached. Its INFO/WARNING banners
+    # go to /dev/null: they would otherwise land in the middle of the dev
+    # server's log, and nothing here reads them.
+    def spawn_emulator(argv)
+      pid = Process.spawn(Shellout.child_env, *argv, pgroup: true, out: File::NULL, err: File::NULL)
+      Process.detach(pid)
+      pid
+    end
+
+    # Run a command with a deadline, and report whether it finished in time.
+    #
+    # This exists for `adb wait-for-device`, which blocks forever by design: an
+    # AVD that fails to start would hang the dev loop with no output at all.
+    # Waiting on the child ourselves is the only way to put a ceiling on it, so
+    # the "never came up" path reaches a message a human can act on.
+    def bounded_wait(argv, timeout: BOOT_TIMEOUT)
+      pid = Process.spawn(Shellout.child_env, *argv, out: File::NULL, err: File::NULL)
+      deadline = Time.now + timeout
+      loop do
+        return true if Process.waitpid(pid, Process::WNOHANG)
+        break if Time.now > deadline
+
+        sleep POLL_INTERVAL
+      end
+
+      begin
+        Process.kill("TERM", pid)
+        Process.waitpid(pid)
+      rescue StandardError
+        nil
+      end
+      false
+    end
+  end
+end

data/lib/everywhere/engine.rb

@@ -39,6 +39,18 @@ module Everywhere
       end
     end
 
+    # Third-party sign-in for the native shells (everywhere.yml `auth:`). Middleware
+    # rather than routes: two thirds of the job is watching the app's *own* auth
+    # responses go by — see Everywhere::AuthHandoff. At the TOP of the stack,
+    # deliberately: a provider path from the web view must be diverted before any
+    # OmniAuth-family middleware (Devise's included) can answer it, and appended
+    # middleware sits below those or not depending on Gemfile order — which no
+    # app should have to know. Does nothing at all until the app declares `auth:`.
+    initializer "everywhere.auth" do |app|
+      require_relative "auth_handoff"
+      app.middleware.insert_before 0, Everywhere::AuthHandoff, root: app.root.to_s
+    end
+
     # /everywhere/ios_v1.json — the mobile shells' remote path configuration
     # (rules + settings.tabs), generated from config/everywhere.yml at request
     # time so tab changes ship with a normal deploy. A real controller (not

data/lib/everywhere/fatal.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Everywhere
+  # A failure that ends the current unit of work — not necessarily the process.
+  #
+  # It subclasses SystemExit deliberately. At the top level Ruby exits with
+  # #status and prints nothing (UI.die! has already written the ✗ line), so an
+  # uncaught Fatal behaves exactly like the Kernel#abort it replaces. Inside
+  # `every dev` a worker thread catches it instead and returns to the key menu,
+  # which is the whole point: a Swift typo must not take the Rails server down
+  # with it.
+  #
+  # CAUTION for anyone catching this in a thread: MRI enqueues a SystemExit that
+  # escapes a non-main thread onto the MAIN thread, which re-raises it wherever
+  # that thread happens to be. A worker must therefore `rescue Exception`, not
+  # `rescue Everywhere::Fatal` — see TaskPool.
+  class Fatal < SystemExit
+    def initialize(status = 1, message = nil) = super
+  end
+end