console_ipc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 184ebdc1e89525ad7d1b5572a1fc6283b6ab5a16a19cf4bf35cafcbeb11f0941
+  data.tar.gz: ddb7d85809958e6e92ea6f7c8ec1be49e33c0a0d16452469a05c73410f50b622
+SHA512:
+  metadata.gz: f94f1222cbf44a7ec76977b28a9346149282d254b95c4263fc179e1d15fd789a577f73342260aef3aec1b4d9406a0322412831f1bcaa1f30d3ea285f6e2a75c9
+  data.tar.gz: 92d396c212ed6ba1b512314c193e405e1784d1b53bd3e165d88aa7c8f5f3cd89bdcffc0763246e606f58bf1acf0e89054a779eb3e4b710f1b4a78ed7e2543043

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jean-Francis Bastien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,173 @@
+# Console IPC
+
+Fast, stateful `rails runner` alternative over a Unix socket.
+
+## Why use it?
+
+`console-ipc` gives you a scriptable Rails console that stays warm.
+
+Instead of paying Rails boot cost for every `rails runner` command, start one background console and send Ruby snippets
+to it over a Unix socket. Each snippet runs in the same top-level console binding, so local variables, helper methods,
+loaded records, and exploratory state can survive across commands.
+
+```bash
+bundle exec console-ipc start > log/console-ipc.log 2>&1
+bundle exec console-ipc run 'account = Account.last'
+bundle exec console-ipc run 'account.email'
+bundle exec console-ipc run --json 'account.attributes.slice("id", "email")'
+```
+
+It is built for tight local feedback loops:
+
+- Inspect production-shaped Rails data locally without repeating setup code.
+- Keep expensive objects, query results, and helper methods alive between probes.
+- Run quick snippets from shell scripts, editors, terminals, and AI coding agents.
+- Produce fewer output tokens for agent workflows because setup, helper definitions, and repeated context can stay in
+  the warm console instead of being printed again for every command.
+- Ask Ruby and Rails where code lives: `source_location`, `const_source_location`, `ancestors`, `methods`, and related
+  reflection calls.
+- Edit source, call `reload`, and keep exploring without restarting the console.
+- Use `--json` when another tool needs structured `stdout`, `stderr`, result, and error data.
+
+The result is faster turnaround, less terminal noise, and smaller agent transcripts. Instead of rerunning a large setup
+script, you build context once and reuse it.
+
+## Install
+
+Add the gem to a Rails app:
+
+```ruby
+gem "console_ipc", group: :development
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick start
+
+Start it from the Rails app root. The command daemonizes by default and returns only after Rails is loaded and the
+socket is listening:
+
+```bash
+bundle exec console-ipc start > log/console-ipc.log 2>&1
+```
+
+Run snippets against the warm console:
+
+```bash
+bundle exec console-ipc run 'emails = Account.last(10).map(&:email)'
+bundle exec console-ipc run 'puts emails'
+bundle exec console-ipc run --json 'Account.count'
+```
+
+State persists:
+
+```bash
+bundle exec console-ipc run 'def explain(record); record.attributes.slice("id", "created_at"); end'
+bundle exec console-ipc run --json 'explain(Account.last)'
+```
+
+Send code through stdin when that is easier than shell quoting:
+
+```bash
+cat <<'RUBY' | bundle exec console-ipc run --json
+account = Account.last
+{
+  id: account.id,
+  email: account.email,
+  changes: account.previous_changes
+}
+RUBY
+```
+
+## What it can do
+
+### Stateful Rails probing
+
+Every `run` command evaluates in the same console context:
+
+```bash
+bundle exec console-ipc run 'scope = Account.where(active: true)'
+bundle exec console-ipc run 'scope.count'
+bundle exec console-ipc run 'sample = scope.order(:created_at).last'
+bundle exec console-ipc run 'sample.class'
+```
+
+That makes repetitive inspection much cheaper than rebuilding the same scope every time.
+
+### Reflection and source discovery
+
+Use normal Ruby and Rails reflection from the terminal:
+
+```bash
+bundle exec console-ipc run 'Account.instance_method(:save).source_location'
+bundle exec console-ipc run 'Object.const_source_location("Account")'
+bundle exec console-ipc run 'Account.ancestors'
+bundle exec console-ipc run 'Account.new.public_methods.grep(/email/)'
+```
+
+### Machine-readable output
+
+`--json` prints the raw response object:
+
+```bash
+bundle exec console-ipc run --json 'Account.count'
+```
+
+Successful responses include:
+
+- `ok`: whether evaluation succeeded.
+- `stdout`: captured `$stdout`.
+- `stderr`: captured `$stderr`.
+- `result`: `inspect` output for the last expression.
+- `output`: console-style combined output.
+
+Error responses include `ok: false`, captured output, and the exception message with a short backtrace.
+
+### Source reloads
+
+Use `reload` after source edits. It calls Rails console `reload!` inside the running process:
+
+```bash
+bundle exec console-ipc reload
+```
+
+### Process lifecycle
+
+Use `reset` for a clean process and `stop` when done:
+
+```bash
+bundle exec console-ipc reset
+bundle exec console-ipc stop
+```
+
+Use `--foreground` when debugging the console process directly or when you want Ctrl-C to stop it:
+
+```bash
+bundle exec console-ipc start --foreground
+```
+
+## Tips
+
+Start the console once and reuse `run` for later snippets. Do not stop or restart it between runs unless the socket is
+stale or `run` reports that no console is listening. If that happens, remove the stale socket and start it again:
+
+```bash
+rm -f tmp/console_ipc.sock
+bundle exec console-ipc start > log/console-ipc.log 2>&1
+```
+
+Use `reset` when state gets confusing:
+
+```bash
+bundle exec console-ipc reset
+```
+
+## Security model
+
+`console-ipc` is intended for local development and trusted automation. It evaluates arbitrary Ruby in your Rails app.
+The socket is created with `0600` permissions, but anyone who can access the socket as your user can run code in that
+Rails process. Do not expose the socket over the network.

data/exe/console-ipc

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'console_ipc/cli'
+
+exit ConsoleIpc::CLI.new(ARGV).call

data/lib/console_ipc/cli.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'io/wait'
+require 'optparse'
+
+require_relative 'connection'
+
+module ConsoleIpc
+  class CLI
+    COMMANDS = %w[reload reset run start stop].freeze
+    START_WAIT_TIMEOUT_SECONDS = 120
+
+    def initialize(argv, output: $stdout, error: $stderr)
+      @argv = argv.dup
+      @output = output
+      @error = error
+      @socket_path = Connection.socket_path
+    end
+
+    def call
+      command = @argv.shift
+
+      return usage(1) unless COMMANDS.include?(command)
+
+      call_command(command)
+    end
+
+    private
+
+    attr_reader :argv, :output, :error, :socket_path
+
+    def call_command(command)
+      case command
+        when 'reload'
+          reload
+        when 'reset'
+          reset
+        when 'run'
+          run_code
+        when 'start'
+          start
+        when 'stop'
+          stop
+      end
+    end
+
+    def start
+      foreground = parse_start_options
+      return start_server if foreground
+
+      start_daemon
+    end
+
+    def start_server(&ready_callback)
+      load_rails_console
+      Server.new(context: TOPLEVEL_BINDING, socket_path: socket_path).start(&ready_callback)
+      0
+    end
+
+    def start_daemon
+      read_pipe, write_pipe = IO.pipe
+
+      pid = fork do
+        read_pipe.close
+        detach_from_shell
+
+        begin
+          start_server { signal_ready(write_pipe) }
+        rescue StandardError => e
+          signal_start_error(write_pipe, e)
+          raise
+        ensure
+          write_pipe.close unless write_pipe.closed?
+        end
+      end
+
+      write_pipe.close
+      Process.detach(pid)
+      wait_until_daemon_ready(read_pipe)
+    end
+
+    def run_code
+      json = parse_run_options
+      code = read_code
+
+      abort_with('console-ipc run requires Ruby code as an argument or stdin') if code.empty?
+
+      response = Connection.execute(code, socket_path: socket_path)
+      write_response(response, json: json)
+    rescue ConnectionError => e
+      error.puts e.message
+      1
+    end
+
+    def parse_run_options
+      json = false
+
+      OptionParser.new do |opts|
+        opts.banner = 'Usage: console-ipc run [options] RUBY_CODE'
+
+        opts.on('--json', 'Print raw JSON response') do
+          json = true
+        end
+
+        opts.on('--socket PATH', 'Unix socket path') do |path|
+          @socket_path = File.expand_path(path)
+        end
+      end.parse!(argv)
+
+      json
+    end
+
+    def read_code
+      code = argv.join(' ')
+      code = $stdin.read if code.empty? && !$stdin.tty?
+      code
+    end
+
+    def stop
+      parse_socket_option('Usage: console-ipc stop [--socket PATH]')
+
+      response = Connection.stop(socket_path: socket_path)
+      output.print response.fetch('output')
+      Connection.wait_until_stopped(socket_path: socket_path)
+      response.fetch('ok') ? 0 : 1
+    rescue ConnectionError => e
+      error.puts e.message
+      1
+    end
+
+    def reset
+      parse_socket_option('Usage: console-ipc reset [--socket PATH]')
+      stop_existing_console
+      load_rails_console
+      Server.new(context: TOPLEVEL_BINDING, socket_path: socket_path).start
+      0
+    end
+
+    def reload
+      parse_socket_option('Usage: console-ipc reload [--socket PATH]')
+
+      response = Connection.reload(socket_path: socket_path)
+      output.print response.fetch('output')
+      response.fetch('ok') ? 0 : 1
+    rescue ConnectionError => e
+      error.puts e.message
+      1
+    end
+
+    def parse_socket_option(banner)
+      OptionParser.new do |opts|
+        opts.banner = banner
+
+        opts.on('--socket PATH', 'Unix socket path') do |path|
+          @socket_path = File.expand_path(path)
+        end
+      end.parse!(argv)
+    end
+
+    def parse_start_options
+      foreground = false
+
+      OptionParser.new do |opts|
+        opts.banner = 'Usage: console-ipc start [--foreground] [--socket PATH]'
+
+        opts.on('--foreground', 'Keep the console process attached to the current shell') do
+          foreground = true
+        end
+
+        opts.on('--socket PATH', 'Unix socket path') do |path|
+          @socket_path = File.expand_path(path)
+        end
+      end.parse!(argv)
+
+      foreground
+    end
+
+    def stop_existing_console
+      response = Connection.stop(socket_path: socket_path)
+      output.print response.fetch('output')
+      Connection.wait_until_stopped(socket_path: socket_path)
+    rescue ConnectionError
+      nil
+    end
+
+    def detach_from_shell
+      Process.setsid
+      trap('HUP', 'IGNORE') if Signal.list.key?('HUP')
+    rescue Errno::EPERM
+      nil
+    end
+
+    def signal_ready(write_pipe)
+      write_pipe.puts('ready')
+      write_pipe.close
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def signal_start_error(write_pipe, exception)
+      write_pipe.puts("error: #{exception.class}: #{exception.message}") unless write_pipe.closed?
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def wait_until_daemon_ready(read_pipe)
+      ready = read_pipe.wait_readable(START_WAIT_TIMEOUT_SECONDS)
+
+      return daemon_start_timeout(read_pipe) unless ready
+
+      status = read_pipe.gets
+      read_pipe.close
+
+      case status&.chomp
+        when 'ready'
+          0
+        when /^error: /
+          error.puts status
+          1
+        else
+          error.puts 'console-ipc daemon exited before it was ready'
+          1
+      end
+    end
+
+    def daemon_start_timeout(read_pipe)
+      read_pipe.close
+      error.puts "Timed out waiting for console-ipc to start on #{socket_path}"
+      1
+    end
+
+    def load_rails_console
+      require_relative 'server'
+      require File.expand_path('config/environment', Connection.root_path)
+      Rails.application.load_console
+      TOPLEVEL_BINDING.receiver.extend(Rails::ConsoleMethods)
+    end
+
+    def write_response(response, json:)
+      if json
+        output.puts JSON.generate(response)
+      else
+        output.print response.fetch('output')
+      end
+
+      response.fetch('ok') ? 0 : 1
+    end
+
+    def usage(exit_code)
+      error.puts <<~USAGE
+        Usage: console-ipc COMMAND [options]
+
+        Commands:
+          start    Start a Rails console server
+          run      Run Ruby code in the running console
+          stop     Stop the running console
+          reset    Stop the running console, then start a new one
+          reload   Call reload! in the running console
+
+        Start options:
+          --foreground  Keep the console process attached to the current shell
+      USAGE
+      exit_code
+    end
+
+    def abort_with(message)
+      error.puts message
+      1
+    end
+  end
+end

data/lib/console_ipc/connection.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'socket'
+
+module ConsoleIpc
+  class ConnectionError < StandardError; end
+
+  class Connection
+    DEFAULT_SOCKET_PATH = 'tmp/console_ipc.sock'
+    STOP_WAIT_TIMEOUT_SECONDS = 5
+
+    def self.socket_path
+      ENV.fetch('CONSOLE_IPC_SOCKET') do
+        File.expand_path(DEFAULT_SOCKET_PATH, root_path)
+      end
+    end
+
+    def self.root_path
+      bundle_gemfile = ENV.fetch('BUNDLE_GEMFILE', nil)
+
+      return File.dirname(File.expand_path(bundle_gemfile)) if bundle_gemfile
+
+      Dir.pwd
+    end
+
+    def self.execute(code, socket_path: self.socket_path)
+      request({ action: 'execute', code: code }, socket_path: socket_path)
+    end
+
+    def self.reload(socket_path: self.socket_path)
+      request({ action: 'reload' }, socket_path: socket_path)
+    end
+
+    def self.stop(socket_path: self.socket_path)
+      request({ action: 'stop' }, socket_path: socket_path)
+    end
+
+    def self.wait_until_stopped(socket_path: self.socket_path, timeout: STOP_WAIT_TIMEOUT_SECONDS)
+      deadline = monotonic_time + timeout
+
+      while listening?(socket_path)
+        raise ConnectionError, "Timed out waiting for background console to stop on #{socket_path}" if monotonic_time >= deadline
+
+        sleep 0.05
+      end
+    end
+
+    def self.monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def self.listening?(socket_path = self.socket_path)
+      UNIXSocket.open(socket_path).close
+      true
+    rescue Errno::ENOENT, Errno::ECONNREFUSED
+      false
+    end
+
+    def self.request(payload, socket_path: self.socket_path)
+      UNIXSocket.open(socket_path) do |socket|
+        socket.puts(JSON.generate(payload))
+        JSON.parse(socket.read)
+      end
+    rescue Errno::ENOENT, Errno::ECONNREFUSED => e
+      raise ConnectionError, "No background console is listening on #{socket_path} (#{e.message})"
+    end
+  end
+end

data/lib/console_ipc/evaluator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module ConsoleIpc
+  class Evaluator
+    ERROR_BACKTRACE_LINES = 10
+
+    def initialize(context)
+      @context = context
+    end
+
+    def call(code)
+      stdout = StringIO.new
+      stderr = StringIO.new
+
+      with_output(stdout, stderr) do
+        result = @context.eval(code, '(console-ipc)')
+        response(stdout: stdout, stderr: stderr, result: result)
+      end
+    rescue StandardError => e
+      error_response(stdout: stdout, stderr: stderr, error: e)
+    end
+
+    private
+
+    def response(stdout:, stderr:, result:)
+      result_output = "=> #{result.inspect}\n"
+
+      {
+        ok: true,
+        stdout: stdout.string,
+        stderr: stderr.string,
+        result: result.inspect,
+        output: "#{stdout.string}#{stderr.string}#{result_output}"
+      }
+    end
+
+    def error_response(stdout:, stderr:, error:)
+      message = error_message(error)
+
+      {
+        ok: false,
+        stdout: stdout.string,
+        stderr: stderr.string,
+        error: message,
+        output: "#{stdout.string}#{stderr.string}#{message}\n"
+      }
+    end
+
+    def error_message(error)
+      backtrace = error.backtrace&.first(ERROR_BACKTRACE_LINES)&.join("\n")
+      "#{error.class}: #{error.message}\n#{backtrace}"
+    end
+
+    def with_output(stdout, stderr)
+      original_stdout = $stdout
+      original_stderr = $stderr
+      $stdout = stdout
+      $stderr = stderr
+      yield
+    ensure
+      $stdout = original_stdout
+      $stderr = original_stderr
+    end
+  end
+end

data/lib/console_ipc/server.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'socket'
+
+require_relative 'connection'
+require_relative 'evaluator'
+
+module ConsoleIpc
+  class Server
+    def initialize(context:, socket_path: Connection.socket_path, output: $stdout)
+      @evaluator = Evaluator.new(context)
+      @socket_path = socket_path
+      @output = output
+    end
+
+    def start
+      prepare_socket
+      install_signal_handlers
+
+      UNIXServer.open(socket_path) do |server|
+        File.chmod(0o600, socket_path)
+        @server = server
+        @output.puts "console-ipc listening on #{socket_path}"
+        yield if block_given?
+        serve(server)
+      end
+    ensure
+      cleanup_socket
+    end
+
+    private
+
+    attr_reader :socket_path
+
+    def prepare_socket
+      FileUtils.mkdir_p(File.dirname(socket_path))
+
+      return unless File.exist?(socket_path)
+
+      raise "console-ipc is already listening on #{socket_path}" if Connection.listening?(socket_path)
+
+      File.delete(socket_path)
+    end
+
+    def install_signal_handlers
+      %w[INT TERM].each do |signal|
+        trap(signal) do
+          @server&.close
+          cleanup_socket
+          exit
+        end
+      end
+
+      trap('HUP', 'IGNORE') if Signal.list.key?('HUP')
+    end
+
+    def serve(server)
+      loop do
+        handle_client(server.accept)
+      rescue IOError
+        break
+      end
+    end
+
+    def handle_client(client)
+      request_body = client.gets
+      return if request_body.nil?
+
+      request = JSON.parse(request_body)
+      response = response_for(request)
+      write_response(client, response)
+    rescue JSON::ParserError, KeyError, TypeError => e
+      write_response(client, ok: false, error: e.message, output: "#{e.class}: #{e.message}\n")
+    ensure
+      client&.close
+      @server&.close if @stopping
+    end
+
+    def write_response(client, response)
+      client.write(JSON.generate(response))
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def response_for(request)
+      case request.fetch('action', 'execute')
+        when 'execute'
+          @evaluator.call(request.fetch('code'))
+        when 'reload'
+          @evaluator.call('reload!')
+        when 'stop'
+          @stopping = true
+          { ok: true, output: "console-ipc stopped\n" }
+        else
+          { ok: false, output: "Unknown console-ipc action: #{request.fetch('action')}\n" }
+      end
+    end
+
+    def cleanup_socket
+      File.delete(socket_path) if File.socket?(socket_path)
+    end
+  end
+end

data/lib/console_ipc/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ConsoleIpc
+  VERSION = '0.1.0'
+end

data/lib/console_ipc.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'console_ipc/version'
+require_relative 'console_ipc/cli'
+require_relative 'console_ipc/connection'
+require_relative 'console_ipc/evaluator'
+require_relative 'console_ipc/server'
+
+module ConsoleIpc
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: console_ipc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jean-Francis Bastien
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Console IPC loads a Rails console once and runs snippets against the
+  same process, preserving state between runs while avoiding repeated Rails boot time.
+email:
+- bhacaz@gmail.com
+executables:
+- console-ipc
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/console-ipc
+- lib/console_ipc.rb
+- lib/console_ipc/cli.rb
+- lib/console_ipc/connection.rb
+- lib/console_ipc/evaluator.rb
+- lib/console_ipc/server.rb
+- lib/console_ipc/version.rb
+homepage: https://github.com/jfbastien/console_ipc
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/jfbastien/console_ipc
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Fast, stateful rails runner alternative over a Unix socket.
+test_files: []