ruflet 0.0.9 → 0.0.11

data/lib/ruflet/cli/build_command.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "find"
+require "json"
+require "pathname"
+require "rbconfig"
 require "uri"
 require "yaml"
 
@@ -28,9 +32,11 @@ module Ruflet
       }.freeze
 
       def command_build(args)
+        self_contained = args.delete("--self")
+        verbose = args.delete("--verbose") || args.delete("-v")
         platform = (args.shift || "").downcase
         if platform.empty?
-          warn "Usage: ruflet build <apk|android|ios|aab|web|macos|windows|linux>"
+          warn "Usage: ruflet build <apk|android|ios|aab|web|macos|windows|linux> [--self] [--verbose]"
           return 1
         end
 
@@ -40,34 +46,278 @@ module Ruflet
           return 1
         end
 
-        client_dir = detect_flutter_client_dir
+        client_dir = ensure_flutter_client_dir(verbose: !!verbose)
         unless client_dir
           warn "Could not find Flutter client directory."
-          warn "Set RUFLET_CLIENT_DIR or place client at ./ruflet_client"
+          warn "Set RUFLET_CLIENT_DIR or let Ruflet manage the client under ./build/client"
           return 1
         end
 
+        build_note("Preparing #{platform} build (#{self_contained ? 'self-contained' : 'server-driven'})")
         config = load_ruflet_config
         tools = ensure_flutter!("build", client_dir: client_dir)
-        ok = prepare_flutter_client(client_dir, tools: tools, config: config)
+        command_env = build_tool_env(tools[:env], platform, client_dir)
+        ok = prepare_flutter_client(
+          client_dir,
+          platform: platform,
+          tools: tools.merge(env: command_env),
+          config: config,
+          self_contained: !!self_contained,
+          verbose: !!verbose
+        )
         return 1 unless ok
 
         build_args = [*flutter_cmd, *args]
-        client_url = configured_client_url(config)
-        if client_url
-          build_args += ["--dart-define", "RUFLET_CLIENT_URL=#{client_url}"]
+        build_args << "--codesign" if ios_device_build_needs_codesign_flag?(platform, build_args)
+        target_entrypoint = flutter_target_entrypoint(client_dir, self_contained: !!self_contained)
+        build_args += ["--target", target_entrypoint] if target_entrypoint
+        backend_url = configured_backend_url(config)
+        if self_contained
+          build_args += ["--dart-define", "RUFLET_BACKEND_URL=#{backend_url}"] if backend_url
+        else
+          unless backend_url
+            warn "build config error: backend_url is required for server-driven builds"
+            warn "Set app.backend_url or backend_url in ruflet.yaml"
+            return 1
+          end
+          build_args += ["--dart-define", "RUFLET_BACKEND_URL=#{backend_url}"]
+        end
+        build_args << "-v" if verbose
+
+        build_log(verbose, "mode=#{self_contained ? 'self' : 'server'}")
+        build_log(verbose, "client_dir=#{client_dir}")
+        build_log(verbose, "flutter=#{tools[:flutter]}")
+        build_log(verbose, "dart=#{tools[:dart]}")
+        build_log(verbose, "target=#{target_entrypoint}") if target_entrypoint
+        build_log(verbose, "command=#{([tools[:flutter]] + build_args).join(' ')}")
+
+        build_note("Running Flutter #{build_args.join(' ')}")
+        ok = run_external_command(command_env, tools[:flutter], *build_args, chdir: client_dir, unbundled: true)
+        export_platform_build_outputs(client_dir, platform, verbose: !!verbose) if ok
+        ok ? 0 : 1
+      end
+
+      def command_install(args)
+        verbose = args.delete("--verbose") || args.delete("-v")
+        device_id = extract_option_value!(args, "--device", "-d")
+
+        client_dir = ensure_flutter_client_dir(verbose: !!verbose)
+        unless client_dir
+          warn "Could not find Flutter client directory."
+          warn "Set RUFLET_CLIENT_DIR or let Ruflet manage the client under ./build/client"
+          return 1
+        end
+
+        tools = ensure_flutter!("install", client_dir: client_dir)
+        command_env = install_tool_env(tools[:env], client_dir)
+        install_platform = install_platform_for_device(device_id)
+        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`."
+          return 1
+        end
+        unless validate_install_artifacts(client_dir, platform: install_platform, device_id: device_id)
+          return 1
         end
 
-        ok = system(tools[:env], tools[:flutter], *build_args, chdir: client_dir)
+        install_args = ["install"]
+        install_args += ["-d", device_id] if device_id
+        install_args << "-v" if verbose
+
+        build_log(verbose, "client_dir=#{client_dir}")
+        build_log(verbose, "flutter=#{tools[:flutter]}")
+        build_log(verbose, "dart=#{tools[:dart]}")
+        build_log(verbose, "install_command=#{([tools[:flutter]] + install_args).join(' ')}")
+        build_note("Installing app#{device_id ? " to device #{device_id}" : ""}")
+
+        ok = run_external_command(command_env, tools[:flutter], *install_args, chdir: client_dir, unbundled: true)
         ok ? 0 : 1
       end
 
       private
 
+      def extract_option_value!(args, *flags)
+        flags.each do |flag|
+          index = args.index(flag)
+          next unless index
+
+          value = args[index + 1]
+          args.slice!(index, 2)
+          return value
+        end
+        nil
+      end
+
+      def ensure_flutter_client_dir(verbose: false)
+        client_dir = detect_flutter_client_dir
+        return client_dir if client_dir
+
+        bootstrapped = bootstrap_flutter_client_template
+        build_log(verbose, "bootstrapped client template at #{bootstrapped}") if bootstrapped
+        bootstrapped
+      end
+
+      def build_tool_env(env, platform, client_dir = nil)
+        return env unless %w[ios macos].include?(platform)
+
+        apple_env = unbundled_command_env(env)
+        apple_env["PATH"] = apple_build_path(apple_env["PATH"])
+        install_apple_pod_shim(client_dir, apple_env) if client_dir
+        apple_env
+      end
+
+      def install_tool_env(env, client_dir)
+        return build_tool_env(env, inferred_install_platform, client_dir) if inferred_install_platform
+
+        command_env = unbundled_command_env(env)
+        command_env["PATH"] = apple_build_path(command_env["PATH"])
+        install_apple_pod_shim(client_dir, command_env)
+        command_env
+      end
+
+      def inferred_install_platform
+        host_os = RbConfig::CONFIG["host_os"]
+        return "ios" if host_os.match?(/darwin/i)
+
+        nil
+      end
+
+      def export_platform_build_outputs(client_dir, platform, verbose: false)
+        exports_for(platform).each do |relative_source, relative_target|
+          source = File.join(client_dir, "build", relative_source)
+          next unless File.exist?(source)
+
+          target = File.join(user_build_root, relative_target)
+          FileUtils.rm_rf(target)
+          FileUtils.mkdir_p(File.dirname(target))
+          FileUtils.cp_r(source, target)
+          build_log(verbose, "exported #{source} -> #{target}")
+        end
+      end
+
+      def sync_built_outputs_for_install(client_dir, platform: nil, verbose: false)
+        synced = false
+
+        platforms =
+          if platform
+            install_sync_platforms(platform)
+          else
+            %w[android ios macos windows linux web apk aab appbundle]
+          end
+
+        platforms.each do |target_platform|
+          exports_for(target_platform).each do |relative_source, relative_target|
+            source = File.join(user_build_root, relative_target)
+            next unless File.exist?(source)
+
+            target = File.join(client_dir, "build", relative_source)
+            FileUtils.rm_rf(target)
+            FileUtils.mkdir_p(File.dirname(target))
+            FileUtils.cp_r(source, target)
+            build_log(verbose, "synced #{source} -> #{target}")
+            synced = true
+          end
+        end
+
+        synced
+      end
+
+      def install_sync_platforms(platform)
+        case platform
+        when "ios"
+          %w[ios]
+        when "android"
+          %w[android apk aab appbundle]
+        when "macos"
+          %w[macos]
+        when "windows"
+          %w[windows]
+        when "linux"
+          %w[linux]
+        when "web"
+          %w[web]
+        else
+          []
+        end
+      end
+
+      def install_platform_for_device(device_id)
+        return inferred_install_platform unless device_id
+
+        return "android" if device_id.include?("emulator-") || device_id.match?(/\A[a-z0-9._:-]+\z/i) && device_id != "macos" && device_id != "chrome" && !device_id.include?("-")
+        return "ios" if device_id.match?(/\A[0-9A-F-]{8,}\z/i)
+        return "macos" if device_id == "macos"
+        return "web" if device_id == "chrome"
+
+        inferred_install_platform
+      end
+
+      def validate_install_artifacts(client_dir, platform:, device_id:)
+        return true unless platform == "ios"
+
+        return validate_ios_simulator_install_artifacts(client_dir) if ios_simulator_device_id?(device_id)
+
+        device_app = File.join(client_dir, "build", "ios", "iphoneos", "Runner.app")
+        return true unless Dir.exist?(device_app)
+        return true if ios_app_signed?(device_app)
+
+        warn "install config error: iOS device app bundle is not code signed"
+        warn "Rebuild for a device with: ruflet build ios --self"
+        warn "If you intentionally built without signing, install from Xcode or rebuild without --no-codesign."
+        false
+      end
+
+      def validate_ios_simulator_install_artifacts(client_dir)
+        simulator_app = File.join(client_dir, "build", "ios", "iphonesimulator", "Runner.app")
+        return true if Dir.exist?(simulator_app)
+
+        device_app = File.join(client_dir, "build", "ios", "iphoneos", "Runner.app")
+        if Dir.exist?(device_app)
+          warn "install config error: selected device is an iOS simulator, but the latest build is for iphoneos"
+          warn "Rebuild for the simulator with: ruflet build ios --self --simulator"
+        else
+          warn "install config error: no iOS simulator app bundle was found"
+          warn "Build the simulator target first with: ruflet build ios --self --simulator"
+        end
+        false
+      end
+
+      def ios_simulator_device_id?(device_id)
+        return false if device_id.to_s.strip.empty?
+
+        device_id.match?(/\A[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}\z/i)
+      end
+
+      def ios_app_signed?(app_path)
+        system("/usr/bin/codesign", "-vv", app_path, out: File::NULL, err: File::NULL)
+      end
+
+      def exports_for(platform)
+        case platform
+        when "apk", "android", "aab", "appbundle"
+          { File.join("app", "outputs") => "android" }
+        when "ios"
+          { "ios" => "ios" }
+        when "macos"
+          { "macos" => "macos" }
+        when "windows"
+          { "windows" => "windows" }
+        when "linux"
+          { "linux" => "linux" }
+        when "web"
+          { "web" => "web" }
+        else
+          {}
+        end
+      end
+
       def detect_flutter_client_dir
         env_dir = ENV["RUFLET_CLIENT_DIR"]
         return env_dir if env_dir && Dir.exist?(env_dir)
 
+        hidden = hidden_flutter_client_dir
+        return hidden if Dir.exist?(hidden)
+
         local = File.expand_path("ruflet_client", Dir.pwd)
         return local if Dir.exist?(local)
 
@@ -77,27 +327,64 @@ module Ruflet
         nil
       end
 
-      def prepare_flutter_client(client_dir, tools:, config:)
+      def bootstrap_flutter_client_template
+        return nil if ENV["RUFLET_CLIENT_DIR"]
+
+        target = hidden_flutter_client_dir
+        return target if Dir.exist?(target)
+
+        if Ruflet::CLI.respond_to?(:copy_ruflet_client_template, true)
+          Ruflet::CLI.send(:copy_ruflet_client_template, Dir.pwd)
+        end
+
+        Dir.exist?(target) ? target : nil
+      end
+
+      def hidden_flutter_client_dir(root = Dir.pwd)
+        File.join(root, "build", "client")
+      end
+
+      def user_build_root(root = Dir.pwd)
+        File.join(root, "build")
+      end
+
+      def prepare_flutter_client(client_dir, platform:, tools:, config:, self_contained: false, verbose: false)
+        refresh_managed_client_template_files(client_dir, verbose: verbose)
+        sync_client_metadata(client_dir, config, verbose: verbose)
+        configure_client_runtime_mode(client_dir, self_contained: self_contained, verbose: verbose)
         apply_service_extension_config(client_dir, config)
         asset_flags = apply_build_config(client_dir, config)
         if asset_flags[:error]
           warn asset_flags[:error]
           return false
         end
-        unless system(tools[:env], tools[:flutter], "pub", "get", chdir: client_dir)
+        announce_asset_configuration(asset_flags)
+        clear_flutter_build_state(client_dir, verbose: verbose)
+        clear_stale_platform_outputs(client_dir, platform, verbose: verbose)
+        build_note("Resolving Flutter packages")
+        build_log(verbose, "running flutter pub get")
+        unless run_external_command(tools[:env], tools[:flutter], "pub", "get", chdir: client_dir, unbundled: true)
           warn "flutter pub get failed"
           return false
         end
 
+        unless ensure_native_build_dependencies(client_dir, platform, tools[:env], verbose: verbose)
+          return false
+        end
+
         if asset_flags[:has_splash]
-          unless system(tools[:env], tools[:dart], "run", "flutter_native_splash:create", chdir: client_dir)
+          build_note("Generating splash screen with flutter_native_splash")
+          build_log(verbose, "running flutter_native_splash:create")
+          unless run_external_command(tools[:env], tools[:dart], "run", "flutter_native_splash:create", chdir: client_dir, unbundled: true)
             warn "flutter_native_splash failed"
             return false
           end
         end
 
         if asset_flags[:has_icon]
-          unless system(tools[:env], tools[:dart], "run", "flutter_launcher_icons", chdir: client_dir)
+          build_note("Generating launcher icons with flutter_launcher_icons")
+          build_log(verbose, "running flutter_launcher_icons")
+          unless run_external_command(tools[:env], tools[:dart], "run", "flutter_launcher_icons", chdir: client_dir, unbundled: true)
             warn "flutter_launcher_icons failed"
             return false
           end
@@ -106,9 +393,111 @@ module Ruflet
         true
       end
 
-      def configured_client_url(config)
+      def ensure_native_build_dependencies(client_dir, platform, env, verbose: false)
+        case platform
+        when "ios"
+          ensure_cocoapods_install(client_dir, "ios", env, verbose: verbose)
+        when "macos"
+          ok = true
+          ok &&= ensure_cocoapods_install(client_dir, "ios", env, verbose: verbose)
+          ok &&= ensure_cocoapods_install(client_dir, "macos", env, verbose: verbose)
+          ok
+        else
+          true
+        end
+      end
+
+      def ensure_cocoapods_install(client_dir, platform_dir, env, verbose: false)
+        pod_dir = File.join(client_dir, platform_dir)
+        return true unless Dir.exist?(pod_dir)
+        return true unless File.file?(File.join(pod_dir, "Podfile"))
+
+        build_note("Running CocoaPods install for #{platform_dir}")
+        build_log(verbose, "pod install in #{pod_dir}")
+        ok =
+          if defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)
+            Bundler.with_unbundled_env do
+              run_external_command(unbundled_command_env(env), "pod", "install", chdir: pod_dir, unbundled: false)
+            end
+          else
+            run_external_command(unbundled_command_env(env), "pod", "install", chdir: pod_dir, unbundled: false)
+          end
+        return true if ok
+
+        warn "CocoaPods install failed for #{platform_dir}"
+        warn "Make sure `pod` is installed and working for the Ruby used by Flutter."
+        false
+      end
+
+      def unbundled_command_env(env)
+        sanitized_env = env.reject { |key, _value| key.start_with?("BUNDLE_") || key == "RUBYOPT" || key == "RUBYLIB" }
+        cleared_env = {}
+        ENV.each_key do |key|
+          next unless key.start_with?("BUNDLE_") || key == "RUBYOPT" || key == "RUBYLIB" || key.start_with?("GEM_")
+
+          cleared_env[key] = nil
+        end
+
+        cleared_env.merge(sanitized_env)
+      end
+
+      def run_external_command(env, *cmd, chdir:, unbundled: false)
+        if unbundled && defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)
+          Bundler.with_unbundled_env do
+            system(env, *cmd, chdir: chdir)
+          end
+        else
+          system(env, *cmd, chdir: chdir)
+        end
+      end
+
+      def apple_build_path(existing_path)
+        segments = existing_path.to_s.split(File::PATH_SEPARATOR)
+        segments.reject! { |segment| segment.include?("/.gem/ruby/") && segment.end_with?("/bin") }
+
+        preferred = []
+        preferred << "/opt/homebrew/bin" if File.executable?("/opt/homebrew/bin/pod")
+        preferred << "/usr/local/bin" if File.executable?("/usr/local/bin/pod")
+
+        (preferred + segments).uniq.join(File::PATH_SEPARATOR)
+      end
+
+      def install_apple_pod_shim(client_dir, env)
+        pod_executable = resolve_working_pod_executable
+        return unless pod_executable
+
+        shim_dir = File.join(client_dir, ".ruflet", "bin")
+        FileUtils.mkdir_p(shim_dir)
+        shim_path = File.join(shim_dir, "pod")
+        File.write(
+          shim_path,
+          <<~SH
+            #!/bin/sh
+            exec "#{pod_executable}" "$@"
+          SH
+        )
+        FileUtils.chmod("+x", shim_path)
+        env["PATH"] = ([shim_dir] + env["PATH"].to_s.split(File::PATH_SEPARATOR)).uniq.join(File::PATH_SEPARATOR)
+        env["COCOAPODS_DISABLE_STATS"] = "true"
+        env["GEM_HOME"] = nil
+        env["GEM_PATH"] = nil
+        env["GEM_ROOT"] = nil
+      end
+
+      def resolve_working_pod_executable
+        return "/opt/homebrew/bin/pod" if File.executable?("/opt/homebrew/bin/pod")
+        return "/usr/local/bin/pod" if File.executable?("/usr/local/bin/pod")
+
+        nil
+      end
+
+      def configured_backend_url(config)
         candidates = [
+          config["backend_url"],
+          config["server_url"],
           config["ruflet_client_url"],
+          (config["app"].is_a?(Hash) ? config["app"]["backend_url"] : nil),
+          (config["app"].is_a?(Hash) ? config["app"]["server_url"] : nil),
           (config["app"].is_a?(Hash) ? config["app"]["ruflet_client_url"] : nil)
         ]
         raw = candidates.find { |v| !v.to_s.strip.empty? }
@@ -196,19 +585,38 @@ module Ruflet
         end
         copy_asset.call(icon_macos, "icon_macos.png")
 
+        default_splash = File.file?(File.join(assets_dir, "splash.png"))
+        default_icon = File.file?(File.join(assets_dir, "icon.png"))
+
+        using_default_splash = false
+        using_default_icon = false
+
         if splash_defined && splash.nil?
-          return { has_icon: false, has_splash: false, error: "build config error: splash_screen is set but file was not found" }
+          if default_splash
+            using_default_splash = true
+            build_note("Configured splash_screen was not found; using default template asset assets/splash.png")
+          else
+            return { has_icon: false, has_splash: false, error: "build config error: splash_screen is set but file was not found, and no default splash asset exists" }
+          end
         end
         if icon_defined && icon.nil?
-          return { has_icon: false, has_splash: false, error: "build config error: icon_launcher is set but file was not found" }
+          if default_icon
+            using_default_icon = true
+            build_note("Configured icon_launcher was not found; using default template asset assets/icon.png")
+          else
+            return { has_icon: false, has_splash: false, error: "build config error: icon_launcher is set but file was not found, and no default icon asset exists" }
+          end
         end
 
+        has_splash = !splash.nil? || default_splash
+        has_icon = !icon.nil? || default_icon
+
         pubspec_path = File.join(client_dir, "pubspec.yaml")
         unless File.file?(pubspec_path)
-          return { has_icon: icon_defined && !icon.nil?, has_splash: splash_defined && !splash.nil?, error: nil }
+          return { has_icon: has_icon, has_splash: has_splash, error: nil }
         end
 
-        if icon_defined && icon
+        if has_icon
           update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path", "\"assets/icon.png\"", multiple: true)
         end
         update_pubspec_value(pubspec_path, "flutter_launcher_icons", "image_path_android", "\"assets/icon_android.png\"", multiple: true) if icon_android
@@ -223,12 +631,306 @@ module Ruflet
         update_pubspec_value(pubspec_path, "flutter_launcher_icons", "background_color", "\"#{icon_background}\"") if icon_background
         update_pubspec_value(pubspec_path, "flutter_launcher_icons", "theme_color", "\"#{theme_color}\"") if theme_color
 
-        update_pubspec_value(pubspec_path, "flutter_native_splash", "image", "\"assets/splash.png\"") if splash_defined && splash
+        update_pubspec_value(pubspec_path, "flutter_native_splash", "image", "\"assets/splash.png\"") if has_splash
         update_pubspec_value(pubspec_path, "flutter_native_splash", "image_dark", "\"assets/splash_dark.png\"") if splash_dark
         update_pubspec_value(pubspec_path, "flutter_native_splash", "color", "\"#{splash_color}\"") if splash_color
         update_pubspec_value(pubspec_path, "flutter_native_splash", "color_dark", "\"#{splash_dark_color}\"") if splash_dark_color
 
-        { has_icon: icon_defined && !icon.nil?, has_splash: splash_defined && !splash.nil?, error: nil }
+        {
+          has_icon: has_icon,
+          has_splash: has_splash,
+          using_default_icon: using_default_icon,
+          using_default_splash: using_default_splash,
+          error: nil
+        }
+      end
+
+      def sync_client_metadata(client_dir, config = {}, verbose: false)
+        metadata = build_client_metadata(config, client_dir)
+        apply_pubspec_metadata(client_dir, metadata)
+        apply_android_metadata(client_dir, metadata)
+        apply_ios_metadata(client_dir, metadata)
+        apply_macos_metadata(client_dir, metadata)
+        apply_web_metadata(client_dir, metadata)
+        apply_windows_metadata(client_dir, metadata)
+        apply_linux_metadata(client_dir, metadata)
+        build_log(
+          verbose,
+          "app=#{metadata[:display_name]} package=#{metadata[:package_name]} org=#{metadata[:organization]} bundle=#{metadata[:bundle_identifier]}"
+        )
+      end
+
+      def build_client_metadata(config, client_dir)
+        app = config["app"].is_a?(Hash) ? config["app"] : {}
+        current_pubspec = load_client_pubspec(client_dir)
+        current_name = current_pubspec["name"].to_s
+        inferred_display_name = app["name"] || config["name"] || humanize_name(File.basename(Dir.pwd))
+        package_name = normalize_package_name(app["package_name"] || config["package_name"] || current_name || inferred_display_name)
+        display_name = first_present(app["display_name"], app["name"], config["display_name"], config["name"], humanize_name(package_name))
+        organization = normalize_bundle_prefix(
+          first_present(app["org"], app["organization"], config["org"], config["organization"], "com.example")
+        )
+        bundle_identifier = normalize_bundle_identifier(
+          first_present(app["bundle_identifier"], config["bundle_identifier"], "#{organization}.#{package_name}")
+        )
+
+        {
+          package_name: package_name,
+          display_name: display_name,
+          description: first_present(app["description"], config["description"], current_pubspec["description"], "A new Flutter project."),
+          version: first_present(app["version"], config["version"], current_pubspec["version"], "1.0.0+1"),
+          organization: organization,
+          company_name: first_present(app["company_name"], config["company_name"], organization),
+          bundle_identifier: bundle_identifier,
+          android_application_id: normalize_bundle_identifier(
+            first_present(app["android_application_id"], config["android_application_id"], bundle_identifier)
+          ),
+          ios_bundle_identifier: normalize_bundle_identifier(
+            first_present(app["ios_bundle_identifier"], config["ios_bundle_identifier"], bundle_identifier)
+          ),
+          macos_bundle_identifier: normalize_bundle_identifier(
+            first_present(app["macos_bundle_identifier"], config["macos_bundle_identifier"], bundle_identifier)
+          ),
+          linux_application_id: normalize_bundle_identifier(
+            first_present(app["linux_application_id"], config["linux_application_id"], bundle_identifier)
+          ),
+          short_name: first_present(app["short_name"], config["short_name"], display_name)
+        }
+      end
+
+      def load_client_pubspec(client_dir)
+        pubspec_path = File.join(client_dir, "pubspec.yaml")
+        return {} unless File.file?(pubspec_path)
+
+        YAML.safe_load(File.read(pubspec_path), aliases: true) || {}
+      rescue StandardError
+        {}
+      end
+
+      def apply_pubspec_metadata(client_dir, metadata)
+        pubspec_path = File.join(client_dir, "pubspec.yaml")
+        return unless File.file?(pubspec_path)
+
+        data = YAML.safe_load(File.read(pubspec_path), aliases: true) || {}
+        data["name"] = metadata[:package_name]
+        data["description"] = metadata[:description]
+        data["version"] = metadata[:version]
+        write_pubspec_yaml(pubspec_path, data)
+      end
+
+      def apply_android_metadata(client_dir, metadata)
+        gradle_path = File.join(client_dir, "android", "app", "build.gradle.kts")
+        replace_in_file(
+          gradle_path,
+          /^\s*namespace = ".*"$/,
+          %(    namespace = "#{metadata[:android_application_id]}")
+        )
+        replace_in_file(
+          gradle_path,
+          /^\s*applicationId = ".*"$/,
+          %(        applicationId = "#{metadata[:android_application_id]}")
+        )
+
+        manifest_path = File.join(client_dir, "android", "app", "src", "main", "AndroidManifest.xml")
+        replace_in_file(
+          manifest_path,
+          /android:label="[^"]*"/,
+          %(android:label="#{xml_escape(metadata[:display_name])}")
+        )
+      end
+
+      def apply_ios_metadata(client_dir, metadata)
+        info_plist_path = File.join(client_dir, "ios", "Runner", "Info.plist")
+        replace_plist_value(info_plist_path, "CFBundleDisplayName", metadata[:display_name])
+        replace_plist_value(info_plist_path, "CFBundleName", metadata[:display_name])
+
+        pbxproj_path = File.join(client_dir, "ios", "Runner.xcodeproj", "project.pbxproj")
+        return unless File.file?(pbxproj_path)
+
+        content = File.read(pbxproj_path)
+        content.gsub!(/INFOPLIST_KEY_CFBundleDisplayName = "[^"]*";/, %(INFOPLIST_KEY_CFBundleDisplayName = "#{xcode_escape(metadata[:display_name])}";))
+        content.gsub!(/PRODUCT_BUNDLE_IDENTIFIER = ([^;]+);/) do |match|
+          identifier = Regexp.last_match(1).to_s.strip
+          if identifier.include?("RunnerTests")
+            match
+          else
+            "PRODUCT_BUNDLE_IDENTIFIER = #{metadata[:ios_bundle_identifier]};"
+          end
+        end
+        File.write(pbxproj_path, content)
+      end
+
+      def apply_macos_metadata(client_dir, metadata)
+        app_info_path = File.join(client_dir, "macos", "Runner", "Configs", "AppInfo.xcconfig")
+        replace_in_file(
+          app_info_path,
+          /^PRODUCT_NAME = .*$/,
+          "PRODUCT_NAME = #{metadata[:display_name]}"
+        )
+        replace_in_file(
+          app_info_path,
+          /^PRODUCT_BUNDLE_IDENTIFIER = .*$/,
+          "PRODUCT_BUNDLE_IDENTIFIER = #{metadata[:macos_bundle_identifier]}"
+        )
+        replace_in_file(
+          app_info_path,
+          /^PRODUCT_COPYRIGHT = .*$/,
+          "PRODUCT_COPYRIGHT = Copyright © #{Time.now.year} #{metadata[:company_name]}. All rights reserved."
+        )
+      end
+
+      def apply_web_metadata(client_dir, metadata)
+        manifest_path = File.join(client_dir, "web", "manifest.json")
+        if File.file?(manifest_path)
+          data = JSON.parse(File.read(manifest_path))
+          data["name"] = metadata[:display_name]
+          data["short_name"] = metadata[:short_name]
+          data["description"] = metadata[:description]
+          File.write(manifest_path, JSON.pretty_generate(data) + "\n")
+        end
+
+        index_path = File.join(client_dir, "web", "index.html")
+        replace_in_file(
+          index_path,
+          /<meta name="description" content="[^"]*">/,
+          %(<meta name="description" content="#{html_escape(metadata[:description])}">)
+        )
+        replace_in_file(
+          index_path,
+          /<meta name="apple-mobile-web-app-title" content="[^"]*">/,
+          %(<meta name="apple-mobile-web-app-title" content="#{html_escape(metadata[:short_name])}">)
+        )
+        replace_in_file(
+          index_path,
+          /<title>.*<\/title>/,
+          "<title>#{html_escape(metadata[:display_name])}</title>"
+        )
+      end
+
+      def apply_windows_metadata(client_dir, metadata)
+        cmake_path = File.join(client_dir, "windows", "CMakeLists.txt")
+        replace_in_file(cmake_path, /^project\(.*\)$/, "project(#{metadata[:package_name]} LANGUAGES CXX)")
+        replace_in_file(cmake_path, /^set\(BINARY_NAME ".*"\)$/, %(set(BINARY_NAME "#{metadata[:package_name]}")))
+
+        runner_rc_path = File.join(client_dir, "windows", "runner", "Runner.rc")
+        replace_in_file(
+          runner_rc_path,
+          /VALUE "CompanyName", ".*" "\\0"/,
+          %(VALUE "CompanyName", "#{windows_string_escape(metadata[:company_name])}" "\\0")
+        )
+        replace_in_file(
+          runner_rc_path,
+          /VALUE "FileDescription", ".*" "\\0"/,
+          %(VALUE "FileDescription", "#{windows_string_escape(metadata[:display_name])}" "\\0")
+        )
+        replace_in_file(
+          runner_rc_path,
+          /VALUE "InternalName", ".*" "\\0"/,
+          %(VALUE "InternalName", "#{windows_string_escape(metadata[:package_name])}" "\\0")
+        )
+        replace_in_file(
+          runner_rc_path,
+          /VALUE "LegalCopyright", ".*" "\\0"/,
+          %(VALUE "LegalCopyright", "Copyright (C) #{Time.now.year} #{windows_string_escape(metadata[:company_name])}. All rights reserved." "\\0")
+        )
+        replace_in_file(
+          runner_rc_path,
+          /VALUE "OriginalFilename", ".*" "\\0"/,
+          %(VALUE "OriginalFilename", "#{windows_string_escape(metadata[:package_name])}.exe" "\\0")
+        )
+        replace_in_file(
+          runner_rc_path,
+          /VALUE "ProductName", ".*" "\\0"/,
+          %(VALUE "ProductName", "#{windows_string_escape(metadata[:display_name])}" "\\0")
+        )
+      end
+
+      def apply_linux_metadata(client_dir, metadata)
+        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]}")))
+      end
+
+      def replace_plist_value(path, key, value)
+        return unless File.file?(path)
+
+        content = File.read(path)
+        pattern = %r{(<key>#{Regexp.escape(key)}</key>\s*<string>)(.*?)(</string>)}m
+        updated = content.gsub(pattern) do
+          "#{Regexp.last_match(1)}#{xml_escape(value)}#{Regexp.last_match(3)}"
+        end
+        File.write(path, updated) unless updated == content
+      end
+
+      def replace_in_file(path, pattern, replacement)
+        return unless File.file?(path)
+
+        content = File.read(path)
+        updated = content.gsub(pattern, replacement)
+        File.write(path, updated) unless updated == content
+      end
+
+      def first_present(*values)
+        values.find { |value| !value.to_s.strip.empty? }
+      end
+
+      def normalize_package_name(value)
+        normalized = value.to_s.strip.downcase.gsub(/[^a-z0-9_]+/, "_")
+        normalized.gsub!(/\A_+|_+\z/, "")
+        normalized.gsub!(/_+/, "_")
+        normalized = "ruflet_client" if normalized.empty?
+        normalized = "app_#{normalized}" if normalized.match?(/\A\d/)
+        normalized
+      end
+
+      def normalize_bundle_prefix(value)
+        segments = value.to_s.strip.downcase.split(".").map do |segment|
+          normalized = segment.gsub(/[^a-z0-9_]+/, "")
+          normalized = "app" if normalized.empty?
+          normalized = "app#{normalized}" if normalized.match?(/\A\d/)
+          normalized
+        end
+        segments.reject!(&:empty?)
+        segments = %w[com example] if segments.empty?
+        segments.join(".")
+      end
+
+      def normalize_bundle_identifier(value)
+        segments = value.to_s.strip.downcase.split(".").map do |segment|
+          normalized = segment.gsub(/[^a-z0-9_]+/, "_")
+          normalized.gsub!(/\A_+|_+\z/, "")
+          normalized = "app" if normalized.empty?
+          normalized = "app#{normalized}" if normalized.match?(/\A\d/)
+          normalized
+        end
+        segments.reject!(&:empty?)
+        segments = %w[com example ruflet_client] if segments.empty?
+        segments.join(".")
+      end
+
+      def humanize_name(name)
+        name.to_s.gsub(/[_-]+/, " ").split.map(&:capitalize).join(" ")
+      end
+
+      def xml_escape(value)
+        value.to_s
+             .gsub("&", "&amp;")
+             .gsub("<", "&lt;")
+             .gsub(">", "&gt;")
+             .gsub('"', "&quot;")
+             .gsub("'", "&apos;")
+      end
+
+      def html_escape(value)
+        xml_escape(value)
+      end
+
+      def xcode_escape(value)
+        value.to_s.gsub("\\", "\\\\\\").gsub('"', '\"')
+      end
+
+      def windows_string_escape(value)
+        value.to_s.gsub('"', '""')
       end
 
       def key_defined?(hash, key)
@@ -242,9 +944,263 @@ module Ruflet
         extension_aliases = extension_keys.filter_map { |key| CLIENT_EXTENSION_MAP[key]&.fetch(:alias) }.uniq
 
         pubspec_path = File.join(client_dir, "pubspec.yaml")
-        main_path = File.join(client_dir, "lib", "main.dart")
         prune_client_pubspec(pubspec_path, extension_packages) if File.file?(pubspec_path)
-        prune_client_main(main_path, extension_aliases) if File.file?(main_path)
+        client_entrypoint_paths(client_dir).each do |entrypoint|
+          prune_client_main(entrypoint, extension_aliases) if File.file?(entrypoint)
+        end
+      end
+
+      def clear_flutter_build_state(client_dir, verbose: false)
+        flutter_build_dir = File.join(client_dir, ".dart_tool", "flutter_build")
+        return unless Dir.exist?(flutter_build_dir)
+
+        FileUtils.rm_rf(flutter_build_dir)
+        build_log(verbose, "cleared .dart_tool/flutter_build")
+      end
+
+      def clear_stale_platform_outputs(client_dir, platform, verbose: false)
+        return unless platform == "ios"
+
+        stale_paths = %w[
+          build/ios/Debug-iphonesimulator
+          build/ios/iphonesimulator
+        ]
+
+        stale_paths.each do |relative_path|
+          path = File.join(client_dir, relative_path)
+          next unless Dir.exist?(path)
+
+          FileUtils.rm_rf(path)
+          build_log(verbose, "cleared stale #{relative_path}")
+        end
+      end
+
+      def client_entrypoint_paths(client_dir)
+        %w[main.dart main.self.dart main.server.dart].map do |name|
+          File.join(client_dir, "lib", name)
+        end
+      end
+
+      def configure_client_runtime_mode(client_dir, self_contained:, verbose: false)
+        build_log(verbose, "configuring #{self_contained ? 'self-contained' : 'server-driven'} runtime")
+        sync_client_pubspec_for_runtime_mode(client_dir, self_contained: self_contained)
+        if self_contained
+          sync_self_contained_project_assets(client_dir, verbose: verbose)
+          remove_local_ruby_runtime_override(client_dir, verbose: verbose)
+        else
+          remove_self_contained_project_assets(client_dir, verbose: verbose)
+          remove_local_ruby_runtime_override(client_dir, verbose: verbose)
+        end
+      end
+
+      def sync_client_pubspec_for_runtime_mode(client_dir, self_contained:)
+        pubspec_path = File.join(client_dir, "pubspec.yaml")
+        return unless File.file?(pubspec_path)
+
+        data = YAML.safe_load(File.read(pubspec_path), aliases: true) || {}
+        dependencies = data["dependencies"]
+        dependencies = data["dependencies"] = {} unless dependencies.is_a?(Hash)
+        flutter = data["flutter"]
+        flutter = data["flutter"] = {} unless flutter.is_a?(Hash)
+        assets = Array(flutter["assets"]).map(&:to_s)
+
+        if self_contained
+          dependencies["ruby_runtime"] = "^0.0.3"
+          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)
+        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?
+        flutter.delete("assets") if assets.empty?
+        write_pubspec_yaml(pubspec_path, data)
+      end
+
+      def refresh_managed_client_template_files(client_dir, verbose: false)
+        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 && Dir.exist?(template_root)
+
+        managed_files = [
+          "lib/main.dart",
+          "lib/main.self.dart",
+          "lib/main.server.dart",
+          "lib/connection_probe.dart",
+          "lib/connection_probe_io.dart",
+          "lib/connection_probe_stub.dart"
+        ]
+
+        managed_files.each do |relative_path|
+          source = File.join(template_root, relative_path)
+          next unless File.file?(source)
+
+          destination = File.join(client_dir, relative_path)
+          FileUtils.mkdir_p(File.dirname(destination))
+          FileUtils.cp(source, destination)
+          build_log(verbose, "refreshed template file #{relative_path}")
+        end
+      end
+
+      def write_pubspec_yaml(path, data)
+        content = YAML.dump(data)
+        content = content.sub(/\A---\n/, "")
+
+        content = indent_pubspec_sequences(content)
+
+        File.write(path, content)
+      end
+
+      def indent_pubspec_sequences(content)
+        current_key_indent = nil
+        content.lines.map do |line|
+          if (match = line.match(/\A(\s*)[^#\s][^:]*:\s*(?:#.*)?\n?\z/))
+            current_key_indent = match[1].length
+          elsif (match = line.match(/\A(\s*)-\s/)) && current_key_indent && match[1].length <= current_key_indent
+            line = (" " * (current_key_indent + 2)) + line.lstrip
+          end
+
+          line
+        end.join
+      end
+
+      def sync_self_contained_project_assets(client_dir, verbose: false)
+        project_root = Pathname.new(Dir.pwd)
+        assets_root = File.join(client_dir, "assets")
+        destination_root = File.join(assets_root, self_contained_project_name)
+        FileUtils.rm_rf(destination_root)
+        FileUtils.rm_rf(File.join(assets_root, "ruby_project"))
+        FileUtils.mkdir_p(destination_root)
+
+        legacy_entrypoint = File.join(client_dir, "assets", "main.rb")
+        FileUtils.rm_f(legacy_entrypoint)
+
+        copied = 0
+        project_asset_relative_paths.each do |relative_path|
+          source = project_root.join(relative_path)
+          next unless source.exist? && source.file?
+
+          destination = File.join(destination_root, relative_path)
+          FileUtils.mkdir_p(File.dirname(destination))
+          FileUtils.cp(source.to_s, destination)
+          copied += 1
+        end
+
+        build_log(verbose, "copied #{copied} project file#{copied == 1 ? '' : 's'} to assets/#{self_contained_project_name}")
+      end
+
+      def remove_self_contained_project_assets(client_dir, verbose: false)
+        assets_root = File.join(client_dir, "assets")
+        legacy_entrypoint = File.join(client_dir, "assets", "main.rb")
+        FileUtils.rm_f(legacy_entrypoint)
+        removed = false
+
+        project_root = File.join(assets_root, self_contained_project_name)
+        if Dir.exist?(project_root)
+          FileUtils.rm_rf(project_root)
+          removed = true
+        end
+
+        legacy_root = File.join(assets_root, "ruby_project")
+        if Dir.exist?(legacy_root)
+          FileUtils.rm_rf(legacy_root)
+          removed = true
+        end
+
+        build_log(verbose, "removed embedded self-contained project assets") if removed
+      end
+
+      def project_asset_relative_paths
+        root = Pathname.new(Dir.pwd)
+        included = []
+
+        Find.find(root.to_s) do |path|
+          pathname = Pathname.new(path)
+          relative = pathname.relative_path_from(root).to_s
+          next if relative.empty?
+
+          if pathname.directory?
+            if skip_project_asset_directory?(relative)
+              Find.prune
+            else
+              next
+            end
+          end
+
+          next unless include_project_asset_file?(relative)
+
+          included << relative
+        end
+
+        included.sort
+      end
+
+      def self_contained_project_name
+        name = File.basename(Dir.pwd.to_s)
+        name = "app" if name.to_s.strip.empty?
+        name
+      end
+
+      def skip_project_asset_directory?(relative)
+        first = relative.split(File::SEPARATOR).first
+        %w[
+          .git
+          .bundle
+          .dart_tool
+          .idea
+          .ruby-lsp
+          .vscode
+          build
+          coverage
+          log
+          node_modules
+          pkg
+          ruflet_client
+          tmp
+          vendor
+        ].include?(first)
+      end
+
+      def include_project_asset_file?(relative)
+        basename = File.basename(relative)
+        return false if %w[Gemfile.lock pubspec.lock Podfile.lock package-lock.json yarn.lock pnpm-lock.yaml].include?(basename)
+        return true if %w[main.rb Gemfile ruflet.yaml ruflet.yml manifest.json].include?(basename)
+
+        ext = File.extname(relative).downcase
+        return true if %w[.rb .json .yml .yaml].include?(ext)
+
+        first = relative.split(File::SEPARATOR).first
+        return true if first == "assets"
+
+        false
+      end
+
+      def flutter_target_entrypoint(client_dir, self_contained:)
+        candidate = File.join(
+          client_dir,
+          "lib",
+          self_contained ? "main.self.dart" : "main.server.dart"
+        )
+        return nil unless File.file?(candidate)
+
+        File.join("lib", File.basename(candidate))
+      end
+
+      def remove_local_ruby_runtime_override(client_dir, verbose: false)
+        overrides_path = File.join(client_dir, "pubspec_overrides.yaml")
+        return unless File.file?(overrides_path)
+
+        File.delete(overrides_path)
+        build_log(verbose, "removed ruby_runtime override")
+      rescue StandardError => e
+        warn "Failed to remove ruby_runtime override: #{e.class}: #{e.message}"
       end
 
       def normalize_extension_key(value)
@@ -274,38 +1230,34 @@ module Ruflet
       end
 
       def prune_client_main(path, selected_aliases)
-        lines = File.readlines(path)
+        content = File.read(path)
         alias_to_package = {}
 
-        lines.each do |line|
-          match = line.match(%r{\Aimport 'package:(flet_[^/]+)/\1\.dart' as ([a-zA-Z0-9_]+);})
-          next unless match
-
-          alias_to_package[match[2]] = match[1]
+        content.scan(%r{^import 'package:(flet_[^/]+)/\1\.dart'\s+as ([a-zA-Z0-9_]+);$}m) do |package_name, import_alias|
+          alias_to_package[import_alias] = package_name
         end
 
-        kept = lines.select do |line|
-          import_match = line.match(%r{\Aimport 'package:(flet_[^/]+)/\1\.dart' as ([a-zA-Z0-9_]+);})
-          if import_match
-            package_name = import_match[1]
-            next true if package_name == "flet"
-            next true if selected_aliases.include?(import_match[2])
-            next false
+        content = content.gsub(%r{^import 'package:(flet_[^/]+)/\1\.dart'\s+as ([a-zA-Z0-9_]+);\n}m) do |match|
+          package_name = Regexp.last_match(1)
+          import_alias = Regexp.last_match(2)
+          if package_name == "flet" || selected_aliases.include?(import_alias)
+            match
+          else
+            ""
           end
+        end
 
-          extension_match = line.match(/\A\s*([a-zA-Z0-9_]+)\.Extension\(\),\s*\z/)
-          if extension_match
-            extension_alias = extension_match[1]
-            package_name = alias_to_package[extension_alias]
-            next true if package_name.nil?
-            next true if selected_aliases.include?(extension_alias)
-            next false
+        content = content.gsub(/^(\s*)([a-zA-Z0-9_]+)\.Extension\(\),\s*$/) do |match|
+          extension_alias = Regexp.last_match(2)
+          package_name = alias_to_package[extension_alias]
+          if package_name.nil? || selected_aliases.include?(extension_alias)
+            match
+          else
+            ""
           end
-
-          true
         end
 
-        File.write(path, kept.join)
+        File.write(path, content)
       end
 
       def update_pubspec_value(path, block, key, value, multiple: false)
@@ -354,7 +1306,7 @@ module Ruflet
         when "aab", "appbundle"
           ["build", "appbundle"]
         when "ios"
-          ["build", "ios", "--no-codesign"]
+          ["build", "ios"]
         when "web"
           ["build", "web"]
         when "macos"
@@ -367,6 +1319,47 @@ module Ruflet
           nil
         end
       end
+
+      def ios_device_build_needs_codesign_flag?(platform, build_args)
+        return false unless platform == "ios"
+        return false if build_args.include?("--simulator")
+        return false if build_args.include?("--no-codesign")
+        return false if build_args.include?("--codesign")
+
+        true
+      end
+
+      def build_log(verbose, message)
+        return unless verbose
+
+        puts "[ruflet build] #{message}"
+      end
+
+      def build_note(message)
+        puts "[ruflet build] #{message}"
+      end
+
+      def announce_asset_configuration(asset_flags)
+        if asset_flags[:has_splash]
+          if asset_flags[:using_default_splash]
+            build_note("Splash screen will use the default template asset")
+          else
+            build_note("Splash screen is configured")
+          end
+        else
+          build_note("No splash screen configured")
+        end
+
+        if asset_flags[:has_icon]
+          if asset_flags[:using_default_icon]
+            build_note("Launcher icons will use the default template asset")
+          else
+            build_note("Launcher icons are configured")
+          end
+        else
+          build_note("No launcher icons configured")
+        end
+      end
     end
   end
 end