rails-ai-context 4.3.3 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5568327e1027266892b2514cad27a3665532acfa1405236caecda030ff313739
-  data.tar.gz: 6be68e0d310f9a42aafc47161a676d162debba0cfe8a8f4087ee6051f79900cc
+  metadata.gz: 41d06a29e3165804283c9dcef76e2c1ee5625ef5ac236931fa492d76172062b6
+  data.tar.gz: 8f2f81c3186b2d16fa9c4ea2b84721fd519d437b4cbd8fb99a3978e45723a189
 SHA512:
-  metadata.gz: 151fec5402860aa577e1c21af3ece8c0378a3f5b50f3e18e34236a43061d01da945a869972347e07d2748601c4e7965a449596fecb04cf1eecb0915a0ef73463
-  data.tar.gz: 18f46e2c0c1d638c3822687f949588dc5f9874cb61cf3f827827205e472456c95d7c55f74cec6a157bfa99531ab4849a9e14a9c23fce7676fc554463a934d9d3
+  metadata.gz: 94ee0d646375d50942d8d3ea186a3f5faea8795f1fee1588f63304a06ab283db79e8dd07a1460284279b9edeac9bc3604e9208b847dda6ef144f9d5e68c5df2b
+  data.tar.gz: 838c87226b6027f62aa045c3eebd2842f82434db0b6a9fa2f20234bde75a9e0f4d6407fe4d510e129c0e192141b15a75fec5c9d0d3620a2991c2860db7ad5e42

data/CHANGELOG.md

@@ -5,6 +5,61 @@ 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).
 
+## [4.4.0] — 2026-04-03
+
+### Added
+- **33 introspector enhancements** — every introspector upgraded with new detection capabilities:
+  - **SchemaIntrospector**: expression indexes, column comments in static parse, `change_column_default`/`change_column_null` in migration replay
+  - **ModelIntrospector**: STI hierarchy detection (parent/children/type column), `attribute` API, enum `_prefix:`/`_suffix:`, `after_commit on:` parsing, inline `private def` exclusion
+  - **RouteIntrospector**: route parameter extraction, root route detection, RESTful action flag
+  - **JobIntrospector**: SolidQueue recurring job config, Sidekiq config (concurrency/queues), job callbacks (`before_perform`, `around_enqueue`, etc.)
+  - **GemIntrospector**: path/git gems from Gemfile, gem group extraction (dev/test/prod)
+  - **ConventionDetector**: multi-tenant (Apartment/ActsAsTenant), feature flags (Flipper/LaunchDarkly), error monitoring (Sentry/Bugsnag/Honeybadger), event-driven (Kafka/RabbitMQ/SNS), Zeitwerk detection, STI with type column verification
+  - **ControllerIntrospector**: `rate_limit` parsed into structured data (to/within/only), inline `private def` exclusion
+  - **StimulusIntrospector**: lifecycle hooks (connect/disconnect/initialize), outlet controller type mapping, action bindings from views (`data-action` parsing)
+  - **ViewIntrospector**: `yield`/`content_for` extraction from layouts, conditional layout detection with only/except
+  - **TurboIntrospector**: stream action semantics (append/update/remove counts), frame `src` URL extraction
+  - **I18nIntrospector**: locale fallback chain detection, locale coverage % per locale
+  - **ConfigIntrospector**: cache store options, error monitoring gem detection, job processor config (Sidekiq queues/concurrency)
+  - **ActiveStorageIntrospector**: attachment validations (content_type/size), variant definitions
+  - **ActionTextIntrospector**: Trix editor customization detection (toolbar/attachment/events)
+  - **AuthIntrospector**: OmniAuth provider detection, Devise settings (timeout/lockout/password_length)
+  - **ApiIntrospector**: GraphQL resolvers/subscriptions/dataloaders, API pagination strategy detection
+  - **TestIntrospector**: shared examples/contexts detection, database cleaner strategy
+  - **RakeTaskIntrospector**: task dependencies (`=> :prerequisite`), task arguments (`[:arg1, :arg2]`)
+  - **AssetPipelineIntrospector**: Bun bundler, Foundation CSS, PostCSS standalone detection
+  - **DevOpsIntrospector**: Fly.io/Render/Railway deployment detection, `docker-compose.yaml` support
+  - **ActionMailboxIntrospector**: mailbox callback detection (before/after/around_processing)
+  - **MigrationIntrospector**: `change_column_default`, `change_column_null`, `add_check_constraint` action detection
+  - **SeedsIntrospector**: CSV loader detection, seed ordering detection
+  - **MiddlewareIntrospector**: middleware added via initializers (`config.middleware.use/insert_before`)
+  - **EngineIntrospector**: route count + model count inside discovered engines
+  - **MultiDatabaseIntrospector**: shard names/keys/count from `connects_to`, improved YAML parsing for nested multi-db configs
+  - **ComponentIntrospector**: `**kwargs` splat prop detection
+  - **AccessibilityIntrospector**: heading hierarchy (h1-h6), skip link detection, `aria-live` regions, form input analysis (required/types)
+  - **PerformanceIntrospector**: polymorphic association compound index detection (`[type, id]`)
+  - **FrontendFrameworkIntrospector**: API client detection (Axios/Apollo/SWR/etc.), component library detection (MUI/Radix/shadcn/etc.)
+  - **DatabaseStatsIntrospector**: MySQL + SQLite support (was PostgreSQL-only), PostgreSQL dead row counts
+  - **ViewTemplateIntrospector**: slot reference detection
+  - **DesignTokenIntrospector**: Tailwind arbitrary value extraction
+
+### Fixed
+- **Security: SQLite SQL injection** — `database_stats_introspector` used string interpolation for table names in COUNT queries; now uses `conn.quote_table_name`
+- **Security: query column redaction bypass** — `SELECT password AS pwd` bypassed redaction; now also matches columns ending in `password`, `secret`, `token`, `key`, `digest`, `hash`
+- **Security: log redaction gaps** — added AWS access key (`AKIA...`), JWT token (`eyJ...`), and SSH/TLS private key header patterns
+- **Security: HTTP bind wildcard** — non-loopback warning now catches `0.0.0.0` and `::` (was only checking 3 specific addresses)
+- **Thread safety: `app_size()` race condition** — `SHARED_CACHE[:context]` read without mutex; now wrapped in `SHARED_CACHE[:mutex].synchronize`
+- **Crash: nil callback filter** — `model_introspector` `cb.filter.to_s` crashed on nil filters; added `cb.filter.nil?` guard
+- **Crash: fingerprinter TOCTOU** — `File.mtime` after `File.exist?` could raise `Errno::ENOENT` if file deleted between calls; added rescue
+- **Crash: tool_runner bounds** — `args[i+1]` access without bounds check; added `i + 1 < args.size` guard
+- **Bug: server logs wrong tool list** — logged all 39 `TOOLS` instead of filtered `active_tools` after `skip_tools`; now shows correct count and names
+- **Bug: STI false positive** — convention detector flagged `Admin < User` as STI even without `type` column; now verifies parent's table has `type` column via schema.rb
+- **Bug: resources bare raise** — `raise "Unknown resource"` changed to `raise RailsAiContext::Error`
+- **Config validation** — `http_port` (1-65535), `cache_ttl` (> 0), `max_tool_response_chars` (> 0), `query_row_limit` (1-1000) now validated on assignment
+
+### Changed
+- Test count: 1529 (unchanged — all new features tested via integration test against sample app)
+
 ## [4.3.3] — 2026-04-02
 
 ### Fixed
@@ -331,7 +386,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Phase 1 improvements** — scope definitions include lambda body, controller actions show instance variables + private methods called inline, Stimulus shows HTML data-attributes + reverse view lookup.
 - **3 new validation rules** — instance variable consistency (view uses @foo but controller never sets it), Turbo Stream channel matching (broadcast without subscriber), respond_to template existence.
 - **`rails_security_scan` tool** — Brakeman static security analysis via MCP. Detects SQL injection, XSS, mass assignment, and more. Optional dependency — returns install instructions if Brakeman isn't present. Supports file filtering, confidence levels (high/medium/weak), specific check selection, and three detail levels (summary/standard/full).
-- **`config.skip_tools`** — users can now exclude specific built-in tools: `config.skip_tools = %w[rails_security_scan]`. Defaults to empty (all 25 tools active).
+- **`config.skip_tools`** — users can now exclude specific built-in tools: `config.skip_tools = %w[rails_security_scan]`. Defaults to empty (all 39 tools active).
 - **Schema index hints** — `get_schema` standard detail now shows `[indexed]`/`[unique]` on columns, saving a round-trip to full detail.
 - **Enum backing types** — `get_model_details` now shows integer vs string backing: `status: pending(0), active(1) [integer]`.
 - **Search context lines default 2** — `search_code` now returns 2 lines of context by default (was 0). Eliminates follow-up calls for context.

data/CLAUDE.md

@@ -21,12 +21,12 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context/watcher.rb` — File watcher for auto-regenerating context files
 - `lib/rails_ai_context/engine.rb` — Rails Engine for auto-integration
 - `lib/generators/rails_ai_context/install/` — Install generator (creates .mcp.json, initializer, context files)
-- `exe/rails-ai-context` — Standalone Thor CLI (serve, context, inspect, watch, doctor, tool, version)
+- `exe/rails-ai-context` — Standalone Thor CLI (init, serve, context, inspect, watch, doctor, tool, version) — works without Gemfile entry via `gem install`
 
 ## Key Design Decisions
 
 1. **Built on official mcp SDK** — not a custom protocol implementation
-2. **Zero-config** — Railtie auto-registers at boot, introspects without setup
+2. **Sensible defaults** — works standalone (`gem install` + `rails-ai-context init`) or in-Gemfile with Railtie auto-registration
 3. **Graceful degradation** — works without DB by parsing schema.rb as text
 4. **Read-only tools only** — all MCP tools are annotated as non-destructive
 5. **Sensitive pattern blocking** — search/read tools reject `.env`, `*.key`, `*.pem` and other secret files via `sensitive_patterns`
@@ -56,6 +56,12 @@ structure to AI assistants via the Model Context Protocol (MCP).
 29. **Docs search** — bundled topic index with weighted keyword search, on-demand GitHub fetch
 30. **Safe SQL queries** — defense-in-depth: regex pre-filter + SET TRANSACTION READ ONLY + timeout
 31. **Log reading** — reverse file tail with level filtering and sensitive data redaction
+32. **Config validation** — `http_port`, `cache_ttl`, `max_tool_response_chars`, `query_row_limit` validated on assignment with clear error messages
+33. **Sensitive column redaction** — query tool redacts columns by name AND by suffix pattern (password, secret, token, key, digest, hash) to prevent alias bypass
+34. **Standalone mode** — `gem install rails-ai-context && rails-ai-context init` works without Gemfile entry. CLI pre-loads gem before Rails boot, restores `$LOAD_PATH` entries stripped by `Bundler.setup`. Config from `.rails-ai-context.yml`.
+35. **YAML config** — `.rails-ai-context.yml` as alternative to initializer. Supports all config options except `custom_tools` (Ruby classes) and `excluded_concerns` (regex). Precedence: initializer > YAML > defaults.
+36. **Config auto-loading** — `Configuration.auto_load!` checks `configured_via_block?` flag. If initializer ran, YAML is skipped. Corrupted YAML degrades gracefully with a warning.
+37. **Three install paths** — In-Gemfile (`rails generate rails_ai_context:install`), Standalone (`rails-ai-context init`), Zero config (just run `rails-ai-context serve` with defaults). Users can switch between paths freely; `.mcp.json` command is updated on re-init/re-install.
 
 ## Testing
 

data/README.md

@@ -51,6 +51,15 @@ gem "rails-ai-context", group: :development
 rails generate rails_ai_context:install
 ```
 
+### Or standalone — no Gemfile needed
+
+```bash
+gem install rails-ai-context
+cd your-rails-app
+rails-ai-context init     # interactive setup
+rails-ai-context serve    # start MCP server
+```
+
 <div align="center">
 
 ![Install demo](demo.gif)
@@ -341,7 +350,7 @@ Every tool is **read-only** and returns structured, token-efficient context.
                          ▼
 ┌─────────────────────────────────────────────────────────┐
 │  rails-ai-context                                        │
-│  Parses everything. Caches results. Zero config.         │
+│  Parses everything. Caches results. Sensible defaults.    │
 └────────┬──────────────────┬──────────────┬──────────────┘
          │                  │              │
          ▼                  ▼              ▼
@@ -357,27 +366,35 @@ Every tool is **read-only** and returns structured, token-efficient context.
 
 ## Install
 
+**Option A — In Gemfile:**
+
 ```bash
 gem "rails-ai-context", group: :development
 rails generate rails_ai_context:install
 ```
 
-The installer asks which AI tools you use and whether you want MCP or CLI mode. That's it.
+**Option B — Standalone (no Gemfile entry needed):**
+
+```bash
+gem install rails-ai-context
+cd your-rails-app
+rails-ai-context init
+```
 
-`.mcp.json` is auto-detected by Claude Code and Cursor — no manual config.
+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.
 
 <br>
 
 ## Commands
 
-| Command | What it does |
-|:--------|:------------|
-| `rails ai:context` | Generate context files for your AI tools |
-| `rails 'ai:tool[NAME]'` | Run any of the 39 tools from CLI |
-| `rails ai:tool` | List all available tools |
-| `rails ai:serve` | Start MCP server (stdio) |
-| `rails ai:doctor` | Diagnostics + AI readiness score |
-| `rails ai:watch` | Auto-regenerate on file changes |
+| In-Gemfile | Standalone | What it does |
+|:-----------|:-----------|:------------|
+| `rails ai:context` | `rails-ai-context context` | Generate context files |
+| `rails 'ai:tool[NAME]'` | `rails-ai-context tool NAME` | Run any of the 39 tools |
+| `rails ai:tool` | `rails-ai-context tool --list` | List all available tools |
+| `rails ai:serve` | `rails-ai-context serve` | Start MCP server (stdio) |
+| `rails ai:doctor` | `rails-ai-context doctor` | Diagnostics + AI readiness score |
+| `rails ai:watch` | `rails-ai-context watch` | Auto-regenerate on file changes |
 
 <br>
 
@@ -427,7 +444,7 @@ end
 ## About
 
 Built by a Rails developer with 10+ years of production experience.<br>
-1529 tests. 39 tools. 33 introspectors. Zero config.<br>
+1529 tests. 39 tools. 33 introspectors. Standalone or in-Gemfile.<br>
 MIT licensed. [Contributions welcome.](CONTRIBUTING.md)
 
 <br>

data/docs/GUIDE.md

@@ -29,35 +29,35 @@
 
 ## Installation
 
-### New project
+### Option A: In Gemfile
 
 ```bash
-bundle add rails-ai-context
+gem "rails-ai-context", group: :development
+bundle install
 rails generate rails_ai_context:install
 rails ai:context
 ```
 
 This creates:
 1. `config/initializers/rails_ai_context.rb` — configuration file
-2. `.mcp.json` — MCP auto-discovery for Claude Code and Cursor
-3. 29 context files — tailored for each AI assistant
+2. `.rails-ai-context.yml` — standalone config (enables switching later)
+3. `.mcp.json` — MCP auto-discovery for Claude Code and Cursor
+4. Context files — tailored for each AI assistant
 
-### Existing project
+### Option B: Standalone (no Gemfile entry needed)
 
 ```bash
-# Add to Gemfile
-gem "rails-ai-context"
-
-# Install
-bundle install
-rails generate rails_ai_context:install
+gem install rails-ai-context
+cd your-rails-app
+rails-ai-context init
+```
 
-# Generate context files
-rails ai:context
+This creates:
+1. `.rails-ai-context.yml` — configuration file
+2. `.mcp.json` — MCP auto-discovery (if MCP mode selected)
+3. Context files — tailored for each AI assistant
 
-# Verify everything works
-rails ai:doctor
-```
+No Gemfile entry, no initializer, no files in your project besides config and context.
 
 ### What the install generator does
 
@@ -220,9 +220,10 @@ Commit **all files except `.ai-context.json`** (which is gitignored). This gives
 
 ### Standalone CLI
 
-The gem ships a `rails-ai-context` executable as an alternative to rake tasks. Useful for `.mcp.json` configs or when you prefer a shorter command.
+The gem ships a `rails-ai-context` executable that works **without adding the gem to your Gemfile**. Install globally with `gem install rails-ai-context`, then run from any Rails app directory.
 
 ```bash
+rails-ai-context init                      # Interactive setup (creates .rails-ai-context.yml + .mcp.json)
 rails-ai-context serve                     # Start MCP server (stdio)
 rails-ai-context serve --transport http    # Start MCP server (HTTP, port 6029)
 rails-ai-context serve --transport http --port 8080  # Custom port
@@ -241,6 +242,8 @@ rails-ai-context help                      # Show all commands
 
 Must be run from your Rails app root directory (requires `config/environment.rb`).
 
+**Config:** Standalone mode reads from `.rails-ai-context.yml` (created by `init`). If no config file exists, defaults are used. If the gem is also in the Gemfile, the initializer takes precedence over the YAML file.
+
 ### Legacy command
 
 ```bash
@@ -1042,8 +1045,9 @@ curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=rails-ai-cont
 
 ### Auto-discovery (recommended)
 
-The install generator creates `.mcp.json` in your project root:
+The install generator (or `rails-ai-context init`) creates `.mcp.json` in your project root:
 
+**In-Gemfile:**
 ```json
 {
   "mcpServers": {
@@ -1055,6 +1059,18 @@ The install generator creates `.mcp.json` in your project root:
 }
 ```
 
+**Standalone:**
+```json
+{
+  "mcpServers": {
+    "rails-ai-context": {
+      "command": "rails-ai-context",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
 **Claude Code** and **Cursor** auto-detect this file. No manual config needed — just open your project.
 
 ### Claude Code
@@ -1062,7 +1078,11 @@ The install generator creates `.mcp.json` in your project root:
 Auto-discovered via `.mcp.json`. Or add manually:
 
 ```bash
+# In-Gemfile
 claude mcp add rails-ai-context -- bundle exec rails ai:serve
+
+# Standalone
+claude mcp add rails-ai-context -- rails-ai-context serve
 ```
 
 ### Claude Desktop
@@ -1081,6 +1101,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 }
 ```
 
+Or for standalone: replace `"command": "bundle"` / `"args": ["exec", "rails", "ai:serve"]` with `"command": "rails-ai-context"` / `"args": ["serve"]`.
+
 ### Cursor
 
 Auto-discovered via `.mcp.json`. Or add manually in **Cursor Settings > MCP**:
@@ -1097,6 +1119,9 @@ Auto-discovered via `.mcp.json`. Or add manually in **Cursor Settings > MCP**:
 }
 ```
 
+For standalone: use `"command": "rails-ai-context"` / `"args": ["serve"]` instead.
+```
+
 ### HTTP transport
 
 For browser-based or remote AI clients:
@@ -1407,6 +1432,19 @@ config.introspectors = %i[schema models routes gems auth api]
 }
 ```
 
+For standalone: use `"command": ["rails-ai-context", "serve"]` instead.
+
+```json
+{
+  "mcp": {
+    "rails-ai-context": {
+      "type": "local",
+      "command": ["rails-ai-context", "serve"]
+    }
+  }
+}
+```
+
 **Context files loaded:**
 - `AGENTS.md` — project overview + MCP tool guide, read at conversation start
 - `app/models/AGENTS.md` — model listing, auto-loaded when agent reads model files