ruby_everywhere 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c87aa5a2416d070a8047b790f28c7230882999b7df4f7f584256ee96852f066
-  data.tar.gz: 6fa25612acf17e6d90b3302a4e7f93a8d5ded79fd8ffb39aec318b908df32bcf
+  metadata.gz: a1644d6c9be14fdb8ef738eaee6f33225e5916ea401945f7c6c494e8963a2c16
+  data.tar.gz: 03621b7846f16b5621a352e7d4fc42ac38c8859095fc1be1098eef48b081fb0f
 SHA512:
-  metadata.gz: 69fb1bdb659b8b886d9b602e09e21d8016caf140ac401ee371d4b0eaab2e06f3b342fb7742e2684570b80e71768fb2c5ede34dca3f1d5b9015185b93b176ba59
-  data.tar.gz: 450a804d3bf9765ea664e0728c66df31019e5633393680120ef9ec7ba40def7e69f163b9aaaf6b2d2fcec948e62c5d3821b26bb553924666dfb57b7d1c6b29cd
+  metadata.gz: 4de42927fa8a53c136e0f9a3015ee1f930199642a26504d198673d0fe3e8cc24e32e9db219d34a170023809db8a9fb20715a6577e13cc6bb030fc9e3a8600b45
+  data.tar.gz: 58da2af357a422bd9dd87badf31175ba71767a5c3364d52f875690fd217a0be15cf1b12296bb195332ebec015ede65b7f486e3c1bf65ff66d5d0cb6831a20e3f

data/exe/every

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "everywhere/cli"
+require "everywhere/entrypoint"
 
-Dry::CLI.new(Everywhere::CLI).call
+Everywhere::Entrypoint.run

data/exe/rbe

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "everywhere/cli"
+require "everywhere/entrypoint"
 
-Dry::CLI.new(Everywhere::CLI).call
+Everywhere::Entrypoint.run

data/lib/everywhere/agents_guide.rb

@@ -51,7 +51,9 @@ module Everywhere
       path = File.join(template_dir, *parts)
       File.exist?(path) or UI.die!("couldn't find the bundled AGENTS.md template at #{path}; " \
                                    "reinstall ruby_everywhere")
-      File.read(path)
+      # The templates are UTF-8 prose; under LANG=C the gsub below would raise
+      # on them rather than substitute.
+      File.read(path, encoding: "UTF-8").scrub
     end
   end
 end

data/lib/everywhere/blake2b.rb

@@ -68,7 +68,12 @@ module Everywhere
       rescue StandardError
         nil
       end
-      return digest(File.binread(path), 64) unless md
+      # `digest` is one-shot (no incremental update), so the fallback has to hold
+      # the whole artifact in memory — worth warning about on a 300MB .zip.
+      unless md
+        warn_pure_ruby_fallback(path)
+        return digest(File.binread(path), 64)
+      end
 
       File.open(path, "rb") do |io|
         while (chunk = io.read(1 << 20))
@@ -78,6 +83,17 @@ module Everywhere
       md.digest
     end
 
+    # Once per process — signing prehashes the same artifact more than once.
+    def warn_pure_ruby_fallback(path)
+      return if @warned_fallback
+
+      @warned_fallback = true
+      require_relative "ui"
+      mb = (File.size(path) / 1024.0 / 1024.0).round(1)
+      Everywhere::UI.warn("this Ruby's OpenSSL has no BLAKE2b512 — hashing #{mb}MB in pure Ruby " \
+                          "(slow, and the file is read into memory)")
+    end
+
     def compress(h, block, t, last)
       m = block.unpack("Q<16")
       v = h + IV

data/lib/everywhere/boot.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "securerandom"
+require_relative "error"
 
 module Everywhere
   # Runtime boot for the packaged desktop build. Called from the app's
@@ -64,15 +65,32 @@ module Everywhere
     def default_app_data
       case RUBY_PLATFORM
       when /darwin/
-        File.join(Dir.home, "Library", "Application Support", config.bundle_id)
+        File.join(home, "Library", "Application Support", config.bundle_id)
       when /mingw|mswin/
-        File.join(ENV.fetch("APPDATA"), config.bundle_id)
+        File.join(app_data_env("APPDATA"), config.bundle_id)
       else
-        File.join(ENV.fetch("XDG_DATA_HOME", File.join(Dir.home, ".local", "share")),
-                  config.bundle_id)
+        # `||`, not ENV.fetch's default: the fallback resolves a home that a
+        # machine setting XDG_DATA_HOME needn't have.
+        File.join(ENV["XDG_DATA_HOME"] || File.join(home, ".local", "share"), config.bundle_id)
       end
     end
 
+    # Only reached in a standalone run — the shell always passes NATIVE_APPDATA.
+    # Dir.home raises when HOME is unset and there's no passwd entry (a
+    # container run with --user), which is a bare ArgumentError otherwise.
+    def home
+      Dir.home
+    rescue ArgumentError
+      raise Error, app_data_hint("no home directory")
+    end
+
+    def app_data_env(key)
+      ENV[key] or raise Error, app_data_hint("#{key} is unset")
+    end
+
+    def app_data_hint(reason) = "can't work out where to keep app data (#{reason}) — " \
+                                "set NATIVE_APPDATA (or HOME / APPDATA)"
+
     def prepare_app_data
       storage = File.join(app_data, "storage")
       FileUtils.mkdir_p(storage)
@@ -124,8 +142,14 @@ module Everywhere
     def ensure_secret_key_base
       secret_file = File.join(app_data, "secret_key_base")
       unless File.exist?(secret_file)
-        File.write(secret_file, SecureRandom.hex(64))
-        File.chmod(0o600, secret_file)
+        # Created 0600 rather than written then chmod'ed: this signs the app's
+        # cookies, and write-then-tighten leaves it world-readable in between.
+        # EXCL so a racing boot doesn't clobber the one already in use.
+        begin
+          File.open(secret_file, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |f| f.write(SecureRandom.hex(64)) }
+        rescue Errno::EEXIST
+          nil
+        end
       end
       ENV["SECRET_KEY_BASE"] ||= File.read(secret_file).strip
     end

data/lib/everywhere/builders/android.rb

@@ -10,6 +10,8 @@ require_relative "../android_resources"
 require_relative "../android_sdk"
 require_relative "../version"
 require_relative "../ui"
+require_relative "base"
+require_relative "native_sources"
 
 module Everywhere
   module Builders
@@ -32,13 +34,34 @@ module Everywhere
     #   app/src/stamped/res/drawable*/                  native/android/assets/** as drawables
     #   app/src/main/java/com/rubyeverywhere/shell/extensions/   native/android/*.kt + registry
     #
-    # MVP scope is a debug/unsigned-release APK. Keystore signing, AAB and Play
-    # upload hang off the same seam later — see docs/android-plan.md §9.
-    class Android
+    # Signing and the format Play accepts are driven from the environment, not
+    # from everywhere.yml — see SIGNING_ENV.
+    class Android < Base
       # Fixed by the template contract: one Gradle module, always :app, so
       # build paths and task names never depend on per-app values.
       GRADLE_MODULE = ":app"
 
+      # What each package format is called in the three places it has a name:
+      # the Gradle verb, the outputs/ subdirectory and the file extension.
+      FORMATS = {
+        apk: { task: "assemble", dir: "apk", extension: "apk" },
+        aab: { task: "bundle", dir: "bundle", extension: "aab" }
+      }.freeze
+
+      # Release signing is read from the environment and handed to Gradle as
+      # environment, never stamped into everywhere.properties: that file lives
+      # in the work dir for the life of the app, and a keystore password written
+      # there outlives the build that needed it. The keystore itself stays where
+      # the machine put it — nothing is copied into the project.
+      SIGNING_ENV = %w[EVERY_ANDROID_KEYSTORE EVERY_ANDROID_KEYSTORE_PASSWORD
+                       EVERY_ANDROID_KEY_ALIAS EVERY_ANDROID_KEY_PASSWORD].freeze
+
+      # The two the keystore can't be used without. EVERY_ANDROID_KEY_PASSWORD
+      # is not among them: a key generated without -keypass shares the store's.
+      REQUIRED_SIGNING_ENV = %w[EVERY_ANDROID_KEYSTORE_PASSWORD EVERY_ANDROID_KEY_ALIAS].freeze
+
+      VERSION_CODE_ENV = "EVERY_ANDROID_VERSION_CODE"
+
       # The Kotlin package the shell's sources live in. NOT the applicationId:
       # the app id is stamped per app, the code's package is frozen, and mixing
       # them up is the classic Android manifest mistake — so anything we
@@ -86,47 +109,36 @@ module Everywhere
       # keeps its fonts out of assets/ still resolves.
       BUNDLED_FONT_DIRS = [%w[app src main assets fonts], %w[fonts]].freeze
 
-      # Marks which template a work dir was staged from. A gem upgrade can add,
-      # rename or delete template files, and staging merges rather than wipes
-      # (see #stage), so a stale Kotlin file from an older template would keep
-      # compiling in. Version mismatch = wipe once, then merge as usual.
-      STAGE_MARKER = ".everywhere-template"
-
       # What AGP accepts as an applicationId: two or more segments, each a Java
       # identifier starting with a letter. No hyphens, unlike a bundle id.
       APPLICATION_ID = /\A[a-zA-Z]\w*(\.[a-zA-Z]\w*)+\z/
 
-      def initialize(config:, root:, target:, template_dir: nil)
-        @config = config
-        @root = root
-        @target = target
-        @template_dir = template_dir
-      end
-
-      # Build the APK and copy it into dist_dir. `dev` builds the debug variant
+      # Build the app and copy it into dist_dir. `dev` builds the debug variant
       # and relaxes the remote-mode requirement (the dev URL is stamped into a
       # debug asset each run — Android has no SIMCTL_CHILD_* equivalent).
-      # Returns the path of the collected APK.
-      def build!(dist_dir:, dev: false, dev_url: nil)
+      # `format` is :apk (installable) or :aab (what Play accepts). Returns the
+      # path of the collected artifact.
+      def build!(dist_dir:, dev: false, dev_url: nil, format: :apk)
         # The template is resolved before preflight, not after it like iOS:
         # preflight has to settle the icon font, and the bundled font lives in
         # the template. Everything that can fail slowly (a font download) or
         # cheaply (a typo'd icon name) is therefore decided before Gradle — the
         # difference between a 5-second error and one that lands 90 seconds in.
         template = @template_dir ? File.expand_path(@template_dir) : Paths.android_dir!
-        preflight!(dev: dev, template: template)
+        preflight!(dev: dev, format: format, template: template)
         work = stage(template)
         stamp!(work)
         stamp_dev_url!(work, dev_url)
         variant = dev ? "debug" : "release"
-        gradle!(work, variant, dist_dir)
-        collect(work, variant, dist_dir)
+        gradle!(work, variant, format, dist_dir)
+        collect(work, variant, format, dist_dir)
       end
 
       private
 
-      def name = @config.name(target: @target)
-      def application_id = @config.bundle_id(target: @target)
+      # AGP name for the bundle id, kept because everything Android-side (the
+      # properties file, the work dir, the validation) says applicationId.
+      def application_id = bundle_id
 
       # The dev-server URL, for the debug source set only (EverywhereConfig's
       # devUrl reads it, and release builds never look). This is the whole of
@@ -149,13 +161,17 @@ module Everywhere
         UI.step("pointing the shell at #{UI.cyan(dev_url)}")
       end
 
-      def preflight!(dev:, template:)
+      def preflight!(dev:, format:, template:)
         # Config shape first, machine state second: a typo in everywhere.yml is
         # the app author's to fix wherever they are, while "no Android SDK"
         # depends on the machine they happen to be sitting at.
         errors = @config.native_android_errors
         UI.die!("native.android in config/everywhere.yml:\n#{errors.join("\n")}") unless errors.empty?
 
+        check_format!(dev: dev, format: format)
+        @signing = dev ? nil : signing_env!
+        @version_code = version_code
+
         unless dev || @config.remote?
           UI.die!("Android apps are remote mode only for now — set remote.url in config/everywhere.yml " \
                   "(the shell wraps your deployed app; nothing is packaged locally)")
@@ -179,7 +195,10 @@ module Everywhere
         # fix — the analogue of the iOS xcode-select message.
         @sdk_root = AndroidSdk.sdk_root!
         @java_home = AndroidSdk.java_home!
-        AndroidSdk.adb!
+        # adb only matters when something is going to be installed on a device,
+        # so it is a `dev` requirement and not a build one — a headless runner
+        # that builds a release AAB has no reason to carry platform-tools.
+        AndroidSdk.adb! if dev
         # A missing compile SDK surfaces from Gradle as "Failed to find target
         # with hash string android-35", minutes in and after the AGP download.
         AndroidSdk.platform!
@@ -187,6 +206,48 @@ module Everywhere
         resolve_icon_font!(template)
       end
 
+      def check_format!(dev:, format:)
+        unless FORMATS.key?(format)
+          UI.die!("#{format.inspect} isn't an Android package format — :apk (installable) or :aab " \
+                  "(what Google Play accepts)")
+        end
+        return unless format == :aab && dev
+
+        UI.die!("an .aab can't be installed on a device or an emulator — it's an upload format Play " \
+                "re-signs into per-device APKs. `every dev` builds an APK; ask for the bundle when " \
+                "you're publishing")
+      end
+
+      # --- signing ---------------------------------------------------------------
+
+      # The signing environment Gradle is handed, or nil for the unsigned
+      # release the default build still produces. Resolved here rather than left
+      # to the build script so a half-configured keystore fails in seconds with
+      # the missing variable named, instead of as an AGP error two minutes in —
+      # or, worse, as an unsigned APK nobody notices until Play rejects it.
+      def signing_env!
+        keystore = env_value("EVERY_ANDROID_KEYSTORE") or return nil
+
+        missing = REQUIRED_SIGNING_ENV.reject { |name| env_value(name) }
+        unless missing.empty?
+          UI.die!("EVERY_ANDROID_KEYSTORE is set but #{missing.join(" and ")} " \
+                  "#{missing.one? ? "is" : "are"} not — signing needs the keystore, its password " \
+                  "and the alias of the key inside it (EVERY_ANDROID_KEY_PASSWORD falls back to " \
+                  "the keystore password)")
+        end
+
+        path = File.expand_path(keystore)
+        UI.die!("EVERY_ANDROID_KEYSTORE points at #{path}, which isn't a file") unless File.file?(path)
+
+        UI.step("signing the release #{UI.dim("(#{env_value("EVERY_ANDROID_KEY_ALIAS")} in " \
+                                             "#{UI.short_path(path)})")}")
+        { "EVERY_ANDROID_KEYSTORE" => path,
+          "EVERY_ANDROID_KEYSTORE_PASSWORD" => env_value("EVERY_ANDROID_KEYSTORE_PASSWORD"),
+          "EVERY_ANDROID_KEY_ALIAS" => env_value("EVERY_ANDROID_KEY_ALIAS"),
+          "EVERY_ANDROID_KEY_PASSWORD" => env_value("EVERY_ANDROID_KEY_PASSWORD") ||
+            env_value("EVERY_ANDROID_KEYSTORE_PASSWORD") }
+      end
+
       # Copy the template into the app's persistent work dir. Merged over
       # whatever is already there, NOT wiped like the iOS stage: Gradle's
       # incremental state (app/build/, .gradle/) lives *inside* this directory,
@@ -202,15 +263,10 @@ module Everywhere
         # non-executable gradlew fails with a bare "Permission denied".
         wrapper = File.join(work, "gradlew")
         FileUtils.chmod("u+x", wrapper) if File.file?(wrapper)
-        File.write(File.join(work, STAGE_MARKER), "#{Everywhere::VERSION}\n")
+        mark_staged!(work)
         work
       end
 
-      def staged_version(work)
-        marker = File.join(work, STAGE_MARKER)
-        File.read(marker).strip if File.file?(marker)
-      end
-
       # The whole per-app surface: identity properties, two JSON assets, colors,
       # launcher icons, the icon font, the merged-in manifest, the Extensions
       # sources + generated registry, and the Maven coordinate script. No build
@@ -248,7 +304,7 @@ module Everywhere
           # belong in config/everywhere.yml.
           everywhere.applicationId=#{properties_value(application_id)}
           everywhere.versionName=#{properties_value(@config.version(target: @target))}
-          everywhere.versionCode=#{version_code}
+          everywhere.versionCode=#{@version_code}
           everywhere.label=#{properties_value(name)}
         PROPERTIES
       end
@@ -257,7 +313,20 @@ module Everywhere
       # deriving it from the version the app already maintains beats asking for
       # a second number nobody remembers to bump. 1.2.3 → 10203, which stays
       # monotonic as long as minor/patch stay under 100.
+      #
+      # EVERY_ANDROID_VERSION_CODE overrides it outright, for the pipeline that
+      # numbers builds rather than versions them (a run number, a commit count).
       def version_code
+        override = env_value(VERSION_CODE_ENV) or return derived_version_code
+
+        unless override.match?(/\A[1-9]\d*\z/)
+          UI.die!("#{VERSION_CODE_ENV}=#{override.inspect} — a versionCode is a positive integer, " \
+                  "and Play only accepts an upload whose code is higher than the last one's")
+        end
+        override.to_i
+      end
+
+      def derived_version_code
         major, minor, patch = @config.version(target: @target).to_s.split(".").map(&:to_i)
         code = ((major || 0) * 10_000) + ((minor || 0) * 100) + (patch || 0)
         [code, 1].max
@@ -473,7 +542,13 @@ module Everywhere
             when Net::HTTPRedirection
               raise "too many redirects for #{url}" if redirects <= 0
 
-              return fetch!(response["location"], dest, sha256: sha256, redirects: redirects - 1)
+              # The font is checksummed, so a swapped body is caught anyway —
+              # but the base is https and a redirect has no business dropping
+              # to http on the way to a cached artifact.
+              target = URI.join(uri, response["location"].to_s)
+              raise "refusing a non-https redirect to #{target.host}" unless target.scheme == "https"
+
+              return fetch!(target.to_s, dest, sha256: sha256, redirects: redirects - 1)
             when Net::HTTPSuccess
               File.open(part, "wb") { |f| response.read_body { |chunk| f.write(chunk) } }
             else
@@ -672,18 +747,9 @@ module Everywhere
         FileUtils.rm_rf(dest)
         FileUtils.mkdir_p(dest)
 
-        source = File.join(@root, "native", "android")
-        sources = File.directory?(source) ? Dir.glob(File.join(source, "**", "*.kt")).sort : []
-        sources.each do |file|
-          relative = file.delete_prefix("#{source}/")
-          if File.basename(file) == "EverywhereExtensions.kt"
-            UI.die!("native/android/#{relative}: EverywhereExtensions.kt is generated by " \
-                    "`every build` — declare your types under native.android in config/everywhere.yml instead")
-          end
+        sources = NativeSources.copy!(from: File.join(@root, "native", "android"), into: dest, ext: "kt",
+                                      reserved: "EverywhereExtensions.kt", label: "native/android") do |file, relative|
           check_package!(file, relative)
-          target_file = File.join(dest, relative)
-          FileUtils.mkdir_p(File.dirname(target_file))
-          FileUtils.cp(file, target_file)
         end
 
         if @config.native_android?
@@ -796,45 +862,67 @@ module Everywhere
 
       # --- gradle ---------------------------------------------------------------
 
-      def gradle!(work, variant, dist_dir)
-        UI.step("building Android shell #{UI.dim("(Gradle, #{variant}, first run downloads " \
-                                                "Gradle and the Android Gradle Plugin)")}")
+      def gradle!(work, variant, format, dist_dir)
+        UI.step("building Android shell #{UI.dim("(Gradle, #{variant} #{format.to_s.upcase}, first " \
+                                                "run downloads Gradle and the Android Gradle Plugin)")}")
         FileUtils.mkdir_p(dist_dir)
         log = File.join(dist_dir, "android-build.log")
-        task = "#{GRADLE_MODULE}:assemble#{variant.capitalize}"
+        task = "#{GRADLE_MODULE}:#{FORMATS.fetch(format)[:task]}#{variant.capitalize}"
         # -p instead of a chdir: the wrapper finds its own jar from $0, so an
         # absolute gradlew with an explicit project dir works from anywhere
         # (Shellout.run_logged! has no chdir). --console=plain keeps the stream
         # line-oriented for LogFilter whether or not a TTY is attached.
         Shellout.run_logged!(gradle_env,
-                             [File.join(work, "gradlew"), "-p", work, "--console=plain", task],
+                             [gradle_wrapper(work), "-p", work, "--console=plain", task],
                              log: log, filter: LogFilter.for(:gradle))
       end
 
+      # The wrapper Windows can actually execute — the POSIX gradlew is a shell
+      # script there, and cmd.exe won't run it.
+      def gradle_wrapper(work)
+        File.join(work, AndroidSdk.windows? ? "gradlew.bat" : "gradlew")
+      end
+
       # The whole toolchain is handed to Gradle explicitly. ANDROID_HOME is what
       # AGP reads when there's no local.properties — and we never write one, so
       # the stamped project stays clean and Android Studio can resolve its own
       # SDK. GRADLE_USER_HOME redirects the 1.4 GB of Gradle distribution, AGP
       # and Hotwire artifacts out of the gem and into a cache shared by every app.
+      #
+      # The signing variables travel the same way rather than through a file the
+      # build script reads: env is the one channel that reaches the Gradle child
+      # without leaving a password on disk. The resolved values (absolute
+      # keystore path, key password defaulted to the store's) are what's passed,
+      # so the build script never has to repeat the fallback.
       def gradle_env
         { "JAVA_HOME" => @java_home,
           "ANDROID_HOME" => @sdk_root,
           "ANDROID_SDK_ROOT" => @sdk_root,
-          "GRADLE_USER_HOME" => Paths.android_gradle_home }
-      end
-
-      # Copy the APK out of the module's build dir. Release is unsigned until
-      # keystore signing lands (docs/android-plan.md §9), and AGP spells that
-      # variant app-release-unsigned.apk — accept either name so the collect
-      # step doesn't have to be revisited when signing arrives.
-      def collect(work, variant, dist_dir)
-        dir = File.join(work, "app", "build", "outputs", "apk", variant)
-        built = ["app-#{variant}.apk", "app-#{variant}-unsigned.apk"]
-                .map { |file| File.join(dir, file) }
-                .find { |path| File.file?(path) }
-        UI.die!("Gradle reported success but no APK in #{UI.short_path(dir)}") unless built
+          "GRADLE_USER_HOME" => Paths.android_gradle_home,
+          VERSION_CODE_ENV => @version_code.to_s }.merge(@signing || {})
+      end
+
+      # Copy the built artifact out of the module's build dir. An unsigned
+      # release APK is spelled app-release-unsigned.apk by AGP, so both names
+      # are accepted — but only when no keystore was configured: with one set,
+      # the unsigned name means the signingConfig didn't take, and shipping that
+      # silently is how an unsignable APK reaches Play. Bundles have no such
+      # spelling; bundleRelease writes app-release.aab either way.
+      def collect(work, variant, format, dist_dir)
+        spec = FORMATS.fetch(format)
+        kind = spec[:extension].upcase
+        dir = File.join(work, "app", "build", "outputs", spec[:dir], variant)
+        signed = File.join(dir, "app-#{variant}.#{spec[:extension]}")
+        unsigned = File.join(dir, "app-#{variant}-unsigned.#{spec[:extension]}")
+        built = [signed, unsigned].find { |path| File.file?(path) }
+        UI.die!("Gradle reported success but no #{kind} in #{UI.short_path(dir)}") unless built
+
+        if @signing && built == unsigned
+          UI.die!("Gradle wrote #{File.basename(built)} — EVERY_ANDROID_KEYSTORE is set, so the " \
+                  "#{kind} should have been signed. Check the keystore's alias and passwords")
+        end
 
-        dest = File.join(dist_dir, "#{name}.apk")
+        dest = File.join(dist_dir, "#{name}.#{spec[:extension]}")
         FileUtils.rm_f(dest)
         FileUtils.cp(built, dest)
         dest

data/lib/everywhere/builders/base.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../version"
+
+module Everywhere
+  module Builders
+    # What the three platform builders (Android, Ios, Desktop) genuinely share.
+    # Deliberately thin: `stage`, `preflight!`, `stamp!` and `collect` are
+    # structurally parallel across the three but mean different things on each
+    # platform, so they stay where they are. Only identity (name, bundle id),
+    # the environment reader and the stage marker live here.
+    class Base
+      # Marks which template a work dir was staged from. A gem upgrade can add,
+      # rename or delete template files, and staging merges rather than wipes
+      # (see #stage), so a stale Kotlin file from an older template would keep
+      # compiling in. Version mismatch = wipe once, then merge as usual.
+      STAGE_MARKER = ".everywhere-template"
+
+      # `target` is a build target like "ios-arm64" or "android-arm64"; the
+      # desktop builder has none, and everything below reads it as nil.
+      def initialize(config:, root:, target: nil, template_dir: nil)
+        @config = config
+        @root = root
+        @target = target
+        @template_dir = template_dir
+      end
+
+      private
+
+      def name = @config.name(target: @target)
+      def bundle_id = @config.bundle_id(target: @target)
+
+      # An env var that was set to nothing is the same as unset here: CI writes
+      # `EVERY_ANDROID_KEYSTORE: ${{ secrets.KEYSTORE }}` whether or not the
+      # secret exists, and an empty keystore path must not look configured.
+      def env_value(name)
+        value = ENV[name].to_s.strip
+        value.empty? ? nil : value
+      end
+
+      def staged_version(work)
+        marker = File.join(work, STAGE_MARKER)
+        File.read(marker).strip if File.file?(marker)
+      end
+
+      # Records which gem version staged this work dir, for the next run to
+      # read back.
+      def mark_staged!(work)
+        File.write(File.join(work, STAGE_MARKER), "#{Everywhere::VERSION}\n")
+      end
+    end
+  end
+end