ruby_everywhere 0.6.0 → 0.8.0

data/lib/everywhere/commands/dev.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
 require "dry/cli"
-require "socket"
 require "shellwords"
 require "fileutils"
 require_relative "../shellout"
-require_relative "../paths"
-require_relative "../icon"
-require_relative "../desktop_assets"
+require_relative "../host"
+require_relative "../desktop_dev_app"
+require_relative "../raw_tty"
 require_relative "../builders/ios"
 require_relative "../builders/android"
 require_relative "../builders/desktop"
@@ -15,8 +14,8 @@ require_relative "../simulator"
 require_relative "../emulator"
 require_relative "../console"
 require_relative "../child_processes"
+require_relative "../child_supervision"
 require_relative "../task_pool"
-require_relative "../relay"
 require_relative "../dock"
 require_relative "../log_filter"
 require_relative "logs"
@@ -37,6 +36,8 @@ module Everywhere
     # Dock keeps the keymap and every target's state pinned to the bottom of the
     # terminal while the logs scroll above it.
     class Dev < Dry::CLI::Command
+      include ChildSupervision
+
       desc "Run the dev server with native shells on demand (live reload, no packaging)"
 
       IOS_TARGET = "ios-arm64"
@@ -58,12 +59,9 @@ module Everywhere
       def call(port: "3000", shell_dir: nil, target: nil, desktop: false, ios: false, android: false,
                mobile: false, browser: false, dev_url: nil, **)
         @shell_dir = shell_dir
-        @port = port
+        port = @port = validate_port!(port)
         @dev_url_override = dev_url
-        # Children are spawned from pool threads as well as the main one.
-        @pids = {}
-        @relays = {}
-        @children = Mutex.new
+        init_children!
         targets = requested_targets(target, desktop: desktop, ios: ios, android: android,
                                             mobile: mobile, browser: browser)
         @framework, @config = detect_app
@@ -127,6 +125,12 @@ module Everywhere
           UI.die!("no supported framework here (Rails, Hanami, Sinatra) and no remote.url in " \
                   "config/everywhere.yml — nothing to run")
         end
+
+        # The bundle id keys every per-app dir under ~/.rubyeverywhere that the
+        # session stages into, so it's checked before anything is written.
+        errors = config.identity_errors
+        UI.die!("app: in config/everywhere.yml:\n#{errors.join("\n")}") unless errors.empty?
+
         [framework, config]
       end
 
@@ -147,8 +151,8 @@ module Everywhere
         else
           UI.step("starting #{UI.bold(framework.name)} dev server #{UI.dim("(" + framework.dev_command + ")")}")
           @dock.set(:web, :booting)
-          supervise(:web, { "PORT" => port.to_s }, framework.dev_command, chdir: framework.root)
-          wait_for_port(port)
+          pid = supervise(:web, { "PORT" => port.to_s }, framework.dev_command, chdir: framework.root)
+          wait_for_port(port, pid: pid)
           @dock.set(:web, :running, detail: ":#{port}")
         end
       end
@@ -186,6 +190,15 @@ module Everywhere
         end
       end
 
+      # Everything the running desktop shell is staged out of: the assets, the
+      # Dock icon, the throwaway .app it runs from. Memoized because a restart
+      # restages all of it against the same config.
+      def desktop_dev_app = @desktop_dev_app ||= DesktopDevApp.new(config: @config)
+
+      def dev_bundle_name = desktop_dev_app.dev_bundle_name
+
+      def dev_info_plist = desktop_dev_app.dev_info_plist
+
       # `d` relaunches, the same way `i` and `a` do — quit the running window and
       # open a fresh one. Refusing with "already running" made the desktop the
       # odd one out, and left no way to restart a shell that had wedged or was
@@ -193,85 +206,13 @@ module Everywhere
       #
       # The rebuild is free either way: a warm `cargo run` re-checks the crate
       # graph in well under a second before handing off.
-      # native/desktop/assets/** → the staged flat folder the running shell
-      # reads. Runs the same compiler `every build` does, so an asset that
-      # resolves in dev resolves in the packaged app too. Returns
-      # [dir, errors]; the dir is returned even when the app ships no assets,
-      # because the shell only has to cope with it not existing.
-      def stage_desktop_assets
-        dest = Everywhere::Paths.desktop_assets_dir(@config.bundle_id)
-        source = File.join(@config.root, "native", "desktop", "assets")
-        _names, errors = Everywhere::DesktopAssets.write!(source, dest)
-        [dest, errors]
-      end
-
-      # A minimal .app around the dev binary, so macOS has a CFBundleName to
-      # read. Without it every menu that names the app says "example-shell" —
-      # the crate name — because an unbundled process has nothing else to go on.
-      # (Setting NSProcessInfo's processName at runtime does NOT fix this: the
-      # menu bar and the predefined About/Hide/Quit items are built from the
-      # bundle, and macOS has already decided by the time any Rust runs.)
-      #
-      # Only the plist matters here. No icon is stamped: the shell sets the Dock
-      # icon at runtime from NATIVE_ICON_PATH, because Tauri applies its own
-      # compiled-in icon after launch and would win over a bundle icns anyway.
-      # `every build` writes the real, complete plist — this is the dev subset.
-      def stage_dev_bundle
-        app = File.join(Everywhere::Paths.desktop_dev_app_dir(@config.bundle_id),
-                        "#{@config.name}.app")
-        macos = File.join(app, "Contents", "MacOS")
-        FileUtils.mkdir_p(macos)
-        File.write(File.join(app, "Contents", "Info.plist"), dev_info_plist)
-        [app, File.join(macos, dev_exe_name)]
-      end
-
-      # Spaces are legal in CFBundleExecutable but a nuisance in every shell
-      # command that names it, so the executable follows the packaged app's
-      # convention and drops them.
-      def dev_exe_name = @config.name.gsub(/\s+/, "")
-
-      def dev_info_plist
-        <<~PLIST
-          <?xml version="1.0" encoding="UTF-8"?>
-          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-          <plist version="1.0">
-          <dict>
-            <key>CFBundleName</key><string>#{@config.name}</string>
-            <key>CFBundleDisplayName</key><string>#{@config.name}</string>
-            <key>CFBundleExecutable</key><string>#{dev_exe_name}</string>
-            <key>CFBundleIdentifier</key><string>#{@config.bundle_id}</string>
-            <key>CFBundlePackageType</key><string>APPL</string>
-            <key>CFBundleShortVersionString</key><string>#{@config.version}</string>
-            <key>NSHighResolutionCapable</key><true/>
-          </dict>
-          </plist>
-        PLIST
-      end
-
-      # The Dock icon for the running shell. `cargo run` produces a bare binary
-      # with no .app around it, so macOS has nothing to read an icon from and
-      # Tauri's compiled-in placeholder wins — which is how you end up staring
-      # at the gem's icon while testing your own app.
-      #
-      # Shaped with the same Big Sur inset + squircle the packaged .icns gets
-      # (Icon.macos_master), so the Dock looks identical in dev and in a release
-      # build rather than subtly rounder in one of them. Returns "" when the app
-      # has no icon — the shell reads that as "leave it alone".
-      def stage_desktop_icon
-        source = @config.icon
-        return "" unless source && File.exist?(source)
-
-        dest = File.join(Everywhere::Paths.desktop_icon_dir(@config.bundle_id), "icon.png")
-        FileUtils.mkdir_p(File.dirname(dest))
-        FileUtils.cp(source, dest) unless Everywhere::Icon.macos_master(source, dest)
-        dest
-      rescue StandardError => e
-        # A Dock icon is never worth failing a dev session over.
-        UI.warn("couldn't prepare the Dock icon (#{e.class}) — using the default")
-        ""
-      end
-
       def launch_desktop
+        # Checked before anything is staged: without cargo the build dies deep
+        # in a relayed `sh: cargo: command not found`, after a dock entry and a
+        # half-written dev bundle say a shell is on its way.
+        Shellout.ensure_tool!("cargo", "the desktop shell is built with Rust — install it from " \
+                                       "https://rustup.rs, then press d again")
+
         # A bad `window:` or a broken assets/ tree marks the desktop red and
         # leaves the dev server and the mobile shells alone — the same deal
         # every other target gets when its build fails. Dying here would take
@@ -284,7 +225,7 @@ module Everywhere
           return
         end
 
-        assets_dir, asset_errors = stage_desktop_assets
+        assets_dir, asset_errors = desktop_dev_app.stage_desktop_assets
         unless asset_errors.empty?
           asset_errors.each { |error| UI.warn(error) }
           @dock.set(:desktop, :failed, detail: "native/desktop/assets")
@@ -320,10 +261,10 @@ module Everywhere
         supervise(:desktop,
                   { "NATIVE_DEV_URL" => @dev_url, "NATIVE_CONFIG" => @config.to_shell_json,
                     "NATIVE_ASSETS_DIR" => assets_dir,
-                    "NATIVE_ICON_PATH" => stage_desktop_icon,
+                    "NATIVE_ICON_PATH" => desktop_dev_app.stage_desktop_icon,
                     "CARGO_TARGET_DIR" => prepared.target_dir,
                     "CARGO_TERM_COLOR" => "always" },
-                  desktop_command(prepared), chdir: prepared.dir,
+                  desktop_dev_app.desktop_command(prepared), chdir: prepared.dir,
                   filter: LogFilter.for(:cargo), log: dist_log("desktop-dev.log"),
                   # cargo colors its status lines, so the marker has to be
                   # matched past the escape codes. "Finished" is cargo's last
@@ -334,37 +275,21 @@ module Everywhere
                   })
       end
 
-      # macOS runs the shell from inside a throwaway .app so it has a name;
-      # everywhere else `cargo run` is still the whole story.
-      #
-      # Three steps in one command rather than three Ruby calls, because the
-      # link has to happen between the compile and the launch and we want ONE
-      # supervised child: cargo's progress relays into the dock, and exec then
-      # replaces it with the app, so the pid we're tracking is the window.
-      #
-      # A hard link, not a copy: same volume (both under ~/.rubyeverywhere), so
-      # it's free and instant, where copying a debug Tauri binary is ~100MB on
-      # every launch. cargo replaces the file on rebuild rather than writing
-      # through it, so the link is remade each time — hence `ln -f`.
-      def desktop_command(prepared)
-        return "cargo run" unless RUBY_PLATFORM.include?("darwin")
-
-        _app, exe = stage_dev_bundle
-        built = File.join(prepared.target_dir, "debug", "example-shell")
-        [
-          "cargo build",
-          "{ ln -f #{built.shellescape} #{exe.shellescape} 2>/dev/null || " \
-            "cp -f #{built.shellescape} #{exe.shellescape}; }",
-          "exec #{exe.shellescape}"
-        ].join(" && ")
-      end
-
       # Build the shell (Debug, warm after the first run), put it on a booted
       # Simulator and hand it the dev URL. The Simulator shares the Mac's
       # loopback, so 127.0.0.1 works as-is; the template's ATS exception
       # covers plain http for local networking. Pressing i again rebuilds and
       # relaunches, so it doubles as a native-shell reload.
       def launch_ios
+        # xcodebuild and simctl are macOS-only, so `i` elsewhere can only ever
+        # produce a long build that fails at the first tool. Android stays
+        # available everywhere — its toolchain genuinely is cross-platform.
+        unless Host.darwin?
+          UI.warn("iOS builds need macOS and Xcode — #{UI.dim("nothing to do on this platform")}")
+          @dock.set(:ios, :idle, detail: "needs macOS")
+          return
+        end
+
         @dock.set(:ios, :building)
         app = Builders::Ios.new(config: @config, root: @config.root, target: IOS_TARGET)
                            .build!(dist_dir: File.expand_path("dist", @config.root), dev: true)
@@ -406,7 +331,22 @@ module Everywhere
 
       def launch_browser
         UI.step("opening browser → #{UI.cyan(@dev_url)}")
-        opener = RUBY_PLATFORM.include?("darwin") ? "open" : "xdg-open"
+        # `start` is a cmd builtin, not an executable, so it can't be probed or
+        # spawned directly; the empty "" is the window title argument, without
+        # which cmd reads the URL as one.
+        if Gem.win_platform?
+          system("cmd", "/c", "start", "", @dev_url)
+          return
+        end
+
+        opener = Host.darwin? ? "open" : "xdg-open"
+        # A headless Linux box (or WSL) has no xdg-open, and run? would just
+        # return nil — the key would look broken. Print the URL instead.
+        unless Shellout.tool?(opener)
+          UI.warn("couldn't find #{opener} — open #{UI.cyan(@dev_url)} yourself")
+          return
+        end
+
         Shellout.run?(opener, @dev_url, quiet: true)
       end
 
@@ -431,109 +371,51 @@ module Everywhere
 
       # --- child supervision ----------------------------------------------------
 
-      # Spawn a long-lived child on a pty and relay its output, one tagged line
-      # at a time. A pty rather than a pipe so foreman, cargo and friends still
-      # believe they're on a terminal and keep their colors; PTY.spawn also
-      # setsids, so a Ctrl-C at our terminal can't reach them and teardown
-      # decides when they die.
-      def supervise(key, env, cmd, chdir:, filter: nil, log: nil, on_line: nil)
-        if Shellout.pty?
-          io, pid = Shellout.spawn_pty(env, cmd, chdir: chdir)
-          thread = relay_thread(key, io, pid, filter: filter, log: log, on_line: on_line)
-        else
-          # Windows, or any platform without a pty: fall back to inherited fds.
-          # No tags and no dock framing, but everything else works.
-          pid = Shellout.spawn(env, cmd, chdir: chdir)
-        end
-        Process.detach(pid)
-        @children.synchronize do
-          @pids[key] = pid
-          @relays[key] = thread if thread
-        end
-        pid
-      end
+      def spawn_child(env, cmd, chdir:)
+        return Shellout.spawn_pty(env, cmd, chdir: chdir) if Shellout.pty?
 
-      def relay_thread(key, io, pid, filter:, log:, on_line:)
-        Thread.new do
-          Thread.current.name = "relay-#{key}"
-          Thread.current.report_on_exception = false
-          begin
-            Relay.new(io, source: key, log: log, filter: filter, on_line: on_line).run
-          rescue StandardError => e
-            # Losing a relay costs us that child's output, nothing more. It must
-            # not surface later out of the join in teardown.
-            Kernel.warn("#{key} output relay stopped: #{e.class}: #{e.message}")
-          end
-          # Only report a death we didn't ask for. stop_child removes the pid
-          # BEFORE it signals, so a deliberate restart can never match here —
-          # what does match is a shell that quit or crashed on its own, which is
-          # exactly what the dock should show.
-          @dock.set(key, :stopped) if !@stopping && @children.synchronize { @pids[key] } == pid
-        end
+        # Windows, or any platform without a pty: fall back to inherited fds.
+        # No tags and no dock framing, but everything else works.
+        [nil, Shellout.spawn(env, cmd, chdir: chdir)]
       end
 
-      # TERM the child's whole process group, escalate to KILL, and wait for the
-      # relay to drain so its last lines aren't lost. The pid is dropped from
-      # the registry FIRST, so the relay knows this death was asked for.
-      def stop_child(key, grace: 5)
-        pid, thread = @children.synchronize { [@pids.delete(key), @relays.delete(key)] }
-        return unless pid
-
-        reap([pid], grace: grace)
-        thread&.join(1)
+      # The extra advice an `every dev` failure carries: this is the app's own
+      # bin/dev, run from the app's own checkout, so the two usual explanations
+      # are worth naming.
+      def wait_for_port(port, pid: nil, timeout: 60,
+                        dead_hint: " (did `bundle install` run? does bin/dev's foreman exist?)",
+                        slow_hint: " — it may just be slow to boot; check its output above")
+        super
       end
 
-      # TERM each process group, wait for them together rather than serially,
-      # then KILL the stragglers.
-      def reap(pids, grace: 5)
-        live = pids.compact.select { |pid| ChildProcesses.alive?(pid) }
-        return if live.empty?
-
-        live.each { |pid| ChildProcesses.signal(pid, "TERM") }
-        deadline = monotonic + grace
-        sleep(0.1) while live.any? { |pid| ChildProcesses.alive?(pid) } && monotonic < deadline
-        live.select { |pid| ChildProcesses.alive?(pid) }.each { |pid| ChildProcesses.signal(pid, "KILL") }
+      # Only report a death we didn't ask for. stop_child removes the pid
+      # BEFORE it signals, so a deliberate restart can never match here —
+      # what does match is a shell that quit or crashed on its own, which is
+      # exactly what the dock should show.
+      def on_child_exit(key, pid)
+        @dock.set(key, :stopped) if !@stopping && @children.synchronize { @pids[key] } == pid
       end
 
-      def child_pid(key) = @children.synchronize { @pids[key] }
-
       # --- the key menu ---------------------------------------------------------
 
-      # io/console's getch holds full raw mode while blocked, which clears OPOST
-      # and stair-steps every log line we relay; stty -icanon -echo disables only
-      # line buffering and echo, leaving output processing (and Ctrl-C as SIGINT)
-      # intact. Builds no longer run on this thread, so the menu stays responsive
+      # Builds no longer run on this thread, so the menu stays responsive
       # while one is going — including `q`.
       def interact
         @dock.announce_keys
-        saved_tty = `stty -g`.chomp
-        system("stty", "-icanon", "-echo")
-        trap_exit_signals
-        loop do
-          case $stdin.getc
-          when "d"                then background(:desktop) { launch_desktop }
-          when "i"                then background(:ios)     { launch_ios }
-          when "a"                then background(:android) { launch_android }
-          when "b"                then launch_browser
-          when "l"                then toggle_logs
-          when "r"                then background(:web)     { restart_server }
-          when "?"                then @dock.toggle_help
-          when "q", "\u0004", nil then break # q, Ctrl-D, EOF (Ctrl-C stays a real SIGINT)
+        RawTty.with do
+          loop do
+            case $stdin.getc
+            when "d"                then background(:desktop) { launch_desktop }
+            when "i"                then background(:ios)     { launch_ios }
+            when "a"                then background(:android) { launch_android }
+            when "b"                then launch_browser
+            when "l"                then toggle_logs
+            when "r"                then background(:web)     { restart_server }
+            when "?"                then @dock.toggle_help
+            when "q", "\u0004", nil then break # q, Ctrl-D, EOF (Ctrl-C stays a real SIGINT)
+            end
           end
         end
-      ensure
-        system("stty", saved_tty) unless saved_tty.to_s.empty?
-      end
-
-      # The dock hides the cursor and the key loop puts the tty in -icanon
-      # -echo; a SIGTERM that skipped our ensure blocks would leave the user's
-      # shell in that state. exit(1) from a trap unwinds normally, which is all
-      # this needs to do — a handler must stay this small, because anything that
-      # takes a lock (Console, the dock) raises ThreadError in trap context.
-      def trap_exit_signals
-        %w[TERM HUP].each { |sig| Signal.trap(sig) { exit(1) } }
-      rescue ArgumentError
-        nil
       end
 
       # --- headless -------------------------------------------------------------
@@ -579,26 +461,8 @@ module Everywhere
 
       # --- teardown -------------------------------------------------------------
 
-      # Teardown must never raise — it runs from an ensure, where an exception
-      # would mask whatever actually ended the session — and one failed step
-      # must not skip the rest, or a child survives the CLI that spawned it.
       def teardown
-        @stopping = true
-        pids, relays = @children ? @children.synchronize { [@pids.values, @relays.values] } : [[], []]
-        [
-          -> { @dock&.close },
-          -> { @pool&.shutdown },
-          # TERM everything, then give it a moment and KILL whatever is left.
-          # The CLI exits the instant this returns, so anything still alive is
-          # orphaned — and a windowed shell is exactly the kind of child that
-          # doesn't drop dead on the first signal.
-          -> { reap(pids, grace: 2) },
-          -> { relays.each { |thread| thread.join(1) } }
-        ].each do |step|
-          step.call
-        rescue StandardError => e
-          Kernel.warn("teardown: #{e.class}: #{e.message}")
-        end
+        teardown_children(before: [-> { @dock&.close }, -> { @pool&.shutdown }])
       end
 
       # --- helpers --------------------------------------------------------------
@@ -610,21 +474,6 @@ module Everywhere
       rescue StandardError
         nil
       end
-
-      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-      def port_open?(port)
-        TCPSocket.new("127.0.0.1", Integer(port)).close
-        true
-      rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT
-        false
-      end
-
-      def wait_for_port(port, timeout: 60)
-        deadline = Time.now + timeout
-        sleep 0.5 until port_open?(port) || Time.now > deadline
-        UI.die!("dev server never came up on port #{port}") unless port_open?(port)
-      end
     end
   end
 end

data/lib/everywhere/commands/doctor.rb

@@ -2,49 +2,167 @@
 
 require "dry/cli"
 require_relative "../shellout"
+require_relative "../host"
 require_relative "../paths"
+require_relative "../config"
 require_relative "../android_sdk"
 
 module Everywhere
   module Commands
-    # Check that this machine can build native apps. Desktop checks always
-    # run; the iOS and Android sections join in when the app's build.targets
-    # include such a target, or explicitly via --target ios-* / android-*.
+    # Check that this machine can build native apps. Every section always
+    # shows, so one run answers "what can this machine build?" — but only the
+    # sections the app's build.targets declare (or --target names) gate the
+    # exit status: failing doctor over a toolchain the app doesn't use would
+    # be a lie, the same reasoning as the cmdline-tools warning below.
     class Doctor < Dry::CLI::Command
       desc "Check the toolchain (rbe-tebako, rust, brew deps; Xcode for iOS, SDK/JDK for Android)"
 
-      option :root,   default: ".", desc: "App root (its build.targets pick the sections)"
-      option :target, default: nil, desc: "Also check a specific target's toolchain (e.g. ios-arm64)"
+      option :root,   default: ".", desc: "App root (its build.targets pick which sections are required)"
+      option :target, default: nil, desc: "Require a specific target's toolchain (e.g. ios-arm64)"
 
       def call(root: ".", target: nil, **)
-        ok = true
-        ok &= check("rbe-tebako installed") { Shellout.run?("rbe-tebako help > /dev/null 2>&1") }
-        ok &= check("cargo installed")    { Shellout.run?("cargo --version > /dev/null 2>&1") }
-        ok &= check("homebrew bison")     { !`brew --prefix bison 2>/dev/null`.strip.empty? }
+        ok = config_check(root)
 
-        ok &= ios_checks if ios_wanted?(root, target)
-        ok &= android_checks if android_wanted?(root, target)
+        @optional_gaps = []
+        sections = [
+          ["Desktop", desktop_wanted?(root, target), method(:desktop_checks)],
+          ["iOS",     ios_wanted?(root, target),     method(:ios_checks)],
+          ["Android", android_wanted?(root, target), method(:android_checks)]
+        ]
+        # The sections that gate the run are the ones the user came to fix, so
+        # they come first; the informational ones read as an appendix.
+        # partition, not sort_by — Ruby's sort isn't stable.
+        required_sections, info_sections = sections.partition { |_, required, _| required }
+        (required_sections + info_sections).each do |name, required, checks|
+          ok &= section(name, required: required) { |req| checks.call(req) }
+        end
 
         puts
-        ok ? UI.success("ready to build") : UI.bad("fix the items above (see https://rubyeverywhere.com/docs/diy/requirements)")
+        if ok
+          note = @optional_gaps.any? ? " #{UI.dim("(#{@optional_gaps.join(" and ")} would need setup — see above)")}" : ""
+          UI.success("ready to build#{note}")
+        else
+          UI.bad("fix the items above (see https://rubyeverywhere.com/docs/diy/requirements)")
+        end
         exit(1) unless ok
       end
 
       private
 
+      # A section always renders; only a required one can fail the run. An
+      # optional section's gaps are remembered for the summary line instead.
+      def section(name, required:)
+        passed = yield(required)
+        @optional_gaps << name if !passed && !required
+        required ? passed : true
+      end
+
+      def section_label(name, required)
+        required ? name : "#{name} #{UI.dim("(not in build.targets — informational)")}"
+      end
+
+
+      # Desktop is the implicit default: an app with no build.targets presses
+      # for the host. Any non-mobile target (or --target) counts as desktop,
+      # mirroring how build/dev route targets.
+      def desktop_wanted?(root, target)
+        return true if target && !%w[ios android].include?(Everywhere::Config.os_of(target))
+
+        targets = config(root).targets
+        targets.empty? || targets.any? { |t| !%w[ios android].include?(Everywhere::Config.os_of(t)) }
+      rescue StandardError
+        true
+      end
+
+      def desktop_checks(required = true)
+        puts
+        UI.step(section_label("Desktop target", required))
+        # Mirrors the gate in `every build`: pressing is macOS-only today, so
+        # probing for its toolchain elsewhere would only mislead.
+        unless Host.darwin?
+          return fix_check("macOS", "desktop builds are macOS-only for now") { false } if required
+
+          UI.warn("desktop builds are macOS-only for now — skipped")
+          return false
+        end
+
+        ok = fix_check("rbe-tebako installed",
+                       "it ships as a dependency of ruby_everywhere: `gem install rbe-tebako` " \
+                       "(or reinstall the gem)") { Shellout.run?("rbe-tebako help > /dev/null 2>&1") }
+        ok &= fix_check("cargo installed", "install Rust: https://rustup.rs") do
+          Shellout.run?("cargo --version > /dev/null 2>&1")
+        end
+        ok &= fix_check(bison_label, bison_hint) { bison? }
+        ok
+      end
+
+      # macOS ships a bison far too old for tebako's build, so there the brew
+      # one is the only one that counts — and asking brew is the only way to see
+      # it, since it stays off PATH (keg-only). Everywhere else the package
+      # manager installs a current bison normally.
+      def bison?
+        return Shellout.tool?("bison") unless Host.darwin?
+
+        out, status = Shellout.capture("brew", "--prefix", "bison")
+        !status.nil? && status.success? && !out.strip.empty?
+      end
+
+      def bison_label = Host.darwin? ? "homebrew bison" : "bison"
+      def bison_hint  = Host.darwin? ? "brew install bison" : "install bison with your package manager"
+
+      # Config.load raises on an unparseable everywhere.yml; doctor reports it
+      # as its first check and carries on with an empty config, so the machine
+      # that most needs the rest of the report still gets it. The load happens
+      # once, here, and every later reader gets what it produced.
+      def config_check(root)
+        return true unless File.exist?(File.join(File.expand_path(root), Everywhere::Config::FILE))
+
+        config(root)
+        if @config_error
+          UI.bad(@config_error)
+          return false
+        end
+
+        UI.ok(Everywhere::Config::FILE)
+        true
+      end
+
+      def config(root)
+        return @config if defined?(@config)
+
+        @config_error = nil
+        @config = begin
+          Everywhere::Config.load(File.expand_path(root))
+        rescue StandardError, SystemExit => e
+          @config_error = e.message
+          Everywhere::Config.new({}, File.expand_path(root))
+        end
+      end
+
       def ios_wanted?(root, target)
         return true if target && Everywhere::Config.os_of(target) == "ios"
 
-        Everywhere::Config.load(File.expand_path(root)).targets
-                          .any? { |t| Everywhere::Config.os_of(t) == "ios" }
+        config(root).targets.any? { |t| Everywhere::Config.os_of(t) == "ios" }
       rescue StandardError
         false
       end
 
-      def ios_checks
+      def ios_checks(required = true)
         puts
-        UI.step("iOS target")
-        ok = check("full Xcode selected") { Shellout.run?("xcodebuild -version > /dev/null 2>&1") }
+        UI.step(section_label("iOS target", required))
+        # Off macOS every tool below is guaranteed absent — one honest line
+        # beats four unfixable ✗s.
+        unless Host.darwin?
+          return fix_check("macOS with Xcode", "iOS apps can only be built on a Mac") { false } if required
+
+          UI.warn("needs macOS and Xcode — skipped")
+          return false
+        end
+
+        ok = fix_check("full Xcode selected",
+                       "install Xcode and run `sudo xcode-select -s /Applications/Xcode.app`") do
+          Shellout.run?("xcodebuild -version > /dev/null 2>&1")
+        end
         ok &= check("iOS Simulator SDK") do
           Shellout.run?("xcrun", "--sdk", "iphonesimulator", "--show-sdk-path", quiet: true)
         end
@@ -69,8 +187,7 @@ module Everywhere
       def android_wanted?(root, target)
         return true if target && Everywhere::Config.os_of(target) == "android"
 
-        Everywhere::Config.load(File.expand_path(root)).targets
-                          .any? { |t| Everywhere::Config.os_of(t) == "android" }
+        config(root).targets.any? { |t| Everywhere::Config.os_of(t) == "android" }
       rescue StandardError
         false
       end
@@ -80,9 +197,9 @@ module Everywhere
       # without exporting any of them, so a `which adb` would report a broken
       # machine that in fact builds fine. Nothing auto-installs — SDK components
       # are gigabytes — so each failure carries the exact command to run.
-      def android_checks
+      def android_checks(required = true)
         puts
-        UI.step("Android target")
+        UI.step(section_label("Android target", required))
         sdk = Everywhere::AndroidSdk
         root = sdk.sdk_root