ruflet 0.0.14 → 0.0.16

data/lib/ruflet/cli/environment_setup.rb

@@ -0,0 +1,241 @@
+# 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(' ')}"
+        # Package installs (apt/dnf/pacman...) routinely download hundreds of
+        # megabytes and take minutes. Always stream their output so the user
+        # can see progress instead of a frozen-looking prompt; `verbose` is
+        # left for callers that want to add their own detail elsewhere.
+        system(*full, out: $stdout, err: $stderr)
+      end
+
+      def sudo_prefix
+        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,13 @@ module Ruflet
           end
         end
         puts "  Flutter: #{flutter_version_summary(tools)}"
-        ok = system(tools[:env], tools[:flutter], "doctor", *(verbose ? ["-v"] : []))
-        status = $?.exitstatus if $?
-        status ||= ok ? 0 : 1
+        environment_issues += android_environment_setup!(fix: !!fix, verbose: !!verbose)
+        ok = system(android_build_env(tools[:env]), tools[:flutter], "doctor", *(verbose ? ["-v"] : []))
+        status = ok ? 0 : ($?&.exitstatus || 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

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

@@ -25,6 +25,7 @@ module Ruflet
         "map" => { package: "flet_map", alias: "ruflet_map" },
         "permission_handler" => { package: "flet_permission_handler", alias: "ruflet_permission_handler" },
         "secure_storage" => { package: "flet_secure_storage", alias: "ruflet_secure_storage" },
+        "spinkit" => { package: "flet_spinkit", alias: "ruflet_spinkit" },
         "video" => { package: "flet_video", alias: "ruflet_video" },
         "webview" => { package: "flet_webview", alias: "ruflet_webview" }
       }.freeze
@@ -84,7 +85,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 +126,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 +179,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 +225,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 +244,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)