vagrant-orbstack 0.1.0

data/lib/vagrant-orbstack/action/create.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative '../util/machine_namer'
+require_relative '../util/orbstack_cli'
+require_relative '../util/ssh_readiness_checker'
+
+module VagrantPlugins
+  module OrbStack
+    module Action
+      # Action middleware for creating and starting OrbStack machines
+      #
+      # This middleware handles the machine creation lifecycle with full
+      # idempotency support. It checks the current machine state and:
+      # - If running: does nothing (no-op)
+      # - If stopped: starts the existing machine
+      # - If not created: creates a new machine with unique name
+      #
+      # After creation, persists machine metadata and invalidates state cache.
+      #
+      # @example Usage in action builder
+      #   Vagrant::Action::Builder.new.tap do |b|
+      #     b.use VagrantPlugins::OrbStack::Action::Create
+      #   end
+      #
+      # @api public
+      class Create
+        # Initialize the middleware.
+        #
+        # @param app [Object] The next middleware in the chain
+        # @param env [Hash] The environment hash containing :machine, :ui, etc.
+        # @api public
+        def initialize(app, _env)
+          @app = app
+        end
+
+        # Execute the middleware.
+        #
+        # Implements idempotent machine creation:
+        # 1. Query current state
+        # 2. If running: no-op
+        # 3. If stopped: start machine
+        # 4. If not created: create new machine
+        # 5. Persist metadata and invalidate cache
+        # 6. Continue middleware chain
+        #
+        # @param env [Hash] The environment hash
+        # @return [Object] Result from next middleware
+        # @raise [MachineNameCollisionError] If name generation fails
+        # @raise [OrbStackNotInstalled] If OrbStack CLI not available
+        # @raise [CommandTimeoutError] If CLI command times out
+        # @raise [CommandExecutionError] If machine creation/start fails
+        # @api public
+        def call(env)
+          handle_machine_state(env)
+          @app.call(env)
+        end
+
+        private
+
+        # Route to appropriate state handler based on current machine state.
+        #
+        # @param env [Hash] The environment hash
+        # @return [void]
+        # @api private
+        def handle_machine_state(env)
+          current_state = env[:machine].provider.state
+
+          case current_state.id
+          when :running  then handle_running_machine(env)
+          when :stopped  then handle_stopped_machine(env)
+          else                handle_not_created_machine(env)
+          end
+        end
+
+        # Handle a machine that is already running (no-op).
+        #
+        # @param env [Hash] The environment hash
+        # @return [void]
+        # @api private
+        def handle_running_machine(env)
+          env[:machine].ui.info('Machine is already running')
+        end
+
+        # Handle a machine that is stopped by starting it.
+        #
+        # @param env [Hash] The environment hash
+        # @return [void]
+        # @api private
+        def handle_stopped_machine(env)
+          machine = env[:machine]
+          machine.ui.info('Starting stopped machine...')
+          Util::OrbStackCLI.start_machine(machine.id)
+          Util::SSHReadinessChecker.wait_for_ready(machine.id, ui: machine.ui)
+          machine.provider.invalidate_state_cache
+        end
+
+        # Handle a machine that doesn't exist by creating it.
+        #
+        # @param env [Hash] The environment hash
+        # @return [void]
+        # @api private
+        def handle_not_created_machine(env)
+          create_machine(env)
+        end
+
+        # Create a new OrbStack machine.
+        #
+        # Generates unique machine name, creates machine via OrbStack CLI,
+        # persists metadata, and invalidates state cache.
+        #
+        # @param env [Hash] The environment hash
+        # @return [void]
+        # @api private
+        def create_machine(env)
+          machine = env[:machine]
+          ui = machine.ui
+
+          ui.info('Creating new machine...')
+
+          machine_name = Util::MachineNamer.generate(machine)
+          distro = build_distribution_string(machine.provider_config)
+          Util::OrbStackCLI.create_machine(machine_name, distribution: distro)
+          Util::SSHReadinessChecker.wait_for_ready(machine_name, ui: ui)
+
+          persist_metadata(env, machine_name, distro)
+
+          ui.info("Machine '#{machine_name}' created successfully")
+        end
+
+        # Build distribution string from configuration.
+        #
+        # Formats the distribution string for OrbStack CLI based on
+        # configured distro and version. If version is specified, returns
+        # "distro:version", otherwise just "distro".
+        #
+        # @param config [VagrantPlugins::OrbStack::Config] Provider configuration
+        # @return [String] Formatted distribution string
+        # @api private
+        def build_distribution_string(config)
+          return config.distro unless config.version
+
+          "#{config.distro}:#{config.version}"
+        end
+
+        # Persist machine metadata to Vagrant data directory.
+        #
+        # Stores machine ID and metadata (name, distribution, timestamp)
+        # for future Vagrant operations.
+        #
+        # @param env [Hash] The environment hash
+        # @param machine_name [String] The generated machine name
+        # @param distro [String] The distribution string (e.g., "ubuntu:noble")
+        # @return [void]
+        # @api private
+        def persist_metadata(env, machine_name, distro)
+          machine = env[:machine]
+          provider = machine.provider
+
+          # Store machine ID (Vagrant core will call machine.id= after this)
+          provider.write_machine_id(machine_name)
+
+          # Store metadata
+          metadata = {
+            'machine_name' => machine_name,
+            'distribution' => distro,
+            'created_at' => Time.now.utc.iso8601
+          }
+          provider.write_metadata(metadata)
+
+          # Invalidate state cache to force fresh query
+          provider.invalidate_state_cache
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/action/destroy.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative '../util/orbstack_cli'
+require_relative 'machine_validation'
+require 'fileutils'
+
+module VagrantPlugins
+  module OrbStack
+    module Action
+      # Action middleware for destroying (deleting) OrbStack machines
+      #
+      # This middleware handles permanent removal of OrbStack machines, including
+      # deletion from OrbStack and cleanup of local metadata files. The operation
+      # is idempotent and uses a best-effort cleanup strategy: if the OrbStack
+      # CLI deletion fails (e.g., machine already deleted or daemon offline), local
+      # cleanup continues anyway to ensure Vagrant state remains consistent.
+      #
+      # @example Usage in action builder
+      #   Vagrant::Action::Builder.new.tap do |b|
+      #     b.use VagrantPlugins::OrbStack::Action::Destroy
+      #   end
+      #
+      # @api public
+      class Destroy
+        include MachineValidation
+
+        # Initialize the middleware.
+        #
+        # @param app [Object] The next middleware in the chain
+        # @param env [Hash] The environment hash containing :machine, :ui, etc.
+        # @api public
+        def initialize(app, _env)
+          @app = app
+        end
+
+        # Execute the middleware.
+        #
+        # Destroys the machine by:
+        # 1. Calling OrbStack CLI delete command (best-effort)
+        # 2. Removing id and metadata.json files from data directory
+        # 3. Invalidating state cache
+        # 4. Continuing middleware chain
+        #
+        # If the OrbStack CLI delete fails, a warning is logged and cleanup
+        # continues. This ensures Vagrant can clean up its local state even
+        # if the machine was already deleted manually or OrbStack is offline.
+        #
+        # @param env [Hash] The environment hash
+        # @return [Object] Result from next middleware
+        # @raise [ArgumentError] If machine ID is empty string (nil is handled gracefully)
+        # @api public
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        def call(env)
+          machine = env[:machine]
+          ui = env[:ui]
+
+          # Handle already-destroyed machines gracefully (idempotency)
+          if machine.id.nil?
+            ui.info('Machine is already destroyed or was never created.')
+            return @app.call(env)
+          end
+
+          # Validate machine ID exists
+          machine_id = validate_machine_id!(machine, 'destroy')
+
+          ui.info("Destroying machine '#{machine_id}'...")
+
+          # Call OrbStack CLI to delete the machine (best-effort)
+          begin
+            Util::OrbStackCLI.delete_machine(machine_id)
+          rescue Errors::CommandExecutionError => e
+            ui.warn("Error deleting machine from OrbStack: #{e.message}")
+            ui.warn('Continuing with local cleanup...')
+          end
+
+          # Clean up metadata files from data_dir (idempotent)
+          FileUtils.rm_f(machine.provider.id_file_path)
+          FileUtils.rm_f(machine.provider.metadata_file_path)
+
+          # Invalidate state cache to ensure fresh state on next query
+          machine.provider.invalidate_state_cache
+
+          # Continue middleware chain
+          @app.call(env)
+        end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/action/halt.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative '../util/orbstack_cli'
+require_relative 'machine_validation'
+
+module VagrantPlugins
+  module OrbStack
+    module Action
+      # Action middleware for halting (stopping) OrbStack machines
+      #
+      # This middleware handles stopping a running OrbStack machine gracefully.
+      # It calls the OrbStack CLI to stop the machine and invalidates the
+      # provider's state cache to ensure subsequent state queries are fresh.
+      #
+      # @example Usage in action builder
+      #   Vagrant::Action::Builder.new.tap do |b|
+      #     b.use VagrantPlugins::OrbStack::Action::Halt
+      #   end
+      #
+      # @api public
+      class Halt
+        include MachineValidation
+
+        # Initialize the middleware.
+        #
+        # @param app [Object] The next middleware in the chain
+        # @param env [Hash] The environment hash containing :machine, :ui, etc.
+        # @api public
+        def initialize(app, _env)
+          @app = app
+        end
+
+        # Execute the middleware.
+        #
+        # Halts the machine by calling OrbStack CLI stop command,
+        # then invalidates the state cache to ensure fresh state queries.
+        #
+        # @param env [Hash] The environment hash
+        # @return [Object] Result from next middleware
+        # @raise [CommandExecutionError] If stop command fails
+        # @raise [CommandTimeoutError] If stop command times out
+        # @api public
+        def call(env)
+          machine = env[:machine]
+          ui = env[:ui]
+
+          # Validate machine ID exists
+          machine_id = validate_machine_id!(machine, 'halt')
+
+          ui.info("Halting machine '#{machine_id}'...")
+
+          # Call OrbStack CLI to stop the machine
+          Util::OrbStackCLI.stop_machine(machine_id)
+
+          # Invalidate state cache to ensure fresh state on next query
+          machine.provider.invalidate_state_cache
+
+          # Continue middleware chain
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/action/machine_validation.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module OrbStack
+    module Action
+      # Machine validation mixin for action middleware.
+      #
+      # This module provides machine ID validation for **Direct Action Pattern**
+      # actions that interact directly with OrbStack CLI. Include this module
+      # when your action needs to validate machine existence before performing
+      # CLI operations.
+      #
+      # **IMPORTANT**: Do NOT include this module in Composition Actions that
+      # orchestrate other actions. Composition actions delegate validation to
+      # their composed actions to avoid redundant checks.
+      #
+      # ## Usage
+      #
+      # ### Direct Actions (Include this module)
+      # - Create, Halt, Start, Destroy
+      # - Any action that directly calls Util::OrbStackCLI
+      # - Actions that manage state cache directly
+      #
+      # ### Composition Actions (Do NOT include)
+      # - Reload (composes Halt + Start, which both validate)
+      # - Any action that only orchestrates via Action::Builder
+      #
+      # See docs/DESIGN.md "Action Patterns" for complete pattern documentation.
+      #
+      # @example Include in a direct action
+      #   class Destroy
+      #     include MachineValidation
+      #
+      #     def call(env)
+      #       machine_id = validate_machine_id!(env[:machine], 'destroy')
+      #       # ...
+      #     end
+      #   end
+      #
+      # @api public
+      module MachineValidation
+        # Validate that a machine has a non-nil, non-empty ID.
+        #
+        # @param machine [Vagrant::Machine] The machine to validate
+        # @param action_name [String] The action being performed (for error messages)
+        # @return [String] The machine ID if valid
+        # @raise [ArgumentError] If machine ID is nil or empty
+        # @api public
+        def validate_machine_id!(machine, action_name)
+          machine_id = machine.id
+          if machine_id.nil? || machine_id.empty?
+            raise ArgumentError,
+                  "Cannot #{action_name} machine: machine ID is nil or empty"
+          end
+          machine_id
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/action/reload.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module OrbStack
+    module Action
+      # Action middleware for reloading (restarting) OrbStack machines.
+      #
+      # This is a **Composition Action** that orchestrates Halt + Start actions
+      # rather than directly interacting with OrbStack CLI. Following the
+      # composition pattern, this class:
+      #
+      # - Does NOT include MachineValidation (composed actions handle validation)
+      # - Does NOT directly call OrbStackCLI (delegates to Halt/Start)
+      # - Does NOT manage state cache (composed actions handle invalidation)
+      #
+      # The actual work is performed by the Action::Builder chain in the
+      # provider's action method, which composes: Halt → Start → (optional) Provision
+      #
+      # This class exists as a pattern consistency marker and for potential future
+      # pre/post reload logic that doesn't fit in the composed actions.
+      #
+      # See docs/DESIGN.md "Action Patterns" section for pattern documentation.
+      #
+      # @example Usage in action builder
+      #   Vagrant::Action::Builder.new.tap do |b|
+      #     b.use VagrantPlugins::OrbStack::Action::Reload
+      #   end
+      #
+      # @api public
+      class Reload
+        # Initialize the middleware.
+        #
+        # @param app [Object] The next middleware in the chain
+        # @param env [Hash] The environment hash containing :machine, :ui, etc.
+        # @api public
+        def initialize(app, _env)
+          @app = app
+        end
+
+        # Execute the middleware.
+        #
+        # This is a pass-through middleware - the actual reload logic is
+        # composed in the provider's action method. This class exists to
+        # maintain consistency with the action middleware pattern.
+        #
+        # @param env [Hash] The environment hash
+        # @return [Object] Result from next middleware
+        # @api public
+        def call(env)
+          # Continue middleware chain
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/action/ssh_run.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'machine_validation'
+
+module VagrantPlugins
+  module OrbStack
+    module Action
+      # Action middleware for validating SSH readiness before command execution
+      #
+      # This middleware validates that the machine is in a running state before
+      # Vagrant executes SSH commands via `vagrant ssh -c "command"`. It does NOT
+      # execute the SSH command itself - Vagrant's built-in SSH layer handles that
+      # after this validation middleware approves the operation.
+      #
+      # Unlike other actions, SSHRun is read-only: it only validates state and does
+      # not call OrbStack CLI or modify machine state. This makes it safe to call
+      # repeatedly without side effects.
+      #
+      # @example Usage in action builder
+      #   Vagrant::Action::Builder.new.tap do |b|
+      #     b.use VagrantPlugins::OrbStack::Action::SSHRun
+      #   end
+      #
+      # @api public
+      class SSHRun
+        include MachineValidation
+
+        # Initialize the middleware.
+        #
+        # @param app [Object] The next middleware in the chain
+        # @param env [Hash] The environment hash containing :machine, :ui, etc.
+        # @api public
+        def initialize(app, _env)
+          @app = app
+        end
+
+        # Execute the middleware.
+        #
+        # Validates that the machine has a valid ID and is in running state.
+        # If validation passes, continues the middleware chain for Vagrant to
+        # execute the SSH command. If validation fails, raises an error and
+        # blocks SSH command execution.
+        #
+        # This is a read-only operation:
+        # - Does NOT call OrbStack CLI (only queries cached state)
+        # - Does NOT invalidate state cache (no state changes occur)
+        # - Does NOT display UI messages (validation only)
+        #
+        # @param env [Hash] The environment hash
+        # @return [Object] Result from next middleware
+        # @raise [ArgumentError] If machine ID is nil or empty (from MachineValidation)
+        # @raise [Errors::SSHNotReady] If machine is not in running state
+        # @api public
+        def call(env)
+          machine = env[:machine]
+
+          # Validate machine ID exists (from MachineValidation)
+          validate_machine_id!(machine, 'ssh')
+
+          # Validate machine is running
+          state = machine.provider.state
+          raise Errors::SSHNotReady, machine_name: machine.id unless state.id == :running
+
+          # Continue middleware chain (Vagrant handles SSH execution)
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/action/start.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../util/orbstack_cli'
+require_relative 'machine_validation'
+
+module VagrantPlugins
+  module OrbStack
+    module Action
+      # Action middleware for starting OrbStack machines
+      #
+      # This middleware handles starting a stopped OrbStack machine.
+      # It calls the OrbStack CLI to start the machine and invalidates the
+      # provider's state cache to ensure subsequent state queries are fresh.
+      #
+      # The OrbStack CLI is idempotent - starting an already running machine
+      # is safe and will not cause an error.
+      #
+      # @example Usage in action builder
+      #   Vagrant::Action::Builder.new.tap do |b|
+      #     b.use VagrantPlugins::OrbStack::Action::Start
+      #   end
+      #
+      # @api public
+      class Start
+        include MachineValidation
+
+        # Initialize the middleware.
+        #
+        # @param app [Object] The next middleware in the chain
+        # @param env [Hash] The environment hash containing :machine, :ui, etc.
+        # @api public
+        def initialize(app, _env)
+          @app = app
+        end
+
+        # Execute the middleware.
+        #
+        # Starts the machine by calling OrbStack CLI start command,
+        # then invalidates the state cache to ensure fresh state queries.
+        #
+        # @param env [Hash] The environment hash
+        # @return [Object] Result from next middleware
+        # @raise [CommandExecutionError] If start command fails
+        # @raise [CommandTimeoutError] If start command times out
+        # @raise [OrbStackNotInstalledError] If OrbStack CLI is not available
+        # @api public
+        def call(env)
+          machine = env[:machine]
+          ui = env[:ui]
+
+          # Validate machine ID exists
+          machine_id = validate_machine_id!(machine, 'start')
+
+          ui.info("Starting machine '#{machine_id}'...")
+
+          # Call OrbStack CLI to start the machine
+          Util::OrbStackCLI.start_machine(machine_id)
+
+          # Invalidate state cache to ensure fresh state on next query
+          machine.provider.invalidate_state_cache
+
+          # Continue middleware chain
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/action.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module OrbStack
+    # Action middleware namespace for OrbStack provider.
+    #
+    # Contains action classes that implement Vagrant middleware operations
+    # for OrbStack machine lifecycle management (create, halt, destroy, etc).
+    #
+    # @api public
+    module Action
+      # Action middleware autoload definitions
+      autoload :Create, 'vagrant-orbstack/action/create'
+      autoload :Destroy, 'vagrant-orbstack/action/destroy'
+      autoload :Halt, 'vagrant-orbstack/action/halt'
+      autoload :Reload, 'vagrant-orbstack/action/reload'
+      autoload :SSHRun, 'vagrant-orbstack/action/ssh_run'
+      autoload :Start, 'vagrant-orbstack/action/start'
+    end
+  end
+end