vagrant-orbstack 0.1.0

data/lib/vagrant-orbstack/config.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'vagrant-orbstack'
+
+module VagrantPlugins
+  module OrbStack
+    # Configuration class for OrbStack provider.
+    #
+    # This class defines configuration options available in Vagrantfiles
+    # for customizing OrbStack machine creation and behavior.
+    #
+    # @example Basic configuration
+    #   Vagrant.configure("2") do |config|
+    #     config.vm.provider :orbstack do |os|
+    #       os.distro = "ubuntu"
+    #       os.version = "22.04"
+    #       os.machine_name = "my-dev-env"
+    #     end
+    #   end
+    #
+    # @api public
+    class Config < Vagrant.plugin('2', :config)
+      # @!attribute [rw] distro
+      #   Linux distribution to use for the machine
+      #   @return [String, nil] Distribution name (e.g., "ubuntu", "debian")
+      #   @api public
+      #
+      # @!attribute [rw] version
+      #   Distribution version to use
+      #   @return [String, nil] Version string (e.g., "22.04")
+      #   @api public
+      #
+      # @!attribute [rw] machine_name
+      #   Custom name for the OrbStack machine
+      #   @return [String, nil] Machine name
+      #   @api public
+      #
+      # @!attribute [rw] ssh_username
+      #   Custom SSH username for connecting to the machine
+      #   @return [String, nil] SSH username (defaults to OrbStack's default if nil)
+      #   @api public
+      #
+      # @!attribute [rw] forward_agent
+      #   Enable SSH agent forwarding
+      #   @return [Boolean, nil] Whether to forward SSH agent (defaults to false)
+      #   @api public
+      attr_accessor :distro
+      attr_accessor :version, :machine_name, :ssh_username, :forward_agent
+
+      # Error message constants for validation
+      DISTRO_EMPTY_ERROR = 'distro cannot be empty'
+      MACHINE_NAME_FORMAT_ERROR = 'machine_name must contain only alphanumeric characters and hyphens'
+      SSH_USERNAME_EMPTY_ERROR = 'ssh_username cannot be empty'
+      FORWARD_AGENT_BOOLEAN_ERROR = 'forward_agent must be a boolean (true or false)'
+
+      # Regular expression pattern for valid machine_name format.
+      #
+      # Valid machine names must:
+      # - Start with an alphanumeric character (a-z, A-Z, 0-9)
+      # - End with an alphanumeric character
+      # - May contain hyphens between alphanumeric segments
+      # - No consecutive hyphens allowed
+      MACHINE_NAME_PATTERN = /^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$/
+
+      # Initialize configuration with unset values.
+      #
+      # @api public
+      def initialize
+        super
+        @distro = VagrantPlugins::OrbStack::UNSET_VALUE
+        @version = VagrantPlugins::OrbStack::UNSET_VALUE
+        @machine_name = VagrantPlugins::OrbStack::UNSET_VALUE
+        @ssh_username = VagrantPlugins::OrbStack::UNSET_VALUE
+        @forward_agent = VagrantPlugins::OrbStack::UNSET_VALUE
+        @logger = Log4r::Logger.new('vagrant_orbstack::config')
+      end
+
+      # Finalize configuration by setting defaults.
+      #
+      # Called by Vagrant after Vagrantfile is loaded to set default values
+      # for any unset configuration options.
+      #
+      # @api public
+      def finalize!
+        @distro = 'ubuntu' if @distro == VagrantPlugins::OrbStack::UNSET_VALUE
+        @version = nil if @version == VagrantPlugins::OrbStack::UNSET_VALUE
+        @machine_name = nil if @machine_name == VagrantPlugins::OrbStack::UNSET_VALUE
+        @ssh_username = nil if @ssh_username == VagrantPlugins::OrbStack::UNSET_VALUE
+        @forward_agent = false if @forward_agent == VagrantPlugins::OrbStack::UNSET_VALUE
+      end
+
+      # Validate configuration values.
+      #
+      # @param [Vagrant::Machine] _machine The machine to validate for
+      # @return [Hash<String, Array<String>>] Validation errors by namespace
+      # @api public
+      def validate(_machine)
+        errors = _detected_errors
+        validate_distro(errors)
+        validate_machine_name(errors)
+        validate_ssh_username(errors)
+        validate_forward_agent(errors)
+        { 'OrbStack Provider' => errors }
+      end
+
+      private
+
+      # Validation methods use defensive type coercion (.to_s) to prevent
+      # NoMethodError crashes if attributes are accidentally set to non-String types.
+      # This approach prioritizes robustness over strict type enforcement.
+      #
+      # Pattern: Always check nil first, then coerce to string for validation.
+      #
+      # Example:
+      #   return if @attribute.nil?
+      #   errors << ERROR_CONSTANT if @attribute.to_s.strip.empty?
+
+      # Validate that distro attribute is not empty.
+      #
+      # @param errors [Array<String>] Error accumulator array
+      # @return [void]
+      def validate_distro(errors)
+        errors << DISTRO_EMPTY_ERROR if @distro.nil? || @distro.to_s.strip.empty?
+      end
+
+      # Validate machine_name format if set.
+      #
+      # @param errors [Array<String>] Error accumulator array
+      # @return [void]
+      def validate_machine_name(errors)
+        return if @machine_name.nil?
+
+        # Convert to string for regex matching (defensive programming)
+        machine_name_str = @machine_name.to_s
+        errors << MACHINE_NAME_FORMAT_ERROR unless machine_name_str.match?(MACHINE_NAME_PATTERN)
+      end
+
+      # Validate that ssh_username attribute is not empty if set.
+      #
+      # @param errors [Array<String>] Error accumulator array
+      # @return [void]
+      def validate_ssh_username(errors)
+        return if @ssh_username.nil?
+        return unless @ssh_username.to_s.strip.empty?
+
+        errors << SSH_USERNAME_EMPTY_ERROR
+      end
+
+      # Validate that forward_agent is a boolean if set.
+      #
+      # @param errors [Array<String>] Error accumulator array
+      # @return [void]
+      def validate_forward_agent(errors)
+        return if @forward_agent.nil?
+        return if [true, false].include?(@forward_agent)
+
+        errors << FORWARD_AGENT_BOOLEAN_ERROR
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/errors.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module OrbStack
+    # Base error class for OrbStack provider errors.
+    # Inherits from Vagrant's VagrantError to integrate with Vagrant's error handling.
+    class Errors < Vagrant::Errors::VagrantError
+      error_namespace('vagrant_orbstack.errors')
+    end
+
+    # Error raised when OrbStack is not installed.
+    class OrbStackNotInstalled < Errors
+      error_key(:orbstack_not_installed)
+    end
+
+    # Error raised when OrbStack is not running.
+    class OrbStackNotRunning < Errors
+      error_key(:orbstack_not_running)
+    end
+
+    # Error raised when an OrbStack CLI command fails.
+    class CommandExecutionError < Errors
+      error_key(:command_execution_error)
+    end
+
+    # Error raised when an OrbStack CLI command times out.
+    class CommandTimeoutError < Errors
+      error_key(:command_timeout_error)
+    end
+
+    # Error raised when machine name collision cannot be resolved after retries.
+    class MachineNameCollisionError < Errors
+      error_key(:machine_name_collision)
+    end
+
+    # Error raised when SSH is not ready on a machine.
+    class SSHNotReady < Errors
+      error_key(:ssh_not_ready)
+    end
+
+    # Error raised when SSH connection fails.
+    class SSHConnectionFailed < Errors
+      error_key(:ssh_connection_failed)
+    end
+
+    # Reopen Errors class to add nested constants for namespaced access
+    # This allows both VagrantPlugins::OrbStack::CommandTimeoutError
+    # and VagrantPlugins::OrbStack::Errors::CommandTimeoutError to work
+    class Errors
+      # Alias error classes inside Errors namespace for tests that expect them there
+      OrbStackNotInstalled = ::VagrantPlugins::OrbStack::OrbStackNotInstalled
+      OrbStackNotInstalledError = OrbStackNotInstalled
+      OrbStackNotRunning = ::VagrantPlugins::OrbStack::OrbStackNotRunning
+      CommandExecutionError = ::VagrantPlugins::OrbStack::CommandExecutionError
+      CommandTimeoutError = ::VagrantPlugins::OrbStack::CommandTimeoutError
+      MachineNameCollisionError = ::VagrantPlugins::OrbStack::MachineNameCollisionError
+      SSHNotReady = ::VagrantPlugins::OrbStack::SSHNotReady
+      SSHConnectionFailed = ::VagrantPlugins::OrbStack::SSHConnectionFailed
+
+      # Alias for CLI errors
+      OrbStackCLIError = CommandExecutionError
+    end
+  end
+end

data/lib/vagrant-orbstack/plugin.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'vagrant-orbstack/version'
+
+module VagrantPlugins
+  # OrbStack provider plugin namespace
+  module OrbStack
+    # OrbStack provider plugin for Vagrant.
+    #
+    # This plugin enables OrbStack as a provider backend for Vagrant,
+    # allowing users to create and manage Linux development environments
+    # on macOS using OrbStack's high-performance virtualization.
+    #
+    # @api public
+    class Plugin < Vagrant.plugin('2')
+      name 'vagrant-orbstack'
+      description 'Enables OrbStack as a Vagrant provider for macOS development'
+
+      # Register OrbStack provider with Vagrant.
+      #
+      # @api private
+      provider(:orbstack, priority: 5) do
+        require_relative 'provider'
+        Provider
+      end
+
+      # Register configuration class for OrbStack provider.
+      #
+      # @api private
+      config(:orbstack, :provider) do
+        require_relative 'config'
+        Config
+      end
+
+      # Setup I18n locale files for error messages
+      def self.setup!
+        locale_path = Pathname.new(File.expand_path('../locales', __dir__))
+        I18n.load_path << locale_path.join('en.yml') if locale_path.exist?
+      end
+    end
+
+    # Initialize I18n on plugin load
+    Plugin.setup!
+  end
+end

data/lib/vagrant-orbstack/provider.rb

@@ -0,0 +1,387 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'vagrant-orbstack/errors'
+require 'vagrant-orbstack/util/state_cache'
+require 'vagrant-orbstack/util/orbstack_cli'
+require 'vagrant-orbstack/action'
+
+module VagrantPlugins
+  module OrbStack
+    # Vagrant provider implementation for OrbStack.
+    #
+    # This class implements the Vagrant provider interface, delegating
+    # machine lifecycle operations to OrbStack via CLI commands.
+    #
+    # @api public
+    class Provider < Vagrant.plugin('2', :provider)
+      # Initialize the provider with a machine instance.
+      #
+      # @param [Vagrant::Machine] machine The machine this provider is for
+      # @api public
+      def initialize(machine)
+        @machine = machine
+        @logger = Log4r::Logger.new('vagrant_orbstack::provider')
+      end
+
+      # Return action middleware for requested operation.
+      #
+      # Creates and returns an Action::Builder containing the appropriate
+      # middleware stack for the requested operation. Currently only :up
+      # is implemented; other actions return nil.
+      #
+      # @param [Symbol] name The action name (:up, :halt, :destroy, etc.)
+      # @return [Vagrant::Action::Builder, nil] Action middleware builder or nil
+      # @api public
+      # rubocop:disable Metrics/MethodLength
+      def action(name)
+        case name
+        when :up
+          Vagrant::Action::Builder.new.tap do |b|
+            b.use Action::Create
+          end
+        when :halt
+          Vagrant::Action::Builder.new.tap do |b|
+            b.use Action::Halt
+          end
+        when :reload
+          build_reload_action
+        when :ssh_run
+          Vagrant::Action::Builder.new.tap do |b|
+            b.use Action::SSHRun
+          end
+        when :destroy
+          Vagrant::Action::Builder.new.tap do |b|
+            b.use Action::Destroy
+          end
+          # Return nil for unsupported actions (future stories, etc.)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Provide SSH connection information for the machine.
+      #
+      # Returns SSH connection parameters for Vagrant to connect to the machine
+      # using OrbStack's SSH proxy architecture.
+      #
+      # CRITICAL: OrbStack uses SSH proxy at localhost:32222, NOT direct SSH to VM IP.
+      #
+      # Returns nil if the machine is not running.
+      #
+      # @return [Hash, nil] SSH connection parameters with keys:
+      #   - :host - Always '127.0.0.1' (OrbStack SSH proxy, NOT VM IP)
+      #   - :port - Always 32222 (OrbStack SSH proxy port, NOT 22)
+      #   - :username - Machine ID for proxy routing
+      #   - :private_key_path - OrbStack's auto-generated ED25519 key
+      #   - :forward_agent - Whether to forward SSH agent (from config)
+      # @api public
+      def ssh_info
+        # Return nil if machine is not running
+        current_state = state
+        return nil if %i[not_created stopped].include?(current_state.id)
+
+        # Return OrbStack SSH proxy configuration
+        {
+          host: '127.0.0.1',
+          port: 32_222,
+          username: @machine.id,
+          private_key_path: File.expand_path('~/.orbstack/ssh/id_ed25519'),
+          proxy_command: orbstack_proxy_command,
+          forward_agent: @machine.provider_config.forward_agent
+        }
+      end
+
+      # Return current machine state.
+      #
+      # Queries OrbStack CLI to determine the current state of the machine.
+      # Results are cached with a 5-second TTL to reduce redundant CLI calls.
+      # State is automatically invalidated when state-changing actions occur.
+      #
+      # @return [Vagrant::MachineState] Current state of the machine
+      # @api public
+      def state
+        # Return early if machine ID is nil
+        return not_created_state('The machine has not been created') if @machine.id.nil?
+
+        # Check cache first
+        cached_state = state_cache.get(@machine.id)
+        return cached_state if cached_state
+
+        # Cache miss: Query OrbStack CLI
+        query_and_cache_state
+      rescue StandardError => e
+        # Handle query errors gracefully
+        handle_state_query_error(e)
+      end
+
+      # Invalidate the state cache.
+      #
+      # Clears all cached state entries, forcing the next state query to
+      # fetch fresh data from OrbStack CLI. This is typically called by
+      # action middleware after state-changing operations (create, start, stop).
+      #
+      # @return [void]
+      # @api public
+      def invalidate_state_cache
+        state_cache.invalidate_all
+      end
+
+      # Human-readable provider description.
+      #
+      # @return [String] Provider name
+      # @api public
+      def to_s
+        'OrbStack'
+      end
+
+      # Callback invoked when the machine ID changes.
+      #
+      # Persists the new machine ID to the data directory for retrieval
+      # in future Vagrant sessions. This is called by Vagrant core when
+      # a machine is created or its ID is updated.
+      #
+      # The guard clause ensures we only persist when the machine has a valid ID,
+      # as some test scenarios may not have @machine.id available.
+      #
+      # @return [void]
+      # @api public
+      def machine_id_changed
+        # Guard clause: Only persist if machine has an ID
+        # Some test scenarios may not have @machine.id available
+        return unless @machine.respond_to?(:id) && !@machine.id.nil?
+
+        write_machine_id(@machine.id)
+      end
+
+      # Read the machine ID from persistent storage.
+      #
+      # Reads the machine ID from the id file in the data directory.
+      # Returns nil if the file doesn't exist or cannot be read.
+      #
+      # @return [String, nil] The machine ID if found, nil otherwise
+      # @raise [Errno::EACCES] If permission denied (logged and returns nil)
+      # @raise [Errno::ENOENT] If file not found (logged and returns nil)
+      # @raise [Encoding::InvalidByteSequenceError] If file contains invalid data (logged and returns nil)
+      # @api public
+      def read_machine_id
+        return nil unless File.exist?(id_file_path)
+
+        File.read(id_file_path).strip
+      rescue Errno::EACCES, Errno::ENOENT, Encoding::InvalidByteSequenceError => e
+        # Log error and return nil - graceful degradation for non-critical errors
+        @machine.ui&.warn("OrbStack: Could not read machine ID: #{e.message}")
+        nil
+      end
+
+      # Write the machine ID to persistent storage.
+      #
+      # Writes the machine ID to the id file in the data directory.
+      # Creates the directory if it doesn't exist.
+      #
+      # @param [String] machine_id The machine ID to persist
+      # @return [void]
+      # @raise [Errno::EACCES] If permission denied
+      # @raise [Errno::ENOSPC] If disk is full
+      # @raise [Errno::EROFS] If filesystem is read-only
+      # @api public
+      def write_machine_id(machine_id)
+        ensure_data_dir_exists
+        File.write(id_file_path, machine_id)
+      rescue Errno::EACCES, Errno::ENOSPC, Errno::EROFS => e
+        # Log error and re-raise - critical errors that cannot be ignored
+        @machine.ui&.error("OrbStack: Could not write machine ID: #{e.message}")
+        raise
+      end
+
+      # Read machine metadata from persistent storage.
+      #
+      # Reads metadata from the metadata.json file in the data directory.
+      # Returns an empty hash if the file doesn't exist or contains invalid JSON.
+      #
+      # @return [Hash] The metadata hash, or empty hash if not found
+      # @raise [JSON::ParserError] If JSON is invalid (logged and returns {})
+      # @raise [Errno::EACCES] If permission denied (logged and returns {})
+      # @raise [Errno::ENOENT] If file not found (logged and returns {})
+      # @raise [Encoding::InvalidByteSequenceError] If file contains invalid data (logged and returns {})
+      # @api public
+      def read_metadata
+        return {} unless File.exist?(metadata_file_path)
+
+        JSON.parse(File.read(metadata_file_path))
+      rescue JSON::ParserError, Errno::EACCES, Errno::ENOENT, Encoding::InvalidByteSequenceError => e
+        # Log error and return empty hash - graceful degradation for non-critical errors
+        @machine.ui&.warn("OrbStack: Could not read metadata: #{e.message}")
+        {}
+      end
+
+      # Write machine metadata to persistent storage.
+      #
+      # Writes metadata to the metadata.json file in the data directory.
+      # Creates the directory if it doesn't exist. Formats JSON for readability.
+      #
+      # @param [Hash] metadata The metadata hash to persist
+      # @return [void]
+      # @raise [JSON::ParserError] If JSON generation fails
+      # @raise [Errno::EACCES] If permission denied
+      # @raise [Errno::ENOSPC] If disk is full
+      # @raise [Errno::EROFS] If filesystem is read-only
+      # @api public
+      def write_metadata(metadata)
+        ensure_data_dir_exists
+        File.write(metadata_file_path, JSON.pretty_generate(metadata))
+      rescue JSON::ParserError, Errno::EACCES, Errno::ENOSPC, Errno::EROFS => e
+        # Log error and re-raise - critical errors that cannot be ignored
+        @machine.ui&.error("OrbStack: Could not write metadata: #{e.message}")
+        raise
+      end
+
+      # Path to the machine ID file.
+      #
+      # @return [Pathname] Path to the ID file
+      # @api public
+      def id_file_path
+        @machine.data_dir.join('id')
+      end
+
+      # Path to the metadata JSON file.
+      #
+      # @return [Pathname] Path to the metadata file
+      # @api public
+      def metadata_file_path
+        @machine.data_dir.join('metadata.json')
+      end
+
+      private
+
+      # Get the state cache instance.
+      #
+      # Lazy-initializes a StateCache instance with 5-second TTL.
+      # The cache is shared across all state queries for this provider instance.
+      #
+      # @return [Util::StateCache] The state cache instance
+      # @api private
+      def state_cache
+        @state_cache ||= Util::StateCache.new(ttl: 5)
+      end
+
+      # Generate OrbStack SSH ProxyCommand.
+      #
+      # OrbStack routes all SSH connections through the OrbStack Helper app
+      # using a ProxyCommand. This returns the correctly formatted command
+      # that Vagrant's SSH layer will use.
+      #
+      # @return [String] ProxyCommand string for SSH config
+      # @api private
+      def orbstack_proxy_command
+        helper_path = '/Applications/OrbStack.app/Contents/Frameworks/' \
+                      'OrbStack Helper.app/Contents/MacOS/OrbStack Helper'
+        "'#{helper_path}' ssh-proxy-fdpass #{Process.uid}"
+      end
+
+      # Map OrbStack machine info to Vagrant state tuple.
+      #
+      # Converts OrbStack machine status to Vagrant state representation.
+      # Returns a tuple of [state_id, short_description, long_description].
+      #
+      # @param machine_info [Hash, nil] Machine info from OrbStack CLI with :name and :status,
+      #   or nil if machine was not found
+      # @return [Array<Symbol, String, String>] Tuple of [state_id, short_desc, long_desc]
+      # @api private
+      def map_orbstack_state_to_vagrant(machine_info)
+        if machine_info.nil?
+          [:not_created, 'not created', 'Machine does not exist in OrbStack']
+        elsif machine_info[:status] == 'running'
+          [:running, 'running', 'Machine is running in OrbStack']
+        elsif machine_info[:status] == 'stopped'
+          [:stopped, 'stopped', 'Machine is stopped']
+        else
+          # Unknown state - treat as not created
+          [:not_created, 'unknown', 'Machine state is unknown']
+        end
+      end
+
+      # Create a :not_created MachineState with appropriate description.
+      #
+      # @param reason [String] The reason the machine is not created
+      # @return [Vagrant::MachineState] A not_created state object
+      # @api private
+      def not_created_state(reason)
+        Vagrant::MachineState.new(:not_created, 'not created', reason)
+      end
+
+      # Query OrbStack CLI for current machine state and cache result.
+      #
+      # @return [Vagrant::MachineState] The queried machine state
+      # @api private
+      def query_and_cache_state
+        machines = Util::OrbStackCLI.list_machines
+        our_machine = machines.find { |m| m[:name] == @machine.id }
+
+        # Map OrbStack state to Vagrant state
+        state_id, short_desc, long_desc = map_orbstack_state_to_vagrant(our_machine)
+
+        # Create MachineState and cache it
+        machine_state = Vagrant::MachineState.new(state_id, short_desc, long_desc)
+        state_cache.set(@machine.id, machine_state)
+
+        machine_state
+      end
+
+      # Handle error during state query and return not_created state.
+      #
+      # @param error [Exception] The error that occurred
+      # @return [Vagrant::MachineState] A not_created state object
+      # @api private
+      def handle_state_query_error(error)
+        if error.is_a?(CommandTimeoutError)
+          @machine.ui.warn('OrbStack: Command timeout querying machine state')
+          @logger.warn("State query timed out: #{error.message}")
+          not_created_state('Timeout querying machine state')
+        else
+          @machine.ui.warn("OrbStack: Error querying machine state: #{error.message}")
+          @logger.error("Failed to query machine state: #{error.message}")
+          not_created_state('Error querying machine state')
+        end
+      end
+
+      # Ensure the data directory exists.
+      #
+      # Creates the data directory if it doesn't exist.
+      #
+      # @return [void]
+      # @api private
+      def ensure_data_dir_exists
+        dir = @machine.data_dir
+        FileUtils.mkdir_p(dir)
+      end
+
+      # Build reload action: Halt → Start → (optional) Provision
+      #
+      # @param env [Hash] Environment hash (unused, for consistency)
+      # @return [Vagrant::Action::Builder] Configured action builder
+      # @api private
+      def build_reload_action(_env = nil)
+        Vagrant::Action::Builder.new.tap do |b|
+          b.use Action::Halt
+          b.use Action::Start
+          include_provisioning(b)
+        end
+      end
+
+      # Include provisioning middleware if available.
+      #
+      # Conditionally includes Vagrant's built-in Provision middleware.
+      # Defensive check ensures compatibility if middleware isn't available.
+      #
+      # @param builder [Vagrant::Action::Builder] Builder to modify
+      # @return [void]
+      # @api private
+      def include_provisioning(builder)
+        return unless defined?(Vagrant::Action::Builtin::Provision)
+
+        builder.use Vagrant::Action::Builtin::Provision
+      end
+    end
+  end
+end