ctx_cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 367e5a47fb0f653f5ef833f8efee765606717ae2c97aa6025f6116032ba1edbf
+  data.tar.gz: b87ac1112712391f7fd1eac7fc66fd4e93e6af6dc5ceb3d08508872f0c55345c
+SHA512:
+  metadata.gz: 948f143970bc4d5a0af50470e6c35a1bdfe98c0eb63d6d3efa18531c7578f6a00ea3da4da2545091433416b119e715f69bd739c745ca763f08acf2432a0a51d1
+  data.tar.gz: a3f788a3d3bd2e946c484594747c01912d28455a3b771f5acc7d8208cacca5d838103003fa67383bc3139afceb84e1f1555cd86981d22f355d239dffd8a8e691

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 (2026-10-22)
+
+- Extract reusable configuration discovery, private initialization, command dispatch, option groups, terminal interaction, input/output and collection entrypoint orchestration.
+- Integrate existing VXLAN, Wireless and net-connector backup/topology entrypoints; keep baseline integration limited to the existing coverage script.
+- Preserve Ruby 3.4 compatibility and verify standalone package installation without application or device dependencies.

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Song Huang
+Copyright (c) 2026 Gatework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,80 @@
+# ctx_cli
+
+可组合的 Ruby 命令行基础库，用于减少网络自动化模块的入口样板代码。它处理配置、终端和入口流程，领域模块继续拥有厂商语法、业务校验、清单选择及设备能力。
+
+## 公共能力
+
+| 对象 | 职责 |
+| --- | --- |
+| `Application` | 惰性子命令分发、全局帮助/版本、返回退出码 |
+| `Command` / `Options` | 每次独立的参数快照、信息分支、公共 OptionParser 分组 |
+| `Configuration` | 多层文件发现、隔离环境、来源路径、纯数据快照 |
+| `Initialization` | 私有文件排他创建、同步、保留已有配置 |
+| `Terminal` | 真实终端检查、问答、隐藏密码、完整 token 确认 |
+| `Input` / `Output` | 文件/stdin、显式 JSON、仅含错误类型的诊断 |
+| `Collection` | 配置、预览、全批预检、调度交付及退出码映射 |
+
+Ruby >= 3.4。`require "ctx_cli"` 或按能力加载 `ctx_cli/configuration` 等路径；加载不读取用户文件、不修改 ENV、不建立网络连接。核心不依赖 ctx_parser、ctx_runner 或 net-connector。代码和工程规范参照 ctx_parser，保留 Ruby 3.4 是为了兼容现有 backup 宿主。
+
+## 少写入口代码
+
+```ruby
+require "ctx_cli"
+
+command = CtxCli::Command.new(banner: "audit [选项]", defaults: { complete: false }) do |parser, values|
+  parser.on("--file FILE") { |path| values[:file] = path }
+  parser.on("--complete") { values[:complete] = true }
+  CtxCli::Options.information(parser, values)
+end
+values = command.parse(ARGV)
+unless command.informational?(examples: "audit --file running.cfg --complete")
+  body = CtxCli::Input.read(path: values[:file])
+  # 调用自己的领域 API；完整采集与业务健康由领域分别判断。
+  CtxCli::Output.new.json({ bytes: body.bytesize, complete: values[:complete] })
+end
+```
+
+库方法不调用 exit。宿主自己决定参数错误、部分结果、取消对应的退出码。`Command#parse` 不接受位置参数，每次重建默认值和 OptionParser；配置块必须将本次值写入块参数，不缓存上次的值容器。特殊参数直接用 OptionParser，不要求继承或注册 DSL。
+
+`Options.configuration(parser) { |key, value| ... }` 登记 config/env_file/parallel/directory；`parallel_help:` 可说明宿主自己的并发范围、默认值与环境变量。`Options.initialization`、`output`、`information` 接收当前标记 Hash。值转换、公开字段允许列表、层级优先级和领域校验属于宿主。
+
+## 配置与初始化
+
+```ruby
+files = CtxCli::Configuration.new(
+  name: "audit", namespace: "network-tools", names: %w[audit backup],
+  common_keys: %w[ssh inventory], config_env: "AUDIT_CONFIG",
+  path_fields: %w[directory ssh.known_hosts], env_path_keys: %w[AUDIT_DIRECTORY]
+).load
+
+files.data        # 深冻结的 YAML 合并结果
+files.environment # .env 加原进程环境；不修改 ENV
+files.sources     # 路径与字段来源，不包含环境值
+```
+
+默认依次搜索 `/etc/<namespace>`、`/usr/local/etc/<namespace>`、`$XDG_CONFIG_HOME/<namespace>`（否则 `~/.config/<namespace>`）、入口目录和启动目录。每层读取 `<namespace>.yml` 与 `<name>.yml`，显式文件最后。共享文件按 `common` 和工具名称分区；name 与 namespace 相同时使用普通独立文件。`directories:` 可以完整替换搜索范围。
+
+宿主把各层公共环境值转换成领域字段后，通过 `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)。
+
+## 采集协议
+
+`Collection.new(adapter:, options:, progress:, batch:, label:, report_error:, failure_code:, out:, error:, input:)` 返回一个可运行入口。options/progress 为工厂 callable；batch 是实现 `new(report:, progress:, requested:)`、`collect(device) { snapshot }` 与 `run(present:) { operation }` 的协作者，当前使用 `CtxRunner::Batch`。Collection 不加载 Runner，也不重复实现报告或取消状态机。
+
+adapter 实现 `inventory(options, progress:) -> [targets, total]`、`prepare(targets, options) -> context`、`report(options)`、`execute(targets, options) { |target| ... }`、`collect(target, options, context:, progress:) -> snapshot`、`after_collect(report, options)`。execute 必须在返回前回收线程。预览在凭据和设备预检之前，所有预检在报告创建与连接之前。`run` 返回 0 完整、1 未完成/无目标、2 错误、130 取消。
+
+Options 协作者沿用现有入口协议：`informational?`、`validate_interaction!`、`load_environment`、`initialize_files`、`missing?`、`load`、`config`、`flags`、`values`、`sources`、`public_values`。厂商命令、凭据映射、AP 租约、Fabric 检查、backup 成功策略保留在消费模块。详见 [迁移边界](docs/migration.md)。
+
+## 开发与验证
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake build
+ruby script/verify_package.rb pkg/ctx_cli-0.1.0.gem
+```
+
+默认任务包括 RSpec、RuboCop 和离线示例。安装验证在独立 GEM_HOME/GEM_PATH 下运行普通与最小 Bundler 应用，检查实际加载来源。CI 参照 ctx_parser 的固定 action 提交和候选制品校验；发布需另行明确授权。
+
+消费仓库可用 `CTX_CLI_PATH=../ctx_cli bundle exec rake` 显式联调；普通入口须先安装候选包。不隐式探测相邻目录。baseline 只在 Gemfile 中为现有 coverage 脚本引入开发依赖，没有新增 baseline 命令或核心依赖。

data/docs/migration.md

@@ -0,0 +1,13 @@
+# 消费模块接入边界
+
+| 消费者 | 移交给 ctx_cli | 保留职责 |
+| --- | --- | --- |
+| net-connector Config | YAML/.env 发现、来源路径、数据快照 | net-connector.yml 分区、默认目录与环境变量 |
+| backup/TFTP/topology | 公共参数组、终端检查/密码、配置排他发布 | Planner、备份回执、TFTP 核验、归档与成功策略 |
+| VXLAN | 分发、公共参数、初始化、终端确认、离线输入输出、采集入口 | NX-OS 命令、Fabric、计划项/哈希验证、凭据及操作租约 |
+| Wireless | 同上 | 平台、AP/LLDP、计划格式、凭据与 AP 会话 |
+| baseline | 现有 script/coverage.rb 参数和输出边界 | 能力矩阵生成、--check、领域 API 与所有离线示例 |
+
+ctx_runner 继续拥有采集/报告/执行的业务状态，net-connector Inventory 继续拥有筛选；ctx_cli 不反向加载二者。普通 Config 旧入口保留为宿主政策适配，无第二份配置发现实现。
+
+ctx_cli 初始版本为 0.1.0。首次发布依赖顺序先 ctx_cli，再 net-connector 与 CLI 消费模块；ctx_runner 的依赖链仍按其原有约定。提交、远程创建和发布按用户明确授权的范围执行。

data/examples/configuration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "ctx_cli"
+require "tmpdir"
+
+# 自定义宿主命名空间；示例只操作临时目录，不读取真实用户配置。
+Dir.mktmpdir do |root|
+  path = File.join(root, "audit.yml")
+  publisher = CtxCli::Initialization.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 })
+  abort "Unexpected precedence" unless effective == { "directory" => File.join(root, "reports"), "parallel" => 4 }
+  abort "Existing configuration overwritten" unless publisher.create(path: path, contents: "invalid") == :exists
+end
+puts "Configuration discovery and private initialization verified"

data/examples/offline.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "ctx_cli"
+require "stringio"
+
+# 领域只声明自己的参数和动作；标准流始终由宿主拥有。
+out = StringIO.new
+command = CtxCli::Command.new(banner: "sample [--complete]", defaults: { complete: false }, out: out) do |parser, values|
+  parser.on("--complete", "声明输入采集完整") { values[:complete] = true }
+  CtxCli::Options.information(parser, values)
+end
+values = command.parse([ "--complete" ])
+body = CtxCli::Input.read(input: StringIO.new("synthetic evidence"))
+CtxCli::Output.new(out: out).json({ complete: values[:complete], bytes: body.bytesize })
+abort "Unexpected offline output" unless JSON.parse(out.string) == { "complete" => true, "bytes" => 18 }
+puts "Offline command boundary verified"

data/lib/ctx_cli/application.rb

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

data/lib/ctx_cli/collection.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "output"
+
+module CtxCli
+  # 终端采集入口的固定顺序；领域适配器拥有清单、预检、调度及采集策略。
+  class Collection
+    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
+      @label, @report_error, @failure_code = label, report_error, failure_code
+      @out, @error, @input = out, error, input
+      @output = Output.new(out: out, error: error)
+    end
+
+    # 先预检全部输入和凭据，再创建报告和连接；失败分类不打印原始异常正文。
+    def run(argv)
+      # 每次运行独立持有批次状态；预检失败不能改写上一次报告。
+      @options, @store, @progress, @devices, @batch = nil, nil, nil, [], nil
+      @options = @options_factory.call(argv)
+      return 0 if @options.informational?
+      @options.validate_interaction!(input: @input, error: @error)
+      @options.load_environment
+      if @options.flags[:init]
+        @options.initialize_files
+        return 0
+      end
+      return 0 if @options.missing?(input: @input, error: @error)
+      @options.load
+      @progress = @progress_factory.call(@options)
+      @progress.notice("配置：#{@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("没有匹配设备，未建立连接")
+        @output.json({ status: :no_devices, total: 0 }, pretty: false) if @options.flags[:json]
+        return 1
+      end
+      context = @adapter.prepare(devices, @options)
+      @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.with_updates do
+          @adapter.execute(devices, @options) do |device|
+            @batch.collect(device) { @adapter.collect(device, @options, context: context, progress: @progress) }
+          end
+        end
+        @adapter.after_collect(@store, @options)
+      end
+      completion(outcome)
+    rescue Interrupt
+      diagnostic "采集已取消，已保存的设备报告保留；未保存结果见报告状态"
+      130
+    rescue SystemCallError, IOError => error
+      diagnostic "#{@label} 参数或报告错误：#{report_diagnostic(error)}"
+      2
+    rescue OptionParser::ParseError, ArgumentError, LoadError => error
+      diagnostic "#{@label} 参数、依赖或报告错误：#{error.message}；使用 --help 查看参数"
+      2
+    rescue StandardError => error
+      diagnostic "#{@label} 清单或执行失败：#{@failure_code.call(error)}（#{error.class.name}）"
+      2
+    end
+
+    def inspect = "#<#{self.class.name}>"
+    alias_method :to_s, :inspect
+    def pretty_print(printer) = printer.text(inspect)
+
+    private
+
+    # Runner 决定批次结论；CLI 仅呈现安全诊断并映射退出码。
+    def completion(outcome)
+      if outcome.finalization_error
+        diagnostic "#{@label} 摘要报告错误：#{outcome.finalization_error}"
+      end
+      if outcome.recovery_failed
+        diagnostic "摘要恢复未确认；请依据退出码及报告目录检查，不能将旧摘要视为本次成功。"
+      end
+      if outcome.status == :interrupted
+        diagnostic "采集已取消，已保存的设备报告保留；未保存结果见报告状态"
+      elsif (failure = outcome.failure)
+        if failure[:kind] == :report
+          diagnostic "#{@label} 参数或报告错误：#{failure[:detail]}"
+        else
+          diagnostic "#{@label} 清单或执行失败：#{failure[:error_type]}；已采集结果见批次报告"
+        end
+      end
+      { complete: 0, incomplete: 1, failed: 2, interrupted: 130 }.fetch(outcome.status)
+    end
+
+    # 错误提示失败不能覆盖取消或执行退出码；已失效的进度流不再重试。
+    def diagnostic(message)
+      @output.diagnostic(message) unless @progress&.output_error
+    end
+
+    # 自有发布错误消息不含正文；外部文件异常只显示类型，不打印 message/cause。
+    def report_diagnostic(error)
+      error.instance_of?(@report_error) ? error.message : error.class.name
+    end
+
+    # 预览默认显示逐设备身份；公开配置由显式开关展示。
+    def output(value)
+      if @options.flags[:json] || value.is_a?(Hash)
+        @output.json(value)
+      else
+        value.each { |device| @out.puts "#{device.fetch('host')}\t#{device.fetch('name')}\t#{device['model']}" }
+        @out.puts "设备：#{value.size} 台；未建立设备连接"
+      end
+      value.is_a?(Array) && value.empty? ? 1 : 0
+    end
+  end
+end

data/lib/ctx_cli/command.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "configuration"
+
+module CtxCli
+  # 每次解析新建值与解析器；领域参数通过普通 OptionParser 块扩展。
+  class Command
+    attr_reader :values, :parser
+
+    def initialize(banner:, defaults: {}, out: $stdout, &configure)
+      @banner, @defaults, @out, @configure = banner, Configuration.copy(defaults), out, configure
+    end
+
+    def parse(argv)
+      @values = Configuration.copy(@defaults)
+      @parser = OptionParser.new
+      @parser.banner = @banner
+      @configure&.call(@parser, @values)
+      rest = @parser.parse(argv.dup)
+      raise ArgumentError, "不接受位置参数" unless rest.empty?
+      @values
+    end
+
+    # 信息分支只写指定输出流，调用方在此后才读取输入或配置。
+    def informational?(examples: nil, details: nil)
+      if values[:help] || values[:help_all]
+        @out.puts parser
+        @out.puts details if values[:help_all] && details
+      elsif values[:examples] && examples
+        @out.puts examples
+      else
+        return false
+      end
+      true
+    end
+
+    def inspect = "#<#{self.class.name}>"
+    alias_method :to_s, :inspect
+    def pretty_print(printer) = printer.text(inspect)
+  end
+end

data/lib/ctx_cli/configuration.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module CtxCli
+  # 宿主配置发现；加载文件不读取配置或建立设备连接。
+  class Configuration
+    attr_reader :data, :specific, :process_environment, :file_environment, :environment,
+                :config_files, :environment_files, :sources
+
+    def initialize(name:, env: ENV, script: $PROGRAM_NAME, cwd: Dir.pwd, home: Dir.home,
+                   directories: nil, config: nil, env_file: nil, config_env: nil,
+                   path_fields: [], env_path_keys: [], path_literals: {},
+                   namespace: name, names: [ name.to_s ], common_keys: [])
+      @name = name.to_s.dup.freeze
+      @namespace = namespace.to_s.dup.freeze
+      @names = self.class.freeze_tree(self.class.copy(names))
+      @common_keys = self.class.freeze_tree(self.class.copy(common_keys))
+      raise ArgumentError, "unsupported configuration name: #{@name}" unless @names.include?(@name)
+
+      @cwd = File.expand_path(cwd)
+      @home = File.expand_path(home)
+      @config_env = (config_env || "#{@name.upcase}_CONFIG").to_s.dup.freeze
+      @env_path_keys = (env_path_keys.map { |key| key.to_s.dup.freeze } + [ @config_env ]).uniq.freeze
+      @path_literals = self.class.freeze_tree(self.class.copy(path_literals.transform_keys(&:to_s)))
+      @process_environment = self.class.copy(env.to_h)
+      resolve_environment_paths!(@process_environment, @cwd)
+      self.class.freeze_tree(@process_environment)
+      @user_directory = File.join(user_config_home, @namespace)
+      @directories = (directories || [ "/etc/#{@namespace}", "/usr/local/etc/#{@namespace}", @user_directory,
+                                      File.dirname(File.expand_path(script, @cwd)), @cwd ]).map do |path|
+        File.expand_path(path, @cwd)
+      end.uniq
+      @explicit_config = absolute(config, @cwd)
+      @explicit_env_file = absolute(env_file, @cwd)
+      @path_fields = path_fields.map { |path| path.to_s.split(".") }
+      @data = @specific = @file_environment = @environment = {}.freeze
+      @config_files = @environment_files = [].freeze
+      @sources = { "configuration_files" => @config_files, "environment_files" => @environment_files, "fields" => {}.freeze }.freeze
+    end
+
+    # 环境文件只形成私有快照，不修改 ENV，不读取 YAML。
+    def load_environment(allow_missing: false)
+      return self if @environment_loaded
+
+      files = candidates(".env", @explicit_env_file)
+      values = {}
+      loaded = []
+      files.each do |path|
+        next unless readable_file?(path, explicit: path == @explicit_env_file, allow_missing: allow_missing)
+
+        parsed = parse_environment(path, values.merge(@process_environment))
+        resolve_environment_paths!(parsed, File.dirname(path))
+        values.merge!(parsed)
+        loaded << path
+      end
+      @file_environment = self.class.freeze_tree(values)
+      @environment = self.class.freeze_tree(values.merge(self.class.copy(@process_environment)))
+      @environment_files = self.class.freeze_tree(loaded)
+      # 空的选择变量视为缺失，包括进程中显式的空值。
+      selector = present(@process_environment[@config_env]) || present(values[@config_env])
+      @selected_config = @explicit_config || absolute(selector, @cwd)
+      @environment_loaded = true
+      update_sources({})
+      self
+    end
+
+    # 每批固定一份快照；重复调用不重新读取文件。
+    def load(allow_missing: false)
+      return self if @loaded
+
+      load_environment(allow_missing: allow_missing)
+      merged = {}
+      specific = {}
+      fields = {}
+      loaded = []
+      @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|
+        next unless readable_file?(path, explicit: path == @selected_config, allow_missing: allow_missing)
+
+        document = read_yaml(path)
+        if @namespace != @name && File.basename(path) == "#{@namespace}.yml"
+          common, native, applicable = shared_sections(document, path)
+          merged = merge_layer(merged, common, path, fields)
+          @applicable ||= applicable
+        else
+          native = document
+          validate_string_keys!(native, path)
+          @applicable = true
+        end
+        merged = merge_layer(merged, native, path, fields)
+        specific = self.class.merge(specific, resolve_paths(native, path))
+        loaded << path
+      end
+      @data = self.class.freeze_tree(merged)
+      @specific = self.class.freeze_tree(specific)
+      @config_files = self.class.freeze_tree(loaded)
+      update_sources(fields)
+      @loaded = true
+      self
+    end
+
+    def config
+      @selected_config || @explicit_config || @config_files.last || init_config
+    end
+
+    def env_file
+      @explicit_env_file || @environment_files.last || init_env_file
+    end
+
+    def init_config
+      @selected_config || @explicit_config || File.join(@user_directory, "#{@name}.yml")
+    end
+
+    def init_env_file
+      @explicit_env_file || File.join(@user_directory, ".env")
+    end
+
+    def missing?
+      !@applicable
+    end
+
+    # 序列化规则与目标文件的发现规则一致。
+    def self.dump(document, name:, path:, namespace: name)
+      YAML.dump(File.basename(path) == "#{namespace}.yml" && namespace.to_s != name.to_s ? { name.to_s => document } : document)
+    end
+
+    # 默认展示仅包含类型，公开来源通过 sources 显式读取。
+    def inspect = "#<#{self.class.name}>"
+    alias_method :to_s, :inspect
+    def pretty_print(printer) = printer.text(inspect)
+
+    # 递归合并但不修改来源；数组、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)
+        end
+        result
+      end
+    end
+
+    # 只复制普通数据；循环或不透明对象不能进入快照并冻结调用方资源。
+    def self.copy(value, active = {}.compare_by_identity)
+      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) ] }
+          else
+            value.map { |entry| copy(entry, active) }
+          end
+        ensure
+          active.delete(value)
+        end
+      when String then String.new(value)
+      when Integer, Float, Symbol, NilClass, TrueClass, FalseClass then value
+      else raise ArgumentError, "configuration accepts plain data only"
+      end
+    end
+
+    def self.freeze_tree(value)
+      case value
+      when Hash then value.each { |key, entry| freeze_tree(key); freeze_tree(entry) }
+      when Array then value.each { |entry| freeze_tree(entry) }
+      end
+      value.freeze
+    end
+
+    private
+
+    def present(value)
+      value unless value.nil? || value.to_s.strip.empty?
+    end
+
+    def absolute(path, directory)
+      File.expand_path(path.to_s, directory) if present(path)
+    end
+
+    def user_config_home
+      absolute(present(@process_environment["XDG_CONFIG_HOME"]), @cwd) || File.join(@home, ".config")
+    end
+
+    def candidates(filename, explicit)
+      final_candidates(@directories.map { |directory| File.join(directory, filename) }, explicit)
+    end
+
+    def final_candidates(paths, explicit)
+      paths = paths.reject { |path| path == explicit } + [ explicit ] if explicit
+      paths.uniq
+    end
+
+    def readable_file?(path, explicit:, allow_missing:)
+      unless File.exist?(path)
+        raise ArgumentError, "configuration file does not exist: #{path}" if explicit && !allow_missing
+
+        return false
+      end
+      return true if File.file?(path) && File.readable?(path)
+
+      raise ArgumentError, "configuration path is not a readable regular file: #{path}"
+    end
+
+    def read_yaml(path)
+      contents = File.read(path)
+      validate_yaml_structure!(contents, path)
+      document = YAML.safe_load(contents, permitted_classes: [], permitted_symbols: [], aliases: false)
+      document = {} if document.nil?
+      raise ArgumentError, "configuration must contain a mapping: #{path}" unless document.is_a?(Hash)
+
+      document
+    rescue Psych::Exception, SystemCallError, IOError => error
+      raise ArgumentError, "cannot read configuration file: #{path} (#{error.class})", cause: nil
+    end
+
+    # 覆盖只能来自明确文件层；同文件不能隐藏重复键
+    # 或在领域校验前静默丢弃后续文档。
+    def validate_yaml_structure!(contents, path)
+      stream = YAML.parse_stream(contents)
+      raise ArgumentError, "configuration must contain a single YAML document: #{path}" if stream.children.size > 1
+
+      stream.each do |node|
+        next unless node.is_a?(Psych::Nodes::Mapping)
+
+        keys = {}
+        node.children.each_slice(2) do |key, _|
+          next unless key.is_a?(Psych::Nodes::Scalar)
+          if keys.key?(key.value)
+            raise ArgumentError, "duplicate configuration key at line #{key.start_line + 1}: #{path}"
+          end
+
+          keys[key.value] = true
+        end
+      end
+    end
+
+    def validate_string_keys!(value, path)
+      case value
+      when Hash
+        raise ArgumentError, "configuration keys must be strings: #{path}" unless value.keys.all?(String)
+
+        value.each_value { |entry| validate_string_keys!(entry, path) }
+      when Array
+        value.each { |entry| validate_string_keys!(entry, path) }
+      end
+    end
+
+    def shared_sections(document, path)
+      unknown = document.keys - [ "common", *@names ]
+      raise ArgumentError, "unknown shared configuration namespaces in #{path}: #{unknown.join(", ")}" unless unknown.empty?
+
+      common = document.fetch("common", {})
+      native = document.fetch(@name, {})
+      unless common.is_a?(Hash) && native.is_a?(Hash)
+        raise ArgumentError, "common and #{@name} configuration must contain mappings: #{path}"
+      end
+      unknown_common = common.keys - @common_keys
+      unless unknown_common.empty?
+        raise ArgumentError, "unsupported common configuration fields in #{path}: #{unknown_common.join(", ")}"
+      end
+      validate_string_keys!(common, path)
+      validate_string_keys!(native, path)
+      [ common, native, document.key?(@name) ]
+    end
+
+    def resolve_paths(document, path)
+      result = self.class.copy(document)
+      @path_fields.each { |segments| resolve_path!(result, segments, File.dirname(path), segments.join(".")) }
+      result
+    end
+
+    def resolve_path!(value, segments, directory, field)
+      return unless value.is_a?(Hash) && !segments.empty?
+
+      key, *rest = segments
+      keys = key == "*" ? value.keys : [ key ]
+      keys.each do |entry|
+        next unless value.key?(entry)
+
+        if rest.empty?
+          value[entry] = declared_path(value[entry], directory, field) if value[entry].is_a?(String) && !value[entry].empty?
+        else
+          resolve_path!(value[entry], rest, directory, field)
+        end
+      end
+    end
+
+    # 路径也可能是远程归档 URI，不能无条件转成本机路径。
+    def declared_path(value, directory, field)
+      raise ArgumentError if value.to_s.include?("\0")
+
+      return value if @path_literals.fetch(field, []).include?(value)
+
+      value.to_s.match?(%r{\A[A-Za-z][A-Za-z0-9+.-]*://}) ? value : absolute(value, directory)
+    rescue ArgumentError
+      raise ArgumentError, "invalid path #{field}", cause: nil
+    end
+
+    def resolve_environment_paths!(values, directory)
+      @env_path_keys.each do |key|
+        values[key] = declared_path(values[key], directory, key) if present(values[key])
+      end
+    end
+
+    def merge_layer(previous, document, path, fields)
+      resolved = resolve_paths(document, path)
+      record_fields(resolved, path, fields, previous: previous)
+      self.class.merge(previous, resolved)
+    end
+
+    def record_fields(document, source, fields, prefix = nil, previous: {})
+      document.each do |key, value|
+        name = [ prefix, key ].compact.join(".")
+        before = previous.is_a?(Hash) ? previous[key] : nil
+        next if value.is_a?(Hash) && value.empty? && before.is_a?(Hash) && !before.empty?
+
+        if value.is_a?(Hash) && !value.empty?
+          fields.delete(name)
+          record_fields(value, source, fields, name, previous: before)
+        else
+          fields.delete_if { |field, _| field == name || field.start_with?("#{name}.") }
+          fields[name] = source
+        end
+      end
+    end
+
+    def update_sources(fields)
+      @sources = self.class.freeze_tree({ "configuration_files" => @config_files,
+                                          "environment_files" => @environment_files, "fields" => fields })
+    end
+
+    # 复用 dotenv 语法，但替换只读取本次快照：
+    # 不能使用默认的进程 ENV 读取或命令替换。
+    def parse_environment(path, inherited)
+      require "dotenv"
+      process = @process_environment
+      variable_pattern = Dotenv::Substitutions::Variable.singleton_class.const_get(:VARIABLE)
+      parser_class = Class.new(Dotenv::Parser) do
+        define_singleton_method(:substitutions) do
+          [ lambda do |value, local|
+            raise ArgumentError, "command substitution is unsupported" if value.include?("$(")
+
+            value.gsub(variable_pattern) do |variable|
+              match = Regexp.last_match
+              if match[1] == "\\"
+                variable[1..]
+              elsif match[3]
+                process.fetch(match[3]) { local.fetch(match[3]) { inherited.fetch(match[3], "") } }
+              else
+                variable
+              end
+            end
+          end ]
+        end
+        define_method(:expand_newlines) do |value|
+          if (@hash["DOTENV_LINEBREAK_MODE"] || inherited["DOTENV_LINEBREAK_MODE"]) == "legacy"
+            value.gsub('\\n', "\n").gsub('\\r', "\r")
+          else
+            value.gsub('\\n', "\\\\\\n").gsub('\\r', "\\\\\\r")
+          end
+        end
+        private :expand_newlines
+      end
+      contents = File.read(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"
+      end
+      parser_class.call(contents, overwrite: true)
+    rescue Dotenv::FormatError, ArgumentError, SystemCallError, IOError => error
+      raise ArgumentError, "cannot read environment file: #{path} (#{error.class})", cause: nil
+    end
+  end
+end

data/lib/ctx_cli/initialization.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+
+module CtxCli
+  # 只发布已经过宿主校验的模板，不收集凭据、不覆盖已有目录项。
+  class Initialization
+    def initialize(prefix: ".ctx-cli-init-")
+      @prefix = prefix
+    end
+
+    # 符号链接和目录不算可保留配置；用 lstat 同时拒绝悬空链接。
+    def existing?(path)
+      stat = File.lstat(path)
+      raise ArgumentError, "config path must be a regular file" unless stat.file?
+      true
+    rescue Errno::ENOENT
+      false
+    end
+
+    # 文件先完整同步，排他链接后再同步目录；失败不返回已确认状态。
+    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)
+      directory = File.realpath(File.dirname(File.expand_path(path)))
+      destination = File.join(directory, File.basename(path))
+      file = parent = primary = nil
+      begin
+        Thread.handle_interrupt(Exception => :never) { file = Tempfile.new([ @prefix, ".tmp" ], directory) }
+        file.binmode
+        file.chmod(0o600)
+        file.write(contents)
+        file.flush
+        file.fsync
+        begin
+          File.link(file.path, destination)
+        rescue Errno::EEXIST
+          return :exists if existing?(destination)
+          raise
+        end
+        Thread.handle_interrupt(Exception => :never) { parent = File.open(directory, File::RDONLY | File::NOFOLLOW) }
+        parent.fsync
+        :created
+      rescue Exception => failure # rubocop:disable Lint/RescueException -- 清理不能覆盖取消或发布故障。
+        primary = failure
+        raise
+      ensure
+        close_files(file, parent, primary)
+      end
+    end
+
+    private
+
+    # 全部句柄都尝试关闭，保留原始故障；不把清理失败变为成功。
+    def close_files(file, parent, primary)
+      Thread.handle_interrupt(Exception => :never) do
+        error = nil
+        [ -> { parent&.close }, -> { file&.close! } ].each do |close|
+          begin
+            close.call
+          rescue Exception => failure # rubocop:disable Lint/RescueException -- 两个资源均尝试关闭。
+            error ||= failure
+          end
+        end
+        raise error if error && !primary
+      end
+    end
+  end
+end

data/lib/ctx_cli/input.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CtxCli
+  # 只关闭自行打开的文件，stdin 的读取和关闭权仍由宿主控制。
+  module Input
+    def self.read(path: nil, input: $stdin)
+      path ? File.read(path) : input.read
+    end
+  end
+end

data/lib/ctx_cli/options.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+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 }
+    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 }
+    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 }
+    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) }
+      parser.on("-p", "--parallel N", Integer, parallel_help) { |value| store.call(:parallel, value) }
+      parser.on("--directory DIR", "按设备保存报告的目录") { |value| store.call(:directory, value) }
+    end
+
+    def self.list(value)
+      values = value.split(",", -1).map(&:strip)
+      raise ArgumentError, "列表不能有空项" if values.any?(&:empty?)
+      values
+    end
+  end
+end

data/lib/ctx_cli/output.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json"
+
+module CtxCli
+  # 结果显式导出；诊断不展开异常正文，输出失败不能伪装结果成功。
+  class Output
+    def initialize(out: $stdout, error: $stderr)
+      @out, @error = out, error
+    end
+
+    def text(value) = @out.puts(value)
+    def json(value, pretty: true) = @out.puts(pretty ? JSON.pretty_generate(value) : JSON.generate(value))
+
+    # 最后的错误流失败不能覆盖原本的失败或取消状态。
+    def diagnostic(message, exception: nil)
+      @error.puts(exception ? "#{message}（#{exception.class.name}）" : message)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/ctx_cli/terminal.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CtxCli
+  # 终端只借用标准流；确认、问答和密码读取都由调用方显式发起。
+  class Terminal
+    def initialize(input: $stdin, out: $stderr)
+      @input, @out = input, out
+    end
+
+    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: "必须使用真实交互终端")
+      raise ArgumentError, message unless tty?(*others)
+    end
+
+    def question(prompt)
+      require_tty!
+      @out.print prompt
+      @out.flush
+      @input.gets("\n")&.strip
+    end
+
+    def confirm(token:, prompt:)
+      question(prompt) == token
+    end
+
+    def password(label:)
+      raise ArgumentError, "密码提示需要交互终端；自动化任务可使用环境变量或 --stdin-credentials" unless self.class.tty?(@input)
+      require "io/console"
+      @out.print "#{label}："
+      @out.flush
+      value = @input.noecho { |terminal| terminal.gets("\n") }&.chomp("\n")
+      @out.puts
+      raise ArgumentError, "密码不能为空" if value.nil? || value.empty?
+      value
+    end
+  end
+end

data/lib/ctx_cli/version.rb

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

data/lib/ctx_cli.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "ctx_cli/version"
+require_relative "ctx_cli/configuration"
+require_relative "ctx_cli/initialization"
+require_relative "ctx_cli/application"
+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"

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: ctx_cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gatework contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: fileutils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: io-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: optparse
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tempfile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Shared configuration discovery, private initialization, terminal interaction
+  and CLI orchestration without device or application dependencies.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/migration.md
+- 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/input.rb
+- lib/ctx_cli/options.rb
+- lib/ctx_cli/output.rb
+- lib/ctx_cli/terminal.rb
+- lib/ctx_cli/version.rb
+homepage: https://github.com/gatework/ctx_cli
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/gatework/ctx_cli
+  bug_tracker_uri: https://github.com/gatework/ctx_cli/issues
+  changelog_uri: https://github.com/gatework/ctx_cli/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/gatework/ctx_cli#readme
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Composable command-line boundaries for network automation.
+test_files: []