ruflet 0.0.18 → 0.0.20

data/lib/ruflet/cli/run_command.rb

@@ -16,12 +16,16 @@ require "time"
 module Ruflet
   module CLI
     module RunCommand
+      CLIENT_CHANNEL_MANIFEST = "ruflet_client-manifest.json"
+      DEFAULT_CLIENT_UPDATE_INTERVAL = 6 * 60 * 60
+
       def command_run(args)
-        options = { target: "mobile", requested_port: 8550 }
+        options = { target: "mobile", requested_port: 8550, reload: true }
         parser = OptionParser.new do |o|
           o.on("--web") { options[:target] = "web" }
           o.on("--desktop") { options[:target] = "desktop" }
           o.on("--port PORT", Integer) { |v| options[:requested_port] = v }
+          o.on("--no-reload") { options[:reload] = false }
         end
         parser.parse!(args)
 
@@ -44,18 +48,32 @@ module Ruflet
         assets_dir = File.join(File.dirname(script_path), "assets")
         env["RUFLET_ASSETS_DIR"] = assets_dir if File.directory?(assets_dir)
 
+        # The backend serves the web client itself so both share one origin.
+        if options[:target] == "web"
+          web_client_dir = detect_web_client_dir
+          if web_client_dir
+            env["RUFLET_WEB_CLIENT_DIR"] = web_client_dir
+          else
+            warn "Web client build not found and prebuilt download failed."
+            warn "Build one with `ruflet build web`, or set RUFLET_CLIENT_DIR."
+            return 1
+          end
+        end
+
         print_run_banner(target: options[:target], requested_port: options[:requested_port], port: selected_port)
         print_mobile_qr_hint(port: selected_port) if options[:target] == "mobile"
+        print_hot_reload_banner if options[:reload]
 
         gemfile_path = find_nearest_gemfile(Dir.pwd)
-        cmd = build_runtime_command(script_path, gemfile_path: gemfile_path, env: env)
+        cmd = build_runtime_command(script_path, gemfile_path: gemfile_path, env: env, reload: options[:reload])
         return 1 unless cmd
 
-        child_pid = Process.spawn(env, *cmd, pgroup: true)
+        run_state = { child_pid: Process.spawn(env, *cmd, pgroup: true), restart: false }
+        reload_input_thread = options[:reload] ? start_reload_input_thread(run_state) : nil
         launched_client_pids = launch_target_client(options[:target], selected_port)
         forward_signal = lambda do |signal|
           begin
-            Process.kill(signal, -child_pid)
+            Process.kill(signal, -run_state[:child_pid])
           rescue Errno::ESRCH
             nil
           end
@@ -64,15 +82,28 @@ module Ruflet
         previous_int = Signal.trap("INT") { forward_signal.call("INT") }
         previous_term = Signal.trap("TERM") { forward_signal.call("TERM") }
 
-        _pid, status = Process.wait2(child_pid)
-        status.success? ? 0 : (status.exitstatus || 1)
+        loop do
+          _pid, status = Process.wait2(run_state[:child_pid])
+          return status.success? ? 0 : (status.exitstatus || 1) unless run_state[:restart]
+
+          # Full restart requested ("R"): respawn the backend; connected
+          # clients reconnect and re-register on their own (Flet-style).
+          run_state[:restart] = false
+          puts "Restarting app..."
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          run_state[:child_pid] = Process.spawn(env, *cmd, pgroup: true)
+          wait_for_server_boot(selected_port)
+          elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+          puts "Restarted in #{elapsed_ms}ms"
+        end
       ensure
+        reload_input_thread&.kill if defined?(reload_input_thread)
         Signal.trap("INT", previous_int) if defined?(previous_int) && previous_int
         Signal.trap("TERM", previous_term) if defined?(previous_term) && previous_term
 
-        if defined?(child_pid) && child_pid
+        if defined?(run_state) && run_state && run_state[:child_pid]
           begin
-            Process.kill("TERM", -child_pid)
+            Process.kill("TERM", -run_state[:child_pid])
           rescue Errno::ESRCH
             nil
           end
@@ -94,16 +125,111 @@ module Ruflet
 
       private
 
-      def build_runtime_command(script_path, gemfile_path:, env:)
+      def build_runtime_command(script_path, gemfile_path:, env:, reload: false)
+        entry_script = script_path
+        if reload
+          env["RUFLET_APP_SCRIPT"] = script_path
+          env["RUFLET_WATCH_ROOT"] = File.dirname(script_path)
+          env["RUFLET_BOOTSNAP_DIR"] = bootsnap_cache_dir(script_path)
+          entry_script = hot_reload_harness_path
+        end
+
         if gemfile_path
           env["BUNDLE_GEMFILE"] = gemfile_path
           bundle_ready = system(env, RbConfig.ruby, "-S", "bundle", "check", out: File::NULL, err: File::NULL)
           return nil unless bundle_ready || system(env, RbConfig.ruby, "-S", "bundle", "install")
 
-          return [RbConfig.ruby, "-rbundler/setup", script_path]
+          return [RbConfig.ruby, "-rbundler/setup", entry_script]
+        end
+
+        [RbConfig.ruby, entry_script]
+      end
+
+      def hot_reload_harness_path
+        File.expand_path("../hot_reload/harness.rb", __dir__)
+      end
+
+      # Persistent, per-app bootsnap cache so it stays warm across restarts.
+      # Kept under ~/.ruflet (not the project, so nothing to gitignore) and
+      # keyed by app path + Ruby version so bytecode never crosses apps or
+      # incompatible VMs.
+      def bootsnap_cache_dir(script_path)
+        app_key = File.dirname(File.expand_path(script_path)).gsub(/[^a-zA-Z0-9]+/, "-").delete_prefix("-")
+        File.join(Dir.home, ".ruflet", "bootsnap", RUBY_VERSION, app_key)
+      end
+
+      def manual_reload_supported?
+        $stdin.tty? && Signal.list.key?("USR1")
+      end
+
+      def print_hot_reload_banner
+        hint = manual_reload_supported? ? "; press \"r\" to reload, \"R\" to restart" : ""
+        puts "Hot reload: watching *.rb#{hint} (disable with --no-reload)"
+      end
+
+      def start_reload_input_thread(run_state)
+        return nil unless manual_reload_supported?
+
+        Thread.new do
+          loop do
+            key = read_reload_key
+            break if key.nil?
+            break unless handle_reload_command(key, run_state)
+          end
+        rescue StandardError
+          nil
+        end
+      end
+
+      # Single keypress, no Enter required. getch puts the terminal in raw
+      # mode only for the duration of the read; intr keeps Ctrl-C working.
+      def read_reload_key
+        $stdin.getch(intr: true)
+      rescue ArgumentError
+        # Older Rubies without the intr keyword.
+        $stdin.getch
+      rescue StandardError
+        nil
+      end
+
+      # Returns false when the child process is gone and the thread should end.
+      def handle_reload_command(command, run_state)
+        case command
+        when "r"
+          Process.kill("USR1", run_state[:child_pid])
+        when "R"
+          run_state[:restart] = true
+          Process.kill("TERM", -run_state[:child_pid])
+          escalate_child_shutdown(run_state[:child_pid])
         end
+        true
+      rescue Errno::ESRCH
+        run_state[:restart] = false
+        false
+      end
 
-        [RbConfig.ruby, script_path]
+      # An app can block TERM (bad traps, stuck threads); force the restart
+      # through with KILL if the child is still running after the grace period.
+      def escalate_child_shutdown(child_pid, grace_seconds: 3)
+        Thread.new do
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + grace_seconds
+          loop do
+            sleep 0.1
+            begin
+              Process.kill(0, child_pid)
+            rescue Errno::ESRCH
+              break
+            end
+            next unless Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+            begin
+              Process.kill("KILL", -child_pid)
+            rescue Errno::ESRCH
+              nil
+            end
+            break
+          end
+        end
       end
 
       def apply_local_ruflet_dev_overrides(env)
@@ -174,34 +300,24 @@ module Ruflet
         end
       end
 
+      # The backend serves the web client on its own port, so the client loads
+      # and opens its websocket on the same origin. The explicit url parameter
+      # is kept because prebuilt production clients have no default URL and use
+      # it to select the websocket transport.
       def launch_web_client(port)
-        web_dir = detect_web_client_dir
-        unless web_dir
-          warn "Web client build not found and prebuilt download failed."
-          return []
-        end
-
-        web_port = find_available_port(port + 1)
-        web_pid = Process.spawn("python3", "-m", "http.server", web_port.to_s, "--bind", "127.0.0.1", chdir: web_dir, out: File::NULL, err: File::NULL)
-        Process.detach(web_pid)
-        wait_for_server_boot(web_port)
         backend_url = "http://localhost:#{port}"
-        web_url = "http://localhost:#{web_port}/?#{URI.encode_www_form(url: backend_url)}"
+        web_url = "#{backend_url}/?#{URI.encode_www_form(url: backend_url)}"
         browser_pid = open_in_browser_app_mode(web_url)
         open_in_browser(web_url) if browser_pid.nil?
         puts "Ruflet web client: #{web_url}"
         puts "Ruflet backend ws: ws://localhost:#{port}/ws"
-        [web_pid, browser_pid].compact
-      rescue Errno::ENOENT
-        warn "python3 is required to host web client locally."
-        warn "Install Python 3 and rerun."
-        []
+        [browser_pid].compact
       rescue StandardError => e
         warn "Failed to launch web client: #{e.class}: #{e.message}"
         []
       end
 
-      def wait_for_server_boot(port, timeout_seconds: 10)
+      def wait_for_server_boot(port, timeout_seconds: 10, poll_interval: 0.01)
         Timeout.timeout(timeout_seconds) do
           loop do
             begin
@@ -210,7 +326,7 @@ module Ruflet
               sock.close
               break
             rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-              sleep 0.15
+              sleep poll_interval
             end
           end
         end
@@ -293,7 +409,10 @@ module Ruflet
           return
         end
 
-        pid = Process.spawn(*cmd, out: File::NULL, err: File::NULL)
+        # The Flutter client took the URL as argv; a Ruflet app used as the
+        # client reads RUFLET_URL, so it connects instead of showing its own
+        # launcher. Pass both so either client auto-connects.
+        pid = Process.spawn({ "RUFLET_URL" => url }, *cmd, out: File::NULL, err: File::NULL)
         Process.detach(pid)
         if !pid
           warn "Failed to launch desktop client: #{cmd.first}"
@@ -306,6 +425,38 @@ module Ruflet
         []
       end
 
+      # A Ruflet app used as the preview client builds its native project into
+      # build/client, so its Flutter output is one level deeper than a bare
+      # Flutter client's. Search both, and never assume the app is named
+      # ruflet_client: the bundle takes the app's own display name.
+      def client_build_roots(root)
+        [File.join(root, "build", "client"), root].select { |dir| Dir.exist?(dir) }
+      end
+
+      def executable_file?(path)
+        File.file?(path) && File.executable?(path)
+      end
+
+      # A Flutter project's own web/ folder holds a source index.html, so
+      # index.html alone would match an unbuilt project. Require a compiled
+      # entrypoint as well.
+      WEB_BUILD_MARKERS = %w[flutter_bootstrap.js main.dart.js flutter.js].freeze
+
+      def built_web_client_dir?(dir)
+        return false unless Dir.exist?(dir) && File.file?(File.join(dir, "index.html"))
+
+        WEB_BUILD_MARKERS.any? { |marker| File.file?(File.join(dir, marker)) }
+      end
+
+      def macos_app_executable(app_bundle)
+        macos_dir = File.join(app_bundle, "Contents", "MacOS")
+        return nil unless Dir.exist?(macos_dir)
+
+        Dir.children(macos_dir)
+          .map { |entry| File.join(macos_dir, entry) }
+          .find { |path| executable_file?(path) }
+      end
+
       def detect_desktop_client_command(url)
         root = ENV["RUFLET_CLIENT_DIR"]
         root = File.expand_path("ruflet_client", Dir.pwd) if root.to_s.strip.empty?
@@ -314,28 +465,42 @@ module Ruflet
         return nil unless root && Dir.exist?(root)
 
         host_os = RbConfig::CONFIG["host_os"]
-        if host_os.match?(/darwin/i)
-          release_bin = File.join(root, "build", "macos", "Build", "Products", "Release", "ruflet_client.app", "Contents", "MacOS", "ruflet_client")
-          debug_bin = File.join(root, "build", "macos", "Build", "Products", "Debug", "ruflet_client.app", "Contents", "MacOS", "ruflet_client")
-          prebuilt_bin = File.join(root, "desktop", "ruflet_client.app", "Contents", "MacOS", "ruflet_client")
-          executable = [release_bin, debug_bin].find { |p| File.file?(p) && File.executable?(p) }
-          executable ||= prebuilt_bin if File.file?(prebuilt_bin) && File.executable?(prebuilt_bin)
-          return [executable, url] if executable
-        elsif host_os.match?(/mswin|mingw|cygwin/i)
-          exe = File.join(root, "build", "windows", "x64", "runner", "Release", "ruflet_client.exe")
-          prebuilt = File.join(root, "desktop", "ruflet_client.exe")
-          exe = prebuilt if !File.file?(exe) && File.file?(prebuilt)
-          return [exe, url] if File.file?(exe)
-        else
-          direct = File.join(root, "build", "linux", "x64", "release", "bundle", "ruflet_client")
-          prebuilt_direct = File.join(root, "desktop", "ruflet_client")
-          direct = prebuilt_direct if !File.file?(direct) && File.file?(prebuilt_direct)
-          return [direct, url] if File.file?(direct)
-          bundle_dir = File.join(root, "build", "linux", "x64", "release", "bundle")
-          if Dir.exist?(bundle_dir)
-            candidate = Dir.children(bundle_dir).map { |f| File.join(bundle_dir, f) }
-              .find { |path| File.file?(path) && File.executable?(path) }
-            return [candidate, url] if candidate
+        client_build_roots(root).each do |base|
+          if host_os.match?(/darwin/i)
+            search = %w[Release Debug].map { |config| File.join(base, "build", "macos", "Build", "Products", config) }
+            search << File.join(base, "desktop")
+            search.each do |dir|
+              next unless Dir.exist?(dir)
+
+              Dir.glob(File.join(dir, "*.app")).sort.each do |app_bundle|
+                executable = macos_app_executable(app_bundle)
+                return [executable, url] if executable
+              end
+            end
+          elsif host_os.match?(/mswin|mingw|cygwin/i)
+            search = [
+              File.join(base, "build", "windows", "x64", "runner", "Release"),
+              File.join(base, "desktop")
+            ]
+            search.each do |dir|
+              next unless Dir.exist?(dir)
+
+              exe = Dir.glob(File.join(dir, "*.exe")).sort.find { |path| File.file?(path) }
+              return [exe, url] if exe
+            end
+          else
+            search = [
+              File.join(base, "build", "linux", "x64", "release", "bundle"),
+              File.join(base, "desktop")
+            ]
+            search.each do |dir|
+              next unless Dir.exist?(dir)
+
+              candidate = Dir.children(dir).sort
+                .map { |entry| File.join(dir, entry) }
+                .find { |path| executable_file?(path) }
+              return [candidate, url] if candidate
+            end
           end
         end
 
@@ -349,10 +514,11 @@ module Ruflet
         root ||= ensure_prebuilt_client(web: true)
         return nil unless root && Dir.exist?(root)
 
-        built = File.join(root, "build", "web")
-        return built if Dir.exist?(built) && File.file?(File.join(built, "index.html"))
-        prebuilt = File.join(root, "web")
-        return prebuilt if Dir.exist?(prebuilt) && File.file?(File.join(prebuilt, "index.html"))
+        client_build_roots(root).each do |base|
+          [File.join(base, "build", "web"), File.join(base, "web")].each do |dir|
+            return dir if built_web_client_dir?(dir)
+          end
+        end
 
         nil
       end
@@ -371,17 +537,29 @@ module Ruflet
           return nil if desktop_asset.nil?
           wanted_assets << { kind: :desktop, name: desktop_asset, platform: platform }
         end
-        if !force && (wanted_assets.empty? || prebuilt_assets_present?(cache_root, web: web, desktop: desktop, platform: platform))
+        cache_ready = wanted_assets.empty? || prebuilt_assets_present?(cache_root, web: web, desktop: desktop, platform: platform)
+        release = nil
+        if !force && cache_ready
           ensure_client_manifest(cache_root, platform: platform)
-          return cache_root
+          manifest = read_client_manifest(cache_root)
+          return cache_root unless client_update_due?(manifest)
+
+          release = fetch_release_for_version(wanted_assets: wanted_assets)
+          if release.nil? || client_release_current?(manifest, release, wanted_assets)
+            mark_client_update_checked(cache_root)
+            return cache_root
+          end
+
+          force = true
         end
 
-        release = fetch_release_for_version
+        release ||= fetch_release_for_version(wanted_assets: wanted_assets)
         return nil unless release
 
         assets = release.fetch("assets", [])
         asset_names = assets.map { |a| a["name"].to_s }
         installed_assets = []
+        release_revision = client_release_revision(release)
         Dir.mktmpdir("ruflet-prebuilt-") do |tmpdir|
           wanted_assets.each do |wanted|
             asset_name = wanted.fetch(:name)
@@ -408,7 +586,8 @@ module Ruflet
               "kind" => wanted[:kind].to_s,
               "platform" => wanted[:platform] || platform,
               "asset_name" => resolved_name,
-              "download_url" => asset.fetch("browser_download_url")
+              "download_url" => asset.fetch("browser_download_url"),
+              "release_revision" => release_revision
             }
           end
         end
@@ -467,12 +646,71 @@ module Ruflet
         File.join(Dir.home, ".ruflet", "client", ruflet_version, platform.to_s)
       end
 
-      def fetch_release_for_version
-        release_by_tag("v#{ruflet_version}") ||
-          release_by_tag(ruflet_version) ||
-          release_by_tag("prebuild") ||
-          release_by_tag("prebuild-main") ||
-          release_latest
+      def fetch_release_for_version(wanted_assets: [])
+        releases = []
+        channel = client_release_channel
+        if channel != "stable"
+          rolling = release_by_tag(channel)
+          releases << rolling if rolling && rolling_release_complete?(rolling)
+        end
+        releases << release_by_tag("v#{ruflet_version}")
+        releases << release_by_tag(ruflet_version)
+        releases << release_latest
+        releases.compact.find { |release| release_has_wanted_assets?(release, wanted_assets) }
+      end
+
+      def client_release_channel
+        value = ENV.fetch("RUFLET_CLIENT_CHANNEL", "prebuild-main").to_s.strip
+        value.empty? ? "prebuild-main" : value
+      end
+
+      def rolling_release_complete?(release)
+        release.fetch("assets", []).any? { |asset| asset["name"] == CLIENT_CHANNEL_MANIFEST }
+      end
+
+      def release_has_wanted_assets?(release, wanted_assets)
+        assets = release.fetch("assets", [])
+        wanted_assets.all? do |wanted|
+          assets.any? { |asset| asset["name"] == wanted[:name] } || fallback_release_asset(assets, wanted)
+        end
+      end
+
+      def client_release_revision(release)
+        marker = release.fetch("assets", []).find { |asset| asset["name"] == CLIENT_CHANNEL_MANIFEST }
+        source = marker || release
+        [source["id"], source["updated_at"] || source["published_at"], source["size"]].compact.join(":")
+      end
+
+      def client_release_current?(manifest, release, wanted_assets)
+        return false unless manifest
+
+        revision = client_release_revision(release)
+        targets = Array(manifest["targets"])
+        wanted_assets.all? do |wanted|
+          targets.any? do |target|
+            target["kind"] == wanted[:kind].to_s &&
+              (wanted[:platform].nil? || target["platform"] == wanted[:platform]) &&
+              target["release_revision"] == revision
+          end
+        end
+      end
+
+      def client_update_due?(manifest)
+        return false if ENV["RUFLET_CLIENT_AUTO_UPDATE"].to_s.match?(/\A(?:0|false|no|off)\z/i)
+        return true unless manifest
+
+        checked_at = manifest["checked_at"] || manifest["installed_at"]
+        return true if checked_at.to_s.empty?
+
+        Time.now.utc - Time.iso8601(checked_at) >= client_update_interval
+      rescue ArgumentError
+        true
+      end
+
+      def client_update_interval
+        Integer(ENV.fetch("RUFLET_CLIENT_UPDATE_INTERVAL", DEFAULT_CLIENT_UPDATE_INTERVAL.to_s), 10).clamp(0, 7 * 24 * 60 * 60)
+      rescue ArgumentError
+        DEFAULT_CLIENT_UPDATE_INTERVAL
       end
 
       def ruflet_version
@@ -596,18 +834,36 @@ module Ruflet
 
       def write_client_manifest(root, platform:, release:, assets:)
         FileUtils.mkdir_p(root)
+        existing = read_client_manifest(root) || {}
+        installed_targets = Array(existing["targets"])
+        assets.each do |asset|
+          installed_targets.reject! do |target|
+            target["kind"] == asset["kind"] && target["platform"] == asset["platform"]
+          end
+          installed_targets << asset
+        end
         payload = {
-          "schema" => 1,
+          "schema" => 2,
           "ruflet_version" => ruflet_version,
           "platform" => platform,
-          "release_tag" => release && release["tag_name"],
-          "released_at" => release && release["published_at"],
+          "release_tag" => release && release["tag_name"] || existing["release_tag"],
+          "release_revision" => release && client_release_revision(release) || existing["release_revision"],
+          "released_at" => release && release["published_at"] || existing["released_at"],
+          "checked_at" => Time.now.utc.iso8601,
           "installed_at" => Time.now.utc.iso8601,
-          "targets" => assets
+          "targets" => installed_targets
         }
         File.write(client_manifest_path(root), JSON.pretty_generate(payload))
       end
 
+      def mark_client_update_checked(root)
+        manifest = read_client_manifest(root)
+        return unless manifest
+
+        manifest["checked_at"] = Time.now.utc.iso8601
+        File.write(client_manifest_path(root), JSON.pretty_generate(manifest))
+      end
+
       def print_mobile_qr_hint(port: 8550)
         host = best_lan_host
         payload = "http://#{host}:#{port}"

data/lib/ruflet/cli/templates.rb

@@ -7,7 +7,10 @@ module Ruflet
     Ruflet.run do |page|
       page.title = "Counter Demo"
       count = 0
-      count_text = text(count.to_s, style: {size: 40})
+      count_text = text(
+        value: count.to_s,
+        style: { size: 40, weight: "w700" }
+      )
       page.floating_action_button = fab(
         icon: "add",
         on_click: ->(_e) do
@@ -23,7 +26,7 @@ module Ruflet
             alignment: Ruflet::MainAxisAlignment::CENTER,
             horizontal_alignment: Ruflet::CrossAxisAlignment::CENTER,
             children: [
-              text("You have pushed the button this many times:"),
+              text(value: "You have pushed the button this many times:"),
               count_text
             ]
           )
@@ -54,14 +57,14 @@ module Ruflet
       ## Run
 
       ```bash
-      bundle exec ruflet run main
+      ruflet run main
       ```
 
       ## Build
 
       ```bash
-      bundle exec ruflet build apk
-      bundle exec ruflet build ios
+      ruflet build apk
+      ruflet build ios
       ```
     MD
   end

data/lib/ruflet/cli.rb

@@ -66,14 +66,14 @@ module Ruflet
           ruflet --version
           ruflet create <appname>
           ruflet new <appname>
-          ruflet run [scriptname|path] [--web|--desktop] [--port PORT]
+          ruflet run [scriptname|path] [--web|--desktop] [--port PORT] [--no-reload]
           ruflet update [web|desktop|all] [--check] [--force] [--platform PLATFORM]
           ruflet debug [scriptname|path]
           ruflet build <apk|android|ios|aab|web|macos|windows|linux> [--self] [--verbose]
           ruflet install [--device DEVICE_ID] [--verbose]
           ruflet devices
           ruflet emulators
-          ruflet doctor
+          ruflet doctor [--fix] [--verbose]
       HELP
     end
 
@@ -89,7 +89,7 @@ module Ruflet
     private
 
     def ensure_first_run_assets(command)
-      return if %w[version -v --version help -h --help].include?(command)
+      return unless %w[create new bootstrap init update debug build install doctor].include?(command)
       return unless respond_to?(:download_ruflet_assets, true)
 
       send(:download_ruflet_assets)

data/lib/ruflet/hot_reload/harness.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Child-process entrypoint used by `ruflet run` when hot reload is enabled.
+# The CLI spawns `ruby [-rbundler/setup] harness.rb` with:
+#   RUFLET_APP_SCRIPT   absolute path to the application script (required)
+#   RUFLET_WATCH_ROOT   directory to watch for *.rb changes (optional)
+#   RUFLET_BOOTSNAP_DIR bootsnap cache directory (optional)
+
+# Bootsnap caches compiled bytecode and $LOAD_PATH resolution, which cuts the
+# cold-boot cost paid on every full restart ("R"). It is optional: used only
+# when the app bundles it (add `gem "bootsnap"` to speed restarts up). Set up
+# before requiring the framework so those requires hit the cache.
+if (cache_dir = ENV["RUFLET_BOOTSNAP_DIR"].to_s) && !cache_dir.empty?
+  begin
+    require "bootsnap"
+    Bootsnap.setup(
+      cache_dir: cache_dir,
+      load_path_cache: true,
+      compile_cache_iseq: true,
+      compile_cache_yaml: false
+    )
+  rescue LoadError
+    # bootsnap not in the bundle; boot without it.
+  end
+end
+
+require_relative "../hot_reload"
+
+script = ENV["RUFLET_APP_SCRIPT"].to_s
+abort "ruflet hot reload: RUFLET_APP_SCRIPT is not set" if script.empty?
+
+Ruflet::HotReload.run(script: script, watch_root: ENV["RUFLET_WATCH_ROOT"])