pvectl 0.2.0

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

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

data/lib/pvectl/commands/top/resource_handler.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    module Top
+      # Interface module for Top command handlers.
+      #
+      # Each handler wraps a Get handler and returns a Top-specific presenter
+      # for metrics-focused display (CPU%, MEM%, etc.).
+      #
+      # @abstract Include in handler class and implement required methods.
+      #
+      # @example Implementing a handler
+      #   class NodesHandler
+      #     include Top::ResourceHandler
+      #
+      #     def list(sort: nil, **_)
+      #       get_handler.list(sort: sort)
+      #     end
+      #
+      #     def presenter
+      #       Presenters::TopNode.new
+      #     end
+      #   end
+      #
+      module ResourceHandler
+        # Lists resources with optional sorting.
+        #
+        # @param options [Hash] keyword arguments (e.g., sort:)
+        # @return [Array<Object>] collection of model objects
+        # @raise [NotImplementedError] if not implemented by including class
+        def list(**options)
+          raise NotImplementedError, "#{self.class}#list must be implemented"
+        end
+
+        # Returns the Top-specific presenter for this resource type.
+        #
+        # @return [Presenters::Base] presenter instance
+        # @raise [NotImplementedError] if not implemented by including class
+        def presenter
+          raise NotImplementedError, "#{self.class}#presenter must be implemented"
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/commands/top/resource_registry.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    module Top
+      # Registry for Top command resource handlers.
+      #
+      # Inherits registration and lookup from Commands::ResourceRegistry,
+      # maintaining its own isolated set of handlers.
+      #
+      # @example Registering a handler
+      #   Top::ResourceRegistry.register("nodes", Handlers::Nodes, aliases: ["node"])
+      #
+      # @example Looking up a handler
+      #   handler = Top::ResourceRegistry.for("nodes")
+      #
+      # @see Pvectl::Commands::ResourceRegistry Base registry
+      #
+      class ResourceRegistry < Commands::ResourceRegistry; end
+    end
+  end
+end

data/lib/pvectl/commands/unlink_disk_vm.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl unlink disk vm` command.
+    #
+    # Removes one or more disks from a VM configuration. By default, the
+    # disk entry is converted to `unused[n]` (the underlying volume is
+    # preserved). With `--force`, the underlying volume is physically
+    # deleted.
+    #
+    # @example Soft unlink (keeps volume as unused0)
+    #   pvectl unlink disk vm 100 scsi1
+    #
+    # @example Unlink multiple disks
+    #   pvectl unlink disk vm 100 scsi1,virtio0
+    #
+    # @example Hard delete the underlying volume
+    #   pvectl unlink disk vm 100 scsi1 --force --yes
+    #
+    class UnlinkDiskVm
+      # Registers the unlink command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Unlink a disk from a resource"
+        cli.long_desc <<~HELP
+          DESCRIPTION
+            Remove one or more disks from a VM configuration.
+
+            By default, the disk entry is moved to `unused[n]` in the VM
+            config — the underlying volume is preserved so it can be
+            re-attached or inspected later. With --force, the underlying
+            volume is physically deleted and cannot be recovered.
+
+            Multiple disks may be removed in a single call by passing a
+            comma-separated list (e.g. "scsi1,virtio0").
+
+          EXAMPLES
+            Soft unlink (keeps the volume as unused0):
+              $ pvectl unlink disk vm 100 scsi1
+
+            Unlink multiple disks at once:
+              $ pvectl unlink disk vm 100 scsi1,virtio0
+
+            Permanently delete the underlying volume:
+              $ pvectl unlink disk vm 100 scsi1 --force --yes
+
+            Skip confirmation prompt:
+              $ pvectl unlink disk vm 100 scsi1 -y
+
+          NOTES
+            --force is destructive: the underlying volume is removed and
+            cannot be recovered. Without --force, the volume can be
+            re-attached later (e.g. via `pvectl set vm`).
+
+            The command operates only on QEMU virtual machines; LXC
+            containers are not supported by the Proxmox /unlink endpoint.
+
+          SEE ALSO
+            pvectl help describe vm     Show VM configuration including disks
+            pvectl help edit volume     Edit volume properties interactively
+            pvectl help set vm          Modify VM configuration (re-attach unused)
+        HELP
+        cli.arg_name "RESOURCE_TYPE ID DISK_LIST"
+        cli.command :unlink do |c|
+          c.desc "Skip confirmation prompt"
+          c.switch [:yes, :y], negatable: false
+
+          c.desc "Physically delete the underlying volume(s)"
+          c.switch [:force], negatable: false
+
+          c.action do |global_options, options, args|
+            resource_type = args.shift
+            scope = args.shift
+
+            exit_code = case [resource_type, scope]
+            when %w[disk vm]
+              Commands::UnlinkDiskVm.execute(args, options, global_options)
+            else
+              $stderr.puts "Error: Unknown unlink target: #{resource_type} #{scope}".strip
+              $stderr.puts "Valid form: unlink disk vm <id> <disk_list>"
+              ExitCodes::USAGE_ERROR
+            end
+
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+
+      # Executes the unlink disk vm command.
+      #
+      # @param args [Array<String>] command arguments (VMID, DISK_LIST)
+      # @param options [Hash] command options
+      # @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
+
+      # @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 unlink disk vm command.
+      #
+      # @return [Integer] exit code
+      def execute
+        vmid_arg = @args[0]
+        disk_list = @args[1]
+
+        return usage_error("VMID required") if vmid_arg.nil? || vmid_arg.to_s.empty?
+        return usage_error("Disk list required (e.g., scsi1 or scsi1,virtio0)") if disk_list.nil? || disk_list.to_s.empty?
+        return usage_error("Invalid VMID: #{vmid_arg}") unless vmid_arg.to_s.match?(/\A\d+\z/)
+
+        vmid = vmid_arg.to_i
+        load_config
+        node = resolve_node(vmid)
+        return ExitCodes::NOT_FOUND if node.nil?
+
+        return ExitCodes::SUCCESS unless confirm_operation(vmid, disk_list)
+
+        repo = build_repository
+        service = Pvectl::Services::UnlinkDisk.new(repository: repo)
+        result = service.execute(
+          vmid: vmid,
+          node: node,
+          disk_ids: disk_list,
+          force: @options[:force] == true
+        )
+
+        output_result(result)
+        result.failed? ? ExitCodes::GENERAL_ERROR : ExitCodes::SUCCESS
+      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
+
+      # Loads configuration.
+      #
+      # @return [void]
+      def load_config
+        service = Pvectl::Config::Service.new
+        service.load(config: @global_options[:config])
+        @config = service.current_config
+      end
+
+      # Resolves the node for a VMID.
+      #
+      # @param vmid [Integer] VM identifier
+      # @return [String, nil] node name or nil if not found
+      def resolve_node(vmid)
+        connection = Pvectl::Connection.new(@config)
+        resolver = Pvectl::Utils::ResourceResolver.new(connection)
+        resolved = resolver.resolve(vmid)
+
+        unless resolved && resolved[:type] == :qemu
+          $stderr.puts "Error: VM #{vmid} not found"
+          return nil
+        end
+
+        resolved[:node]
+      end
+
+      # Builds the VM repository.
+      #
+      # @return [Repositories::Vm] VM repository
+      def build_repository
+        connection = Pvectl::Connection.new(@config)
+        Pvectl::Repositories::Vm.new(connection)
+      end
+
+      # Confirms the unlink operation with the user, if not auto-approved.
+      #
+      # @param vmid [Integer] VM identifier
+      # @param disk_list [String] comma-separated disk list
+      # @return [Boolean] true to proceed, false to cancel
+      def confirm_operation(vmid, disk_list)
+        return true if @options[:yes]
+
+        $stdout.puts "About to unlink disk(s) #{disk_list} from VM #{vmid}."
+        if @options[:force]
+          $stdout.puts ""
+          $stdout.puts "WARNING: --force will delete the underlying volume(s) permanently."
+          $stdout.puts ""
+        end
+        $stdout.print "Proceed? [y/N]: "
+        $stdout.flush
+
+        answer = $stdin.gets&.strip&.downcase
+        answer == "y"
+      end
+
+      # Outputs the operation result via the configured formatter.
+      #
+      # @param result [Models::VmOperationResult] operation result
+      # @return [void]
+      def output_result(result)
+        presenter = Pvectl::Presenters::VmOperationResult.new
+        format = @global_options[:output] || "table"
+        color_flag = @global_options[:color]
+
+        formatter = Pvectl::Formatters::Registry.for(format)
+        output = formatter.format([result], presenter, color: color_flag)
+        $stdout.puts output
+      end
+
+      # Outputs a usage error message and returns the corresponding exit code.
+      #
+      # @param message [String] error message
+      # @return [Integer] usage error exit code
+      def usage_error(message)
+        $stderr.puts "Error: #{message}"
+        ExitCodes::USAGE_ERROR
+      end
+    end
+  end
+end

data/lib/pvectl/commands/vm_lifecycle_command.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # VM-specific lifecycle command hooks.
+    #
+    # Provides VM repository, selector, service, and presenter
+    # to ResourceLifecycleCommand's template methods.
+    #
+    # @example Usage
+    #   class Start
+    #     include VmLifecycleCommand
+    #     OPERATION = :start
+    #   end
+    #
+    module VmLifecycleCommand
+      include ResourceLifecycleCommand
+
+      # Extends the including class with ClassMethods from ResourceLifecycleCommand.
+      #
+      # @param base [Class] the class including this module
+      def self.included(base)
+        base.extend(ResourceLifecycleCommand::ClassMethods)
+      end
+
+      private
+
+      # @return [Array<String>] supported resource types
+      def supported_resources
+        %w[vm]
+      end
+
+      # @return [String] human label for VM resources
+      def resource_label
+        "VM"
+      end
+
+      # @return [String] human label for VM IDs
+      def resource_id_label
+        "VMID"
+      end
+
+      # Builds VM repository.
+      #
+      # @param connection [Connection] API connection
+      # @return [Repositories::Vm] VM repository
+      def build_repository(connection)
+        Pvectl::Repositories::Vm.new(connection)
+      end
+
+      # Builds VM lifecycle service.
+      #
+      # @param repo [Repositories::Vm] VM repository
+      # @param task_repo [Repositories::Task] task repository
+      # @param options [Hash] service options
+      # @return [Services::VmLifecycle] VM lifecycle service
+      def build_service(repo, task_repo, options)
+        Pvectl::Services::VmLifecycle.new(repo, task_repo, options)
+      end
+
+      # Builds VM operation result presenter.
+      #
+      # @return [Presenters::VmOperationResult] presenter
+      def build_presenter
+        Pvectl::Presenters::VmOperationResult.new
+      end
+
+      # Builds VM selector from strings.
+      #
+      # @param strings [Array<String>] selector strings
+      # @return [Selectors::Vm] parsed selector
+      def build_selector(strings)
+        Pvectl::Selectors::Vm.parse_all(strings)
+      end
+    end
+  end
+end

data/lib/pvectl/commands/wakeonlan_node.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl wakeonlan node` command.
+    #
+    # Sends a Wake-on-LAN magic packet to a cluster node. The target node
+    # must have its MAC address registered in the cluster configuration
+    # (via `pvecm` or the web UI) — without it, Proxmox cannot assemble
+    # the packet and the command returns an error.
+    #
+    # The Proxmox API returns the MAC address used for the packet on
+    # success, which is surfaced in the output for confirmation.
+    #
+    # @example Wake up a node
+    #   pvectl wakeonlan node pve3
+    #
+    # @example JSON output for scripting
+    #   pvectl wakeonlan node pve3 -o json
+    #
+    class WakeonlanNode
+      # Registers the `wakeonlan node` command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Send Wake-on-LAN packet to a cluster node"
+        cli.long_desc <<~HELP
+          Trigger a Wake-on-LAN magic packet to a cluster node via the
+          Proxmox API (POST /nodes/{node}/wakeonlan).
+
+          EXAMPLES
+            Wake a node:
+              $ pvectl wakeonlan node pve3
+
+            Output as JSON:
+              $ pvectl wakeonlan node pve3 -o json
+
+          NOTES
+            The target node must have its MAC address registered in the
+            cluster configuration beforehand. Use `pvecm` or the Proxmox
+            web UI to set the MAC for each node before relying on WoL.
+
+            The packet is sent by another online node in the cluster, so
+            at least one other node must be reachable.
+
+          SEE ALSO
+            pvectl help get nodes      List nodes and current status
+            pvectl help describe node  Show node details
+        HELP
+        cli.arg_name "RESOURCE_TYPE NAME"
+        cli.command :wakeonlan do |c|
+          c.action do |global_options, _options, args|
+            resource_type = args.shift
+            resource_name = args.shift
+
+            unless resource_type == "node"
+              $stderr.puts "Error: Only `pvectl wakeonlan node <NAME>` is supported"
+              exit Pvectl::ExitCodes::USAGE_ERROR
+            end
+
+            cmd = WakeonlanNode.new(resource_name, {}, global_options)
+            exit_code = cmd.execute
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+
+      # Creates a new command instance.
+      #
+      # @param node_name [String, nil] target node name
+      # @param options [Hash] command options
+      # @param global_options [Hash] global CLI options
+      # @param service [Services::Wakeonlan, nil] injected service (testing)
+      def initialize(node_name, options, global_options, service: nil)
+        @node_name = node_name
+        @options = options
+        @global_options = global_options
+        @service = service
+      end
+
+      # Executes the wakeonlan command.
+      #
+      # @return [Integer] exit code
+      def execute
+        return usage_error("NODE name is required") if @node_name.nil? || @node_name.to_s.empty?
+
+        result = service.execute(node_name: @node_name)
+        render(result)
+
+        result.successful? ? ExitCodes::SUCCESS : ExitCodes::GENERAL_ERROR
+      rescue Pvectl::Config::ConfigNotFoundError,
+             Pvectl::Config::InvalidConfigError,
+             Pvectl::Config::ContextNotFoundError,
+             Pvectl::Config::ClusterNotFoundError,
+             Pvectl::Config::UserNotFoundError
+        raise
+      rescue Timeout::Error, Errno::ECONNREFUSED, SocketError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::CONNECTION_ERROR
+      rescue StandardError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::GENERAL_ERROR
+      end
+
+      private
+
+      # Lazily builds the Wakeonlan service from current config.
+      #
+      # @return [Services::Wakeonlan]
+      def service
+        @service ||= begin
+          config_service = Pvectl::Config::Service.new
+          config_service.load(config: @global_options[:config])
+          connection = Pvectl::Connection.new(config_service.current_config)
+          node_repo = Pvectl::Repositories::Node.new(connection)
+          Pvectl::Services::Wakeonlan.new(node_repository: node_repo)
+        end
+      end
+
+      # Renders the operation result using the requested output format.
+      #
+      # @param result [Models::NodeOperationResult]
+      # @return [void]
+      def render(result)
+        format = @global_options[:output] || "table"
+        presenter = Pvectl::Presenters::NodeOperationResult.new
+        formatter = Pvectl::Formatters::Registry.for(format)
+        puts formatter.format([result], presenter, color_enabled: color_enabled)
+      end
+
+      # Determines color output based on global flag and TTY status.
+      #
+      # @return [Boolean]
+      def color_enabled
+        explicit = @global_options[:color]
+        return explicit unless explicit.nil?
+
+        $stdout.tty?
+      end
+
+      # Outputs a usage error and returns the proper exit code.
+      #
+      # @param msg [String]
+      # @return [Integer]
+      def usage_error(msg)
+        $stderr.puts "Error: #{msg}"
+        $stderr.puts "Usage: pvectl wakeonlan node <NODE>"
+        ExitCodes::USAGE_ERROR
+      end
+    end
+  end
+end

data/lib/pvectl/config/errors.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Config
+    # Base error class for all configuration-related exceptions.
+    #
+    # All configuration errors inherit from this class, allowing
+    # consumers to catch all config errors with a single rescue clause.
+    #
+    # @example Catching all configuration errors
+    #   begin
+    #     service.load(config: path)
+    #   rescue Pvectl::Config::ConfigError => e
+    #     $stderr.puts "Configuration error: #{e.message}"
+    #     exit Pvectl::ExitCodes::CONFIG_ERROR
+    #   end
+    #
+    class ConfigError < StandardError; end
+
+    # Raised when the configuration file cannot be found at the specified path.
+    #
+    # @example
+    #   raise ConfigNotFoundError, "Configuration file not found: ~/.pvectl/config"
+    #
+    class ConfigNotFoundError < ConfigError; end
+
+    # Raised when the configuration file contains invalid YAML or structure.
+    #
+    # @example
+    #   raise InvalidConfigError, "Invalid YAML syntax at line 5"
+    #
+    class InvalidConfigError < ConfigError; end
+
+    # Raised when a referenced context does not exist in the configuration.
+    #
+    # @example
+    #   raise ContextNotFoundError, "Context 'production' not found"
+    #
+    class ContextNotFoundError < ConfigError; end
+
+    # Raised when a context references a cluster that does not exist.
+    #
+    # @example
+    #   raise ClusterNotFoundError, "Cluster 'main' not found in configuration"
+    #
+    class ClusterNotFoundError < ConfigError; end
+
+    # Raised when a context references a user that does not exist.
+    #
+    # @example
+    #   raise UserNotFoundError, "User 'admin' not found in configuration"
+    #
+    class UserNotFoundError < ConfigError; end
+
+    # Raised when no valid credentials are available for authentication.
+    #
+    # @example
+    #   raise MissingCredentialsError, "No valid credentials found. Provide token or username/password"
+    #
+    class MissingCredentialsError < ConfigError; end
+  end
+end