vagrant-orbstack-provider 0.1.1

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.1'
+  end
+end

data/lib/vagrant-orbstack-provider.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Vagrant's plugin loader requires a file matching the packaged gem name
+# ("vagrant-orbstack-provider"). The actual implementation lives under
+# vagrant-orbstack/ to keep the require path stable across gem renames.
+require 'vagrant-orbstack'

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

data/locales/en.yml

@@ -0,0 +1,49 @@
+en:
+  vagrant_orbstack:
+    errors:
+      orbstack_not_installed: |-
+        OrbStack CLI not found. The 'orb' command is not available in your PATH.
+
+        To fix this issue:
+        1. Install OrbStack from https://orbstack.dev/
+        2. Ensure the 'orb' command is in your PATH
+        3. Restart your terminal and try again
+
+      orbstack_not_running: |-
+        OrbStack is not running. Please start OrbStack before using this provider.
+
+        To fix this issue:
+        1. Open the OrbStack application
+        2. Wait for it to fully start
+        3. Try your Vagrant command again
+
+      command_execution_error: |-
+        Failed to execute OrbStack CLI command: %{command}
+
+        Error details: %{details}
+
+        Please check that OrbStack is properly installed and running.
+
+      ssh_not_ready: |-
+        SSH is not ready on machine '%{machine_name}'.
+
+        The machine exists but SSH service is not yet available. This typically
+        happens when the machine is still booting or the SSH daemon is starting.
+
+        Please wait a few moments and try again. If the problem persists, check
+        that the machine is fully started and SSH is enabled.
+
+      ssh_connection_failed: |-
+        Failed to establish SSH connection to machine '%{machine_name}'.
+
+        Reason: %{reason}
+
+        This error occurs when SSH connection attempts fail after the machine
+        appears ready. Common causes include:
+
+        - Network connectivity issues
+        - SSH authentication problems
+        - Firewall blocking connections
+        - SSH service crashed after initial startup
+
+        Check the machine's SSH configuration and network settings.

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: vagrant-orbstack-provider
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Spiral House
+- hungthai1401
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Enables OrbStack as a Vagrant provider for managing Linux development
+  environments on macOS
+email:
+- opensource@spiralhouse.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/vagrant-orbstack-provider.rb
+- lib/vagrant-orbstack.rb
+- lib/vagrant-orbstack/action.rb
+- lib/vagrant-orbstack/action/create.rb
+- lib/vagrant-orbstack/action/destroy.rb
+- lib/vagrant-orbstack/action/halt.rb
+- lib/vagrant-orbstack/action/machine_validation.rb
+- lib/vagrant-orbstack/action/reload.rb
+- lib/vagrant-orbstack/action/ssh_run.rb
+- lib/vagrant-orbstack/action/start.rb
+- lib/vagrant-orbstack/config.rb
+- lib/vagrant-orbstack/errors.rb
+- lib/vagrant-orbstack/plugin.rb
+- lib/vagrant-orbstack/provider.rb
+- lib/vagrant-orbstack/util/machine_namer.rb
+- lib/vagrant-orbstack/util/orbstack_cli.rb
+- lib/vagrant-orbstack/util/ssh_readiness_checker.rb
+- lib/vagrant-orbstack/util/state_cache.rb
+- lib/vagrant-orbstack/version.rb
+- locales/en.yml
+homepage: https://github.com/hungthai1401/vagrant-orbstack-provider
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hungthai1401/vagrant-orbstack-provider
+  source_code_uri: https://github.com/hungthai1401/vagrant-orbstack-provider
+  bug_tracker_uri: https://github.com/hungthai1401/vagrant-orbstack-provider/issues
+  changelog_uri: https://github.com/hungthai1401/vagrant-orbstack-provider/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/hungthai1401/vagrant-orbstack-provider
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Vagrant provider for OrbStack
+test_files: []