pod-binary-pack 1.0.0

data/lib/core/git_helper.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+require 'shellwords'
+require_relative 'push'
+
+module Build
+  class GitHelper
+
+    # @return [Boolean] 返回是否有变更
+    def GitHelper.status(path)
+      current = Dir.pwd
+      Dir.chdir(path)
+      Build.log.debug("获取代码状态(#{File.basename(path)}): git status")
+      res = %x(git status)
+      Dir.chdir(current)
+      if res.include? 'nothing to commit, working tree clean'
+        Build.log.debug("当前无变更")
+        return false
+      end
+      true
+    end
+
+    def GitHelper.add_stag(path)
+      command = "git add ."
+      GitHelper.execute(path, command, true)
+    end
+
+    # 仅暂存指定文件(避免把构建产物/临时文件一并提交)
+    def GitHelper.add_files(path, files)
+      list = Array(files).map { |f| Shellwords.escape(f) }.join(' ')
+      GitHelper.execute(path, "git add -- #{list}", true)
+    end
+
+    # 指定文件相对HEAD是否有改动(含修改/新增/删除)
+    # @return [Boolean]
+    def GitHelper.file_changed?(path, file)
+      res = GitHelper.capture(path, "git status --porcelain -- #{Shellwords.escape(file)}")
+      !res.strip.empty?
+    end
+
+    def GitHelper.commit(path, commit_msg = nil)
+      commit_msg = commit_msg ? commit_msg : "none message"
+      # commit_msg含上游committer/commit信息(任意字符)，必须转义避免引号断裂命令或注入
+      command = "git commit -m #{Shellwords.escape(commit_msg)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.pull(path)
+      command = "git pull"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.push(path, branch)
+      command = "git push origin #{Shellwords.escape(branch)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.push_f(path, branch)
+      command = "git push origin -f #{Shellwords.escape(branch)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.reset_hard(path)
+      command = "git reset --hard"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.fetch(path)
+      command = "git fetch"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.checkout(path, checkout_branch)
+      command = "git checkout #{Shellwords.escape(checkout_branch)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.tag_delete_local(path, tag)
+      command = "git tag -d #{Shellwords.escape(tag)}"
+      GitHelper.execute(path, command, false)
+    end
+
+    def GitHelper.tag_delete_origin(path, tag)
+      command = "git push origin :refs/tags/#{Shellwords.escape(tag)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.tag_local(path, tag)
+      command = "git tag #{Shellwords.escape(tag)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.tag_origin(path, tag)
+      command = "git push origin #{Shellwords.escape(tag)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    def GitHelper.push_tags(path)
+      command = "git push origin --tags"
+      GitHelper.execute(path, command, true)
+    end
+
+    # 远端是否存在指定分支
+    # @return [Boolean]
+    def GitHelper.remote_branch?(path, branch)
+      res = GitHelper.capture(path, "git ls-remote --heads origin #{Shellwords.escape(branch)}")
+      !res.strip.empty?
+    end
+
+    # 解析某个引用的commit sha，解析失败返回nil
+    # @return [String, nil]
+    def GitHelper.revision(path, ref)
+      res = GitHelper.capture(path, "git rev-parse --verify #{Shellwords.escape(ref)}^{commit} 2>/dev/null")
+      res = res.strip
+      res.empty? ? nil : res
+    end
+
+    # 判断ancestor是否为descendant的祖先(用于fast-forward可行性判断)
+    # @return [Boolean]
+    def GitHelper.ancestor?(path, ancestor, descendant)
+      GitHelper.run_bool(path, "git merge-base --is-ancestor #{Shellwords.escape(ancestor)} #{Shellwords.escape(descendant)}")
+    end
+
+    # 基于远端分支创建/重置本地分支并切换: git checkout -B branch origin/branch
+    def GitHelper.checkout_tracking(path, branch)
+      command = "git checkout -B #{Shellwords.escape(branch)} origin/#{Shellwords.escape(branch)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    # fast-forward合并到指定引用，不能ff时命令失败
+    def GitHelper.merge_ff_only(path, ref)
+      command = "git merge --ff-only #{Shellwords.escape(ref)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    # 把当前HEAD推送为远端指定分支名(用于远端目标分支不存在时创建)
+    def GitHelper.push_head_as(path, remote_branch)
+      command = "git push origin HEAD:#{Shellwords.escape(remote_branch)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    # ===== http归档git化专用(http归档组件在fork阶段就地建成全新git仓库) =====
+
+    # 初始化全新git仓库并写入本地提交者配置，不依赖机器全局git配置；
+    # 不指定初始分支名(兼容低版本git无init -b)，推送时用 HEAD:master 显式对齐远端分支名
+    def GitHelper.init_repo(path)
+      GitHelper.execute(path, "git init", true)
+      GitHelper.execute(path, "git config user.name jenkins", true)
+      GitHelper.execute(path, "git config user.email jenkins@jenkins.com", true)
+    end
+
+    # 全新仓库添加origin远程地址
+    def GitHelper.remote_add(path, name, url)
+      command = "git remote add #{name} #{Shellwords.escape(url)}"
+      GitHelper.execute(path, command, true)
+    end
+
+    # 当前HEAD强推为远端master分支(全新git化仓库推送，不依赖本地分支名)
+    def GitHelper.push_head_master_f(path)
+      command = "git push origin -f HEAD:master"
+      GitHelper.execute(path, command, true)
+    end
+
+    # 强推指定tag(同名tag指向新commit时的覆盖推送)
+    def GitHelper.tag_origin_f(path, tag)
+      command = "git push origin -f #{tag}"
+      GitHelper.execute(path, command, true)
+    end
+
+    # 获取远端仓库全部tag名(ls-remote直查远端，不依赖本地克隆，剥离 ^{} 剥离引用)。
+    # 仓库不存在/不可达时返回nil，空仓库返回[]
+    # @return [Array<String>, nil]
+    def GitHelper.remote_tags(url)
+      res = %x(git ls-remote --tags #{Shellwords.escape(url)} 2>/dev/null)
+      return nil unless $?.success?
+
+      res.lines.map do |line|
+        ref = line.split("\t")[1].to_s.chomp
+        ref.sub(/\Arefs\/tags\//, '').sub(/\^\{\}\z/, '')
+      end.reject(&:empty?).uniq
+    end
+
+    private
+    # 执行命令并返回标准输出内容，不改变调用方目录
+    def GitHelper.capture(path, command)
+      current = Dir.pwd
+      Dir.chdir(path)
+      Build.log.debug("git命令(#{File.basename(path)}):#{command}")
+      res = %x(#{command})
+      Dir.chdir(current)
+      res
+    end
+
+    # 执行命令并返回布尔结果，不因失败退出进程
+    # @return [Boolean]
+    def GitHelper.run_bool(path, command)
+      current = Dir.pwd
+      Dir.chdir(path)
+      Build.log.debug("git命令(#{File.basename(path)}):#{command}")
+      ok = system(command)
+      Dir.chdir(current)
+      ok == true
+    end
+
+    private
+    def GitHelper.execute(path, command, can_raise)
+      current = Dir.pwd
+      Dir.chdir(path)
+
+      Build.log.debug("git命令(#{File.basename(path)}):#{command}")
+      res = system command
+
+      if can_raise and not res
+        pusher = Push.instance
+        error = "失败: #{command}"
+        pusher.push("❌ 失败", error)
+        Process.exit(-1)
+      end
+
+      Dir.chdir(current)
+    end
+  end
+end

data/lib/core/github_fork.rb

@@ -0,0 +1,425 @@
+# frozen_string_literal: true
+require_relative 'repo'
+require_relative 'config'
+require_relative 'hosting'
+require 'git'
+require 'json'
+require 'fileutils'
+require 'digest'
+require 'shellwords'
+require 'singleton'
+
+# https://rubydoc.info/gems/git/2.3.0/Git/Base
+
+module Build
+  class GithubFork
+    include Singleton
+
+    # @return [String] 仓库本机路径
+    attr_accessor :path
+
+    # @return [String] 组件名
+    attr_accessor :pod_name
+
+    # @return [String] fork前对应的github地址
+    attr_accessor :github_url
+
+    # @return [String] fork后对应的代码托管平台地址(Gitee/GitLab)
+    attr_accessor :source_repo_url
+
+    # @return [Git] 当前仓库 clone完毕后有值
+    attr_accessor :repo
+
+    # http归档信息(source.http组件)；git源组件为nil
+    # @return [Hash, nil] {url:, type:, sha256:, sha1:, flatten:, version:}
+    attr_accessor :archive
+
+    # 下载到本地的podspec.json路径(播种进归档目录时使用)
+    attr_accessor :podspec_json_path
+
+    # 是否强制覆盖(镜像仓同名tag指向新commit时允许覆盖推送)
+    attr_accessor :force_cover
+
+    def setup(path, pod_name, github_url, source_repo_url, archive: nil, podspec_json_path: nil, force_cover: false)
+      self.path = path
+      self.pod_name = pod_name
+      self.github_url = github_url
+      self.source_repo_url = source_repo_url
+      self.archive = archive
+      self.podspec_json_path = podspec_json_path
+      self.force_cover = force_cover == true
+    end
+
+    def fork_if_need(repo_cocoapods_source)
+      if archive
+        fork_http_archive(repo_cocoapods_source)
+      else
+        download_github
+        check_can_fork(repo_cocoapods_source)
+        create_if_need
+        upload_source
+      end
+    end
+
+    private
+
+    # ===== http归档组件流程：下载归档 → 解压 → 播种podspec → 建镜像仓 → 防呆校验 → 就地git化推送 =====
+    # 背景：sqlite3等组件的podspec source为{http: 官方归档}，没有上游git仓可克隆，
+    # 无法走常规fork流程。将归档内容git化成一个镜像仓(等价正常源码仓库)后，
+    # 发布podspec引用{git: 镜像仓, tag: 版本号}，下游全部复用现有机制
+    def fork_http_archive(repo_cocoapods_source)
+      download_archive
+      seed_podspec
+      create_if_need(archive[:url])
+      check_published_refs_on_mirror(repo_cocoapods_source)
+      gitify_and_upload
+    end
+
+    # 下载归档文件：原始地址优先，github.com归档自动追加代理镜像候选，失败切换下一个
+    def download_archive
+      Build.log.step("下载http归档(#{File.basename(self.path)})")
+      # 上次失败可能残留半成品目录/文件，先清理
+      FileUtils.rm_rf(self.path)
+      FileUtils.rm_rf(archive_tmp_file)
+      FileUtils.mkdir_p(self.path)
+
+      urls = build_archive_urls
+      downloaded = false
+      urls.each_with_index do |url, index|
+        begin
+          Build.log.info("下载归档(#{index + 1}/#{urls.size} #{url})...")
+          # -f: HTTP错误码直接失败(避免把错误页存成文件) -L: 跟随重定向 -sS: 静默但保留错误输出
+          command = "curl -fsSL --retry 2 --connect-timeout 15 --max-time 600 " \
+                    "-o #{Shellwords.escape(archive_tmp_file)} #{Shellwords.escape(url)}"
+          raise 'curl命令执行失败' unless system(command)
+          raise '归档文件未生成或为空' unless File.exist?(archive_tmp_file) && File.size(archive_tmp_file) > 0
+
+          downloaded = true
+          break
+        rescue => exception
+          Build.log.detail("归档下载失败：#{exception.message}，切换下一个下载源")
+          FileUtils.rm_f(archive_tmp_file)
+        end
+      end
+
+      unless downloaded
+        Build.log.error("所有归档下载源均失败，请检查网络后重试：#{archive[:url]}")
+        Process.exit(-1)
+      end
+
+      verify_archive_digest
+      extract_archive
+      FileUtils.rm_f(archive_tmp_file)
+      Build.log.detail("归档解压完毕(#{Dir.children(self.path).size}个顶层条目)")
+    end
+
+    # 归档文件临时存放路径(与解压目录同级，解压后删除)
+    def archive_tmp_file
+      "#{self.path}.archive"
+    end
+
+    # 归档下载候选地址：原始地址优先；github.com归档自动追加代理镜像
+    # @return [Array<String>]
+    def build_archive_urls
+      urls = [archive[:url]]
+      if archive[:url] =~ %r{\Ahttps?://(www\.)?github\.com/}
+        urls << "https://ghproxy.net/#{archive[:url]}"
+        urls << "https://gh-proxy.com/#{archive[:url]}"
+      end
+      urls.uniq
+    end
+
+    # 归档摘要校验：声明了sha256/sha1时与实际计算值比对，不一致直接终止；
+    # 实际sha256始终记录到GithubHelper(无论是否声明)，供发布podspec的build_metadata溯源
+    def verify_archive_digest
+      actual_sha256 = Digest::SHA256.file(archive_tmp_file).hexdigest
+      GithubHelper.instance.archive_sha_actual = actual_sha256
+
+      if archive[:sha256].to_s.strip.empty? && archive[:sha1].to_s.strip.empty?
+        Build.log.detail("归档未声明摘要，已计算sha256: #{actual_sha256}")
+        return
+      end
+
+      if !archive[:sha256].to_s.strip.empty?
+        if actual_sha256 != archive[:sha256].strip.downcase
+          fail_digest('sha256', archive[:sha256], actual_sha256)
+        end
+      elsif !archive[:sha1].to_s.strip.empty?
+        actual_sha1 = Digest::SHA1.file(archive_tmp_file).hexdigest
+        if actual_sha1 != archive[:sha1].strip.downcase
+          fail_digest('sha1', archive[:sha1], actual_sha1)
+        end
+      end
+      Build.log.detail("归档摘要校验通过: sha256=#{actual_sha256}")
+    end
+
+    def fail_digest(type, declared, actual)
+      Build.log.error("归档#{type}校验失败：声明#{declared}，实际#{actual}，归档内容可能被篡改或声明有误")
+      Process.exit(-1)
+    end
+
+    # 按归档类型解压到目标目录(保留归档原始顶层目录结构，flatten=true时上移)
+    def extract_archive
+      Build.log.detail("解压归档(#{archive[:type]})到#{File.basename(self.path)}")
+      escaped_file = Shellwords.escape(archive_tmp_file)
+      escaped_dir = Shellwords.escape(self.path)
+      command = case archive[:type]
+                when 'zip' then "unzip -q -o #{escaped_file} -d #{escaped_dir}"
+                when 'tar.gz', 'tgz' then "tar -xzf #{escaped_file} -C #{escaped_dir}"
+                when 'tar.bz2', 'tbz', 'tbz2' then "tar -xjf #{escaped_file} -C #{escaped_dir}"
+                when 'tar.xz', 'txz' then "tar -xJf #{escaped_file} -C #{escaped_dir}"
+                else
+                  Build.log.error("不支持的归档类型: #{archive[:type]}")
+                  Process.exit(-1)
+                end
+      unless system(command)
+        Build.log.error("归档解压失败: #{command}")
+        Process.exit(-1)
+      end
+
+      # 清理macOS压缩包自带的资源叉目录/文件，避免污染flatten判定与镜像仓内容
+      if archive[:type] == 'zip'
+        FileUtils.rm_rf(File.join(self.path, '__MACOSX'))
+        Dir.glob(File.join(self.path, '**', '.DS_Store'), File::FNM_DOTMATCH).each { |p| FileUtils.rm_f(p) }
+      end
+
+      flatten_archive_root if archive[:flatten]
+    end
+
+    # flatten语义：归档仅有一个顶层目录时，把其内容上移到根目录
+    # (与CocoaPods http下载flatten行为一致，便于source_files直接匹配根目录)
+    def flatten_archive_root
+      entries = Dir.children(self.path).reject { |e| e == '.DS_Store' }
+      return unless entries.size == 1 && File.directory?(File.join(self.path, entries.first))
+
+      top_dir = File.join(self.path, entries.first)
+      Dir.children(top_dir).each do |child|
+        FileUtils.mv(File.join(top_dir, child), File.join(self.path, child))
+      end
+      FileUtils.rmdir(top_dir)
+      Build.log.detail("flatten=true，已将归档顶层目录#{entries.first}内容上移到根目录")
+    end
+
+    # 播种podspec：把从Specs下载的podspec.json放入归档根目录。
+    # 归档内不携带podspec，git化后镜像仓自身携带才能让克隆侧定位到podspec
+    # (source_podspec_entry扫描与LocalDependencies的path集成均依赖它)
+    def seed_podspec
+      unless podspec_json_path && File.exist?(podspec_json_path)
+        Build.log.error("未找到已下载的podspec文件，无法播种到归档目录: #{podspec_json_path}")
+        Process.exit(-1)
+      end
+
+      dest = File.join(self.path, "#{self.pod_name}.podspec.json")
+      FileUtils.cp(podspec_json_path, dest)
+      Build.log.detail("已播种podspec: #{File.basename(dest)}")
+    end
+
+    # 防呆校验：已发布源码spec引用的版本tag必须仍存在于镜像仓远端。
+    # http归档组件每次构建都是全新单提交历史，无法像git fork那样用上游全量历史校验，
+    # 改为ls-remote直查镜像仓远端refs——可拦截"镜像仓被删除重建导致历史tag丢失"
+    # 后静默发布引用失效spec的问题(旧版本切源码时会拉不到代码)
+    def check_published_refs_on_mirror(repo_cocoapods_source)
+      versions = repo_cocoapods_source.pod_name_versions(self.pod_name)
+      return unless versions
+
+      tag_refs = versions.map { |version| published_source_ref(repo_cocoapods_source.path, version) }
+                         .compact
+                         .select { |ref_type, _| ref_type == 'tag' }
+                         .map { |_, ref_name| ref_name }
+                         .uniq
+      return if tag_refs.empty?
+
+      Build.log.step("校验已发布版本tag在镜像仓仍存在(#{self.source_repo_url})")
+      remote_tags = GitHelper.remote_tags(self.source_repo_url.ssh_to_http)
+      if remote_tags.nil?
+        Build.log.detail("镜像仓暂不可达或尚未创建，跳过已发布tag校验(后续推送若失败会直接报错)")
+        return
+      end
+
+      missing = tag_refs - remote_tags
+      if missing.any?
+        Build.log.error("镜像仓#{self.source_repo_url}缺失已发布版本引用的tag：#{missing.join('、')}，" \
+                        "镜像仓可能被删除重建，旧版本切源码将拉不到代码，请先恢复历史tag或使用强制覆盖后重新git化")
+        Process.exit(-1)
+      end
+      Build.log.detail("已发布版本tag校验通过，共#{tag_refs.size}个")
+    end
+
+    # 就地git化并推送镜像仓：
+    #   git init(本地提交者配置兜底) → 提交原始归档内容 → 打版本tag → 强推master → 推tag
+    # 只推送master与当前版本tag，禁用--mirror/--prune，保证不影响镜像仓里其它历史tag
+    def gitify_and_upload
+      Build.log.step("归档git化并推送镜像仓(#{File.basename(self.path)})")
+      tag = archive[:version]
+
+      GitHelper.init_repo(self.path)
+      GitHelper.add_stag(self.path)
+      digest = GithubHelper.instance.archive_sha_actual
+      commit_msg = "#{self.pod_name} #{tag} 官方归档导入(地址: #{archive[:url]} sha256: #{digest})"
+      GitHelper.commit(self.path, commit_msg)
+      GitHelper.tag_local(self.path, tag)
+      GitHelper.remote_add(self.path, 'origin', self.source_repo_url)
+      GitHelper.push_head_master_f(self.path)
+
+      # tag推送策略：归档内容固定，镜像仓已有同名tag时默认跳过；--force-cover时强制覆盖到新commit
+      existing_tags = GitHelper.remote_tags(self.source_repo_url.ssh_to_http) || []
+      if existing_tags.include?(tag)
+        if self.force_cover
+          GitHelper.tag_origin_f(self.path, tag)
+          Build.log.info("镜像仓tag#{tag}已存在，force_cover=true 已强制覆盖")
+        else
+          Build.log.info("镜像仓tag#{tag}已存在且归档内容固定，跳过tag推送")
+        end
+      else
+        GitHelper.tag_origin(self.path, tag)
+      end
+
+      Build.log.detail("归档git化推送完毕(master + tag #{tag})")
+    end
+
+    # ===== 以下为git源fork组件的原有流程 =====
+
+    def download_github
+      repo_path = Pathname(path)
+      Build.log.step("fork源码(#{File.basename(self.path)})")
+
+      # 克隆候选地址：优先原始地址直连，失败再依次切换镜像重试
+      clone_urls = build_clone_urls
+      cloned = false
+      clone_urls.each_with_index do |clone_url, index|
+        begin
+          Build.log.info("下载源码文件(#{index + 1}/#{clone_urls.size} #{clone_url})...")
+          # 上次克隆失败可能残留半成品目录，克隆前先清理，避免目录已存在导致再次克隆失败
+          FileUtils.rm_rf(repo_path)
+          # 单次克隆设置120秒超时，避免镜像不可达时长时间卡住打包流程
+          Git.clone(clone_url, repo_path, timeout: 120)
+          cloned = true
+          break
+        rescue => exception
+          Build.log.detail("源码下载失败：#{exception.message}，切换下一个下载源")
+        end
+      end
+
+      unless cloned
+        Build.log.error("所有源码下载源均克隆失败，请检查网络后重试：#{self.github_url}")
+        Process.exit(-1)
+      end
+      Build.log.detail("上游源码克隆完毕")
+
+      Build.log.detail("检出所有分支")
+      self.repo = Git.open(repo_path)
+      # git gem 5.x 新API：branch_list 同时返回本地和远程跟踪分支(BranchInfo)。
+      # 遍历每个分支并检出：远程跟踪分支需先在本地创建同名分支，
+      # 这样后续 push --all 才能把上游全部分支镜像到目标仓库
+      self.repo.branch_list.each do |branch_info|
+        # 跳过 origin/HEAD 这类指向默认分支的符号引用，它不是真实分支
+        next if branch_info.symref?
+
+        branch_name = branch_info.short_name
+        if branch_info.remote? && !self.repo.local_branch?(branch_name)
+          self.repo.branch_new(branch_name, branch_info.refname)
+        end
+        self.repo.checkout(branch_name)
+      end
+
+      self.repo.config_set('remote.origin.url', self.source_repo_url)
+    end
+
+    # 构造源码克隆候选地址：原始地址优先，其后依次为 kkgithub 域名替换、gh.llkk.cc 前缀代理
+    # @return [Array<String>]
+    def build_clone_urls
+      if self.github_url.start_with?("http")
+        http_url = self.github_url
+      else
+        # SSH 地址镜像不支持，先转成 https 形式再拼镜像
+        http_url = self.github_url.ssh_to_http.sub(/\Ahttp:/, "https:")
+        http_url = "#{http_url}.git" unless http_url.end_with?(".git")
+      end
+
+      [
+        self.github_url,
+        http_url.gsub("github.com", "kkgithub.com"),
+        "https://gh.llkk.cc/#{http_url}"
+      ].uniq
+    end
+
+    # fork前校验：源码spec仓里每个已发布版本的podspec，其source引用的tag/branch/commit
+    # 必须在上游仓库真实存在，避免镜像force推送后老版本引用失效。
+    # 注意：不能拿版本号(如1.1.0)直接与tag名比较——三方库上游tag普遍带v前缀(如v1.1.0)，
+    # 必须以已发布podspec里source声明的实际引用为准。
+    # 只校验源码spec仓：二进制spec的source指向二进制组件仓，与GitHub上游无关，不在此校验。
+    def check_can_fork(repo_cocoapods)
+      versions = repo_cocoapods.pod_name_versions(self.pod_name)
+      return unless versions
+
+      Build.log.step("校验已发布版本引用是否都存在于上游仓库(#{self.github_url})")
+      missing = []
+      versions.each do |version|
+        ref_type, ref_name = published_source_ref(repo_cocoapods.path, version)
+        if ref_type.nil?
+          Build.log.detail("版本#{version}未找到可校验的podspec source(tag/branch/commit)，跳过")
+          next
+        end
+
+        if ref_exist?(ref_name)
+          Build.log.detail("版本#{version} 引用 #{ref_type} #{ref_name}：上游存在")
+        else
+          missing << "#{version}(#{ref_type}:#{ref_name})"
+        end
+      end
+
+      if missing.length > 0
+        Build.log.error("fork失败，以下已发布版本引用的tag/分支/commit在上游仓库#{self.github_url}中不存在：#{missing.join('、')}，请手动处理后再打包。")
+        Process.exit(-1)
+      end
+      Build.log.detail("已发布版本引用校验通过，共#{versions.length}个版本")
+    end
+
+    # 读取源码spec仓中某已发布版本podspec.json声明的源码引用
+    # @return [Array(String, String), nil] [tag/branch/commit, 引用名]；无podspec或source非git引用时返回nil
+    def published_source_ref(spec_root, version)
+      json_path = File.join(spec_root, self.pod_name, version, "#{self.pod_name}.podspec.json")
+      unless File.exist?(json_path)
+        # 兼容非常规命名：版本目录下唯一的podspec.json
+        candidates = Dir.glob(File.join(spec_root, self.pod_name, version, '*.podspec.json'))
+        json_path = candidates.first if candidates.length == 1
+      end
+      return nil unless json_path && File.exist?(json_path)
+
+      source = JSON.parse(File.read(json_path))['source'] rescue nil
+      return nil unless source.is_a?(Hash)
+
+      if !source['tag'].to_s.empty?
+        ['tag', source['tag'].to_s]
+      elsif !source['branch'].to_s.empty?
+        ['branch', source['branch'].to_s]
+      elsif !source['commit'].to_s.empty?
+        ['commit', source['commit'].to_s]
+      end
+    end
+
+    # 校验某个git引用(tag名/分支名/commit号)在克隆下来的上游仓库中是否存在。
+    # 全量克隆包含上游所有历史，revparse 对tag/branch/commit均可解析；不存在时git gem抛FailedError
+    def ref_exist?(ref_name)
+      self.repo.revparse(ref_name)
+      true
+    rescue Git::FailedError
+      false
+    end
+
+    def create_if_need(description = self.github_url)
+      provider = Hosting.provider_for(self.source_repo_url)
+      # fork源码镜像仓不存在时自动创建为私有仓库(固定私有)
+      provider.create_project_if_need(self.pod_name, self.source_repo_url.ssh_to_http, description: description)
+    end
+
+    def upload_source
+      Build.log.detail("推送并覆盖所有分支和标签(#{self.source_repo_url})")
+      # git gem 5.x: push(remote, refspec, opts)，all/tags/force 在第三个参数
+      self.repo.push('origin', nil, {:all => true, :force => true})
+      self.repo.push('origin', nil, {:tags => true, :force => true})
+      Build.log.detail("分支和标签推送完毕")
+    end
+
+  end
+end