vagrant-orbstack 0.1.0

data/lib/vagrant-orbstack/util/machine_namer.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'orbstack_cli'
+require_relative '../errors'
+
+module VagrantPlugins
+  module OrbStack
+    module Util
+      # Utility class for generating unique machine names with collision avoidance
+      #
+      # Generates machine names in the format: vagrant-<sanitized-name>-<short-id>
+      # where short-id is a 6-character random hex string. Implements collision
+      # detection and automatic retry with new IDs.
+      #
+      # @example Generate a unique machine name
+      #   machine = double('machine', name: 'web_server')
+      #   name = MachineNamer.generate(machine)
+      #   # => "vagrant-web-server-a3b2c1"
+      #
+      # @example Collision handling
+      #   # If "vagrant-default-a3b2c1" exists, generates new ID automatically
+      #   name = MachineNamer.generate(machine)
+      #   # => "vagrant-default-d4e5f6" (different ID)
+      #
+      # @api public
+      class MachineNamer
+        # Maximum number of retry attempts for collision avoidance
+        MAX_RETRIES = 3
+
+        # Maximum machine name length (DNS hostname limit)
+        MAX_NAME_LENGTH = 63
+
+        # Generate a unique machine name with collision avoidance.
+        #
+        # Creates a machine name in the format vagrant-<name>-<id> where:
+        # - name is sanitized from machine.name (lowercase, hyphens, alphanumeric)
+        # - id is a 6-character random hex string
+        #
+        # If a collision is detected (name already exists in OrbStack), retries
+        # with a new random ID up to MAX_RETRIES times.
+        #
+        # @param machine [Vagrant::Machine] The machine object with name attribute
+        # @return [String] A unique machine name
+        # @raise [MachineNameCollisionError] If all retry attempts are exhausted
+        # @raise [OrbStackNotInstalled] If OrbStack CLI is not available
+        # @raise [CommandTimeoutError] If OrbStack CLI times out
+        # @api public
+        def self.generate(machine)
+          machine_name = machine.name.to_s
+          sanitized = sanitize_name(machine_name)
+
+          MAX_RETRIES.times do
+            short_id = SecureRandom.hex(3)
+            candidate = "vagrant-#{sanitized}-#{short_id}"
+
+            return candidate unless check_collision?(candidate)
+          end
+
+          # All retries exhausted - raise error
+          raise MachineNameCollisionError,
+                "Failed to generate unique machine name after #{MAX_RETRIES} attempts (machine: #{machine_name})"
+        end
+
+        # Sanitize a machine name for use in hostname.
+        #
+        # Applies the following transformations:
+        # - Convert to lowercase
+        # - Replace underscores with hyphens
+        # - Remove all characters except alphanumeric and hyphens
+        # - Strip leading/trailing whitespace
+        # - Collapse consecutive hyphens to single hyphen
+        # - Truncate to fit within MAX_NAME_LENGTH minus prefix/suffix space
+        # - Default to "default" if result is empty
+        #
+        # @param name [String, nil] The name to sanitize
+        # @return [String] The sanitized name
+        # @api private
+        class << self
+          private
+
+          # Method length acceptable: Each transformation step is clear and well-documented.
+          # Combining steps would reduce readability.
+          # rubocop:disable Metrics/MethodLength
+          def sanitize_name(name)
+            # Handle nil or empty input → default
+            return 'default' if name.nil? || name.strip.empty?
+
+            # Apply sanitization rules:
+            # 1. Strip whitespace
+            # 2. Convert to lowercase
+            # 3. Replace underscores with hyphens (DNS-safe)
+            # 4. Remove non-alphanumeric (except hyphens)
+            # 5. Collapse consecutive hyphens
+            # 6. Remove leading/trailing hyphens
+            sanitized = name.to_s
+                            .strip           # Rule 1
+                            .downcase        # Rule 2
+                            .gsub('_', '-')  # Rule 3
+                            .gsub(/[^a-z0-9-]/, '')  # Rule 4
+                            .gsub(/-+/, '-')         # Rule 5
+                            .gsub(/^-|-$/, '')       # Rule 6
+
+            return 'default' if sanitized.empty?
+
+            # DNS limit (63) - "vagrant-" (8) - "-XXXXXX" (7) = 48 max
+            max_length = MAX_NAME_LENGTH - 15
+            sanitized[0...max_length]
+          end
+          # rubocop:enable Metrics/MethodLength
+
+          # Check if a machine name already exists in OrbStack.
+          #
+          # Queries OrbStack CLI for list of existing machines and checks
+          # if the candidate name is already in use.
+          #
+          # @param name [String] The candidate name to check
+          # @return [Boolean] true if collision detected, false otherwise
+          # @raise [OrbStackNotInstalled] If OrbStack CLI is not available
+          # @raise [CommandTimeoutError] If OrbStack CLI times out
+          # @api private
+          def check_collision?(name)
+            machines = OrbStackCLI.list_machines
+            machines.any? { |m| m[:name] == name }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/util/orbstack_cli.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'timeout'
+require 'json'
+require 'vagrant-orbstack/errors'
+
+module VagrantPlugins
+  module OrbStack
+    module Util
+      # Utility class for detecting and interacting with OrbStack CLI
+      #
+      # This class provides a Ruby interface to the OrbStack command-line tool (`orb`).
+      # All methods execute shell commands and return parsed results. The class handles
+      # timeouts, error detection, and logging automatically.
+      #
+      # @example Check if OrbStack is available
+      #   if OrbStackCLI.available?
+      #     puts "OrbStack version: #{OrbStackCLI.version}"
+      #   end
+      #
+      # @example Create and manage a machine
+      #   OrbStackCLI.create_machine('ubuntu', 'my-dev-vm')
+      #   OrbStackCLI.start_machine('my-dev-vm')
+      #   info = OrbStackCLI.machine_info('my-dev-vm')
+      #   OrbStackCLI.stop_machine('my-dev-vm')
+      #
+      # @example List all machines
+      #   machines = OrbStackCLI.list_machines
+      #   machines.each do |m|
+      #     puts "#{m[:name]} - #{m[:status]}"
+      #   end
+      class OrbStackCLI
+        # Default timeout for non-mutating query operations (list, info).
+        # Use this for fast read operations.
+        # @return [Integer] Timeout in seconds
+        QUERY_TIMEOUT = 30
+
+        # Default timeout for state-changing operations (start, stop, delete).
+        # Use this for operations that modify machine state.
+        # @return [Integer] Timeout in seconds
+        MUTATE_TIMEOUT = 60
+
+        # Default timeout for machine creation operations.
+        # Longer timeout accounts for distribution image downloads which
+        # can take 30-120 seconds on first use.
+        # @return [Integer] Timeout in seconds
+        CREATE_TIMEOUT = 120
+
+        @logger = Log4r::Logger.new('vagrant_orbstack::util')
+
+        class << self
+          # Check if orb command is available in PATH
+          # @return [Boolean] true if orb command exists, false otherwise
+          def available?
+            stdout, _stderr, success = execute_command('which orb')
+            !stdout.empty? && success
+          end
+
+          # Get OrbStack version
+          # @return [String, nil] version string or nil if not available
+          def version
+            stdout, _stderr, success = execute_command('orb --version')
+            return nil unless success
+
+            # Parse version from output like "orb version 1.2.3" or just "1.2.3"
+            match = stdout.match(/(\d+\.\d+\.\d+)/)
+            match ? match[1] : nil
+          end
+
+          # Check if OrbStack is currently running
+          # @return [Boolean] true if running, false otherwise
+          def running?
+            stdout, _stderr, success = execute_command('orb status')
+            success && stdout.match?(/running/i)
+          end
+
+          # List all OrbStack machines
+          #
+          # Executes `orb list` and parses the output into an array of machine hashes.
+          # Each hash contains the machine name and current status.
+          #
+          # @return [Array<Hash>] Array of machine hashes, each with:
+          #   - :name [String] The machine name
+          #   - :status [String] The machine status (e.g., 'running', 'stopped')
+          # @return [Array] Empty array on failure or if no machines exist
+          # @raise [CommandTimeoutError] If command times out
+          #
+          # @example List all machines
+          #   machines = OrbStackCLI.list_machines
+          #   # => [{name: 'ubuntu-dev', status: 'running'}, {name: 'debian-test', status: 'stopped'}]
+          # rubocop:disable Metrics/MethodLength
+          def list_machines
+            stdout, _stderr, success = execute_command('orb list', timeout: QUERY_TIMEOUT)
+            return [] unless success
+            return [] if stdout.empty?
+
+            # Parse machine list output (format: NAME STATUS DISTRO IP)
+            machines = []
+            stdout.each_line do |line|
+              parts = line.strip.split(/\s+/)
+              next if parts.empty?
+
+              machines << {
+                name: parts[0],
+                status: parts[1]
+              }
+            end
+
+            machines
+          end
+          # rubocop:enable Metrics/MethodLength
+
+          # Get detailed information about a specific machine
+          #
+          # Executes `orb info <name>` and parses the JSON output. Returns nil if
+          # the machine doesn't exist or if JSON parsing fails.
+          #
+          # @param name [String] The machine name
+          # @return [Hash, nil] Parsed machine information hash with OrbStack-specific
+          #   fields, or nil if machine not found or parsing fails
+          # @raise [CommandTimeoutError] If command times out
+          #
+          # @example Get machine info
+          #   info = OrbStackCLI.machine_info('my-dev-vm')
+          #   puts info['distro'] if info
+          def machine_info(name)
+            stdout, _stderr, success = execute_command("orb info --format json #{name}", timeout: QUERY_TIMEOUT)
+            return nil unless success
+
+            JSON.parse(stdout)
+          rescue JSON::ParserError => e
+            @logger.warn("Failed to parse machine info JSON: #{e.message}")
+            nil
+          end
+
+          # Create a new OrbStack machine
+          #
+          # Executes `orb create <distro> <name>`. This operation can take 30-120 seconds
+          # on first use if the distribution image needs to be downloaded. Subsequent
+          # creations of the same distribution are much faster.
+          #
+          # @param name [String] The machine name
+          # @param distribution [String] The distribution to use (e.g., 'ubuntu:noble', 'debian')
+          # @param timeout [Integer] Command timeout in seconds (default: CREATE_TIMEOUT)
+          # @return [Hash] Machine info hash with :id and :status keys
+          # @raise [CommandExecutionError] If creation fails
+          # @raise [CommandTimeoutError] If command times out
+          #
+          # @example Create an Ubuntu machine
+          #   OrbStackCLI.create_machine('my-dev-vm', distribution: 'ubuntu:noble')
+          #
+          # @example Create with custom timeout for slow networks
+          #   OrbStackCLI.create_machine('my-vm', distribution: 'ubuntu', timeout: 180)
+          # rubocop:disable Naming/PredicateMethod
+          def create_machine(name, distribution:, timeout: CREATE_TIMEOUT)
+            _, stderr, success = execute_command("orb create #{distribution} #{name}", timeout: timeout)
+            raise_unless_successful!('create', stderr, success)
+            { id: name, status: 'running' }
+          end
+
+          # Delete an OrbStack machine
+          #
+          # Executes `orb delete <name>`. This permanently removes the machine and
+          # all its data. The operation cannot be undone.
+          #
+          # @param name [String] The machine name
+          # @return [Boolean] true on success
+          # @raise [CommandExecutionError] If deletion fails
+          # @raise [CommandTimeoutError] If command times out
+          #
+          # @example Delete a machine
+          #   OrbStackCLI.delete_machine('my-dev-vm')
+          def delete_machine(name)
+            _, stderr, success = execute_command("orb delete #{name}", timeout: MUTATE_TIMEOUT)
+            raise_unless_successful!('delete', stderr, success)
+            true
+          end
+
+          # Start an OrbStack machine
+          #
+          # Executes `orb start <name>`. Starts a stopped machine. If the machine
+          # is already running, this is a no-op.
+          #
+          # @param name [String] The machine name
+          # @param timeout [Integer] Command timeout in seconds (default: MUTATE_TIMEOUT)
+          # @return [Hash] Machine info hash with :id and :status keys
+          # @raise [CommandExecutionError] If start fails
+          # @raise [CommandTimeoutError] If command times out
+          #
+          # @example Start a machine
+          #   OrbStackCLI.start_machine('my-dev-vm')
+          def start_machine(name, timeout: MUTATE_TIMEOUT)
+            _, stderr, success = execute_command("orb start #{name}", timeout: timeout)
+            raise_unless_successful!('start', stderr, success)
+            { id: name, status: 'running' }
+          end
+
+          # Stop an OrbStack machine
+          #
+          # Executes `orb stop <name>`. Stops a running machine gracefully. If the
+          # machine is already stopped, this is a no-op.
+          #
+          # @param name [String] The machine name
+          # @return [Boolean] true on success
+          # @raise [CommandExecutionError] If stop fails
+          # @raise [CommandTimeoutError] If command times out
+          #
+          # @example Stop a machine
+          #   OrbStackCLI.stop_machine('my-dev-vm')
+          def stop_machine(name)
+            _, stderr, success = execute_command("orb stop #{name}", timeout: MUTATE_TIMEOUT)
+            raise_unless_successful!('stop', stderr, success)
+            true
+          end
+          # rubocop:enable Naming/PredicateMethod
+
+          private
+
+          # Raises CommandExecutionError unless the operation succeeded
+          #
+          # Helper method to enforce error handling for mutating operations.
+          # Only raises if the operation failed.
+          #
+          # @param action [String] The action being performed (e.g., 'create', 'delete')
+          # @param stderr [String] Error output from CLI
+          # @param success [Boolean] Whether the operation succeeded
+          # @return [void]
+          # @raise [CommandExecutionError] If success is false
+          def raise_unless_successful!(action, stderr, success)
+            return if success
+
+            raise CommandExecutionError, command: "orb #{action}", details: stderr
+          end
+
+          # Execute an OrbStack CLI command.
+          #
+          # Executes a shell command using Open3.capture3 and captures stdout,
+          # stderr, and exit status. Supports optional timeout for long-running
+          # operations. Logs command execution at DEBUG level on success and
+          # ERROR level on failure.
+          #
+          # On any StandardError (other than timeout), returns empty strings and
+          # false success flag rather than propagating the exception.
+          #
+          # @param command [String] The command to execute
+          # @param timeout [Integer] Timeout in seconds (default: QUERY_TIMEOUT)
+          # @return [Array<String, String, Boolean>] Tuple of [stdout, stderr, success].
+          #   All string values are stripped of leading/trailing whitespace.
+          # @raise [CommandTimeoutError] If command exceeds timeout
+          # @api private
+          # rubocop:disable Metrics/MethodLength
+          def execute_command(command, timeout: QUERY_TIMEOUT)
+            stdout, stderr, status = if timeout
+                                       Timeout.timeout(timeout) do
+                                         Open3.capture3(command)
+                                       end
+                                     else
+                                       Open3.capture3(command)
+                                     end
+
+            success = status.success?
+
+            if success
+              @logger.debug("Command succeeded: #{command}")
+            else
+              @logger.error("Command failed: #{command}, stderr: #{stderr}")
+            end
+
+            [stdout.strip, stderr.strip, success]
+          rescue Timeout::Error
+            @logger.error("Command timed out after #{timeout}s: #{command}")
+            raise CommandTimeoutError, "Command timed out: #{command}"
+          rescue StandardError => e
+            @logger.error("Command error: #{e.message}")
+            ['', '', false]
+          end
+          # rubocop:enable Metrics/MethodLength
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/util/ssh_readiness_checker.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative 'orbstack_cli'
+require_relative '../errors'
+
+module VagrantPlugins
+  module OrbStack
+    module Util
+      # Utility module for waiting until SSH becomes available on an OrbStack machine
+      #
+      # This module provides a polling mechanism to check if an OrbStack machine
+      # is ready for SSH connections. It repeatedly queries the machine status
+      # until the machine reports as 'running', indicating SSH is available.
+      #
+      # @example Wait for SSH on a newly created machine
+      #   SSHReadinessChecker.wait_for_ready('my-machine', ui: ui)
+      #
+      # @example Handle timeout gracefully
+      #   begin
+      #     SSHReadinessChecker.wait_for_ready('my-machine', ui: ui)
+      #   rescue VagrantPlugins::OrbStack::SSHNotReady => e
+      #     ui.error("SSH not ready: #{e.message}")
+      #   end
+      #
+      # @api public
+      module SSHReadinessChecker
+        # Maximum time to wait for SSH to become ready (in seconds)
+        # @return [Integer] Timeout in seconds
+        MAX_WAIT_TIME = 120
+
+        # Interval between status polls (in seconds)
+        # @return [Integer] Poll interval in seconds
+        POLL_INTERVAL = 2
+
+        # Wait for SSH to become available on a machine.
+        #
+        # Polls the machine status every POLL_INTERVAL seconds until the machine
+        # reports 'running' status, or until MAX_WAIT_TIME is exceeded. Displays
+        # progress messages via the provided UI object.
+        #
+        # @param machine_name [String] The name of the machine to check
+        # @param ui [Vagrant::UI::Interface] UI object for displaying progress messages
+        # @return [Boolean] true when SSH is ready
+        # @raise [SSHNotReady] If machine doesn't become ready within MAX_WAIT_TIME
+        # @raise [CommandExecutionError] If OrbStack CLI command fails
+        # @raise [CommandTimeoutError] If OrbStack CLI command times out
+        # @raise [OrbStackNotInstalled] If OrbStack CLI is not available
+        #
+        # @example Wait for SSH
+        #   SSHReadinessChecker.wait_for_ready('ubuntu-dev', ui: machine.ui)
+        #   # => true
+        #
+        # @api public
+        # rubocop:disable Naming/MethodParameterName
+        def self.wait_for_ready(machine_name, ui:)
+          # rubocop:enable Naming/MethodParameterName
+          ui.info("Waiting for SSH to become available on #{machine_name}...")
+
+          poll_until_ready(machine_name, ui) ||
+            raise_timeout_error(machine_name)
+        end
+
+        # Poll machine status until ready or timeout.
+        #
+        # @param machine_name [String] The name of the machine to check
+        # @param ui [Vagrant::UI::Interface] UI object for progress messages
+        # @return [Boolean, nil] true if ready, nil if timeout
+        # @api private
+        # rubocop:disable Naming/MethodParameterName, Metrics/MethodLength
+        def self.poll_until_ready(machine_name, ui)
+          # rubocop:enable Naming/MethodParameterName, Metrics/MethodLength
+          start_time = Time.now
+          elapsed = 0
+
+          while elapsed < MAX_WAIT_TIME
+            if machine_running?(machine_name)
+              ui.info('SSH is ready!')
+              return true
+            end
+
+            sleep(POLL_INTERVAL)
+            elapsed = Time.now - start_time
+            ui.info("  Still waiting... (#{elapsed.to_i} seconds elapsed)")
+          end
+
+          nil
+        end
+
+        # Raise timeout error with machine_name parameter for I18n.
+        #
+        # @param machine_name [String] The name of the machine
+        # @raise [SSHNotReady] Always raises with machine_name parameter
+        # @api private
+        def self.raise_timeout_error(machine_name)
+          raise SSHNotReady, machine_name: machine_name
+        end
+
+        # Check if machine is in running state.
+        #
+        # Queries OrbStack CLI for machine status and checks if it's 'running'.
+        # Handles nil responses and missing 'status' keys gracefully.
+        #
+        # @param machine_name [String] The name of the machine to check
+        # @return [Boolean] true if machine status is 'running', false otherwise
+        # @api private
+        def self.machine_running?(machine_name)
+          info = OrbStackCLI.machine_info(machine_name)
+          info && info.dig('record', 'state') == 'running'
+        end
+
+        private_class_method :poll_until_ready, :raise_timeout_error, :machine_running?
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/util/state_cache.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module OrbStack
+    module Util
+      # TTL-based cache utility for machine state queries.
+      #
+      # This class provides a simple time-to-live (TTL) cache to reduce redundant
+      # CLI calls when querying machine state. State queries are cached with a
+      # configurable TTL (default 5 seconds), and automatically expire when the
+      # TTL is exceeded.
+      #
+      # The cache is designed for Vagrant's single-threaded environment and does
+      # not implement thread-safety mechanisms.
+      #
+      # @example Basic usage with default TTL
+      #   cache = StateCache.new
+      #   cache.set('machine-id', state)
+      #   cached_state = cache.get('machine-id')  # Returns state
+      #
+      # @example Custom TTL
+      #   cache = StateCache.new(ttl: 10)  # 10-second cache
+      #   cache.set('key', 'value')
+      #   # 11 seconds later...
+      #   cache.get('key')  # Returns nil (expired)
+      #
+      # @example Cache invalidation
+      #   cache.invalidate('key')       # Remove specific key
+      #   cache.invalidate_all          # Clear entire cache
+      class StateCache
+        # Default TTL for cached entries (in seconds)
+        DEFAULT_TTL = 5
+
+        # Initialize a new state cache.
+        #
+        # @param ttl [Integer] Time-to-live for cached entries in seconds (default: 5)
+        # @api public
+        def initialize(ttl: DEFAULT_TTL)
+          @ttl = ttl
+          @cache = {}
+        end
+
+        # Retrieve a cached value.
+        #
+        # Returns the cached value if it exists and has not expired. Returns nil
+        # if the key doesn't exist or if the cached entry has exceeded its TTL.
+        #
+        # @param key [String] The cache key
+        # @return [Object, nil] The cached value if valid, nil if missing or expired
+        # @api public
+        def get(key)
+          entry = @cache[key]
+          return nil unless entry
+
+          # Check if entry has expired
+          if Time.now - entry[:timestamp] > @ttl
+            # Entry expired, remove it and return nil
+            @cache.delete(key)
+            return nil
+          end
+
+          entry[:value]
+        end
+
+        # Store a value in the cache.
+        #
+        # Stores the value with the current timestamp. If the key already exists,
+        # its value and timestamp are overwritten.
+        #
+        # @param key [String] The cache key
+        # @param value [Object] The value to cache (can be any object, including nil)
+        # @return [void]
+        # @api public
+        def set(key, value)
+          @cache[key] = {
+            value: value,
+            timestamp: Time.now
+          }
+        end
+
+        # Invalidate a specific cache entry.
+        #
+        # Removes the specified key from the cache. This is a no-op if the key
+        # doesn't exist.
+        #
+        # @param key [String] The cache key to remove
+        # @return [void]
+        # @api public
+        def invalidate(key)
+          @cache.delete(key)
+        end
+
+        # Clear all cache entries.
+        #
+        # Removes all cached entries. This is useful when you need to ensure
+        # fresh data is retrieved on the next query.
+        #
+        # @return [void]
+        # @api public
+        def invalidate_all
+          @cache.clear
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-orbstack/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module OrbStack
+    VERSION = '0.1.0'
+  end
+end

data/lib/vagrant-orbstack.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'vagrant-orbstack/plugin'
+
+module VagrantPlugins
+  # OrbStack provider for Vagrant.
+  #
+  # This module contains the implementation of the OrbStack provider plugin,
+  # enabling Vagrant to use OrbStack as a backend for managing Linux
+  # development environments on macOS.
+  #
+  # @see Plugin
+  # @see Provider
+  # @see Config
+  module OrbStack
+    lib_path = Pathname.new(File.join(__dir__, 'vagrant-orbstack'))
+    autoload :Action, lib_path.join('action')
+    autoload :Errors, lib_path.join('errors')
+
+    # Sentinel value to distinguish "not set" from nil.
+    # Used in configuration to differentiate between explicitly set to nil
+    # versus never configured (should use default).
+    #
+    # @api private
+    UNSET_VALUE = ::Object.new.freeze
+
+    # Returns the path to the source of this plugin.
+    #
+    # @return [Pathname] Root directory of the plugin source
+    # @api private
+    def self.source_root
+      @source_root ||= Pathname.new(File.join(__dir__, '..'))
+    end
+  end
+end