ruby_everywhere 0.3.0 → 0.4.0

data/lib/everywhere/android_sdk.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "shellout"
+require_relative "ui"
+
+module Everywhere
+  # Locates the Android toolchain — SDK, adb, emulator, sdkmanager, JDK — for
+  # the builder, the emulator driver, `every logs` and `every doctor`.
+  #
+  # The one rule everything here follows: resolve BY LOCATION, never off PATH.
+  # Android Studio provisions the whole toolchain (SDK, platform-tools, the
+  # emulator, system images, a bundled JDK) and exports none of it — no shell
+  # profile is touched, so a machine that can build Android apps all day has no
+  # `adb`, no `sdkmanager` and often no `java` on PATH at all. A `which adb`
+  # here would report "missing" on a perfectly provisioned Mac. Fixed locations
+  # under the SDK root are what's actually stable, the same way `xcrun` shields
+  # the iOS builder from wherever Xcode put its internals.
+  module AndroidSdk
+    module_function
+
+    # Android Gradle Plugin 8.x refuses to run on anything older, and the
+    # failure surfaces as an unreadable Gradle/Kotlin stacktrace rather than a
+    # version complaint — so we check before Gradle ever starts.
+    MINIMUM_JDK = 17
+
+    # The API level the shell template compiles against. Named here (not in the
+    # builder) because `every doctor` has to print the sdkmanager line for it
+    # long before a build is attempted.
+    COMPILE_SDK = 35
+
+    # Android Studio's bundled JetBrains Runtime, per platform. Studio never
+    # exports it, so these paths are the only way to find a JDK on a machine
+    # whose owner installed Studio and nothing else.
+    STUDIO_JBR = [
+      "/Applications/Android Studio.app/Contents/jbr/Contents/Home",
+      "~/Applications/Android Studio.app/Contents/jbr/Contents/Home",
+      "/opt/android-studio/jbr",
+      "/usr/local/android-studio/jbr",
+      "~/android-studio/jbr",
+      "C:/Program Files/Android/Android Studio/jbr"
+    ].freeze
+
+    # --- platform ------------------------------------------------------------
+
+    def macos?   = RUBY_PLATFORM.include?("darwin")
+    def windows? = RUBY_PLATFORM.match?(/mswin|mingw|cygwin/)
+
+    # --- SDK root ------------------------------------------------------------
+
+    # Where the SDK lives on a default install, per platform. Studio writes
+    # exactly one of these and records it in its own settings — never in the
+    # environment — which is why the fallback matters more here than it would
+    # for a toolchain with an installer that edits your profile.
+    def default_sdk_roots
+      if macos?
+        ["~/Library/Android/sdk"]
+      elsif windows?
+        [ENV["LOCALAPPDATA"] && File.join(ENV["LOCALAPPDATA"], "Android", "Sdk")].compact
+      else
+        ["~/Android/Sdk"]
+      end
+    end
+
+    # The SDK root, or nil. An explicit env var wins so CI images and secondary
+    # SDKs work without moving anything; ANDROID_HOME comes first because it's
+    # the spelling Studio and the docs use now (ANDROID_SDK_ROOT is deprecated
+    # but still all over CI). A var pointing at a directory that isn't there is
+    # skipped rather than fatal — a stale export shouldn't hide the SDK sitting
+    # in the default location.
+    def sdk_root
+      [ENV["ANDROID_HOME"], ENV["ANDROID_SDK_ROOT"], *default_sdk_roots]
+        .reject { |dir| dir.to_s.empty? }
+        .map { |dir| File.expand_path(dir) }
+        .find { |dir| File.directory?(dir) }
+    end
+
+    def sdk_root!
+      sdk_root or UI.die!("no Android SDK — install Android Studio (it provisions the SDK, adb, " \
+                          "the emulator and a JDK in one go), or point ANDROID_HOME at an " \
+                          "existing SDK; looked in #{expected_sdk_root}")
+    end
+
+    # The path named in "we couldn't find it" messages, so the user is told
+    # where we looked rather than left to guess.
+    def expected_sdk_root
+      File.expand_path(default_sdk_roots.first || "~/Android/Sdk")
+    end
+
+    # --- tools ---------------------------------------------------------------
+
+    def adb      = sdk_tool("platform-tools", "adb")
+    def emulator = sdk_tool("emulator", "emulator")
+
+    def adb!
+      adb or UI.die!("no adb under #{sdk_root!} — #{install_hint("platform-tools")}")
+    end
+
+    def emulator!
+      emulator or UI.die!("no Android emulator under #{sdk_root!} — #{install_hint("emulator")}")
+    end
+
+    def sdkmanager = cmdline_tool("sdkmanager")
+    def avdmanager = cmdline_tool("avdmanager")
+
+    def sdkmanager!
+      sdkmanager or UI.die!("no sdkmanager under #{sdk_root!} — #{cmdline_tools_hint}")
+    end
+
+    def avdmanager!
+      avdmanager or UI.die!("no avdmanager under #{sdk_root!} — #{cmdline_tools_hint}")
+    end
+
+    # Whether this SDK can install anything at all. Worth asking on its own,
+    # because it's the one component whose absence makes every other
+    # remediation unquotable: without it there is no `sdkmanager` to run, and
+    # the Phase 0 machine had a complete SDK, adb, the emulator, build-tools and
+    # an AVD with no cmdline-tools anywhere — not in the SDK, not inside Android
+    # Studio. So a missing one is an advisory, not a broken machine.
+    def cmdline_tools? = !sdkmanager.nil?
+
+    # How to get command-line tools without already having them. The Studio
+    # route is first because it also accepts the licences, but the manual zip
+    # matters: it's the only answer for a machine with no Studio, and Studio's
+    # own SDK Tools list is exactly where this component was already unchecked.
+    CMDLINE_TOOLS_URL = "https://developer.android.com/studio#command-line-tools-only"
+
+    def cmdline_tools_hint
+      "install \"Android SDK Command-line Tools (latest)\" in Android Studio → Settings → " \
+        "Languages & Frameworks → Android SDK → SDK Tools, or download " \
+        "commandlinetools-#{host_tag}-*_latest.zip from #{CMDLINE_TOOLS_URL} and unzip it into " \
+        "#{cmdline_tools_dir} (so its bin/ lands there)"
+    end
+
+    # Where an unzipped command-line-tools release has to end up. Named because
+    # both hints point at it, and because "unzip it somewhere in the SDK" is
+    # the instruction people get wrong — the tools look for their own jars
+    # relative to this exact directory.
+    def cmdline_tools_dir
+      File.join(sdk_root || expected_sdk_root, "cmdline-tools", "latest")
+    end
+
+    # The token Google's command-line-tools downloads are named with.
+    def host_tag
+      return "mac" if macos?
+
+      windows? ? "win" : "linux"
+    end
+
+    # A tool at its fixed spot under the SDK root, or nil.
+    def sdk_tool(subdir, name)
+      root = sdk_root or return nil
+
+      tool_in(File.join(root, subdir), name)
+    end
+
+    # sdkmanager and avdmanager are the one pair that moved: current installs
+    # put them in cmdline-tools/latest/bin, an SDK pinned to a specific
+    # command-line-tools release uses cmdline-tools/<version>/bin, and anything
+    # provisioned before 2021 still has the legacy tools/bin copy. Try all three
+    # so `every doctor` can print a working install line on an older machine
+    # instead of a path that doesn't exist.
+    def cmdline_tool(name)
+      root = sdk_root or return nil
+
+      # Reverse-sorted so 12.0 beats 9.0 in the common case; "latest" is tried
+      # first anyway, so this ordering only decides between pinned releases.
+      versioned = Dir.glob(File.join(root, "cmdline-tools", "*", "bin")).sort.reverse
+      dirs = [File.join(root, "cmdline-tools", "latest", "bin"), *versioned,
+              File.join(root, "tools", "bin")]
+      dirs.uniq.filter_map { |dir| tool_in(dir, name) }.first
+    end
+
+    # Windows spells the same tools adb.exe and sdkmanager.bat; probing the
+    # suffixes here lets every caller ask for the plain Unix name.
+    def tool_in(dir, name)
+      [name, "#{name}.exe", "#{name}.bat"]
+        .map { |file| File.join(dir, file) }
+        .find { |path| File.file?(path) }
+    end
+
+    # A ready-to-paste instruction for installing a missing SDK package. When
+    # the SDK has no command-line tools at all there IS no command to paste, so
+    # say what to click in Studio instead — an honest instruction beats a
+    # copyable line that resolves to nothing. Phrased to read on its own, since
+    # callers append it after an em dash.
+    def install_hint(package)
+      if (manager = sdkmanager)
+        "run: #{manager.shellescape} #{package.inspect}"
+      else
+        # The short form of cmdline_tools_hint: doctor prints the full version
+        # once, above these lines, and repeating a URL and two absolute paths
+        # on every missing package buries what each line is actually about.
+        "install \"Android SDK Command-line Tools\" (Android Studio → SDK Tools, or unzip " \
+        "commandlinetools-#{host_tag}-*_latest.zip into #{cmdline_tools_dir}), " \
+        "then run: sdkmanager #{package.inspect}"
+      end
+    end
+
+    # --- JDK -----------------------------------------------------------------
+
+    # Gradle needs a JDK. JAVA_HOME wins because it's the one explicit choice on
+    # the machine; then macOS's own registry (which knows about JDKs installed
+    # by brew, Oracle or SDKMAN without any of them being on PATH); then
+    # Studio's bundled runtime, which is what a Studio-only machine actually has.
+    def java_home
+      explicit = ENV["JAVA_HOME"].to_s
+      return File.expand_path(explicit) if !explicit.empty? && File.directory?(explicit)
+
+      registry_java_home || studio_java_home
+    end
+
+    # Like #java_home but also enforces the minimum: a JDK 11 that resolves
+    # cleanly still fails the build later, deep inside Gradle, so reject it here
+    # where the message can name the cause.
+    def java_home!(minimum: MINIMUM_JDK)
+      home = java_home or
+        UI.die!("no JDK — install Android Studio (it bundles one at #{STUDIO_JBR.first}) " \
+                "or set JAVA_HOME to a JDK #{minimum} or newer")
+      version = java_version
+      return home if version.nil? || version >= minimum
+
+      UI.die!("#{home} is JDK #{version}; the Android Gradle Plugin needs #{minimum} or newer — " \
+              "set JAVA_HOME to a JDK #{minimum}+, or install Android Studio and use its bundled runtime")
+    end
+
+    # The JDK's major version, or nil if it can't be determined. Read from the
+    # `release` file the JDK ships rather than by running `java -version`: it's
+    # a file read instead of a JVM start, and it works for a JDK that isn't on
+    # PATH — which, per the rule at the top, is most of them. A JDK 8 reports
+    # JAVA_VERSION="1.8.0_412", so this yields 1, which compares correctly
+    # against MINIMUM_JDK without special-casing the old scheme.
+    def java_version
+      home = java_home or return nil
+      release = File.join(home, "release")
+      return File.read(release)[/^JAVA_VERSION="?(\d+)/, 1]&.to_i if File.file?(release)
+
+      java = tool_in(File.join(home, "bin"), "java") or return nil
+      out, status = Shellout.capture(java, "-version")
+      out[/version "?(\d+)/, 1]&.to_i if status&.success?
+    end
+
+    # macOS keeps a registry of installed JDKs that java_home queries; -v 17
+    # asks for "17 or newer", so a machine with only JDK 21 still answers.
+    def registry_java_home
+      return nil unless macos?
+
+      out, status = Shellout.capture("/usr/libexec/java_home", "-v", MINIMUM_JDK.to_s)
+      home = out.to_s.strip
+      home if status&.success? && !home.empty? && File.directory?(home)
+    end
+
+    def studio_java_home
+      STUDIO_JBR.map { |dir| File.expand_path(dir) }.find { |dir| File.directory?(dir) }
+    end
+
+    # --- installed packages --------------------------------------------------
+
+    # Which platforms/build-tools are on disk, read straight off the filesystem
+    # rather than from `sdkmanager --list`: that's a multi-second JVM start that
+    # also reaches out for the remote catalogue we don't care about, and it
+    # needs the command-line tools, which are exactly the component most likely
+    # to be missing on a Studio-only machine.
+    def installed_platforms   = sdk_package_dirs("platforms")
+    def installed_build_tools = sdk_package_dirs("build-tools")
+
+    def sdk_package_dirs(kind)
+      root = sdk_root or return []
+
+      Dir.glob(File.join(root, kind, "*"))
+         .select { |dir| File.directory?(dir) }
+         .map { |dir| File.basename(dir) }
+         .sort
+    end
+
+    # `platform?(35)` and `platform?("android-35")` both work — callers spell it
+    # whichever way reads better where they are.
+    def platform?(api = COMPILE_SDK)
+      name = api.to_s.start_with?("android-") ? api.to_s : "android-#{api}"
+      installed_platforms.include?(name)
+    end
+
+    def platform!(api = COMPILE_SDK)
+      return true if platform?(api)
+
+      package = "platforms;android-#{api.to_s.delete_prefix("android-")}"
+      UI.die!("the Android SDK has no #{package} (installed: " \
+              "#{installed_platforms.empty? ? "none" : installed_platforms.join(", ")}) — " \
+              "#{install_hint(package)}")
+    end
+
+    # --- AVDs ----------------------------------------------------------------
+
+    # Virtual devices, newest-created last. Asked of the emulator binary rather
+    # than globbed out of ~/.android/avd because the emulator also honours
+    # ANDROID_AVD_HOME and ANDROID_SDK_HOME — and an AVD it won't list is one we
+    # couldn't boot anyway. Studio's Device Manager writes to the same place, so
+    # a VM created in the GUI shows up here with no extra step.
+    def avds
+      exe = emulator or return []
+
+      out, status = Shellout.capture(exe, "-list-avds")
+      return [] unless status&.success?
+
+      # The emulator prints INFO/WARNING banners on the same stream; AVD names
+      # can only contain [A-Za-z0-9._-], so anything with a space is chatter.
+      out.lines.map(&:strip).reject(&:empty?).grep(/\A[\w.-]+\z/)
+    end
+
+    def avds!
+      found = avds
+      return found if found.any?
+
+      UI.die!("no Android virtual devices — #{create_avd_hint}")
+    end
+
+    # How to get a bootable AVD. The GUI route comes first because a machine
+    # with Studio installed almost always has a device defined already, and
+    # Device Manager also downloads the system image the CLI line assumes.
+    def create_avd_hint
+      "create one in Android Studio → Device Manager, or run: " \
+      "#{(avdmanager || "avdmanager").shellescape} create avd -n Pixel_API_#{COMPILE_SDK} " \
+      "-k \"system-images;android-#{COMPILE_SDK};google_apis;#{host_abi}\""
+    end
+
+    # The system image ABI that runs at native speed on this host — an x86_64
+    # image on Apple silicon boots, technically, at a speed nobody will wait for.
+    def host_abi = RUBY_PLATFORM.match?(/arm64|aarch64/) ? "arm64-v8a" : "x86_64"
+  end
+end

data/lib/everywhere/asset_catalog.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Everywhere
+  # Compiles an app's native/ios/assets/ tree into Assets.xcassets imagesets so
+  # native code can reach them by name — Image("logo") in SwiftUI,
+  # UIImage(named: "logo") in UIKit. The catalog already ships in the frozen
+  # template and is compiled by actool, so writing imagesets into it keeps the
+  # stamp-only contract (the pbxproj is never touched).
+  #
+  # Filenames are the whole API: <name>[@2x|@3x][~dark].<ext>. Sub-directories
+  # organise the catalog but do NOT namespace it — asset names stay global, so
+  # assets/branding/logo.png is still Image("logo").
+  module AssetCatalog
+    RASTER = %w[.png .jpg .jpeg].freeze
+    VECTOR = %w[.pdf .svg].freeze
+    EXTENSIONS = (RASTER + VECTOR).freeze
+
+    # Written by the iOS builder itself (icon, launch background, tint) — an
+    # app asset of the same name would silently lose to, or clobber, those.
+    RESERVED = %w[AppIcon AccentColor LaunchBackground].freeze
+
+    VALID_NAME = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/
+    INFO = { "author" => "xcode", "version" => 1 }.freeze
+
+    class << self
+      # Copy every image under `source` into `catalog` as an imageset. Returns
+      # [names, errors]; nothing is written when errors is non-empty, so a
+      # broken assets/ tree can't half-stamp a catalog.
+      def write!(source, catalog)
+        sets, errors = plan(source)
+        return [[], errors] unless errors.empty?
+
+        sets.each do |set|
+          group = set[:dir] == "." ? catalog : File.join(catalog, set[:dir])
+          dir = File.join(group, "#{set[:name]}.imageset")
+          FileUtils.mkdir_p(dir)
+          set[:variants].each { |v| FileUtils.cp(v[:path], File.join(dir, File.basename(v[:path]))) }
+          File.write(File.join(dir, "Contents.json"), "#{JSON.pretty_generate(contents(set))}\n")
+          write_group_folders(catalog, set[:dir])
+        end
+
+        [sets.map { |set| set[:name] }.sort, []]
+      end
+
+      private
+
+      # Group the tree into one imageset per name, validating as we go. Errors
+      # are collected (not raised) so one `every build` reports every problem.
+      def plan(source)
+        errors = []
+        files = Dir.glob(File.join(source, "**", "*"))
+                   .select { |path| File.file?(path) && !File.basename(path).start_with?(".") }
+                   .sort
+        images, other = files.partition { |path| EXTENSIONS.include?(File.extname(path).downcase) }
+
+        other.each do |path|
+          errors << "#{relative(path, source)}: unsupported image type — use #{EXTENSIONS.join(", ")}"
+        end
+        variants = images.filter_map { |path| variant(path, source, errors) }
+
+        sets = variants.group_by { |v| v[:name] }.map do |name, group|
+          dirs = group.map { |v| v[:dir] }.uniq
+          if dirs.length > 1
+            errors << "#{name}: same asset name in #{dirs.map { |d| d == "." ? "assets/" : "assets/#{d}/" }.join(" and ")} " \
+                      "— names are global in the catalog, so rename one"
+          end
+          errors.concat(slot_errors(name, group))
+          { name: name, dir: dirs.first, variants: group }
+        end
+
+        [sets, errors]
+      end
+
+      def variant(path, source, errors)
+        relative = relative(path, source)
+        extension = File.extname(path).downcase
+        name, scale, dark = parse(File.basename(path, File.extname(path)))
+
+        unless name.match?(VALID_NAME)
+          errors << "#{relative}: #{name.inspect} isn't a usable asset name — " \
+                    "use letters, digits, _, - and ."
+          return nil
+        end
+        if RESERVED.include?(name)
+          errors << "#{relative}: #{name} is reserved (stamped from config/everywhere.yml) — rename it"
+          return nil
+        end
+        if scale && VECTOR.include?(extension)
+          errors << "#{relative}: vector assets are scale-free — drop the @#{scale} suffix"
+          return nil
+        end
+
+        { name: name, dir: File.dirname(relative), scale: scale, dark: dark,
+          vector: VECTOR.include?(extension), path: path, relative: relative }
+      end
+
+      # Trailing @2x/@3x and ~dark markers, in either order, off the stem.
+      def parse(base)
+        name = base.dup
+        scale = nil
+        dark = false
+        loop do
+          if name.sub!(/~dark\z/, "")
+            dark = true
+          elsif name.sub!(/@([23])x\z/, "")
+            scale = "#{Regexp.last_match(1)}x"
+          else
+            break
+          end
+        end
+        [name, scale, dark]
+      end
+
+      def slot_errors(name, group)
+        errors = []
+        if group.map { |v| v[:vector] }.uniq.length > 1
+          errors << "#{name}: mixes vector and raster files — pick one per asset"
+        end
+        group.group_by { |v| [v[:scale], v[:dark]] }.each_value do |clash|
+          next if clash.length < 2
+
+          errors << "#{name}: #{clash.map { |v| v[:relative] }.join(" and ")} both claim the same slot"
+        end
+        errors
+      end
+
+      # Two shapes: a 1x/2x/3x set when any file carries a scale suffix (empty
+      # slots are declared, which is what Xcode itself writes), otherwise a
+      # single-scale set — one file used at every scale. Bare filenames get
+      # single-scale so a 3x-resolution export isn't silently treated as 1x.
+      def contents(set)
+        images =
+          if set[:variants].any? { |v| v[:scale] }
+            %w[1x 2x 3x].flat_map { |scale| slots(set, scale) }
+          else
+            slots(set, nil)
+          end
+
+        { "images" => images, "info" => INFO }
+      end
+
+      def slots(set, scale)
+        [false, true].filter_map do |dark|
+          # A light slot always exists (Xcode declares empty ones); a dark slot
+          # only when the app actually shipped a ~dark file for it.
+          file = set[:variants].find { |v| v[:dark] == dark && (scale.nil? || (v[:scale] || "1x") == scale) }
+          next if dark && file.nil?
+
+          entry = { "idiom" => "universal" }
+          entry["appearances"] = [{ "appearance" => "luminosity", "value" => "dark" }] if dark
+          entry["filename"] = File.basename(file[:path]) if file
+          entry["scale"] = scale if scale
+          entry["properties"] = { "preserves-vector-representation" => true } if file && file[:vector]
+          entry
+        end
+      end
+
+      # Plain catalog folders (no provides-namespace) — organisation only, so
+      # assets/branding/logo.png stays Image("logo").
+      def write_group_folders(catalog, dir)
+        return if dir == "."
+
+        path_prefixes(dir).each do |prefix|
+          path = File.join(catalog, prefix)
+          FileUtils.mkdir_p(path)
+          contents = File.join(path, "Contents.json")
+          File.write(contents, "#{JSON.pretty_generate("info" => INFO)}\n") unless File.exist?(contents)
+        end
+      end
+
+      def path_prefixes(dir)
+        dir.split(File::SEPARATOR).each_with_object([]) do |part, acc|
+          acc << (acc.empty? ? part : File.join(acc.last, part))
+        end
+      end
+
+      def relative(path, source)
+        path.delete_prefix("#{source}/")
+      end
+    end
+  end
+end