ctx_cli 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 367e5a47fb0f653f5ef833f8efee765606717ae2c97aa6025f6116032ba1edbf
-  data.tar.gz: b87ac1112712391f7fd1eac7fc66fd4e93e6af6dc5ceb3d08508872f0c55345c
+  metadata.gz: 6757c9c4e28fdbf88436ead17a364fc8dcb7fc2d4fda107654fd278c0d5229c3
+  data.tar.gz: a727b09657a6b79ab821c2a2f8f899c1d09b248faf659ff288306514c07d0a68
 SHA512:
-  metadata.gz: 948f143970bc4d5a0af50470e6c35a1bdfe98c0eb63d6d3efa18531c7578f6a00ea3da4da2545091433416b119e715f69bd739c745ca763f08acf2432a0a51d1
-  data.tar.gz: a3f788a3d3bd2e946c484594747c01912d28455a3b771f5acc7d8208cacca5d838103003fa67383bc3139afceb84e1f1555cd86981d22f355d239dffd8a8e691
+  metadata.gz: d0d80afb9a473f4bceff0dc6f0cfbb7b78d2987b8aed673c4b230e1c05086bdbc9f2fa950ee1f54dc95cbfe487f803178ecace433d40ac758257e7b0633c726e
+  data.tar.gz: ee8af08341391087d93c40df85d61b486346fcfef8c92ee8b675704749e4ad3e4dcededc8126edadb7d52fc1d82190725fa1e1774c6604cd36124c6c9f938c6e

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.2.1 (2026-10-23)
+
+- Use English command help, prompts and collection/review diagnostics.
+- Allow compatible dotenv versions without an upper version bound.
+
+## 0.2.0 (2026-10-23)
+
+- Rename Initialization to Initializer and Application to Router; remove the old constants and require paths in the 0.2.0 candidate.
+- Preserve caller argument strings during routing and publish configuration applicability only after every layer succeeds.
+- Remove quadratic field-source scans for leaf configuration values.
+- Bound offline review source counts and cumulative bytes, and treat batch directory names literally.
+- Redact adapter argument and dependency errors at the collection boundary.
+- Share offline review preflight/publication ordering and redacted diagnostics without depending on Runner or domain schemas.
+- Bound input bytes and configuration nesting/nodes before deserialization; merge owned layers without recursive copies.
+- Synchronize newly created parent directories before publishing configuration templates.
+
 ## 0.1.0 (2026-10-22)
 
 - Extract reusable configuration discovery, private initialization, command dispatch, option groups, terminal interaction, input/output and collection entrypoint orchestration.

data/README.md

@@ -6,12 +6,13 @@
 
 | 对象 | 职责 |
 | --- | --- |
-| `Application` | 惰性子命令分发、全局帮助/版本、返回退出码 |
+| `Router` | 惰性子命令分发、全局帮助/版本、返回退出码 |
 | `Command` / `Options` | 每次独立的参数快照、信息分支、公共 OptionParser 分组 |
 | `Configuration` | 多层文件发现、隔离环境、来源路径、纯数据快照 |
-| `Initialization` | 私有文件排他创建、同步、保留已有配置 |
+| `Initializer` | 私有文件排他创建、同步、保留已有配置 |
 | `Terminal` | 真实终端检查、问答、隐藏密码、完整 token 确认 |
 | `Input` / `Output` | 文件/stdin、显式 JSON、仅含错误类型的诊断 |
+| `Review` | 离线来源读取、全量预检后发布、安全诊断与退出码映射 |
 | `Collection` | 配置、预览、全批预检、调度交付及退出码映射 |
 
 Ruby >= 3.4。`require "ctx_cli"` 或按能力加载 `ctx_cli/configuration` 等路径；加载不读取用户文件、不修改 ENV、不建立网络连接。核心不依赖 ctx_parser、ctx_runner 或 net-connector。代码和工程规范参照 ctx_parser，保留 Ruby 3.4 是为了兼容现有 backup 宿主。
@@ -56,7 +57,7 @@ files.sources     # 路径与字段来源，不包含环境值
 
 宿主把各层公共环境值转换成领域字段后，通过 `Configuration.merge(defaults, dotenv_values, yaml, process_values, cli)` 实现 CLI > 进程环境 > YAML > .env > 默认值。数组整层替换，false/nil 保留。相对路径按来源目录解释；支持 `path_literals:`（如 `system`）和 URI。`load` 重复调用不重新读文件。
 
-`Initialization#create(path:, contents:)` 返回 `:created` 或 `:exists`。文件先写完并同步，再排他发布并同步目录；既有普通文件保留，符号链接/目录拒绝。发布后同步失败仍抛错，不能当作成功；不把凭据自动写入模板。例子见 [examples/configuration.rb](examples/configuration.rb)。
+`Initializer#create(path:, contents:)` 返回 `:created` 或 `:exists`。文件先写完并同步，再排他发布并同步目录；既有普通文件保留，符号链接/目录拒绝。发布后同步失败仍抛错，不能当作成功；不把凭据自动写入模板。例子见 [examples/configuration.rb](examples/configuration.rb)。
 
 ## 采集协议
 
@@ -72,9 +73,22 @@ Options 协作者沿用现有入口协议：`informational?`、`validate_interac
 bundle install
 bundle exec rake
 bundle exec rake build
-ruby script/verify_package.rb pkg/ctx_cli-0.1.0.gem
+ruby script/verify_package.rb pkg/ctx_cli-0.2.1.gem
 ```
 
 默认任务包括 RSpec、RuboCop 和离线示例。安装验证在独立 GEM_HOME/GEM_PATH 下运行普通与最小 Bundler 应用，检查实际加载来源。CI 参照 ctx_parser 的固定 action 提交和候选制品校验；发布需另行明确授权。
 
 消费仓库可用 `CTX_CLI_PATH=../ctx_cli bundle exec rake` 显式联调；普通入口须先安装候选包。不隐式探测相邻目录。baseline 只在 Gemfile 中为现有 coverage 脚本引入开发依赖，没有新增 baseline 命令或核心依赖。
+
+Input reads default to a 16 MiB byte budget (`CtxCli::Input.read(max_bytes:)`). Configuration data is limited to 128 nesting levels and 100,000 nodes; oversized input raises `ArgumentError` before recursive deserialization.
+
+## 离线 review 入口
+
+`CtxCli::Review` 接收 `command:`（`CtxCli::Command`）、`directory:`（批次内证据目录名）和 `adapter:`。入口先处理帮助，再按文件名顺序读取 JSON，通过 `Input` 限制单个文件大小，最后依次调用：
+
+- `adapter.prepare(sources, options)`：验证全部领域记录、身份及策略并返回上下文，不创建输出。每条来源为 `[path, body, document]`；领域适配器可在本次入口拥有的来源数组中附加建议。
+- `adapter.publish(sources, options, batch:, context:)`：创建报告并返回完成提示。发布及持久性状态仍由领域模块和 Runner 管理。
+
+失败只输出异常类型，返回 2；中断返回 130；诊断流失败不覆盖原始退出码。帮助不加载证据或调用适配器。此类不读取凭据、连接设备或判断业务健康。默认单文件 16 MiB、批次原始正文总计 64 MiB、文件数 10000；宿主可通过 `max_bytes:`、`max_total_bytes:`、`max_files:` 调整。JSON 默认嵌套限制保持开启；上述限制不是进程 RSS 的精确上限。
+
+`Collection` 对普通参数/依赖异常只显示类型；宿主需要公开操作提示时使用 `CtxCli::Collection::Error`，其正文必须由宿主构造，不得直接包装外部异常正文、凭据或设备回显。该类型继承 ArgumentError，既有库调用方仍可按参数错误捕获。

data/docs/migration.md

@@ -11,3 +11,10 @@
 ctx_runner 继续拥有采集/报告/执行的业务状态，net-connector Inventory 继续拥有筛选；ctx_cli 不反向加载二者。普通 Config 旧入口保留为宿主政策适配，无第二份配置发现实现。
 
 ctx_cli 初始版本为 0.1.0。首次发布依赖顺序先 ctx_cli，再 net-connector 与 CLI 消费模块；ctx_runner 的依赖链仍按其原有约定。提交、远程创建和发布按用户明确授权的范围执行。
+
+## 0.2.0 接口命名
+
+- `CtxCli::Initialization` / `ctx_cli/initialization` 改为 `CtxCli::Initializer` / `ctx_cli/initializer`，仅负责模板安全发布。
+- `CtxCli::Application` / `ctx_cli/application` 改为 `CtxCli::Router` / `ctx_cli/router`，仅负责全局信息和子命令分发。
+
+旧常量和 require 路径不保留别名。宿主需同步修改引用，并将 ctx_cli 依赖更新为 `~> 0.2.0`。`create`、`existing?`、`run` 的结果约定不变；初始化参数询问和厂商语义不迁入这两个对象。0.2.0 当前为本地候选，尚未发布。

data/examples/configuration.rb

@@ -6,7 +6,7 @@ require "tmpdir"
 # 自定义宿主命名空间；示例只操作临时目录，不读取真实用户配置。
 Dir.mktmpdir do |root|
   path = File.join(root, "audit.yml")
-  publisher = CtxCli::Initialization.new
+  publisher = CtxCli::Initializer.new
   abort "Initialization failed" unless publisher.create(path: path, contents: "directory: reports\nparallel: 2\n") == :created
   files = CtxCli::Configuration.new(name: "audit", env: {}, directories: [ root ], path_fields: [ "directory" ]).load
   effective = CtxCli::Configuration.merge({ "parallel" => 1 }, files.data, { "parallel" => 4 })

data/lib/ctx_cli/collection.rb

@@ -2,10 +2,14 @@
 
 require "optparse"
 require_relative "output"
+require_relative "configuration"
 
 module CtxCli
   # 终端采集入口的固定顺序；领域适配器拥有清单、预检、调度及采集策略。
   class Collection
+    # 宿主明确构造的公开操作提示，不得包装凭据或外部异常正文。
+    class Error < ArgumentError; end
+
     def initialize(adapter:, options:, progress:, batch:, label:, report_error:, failure_code:,
                    out: $stdout, error: $stderr, input: $stdin)
       @adapter, @options_factory, @progress_factory, @batch_class = adapter, options, progress, batch
@@ -29,13 +33,13 @@ module CtxCli
       return 0 if @options.missing?(input: @input, error: @error)
       @options.load
       @progress = @progress_factory.call(@options)
-      @progress.notice("配置：#{@options.config}")
+      @progress.notice("Configuration: #{@options.config}")
       return output(@options.public_values.merge("sources" => @options.sources)) if @options.flags[:show_config]
       @devices, @inventory_total = @adapter.inventory(@options, progress: @progress)
       devices = @devices
       return output(devices) if @options.flags[:inventory_only]
       if devices.empty?
-        @progress.notice("没有匹配设备，未建立连接")
+        @progress.notice("No devices matched; no connections opened")
         @output.json({ status: :no_devices, total: 0 }, pretty: false) if @options.flags[:json]
         return 1
       end
@@ -43,7 +47,7 @@ module CtxCli
       @store = @adapter.report(@options)
       @batch = @batch_class.new(report: @store, progress: @progress, requested: devices)
       outcome = @batch.run(present: ->(summary) { @output.json(summary) if @options.flags[:json] }) do
-        @progress.plan(devices: devices, total: @inventory_total, parallel: @options.values.fetch("parallel"), label: "#{@label} 只读采集")
+        @progress.plan(devices: devices, total: @inventory_total, parallel: @options.values.fetch("parallel"), label: "#{@label} read-only collection")
         @progress.with_updates do
           @adapter.execute(devices, @options) do |device|
             @batch.collect(device) { @adapter.collect(device, @options, context: context, progress: @progress) }
@@ -53,16 +57,19 @@ module CtxCli
       end
       completion(outcome)
     rescue Interrupt
-      diagnostic "采集已取消，已保存的设备报告保留；未保存结果见报告状态"
+      diagnostic "Collection cancelled; saved device reports retained; check report status for unsaved results"
       130
     rescue SystemCallError, IOError => error
-      diagnostic "#{@label} 参数或报告错误：#{report_diagnostic(error)}"
+      diagnostic "#{@label} argument or report error: #{report_diagnostic(error)}"
+      2
+    rescue Error, Configuration::Error => error
+      diagnostic "#{@label} argument, dependency or report error: #{error.message}; use --help for options"
       2
     rescue OptionParser::ParseError, ArgumentError, LoadError => error
-      diagnostic "#{@label} 参数、依赖或报告错误：#{error.message}；使用 --help 查看参数"
+      diagnostic "#{@label} argument, dependency or report error: #{error.class.name}; use --help for options"
       2
     rescue StandardError => error
-      diagnostic "#{@label} 清单或执行失败：#{@failure_code.call(error)}（#{error.class.name}）"
+      diagnostic "#{@label} inventory or execution failed: #{@failure_code.call(error)} (#{error.class.name})"
       2
     end
 
@@ -75,18 +82,18 @@ module CtxCli
     # Runner 决定批次结论；CLI 仅呈现安全诊断并映射退出码。
     def completion(outcome)
       if outcome.finalization_error
-        diagnostic "#{@label} 摘要报告错误：#{outcome.finalization_error}"
+        diagnostic "#{@label} summary report error: #{outcome.finalization_error}"
       end
       if outcome.recovery_failed
-        diagnostic "摘要恢复未确认；请依据退出码及报告目录检查，不能将旧摘要视为本次成功。"
+        diagnostic "Summary recovery is unconfirmed; check the exit code and report directory. An earlier summary does not confirm this run succeeded."
       end
       if outcome.status == :interrupted
-        diagnostic "采集已取消，已保存的设备报告保留；未保存结果见报告状态"
+        diagnostic "Collection cancelled; saved device reports retained; check report status for unsaved results"
       elsif (failure = outcome.failure)
         if failure[:kind] == :report
-          diagnostic "#{@label} 参数或报告错误：#{failure[:detail]}"
+          diagnostic "#{@label} argument or report error: #{failure[:detail]}"
         else
-          diagnostic "#{@label} 清单或执行失败：#{failure[:error_type]}；已采集结果见批次报告"
+          diagnostic "#{@label} inventory or execution failed: #{failure[:error_type]}; see the batch report for collected results"
         end
       end
       { complete: 0, incomplete: 1, failed: 2, interrupted: 130 }.fetch(outcome.status)
@@ -108,7 +115,7 @@ module CtxCli
         @output.json(value)
       else
         value.each { |device| @out.puts "#{device.fetch('host')}\t#{device.fetch('name')}\t#{device['model']}" }
-        @out.puts "设备：#{value.size} 台；未建立设备连接"
+        @out.puts "Devices: #{value.size}; no device connections opened"
       end
       value.is_a?(Array) && value.empty? ? 1 : 0
     end

data/lib/ctx_cli/command.rb

@@ -18,7 +18,7 @@ module CtxCli
       @parser.banner = @banner
       @configure&.call(@parser, @values)
       rest = @parser.parse(argv.dup)
-      raise ArgumentError, "不接受位置参数" unless rest.empty?
+      raise ArgumentError, "Positional arguments are not accepted" unless rest.empty?
       @values
     end
 

data/lib/ctx_cli/configuration.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
 require "yaml"
+require_relative "input"
 
 module CtxCli
   # 宿主配置发现；加载文件不读取配置或建立设备连接。
   class Configuration
+    # 仅用于本类构造的公开配置诊断，不携带文件正文。
+    class Error < ArgumentError; end
+
+    MAX_DEPTH = 128
+    MAX_NODES = 100_000
     attr_reader :data, :specific, :process_environment, :file_environment, :environment,
                 :config_files, :environment_files, :sources
 
@@ -74,7 +80,7 @@ module CtxCli
       specific = {}
       fields = {}
       loaded = []
-      @applicable = false
+      applicable = false
       paths = @directories.flat_map { |directory| [ File.join(directory, "#{@namespace}.yml"), File.join(directory, "#{@name}.yml") ] }
       paths = final_candidates(paths, @selected_config)
       paths.each do |path|
@@ -82,13 +88,13 @@ module CtxCli
 
         document = read_yaml(path)
         if @namespace != @name && File.basename(path) == "#{@namespace}.yml"
-          common, native, applicable = shared_sections(document, path)
+          common, native, native_present = shared_sections(document, path)
           merged = merge_layer(merged, common, path, fields)
-          @applicable ||= applicable
+          applicable ||= native_present
         else
           native = document
           validate_string_keys!(native, path)
-          @applicable = true
+          applicable = true
         end
         merged = merge_layer(merged, native, path, fields)
         specific = self.class.merge(specific, resolve_paths(native, path))
@@ -98,6 +104,7 @@ module CtxCli
       @specific = self.class.freeze_tree(specific)
       @config_files = self.class.freeze_tree(loaded)
       update_sources(fields)
+      @applicable = applicable
       @loaded = true
       self
     end
@@ -132,27 +139,41 @@ module CtxCli
     alias_method :to_s, :inspect
     def pretty_print(printer) = printer.text(inspect)
 
-    # 递归合并但不修改来源；数组、false、nil 按值替换。
+    # 每层只复制一次，再合并拥有的映射；数组、false、nil 按值替换。
     def self.merge(*hashes)
       hashes.reduce({}) do |result, hash|
-        hash.each do |key, value|
-          result[copy(key)] = result[key].is_a?(Hash) && value.is_a?(Hash) ? merge(result[key], value) : copy(value)
+        raise ArgumentError, "configuration layers must be mappings" unless hash.is_a?(Hash)
+        pending = [ [ result, copy(hash) ] ]
+        until pending.empty?
+          target, source = pending.pop
+          source.each do |key, value|
+            if target[key].is_a?(Hash) && value.is_a?(Hash)
+              pending << [ target[key], value ]
+            else
+              target[key] = value
+            end
+          end
         end
         result
       end
     end
 
     # 只复制普通数据；循环或不透明对象不能进入快照并冻结调用方资源。
-    def self.copy(value, active = {}.compare_by_identity)
+    def self.copy(value) = copy_value(value, {}.compare_by_identity, 0, [ MAX_NODES ])
+
+    def self.copy_value(value, active, depth, budget)
+      raise ArgumentError, "configuration nesting exceeds budget" if depth > MAX_DEPTH
+      budget[0] -= 1
+      raise ArgumentError, "configuration node budget exceeded" if budget[0].negative?
       case value
       when Hash, Array
         raise ArgumentError, "cyclic configuration value" if active.key?(value)
         active[value] = true
         begin
           if value.is_a?(Hash)
-            value.to_h { |key, entry| [ copy(key, active), copy(entry, active) ] }
+            value.to_h { |key, entry| [ copy_value(key, active, depth + 1, budget), copy_value(entry, active, depth + 1, budget) ] }
           else
-            value.map { |entry| copy(entry, active) }
+            value.map { |entry| copy_value(entry, active, depth + 1, budget) }
           end
         ensure
           active.delete(value)
@@ -162,6 +183,7 @@ module CtxCli
       else raise ArgumentError, "configuration accepts plain data only"
       end
     end
+    private_class_method :copy_value
 
     def self.freeze_tree(value)
       case value
@@ -196,7 +218,7 @@ module CtxCli
 
     def readable_file?(path, explicit:, allow_missing:)
       unless File.exist?(path)
-        raise ArgumentError, "configuration file does not exist: #{path}" if explicit && !allow_missing
+        raise Error, "configuration file does not exist: #{path}" if explicit && !allow_missing
 
         return false
       end
@@ -206,7 +228,7 @@ module CtxCli
     end
 
     def read_yaml(path)
-      contents = File.read(path)
+      contents = Input.read(path: path)
       validate_yaml_structure!(contents, path)
       document = YAML.safe_load(contents, permitted_classes: [], permitted_symbols: [], aliases: false)
       document = {} if document.nil?
@@ -223,7 +245,14 @@ module CtxCli
       stream = YAML.parse_stream(contents)
       raise ArgumentError, "configuration must contain a single YAML document: #{path}" if stream.children.size > 1
 
-      stream.each do |node|
+      pending = [ [ stream, 0 ] ]
+      remaining = MAX_NODES
+      until pending.empty?
+        node, depth = pending.pop
+        raise ArgumentError, "configuration nesting exceeds budget" if depth > MAX_DEPTH
+        remaining -= 1
+        raise ArgumentError, "configuration node budget exceeded" if remaining.negative?
+        node.children&.reverse_each { |child| pending << [ child, depth + 1 ] }
         next unless node.is_a?(Psych::Nodes::Mapping)
 
         keys = {}
@@ -322,7 +351,11 @@ module CtxCli
           fields.delete(name)
           record_fields(value, source, fields, name, previous: before)
         else
-          fields.delete_if { |field, _| field == name || field.start_with?("#{name}.") }
+          # 只有旧映射被整体替换才需要删除后代；新增/覆盖叶子直接赋值。
+          if before.is_a?(Hash) && !before.empty?
+            descendant_prefix = "#{name}."
+            fields.delete_if { |field, _| field.start_with?(descendant_prefix) }
+          end
           fields[name] = source
         end
       end
@@ -365,7 +398,7 @@ module CtxCli
         end
         private :expand_newlines
       end
-      contents = File.read(path)
+      contents = Input.read(path: path)
       remainder = contents.gsub(Dotenv::Parser::LINE, "")
       unless remainder.lines("\n").all? { |line| line.strip.empty? || line.lstrip.start_with?("#") }
         raise ArgumentError, "invalid environment syntax"

data/lib/ctx_cli/{initialization.rb → initializer.rb}

@@ -5,7 +5,7 @@ require "tempfile"
 
 module CtxCli
   # 只发布已经过宿主校验的模板，不收集凭据、不覆盖已有目录项。
-  class Initialization
+  class Initializer
     def initialize(prefix: ".ctx-cli-init-")
       @prefix = prefix
     end
@@ -23,7 +23,7 @@ module CtxCli
     def create(path:, contents:)
       raise ArgumentError, "config path must be a nonempty String" unless path.is_a?(String) && !path.empty?
       return :exists if existing?(path)
-      FileUtils.mkdir_p(File.dirname(File.expand_path(path)), mode: 0o700)
+      prepare_directory(File.dirname(File.expand_path(path)))
       directory = File.realpath(File.dirname(File.expand_path(path)))
       destination = File.join(directory, File.basename(path))
       file = parent = primary = nil
@@ -53,6 +53,19 @@ module CtxCli
 
     private
 
+    # 先确认新目录在各父级的名字已同步，再发布其中的配置文件。
+    def prepare_directory(path)
+      missing, parent = [], path
+      until File.directory?(parent)
+        missing << parent
+        parent = File.dirname(parent)
+      end
+      FileUtils.mkdir_p(path, mode: 0o700)
+      missing.reverse_each do |created|
+        File.open(File.realpath(File.dirname(created)), File::RDONLY | File::NOFOLLOW) { |directory| directory.fsync }
+      end
+    end
+
     # 全部句柄都尝试关闭，保留原始故障；不把清理失败变为成功。
     def close_files(file, parent, primary)
       Thread.handle_interrupt(Exception => :never) do

data/lib/ctx_cli/input.rb

@@ -3,8 +3,14 @@
 module CtxCli
   # 只关闭自行打开的文件，stdin 的读取和关闭权仍由宿主控制。
   module Input
-    def self.read(path: nil, input: $stdin)
-      path ? File.read(path) : input.read
+    MAX_BYTES = 16 * 1024 * 1024
+
+    def self.read(path: nil, input: $stdin, max_bytes: MAX_BYTES)
+      raise ArgumentError, "input byte budget must be positive" unless max_bytes.is_a?(Integer) && max_bytes.positive?
+      return File.open(path, "r") { |file| read(input: file, max_bytes: max_bytes) } if path
+      contents = input.read(max_bytes + 1) || +""
+      raise ArgumentError, "input exceeds byte budget" if contents.bytesize > max_bytes
+      contents.force_encoding(input.external_encoding || Encoding.default_external)
     end
   end
 end

data/lib/ctx_cli/options.rb

@@ -4,34 +4,34 @@ module CtxCli
   # 普通参数分组只登记语法；不加载配置、不执行操作、不拥有领域校验。
   module Options
     def self.initialization(parser, values)
-      parser.on("--init", "创建缺失配置和环境模板后退出；已有文件不覆盖") { values[:init] = true }
-      parser.on("--interactive", "缺少配置时询问是否创建；要求真实终端") { values[:interactive] = true }
-      parser.on("--non-interactive", "禁用问答；创建文件须同时指定 --init") { values[:interactive] = false }
+      parser.on("--init", "Create missing configuration and environment templates, then exit; preserve existing files") { values[:init] = true }
+      parser.on("--interactive", "Prompt to create missing configuration; requires an interactive terminal") { values[:interactive] = true }
+      parser.on("--non-interactive", "Disable prompts; specify --init to create files") { values[:interactive] = false }
     end
 
     def self.output(parser, values, quiet: :quiet)
-      parser.on("--json", "stdout 输出 JSON；默认显示可读摘要") { values[:json] = true }
-      parser.on("--quiet", "--no-progress", "关闭 stderr 进度，可配合 --json") { values[quiet] = true }
-      parser.on("--verbose", "显示逐台结果及安全命令事件") { values[:verbose] = true }
+      parser.on("--json", "Write JSON to stdout; defaults to a readable summary") { values[:json] = true }
+      parser.on("--quiet", "--no-progress", "Disable progress on stderr; can be combined with --json") { values[quiet] = true }
+      parser.on("--verbose", "Show per-device results and safe command events") { values[:verbose] = true }
     end
 
     def self.information(parser, values)
-      parser.on("-h", "--help", "查看选项帮助") { values[:help] = true }
-      parser.on("--help-all", "查看全部选项、路径与环境约定") { values[:help_all] = true }
-      parser.on("--examples", "查看常用命令范例，不执行任务") { values[:examples] = true }
+      parser.on("-h", "--help", "Show option help") { values[:help] = true }
+      parser.on("--help-all", "Show all options, paths and environment conventions") { values[:help_all] = true }
+      parser.on("--examples", "Show common command examples without executing tasks") { values[:examples] = true }
     end
 
     # 值转换留在宿主边界，允许不同入口沿用原有存储格式。
-    def self.configuration(parser, parallel_help: "设备并发数", &store)
-      parser.on("--config FILE", "显式 YAML 最后叠加于自动发现的配置") { |value| store.call(:config, value) }
-      parser.on("--env-file FILE", "显式环境文件最后叠加；进程环境优先") { |value| store.call(:env_file, value) }
+    def self.configuration(parser, parallel_help: "Device concurrency", &store)
+      parser.on("--config FILE", "Overlay explicit YAML after automatically discovered configuration") { |value| store.call(:config, value) }
+      parser.on("--env-file FILE", "Load explicit environment files last; process environment takes precedence") { |value| store.call(:env_file, value) }
       parser.on("-p", "--parallel N", Integer, parallel_help) { |value| store.call(:parallel, value) }
-      parser.on("--directory DIR", "按设备保存报告的目录") { |value| store.call(:directory, value) }
+      parser.on("--directory DIR", "Directory for per-device reports") { |value| store.call(:directory, value) }
     end
 
     def self.list(value)
       values = value.split(",", -1).map(&:strip)
-      raise ArgumentError, "列表不能有空项" if values.any?(&:empty?)
+      raise ArgumentError, "Lists must not contain empty entries" if values.any?(&:empty?)
       values
     end
   end

data/lib/ctx_cli/output.rb

@@ -14,7 +14,7 @@ module CtxCli
 
     # 最后的错误流失败不能覆盖原本的失败或取消状态。
     def diagnostic(message, exception: nil)
-      @error.puts(exception ? "#{message}（#{exception.class.name}）" : message)
+      @error.puts(exception ? "#{message} (#{exception.class.name})" : message)
     rescue StandardError
       nil
     end

data/lib/ctx_cli/review.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "input"
+require_relative "output"
+
+module CtxCli
+  # 离线入口先读取并预检全部来源，再允许领域适配器创建报告。
+  class Review
+    MAX_FILES = 10_000
+    MAX_TOTAL_BYTES = 64 * 1024 * 1024
+
+    def initialize(command:, directory:, adapter:, out: $stdout, error: $stderr,
+                   max_files: MAX_FILES, max_bytes: Input::MAX_BYTES, max_total_bytes: MAX_TOTAL_BYTES)
+      unless [ max_files, max_bytes, max_total_bytes ].all? { |limit| limit.is_a?(Integer) && limit.positive? }
+        raise ArgumentError, "review budgets must be positive integers"
+      end
+      @max_files, @max_bytes, @max_total_bytes = max_files, max_bytes, max_total_bytes
+      @command, @directory, @adapter = command, directory, adapter
+      @output = Output.new(out: out, error: error)
+    end
+
+    def run(argv)
+      options = @command.parse(argv)
+      return 0 if @command.informational?
+      raise ArgumentError, "A batch directory is required" unless options[:batch]
+      batch = File.expand_path(options[:batch])
+      paths = source_paths(File.join(batch, @directory))
+      raise ArgumentError, "No device reports found" if paths.empty?
+      remaining = @max_total_bytes
+      sources = paths.map do |path|
+        raise ArgumentError, "review byte budget exceeded" unless remaining.positive?
+        body = Input.read(path: path, max_bytes: [ @max_bytes, remaining ].min)
+        remaining -= body.bytesize
+        [ path, body, JSON.parse(body) ]
+      end
+      context = @adapter.prepare(sources, options)
+      @output.text(@adapter.publish(sources, options, batch: batch, context: context))
+      0
+    rescue Interrupt
+      @output.diagnostic("Review cancelled; existing reports retained; no device changes executed.")
+      130
+    rescue StandardError => error
+      @output.diagnostic("Review failed (#{error.class.name}); check the input structure, directory permissions and --help; no device changes executed.")
+      2
+    end
+
+    def inspect = "#<#{self.class.name}>"
+    alias_method :to_s, :inspect
+    def pretty_print(printer) = printer.text(inspect)
+
+    private
+
+    # 目录名按字面处理；边枚举边限制数量，避免先创建无限制的路径数组。
+    def source_paths(directory)
+      paths = []
+      Dir.each_child(directory) do |name|
+        next if name.start_with?(".") || !name.end_with?(".json")
+        raise ArgumentError, "review file budget exceeded" if paths.size >= @max_files
+        paths << File.join(directory, name)
+      end
+      paths.sort
+    end
+  end
+end

data/lib/ctx_cli/{application.rb → router.rb}

@@ -2,7 +2,7 @@
 
 module CtxCli
   # 命令工厂按需执行；帮助和版本不加载领域实现或配置。
-  class Application
+  class Router
     def initialize(name:, version:, usage:, commands:, out: $stdout, error: $stderr)
       @name, @version, @usage, @commands = name, version, usage, commands.dup.freeze
       @out, @error = out, error
@@ -10,7 +10,7 @@ module CtxCli
 
     # 退出行为归调用方；保留 argv 并只返回命令退出码。
     def run(argv)
-      arguments = argv.dup
+      arguments = argv.map { |argument| String.new(argument) }
       command = arguments.shift
       if [ nil, "--help", "--help-all", "-h" ].include?(command) && arguments.empty?
         @out.puts @usage
@@ -21,7 +21,7 @@ module CtxCli
         return 0
       end
       return @commands.fetch(command).call(arguments) if @commands.key?(command)
-      @error.puts "未知命令或多余参数；使用 #{@name} --help 查看用法"
+      @error.puts "Unknown command or extra arguments; use #{@name} --help for usage"
       2
     end
   end

data/lib/ctx_cli/terminal.rb

@@ -10,7 +10,7 @@ module CtxCli
     def self.tty?(*streams) = streams.all? { |stream| stream.respond_to?(:tty?) && stream.tty? }
     def tty?(*others) = self.class.tty?(@input, @out, *others)
 
-    def require_tty!(*others, message: "必须使用真实交互终端")
+    def require_tty!(*others, message: "An interactive terminal is required")
       raise ArgumentError, message unless tty?(*others)
     end
 
@@ -26,13 +26,13 @@ module CtxCli
     end
 
     def password(label:)
-      raise ArgumentError, "密码提示需要交互终端；自动化任务可使用环境变量或 --stdin-credentials" unless self.class.tty?(@input)
+      raise ArgumentError, "Password prompts require an interactive terminal; use environment variables or --stdin-credentials for automation" unless self.class.tty?(@input)
       require "io/console"
-      @out.print "#{label}："
+      @out.print "#{label}: "
       @out.flush
       value = @input.noecho { |terminal| terminal.gets("\n") }&.chomp("\n")
       @out.puts
-      raise ArgumentError, "密码不能为空" if value.nil? || value.empty?
+      raise ArgumentError, "Password must not be empty" if value.nil? || value.empty?
       value
     end
   end

data/lib/ctx_cli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CtxCli
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/ctx_cli.rb

@@ -2,11 +2,12 @@
 
 require_relative "ctx_cli/version"
 require_relative "ctx_cli/configuration"
-require_relative "ctx_cli/initialization"
-require_relative "ctx_cli/application"
+require_relative "ctx_cli/initializer"
+require_relative "ctx_cli/router"
 require_relative "ctx_cli/command"
 require_relative "ctx_cli/options"
 require_relative "ctx_cli/terminal"
 require_relative "ctx_cli/input"
 require_relative "ctx_cli/output"
 require_relative "ctx_cli/collection"
+require_relative "ctx_cli/review"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_cli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Gatework contributors
@@ -15,20 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: fileutils
   requirement: !ruby/object:Gem::Requirement
@@ -126,14 +120,15 @@ files:
 - examples/configuration.rb
 - examples/offline.rb
 - lib/ctx_cli.rb
-- lib/ctx_cli/application.rb
 - lib/ctx_cli/collection.rb
 - lib/ctx_cli/command.rb
 - lib/ctx_cli/configuration.rb
-- lib/ctx_cli/initialization.rb
+- lib/ctx_cli/initializer.rb
 - lib/ctx_cli/input.rb
 - lib/ctx_cli/options.rb
 - lib/ctx_cli/output.rb
+- lib/ctx_cli/review.rb
+- lib/ctx_cli/router.rb
 - lib/ctx_cli/terminal.rb
 - lib/ctx_cli/version.rb
 homepage: https://github.com/gatework/ctx_cli