pvectl 0.2.0

data/lib/pvectl/commands/template_command.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Template-specific functionality built on IrreversibleCommand.
+    #
+    # Converts VMs/containers to Proxmox templates (irreversible operation).
+    # Filters out resources that are already templates with a warning.
+    # Calls the repository's convert_to_template method for each resource.
+    #
+    # @example Including in a command class
+    #   class TemplateVm
+    #     include TemplateCommand
+    #     RESOURCE_TYPE = :vm
+    #     SUPPORTED_RESOURCES = %w[vm].freeze
+    #   end
+    #
+    module TemplateCommand
+      include IrreversibleCommand
+
+      # Hook called when module is included.
+      #
+      # @param base [Class] the class including this module
+      def self.included(base)
+        base.extend(IrreversibleCommand::ClassMethods)
+      end
+
+      private
+
+      # Overrides perform_operation to filter already-template resources.
+      #
+      # @return [Integer] exit code
+      def perform_operation
+        load_config
+        connection = Pvectl::Connection.new(@config)
+
+        resources = resolve_resources(connection)
+        return no_resources_found if resources.empty?
+
+        # Filter out already-template resources with warning
+        convertible, already_templates = resources.partition { |r| !r.template? }
+
+        already_templates.each do |r|
+          type_name = resource_type_symbol == :vm ? "VM" : "Container"
+          $stderr.puts "Warning: #{type_name} #{r.vmid} is already a template, skipping"
+        end
+
+        return ExitCodes::SUCCESS if convertible.empty?
+        return ExitCodes::SUCCESS unless confirm_operation(convertible)
+
+        results = perform_service_call(convertible, connection)
+        output_results(results)
+        determine_exit_code(results)
+      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
+
+      # Confirms template operation — uses --yes flag.
+      #
+      # @param resources [Array] Resources to convert
+      # @return [Boolean] true if operation should proceed
+      def confirm_operation(resources)
+        return true if @options[:yes]
+
+        $stdout.puts confirm_message(resources)
+        $stdout.puts ""
+        $stdout.puts irreversibility_warning
+        $stdout.print "Proceed? [y/N]: "
+
+        response = $stdin.gets&.strip&.downcase
+        %w[y yes].include?(response)
+      end
+
+      # Returns confirmation message for template conversion.
+      #
+      # @param resources [Array] resources to convert
+      # @return [String] confirmation message
+      def confirm_message(resources)
+        type_name = resource_type_symbol == :vm ? "VM" : "container"
+        type_plural = resource_type_symbol == :vm ? "VMs" : "containers"
+
+        if resources.size == 1
+          r = resources.first
+          "You are about to convert #{type_name} #{r.vmid} (#{r.name || 'unnamed'}) on #{r.node} to a template."
+        else
+          lines = ["You are about to convert #{resources.size} #{type_plural} to templates:"]
+          resources.each { |r| lines << "  - #{r.vmid} (#{r.name || 'unnamed'}) on #{r.node}" }
+          lines.join("\n")
+        end
+      end
+
+      # Returns irreversibility warning for template conversion.
+      #
+      # @return [String] warning text
+      def irreversibility_warning
+        "This action is IRREVERSIBLE. Templates cannot be converted back and cannot be started."
+      end
+
+      # Performs template conversion for each resource.
+      #
+      # @param resources [Array] resources to convert
+      # @param connection [Connection] API connection
+      # @return [Array<Models::OperationResult>] results
+      def perform_service_call(resources, connection)
+        repo = build_repository(connection)
+        @task_repository = Pvectl::Repositories::Task.new(connection) if @options[:force]
+        resources.map do |resource|
+          convert_single(repo, resource)
+        end
+      end
+
+      # Converts a single resource to template.
+      # Handles running resources: errors without --force, stops with --force.
+      #
+      # @param repo [Repositories::Base] repository
+      # @param resource [Models::Vm, Models::Container] resource to convert
+      # @return [Models::OperationResult] result
+      def convert_single(repo, resource)
+        if resource.status == "running"
+          return running_error(resource) unless @options[:force]
+
+          stop_result = stop_resource(repo, resource)
+          return stop_result if stop_result.failed?
+        end
+
+        if resource_type_symbol == :vm
+          repo.convert_to_template(resource.vmid, resource.node, disk: @options[:disk])
+        else
+          repo.convert_to_template(resource.vmid, resource.node)
+        end
+
+        build_success_result(resource)
+      rescue StandardError => e
+        build_error_result(resource, e.message)
+      end
+
+      # Returns error result for a running resource without --force.
+      #
+      # @param resource [Models::Vm, Models::Container] resource
+      # @return [Models::OperationResult] failed result
+      def running_error(resource)
+        type_name = resource_type_symbol == :vm ? "VM" : "Container"
+        build_error_result(resource, "#{type_name} #{resource.vmid} is running. Stop it first or use --force")
+      end
+
+      # Stops a running resource before template conversion.
+      #
+      # @param repo [Repositories::Base] repository
+      # @param resource [Models::Vm, Models::Container] resource
+      # @return [Models::OperationResult] result
+      def stop_resource(repo, resource)
+        upid = repo.stop(resource.vmid, resource.node)
+        timeout = @options[:timeout] || 60
+        task = @task_repository.wait(upid, timeout: timeout)
+
+        if task.successful?
+          build_success_result(resource)
+        else
+          build_error_result(resource, "Failed to stop: #{task.exitstatus}")
+        end
+      end
+
+      # Builds a successful operation result.
+      #
+      # @param resource [Models::Vm, Models::Container] resource
+      # @return [Models::OperationResult] success result
+      def build_success_result(resource)
+        result_class = resource_type_symbol == :vm ? Models::VmOperationResult : Models::ContainerOperationResult
+        attrs = { operation: :template, success: true }
+        attrs[resource_type_symbol == :vm ? :vm : :container] = resource
+        result_class.new(attrs)
+      end
+
+      # Builds an error operation result.
+      #
+      # @param resource [Models::Vm, Models::Container] resource
+      # @param error_message [String] error message
+      # @return [Models::OperationResult] error result
+      def build_error_result(resource, error_message)
+        result_class = resource_type_symbol == :vm ? Models::VmOperationResult : Models::ContainerOperationResult
+        attrs = { operation: :template, success: false, error: error_message }
+        attrs[resource_type_symbol == :vm ? :vm : :container] = resource
+        result_class.new(attrs)
+      end
+
+      # Builds presenter for template results.
+      #
+      # @return [Presenters::Base] presenter
+      def build_presenter
+        if resource_type_symbol == :vm
+          Pvectl::Presenters::VmOperationResult.new
+        else
+          Pvectl::Presenters::ContainerOperationResult.new
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/commands/template_container.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl template container` command.
+    #
+    # Converts one or more containers to templates (irreversible).
+    # Always requires confirmation (--yes to skip).
+    # Running containers must be stopped first or use --force.
+    #
+    # @example Convert a single container
+    #   pvectl template container 200 --yes
+    #
+    # @example Convert using ct alias
+    #   pvectl template ct 200 --yes
+    #
+    # @example Force convert running container
+    #   pvectl template container 200 --force --yes
+    #
+    class TemplateContainer
+      include TemplateCommand
+
+      RESOURCE_TYPE = :container
+      SUPPORTED_RESOURCES = %w[container ct].freeze
+    end
+  end
+end

data/lib/pvectl/commands/template_vm.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl template vm` command.
+    #
+    # Converts one or more VMs to templates (irreversible).
+    # Always requires confirmation (--yes to skip).
+    # Running VMs must be stopped first or use --force.
+    #
+    # @example Convert a single VM
+    #   pvectl template vm 100 --yes
+    #
+    # @example Convert multiple VMs
+    #   pvectl template vm 100 101 102 --yes
+    #
+    # @example Force convert running VM (stops it first)
+    #   pvectl template vm 100 --force --yes
+    #
+    # @example Convert specific disk only
+    #   pvectl template vm 100 --disk scsi0 --yes
+    #
+    class TemplateVm
+      include TemplateCommand
+
+      # Registers the template command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Convert a resource to a template (irreversible)"
+        cli.long_desc <<~HELP
+          Convert a virtual machine or container into a Proxmox template.
+          Templates are read-only base images used for linked cloning.
+
+          WARNING: This operation is irreversible. Once converted, the resource
+          cannot be converted back to a regular VM/container.
+
+          EXAMPLES
+            Convert a stopped VM to template:
+              $ pvectl template vm 100 --yes
+
+            Convert a running VM (stops it first):
+              $ pvectl template vm 100 --force --yes
+
+            Convert multiple VMs:
+              $ pvectl template vm 100 101 102 --yes
+
+            Convert a container:
+              $ pvectl template ct 200 --yes
+
+          NOTES
+            The resource must be stopped before conversion. Use --force to
+            automatically stop a running resource before converting.
+
+            --yes skips the confirmation prompt. Without it, you will be
+            asked to confirm the irreversible operation.
+
+          SEE ALSO
+            pvectl help clone           Create linked clones from templates
+            pvectl help get templates   List existing templates
+        HELP
+        cli.arg_name "RESOURCE_TYPE [ID...]"
+        cli.command :template do |c|
+          c.desc "Skip confirmation prompt"
+          c.switch [:yes, :y], negatable: false
+
+          c.desc "Force stop running VM/container before conversion"
+          c.switch [:force, :f], negatable: false
+
+          c.desc "Filter by node name"
+          c.flag [:node, :n], arg_name: "NODE"
+
+          c.desc "Filter by selector (e.g., status=stopped,tags=base)"
+          c.flag [:l, :selector], arg_name: "SELECTOR", multiple: true
+
+          c.desc "Select all resources of this type"
+          c.switch [:all, :A], negatable: false
+
+          c.desc "Specific disk to convert (VM only, e.g., scsi0)"
+          c.flag [:disk], arg_name: "DISK"
+
+          c.action do |global_options, options, args|
+            resource_type = args.shift
+
+            exit_code = case resource_type
+            when "vm"
+              Commands::TemplateVm.execute(resource_type, args, options, global_options)
+            when "container", "ct"
+              Commands::TemplateContainer.execute(resource_type, 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/top/command.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    module Top
+      # Dispatcher for the `pvectl top <resource_type>` command.
+      #
+      # Displays resource usage metrics (CPU, memory, disk, swap) for
+      # cluster resources. Supports nodes, VMs, and containers.
+      #
+      # Uses Top::ResourceRegistry for handler lookup and Top-specific
+      # presenters for metrics-focused display. VMs and containers are
+      # filtered to running-only by default (use --all to show all).
+      #
+      # @example Basic usage
+      #   Commands::Top::Command.execute("nodes", options, global_options)
+      #
+      class Command
+        # Resource types where running-only filtering does NOT apply.
+        SHOW_ALL_RESOURCE_TYPES = %w[nodes node].freeze
+
+        # Registers the top command with the CLI.
+        #
+        # @param cli [GLI::App] the CLI application object
+        # @return [void]
+        def self.register(cli)
+          cli.desc "Display resource usage metrics (CPU, memory, disk)"
+          cli.long_desc <<~HELP
+            Display real-time resource usage metrics for cluster resources.
+            Shows CPU, memory, disk, and network utilization in a table format.
+
+            By default, only running VMs and containers are shown. Use --all to
+            include stopped resources. Nodes always show all (including offline).
+
+            RESOURCE TYPES
+              nodes                     Cluster node metrics
+              vms                       Virtual machine metrics (running only by default)
+              containers                Container metrics (running only by default)
+
+            EXAMPLES
+              Cluster node resource usage:
+                $ pvectl top nodes
+
+              VMs sorted by CPU usage:
+                $ pvectl top vms --sort-by cpu
+
+              All containers including stopped:
+                $ pvectl top containers --all
+
+              Memory usage in JSON format:
+                $ pvectl top vms --sort-by memory -o json
+
+            NOTES
+              Sort fields: cpu, memory, disk, netin, netout, name, node.
+
+              Stopped VMs/containers show 0% for all metrics. Use --all
+              if you need to see them alongside running resources.
+
+            SEE ALSO
+              pvectl help get           List resources with status info
+              pvectl help describe      Detailed resource information
+          HELP
+          cli.arg_name "RESOURCE_TYPE"
+          cli.command :top do |c|
+            c.desc "Sort by field (cpu, memory, disk, netin, netout, name, node)"
+            c.flag [:"sort-by"], arg_name: "FIELD"
+
+            c.desc "Show all (including stopped)"
+            c.switch [:all], default_value: false
+
+            c.action do |global_options, options, args|
+              resource_type = args[0]
+              exit_code = execute(resource_type, options, global_options)
+              exit exit_code if exit_code != 0
+            end
+          end
+        end
+
+        # Executes the top command.
+        #
+        # @param resource_type [String, nil] type of resource (e.g., "nodes")
+        # @param options [Hash] command-specific options
+        #   - :"sort-by" [String] sort field (cpu, memory, disk)
+        # @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
+        def self.execute(resource_type, options, global_options)
+          new(resource_type, options, global_options).execute
+        end
+
+        # Creates a new Top command instance.
+        #
+        # @param resource_type [String, nil] type of resource
+        # @param options [Hash] command options
+        # @param global_options [Hash] global CLI options
+        # @param handler [Object, nil] override handler for testing
+        # @param registry [Class] resource registry (default: Top::ResourceRegistry)
+        def initialize(resource_type, options, global_options,
+                       handler: nil, registry: Top::ResourceRegistry)
+          @resource_type = resource_type
+          @options = options
+          @global_options = global_options
+          @handler = handler
+          @registry = registry
+        end
+
+        # Executes the top operation.
+        #
+        # @return [Integer] exit code
+        def execute
+          return missing_resource_type_error if @resource_type.nil?
+
+          handler = @handler || @registry.for(@resource_type)
+          return unknown_resource_error unless handler
+
+          models = handler.list(sort: @options[:"sort-by"])
+          models = filter_running(models) unless @options[:all]
+          output = format_output(models, handler.presenter)
+          puts output
+
+          ExitCodes::SUCCESS
+        rescue Pvectl::Config::ConfigNotFoundError,
+               Pvectl::Config::InvalidConfigError,
+               Pvectl::Config::ContextNotFoundError,
+               Pvectl::Config::ClusterNotFoundError,
+               Pvectl::Config::UserNotFoundError => e
+          $stderr.puts "Error: #{e.message}"
+          ExitCodes::CONFIG_ERROR
+        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
+        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 top RESOURCE_TYPE [options]"
+          $stderr.puts "Available resources: nodes, vms, containers"
+          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}"
+          $stderr.puts "Available resources: nodes, vms, containers"
+          ExitCodes::USAGE_ERROR
+        end
+
+        # Filters models to running-only for VM/CT resource types.
+        # Nodes always show all (offline nodes are important info).
+        #
+        # @param models [Array<Object>] models to filter
+        # @return [Array<Object>] filtered models
+        def filter_running(models)
+          return models if SHOW_ALL_RESOURCE_TYPES.include?(@resource_type)
+          return models unless models.first.respond_to?(:running?)
+
+          models.select(&:running?)
+        end
+
+        # Outputs connection error message.
+        #
+        # @param message [String] the error message
+        # @return [void]
+        def output_connection_error(message)
+          $stderr.puts "Error: #{message}"
+        end
+
+        # Formats models for output using the appropriate formatter.
+        #
+        # @param models [Array<Object>] collection of models
+        # @param presenter [Presenters::Base] presenter for the resource type
+        # @return [String] formatted output
+        def format_output(models, presenter)
+          format = @global_options[:output] || "table"
+          color_enabled = determine_color_enabled
+          formatter = Formatters::Registry.for(format)
+          formatter.format(models, presenter, color_enabled: 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

data/lib/pvectl/commands/top/handlers/containers.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    module Top
+      module Handlers
+        # Handler for Top command container metrics display.
+        #
+        # Wraps Get::Handlers::Containers to fetch container data and pairs it
+        # with TopContainer presenter for metrics-focused output.
+        #
+        # @example Using via ResourceRegistry
+        #   handler = Top::ResourceRegistry.for("containers")
+        #   containers = handler.list(sort: "cpu")
+        #   presenter = handler.presenter
+        #
+        # @see Pvectl::Commands::Get::Handlers::Containers Get handler
+        # @see Pvectl::Presenters::TopContainer Top presenter
+        #
+        class Containers
+          include Top::ResourceHandler
+
+          # Creates handler with optional Get handler for dependency injection.
+          #
+          # @param get_handler [Get::Handlers::Containers, nil] handler (default: create new)
+          def initialize(get_handler: nil)
+            @get_handler = get_handler
+          end
+
+          # Lists containers with optional sorting.
+          #
+          # @param sort [String, nil] sort field (cpu, memory, disk)
+          # @return [Array<Models::Container>] collection of Container models
+          def list(sort: nil, **_)
+            get_handler.list(sort: sort)
+          end
+
+          # Returns Top-specific presenter for containers.
+          #
+          # @return [Presenters::TopContainer] TopContainer presenter instance
+          def presenter
+            Presenters::TopContainer.new
+          end
+
+          private
+
+          # Returns Get handler, creating it if necessary.
+          #
+          # @return [Get::Handlers::Containers] Containers get handler
+          def get_handler
+            @get_handler ||= Get::Handlers::Containers.new
+          end
+        end
+      end
+    end
+  end
+end
+
+Pvectl::Commands::Top::ResourceRegistry.register(
+  "containers", Pvectl::Commands::Top::Handlers::Containers, aliases: ["container", "cts", "ct"]
+)

data/lib/pvectl/commands/top/handlers/nodes.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    module Top
+      module Handlers
+        # Handler for Top command node metrics display.
+        #
+        # Wraps Get::Handlers::Nodes to fetch node data and pairs it
+        # with TopNode presenter for metrics-focused output.
+        #
+        # @example Using via ResourceRegistry
+        #   handler = Top::ResourceRegistry.for("nodes")
+        #   nodes = handler.list(sort: "cpu")
+        #   presenter = handler.presenter
+        #
+        # @see Pvectl::Commands::Get::Handlers::Nodes Get handler
+        # @see Pvectl::Presenters::TopNode Top presenter
+        #
+        class Nodes
+          include Top::ResourceHandler
+
+          # Creates handler with optional Get handler for dependency injection.
+          #
+          # @param get_handler [Get::Handlers::Nodes, nil] handler (default: create new)
+          def initialize(get_handler: nil)
+            @get_handler = get_handler
+          end
+
+          # Lists nodes with optional sorting.
+          #
+          # @param sort [String, nil] sort field (cpu, memory, disk)
+          # @return [Array<Models::Node>] collection of Node models
+          def list(sort: nil, **_)
+            get_handler.list(sort: sort)
+          end
+
+          # Returns Top-specific presenter for nodes.
+          #
+          # @return [Presenters::TopNode] TopNode presenter instance
+          def presenter
+            Presenters::TopNode.new
+          end
+
+          private
+
+          # Returns Get handler, creating it if necessary.
+          #
+          # @return [Get::Handlers::Nodes] Nodes get handler
+          def get_handler
+            @get_handler ||= Get::Handlers::Nodes.new
+          end
+        end
+      end
+    end
+  end
+end
+
+Pvectl::Commands::Top::ResourceRegistry.register(
+  "nodes", Pvectl::Commands::Top::Handlers::Nodes, aliases: ["node"]
+)