pindo 5.17.4 → 5.18.3

data/lib/pindo/module/android/workflow_gradle_injector.rb

@@ -0,0 +1,702 @@
+require "fileutils"
+require "json"
+require "digest"
+require "securerandom"
+require "set"
+
+require_relative "android_build_helper"
+
+module Pindo
+  module Android
+    class WorkflowGradleInjector
+      TMP_ROOT_RELATIVE = ".pindo_tmp".freeze
+      LOCK_RELATIVE_PATH = File.join(TMP_ROOT_RELATIVE, "locks", "gradle_inject.lock").freeze
+      RUNS_RELATIVE_DIR = File.join(TMP_ROOT_RELATIVE, "gradle_inject").freeze
+
+      MARK_BEGIN = "PINDO_WORKFLOW_GRADLE_INJECTOR_BEGIN".freeze
+      MARK_END = "PINDO_WORKFLOW_GRADLE_INJECTOR_END".freeze
+
+      RELEASE_SIGNING_ENV_VARS = %w[
+        RELEASE_KEYSTORE_PATH
+        RELEASE_KEYSTORE_PASSWORD
+        RELEASE_KEY_ALIAS
+        RELEASE_KEY_PASSWORD
+      ].freeze
+
+      class << self
+        # 仅执行 prepare! 并 yield(context)。不在此自动 cleanup!：
+        # Gradle 注入与 JKS 的清理时机由调用方在「AAB→APK（universal.apk）成功产出后」统一处理；
+        # 构建失败时调用方应在 ensure 中执行 cleanup! 以恢复 gradle，但不应删除尚未完成转换流程所需的 JKS。
+        def with_injection(project_dir:, workflow_name:, workflow_build_type: nil, enable_pad: true, main_module: nil)
+          injector = new
+          injector.prepare!(
+            project_dir: project_dir,
+            workflow_name: workflow_name,
+            workflow_build_type: workflow_build_type,
+            enable_pad: enable_pad,
+            main_module: main_module
+          ).tap { |context| yield(context) }
+        end
+
+        # 删除工程根下打包过程生成的 `.pindo_tmp`（锁文件、gradle_inject 等）。
+        # 须在 `cleanup!` 释放文件锁之后调用。
+        def remove_project_pindo_tmp_dir!(project_dir)
+          return if project_dir.to_s.empty?
+
+          base = File.expand_path(project_dir)
+          return unless File.directory?(base)
+
+          target = File.expand_path(File.join(base, TMP_ROOT_RELATIVE))
+          return unless File.dirname(target) == base
+
+          FileUtils.rm_rf(target) if File.exist?(target)
+        end
+      end
+
+      def prepare!(project_dir:, workflow_name:, workflow_build_type: nil, enable_pad: true, main_module: nil)
+        raise ArgumentError, "project_dir 不能为空" if project_dir.to_s.empty?
+        raise ArgumentError, "项目目录不存在: #{project_dir}" unless File.directory?(project_dir)
+        raise ArgumentError, "workflow_name 不能为空" if workflow_name.to_s.empty?
+
+        run_id = SecureRandom.uuid
+        workflow_build_type ||= sanitize_workflow_build_type(workflow_name)
+        signing_config_name = workflow_build_type
+
+        tmp_run_dir = File.join(project_dir, RUNS_RELATIVE_DIR, run_id)
+        backup_dir = File.join(tmp_run_dir, "backup")
+        marker_path = File.join(tmp_run_dir, "marker")
+        manifest_path = File.join(tmp_run_dir, "manifest.json")
+
+        FileUtils.mkdir_p(backup_dir)
+
+        lock_file = File.join(project_dir, LOCK_RELATIVE_PATH)
+        FileUtils.mkdir_p(File.dirname(lock_file))
+
+        lock_io = File.open(lock_file, File::RDWR | File::CREAT, 0o644)
+        lock_io.flock(File::LOCK_EX)
+
+        begin
+          self_check_restore!(project_dir)
+
+          context = {
+            project_dir: project_dir,
+            run_id: run_id,
+            workflow_name: workflow_name,
+            workflow_build_type: workflow_build_type,
+            signing_config_name: signing_config_name,
+            tmp_run_dir: tmp_run_dir,
+            backup_dir: backup_dir,
+            marker_path: marker_path,
+            manifest_path: manifest_path,
+            lock_file: lock_file,
+            lock_io: lock_io,
+            backups: [],
+            created_dirs: [],
+          }
+
+          # 1) 先备份/再 PAD（PAD 会改 settings.gradle/launcher build.gradle/新增 pack 目录/移动 assets）
+          if enable_pad
+            pad_backup!(context)
+            run_pad!(context)
+          end
+
+          # 2) 注入 buildType/signingConfig（对所有 Android modules）
+          gradle_files = discover_gradle_module_files(project_dir)
+          main_module_gradle = resolve_main_module_gradle_file(project_dir, gradle_files, main_module: main_module)
+
+          # 需要改写的文件清单（幂等：已包含标记则不会重复注入）
+          to_inject = gradle_files.dup
+          to_inject << main_module_gradle if main_module_gradle && !to_inject.include?(main_module_gradle)
+          to_inject.compact!
+          to_inject.uniq!
+
+          to_inject.each { |path| backup_file!(context, path) }
+
+          File.write(marker_path, JSON.pretty_generate({
+            run_id: run_id,
+            workflow_name: workflow_name,
+            workflow_build_type: workflow_build_type,
+            signing_config_name: signing_config_name,
+            started_at: Time.now.to_i,
+          }))
+
+          to_inject.each do |gradle_path|
+            inject_into_gradle_file!(
+              gradle_path: gradle_path,
+              workflow_name: workflow_name,
+              workflow_build_type: workflow_build_type,
+              signing_config_name: signing_config_name,
+              is_main_module: (gradle_path == main_module_gradle)
+            )
+          end
+
+          File.write(manifest_path, JSON.pretty_generate({
+            run_id: run_id,
+            marker_path: marker_path,
+            backups: context[:backups],
+            created_dirs: context[:created_dirs],
+          }))
+
+          context
+        rescue
+          # 如果 prepare! 中途失败，也尽可能清理掉 marker/恢复备份，避免污染后续运行
+          begin
+            cleanup!({
+              project_dir: project_dir,
+              tmp_run_dir: tmp_run_dir,
+              marker_path: marker_path,
+              manifest_path: manifest_path,
+              lock_io: lock_io,
+              backups: [],
+              created_dirs: [],
+            })
+          rescue
+            # ignore
+          end
+          raise
+        end
+      end
+
+      def cleanup!(context)
+        project_dir = context[:project_dir]
+        tmp_run_dir = context[:tmp_run_dir]
+
+        restore_from_manifest!(context)
+
+        FileUtils.rm_f(context[:marker_path]) if context[:marker_path]
+        FileUtils.rm_rf(tmp_run_dir) if tmp_run_dir && tmp_run_dir.start_with?(project_dir.to_s)
+      ensure
+        begin
+          if (lock_io = context[:lock_io])
+            lock_io.flock(File::LOCK_UN)
+            lock_io.close
+          end
+        rescue
+          # ignore
+        end
+      end
+
+      def sanitize_workflow_build_type(workflow_name)
+        raw = workflow_name.to_s
+
+        parts = raw.gsub(/[^A-Za-z0-9_]+/, " ").strip.split(/\s+/)
+        # 去掉开头的 "test" 词：AGP 禁止 BuildType 名以 test 开头；如 "test demo" 应生成 demo 而非 testDemo
+        while parts.first && parts.first.casecmp("test").zero?
+          parts.shift
+        end
+
+        base = if parts.empty?
+                 "workflow"
+               else
+                 first = parts.first.downcase
+                 rest = parts.drop(1).map { |p| p[0].to_s.upcase + p[1..].to_s.downcase }
+                 ([first] + rest).join
+               end
+
+        base = base.gsub(/[^A-Za-z0-9_]/, "")
+        base = "w_#{base}" unless base.match?(/\A[A-Za-z]/)
+        # AGP：BuildType 名称不能以 test 开头（保留字），否则报 BuildType names cannot start with 'test'
+        base = "wf_#{base}" if base.match?(/\Atest/i)
+
+        max_len = 40
+        if base.length > max_len
+          digest = Digest::SHA256.hexdigest(raw)[0, 8]
+          base = "#{base[0, max_len - 9]}_#{digest}"
+        end
+
+        base
+      end
+
+      private
+
+      def self_check_restore!(project_dir)
+        runs_dir = File.join(project_dir, RUNS_RELATIVE_DIR)
+        return unless File.directory?(runs_dir)
+
+        Dir.each_child(runs_dir) do |run_id|
+          run_dir = File.join(runs_dir, run_id)
+          marker = File.join(run_dir, "marker")
+          manifest = File.join(run_dir, "manifest.json")
+          next unless File.file?(marker) && File.file?(manifest)
+
+          begin
+            data = JSON.parse(File.read(manifest))
+            self.class.restore_from_manifest_data!(project_dir, data)
+            FileUtils.rm_rf(run_dir)
+          rescue => e
+            raise RuntimeError, "检测到未恢复的 Gradle 注入残留，但自动恢复失败: #{e.message}\n残留目录: #{run_dir}"
+          end
+        end
+      end
+
+      def restore_from_manifest!(context)
+        manifest_path = context[:manifest_path]
+        return unless manifest_path && File.file?(manifest_path)
+
+        data = JSON.parse(File.read(manifest_path))
+        self.class.restore_from_manifest_data!(context[:project_dir], data)
+      end
+
+      def self.restore_from_manifest_data!(project_dir, data)
+        backups = data["backups"] || []
+        backups.each do |item|
+          path = File.join(project_dir, item.fetch("path"))
+          backup_path = File.join(project_dir, item.fetch("backup_path"))
+          next unless File.file?(backup_path)
+
+          FileUtils.mkdir_p(File.dirname(path))
+          bin_copy(backup_path, path)
+        end
+
+        (data["created_dirs"] || []).each do |rel|
+          abs = File.join(project_dir, rel)
+          FileUtils.rm_rf(abs) if abs.start_with?(project_dir.to_s)
+        end
+      end
+
+      def pad_backup!(context)
+        project_dir = context[:project_dir]
+
+        settings = find_settings_gradle(project_dir)
+        backup_file!(context, settings) if settings
+
+        # 备份 launcher/app build.gradle（PAD 会写 assetPacks；我们先按既有规则猜主模块）
+        gradle_files = discover_gradle_module_files(project_dir)
+        main_gradle = resolve_main_module_gradle_file(project_dir, gradle_files, main_module: nil)
+        backup_file!(context, main_gradle) if main_gradle
+
+        assets_root = File.join(project_dir, "unityLibrary", "src", "main", "assets")
+        return unless File.directory?(assets_root)
+
+        subdirs = Dir.glob(File.join(assets_root, "*")).select { |p| File.directory?(p) }
+        subdirs.reject! { |p| File.basename(p).downcase == "bin" }
+        return if subdirs.empty?
+
+        subdirs.each do |abs_dir|
+          rel = abs_dir.delete_prefix("#{project_dir}/")
+          backup_dir = File.join(project_dir, context[:backup_dir].delete_prefix("#{project_dir}/"), rel)
+          FileUtils.mkdir_p(File.dirname(backup_dir))
+          FileUtils.rm_rf(backup_dir)
+          FileUtils.cp_r(abs_dir, backup_dir)
+          context[:backups] << {
+            "type" => "dir",
+            "path" => rel,
+            "backup_path" => backup_dir.delete_prefix("#{project_dir}/"),
+          }
+        end
+      end
+
+      def run_pad!(context)
+        project_dir = context[:project_dir]
+
+        before_children = Dir.children(project_dir).to_set
+        Pindo::AndroidBuildHelper.share_instance.setup_play_asset_delivery(project_dir)
+        after_children = Dir.children(project_dir).to_set
+
+        created = (after_children - before_children).select do |name|
+          # PAD 产物一般是 *_pack 目录
+          name.end_with?("_pack") && File.directory?(File.join(project_dir, name))
+        end
+
+        created.each do |name|
+          context[:created_dirs] << name
+        end
+      end
+
+      def discover_gradle_module_files(project_dir)
+        settings = find_settings_gradle(project_dir)
+        module_names = settings ? parse_settings_includes(settings) : []
+
+        paths = module_names.filter_map do |m|
+          rel = m.tr(":", "/").sub(%r{\A/+}, "")
+          next if rel.empty?
+
+          groovy = File.join(project_dir, rel, "build.gradle")
+          kts = File.join(project_dir, rel, "build.gradle.kts")
+          if File.file?(kts)
+            kts
+          elsif File.file?(groovy)
+            groovy
+          end
+        end
+
+        # settings 解析失败时，兜底扫描常见主模块
+        if paths.empty?
+          %w[launcher app unityLibrary].each do |name|
+            %w[build.gradle build.gradle.kts].each do |f|
+              p = File.join(project_dir, name, f)
+              paths << p if File.file?(p)
+            end
+          end
+        end
+
+        paths.uniq
+      end
+
+      def find_settings_gradle(project_dir)
+        groovy = File.join(project_dir, "settings.gradle")
+        kts = File.join(project_dir, "settings.gradle.kts")
+        return kts if File.file?(kts)
+        return groovy if File.file?(groovy)
+
+        nil
+      end
+
+      def parse_settings_includes(settings_path)
+        content = File.read(settings_path)
+        includes = []
+
+        content.scan(/include\s+(.*)$/).each do |m|
+          line = m.first.to_s
+          line.scan(/["'](:[^"']+)["']/).each do |mm|
+            includes << mm.first
+          end
+        end
+
+        includes.uniq
+      end
+
+      def resolve_main_module_gradle_file(project_dir, gradle_files, main_module:)
+        if main_module && !main_module.to_s.empty?
+          %w[build.gradle.kts build.gradle].each do |f|
+            p = File.join(project_dir, main_module.to_s.delete_prefix(":"), f)
+            return p if File.file?(p)
+          end
+        end
+
+        # 优先 launcher，其次 app，其次第一个 application module
+        candidate = gradle_files.find { |p| p.include?("/launcher/") } ||
+                    gradle_files.find { |p| p.include?("/app/") }
+        return candidate if candidate && android_application_module?(candidate)
+
+        gradle_files.find { |p| android_application_module?(p) }
+      end
+
+      def android_application_module?(gradle_path)
+        content = File.read(gradle_path)
+        return true if content.include?("com.android.application")
+        return true if content.match?(/id\s*\(?\s*["']com\.android\.application["']\s*\)?/)
+        return true if content.match?(/alias\(\s*libs\.plugins\.android\.application\s*\)/)
+
+        false
+      end
+
+      def android_asset_pack_module?(gradle_path)
+        content = File.read(gradle_path)
+        content.include?("com.android.asset-pack") ||
+          content.match?(/id\s*\(?\s*["']com\.android\.asset-pack["']\s*\)?/) ||
+          content.match?(/alias\(\s*libs\.plugins\.android\.asset\.pack\s*\)/)
+      end
+
+      def android_module?(gradle_path)
+        content = File.read(gradle_path)
+        return false if android_asset_pack_module?(gradle_path)
+
+        content.include?("com.android.application") ||
+          content.include?("com.android.library") ||
+          content.include?("com.android.dynamic-feature") ||
+          content.match?(/com\.android\.(application|library|dynamic-feature)/) ||
+          content.match?(/alias\(\s*libs\.plugins\.android\.(application|library|dynamic\.feature)\s*\)/)
+      end
+
+      def gradle_dsl(gradle_path)
+        gradle_path.end_with?(".kts") ? :kts : :groovy
+      end
+
+      def inject_into_gradle_file!(gradle_path:, workflow_name:, workflow_build_type:, signing_config_name:, is_main_module:)
+        return unless File.file?(gradle_path)
+        return unless android_module?(gradle_path)
+        return if android_asset_pack_module?(gradle_path)
+
+        original = File.read(gradle_path)
+        # 模板可能迭代升级：若存在旧注入块，先移除再按新模板注入
+        if original.include?(MARK_BEGIN) && original.include?(MARK_END)
+          original = remove_marked_blocks(original)
+        end
+
+        dsl = gradle_dsl(gradle_path)
+
+        signing_entry = if is_main_module
+                          dsl == :kts ? kts_signing_config_entry(workflow_name:, workflow_build_type:, signing_config_name:) :
+                            groovy_signing_config_entry(workflow_name:, workflow_build_type:, signing_config_name:)
+                        end
+
+        build_type_entry = dsl == :kts ? kts_build_type_entry(workflow_name:, workflow_build_type:, signing_config_name:, is_main_module:) :
+          groovy_build_type_entry(workflow_name:, workflow_build_type:, signing_config_name:, is_main_module:)
+
+        updated = inject_into_existing_android_block(
+          original,
+          signing_entry: signing_entry,
+          build_type_entry: build_type_entry,
+          workflow_build_type: workflow_build_type,
+          signing_config_name: signing_config_name,
+          dsl: dsl
+        )
+        File.write(gradle_path, updated)
+      end
+
+      def remove_marked_blocks(content)
+        out = content.dup
+        loop do
+          b = out.index(MARK_BEGIN)
+          e = out.index(MARK_END)
+          break unless b && e && e > b
+
+          line_start = out.rindex("\n", b) || 0
+          line_start = 0 if line_start == 0
+          line_end = out.index("\n", e) || (out.length - 1)
+          out = out[0...line_start] + out[(line_end + 1)..]
+        end
+        out
+      end
+
+      def groovy_signing_config_entry(workflow_name:, workflow_build_type:, signing_config_name:)
+        lines = []
+        lines << "// #{MARK_BEGIN}"
+        lines << "// workflowName=#{workflow_name.inspect}"
+        lines << "#{signing_config_name} {"
+        lines << "    def signingEnvVars = #{RELEASE_SIGNING_ENV_VARS.inspect}"
+        lines << "    def hasCompleteReleaseSigningEnv = signingEnvVars.every { System.getenv(it) }"
+        lines << "    if (!hasCompleteReleaseSigningEnv) {"
+        lines << "        throw new GradleException(\"Missing required environment variables for release signing: ${signingEnvVars.join(', ')}\")"
+        lines << "    }"
+        lines << "    def releaseKeystorePath = System.getenv(\"RELEASE_KEYSTORE_PATH\")"
+        lines << "    def keystoreFile = file(releaseKeystorePath)"
+        lines << "    if (!keystoreFile.exists()) {"
+        lines << "        throw new GradleException(\"Keystore file not found: ${keystoreFile.absolutePath}\")"
+        lines << "    }"
+        lines << "    storeFile keystoreFile"
+        lines << "    storePassword System.getenv(\"RELEASE_KEYSTORE_PASSWORD\")"
+        lines << "    keyAlias System.getenv(\"RELEASE_KEY_ALIAS\")"
+        lines << "    keyPassword System.getenv(\"RELEASE_KEY_PASSWORD\")"
+        lines << "}"
+        lines << "// #{MARK_END}"
+        lines.join("\n")
+      end
+
+      def kts_signing_config_entry(workflow_name:, workflow_build_type:, signing_config_name:)
+        lines = []
+        lines << "// #{MARK_BEGIN}"
+        lines << "// workflowName=#{workflow_name.inspect}"
+        lines << "create(\"#{signing_config_name}\") {"
+        lines << "    val signingEnvVars = listOf("
+        RELEASE_SIGNING_ENV_VARS.each_with_index do |v, idx|
+          comma = idx == RELEASE_SIGNING_ENV_VARS.length - 1 ? "" : ","
+          lines << "        \"#{v}\"#{comma}"
+        end
+        lines << "    )"
+        lines << "    val hasCompleteReleaseSigningEnv = signingEnvVars.all { System.getenv(it)?.isNotBlank() == true }"
+        lines << "    if (!hasCompleteReleaseSigningEnv) {"
+        lines << "        throw GradleException(\"Missing required environment variables for release signing: ${signingEnvVars.joinToString(\", \")}\")"
+        lines << "    }"
+        lines << "    val releaseKeystorePath = System.getenv(\"RELEASE_KEYSTORE_PATH\")"
+        lines << "    val keystoreFile = file(releaseKeystorePath)"
+        lines << "    if (!keystoreFile.exists()) {"
+        lines << "        throw GradleException(\"Keystore file not found: ${keystoreFile.absolutePath}\")"
+        lines << "    }"
+        lines << "    storeFile = keystoreFile"
+        lines << "    storePassword = System.getenv(\"RELEASE_KEYSTORE_PASSWORD\")"
+        lines << "    keyAlias = System.getenv(\"RELEASE_KEY_ALIAS\")"
+        lines << "    keyPassword = System.getenv(\"RELEASE_KEY_PASSWORD\")"
+        lines << "}"
+        lines << "// #{MARK_END}"
+        lines.join("\n")
+      end
+
+      def groovy_build_type_entry(workflow_name:, workflow_build_type:, signing_config_name:, is_main_module:)
+        lines = []
+        lines << "// #{MARK_BEGIN}"
+        lines << "// workflowName=#{workflow_name.inspect}"
+        lines << "#{workflow_build_type} {"
+        lines << "    minifyEnabled false"
+        if is_main_module
+          lines << "    signingConfig signingConfigs.#{signing_config_name}"
+        end
+        lines << "    proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'"
+        lines << "}"
+        lines << "// #{MARK_END}"
+        lines.join("\n")
+      end
+
+      def kts_build_type_entry(workflow_name:, workflow_build_type:, signing_config_name:, is_main_module:)
+        lines = []
+        lines << "// #{MARK_BEGIN}"
+        lines << "// workflowName=#{workflow_name.inspect}"
+        lines << "create(\"#{workflow_build_type}\") {"
+        lines << "    isMinifyEnabled = false"
+        if is_main_module
+          lines << "    signingConfig = signingConfigs.getByName(\"#{signing_config_name}\")"
+        end
+        lines << "    proguardFiles("
+        lines << "        getDefaultProguardFile(\"proguard-android-optimize.txt\"),"
+        lines << "        \"proguard-rules.pro\""
+        lines << "    )"
+        lines << "}"
+        lines << "// #{MARK_END}"
+        lines.join("\n")
+      end
+
+      def inject_into_existing_android_block(content, signing_entry:, build_type_entry:, workflow_build_type:, signing_config_name:, dsl:)
+        android_open = content.index(/\bandroid\s*\{/)
+        unless android_open
+          android_body = []
+          if signing_entry
+            android_body << "signingConfigs {\n#{indent_lines(signing_entry, '    ')}\n}"
+          end
+          android_body << "buildTypes {\n#{indent_lines(build_type_entry, '    ')}\n}"
+          return content.rstrip + "\n\nandroid {\n" + android_body.join("\n") + "\n}\n"
+        end
+
+        android_line_start = content.rindex("\n", android_open) || 0
+        android_line_start = 0 if android_line_start == 0
+        android_indent = content[android_line_start..android_open].match(/^\s*/).to_s
+
+        block_start = content.index("{", android_open)
+        block_end = find_matching_brace(content, block_start)
+        raise "无法定位 android { } 结束位置" unless block_end
+
+        android_block = content[block_start..block_end]
+        android_inner = content[(block_start + 1)...block_end]
+
+        updated_inner = android_inner.dup
+
+        # 仅在 android 块前半段查找，避免误匹配 dependencies/注释等处的 "buildTypes"/"signingConfigs" 子串
+        build_types_anchor_before = updated_inner.index(/\n\s*buildTypes\s*\{/)
+        signing_search_space = build_types_anchor_before ? updated_inner[0...build_types_anchor_before] : updated_inner
+
+        if signing_entry
+          updated_inner = inject_into_child_block(
+            updated_inner,
+            block_name: "signingConfigs",
+            entry: signing_entry,
+            entry_present: false,
+            base_indent: android_indent,
+            search_space: signing_search_space,
+            brace_end_exclusive: build_types_anchor_before
+          )
+        end
+
+        # 签名块注入会改变 updated_inner 长度，必须重新定位 buildTypes / compileOptions
+        build_types_anchor = updated_inner.index(/\n\s*buildTypes\s*\{/)
+        compile_options_anchor = if build_types_anchor
+                                   updated_inner.index(/\n\s*compileOptions\s*\{/, build_types_anchor)
+                                 else
+                                   updated_inner.index(/\n\s*compileOptions\s*\{/)
+                                 end
+        build_types_search_space = compile_options_anchor ? updated_inner[0...compile_options_anchor] : updated_inner
+
+        updated_inner = inject_into_child_block(
+          updated_inner,
+          block_name: "buildTypes",
+          entry: build_type_entry,
+          entry_present: false,
+          base_indent: android_indent,
+          search_space: build_types_search_space,
+          brace_end_exclusive: compile_options_anchor
+        )
+
+        before_android = content[0..block_start]
+        after_android = content[block_end..]
+        before_android + updated_inner + after_android
+      end
+
+      def inject_into_child_block(android_inner, block_name:, entry:, entry_present:, base_indent:, search_space: nil, brace_end_exclusive: nil)
+        return android_inner if entry_present
+
+        space = search_space || android_inner
+        m = space.match(/\b#{Regexp.escape(block_name)}\s*\{/)
+        if m
+          open_idx = m.begin(0)
+          brace_idx = android_inner.index("{", open_idx)
+          close_idx = if brace_end_exclusive && brace_end_exclusive > brace_idx
+                        fragment = android_inner[brace_idx...brace_end_exclusive]
+                        rel = find_matching_brace(fragment, 0)
+                        rel ? (brace_idx + rel) : nil
+                      else
+                        scan = search_space || android_inner
+                        find_matching_brace(scan, brace_idx)
+                      end
+          return android_inner unless close_idx
+
+          line_start = android_inner.rindex("\n", open_idx) || 0
+          line_start = 0 if line_start == 0
+          block_indent = android_inner[line_start..open_idx].match(/^\s*/).to_s
+          entry_text = indent_lines(entry, block_indent + "    ")
+
+          before = android_inner[0...close_idx].rstrip
+          after = android_inner[close_idx..]
+          return before + "\n" + entry_text + "\n" + after
+        end
+
+        # child block 不存在：在 android 末尾创建一个
+        entry_text = indent_lines(entry, base_indent + "        ")
+        block = []
+        block << "\n" + (base_indent + "    ") + "#{block_name} {"
+        block << "\n" + entry_text
+        block << "\n" + (base_indent + "    ") + "}"
+        android_inner.rstrip + block.join + "\n"
+      end
+
+      # 注意：不要依赖“是否已存在同名条目”来跳过注入。
+      # 很多项目可能已经有同名 buildType/signingConfig（但签名读取方式不符合 workflow 要求），
+      # 这里通过再次配置同名条目来覆盖关键字段（Gradle DSL 会合并同名对象），并以文件级 marker 保证幂等。
+
+      def find_matching_brace(str, open_brace_index)
+        depth = 0
+        i = open_brace_index
+        while i < str.length
+          ch = str.getbyte(i)
+          if ch == 123 # {
+            depth += 1
+          elsif ch == 125 # }
+            depth -= 1
+            return i if depth == 0
+          end
+          i += 1
+        end
+        nil
+      end
+
+      def indent_lines(text, base_indent)
+        text.lines.map do |line|
+          if line.strip.empty?
+            line
+          else
+            base_indent + line
+          end
+        end.join
+      end
+
+      def backup_file!(context, abs_path)
+        project_dir = context[:project_dir]
+        return unless abs_path && File.file?(abs_path)
+        return unless abs_path.start_with?(project_dir.to_s)
+
+        rel = abs_path.delete_prefix("#{project_dir}/")
+
+        # 已备份过就跳过
+        return if context[:backups].any? { |b| b["path"] == rel && b["type"] == "file" }
+
+        backup_path = File.join(context[:backup_dir], rel)
+        FileUtils.mkdir_p(File.dirname(backup_path))
+        self.class.bin_copy(abs_path, backup_path)
+
+        context[:backups] << {
+          "type" => "file",
+          "path" => rel,
+          "backup_path" => backup_path.delete_prefix("#{project_dir}/"),
+          "sha256_before" => Digest::SHA256.file(abs_path).hexdigest,
+        }
+      end
+
+      def self.bin_copy(src, dst)
+        File.open(src, "rb") do |r|
+          File.open(dst, "wb") do |w|
+            IO.copy_stream(r, w)
+          end
+        end
+      end
+    end
+  end
+end
+