ruby_everywhere 0.4.0 → 0.5.0

data/lib/everywhere/dock/footer.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "../ui"
+
+module Everywhere
+  class Dock
+    # Renders the pinned footer. PURE: state in, array of strings out. No IO, no
+    # clock, no terminal — every layout decision here is testable with plain
+    # string assertions.
+    #
+    # Composition rule: build every segment as PLAIN text, measure it, truncate,
+    # and only then paint. Measuring or cutting a string that already contains
+    # SGR codes is how you end up slicing through "\e[32" and corrupting the
+    # terminal, and it makes the width math quietly wrong under NO_COLOR.
+    module Footer
+      # Every state gets its own glyph, so the footer stays fully legible with
+      # NO_COLOR — color is redundant reinforcement, never the only signal.
+      # A nil glyph means "use the spinner frame".
+      GLYPHS = {
+        idle: ["○", :gray],
+        booting: [nil, :cyan],
+        building: [nil, :cyan],
+        installing: [nil, :cyan],
+        running: ["●", :green],
+        failed: ["✗", :red],
+        stopped: ["!", :yellow]
+      }.freeze
+
+      GAP = "   "
+      KEY_GAP = " · "
+      ELLIPSIS = "…"
+
+      module_function
+
+      # targets: Array<State::Target>. elapsed: ->(target) { seconds }.
+      # keys: Array<[key, description]>, or nil to omit the keymap row.
+      def render(targets, cols:, keys: nil, frame: 0, elapsed: nil, rule: true)
+        cols = [cols.to_i, 1].max
+        lines = []
+        lines << UI.gray("─" * cols) if rule
+        lines << status_row(targets, cols, frame, elapsed)
+        lines << keys_row(keys, cols) if keys
+        lines
+      end
+
+      # --- status row ----------------------------------------------------------
+
+      # Three levels of degradation, tried in order until one fits: everything;
+      # details only on what's actually working; then drop idle targets. A hard
+      # truncation is the last resort.
+      def status_row(targets, cols, frame, elapsed)
+        segments = targets.map { |t| segment(t, frame, elapsed) }
+
+        candidates = [
+          segments,
+          segments.map { |s| s[:busy] ? s : s.merge(detail: nil) },
+          segments.select { |s| s[:state] != :idle }
+        ]
+        chosen = candidates.find { |set| plain_width(set) <= cols } || candidates.last
+        fit(chosen.map { |s| [plain(s), painted(s)] }, cols)
+      end
+
+      def segment(target, frame, elapsed)
+        glyph, color = GLYPHS.fetch(target.state, GLYPHS[:idle])
+        { glyph: glyph || UI::FRAMES[frame % UI::FRAMES.size],
+          color: color,
+          label: target.label,
+          detail: detail_for(target, elapsed),
+          state: target.state,
+          busy: target.busy? }
+      end
+
+      # Busy targets carry a running clock — the whole reason the dock exists is
+      # that a cold Gradle build looks identical to a hung one without it.
+      def detail_for(target, elapsed)
+        if target.busy?
+          seconds = elapsed&.call(target)
+          [target.state == :building ? nil : target.state.to_s,
+           (UI.elapsed(seconds) if seconds)].compact.join(" ")
+        else
+          target.detail
+        end
+      end
+
+      def plain(seg)
+        [seg[:glyph], seg[:label], presence(seg[:detail])].compact.join(" ")
+      end
+
+      def painted(seg)
+        tint = UI.method(seg[:color])
+        parts = [tint.call(seg[:glyph]), seg[:state] == :idle ? UI.gray(seg[:label]) : seg[:label]]
+        parts << UI.dim(seg[:detail]) if presence(seg[:detail])
+        parts.join(" ")
+      end
+
+      def plain_width(segments) = segments.sum { |s| plain(s).length } + (GAP.length * [segments.size - 1, 0].max)
+
+      # --- keys row ------------------------------------------------------------
+
+      # Named keys with dot separators, then named keys packed tighter, then
+      # bare letters. Measured on the plain text and painted only once a tier
+      # fits, so the width math can't be thrown off by SGR codes.
+      def keys_row(keys, cols)
+        tiers = [
+          [:named, KEY_GAP],
+          [:named, "  "],
+          [:bare,  " "]
+        ]
+        tiers.each do |style, gap|
+          plain = "⌨ #{keys.map { |key, desc| plain_key(key, desc, style) }.join(gap)}"
+          next unless plain.length <= cols
+
+          painted = keys.map { |key, desc| paint_key(key, desc, style) }.join(gap == KEY_GAP ? UI.gray(gap) : gap)
+          return "#{UI.cyan("⌨")} #{painted}"
+        end
+        ""
+      end
+
+      def plain_key(key, desc, style) = style == :bare ? key : "#{key} #{desc}"
+
+      def paint_key(key, desc, style)
+        style == :bare ? UI.bold(key) : "#{UI.bold(key)} #{UI.dim(desc)}"
+      end
+
+      # --- fitting -------------------------------------------------------------
+
+      # pairs: [[plain, painted], …]. Emit painted segments while they fit,
+      # measuring only the plain text; cut the first one that doesn't.
+      def fit(pairs, cols)
+        out = +""
+        width = 0
+        pairs.each_with_index do |(text, colored), index|
+          gap = index.zero? ? "" : GAP
+          if width + gap.length + text.length <= cols
+            out << gap << colored
+            width += gap.length + text.length
+            next
+          end
+
+          room = cols - width - gap.length - ELLIPSIS.length
+          out << gap << text[0, room] << ELLIPSIS if room.positive?
+          break
+        end
+        out
+      end
+
+      def presence(str) = str.nil? || str.empty? ? nil : str
+    end
+  end
+end

data/lib/everywhere/dock/screen.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Dock
+    # Emits the escape sequences that keep the footer pinned to the bottom.
+    #
+    # THE MECHANIC, and why it isn't the obvious one:
+    #
+    # The tempting approach is DECSTBM — set a scroll region (ESC[1;Nr) that
+    # excludes the last few rows and let the terminal itself keep output off
+    # them. It works, and it even confines child processes writing straight to
+    # the fd. It was rejected for two reasons:
+    #
+    #   1. It destroys scrollback. tmux only copies scrolled-out rows into its
+    #      history when the scroll region is the full screen
+    #      (grid_view_scroll_region_up checks rupper == 0 && rlower == sy - 1);
+    #      screen and, as far as we can tell, iTerm2 behave the same way. Losing
+    #      the ability to scroll up and read a Rails backtrace is a far worse
+    #      regression than the one the dock is fixing.
+    #   2. Its failure mode is terrible. If the CLI is SIGKILLed before it can
+    #      emit ESC[r, the user's terminal keeps a dead band at the bottom until
+    #      they run `reset`.
+    #
+    # So instead we own every byte (the dev server and shells are relayed
+    # through us, not inherited) and repaint: erase the footer rows, write the
+    # new content — which scrolls normally, preserving scrollback everywhere —
+    # then draw the footer again. This is what indicatif, Ink, docker compose
+    # and cargo all do. Worst-case failure is one stale line on screen.
+    #
+    # Everything is emitted as a SINGLE write per frame. Byte interleaving
+    # between processes happens between write(2) calls, not inside one.
+    class Screen
+      ERASE_ROW = "\r\e[2K"        # clear this row, cursor back to column 1
+      UP_ROW    = "\e[1A\e[2K"     # up one row and clear it
+      HIDE      = "\e[?25l"
+      SHOW      = "\e[?25h"
+
+      DEFAULT_SIZE = [24, 80].freeze
+
+      def initialize(io:, size: nil)
+        @io = io
+        @size = size
+        @drawn = 0
+        @open = false
+      end
+
+      def open
+        return if @open
+
+        @open = true
+        @sync = @io.sync
+        @io.sync = true
+        @io.write(HIDE)
+      end
+
+      # content: text to land above the footer (must end in a newline, or be
+      # empty). footer: the rows to pin.
+      def frame(content, footer)
+        return unless @open
+
+        out = +""
+        out << erase
+        out << content
+        out << footer.join("\n")
+        @drawn = footer.length
+        @io.write(out)
+      end
+
+      # Wipe the footer without redrawing it — for anything that has to write
+      # outside our frame discipline (stderr, an interactive child).
+      def clear
+        return unless @open && @drawn.positive?
+
+        @io.write(erase)
+        @drawn = 0
+      end
+
+      def close
+        return unless @open
+
+        @io.write("#{erase}#{SHOW}")
+        @drawn = 0
+        @open = false
+        @io.sync = @sync
+      end
+
+      # Rows and columns, re-read on every resize. IO#winsize is a plain
+      # TIOCGWINSZ ioctl — it does not touch termios, so it is safe alongside
+      # the `stty -icanon -echo` the key loop sets.
+      def size
+        return @size if @size
+
+        require "io/console"
+        @io.winsize
+      rescue StandardError
+        env = [ENV["LINES"].to_i, ENV["COLUMNS"].to_i]
+        env.all?(&:positive?) ? env : DEFAULT_SIZE
+      end
+
+      def rows = size[0]
+      def cols = size[1]
+
+      private
+
+      # Cursor sits at the end of the last footer row; walk back up to column 1
+      # of the first, clearing as we go.
+      def erase
+        return "" if @drawn.zero?
+
+        ERASE_ROW + (UP_ROW * (@drawn - 1))
+      end
+    end
+  end
+end

data/lib/everywhere/dock/state.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Everywhere
+  class Dock
+    # What the dock knows about each thing `every dev` is running. Pure data
+    # with an injected clock, so elapsed times are deterministic under test.
+    class State
+      # Ordered so the dock reads left-to-right the way the session starts up.
+      ORDER = %i[web desktop ios android].freeze
+
+      LABELS = {
+        web: "web",
+        desktop: "desktop",
+        ios: "iOS",
+        android: "Android"
+      }.freeze
+
+      # States that are "in flight" — they get a spinner and a running clock.
+      BUSY = %i[booting building installing].freeze
+
+      Target = Struct.new(:key, :label, :state, :detail, :since, keyword_init: true) do
+        def busy? = BUSY.include?(state)
+      end
+
+      def initialize(keys, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @clock = clock
+        @lock = Mutex.new
+        ordered = ORDER & keys
+        @targets = ordered.to_h do |key|
+          [key, Target.new(key: key, label: LABELS.fetch(key, key.to_s), state: :idle, since: clock.call)]
+        end
+      end
+
+      def set(key, state, detail: nil)
+        @lock.synchronize do
+          target = @targets[key] or return nil
+          # Keep `since` when nothing actually changed, so a repeated
+          # set(:ios, :building) from a retry doesn't reset the elapsed clock.
+          target.since = @clock.call unless target.state == state
+          target.state = state
+          target.detail = detail
+          target
+        end
+      end
+
+      def detail(key, text)
+        @lock.synchronize { @targets[key]&.detail = text }
+      end
+
+      def [](key) = @lock.synchronize { @targets[key] }
+
+      def targets = @lock.synchronize { @targets.values.map(&:dup) }
+
+      def busy? = @lock.synchronize { @targets.each_value.any?(&:busy?) }
+
+      def elapsed(target) = @clock.call - target.since
+    end
+  end
+end

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

@@ -372,7 +372,7 @@ module Everywhere
     # 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 = Shellout.unbundled { Process.spawn(*argv, pgroup: true, out: File::NULL, err: File::NULL) }
+      pid = Process.spawn(Shellout.child_env, *argv, pgroup: true, out: File::NULL, err: File::NULL)
       Process.detach(pid)
       pid
     end
@@ -384,7 +384,7 @@ module Everywhere
     # 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 = Shellout.unbundled { Process.spawn(*argv, out: File::NULL, err: File::NULL) }
+      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)

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

data/lib/everywhere/line_pump.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Everywhere
+  # Turns the raw byte stream off a pty master into whole lines.
+  #
+  # `every dev` relays the dev server and the desktop shell itself so it can tag
+  # each line with its source. That relay has to be line-oriented — a half-line
+  # written to the terminal would leave the cursor mid-row and the dock repaints
+  # from column 1 — but a pty hands over arbitrary chunks, so this buffers.
+  #
+  # Two pty-specific quirks it exists to absorb:
+  #
+  #   * ONLCR. The slave's line discipline turns every LF into CRLF, so lines
+  #     arrive as "text\r\n". The trailing CR is an artifact, not content.
+  #   * In-place rewrites. cargo (and anything with a progress bar) redraws a
+  #     row by writing CR and the new text without a newline. What the terminal
+  #     would have shown is whatever followed the LAST CR, so that is what gets
+  #     emitted — one settled line instead of thirty flickering ones.
+  #
+  # Pure: feed it strings, get lines back. No IO, no threads, no clock beyond
+  # the idle deadline the caller passes in.
+  class LinePump
+    # How long a partial line may sit unterminated before it is emitted anyway.
+    # Without this a progress bar that never writes a newline — or a prompt like
+    # "Overwrite? [Yn]" — would be invisible for as long as it mattered.
+    IDLE_FLUSH = 0.2
+
+    def initialize(idle_flush: IDLE_FLUSH, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      # Bytes in, text out. A pty hands over BINARY, and a chunk boundary can
+      # land in the middle of a multi-byte character, so buffering and splitting
+      # happen on bytes — UTF-8 is self-synchronizing, so a newline is never
+      # inside a character — and each settled line is transcoded on the way out.
+      @buffer = String.new(encoding: Encoding::BINARY)
+      @idle_flush = idle_flush
+      @clock = clock
+      @touched = nil
+    end
+
+    # Feed a chunk; returns the complete lines it produced (without newlines).
+    def <<(chunk)
+      @buffer << chunk.b
+      @touched = @clock.call
+      lines = []
+      while (index = @buffer.index("\n"))
+        raw = @buffer.slice!(0, index + 1)
+        line = settle(raw.chomp("\n"))
+        lines << line if line
+      end
+      lines
+    end
+
+    # Emit a still-unterminated partial line once it has gone quiet. Call this
+    # from the relay loop whenever a read times out.
+    def flush_idle
+      return [] if @buffer.empty?
+      return [] if @touched && (@clock.call - @touched) < @idle_flush
+
+      lines = drain
+      @touched = @clock.call
+      lines
+    end
+
+    # Emit whatever is left, terminated or not. For end-of-stream.
+    def drain
+      return [] if @buffer.empty?
+
+      line = settle(@buffer)
+      @buffer = +""
+      line ? [line] : []
+    end
+
+    def pending? = !@buffer.empty?
+
+    private
+
+    # chomp the ONLCR artifact first, THEN collapse an in-place rewrite —
+    # order matters. Doing it the other way round reads "bar\r" as a rewrite to
+    # the empty string and swallows the line.
+    #
+    # scrub, not just force_encoding: a build tool can emit a stray byte that is
+    # not valid UTF-8, and a String that claims an encoding it doesn't satisfy
+    # raises the moment anything tries to concatenate a tag onto it.
+    def settle(raw)
+      line = raw.chomp("\r")
+      line = line[(line.rindex("\r") + 1)..] if line.include?("\r")
+      line.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+  end
+end