network-infra-utility 0.2.0 → 0.5.0

data/bin/dns-query

@@ -0,0 +1,834 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# coding: utf-8
+#
+# dns-query — 跨平台统一域名查询命令行工具 (network-infra-utility)
+#
+# 自动检测当前平台所有可用的 DNS 查询工具 (dig / nslookup / host /
+# Resolve-DnsName 等)，默认使用优先级最高的工具执行查询；也支持指定
+# DNS 服务器、指定记录类型、遍历全部可用工具交叉查询。
+#
+# 用法:
+#   ruby bin/dns-query <目标> [选项]
+#   ruby bin/dns-query www.baidu.com              # 正查 A 记录
+#   ruby bin/dns-query 8.8.8.8                     # 反查 PTR (自动识别 IP)
+#   ruby bin/dns-query www.baidu.com -t MX         # 指定记录类型
+#   ruby bin/dns-query www.baidu.com -s 8.8.8.8    # 指定 DNS 服务器
+#   ruby bin/dns-query www.baidu.com -a            # 用所有可用工具查询
+#   ruby bin/dns-query --tools                     # 列出当前平台可用工具
+#   ruby bin/dns-query --matrix                    # 全平台工具矩阵
+#
+# 选项:
+#   -t, --type TYPE      DNS 记录类型, 默认 A
+#   -s, --server SERVER  指定 DNS 服务器 (IP 或域名)
+#   -a, --all            使用所有可用工具交叉查询
+#       --tools          列出当前平台可用工具
+#       --matrix         显示全平台工具矩阵
+#       --no-color       禁用 ANSI 颜色输出
+#   -v, --version        显示版本
+#   -h, --help           显示帮助
+#
+# 退出码: 0 成功, 1 参数错误 / 无可用工具 / 查询全部失败
+
+require "optparse"
+require "rbconfig"
+require "shellwords"
+require "ipaddr"
+require_relative "../version"
+
+module DnsQuery
+  # ============================================================
+  # 平台检测
+  # ============================================================
+  module Platform
+    def self.os
+      @os ||= detect_os
+    end
+
+    def self.linux?
+      os == :linux
+    end
+
+    def self.windows?
+      os == :windows
+    end
+
+    def self.wsl?
+      linux? && File.exist?("/proc/version") &&
+        File.read("/proc/version").downcase.include?("microsoft")
+    end
+
+    def self.distro
+      @distro ||= detect_distro
+    end
+
+    def self.windows_build
+      return @win_build if @win_build
+      return nil unless windows?
+      raw = cmd_utf8("ver 2>NUL").strip
+      if raw =~ /(\d+\.\d+\.(\d+))/
+        @win_build = Regexp.last_match(2).to_i
+      else
+        @win_build = 0
+      end
+      @win_build
+    end
+
+    def self.windows_version_name
+      return nil unless windows?
+      b = windows_build
+      if b >= 22000 then "Win11"
+      elsif b >= 10240 then "Win10"
+      else "Win7"
+      end
+    end
+
+    def self.ps_version
+      return @ps_ver if @ps_ver
+      if windows?
+        raw = cmd_utf8('powershell -Command "$PSVersionTable.PSVersion.Major" 2>NUL').strip
+        @ps_ver = raw.to_i
+      else
+        @ps_ver = 0
+      end
+      @ps_ver
+    end
+
+    def self.to_s
+      if linux?
+        wsl_suffix = wsl? ? " (WSL)" : ""
+        "Linux/#{distro}#{wsl_suffix}"
+      elsif windows?
+        "Windows/#{windows_version_name}"
+      else
+        "Unknown"
+      end
+    end
+
+    private
+
+    # Windows 命令输出常为 GBK 编码，统一转成 UTF-8 字符串再处理
+    def self.cmd_utf8(cmd)
+      out = `#{cmd}`
+      if out.encoding == Encoding::UTF_8 && !out.valid_encoding?
+        out = out.force_encoding(Encoding::GBK)
+      end
+      out.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    rescue StandardError
+      out
+    end
+
+    def self.detect_os
+      case RbConfig::CONFIG["host_os"]
+      when /linux/   then :linux
+      when /mswin|mingw|cygwin|windows/ then :windows
+      when /darwin/  then :darwin
+      else :unknown
+      end
+    end
+
+    def self.detect_distro
+      return :unknown unless linux?
+      if File.exist?("/etc/alpine-release")      then :alpine
+      elsif File.exist?("/etc/lsb-release")       then :ubuntu
+      elsif File.exist?("/etc/debian_version")    then :debian
+      elsif File.exist?("/etc/redhat-release")     then :rhel
+      else :unknown_linux
+      end
+    end
+  end
+
+  # ============================================================
+  # 工具定义：10个DNS查询工具的全平台信息
+  # ============================================================
+  TOOL_DEFS = [
+    {
+      key: :dig,
+      name: "dig",
+      desc: "DNS查询瑞士军刀，功能最全面",
+      features: %w[A AAAA CNAME MX NS PTR SOA TXT SRV ANY AXFR DNSSEC trace short],
+      linux: {
+        ubuntu: { avail: true,  pkg: "dnsutils",       install: "sudo apt install -y dnsutils" },
+        alpine: { avail: true,  pkg: "bind-tools",     install: "sudo apk add bind-tools" },
+        debian: { avail: true,  pkg: "dnsutils",       install: "sudo apt install -y dnsutils" },
+        rhel:   { avail: true,  pkg: "bind-utils",     install: "sudo yum install -y bind-utils" },
+      },
+      windows: {
+        win7:  { avail: false, note: "需手动安装ISC BIND" },
+        win10: { avail: false, note: "需手动安装ISC BIND" },
+        win11: { avail: false, note: "需手动安装ISC BIND" },
+      },
+    },
+    {
+      key: :nslookup,
+      name: "nslookup",
+      desc: "经典DNS查询工具，跨平台内置",
+      features: %w[A AAAA CNAME MX NS PTR SOA TXT SRV],
+      linux: {
+        ubuntu: { avail: true,  pkg: "dnsutils",       install: "sudo apt install -y dnsutils" },
+        alpine: { avail: true,  pkg: "bind-tools",     install: "sudo apk add bind-tools" },
+        debian: { avail: true,  pkg: "dnsutils",       install: "sudo apt install -y dnsutils" },
+        rhel:   { avail: true,  pkg: "bind-utils",     install: "sudo yum install -y bind-utils" },
+      },
+      windows: {
+        win7:  { avail: true,  note: "系统内置" },
+        win10: { avail: true,  note: "系统内置" },
+        win11: { avail: true,  note: "系统内置" },
+      },
+    },
+    {
+      key: :host,
+      name: "host",
+      desc: "简洁的DNS查询工具，输出友好",
+      features: %w[A AAAA CNAME MX NS PTR SOA TXT SRV],
+      linux: {
+        ubuntu: { avail: true,  pkg: "dnsutils",       install: "sudo apt install -y dnsutils" },
+        alpine: { avail: true,  pkg: "bind-tools",     install: "sudo apk add bind-tools" },
+        debian: { avail: true,  pkg: "dnsutils",       install: "sudo apt install -y dnsutils" },
+        rhel:   { avail: true,  pkg: "bind-utils",     install: "sudo yum install -y bind-utils" },
+      },
+      windows: {
+        win7:  { avail: false, note: "Windows无此工具" },
+        win10: { avail: false, note: "Windows无此工具" },
+        win11: { avail: false, note: "Windows无此工具" },
+      },
+    },
+    {
+      key: :drill,
+      name: "drill",
+      desc: "ldns提供的DNS查询工具，支持DNSSEC",
+      features: %w[A AAAA CNAME MX NS PTR SOA TXT DNSSEC trace],
+      linux: {
+        ubuntu: { avail: true,  pkg: "ldnsutils",       install: "sudo apt install -y ldnsutils" },
+        alpine: { avail: true,  pkg: "drill",           install: "sudo apk add drill" },
+        debian: { avail: true,  pkg: "ldnsutils",       install: "sudo apt install -y ldnsutils" },
+        rhel:   { avail: true,  pkg: "ldns",            install: "sudo yum install -y ldns" },
+      },
+      windows: {
+        win7:  { avail: false, note: "Windows无此工具" },
+        win10: { avail: false, note: "Windows无此工具" },
+        win11: { avail: false, note: "Windows无此工具" },
+      },
+    },
+    {
+      key: :kdig,
+      name: "kdig",
+      desc: "Knot DNS查询工具，支持DNSSEC/DoH/DoT",
+      features: %w[A AAAA CNAME MX NS PTR SOA TXT DNSSEC DoH DoT trace],
+      linux: {
+        ubuntu: { avail: true,  pkg: "knot-dnsutils",   install: "sudo apt install -y knot-dnsutils" },
+        alpine: { avail: true,  pkg: "knot",            install: "sudo apk add knot" },
+        debian: { avail: true,  pkg: "knot-dnsutils",   install: "sudo apt install -y knot-dnsutils" },
+        rhel:   { avail: true,  pkg: "knot-utils",      install: "sudo yum install -y knot-utils" },
+      },
+      windows: {
+        win7:  { avail: false, note: "Windows无此工具" },
+        win10: { avail: false, note: "Windows无此工具" },
+        win11: { avail: false, note: "Windows无此工具" },
+      },
+    },
+    {
+      key: :dog,
+      name: "dog",
+      desc: "Rust编写的彩色DNS查询工具",
+      features: %w[A AAAA CNAME MX NS PTR SOA TXT SRV],
+      linux: {
+        ubuntu: { avail: true,  pkg: "dog",             install: "sudo apt install -y dog || cargo install dog" },
+        alpine: { avail: true,  pkg: "dog",             install: "sudo apk add dog (需community仓库)" },
+        debian: { avail: true,  pkg: "dog",             install: "sudo apt install -y dog || cargo install dog" },
+        rhel:   { avail: true,  pkg: "dog",             install: "cargo install dog" },
+      },
+      windows: {
+        win7:  { avail: false, note: "需cargo install dog" },
+        win10: { avail: false, note: "需cargo install dog" },
+        win11: { avail: false, note: "需cargo install dog" },
+      },
+    },
+    {
+      key: :resolve_dnspath,
+      name: "Resolve-DnsName",
+      desc: "PowerShell内置DNS查询Cmdlet",
+      features: %w[A AAAA CNAME MX NS PTR SOA TXT SRV],
+      linux: {
+        ubuntu: { avail: false, pkg: "-", install: "需安装PowerShell Core" },
+        alpine: { avail: false, pkg: "-", install: "需安装PowerShell Core" },
+        debian: { avail: false, pkg: "-", install: "需安装PowerShell Core" },
+        rhel:   { avail: false, pkg: "-", install: "需安装PowerShell Core" },
+      },
+      windows: {
+        win7:  { avail: false, note: "需PS4.0+，Win7自带PS2.0不支持" },
+        win10: { avail: true,  note: "PS5.1内置" },
+        win11: { avail: true,  note: "PS5.1内置" },
+      },
+    },
+    {
+      key: :ping_a,
+      name: "ping -a",
+      desc: "通过ping反查主机名（仅PTR，功能有限）",
+      features: %w[PTR],
+      linux: {
+        ubuntu: { avail: false, pkg: "-", install: "Linux ping无-a参数" },
+        alpine: { avail: false, pkg: "-", install: "Linux ping无-a参数" },
+        debian: { avail: false, pkg: "-", install: "Linux ping无-a参数" },
+        rhel:   { avail: false, pkg: "-", install: "Linux ping无-a参数" },
+      },
+      windows: {
+        win7:  { avail: true,  note: "内置" },
+        win10: { avail: true,  note: "内置" },
+        win11: { avail: true,  note: "内置" },
+      },
+    },
+    {
+      key: :getent,
+      name: "getent hosts",
+      desc: "通过nsswitch查询主机名解析",
+      features: %w[A AAAA],
+      linux: {
+        ubuntu: { avail: true,  pkg: "libc-bin",        install: "sudo apt install -y libc-bin" },
+        alpine: { avail: true,  pkg: "musl",            install: "默认内置" },
+        debian: { avail: true,  pkg: "libc-bin",        install: "sudo apt install -y libc-bin" },
+        rhel:   { avail: true,  pkg: "glibc-common",   install: "默认内置" },
+      },
+      windows: {
+        win7:  { avail: false, note: "Windows无此工具" },
+        win10: { avail: false, note: "Windows无此工具" },
+        win11: { avail: false, note: "Windows无此工具" },
+      },
+    },
+    {
+      key: :resolvectl,
+      name: "resolvectl query",
+      desc: "systemd-resolved DNS查询接口",
+      features: %w[A AAAA CNAME MX NS PTR SOA TXT SRV],
+      linux: {
+        ubuntu: { avail: true,  pkg: "systemd-resolved", install: "默认内置(16.04+)" },
+        alpine: { avail: false, pkg: "-",                install: "Alpine用OpenRC，无systemd" },
+        debian: { avail: true,  pkg: "systemd-resolved", install: "默认内置" },
+        rhel:   { avail: true,  pkg: "systemd-resolved", install: "默认内置(7+)" },
+      },
+      windows: {
+        win7:  { avail: false, note: "Windows无此工具" },
+        win10: { avail: false, note: "Windows无此工具" },
+        win11: { avail: false, note: "Windows无此工具" },
+      },
+    },
+  ].freeze
+
+  # ============================================================
+  # 工具运行时检测
+  # ============================================================
+  module ToolDetector
+    # 检测当前平台上哪些工具实际可用，返回 [{key:, name:, priority:}, ...]
+    def self.detect
+      tools = []
+
+      if Platform.linux?
+        add_if_exists(tools, :dig,          "dig",          0)
+        add_if_exists(tools, :host,          "host",         1)
+        add_if_exists(tools, :nslookup,      "nslookup",     2)
+        add_if_exists(tools, :drill,         "drill",        3)
+        add_if_exists(tools, :kdig,          "kdig",         4)
+        add_if_exists(tools, :dog,           "dog",          5)
+        add_if_exists(tools, :getent,        "getent",       6)
+        add_if_exists(tools, :resolvectl,    "resolvectl",   7)
+      elsif Platform.windows?
+        add_if_exists(tools, :dig,           "dig",          -1)
+        add_if_exists(tools, :nslookup,       "nslookup",     0)
+        if Platform.ps_version >= 4
+          tools << { key: :resolve_dnspath, name: "Resolve-DnsName", priority: 1 }
+        end
+        tools << { key: :ping_a, name: "ping -a", priority: 10 }
+        add_if_exists(tools, :drill,         "drill",        5)
+      end
+
+      tools.sort_by { |t| t[:priority] }
+    end
+
+    private
+
+    # 命令存在性检测，按平台用各自的命令与重定向符号，
+    # 避免 which 在 Windows / where 在 Linux 上互相踩坑
+    def self.add_if_exists(tools, key, cmd, priority)
+      exists = Platform.windows? ? windows_cmd?(cmd) : linux_cmd?(cmd)
+      if exists
+        tools << { key: key, name: cmd == "getent" ? "getent hosts" : cmd, priority: priority }
+      end
+      tools
+    end
+
+    def self.linux_cmd?(cmd)
+      system("command -v #{cmd} >/dev/null 2>&1")
+    end
+
+    def self.windows_cmd?(cmd)
+      system("where #{cmd} >NUL 2>&1")
+    end
+  end
+
+  # ============================================================
+  # 工具执行器：所有工具的调用逻辑统一在此
+  # ============================================================
+  module Executor
+    # 用指定工具执行查询，返回 [stdout, stderr, exit_code]
+    def self.run(tool_key, target, qtype, server = nil)
+      # PTR 反查统一转成反向域名 (in-addr.arpa / ip6.arpa)，
+      # 保证 dig/drill/kdig 等所有工具行为一致
+      qtarget = qtype == "PTR" ? reverse_domain(target) : target
+
+      case tool_key
+      when :dig            then run_dig(qtarget, qtype, server)
+      when :nslookup       then run_nslookup(qtarget, qtype, server)
+      when :host           then run_host(qtarget, qtype, server)
+      when :drill          then run_drill(qtarget, qtype, server)
+      when :kdig           then run_kdig(qtarget, qtype, server)
+      when :dog            then run_dog(qtarget, qtype, server)
+      when :getent         then run_getent(target, qtype)
+      when :resolvectl     then run_resolvectl(qtarget)
+      when :resolve_dnspath then run_resolve_dnspath(qtarget, qtype, server)
+      when :ping_a         then run_ping_a(target)
+      else ["[错误] 未知工具: #{tool_key}", "", 1]
+      end
+    end
+
+    # --- dig ---
+    def self.run_dig(target, qtype, server)
+      args = []
+      args << "@#{shell_quote(server)}" if server
+      args << shell_quote(target)
+      args << shell_quote(qtype)
+      args << "+short"
+      exec_cmd("dig #{args.join(' ')}")
+    end
+
+    # --- nslookup ---
+    def self.run_nslookup(target, qtype, server)
+      cmd = "nslookup -type=#{qtype} #{shell_quote(target)}"
+      cmd << " #{shell_quote(server)}" if server
+      exec_cmd(cmd)
+    end
+
+    # --- host ---
+    def self.run_host(target, qtype, server)
+      cmd = "host -t #{shell_quote(qtype)} #{shell_quote(target)}"
+      cmd << " #{shell_quote(server)}" if server
+      exec_cmd(cmd)
+    end
+
+    # --- drill ---
+    def self.run_drill(target, qtype, server)
+      cmd = "drill #{shell_quote(target)} #{shell_quote(qtype)}"
+      cmd << " @#{shell_quote(server)}" if server
+      exec_cmd(cmd)
+    end
+
+    # --- kdig ---
+    def self.run_kdig(target, qtype, server)
+      cmd = "kdig #{shell_quote(target)} #{shell_quote(qtype)}"
+      cmd << " @#{shell_quote(server)}" if server
+      exec_cmd(cmd)
+    end
+
+    # --- dog ---
+    def self.run_dog(target, qtype, server)
+      cmd = "dog #{shell_quote(qtype)} #{shell_quote(target)}"
+      cmd << " @#{shell_quote(server)}" if server
+      exec_cmd(cmd)
+    end
+
+    # --- getent hosts ---
+    def self.run_getent(target, _qtype)
+      exec_cmd("getent hosts #{shell_quote(target)}")
+    end
+
+    # --- resolvectl query ---
+    def self.run_resolvectl(target)
+      exec_cmd("resolvectl query #{shell_quote(target)}")
+    end
+
+    # --- Resolve-DnsName (Windows PowerShell) ---
+    def self.run_resolve_dnspath(target, qtype, server)
+      # 单引号在 PowerShell 字符串中需双写转义
+      t = target.to_s.gsub("'", "''")
+      s = server.to_s.gsub("'", "''")
+      ps_cmd = "Resolve-DnsName '#{t}' -DnsOnly"
+      ps_cmd << " -Type #{qtype}" unless qtype == "A"
+      ps_cmd << " -Server #{s}" unless s.empty?
+      exec_cmd("powershell -Command \"#{ps_cmd}\"")
+    end
+
+    # --- ping -a ---
+    def self.run_ping_a(target)
+      if Platform.windows?
+        exec_cmd("ping -a -n 1 #{shell_quote(target)}")
+      else
+        ["[跳过] Linux ping不支持-a参数", "", 0]
+      end
+    end
+
+    private
+
+    def self.exec_cmd(cmd)
+      stdout = `#{cmd} 2>&1`
+      exit_code = $?.exitstatus
+      [normalize_output(stdout), "", exit_code]
+    rescue StandardError => e
+      ["", e.message, 1]
+    end
+
+    # Windows 命令输出常为 GBK，统一转成 UTF-8，避免乱码
+    def self.normalize_output(str)
+      return str if str.encoding == Encoding::UTF_8 && str.valid_encoding?
+      if str.encoding == Encoding::UTF_8 && !str.valid_encoding?
+        str = str.force_encoding(Encoding::GBK)
+      end
+      if str.valid_encoding?
+        str.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      else
+        str.force_encoding(Encoding::UTF_8).scrub
+      end
+    rescue StandardError
+      str
+    end
+
+    def self.reverse_domain(host)
+      IPAddr.new(host).reverse
+    rescue IPAddr::InvalidAddressError
+      host
+    end
+
+    def self.shell_quote(str)
+      Shellwords.shellescape(str.to_s)
+    end
+  end
+
+  # ============================================================
+  # 查询入口：自动选择最佳工具或用全部工具
+  # ============================================================
+  class Query
+    def initialize(target, qtype: "A", server: nil)
+      @target = target
+      @qtype = qtype
+      @server = server
+      @is_ip = ip_like?(target)
+
+      # IP 反查自动切换为 PTR
+      @qtype = "PTR" if @is_ip && @qtype == "A"
+    end
+
+    # 自动选择最佳工具查询，返回 [stdout, exit_code]
+    def execute
+      tools = ToolDetector.detect
+      if tools.empty?
+        return ["[错误] 当前平台未找到任何可用的DNS查询工具", 1]
+      end
+
+      best = tools.first
+      puts DnsQuery.color("=== 使用 #{best[:name]} 查询 #{@target} (#{@qtype}) ===", :cyan)
+      puts ""
+      stdout, _stderr, code = Executor.run(best[:key], @target, @qtype, @server)
+      puts stdout
+      [stdout, code]
+    end
+
+    # 用所有可用工具查询，返回 [汇总文本, exit_code]
+    def execute_all
+      tools = ToolDetector.detect
+      if tools.empty?
+        return ["[错误] 未找到任何可用的DNS查询工具", 1]
+      end
+
+      puts DnsQuery.color("=== 使用所有可用工具查询 #{@target} (#{@qtype}) ===", :cyan)
+      puts ""
+      ok = 0
+      tools.each do |t|
+        puts DnsQuery.color("--- #{t[:name]} ---", :yellow)
+        stdout, _stderr, code = Executor.run(t[:key], @target, @qtype, @server)
+        if code != 0 && stdout.strip.empty?
+          puts "  [查询失败或不可用]"
+        else
+          puts stdout
+          ok += 1
+        end
+        puts ""
+      end
+      [ok.positive? ? "done" : "", ok.zero? ? 1 : 0]
+    end
+
+    private
+
+    def ip_like?(s)
+      IPAddr.new(s).ipv4? || IPAddr.new(s).ipv6?
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+  end
+
+  # ============================================================
+  # 工具列表展示
+  # ============================================================
+  module ToolList
+    def self.print
+      puts DnsQuery.color("============================================================", :cyan)
+      puts DnsQuery.color(" 当前平台可用DNS查询工具", :cyan)
+      puts DnsQuery.color(" OS: #{Platform}", :cyan)
+      puts DnsQuery.color("============================================================", :cyan)
+      puts ""
+
+      tools = ToolDetector.detect
+      if tools.empty?
+        puts "  [!] 未检测到可用工具"
+      else
+        tools.each_with_index do |t, i|
+          puts "  #{i + 1}. #{t[:name]} (优先级: #{t[:priority]})"
+        end
+      end
+      puts ""
+      puts "  默认将使用优先级最高的工具执行查询"
+    end
+  end
+
+  # ============================================================
+  # 全平台矩阵展示
+  # ============================================================
+  module Matrix
+    def self.print
+      puts "=" * 130
+      puts " 域名查询工具全平台矩阵"
+      puts "=" * 130
+      puts ""
+
+      distros = %i[ubuntu alpine debian rhel]
+      win_vers = %i[win7 win10 win11]
+
+      TOOL_DEFS.each do |tool|
+        puts "--- #{tool[:name]} ---"
+        puts "  说明: #{tool[:desc]}"
+        puts "  支持记录: #{tool[:features].join(', ')}"
+        puts ""
+
+        # Linux
+        printf "  %-12s", "Linux发行版"
+        distros.each { |d| printf " %-16s", d }
+        puts ""
+
+        printf "  %-12s", "可用性"
+        distros.each do |d|
+          info = tool[:linux][d] || {}
+          printf " %-16s", info[:avail] ? "Y" : "N"
+        end
+        puts ""
+
+        printf "  %-12s", "安装包"
+        distros.each do |d|
+          info = tool[:linux][d] || {}
+          printf " %-16s", info[:pkg] || "-"
+        end
+        puts ""
+
+        printf "  %-12s", "安装命令"
+        distros.each do |d|
+          info = tool[:linux][d] || {}
+          ic = info[:install] || "-"
+          printf " %-16s", ic.length > 16 ? ic[0..13] + "..." : ic
+        end
+        puts ""
+        puts ""
+
+        # Windows
+        printf "  %-12s", "Windows"
+        win_vers.each { |w| printf " %-24s", w }
+        puts ""
+
+        printf "  %-12s", "可用性"
+        win_vers.each do |w|
+          info = tool[:windows][w] || {}
+          printf " %-24s", info[:avail] ? "Y" : "N"
+        end
+        puts ""
+
+        printf "  %-12s", "说明"
+        win_vers.each do |w|
+          info = tool[:windows][w] || {}
+          note = info[:note] || "-"
+          printf " %-24s", note.length > 24 ? note[0..21] + "..." : note
+        end
+        puts ""
+        puts ""
+      end
+
+      puts "  Y = 可用  N = 不可用/需额外安装"
+      puts "  * Alpine的dog需community仓库"
+    end
+  end
+
+  # ============================================================
+  # 颜色输出（终端自动检测，可用 --no-color 强制关闭）
+  # ============================================================
+  module Color
+    CODES = {
+      black:   30, red: 31, green: 32, yellow: 33,
+      blue:    34, magenta: 35, cyan: 36, white: 37,
+    }.freeze
+
+    def self.disabled=(v)
+      @disabled = v
+      @supported = nil if v
+    end
+
+    def self.supported?
+      return false if @disabled
+      return @supported if defined?(@supported)
+      @supported = $stdout.tty? || ENV["TERM"] || ENV["ANSICON"] ||
+                   (Platform.windows? && ENV["WT_SESSION"])
+    end
+
+    def self.apply(text, color)
+      return text unless supported?
+      code = CODES[color]
+      return text unless code
+      "\e[0;#{code}m#{text}\e[0m"
+    end
+  end
+
+  def self.color(text, c)
+    Color.apply(text, c)
+  end
+
+  # ============================================================
+  # CLI 入口：参数解析 + 分发，返回进程退出码
+  # ============================================================
+  module CLI
+    SUPPORTED_TYPES = %w[A AAAA CNAME MX NS PTR SOA TXT SRV ANY].freeze
+
+    def self.run(argv)
+      options = {
+        type: "A", server: nil, all: false,
+        list_tools: false, matrix: false,
+        help: false, version: false, no_color: false,
+      }
+
+      parser = build_parser(options)
+      begin
+        parser.parse!(argv)
+      rescue OptionParser::ParseError => e
+        warn "错误: #{e.message}"
+        warn "用法: ruby bin/dns-query <目标> [选项]  (用 -h 查看完整帮助)"
+        return 1
+      end
+
+      Color.disabled = true if options[:no_color]
+
+      return print_help(parser)   if options[:help]
+      return print_version        if options[:version]
+      return print_matrix         if options[:matrix]
+      return print_tools          if options[:list_tools]
+
+      target = argv.shift
+      if target.nil?
+        warn "错误: 缺少查询目标（域名或 IP 地址）"
+        warn "用法: ruby bin/dns-query <目标> [选项]  (用 -h 查看完整帮助)"
+        return 1
+      end
+
+      unless argv.empty?
+        warn "注意: 忽略多余参数: #{argv.join(', ')}"
+      end
+
+      unless SUPPORTED_TYPES.include?(options[:type])
+        warn "错误: 不支持的记录类型 #{options[:type]}"
+        warn "支持的类型: #{SUPPORTED_TYPES.join(' / ')}"
+        return 1
+      end
+
+      unless valid_server?(options[:server])
+        warn "错误: DNS 服务器格式非法: #{options[:server]}"
+        warn "仅支持 IP 地址或域名"
+        return 1
+      end
+
+      query = DnsQuery::Query.new(target, qtype: options[:type], server: options[:server])
+      if options[:all]
+        _out, code = query.execute_all
+      else
+        _out, code = query.execute
+      end
+      code
+    end
+
+    def self.build_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = <<~BAN
+          dns-query — 跨平台统一域名查询工具 (network-infra-utility)
+
+          自动检测当前系统可用的 DNS 查询工具 (dig / nslookup / host /
+          Resolve-DnsName 等)，默认使用优先级最高的工具执行查询；
+          目标为 IP 地址时自动反查 PTR 记录。
+
+          用法:
+            ruby bin/dns-query <目标> [选项]
+            ruby bin/dns-query www.baidu.com              # 正查 A 记录
+            ruby bin/dns-query 8.8.8.8                     # 反查 PTR (自动识别 IP)
+            ruby bin/dns-query www.baidu.com -t MX         # 指定记录类型
+            ruby bin/dns-query www.baidu.com -s 8.8.8.8    # 指定 DNS 服务器
+            ruby bin/dns-query www.baidu.com -a            # 用所有可用工具查询
+            ruby bin/dns-query --tools                     # 列出当前平台可用工具
+            ruby bin/dns-query --matrix                    # 全平台工具矩阵
+
+          选项:
+        BAN
+        opts.on("-t", "--type TYPE", "DNS 记录类型 (A/AAAA/CNAME/MX/NS/PTR/SOA/TXT/SRV/ANY)，默认 A") do |v|
+          options[:type] = v.upcase
+        end
+        opts.on("-s", "--server SERVER", "指定 DNS 服务器 (IP 或域名)") do |v|
+          options[:server] = v
+        end
+        opts.on("-a", "--all", "使用所有可用工具交叉查询") do
+          options[:all] = true
+        end
+        opts.on("--tools", "列出当前平台可用工具") do
+          options[:list_tools] = true
+        end
+        opts.on("--matrix", "显示全平台工具矩阵") do
+          options[:matrix] = true
+        end
+        opts.on("--no-color", "禁用 ANSI 颜色输出") do
+          options[:no_color] = true
+        end
+        opts.on("-v", "--version", "显示版本") do
+          options[:version] = true
+        end
+        opts.on("-h", "--help", "显示帮助") do
+          options[:help] = true
+        end
+      end
+    end
+
+    def self.print_help(parser)
+      puts parser
+      0
+    end
+
+    def self.print_version
+      puts "dns-query #{NetworkInfraUtility::VERSION}"
+      0
+    end
+
+    def self.print_tools
+      DnsQuery::ToolList.print
+      0
+    end
+
+    def self.print_matrix
+      DnsQuery::Matrix.print
+      0
+    end
+
+    def self.valid_server?(server)
+      return true if server.nil? || server.empty?
+      server.match?(/\A[0-9A-Za-z.\-:\[\]]+\z/)
+    end
+  end
+end
+
+# 仅作为命令行执行时运行 CLI；被 require 时只提供模块能力
+exit DnsQuery::CLI.run(ARGV) if __FILE__ == $PROGRAM_NAME