consolle 0.3.7 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a88f6019a32aaae300dee3a3e39b1dd1084ea1e2900171d6ee02f880923e071e
-  data.tar.gz: e9c468bc8095d8197e8f70cc4c0b75d0cc8da9ba3a7b0af45573300b755e1970
+  metadata.gz: '0975195db50059158fa8643203c06099ea77c53a6ee199705731244806d7b2d8'
+  data.tar.gz: 8d1fc462e0dc7acd21b9f53989f892ffdf03920b1bc327c82fc70516fda8e201
 SHA512:
-  metadata.gz: e5c0615769edda8936547380360ed5a7beeaaeda7569ccf91322daa4658923a82cad4ad87e5ffabeca4c230e89f3d371ebcaa5eec58663b25172ee0ab8c2ba07
-  data.tar.gz: 83dd02825015e9f9e73ff48075436f459722cdc045ee4b0b8d90509c5ca91274c27af682549ef114598efcf21d90628fc460360f33a069134b0da63eeab94c81
+  metadata.gz: a281509268f01cdbb60e1a538e9c037c82cce14f26aebd1faf30befeee6aeba6996eaa94f37fa70f13949f0a1d5d749db7604fae39253154d61ec14e6db637ff
+  data.tar.gz: 58c2126e05ca127992001c57a597a095b3c4aa193c36b934de5490d3eddb95bc85770c7bd7e1905c3fdd2b4e95bc68d77f9518d35a22cd8f3619f71c4de15638

data/.version

@@ -1 +1 @@
-0.3.7
+0.3.8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    consolle (0.3.7)
+    consolle (0.3.8)
       logger (~> 1.0)
       thor (~> 1.0)
 

data/lib/consolle/adapters/rails_console.rb

@@ -13,7 +13,7 @@ module Consolle
       attr_reader :socket_path, :process_pid, :pid_path, :log_path
 
       def initialize(socket_path: nil, pid_path: nil, log_path: nil, rails_root: nil, rails_env: nil, verbose: false,
-                     command: nil, wait_timeout: nil)
+                     command: nil, wait_timeout: nil, mode: nil)
         @socket_path = socket_path || default_socket_path
         @pid_path = pid_path || default_pid_path
         @log_path = log_path || default_log_path
@@ -22,6 +22,7 @@ module Consolle
         @verbose = verbose
         @command = command || 'bin/rails console'
         @wait_timeout = wait_timeout || Consolle::DEFAULT_WAIT_TIMEOUT
+        @mode = mode  # nil means use config file setting
         @server_pid = nil
       end
 
@@ -149,7 +150,8 @@ module Consolle
           @pid_path,
           @log_path,
           @command,
-          @wait_timeout.to_s
+          @wait_timeout.to_s,
+          @mode.to_s  # empty string if nil (use config file)
         ]
       end
 
@@ -159,8 +161,9 @@ module Consolle
             require 'consolle/server/console_socket_server'
             require 'logger'
           #{'  '}
-            socket_path, rails_root, rails_env, log_level, pid_path, log_path, command, wait_timeout_str = ARGV
+            socket_path, rails_root, rails_env, log_level, pid_path, log_path, command, wait_timeout_str, mode_str = ARGV
             wait_timeout = wait_timeout_str ? wait_timeout_str.to_i : nil
+            mode = mode_str && !mode_str.empty? ? mode_str.to_sym : nil  # nil = use config file
           #{'  '}
             # Write initial log
             log_file = log_path || socket_path.sub(/\\.socket$/, '.log')
@@ -191,10 +194,11 @@ module Consolle
               rails_env: rails_env,
               logger: logger,
               command: command,
-              wait_timeout: wait_timeout
+              wait_timeout: wait_timeout,
+              mode: mode
             )
           #{'  '}
-            puts "[Server] Starting server with log level: \#{log_level}..."
+            puts "[Server] Starting server with log level: \#{log_level}, mode: \#{mode || 'config'}..."
             server.start
           #{'  '}
             puts "[Server] Server started, entering sleep..."
@@ -204,17 +208,17 @@ module Consolle
           rescue => e
             puts "[Server] Error: \#{e.class}: \#{e.message}"
             puts e.backtrace.join("\\n")
-            
+
             # Clean up socket file if it exists
             if defined?(socket_path) && socket_path && File.exist?(socket_path)
               File.unlink(socket_path) rescue nil
             end
-            
+
             # Clean up PID file if it exists
             if defined?(pid_file) && pid_file && File.exist?(pid_file)
               File.unlink(pid_file) rescue nil
             end
-            
+
             exit 1
           end
         RUBY

data/lib/consolle/cli.rb

@@ -124,15 +124,25 @@ module Consolle
         RAILS_ENV=production cone start --target api
         RAILS_ENV=development cone start --target worker
 
-      Custom console commands are supported for special environments:
+      Supervisor modes (--mode):
+        pty         - Traditional PTY-based mode, supports custom commands (default)
+        embed-irb   - Pure IRB embedding, Ruby 3.3+ only
+        embed-rails - Rails console embedding, Ruby 3.3+ only
+
+      Custom console commands are supported for PTY mode:
         cone start --command "kamal app exec -i 'bin/rails console'"
         cone start --command "docker exec -it myapp bin/rails console"
-      
+
       For SSH-based commands that require authentication (e.g., 1Password SSH agent):
         cone start --command "kamal console" --wait-timeout 60
+
+      Use embedded modes for faster local execution (200x faster):
+        cone start --mode embed-rails
+        cone start --mode embed-irb
     LONGDESC
     # Rails environment is now controlled via RAILS_ENV, not a CLI option
-    method_option :command, type: :string, aliases: '-c', desc: 'Custom console command', default: 'bin/rails console'
+    method_option :mode, type: :string, aliases: '-m', desc: 'Supervisor mode: pty, embed-irb, embed-rails'
+    method_option :command, type: :string, aliases: '-c', desc: 'Custom console command (PTY mode only)', default: 'bin/rails console'
     method_option :wait_timeout, type: :numeric, aliases: '-w', desc: 'Timeout for console startup (seconds)', default: Consolle::DEFAULT_WAIT_TIMEOUT
     def start
       ensure_rails_project!
@@ -160,7 +170,13 @@ module Consolle
         clear_session_info
       end
 
-      adapter = create_rails_adapter(current_rails_env, options[:target], options[:command], options[:wait_timeout])
+      adapter = create_rails_adapter(
+        current_rails_env,
+        options[:target],
+        options[:command],
+        options[:wait_timeout],
+        options[:mode]
+      )
 
       puts 'Starting Rails console...'
 
@@ -557,8 +573,8 @@ module Consolle
       if result['success']
         # Always print result, even if empty (multiline code often returns empty string)
         puts result['result'] unless result['result'].nil?
-        # Always show execution time when available
-        puts "Execution time: #{result['execution_time'].round(3)}s" if result['execution_time']
+        # Show execution time only in verbose mode
+        puts "Execution time: #{result['execution_time'].round(3)}s" if options[:verbose] && result['execution_time']
       else
         # Display error information
         if result['error_code']
@@ -574,10 +590,10 @@ module Consolle
         
         puts result['message']
         puts result['backtrace']&.join("\n") if options[:verbose] && result['backtrace']
-        
-        # Show execution time for errors too
-        puts "Execution time: #{result['execution_time'].round(3)}s" if result['execution_time']
-        
+
+        # Show execution time for errors too (verbose only)
+        puts "Execution time: #{result['execution_time'].round(3)}s" if options[:verbose] && result['execution_time']
+
         exit 1
       end
     end
@@ -702,7 +718,7 @@ module Consolle
       File.join(Dir.pwd, 'tmp', 'cone', 'sessions.json')
     end
 
-    def create_rails_adapter(rails_env = 'development', target = nil, command = nil, wait_timeout = nil)
+    def create_rails_adapter(rails_env = 'development', target = nil, command = nil, wait_timeout = nil, mode = nil)
       target ||= options[:target]
 
       Consolle::Adapters::RailsConsole.new(
@@ -713,7 +729,8 @@ module Consolle
         rails_env: rails_env,
         verbose: options[:verbose],
         command: command,
-        wait_timeout: wait_timeout
+        wait_timeout: wait_timeout,
+        mode: mode
       )
     end
 

data/lib/consolle/config.rb

@@ -14,13 +14,23 @@ module Consolle
     # - Generic prompts: >> or >
     DEFAULT_PROMPT_PATTERN = /^[^\w]*(\u001E\u001F<CONSOLLE>\u001F\u001E|\w+[-_]?\w*\([^)]*\)(:\d+)?>|irb\([^)]+\):\d+:?\d*[>*]|>>|>)\s*$/
 
-    attr_reader :rails_root, :prompt_pattern, :raw_prompt_pattern
+    # Valid supervisor modes
+    # - pty: PTY-based, supports custom command (local/remote)
+    # - embed-irb: Pure IRB embedding (Ruby 3.3+, local only)
+    # - embed-rails: Rails console embedding (Ruby 3.3+, local only)
+    VALID_MODES = %w[pty embed-irb embed-rails].freeze
+    DEFAULT_MODE = :pty
+    DEFAULT_COMMAND = 'bin/rails console'
+
+    attr_reader :rails_root, :prompt_pattern, :raw_prompt_pattern, :mode, :command
 
     def initialize(rails_root)
       @rails_root = rails_root
       @config = load_config
       @raw_prompt_pattern = @config['prompt_pattern']
       @prompt_pattern = parse_prompt_pattern(@raw_prompt_pattern)
+      @mode = parse_mode(@config['mode'])
+      @command = @config['command'] || DEFAULT_COMMAND
     end
 
     def self.load(rails_root)
@@ -74,5 +84,21 @@ module Consolle
         DEFAULT_PROMPT_PATTERN
       end
     end
+
+    def parse_mode(mode_string)
+      return DEFAULT_MODE if mode_string.nil?
+
+      # Normalize: convert underscores/symbols, handle legacy 'embedded' -> 'embed-rails'
+      normalized = mode_string.to_s.downcase.tr('_', '-')
+      normalized = 'embed-rails' if normalized == 'embedded'
+      normalized = 'pty' if normalized == 'auto'
+
+      unless VALID_MODES.include?(normalized)
+        warn "[Consolle] Warning: Invalid mode '#{mode_string}'. Using '#{DEFAULT_MODE}'."
+        return DEFAULT_MODE
+      end
+
+      normalized.tr('-', '_').to_sym  # :pty, :embed_irb, :embed_rails
+    end
   end
 end

data/lib/consolle/errors.rb

@@ -110,6 +110,20 @@ module Consolle
       end
     end
 
+    # Configuration error
+    class ConfigurationError < Error
+      def initialize(message)
+        super("Configuration error: #{message}")
+      end
+    end
+
+    # Unsupported Ruby version for embedded mode
+    class UnsupportedRubyVersion < Error
+      def initialize(message)
+        super(message)
+      end
+    end
+
     # Error classifier to map exceptions to error codes
     class ErrorClassifier
       ERROR_CODE_MAP = {

data/lib/consolle/server/base_supervisor.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Consolle
+  module Server
+    # Base interface for console supervisors
+    # Both PTY-based and embedded IRB modes inherit from this class
+    class BaseSupervisor
+      attr_reader :rails_root, :rails_env, :logger, :config
+
+      def initialize(rails_root:, rails_env: 'development', logger: nil)
+        @rails_root = rails_root
+        @rails_env = rails_env
+        @logger = logger || Logger.new($stdout)
+        @config = Consolle::Config.load(rails_root)
+      end
+
+      # Execute code and return result
+      # @param code [String] Ruby code to evaluate
+      # @param timeout [Integer] Timeout in seconds
+      # @return [Hash] Result hash with :success, :output, :execution_time, etc.
+      def eval(code, timeout: 60)
+        raise NotImplementedError, "#{self.class} must implement #eval"
+      end
+
+      # Check if the console is running and ready
+      # @return [Boolean]
+      def running?
+        raise NotImplementedError, "#{self.class} must implement #running?"
+      end
+
+      # Stop the console
+      def stop
+        raise NotImplementedError, "#{self.class} must implement #stop"
+      end
+
+      # Restart the console
+      def restart
+        raise NotImplementedError, "#{self.class} must implement #restart"
+      end
+
+      # Returns the mode name for logging/debugging
+      # @return [Symbol] :pty or :embedded
+      def mode
+        raise NotImplementedError, "#{self.class} must implement #mode"
+      end
+
+      protected
+
+      def build_success_response(output, execution_time:, result: nil)
+        response = {
+          success: true,
+          output: output,
+          execution_time: execution_time
+        }
+        response[:result] = result if result
+        response
+      end
+
+      def build_error_response(exception, execution_time: nil)
+        if exception.is_a?(String)
+          error_code = Consolle::Errors::ErrorClassifier.classify_message(exception)
+          return {
+            success: false,
+            error_class: 'RuntimeError',
+            error_code: error_code,
+            output: exception,
+            execution_time: execution_time
+          }
+        end
+
+        {
+          success: false,
+          error_class: exception.class.name,
+          error_code: Consolle::Errors::ErrorClassifier.to_code(exception),
+          output: "#{exception.class}: #{exception.message}",
+          execution_time: execution_time
+        }
+      end
+
+      def build_timeout_response(timeout_seconds)
+        error = Consolle::Errors::ExecutionTimeout.new(timeout_seconds)
+        {
+          success: false,
+          error_class: error.class.name,
+          error_code: Consolle::Errors::ErrorClassifier.to_code(error),
+          output: error.message,
+          execution_time: timeout_seconds
+        }
+      end
+    end
+  end
+end

data/lib/consolle/server/console_socket_server.rb

@@ -5,6 +5,8 @@ require 'json'
 require 'logger'
 require 'fileutils'
 require_relative 'console_supervisor'
+require_relative 'embedded_supervisor'
+require_relative 'supervisor_factory'
 require_relative 'request_broker'
 
 module Consolle
@@ -12,14 +14,15 @@ module Consolle
     class ConsoleSocketServer
       attr_reader :socket_path, :logger
 
-      def initialize(socket_path:, rails_root:, rails_env: 'development', logger: nil, command: nil, wait_timeout: nil)
+      def initialize(socket_path:, rails_root:, rails_env: 'development', logger: nil, command: nil, wait_timeout: nil, mode: nil)
         @socket_path = socket_path
         @rails_root = rails_root
         @rails_env = rails_env
         @command = command || 'bin/rails console'
         @wait_timeout = wait_timeout
+        @mode = mode  # nil = use config file, otherwise :pty, :embed_irb, :embed_rails
         @logger = logger || begin
-          log = Logger.new(STDOUT)
+          log = Logger.new($stdout)
           log.level = Logger::DEBUG
           log
         end
@@ -97,13 +100,20 @@ module Consolle
       end
 
       def setup_supervisor
-        @supervisor = ConsoleSupervisor.new(
+        # Load config to get default mode if not explicitly specified
+        config = Consolle::Config.load(@rails_root)
+        effective_mode = @mode || config.mode
+
+        @supervisor = SupervisorFactory.create(
           rails_root: @rails_root,
+          mode: effective_mode,
           rails_env: @rails_env,
           logger: @logger,
           command: @command,
           wait_timeout: @wait_timeout
         )
+
+        @logger.info "[ConsoleSocketServer] Using #{@supervisor.mode} mode"
       end
 
       def setup_broker

data/lib/consolle/server/console_supervisor.rb

@@ -300,6 +300,12 @@ module Consolle
         end
       end
 
+      # Returns the mode name for logging/debugging
+      # @return [Symbol] :pty
+      def mode
+        :pty
+      end
+
       # Returns the prompt pattern to use (custom from config or default)
       def prompt_pattern
         @config&.prompt_pattern || Consolle::Config::DEFAULT_PROMPT_PATTERN

data/lib/consolle/server/embedded_supervisor.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require 'stringio'
+require_relative 'base_supervisor'
+require_relative '../errors'
+
+module Consolle
+  module Server
+    # IRB embedding mode supervisor (Ruby 3.3+)
+    # Runs IRB directly in-process without PTY
+    # Supports two modes:
+    # - :embed_irb   - Pure IRB without Rails
+    # - :embed_rails - Rails console with IRB
+    class EmbeddedSupervisor < BaseSupervisor
+      MINIMUM_RUBY_VERSION = Gem::Version.new('3.3.0')
+      VALID_MODES = %i[embed_irb embed_rails].freeze
+
+      class << self
+        def supported?
+          Gem::Version.new(RUBY_VERSION) >= MINIMUM_RUBY_VERSION
+        end
+
+        def check_support!
+          return if supported?
+
+          raise Consolle::Errors::UnsupportedRubyVersion.new(
+            "Embedded mode requires Ruby #{MINIMUM_RUBY_VERSION}+, " \
+            "current version: #{RUBY_VERSION}"
+          )
+        end
+      end
+
+      # @param rails_root [String] Project root directory
+      # @param rails_env [String] Rails environment (only for embed_rails mode)
+      # @param logger [Logger] Logger instance
+      # @param embed_mode [Symbol] :embed_irb or :embed_rails
+      def initialize(rails_root:, rails_env: 'development', logger: nil, embed_mode: :embed_rails)
+        super(rails_root: rails_root, rails_env: rails_env, logger: logger)
+        @embed_mode = validate_embed_mode(embed_mode)
+        @running = false
+        @workspace = nil
+        @mutex = Mutex.new
+
+        boot_environment
+        setup_irb
+        @running = true
+
+        mode_name = @embed_mode == :embed_rails ? 'Rails console' : 'IRB'
+        logger.info "[EmbeddedSupervisor] #{mode_name} embedded mode initialized (Ruby #{RUBY_VERSION})"
+      end
+
+      def eval(code, timeout: nil, pre_sigint: nil)
+        # pre_sigint is ignored in embedded mode (no PTY)
+
+        env_timeout = ENV['CONSOLLE_TIMEOUT']&.to_i
+        timeout = if env_timeout && env_timeout.positive?
+                    env_timeout
+                  else
+                    timeout || 60
+                  end
+
+        @mutex.synchronize do
+          raise 'Console is not running' unless running?
+
+          start_time = Time.now
+          execute_code(code, timeout, start_time)
+        end
+      end
+
+      def running?
+        @running && @workspace
+      end
+
+      def stop
+        @running = false
+        @workspace = nil
+        logger.info '[EmbeddedSupervisor] Stopped'
+      end
+
+      def restart
+        logger.info '[EmbeddedSupervisor] Restarting IRB workspace...'
+        @mutex.synchronize do
+          setup_irb
+        end
+        logger.info '[EmbeddedSupervisor] IRB workspace restarted'
+      end
+
+      def mode
+        @embed_mode
+      end
+
+      # Returns the current process PID (embedded mode runs in-process)
+      # @return [Integer]
+      def pid
+        Process.pid
+      end
+
+      # Returns the prompt pattern (for compatibility with PTY mode)
+      def prompt_pattern
+        @config&.prompt_pattern || Consolle::Config::DEFAULT_PROMPT_PATTERN
+      end
+
+      private
+
+      def validate_embed_mode(mode)
+        mode_sym = mode.to_sym
+        return mode_sym if VALID_MODES.include?(mode_sym)
+
+        raise ArgumentError, "Invalid embed_mode: #{mode}. Must be one of: #{VALID_MODES.join(', ')}"
+      end
+
+      def boot_environment
+        return boot_rails if @embed_mode == :embed_rails
+
+        # For embed_irb mode, no Rails loading needed
+        logger.info '[EmbeddedSupervisor] Pure IRB mode - skipping Rails environment'
+      end
+
+      def boot_rails
+        return if defined?(Rails) && Rails.application
+
+        ENV['RAILS_ENV'] = @rails_env
+
+        environment_file = File.join(@rails_root, 'config', 'environment.rb')
+        unless File.exist?(environment_file)
+          raise Consolle::Errors::ConfigurationError.new(
+            "Rails environment file not found: #{environment_file}"
+          )
+        end
+
+        logger.info "[EmbeddedSupervisor] Loading Rails environment from #{environment_file}"
+        require environment_file
+        logger.info "[EmbeddedSupervisor] Rails #{Rails.version} loaded (#{Rails.env})"
+      end
+
+      def setup_irb
+        require 'irb'
+
+        # Initialize IRB if not already done
+        IRB.setup(nil, argv: []) unless IRB.conf[:PROMPT]
+
+        # Configure IRB for automation
+        IRB.conf[:USE_COLORIZE] = false
+        IRB.conf[:USE_AUTOCOMPLETE] = false
+        IRB.conf[:USE_PAGER] = false
+        IRB.conf[:VERBOSE] = false
+        IRB.conf[:USE_MULTILINE] = false
+
+        # Create workspace with top-level binding for Rails Console-like behavior
+        @workspace = IRB::WorkSpace.new(TOPLEVEL_BINDING)
+
+        # Inject Rails console helpers if available
+        inject_rails_console_methods
+
+        logger.debug '[EmbeddedSupervisor] IRB workspace configured'
+      end
+
+      def inject_rails_console_methods
+        # Only inject for embed_rails mode
+        return unless @embed_mode == :embed_rails
+
+        begin
+          # Rails 7.1 and earlier: use Rails::ConsoleMethods
+          if defined?(Rails::ConsoleMethods)
+            @workspace.binding.eval('extend Rails::ConsoleMethods')
+            logger.debug '[EmbeddedSupervisor] Rails::ConsoleMethods injected'
+          else
+            # Rails 7.2+: ConsoleMethods moved, define reload! directly
+            inject_reload_method
+            logger.debug '[EmbeddedSupervisor] reload! method injected directly'
+          end
+        rescue StandardError => e
+          logger.warn "[EmbeddedSupervisor] Failed to inject console methods: #{e.message}"
+        end
+      end
+
+      def inject_reload_method
+        # Define reload! method that calls Rails reloader
+        @workspace.binding.eval(<<~RUBY)
+          def reload!(print = true)
+            puts "Reloading..." if print
+            Rails.application.reloader.reload!
+            true
+          end
+        RUBY
+      end
+
+      def execute_code(code, timeout, start_time)
+        stdout_capture = StringIO.new
+        stderr_capture = StringIO.new
+        result = nil
+        error = nil
+
+        # Capture stdout/stderr
+        original_stdout = $stdout
+        original_stderr = $stderr
+        $stdout = stdout_capture
+        $stderr = stderr_capture
+
+        begin
+          Timeout.timeout(timeout) do
+            # Use workspace.binding.eval for full IRB context
+            result = @workspace.binding.eval(code, '(consolle)', 1)
+          end
+        rescue Timeout::Error
+          $stdout = original_stdout
+          $stderr = original_stderr
+          return build_timeout_response(timeout)
+        rescue SyntaxError => e
+          error = e
+        rescue StandardError => e
+          error = e
+        ensure
+          $stdout = original_stdout
+          $stderr = original_stderr
+        end
+
+        execution_time = Time.now - start_time
+        captured_output = stdout_capture.string + stderr_capture.string
+
+        if error
+          build_error_response_with_output(error, captured_output, execution_time)
+        else
+          build_success_response_with_result(result, captured_output, execution_time)
+        end
+      end
+
+      def build_error_response_with_output(error, captured_output, execution_time)
+        output = captured_output.empty? ? "#{error.class}: #{error.message}" : captured_output
+
+        {
+          success: false,
+          error_class: error.class.name,
+          error_code: Consolle::Errors::ErrorClassifier.to_code(error),
+          output: output,
+          execution_time: execution_time
+        }
+      end
+
+      def build_success_response_with_result(result, captured_output, execution_time)
+        # Format output like Rails console
+        # If there's captured stdout, include it
+        # Always include the return value with => prefix
+        output_parts = []
+        output_parts << captured_output unless captured_output.empty?
+        output_parts << "=> #{result.inspect}"
+
+        {
+          success: true,
+          output: output_parts.join("\n"),
+          result: result,
+          execution_time: execution_time
+        }
+      end
+    end
+  end
+end

data/lib/consolle/server/supervisor_factory.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'console_supervisor'
+require_relative 'embedded_supervisor'
+
+module Consolle
+  module Server
+    # Factory for creating the appropriate supervisor based on configuration
+    #
+    # Modes:
+    # - :pty        - PTY-based, supports custom command (local/remote)
+    # - :embed_irb  - Pure IRB embedding (Ruby 3.3+, local only)
+    # - :embed_rails - Rails console embedding (Ruby 3.3+, local only)
+    class SupervisorFactory
+      MODES = %i[pty embed_irb embed_rails].freeze
+      EMBEDDED_MODES = %i[embed_irb embed_rails].freeze
+
+      class << self
+        # Create a supervisor instance
+        # @param rails_root [String] Path to project root
+        # @param mode [Symbol] :pty, :embed_irb, or :embed_rails
+        # @param options [Hash] Additional options passed to supervisor
+        # @return [BaseSupervisor] PTY or Embedded supervisor
+        def create(rails_root:, mode: :pty, **options)
+          mode = normalize_mode(mode)
+          validate_mode!(mode)
+
+          case mode
+          when :pty
+            create_pty_supervisor(rails_root, options)
+          when :embed_irb
+            create_embedded_supervisor(rails_root, :embed_irb, options)
+          when :embed_rails
+            create_embedded_supervisor(rails_root, :embed_rails, options)
+          end
+        end
+
+        # Check if embedded mode is available (Ruby 3.3+)
+        # @return [Boolean]
+        def embedded_available?
+          EmbeddedSupervisor.supported?
+        end
+
+        private
+
+        def normalize_mode(mode)
+          mode_sym = mode.to_s.tr('-', '_').to_sym
+
+          # Handle legacy mode names
+          case mode_sym
+          when :embedded then :embed_rails
+          when :auto then :pty
+          else mode_sym
+          end
+        end
+
+        def validate_mode!(mode)
+          return if MODES.include?(mode)
+
+          raise ArgumentError, "Invalid mode: #{mode}. Must be one of: #{MODES.join(', ')}"
+        end
+
+        def create_pty_supervisor(rails_root, options)
+          ConsoleSupervisor.new(
+            rails_root: rails_root,
+            rails_env: options[:rails_env] || 'development',
+            logger: options[:logger],
+            command: options[:command],
+            wait_timeout: options[:wait_timeout]
+          )
+        end
+
+        def create_embedded_supervisor(rails_root, embed_mode, options)
+          EmbeddedSupervisor.check_support!
+
+          EmbeddedSupervisor.new(
+            rails_root: rails_root,
+            rails_env: options[:rails_env] || 'development',
+            logger: options[:logger],
+            embed_mode: embed_mode
+          )
+        end
+      end
+    end
+  end
+end

data/rule.ko.md

@@ -37,6 +37,46 @@ $ cone stop # 서버 중지
 
 작업을 마치면 반드시 종료해 주세요.
 
+## 실행 모드
+
+Cone은 세 가지 실행 모드를 지원합니다. `--mode` 옵션으로 지정할 수 있습니다.
+
+| 모드 | 설명 | Ruby 요구사항 | 실행 속도 |
+|------|------|--------------|----------|
+| `pty` | PTY 기반, 커스텀 명령어 지원 (기본값) | 모든 버전 | ~0.6s |
+| `embed-rails` | Rails 콘솔 임베딩 | Ruby 3.3+ | ~0.001s |
+| `embed-irb` | 순수 IRB 임베딩 (Rails 미로드) | Ruby 3.3+ | ~0.001s |
+
+```bash
+$ cone start                      # PTY 모드 (기본값)
+$ cone start --mode embed-rails   # Rails 콘솔 임베딩 (200배 빠름)
+$ cone start --mode embed-irb     # 순수 IRB 임베딩 (Rails 없이)
+```
+
+### 모드 선택 기준
+
+- **`pty`**: 원격 환경(SSH, Docker, Kamal)이나 커스텀 명령어가 필요한 경우
+- **`embed-rails`**: 로컬 Rails 개발에서 빠른 실행이 필요한 경우
+- **`embed-irb`**: Rails 없이 순수 Ruby 코드만 실행하는 경우
+
+### 커스텀 명령어 (PTY 모드 전용)
+
+PTY 모드에서는 `--command` 옵션으로 커스텀 콘솔 명령어를 지정할 수 있습니다.
+
+```bash
+$ cone start --command "docker exec -it app bin/rails console"
+$ cone start --command "kamal console" --wait-timeout 60
+```
+
+### 설정 파일
+
+프로젝트 루트에 `.consolle.yml` 파일로 기본 모드를 설정할 수 있습니다. CLI 옵션은 설정 파일보다 우선합니다.
+
+```yaml
+mode: embed-rails
+# command: "bin/rails console"  # PTY 모드 전용
+```
+
 ## Cone 서버 상태 확인
 
 ```bash
@@ -74,10 +114,13 @@ $ cone exec 'puts u'
 $ cone exec -f example.rb
 ```
 
-디버깅을 위한 `-v` 옵션(Verbose 출력)이 제공됩니다.
+디버깅을 위한 `-v` 옵션(Verbose 출력)이 제공됩니다. 실행 시간 및 추가 정보를 표시합니다.
 
 ```bash
 $ cone exec -v 'puts "hello, world"'
+hello, world
+=> nil
+Execution time: 0.001s
 ```
 
 ## 코드 입력 모범 사례

data/rule.md

@@ -37,6 +37,46 @@ $ cone stop # Stop server
 
 Always terminate when you finish your work.
 
+## Execution Modes
+
+Cone supports three execution modes. You can specify the mode with the `--mode` option.
+
+| Mode | Description | Ruby Requirement | Execution Speed |
+|------|-------------|-----------------|-----------------|
+| `pty` | PTY-based, supports custom commands (default) | All versions | ~0.6s |
+| `embed-rails` | Rails console embedding | Ruby 3.3+ | ~0.001s |
+| `embed-irb` | Pure IRB embedding (no Rails) | Ruby 3.3+ | ~0.001s |
+
+```bash
+$ cone start                      # PTY mode (default)
+$ cone start --mode embed-rails   # Rails console embedding (200x faster)
+$ cone start --mode embed-irb     # Pure IRB embedding (without Rails)
+```
+
+### Mode Selection Guide
+
+- **`pty`**: For remote environments (SSH, Docker, Kamal) or when custom commands are needed
+- **`embed-rails`**: For local Rails development when fast execution is required
+- **`embed-irb`**: When running pure Ruby code without Rails
+
+### Custom Commands (PTY Mode Only)
+
+In PTY mode, you can specify a custom console command with the `--command` option.
+
+```bash
+$ cone start --command "docker exec -it app bin/rails console"
+$ cone start --command "kamal console" --wait-timeout 60
+```
+
+### Configuration File
+
+You can set the default mode in a `.consolle.yml` file at the project root. CLI options take precedence over the configuration file.
+
+```yaml
+mode: embed-rails
+# command: "bin/rails console"  # PTY mode only
+```
+
 ## Checking Cone Server Status
 
 ```bash
@@ -74,10 +114,13 @@ You can also execute Ruby files directly using the `-f` option. Unlike Rails Run
 $ cone exec -f example.rb
 ```
 
-A `-v` option (Verbose output) is provided for debugging.
+A `-v` option (Verbose output) is provided for debugging. It shows execution time and additional details.
 
 ```bash
 $ cone exec -v 'puts "hello, world"'
+hello, world
+=> nil
+Execution time: 0.001s
 ```
 
 ## Best Practices for Code Input

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: consolle
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.3.8
 platform: ruby
 authors:
 - nacyot
@@ -82,9 +82,12 @@ files:
 - lib/consolle/config.rb
 - lib/consolle/constants.rb
 - lib/consolle/errors.rb
+- lib/consolle/server/base_supervisor.rb
 - lib/consolle/server/console_socket_server.rb
 - lib/consolle/server/console_supervisor.rb
+- lib/consolle/server/embedded_supervisor.rb
 - lib/consolle/server/request_broker.rb
+- lib/consolle/server/supervisor_factory.rb
 - lib/consolle/version.rb
 - mise/release.sh
 - rule.ko.md