pvectl 0.2.0

data/lib/pvectl/commands/config/use_context.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    module Config
+      # Handler for the `pvectl config use-context` command.
+      #
+      # Switches the active context in the configuration file.
+      # The context name must exist in the configuration.
+      #
+      # @example Usage
+      #   pvectl config use-context production
+      #   pvectl config use-context dev
+      #
+      class UseContext
+        # Registers the use-context subcommand.
+        #
+        # @param parent [GLI::Command] parent config command
+        # @return [void]
+        def self.register_subcommand(parent)
+          parent.desc "Switch to a different context"
+          parent.long_desc <<~HELP
+            Switch the active context. The context determines which Proxmox
+            cluster and credentials are used for subsequent commands.
+
+            EXAMPLES
+              Switch to production:
+                $ pvectl config use-context production
+
+            NOTES
+              Changes are persisted to the config file immediately.
+              Use PVECTL_CONTEXT env var for temporary overrides.
+          HELP
+          parent.command :"use-context" do |use_ctx|
+            use_ctx.arg_name "CONTEXT_NAME"
+            use_ctx.action do |global_options, _options, args|
+              if args.empty?
+                $stderr.puts "Error: context name is required"
+                exit ExitCodes::USAGE_ERROR
+              end
+              exit_code = execute(args[0], global_options)
+              exit exit_code if exit_code != 0
+            end
+          end
+        end
+
+        # Executes the use-context command.
+        #
+        # @param context_name [String] name of the context to switch to
+        # @param global_options [Hash] global CLI options (includes :config path)
+        # @return [Integer] exit code (0 for success)
+        # @raise [Config::ContextNotFoundError] if context doesn't exist
+        def self.execute(context_name, global_options)
+          config_path = global_options[:config]
+          service = Pvectl::Config::Service.new
+          service.load(config: config_path)
+
+          service.use_context(context_name)
+
+          puts "Switched to context \"#{context_name}\"."
+          0
+        rescue Pvectl::Config::ContextNotFoundError => e
+          $stderr.puts "Error: #{e.message}"
+          ExitCodes::CONFIG_ERROR
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/commands/config/view.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Pvectl
+  module Commands
+    module Config
+      # Handler for the `pvectl config view` command.
+      #
+      # Displays the current configuration with secrets masked.
+      # Secrets (token-secret, password) are replaced with ********.
+      #
+      # @example Usage
+      #   pvectl config view
+      #   pvectl config view -o json
+      #
+      class View
+        # Registers the view subcommand.
+        #
+        # @param parent [GLI::Command] parent config command
+        # @return [void]
+        def self.register_subcommand(parent)
+          parent.desc "Display current configuration with masked secrets"
+          parent.long_desc <<~HELP
+            Display the current configuration file contents. Secrets (token
+            secrets, passwords) are masked for security.
+
+            EXAMPLES
+              $ pvectl config view
+              $ pvectl config view -o yaml
+          HELP
+          parent.command :view do |view|
+            view.action do |global_options, _options, _args|
+              exit_code = execute(global_options)
+              exit exit_code if exit_code != 0
+            end
+          end
+        end
+
+        # Executes the view command.
+        #
+        # @param global_options [Hash] global CLI options (includes :config, :output)
+        # @return [Integer] exit code (0 for success)
+        def self.execute(global_options)
+          config_path = global_options[:config]
+          output_format = global_options[:output] || "yaml"
+
+          service = Pvectl::Config::Service.new
+          service.load(config: config_path)
+
+          masked_config = service.masked_config
+
+          case output_format
+          when "json"
+            puts JSON.pretty_generate(masked_config)
+          else
+            # Default to YAML for human-readable output
+            puts masked_config.to_yaml
+          end
+
+          0
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/commands/console.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # CLI registration for the `pvectl console` command.
+    #
+    # Opens an interactive terminal console to a VM or container via
+    # WebSocket-based termproxy. Dispatches to {ConsoleVm} or {ConsoleCt}
+    # based on the resource type argument.
+    #
+    # @example Open console to a VM
+    #   pvectl console vm 100
+    #
+    # @example Open console to a container
+    #   pvectl console ct 200
+    #
+    # @example Open console with explicit credentials
+    #   pvectl console vm 100 --user root@pam --password secret
+    #
+    class Console
+      # Supported resource type arguments.
+      SUPPORTED_RESOURCES = %w[vm ct container].freeze
+
+      # Registers the console command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Open interactive terminal console to a VM or container"
+        cli.long_desc <<~HELP
+          Open an interactive terminal session to a VM or container via
+          WebSocket-based termproxy (xtermjs protocol).
+
+          EXAMPLES
+            Open console to a VM:
+              $ pvectl console vm 100
+
+            Open console to a container:
+              $ pvectl console ct 200
+
+            Specify node explicitly:
+              $ pvectl console vm 100 --node pve1
+
+            Provide credentials (prompted for password if omitted):
+              $ pvectl console vm 100 --user root@pam
+
+          NOTES
+            Console requires session authentication (username/password). If your
+            config only has an API token, pvectl will prompt for credentials.
+
+            Disconnect with Ctrl+].
+
+            The console uses a WebSocket connection. Network interruptions will
+            close the session.
+
+          SEE ALSO
+            pvectl help describe        View VM/container configuration
+            pvectl help start           Start a stopped VM before connecting
+        HELP
+        cli.arg_name "RESOURCE_TYPE ID"
+        cli.command :console do |c|
+          c.desc "Filter by node name"
+          c.flag [:node, :n], arg_name: "NODE"
+
+          c.desc "Username for session authentication"
+          c.flag [:user], arg_name: "USER"
+
+          c.desc "Password for session authentication"
+          c.flag [:password], arg_name: "PASSWORD"
+
+          c.action do |global_options, options, args|
+            resource_type = args.shift
+            resource_id = args.shift
+
+            unless resource_type && SUPPORTED_RESOURCES.include?(resource_type)
+              $stderr.puts "Error: Resource type required (vm, ct)"
+              exit Pvectl::ExitCodes::USAGE_ERROR
+            end
+
+            exit_code = case resource_type
+            when "ct", "container"
+              ConsoleCt.execute(resource_id, options, global_options)
+            else
+              ConsoleVm.execute(resource_id, options, global_options)
+            end
+
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/commands/console_ct.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl console ct` command.
+    #
+    # Opens an interactive terminal console session to an LXC container
+    # via WebSocket-based termproxy. Requires a running container and
+    # interactive terminal (TTY).
+    #
+    # @example Open console to container 200
+    #   pvectl console ct 200
+    #
+    # @example Open console with explicit credentials
+    #   pvectl console ct 200 --user root@pam --password secret
+    #
+    class ConsoleCt
+      # Executes the console container command.
+      #
+      # @param ctid [String, nil] container identifier
+      # @param options [Hash] command options (:user, :password)
+      # @param global_options [Hash] global CLI options
+      # @return [Integer] exit code
+      def self.execute(ctid, options, global_options)
+        new(ctid, options, global_options).execute
+      end
+
+      # Initializes a console container command.
+      #
+      # @param ctid [String, nil] container identifier
+      # @param options [Hash] command options
+      # @param global_options [Hash] global CLI options
+      def initialize(ctid, options, global_options)
+        @ctid = ctid
+        @options = options
+        @global_options = global_options
+      end
+
+      # Executes the console flow.
+      #
+      # @return [Integer] exit code
+      def execute
+        return usage_error("CTID is required") unless @ctid
+        return usage_error("Console requires an interactive terminal (TTY)") unless $stdin.tty?
+
+        load_config
+        connection = Pvectl::Connection.new(@config)
+        repo = Pvectl::Repositories::Container.new(connection)
+
+        resource = repo.get(@ctid.to_i)
+        return not_found("Container #{@ctid} not found") unless resource
+
+        username, password = resolve_credentials
+        return ExitCodes::GENERAL_ERROR if username.nil? || password.nil?
+
+        $stderr.puts "Connecting to container #{resource.vmid} (#{resource.name || 'unnamed'}) on node #{resource.node}..."
+
+        Pvectl::Services::Console.new.run(
+          resource: resource,
+          resource_path: resource_path,
+          server: @config.server,
+          username: username,
+          password: password,
+          verify_ssl: @config.verify_ssl
+        )
+
+        ExitCodes::SUCCESS
+      rescue Services::Console::ResourceNotRunningError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::GENERAL_ERROR
+      rescue Services::Console::AuthenticationError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::PERMISSION_DENIED
+      rescue Pvectl::Config::ConfigNotFoundError,
+             Pvectl::Config::InvalidConfigError,
+             Pvectl::Config::ContextNotFoundError,
+             Pvectl::Config::ClusterNotFoundError,
+             Pvectl::Config::UserNotFoundError,
+             Pvectl::Config::MissingCredentialsError
+        raise # re-raise for CLI handler
+      rescue Errno::ECONNREFUSED, SocketError, Timeout::Error => e
+        $stderr.puts "Error: Cannot connect to console: #{e.message}"
+        ExitCodes::CONNECTION_ERROR
+      rescue StandardError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::GENERAL_ERROR
+      end
+
+      private
+
+      # Returns the API resource path for an LXC container.
+      #
+      # @return [String] resource path segment
+      def resource_path
+        "lxc/#{@ctid}"
+      end
+
+      # Resolves authentication credentials for the console session.
+      #
+      # Priority: CLI flags > config file > interactive prompt.
+      # Extracts default username from token_id when available.
+      #
+      # @return [Array<String, String>, Array<nil, nil>] [username, password] or [nil, nil] if cancelled
+      def resolve_credentials
+        username = @options[:user]
+        password = @options[:password]
+
+        if username.nil? && password.nil? && @config.username && @config.password
+          username = @config.username
+          password = @config.password
+        end
+
+        if username.nil? && @config.token_id
+          # Extract default username from token_id (e.g., "root@pam!pvectl" -> "root@pam")
+          default_username = @config.token_id.split("!").first
+        end
+
+        # When credentials come from config (username+password pair), use them directly.
+        # Otherwise, prompt interactively — always show both prompts so the user knows
+        # which username will be used and can change it.
+        if password.nil?
+          username = prompt_username(username || default_username)
+          return [nil, nil] if username.nil?
+
+          password = prompt_password
+        end
+        return [nil, nil] if password.nil?
+
+        [username, password]
+      end
+
+      # Prompts the user for a username.
+      #
+      # @param default [String, nil] default username to suggest
+      # @return [String, nil] entered username or nil if cancelled
+      def prompt_username(default = nil)
+        prompt = default ? "Username [#{default}]: " : "Username: "
+        $stderr.print prompt
+        input = $stdin.gets&.strip
+        return nil if input.nil?
+
+        input.empty? ? default : input
+      end
+
+      # Prompts the user for a password (hidden input).
+      #
+      # @return [String, nil] entered password or nil if cancelled
+      def prompt_password
+        $stderr.print "Password: "
+        password = $stdin.noecho(&:gets)&.strip
+        $stderr.puts # newline after hidden input
+        return nil if password.nil? || password.empty?
+
+        password
+      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 a usage error and returns the 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
+
+      # Outputs a not-found error and returns the exit code.
+      #
+      # @param message [String] error message
+      # @return [Integer] NOT_FOUND exit code
+      def not_found(message)
+        $stderr.puts "Error: #{message}"
+        ExitCodes::NOT_FOUND
+      end
+    end
+  end
+end

data/lib/pvectl/commands/console_vm.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl console vm` command.
+    #
+    # Opens an interactive terminal console session to a QEMU virtual machine
+    # via WebSocket-based termproxy. Requires a running VM and interactive
+    # terminal (TTY).
+    #
+    # @example Open console to VM 100
+    #   pvectl console vm 100
+    #
+    # @example Open console with explicit credentials
+    #   pvectl console vm 100 --user root@pam --password secret
+    #
+    class ConsoleVm
+      # Executes the console VM command.
+      #
+      # @param vmid [String, nil] VM identifier
+      # @param options [Hash] command options (:user, :password)
+      # @param global_options [Hash] global CLI options
+      # @return [Integer] exit code
+      def self.execute(vmid, options, global_options)
+        new(vmid, options, global_options).execute
+      end
+
+      # Initializes a console VM command.
+      #
+      # @param vmid [String, nil] VM identifier
+      # @param options [Hash] command options
+      # @param global_options [Hash] global CLI options
+      def initialize(vmid, options, global_options)
+        @vmid = vmid
+        @options = options
+        @global_options = global_options
+      end
+
+      # Executes the console flow.
+      #
+      # @return [Integer] exit code
+      def execute
+        return usage_error("VMID is required") unless @vmid
+        return usage_error("Console requires an interactive terminal (TTY)") unless $stdin.tty?
+
+        load_config
+        connection = Pvectl::Connection.new(@config)
+        repo = Pvectl::Repositories::Vm.new(connection)
+
+        resource = repo.get(@vmid.to_i)
+        return not_found("VM #{@vmid} not found") unless resource
+
+        username, password = resolve_credentials
+        return ExitCodes::GENERAL_ERROR if username.nil? || password.nil?
+
+        $stderr.puts "Connecting to VM #{resource.vmid} (#{resource.name || 'unnamed'}) on node #{resource.node}..."
+
+        Pvectl::Services::Console.new.run(
+          resource: resource,
+          resource_path: resource_path,
+          server: @config.server,
+          username: username,
+          password: password,
+          verify_ssl: @config.verify_ssl
+        )
+
+        ExitCodes::SUCCESS
+      rescue Services::Console::ResourceNotRunningError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::GENERAL_ERROR
+      rescue Services::Console::AuthenticationError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::PERMISSION_DENIED
+      rescue Pvectl::Config::ConfigNotFoundError,
+             Pvectl::Config::InvalidConfigError,
+             Pvectl::Config::ContextNotFoundError,
+             Pvectl::Config::ClusterNotFoundError,
+             Pvectl::Config::UserNotFoundError,
+             Pvectl::Config::MissingCredentialsError
+        raise # re-raise for CLI handler
+      rescue Errno::ECONNREFUSED, SocketError, Timeout::Error => e
+        $stderr.puts "Error: Cannot connect to console: #{e.message}"
+        ExitCodes::CONNECTION_ERROR
+      rescue StandardError => e
+        $stderr.puts "Error: #{e.message}"
+        ExitCodes::GENERAL_ERROR
+      end
+
+      private
+
+      # Returns the API resource path for a QEMU VM.
+      #
+      # @return [String] resource path segment
+      def resource_path
+        "qemu/#{@vmid}"
+      end
+
+      # Resolves authentication credentials for the console session.
+      #
+      # Priority: CLI flags > config file > interactive prompt.
+      # Extracts default username from token_id when available.
+      #
+      # @return [Array<String, String>, Array<nil, nil>] [username, password] or [nil, nil] if cancelled
+      def resolve_credentials
+        username = @options[:user]
+        password = @options[:password]
+
+        if username.nil? && password.nil? && @config.username && @config.password
+          username = @config.username
+          password = @config.password
+        end
+
+        if username.nil? && @config.token_id
+          # Extract default username from token_id (e.g., "root@pam!pvectl" -> "root@pam")
+          default_username = @config.token_id.split("!").first
+        end
+
+        # When credentials come from config (username+password pair), use them directly.
+        # Otherwise, prompt interactively — always show both prompts so the user knows
+        # which username will be used and can change it.
+        if password.nil?
+          username = prompt_username(username || default_username)
+          return [nil, nil] if username.nil?
+
+          password = prompt_password
+        end
+        return [nil, nil] if password.nil?
+
+        [username, password]
+      end
+
+      # Prompts the user for a username.
+      #
+      # @param default [String, nil] default username to suggest
+      # @return [String, nil] entered username or nil if cancelled
+      def prompt_username(default = nil)
+        prompt = default ? "Username [#{default}]: " : "Username: "
+        $stderr.print prompt
+        input = $stdin.gets&.strip
+        return nil if input.nil?
+
+        input.empty? ? default : input
+      end
+
+      # Prompts the user for a password (hidden input).
+      #
+      # @return [String, nil] entered password or nil if cancelled
+      def prompt_password
+        $stderr.print "Password: "
+        password = $stdin.noecho(&:gets)&.strip
+        $stderr.puts # newline after hidden input
+        return nil if password.nil? || password.empty?
+
+        password
+      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 a usage error and returns the 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
+
+      # Outputs a not-found error and returns the exit code.
+      #
+      # @param message [String] error message
+      # @return [Integer] NOT_FOUND exit code
+      def not_found(message)
+        $stderr.puts "Error: #{message}"
+        ExitCodes::NOT_FOUND
+      end
+    end
+  end
+end

data/lib/pvectl/commands/container_lifecycle_command.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Container-specific lifecycle command hooks.
+    #
+    # Provides container repository, selector, service, and presenter
+    # to ResourceLifecycleCommand's template methods.
+    #
+    # @example Usage
+    #   class StartContainer
+    #     include ContainerLifecycleCommand
+    #     OPERATION = :start
+    #   end
+    #
+    module ContainerLifecycleCommand
+      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[container ct]
+      end
+
+      # @return [String] human label for container resources
+      def resource_label
+        "container"
+      end
+
+      # @return [String] human label for container IDs
+      def resource_id_label
+        "CTID"
+      end
+
+      # Builds container repository.
+      #
+      # @param connection [Connection] API connection
+      # @return [Repositories::Container] container repository
+      def build_repository(connection)
+        Pvectl::Repositories::Container.new(connection)
+      end
+
+      # Builds container lifecycle service.
+      #
+      # @param repo [Repositories::Container] container repository
+      # @param task_repo [Repositories::Task] task repository
+      # @param options [Hash] service options
+      # @return [Services::ContainerLifecycle] container lifecycle service
+      def build_service(repo, task_repo, options)
+        Pvectl::Services::ContainerLifecycle.new(repo, task_repo, options)
+      end
+
+      # Builds container operation result presenter.
+      #
+      # @return [Presenters::ContainerOperationResult] presenter
+      def build_presenter
+        Pvectl::Presenters::ContainerOperationResult.new
+      end
+
+      # Builds container selector from strings.
+      #
+      # @param strings [Array<String>] selector strings
+      # @return [Selectors::Container] parsed selector
+      def build_selector(strings)
+        Pvectl::Selectors::Container.parse_all(strings)
+      end
+    end
+  end
+end