ruflet 0.0.15 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 629de90fa5d63db66ce7f96b69fcd83da284621d1bf8f3c179d2ea7b54f1591b
-  data.tar.gz: 4f91dfe6d31fe054b683f9838120fb6476501ac959e981eff19ef1809c880aa9
+  metadata.gz: 653ba520f85466110b49be97b22029f8f1e30629edefcd3057def6ecbf20be2c
+  data.tar.gz: 66107e193cfd961763921dafcec2d67f21216f34daad33a22eeffbef279b1b0e
 SHA512:
-  metadata.gz: 23a877adf84ca8bc119cb5452a480dd666e05f36fd6f3a1a03f75f51fa5b2ff028f07b5373b8c043a1acd43b49dc68f7885992bcb3596e279be07fed5751cb07
-  data.tar.gz: c66e78cc467a27803bbb52264444289f4a9126763c4aed1c53df6b945e1c08f0478fff277008a40c742750dde027a67c84a2209ff4d255b6b48483ffa6a21549
+  metadata.gz: 73608863d7814a25d421f4a1b26bf07a231673b50679e3815eeb7e22df39c0da3c92bbdc696c207a36af38b427413d1d2ed6d61ba36d2720e8a0f444bb3ac3a7
+  data.tar.gz: 9a25b923371b68c7a8f51dbab32a30a71c0034033760c89cdf1773ffb9295707728107072f88523c9a5f7db4b43c5ded66d74096d52fa0547cd35103c99066b1

data/README.md

@@ -1,3 +1,42 @@
 # ruflet
 
-Part of Ruflet monorepo.
+`ruflet` is the command-line package for creating, running, diagnosing, and
+building Ruflet applications.
+
+## Install
+
+```bash
+gem install ruflet
+```
+
+Create a project and run it:
+
+```bash
+ruflet new my_app
+cd my_app
+bundle install
+bundle exec ruflet run --web
+```
+
+Generated projects include `ruflet_core` and `ruflet_server` as application
+dependencies. Use `bundle exec ruflet` inside a project so commands run with
+the versions declared in its `Gemfile`.
+
+## Commands
+
+```bash
+ruflet new <appname>
+ruflet run [scriptname|path] [--web|--desktop] [--port PORT]
+ruflet debug [scriptname|path]
+ruflet devices
+ruflet emulators
+ruflet doctor
+ruflet update [web|desktop|all] [--check] [--force]
+ruflet build <apk|android|ios|aab|web|macos|windows|linux> [--self]
+ruflet install [--device DEVICE_ID]
+```
+
+Run `ruflet install` without `--device` to choose from a numbered list of
+connected devices. Pass `--device DEVICE_ID` to skip the prompt.
+
+Run `ruflet help <command>` for all options.

data/lib/ruflet/cli/android_sdk.rb

@@ -246,8 +246,9 @@ module Ruflet
 
         puts "  Installing Android packages: #{missing.join(', ')}"
         env = sdkmanager_env(java)
-        output = verbose ? $stdout : File::NULL
-        system(env, sdkmanager, "--sdk_root=#{sdk_root}", *missing, out: output, err: $stderr)
+        # sdkmanager downloads sizeable platform/build-tool archives; stream so
+        # the install reports progress instead of appearing to hang.
+        system(env, sdkmanager, "--sdk_root=#{sdk_root}", *missing, out: $stdout, err: $stderr)
       end
 
       def android_package_installed?(sdk_root, package)

data/lib/ruflet/cli/build_command.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "find"
 require "json"
+require "open3"
 require "pathname"
 require "rbconfig"
 require "uri"
@@ -28,7 +29,9 @@ 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" },
+        "rive" => { package: "flet_rive", alias: "ruflet_rive" },
         "secure_storage" => { package: "flet_secure_storage", alias: "ruflet_secure_storage" },
+        "spinkit" => { package: "flet_spinkit", alias: "ruflet_spinkit" },
         "video" => { package: "flet_video", alias: "ruflet_video" },
         "webview" => { package: "flet_webview", alias: "ruflet_webview" }
       }.freeze
@@ -169,6 +172,10 @@ module Ruflet
         backend_url = configured_backend_url(config)
         if self_contained
           build_args += ["--dart-define", "RUFLET_BACKEND_URL=#{backend_url}"] if backend_url
+          # Pin the embedded entry project so the runtime doesn't have to guess.
+          # Apps that bundle nested projects (e.g. ruflet_studio's standalone_apps,
+          # each with their own main.rb) otherwise trip auto-discovery.
+          build_args += ["--dart-define", "RUFLET_EMBEDDED_PROJECT=#{self_contained_project_name}"]
         else
           unless backend_url
             warn "build config error: backend_url is required for server-driven builds"
@@ -204,8 +211,16 @@ module Ruflet
         end
 
         tools = ensure_flutter!("install", client_dir: client_dir)
-        command_env = install_tool_env(tools[:env], client_dir)
+        discovery_env = unbundled_command_env(tools[:env])
+        device_id ||= select_install_device(
+          flutter: tools[:flutter],
+          env: discovery_env,
+          client_dir: client_dir
+        )
+        return 1 unless device_id
+
         install_platform = install_platform_for_device(device_id)
+        command_env = install_tool_env(tools[:env], client_dir, platform: install_platform)
         unless sync_built_outputs_for_install(client_dir, platform: install_platform, verbose: !!verbose)
           warn "Could not find built app outputs under ./build"
           warn "Run `ruflet build ...` first, then `ruflet install`."
@@ -243,6 +258,59 @@ module Ruflet
         nil
       end
 
+      def select_install_device(flutter:, env:, client_dir:, input: $stdin, output: $stdout)
+        devices = discover_install_devices(flutter: flutter, env: env, client_dir: client_dir)
+        if devices.empty?
+          warn "No supported devices are connected."
+          warn "Run `ruflet devices` to check device availability."
+          return nil
+        end
+
+        output.puts "Available devices:"
+        devices.each_with_index do |device, index|
+          details = [device["targetPlatform"], device["emulator"] ? "emulator" : "physical"].compact
+          output.puts "  #{index + 1}) #{device.fetch("name", device["id"])} (#{details.join(", ")}) [#{device["id"]}]"
+        end
+
+        loop do
+          output.print "Choose a device [1-#{devices.length}]: "
+          output.flush
+          choice = input.gets
+          unless choice
+            warn "Device selection cancelled. Use `--device DEVICE_ID` for noninteractive installs."
+            return nil
+          end
+
+          index = Integer(choice.strip, exception: false)
+          return devices[index - 1]["id"] if index && index.between?(1, devices.length)
+
+          output.puts "Enter a number from 1 to #{devices.length}."
+        end
+      end
+
+      def discover_install_devices(flutter:, env:, client_dir:)
+        stdout, stderr, status = Open3.capture3(
+          env,
+          flutter,
+          "devices",
+          "--machine",
+          chdir: client_dir
+        )
+        unless status.success?
+          warn "Could not list Flutter devices."
+          warn stderr.strip unless stderr.to_s.strip.empty?
+          return []
+        end
+
+        devices = JSON.parse(stdout)
+        Array(devices).select do |device|
+          device.is_a?(Hash) && !device["id"].to_s.empty? && device["isSupported"] != false
+        end
+      rescue JSON::ParserError => e
+        warn "Could not parse Flutter device list: #{e.message}"
+        []
+      end
+
       def ensure_flutter_client_dir(verbose: false)
         client_dir = detect_flutter_client_dir
         return client_dir if client_dir
@@ -264,8 +332,9 @@ module Ruflet
         apple_env
       end
 
-      def install_tool_env(env, client_dir)
-        return build_tool_env(env, inferred_install_platform, client_dir) if inferred_install_platform
+      def install_tool_env(env, client_dir, platform: nil)
+        platform ||= inferred_install_platform
+        return build_tool_env(env, platform, client_dir) if platform
 
         command_env = unbundled_command_env(env)
         command_env["PATH"] = apple_build_path(command_env["PATH"])
@@ -998,6 +1067,23 @@ module Ruflet
         cmake_path = File.join(client_dir, "linux", "CMakeLists.txt")
         replace_in_file(cmake_path, /^set\(BINARY_NAME ".*"\)$/, %(set(BINARY_NAME "#{metadata[:package_name]}")))
         replace_in_file(cmake_path, /^set\(APPLICATION_ID ".*"\)$/, %(set(APPLICATION_ID "#{metadata[:linux_application_id]}")))
+
+        # The GTK runner hardcodes the window title (header-bar and fallback
+        # paths). Without this it shows the package name (e.g. "ruflet_client")
+        # instead of the configured app name. Match the call, not the literal,
+        # so re-runs stay idempotent.
+        my_application_path = File.join(client_dir, "linux", "runner", "my_application.cc")
+        title = c_string_escape(metadata[:display_name])
+        replace_in_file(
+          my_application_path,
+          /gtk_header_bar_set_title\(header_bar, "[^"]*"\)/,
+          %(gtk_header_bar_set_title(header_bar, "#{title}"))
+        )
+        replace_in_file(
+          my_application_path,
+          /gtk_window_set_title\(window, "[^"]*"\)/,
+          %(gtk_window_set_title(window, "#{title}"))
+        )
       end
 
       def apply_dart_metadata(client_dir, metadata)
@@ -1090,6 +1176,13 @@ module Ruflet
         value.to_s.gsub('"', '""')
       end
 
+      # Escape a value for embedding inside a C string literal (used for the
+      # GTK runner window title in my_application.cc). Block form avoids
+      # backslash interpretation in the gsub replacement string.
+      def c_string_escape(value)
+        value.to_s.gsub(/[\\"]/) { |ch| "\\#{ch}" }
+      end
+
       def dart_single_quote_escape(value)
         value.to_s.gsub("\\", "\\\\\\").gsub("'", "\\\\'")
       end
@@ -1107,6 +1200,7 @@ module Ruflet
         extension_packages = extension_keys.filter_map { |key| CLIENT_EXTENSION_MAP[key]&.fetch(:package) }.uniq
         extension_aliases = extension_keys.filter_map { |key| CLIENT_EXTENSION_MAP[key]&.fetch(:alias) }.uniq
 
+        sync_client_flet_packages(client_dir, extension_packages)
         pubspec_path = File.join(client_dir, "pubspec.yaml")
         if File.file?(pubspec_path)
           sync_client_extension_dependencies(pubspec_path, extension_packages)
@@ -1293,8 +1387,23 @@ module Ruflet
         return if content.include?("<key>#{key}</key>")
 
         entry = "\t<key>#{key}</key>\n\t#{value_xml}\n"
-        updated = content.sub(%r{</dict>}, "#{entry}</dict>")
-        File.write(path, updated == content ? "#{content}\n#{entry}" : updated)
+
+        # Insert into the ROOT <dict> (opened right after <plist ...>), never the
+        # first nested </dict>. Modern Flutter Info.plists nest a dict inside
+        # UIApplicationSceneManifest, so subbing the first </dict> would bury
+        # top-level keys (e.g. NS*UsageDescription) where iOS can't read them —
+        # which crashes the app the moment a permission is requested.
+        root_open = content.match(%r{<plist\b[^>]*>\s*<dict>}m)
+        updated =
+          if root_open
+            insert_at = root_open.end(0)
+            content[0...insert_at] + "\n#{entry}" + content[insert_at..]
+          elsif (last = content.rindex("</dict>"))
+            content[0...last] + entry + content[last..]
+          else
+            "#{content}\n#{entry}"
+          end
+        File.write(path, updated)
       end
 
       def remove_plist_entry(path, key)
@@ -1358,18 +1467,20 @@ module Ruflet
         flutter = data["flutter"]
         flutter = data["flutter"] = {} unless flutter.is_a?(Hash)
         assets = Array(flutter["assets"]).map(&:to_s)
+        project_asset_prefix = "assets/#{self_contained_project_name}/"
+        assets.reject! { |asset| asset.start_with?(project_asset_prefix) }
 
         if self_contained
           dependencies["ruby_runtime"] = ruby_runtime_dependency(dependencies["ruby_runtime"])
           assets.delete("assets/main.rb")
           assets.delete("assets/ruby_project/")
-          project_asset_path = "assets/#{self_contained_project_name}/"
-          assets << project_asset_path unless assets.include?(project_asset_path)
+          project_asset_relative_paths.each do |relative_path|
+            assets << "#{project_asset_prefix}#{relative_path}"
+          end
         else
           dependencies.delete("ruby_runtime")
           assets.delete("assets/main.rb")
           assets.delete("assets/ruby_project/")
-          assets.delete("assets/#{self_contained_project_name}/")
         end
 
         flutter["assets"] = assets unless assets.empty?
@@ -1377,7 +1488,7 @@ module Ruflet
         write_pubspec_yaml(pubspec_path, data)
       end
 
-      RUBY_RUNTIME_FALLBACK_REQUIREMENT = "^0.0.5"
+      RUBY_RUNTIME_FALLBACK_REQUIREMENT = "^0.0.6"
 
       def ruby_runtime_dependency(current_dependency = nil)
         local_path = explicit_local_ruby_runtime_path || repo_checkout_ruby_runtime_path
@@ -1747,6 +1858,50 @@ module Ruflet
         write_pubspec_yaml(path, data)
       end
 
+      def sync_client_flet_packages(client_dir, selected_packages)
+        template_root =
+          if Ruflet::CLI.respond_to?(:resolve_ruflet_client_template_root, true)
+            Ruflet::CLI.send(:resolve_ruflet_client_template_root)
+          end
+        return unless template_root
+
+        source_root = File.join(template_root, "flet_packages")
+        target_root = File.join(client_dir, "flet_packages")
+        return unless Dir.exist?(source_root)
+        return if File.expand_path(source_root) == File.expand_path(target_root)
+
+        # The repository's standalone client intentionally carries the full
+        # local package catalog. Only generated/template-derived clients are
+        # conditioned for a particular Ruflet application.
+        return if standalone_ruflet_client_source?(client_dir, template_root)
+
+        known_packages = CLIENT_EXTENSION_MAP.values.map { |meta| meta.fetch(:package) }.uniq
+        required_packages = (["flet"] + selected_packages).uniq
+
+        FileUtils.mkdir_p(target_root)
+        required_packages.each do |package_name|
+          source = File.join(source_root, package_name)
+          target = File.join(target_root, package_name)
+          next unless Dir.exist?(source)
+          next if Dir.exist?(target)
+
+          FileUtils.cp_r(source, target)
+        end
+
+        (known_packages - selected_packages).each do |package_name|
+          FileUtils.rm_rf(File.join(target_root, package_name))
+        end
+      end
+
+      def standalone_ruflet_client_source?(client_dir, template_root)
+        client_root = File.expand_path(client_dir)
+        candidates = [
+          File.expand_path("../../ruflet_client", template_root),
+          File.expand_path("../../../../../ruflet_client", __dir__)
+        ]
+        candidates.any? { |candidate| File.expand_path(candidate) == client_root }
+      end
+
       def sync_client_extension_dependencies(path, selected_packages)
         return if selected_packages.empty?
 
@@ -1755,14 +1910,30 @@ module Ruflet
 
         data = YAML.safe_load(File.read(path), aliases: true) || {}
         deps = (data["dependencies"] || {}).dup
+        if selected_packages.include?("flet_rive")
+          deps.delete("rive")
+          deps.delete("rive_native")
+        end
         selected_packages.each do |package_name|
           deps[package_name] = template_deps[package_name] if template_deps.key?(package_name)
         end
 
         data["dependencies"] = deps
+        sync_local_flet_dependency_override(data, deps["flet"])
         write_pubspec_yaml(path, data)
       end
 
+      # Git-backed Flet extensions declare their own Flet source. When Ruflet
+      # vendors the core engine locally, force every extension to resolve that
+      # same copy instead of letting Pub reject the mixed sources.
+      def sync_local_flet_dependency_override(data, flet_dependency)
+        return unless flet_dependency.is_a?(Hash) && key_defined?(flet_dependency, "path")
+
+        overrides = data["dependency_overrides"]
+        overrides = data["dependency_overrides"] = {} unless overrides.is_a?(Hash)
+        overrides["flet"] = flet_dependency
+      end
+
       def template_client_pubspec_dependencies
         template_root =
           if Ruflet::CLI.respond_to?(:resolve_ruflet_client_template_root, true)

data/lib/ruflet/cli/environment_setup.rb

@@ -212,8 +212,11 @@ module Ruflet
       def run_privileged_command(*command, verbose: false)
         full = sudo_prefix + command
         puts "  $ #{full.join(' ')}"
-        output = verbose ? $stdout : File::NULL
-        system(*full, out: output, err: $stderr)
+        # Package installs (apt/dnf/pacman...) routinely download hundreds of
+        # megabytes and take minutes. Always stream their output so the user
+        # can see progress instead of a frozen-looking prompt; `verbose` is
+        # left for callers that want to add their own detail elsewhere.
+        system(*full, out: $stdout, err: $stderr)
       end
 
       def sudo_prefix

data/lib/ruflet/cli/extra_command.rb

@@ -56,8 +56,7 @@ module Ruflet
         puts "  Flutter: #{flutter_version_summary(tools)}"
         environment_issues += android_environment_setup!(fix: !!fix, verbose: !!verbose)
         ok = system(android_build_env(tools[:env]), tools[:flutter], "doctor", *(verbose ? ["-v"] : []))
-        status = $?.exitstatus if $?
-        status ||= ok ? 0 : 1
+        status = ok ? 0 : ($?&.exitstatus || 1)
         if environment_issues.any?
           warn "Unresolved environment issues: #{environment_issues.join('; ')}"
           status = 1 if status.zero?

data/lib/ruflet/cli/flutter_sdk.rb

@@ -84,8 +84,12 @@ module Ruflet
           File.write(fvmrc_path, "{\"flutter\":\"#{version}\"}\n")
         end
 
-        system(fvm_env, fvm, "install", version.to_s, chdir: project_dir, out: File::NULL, err: File::NULL)
-        system(fvm_env, fvm, "use", "--force", version.to_s, chdir: project_dir, out: File::NULL, err: File::NULL)
+        # Installing a Flutter SDK through FVM downloads/extracts hundreds of
+        # megabytes. Stream FVM's output so the run does not look frozen.
+        puts "  $ fvm install #{version}"
+        system(fvm_env, fvm, "install", version.to_s, chdir: project_dir, out: $stdout, err: $stderr)
+        puts "  $ fvm use --force #{version}"
+        system(fvm_env, fvm, "use", "--force", version.to_s, chdir: project_dir, out: $stdout, err: $stderr)
 
         flutter = flutter_bin_path(project_dir)
         return nil unless File.executable?(flutter)
@@ -107,7 +111,8 @@ module Ruflet
         end
         return nil unless dart && File.executable?(dart)
 
-        system(dart, "pub", "global", "activate", "fvm", out: File::NULL, err: File::NULL)
+        puts "  $ dart pub global activate fvm"
+        system(dart, "pub", "global", "activate", "fvm", out: $stdout, err: $stderr)
         installed_fvm = File.join(pub_cache_bin_dir, fvm_executable_name)
         return installed_fvm if File.executable?(installed_fvm)
 
@@ -148,10 +153,13 @@ module Ruflet
         return sdk_root if File.executable?(flutter_bin)
 
         FileUtils.mkdir_p(install_root)
+        puts "  Installing Flutter #{release.fetch('version')} (#{host}) into #{install_root}"
         Dir.mktmpdir("ruflet-flutter-sdk-") do |tmpdir|
           archive_path = File.join(tmpdir, File.basename(archive))
-          download_file("#{RELEASES_BASE}/#{archive}", archive_path)
+          download_file("#{RELEASES_BASE}/#{archive}", archive_path, label: "Flutter SDK")
+          puts "  Extracting #{File.basename(archive)} (this can take a minute)"
           extract_archive(archive_path, install_root)
+          puts "  Extracted Flutter SDK"
         end
 
         return sdk_root if File.executable?(flutter_bin)
@@ -366,7 +374,7 @@ module Ruflet
         nil
       end
 
-      def download_file(url, destination, limit: 5)
+      def download_file(url, destination, limit: 5, label: nil)
         raise "Too many redirects while downloading #{url}" if limit <= 0
 
         uri = URI(url)
@@ -376,10 +384,21 @@ module Ruflet
           http.request(req) do |res|
             case res
             when Net::HTTPSuccess
-              File.open(destination, "wb") { |f| res.read_body { |chunk| f.write(chunk) } }
+              name = label || File.basename(destination)
+              total = res["content-length"].to_i
+              downloaded = 0
+              marker = -1
+              File.open(destination, "wb") do |f|
+                res.read_body do |chunk|
+                  f.write(chunk)
+                  downloaded += chunk.bytesize
+                  marker = report_download_progress(name, downloaded, total, marker)
+                end
+              end
+              finish_download_progress(name, downloaded, total)
               return destination
             when Net::HTTPRedirection
-              return download_file(res["location"], destination, limit: limit - 1)
+              return download_file(res["location"], destination, limit: limit - 1, label: label)
             else
               raise "Download failed (#{res.code})"
             end
@@ -389,6 +408,51 @@ module Ruflet
         curl_download(url, destination)
       end
 
+      # Net::HTTP gives no progress for a multi-hundred-MB SDK download, which
+      # looks like a hang. Report percentage on a TTY (rewritten in place) and
+      # at coarse steps when piped, so logs stay readable either way.
+      def report_download_progress(name, downloaded, total, marker)
+        if total.positive?
+          percent = downloaded * 100 / total
+          return marker if percent <= marker
+
+          line = "  Downloading #{name}: #{percent}% (#{human_size(downloaded)} / #{human_size(total)})"
+          if $stdout.tty?
+            $stdout.print("\r#{line}")
+          elsif (percent % 10).zero?
+            puts line
+          end
+          percent
+        else
+          step = downloaded / (5 * 1024 * 1024)
+          return marker if step <= marker
+
+          line = "  Downloading #{name}: #{human_size(downloaded)}"
+          $stdout.tty? ? $stdout.print("\r#{line}") : puts(line)
+          step
+        end
+      end
+
+      def finish_download_progress(name, downloaded, total)
+        summary = total.positive? ? "#{human_size(downloaded)} / #{human_size(total)}" : human_size(downloaded)
+        if $stdout.tty?
+          $stdout.print("\r  Downloaded #{name}: #{summary}\n")
+        else
+          puts "  Downloaded #{name}: #{summary}"
+        end
+      end
+
+      def human_size(bytes)
+        units = %w[B KB MB GB TB]
+        size = bytes.to_f
+        unit = units.shift
+        while size >= 1024 && units.any?
+          size /= 1024
+          unit = units.shift
+        end
+        format("%.1f %s", size, unit)
+      end
+
       def extract_archive(archive, destination)
         if archive.end_with?(".zip")
           if windows_host?

data/lib/ruflet/cli/new_command.rb

@@ -25,6 +25,7 @@ module Ruflet
         "map" => { package: "flet_map", alias: "ruflet_map" },
         "permission_handler" => { package: "flet_permission_handler", alias: "ruflet_permission_handler" },
         "secure_storage" => { package: "flet_secure_storage", alias: "ruflet_secure_storage" },
+        "spinkit" => { package: "flet_spinkit", alias: "ruflet_spinkit" },
         "video" => { package: "flet_video", alias: "ruflet_video" },
         "webview" => { package: "flet_webview", alias: "ruflet_webview" }
       }.freeze

data/lib/ruflet/cli/run_command.rb

@@ -17,12 +17,18 @@ require "yaml"
 module Ruflet
   module CLI
     module RunCommand
+      DEFAULT_BACKEND_PORTS = {
+        "web" => 8550,
+        "desktop" => 8560,
+        "mobile" => 8570
+      }.freeze
+
       def command_run(args)
-        options = { target: "mobile", requested_port: 8550 }
+        options = { target: "mobile", requested_port: nil }
         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("--port PORT", Integer, "Backend port (defaults: web 8550, desktop 8560, mobile 8570)") { |v| options[:requested_port] = v }
         end
         parser.parse!(args)
 
@@ -34,18 +40,33 @@ module Ruflet
           return 1
         end
 
-        selected_port = resolve_backend_port(options[:target], requested_port: options[:requested_port])
+        requested_port = options[:requested_port] || default_backend_port(options[:target])
+        selected_port = resolve_backend_port(options[:target], requested_port: requested_port)
         return 1 unless selected_port
         env = {
           "RUFLET_TARGET" => options[:target],
           "RUFLET_SUPPRESS_SERVER_BANNER" => "1",
-          "RUFLET_PORT" => selected_port.to_s
+          "RUFLET_PORT" => selected_port.to_s,
+          "RUFLET_STRICT_PORT" => "1"
         }
         apply_local_ruflet_dev_overrides(env)
         assets_dir = File.join(File.dirname(script_path), "assets")
         env["RUFLET_ASSETS_DIR"] = assets_dir if File.directory?(assets_dir)
 
-        print_run_banner(target: options[:target], requested_port: options[:requested_port], port: selected_port)
+        # Web: the Ruby backend serves the Flutter web client itself (same
+        # origin/port as /ws), so no separate static server or proxy is needed.
+        if options[:target] == "web"
+          web_dir = detect_web_client_dir
+          if web_dir
+            env["RUFLET_WEB_CLIENT_DIR"] = web_dir
+          else
+            warn "Ruflet web client unavailable for version #{ruflet_version}."
+            warn "Install the matching GitHub release client before running --web."
+            return 1
+          end
+        end
+
+        print_run_banner(target: options[:target], requested_port: requested_port, port: selected_port)
         print_mobile_qr_hint(port: selected_port) if options[:target] == "mobile"
 
         gemfile_path = find_nearest_gemfile(Dir.pwd)
@@ -150,16 +171,14 @@ module Ruflet
 
       def print_run_banner(target:, requested_port:, port:)
         if port != requested_port.to_i
-          puts "Requested port #{requested_port} is busy; bound to #{port}"
+          puts "Port #{requested_port} is busy; using #{port} for #{target}."
         end
         if target == "desktop"
           puts "Ruflet desktop URL: http://localhost:#{port}"
         elsif target == "mobile"
           puts "Ruflet target: #{target}"
-        else
-          puts "Ruflet target: #{target}"
-          puts "Ruflet URL: http://localhost:#{port}"
         end
+        # web: launch_web_client prints the single app URL after the server boots
       end
 
       def launch_target_client(target, port)
@@ -175,30 +194,19 @@ module Ruflet
         end
       end
 
+      # The Ruby backend (Ruflet::Server) serves the Flutter web client on its
+      # own port, so the client loads and opens its websocket on that same
+      # origin. The prebuilt web client derives its backend from Uri.base, so
+      # the public URL stays clean and dynamic port selection works naturally.
       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)}"
-        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."
-        []
+        url = "http://localhost:#{port}/"
+        browser_pid = open_in_browser_app_mode(url)
+        open_in_browser(url) if browser_pid.nil?
+        puts "Ruflet web app: #{url}"
+        [browser_pid].compact
       rescue StandardError => e
-        warn "Failed to launch web client: #{e.class}: #{e.message}"
+        warn "Failed to open web client: #{e.class}: #{e.message}"
+        warn "Open it manually: http://localhost:#{port}/"
         []
       end
 
@@ -286,7 +294,7 @@ module Ruflet
       end
 
       def launch_desktop_client(url)
-        cmd = detect_project_desktop_client_command(url) || detect_desktop_client_command(url)
+        cmd = detect_desktop_client_command(url)
         unless cmd
           warn "Desktop client executable not found."
           warn "Set RUFLET_CLIENT_DIR to your client path."
@@ -307,136 +315,37 @@ module Ruflet
         []
       end
 
-      def detect_project_desktop_client_command(url)
-        return nil unless project_run_requires_managed_client?
-        return nil unless respond_to?(:ensure_flutter_client_dir, true)
-        return nil unless respond_to?(:prepare_flutter_client, true)
-        return nil unless respond_to?(:ensure_flutter!, true)
-
-        platform = host_platform_name
-        return nil unless %w[macos windows linux].include?(platform)
-
-        ensure_ruflet_build_assets(verbose: false) if respond_to?(:ensure_ruflet_build_assets, true)
-        client_dir = ensure_flutter_client_dir(verbose: false)
-        return nil unless client_dir
-
-        config = project_run_config
-        tools = ensure_flutter!("run", client_dir: client_dir)
-        env = build_tool_env(tools[:env], platform, client_dir)
-        return nil unless prepare_flutter_client(
-          client_dir,
-          platform: platform,
-          tools: tools,
-          config: config,
-          self_contained: false,
-          verbose: false
-        )
-
-        [
-          env,
-          tools[:flutter],
-          "run",
-          "-d",
-          platform,
-          "--target",
-          "lib/main.server.dart",
-          "--dart-define",
-          "RUFLET_BACKEND_URL=#{url}"
-        ]
-      rescue StandardError => e
-        warn "Project desktop client setup failed: #{e.class}: #{e.message}"
-        nil
-      end
-
-      def project_run_requires_managed_client?
-        extensions = Array(project_run_config["extensions"]).map { |value| normalize_run_extension_key(value) }.compact
-        protected_extensions =
-          if defined?(Ruflet::CLI::BuildCommand::SERVICE_EXTENSION_MAP)
-            Ruflet::CLI::BuildCommand::SERVICE_EXTENSION_MAP.values.flatten
-          else
-            []
-          end
-        return true if (extensions - protected_extensions).any?
-
-        services =
-          if respond_to?(:load_service_definitions, true)
-            send(:load_service_definitions).keys
-          else
-            []
-          end
-        return false if services.empty?
-
-        known_services =
-          if defined?(Ruflet::CLI::BuildCommand::DEFAULT_SERVICE_NATIVE_REQUIREMENTS)
-            Ruflet::CLI::BuildCommand::DEFAULT_SERVICE_NATIVE_REQUIREMENTS.keys
-          else
-            []
-          end
-        (services & known_services).any?
-      end
-
-      def project_run_config
-        config_path = ENV["RUFLET_CONFIG"] || (File.file?("ruflet.yaml") ? "ruflet.yaml" : "ruflet.yml")
-        return {} unless File.file?(config_path)
-
-        YAML.safe_load(File.read(config_path), aliases: true) || {}
-      rescue StandardError
-        {}
-      end
+      def detect_desktop_client_command(url)
+        root = configured_client_root
 
-      def normalize_run_extension_key(value)
-        key = value.to_s.strip.downcase
-        return nil if key.empty?
+        command = desktop_client_command_from_root(root, url)
+        return command if command
 
-        key.tr!("-", "_")
-        key.gsub!(/\A(flet_)+/, "")
-        key.gsub!(/\Aservice_/, "")
-        key
+        cached_root = ensure_prebuilt_client(desktop: true)
+        desktop_client_command_from_root(cached_root, url)
       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?
-        root = nil unless Dir.exist?(root)
-        root ||= ensure_prebuilt_client(desktop: true)
+      def desktop_client_command_from_root(root, url)
         return nil unless root && Dir.exist?(root)
 
         host_os = RbConfig::CONFIG["host_os"]
         if host_os.match?(/darwin/i)
-          app_path = [
-            File.join(root, "build", "macos", "Build", "Products", "Release", "ruflet_client.app"),
-            File.join(root, "build", "macos", "Build", "Products", "Debug", "ruflet_client.app"),
-            File.join(root, "desktop", "ruflet_client.app")
-          ].find do |candidate|
-            bin = File.join(candidate, "Contents", "MacOS", "ruflet_client")
-            File.file?(bin) && File.executable?(bin) && ensure_macos_file_picker_entitlement(candidate)
-          end
-          return [File.join(app_path, "Contents", "MacOS", "ruflet_client"), url] if app_path
+          app_path = File.join(root, "desktop", "ruflet_client.app")
+          bin = File.join(app_path, "Contents", "MacOS", "ruflet_client")
+          return [bin, url] if File.file?(bin) && File.executable?(bin) && ensure_macos_file_picker_entitlement(app_path)
         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)
+          exe = File.join(root, "desktop", "ruflet_client.exe")
           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)
+          direct = File.join(root, "desktop", "ruflet_client")
           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
-          end
         end
 
         nil
       end
 
       def detect_web_client_dir
-        root = ENV["RUFLET_CLIENT_DIR"]
-        root = File.expand_path("ruflet_client", Dir.pwd) if root.to_s.strip.empty?
-        root = nil unless Dir.exist?(root)
+        root = configured_client_root
         root ||= ensure_prebuilt_client(web: true)
         return nil unless root && Dir.exist?(root)
 
@@ -448,6 +357,14 @@ module Ruflet
         nil
       end
 
+      def configured_client_root
+        root = ENV["RUFLET_CLIENT_DIR"].to_s.strip
+        return nil if root.empty?
+
+        expanded = File.expand_path(root)
+        Dir.exist?(expanded) ? expanded : nil
+      end
+
       def ensure_prebuilt_client(web: false, desktop: false, platform: nil, force: false)
         platform ||= host_platform_name
         return nil if platform.nil?
@@ -462,10 +379,12 @@ 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))
-          ensure_client_manifest(cache_root, platform: platform)
+        cached = prebuilt_assets_present?(cache_root, web: web, desktop: desktop, platform: platform)
+        compatible_cache = cached && compatible_client_cache?(cache_root, platform: platform)
+        if !force && (wanted_assets.empty? || compatible_cache)
           return cache_root
         end
+        force = true if cached && !compatible_cache
 
         release = fetch_release_for_version
         return nil unless release
@@ -561,11 +480,33 @@ module Ruflet
       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
+        client_release_tags.each do |tag|
+          release = release_by_tag(tag)
+          return release if release
+        end
+
+        nil
+      end
+
+      def client_release_tags
+        channel = ENV["RUFLET_CLIENT_CHANNEL"].to_s.strip
+        unless channel.empty?
+          raise ArgumentError, "Invalid RUFLET_CLIENT_CHANNEL" unless channel.match?(/\A[A-Za-z0-9._-]+\z/)
+
+          return [channel]
+        end
+
+        ["v#{ruflet_version}", ruflet_version]
+      end
+
+      def compatible_client_cache?(root, platform:)
+        manifest = read_client_manifest(root)
+        return false unless manifest
+
+        manifest["schema"] == 1 &&
+          manifest["ruflet_version"] == ruflet_version &&
+          manifest["platform"] == platform &&
+          client_release_tags.include?(manifest["release_tag"])
       end
 
       def ruflet_version
@@ -575,10 +516,6 @@ module Ruflet
         Ruflet::VERSION
       end
 
-      def release_latest
-        github_get_json("https://api.github.com/repos/AdamMusa/Ruflet/releases/latest")
-      end
-
       def release_by_tag(tag)
         github_get_json("https://api.github.com/repos/AdamMusa/Ruflet/releases/tags/#{tag}")
       rescue StandardError
@@ -748,19 +685,6 @@ module Ruflet
         nil
       end
 
-      def ensure_client_manifest(root, platform:)
-        return if read_client_manifest(root)
-
-        assets = []
-        assets << { "kind" => "web", "platform" => platform, "asset_name" => nil } if File.file?(File.join(root, "web", "index.html"))
-        if prebuilt_desktop_present?(root, platform: platform)
-          assets << { "kind" => "desktop", "platform" => platform, "asset_name" => nil }
-        end
-        return if assets.empty?
-
-        write_client_manifest(root, platform: platform, release: nil, assets: assets)
-      end
-
       def write_client_manifest(root, platform:, release:, assets:)
         FileUtils.mkdir_p(root)
         payload = {
@@ -793,26 +717,24 @@ module Ruflet
         port = start_port.to_i
 
         max_attempts.times do
-          begin
-            begin
-              probe = TCPServer.new("0.0.0.0", port)
-            rescue Errno::EACCES, Errno::EPERM
-              probe = TCPServer.new("127.0.0.1", port)
-            end
-            probe.close
-            return port
-          rescue Errno::EADDRINUSE, Errno::EACCES, Errno::EPERM
-            port += 1
-          end
+          return port if port_available?(port)
+
+          port += 1
         end
 
-        start_port
+        nil
+      end
+
+      def default_backend_port(target)
+        DEFAULT_BACKEND_PORTS.fetch(target.to_s, DEFAULT_BACKEND_PORTS.fetch("mobile"))
       end
 
-      def resolve_backend_port(_target, requested_port: 8550)
+      def resolve_backend_port(target, requested_port: nil)
         base = requested_port.to_i
-        base = 8550 if base <= 0
-        find_available_port(base)
+        base = default_backend_port(target) if base <= 0
+        selected = find_available_port(base)
+        warn "No available Ruflet port found starting at #{base}." unless selected
+        selected
       end
 
       def port_available?(port)
@@ -824,7 +746,7 @@ module Ruflet
             probe = TCPServer.new("127.0.0.1", port)
           end
           true
-        rescue Errno::EADDRINUSE
+        rescue Errno::EADDRINUSE, Errno::EACCES, Errno::EPERM
           false
         ensure
           probe&.close

data/lib/ruflet/cli.rb

@@ -6,6 +6,13 @@ require "optparse"
 # depend on the caller's locale for reading them.
 Encoding.default_external = Encoding::UTF_8 if Encoding.default_external == Encoding::US_ASCII
 
+# Provisioning (downloads, package installs, SDK extraction) can run for
+# minutes. When stdout is not a TTY (CI logs, pipes, editor consoles) Ruby
+# buffers it, so progress notes would only appear once the whole run finishes.
+# Unbuffer both streams so the pipeline reports progress as it happens.
+$stdout.sync = true
+$stderr.sync = true
+
 require_relative "version"
 require_relative "cli/templates"
 require_relative "cli/new_command"

data/lib/ruflet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruflet
-  VERSION = "0.0.15" unless const_defined?(:VERSION)
+  VERSION = "0.0.16" unless const_defined?(:VERSION)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruflet
 version: !ruby/object:Gem::Version
-  version: 0.0.15
+  version: 0.0.16
 platform: ruby
 authors:
 - AdamMusa
@@ -49,7 +49,8 @@ files:
 - lib/ruflet/version.rb
 - lib/ruflet_cli.rb
 homepage: https://github.com/AdamMusa/Ruflet
-licenses: []
+licenses:
+- MIT
 metadata: {}
 rdoc_options: []
 require_paths: