rails-ai-context 5.4.0 → 5.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43e8a71c793404bd950627b8f3319b4e909a0ba7a2cfe937a8d1027e2ede4af0
-  data.tar.gz: f296960edc1f3f336e90b9549618fd4b48d51d31330d95a65de9304ba47aa0af
+  metadata.gz: 313744756e1399207abeb841866440c3de88da5863f92163fd7d344b60c479c5
+  data.tar.gz: 4de97686b1d62c8444a76ed78fc709aade9e0e004adae1a7a655c7d0eae8ce23
 SHA512:
-  metadata.gz: bc10e825ef820ad955e89ded454469104160f954b967958866876794b1c114d9b708564e99781f1252cf4faa683d468bf5143823ee3418080de43ef745508ab2
-  data.tar.gz: 127d4159c5d88da79ae7fcb7389ffb84cca28621e0181da7b7e495e6af6fe0f8c0073b37dff3087a67be78c236e6f09e36aaef82e070461406e8a2027d88d2a8
+  metadata.gz: 0df4cd4cd7c0e99f8c1e662baae65a960819ed8bea551e8bb536bf06cf2b1ba6c42fee462668e990c2bf48572d5b65b66b6f38c730f643c2cd6e19b751ab7a9c
+  data.tar.gz: 88df4ee906be73bb71212bf47acc88e09efe0ac82a87abef786a3f9a829c5aed57bdb63d19c58d6f5a4361d8ebf5955b3ce29a09235a84aa01e9c204e7ee9471

data/CHANGELOG.md

@@ -5,6 +5,83 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.7.0] — 2026-04-09
+
+### Quickstart — Two commands. Problem gone.
+
+```bash
+gem "rails-ai-context", group: :development
+rails generate rails_ai_context:install
+```
+
+### Fixed — Bug Fixes from Codebase Audit
+
+6 bug fixes discovered via automated codebase audit (bug-finder, code-reviewer, doc-consistency-checker agents).
+
+- **AnalyzeFeature service/mailer method extraction** (HIGH) — `\A` (start-of-string) anchor in `scan` regex replaced with `^` (start-of-line). Services and mailers now correctly list all methods instead of always returning empty arrays.
+
+- **SearchCode exact_match + definition double-escaping** (HIGH) — Word boundaries (`\b`) were applied before `Regexp.escape`, producing unmatchable regex when combining `exact_match: true` with `match_type: "definition"` or `"class"`. Boundaries now applied per-match_type after escaping.
+
+- **MigrationAdvisor empty string column bypass** (MEDIUM) — Empty string `""` column names bypassed the "column required" validation (Ruby truthiness). Now normalized via `.presence` so empty strings become `nil` and are caught.
+
+- **GetConcern class method block tracking** — Regex no longer matches `def self.method` as a `class_methods do` block entry, preventing instance methods after `def self.` from being incorrectly skipped.
+
+- **AstCache eviction comment accuracy** — Comment corrected from "evicts oldest entries" to "arbitrary selection" since `Concurrent::Map` has no ordering guarantee.
+
+- **SECURITY.md supported versions** — Added missing 5.6.x row to supported versions table.
+
+- **CONFIGURATION.md preset count** — Fixed stale `:standard` preset count from 13 to 17.
+
+## [5.6.0] — 2026-04-09
+
+### Added — Auto-Registration, TestHelper & Bug Fixes
+
+Developer experience improvements inspired by action_mcp patterns, plus 5 security/correctness bug fixes.
+
+- **Auto-registration via `inherited` hook** — Tools are now auto-discovered from `BaseTool` subclasses. No manual list to maintain — drop a file in `tools/` and it's registered. `Server.builtin_tools` is the new public API. Thread-safe via `@registry_mutex` with deadlock-free design (const_get runs outside mutex to avoid recursive locking from inherited). `Server::TOOLS` preserved as deprecated `const_missing` shim for backwards compatibility.
+
+- **`abstract!` pattern** — `BaseTool.abstract!` excludes a class from the registry. `BaseTool` itself is abstract. Subclasses are concrete by default.
+
+- **TestHelper module** (`lib/rails_ai_context/test_helper.rb`) — Reusable test helper for custom_tools users. Methods: `execute_tool` (by name, short name, or class), `execute_tool_with_error`, `assert_tool_findable`, `assert_tool_response_includes`, `assert_tool_response_excludes`, `extract_response_text`. Works with both RSpec and Minitest. Supports fuzzy name resolution (`schema` → `rails_get_schema`).
+
+### Fixed
+
+- **SQL comment stripping validation bypass** (HIGH) — `#` comment stripping now restricted to line-start only, preventing validation bypass via hash characters in string literals. PostgreSQL JSONB operators (`#>>`) preserved.
+
+- **SHARED_CACHE read outside mutex** (MEDIUM) — `redact_results` now uses `cached_context` for thread-safe access to encrypted column data.
+
+- **McpController double-checked locking** (MEDIUM) — Removed unsynchronized read outside mutex, fixing unsafe pattern on non-GVL Rubies (JRuby/TruffleRuby).
+
+- **PG EXPLAIN parser bare rescue** (LOW) — Changed from `rescue` to `rescue JSON::ParserError`, preventing silent swallowing of bugs in `extract_pg_nodes`.
+
+- **GetConcern `class_methods` block closing** (LOW) — Indent-based tracking to detect the closing `end`, so `def self.` methods after the block are no longer lost.
+
+- **Query spec graceful degradation** — Replaced permanently-pending spec (sqlite3 2.x removed `set_progress_handler`) with a spec that verifies queries execute correctly without it.
+
+## [5.5.0] — 2026-04-08
+
+### Added — Universal MCP Auto-Discovery & Per-Tool Context Optimization (#51-#56)
+
+Every AI tool now gets its own MCP config file — auto-detected on project open. No manual setup needed for any supported tool.
+
+- **McpConfigGenerator** (`lib/rails_ai_context/mcp_config_generator.rb`) — Shared infrastructure for per-tool MCP config generation. Writes `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (GitHub Copilot), `opencode.json` (OpenCode), `.codex/config.toml` (Codex CLI). Merge-safe — only manages the `rails-ai-context` entry, preserves other servers. Supports standalone mode and CLI skip.
+
+- **Codex CLI support** (#51) — 5th supported AI tool. Reuses `AGENTS.md` (shared with OpenCode) and `OpencodeRulesSerializer` for directory-level split rules. Config via `.codex/config.toml` (TOML format) with `[mcp_servers.rails-ai-context.env]` subsection that snapshots Ruby environment variables at install time — required because Codex CLI `env_clear()`s the process before spawning MCP servers. Works with all Ruby version managers (rbenv, rvm, asdf, mise, chruby, system). Added to all 3 install paths (generator, CLI, rake), doctor checks, and search exclusions.
+
+- **Cursor improvements** (#52) — `.cursor/mcp.json` auto-generated for MCP auto-discovery. MCP tools rule changed from `alwaysApply: true` to `alwaysApply: false` with descriptive text for agent-requested (Type 3) loading.
+
+- **OpenCode improvements** (#53) — `opencode.json` auto-generated for MCP auto-discovery.
+
+- **Claude Code improvements** (#54) — `paths:` YAML frontmatter added to `.claude/rules/` schema, models, and components rules for conditional loading. Context and mcp-tools rules remain unconditional.
+
+- **Copilot improvements** (#55) — `.vscode/mcp.json` auto-generated for MCP auto-discovery. `name:` and `description:` YAML frontmatter added to all `.github/instructions/` files. Updated `excludeAgent` spec to validate `code-review`, `coding-agent`, and `workspace` per GitHub Copilot docs.
+
+- **All 3 install paths updated** — Install generator, standalone CLI (`rails-ai-context init`), and rake task (`rails ai:setup`) all delegate to McpConfigGenerator. Codex added as option "5" in interactive tool selection.
+
+- **Doctor expanded** — `check_mcp_json` now validates per-tool MCP configs based on configured `ai_tools` (JSON parse validation + TOML existence check).
+
+- **Search exclusions** — `.codex/`, `.vscode/mcp.json`, `opencode.json` added to `search_code` tool exclusions.
+
 ## [5.4.0] — 2026-04-08
 
 ### Added — Phase 3: Dynamic VFS & Live Resource Architecture (Ground Truth Engine Blueprint #39)

data/CONTRIBUTING.md

@@ -41,7 +41,7 @@ lib/rails_ai_context/
 1. Create `lib/rails_ai_context/tools/your_tool.rb` inheriting from `BaseTool` (auto-loaded by Zeitwerk)
 2. Define `tool_name`, `description`, `input_schema`, and `annotations`
 3. Implement `def self.call(...)` returning `text_response(string)`
-4. Register in `Server::TOOLS`
+4. Auto-registered — no manual list to update (BaseTool.inherited tracks it)
 5. Write specs in `spec/lib/rails_ai_context/tools/your_tool_spec.rb`
 
 ## Adding a Prism Listener

data/README.md

@@ -9,7 +9,8 @@
 <a href="https://cursor.com"><img src="https://img.shields.io/badge/Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white" alt="Cursor"></a>
 <a href="https://github.com/features/copilot"><img src="https://img.shields.io/badge/GitHub_Copilot-000000?style=for-the-badge&logo=githubcopilot&logoColor=white" alt="GitHub Copilot"></a>
 <a href="https://opencode.ai"><img src="https://img.shields.io/badge/OpenCode-4285F4?style=for-the-badge&logoColor=white" alt="OpenCode"></a>
-<a href="#-cli--works-everywhere"><img src="https://img.shields.io/badge/Any_Terminal-4EAA25?style=for-the-badge&logo=gnubash&logoColor=white" alt="Any Terminal"></a>
+<a href="https://codex.openai.com"><img src="https://img.shields.io/badge/Codex_CLI-412991?style=for-the-badge&logo=openai&logoColor=white" alt="Codex CLI"></a>
+<a href="docs/CLI.md"><img src="https://img.shields.io/badge/Any_Terminal-4EAA25?style=for-the-badge&logo=gnubash&logoColor=white" alt="Any Terminal"></a>
 
 
 
@@ -20,7 +21,7 @@
 <br>
 [![Ruby](https://img.shields.io/badge/Ruby-3.2%20%7C%203.3%20%7C%203.4-CC342D)](https://github.com/crisnahine/rails-ai-context)
 [![Rails](https://img.shields.io/badge/Rails-7.1%20%7C%207.2%20%7C%208.0-CC0000)](https://github.com/crisnahine/rails-ai-context)
-[![Tests](https://img.shields.io/badge/Tests-1813%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
+[![Tests](https://img.shields.io/badge/Tests-1889%20passing-brightgreen)](https://github.com/crisnahine/rails-ai-context/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 </div>
@@ -131,7 +132,7 @@ Compare what AI outputs with and without these tools wired in. The difference is
 
 ### MCP Server (stdio)
 
-AI calls tools directly via the protocol. Auto-discovered through `.mcp.json`.
+AI calls tools directly via the protocol. Each AI tool gets its own config file — auto-detected on project open.
 
 ```
 rails ai:serve
@@ -186,20 +187,18 @@ rails 'ai:tool[analyze_feature]' feature=billing
 <br>
 
 ```bash
-# Step 1: Check what exists
 rails 'ai:tool[schema]' table=users
-# → 20 columns, types, indexes, encrypted hints, defaults
-
-# Step 2: Understand the model
-rails 'ai:tool[model_details]' model=User
-# → associations, validations, scopes, enums, callbacks, Devise modules
-
-# Step 3: See the full feature
-rails 'ai:tool[analyze_feature]' feature=subscription
-# → models + controllers + routes + services + jobs + views + tests in one shot
+```
+```
+## Table: users
+| Column              | Type    | Null | Default |
+|---------------------|---------|------|---------|
+| email               | string  | NO   | [unique] |
+| subscription_status | string  | yes  | "free"   |
+| created_at          | datetime| NO   |          |
 ```
 
-AI writes a correct migration, model change, and controller update on the **first attempt**.
+AI sees `subscription_status` already exists. Checks the model, then generates a correct migration — **first attempt**.
 
 </details>
 
@@ -209,19 +208,18 @@ AI writes a correct migration, model change, and controller update on the **firs
 <br>
 
 ```bash
-# Trace what happens
 rails 'ai:tool[controllers]' controller=CooksController action=create
-# → source code + inherited filters + strong params + render map + side effects
-
-# Check the routes
-rails 'ai:tool[routes]' controller=cooks
-# → code-ready helpers (cook_path(@record)) + required params
+```
+```
+# CooksController#create
 
-# Validate after fixing
-rails 'ai:tool[validate]' files=app/controllers/cooks_controller.rb level=rails
-# → syntax + semantics + Brakeman security scan
+Filters: before_action :authenticate_user!, before_action :set_cook (only: show, edit)
+Strong params: cook_params → name, specialty, bio
+Renders: redirect_to @cook | render :new
 ```
 
+AI sees the inherited `authenticate_user!` filter, the actual strong params, and the render paths. No guessing.
+
 </details>
 
 <details>
@@ -251,7 +249,7 @@ rails 'ai:tool[stimulus]' controller=chart
 
 Every tool is **read-only** and returns data verified against your actual app — not guesses, not training data.
 
-<details>
+<details open>
 <summary><strong>Search & Trace</strong></summary>
 
 | Tool | What it does |
@@ -261,7 +259,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Understand</strong></summary>
 
 | Tool | What it does |
@@ -272,7 +270,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Schema & Models</strong></summary>
 
 | Tool | What it does |
@@ -284,7 +282,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Controllers & Routes</strong></summary>
 
 | Tool | What it does |
@@ -294,7 +292,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Views & Frontend</strong></summary>
 
 | Tool | What it does |
@@ -307,7 +305,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Testing & Quality</strong></summary>
 
 | Tool | What it does |
@@ -320,7 +318,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>App Config & Services</strong></summary>
 
 | Tool | What it does |
@@ -336,7 +334,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-<details>
+<details open>
 <summary><strong>Data & Debugging</strong></summary>
 
 | Tool | What it does |
@@ -353,7 +351,7 @@ Every tool is **read-only** and returns data verified against your actual app
 
 </details>
 
-> **[Full parameter docs →](docs/GUIDE.md)**
+> **[All 38 tools with parameters →](docs/TOOLS.md)** &nbsp;|&nbsp; **[Real-world recipes →](docs/RECIPES.md)**
 
 <br>
 
@@ -397,26 +395,21 @@ Enabled by default. Disable with `config.anti_hallucination_rules = false` if yo
 
 ## How it works
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  Your Rails App                                          │
-│  models + schema + routes + controllers + views + jobs   │
-└────────────────────────┬────────────────────────────────┘
-                         │ introspects (31 introspectors)
-                         ▼
-┌─────────────────────────────────────────────────────────┐
-│  rails-ai-context                                        │
-│  Prism AST parsing. Cached. Confidence-tagged results.    │
-│  VFS: rails-ai-context:// URIs introspected fresh.        │
-└────────┬──────────────────┬──────────────┬──────────────┘
-         │                  │              │
-         ▼                  ▼              ▼
-┌──────────────────┐ ┌────────────┐ ┌────────────────────┐
-│  Static Files     │ │  MCP Server │ │  CLI Tools          │
-│  CLAUDE.md        │ │  38 tools   │ │  Same 38 tools      │
-│  .cursor/rules/   │ │  5 templates│ │  No server needed   │
-│  .github/instr... │ │  stdio/HTTP │ │  rails 'ai:tool[X]' │
-└──────────────────┘ └────────────┘ └────────────────────┘
+```mermaid
+graph TD
+    A["Your Rails App\nmodels + schema + routes + controllers + views + jobs"] -->|"31 introspectors"| B
+
+    B["rails-ai-context\nPrism AST parsing · Cached · Confidence-tagged\nVFS: rails-ai-context:// URIs introspected fresh"]
+
+    B --> C["MCP Server\nstdio / HTTP\n38 tools · 5 templates"]
+    B --> D["CLI Tools\nRake / Thor\nSame 38 tools"]
+    B --> E["Static Files\nCLAUDE.md · .cursor/rules/\n.github/instructions/"]
+
+    style A fill:#4a9eff,stroke:#2d7ad4,color:#fff
+    style B fill:#2d2d2d,stroke:#555,color:#fff
+    style C fill:#0984e3,stroke:#0770c2,color:#fff
+    style D fill:#00cec9,stroke:#00b5b0,color:#fff
+    style E fill:#a29bfe,stroke:#8c83f0,color:#fff
 ```
 
 <br>
@@ -438,7 +431,7 @@ cd your-rails-app
 rails-ai-context init
 ```
 
-Both paths ask which AI tools you use and whether you want MCP or CLI mode. `.mcp.json` is auto-detected by Claude Code and Cursor.
+Both paths ask which AI tools you use (Claude Code, Cursor, GitHub Copilot, OpenCode, Codex CLI) and whether you want MCP or CLI mode. Each tool gets its own MCP config file — auto-detected on project open.
 
 <br>
 
@@ -455,6 +448,58 @@ Both paths ask which AI tools you use and whether you want MCP or CLI mode. `.mc
 
 <br>
 
+## Documentation
+
+| | |
+|:------|:------------|
+| **[Quickstart](docs/QUICKSTART.md)** | 5-minute getting started |
+| **[Tools Reference](docs/TOOLS.md)** | All 38 tools with every parameter |
+| **[Recipes](docs/RECIPES.md)** | Real-world workflows and examples |
+| **[Custom Tools](docs/CUSTOM_TOOLS.md)** | Build and test your own MCP tools |
+| **[Configuration](docs/CONFIGURATION.md)** | 40+ config options with defaults |
+| **[AI Tool Setup](docs/SETUP.md)** | Claude, Cursor, Copilot, OpenCode, Codex |
+| **[Architecture](docs/ARCHITECTURE.md)** | System design and internals |
+| **[Introspectors](docs/INTROSPECTORS.md)** | All 31 introspectors and AST engine |
+| **[Security](docs/SECURITY.md)** | 4-layer SQL safety and file blocking |
+| **[CLI Reference](docs/CLI.md)** | Commands and argument syntax |
+| **[Standalone](docs/STANDALONE.md)** | Use without Gemfile entry |
+| **[Troubleshooting](docs/TROUBLESHOOTING.md)** | Common issues and fixes |
+| **[FAQ](docs/FAQ.md)** | Frequently asked questions |
+
+<br>
+
+## Build your own tools
+
+Register custom MCP tools alongside the 38 built-in ones:
+
+```ruby
+# app/mcp_tools/rails_get_business_metrics.rb
+class RailsGetBusinessMetrics < MCP::Tool
+  tool_name "rails_get_business_metrics"
+  description "Key business metrics for this app"
+
+  def call(period: "week")
+    MCP::Tool::Response.new([{ type: "text", text: "Users this #{period}: #{User.recent.count}" }])
+  end
+end
+
+# config/initializers/rails_ai_context.rb
+config.custom_tools = [RailsGetBusinessMetrics]
+```
+
+Test with the built-in `TestHelper` (works with RSpec and Minitest):
+
+```ruby
+include RailsAiContext::TestHelper
+
+response = execute_tool("business_metrics", period: "month")
+assert_tool_response_includes(response, "Users")
+```
+
+> **[Custom Tools Guide →](docs/CUSTOM_TOOLS.md)**
+
+<br>
+
 ## Configuration
 
 ```ruby
@@ -468,31 +513,13 @@ if defined?(RailsAiContext)
 end
 ```
 
-<details>
-<summary><strong>All configuration options</strong></summary>
-
-<br>
-
-| Option | Default | Description |
-|:-------|:--------|:------------|
-| `preset` | `:full` | `:full` (31 introspectors) or `:standard` (17) |
-| `context_mode` | `:compact` | `:compact` (150 lines) or `:full` |
-| `generate_root_files` | `true` | Set `false` for split rules only |
-| `anti_hallucination_rules` | `true` | Embed 6-rule verification protocol in generated context files |
-| `cache_ttl` | `60` | Cache TTL in seconds |
-| `max_tool_response_chars` | `200_000` | Safety cap for tool responses |
-| `live_reload` | `:auto` | `:auto`, `true`, or `false` |
-| `custom_tools` | `[]` | Additional MCP tool classes |
-| `skip_tools` | `[]` | Built-in tools to exclude |
-| `excluded_models` | `[]` | Models to skip during introspection |
-
-</details>
+> **[All 40+ configuration options →](docs/CONFIGURATION.md)**
 
 <br>
 
 ## Observability
 
-Every MCP tool call and resource read fires an `ActiveSupport::Notifications` event. Subscribe with standard Rails patterns:
+Every MCP tool call fires an `ActiveSupport::Notifications` event:
 
 ```ruby
 ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
@@ -500,8 +527,6 @@ ActiveSupport::Notifications.subscribe("rails_ai_context.tools.call") do |event|
 end
 ```
 
-Events: `rails_ai_context.tools.call`, `rails_ai_context.resources.read`, and more. All 38 tools declare `output_schema` in the MCP protocol, so clients know the response format before calling.
-
 <br>
 
 ## Requirements
@@ -518,7 +543,7 @@ Events: `rails_ai_context.tools.call`, `rails_ai_context.resources.read`, and mo
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-1813 tests. 38 tools. 5 resource templates. 31 introspectors. Standalone or in-Gemfile.<br>
+1889 tests. 38 tools. 5 resource templates. 31 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

data/SECURITY.md

@@ -4,6 +4,12 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 5.7.x   | :white_check_mark: |
+| 5.6.x   | :white_check_mark: |
+| 5.5.x   | :white_check_mark: |
+| 5.4.x   | :white_check_mark: |
+| 5.3.x   | :white_check_mark: |
+| 5.2.x   | :white_check_mark: |
 | 5.1.x   | :white_check_mark: |
 | 5.0.x   | :white_check_mark: |
 | 4.7.x   | :white_check_mark: |

data/app/controllers/rails_ai_context/mcp_controller.rb

@@ -18,7 +18,7 @@ module RailsAiContext
       # Class-level memoization — transport persists across requests.
       # Thread-safe: MCP::Server and transport are stateless for reads.
       def mcp_transport
-        @mcp_transport || @transport_mutex.synchronize do
+        @transport_mutex.synchronize do
           @mcp_transport ||= begin
             server = RailsAiContext::Server.new(Rails.application, transport: :http).build
             MCP::Server::Transports::StreamableHTTPTransport.new(server)