fosm-rails-coding-agent 0.0.1

data/lib/fosm_rails_coding_agent/tools/get_models.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module FosmRailsCodingAgent
+  module Tools
+    # Lists all ActiveRecord models in the application with their source locations.
+    class GetModels < Base
+      tool_name "get_models"
+      description <<~DESC
+        Returns a list of all ActiveRecord model classes in the application
+        with their source file locations.
+      DESC
+
+      def call
+        Rails.application.eager_load!
+
+        ActiveRecord::Base.descendants.reject(&:abstract_class?).sort_by(&:name).map do |model|
+          location = source_location_for(model.name)
+          location ? "* #{model.name} at #{location}" : "* #{model.name}"
+        end.join("\n")
+      end
+
+      private
+
+      def source_location_for(class_name)
+        file_path, line_number = Object.const_source_location(class_name)
+        return nil unless file_path
+
+        relative = Pathname.new(file_path).relative_path_from(Rails.root)
+        "#{relative}:#{line_number}"
+      rescue ArgumentError
+        "#{file_path}:#{line_number}"
+      end
+    end
+  end
+end

data/lib/fosm_rails_coding_agent/tools/get_source_location.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module FosmRailsCodingAgent
+  module Tools
+    # Finds the source file and line number for a Ruby constant or method.
+    # Supports constants (String), instance methods (String#gsub),
+    # class methods (File.executable?), and gem roots (dep:rails).
+    class GetSourceLocation < Base
+      tool_name "get_source_location"
+      description <<~DESC
+        Returns the source location for a Ruby constant or method reference.
+
+        Examples: `String`, `String#gsub`, `File.executable?`, `dep:rails`
+
+        Works across the current project and all loaded gems.
+        Prefer this over grepping when you know the exact reference.
+      DESC
+
+      arguments do
+        required(:reference).filled(:string).description("Constant, method, or dep:PACKAGE to look up")
+      end
+
+      def call(reference:)
+        if reference.start_with?("dep:")
+          return package_location(reference.delete_prefix("dep:"))
+        end
+
+        file_path, line_number = self.class.resolve(reference)
+        raise NameError, "could not find source location for #{reference}" unless file_path
+
+        relative_path(file_path, line_number)
+      end
+
+      # Resolve a reference to [file_path, line_number].
+      # Used by GetDocs to share resolution logic.
+      def self.resolve(reference)
+        constant_path, selector, method_name = reference.rpartition(/\.|#/)
+        return Object.const_source_location(method_name) if selector.empty?
+
+        mod = Object.const_get(constant_path)
+        raise "#{constant_path} is not a class/module" unless mod.is_a?(Module)
+
+        if selector == "#"
+          mod.instance_method(method_name).source_location
+        else
+          mod.method(method_name).source_location
+        end
+      end
+
+      private
+
+      def package_location(package)
+        raise "dep: prefix requires Bundler" unless defined?(Bundler)
+
+        spec = Bundler.load.specs.find { |s| s.name == package }
+        raise "Package #{package} not found in Gemfile" unless spec
+
+        spec.full_gem_path
+      end
+
+      def relative_path(file_path, line_number)
+        relative = Pathname.new(file_path).relative_path_from(Rails.root)
+        "#{relative}:#{line_number}"
+      rescue ArgumentError
+        "#{file_path}:#{line_number}"
+      end
+    end
+  end
+end

data/lib/fosm_rails_coding_agent/tools/project_eval.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "timeout"
+require "json"
+
+module FosmRailsCodingAgent
+  module Tools
+    # Evaluates Ruby code in the running Rails application context.
+    # Captures stdout/stderr and enforces a configurable timeout.
+    class ProjectEval < Base
+      tool_name "project_eval"
+      description <<~DESC
+        Evaluates Ruby code in the context of the running Rails application.
+        Current Ruby version: #{RUBY_VERSION}
+
+        Use this to test behavior, inspect objects, or debug issues.
+        Returns the result plus any stdout/stderr output.
+      DESC
+
+      arguments do
+        required(:code).filled(:string).description("The Ruby code to evaluate")
+        optional(:arguments).value(:array).description("Arguments available as `arguments` in the evaluated code")
+        optional(:timeout).filled(:integer).description("Timeout in milliseconds (default: 30000)")
+      end
+
+      def @input_schema.json_schema
+        schema = super
+        schema[:properties][:arguments][:items] = {}
+        schema
+      end
+
+      def call(code:, arguments: [], timeout: nil)
+        timeout ||= FosmRailsCodingAgent.config.eval_timeout_ms
+        original_stdout = $stdout
+        original_stderr = $stderr
+
+        stdout_capture = StringIO.new
+        stderr_capture = StringIO.new
+        $stdout = stdout_capture
+        $stderr = stderr_capture
+
+        begin
+          timeout_seconds = timeout / 1000.0
+
+          success, result = begin
+            Timeout.timeout(timeout_seconds) do
+              [true, eval(code, eval_binding(arguments))] # rubocop:disable Security/Eval
+            end
+          rescue Timeout::Error
+            [false, "Timeout::Error: Evaluation timed out after #{timeout}ms"]
+          rescue => e
+            [false, e.full_message]
+          end
+
+          stdout = stdout_capture.string
+          stderr = stderr_capture.string
+
+          if stdout.empty? && stderr.empty?
+            result.to_s
+          else
+            "STDOUT:\n#{stdout}\n\nSTDERR:\n#{stderr}\n\nResult:\n#{result}"
+          end
+        ensure
+          $stdout = original_stdout
+          $stderr = original_stderr
+        end
+      end
+
+      private
+
+      def eval_binding(arguments)
+        binding
+      end
+    end
+  end
+end

data/lib/fosm_rails_coding_agent/transport.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+require "rack"
+require "fast_mcp"
+
+module FosmRailsCodingAgent
+  # Streamable HTTP transport for MCP — POST-only, no SSE.
+  # Implements the MCP Streamable HTTP protocol for synchronous
+  # JSON-RPC message exchange between coding agents and FosmRailsCodingAgent.
+  class Transport < FastMcp::Transports::BaseTransport
+    attr_reader :app, :path
+
+    def initialize(app, server, options = {})
+      super(server, logger: options[:logger])
+      @app     = app
+      @path    = options[:path_prefix] || "/mcp"
+      @running = false
+    end
+
+    def start
+      @logger.debug("[FosmRailsCodingAgent] MCP transport started at #{@path}")
+      @running = true
+    end
+
+    def stop
+      @logger.debug("[FosmRailsCodingAgent] MCP transport stopped")
+      @running = false
+    end
+
+    def send_message(message)
+      @captured_response = message
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+
+      if request.path == @path
+        @server.transport = self
+        handle_request(request)
+      else
+        @app.call(env)
+      end
+    end
+
+    private
+
+    def handle_request(request)
+      return method_not_allowed unless request.post?
+
+      body    = request.body.read
+      message = JSON.parse(body)
+
+      return json_error(400, -32600, "Invalid Request") unless valid_jsonrpc?(message)
+
+      @captured_response = nil
+      @server.handle_json_request(message)
+
+      if @captured_response
+        [200, { "Content-Type" => "application/json" }, [JSON.generate(@captured_response)]]
+      else
+        [202, {}, []]
+      end
+    rescue JSON::ParserError
+      json_error(400, -32700, "Parse error")
+    rescue => e
+      @logger.error("[FosmRailsCodingAgent] #{e.message}")
+      json_error(500, -32603, "Internal error")
+    end
+
+    def valid_jsonrpc?(msg)
+      msg.is_a?(Hash) && msg["jsonrpc"] == "2.0" && (msg.key?("method") || msg.key?("result") || msg.key?("error"))
+    end
+
+    def method_not_allowed
+      json_error(405, -32601, "Only POST requests are supported")
+    end
+
+    def json_error(http_status, code, message)
+      [http_status, { "Content-Type" => "application/json" },
+       [JSON.generate({ jsonrpc: "2.0", error: { code: code, message: message }, id: nil })]]
+    end
+  end
+end

data/lib/fosm_rails_coding_agent/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FosmRailsCodingAgent
+  VERSION = "0.0.1"
+end

data/lib/fosm_rails_coding_agent.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "fosm_rails_coding_agent/version"
+require "fosm_rails_coding_agent/configuration"
+
+module FosmRailsCodingAgent
+  class << self
+    # Returns the global FosmRailsCodingAgent configuration.
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Yields the configuration for block-style setup.
+    def configure
+      yield config
+    end
+
+    # Returns true when fosm-rails is loaded and the Fosm::Lifecycle constant
+    # is defined. FOSM tools are only registered when this returns true.
+    def fosm_available?
+      defined?(::Fosm::Lifecycle) && defined?(::Fosm::Registry)
+    end
+  end
+end
+
+require "fosm_rails_coding_agent/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: fosm-rails-coding-agent
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Abhishek Parolkar
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: fast-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: acp_ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: |
+  Embeds a FOSM-aware MCP server and ACP agent into your Rails development
+  environment, giving coding agents (Claude Code, Codex, Copilot) runtime intelligence:
+  database queries, logs, code evaluation, and deep introspection of FOSM lifecycle
+  definitions, state machines, transitions, guards, and audit trails.
+
+  Built on the FOSM (Finite Object State Machine) paradigm — declarative lifecycles
+  for business objects where AI agents operate within bounded, auditable state machines.
+email:
+- abhishek@parolkar.com
+executables:
+- fosm-coding-agent
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/fosm-coding-agent
+- lib/fosm_rails_coding_agent.rb
+- lib/fosm_rails_coding_agent/acp_agent.rb
+- lib/fosm_rails_coding_agent/configuration.rb
+- lib/fosm_rails_coding_agent/exceptions_middleware.rb
+- lib/fosm_rails_coding_agent/middleware.rb
+- lib/fosm_rails_coding_agent/quiet_middleware.rb
+- lib/fosm_rails_coding_agent/railtie.rb
+- lib/fosm_rails_coding_agent/tools/base.rb
+- lib/fosm_rails_coding_agent/tools/execute_sql.rb
+- lib/fosm_rails_coding_agent/tools/fosm/available_events.rb
+- lib/fosm_rails_coding_agent/tools/fosm/fire_event.rb
+- lib/fosm_rails_coding_agent/tools/fosm/inspect_lifecycle.rb
+- lib/fosm_rails_coding_agent/tools/fosm/list_lifecycles.rb
+- lib/fosm_rails_coding_agent/tools/fosm/model_resolver.rb
+- lib/fosm_rails_coding_agent/tools/fosm/transition_history.rb
+- lib/fosm_rails_coding_agent/tools/fosm/why_blocked.rb
+- lib/fosm_rails_coding_agent/tools/get_docs.rb
+- lib/fosm_rails_coding_agent/tools/get_logs.rb
+- lib/fosm_rails_coding_agent/tools/get_models.rb
+- lib/fosm_rails_coding_agent/tools/get_source_location.rb
+- lib/fosm_rails_coding_agent/tools/project_eval.rb
+- lib/fosm_rails_coding_agent/transport.rb
+- lib/fosm_rails_coding_agent/version.rb
+homepage: https://github.com/inloopstudio/fosm-rails-coding-agent
+licenses:
+- FSL-1.1-Apache-2.0
+metadata:
+  homepage_uri: https://github.com/inloopstudio/fosm-rails-coding-agent
+  source_code_uri: https://github.com/inloopstudio/fosm-rails-coding-agent
+  changelog_uri: https://github.com/inloopstudio/fosm-rails-coding-agent/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: FOSM-aware runtime intelligence for Rails — MCP server + ACP agent for coding
+  agents
+test_files: []