rails_agent_server 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67c2f8f4c1a4d5f62de047f40c1bf076549b7f303b1dad62b8459919cd73ed87
-  data.tar.gz: 4ae4c453471fb620d461742684b379fc0ba4e28d62b77d662f704bc039b10a54
+  metadata.gz: 11eb2a0d810274304d6e7131cdcddfd1c3f5b4a1473eed28c0fd27b36d664237
+  data.tar.gz: e029aa9ba2ee8b4c36c56e0ef2bca85d59b99597aad5333dc2f4c9accbc99e99
 SHA512:
-  metadata.gz: 414387d2240dd9736ae51d8149949e0adb72d75eac81b39dcd50da9cbf03ff29424cbc281d4477fe10ab211541e45b6d7e48b5d512d3ce20389f50508e768f45
-  data.tar.gz: 325d73826e71519c811aac9b91206d1f1f702006d578ddc40618abac28d18ca7411da1dc5db54d8bc13bba68036f0bc2ad96491bf9bb3f0c621122ddef29f33a
+  metadata.gz: 45ce707f90465a9be908e2fede50fd55a89ec92b2ad9f92f04766d7e23f6d18725b2ba7db9f021126869116383dec56f8ac91f922cf84d7d480c35924e5d72c1
+  data.tar.gz: f5e672ba4329e07f4eaac6e6338e78dd8a386c127706f2236f3ce4568458b85a1bda06f56a57d7cfe8bd09334f5f3145e94e10f83c8e802f557560cca6c8bda2

data/README.md

@@ -6,7 +6,7 @@ A persistent Rails server for AI agents that avoids boot overhead for repeated q
 
 When using AI coding assistants or automation tools with Rails applications, the agent often needs to run many small queries via `bin/rails runner` to understand the runtime behaviour or state. Using `bin/rails runner` for each query means booting Rails every time, which can typically take 5-10 seconds per query.
 
-Rails Agent Server starts a persistent background server that keeps Rails loaded in memory. The first request takes the normal Rails boot time, but subsequent requests are instant.
+Rails Agent Server starts a persistent background server that keeps Rails loaded in memory. The first request takes the normal Rails boot time, but subsequent requests are almost instant.
 
 ### Why Not `bin/rails console`?
 
@@ -43,7 +43,19 @@ Rails Agent Server is a lightweight alternative that lets AI agents treat your R
 
 ## Installation
 
-Add this line to your application's Gemfile:
+### Option 1: Global Installation (Recommended for AI Agents)
+
+Install the gem globally so it works with any Rails app without modifying Gemfiles:
+
+```bash
+gem install rails_agent_server
+```
+
+This allows AI agents to use the tool on any Rails project immediately.
+
+### Option 2: Add to Gemfile
+
+Alternatively, add it to your application's Gemfile:
 
 ```ruby
 gem 'rails_agent_server', group: :development
@@ -55,12 +67,6 @@ And then execute:
 bundle install
 ```
 
-Or install it yourself as:
-
-```bash
-gem install rails_agent_server
-```
-
 ## Agent Setup
 
 Add this section to your project's `CLAUDE.md` or equivalent:
@@ -73,13 +79,15 @@ This project uses `rails_agent_server` for fast Rails runner access without boot
 When you need to query the database or run Rails code:
 - Use `rails_agent_server 'YourCode.here'` instead of `bin/rails runner`
 - First request auto-starts a persistent server (takes ~5 seconds)
-- Subsequent requests are instant (no Rails boot time)
+- Subsequent requests are almost instant (no Rails boot time)
 - Server stays running in background until you run `rails_agent_server stop`
 
 Examples:
-  rails_agent_server 'User.count'
-  rails_agent_server 'Post.where(published: true).count'
-  rails_agent_server 'User.find_by(email: "test@example.com")&.name'
+  rails_agent_server 'puts User.count'
+  rails_agent_server 'puts Post.where(published: true).count'
+  rails_agent_server 'puts User.find_by(email: "test@example.com")&.name'
+
+Note: Use `bundle exec rails_agent_server` if the gem is in your Gemfile, or just `rails_agent_server` if installed globally.
 ```
 
 ## Usage
@@ -90,7 +98,7 @@ These commands are designed to be used by AI agents (like Claude Code) or automa
 
 ```bash
 # Run a Ruby expression (auto-starts server if needed)
-rails_agent_server 'User.count'
+rails_agent_server 'puts User.count'
 
 # Run code that prints output
 rails_agent_server 'puts User.pluck(:email).join(", ")'
@@ -100,27 +108,24 @@ rails_agent_server /path/to/script.rb
 
 # Server management
 rails_agent_server status                    # Check if server is running
-rails_agent_server start                     # Manually start the server
 rails_agent_server stop                      # Stop the background server
 rails_agent_server restart                   # Restart the background server
-rails_agent_server help                      # Show help
 ```
 
 ### Examples
 
 ```bash
 # Database queries
-rails_agent_server 'User.count'
-rails_agent_server 'Post.where(published: true).pluck(:title)'
-rails_agent_server 'User.find_by(email: "test@example.com")&.name'
+rails_agent_server 'puts User.count'
+rails_agent_server 'puts Post.where(published: true).pluck(:title)'
+rails_agent_server 'puts User.find_by(email: "test@example.com")&.name'
 
 # Inspect schema
-rails_agent_server 'ActiveRecord::Base.connection.tables'
-rails_agent_server 'User.column_names'
+rails_agent_server 'puts ActiveRecord::Base.connection.tables'
+rails_agent_server 'puts User.column_names'
 
 # Complex operations
-rails_agent_server 'User.group(:status).count'
-rails_agent_server 'Rails.cache.clear; "Cache cleared"'
+rails_agent_server 'Rails.cache.clear; puts "Cache cleared"'
 ```
 
 ## How It Works
@@ -156,7 +161,7 @@ If not in a Rails directory, files are created in `/tmp/`.
 ## Performance
 
 - **First request**: ~5-10 seconds (Rails boot time)
-- **Subsequent requests**: ~50-200ms (no boot overhead)
+- **Subsequent requests**: Almost instant (no boot overhead)
 - **Memory**: One Rails process running in background (~200-500MB depending on your app)
 
 ## When to Restart
@@ -183,10 +188,14 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
+### Testing
+
+The test suite includes unit tests (fast, run in CI) and integration tests (slower, require process forking). By default, `rake test` runs only unit tests. See [TESTING.md](TESTING.md) for details on running integration tests locally.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/andyw8/rails_agent_server.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -3,7 +3,9 @@
 require "bundler/gem_tasks"
 require "minitest/test_task"
 
-Minitest::TestTask.create
+Minitest::TestTask.create do |t|
+  t.test_globs = ["test/test_rails_agent_server.rb", "test/test_cli.rb"]
+end
 
 require "standard/rake"
 

data/TESTING.md

@@ -0,0 +1,162 @@
+# Testing
+
+This document explains the test structure and how to run tests for the rails_agent_server gem.
+
+## Test Structure
+
+The test suite is organized into three categories:
+
+### Unit Tests (Always Run)
+
+- **`test/test_rails_agent_server.rb`** - Tests for the `Server` class
+  - Path resolution and defaults
+  - Server status checking
+  - Response formatting
+  - File cleanup
+  - No actual process forking or Rails loading
+
+- **`test/test_cli.rb`** - Tests for the `CLI` class
+  - Command parsing and help text
+  - Error handling
+  - Mocked server interactions
+  - No actual server startup
+
+### Integration Tests (Manual Only)
+
+- **`test/test_integration.rb`** - Tests with actual server process
+  - Forks background server process
+  - Tests real socket communication
+  - Tests code execution and error handling
+  - Requires ability to fork and manage processes
+
+- **`test/test_dummy_integration.rb`** - Tests with dummy Rails app
+  - Uses `test/dummy` Rails application
+  - Tests full Rails environment loading
+  - Tests database operations and persistence
+  - Most realistic but slowest tests
+
+## Running Tests
+
+### Quick Test (Default)
+
+Run the unit tests that are stable in all environments:
+
+```bash
+bundle exec rake test
+```
+
+This runs only the unit tests (`test_rails_agent_server.rb` and `test_cli.rb`).
+
+### Run Linter
+
+```bash
+bundle exec rake standard
+```
+
+### Run Both Tests and Linter
+
+```bash
+bundle exec rake
+```
+
+### Run Integration Tests (Local Only)
+
+These tests fork processes and require a real Rails environment:
+
+```bash
+# Run basic integration tests
+bundle exec ruby -Ilib:test test/test_integration.rb
+
+# Run Rails dummy app integration tests
+cd test/dummy
+bundle exec ruby -I../../lib:../../test ../../test/test_dummy_integration.rb
+```
+
+**Note:** Integration tests are skipped in CI because they were flaky during initial setup. The flakiness stems from:
+- **Timing sensitivity** - Tests poll for file existence with short timeouts that can fail on slow CI runners
+- **Process forking** - Background processes via `fork` and `spawn` can behave differently in GitHub Actions
+- **Rails boot time** - Full Rails environment loading is slow and can exceed polling timeouts
+- **Maintenance cost** - Debugging flaky CI tests outweighed the additional confidence they provide
+
+These tests *could* be enabled in CI with improvements like:
+- Longer timeouts and wait times when `ENV['CI']` is set
+- More robust waiting logic (e.g., exponential backoff)
+- Retry mechanisms for transient failures
+- Dedicated CI job with allowed failures
+
+## CI Configuration
+
+The CI workflow (`.github/workflows/main.yml`) runs:
+
+1. `bundle exec rake test` - Unit tests only
+2. `bundle exec rake standard` - Code linting
+
+The Rakefile explicitly sets `test_globs` to only include unit tests. This is a pragmatic choice:
+- Unit tests provide good coverage of core logic
+- They run in ~10ms vs seconds for integration tests
+- They're deterministic and never flaky
+- Integration tests can be run manually before releases
+
+## Test Philosophy
+
+- **Unit tests** should be fast, deterministic, and run everywhere (local, CI, different OS)
+- **Integration tests** verify real-world behavior but trade speed and reliability for realism
+- All tests use standard Minitest without extra dependencies
+- CI runs unit tests; integration tests are for local verification and releases
+
+## Troubleshooting
+
+### Tests hang or timeout
+
+This usually means an integration test is running when it shouldn't be. Check:
+
+1. Is `ENV['CI']` set? Integration tests skip when this is set.
+2. Are you running the right test file? Use `bundle exec rake test` for safety.
+3. Is there a stale server process? Run `ps aux | grep rails_agent_server` and kill if needed.
+
+### Integration tests fail locally
+
+Integration tests require:
+- Ability to fork processes (won't work on Windows)
+- Write access to temp directories
+- No firewall blocking Unix sockets
+- A working Rails environment for dummy app tests
+
+Common failure modes:
+- **Timeout waiting for socket** - Server took too long to start, increase wait time
+- **Address already in use** - Previous test didn't clean up, check for stale processes
+- **Rails not found** - Dummy app needs `bundle install` in `test/dummy`
+
+If they consistently fail, focus on unit tests which provide 80%+ coverage of core functionality.
+
+## Adding New Tests
+
+- **Add unit tests** for new functionality in the Server or CLI classes
+- **Keep mocks simple** - avoid calling test assertions inside mocked methods (they can cause hangs)
+- **Integration tests are optional** - they verify real behavior but aren't required for CI
+- **Consider CI-friendliness** - if adding integration tests, make timeouts configurable for CI environments
+
+## Re-enabling Integration Tests in CI (Future Work)
+
+If you want to run integration tests in CI:
+
+1. **Make timeouts CI-aware**:
+   ```ruby
+   wait_iterations = ENV['CI'] ? 100 : 30  # 10s vs 3s
+   ```
+
+2. **Add retry logic**:
+   ```ruby
+   Minitest::Retry.use!(retry_count: 3, exceptions_to_retry: [Minitest::Assertion])
+   ```
+
+3. **Create separate CI job**:
+   ```yaml
+   integration-tests:
+     runs-on: ubuntu-latest
+     continue-on-error: true  # Don't block merges on flaky tests
+   ```
+
+4. **Use Docker for consistency**:
+   - Eliminates environment differences
+   - Predictable performance characteristics

data/lib/rails_agent_server/cli.rb

@@ -19,10 +19,7 @@ module RailsAgentServer
         server.restart
       when "status"
         server.status
-      when "start"
-        server.start
-        puts "Rails agent server started"
-      when "--help", "-h", "help", nil
+      when "--help", "-h", nil
         print_help
       else
         execute_code
@@ -39,7 +36,7 @@ module RailsAgentServer
       end
 
       if code.empty?
-        $stderr.puts "Error: No code provided"
+        warn "Error: No code provided"
         print_help
         exit 1
       end
@@ -47,10 +44,10 @@ module RailsAgentServer
       begin
         puts server.execute(code)
       rescue Errno::ENOENT
-        $stderr.puts "Error: Could not connect to Rails agent server"
+        warn "Error: Could not connect to Rails agent server"
         exit 1
       rescue => e
-        $stderr.puts "Error: #{e.message}"
+        warn "Error: #{e.message}"
         exit 1
       end
     end
@@ -60,20 +57,18 @@ module RailsAgentServer
         Rails Agent Server - A persistent Rails server for AI agents
 
         Usage:
-          rails_agent_server 'User.count'              # Run a Ruby expression
+          rails_agent_server 'puts User.count'         # Run a Ruby expression
           rails_agent_server /path/to/script.rb        # Run a script file
-          rails_agent_server start                     # Start the server
           rails_agent_server stop                      # Stop the server
           rails_agent_server restart                   # Restart the server
           rails_agent_server status                    # Check server status
-          rails_agent_server help                      # Show this help
 
         The server auto-starts on first use if not already running.
 
         Examples:
-          rails_agent_server 'User.count'
+          rails_agent_server 'puts User.count'
           rails_agent_server 'puts User.pluck(:email).join(", ")'
-          rails_agent_server 'ActiveRecord::Base.connection.tables'
+          rails_agent_server 'puts ActiveRecord::Base.connection.tables'
           rails_agent_server script.rb
 
         For Claude Code or AI agents, add this to your CLAUDE.md:
@@ -89,9 +84,9 @@ module RailsAgentServer
           - Server stays running in background until you run `rails_agent_server stop`
 
           Examples:
-            rails_agent_server 'User.count'
-            rails_agent_server 'Post.where(published: true).count'
-            rails_agent_server 'User.find_by(email: "test@example.com")&.name'
+            rails_agent_server 'puts User.count'
+            rails_agent_server 'puts Post.where(published: true).count'
+            rails_agent_server 'puts User.find_by(email: "test@example.com")&.name'
       HELP
     end
   end

data/lib/rails_agent_server/server.rb

@@ -19,14 +19,17 @@ module RailsAgentServer
 
       puts "Starting Rails agent server (this will take a few seconds)..."
 
+      # Build load path argument to ensure spawned process uses same gem version
+      load_path_args = $LOAD_PATH.map { |path| ["-I", path] }.flatten
+
       pid = spawn(
-        RbConfig.ruby, "-r", "rails_agent_server/server",
+        RbConfig.ruby, *load_path_args, "-r", "rails_agent_server/server",
         "-e", "RailsAgentServer::Server.new(socket_path: '#{socket_path}', pid_path: '#{pid_path}', log_path: '#{log_path}').run",
         out: log_path, err: log_path
       )
       Process.detach(pid)
 
-      wait_for_server
+      wait_for_server(pid)
     end
 
     def stop
@@ -90,8 +93,8 @@ module RailsAgentServer
         handle_client(client)
       end
     rescue => e
-      $stderr.puts "Server error: #{e.class}: #{e.message}"
-      $stderr.puts e.backtrace.join("\n")
+      warn "Server error: #{e.class}: #{e.message}"
+      warn e.backtrace.join("\n")
       cleanup_files
       raise
     end
@@ -133,9 +136,23 @@ module RailsAgentServer
       end
     end
 
-    def wait_for_server(timeout: 30)
+    def wait_for_server(pid, timeout: 30)
       (timeout * 2).times do
         return if File.exist?(socket_path)
+
+        # Check if process is still alive
+        begin
+          Process.kill(0, pid)
+        rescue Errno::ESRCH
+          # Process died - show error from log
+          if File.exist?(log_path)
+            error_msg = File.read(log_path).strip
+            abort "Rails agent server failed to start: #{error_msg}"
+          else
+            abort "Rails agent server failed to start (no log file found)"
+          end
+        end
+
         sleep 0.5
       end
 
@@ -217,8 +234,6 @@ module RailsAgentServer
 
       if error
         response << error
-      elsif printed_output.empty?
-        response << result.inspect
       end
 
       response

data/lib/rails_agent_server/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAgentServer
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_agent_server
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andy Waite
@@ -11,7 +11,7 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Rails Agent Server provides a persistent background server for running
   Rails code without the overhead of booting Rails for each request. Perfect for AI
-  agents and automation tools that need fast Rails console access.
+  agents that need fast Rails console access.
 email:
 - andyw8@users.noreply.github.com
 executables:
@@ -22,6 +22,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- TESTING.md
 - exe/rails_agent_server
 - lib/rails_agent_server.rb
 - lib/rails_agent_server/cli.rb