net-connector 0.17.0 → 0.17.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 233cb61903727cc01241fcae91e4e540a8bae1462b01210e73aa246fd1a906c9
-  data.tar.gz: 923cdca12fc7c38841743618a0d22527536bee646de7687c26480afbc3265a4a
+  metadata.gz: aadffbf2db023105e9b507fb732a89bd710207adf28456b2edb5184eb245fedf
+  data.tar.gz: 72cc71886fd9c6dce77171af3c8300f5f84af7c7e8192acd335e132c942b2b3c
 SHA512:
-  metadata.gz: d3f2a794edb16faf5429967c4a25ee53a949fef194883cb5aefdc0f9a1a9968ccdf8a539e2f059a4a7d3f28d1e299ab1481c5d66823d555324bb11e2ae10ee0c
-  data.tar.gz: a3ca7a0f4bee7e40861a700063c448f5ac918bf09d7d5b5c87510a664eb024c3fd98cee3ae9a27516d63b59ee8c7aa6af7000231d74acaf24405c2852a7b423f
+  metadata.gz: 4d59d23ae05999d469f96837baf6b5f2eca3518104b8769947c36c860788627f3f9cb35c4e05151e364e51f159f0b171905f64fbfd30b963d096bf176cbf35d5
+  data.tar.gz: 0b0137d959ecc3be69fd72fbed2bcc562e95c615ab13a786c4485dcf107ff9de30376e2c731051edbac6f297b496be1cdc97c2ec321066c955c9a3a88ef369f6

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 更新记录
 
+## Unreleased
+
+## 0.17.2 - 2026-10-23
+
+- Migrate shared CLI entrypoints to ctx_cli 0.2.0 names without legacy aliases.
+- Synchronize new directory ancestry across batch reports and local/SSH archives; synchronize uploaded-file cleanup.
+- Keep host-key comparison and vendor parsing independent of host field separators.
+- Reuse ctx_cli configuration, initialization, terminal and option boundaries without changing backup/TFTP/topology policies.
+
+## 0.17.1 - 2026-10-22
+
+- Delegate shared configuration, private initialization, option groups and terminal interaction to ctx_cli 0.1.0.
+
 ## 0.17.0 - 2026-10-22
 
 - Centralize inventory selection and CLI filters in Net::Connector::Inventory; add vendor/model inclusion, exclusion and matching modes.

data/README.md

@@ -62,3 +62,7 @@ script/ci
 The gate scans secrets, lints Ruby and workflows, runs tests and local PTY benchmarks, and verifies isolated gem installs. See [CONTRIBUTING](CONTRIBUTING.md), [security reporting](SECURITY.md), and the [changelog](CHANGELOG.md). Issues and pull requests may be written in English or Chinese.
 
 Licensed under [MIT](LICENSE).
+
+## ctx_cli 公共入口
+
+宿主配置文件读取、私有文件初始化、公共参数与终端交互由 ctx_cli 维护。原 `Net::Connector::Config`、配置路径、优先级和 backup/TFTP/topology 策略继续保留。源码联调使用 `CTX_CLI_PATH=../ctx_cli`；隔离安装可通过 `CTX_CLI_GEM=/absolute/path/ctx_cli-0.1.0.gem` 传入精确候选。

data/lib/net/connector/config.rb

@@ -1,366 +1,29 @@
 # frozen_string_literal: true
 
-require "yaml"
+require "ctx_cli/configuration"
 
 module Net
   module Connector
-    # Host-side configuration discovery. Requiring this file never loads device I/O.
-    class Config
+    # 保留原配置入口和路径政策；通用发现、来源与快照由 ctx_cli 维护。
+    class Config < CtxCli::Configuration
       NAMES = %w[vxlan wireless backup topology].freeze
       COMMON_KEYS = %w[netdisco inventory ssh].freeze
       CONFIG_ENV = { "vxlan" => "VXLAN_CONFIG", "wireless" => "WIRELESS_CONFIG",
                      "backup" => "NC_CONFIG", "topology" => "NC_CONFIG" }.freeze
 
-      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: {})
-        @name = name.to_s
-        raise ArgumentError, "unsupported configuration name: #{@name}" unless NAMES.include?(@name)
-
-        @cwd = File.expand_path(cwd)
-        @home = File.expand_path(home)
-        @config_env = config_env || CONFIG_ENV.fetch(@name)
-        @env_path_keys = (env_path_keys.map(&:to_s) + [@config_env]).uniq
-        @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, "net-connector")
-        @directories = (directories || ["/etc/net-connector", "/usr/local/etc/net-connector", @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
-
-      # Read environment files without mutating ENV or evaluating any 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)
-        # Empty selectors are absent, including an empty original process variable.
-        selector = present(@process_environment[@config_env]) || present(values[@config_env])
-        @selected_config = @explicit_config || absolute(selector, @cwd)
-        @environment_loaded = true
-        update_sources({})
-        self
-      end
-
-      # Freeze one batch snapshot; repeated calls do not re-read files.
-      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, "net-connector.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 File.basename(path) == "net-connector.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
-
-      # Serialize native values using the same target-file schema as discovery.
-      def self.dump(document, name:, path:)
+      def initialize(name:, config_env: nil, **options)
         name = name.to_s
         raise ArgumentError, "unsupported configuration name: #{name}" unless NAMES.include?(name)
 
-        YAML.dump(File.basename(path) == "net-connector.yml" ? { name => document } : document)
-      end
-
-      # Recursive, non-destructive replacement: arrays, false and nil are values.
-      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)
-        case value
-        when Hash then value.to_h { |key, entry| [copy(key), copy(entry)] }
-        when Array then value.map { |entry| copy(entry) }
-        when String then value.dup
-        else value
-        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
-
-      # Overrides are explicit file layers; one file cannot hide duplicate keys
-      # or silently discard later documents before the tool validates its scope.
-      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
+        super(name: name, config_env: config_env || CONFIG_ENV.fetch(name), namespace: "net-connector",
+              names: NAMES, common_keys: COMMON_KEYS, **options)
       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
-
-      # Declared paths may identify remote archive roots as well as local files.
-      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's grammar is reused, but substitutions are deliberately isolated:
-      # its default implementation reads real ENV and executes shell commands.
-      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?("$(")
+      # 共享文件按工具分区；各专用 YAML 保持原有字段布局。
+      def self.dump(document, name:, path:)
+        raise ArgumentError, "unsupported configuration name: #{name}" unless NAMES.include?(name.to_s)
 
-              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.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})"
+        super(document, name: name, path: path, namespace: "net-connector")
       end
     end
   end

data/lib/net/connector/engine/known_hosts.rb

@@ -159,7 +159,7 @@ module Net
         output, status = Open3.capture2e("ssh-keygen", "-f", path, "-F", @host)
         raise IOError, "reading device host key failed" unless [0, 1].include?(status.exitstatus)
 
-        output.lines("\n").reject { |line| line.start_with?("#") }.map { |line| line.split[1, 2] }.uniq
+        output.lines("\n").reject { |line| line.start_with?("#") }.map { |line| line.split(" ")[1, 2] }.uniq
       end
 
       # 从指定快照中移除当前主机条目，不直接修改共享信任文件。

data/lib/net/connector/netdisco/cli/options.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "ctx_cli/options"
+require "ctx_cli/terminal"
 require_relative "../settings"
 require_relative "../planner"
 require_relative "../config"
@@ -66,13 +68,9 @@ module Net
           def self.add_terminal_options(opts, values)
             opts.on("--ask-password", "隐藏输入设备密码") { values[:ask_password] = true }
             opts.on("--ask-netdisco-password", "隐藏输入 Netdisco 密码") { values[:ask_netdisco_password] = true }
-            opts.on("--quiet", "--no-progress", "关闭进度；可配合 --json") { values[:no_progress] = true }
-            opts.on("--verbose", "显示逐条登录和命令事件") { values[:verbose] = true }
-            opts.on("--json", "在 stdout 输出 JSON；默认显示可读摘要") { values[:json] = true }
+            CtxCli::Options.output(opts, values, quiet: :no_progress)
             opts.on("--stdin-credentials", "从标准输入读取凭据并等待 RUN") { values[:stdin_credentials] = true }
-            opts.on("--init", "创建缺失配置和环境模板后退出；已有文件不覆盖") { values[:init] = true }
-            opts.on("--interactive", "缺少文件时询问是否创建，并可交互填写") { values[:interactive] = true }
-            opts.on("--non-interactive", "禁用问答；创建文件须同时指定 --init") { values[:interactive] = false }
+            CtxCli::Options.initialization(opts, values)
           end
 
           # 登记互斥的拓扑执行模式和格式化参数，应用模式必须显式选择。
@@ -257,15 +255,7 @@ module Net
             return unless values[flag]
 
             raise ArgumentError, "密码提示与显式密码不能同时使用" if values[:environment].key?(key)
-            raise ArgumentError, "密码提示需要交互终端；自动化任务可使用环境变量或 --stdin-credentials" unless input.tty?
-            require "io/console"
-            output.print "#{label}："
-            output.flush
-            password = input.noecho { |terminal| terminal.gets("\n") }&.chomp("\n")
-            output.puts
-            raise ArgumentError, "密码不能为空" if password.nil? || password.empty?
-
-            values[:environment][key] = password
+            values[:environment][key] = CtxCli::Terminal.new(input: input, out: output).password(label: label)
           end
           private_class_method :read_password, :parser_for
         end

data/lib/net/connector/netdisco/cli/setup.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "ctx_cli/terminal"
 require_relative "../config/initializer"
 require_relative "../config/defaults"
 
@@ -98,7 +99,7 @@ module Net
 
           # 标准输入凭据协议独占输入；只有真实终端才允许配置问答。
           def terminal?
-            !@options[:stdin_credentials] && @input.respond_to?(:tty?) && @input.tty? && @output.respond_to?(:tty?) && @output.tty?
+            !@options[:stdin_credentials] && CtxCli::Terminal.tty?(@input, @output)
           end
 
           # 创建和定制为独立选择；显式 --init 默认直接生成已识别值。

data/lib/net/connector/netdisco/config/initializer.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require "yaml"
-require "tempfile"
+require "ctx_cli/initializer"
+require "ctx_cli/terminal"
 require_relative "../settings"
 require_relative "../../config"
 
@@ -14,6 +15,7 @@ module Net
           # 绑定配置问答的输入输出，保留调用方对 IO 的所有权。
           def initialize(input: $stdin, output: $stderr)
             @input, @output = input, output
+            @writer = CtxCli::Initializer.new(prefix: ".net-connector-config-")
           end
 
           # 完成默认值校验与可选问答后独占发布新配置，不覆盖已存在文件。
@@ -26,7 +28,7 @@ module Net
 
             values = YAML.safe_load(YAML.dump(document), aliases: false)
             validate!(values)
-            interactive = @input.respond_to?(:tty?) && @input.tty? && @output.respond_to?(:tty?) && @output.tty? if interactive.nil?
+            interactive = CtxCli::Terminal.tty?(@input, @output) if interactive.nil?
             configure(values, mode: mode, inherited_parallel: inherited_parallel) if interactive && answer("进入交互配置？[y/N]", "n").casecmp?("y")
             validate!(values)
             name = mode == :topology ? "topology" : "backup"
@@ -43,14 +45,7 @@ module Net
           private
 
           # 判断已有配置是否为普通文件；符号链接或其他类型不作为可用配置。
-          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 existing?(path) = @writer.existing?(path)
 
           # 通过完整策略快照校验候选文档，拒绝生成不可执行的配置。
           def validate!(document)
@@ -118,51 +113,8 @@ module Net
             end
           end
 
-          # 尝试关闭目录与临时文件全部句柄，清理失败不覆盖原始异常。
-          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
-
-          # 先写入并同步私有临时文件，再以独占硬链接发布完整配置并同步目录。
-          # 最终路径只在内容写全并同步后出现；已有目标由独占链接保护，取消也不能留下半份配置。
-          def write(path, contents)
-            directory = File.realpath(File.dirname(File.expand_path(path)))
-            destination = File.join(directory, File.basename(path))
-            file = parent = nil
-            begin
-              Thread.handle_interrupt(Exception => :never) { file = Tempfile.new([".net-connector-config-", ".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
+          # 公开文档已校验；排他发布、同步与清理由公共初始化器负责。
+          def write(path, contents) = @writer.create(path: path, contents: contents)
         end
       end
     end

data/lib/net/connector/netdisco/report/store.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../storage/directory"
+
 require "json"
 require_relative "../report"
 require "fileutils"
@@ -17,7 +19,7 @@ module Net
             # 以临时文件和重命名原子写入私有 JSON 报告。
             def write(report, directory:)
               destination = File.expand_path(directory)
-              FileUtils.mkdir_p(destination, mode: 0o700)
+              Storage::Directory.prepare(destination)
               filename = "netdisco-#{report.mode}-#{report.started_at.strftime("%Y%m%dT%H%M%SZ")}-#{SecureRandom.hex(4)}.json"
               path = File.join(destination, filename)
               Storage::AtomicFile.write(path, JSON.pretty_generate(report.summary)).path

data/lib/net/connector/netdisco/ssh/archive/client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../../storage/directory"
+
 require "digest"
 require "json"
 require "open3"
@@ -68,7 +70,7 @@ module Net
               end
               @password = password&.dup&.freeze
               @report_directory = File.expand_path(directory)
-              FileUtils.mkdir_p(@report_directory, mode: 0o700)
+              Storage::Directory.prepare(@report_directory)
               @batch = "#{Time.now.getlocal("+08:00").strftime("%Y-%m-%d_%H-%M-%S")}-ssh-#{SecureRandom.hex(8)}"
               @launcher = launcher || method(:open_ssh)
               @custom_launcher = !launcher.nil?
@@ -179,7 +181,7 @@ module Net
                                           archive_path: remote_path(proof.fetch("archive_path")))
               outcome = outcome.with(backup: receipt)
               path = File.join(@report_directory, "tftp", archive_name)
-              FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+              Storage::Directory.prepare(File.dirname(path))
               Storage::AtomicFile.write(path, bytes)
               outcome = outcome.with(backup: receipt.with(local_path: path))
               raise Tftp::Archive::Failure unless Storage::FileReader.fingerprint(path).sha256 == digest

data/lib/net/connector/netdisco/tftp/archive.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../storage/directory"
+
 require "fileutils"
 require "tempfile"
 require "digest"
@@ -50,7 +52,7 @@ module Net
           def initialize(directory:, root: nil)
             @report_directory = File.expand_path(directory)
             @server_root = root && File.realpath(root)
-            FileUtils.mkdir_p(@report_directory, mode: 0o700)
+            Storage::Directory.prepare(@report_directory)
             @server_archive_directory = create_server_archive_directory if @server_root
             @remote_suffix = reserve_remote_suffix unless @server_root
             @verifier = Tftp::Verifier.new(root: @server_root)
@@ -113,7 +115,7 @@ module Net
             return unless bytes
 
             previous_directory = File.join(@server_archive_directory, "previous")
-            FileUtils.mkdir_p(previous_directory, mode: 0o700)
+            Storage::Directory.prepare(previous_directory)
             archive_path = File.join(previous_directory, archive_filename(device, File.extname(remote_filename)))
             Storage::AtomicFile.write(archive_path, bytes)
             previous
@@ -126,7 +128,7 @@ module Net
             parent = File.join(@server_root, "archive")
             raise ArgumentError, "TFTP archive directory must not be a symlink" if File.symlink?(parent)
 
-            FileUtils.mkdir_p(parent, mode: 0o700)
+            Storage::Directory.prepare(parent)
             raise ArgumentError, "TFTP archive directory escaped its root" unless File.realpath(parent) == parent
 
             base = batch_name
@@ -136,6 +138,7 @@ module Net
               path = File.join(parent, candidate)
               begin
                 Dir.mkdir(path, 0o700)
+                Storage::Directory.sync(parent)
                 return path
               rescue Errno::EEXIST
                 number += 1
@@ -171,7 +174,7 @@ module Net
             receipt = outcome.backup
             saved_paths = { local_path: nil, archive_path: nil }
             batch_directory = File.join(@report_directory, "tftp")
-            FileUtils.mkdir_p(batch_directory, mode: 0o700)
+            Storage::Directory.prepare(batch_directory)
             extension = File.extname(receipt.path)
             filename = archive_filename(outcome.device, extension)
             batch_archive_path = File.join(batch_directory, filename)
@@ -192,6 +195,7 @@ module Net
               raise Failure.new(host: outcome.device.host) unless Storage::FileReader.same_entry?(uploaded_path, uploaded_fingerprint)
 
               File.unlink(uploaded_path)
+              Storage::Directory.sync(File.dirname(uploaded_path))
             end
             outcome.with(backup: receipt.with(**saved_paths))
           rescue StandardError => error

data/lib/net/connector/storage/batch_directory.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "fileutils"
+require_relative "directory"
 
 module Net
   module Connector
@@ -9,7 +9,7 @@ module Net
       class BatchDirectory
         # 固定 UTC+8，不依赖运行主机时区；mkdir 原子防止并发任务覆盖。
         def self.create(root, time: Time.now)
-          FileUtils.mkdir_p(root, mode: 0o700)
+          Directory.prepare(root)
           stamp = time.getlocal("+08:00").strftime("%Y-%m-%d_%H-%M-%S")
           suffix = 0
           loop do
@@ -17,6 +17,7 @@ module Net
             path = File.join(root, name)
             begin
               Dir.mkdir(path, 0o700)
+              Directory.sync(root)
               return path
             rescue Errno::EEXIST
               suffix += 1

data/lib/net/connector/storage/directory.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Net
+  module Connector
+    module Storage
+      # 新建目录与已有目录的文件发布共用持久化边界。
+      module Directory
+        def self.prepare(path)
+          path = File.expand_path(path)
+          missing, parent = [], path
+          until File.directory?(parent)
+            missing << parent
+            parent = File.dirname(parent)
+          end
+          FileUtils.mkdir_p(path, mode: 0o700)
+          missing.reverse_each { |created| sync(File.dirname(created)) }
+          path
+        end
+
+        def self.sync(path)
+          File.open(File.realpath(path), File::RDONLY | File::NOFOLLOW) { |directory| directory.fsync }
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/storage.rb

@@ -4,6 +4,7 @@ module Net
   module Connector
     # 文件存储不依赖设备连接；备份、离线导出和批量报告共享这些原语。
     module Storage
+      autoload :Directory, File.expand_path("storage/directory", __dir__)
       autoload :BatchDirectory, File.expand_path("storage/batch_directory", __dir__)
       autoload :BackupLock, File.expand_path("storage/backup_lock", __dir__)
       autoload :AtomicFile, File.expand_path("storage/atomic_file", __dir__)

data/lib/net/connector/vendor/h3c/topology.rb

@@ -43,7 +43,7 @@ module Net
             local_column = output.match?(/^[ \t]*System Name[ \t]+Local Interface\b/i) ? 1 : 0
             lines = neighbor_lines(output)
             return unless lines.all? do |line|
-              interface = line.split.fetch(local_column, nil)
+              interface = line.split(" ").fetch(local_column, nil)
               interface&.match?(/\A(?:[A-Za-z][A-Za-z-]*\d+(?:\/\d+)+|(?:Bridge-Aggregation|BAGG|Route-Aggregation|RAGG)\d+)(?:[:.]\d+)*\z/i)
             end
 

data/lib/net/connector/vendor/hillstone/tftp.rb

@@ -32,7 +32,7 @@ module Net
 
           # 从山石成功回显提取实际目标文件名。
           def remote_path(_target, result)
-            filename = completion_line(result)&.split&.last
+            filename = completion_line(result)&.split(" ")&.last
             TftpTarget.validate_path!(filename)
           end
 

data/lib/net/connector/version.rb

@@ -3,6 +3,6 @@
 module Net
   module Connector
     # gemspec、CLI 与发布工具共用此版本，运行时读取不触发设备依赖加载。
-    VERSION = "0.17.0"
+    VERSION = "0.17.2"
   end
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.17.2
 platform: ruby
 authors:
 - net-connector contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ctx_cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: expect-pty
   requirement: !ruby/object:Gem::Requirement
@@ -477,6 +491,7 @@ files:
 - lib/net/connector/storage/atomic_file.rb
 - lib/net/connector/storage/backup_lock.rb
 - lib/net/connector/storage/batch_directory.rb
+- lib/net/connector/storage/directory.rb
 - lib/net/connector/storage/file_reader.rb
 - lib/net/connector/storage/saved_config.rb
 - lib/net/connector/textfsm.rb