pvectl 0.2.0

data/lib/pvectl/commands/create_snapshot.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl create snapshot` sub-command.
+    #
+    # Creates snapshots for VMs/containers. Snapshot name is the first
+    # positional argument, VMIDs are specified via --vmid flag.
+    # Without --vmid, operates on ALL VMs/CTs in the cluster.
+    #
+    # @example Create single snapshot
+    #   pvectl create snapshot before-upgrade --vmid 100
+    #
+    # @example Create for multiple VMs
+    #   pvectl create snapshot before-upgrade --vmid 100 --vmid 101
+    #
+    # @example Create cluster-wide
+    #   pvectl create snapshot before-upgrade --yes
+    #
+    class CreateSnapshot
+      VMID_PATTERN = /\A[1-9]\d{0,8}\z/
+
+      # Registers as a sub-command under the parent create command.
+      #
+      # @param parent [GLI::Command] the parent create command
+      # @return [void]
+      def self.register_subcommand(parent)
+        parent.desc "Create a snapshot of VMs or containers"
+        parent.long_desc <<~HELP
+          Create a snapshot of one or more VMs or containers. Snapshots capture
+          the current state of disks (and optionally RAM) for later rollback.
+
+          EXAMPLES
+            Snapshot a single VM:
+              $ pvectl create snapshot before-upgrade --vmid 100
+
+            Snapshot multiple VMs:
+              $ pvectl create snapshot before-upgrade --vmid 100 --vmid 101
+
+            Snapshot with description and VM memory state:
+              $ pvectl create snapshot before-upgrade --vmid 100 --description "Pre-upgrade" --vmstate
+
+            Snapshot all VMs/containers cluster-wide:
+              $ pvectl create snapshot before-upgrade --yes
+
+          NOTES
+            --vmstate saves the VM's RAM state (QEMU only, not for containers).
+            This increases snapshot size but allows resuming from exact state.
+
+            Without --vmid, operates cluster-wide (requires --yes confirmation).
+
+          SEE ALSO
+            pvectl help rollback        Rollback to a snapshot
+            pvectl help delete snapshot Delete snapshots
+            pvectl help get snapshots   List existing snapshots
+        HELP
+        parent.command :snapshot do |s|
+          s.desc "VM/CT ID (repeatable)"
+          s.flag [:vmid], arg_name: "VMID", multiple: true
+
+          s.desc "Save VM memory state (QEMU only)"
+          s.switch [:vmstate], negatable: false
+
+          s.action do |global_options, options, args|
+            exit_code = execute(args, options, global_options)
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+
+      # Executes the create snapshot command.
+      #
+      # @param args [Array<String>] positional args (snapshot name)
+      # @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
+
+      # Initializes a create snapshot command.
+      #
+      # @param args [Array<String>] positional args (snapshot name)
+      # @param options [Hash] command options
+      # @param global_options [Hash] global CLI options
+      def initialize(args, options, global_options)
+        @args = Array(args)
+        @options = options
+        @global_options = global_options
+        @snapshot_name = @args.first
+        @vmids = parse_vmids(options[:vmid])
+        @node = options[:node]
+      end
+
+      # Executes the create snapshot command.
+      #
+      # @return [Integer] exit code
+      def execute
+        return usage_error("Snapshot name required") unless @snapshot_name
+        return usage_error("Invalid VMID: #{invalid_vmid}") if invalid_vmid
+
+        perform_operation
+      end
+
+      private
+
+      # Parses --vmid flag values to integer array.
+      #
+      # @param vmid_values [Array<String>, nil] raw vmid values
+      # @return [Array<Integer>] parsed VMIDs
+      def parse_vmids(vmid_values)
+        return [] if vmid_values.nil? || vmid_values.empty?
+
+        Array(vmid_values).map(&:to_i)
+      end
+
+      # Finds first invalid VMID in options.
+      #
+      # @return [String, nil] invalid VMID value or nil
+      def invalid_vmid
+        return nil if @options[:vmid].nil? || @options[:vmid].empty?
+
+        Array(@options[:vmid]).find { |v| !VMID_PATTERN.match?(v.to_s) }
+      end
+
+      # Performs the snapshot creation operation.
+      #
+      # @return [Integer] exit code
+      def perform_operation
+        load_config
+        connection = Pvectl::Connection.new(@config)
+
+        snapshot_repo = Pvectl::Repositories::Snapshot.new(connection)
+        resolver = Pvectl::Utils::ResourceResolver.new(connection)
+        task_repo = Pvectl::Repositories::Task.new(connection)
+
+        service = Pvectl::Services::Snapshot.new(
+          snapshot_repo: snapshot_repo,
+          resource_resolver: resolver,
+          task_repo: task_repo,
+          options: service_options
+        )
+
+        return ExitCodes::SUCCESS unless confirm_operation
+
+        results = service.create(
+          @vmids,
+          name: @snapshot_name,
+          description: @options[:description],
+          vmstate: @options[:vmstate] || false,
+          node: @node
+        )
+
+        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 operation with user prompt.
+      #
+      # @return [Boolean] true if operation should proceed
+      def confirm_operation
+        return true if @vmids.size == 1
+        return true if @options[:yes]
+
+        if @vmids.empty?
+          $stdout.puts "You are about to create snapshot '#{@snapshot_name}' for ALL VMs/CTs in the cluster."
+        else
+          $stdout.puts "You are about to create snapshot '#{@snapshot_name}' for #{@vmids.size} VMs:"
+          @vmids.each { |vmid| $stdout.puts "  - #{vmid}" }
+        end
+        $stdout.puts ""
+        $stdout.print "Proceed? [y/N]: "
+
+        response = $stdin.gets&.strip&.downcase
+        %w[y yes].include?(response)
+      end
+
+      # Loads configuration.
+      #
+      # @return [void]
+      def load_config
+        service = Pvectl::Config::Service.new
+        service.load(config: @global_options[:config])
+        @config = service.current_config
+      end
+
+      # Builds service options.
+      #
+      # @return [Hash] service options
+      def service_options
+        opts = {}
+        opts[:timeout] = @options[:timeout] if @options[:timeout]
+        opts[:async] = true if @options[:async]
+        opts[:fail_fast] = true if @options[:"fail-fast"]
+        opts
+      end
+
+      # Outputs operation results.
+      #
+      # @param results [Array<Models::OperationResult>] results
+      # @return [void]
+      def output_results(results)
+        presenter = Pvectl::Presenters::SnapshotOperationResult.new
+        format = @global_options[:output] || "table"
+        color_flag = @global_options[:color]
+
+        formatter = Pvectl::Formatters::Registry.for(format)
+        output = formatter.format(results, presenter, color: color_flag)
+        puts output
+      end
+
+      # Determines exit code.
+      #
+      # @param results [Array<Models::OperationResult>] results
+      # @return [Integer] exit code
+      def determine_exit_code(results)
+        return ExitCodes::SUCCESS if results.all?(&:successful?)
+        return ExitCodes::SUCCESS if results.all?(&:pending?)
+
+        ExitCodes::GENERAL_ERROR
+      end
+
+      # Outputs usage error.
+      #
+      # @param message [String] error message
+      # @return [Integer] exit code
+      def usage_error(message)
+        $stderr.puts "Error: #{message}"
+        ExitCodes::USAGE_ERROR
+      end
+    end
+  end
+end

data/lib/pvectl/commands/create_vm.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl create vm` command.
+    #
+    # Includes CreateResourceCommand for shared workflow and overrides
+    # template methods with VM-specific behavior.
+    #
+    # @example Flag-based creation
+    #   pvectl create vm --name web --node pve1 --cores 4 --memory 4096
+    #
+    # @example With disk and network
+    #   pvectl create vm 100 --name web --node pve1 \
+    #     --disk storage=local-lvm,size=32G --net bridge=vmbr0
+    #
+    # @example Dry-run mode
+    #   pvectl create vm --name web --node pve1 --dry-run
+    #
+    class CreateVm
+      include CreateResourceCommand
+      include SharedConfigParsers
+
+      # Registers the create command with the CLI.
+      #
+      # @param cli [GLI::App] the CLI application object
+      # @return [void]
+      def self.register(cli)
+        cli.desc "Create a resource"
+        cli.long_desc <<~HELP
+          Create a new virtual machine, container, snapshot, or backup.
+
+          For VMs and containers, you can either specify configuration via flags
+          or use --interactive for a guided wizard. Use --dry-run to preview
+          the configuration without actually creating the resource.
+
+          SUBCOMMANDS
+            create vm [ID]              Create a virtual machine
+            create container [ID]       Create an LXC container
+            create snapshot NAME        Create a snapshot (see: pvectl help create snapshot)
+            create backup ID...         Create a backup (vzdump)
+
+          EXAMPLES
+            Create a VM with specific config:
+              $ pvectl create vm 100 --cores 4 --memory 8192 --disk storage=local-lvm,size=50G
+
+            Create a VM using interactive wizard:
+              $ pvectl create vm --interactive
+
+            Preview VM creation without executing:
+              $ pvectl create vm 100 --cores 2 --memory 4096 --dry-run
+
+            Create a container:
+              $ pvectl create container 200 --hostname nginx --ostemplate local:vztmpl/debian-12.tar.zst
+
+            Create a backup:
+              $ pvectl create backup 100 --storage nfs-backup --mode snapshot
+
+          NOTES
+            If no ID is specified for VM/container, Proxmox auto-assigns the
+            next available ID.
+
+            VM creation supports cloud-init configuration via --cloud-init flag.
+
+            Backup modes: snapshot (default, no downtime), suspend (brief pause),
+            stop (full stop during backup).
+
+          SEE ALSO
+            pvectl help clone           Clone an existing VM or container
+            pvectl help delete          Delete resources
+            pvectl help get templates   List available templates
+        HELP
+        cli.arg_name "RESOURCE_TYPE [ID...]"
+        cli.command :create do |c|
+          c.desc "Resource name"
+          c.flag [:name], arg_name: "NAME"
+
+          c.desc "Description/notes"
+          c.flag [:description, :notes], arg_name: "TEXT"
+
+          # Backup-specific flags
+          c.desc "Target storage for backup"
+          c.flag [:storage], arg_name: "STORAGE"
+
+          c.desc "Backup mode (snapshot, suspend, stop)"
+          c.default_value "snapshot"
+          c.flag [:mode], arg_name: "MODE", must_match: %w[snapshot suspend stop]
+
+          c.desc "Compression (zstd, gzip, lzo, 0 for none)"
+          c.default_value "zstd"
+          c.flag [:compress], arg_name: "TYPE"
+
+          c.desc "Protect backup from deletion"
+          c.switch [:protected], negatable: false
+
+          # Common flags
+          c.desc "Skip confirmation prompt"
+          c.switch [:yes, :y], negatable: false
+
+          c.desc "Timeout in seconds for sync operations"
+          c.flag [:timeout], type: Integer, arg_name: "SECONDS"
+
+          c.desc "Force async mode (return task ID immediately)"
+          c.switch [:async], negatable: false
+
+          c.desc "Stop on first error (default: continue and report all)"
+          c.switch [:"fail-fast"], negatable: false
+
+          # Shared config flags (VM + container)
+          SharedFlags.common_config(c)
+          SharedFlags.vm_config(c)
+          SharedFlags.container_config(c)
+
+          c.desc "Resource pool"
+          c.flag [:pool], arg_name: "POOL"
+
+          c.desc "Force interactive wizard mode"
+          c.switch [:interactive], negatable: true
+
+          c.desc "Show what would happen without creating"
+          c.switch [:"dry-run"], negatable: false
+
+          # Container-specific create flags
+          c.desc "Container hostname (container)"
+          c.flag [:hostname], arg_name: "NAME"
+
+          c.desc "OS template path (container): storage:vztmpl/name.tar.zst"
+          c.flag [:ostemplate], arg_name: "TEMPLATE"
+
+          # Sub-commands
+          CreateSnapshot.register_subcommand(c)
+
+          c.action do |global_options, options, args|
+            resource_type = args.shift
+            resource_ids = args
+
+            exit_code = case resource_type
+            when "vm"
+              Commands::CreateVm.execute(resource_ids, options, global_options)
+            when "container", "ct"
+              Commands::CreateContainer.execute(resource_ids, options, global_options)
+            when "backup"
+              # Map :description to :notes for backup if notes not set
+              options[:notes] ||= options[:description]
+              Commands::CreateBackup.execute(resource_type, resource_ids, options, global_options)
+            else
+              $stderr.puts "Error: Unknown resource type: #{resource_type}"
+              $stderr.puts "Valid types: vm, container, backup (or use: create snapshot)"
+              ExitCodes::USAGE_ERROR
+            end
+
+            exit exit_code if exit_code != 0
+          end
+        end
+      end
+
+      private
+
+      # @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
+
+      # @return [Boolean] true if --name is missing
+      def required_params_missing?
+        !@options[:name]
+      end
+
+      # @return [Object] VM creation wizard
+      def build_wizard
+        Pvectl::Wizards::CreateVm.new(@options, @global_options)
+      end
+
+      # @param connection [Connection] API connection
+      # @param task_repo [Repositories::Task] task repository
+      # @return [Services::CreateVm] VM creation service
+      def build_create_service(connection, task_repo)
+        vm_repo = Pvectl::Repositories::Vm.new(connection)
+        Pvectl::Services::CreateVm.new(
+          vm_repository: vm_repo,
+          task_repository: task_repo,
+          options: service_options
+        )
+      end
+
+      # @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)
+        puts output
+      end
+
+      # Validates flags and performs flag-based creation.
+      #
+      # Overrides shared #perform_create to add VM-specific validation.
+      #
+      # @return [Integer] exit code
+      def perform_create
+        return usage_error("--name is required") unless @options[:name]
+
+        super
+      end
+
+      # Extracts CLI options into a service params hash.
+      #
+      # Delegates VM config parsing to SharedConfigParsers#build_vm_config_params,
+      # then adds create-specific parameters.
+      #
+      # @return [Hash] service-compatible parameters
+      # @raise [ArgumentError] if parser validation fails
+      def build_params_from_flags
+        params = build_vm_config_params
+        params[:name] = @options[:name]
+        params[:node] = @options[:node] || resolve_default_node
+        params[:description] = @options[:description]
+        params[:pool] = @options[:pool]
+
+        vmid = @args.first
+        params[:vmid] = vmid.to_i if vmid
+
+        params.compact
+      end
+
+      # @param params [Hash] VM creation parameters
+      # @return [void]
+      def display_resource_summary(params)
+        $stdout.puts "  Name:      #{params[:name]}"
+        $stdout.puts "  Node:      #{params[:node] || '(from context)'}"
+
+        if params[:cores] || params[:sockets]
+          $stdout.puts "  CPU:       #{params[:cores] || 1} cores, #{params[:sockets] || 1} socket(s)"
+        end
+
+        $stdout.puts "  Memory:    #{params[:memory] || 2048} MB"
+
+        if params[:disks]
+          params[:disks].each_with_index do |disk, i|
+            $stdout.puts "  Disk#{i}:     #{disk[:storage]}, #{disk[:size]}"
+          end
+        end
+
+        if params[:nets]
+          params[:nets].each_with_index do |net, i|
+            $stdout.puts "  Net#{i}:      #{net[:bridge]}, #{net[:model] || 'virtio'}"
+          end
+        end
+
+        $stdout.puts "  OS Type:   #{params[:ostype]}" if params[:ostype]
+        $stdout.puts "  BIOS:      #{params[:bios]}" if params[:bios]
+        $stdout.puts "  CD-ROM:    #{params[:cdrom]}" if params[:cdrom]
+        $stdout.puts "  Agent:     enabled" if params[:agent]
+        $stdout.puts "  Tags:      #{params[:tags]}" if params[:tags]
+        $stdout.puts "  Pool:      #{params[:pool]}" if params[:pool]
+      end
+    end
+  end
+end

data/lib/pvectl/commands/delete_backup.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Commands
+    # Handler for the `pvectl delete backup` command.
+    #
+    # Deletes a backup identified by its full volume ID (volid).
+    # Requires --yes flag for confirmation.
+    #
+    # @example Delete a backup
+    #   pvectl delete backup local:backup/vzdump-qemu-100-2024_01_15.vma.zst --yes
+    #
+    class DeleteBackup
+      # Executes the delete backup command.
+      #
+      # @param resource_type [String, nil] resource type (backup)
+      # @param args [Array<String>, String, nil] backup volid
+      # @param options [Hash] command options
+      # @param global_options [Hash] global CLI options
+      # @return [Integer] exit code
+      def self.execute(resource_type, args, options, global_options)
+        new(resource_type, args, options, global_options).execute
+      end
+
+      # Initializes a delete backup command.
+      #
+      # @param resource_type [String, nil] resource type (backup)
+      # @param args [Array<String>, String, nil] backup volid
+      # @param options [Hash] command options
+      # @param global_options [Hash] global CLI options
+      def initialize(resource_type, args, options, global_options)
+        @resource_type = resource_type
+        @args = Array(args).compact
+        @options = options
+        @global_options = global_options
+        @volid = @args.first
+      end
+
+      # Executes the delete backup command.
+      #
+      # @return [Integer] exit code
+      def execute
+        return usage_error("Resource type required (backup)") unless @resource_type == "backup"
+        return usage_error("Backup volid is required") if @volid.nil? || @volid.empty?
+        return usage_error("Confirmation required: use --yes to confirm deletion") unless @options[:yes]
+
+        perform_operation
+      end
+
+      private
+
+      # Performs the backup deletion operation.
+      #
+      # @return [Integer] exit code
+      def perform_operation
+        load_config
+        connection = Pvectl::Connection.new(@config)
+
+        backup_repo = Pvectl::Repositories::Backup.new(connection)
+        resolver = Pvectl::Utils::ResourceResolver.new(connection)
+        task_repo = Pvectl::Repositories::Task.new(connection)
+
+        service = Pvectl::Services::Backup.new(
+          backup_repo: backup_repo,
+          resource_resolver: resolver,
+          task_repo: task_repo,
+          options: service_options
+        )
+
+        result = service.delete(@volid)
+
+        output_results([result])
+        determine_exit_code([result])
+      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
+
+      # 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
+
+      # Builds service options from command options.
+      #
+      # @return [Hash] service options
+      def service_options
+        opts = {}
+        opts[:timeout] = @options[:timeout] if @options[:timeout]
+        opts[:async] = true if @options[:async]
+        opts
+      end
+
+      # Outputs operation results using the configured formatter.
+      #
+      # @param results [Array<Models::OperationResult>] operation results
+      # @return [void]
+      def output_results(results)
+        presenter = Pvectl::Presenters::SnapshotOperationResult.new
+        format = @global_options[:output] || "table"
+        color_flag = @global_options[:color]
+
+        formatter = Pvectl::Formatters::Registry.for(format)
+        output = formatter.format(results, presenter, color: color_flag)
+        puts output
+      end
+
+      # Determines exit code based on results.
+      #
+      # @param results [Array<Models::OperationResult>] operation results
+      # @return [Integer] exit code
+      def determine_exit_code(results)
+        return ExitCodes::SUCCESS if results.all?(&:successful?)
+        return ExitCodes::SUCCESS if results.all?(&:pending?)
+
+        ExitCodes::GENERAL_ERROR
+      end
+
+      # Outputs usage error and returns exit code.
+      #
+      # @param message [String] error message
+      # @return [Integer] exit code
+      def usage_error(message)
+        $stderr.puts "Error: #{message}"
+        ExitCodes::USAGE_ERROR
+      end
+    end
+  end
+end