pindo 5.13.1 → 5.13.2

data/lib/pindo/options/core/option_configuration.rb

@@ -0,0 +1,206 @@
+require 'pindo/options/core/option_item'
+
+module Pindo
+  module Options
+    # 参数配置管理器（简化版）
+    # 负责管理参数值的生命周期：默认值、类型转换、验证
+    class OptionConfiguration
+
+      # 初始化
+      # @param available_options [Array<OptionItem>] 可用参数列表
+      # @param raw_values [Hash] 原始参数值
+      # @param command_instance [Object, nil] 命令实例（用于 value_block）
+      def initialize(available_options, raw_values = {}, command_instance: nil)
+        @available_options = available_options
+        @raw_values = raw_values
+        @command_instance = command_instance
+        @values = {}
+        @options_map = build_options_map
+
+        # 执行参数处理流程
+        process_all_options
+      end
+
+      # 获取参数值（支持符号和字符串）
+      # @param key [Symbol, String] 参数键名
+      # @return [Object] 参数值
+      def [](key)
+        key = normalize_key(key)
+        @values[key]
+      end
+
+      # 设置参数值
+      # @param key [Symbol, String] 参数键名
+      # @param value [Object] 参数值
+      def []=(key, value)
+        key = normalize_key(key)
+        option_item = @options_map[key]
+
+        if option_item
+          @values[key] = option_item.auto_convert_value(value)
+          option_item.valid?(@values[key])
+        else
+          @values[key] = value
+        end
+      end
+
+      # 获取所有参数值
+      # @return [Hash] 所有参数值
+      def to_hash
+        @values.dup
+      end
+
+      # 检查参数是否存在
+      # @param key [Symbol, String] 参数键名
+      # @return [Boolean]
+      def key?(key)
+        @values.key?(normalize_key(key))
+      end
+
+      # 获取所有参数键
+      # @return [Array<Symbol>]
+      def keys
+        @values.keys
+      end
+
+      # 遍历所有参数
+      # @yield [key, value] 参数键值对
+      def each(&block)
+        @values.each(&block)
+      end
+
+      private
+
+      # 构建参数映射表（支持别名）
+      # @return [Hash{Symbol => OptionItem}]
+      def build_options_map
+        map = {}
+        @available_options.each do |item|
+          # 主键
+          map[item.key] = item
+          # 别名
+          item.aliases.each do |alias_name|
+            map[alias_name] = item
+          end
+        end
+        map
+      end
+
+      # 参数处理主流程
+      def process_all_options
+        # 1. 应用默认值
+        apply_defaults
+
+        # 2. 应用原始值（命令行参数和环境变量）
+        apply_raw_values
+
+        # 3. 应用 value_block（交互式获取值）
+        apply_value_blocks
+
+        # 4. 类型转换
+        convert_types
+
+        # 5. 验证必填参数
+        validate_required
+
+        # 6. 自定义验证
+        validate_custom
+      end
+
+      # 应用默认值
+      def apply_defaults
+        @available_options.each do |item|
+          @values[item.key] = item.default_value if item.default_value
+        end
+      end
+
+      # 应用原始值（映射别名到主键）
+      def apply_raw_values
+        @raw_values.each do |key, value|
+          normalized_key = normalize_key(key)
+          option_item = @options_map[normalized_key]
+
+          if option_item
+            # 使用主键存储
+            @values[option_item.key] = value
+          else
+            # 未知参数，仍然保存（可能是其他用途）
+            @values[normalized_key] = value
+          end
+        end
+      end
+
+      # 应用 value_block（交互式获取值）
+      # 优先级：命令行参数 > 缓存（已在 raw_values） > value_block > 默认值
+      def apply_value_blocks
+        @available_options.each do |item|
+          # 只有当参数没有值时，才调用 value_block
+          next if @values.key?(item.key) && !@values[item.key].nil?
+          next unless item.value_block
+
+          begin
+            # 调用 value_block 获取值
+            # 如果 value_block 接受参数，则传入命令实例
+            value = if item.value_block.arity > 0
+                      item.value_block.call(@command_instance)
+                    else
+                      item.value_block.call
+                    end
+            @values[item.key] = value unless value.nil?
+          rescue StandardError => e
+            # value_block 执行失败，记录错误但不中断流程
+            puts "[OptionConfiguration] value_block 执行失败 (#{item.key}): #{e.message}"
+          end
+        end
+      end
+
+      # 类型转换
+      def convert_types
+        @available_options.each do |item|
+          next unless @values.key?(item.key)
+
+          begin
+            converted_value = item.auto_convert_value(@values[item.key])
+            @values[item.key] = converted_value
+          rescue StandardError => e
+            raise ArgumentError, "参数 '#{item.key}' 类型转换失败: #{e.message}"
+          end
+        end
+      end
+
+      # 验证必填参数
+      def validate_required
+        @available_options.each do |item|
+          next if item.optional
+
+          # 检查参数是否存在且不为 nil
+          unless @values.key?(item.key) && !@values[item.key].nil?
+            raise ArgumentError, "参数 '#{item.key}' 是必填的"
+          end
+        end
+      end
+
+      # 自定义验证（verify_block）
+      def validate_custom
+        @available_options.each do |item|
+          next unless item.verify_block
+          next unless @values.key?(item.key)
+
+          value = @values[item.key]
+          begin
+            item.verify_block.call(value)
+          rescue StandardError => e
+            raise ArgumentError, "参数 '#{item.key}' 验证失败: #{e.message}"
+          end
+        end
+      end
+
+      # 标准化键名（转为 Symbol）
+      # @param key [Symbol, String] 键名
+      # @return [Symbol]
+      def normalize_key(key)
+        key.to_sym
+      end
+    end
+  end
+end

data/lib/pindo/options/core/option_initializer.rb

@@ -0,0 +1,51 @@
+require 'pindo/options/core/option_value_parser'
+require 'pindo/options/core/option_configuration'
+require 'pindo/options/core/global_options_state'
+
+module Pindo
+  module Options
+    # 参数初始化器
+    # 提供统一的参数初始化流程：解析 → 配置 → 注册
+    module OptionInitializer
+      # 初始化命令参数
+      #
+      # @param command_instance [Object] 命令实例
+      # @param argv [CLAide::ARGV] 命令行参数
+      # @param option_items [Array<OptionItem>] 参数项列表
+      # @param command_name [String] 命令名称
+      # @param directory [String, nil] 工作目录（默认：当前目录）
+      # @param enable_cache [Boolean] 是否启用缓存（默认：false）
+      # @return [OptionConfiguration] 参数配置对象
+      def self.initialize(command_instance, argv, option_items, command_name, directory: nil, enable_cache: false)
+        # 1. 解析参数值（从命令行和环境变量）
+        raw_values = OptionValueParser.parse(argv, option_items)
+
+        # 2. 如果启用缓存，合并缓存值到 raw_values
+        if enable_cache
+          state = GlobalOptionsState.instance
+          state.prepare_cache(command_name, directory || Dir.pwd)
+          cached_values = state.load_cached_values
+
+          # 缓存值优先级：命令行参数 > 缓存 > 默认值
+          # 只有在命令行未提供的参数才使用缓存
+          cached_values.each do |key, value|
+            raw_values[key] = value unless raw_values.key?(key)
+          end
+        end
+
+        # 3. 创建参数配置（自动处理验证等，传入命令实例用于 value_block）
+        options = OptionConfiguration.new(option_items, raw_values, command_instance: command_instance)
+
+        # 4. 设置全局状态
+        GlobalOptionsState.instance.set_command(
+          command_name,
+          options,
+          directory: directory || Dir.pwd,
+          enable_cache: enable_cache
+        )
+
+        options
+      end
+    end
+  end
+end

data/lib/pindo/options/core/option_item.rb

@@ -0,0 +1,144 @@
+module Pindo
+  module Options
+    # OptionItem 类定义单个参数的所有属性和行为（简化版）
+    class OptionItem
+
+      # 核心属性
+      attr_accessor :key              # Symbol: 参数键名
+      attr_accessor :description      # String: 参数描述
+      attr_accessor :type             # Class: 数据类型 (String/Integer/Boolean)
+      attr_accessor :env_name         # String: 环境变量名
+      attr_accessor :aliases          # Array<Symbol>: 参数别名
+      attr_accessor :default_value    # Any: 默认值
+      attr_accessor :optional         # Boolean: 是否可选（默认为 true）
+      attr_accessor :verify_block     # Proc: 自定义验证逻辑
+      attr_accessor :value_block      # Proc: 获取参数值的 block（交互式输入）
+      attr_accessor :example          # String: 使用示例
+
+      # Boolean 类型标记
+      Boolean = :boolean
+
+      # 初始化方法
+      # @param key [Symbol] 参数键名（必填）
+      # @param options [Hash] 其他配置选项
+      def initialize(key:, **options)
+        raise ArgumentError, "key must be a Symbol" unless key.is_a?(Symbol)
+
+        @key = key
+        @description = options[:description] || options[:desc] || ""
+        @type = options[:type] || String
+        @env_name = options[:env_name]
+        @aliases = options[:aliases] || []
+        @default_value = options[:default_value] || options[:default]
+        @optional = options.fetch(:optional, true)
+        @verify_block = options[:verify_block]
+        @value_block = options[:value_block]
+        @example = options[:example]
+
+        validate_type!
+      end
+
+      # 判断是否是 Boolean 类型
+      def boolean?
+        @type == Boolean || @type == :boolean
+      end
+
+      # 从环境变量读取值
+      # @return [String, nil] 环境变量的值
+      def fetch_env_value
+        return nil unless @env_name
+        value = ENV[@env_name]
+        value if value && !value.empty?
+      end
+
+      # 自动类型转换
+      # @param value [Any] 原始值
+      # @return [Any] 转换后的值
+      def auto_convert_value(value)
+        return nil if value.nil?
+
+        case @type
+        when Boolean, :boolean
+          # Boolean 转换
+          if value.is_a?(String)
+            return true if value.downcase == 'true' || value == '1'
+            return false if value.downcase == 'false' || value == '0'
+          end
+          !!value
+        when Integer
+          value.to_i
+        else
+          # String 或其他类型
+          value.to_s
+        end
+      rescue StandardError => e
+        raise ArgumentError, "参数 '#{@key}' 类型转换失败: #{e.message}"
+      end
+
+      # 验证参数值
+      # @param value [Any] 要验证的值
+      # @return [Boolean] 验证是否通过
+      def valid?(value)
+        return true unless @verify_block
+
+        begin
+          @verify_block.call(value)
+          true
+        rescue StandardError => e
+          raise ArgumentError, "参数 '#{@key}' 验证失败: #{e.message}"
+        end
+      end
+
+      # 转换为 CLAide 选项格式（用于 --help 输出）
+      # @return [Array] CLAide 选项格式 [option_string, description]
+      def to_claide_option
+        option_string = build_option_string
+        description_text = build_description_text
+
+        [option_string, description_text]
+      end
+
+      private
+
+      # 验证类型是否合法
+      def validate_type!
+        valid_types = [String, Integer, Boolean, :boolean]
+        unless valid_types.include?(@type)
+          raise ArgumentError, "Invalid type: #{@type}. Valid types: #{valid_types.join(', ')}"
+        end
+      end
+
+      # 构建选项字符串（--key[=VALUE] 格式）
+      def build_option_string
+        # 只显示主选项，不显示别名（避免输出过长导致换行）
+        if boolean?
+          "--#{@key}"
+        else
+          type_hint = type_to_hint
+          "--#{@key}=#{type_hint}"
+        end
+      end
+
+      # 构建描述文本（描述 + 环境变量）
+      def build_description_text
+        if @env_name
+          "#{@description} (环境变量: #{@env_name})"
+        else
+          @description
+        end
+      end
+
+      # 类型转换为提示字符串
+      def type_to_hint
+        case @type
+        when String
+          'VALUE'
+        when Integer
+          'NUMBER'
+        else
+          'VALUE'
+        end
+      end
+    end
+  end
+end

data/lib/pindo/options/core/option_value_parser.rb

@@ -0,0 +1,54 @@
+require 'pindo/options/core/option_item'
+
+module Pindo
+  module Options
+    # 参数值解析器
+    # 负责从 CLAide::ARGV 和环境变量中提取参数的原始值
+    class OptionValueParser
+
+      # 解析参数值
+      # @param argv [CLAide::ARGV] CLAide 的参数对象
+      # @param option_items [Array<OptionItem>] 参数定义列表
+      # @return [Hash] 原始参数值 Hash { key: raw_value }
+      def self.parse(argv, option_items)
+        values = {}
+
+        option_items.each do |item|
+          # 1. 从 argv 提取值（优先级最高）
+          raw_value = extract_from_argv(argv, item)
+
+          # 2. 如果 argv 没有，尝试从环境变量读取
+          if raw_value.nil?
+            raw_value = item.fetch_env_value
+          end
+
+          # 3. 存储值（可能是 nil）
+          values[item.key] = raw_value unless raw_value.nil?
+
+          # 4. 处理别名（别名指向同一个值）
+          item.aliases.each do |alias_name|
+            values[alias_name] = raw_value unless raw_value.nil?
+          end
+        end
+
+        values
+      end
+
+      private
+
+      # 从 argv 提取参数值
+      # @param argv [CLAide::ARGV] CLAide 参数对象
+      # @param item [OptionItem] 参数定义
+      # @return [Object, nil] 提取的值
+      def self.extract_from_argv(argv, item)
+        if item.boolean?
+          # Boolean 类型：使用 flag?
+          argv.flag?(item.key.to_s, nil)
+        else
+          # 其他类型：使用 option
+          argv.option(item.key.to_s, nil)
+        end
+      end
+    end
+  end
+end

data/lib/pindo/options/groups/build_options.rb

@@ -0,0 +1,60 @@
+require 'pindo/options/core/option_item'
+require 'pindo/options/groups/option_group'
+
+module Pindo
+  module Options
+    # 通用构建参数组
+    # 定义跨平台（iOS/Android）的构建参数
+    module BuildOptions
+      extend OptionGroup
+
+      def self.all_options
+
+        @all_options ||= {
+          
+          bundleid: OptionItem.new(
+            key: :bundleid,
+            description: '指定打包的 Bundle ID',
+            type: String,
+            env_name: 'PINDO_BUNDLE_ID',
+            aliases: [:bundle_id, :package_name, :bundle_name],
+            optional: true,
+            verify_block: proc do |value|
+              # 支持 iOS 格式 (com.example.app) 和 Android 格式 (com.example.app)
+              # iOS 可以包含大写字母、连字符和通配符（*）
+              unless value =~ /^[a-zA-Z0-9\-\.\*]+$/
+                raise "Bundle ID/Package Name 格式错误: #{value}，应该类似 com.example.app 或 com.example.*"
+              end
+            end,
+            example: 'pindo ios autobuild --bundleid=com.example.app'
+          ),
+
+          build_type: OptionItem.new(
+            key: :build_type,
+            description: '指定构建类型（dev/adhoc/release）',
+            type: String,
+            env_name: 'PINDO_BUILD_TYPE',
+            default_value: 'dev',
+            optional: true,
+            verify_block: proc do |value|
+              valid_types = ['dev', 'adhoc', 'release']
+              unless valid_types.include?(value.to_s.downcase)
+                raise "构建类型错误: #{value}，必须是 dev、adhoc 或 release 之一"
+              end
+            end,
+            example: 'pindo ios autobuild --build_type=release'
+          ),
+
+          scheme: OptionItem.new(
+            key: :scheme,
+            description: '指定构建 Scheme',
+            type: String,
+            env_name: 'PINDO_SCHEME',
+            optional: true,
+            example: 'pindo ios autobuild --scheme=MyAppScheme'
+          )
+        }
+      end
+    end
+  end
+end

data/lib/pindo/options/groups/jps_options.rb

@@ -0,0 +1,70 @@
+require 'pindo/options/core/option_item'
+require 'pindo/options/groups/option_group'
+
+module Pindo
+  module Options
+    # JPS 平台参数组
+    # 定义 JPS 测试平台特有的参数
+    module JPSOptions
+      extend OptionGroup
+
+      def self.all_options
+        @all_options ||= {
+          proj: OptionItem.new(
+            key: :proj,
+            description: '指定上传到测试平台的项目名称',
+            type: String,
+            env_name: 'PINDO_PROJECT_NAME',
+            optional: true,
+            example: 'pindo ios autobuild --proj="My App"'
+          ),
+
+          upload: OptionItem.new(
+            key: :upload,
+            description: '编译后上传到测试平台（上传成功后自动发送给自己）',
+            type: OptionItem::Boolean,
+            env_name: 'PINDO_UPLOAD',
+            optional: true,
+            example: 'pindo ios autobuild --upload'
+          ),
+
+          send: OptionItem.new(
+            key: :send,
+            description: '发送通知到测试群组（同时也会发送给自己）',
+            type: OptionItem::Boolean,
+            env_name: 'PINDO_SEND',
+            optional: true,
+            example: 'pindo ios autobuild --send'
+          ),
+          desc: OptionItem.new(
+            key: :desc,
+            description: '指定上传的备注信息',
+            type: String,
+            env_name: 'PINDO_UPLOAD_DESC',
+            aliases: [:description],
+            optional: true,
+            example: 'pindo jps upload --desc="版本说明"'
+          ),
+
+          resign: OptionItem.new(
+            key: :resign,
+            description: '上传后是否重签名',
+            type: OptionItem::Boolean,
+            env_name: 'PINDO_RESIGN',
+            optional: true,
+            example: 'pindo jps upload --resign'
+          ),
+
+          certid: OptionItem.new(
+            key: :certid,
+            description: '设置重签名的Bundle ID',
+            type: String,
+            env_name: 'PINDO_CERT_ID',
+            optional: true,
+            example: 'pindo jps resign --certid=com.test.bundleid'
+          )
+        }
+      end
+    end
+  end
+end

data/lib/pindo/options/groups/option_group.rb

@@ -0,0 +1,73 @@
+require 'pindo/options/core/option_item'
+
+module Pindo
+  module Options
+    # 参数组工具模块
+    # 提供参数组的定义、筛选和合并功能
+    # 合并了原 OptionGroupBase 和 OptionRegistry 的功能
+    module OptionGroup
+
+      # ==================== 实例方法（供参数组使用） ====================
+
+      # 选择指定的参数
+      # @param keys [Array<Symbol>] 要选择的参数键名
+      # @return [Array<OptionItem>] 选中的参数列表
+      def select(*keys)
+        keys = keys.flatten.map(&:to_sym)
+        all_options_hash = all_options
+
+        selected = keys.map do |key|
+          option = all_options_hash[key]
+          if option.nil?
+            raise ArgumentError, "参数组 #{self.name} 中不存在参数: #{key}"
+          end
+          option
+        end
+
+        selected
+      end
+
+      # 排除指定的参数，返回剩余参数
+      # @param keys [Array<Symbol>] 要排除的参数键名
+      # @return [Array<OptionItem>] 剩余的参数列表
+      def except(*keys)
+        keys = keys.flatten.map(&:to_sym)
+        all_options_hash = all_options
+
+        all_options_hash.reject { |k, v| keys.include?(k) }.values
+      end
+
+      # 获取所有参数（返回数组）
+      # @return [Array<OptionItem>] 所有参数列表
+      def all
+        all_options.values
+      end
+
+      # 子类必须实现此方法
+      # @return [Hash{Symbol => OptionItem}] 所有参数的 Hash
+      def all_options
+        raise NotImplementedError, "子类必须实现 all_options 方法"
+      end
+
+      # ==================== 类方法（合并参数组） ====================
+
+      # 合并多个参数组
+      # @param option_groups [Array<Array<OptionItem>>] 参数组列表
+      # @return [Array<OptionItem>] 合并后的参数列表（去重）
+      def self.merge(*option_groups)
+        merged_map = {}
+
+        option_groups.flatten.compact.each do |item|
+          unless item.is_a?(OptionItem)
+            raise ArgumentError, "Expected OptionItem, got #{item.class}"
+          end
+
+          # 如果键已存在，后面的覆盖前面的
+          merged_map[item.key] = item
+        end
+
+        merged_map.values
+      end
+    end
+  end
+end