pvectl 0.2.0

data/lib/pvectl/commands/feature_command.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Shared functionality for the feature query commands (feature vm, feature ct).
+    #
+    # Queries whether a Proxmox feature (clone, snapshot, copy) is available for
+    # a given VM or container. Availability depends on storage type, snapshot
+    # state, and other server-side conditions.
+    #
+    # Designed with the hybrid Template Method pattern (MoveDiskCommand /
+    # MigrateCommand) — specializations only set RESOURCE_TYPE and
+    # SUPPORTED_RESOURCES; the FeatureVm specialization additionally implements
+    # +.register+ which wires the GLI command.
+    #
+    # @example Including in a command class
+    #   class FeatureVm
+    #     include FeatureCommand
+    #     RESOURCE_TYPE = :vm
+    #     SUPPORTED_RESOURCES = %w[vm].freeze
+    #   end
+    #
+    module FeatureCommand
+      # Valid feature names per Proxmox API (both QEMU and LXC endpoints).
+      VALID_FEATURES = %w[clone snapshot copy].freeze
+
+      # Class methods added when the module is included.
+      module ClassMethods
+        # Executes the feature query command.
+        #
+        # @param args [Array<String>] command-positional args ([id, feature])
+        # @param options [Hash] command options
+        # @param global_options [Hash] global CLI options
+        # @return [Integer] exit code
+        def execute(args, options, global_options)
+          new(args, options, global_options).execute
+        end
+      end
+
+      # Hook called when the module is included.
+      #
+      # @param base [Class] the class including this module
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Initializes a feature query command.
+      #
+      # @param args [Array<String>] command-positional args ([id, feature])
+      # @param options [Hash] command options
+      # @param global_options [Hash] global CLI options
+      def initialize(args, options, global_options)
+        @args = Array(args).compact
+        @options = options
+        @global_options = global_options
+      end
+
+      # Executes the feature query.
+      #
+      # @return [Integer] exit code (0 if available, 1 if unavailable, 2 on usage)
+      def execute
+        return usage_error("#{id_label} is required") if @args.empty?
+        return usage_error("FEATURE is required") if @args.size < 2
+
+        id_str = @args[0]
+        feature = @args[1]
+
+        unless id_str.to_s.match?(/\A\d+\z/)
+          return usage_error("Invalid #{id_label}: #{id_str}")
+        end
+
+        unless VALID_FEATURES.include?(feature)
+          return usage_error(
+            "Invalid feature: #{feature} (allowed: #{VALID_FEATURES.join(', ')})"
+          )
+        end
+
+        perform_operation(id_str.to_i, feature)
+      end
+
+      private
+
+      # Returns the resource type symbol (:vm or :container).
+      #
+      # @return [Symbol]
+      def resource_type_symbol
+        self.class::RESOURCE_TYPE
+      end
+
+      # Returns the human label for the resource ID ("VMID" or "CTID").
+      #
+      # @return [String]
+      def id_label
+        resource_type_symbol == :vm ? "VMID" : "CTID"
+      end
+
+      # Returns the singular type name ("VM" or "container") used in error messages.
+      #
+      # @return [String]
+      def type_name
+        resource_type_symbol == :vm ? "VM" : "container"
+      end
+
+      # Performs the feature availability check.
+      #
+      # @param id [Integer] resource identifier
+      # @param feature [String] feature name
+      # @return [Integer] exit code
+      def perform_operation(id, feature)
+        load_config
+        connection = Pvectl::Connection.new(@config)
+
+        resource = resolve_resource(connection, id)
+        return resource_not_found(id) if resource.nil?
+
+        result = build_repository(connection)
+          .feature_available?(id, resource.node, feature, snapname: @options[:snapname])
+
+        output_result(result, feature)
+        result[:available] ? ExitCodes::SUCCESS : ExitCodes::GENERAL_ERROR
+      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
+
+      # Resolves the resource (VM or container) by ID using the appropriate repository.
+      #
+      # @param connection [Connection] API connection
+      # @param id [Integer] resource ID
+      # @return [Models::Vm, Models::Container, nil]
+      def resolve_resource(connection, id)
+        build_repository(connection).get(id)
+      end
+
+      # Builds the resource repository (VM or Container) for the current type.
+      #
+      # @param connection [Connection] API connection
+      # @return [Repositories::Vm, Repositories::Container]
+      def build_repository(connection)
+        if resource_type_symbol == :vm
+          Pvectl::Repositories::Vm.new(connection)
+        else
+          Pvectl::Repositories::Container.new(connection)
+        end
+      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
+
+      # Outputs the result in the requested format.
+      #
+      # Plain output: "available"/"unavailable" + optional list of capable nodes.
+      # JSON/YAML output: structured hash with feature metadata.
+      #
+      # @param result [Hash] result from +feature_available?+ (:available, :nodes)
+      # @param feature [String] feature name
+      # @return [void]
+      def output_result(result, feature)
+        format = (@global_options[:output] || "plain").to_s
+
+        case format
+        when "json"
+          require "json"
+          $stdout.puts JSON.pretty_generate(payload(result, feature))
+        when "yaml"
+          require "yaml"
+          $stdout.puts YAML.dump(stringify_keys(payload(result, feature)))
+        else
+          status = result[:available] ? "available" : "unavailable"
+          $stdout.puts status
+          if result[:available] && !result[:nodes].empty?
+            $stdout.puts "nodes: #{result[:nodes].join(', ')}"
+          end
+        end
+      end
+
+      # Builds the structured result payload for JSON/YAML output.
+      #
+      # @param result [Hash] feature_available? result
+      # @param feature [String] feature name
+      # @return [Hash]
+      def payload(result, feature)
+        {
+          available: result[:available],
+          feature: feature,
+          snapname: @options[:snapname],
+          nodes: result[:nodes]
+        }
+      end
+
+      # Converts symbol keys to strings for YAML output.
+      #
+      # @param hash [Hash]
+      # @return [Hash]
+      def stringify_keys(hash)
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      end
+
+      # Outputs usage error and returns the usage exit code.
+      #
+      # @param message [String]
+      # @return [Integer]
+      def usage_error(message)
+        $stderr.puts "Error: #{message}"
+        ExitCodes::USAGE_ERROR
+      end
+
+      # Outputs "not found" error and returns the not-found exit code.
+      #
+      # @param id [Integer]
+      # @return [Integer]
+      def resource_not_found(id)
+        $stderr.puts "Error: No #{type_name} found with ID #{id}"
+        ExitCodes::NOT_FOUND
+      end
+    end
+  end
+end

data/lib/pvectl/commands/feature_container.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl feature ct` command.
+    #
+    # Queries whether a Proxmox feature (clone, snapshot, copy) is available
+    # for an LXC container. The LXC feature endpoint returns only +hasFeature+
+    # (no +nodes+ list), so the +nodes+ column is always empty.
+    #
+    # @example Check whether container 200 supports snapshot
+    #   pvectl feature ct 200 snapshot
+    #
+    class FeatureContainer
+      include FeatureCommand
+
+      RESOURCE_TYPE = :container
+      SUPPORTED_RESOURCES = %w[container ct].freeze
+    end
+  end
+end

data/lib/pvectl/commands/feature_vm.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl feature vm` command.
+    #
+    # Queries whether a Proxmox feature (clone, snapshot, copy) is available
+    # for a virtual machine. Availability depends on storage type, snapshot
+    # state, and other server-side conditions.
+    #
+    # Also registers the top-level `feature` GLI command and dispatches
+    # to FeatureVm or FeatureContainer based on the resource type.
+    #
+    # @example Check whether VM 100 can be cloned
+    #   pvectl feature vm 100 clone
+    #
+    # @example Check snapshot feature against a specific snapshot
+    #   pvectl feature vm 100 snapshot --snapname pre-upgrade
+    #
+    class FeatureVm
+      include FeatureCommand
+
+      # Registers the feature command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Query whether a feature (clone/snapshot/copy) is available"
+        cli.long_desc <<~HELP
+          Check whether a Proxmox feature is available for a VM or container.
+          Availability depends on the storage type backing the disks, current
+          snapshot state, and other server-side conditions.
+
+          Exit code is 0 when the feature is available, 1 when unavailable,
+          5 when the resource is not found, and 2 on invalid usage.
+
+          EXAMPLES
+            Check whether VM 100 can be cloned:
+              $ pvectl feature vm 100 clone
+
+            Check snapshot feature on a container with a specific snapshot:
+              $ pvectl feature ct 200 snapshot --snapname pre-upgrade
+
+            Check copy feature for a VM:
+              $ pvectl feature vm 100 copy
+
+            JSON output (machine-readable):
+              $ pvectl feature vm 100 clone -o json
+
+          NOTES
+            Supported features: clone, snapshot, copy.
+
+            The Proxmox API returns the list of cluster nodes that can host
+            the resource after the requested feature is applied. For VMs the
+            list is printed under the "nodes:" line; for containers the LXC
+            endpoint does not return this list.
+
+            --snapname is required for some checks (e.g. checking whether a
+            specific snapshot can be removed or cloned from).
+
+          SEE ALSO
+            pvectl help clone           Clone a VM or container
+            pvectl help create snapshot Create a snapshot
+            pvectl help get snapshots   List snapshots
+        HELP
+        cli.arg_name "RESOURCE_TYPE ID FEATURE"
+        cli.command :feature do |c|
+          c.desc "Snapshot name (optional, required for some checks)"
+          c.flag [:snapname], arg_name: "NAME"
+
+          c.action do |global_options, options, args|
+            resource_type = args.shift
+
+            exit_code = case resource_type
+            when "vm"
+              Commands::FeatureVm.execute(args, options, global_options)
+            when "container", "ct"
+              Commands::FeatureContainer.execute(args, options, global_options)
+            else
+              $stderr.puts "Error: Unknown resource type: #{resource_type}"
+              $stderr.puts "Valid types: vm, container, ct"
+              ExitCodes::USAGE_ERROR
+            end
+
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+
+      RESOURCE_TYPE = :vm
+      SUPPORTED_RESOURCES = %w[vm].freeze
+    end
+  end
+end

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

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    module Get
+      # Dispatcher for the `pvectl get <resource_type>` command.
+      #
+      # Routes requests to appropriate resource handlers based on the
+      # resource type argument. Supports watch mode for continuous
+      # monitoring and node filtering.
+      #
+      # Responsibilities:
+      # - Control flow (watch vs single execution)
+      # - Handler lookup via ResourceRegistry
+      # - Error handling for unknown resources and handler exceptions
+      #
+      # Delegates to:
+      # - Services::Get::ResourceService for data fetching and formatting
+      #
+      # @example Basic usage
+      #   Commands::Get::Command.execute("nodes", nil, options, global_options)
+      #
+      # @example With watch mode
+      #   options = { watch: true, :"watch-interval" => 5 }
+      #   Commands::Get::Command.execute("vms", nil, options, global_options)
+      #
+      class Command
+        # Registers the get command with the CLI.
+        #
+        # @param cli [GLI::App] the CLI application object
+        # @return [void]
+        def self.register(cli)
+          cli.desc "List resources in cluster"
+          cli.long_desc <<~HELP
+            List resources across the Proxmox cluster. Supports multiple resource
+            types including nodes, VMs, containers, storage, snapshots, backups,
+            templates, and tasks.
+
+            Results can be filtered by node (--node), formatted in different output
+            modes (-o), and auto-refreshed with watch mode (-w).
+
+            RESOURCE TYPES
+              nodes (node)              Cluster nodes
+              vms (vm)                  Virtual machines
+              containers (ct, cts)      LXC containers
+              storage (stor)            Storage pools
+              snapshots (snap)          VM/CT snapshots
+              backups (backup)          Backup volumes
+              templates (template)      VM and container templates
+              tasks (task)              Task history
+              disks (disk)              Physical disks (block devices)
+              volumes (volume, vol)     Virtual disks attached to VMs/containers
+              time                      Node time and timezone settings
+              node-capabilities (caps)  Supported QEMU CPU models and machine types
+              subscription (sub)        Proxmox subscription status per node
+
+            EXAMPLES
+              List all VMs in table format:
+                $ pvectl get vms
+
+              List containers on a specific node as JSON:
+                $ pvectl get containers --node pve1 -o json
+
+              List snapshots for specific VMs:
+                $ pvectl get snapshots --vmid 100 --vmid 101
+
+              Watch cluster nodes with 5-second refresh:
+                $ pvectl get nodes -w --watch-interval 5
+
+              Filter tasks by type and date:
+                $ pvectl get tasks --type vzdump --since 2026-01-01
+
+              Wide output with extra columns:
+                $ pvectl get vms -o wide
+
+              Filter VMs by status (shortcut):
+                $ pvectl get vms --status running
+
+              Filter VMs by selector (supports status, name, tags, pool):
+                $ pvectl get vms -l status=running
+                $ pvectl get vms -l status=running,tags=prod
+                $ pvectl get vms -l name=~web-*
+
+              List VM volumes:
+                $ pvectl get volume vm 100
+
+              List volumes from storage:
+                $ pvectl get volume --storage local-lvm
+
+              List volumes with filtering:
+                $ pvectl get volume vm 100 -l format=raw
+
+              Show node time and timezone for a single node:
+                $ pvectl get time --node pve1
+
+              Show time and timezone for all online nodes:
+                $ pvectl get time
+
+              List supported CPU models / machine types for a node:
+                $ pvectl get node-capabilities --node pve1
+                $ pvectl get caps --node pve1 -o json
+
+              List subscription status across the cluster:
+                $ pvectl get subscription
+
+              Show full license key for one node (key is masked by default):
+                $ pvectl get subscription --node pve1 -o wide
+
+            NOTES
+              Use selectors (-l) to filter VMs/containers by status, name, tags, or
+              pool. Multiple selectors use AND logic. The --status flag is a shortcut
+              for -l status=VALUE and can be combined with other selectors.
+
+              Task listing defaults to 50 entries; use --limit to change.
+
+              Watch mode clears the screen on each refresh. Press Ctrl+C to stop.
+
+            SEE ALSO
+              pvectl help describe    Show detailed info about a single resource
+              pvectl help top         Display real-time resource usage metrics
+              pvectl help logs        Show logs and task history
+          HELP
+          cli.command :get do |c|
+            c.desc "Filter by node name"
+            c.flag [:node], arg_name: "NODE"
+
+            c.desc "Filter by VM/CT ID (repeatable)"
+            c.flag [:vmid], arg_name: "VMID", multiple: true
+
+            c.desc "Filter by storage (for backups)"
+            c.flag [:storage], arg_name: "STORAGE"
+
+            c.desc "Watch for changes with auto-refresh"
+            c.switch [:watch, :w], negatable: false
+
+            c.desc "Watch refresh interval in seconds (default: 2, minimum: 1)"
+            c.default_value 2
+            c.flag [:"watch-interval"], arg_name: "SECONDS", type: Integer
+
+            c.desc "Maximum number of entries to show (for tasks)"
+            c.default_value 50
+            c.flag [:limit], type: Integer, arg_name: "N"
+
+            c.desc "Show entries since timestamp (YYYY-MM-DD or epoch, for tasks)"
+            c.flag [:since], arg_name: "TIMESTAMP"
+
+            c.desc "Show entries until timestamp (YYYY-MM-DD or epoch, for tasks)"
+            c.flag [:until], arg_name: "TIMESTAMP"
+
+            c.desc "Filter by task type (e.g., qmstart, qmstop, vzdump)"
+            c.flag [:type], arg_name: "TYPE"
+
+            c.desc "Filter by status (running, stopped for VMs/CTs; running, ok, error for tasks)"
+            c.flag [:status], arg_name: "STATUS"
+
+            c.desc "Filter by selector (e.g., status=running,tags=prod)"
+            c.flag [:l, :selector], arg_name: "SELECTOR", multiple: true
+
+            c.desc "Search across all cluster nodes (default for tasks)"
+            c.switch [:"all-nodes"], negatable: false
+
+            c.action do |global_options, options, args|
+              resource_type = args[0]
+              resource_args = args[1..] || []
+              exit_code = execute(resource_type, resource_args, options, global_options)
+              exit exit_code if exit_code != 0
+            end
+          end
+        end
+
+        # Executes the get command.
+        #
+        # @param resource_type [String, nil] type of resource to list (e.g., "nodes", "vms")
+        # @param args [String, Array, nil] positional arguments (VMIDs for snapshots, or name filter)
+        # @param options [Hash] command-specific options
+        #   - :watch [Boolean] enable continuous monitoring
+        #   - :"watch-interval" [Integer] refresh interval in seconds
+        #   - :node [String] filter by node name
+        # @param global_options [Hash] global CLI options
+        #   - :output [String] output format (table, json, yaml, wide)
+        #   - :color [Boolean, nil] explicit color setting
+        # @return [Integer] exit code (0 for success, 2 for unknown resource)
+        def self.execute(resource_type, args, options, global_options)
+          new(resource_type, args, options, global_options).execute
+        end
+
+        # Creates a new Get command instance.
+        #
+        # @param resource_type [String, nil] type of resource to list
+        # @param args [String, Array, nil] positional arguments
+        # @param options [Hash] command options
+        # @param global_options [Hash] global CLI options
+        # @param registry [Class] registry class for dependency injection (default: ResourceRegistry)
+        def initialize(resource_type, args, options, global_options,
+                       registry: ResourceRegistry)
+          @resource_type = resource_type
+          @args = normalize_args(args)
+          @options = options
+          @global_options = global_options
+          @registry = registry
+        end
+
+        # Executes the get operation.
+        #
+        # @return [Integer] exit code
+        def execute
+          return missing_resource_type_error if @resource_type.nil?
+
+          handler = @registry.for(@resource_type)
+          return unknown_resource_error unless handler
+
+          if @options[:watch]
+            run_watch_mode(handler)
+          else
+            run_once(handler)
+          end
+
+          ExitCodes::SUCCESS
+        rescue Timeout::Error => e
+          output_connection_error(e.message)
+          ExitCodes::CONNECTION_ERROR
+        rescue Errno::ECONNREFUSED => e
+          output_connection_error(e.message)
+          ExitCodes::CONNECTION_ERROR
+        rescue SocketError => e
+          output_connection_error(e.message)
+          ExitCodes::CONNECTION_ERROR
+        rescue ArgumentError => e
+          output_usage_error(e.message)
+          ExitCodes::USAGE_ERROR
+        end
+
+        private
+
+        attr_reader :resource_type, :args, :options, :global_options
+
+        # Normalizes args to an array.
+        #
+        # @param args [String, Array, nil] input args
+        # @return [Array<String>] normalized args array
+        def normalize_args(args)
+          case args
+          when nil then []
+          when Array then args
+          else [args.to_s]
+          end
+        end
+
+        # 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 get RESOURCE_TYPE [NAME] [options]"
+          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
+
+        # Outputs connection error message.
+        #
+        # @param message [String] the error message
+        # @return [void]
+        def output_connection_error(message)
+          $stderr.puts "Error: #{message}"
+        end
+
+        # Outputs usage error message.
+        #
+        # @param message [String] the error message
+        # @return [void]
+        def output_usage_error(message)
+          $stderr.puts "Error: #{message}"
+        end
+
+        # Executes a single fetch and display operation.
+        #
+        # @param handler [ResourceHandler] the resource handler
+        # @return [void]
+        def run_once(handler)
+          service = build_service(handler)
+          selector = build_selector(handler)
+          output = service.list(
+            node: options[:node],
+            name: nil,
+            args: args,
+            storage: options[:storage],
+            vmid: options[:vmid],
+            limit: options[:limit],
+            since: options[:since],
+            until_time: options[:until],
+            type_filter: options[:type],
+            status_filter: options[:status],
+            all_nodes: options[:"all-nodes"] || false,
+            selector: selector
+          )
+          puts output
+        end
+
+        # Executes watch mode with continuous refresh.
+        #
+        # @param handler [ResourceHandler] the resource handler
+        # @return [void]
+        def run_watch_mode(handler)
+          interval = options[:"watch-interval"] || WatchLoop::DEFAULT_INTERVAL
+          watch_loop = WatchLoop.new(interval: interval)
+          watch_loop.run { run_once(handler) }
+        end
+
+        # Builds a selector from -l and --status flags for client-side filtering.
+        #
+        # For handlers that declare a selector_class (VMs, Containers), --status
+        # is translated into a selector condition. For handlers without selector
+        # support (e.g., tasks), --status is passed through as status_filter.
+        #
+        # @param handler [ResourceHandler] the resource handler
+        # @return [Selectors::Base, nil] parsed selector or nil if not applicable
+        def build_selector(handler)
+          selector_class = handler.selector_class
+          return nil unless selector_class
+
+          selector_strings = Array(options[:selector])
+          selector_strings << "status=#{options[:status]}" if options[:status]
+
+          return nil if selector_strings.empty?
+
+          selector_class.parse_all(selector_strings)
+        end
+
+        # Builds the service for the given handler.
+        #
+        # @param handler [ResourceHandler] the resource handler
+        # @return [Services::Get::ResourceService] the service instance
+        def build_service(handler)
+          Services::Get::ResourceService.new(
+            handler: handler,
+            format: global_options[:output] || "table",
+            color_enabled: determine_color_enabled
+          )
+        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