ruflet 0.0.14 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d273c23251a6550ce0d8fa89003051b98f4b92ade780a048bd0c56c41ca14c81
-  data.tar.gz: e646f2912853da8f30a6b49b924c04cfb9a00fd8328f391f8a68bea0e7875fcb
+  metadata.gz: 629de90fa5d63db66ce7f96b69fcd83da284621d1bf8f3c179d2ea7b54f1591b
+  data.tar.gz: 4f91dfe6d31fe054b683f9838120fb6476501ac959e981eff19ef1809c880aa9
 SHA512:
-  metadata.gz: d6084b2b22d1775ff0849ade08bbc0ac4cb67198816add2f9d02a4c6461fef156936b2e45cd69cde3c4d7f0cc3510e9c942c245d7c2d032def1a39d4d3620c24
-  data.tar.gz: 7e73f5b93c8af40c22f7ff5c154bcf4bc40f87595ef7993144ebd7b7eccc7531fab2b72b7e0f19aa002ec2983a4b5e0d0655a5b8946c49b1a98d90185b8831c0
+  metadata.gz: 23a877adf84ca8bc119cb5452a480dd666e05f36fd6f3a1a03f75f51fa5b2ff028f07b5373b8c043a1acd43b49dc68f7885992bcb3596e279be07fed5751cb07
+  data.tar.gz: c66e78cc467a27803bbb52264444289f4a9126763c4aed1c53df6b945e1c08f0478fff277008a40c742750dde027a67c84a2209ff4d255b6b48483ffa6a21549

data/lib/ruflet/cli/android_sdk.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "rbconfig"
+require "tmpdir"
+
+module Ruflet
+  module CLI
+    # Provisions the Android toolchain so `ruflet build apk|aab|android`
+    # works on a fresh machine:
+    #
+    #   * a JDK (Gradle itself is bootstrapped by the project's Gradle
+    #     wrapper, but the wrapper needs Java)
+    #   * the Android SDK command-line tools
+    #   * platform-tools / a platform / build-tools via sdkmanager
+    #   * accepted SDK licenses
+    #
+    # An existing SDK (ANDROID_HOME, ANDROID_SDK_ROOT, or the standard
+    # per-OS install location) is always preferred; otherwise a Ruflet-managed
+    # SDK is created under ~/.ruflet/android-sdk.
+    module AndroidSdk
+      CMDLINE_TOOLS_VERSION = "11076708"
+      CMDLINE_TOOLS_BASE = "https://dl.google.com/android/repository".freeze
+      ANDROID_PLATFORM = "android-35"
+      ANDROID_BUILD_TOOLS = "35.0.0"
+      MINIMUM_JAVA_MAJOR = 17
+
+      JDK_PACKAGES = {
+        apt: "openjdk-17-jdk",
+        dnf: "java-17-openjdk-devel",
+        pacman: "jdk17-openjdk",
+        zypper: "java-17-openjdk-devel",
+        apk: "openjdk17",
+        brew: "openjdk@17",
+        winget: "EclipseAdoptium.Temurin.17.JDK",
+        choco: "temurin17"
+      }.freeze
+
+      def android_environment_setup!(fix: false, verbose: false)
+        issues = []
+
+        java = ensure_java!(fix: fix, verbose: verbose)
+        if java
+          puts "  Java: #{java[:version]} (#{java[:path]})"
+        else
+          issues << "missing JDK #{MINIMUM_JAVA_MAJOR}+"
+          warn "  Java: missing — Android builds need a JDK (Gradle wrapper requirement)."
+          warn "    #{jdk_install_hint}"
+          return issues unless fix
+        end
+
+        sdk_root = detect_android_sdk_root
+        if sdk_root
+          puts "  Android SDK: #{sdk_root}"
+        elsif fix
+          unless java
+            warn "  Android SDK: skipped (sdkmanager needs Java)"
+            return issues
+          end
+          sdk_root = install_managed_android_sdk(java, verbose: verbose)
+          unless sdk_root
+            issues << "Android SDK install failed"
+            warn "  Android SDK: install failed"
+            return issues
+          end
+          puts "  Android SDK: #{sdk_root} (installed)"
+        else
+          issues << "missing Android SDK"
+          warn "  Android SDK: missing — run `ruflet doctor --fix` to install it under #{managed_android_sdk_root}."
+          return issues
+        end
+
+        if fix && java
+          ensure_android_packages(sdk_root, java, verbose: verbose)
+          accept_android_licenses(sdk_root, java, verbose: verbose)
+        end
+
+        issues
+      end
+
+      # Environment for invoking Flutter/Gradle Android builds.
+      def android_build_env(env)
+        merged = env.dup
+        sdk_root = detect_android_sdk_root
+        if sdk_root
+          merged["ANDROID_HOME"] ||= sdk_root
+          merged["ANDROID_SDK_ROOT"] ||= sdk_root
+          platform_tools = File.join(sdk_root, "platform-tools")
+          if Dir.exist?(platform_tools)
+            merged["PATH"] = "#{platform_tools}#{File::PATH_SEPARATOR}#{merged.fetch('PATH', ENV.fetch('PATH', ''))}"
+          end
+        end
+        java_home = detect_java_home
+        merged["JAVA_HOME"] ||= java_home if java_home
+        merged
+      end
+
+      def detect_android_sdk_root
+        candidates = [
+          ENV["ANDROID_HOME"],
+          ENV["ANDROID_SDK_ROOT"],
+          default_android_sdk_location,
+          managed_android_sdk_root
+        ]
+        candidates.compact.find { |root| android_sdk_present?(root) }
+      end
+
+      def managed_android_sdk_root
+        File.join(Dir.home, ".ruflet", "android-sdk")
+      end
+
+      private
+
+      def android_sdk_present?(root)
+        return false if root.to_s.strip.empty?
+
+        Dir.exist?(File.join(root, "platform-tools")) ||
+          Dir.exist?(File.join(root, "cmdline-tools")) ||
+          Dir.exist?(File.join(root, "platforms"))
+      end
+
+      def default_android_sdk_location
+        if windows_host?
+          local = ENV["LOCALAPPDATA"].to_s
+          return File.join(local, "Android", "Sdk") unless local.empty?
+
+          nil
+        elsif macos_host?
+          File.join(Dir.home, "Library", "Android", "sdk")
+        else
+          File.join(Dir.home, "Android", "Sdk")
+        end
+      end
+
+      def ensure_java!(fix:, verbose: false)
+        java = current_java_info
+        return java if java && java[:major] >= MINIMUM_JAVA_MAJOR
+
+        return nil unless fix
+
+        manager = system_package_manager
+        package = manager && JDK_PACKAGES[manager[:id]]
+        return nil unless package
+
+        if manager[:id] == :winget
+          run_privileged_command(*manager[:install], package, verbose: verbose)
+        else
+          run_privileged_command(*manager[:install], package, verbose: verbose)
+        end
+        current_java_info
+      end
+
+      def current_java_info
+        java = which_command("java") || bundled_java_candidate
+        return nil unless java
+
+        output, status = Open3.capture2e(java, "-version")
+        return nil unless status.success?
+
+        major = parse_java_major(output)
+        return nil unless major
+
+        { path: java, major: major, version: output.lines.first.to_s.strip }
+      rescue StandardError
+        nil
+      end
+
+      def bundled_java_candidate
+        if macos_host?
+          brew_java = "/opt/homebrew/opt/openjdk@17/bin/java"
+          return brew_java if File.executable?(brew_java)
+        end
+        nil
+      end
+
+      def parse_java_major(output)
+        match = output[/version "(\d+)(?:\.(\d+))?/, 1]
+        return nil unless match
+
+        major = match.to_i
+        # "1.8" style versions report the major in the second group.
+        major = output[/version "1\.(\d+)/, 1].to_i if major == 1
+        major
+      end
+
+      def detect_java_home
+        if macos_host?
+          output, status = Open3.capture2e("/usr/libexec/java_home", "-v", MINIMUM_JAVA_MAJOR.to_s)
+          return output.strip if status.success? && !output.strip.empty?
+        end
+
+        java = which_command("java")
+        return nil unless java
+
+        resolved = File.realpath(java) rescue java
+        home = File.expand_path("../..", resolved)
+        File.directory?(File.join(home, "bin")) ? home : nil
+      end
+
+      def install_managed_android_sdk(java, verbose: false)
+        sdk_root = managed_android_sdk_root
+        tools_dir = File.join(sdk_root, "cmdline-tools", "latest")
+        return sdk_root if File.executable?(sdkmanager_bin(sdk_root))
+
+        archive_name = "commandlinetools-#{cmdline_tools_os}-#{CMDLINE_TOOLS_VERSION}_latest.zip"
+        FileUtils.mkdir_p(sdk_root)
+        Dir.mktmpdir("ruflet-android-") do |tmp|
+          archive = File.join(tmp, archive_name)
+          puts "  Downloading Android command-line tools (#{archive_name})"
+          download_file("#{CMDLINE_TOOLS_BASE}/#{archive_name}", archive)
+          extract_archive(archive, tmp)
+          extracted = File.join(tmp, "cmdline-tools")
+          raise "cmdline-tools missing from archive" unless Dir.exist?(extracted)
+
+          FileUtils.rm_rf(tools_dir)
+          FileUtils.mkdir_p(File.dirname(tools_dir))
+          FileUtils.mv(extracted, tools_dir)
+        end
+
+        File.executable?(sdkmanager_bin(sdk_root)) ? sdk_root : nil
+      rescue StandardError => e
+        warn "  Android SDK download failed: #{e.class}: #{e.message}"
+        nil
+      end
+
+      def cmdline_tools_os
+        return "win" if windows_host?
+        return "mac" if macos_host?
+
+        "linux"
+      end
+
+      def sdkmanager_bin(sdk_root)
+        name = windows_host? ? "sdkmanager.bat" : "sdkmanager"
+        File.join(sdk_root, "cmdline-tools", "latest", "bin", name)
+      end
+
+      def ensure_android_packages(sdk_root, java, verbose: false)
+        sdkmanager = sdkmanager_bin(sdk_root)
+        return unless File.executable?(sdkmanager)
+
+        packages = ["platform-tools", "platforms;#{ANDROID_PLATFORM}", "build-tools;#{ANDROID_BUILD_TOOLS}"]
+        missing = packages.reject { |package| android_package_installed?(sdk_root, package) }
+        return if missing.empty?
+
+        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)
+      end
+
+      def android_package_installed?(sdk_root, package)
+        case package
+        when "platform-tools"
+          Dir.exist?(File.join(sdk_root, "platform-tools"))
+        when /\Aplatforms;(.+)\z/
+          Dir.exist?(File.join(sdk_root, "platforms", Regexp.last_match(1)))
+        when /\Abuild-tools;(.+)\z/
+          Dir.exist?(File.join(sdk_root, "build-tools", Regexp.last_match(1)))
+        else
+          false
+        end
+      end
+
+      def accept_android_licenses(sdk_root, java, verbose: false)
+        sdkmanager = sdkmanager_bin(sdk_root)
+        return unless File.executable?(sdkmanager)
+
+        puts "  Accepting Android SDK licenses"
+        env = sdkmanager_env(java)
+        Open3.popen2e(env, sdkmanager, "--sdk_root=#{sdk_root}", "--licenses") do |stdin, stdout, wait|
+          begin
+            stdin.write("y\n" * 64)
+            stdin.close
+          rescue Errno::EPIPE
+            nil
+          end
+          stdout.each_line { |line| puts line if verbose }
+          wait.value
+        end
+      rescue StandardError => e
+        warn "  License acceptance failed: #{e.class}: #{e.message}"
+      end
+
+      def sdkmanager_env(java)
+        env = {}
+        java_home = detect_java_home
+        env["JAVA_HOME"] = java_home if java_home
+        if java && java[:path]
+          env["PATH"] = "#{File.dirname(java[:path])}#{File::PATH_SEPARATOR}#{ENV.fetch('PATH', '')}"
+        end
+        env
+      end
+
+      def jdk_install_hint
+        manager = system_package_manager
+        package = manager && JDK_PACKAGES[manager[:id]]
+        return "#{(sudo_prefix + manager[:install]).join(' ')} #{package}" if package
+
+        "install a JDK #{MINIMUM_JAVA_MAJOR}+ (e.g. Temurin: https://adoptium.net)"
+      end
+    end
+  end
+end

data/lib/ruflet/cli/build_command.rb

@@ -12,6 +12,8 @@ module Ruflet
   module CLI
     module BuildCommand
       include FlutterSdk
+      include EnvironmentSetup
+      include AndroidSdk
       CLIENT_EXTENSION_MAP = {
         "ads" => { package: "flet_ads", alias: "ruflet_ads" },
         "audio" => { package: "flet_audio", alias: "ruflet_audio" },
@@ -31,8 +33,30 @@ module Ruflet
         "webview" => { package: "flet_webview", alias: "ruflet_webview" }
       }.freeze
 
-      SERVICE_NATIVE_REQUIREMENTS = {
-        "audio_recorder" => {
+      SERVICE_EXTENSION_MAP = {
+        "camera" => %w[camera permission_handler],
+        "microphone" => %w[audio_recorder permission_handler],
+        "location" => %w[geolocator permission_handler],
+        "motion" => %w[permission_handler]
+      }.freeze
+
+      DEFAULT_SERVICE_NATIVE_REQUIREMENTS = {
+        "camera" => {
+          android_permissions: ["android.permission.CAMERA"],
+          ios_info: {
+            "NSCameraUsageDescription" => "Camera access is required for camera experiences."
+          },
+          macos_info: {
+            "NSCameraUsageDescription" => "Camera access is required for camera experiences."
+          },
+          macos_entitlements: {
+            "com.apple.security.device.camera" => true
+          },
+          ios_permission_definitions: %w[
+            PERMISSION_CAMERA=1
+          ]
+        },
+        "microphone" => {
           android_permissions: ["android.permission.RECORD_AUDIO"],
           ios_info: {
             "NSMicrophoneUsageDescription" => "Microphone access is required for audio recording."
@@ -42,14 +66,20 @@ module Ruflet
           },
           macos_entitlements: {
             "com.apple.security.device.audio-input" => true
-          }
+          },
+          ios_permission_definitions: %w[
+            PERMISSION_MICROPHONE=1
+          ]
         },
-        "barometer" => {
+        "motion" => {
           ios_info: {
-            "NSMotionUsageDescription" => "Motion access is required for barometer readings."
-          }
+            "NSMotionUsageDescription" => "Motion access is required for motion and sensor readings."
+          },
+          ios_permission_definitions: %w[
+            PERMISSION_SENSORS=1
+          ]
         },
-        "geolocator" => {
+        "location" => {
           android_permissions: [
             "android.permission.ACCESS_FINE_LOCATION",
             "android.permission.ACCESS_COARSE_LOCATION"
@@ -62,11 +92,40 @@ module Ruflet
           },
           macos_entitlements: {
             "com.apple.security.personal-information.location" => true
-          }
+          },
+          ios_permission_definitions: %w[
+            PERMISSION_LOCATION=1
+          ]
         }
       }.freeze
 
       def command_build(args)
+        with_project_build_lock { run_build_command(args) }
+      end
+
+      # Concurrent builds share build/client and corrupt each other's state
+      # (missing app.dill, Xcode build.db I/O errors). flock is released
+      # automatically when the process exits, so the lock cannot go stale.
+      def with_project_build_lock
+        lock_dir = File.join(Dir.pwd, "build")
+        FileUtils.mkdir_p(lock_dir)
+        lock_path = File.join(lock_dir, ".ruflet_build.lock")
+        File.open(lock_path, File::RDWR | File::CREAT, 0o644) do |file|
+          unless file.flock(File::LOCK_EX | File::LOCK_NB)
+            owner = file.read.to_s.strip
+            warn "Another ruflet build is already running for this project#{owner.empty? ? '' : " (#{owner})"}."
+            warn "Concurrent builds share the same build directory and corrupt each other."
+            warn "Wait for it to finish, then retry."
+            return 1
+          end
+          file.truncate(0)
+          file.write("pid=#{Process.pid} started=#{Time.now}")
+          file.flush
+          yield
+        end
+      end
+
+      def run_build_command(args)
         self_contained = args.delete("--self")
         verbose = args.delete("--verbose") || args.delete("-v")
         platform = (args.shift || "").downcase
@@ -194,6 +253,9 @@ module Ruflet
       end
 
       def build_tool_env(env, platform, client_dir = nil)
+        if %w[android apk aab appbundle].include?(platform)
+          return android_build_env(unbundled_command_env(env))
+        end
         return env unless %w[ios macos].include?(platform)
 
         apple_env = unbundled_command_env(env)
@@ -511,7 +573,20 @@ module Ruflet
       end
 
       def unbundled_command_env(env)
-        env.reject { |key, _value| key.start_with?("BUNDLE_") || key == "RUBYOPT" || key == "RUBYLIB" || key.start_with?("GEM_") }
+        command_env = env.reject { |key, _value| key.start_with?("BUNDLE_") || key == "RUBYOPT" || key == "RUBYLIB" || key.start_with?("GEM_") }
+        ensure_utf8_locale(command_env)
+      end
+
+      # CocoaPods refuses to run in a non-UTF-8 terminal and Xcode project
+      # files contain UTF-8; guarantee a UTF-8 locale for child tools.
+      def ensure_utf8_locale(env)
+        locale = env["LC_ALL"].to_s
+        locale = env["LANG"].to_s if locale.empty?
+        return env if locale.downcase.include?("utf-8") || locale.downcase.include?("utf8")
+
+        env["LANG"] = "en_US.UTF-8"
+        env["LC_ALL"] = "en_US.UTF-8"
+        env
       end
 
       def run_external_command(env, *cmd, chdir:, unbundled: false)
@@ -1024,8 +1099,11 @@ module Ruflet
       end
 
       def apply_service_extension_config(client_dir, config = {}, self_contained: @ruflet_self_contained_build)
-        services = Array(config["services"])
-        extension_keys = services.map { |v| normalize_extension_key(v) }.compact.uniq
+        service_definitions = load_service_definitions(client_dir)
+        service_extension_keys = service_definitions.keys.flat_map { |key| Array(SERVICE_EXTENSION_MAP[key]) }.uniq
+        protected_extension_keys = SERVICE_EXTENSION_MAP.values.flatten.uniq
+        configured_extension_keys = Array(config["extensions"]).map { |value| normalize_extension_key(value) }.compact
+        extension_keys = ((configured_extension_keys - protected_extension_keys) | service_extension_keys).uniq
         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
 
@@ -1038,14 +1116,19 @@ module Ruflet
           sync_client_main_extensions(entrypoint, extension_aliases) if File.file?(entrypoint)
           prune_client_main(entrypoint, extension_aliases) if File.file?(entrypoint)
         end
-        apply_service_native_requirements(client_dir, extension_keys)
+        apply_service_native_requirements(client_dir, service_definitions.keys, service_definitions)
       end
 
-      def apply_service_native_requirements(client_dir, extension_keys)
-        stale_keys = SERVICE_NATIVE_REQUIREMENTS.keys - extension_keys
-        remove_service_native_requirements(client_dir, stale_keys)
+      def apply_service_native_requirements(client_dir, extension_keys, service_definitions = load_service_definitions(client_dir))
+        service_requirements = service_native_requirements(service_definitions)
+        stale_keys = service_requirements.keys - extension_keys
+        remove_service_native_requirements(client_dir, stale_keys, service_requirements)
 
-        requirements = merge_service_native_requirements(extension_keys)
+        requirements = merge_service_native_requirements(extension_keys, service_requirements)
+        sync_ios_permission_definitions(
+          File.join(client_dir, "ios", "Podfile"),
+          Array(requirements[:ios_permission_definitions])
+        )
         return if requirements.empty?
 
         android_manifest = File.join(client_dir, "android", "app", "src", "main", "AndroidManifest.xml")
@@ -1071,8 +1154,8 @@ module Ruflet
         end
       end
 
-      def remove_service_native_requirements(client_dir, extension_keys)
-        requirements = merge_service_native_requirements(extension_keys)
+      def remove_service_native_requirements(client_dir, extension_keys, service_requirements = service_native_requirements(load_service_definitions(client_dir)))
+        requirements = merge_service_native_requirements(extension_keys, service_requirements)
         return if requirements.empty?
 
         android_manifest = File.join(client_dir, "android", "app", "src", "main", "AndroidManifest.xml")
@@ -1094,13 +1177,15 @@ module Ruflet
         end
       end
 
-      def merge_service_native_requirements(extension_keys)
+      def merge_service_native_requirements(extension_keys, service_requirements = DEFAULT_SERVICE_NATIVE_REQUIREMENTS)
         extension_keys.each_with_object({}) do |key, memo|
-          requirements = SERVICE_NATIVE_REQUIREMENTS[key]
+          requirements = service_requirements[key]
           next unless requirements
 
           memo[:android_permissions] ||= []
           memo[:android_permissions] |= Array(requirements[:android_permissions])
+          memo[:ios_permission_definitions] ||= []
+          memo[:ios_permission_definitions] |= Array(requirements[:ios_permission_definitions])
           %i[ios_info macos_info macos_entitlements].each do |section|
             memo[section] ||= {}
             memo[section].merge!(requirements[section] || {})
@@ -1108,6 +1193,72 @@ module Ruflet
         end
       end
 
+      def load_service_definitions(client_dir = nil)
+        path = services_config_path(client_dir)
+        return {} unless path
+
+        data = YAML.safe_load(File.read(path), aliases: true) || {}
+        Array(data["services"]).each_with_object({}) do |entry, memo|
+          name, metadata =
+            if entry.is_a?(Hash)
+              entry.first
+            else
+              [entry, {}]
+            end
+          key = normalize_extension_key(name)
+          memo[key] = metadata.is_a?(Hash) ? metadata : {} if key
+        end
+      rescue Psych::Exception => e
+        warn "Could not parse #{path}: #{e.message}"
+        {}
+      end
+
+      def services_config_path(client_dir = nil)
+        candidates = [ENV["RUFLET_SERVICES"], File.expand_path("services.yaml", Dir.pwd)]
+        candidates << File.join(client_dir, "services.yaml") if client_dir
+        candidates.compact.find { |path| File.file?(path) }
+      end
+
+      def service_native_requirements(service_definitions)
+        all_keys = (DEFAULT_SERVICE_NATIVE_REQUIREMENTS.keys | service_definitions.keys)
+        all_keys.each_with_object({}) do |key, memo|
+          defaults = DEFAULT_SERVICE_NATIVE_REQUIREMENTS[key] || {}
+          metadata = service_definitions[key] || {}
+          native = metadata["native"].is_a?(Hash) ? metadata["native"] : metadata
+          memo[key] = {
+            android_permissions: Array(native["android_permissions"] || defaults[:android_permissions]),
+            ios_permission_definitions: Array(native["ios_permission_definitions"] || defaults[:ios_permission_definitions]),
+            ios_info: native["ios_info"].is_a?(Hash) ? native["ios_info"] : (defaults[:ios_info] || {}),
+            macos_info: native["macos_info"].is_a?(Hash) ? native["macos_info"] : (defaults[:macos_info] || {}),
+            macos_entitlements: native["macos_entitlements"].is_a?(Hash) ? native["macos_entitlements"] : (defaults[:macos_entitlements] || {})
+          }
+        end
+      end
+
+      def sync_ios_permission_definitions(path, definitions)
+        return unless File.file?(path)
+
+        content = File.read(path)
+        marker_pattern = %r{\n?\s*# BEGIN RUFLET PERMISSION DEFINITIONS.*?# END RUFLET PERMISSION DEFINITIONS\n?}m
+        updated = content.gsub(marker_pattern, "\n")
+        definitions = Array(definitions).map(&:to_s).reject(&:empty?).uniq.sort
+        if definitions.any?
+          block = <<~RUBY.chomp
+                # BEGIN RUFLET PERMISSION DEFINITIONS
+                target.build_configurations.each do |config|
+                  config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)']
+                  config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] += #{definitions.inspect}
+                end
+                # END RUFLET PERMISSION DEFINITIONS
+          RUBY
+          updated = updated.sub(
+            /^(\s*)flutter_additional_ios_build_settings\(target\)\s*$/,
+            "\\0\n\n#{block}"
+          )
+        end
+        File.write(path, updated) unless updated == content
+      end
+
       def ensure_android_permission(path, permission)
         return unless File.file?(path)
 
@@ -1226,11 +1377,46 @@ module Ruflet
         write_pubspec_yaml(pubspec_path, data)
       end
 
+      RUBY_RUNTIME_FALLBACK_REQUIREMENT = "^0.0.5"
+
       def ruby_runtime_dependency(current_dependency = nil)
-        local_path = explicit_local_ruby_runtime_path
+        local_path = explicit_local_ruby_runtime_path || repo_checkout_ruby_runtime_path
         return { "path" => local_path } if local_path
 
-        current_dependency || "^0.0.3"
+        template_dependency = template_client_pubspec_dependencies["ruby_runtime"]
+        return template_dependency if usable_ruby_runtime_dependency?(template_dependency)
+
+        return current_dependency if usable_ruby_runtime_dependency?(current_dependency)
+
+        RUBY_RUNTIME_FALLBACK_REQUIREMENT
+      end
+
+      # In a ruflet repo checkout the plugin lives next to templates/; build
+      # against it so framework changes are exercised without publishing.
+      def repo_checkout_ruby_runtime_path
+        template_root =
+          if Ruflet::CLI.respond_to?(:resolve_ruflet_client_template_root, true)
+            Ruflet::CLI.send(:resolve_ruflet_client_template_root)
+          end
+        return nil unless template_root
+
+        candidate = File.expand_path(File.join(template_root, "..", "..", "ruby_runtime"))
+        File.file?(File.join(candidate, "pubspec.yaml")) ? candidate : nil
+      end
+
+      # Relative path dependencies only resolve from the directory the
+      # template was authored in — never copy them into a user's client.
+      def usable_ruby_runtime_dependency?(dependency)
+        case dependency
+        when nil then false
+        when Hash
+          path = dependency["path"] || dependency[:path]
+          return true if path.nil? # hosted/git table form
+
+          Pathname.new(path.to_s).absolute? && File.file?(File.join(path, "pubspec.yaml"))
+        else
+          !dependency.to_s.strip.empty?
+        end
       end
 
       def explicit_local_ruby_runtime_path
@@ -1271,6 +1457,27 @@ module Ruflet
           FileUtils.cp(source, destination)
           build_log(verbose, "refreshed template file #{relative_path}")
         end
+
+        repair_legacy_self_contained_bootstrap(client_dir, verbose: verbose)
+      end
+
+      def repair_legacy_self_contained_bootstrap(client_dir, verbose: false)
+        path = File.join(client_dir, "lib", "main.self.dart")
+        return unless File.file?(path)
+
+        content = File.read(path)
+        updated = content.gsub(
+          /^\s*await RubyRuntime\.eval\("ENV\['RUFLET_DEBUG'\].*?\n/,
+          ""
+        )
+        updated = updated.gsub(
+          /^\s*final digestLength = await RubyRuntime\.eval\(\n.*?^\s*\);\n\s*debugPrint\('Embedded Digest::SHA1 bytesize: \$digestLength'\);\n/m,
+          ""
+        )
+        return if updated == content
+
+        File.write(path, updated)
+        build_log(verbose, "removed legacy pre-server RubyRuntime.eval diagnostics")
       end
 
       def write_pubspec_yaml(path, data)

data/lib/ruflet/cli/environment_setup.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Ruflet
+  module CLI
+    # Provisions the host so `ruflet build` can run: checks (and with
+    # `ruflet doctor --fix`, installs) the system tools Flutter requires.
+    #
+    # Coverage:
+    #   Linux   apt (Ubuntu, Debian, Kali, Mint), dnf (Fedora, RHEL),
+    #           pacman (Arch, Omarchy, Manjaro), zypper (openSUSE)
+    #   macOS   Homebrew where available, plus Xcode Command Line Tools and
+    #           CocoaPods guidance
+    #   Windows winget or Chocolatey
+    #
+    # Anything that cannot be installed unattended (Xcode CLT, Visual Studio
+    # Build Tools) is reported with the exact command the developer must run.
+    module EnvironmentSetup
+      Tool = Struct.new(:name, :probe, :purpose, :packages, :manual_hint, keyword_init: true)
+
+      LINUX_PACKAGE_MANAGERS = [
+        { id: :apt, probe: "apt-get", install: %w[apt-get install -y], update: %w[apt-get update] },
+        { id: :dnf, probe: "dnf", install: %w[dnf install -y], update: nil },
+        { id: :pacman, probe: "pacman", install: %w[pacman -S --noconfirm --needed], update: nil },
+        { id: :zypper, probe: "zypper", install: %w[zypper --non-interactive install], update: nil },
+        { id: :apk, probe: "apk", install: %w[apk add], update: nil }
+      ].freeze
+
+      def environment_setup!(fix: false, verbose: false)
+        issues = []
+        tools = required_system_tools
+
+        unless flutter_host
+          issues << unsupported_host_message
+          warn "  System: #{unsupported_host_message}"
+          return issues
+        end
+
+        manager = system_package_manager
+        missing = tools.reject { |tool| tool_present?(tool) }
+
+        if missing.empty?
+          puts "  System tools: ok (#{tools.map(&:name).join(', ')})"
+          return issues
+        end
+
+        puts "  System tools missing: #{missing.map(&:name).join(', ')}"
+
+        unless fix
+          missing.each { |tool| warn "    #{tool.name}: #{manual_hint_for(tool, manager)}" }
+          warn "  Run `ruflet doctor --fix` to install them."
+          return missing.map { |tool| "missing #{tool.name}" }
+        end
+
+        auto, manual = missing.partition { |tool| installable?(tool, manager) }
+
+        if auto.any?
+          if manager
+            install_system_packages(manager, auto, verbose: verbose)
+          end
+          still_missing = auto.reject { |tool| tool_present?(tool) }
+          still_missing.each do |tool|
+            issues << "missing #{tool.name}"
+            warn "    #{tool.name}: install failed — #{manual_hint_for(tool, manager)}"
+          end
+          installed = auto - still_missing
+          puts "  Installed: #{installed.map(&:name).join(', ')}" if installed.any?
+        end
+
+        manual.each do |tool|
+          issues << "missing #{tool.name}"
+          warn "    #{tool.name}: requires a manual step — #{manual_hint_for(tool, manager)}"
+        end
+
+        issues
+      end
+
+      def required_system_tools
+        case flutter_host
+        when "linux" then linux_required_tools
+        when "macos", "macos_arm64" then macos_required_tools
+        when "windows" then windows_required_tools
+        else []
+        end
+      end
+
+      def system_package_manager
+        if windows_host?
+          return { id: :winget, install: %w[winget install --accept-source-agreements --accept-package-agreements -e --id] } if which_command("winget")
+          return { id: :choco, install: %w[choco install -y] } if which_command("choco")
+          return nil
+        end
+
+        if macos_host?
+          return { id: :brew, install: %w[brew install] } if which_command("brew")
+          return nil
+        end
+
+        LINUX_PACKAGE_MANAGERS.each do |manager|
+          next unless which_command(manager[:probe])
+
+          return manager
+        end
+        nil
+      end
+
+      private
+
+      def macos_host?
+        RbConfig::CONFIG["host_os"].match?(/darwin/i)
+      end
+
+      def linux_required_tools
+        [
+          Tool.new(name: "git", probe: "git", purpose: "required by the Flutter tool itself",
+                   packages: { apt: "git", dnf: "git", pacman: "git", zypper: "git", apk: "git" }),
+          Tool.new(name: "curl", probe: "curl", purpose: "SDK downloads",
+                   packages: { apt: "curl", dnf: "curl", pacman: "curl", zypper: "curl", apk: "curl" }),
+          Tool.new(name: "unzip", probe: "unzip", purpose: "extracting Flutter artifacts",
+                   packages: { apt: "unzip", dnf: "unzip", pacman: "unzip", zypper: "unzip", apk: "unzip" }),
+          Tool.new(name: "xz", probe: "xz", purpose: "extracting the Flutter SDK (.tar.xz)",
+                   packages: { apt: "xz-utils", dnf: "xz", pacman: "xz", zypper: "xz", apk: "xz" }),
+          Tool.new(name: "zip", probe: "zip", purpose: "packaging app bundles",
+                   packages: { apt: "zip", dnf: "zip", pacman: "zip", zypper: "zip", apk: "zip" }),
+          Tool.new(name: "clang", probe: "clang", purpose: "Linux desktop builds",
+                   packages: { apt: "clang", dnf: "clang", pacman: "clang", zypper: "clang", apk: "clang" }),
+          Tool.new(name: "cmake", probe: "cmake", purpose: "Linux desktop builds",
+                   packages: { apt: "cmake", dnf: "cmake", pacman: "cmake", zypper: "cmake", apk: "cmake" }),
+          Tool.new(name: "ninja", probe: "ninja", purpose: "Linux desktop builds",
+                   packages: { apt: "ninja-build", dnf: "ninja-build", pacman: "ninja", zypper: "ninja", apk: "ninja" }),
+          Tool.new(name: "pkg-config", probe: "pkg-config", purpose: "Linux desktop builds",
+                   packages: { apt: "pkg-config", dnf: "pkgconf-pkg-config", pacman: "pkgconf", zypper: "pkg-config", apk: "pkgconf" }),
+          Tool.new(name: "GTK 3 headers", probe: nil, purpose: "Linux desktop builds",
+                   packages: { apt: "libgtk-3-dev", dnf: "gtk3-devel", pacman: "gtk3", zypper: "gtk3-devel", apk: "gtk+3.0-dev" })
+        ]
+      end
+
+      def macos_required_tools
+        [
+          Tool.new(name: "git", probe: "git", purpose: "required by the Flutter tool itself",
+                   packages: { brew: "git" },
+                   manual_hint: "install Xcode Command Line Tools: xcode-select --install"),
+          Tool.new(name: "curl", probe: "curl", purpose: "SDK downloads", packages: { brew: "curl" }),
+          Tool.new(name: "unzip", probe: "unzip", purpose: "extracting Flutter artifacts", packages: { brew: "unzip" }),
+          Tool.new(name: "Xcode Command Line Tools", probe: nil, purpose: "macOS/iOS builds",
+                   packages: {},
+                   manual_hint: "run `xcode-select --install` (or install Xcode from the App Store)"),
+          Tool.new(name: "CocoaPods", probe: "pod", purpose: "macOS/iOS plugin dependencies",
+                   packages: { brew: "cocoapods" },
+                   manual_hint: "run `brew install cocoapods` or `sudo gem install cocoapods`")
+        ]
+      end
+
+      def windows_required_tools
+        [
+          Tool.new(name: "git", probe: "git", purpose: "required by the Flutter tool itself",
+                   packages: { winget: "Git.Git", choco: "git" }),
+          Tool.new(name: "Visual Studio Build Tools", probe: nil, purpose: "Windows desktop builds",
+                   packages: {},
+                   manual_hint: "winget install --id Microsoft.VisualStudio.2022.BuildTools (select the " \
+                                "\"Desktop development with C++\" workload)")
+        ]
+      end
+
+      def tool_present?(tool)
+        case tool.name
+        when "GTK 3 headers"
+          return true if which_command("pkg-config") &&
+                         system("pkg-config", "--exists", "gtk+-3.0", out: File::NULL, err: File::NULL)
+
+          false
+        when "Xcode Command Line Tools"
+          system("xcode-select", "-p", out: File::NULL, err: File::NULL)
+        else
+          tool.probe ? !which_command(tool.probe).nil? : false
+        end
+      end
+
+      def installable?(tool, manager)
+        return false unless manager
+
+        tool.packages.key?(manager[:id])
+      end
+
+      def manual_hint_for(tool, manager)
+        return tool.manual_hint if tool.manual_hint && !installable?(tool, manager)
+        return "no supported package manager found; install #{tool.name} manually" unless manager
+
+        package = tool.packages[manager[:id]]
+        return tool.manual_hint || "install #{tool.name} manually" unless package
+
+        "#{(sudo_prefix + manager[:install]).join(' ')} #{package}"
+      end
+
+      def install_system_packages(manager, tools, verbose: false)
+        packages = tools.map { |tool| tool.packages[manager[:id]] }.compact.uniq
+        return if packages.empty?
+
+        if manager[:update]
+          run_privileged_command(*manager[:update], verbose: verbose)
+        end
+
+        if manager[:id] == :winget
+          # winget installs one id at a time.
+          packages.each { |package| run_privileged_command(*manager[:install], package, verbose: verbose) }
+        else
+          run_privileged_command(*manager[:install], *packages, verbose: verbose)
+        end
+      end
+
+      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)
+      end
+
+      def sudo_prefix
+        return [] if windows_host? || macos_host?
+        return [] if Process.respond_to?(:uid) && Process.uid.zero?
+        return ["sudo"] if which_command("sudo")
+
+        []
+      end
+
+      def unsupported_host_message
+        os = RbConfig::CONFIG["host_os"]
+        if os.match?(/linux/i) && machine_arch.match?(/arm|aarch64/)
+          "Flutter publishes no official Linux #{machine_arch} build; use an x64 machine " \
+            "or build Flutter from source (https://github.com/flutter/flutter)."
+        else
+          "unsupported host platform: #{os}"
+        end
+      end
+    end
+  end
+end

data/lib/ruflet/cli/extra_command.rb

@@ -6,6 +6,8 @@ module Ruflet
   module CLI
     module ExtraCommand
       include FlutterSdk
+      include EnvironmentSetup
+      include AndroidSdk
       include NewCommand
 
       def command_create(args)
@@ -20,6 +22,12 @@ module Ruflet
         puts "Ruflet doctor"
         puts "  Ruby: #{RUBY_VERSION}"
         puts "  Flutter host target: #{flutter_host || 'unsupported'}"
+
+        # System prerequisites first: Flutter cannot be installed (or even
+        # extracted) without them.
+        environment_issues = environment_setup!(fix: !!fix, verbose: !!verbose)
+        return 1 unless flutter_host
+
         if template_root
           puts "  Template: #{template_root}"
         elsif fix
@@ -46,9 +54,14 @@ module Ruflet
           end
         end
         puts "  Flutter: #{flutter_version_summary(tools)}"
-        ok = system(tools[:env], tools[:flutter], "doctor", *(verbose ? ["-v"] : []))
+        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
+        if environment_issues.any?
+          warn "Unresolved environment issues: #{environment_issues.join('; ')}"
+          status = 1 if status.zero?
+        end
         status
       end
 

data/lib/ruflet/cli/flutter_sdk.rb

@@ -322,7 +322,10 @@ module Ruflet
         if os.match?(/darwin/i)
           return machine_arch.include?("arm") ? "macos_arm64" : "macos"
         end
-        return "linux" if os.match?(/linux/i)
+        if os.match?(/linux/i)
+          # Flutter publishes Linux archives for x64 only.
+          return machine_arch.match?(/arm|aarch64/) ? nil : "linux"
+        end
         return "windows" if os.match?(/mswin|mingw|cygwin/i)
 
         nil
@@ -391,14 +394,25 @@ module Ruflet
           if windows_host?
             return system("powershell", "-NoProfile", "-Command", "Expand-Archive -Path '#{archive}' -DestinationPath '#{destination}' -Force")
           end
+
+          require_extract_tool!("unzip")
           return system("unzip", "-oq", archive, "-d", destination)
         end
 
         if archive.end_with?(".tar.xz") || archive.end_with?(".tar.gz") || archive.end_with?(".tgz")
+          require_extract_tool!("tar")
+          require_extract_tool!("xz") if archive.end_with?(".tar.xz") && !windows_host?
           return system("tar", "-xf", archive, "-C", destination)
         end
 
-        false
+        raise "Unsupported archive format: #{File.basename(archive)}"
+      end
+
+      def require_extract_tool!(name)
+        return if which_command(name)
+
+        raise "`#{name}` is required to extract the Flutter SDK but was not found. " \
+              "Run `ruflet doctor --fix` to install the missing system tools."
       end
     end
   end

data/lib/ruflet/cli/new_command.rb

@@ -84,7 +84,20 @@ module Ruflet
         end
 
         cached_template = cached_ruflet_client_template_root
-        return cached_template if Dir.exist?(cached_template)
+        if Dir.exist?(cached_template)
+          return cached_template if cached_template_current?(cached_template)
+
+          # The cache was written by a different ruflet version; stale
+          # framework Dart breaks newer asset layouts. Refresh, but never
+          # block a build on the network: fall back to the stale copy loudly.
+          refreshed = download_ruflet_template(force: true)
+          return refreshed if refreshed && Dir.exist?(refreshed)
+
+          warn "ruflet: could not refresh the Flutter client template cache; " \
+               "using a stale copy from another ruflet version at #{cached_template}. " \
+               "Delete it or run with network access to update."
+          return cached_template
+        end
 
         [
           File.expand_path("../../../ruflet_client", __dir__),
@@ -112,6 +125,21 @@ module Ruflet
         File.join(template_cache_root, "ruflet_flutter_template")
       end
 
+      TEMPLATE_CACHE_STAMP = ".ruflet_template_version"
+
+      def cached_template_current?(target)
+        stamp = File.join(target, TEMPLATE_CACHE_STAMP)
+        File.file?(stamp) && File.read(stamp).strip == Ruflet::VERSION
+      rescue StandardError
+        false
+      end
+
+      def write_template_cache_stamp(target)
+        File.write(File.join(target, TEMPLATE_CACHE_STAMP), Ruflet::VERSION)
+      rescue StandardError
+        nil
+      end
+
       def cached_ruby_runtime_root
         File.join(cache_root, "ruby_runtime")
       end
@@ -150,6 +178,7 @@ module Ruflet
           FileUtils.cp_r(source, target)
         end
 
+        write_template_cache_stamp(target)
         target
       rescue StandardError => e
         warn "Failed to fetch Ruflet template: #{e.class}: #{e.message}"
@@ -195,12 +224,11 @@ module Ruflet
             # Example: https://api.example.com
             backend_url: ""
 
-          # Source of truth for Flutter client extensions/plugins.
-          # To test every extension, list all services:
-          # ads, audio, audio_recorder, camera, charts, code_editor, color_pickers,
-          # datatable2, flashlight, geolocator, lottie, map, permission_handler,
-          # secure_storage, video, webview
-          services: []
+          # Flutter extension packages included in the managed client.
+          # Permission-backed extensions such as camera, audio_recorder,
+          # geolocator, and permission_handler are activated by services.yaml
+          # and ignored here.
+          extensions: []
 
           # Build assets configuration consumed by `ruflet build`.
           # Paths are relative to this file unless absolute.
@@ -215,6 +243,11 @@ module Ruflet
             icon_background: "#FFFFFF"
             theme_color: "#FFFFFF"
         YAML
+
+        File.write(File.join(root, "services.yaml"), <<~YAML)
+          # Protected device access requested by this app.
+          services: []
+        YAML
       end
 
       def copy_default_project_assets(root)

data/lib/ruflet/cli/run_command.rb

@@ -349,13 +349,30 @@ module Ruflet
       end
 
       def project_run_requires_managed_client?
-        return false unless defined?(Ruflet::CLI::BuildCommand::CLIENT_EXTENSION_MAP)
+        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 = Array(project_run_config["services"]).map { |value| normalize_run_extension_key(value) }.compact
+        services =
+          if respond_to?(:load_service_definitions, true)
+            send(:load_service_definitions).keys
+          else
+            []
+          end
         return false if services.empty?
 
-        extension_keys = Ruflet::CLI::BuildCommand::CLIENT_EXTENSION_MAP.keys
-        (services & extension_keys).any?
+        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

data/lib/ruflet/cli.rb

@@ -2,10 +2,16 @@
 
 require "optparse"
 
+# Project files (pbxproj, plists, embedded runtime sources) are UTF-8; never
+# depend on the caller's locale for reading them.
+Encoding.default_external = Encoding::UTF_8 if Encoding.default_external == Encoding::US_ASCII
+
 require_relative "version"
 require_relative "cli/templates"
 require_relative "cli/new_command"
 require_relative "cli/flutter_sdk"
+require_relative "cli/environment_setup"
+require_relative "cli/android_sdk"
 require_relative "cli/run_command"
 require_relative "cli/update_command"
 require_relative "cli/build_command"

data/lib/ruflet/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruflet
 version: !ruby/object:Gem::Version
-  version: 0.0.14
+  version: 0.0.15
 platform: ruby
 authors:
 - AdamMusa
@@ -37,7 +37,9 @@ files:
 - assets/splash.png
 - bin/ruflet
 - lib/ruflet/cli.rb
+- lib/ruflet/cli/android_sdk.rb
 - lib/ruflet/cli/build_command.rb
+- lib/ruflet/cli/environment_setup.rb
 - lib/ruflet/cli/extra_command.rb
 - lib/ruflet/cli/flutter_sdk.rb
 - lib/ruflet/cli/new_command.rb