ruflet 0.0.19 → 0.0.20

data/lib/ruflet/cli/flutter_sdk.rb

@@ -131,7 +131,21 @@ module Ruflet
       end
 
       def fvm_env
-        { "PATH" => "#{pub_cache_bin_dir}#{File::PATH_SEPARATOR}#{ENV.fetch('PATH', '')}" }
+        utf8_locale_env.merge("PATH" => "#{pub_cache_bin_dir}#{File::PATH_SEPARATOR}#{ENV.fetch('PATH', '')}")
+      end
+
+      # CocoaPods aborts with "Unicode Normalization not appropriate for
+      # ASCII-8BIT" when it inherits a non-UTF-8 locale, which takes the whole
+      # iOS and macOS build with it. Hand the toolchain a UTF-8 locale unless
+      # the environment already has one.
+      def utf8_locale_env
+        return {} if utf8_locale?(ENV["LC_ALL"]) || utf8_locale?(ENV["LANG"])
+
+        { "LANG" => "en_US.UTF-8", "LC_ALL" => "en_US.UTF-8" }
+      end
+
+      def utf8_locale?(value)
+        value.to_s.match?(/utf-?8/i)
       end
 
       def tools_from_flutter_bin(flutter_bin)
@@ -143,11 +157,11 @@ module Ruflet
         {
           flutter: flutter_bin,
           dart: (File.executable?(dart) ? dart : "dart"),
-          env: {
+          env: utf8_locale_env.merge(
             "PATH" => "#{bin_dir}#{File::PATH_SEPARATOR}#{pub_cache_bin_dir}#{File::PATH_SEPARATOR}#{ENV.fetch('PATH', '')}",
             "FLUTTER_ROOT" => sdk_root,
             "FVM_FLUTTER_SDK" => sdk_root
-          }
+          )
         }
       end
 

data/lib/ruflet/cli/new_command.rb

@@ -25,6 +25,7 @@ module Ruflet
         "lottie" => { package: "flet_lottie", alias: "ruflet_lottie" },
         "map" => { package: "flet_map", alias: "ruflet_map" },
         "permission_handler" => { package: "flet_permission_handler", alias: "ruflet_permission_handler" },
+        "qrcode_scanner" => { package: "ruflet_qrcode_scanner", alias: "ruflet_qrcode_scanner" },
         "rive" => { package: "flet_rive", alias: "ruflet_rive" },
         "secure_storage" => { package: "flet_secure_storage", alias: "ruflet_secure_storage" },
         "video" => { package: "flet_video", alias: "ruflet_video" },
@@ -54,11 +55,11 @@ module Ruflet
         puts "Run:"
         puts "  cd #{project_name}"
         puts "  bundle install"
-        puts "  bundle exec ruflet run main.rb"
+        puts "  ruflet run main.rb"
         puts
         puts "Build:"
-        puts "  bundle exec ruflet build android --self"
-        puts "  bundle exec ruflet build ios --self"
+        puts "  ruflet build android --self"
+        puts "  ruflet build ios --self"
         0
       end
 
@@ -81,21 +82,23 @@ module Ruflet
       end
 
       def resolve_ruflet_client_template_root
-        [
-          File.expand_path("../../../../../templates/ruflet_flutter_template", __dir__)
-        ].each do |template|
-          return template if Dir.exist?(template)
+        explicit = ENV["RUFLET_TEMPLATE_ROOT"].to_s.strip
+        unless explicit.empty?
+          explicit_template = [
+            explicit,
+            File.join(explicit, "templates", "ruflet_flutter_template")
+          ].find { |path| valid_ruflet_template?(path) }
+          return explicit_template if explicit_template
         end
 
-        cached_template = cached_ruflet_client_template_root
-        return cached_template if Dir.exist?(cached_template)
+        sibling_template = File.expand_path(
+          "../../../../../../ruflet-template/templates/ruflet_flutter_template",
+          __dir__
+        )
+        return sibling_template if valid_ruflet_template?(sibling_template)
 
-        [
-          File.expand_path("../../../ruflet_client", __dir__),
-          File.expand_path("../../../../../ruflet_client", __dir__)
-        ].each do |fallback|
-          return fallback if Dir.exist?(fallback)
-        end
+        cached_template = cached_ruflet_client_template_root
+        return cached_template if valid_ruflet_template?(cached_template)
 
         nil
       end
@@ -255,12 +258,6 @@ module Ruflet
       def write_default_ruflet_config(root, app_name)
         File.write(File.join(root, "ruflet.yaml"), <<~YAML)
           app:
-            name: #{app_name}
-            display_name: #{humanize_name(app_name)}
-            package_name: #{app_name.gsub(/[^a-zA-Z0-9_]+/, "_").downcase}
-            organization: com.example
-            version: 1.0.0+1
-            description: A new Ruflet app.
             # Required for server-driven builds: `ruflet build ios`, `apk`, `web`, etc. without `--self`.
             # Example: https://api.example.com
             backend_url: ""
@@ -284,6 +281,16 @@ module Ruflet
         YAML
 
         File.write(File.join(root, "services.yaml"), <<~YAML)
+          # Application identity used by the Flutter build pipeline. Ruflet derives
+          # the mobile identifier as organization.package_name and passes it to
+          # change_app_package_name for Android and iOS builds.
+          app:
+            app_name: #{humanize_name(app_name)}
+            package_name: #{app_name.gsub(/[^a-zA-Z0-9_]+/, "_").downcase}
+            organization: com.example
+            version: 1.0.0+1
+            description: A new Ruflet app.
+
           # Native capabilities that require platform permissions. Ruflet activates
           # the matching client extensions and writes Android/iOS permissions.
           # Supported services: camera, microphone, location, motion

data/lib/ruflet/cli/run_command.rb

@@ -20,11 +20,12 @@ module Ruflet
       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)
 
@@ -47,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
@@ -67,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
@@ -97,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, script_path]
+        [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
+
+      # 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)
@@ -177,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
@@ -213,7 +326,7 @@ module Ruflet
               sock.close
               break
             rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-              sleep 0.15
+              sleep poll_interval
             end
           end
         end
@@ -296,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}"
@@ -309,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?
@@ -317,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
 
@@ -352,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

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,7 +66,7 @@ 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]

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"])