pvectl 0.2.0

data/lib/pvectl/commands/describe/command.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    module Describe
+      # Dispatcher for the `pvectl describe <resource_type> <name>` command.
+      #
+      # Uses EXISTING Get infrastructure:
+      # - Commands::Get::ResourceRegistry for handler lookup
+      # - Services::Get::ResourceService for orchestration
+      # - Handlers call describe() instead of list()
+      #
+      # @example Basic usage
+      #   Commands::Describe::Command.execute("node", "pve1", options, global_options)
+      #
+      class Command
+        # Registers the describe command with the CLI.
+        #
+        # @param cli [GLI::App] the CLI application object
+        # @return [void]
+        def self.register(cli)
+          cli.desc "Show detailed information about a resource"
+          cli.long_desc <<~HELP
+            Show detailed information about a specific resource. Displays all
+            configuration details, runtime status, and related resources in
+            structured, labeled sections.
+
+            Unlike 'get' which lists many resources in a table, 'describe' shows
+            everything known about a single resource in a readable format.
+            Unknown or future Proxmox config keys appear in an "Additional
+            Configuration" catch-all section, so new API fields are never hidden.
+
+            RESOURCE TYPES
+              node NAME                 Full node diagnostics (CPU, memory, storage, services)
+              vm VMID                   Comprehensive VM configuration (see VM SECTIONS below)
+              container VMID            Comprehensive container configuration (see CT SECTIONS below)
+              storage NAME              Storage pool info, content types, usage
+              snapshot NAME             Snapshot metadata and snapshot tree (use --vmid)
+              volume TYPE ID DISK       Virtual disk details (e.g., describe volume vm 100 scsi0)
+
+            VM SECTIONS (matches PVE web UI tabs)
+              Summary        HA state, CPU/memory usage, bootdisk size, uptime,
+                             QEMU version, machine type, network/disk I/O
+              Block Device Statistics
+                             Per-disk I/O counters (read/written bytes, IOPS)
+                             for running VMs
+              Hardware       Memory (with balloon details: actual, max, free
+                             and total inside guest when ballooning active),
+                             balloon, processors, BIOS, machine, display,
+                             SCSI controller, EFI/TPM, disks, network, USB/PCI,
+                             serial ports, audio
+              Cloud-Init     Type, user, DNS, SSH keys, IP config
+              Options        Start at boot, startup order, OS type, boot order,
+                             tablet, hotplug, ACPI, KVM, freeze, localtime,
+                             NUMA, QEMU guest agent, protection, firewall,
+                             hookscript
+              Firewall       Enable, input/output policies, aliases, IP sets
+              Firewall Rules Per-rule table (ENABLED, TYPE, ACTION, PROTO,
+                             SOURCE, DEST, COMMENT)
+              Task History   Recent operations (type, status, date, duration, user)
+              Snapshots      Name, date, VM state, description
+              Pending        Configuration changes awaiting reboot
+              Additional     Catch-all for unrecognized config keys
+
+            CT SECTIONS (matches PVE web UI tabs)
+              Summary        CPU/memory/swap/rootfs usage, uptime, PID, network I/O
+              Resources      Memory, swap, cores, root filesystem, mountpoints
+              Network        Interfaces with bridge, IP, MAC
+              DNS            Nameserver, search domain
+              Options        Start at boot, startup order, OS type, architecture,
+                             unprivileged, features, console mode, TTY, protection,
+                             hookscript
+              Firewall       Enable, input/output policies, aliases, IP sets
+              Firewall Rules Per-rule table (ENABLED, TYPE, ACTION, PROTO,
+                             SOURCE, DEST, COMMENT)
+              Task History   Recent operations (type, status, date, duration, user)
+              Snapshots      Name, date, description
+              High Avail.    HA state and group
+              Additional     Catch-all for unrecognized config keys
+
+            EXAMPLES
+              Full node diagnostics:
+                $ pvectl describe node pve1
+
+              VM details — all configuration sections:
+                $ pvectl describe vm 100
+
+              Container details — all configuration sections:
+                $ pvectl describe container 200
+
+              Storage pool information (node-specific):
+                $ pvectl describe storage local-lvm --node pve1
+
+              Snapshot metadata for a specific VM:
+                $ pvectl describe snapshot before-upgrade --vmid 100
+
+              Snapshot search across multiple VMs:
+                $ pvectl describe snapshot before-upgrade --vmid 100 --vmid 101
+
+              Snapshot search cluster-wide (all VMs and containers):
+                $ pvectl describe snapshot before-upgrade
+
+              Virtual disk details:
+                $ pvectl describe volume vm 100 scsi0
+
+              Container rootfs:
+                $ pvectl describe volume ct 200 rootfs
+
+            NOTES
+              For local storage, --node is required because local storage exists
+              independently on each node.
+
+              Snapshot describe shows a visual tree of all snapshots for the
+              matching VMs, highlighting the described snapshot.
+
+              VM and container describe output includes ALL configuration from
+              the Proxmox API. Any fields not recognized by the presenter are
+              grouped in the "Additional Configuration" section at the end.
+
+            SEE ALSO
+              pvectl help get           List resources in table format
+              pvectl help get volume    List virtual disks attached to VMs/containers
+              pvectl help logs          Show task history and logs
+          HELP
+          cli.arg_name "RESOURCE_TYPE NAME"
+          cli.command :describe do |c|
+            c.desc "Filter by node name (required for local storage)"
+            c.flag [:node], arg_name: "NODE"
+
+            c.desc "Filter by VM/CT ID (repeatable)"
+            c.flag [:vmid], arg_name: "VMID", multiple: true
+
+            c.action do |global_options, options, args|
+              resource_type = args[0]
+              resource_name = args[1]
+              extra_args = args[2..] || []
+              exit_code = execute(resource_type, resource_name, options, global_options, extra_args: extra_args)
+              exit exit_code if exit_code != 0
+            end
+          end
+        end
+
+        # Executes the describe command.
+        #
+        # @param resource_type [String, nil] type of resource (e.g., "node")
+        # @param resource_name [String, nil] name of resource to describe
+        # @param options [Hash] command-specific options
+        # @param global_options [Hash] global CLI options
+        # @return [Integer] exit code
+        def self.execute(resource_type, resource_name, options, global_options, extra_args: [])
+          new(resource_type, resource_name, options, global_options, extra_args: extra_args).execute
+        end
+
+        # Creates a new Describe command instance.
+        #
+        # @param resource_type [String, nil] type of resource
+        # @param resource_name [String, nil] name of resource to describe
+        # @param options [Hash] command options
+        # @param global_options [Hash] global CLI options
+        # @param registry [Class] registry class for dependency injection
+        def initialize(resource_type, resource_name, options, global_options,
+                       extra_args: [], registry: Get::ResourceRegistry)
+          @resource_type = resource_type
+          @resource_name = resource_name
+          @options = options
+          @global_options = global_options
+          @extra_args = extra_args
+          @registry = registry
+        end
+
+        # Executes the describe operation.
+        #
+        # @return [Integer] exit code
+        def execute
+          return missing_resource_type_error if @resource_type.nil?
+          return missing_resource_name_error if @resource_name.nil?
+
+          handler = @registry.for(@resource_type)
+          return unknown_resource_error unless handler
+
+          run_describe(handler)
+          ExitCodes::SUCCESS
+        rescue Pvectl::ResourceNotFoundError => e
+          $stderr.puts "Error: #{e.message}"
+          ExitCodes::NOT_FOUND
+        rescue Timeout::Error => e
+          $stderr.puts "Error: #{e.message}"
+          ExitCodes::CONNECTION_ERROR
+        rescue Errno::ECONNREFUSED => e
+          $stderr.puts "Error: #{e.message}"
+          ExitCodes::CONNECTION_ERROR
+        rescue SocketError => e
+          $stderr.puts "Error: #{e.message}"
+          ExitCodes::CONNECTION_ERROR
+        end
+
+        private
+
+        # Outputs error for missing resource type argument.
+        #
+        # @return [Integer] USAGE_ERROR exit code
+        def missing_resource_type_error
+          $stderr.puts "Error: resource type is required"
+          $stderr.puts "Usage: pvectl describe RESOURCE_TYPE NAME"
+          ExitCodes::USAGE_ERROR
+        end
+
+        # Outputs error for missing resource name argument.
+        #
+        # @return [Integer] USAGE_ERROR exit code
+        def missing_resource_name_error
+          $stderr.puts "Error: resource name is required"
+          $stderr.puts "Usage: pvectl describe #{@resource_type} NAME"
+          ExitCodes::USAGE_ERROR
+        end
+
+        # Outputs error for unknown resource type.
+        #
+        # @return [Integer] USAGE_ERROR exit code
+        def unknown_resource_error
+          $stderr.puts "Unknown resource type: #{@resource_type}"
+          ExitCodes::USAGE_ERROR
+        end
+
+        # Runs the describe operation with the given handler.
+        #
+        # @param handler [ResourceHandler] the resource handler
+        # @return [void]
+        def run_describe(handler)
+          service = Services::Get::ResourceService.new(
+            handler: handler,
+            format: @global_options[:output] || "table",
+            color_enabled: determine_color_enabled
+          )
+          output = service.describe(name: @resource_name, node: @options[:node], args: @extra_args, vmid: @options[:vmid])
+          puts output
+        end
+
+        # Determines if color output should be enabled.
+        #
+        # @return [Boolean] true if color should be enabled
+        def determine_color_enabled
+          explicit = @global_options[:color]
+          return explicit unless explicit.nil?
+
+          $stdout.tty?
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/commands/edit_container.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl edit container` command.
+    #
+    # Includes EditResourceCommand for shared workflow and overrides
+    # template methods with container-specific behavior.
+    #
+    # @example Basic usage
+    #   pvectl edit container 200
+    #
+    # @example With custom editor
+    #   pvectl edit container 200 --editor nano
+    #
+    # @example Dry-run mode
+    #   pvectl edit container 200 --dry-run
+    #
+    class EditContainer
+      include EditResourceCommand
+
+      private
+
+      # @return [String] human label for container resources
+      def resource_label
+        "container"
+      end
+
+      # @return [String] human label for container IDs
+      def resource_id_label
+        "CTID"
+      end
+
+      # Builds execution parameters from a container ID.
+      #
+      # @param resource_id [String] CTID (converted to Integer)
+      # @return [Hash] parameters for the edit service
+      def execute_params(resource_id)
+        { ctid: resource_id.to_i }
+      end
+
+      # Builds the container edit service.
+      #
+      # @param connection [Connection] API connection
+      # @return [Services::EditContainer] container edit service
+      def build_edit_service(connection)
+        ct_repo = Pvectl::Repositories::Container.new(connection)
+        Pvectl::Services::EditContainer.new(
+          container_repository: ct_repo,
+          editor_session: build_editor_session,
+          options: service_options
+        )
+      end
+    end
+  end
+end

data/lib/pvectl/commands/edit_dns.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl edit dns` command.
+    #
+    # Opens the DNS resolver configuration for a node in a YAML editor.
+    # On save, applies the changes via PUT /nodes/{node}/dns.
+    #
+    # The node identifier may be supplied either as a positional argument
+    # (matching `pvectl edit node NAME` semantics) or via the --node flag.
+    #
+    # @example Basic usage
+    #   pvectl edit dns pve1
+    #   pvectl edit dns --node pve1
+    #
+    # @example Dry-run mode
+    #   pvectl edit dns pve1 --dry-run
+    #
+    class EditDns
+      # Executes the edit dns command.
+      #
+      # @param args [Array<String>] command arguments (positional NODE)
+      # @param options [Hash] command options (:node, :editor, :"dry-run")
+      # @param global_options [Hash] global CLI options
+      # @return [Integer] exit code
+      def self.execute(args, options, global_options)
+        new(args, options, global_options).execute
+      end
+
+      # Initializes the command.
+      #
+      # @param args [Array<String>] command arguments
+      # @param options [Hash] command options
+      # @param global_options [Hash] global CLI options
+      def initialize(args, options, global_options)
+        @args = args
+        @options = options
+        @global_options = global_options
+      end
+
+      # Executes the edit flow.
+      #
+      # @return [Integer] exit code
+      def execute
+        node_name = @args.first || @options[:node]
+        return usage_error("NODE is required (positional argument or --node flag)") unless node_name && !node_name.empty?
+
+        load_config
+        connection = Pvectl::Connection.new(@config)
+        service = build_edit_service(connection)
+        result = service.execute(node_name: node_name)
+
+        if result.nil?
+          $stdout.puts "Edit cancelled, no changes made."
+          return ExitCodes::SUCCESS
+        end
+
+        if result.successful?
+          display_diff(result)
+          if @options[:"dry-run"]
+            $stdout.puts "(dry-run mode — no changes applied)"
+          else
+            $stdout.puts "DNS configuration for node #{node_name} updated successfully."
+          end
+          ExitCodes::SUCCESS
+        else
+          $stderr.puts "Error: #{result.error}"
+          ExitCodes::GENERAL_ERROR
+        end
+      rescue Pvectl::Config::ConfigNotFoundError,
+             Pvectl::Config::InvalidConfigError,
+             Pvectl::Config::ContextNotFoundError,
+             Pvectl::Config::ClusterNotFoundError,
+             Pvectl::Config::UserNotFoundError
+        raise
+      rescue StandardError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::GENERAL_ERROR
+      end
+
+      private
+
+      # Builds the EditDns service with a connection.
+      #
+      # @param connection [Connection] API connection
+      # @return [Services::EditDns]
+      def build_edit_service(connection)
+        dns_repo = Pvectl::Repositories::Dns.new(connection)
+        Pvectl::Services::EditDns.new(
+          dns_repository: dns_repo,
+          editor_session: build_editor_session,
+          options: service_options
+        )
+      end
+
+      # Displays a formatted diff from the operation result.
+      #
+      # @param result [Models::NodeOperationResult] operation result with diff
+      # @return [void]
+      def display_diff(result)
+        diff = result.resource&.dig(:diff)
+        return unless diff
+        return if diff[:changed].empty? && diff[:added].empty? && diff[:removed].empty?
+
+        $stdout.puts "\nChanges:"
+        $stdout.puts Pvectl::ConfigSerializer.format_diff(diff)
+        $stdout.puts ""
+      end
+
+      # Loads configuration from file or environment.
+      #
+      # @return [void]
+      def load_config
+        service = Pvectl::Config::Service.new
+        service.load(config: @global_options[:config])
+        @config = service.current_config
+      end
+
+      # Builds service options from CLI options.
+      #
+      # @return [Hash] service options
+      def service_options
+        opts = {}
+        opts[:dry_run] = true if @options[:"dry-run"]
+        opts
+      end
+
+      # Builds an editor session from --editor option.
+      #
+      # @return [EditorSession, nil] editor session or nil if no --editor flag
+      def build_editor_session
+        editor_cmd = @options[:editor]
+        return nil unless editor_cmd
+
+        Pvectl::EditorSession.new(editor: ->(path) { system(editor_cmd, path) })
+      end
+
+      # Outputs usage error and returns exit code.
+      #
+      # @param message [String] error message
+      # @return [Integer] exit code
+      def usage_error(message)
+        $stderr.puts "Error: #{message}"
+        ExitCodes::USAGE_ERROR
+      end
+    end
+  end
+end

data/lib/pvectl/commands/edit_hosts.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl edit hosts` command.
+    #
+    # Opens /etc/hosts for a node in the user's editor. On save, POSTs the
+    # new content back via /nodes/{node}/hosts with the original digest for
+    # optimistic concurrency control.
+    #
+    # The node identifier may be supplied either as a positional argument
+    # (matching `pvectl edit node NAME` semantics) or via the --node flag.
+    #
+    # @example Basic usage
+    #   pvectl edit hosts pve1
+    #   pvectl edit hosts --node pve1
+    #
+    # @example Dry-run mode
+    #   pvectl edit hosts pve1 --dry-run
+    #
+    class EditHosts
+      # Executes the edit hosts command.
+      #
+      # @param args [Array<String>] command arguments (positional NODE)
+      # @param options [Hash] command options (:node, :editor, :"dry-run")
+      # @param global_options [Hash] global CLI options
+      # @return [Integer] exit code
+      def self.execute(args, options, global_options)
+        new(args, options, global_options).execute
+      end
+
+      # Initializes the command.
+      #
+      # @param args [Array<String>] command arguments
+      # @param options [Hash] command options
+      # @param global_options [Hash] global CLI options
+      def initialize(args, options, global_options)
+        @args = args
+        @options = options
+        @global_options = global_options
+      end
+
+      # Executes the edit flow.
+      #
+      # @return [Integer] exit code
+      def execute
+        node_name = @args.first || @options[:node]
+        return usage_error("NODE is required (positional argument or --node flag)") if node_name.nil? || node_name.empty?
+
+        load_config
+        connection = Pvectl::Connection.new(@config)
+        service = build_edit_service(connection)
+        result = service.execute(node_name: node_name)
+
+        if result.nil?
+          $stdout.puts "Edit cancelled, no changes made."
+          return ExitCodes::SUCCESS
+        end
+
+        if result.successful?
+          if @options[:"dry-run"]
+            $stdout.puts "(dry-run mode — no changes applied)"
+          else
+            $stdout.puts "/etc/hosts on node #{node_name} updated successfully."
+          end
+          ExitCodes::SUCCESS
+        else
+          $stderr.puts "Error: #{result.error}"
+          ExitCodes::GENERAL_ERROR
+        end
+      rescue Pvectl::Config::ConfigNotFoundError,
+             Pvectl::Config::InvalidConfigError,
+             Pvectl::Config::ContextNotFoundError,
+             Pvectl::Config::ClusterNotFoundError,
+             Pvectl::Config::UserNotFoundError
+        raise
+      rescue StandardError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::GENERAL_ERROR
+      end
+
+      private
+
+      # Builds the EditHosts service with a connection.
+      #
+      # @param connection [Connection] API connection
+      # @return [Services::EditHosts]
+      def build_edit_service(connection)
+        hosts_repo = Pvectl::Repositories::Hosts.new(connection)
+        Pvectl::Services::EditHosts.new(
+          hosts_repository: hosts_repo,
+          editor_session: build_editor_session,
+          options: service_options
+        )
+      end
+
+      # Loads configuration from file or environment.
+      #
+      # @return [void]
+      def load_config
+        service = Pvectl::Config::Service.new
+        service.load(config: @global_options[:config])
+        @config = service.current_config
+      end
+
+      # Builds service options from CLI options.
+      #
+      # @return [Hash] service options
+      def service_options
+        opts = {}
+        opts[:dry_run] = true if @options[:"dry-run"]
+        opts
+      end
+
+      # Builds an editor session from --editor option.
+      #
+      # @return [EditorSession, nil] editor session or nil if no --editor flag
+      def build_editor_session
+        editor_cmd = @options[:editor]
+        return nil unless editor_cmd
+
+        Pvectl::EditorSession.new(editor: ->(path) { system(editor_cmd, path) })
+      end
+
+      # Outputs usage error and returns exit code.
+      #
+      # @param message [String] error message
+      # @return [Integer] exit code
+      def usage_error(message)
+        $stderr.puts "Error: #{message}"
+        ExitCodes::USAGE_ERROR
+      end
+    end
+  end
+end

data/lib/pvectl/commands/edit_node.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl edit node` command.
+    #
+    # Includes EditResourceCommand for shared workflow and overrides
+    # template methods with node-specific behavior.
+    #
+    # @example Basic usage
+    #   pvectl edit node pve1
+    #
+    # @example Dry-run mode
+    #   pvectl edit node pve1 --dry-run
+    #
+    class EditNode
+      include EditResourceCommand
+
+      private
+
+      # @return [String] human label for node resources
+      def resource_label
+        "node"
+      end
+
+      # @return [String] human label for node IDs
+      def resource_id_label
+        "NODE"
+      end
+
+      # Builds execution parameters from a node name.
+      # Node uses string name (not integer ID).
+      #
+      # @param resource_id [String] node name
+      # @return [Hash] parameters for the edit service
+      def execute_params(resource_id)
+        { node_name: resource_id }
+      end
+
+      # Builds the node edit service.
+      #
+      # @param connection [Connection] API connection
+      # @return [Services::EditNode] node edit service
+      def build_edit_service(connection)
+        node_repo = Pvectl::Repositories::Node.new(connection)
+        Pvectl::Services::EditNode.new(
+          node_repository: node_repo,
+          editor_session: build_editor_session,
+          options: service_options
+        )
+      end
+    end
+  end
+end