consolle 0.3.6 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b3d8a284ca63f38a9e02ca394141f50cd4c0d02a63bae7f78d384a027d0c400
-  data.tar.gz: 7ddfdc210a765e4fc8c6598e5b2d38ffe78f2997a4811c55f6bf461862ccba0a
+  metadata.gz: '0975195db50059158fa8643203c06099ea77c53a6ee199705731244806d7b2d8'
+  data.tar.gz: 8d1fc462e0dc7acd21b9f53989f892ffdf03920b1bc327c82fc70516fda8e201
 SHA512:
-  metadata.gz: ce17c1df36c8284f051bfd658e63252846547e0886cbe4330005470ce4997f24334a470196de0310f24cccf7f305b4c358985752d301cc76a9514d15c296feb5
-  data.tar.gz: 93ff0d888e2436be4cc2952508e6b8dba29afdd79303434e0126871022c23f67de70cccbfc0c8e7e33c0d853c2f90aaf8c2be61f6d3e0559ee8694b195b85807
+  metadata.gz: a281509268f01cdbb60e1a538e9c037c82cce14f26aebd1faf30befeee6aeba6996eaa94f37fa70f13949f0a1d5d749db7604fae39253154d61ec14e6db637ff
+  data.tar.gz: 58c2126e05ca127992001c57a597a095b3c4aa193c36b934de5490d3eddb95bc85770c7bd7e1905c3fdd2b4e95bc68d77f9518d35a22cd8f3619f71c4de15638

data/.version

@@ -1 +1 @@
-0.3.6
+0.3.8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    consolle (0.3.6)
+    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...'
 
@@ -418,7 +434,7 @@ module Consolle
 
           stop
           sleep 1
-          invoke(:start)
+          invoke(:start, [], {})
         else
           puts 'Restarting Rails console subprocess...'
 
@@ -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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Consolle
+  # Configuration loader for .consolle.yml
+  class Config
+    CONFIG_FILENAME = '.consolle.yml'
+
+    # Default prompt pattern that matches various console prompts
+    # - Custom sentinel: \u001E\u001F<CONSOLLE>\u001F\u001E
+    # - Rails app prompts: app(env)> or app(env):001>
+    # - IRB prompts: irb(main):001:0> or irb(main):001>
+    # - Generic prompts: >> or >
+    DEFAULT_PROMPT_PATTERN = /^[^\w]*(\u001E\u001F<CONSOLLE>\u001F\u001E|\w+[-_]?\w*\([^)]*\)(:\d+)?>|irb\([^)]+\):\d+:?\d*[>*]|>>|>)\s*$/
+
+    # 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)
+      new(rails_root)
+    end
+
+    # Check if a custom prompt pattern is configured
+    def custom_prompt_pattern?
+      !@raw_prompt_pattern.nil?
+    end
+
+    # Get human-readable description of expected prompt patterns
+    def prompt_pattern_description
+      if custom_prompt_pattern?
+        "Custom pattern: #{@raw_prompt_pattern}"
+      else
+        <<~DESC.strip
+          Default patterns:
+            - app(env)> or app(env):001>  (Rails console)
+            - irb(main):001:0>            (IRB)
+            - >> or >                     (Generic)
+        DESC
+      end
+    end
+
+    private
+
+    def config_path
+      File.join(@rails_root, CONFIG_FILENAME)
+    end
+
+    def load_config
+      return {} unless File.exist?(config_path)
+
+      begin
+        YAML.safe_load(File.read(config_path)) || {}
+      rescue Psych::SyntaxError => e
+        warn "[Consolle] Warning: Failed to parse #{CONFIG_FILENAME}: #{e.message}"
+        {}
+      end
+    end
+
+    def parse_prompt_pattern(pattern_string)
+      return DEFAULT_PROMPT_PATTERN if pattern_string.nil?
+
+      begin
+        Regexp.new(pattern_string)
+      rescue RegexpError => e
+        warn "[Consolle] Warning: Invalid prompt_pattern '#{pattern_string}': #{e.message}"
+        warn "[Consolle] Using default pattern instead."
+        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

@@ -39,6 +39,56 @@ module Consolle
       end
     end
 
+    # Prompt detection failure with diagnostic information
+    class PromptDetectionError < Error
+      attr_reader :received_output, :expected_patterns, :config_path
+
+      def initialize(timeout:, received_output:, expected_patterns:, config_path:)
+        @received_output = received_output
+        @expected_patterns = expected_patterns
+        @config_path = config_path
+
+        super(build_message(timeout))
+      end
+
+      private
+
+      def build_message(timeout)
+        # Extract last line that looks like a prompt (ends with > or similar)
+        lines = @received_output.to_s.lines.map(&:strip).reject(&:empty?)
+        potential_prompt = lines.reverse.find { |l| l.match?(/[>*]\s*$/) } || lines.last
+
+        <<~MSG.strip
+          Prompt not detected after #{timeout} seconds
+
+          Received output:
+            #{@received_output.to_s.lines.last(5).map { |l| l.strip }.join("\n    ")}
+
+          Potential prompt found:
+            #{potential_prompt.inspect}
+
+          #{@expected_patterns}
+
+          To fix this, add to #{@config_path}:
+            prompt_pattern: '#{escape_for_yaml(potential_prompt)}'
+
+          Or set environment variable:
+            CONSOLLE_PROMPT_PATTERN='#{escape_for_yaml(potential_prompt)}' cone start
+        MSG
+      end
+
+      def escape_for_yaml(str)
+        return '' if str.nil?
+        # Escape special regex characters and create a simple pattern
+        str.to_s
+           .gsub(/\e\[[\d;]*[a-zA-Z]/, '') # Remove ANSI codes
+           .gsub(/[\x00-\x1F]/, '')        # Remove control characters
+           .strip
+           .gsub(/(\d+)/, '\d+')           # Replace numbers with \d+
+           .gsub(/([().\[\]{}|*+?^$\\])/, '\\\\\1') # Escape regex special chars
+      end
+    end
+
     # Syntax error in executed code
     class SyntaxError < ExecutionError
       def initialize(message)
@@ -60,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 = {
@@ -80,7 +144,8 @@ module Consolle
         '::RuntimeError' => 'RUNTIME_ERROR',
         'StandardError' => 'STANDARD_ERROR',
         'Exception' => 'EXCEPTION',
-        'Consolle::Errors::ServerUnhealthy' => 'SERVER_UNHEALTHY'
+        'Consolle::Errors::ServerUnhealthy' => 'SERVER_UNHEALTHY',
+        'Consolle::Errors::PromptDetectionError' => 'PROMPT_DETECTION_ERROR'
       }.freeze
 
       def self.to_code(exception)

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

@@ -5,6 +5,7 @@ require 'timeout'
 require 'fcntl'
 require 'logger'
 require_relative '../constants'
+require_relative '../config'
 require_relative '../errors'
 
 # Ruby 3.4.0+ extracts base64 as a default gem
@@ -17,15 +18,13 @@ $VERBOSE = original_verbose
 module Consolle
   module Server
     class ConsoleSupervisor
-      attr_reader :pid, :reader, :writer, :rails_root, :rails_env, :logger
+      attr_reader :pid, :reader, :writer, :rails_root, :rails_env, :logger, :config
 
       RESTART_DELAY = 1  # seconds
       MAX_RESTARTS = 5   # within 5 minutes
       RESTART_WINDOW = 300 # 5 minutes
-      # Match various Rails console prompts
-      # Match various console prompts: custom sentinel, Rails app prompts, IRB prompts, and generic prompts
-      # Allow optional non-word characters before the prompt (e.g., Unicode symbols like ▽)
-      PROMPT_PATTERN = /^[^\w]*(\u001E\u001F<CONSOLLE>\u001F\u001E|\w+[-_]?\w*\([^)]*\)>|irb\([^)]+\):\d+:?\d*[>*]|>>|>)\s*$/
+      # Legacy constant for backward compatibility - use config.prompt_pattern instead
+      PROMPT_PATTERN = Consolle::Config::DEFAULT_PROMPT_PATTERN
       CTRL_C = "\x03"
 
       def initialize(rails_root:, rails_env: 'development', logger: nil, command: nil, wait_timeout: nil)
@@ -34,6 +33,7 @@ module Consolle
         @command = command || 'bin/rails console'
         @logger = logger || Logger.new(STDOUT)
         @wait_timeout = wait_timeout || Consolle::DEFAULT_WAIT_TIMEOUT
+        @config = Consolle::Config.load(rails_root)
         @pid = nil
         @reader = nil
         @writer = nil
@@ -227,7 +227,7 @@ module Consolle
 
                 # Check if we got prompt back
                 clean = strip_ansi(output)
-                if clean.match?(PROMPT_PATTERN)
+                if clean.match?(prompt_pattern)
                   # Wait a bit for any trailing output
                   sleep 0.1
                   begin
@@ -300,6 +300,17 @@ 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
+      end
+
       def stop
         @running = false
 
@@ -531,7 +542,16 @@ module Consolle
             logger.error "[ConsoleSupervisor] Timeout reached. Current: #{current_time}, Deadline: #{deadline}, Elapsed: #{current_time - start_time}s"
             logger.error "[ConsoleSupervisor] Output so far: #{output.inspect}"
             logger.error "[ConsoleSupervisor] Stripped: #{strip_ansi(output).inspect}"
-            raise Timeout::Error, "No prompt after #{timeout} seconds"
+
+            # Raise PromptDetectionError with diagnostic information
+            config_path = File.join(@rails_root || '.', Consolle::Config::CONFIG_FILENAME)
+            expected_desc = @config&.prompt_pattern_description || "Default prompt patterns"
+            raise Consolle::Errors::PromptDetectionError.new(
+              timeout: timeout,
+              received_output: strip_ansi(output),
+              expected_patterns: expected_desc,
+              config_path: config_path
+            )
           end
 
           # If we found prompt and consume_all is true, continue reading for a bit more
@@ -560,7 +580,7 @@ module Consolle
             clean = strip_ansi(output)
             # Check each line for prompt pattern
             clean.lines.each do |line|
-              if line.match?(PROMPT_PATTERN)
+              if line.match?(prompt_pattern)
                 logger.info '[ConsoleSupervisor] Found prompt!'
                 prompt_found = true
               end
@@ -647,7 +667,7 @@ module Consolle
         # Wait for prompt after configuration with reasonable timeout
         begin
           wait_for_prompt(timeout: 2, consume_all: false)
-        rescue Timeout::Error
+        rescue Timeout::Error, Consolle::Errors::PromptDetectionError
           # This can fail with some console types, but that's okay
           logger.debug '[ConsoleSupervisor] No prompt after IRB configuration, continuing'
         end
@@ -686,7 +706,7 @@ module Consolle
           end
 
           # Skip prompts (but not return values that start with =>)
-          next if line.match?(PROMPT_PATTERN) && !line.start_with?('=>')
+          next if line.match?(prompt_pattern) && !line.start_with?('=>')
 
           # Skip common IRB configuration output patterns
           if line.match?(/^(IRB\.conf|DISABLE_PRY_RAILS|Switch to inspect mode|Loading .*\.rb|nil)$/) ||

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/lib/consolle.rb

@@ -3,6 +3,7 @@
 require_relative 'consolle/version'
 require_relative 'consolle/constants'
 require_relative 'consolle/errors'
+require_relative 'consolle/config'
 require_relative 'consolle/cli'
 
 # Server components

data/rule.ko.md

@@ -20,10 +20,10 @@ Cone은 디버깅, 데이터 탐색, 그리고 개발 보조 도구로 사용됩
 
 ## Cone 서버 시작과 중지
 
-`start` 명령어로 cone을 시작할 수 있으며, `-e`로 실행 환경을 지정할 수 있습니다.
+`start` 명령어로 cone을 시작할 수 있습니다. 실행 환경 지정은 `RAILS_ENV` 환경변수를 사용합니다.
 
 ```bash
-$ cone start # 서버 시작
+$ cone start # 서버 시작 (RAILS_ENV가 없으면 development)
 $ RAILS_ENV=test cone start # test 환경에서 console 시작
 ```
 
@@ -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
 ```
 
 ## 코드 입력 모범 사례
@@ -115,3 +158,34 @@ $ cone exec -f complex_task.rb
 ```
 
 모든 방법은 세션 상태를 유지하므로 변수와 객체가 실행 간에 지속됩니다.
+
+## 실행 안전장치 & 타임아웃
+
+- 기본 타임아웃: 60초
+- 타임아웃 우선순위: `CONSOLLE_TIMEOUT`(설정되고 0보다 클 때) > CLI `--timeout` > 기본값(60초)
+- 사전 Ctrl‑C(프롬프트 분리):
+  - 매 `exec` 전에 Ctrl‑C를 보내고 IRB 프롬프트를 최대 3초 대기해 깨끗한 상태를 보장합니다.
+  - 3초 내 프롬프트가 돌아오지 않으면 콘솔 하위 프로세스를 재시작하고 요청은 `SERVER_UNHEALTHY`로 실패합니다.
+  - 서버 전역 비활성화: `CONSOLLE_DISABLE_PRE_SIGINT=1 cone start`
+  - 호출 단위 제어: `--pre-sigint` / `--no-pre-sigint`
+
+### 예시
+
+```bash
+# CLI로 타임아웃 지정(환경변수 미설정 시 유효)
+cone exec 'heavy_task' --timeout 120
+
+# 최우선 타임아웃(클라이언트·서버 모두 적용)
+CONSOLLE_TIMEOUT=90 cone exec 'heavy_task'
+
+# 타임아웃 이후 복구 확인
+cone exec 'sleep 999' --timeout 2      # -> EXECUTION_TIMEOUT로 실패
+cone exec "puts :after_timeout; :ok"   # -> 정상 동작(프롬프트 복구)
+
+# 호출 단위로 사전 Ctrl‑C 비활성화
+cone exec --no-pre-sigint 'code'
+```
+
+### 에러 코드
+- `EXECUTION_TIMEOUT`: 실행한 코드가 타임아웃을 초과함
+- `SERVER_UNHEALTHY`: 사전 프롬프트 확인(3초) 실패로 콘솔 재시작, 요청 실패

data/rule.md

@@ -20,10 +20,10 @@ Existing objects also reference old code, so you need to create new ones to use
 
 ## Starting and Stopping Cone Server
 
-You can start cone with the `start` command and specify the execution environment with `-e`.
+You can start cone with the `start` command. To select the Rails environment, set the `RAILS_ENV` environment variable.
 
 ```bash
-$ cone start # Start server
+$ cone start # Start server (uses RAILS_ENV or defaults to development)
 $ RAILS_ENV=test cone start # Start console in test environment
 ```
 
@@ -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
@@ -115,3 +158,34 @@ $ cone exec -f complex_task.rb
 ```
 
 All methods maintain the session state, so variables and objects persist between executions.
+
+## Execution Safety & Timeouts
+
+- Default timeout: 60s
+- Timeout precedence: `CONSOLLE_TIMEOUT` (if set and > 0) > CLI `--timeout` > default (60s)
+- Pre-exec Ctrl-C (prompt separation):
+  - Before each `exec`, cone sends Ctrl-C and waits up to 3 seconds for the IRB prompt to ensure a clean state.
+  - If the prompt does not return in 3 seconds, the console subprocess is restarted and the request fails with `SERVER_UNHEALTHY`.
+  - Disable globally for the server: `CONSOLLE_DISABLE_PRE_SIGINT=1 cone start`
+  - Per-call control: `--pre-sigint` / `--no-pre-sigint`
+
+### Examples
+
+```bash
+# Set timeout via CLI (fallback when CONSOLLE_TIMEOUT is not set)
+cone exec 'heavy_task' --timeout 120
+
+# Highest priority timeout (applies on client and server)
+CONSOLLE_TIMEOUT=90 cone exec 'heavy_task'
+
+# Verify recovery after a timeout
+cone exec 'sleep 999' --timeout 2      # -> fails with EXECUTION_TIMEOUT
+cone exec "puts :after_timeout; :ok"   # -> should succeed (prompt recovered)
+
+# Disable pre-exec Ctrl-C for a single call
+cone exec --no-pre-sigint 'code'
+```
+
+### Error Codes
+- `EXECUTION_TIMEOUT`: The executed code exceeded its timeout.
+- `SERVER_UNHEALTHY`: The pre-exec prompt did not return within 3 seconds; the console subprocess was restarted and the request failed.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: consolle
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.3.8
 platform: ruby
 authors:
 - nacyot
 bindir: bin
 cert_chain: []
-date: 2025-09-01 00:00:00.000000000 Z
+date: 2025-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -79,11 +79,15 @@ files:
 - lib/consolle.rb
 - lib/consolle/adapters/rails_console.rb
 - lib/consolle/cli.rb
+- 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