pvectl 0.2.0

data/lib/pvectl/parsers/cloud_init_config.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Parsers
+    # Parses and converts cloud-init configuration strings for Proxmox VMs.
+    #
+    # CloudInitConfig handles the conversion between user-friendly key=value
+    # cloud-init specifications and the parameter names required by the Proxmox API.
+    # Unlike DiskConfig and NetConfig, all keys are optional.
+    #
+    # @example Parsing a cloud-init config string
+    #   config = CloudInitConfig.parse("user=admin,password=secret,ip=dhcp")
+    #   config[:user]     #=> "admin"
+    #   config[:password]  #=> "secret"
+    #   config[:ip]        #=> "dhcp"
+    #
+    # @example Converting to Proxmox API parameters
+    #   config = { user: "admin", ip: "dhcp" }
+    #   CloudInitConfig.to_proxmox_params(config)
+    #   #=> { ciuser: "admin", ipconfig0: "ip=dhcp" }
+    #
+    class CloudInitConfig
+      # All recognized cloud-init configuration keys.
+      VALID_KEYS = %w[user password sshkeys ip gw nameserver searchdomain].freeze
+
+      # Parses a comma-separated key=value cloud-init config string into a Hash.
+      #
+      # @param string [String] cloud-init config in "key=value,key=value" format
+      # @return [Hash<Symbol, String>] parsed configuration
+      # @raise [ArgumentError] if unknown keys are present
+      #
+      # @example
+      #   CloudInitConfig.parse("user=admin,ip=dhcp,nameserver=8.8.8.8")
+      #   #=> { user: "admin", ip: "dhcp", nameserver: "8.8.8.8" }
+      def self.parse(string)
+        pairs = string.split(",").map { |pair| pair.strip.split("=", 2).map(&:strip) }
+        config = pairs.to_h { |k, v| [k.to_sym, v] }
+
+        validate!(config)
+        config
+      end
+
+      # Converts a parsed cloud-init config Hash to Proxmox API parameter names.
+      #
+      # Maps user-friendly keys to their Proxmox API equivalents:
+      # - +user+ becomes +ciuser+
+      # - +password+ becomes +cipassword+
+      # - +sshkeys+ stays +sshkeys+
+      # - +ip+ becomes +ipconfig0+ with "ip=" prefix
+      # - +nameserver+ stays +nameserver+
+      # - +searchdomain+ stays +searchdomain+
+      #
+      # @param config [Hash<Symbol, String>] parsed cloud-init configuration
+      # @return [Hash<Symbol, String>] Proxmox API parameters
+      #
+      # @example Minimal config
+      #   CloudInitConfig.to_proxmox_params({ user: "admin" })
+      #   #=> { ciuser: "admin" }
+      #
+      # @example With IP and nameserver
+      #   CloudInitConfig.to_proxmox_params({ ip: "dhcp", nameserver: "8.8.8.8" })
+      #   #=> { ipconfig0: "ip=dhcp", nameserver: "8.8.8.8" }
+      def self.to_proxmox_params(config)
+        params = {}
+        params[:ciuser] = config[:user] if config[:user]
+        params[:cipassword] = config[:password] if config[:password]
+        params[:sshkeys] = config[:sshkeys] if config[:sshkeys]
+        if config[:ip]
+          ip_str = "ip=#{config[:ip]}"
+          ip_str += ",gw=#{config[:gw]}" if config[:gw]
+          params[:ipconfig0] = ip_str
+        end
+        params[:nameserver] = config[:nameserver] if config[:nameserver]
+        params[:searchdomain] = config[:searchdomain] if config[:searchdomain]
+        params
+      end
+
+      # Validates that config contains only known keys.
+      #
+      # @param config [Hash<Symbol, String>] parsed cloud-init configuration
+      # @return [void]
+      # @raise [ArgumentError] if unknown keys are present
+      def self.validate!(config)
+        unknown = config.keys.map(&:to_s) - VALID_KEYS
+        unless unknown.empty?
+          raise ArgumentError, "Unknown cloud-init config key(s): #{unknown.join(', ')}"
+        end
+      end
+      private_class_method :validate!
+    end
+  end
+end

data/lib/pvectl/parsers/disk_config.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Parsers
+    # Parses and formats disk configuration strings for Proxmox VMs.
+    #
+    # DiskConfig handles the conversion between user-friendly key=value
+    # disk specifications and the format required by the Proxmox API.
+    #
+    # @example Parsing a disk config string
+    #   config = DiskConfig.parse("storage=local-lvm,size=32G,format=qcow2")
+    #   config[:storage] #=> "local-lvm"
+    #   config[:size]    #=> "32G"
+    #   config[:format]  #=> "qcow2"
+    #
+    # @example Converting to Proxmox API format
+    #   config = { storage: "local-lvm", size: "32G", format: "qcow2" }
+    #   DiskConfig.to_proxmox(config) #=> "local-lvm:32,format=qcow2"
+    #
+    class DiskConfig
+      # All recognized disk configuration keys.
+      VALID_KEYS = %w[storage size format cache discard ssd iothread backup].freeze
+
+      # Keys that must be present in every disk configuration.
+      REQUIRED_KEYS = %w[storage size].freeze
+
+      # Optional flags appended to the Proxmox API string.
+      OPTIONAL_FLAGS = %w[cache discard ssd iothread backup].freeze
+
+      # Parses a comma-separated key=value disk config string into a Hash.
+      #
+      # @param string [String] disk config in "key=value,key=value" format
+      # @return [Hash<Symbol, String>] parsed configuration
+      # @raise [ArgumentError] if unknown keys are present or required keys are missing
+      #
+      # @example
+      #   DiskConfig.parse("storage=local-lvm,size=32G")
+      #   #=> { storage: "local-lvm", size: "32G" }
+      def self.parse(string)
+        pairs = string.split(",").map { |pair| pair.strip.split("=", 2).map(&:strip) }
+        config = pairs.to_h { |k, v| [k.to_sym, v] }
+
+        validate!(config)
+        config
+      end
+
+      # Converts a parsed disk config Hash to a Proxmox API string.
+      #
+      # The Proxmox API expects disk specifications in the format
+      # "storage:size,format=fmt,flag=val". Size is extracted as a
+      # numeric value (without the "G" suffix). Format defaults to "raw"
+      # when not specified.
+      #
+      # @param config [Hash<Symbol, String>] parsed disk configuration
+      # @return [String] Proxmox API-compatible disk string
+      #
+      # @example Minimal config
+      #   DiskConfig.to_proxmox({ storage: "local-lvm", size: "32G" })
+      #   #=> "local-lvm:32,format=raw"
+      #
+      # @example With optional flags
+      #   DiskConfig.to_proxmox({ storage: "local-lvm", size: "32G", cache: "writeback" })
+      #   #=> "local-lvm:32,format=raw,cache=writeback"
+      def self.to_proxmox(config)
+        size_num = config[:size].to_s.gsub(/[^0-9]/, "")
+        format = config[:format] || "raw"
+        parts = ["#{config[:storage]}:#{size_num}", "format=#{format}"]
+
+        OPTIONAL_FLAGS.each do |flag|
+          parts << "#{flag}=#{config[flag.to_sym]}" if config[flag.to_sym]
+        end
+
+        parts.join(",")
+      end
+
+      # Validates that config contains only known keys and all required keys.
+      #
+      # @param config [Hash<Symbol, String>] parsed disk configuration
+      # @return [void]
+      # @raise [ArgumentError] if unknown keys are present or required keys are missing
+      def self.validate!(config)
+        unknown = config.keys.map(&:to_s) - VALID_KEYS
+        unless unknown.empty?
+          raise ArgumentError, "Unknown disk config key(s): #{unknown.join(', ')}"
+        end
+
+        REQUIRED_KEYS.each do |key|
+          value = config[key.to_sym]
+          if value.nil? || value.strip.empty?
+            raise ArgumentError, "Missing required disk config key: #{key}"
+          end
+        end
+      end
+      private_class_method :validate!
+    end
+  end
+end

data/lib/pvectl/parsers/lxc_mount_config.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Parsers
+    # Parses and formats LXC mount configurations for Proxmox containers.
+    #
+    # Handles rootfs and mountpoint (mp0, mp1, ...) configuration strings.
+    # Format: key=value pairs separated by commas.
+    #
+    # @example Parsing a rootfs config
+    #   config = LxcMountConfig.parse("storage=local-lvm,size=8G")
+    #   config[:storage] #=> "local-lvm"
+    #   config[:size]    #=> "8G"
+    #
+    # @example Converting to Proxmox API format
+    #   LxcMountConfig.to_proxmox({ storage: "local-lvm", size: "8G" })
+    #   #=> "local-lvm:8"
+    #
+    #   LxcMountConfig.to_proxmox({ storage: "local-lvm", size: "32G", mp: "/mnt/data" })
+    #   #=> "local-lvm:32,mp=/mnt/data"
+    #
+    class LxcMountConfig
+      # All recognized mount configuration keys.
+      VALID_KEYS = %w[storage size mp acl backup quota replicate ro shared].freeze
+
+      # Keys that must be present in every mount configuration.
+      REQUIRED_KEYS = %w[storage size].freeze
+
+      # Optional flags appended to the Proxmox API string.
+      OPTIONAL_FLAGS = %w[acl backup quota replicate ro shared].freeze
+
+      # Parses a comma-separated key=value mount config string into a Hash.
+      #
+      # @param string [String] mount config in "key=value,key=value" format
+      # @return [Hash<Symbol, String>] parsed configuration
+      # @raise [ArgumentError] if unknown keys are present or required keys are missing
+      #
+      # @example
+      #   LxcMountConfig.parse("storage=local-lvm,size=8G")
+      #   #=> { storage: "local-lvm", size: "8G" }
+      def self.parse(string)
+        pairs = string.split(",").map { |pair| pair.strip.split("=", 2).map(&:strip) }
+        config = pairs.to_h { |k, v| [k.to_sym, v] }
+
+        validate!(config)
+        config
+      end
+
+      # Converts a parsed mount config Hash to a Proxmox API string.
+      #
+      # The Proxmox API expects mount specifications in the format
+      # "storage:size[,mp=/path][,flag=val]". Size is extracted as a
+      # numeric value (without the "G" suffix).
+      #
+      # @param config [Hash<Symbol, String>] parsed mount configuration
+      # @return [String] Proxmox API-compatible mount string
+      #
+      # @example Rootfs config
+      #   LxcMountConfig.to_proxmox({ storage: "local-lvm", size: "8G" })
+      #   #=> "local-lvm:8"
+      #
+      # @example Mountpoint with path and flags
+      #   LxcMountConfig.to_proxmox({ storage: "local-lvm", size: "32G", mp: "/mnt/data", backup: "1" })
+      #   #=> "local-lvm:32,mp=/mnt/data,backup=1"
+      def self.to_proxmox(config)
+        size_num = config[:size].to_s.gsub(/[^0-9]/, "")
+        parts = ["#{config[:storage]}:#{size_num}"]
+        parts << "mp=#{config[:mp]}" if config[:mp]
+
+        OPTIONAL_FLAGS.each do |flag|
+          parts << "#{flag}=#{config[flag.to_sym]}" if config[flag.to_sym]
+        end
+
+        parts.join(",")
+      end
+
+      # Validates that config contains only known keys and all required keys.
+      #
+      # @param config [Hash<Symbol, String>] parsed mount configuration
+      # @return [void]
+      # @raise [ArgumentError] if unknown keys are present or required keys are missing
+      def self.validate!(config)
+        unknown = config.keys.map(&:to_s) - VALID_KEYS
+        unless unknown.empty?
+          raise ArgumentError, "Unknown mount config key(s): #{unknown.join(', ')}"
+        end
+
+        REQUIRED_KEYS.each do |key|
+          value = config[key.to_sym]
+          if value.nil? || value.strip.empty?
+            raise ArgumentError, "Missing required mount config key: #{key}"
+          end
+        end
+      end
+      private_class_method :validate!
+    end
+  end
+end

data/lib/pvectl/parsers/lxc_net_config.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Parsers
+    # Parses and formats LXC network configurations for Proxmox containers.
+    #
+    # LXC network format differs from QEMU: uses name/type instead of model,
+    # and supports IP configuration directly in the network spec.
+    #
+    # @example Parsing a net config string
+    #   config = LxcNetConfig.parse("bridge=vmbr0,name=eth0,ip=dhcp")
+    #   config[:bridge] #=> "vmbr0"
+    #   config[:name]   #=> "eth0"
+    #   config[:ip]     #=> "dhcp"
+    #
+    # @example Converting to Proxmox API format
+    #   LxcNetConfig.to_proxmox({ bridge: "vmbr0", ip: "dhcp" })
+    #   #=> "name=eth0,bridge=vmbr0,ip=dhcp,type=veth"
+    #
+    class LxcNetConfig
+      # All recognized LXC network configuration keys.
+      VALID_KEYS = %w[bridge name ip gw ip6 gw6 tag firewall mtu rate type].freeze
+
+      # Keys that must be present in every network configuration.
+      REQUIRED_KEYS = %w[bridge].freeze
+
+      # Optional flags appended to the Proxmox API string.
+      OPTIONAL_FLAGS = %w[ip gw ip6 gw6 tag firewall mtu rate].freeze
+
+      # Parses a comma-separated key=value LXC net config string into a Hash.
+      #
+      # @param string [String] net config in "key=value,key=value" format
+      # @return [Hash<Symbol, String>] parsed configuration
+      # @raise [ArgumentError] if unknown keys are present or required keys are missing
+      #
+      # @example
+      #   LxcNetConfig.parse("bridge=vmbr0,name=eth0,ip=dhcp")
+      #   #=> { bridge: "vmbr0", name: "eth0", ip: "dhcp" }
+      def self.parse(string)
+        pairs = string.split(",").map { |pair| pair.strip.split("=", 2).map(&:strip) }
+        config = pairs.to_h { |k, v| [k.to_sym, v] }
+
+        validate!(config)
+        config
+      end
+
+      # Converts a parsed LXC net config Hash to a Proxmox API string.
+      #
+      # The Proxmox API expects LXC network specifications in the format
+      # "name=eth0,bridge=vmbr0,[flags],type=veth". Name defaults to "eth0"
+      # and type defaults to "veth" when not specified.
+      #
+      # @param config [Hash<Symbol, String>] parsed network configuration
+      # @return [String] Proxmox API-compatible network string
+      #
+      # @example Minimal config
+      #   LxcNetConfig.to_proxmox({ bridge: "vmbr0" })
+      #   #=> "name=eth0,bridge=vmbr0,type=veth"
+      #
+      # @example With IP and gateway
+      #   LxcNetConfig.to_proxmox({ bridge: "vmbr0", ip: "10.0.0.5/24", gw: "10.0.0.1" })
+      #   #=> "name=eth0,bridge=vmbr0,ip=10.0.0.5/24,gw=10.0.0.1,type=veth"
+      def self.to_proxmox(config)
+        name = config[:name] || "eth0"
+        type = config[:type] || "veth"
+        parts = ["name=#{name}", "bridge=#{config[:bridge]}"]
+
+        OPTIONAL_FLAGS.each do |flag|
+          parts << "#{flag}=#{config[flag.to_sym]}" if config[flag.to_sym]
+        end
+
+        parts << "type=#{type}"
+        parts.join(",")
+      end
+
+      # Validates that config contains only known keys and all required keys.
+      #
+      # @param config [Hash<Symbol, String>] parsed network configuration
+      # @return [void]
+      # @raise [ArgumentError] if unknown keys are present or required keys are missing
+      def self.validate!(config)
+        unknown = config.keys.map(&:to_s) - VALID_KEYS
+        unless unknown.empty?
+          raise ArgumentError, "Unknown LXC net config key(s): #{unknown.join(', ')}"
+        end
+
+        REQUIRED_KEYS.each do |key|
+          value = config[key.to_sym]
+          if value.nil? || value.strip.empty?
+            raise ArgumentError, "Missing required LXC net config key: #{key}"
+          end
+        end
+      end
+      private_class_method :validate!
+    end
+  end
+end

data/lib/pvectl/parsers/net_config.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Parsers
+    # Parses and formats network configuration strings for Proxmox VMs.
+    #
+    # NetConfig handles the conversion between user-friendly key=value
+    # network specifications and the format required by the Proxmox API.
+    #
+    # @example Parsing a net config string
+    #   config = NetConfig.parse("bridge=vmbr0,model=virtio,tag=100")
+    #   config[:bridge] #=> "vmbr0"
+    #   config[:model]  #=> "virtio"
+    #   config[:tag]    #=> "100"
+    #
+    # @example Converting to Proxmox API format
+    #   config = { bridge: "vmbr0", tag: "100" }
+    #   NetConfig.to_proxmox(config) #=> "virtio,bridge=vmbr0,tag=100"
+    #
+    class NetConfig
+      # All recognized network configuration keys.
+      VALID_KEYS = %w[bridge model tag firewall mtu queues].freeze
+
+      # Keys that must be present in every network configuration.
+      REQUIRED_KEYS = %w[bridge].freeze
+
+      # Optional flags appended to the Proxmox API string.
+      OPTIONAL_FLAGS = %w[tag firewall mtu queues].freeze
+
+      # Parses a comma-separated key=value net config string into a Hash.
+      #
+      # @param string [String] net config in "key=value,key=value" format
+      # @return [Hash<Symbol, String>] parsed configuration
+      # @raise [ArgumentError] if unknown keys are present or required keys are missing
+      #
+      # @example
+      #   NetConfig.parse("bridge=vmbr0,model=virtio,tag=100")
+      #   #=> { bridge: "vmbr0", model: "virtio", tag: "100" }
+      def self.parse(string)
+        pairs = string.split(",").map { |pair| pair.strip.split("=", 2).map(&:strip) }
+        config = pairs.to_h { |k, v| [k.to_sym, v] }
+
+        validate!(config)
+        config
+      end
+
+      # Converts a parsed net config Hash to a Proxmox API string.
+      #
+      # The Proxmox API expects network specifications in the format
+      # "model,bridge=name,flag=val". Model defaults to "virtio"
+      # when not specified.
+      #
+      # @param config [Hash<Symbol, String>] parsed network configuration
+      # @return [String] Proxmox API-compatible network string
+      #
+      # @example Minimal config
+      #   NetConfig.to_proxmox({ bridge: "vmbr0" })
+      #   #=> "virtio,bridge=vmbr0"
+      #
+      # @example With optional flags
+      #   NetConfig.to_proxmox({ bridge: "vmbr0", tag: "100", firewall: "1" })
+      #   #=> "virtio,bridge=vmbr0,tag=100,firewall=1"
+      def self.to_proxmox(config)
+        model = config[:model] || "virtio"
+        parts = [model, "bridge=#{config[:bridge]}"]
+
+        OPTIONAL_FLAGS.each do |flag|
+          parts << "#{flag}=#{config[flag.to_sym]}" if config[flag.to_sym]
+        end
+
+        parts.join(",")
+      end
+
+      # Validates that config contains only known keys and all required keys.
+      #
+      # @param config [Hash<Symbol, String>] parsed network configuration
+      # @return [void]
+      # @raise [ArgumentError] if unknown keys are present or required keys are missing
+      def self.validate!(config)
+        unknown = config.keys.map(&:to_s) - VALID_KEYS
+        unless unknown.empty?
+          raise ArgumentError, "Unknown net config key(s): #{unknown.join(', ')}"
+        end
+
+        REQUIRED_KEYS.each do |key|
+          value = config[key.to_sym]
+          if value.nil? || value.strip.empty?
+            raise ArgumentError, "Missing required net config key: #{key}"
+          end
+        end
+      end
+      private_class_method :validate!
+    end
+  end
+end

data/lib/pvectl/parsers/smart_text.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Parsers
+    # Parses smartctl text output (NVMe/SAS) into structured key-value pairs.
+    #
+    # NVMe and SAS disks return SMART data as plain text from the Proxmox API
+    # (field +text+ in +GET /nodes/{node}/disks/smart+). This parser extracts
+    # +Key: Value+ lines into an Array of Hashes suitable for table display.
+    #
+    # @example Parsing NVMe SMART text
+    #   text = "Critical Warning:  0x00\nTemperature:  34 Celsius\n"
+    #   Pvectl::Parsers::SmartText.parse(text)
+    #   # => [{ "Attribute" => "Critical Warning", "Value" => "0x00" },
+    #   #     { "Attribute" => "Temperature", "Value" => "34 Celsius" }]
+    #
+    class SmartText
+      # Parses smartctl text output into structured attributes.
+      #
+      # Splits each line on the first colon. Lines without a colon or
+      # without a non-empty value after the colon are skipped.
+      # Uses String#split instead of regex to avoid ReDoS risk.
+      #
+      # @param text [String, nil] raw smartctl text output
+      # @return [Array<Hash{String => String}>] parsed attributes
+      def self.parse(text)
+        return [] if text.nil? || text.empty?
+
+        text.each_line.filter_map { |line|
+          key, value = line.strip.split(":", 2)
+          next unless value
+
+          key = key.strip
+          value = value.strip
+          next if key.empty? || value.empty?
+
+          { "Attribute" => key, "Value" => value }
+        }
+      end
+    end
+  end
+end

data/lib/pvectl/plugin_loader.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Pvectl
+  # Discovers and loads commands from built-in sources and external plugins.
+  #
+  # Loading order:
+  # 1. Built-in commands (BUILTIN_COMMANDS list)
+  # 2. Gem-based plugins (pvectl-plugin-* gems)
+  # 3. Directory-based plugins (~/.pvectl/plugins/*.rb)
+  #
+  # Order matters: built-in commands register first (including their
+  # ResourceRegistries), then plugins can extend those registries.
+  #
+  # @example Plugin registration from a gem
+  #   Pvectl::PluginLoader.register_plugin(MyPlugin::Command)
+  #
+  class PluginLoader
+    # Built-in commands that ship with pvectl.
+    # Each must implement .register(cli).
+    BUILTIN_COMMANDS = [
+      Commands::Ping,
+      Commands::Config::Command,
+      Commands::Cloudinit,
+      Commands::Get::Command,
+      Commands::Top::Command,
+      Commands::Logs::Command,
+      Commands::Describe::Command,
+      Commands::Start,
+      Commands::Stop,
+      Commands::Shutdown,
+      Commands::Restart,
+      Commands::Reset,
+      Commands::Suspend,
+      Commands::Resume,
+      Commands::CreateVm,
+      Commands::DeleteVm,
+      Commands::EditVm,
+      Commands::SetVm,
+      Commands::CloneVm,
+      Commands::MigrateVm,
+      Commands::MoveDiskVm,
+      Commands::FeatureVm,
+      Commands::TemplateVm,
+      Commands::RollbackSnapshot,
+      Commands::RestoreBackup,
+      Commands::Console,
+      Commands::SendkeyVm,
+      Commands::Pull,
+      Commands::Push,
+      Commands::Service,
+      Commands::Apt,
+      Commands::WakeonlanNode,
+      Commands::UnlinkDiskVm,
+    ].freeze
+
+    @registered_plugins = []
+
+    class << self
+      # Registers an external plugin command for loading.
+      #
+      # @param klass [Class] plugin class that implements .register(cli)
+      # @return [void]
+      def register_plugin(klass)
+        @registered_plugins << klass
+      end
+
+      # Returns currently registered plugins (for testing).
+      #
+      # @return [Array<Class>] registered plugin classes
+      def registered_plugins
+        @registered_plugins.dup
+      end
+
+      # Loads all commands: built-in, gem plugins, directory plugins.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def load_all(cli)
+        load_builtins(cli)
+        load_gem_plugins(cli)
+        load_directory_plugins(cli)
+      end
+
+      # Loads built-in commands.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def load_builtins(cli)
+        BUILTIN_COMMANDS.each { |cmd| cmd.register(cli) }
+      end
+
+      # Discovers and loads gem-based plugins.
+      #
+      # Searches for gems matching pvectl-plugin-* via
+      # Gem.find_files("pvectl_plugin/register").
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def load_gem_plugins(cli)
+        Gem.find_files("pvectl_plugin/register").each do |register_file|
+          require register_file
+        rescue StandardError => e
+          warn "Warning: Failed to load plugin #{register_file}: #{e.message}"
+          warn e.backtrace.join("\n") if ENV["GLI_DEBUG"] == "true"
+        end
+        flush_registered_plugins(cli)
+      end
+
+      # Discovers and loads directory-based plugins.
+      #
+      # Scans ~/.pvectl/plugins/*.rb for plugin files.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def load_directory_plugins(cli)
+        return unless Dir.exist?(directory_plugins_path)
+
+        Dir.glob(File.join(directory_plugins_path, "*.rb")).sort.each do |plugin_file|
+          require plugin_file
+        rescue StandardError => e
+          warn "Warning: Failed to load plugin #{plugin_file}: #{e.message}"
+          warn e.backtrace.join("\n") if ENV["GLI_DEBUG"] == "true"
+        end
+        flush_registered_plugins(cli)
+      end
+
+      # Returns the directory path for local plugins.
+      #
+      # @return [String] plugins directory path
+      def directory_plugins_path
+        File.expand_path("~/.pvectl/plugins")
+      end
+
+      # Calls register on all queued plugins and clears the queue.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def flush_registered_plugins(cli)
+        @registered_plugins.each do |klass|
+          klass.register(cli)
+        rescue StandardError => e
+          warn "Warning: Failed to register plugin #{klass}: #{e.message}"
+          warn e.backtrace.join("\n") if ENV["GLI_DEBUG"] == "true"
+        end
+        @registered_plugins.clear
+      end
+
+      # Resets state (for testing).
+      #
+      # @return [void]
+      # @api private
+      def reset!
+        @registered_plugins = []
+      end
+    end
+  end
+end