pvectl 0.2.0

data/lib/pvectl/services/edit_hosts.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates the interactive editing flow for /etc/hosts on a node.
+    #
+    # Fetches current /etc/hosts content + digest, opens it in an editor,
+    # and POSTs the new content back with the original digest for optimistic
+    # locking. If Proxmox returns a digest collision (concurrent modification)
+    # or any other error, the message is surfaced verbatim to the user.
+    #
+    # Unlike DNS (structured YAML), /etc/hosts is edited as raw text —
+    # there is no parsing or validation pvectl-side.
+    #
+    # @example Basic usage
+    #   service = EditHosts.new(hosts_repository: repo)
+    #   result = service.execute(node_name: "pve1")
+    #
+    # @example Dry run
+    #   service = EditHosts.new(hosts_repository: repo, options: { dry_run: true })
+    #   result = service.execute(node_name: "pve1")
+    #
+    class EditHosts
+      # Creates a new EditHosts service.
+      #
+      # @param hosts_repository [Repositories::Hosts] Hosts repository
+      # @param editor_session [EditorSession, nil] optional injected editor session
+      # @param options [Hash] options (dry_run)
+      def initialize(hosts_repository:, editor_session: nil, options: {})
+        @hosts_repository = hosts_repository
+        @editor_session = editor_session
+        @options = options
+      end
+
+      # Executes the interactive /etc/hosts edit flow.
+      #
+      # @param node_name [String] node name
+      # @return [Models::NodeOperationResult, nil] result, or nil if cancelled/no changes
+      def execute(node_name:)
+        hosts = @hosts_repository.fetch(node_name)
+        original = hosts.data || ""
+        digest = hosts.digest
+
+        session = @editor_session || EditorSession.new
+        edited = session.edit(original)
+
+        return nil if edited.nil?
+        return nil if edited == original
+
+        resource_info = {
+          node_name: node_name,
+          diff: { original: original, edited: edited }
+        }
+
+        return build_result(resource_info, success: true) if @options[:dry_run]
+
+        @hosts_repository.update(node_name, edited, digest)
+        build_result(resource_info, success: true)
+      rescue StandardError => e
+        build_result({ node_name: node_name }, success: false, error: e.message)
+      end
+
+      private
+
+      # Builds a NodeOperationResult with the :edit operation.
+      #
+      # @param resource_info [Hash] resource info (node_name, optional diff)
+      # @param attrs [Hash] additional result attributes
+      # @return [Models::NodeOperationResult]
+      def build_result(resource_info, **attrs)
+        node_model = Models::Node.new(name: resource_info[:node_name])
+        Models::NodeOperationResult.new(
+          operation: :edit, node_model: node_model, resource: resource_info, **attrs
+        )
+      end
+    end
+  end
+end

data/lib/pvectl/services/edit_node.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates the interactive node configuration editing flow.
+    #
+    # Fetches current config, presents it as YAML in an editor,
+    # computes diff, and applies changes. Uses plain YAML (not
+    # ConfigSerializer) since node config is flat key-value.
+    #
+    # @example Basic usage
+    #   service = EditNode.new(node_repository: repo)
+    #   result = service.execute(node_name: "pve1")
+    #
+    # @example Dry run with injected editor session
+    #   service = EditNode.new(node_repository: repo, editor_session: session,
+    #                          options: { dry_run: true })
+    #   result = service.execute(node_name: "pve1")
+    #
+    class EditNode
+      # Read-only keys that should not be sent back to the API.
+      READONLY_KEYS = %i[digest].freeze
+
+      # Creates a new EditNode service.
+      #
+      # @param node_repository [Repositories::Node] Node repository
+      # @param editor_session [EditorSession, nil] optional injected editor session
+      # @param options [Hash] options (dry_run)
+      def initialize(node_repository:, editor_session: nil, options: {})
+        @node_repository = node_repository
+        @editor_session = editor_session
+        @options = options
+      end
+
+      # Executes the interactive node edit flow.
+      #
+      # @param node_name [String] node name
+      # @return [Models::NodeOperationResult, nil] result, or nil if cancelled/no changes
+      def execute(node_name:)
+        node = @node_repository.get(node_name)
+        return not_found_result(node_name) unless node
+
+        config = @node_repository.fetch_config(node_name)
+        resource_info = { node_name: node_name, status: node.status }
+
+        # Build editable YAML (exclude digest — it's for optimistic locking only)
+        editable = config.reject { |k, _| READONLY_KEYS.include?(k) }
+        # Convert symbol keys to strings for clean YAML output (avoids :key: format)
+        string_keyed = editable.transform_keys(&:to_s)
+        yaml_content = "# Node: #{node_name}\n# Edit configuration below. Save and close to apply.\n" +
+                        string_keyed.to_yaml
+
+        session = @editor_session || EditorSession.new
+        edited = session.edit(yaml_content)
+
+        return nil unless edited
+
+        # Parse edited YAML (strip comment lines)
+        cleaned = edited.lines.reject { |l| l.strip.start_with?("#") }.join
+        edited_config = YAML.safe_load(cleaned, symbolize_names: true) || {}
+
+        # Compute diff against original editable config (with symbol keys)
+        changes = compute_diff(editable, edited_config)
+
+        if changes[:changed].empty? && changes[:added].empty? && changes[:removed].empty?
+          return nil
+        end
+
+        resource_info[:diff] = changes
+
+        if @options[:dry_run]
+          return build_result(resource_info, success: true)
+        end
+
+        update_params = build_update_params(changes, config)
+        @node_repository.update(node_name, update_params)
+        build_result(resource_info, success: true)
+      rescue StandardError => e
+        build_result({ node_name: node_name }, success: false, error: e.message)
+      end
+
+      private
+
+      # Computes diff between original and edited config.
+      #
+      # @param original [Hash] original config (without readonly keys)
+      # @param edited [Hash] edited config
+      # @return [Hash] diff with :changed, :added, :removed
+      def compute_diff(original, edited)
+        changed = {}
+        added = {}
+        removed = []
+
+        edited.each do |key, value|
+          orig_value = original[key]
+          if orig_value.nil?
+            added[key] = value
+          elsif orig_value.to_s != value.to_s
+            changed[key] = [orig_value.to_s, value.to_s]
+          end
+        end
+
+        original.each_key do |key|
+          removed << key unless edited.key?(key)
+        end
+
+        { changed: changed, added: added, removed: removed }
+      end
+
+      # Builds API update parameters from diff.
+      #
+      # @param changes [Hash] diff hash with :changed, :added, :removed
+      # @param original_config [Hash] original config (for digest)
+      # @return [Hash] API parameters
+      def build_update_params(changes, original_config)
+        params = {}
+        changes[:changed].each { |key, (_old, new_val)| params[key] = new_val }
+        changes[:added].each { |key, val| params[key] = val }
+        unless changes[:removed].empty?
+          params[:delete] = changes[:removed].map(&:to_s).join(",")
+        end
+        params[:digest] = original_config[:digest] if original_config[:digest]
+        params
+      end
+
+      # Builds a NodeOperationResult with the :edit operation.
+      #
+      # @param resource_info [Hash] resource info (node_name, status)
+      # @param attrs [Hash] additional result attributes
+      # @return [Models::NodeOperationResult]
+      def build_result(resource_info, **attrs)
+        node_model = Models::Node.new(name: resource_info[:node_name])
+        Models::NodeOperationResult.new(
+          operation: :edit, node_model: node_model, resource: resource_info, **attrs
+        )
+      end
+
+      # Builds a not-found error result.
+      #
+      # @param node_name [String] node name
+      # @return [Models::NodeOperationResult]
+      def not_found_result(node_name)
+        build_result({ node_name: node_name }, success: false, error: "Node #{node_name} not found")
+      end
+    end
+  end
+end

data/lib/pvectl/services/edit_vm.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates the interactive VM configuration editing flow.
+    #
+    # Fetches current config, opens it in an editor as structured YAML,
+    # validates changes, computes a diff, and applies updates via the API.
+    # Supports dry-run mode and optimistic locking via digest.
+    #
+    # @example Basic usage
+    #   service = EditVm.new(vm_repository: repo)
+    #   result = service.execute(vmid: 100)
+    #
+    # @example Dry run with injected editor session
+    #   service = EditVm.new(vm_repository: repo, editor_session: session,
+    #                        options: { dry_run: true })
+    #   result = service.execute(vmid: 100)
+    #
+    class EditVm
+      # Creates a new EditVm service.
+      #
+      # @param vm_repository [Repositories::Vm] VM repository
+      # @param editor_session [EditorSession, nil] optional injected editor session
+      # @param options [Hash] options (dry_run)
+      def initialize(vm_repository:, editor_session: nil, options: {})
+        @vm_repository = vm_repository
+        @editor_session = editor_session
+        @options = options
+      end
+
+      # Executes the interactive VM edit flow.
+      #
+      # @param vmid [Integer] VM identifier
+      # @return [Models::VmOperationResult, nil] operation result, or nil if cancelled/no changes
+      def execute(vmid:)
+        vm = @vm_repository.get(vmid)
+        return not_found_result(vmid) unless vm
+
+        config = @vm_repository.fetch_config(vm.node, vmid)
+        resource_info = { vmid: vmid, node: vm.node, status: vm.status }
+
+        yaml_content = ConfigSerializer.to_yaml(config, type: :vm, resource: resource_info)
+
+        validator = ->(content) { ConfigSerializer.validate(content, type: :vm) }
+        session = @editor_session || EditorSession.new(validator: validator)
+        edited = session.edit(yaml_content)
+
+        return nil unless edited
+
+        original_roundtrip = ConfigSerializer.from_yaml(yaml_content, type: :vm)
+        edited_flat = ConfigSerializer.from_yaml(edited, type: :vm)
+
+        violations = ConfigSerializer.readonly_violations(original_roundtrip, edited_flat, type: :vm)
+        unless violations.empty?
+          return build_result(resource_info, success: false,
+                              error: "Read-only fields cannot be changed: #{violations.join(', ')}")
+        end
+
+        changes = ConfigSerializer.diff(original_roundtrip, edited_flat)
+
+        if changes[:changed].empty? && changes[:added].empty? && changes[:removed].empty?
+          return nil
+        end
+
+        params = build_update_params(changes, config)
+
+        resource_info[:diff] = changes
+
+        if @options[:dry_run]
+          return build_result(resource_info, success: true)
+        end
+
+        @vm_repository.update(vmid, vm.node, params)
+        build_result(resource_info, success: true)
+      rescue StandardError => e
+        build_result({ vmid: vmid }, success: false, error: e.message)
+      end
+
+      private
+
+      # Builds API update parameters from a diff hash.
+      #
+      # Maps changed/added keys to their new values, removed keys to the
+      # Proxmox `delete` parameter, and includes digest for optimistic locking.
+      #
+      # @param changes [Hash] diff hash with :changed, :added, :removed
+      # @param original_config [Hash] original flat config (for digest)
+      # @return [Hash] Proxmox API parameters
+      def build_update_params(changes, original_config)
+        params = {}
+        changes[:changed].each { |key, (_old, new_val)| params[key] = new_val }
+        changes[:added].each { |key, val| params[key] = val }
+        unless changes[:removed].empty?
+          params[:delete] = changes[:removed].map(&:to_s).join(",")
+        end
+        params[:digest] = original_config[:digest] if original_config[:digest]
+        params
+      end
+
+      # Builds a VmOperationResult with the :edit operation.
+      #
+      # @param resource_info [Hash] resource info (vmid, node, status)
+      # @param attrs [Hash] additional result attributes
+      # @return [Models::VmOperationResult]
+      def build_result(resource_info, **attrs)
+        vm = Models::Vm.new(
+          vmid: resource_info[:vmid],
+          node: resource_info[:node]
+        )
+        Models::VmOperationResult.new(
+          operation: :edit, vm: vm, resource: resource_info, **attrs
+        )
+      end
+
+      # Builds a not-found error result.
+      #
+      # @param vmid [Integer] VM identifier
+      # @return [Models::VmOperationResult]
+      def not_found_result(vmid)
+        build_result({ vmid: vmid }, success: false, error: "VM #{vmid} not found")
+      end
+    end
+  end
+end

data/lib/pvectl/services/edit_volume.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates the interactive volume property editing flow.
+    #
+    # Fetches the disk config string from VM/CT config, parses it into
+    # editable YAML (key-value pairs), opens editor, and applies changes.
+    # Size changes delegate to ResizeVolume; config changes rebuild the
+    # disk config string.
+    #
+    # @example Basic usage
+    #   service = EditVolume.new(repository: vm_repo, resource_type: :vm)
+    #   result = service.execute(id: 100, disk: "scsi0", node: "pve1")
+    #
+    # @example Dry run with injected editor session
+    #   service = EditVolume.new(repository: vm_repo, resource_type: :vm,
+    #                            editor_session: session, options: { dry_run: true })
+    #   result = service.execute(id: 100, disk: "scsi0", node: "pve1")
+    #
+    class EditVolume
+      # @param repository [Repositories::Vm, Repositories::Container] resource repository
+      # @param resource_type [Symbol] :vm or :container
+      # @param editor_session [EditorSession, nil] optional injected editor session
+      # @param options [Hash] options (dry_run)
+      def initialize(repository:, resource_type:, editor_session: nil, options: {})
+        @repository = repository
+        @resource_type = resource_type
+        @editor_session = editor_session
+        @options = options
+      end
+
+      # Executes the interactive volume edit flow.
+      #
+      # @param id [Integer] resource ID (VMID or CTID)
+      # @param disk [String] disk name (e.g., "scsi0", "rootfs")
+      # @param node [String] node name
+      # @return [Models::VolumeOperationResult, nil] result, or nil if cancelled/no changes
+      def execute(id:, disk:, node:)
+        config = @repository.fetch_config(node, id)
+        disk_value = config[disk.to_sym]
+
+        unless disk_value
+          return build_result(id, disk, node, success: false,
+                              error: "Volume '#{disk}' not found in config for resource #{id}")
+        end
+
+        editable = parse_disk_config(disk_value)
+        yaml_content = build_yaml_content(editable, disk, id, node)
+
+        session = @editor_session || EditorSession.new
+        edited = session.edit(yaml_content)
+
+        return nil unless edited
+
+        edited_config = parse_edited_yaml(edited)
+        changes = compute_diff(editable, edited_config)
+
+        return nil if no_changes?(changes)
+
+        if @options[:dry_run]
+          return build_result(id, disk, node, success: true,
+                              resource: { diff: changes })
+        end
+
+        apply_changes(id, disk, node, disk_value, changes)
+        build_result(id, disk, node, success: true)
+      rescue ResizeVolume::VolumeNotFoundError, ResizeVolume::SizeTooSmallError, ArgumentError => e
+        build_result(id, disk, node, success: false, error: e.message)
+      rescue StandardError => e
+        build_result(id, disk, node, success: false, error: e.message)
+      end
+
+      private
+
+      # Parses a disk config string into a hash of editable properties.
+      #
+      # Input: "local-lvm:vm-100-disk-0,size=32G,cache=none"
+      # Output: { "size" => "32G", "cache" => "none" }
+      #
+      # The base (storage:vol-id) is NOT included — it's read-only.
+      #
+      # @param disk_value [String] disk config string
+      # @return [Hash] editable properties with string keys
+      def parse_disk_config(disk_value)
+        parts = disk_value.to_s.split(",")
+        parts.shift # Remove base "storage:vol-id"
+
+        props = {}
+        parts.each do |part|
+          key, value = part.split("=", 2)
+          props[key] = value
+        end
+        props
+      end
+
+      # Builds YAML content for the editor with comment header.
+      #
+      # @param editable [Hash] editable properties
+      # @param disk [String] disk name
+      # @param id [Integer] resource ID
+      # @param node [String] node name
+      # @return [String] YAML content with comments
+      def build_yaml_content(editable, disk, id, node)
+        "# Volume: #{disk} (resource #{id} on #{node})\n" \
+          "# Edit properties below. Save and close to apply.\n" +
+          editable.to_yaml
+      end
+
+      # Parses edited YAML content, stripping comment lines.
+      #
+      # @param edited [String] raw editor content
+      # @return [Hash] parsed config with string keys
+      def parse_edited_yaml(edited)
+        cleaned = edited.lines.reject { |l| l.strip.start_with?("#") }.join
+        YAML.safe_load(cleaned) || {}
+      end
+
+      # Checks whether the diff contains any actual changes.
+      #
+      # @param changes [Hash] diff hash with :changed, :added, :removed
+      # @return [Boolean] true if no changes detected
+      def no_changes?(changes)
+        changes[:changed].empty? && changes[:added].empty? && changes[:removed].empty?
+      end
+
+      # Computes diff between original and edited config.
+      #
+      # @param original [Hash] original config (string keys)
+      # @param edited [Hash] edited config (string keys)
+      # @return [Hash] diff with :changed, :added, :removed
+      def compute_diff(original, edited)
+        changed = {}
+        added = {}
+        removed = []
+
+        edited.each do |key, value|
+          orig_value = original[key.to_s]
+          if orig_value.nil?
+            added[key.to_s] = value
+          elsif orig_value.to_s != value.to_s
+            changed[key.to_s] = [orig_value.to_s, value.to_s]
+          end
+        end
+
+        original.each_key do |key|
+          removed << key.to_s unless edited.key?(key.to_s)
+        end
+
+        { changed: changed, added: added, removed: removed }
+      end
+
+      # Applies changes — delegates size to ResizeVolume, config to rebuild.
+      #
+      # @param id [Integer] resource ID
+      # @param disk [String] disk name
+      # @param node [String] node name
+      # @param original_disk_value [String] original disk config string
+      # @param changes [Hash] diff hash
+      def apply_changes(id, disk, node, original_disk_value, changes)
+        size_change = changes[:changed].delete("size") || changes[:added].delete("size")
+
+        if size_change
+          new_size = size_change.is_a?(Array) ? size_change[1] : size_change
+          parsed_size = ResizeVolume.parse_size(new_size.to_s)
+          resize_service = ResizeVolume.new(repository: @repository)
+          resize_service.preflight(id, disk, parsed_size, node: node)
+          resize_service.perform(id, disk, parsed_size.raw, node: node)
+        end
+
+        config_updates = {}
+        changes[:changed].each { |key, (_old, new_val)| config_updates[key] = new_val }
+        changes[:added].each { |key, val| config_updates[key] = val }
+
+        if !config_updates.empty? || !changes[:removed].empty?
+          new_disk_value = rebuild_disk_config(original_disk_value, config_updates, changes[:removed])
+          @repository.update(id, node, { disk.to_sym => new_disk_value })
+        end
+      end
+
+      # Rebuilds a disk config string with updated/removed properties.
+      #
+      # @param current_value [String] current disk config string
+      # @param updates [Hash] key-value pairs to update
+      # @param removed_keys [Array<String>] keys to remove
+      # @return [String] updated config string
+      def rebuild_disk_config(current_value, updates, removed_keys = [])
+        parts = current_value.to_s.split(",")
+        base = parts.shift
+
+        existing = {}
+        parts.each do |part|
+          key, value = part.split("=", 2)
+          existing[key] = value
+        end
+
+        updates.each { |key, value| existing[key.to_s] = value.to_s }
+        removed_keys.each { |key| existing.delete(key.to_s) }
+
+        config_parts = existing.map { |k, v| "#{k}=#{v}" }
+        ([base] + config_parts).join(",")
+      end
+
+      # Builds a VolumeOperationResult.
+      #
+      # @param id [Integer] resource ID
+      # @param disk [String] disk name
+      # @param node [String] node name
+      # @param attrs [Hash] additional result attributes
+      # @return [Models::VolumeOperationResult]
+      def build_result(id, disk, node, **attrs)
+        volume = Models::Volume.new(
+          name: disk,
+          resource_type: @resource_type.to_s,
+          resource_id: id,
+          node: node
+        )
+        Models::VolumeOperationResult.new(
+          operation: :edit, volume: volume, **attrs
+        )
+      end
+    end
+  end
+end

data/lib/pvectl/services/get/resource_service.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    module Get
+      # Service for fetching and formatting resource data.
+      #
+      # Orchestrates the data flow between:
+      # - ResourceHandler (provides models and presenter)
+      # - Formatters::Registry (formats output)
+      #
+      # This follows ARCHITECTURE.md section 3.4:
+      # "Services orchestrate data flow between Repository, Models, and Formatters"
+      #
+      # @example Basic usage
+      #   handler = ResourceRegistry.for("nodes")
+      #   service = ResourceService.new(handler: handler, format: "table")
+      #   output = service.list(node: "pve1")
+      #   puts output
+      #
+      class ResourceService
+        # Creates a new ResourceService.
+        #
+        # @param handler [ResourceHandler] the resource handler for data fetching
+        # @param format [String] output format (table, json, yaml, wide)
+        # @param color_enabled [Boolean] whether to enable colored output
+        def initialize(handler:, format: "table", color_enabled: true)
+          @handler = handler
+          @format = format
+          @color_enabled = color_enabled
+        end
+
+        # Fetches and formats resources.
+        #
+        # @param node [String, nil] filter by node name
+        # @param name [String, nil] filter by resource name
+        # @param args [Array<String>] additional positional arguments (e.g., VMIDs for snapshots)
+        # @param storage [String, nil] filter by storage (for backups)
+        # @param vmid [Array<String>, nil] filter by VM/CT IDs
+        # @param selector [Selectors::Base, nil] client-side selector for filtering results
+        # @param options [Hash] additional options passed through to handler (e.g., limit, since, type_filter)
+        # @return [String] formatted output string
+        def list(node: nil, name: nil, args: [], storage: nil, vmid: nil, selector: nil, **options)
+          models = @handler.list(node: node, name: name, args: args, storage: storage, vmid: vmid, **options)
+          models = selector.apply(models) if selector && !selector.empty?
+          presenter = @handler.presenter
+          format_output(models, presenter)
+        end
+
+        # Describes and formats a single resource.
+        #
+        # For local storage with multiple instances, returns list of nodes
+        # when no node specified, or full describe when node is specified.
+        #
+        # @param name [String] resource name
+        # @param node [String, nil] filter by node name (for local storage)
+        # @param vmid [Array<String>, nil] filter by VM/CT IDs
+        # @return [String] formatted output string
+        def describe(name:, node: nil, args: [], vmid: nil)
+          result = @handler.describe(name: name, node: node, args: args, vmid: vmid)
+          presenter = @handler.presenter
+
+          if result.is_a?(Array)
+            # Multiple instances - format as list
+            format_output(result, presenter)
+          else
+            # Single model - format as describe
+            format_output_describe(result, presenter)
+          end
+        end
+
+        private
+
+        attr_reader :handler, :format, :color_enabled
+
+        # Formats models for output using the appropriate formatter.
+        #
+        # @param models [Array<Object>] collection of models
+        # @param presenter [Presenters::Base] presenter for the resource type
+        # @return [String] formatted output
+        def format_output(models, presenter)
+          formatter = Formatters::Registry.for(format)
+          formatter.format(models, presenter, color_enabled: color_enabled)
+        end
+
+        # Formats single model for describe output.
+        #
+        # @param model [Object] single model
+        # @param presenter [Presenters::Base] presenter for the resource type
+        # @return [String] formatted output
+        def format_output_describe(model, presenter)
+          formatter = Formatters::Registry.for(format)
+          formatter.format(model, presenter, color_enabled: color_enabled, describe: true)
+        end
+      end
+    end
+  end
+end