rails-ai-bridge 5.2.1 → 5.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.reek.yml +4 -19
- data/Archspec.rb +0 -1
- data/CHANGELOG.md +125 -0
- data/CONTRIBUTING.md +5 -5
- data/README.md +28 -22
- data/SECURITY.md +3 -0
- data/UPGRADING.md +46 -0
- data/docs/BEST_PRACTICES.md +7 -10
- data/docs/EXAMPLES.md +3 -6
- data/docs/GUIDE.md +107 -24
- data/docs/ROADMAP.md +3 -3
- data/docs/design/prism-confidence-tags.md +40 -21
- data/docs/devin-setup.md +5 -8
- data/docs/mcp-security.md +23 -3
- data/docs/ruby-version-support.md +58 -0
- data/lib/generators/rails_ai_bridge/install/command_help.rb +3 -3
- data/lib/generators/rails_ai_bridge/install/install_generator.rb +2 -2
- data/lib/rails_ai_bridge/config/output.rb +6 -0
- data/lib/rails_ai_bridge/config/static_analysis.rb +28 -0
- data/lib/rails_ai_bridge/configuration.rb +12 -0
- data/lib/rails_ai_bridge/instrumentation.rb +7 -2
- data/lib/rails_ai_bridge/introspectors/config_introspector.rb +21 -5
- data/lib/rails_ai_bridge/introspectors/controller_introspector/filter_extractor.rb +8 -1
- data/lib/rails_ai_bridge/introspectors/controller_introspector/strong_params_provenance.rb +41 -0
- data/lib/rails_ai_bridge/introspectors/controller_introspector.rb +26 -2
- data/lib/rails_ai_bridge/introspectors/static_prism_scanner.rb +134 -0
- data/lib/rails_ai_bridge/introspectors/timezone_introspector.rb +44 -0
- data/lib/rails_ai_bridge/introspectors/view_introspector.rb +14 -2
- data/lib/rails_ai_bridge/mcp/cache_rate_limiter.rb +3 -2
- data/lib/rails_ai_bridge/mcp/http_rate_limiter.rb +24 -9
- data/lib/rails_ai_bridge/resources.rb +22 -0
- data/lib/rails_ai_bridge/rubydex_adapter/incremental_indexer.rb +6 -2
- data/lib/rails_ai_bridge/serializers/README.md +0 -1
- data/lib/rails_ai_bridge/serializers/context_file_serializer.rb +6 -0
- data/lib/rails_ai_bridge/serializers/legacy_agent_files.rb +60 -0
- data/lib/rails_ai_bridge/serializers/providers/codex_serializer.rb +0 -1
- data/lib/rails_ai_bridge/tasks/rails_ai_bridge.rake +5 -5
- data/lib/rails_ai_bridge/tool_result_cache.rb +24 -4
- data/lib/rails_ai_bridge/tools/confidence_tag.rb +16 -0
- data/lib/rails_ai_bridge/tools/get_controllers.rb +25 -2
- data/lib/rails_ai_bridge/tools/get_view/full_formatter.rb +44 -13
- data/lib/rails_ai_bridge/tools/provenance_lines.rb +33 -0
- data/lib/rails_ai_bridge/tools/query/payload_formatter.rb +9 -9
- data/lib/rails_ai_bridge/tools/query.rb +25 -10
- data/lib/rails_ai_bridge/tools/search_code/ruby_search.rb +1 -1
- data/lib/rails_ai_bridge/tools/search_code/validator.rb +20 -1
- data/lib/rails_ai_bridge/version.rb +1 -1
- data/lib/rails_ai_bridge.rb +1 -1
- data/server.json +1 -1
- metadata +8 -7
- data/.reviewer.toml +0 -13
- data/.rs-guardignore +0 -26
- data/lib/rails_ai_bridge/services/app_introspection_service.rb +0 -72
- data/lib/rails_ai_bridge/services/configuration_service.rb +0 -59
- data/lib/rails_ai_bridge/services/context_generation_service.rb +0 -71
- data/lib/rails_ai_bridge/services/file_management_service.rb +0 -174
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 0f4066d47a05fac81d54e926520b483bc043b73f29fb7a2ec118caf133e01559
|
|
4
|
+
data.tar.gz: 9bf88dda78fba7d798008dae187d89f34724ceb64b18e962f27eea0d7cfd3b74
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 36183d3adfadb44f8752bfdf75b499128f98796c4c726c5b615dd49300cac3c4c109b76066810f319712dab6130dc9dd5a06f2405511559d12f3256b09a08a33
|
|
7
|
+
data.tar.gz: 27f36fe2f926077a470f3e49631d3e0eac13bd77e0c788a9a828641f9314255af80a1fe104c02b78eb2e2dbfca1314233daf2173a046a7b52682aecc9fa1e755
|
data/.reek.yml
CHANGED
|
@@ -49,6 +49,7 @@ detectors:
|
|
|
49
49
|
- RailsAiBridge::Config::Output#codex_compact_model_list_limit
|
|
50
50
|
- RailsAiBridge::Config::Output#context_mode
|
|
51
51
|
- RailsAiBridge::Config::Output#copilot_compact_model_list_limit
|
|
52
|
+
- RailsAiBridge::Config::Output#legacy_agent_files
|
|
52
53
|
- RailsAiBridge::Config::Output#managed_region
|
|
53
54
|
- RailsAiBridge::Config::Output#max_tool_response_chars
|
|
54
55
|
- RailsAiBridge::Config::Output#output_dir
|
|
@@ -74,6 +75,9 @@ detectors:
|
|
|
74
75
|
- RailsAiBridge::Config::Server#http_port
|
|
75
76
|
- RailsAiBridge::Config::Server#server_name
|
|
76
77
|
- RailsAiBridge::Config::Server#server_version
|
|
78
|
+
- RailsAiBridge::Config::StaticAnalysis#confidence_tags_enabled
|
|
79
|
+
- RailsAiBridge::Config::StaticAnalysis#prism_enabled
|
|
80
|
+
- RailsAiBridge::Config::StaticAnalysis#prism_max_files
|
|
77
81
|
- RailsAiBridge::Fingerprinter::CachedSnapshot#snapshot_ttl
|
|
78
82
|
- RailsAiBridge::Tools::ExplainSymbol#explorer
|
|
79
83
|
- RailsAiBridge#configuration
|
|
@@ -86,7 +90,6 @@ detectors:
|
|
|
86
90
|
- RailsAiBridge::Serializers::ContextFileSerializer#initialize
|
|
87
91
|
- RailsAiBridge::Serializers::SharedAssistantGuidance#compact_engineering_rules_footer_lines
|
|
88
92
|
- RailsAiBridge::Serializers::SharedAssistantGuidance#cursor_engineering_mdc_body_lines
|
|
89
|
-
- RailsAiBridge::Services::FileManagementService#validate_path!
|
|
90
93
|
ControlParameter:
|
|
91
94
|
exclude:
|
|
92
95
|
- RailsAiBridge::Registry::ContextProviderClient#probe
|
|
@@ -112,7 +115,6 @@ detectors:
|
|
|
112
115
|
- RailsAiBridge::Serializers::SharedAssistantGuidance#compact_engineering_rules_footer_lines
|
|
113
116
|
- RailsAiBridge::Serializers::SharedAssistantGuidance#cursor_engineering_mdc_body_lines
|
|
114
117
|
- RailsAiBridge::Service::Result#initialize
|
|
115
|
-
- RailsAiBridge::Services::FileManagementService#validate_path!
|
|
116
118
|
- RailsAiBridge::Tools::GetContext::Resolver#nothing_resolved_error
|
|
117
119
|
- RailsAiBridge::Tools::GetView#self.build_formatter
|
|
118
120
|
- RailsAiBridge::Tools::ResolveSkill#self.not_found_message
|
|
@@ -263,8 +265,6 @@ detectors:
|
|
|
263
265
|
- RailsAiBridge::Serializers::Providers::DevinSerializer#render
|
|
264
266
|
- RailsAiBridge::Serializers::SharedAssistantGuidance#resolved_assistant_overrides_path
|
|
265
267
|
- RailsAiBridge::Server#run_rack_server
|
|
266
|
-
- RailsAiBridge::Services::ContextGenerationService#call
|
|
267
|
-
- RailsAiBridge::Services::FileManagementService#default_allowed_base_dir
|
|
268
268
|
- RailsAiBridge::ToolResultCache#fetch_response
|
|
269
269
|
- RailsAiBridge::ToolResultCache::CachedTool#detect_server_context_param
|
|
270
270
|
- RailsAiBridge::Tools::BaseTool#text_response
|
|
@@ -429,8 +429,6 @@ detectors:
|
|
|
429
429
|
- RailsAiBridge::Serializers::Providers::DevinSerializer#render
|
|
430
430
|
- RailsAiBridge::Server#create_mcp_server
|
|
431
431
|
- RailsAiBridge::Server#run_rack_server
|
|
432
|
-
- RailsAiBridge::Services::AppIntrospectionService#call
|
|
433
|
-
- RailsAiBridge::Services::FileManagementService#file_exists?
|
|
434
432
|
- RailsAiBridge::Tools::GetContext::Composer#append_controller
|
|
435
433
|
- RailsAiBridge::Tools::GetContext::Composer#append_model
|
|
436
434
|
- RailsAiBridge::Tools::GetContext::Composer#append_routes
|
|
@@ -559,7 +557,6 @@ detectors:
|
|
|
559
557
|
- RailsAiBridge::RubydexAdapter#constant_references
|
|
560
558
|
- RailsAiBridge::RubydexAdapter#descendants
|
|
561
559
|
- RailsAiBridge::RubydexAdapter#safe_count
|
|
562
|
-
- RailsAiBridge::Services::FileManagementService#default_allowed_base_dir
|
|
563
560
|
MissingSafeMethod:
|
|
564
561
|
exclude:
|
|
565
562
|
- RailsAiBridge::AssistantFormatsPreference
|
|
@@ -574,7 +571,6 @@ detectors:
|
|
|
574
571
|
- RailsAiBridge::Registry::ResolverCache
|
|
575
572
|
- RailsAiBridge::Registry::DefaultGitRunner
|
|
576
573
|
- RailsAiBridge::RubydexAdapter
|
|
577
|
-
- RailsAiBridge::Services::FileManagementService
|
|
578
574
|
- RailsAiBridge::ToolResultCache
|
|
579
575
|
- RailsAiBridge::Tools::BaseTool
|
|
580
576
|
- RailsAiBridge::Tools::ExplainSymbol
|
|
@@ -659,7 +655,6 @@ detectors:
|
|
|
659
655
|
- RailsAiBridge::Serializers::Providers::ClaudeRulesSerializer#append_tier_model_bullets
|
|
660
656
|
- RailsAiBridge::Serializers::SharedAssistantGuidance#mergeable_override_content?
|
|
661
657
|
- RailsAiBridge::Serializers::SharedAssistantGuidance#resolved_assistant_overrides_path
|
|
662
|
-
- RailsAiBridge::Services::FileManagementService#call
|
|
663
658
|
- RailsAiBridge::Tools::ConfidenceTag#tag
|
|
664
659
|
- RailsAiBridge::Tools::GetContext::Composer#append_controller
|
|
665
660
|
- RailsAiBridge::Tools::GetContext::Composer#append_model
|
|
@@ -970,13 +965,6 @@ detectors:
|
|
|
970
965
|
- RailsAiBridge::Serializers::SharedAssistantGuidance#read_assistant_overrides
|
|
971
966
|
- RailsAiBridge::Serializers::SharedAssistantGuidance#resolved_assistant_overrides_path
|
|
972
967
|
- RailsAiBridge::Server#start_http
|
|
973
|
-
- RailsAiBridge::Services::AppIntrospectionService#call
|
|
974
|
-
- RailsAiBridge::Services::ConfigurationService#call
|
|
975
|
-
- RailsAiBridge::Services::ContextGenerationService#call
|
|
976
|
-
- RailsAiBridge::Services::FileManagementService#call
|
|
977
|
-
- RailsAiBridge::Services::FileManagementService#file_exists?
|
|
978
|
-
- RailsAiBridge::Services::FileManagementService#validate_path!
|
|
979
|
-
- RailsAiBridge::Services::FileManagementService#write_file
|
|
980
968
|
- RailsAiBridge::ToolResultCache#fetch_response
|
|
981
969
|
- RailsAiBridge::ToolResultCache::CachedTool#detect_server_context_param
|
|
982
970
|
- RailsAiBridge::Tools::BaseTool#text_response
|
|
@@ -1317,9 +1305,6 @@ detectors:
|
|
|
1317
1305
|
- RailsAiBridge::Server#register_resources
|
|
1318
1306
|
- RailsAiBridge::Server#tool_classes
|
|
1319
1307
|
- RailsAiBridge::Server#validate_http_server_in_production
|
|
1320
|
-
- RailsAiBridge::Services::ConfigurationService#call
|
|
1321
|
-
- RailsAiBridge::Services::FileManagementService#default_allowed_base_dir
|
|
1322
|
-
- RailsAiBridge::Services::FileManagementService#root_directory?
|
|
1323
1308
|
- RailsAiBridge::ToolResultCache::CachedTool#detect_server_context_param
|
|
1324
1309
|
- RailsAiBridge::Tools::ExplainSymbol::CliExplorer#failure_detail
|
|
1325
1310
|
- RailsAiBridge::Tools::GetContext::RelatedTests#contained?
|
data/Archspec.rb
CHANGED
data/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,131 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [5.4.0] - 2026-10-23
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- `rails_ai_bridge.tool.call` notifications now include `success` and
|
|
15
|
+
`error_class`, while preserving the existing duration, tool name, and
|
|
16
|
+
arguments payload (#339).
|
|
17
|
+
- Ruby version support policy in `docs/ruby-version-support.md` (ticket #341).
|
|
18
|
+
- README Requirements and Ruby policy distinguish blocking Ruby 3.2–3.4 coverage
|
|
19
|
+
from the existing non-blocking Ruby 4.0 / Rails 8.1 canary. The historical Ruby
|
|
20
|
+
3.5 preview is excluded from the matrix.
|
|
21
|
+
- `RailsAiBridge::Introspectors::TimezoneIntrospector` adds runtime confirmation
|
|
22
|
+
metadata to the existing config section (part of #342). `timezone_confirmed`
|
|
23
|
+
compares the IANA identifiers of `config.time_zone` and the current thread's
|
|
24
|
+
`Time.zone`, supporting both Rails names and IANA identifiers. It is false
|
|
25
|
+
when the runtime zone is unavailable or different. Static config introspection
|
|
26
|
+
remains unavailable; tool and serializer rendering is unchanged.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
|
|
30
|
+
- `rails_query` enforces its row limit in SQL and fetches one sentinel row
|
|
31
|
+
before ActiveRecord materializes results. Summary responses now report the
|
|
32
|
+
same bounded `row_count` and `truncated` semantics as other detail levels
|
|
33
|
+
(#350).
|
|
34
|
+
|
|
35
|
+
### Fixed
|
|
36
|
+
|
|
37
|
+
- Disable the review CLI's background auto-updater in CI so the pinned executable
|
|
38
|
+
cannot be replaced during an automated review.
|
|
39
|
+
- Bound the in-process tool response cache to 1,000 entries and the HTTP rate
|
|
40
|
+
limiter to 10,000 active client buckets. Expired entries are reclaimed
|
|
41
|
+
incrementally, and new clients fail closed when the limiter is full (#349).
|
|
42
|
+
|
|
43
|
+
### Security
|
|
44
|
+
|
|
45
|
+
- Code search now skips symlinked files, rejects directory aliases into excluded
|
|
46
|
+
paths, and streams Ruby fallback reads up to the requested result cap (#347).
|
|
47
|
+
- Tool response cache keys now include the active Rails application, preventing
|
|
48
|
+
identical requests from reusing another application scope's response (#348).
|
|
49
|
+
- Refresh locked dependencies to include `crass` 1.0.8, which fixes
|
|
50
|
+
GHSA-pq4g-8rxf-4g29 in the CSS sanitizer dependency chain (#343).
|
|
51
|
+
|
|
52
|
+
### Maintenance
|
|
53
|
+
|
|
54
|
+
- Refresh the mutation and demo-app lockfiles, including MCP 1.8.1, Rubydex
|
|
55
|
+
0.4.2, Rails 8.1.4, SQLite 2.10.1, Faraday 2.15.0, Mutant 0.17.1,
|
|
56
|
+
RuboCop 1.92.1, and compatible transitive updates (#343). Skunk remains on
|
|
57
|
+
0.5.4 because its 0.6 line conflicts with RubyCritic's `path_expander`
|
|
58
|
+
requirement; Reek remains on 6.5.x as required by RubyCritic 4.12.
|
|
59
|
+
|
|
60
|
+
### Deprecated
|
|
61
|
+
|
|
62
|
+
- `.cursorrules`, `.devinrules`, and `.codex/README.md` are no longer written by default. Cursor reads
|
|
63
|
+
`.cursor/rules/` and `AGENTS.md`, Devin does not read `.devinrules`, and Codex reads only `AGENTS.md`.
|
|
64
|
+
`.cursor/rules/`, `.devin/rules/`, and `AGENTS.md` are unchanged. Set
|
|
65
|
+
`config.output.legacy_agent_files = true` to keep writing the three files; the first run prints a
|
|
66
|
+
deprecation notice. The option and the files are removed in 6.0. Existing copies are never deleted.
|
|
67
|
+
|
|
68
|
+
## [5.3.0] - 2026-10-08
|
|
69
|
+
|
|
70
|
+
Confidence tags now reach controllers and the full view listing, and an opt-in Prism pass can upgrade
|
|
71
|
+
controller strong params from `[INFERRED]` to `[VERIFIED]`. This release also removes the unused
|
|
72
|
+
`Services` layer, makes `config.mcp.rate_limiter_key_prefix` take effect, and refreshes dependencies.
|
|
73
|
+
Tool output changes by default because `confidence_tags_enabled` is on; see [UPGRADING.md](UPGRADING.md).
|
|
74
|
+
|
|
75
|
+
### Added
|
|
76
|
+
|
|
77
|
+
- `RailsAiBridge::Tools::ConfidenceTag.footer` builds a one-line verification summary, such as
|
|
78
|
+
`Verification: [VERIFIED] reflection (3) · [INFERRED] regex (2)`, from a per-source count hash.
|
|
79
|
+
Sources with a zero count are left out, and the result is `nil` when none remain.
|
|
80
|
+
- `RailsAiBridge::Introspectors::StaticPrismScanner` finds controller filter macros
|
|
81
|
+
(`before_action` and its variants) with the optional Prism parser and tags each fact
|
|
82
|
+
`provenance: :prism`. It returns an error hash, and never raises, when Prism is unavailable.
|
|
83
|
+
The controller introspector uses it for strong params when `prism_enabled` is on.
|
|
84
|
+
- `Config::StaticAnalysis` adds `confidence_tags_enabled` (default `true`), `prism_enabled` (default `false`), and `prism_max_files` (default `500`). `prism_enabled` turns on the Prism pass for controller strong params.
|
|
85
|
+
- With `prism_enabled` on, strong params that Prism finds as methods in the controller source are tagged `[VERIFIED]` (source `prism`). Otherwise they stay `[INFERRED]`.
|
|
86
|
+
|
|
87
|
+
### Removed
|
|
88
|
+
|
|
89
|
+
- Removed the unused `Services` layer (`AppIntrospectionService`, `ConfigurationService`,
|
|
90
|
+
`ContextGenerationService`, `FileManagementService`). Nothing in the gem used them; they
|
|
91
|
+
were only exercised by their own specs. `RailsAiBridge::Service` and `Service::Result` remain.
|
|
92
|
+
|
|
93
|
+
### Changed
|
|
94
|
+
|
|
95
|
+
- `RailsAiBridge::RubydexAdapter::IncrementalIndexer` raises `ServiceErrors::ValidationError` for an
|
|
96
|
+
unsupported operation and rescues `ServiceErrors::BaseError` into a failure result with
|
|
97
|
+
the same message. The returned result shape is unchanged. Errors that descend from
|
|
98
|
+
`ServiceErrors::BaseError` skip the generic `StandardError` logging path.
|
|
99
|
+
- The controller tool (`rails_get_controllers`) shows confidence tags when `confidence_tags_enabled`
|
|
100
|
+
is on, which is the default. Filters come from Rails reflection. The footer counts them as
|
|
101
|
+
`[VERIFIED]`, except a filter whose `only:` or `except:` came from a string condition, which
|
|
102
|
+
counts as `[INFERRED]`. Filter lines get no per-line tag. Strong params are regex-derived unless Prism confirms them, so they get an
|
|
103
|
+
`[INFERRED]` tag, and are counted as `[INFERRED]` in the footer. Set
|
|
104
|
+
`confidence_tags_enabled` to `false` for the previous output. Controller introspection facts gain
|
|
105
|
+
additive `provenance` keys. Respond_to formats carry provenance in the payload only, because the
|
|
106
|
+
tool does not render them yet.
|
|
107
|
+
- The controller section of `rails_get_context` at `detail: full` shows the same tags and footer as the controller tool. That section is unchanged at summary and standard detail.
|
|
108
|
+
- The full view of `rails_get_view` shows confidence tags when `confidence_tags_enabled` is
|
|
109
|
+
on. Helper methods are regex-derived, so they get an `[INFERRED]` tag. A verification footer
|
|
110
|
+
counts the facts the full view renders. Summary and standard output are unchanged. The setting
|
|
111
|
+
is on by default, so existing full-view output changes. Set `config.confidence_tags_enabled = false`
|
|
112
|
+
to keep the previous output.
|
|
113
|
+
|
|
114
|
+
### Fixed
|
|
115
|
+
|
|
116
|
+
- `config.mcp.rate_limiter_key_prefix` now applies to `Mcp::CacheRateLimiter` when `key_prefix:`
|
|
117
|
+
is omitted. The option was previously set but never read. An explicit `key_prefix:` still wins.
|
|
118
|
+
- The README no longer says `rails_get_model_details` verifies facts with `rubydex`. Association facts are verified by reflection, and no tool emits `rubydex` yet. No `rails_get_model_details` output changed.
|
|
119
|
+
|
|
120
|
+
### Maintenance
|
|
121
|
+
|
|
122
|
+
- Refreshed the mutation testing lockfile (`Gemfile-mutation.lock`): `mcp` 1.6.0 → 1.7.0 and
|
|
123
|
+
`railties` 8.1.3.1 → 8.1.4, with the matching Rails gems. Runtime dependency requirements
|
|
124
|
+
are unchanged.
|
|
125
|
+
- Bumped the `simplecov` development dependency from 1.2.0 to 1.3.2 on Ruby 3.3 and newer.
|
|
126
|
+
The lockfile pins 1.3.2, and the Gemfile allows the 1.3.x line. Ruby 3.2 stays on 1.2.0,
|
|
127
|
+
because simplecov 1.3 requires Ruby 3.3. `reek` and `rubycritic` stay on their current versions.
|
|
128
|
+
- Refreshed nine transitive development gems in `Gemfile-mutation.lock` (`date`, `net-http`,
|
|
129
|
+
`net-smtp`, `parallel`, `prettyprint`, `rdoc`, `regexp_parser`, `sorbet-runtime`, `uri`).
|
|
130
|
+
Their versions are newer; no gem moved down. `reek` and `rubycritic` stay on their current
|
|
131
|
+
versions, because `rubycritic` 4.12.0 requires `reek ~> 6.5.0`.
|
|
132
|
+
|
|
8
133
|
## [5.2.1] - 2026-09-23
|
|
9
134
|
|
|
10
135
|
### Changed
|
data/CONTRIBUTING.md
CHANGED
|
@@ -73,9 +73,9 @@ bundle exec rubocop --parallel # Lint check
|
|
|
73
73
|
4. Update CHANGELOG.md under an `## [Unreleased]` section
|
|
74
74
|
5. Open a PR with a clear title and description
|
|
75
75
|
|
|
76
|
-
The
|
|
77
|
-
receive `
|
|
78
|
-
|
|
76
|
+
The ocr review workflow skips `dependabot[bot]` PRs and PRs from forks. Those PRs
|
|
77
|
+
do not receive `OPENAI_API_KEY`, so the review would fail. They are reviewed by
|
|
78
|
+
CI (RSpec, RuboCop, bundle-audit) only, and a maintainer reviews them by hand.
|
|
79
79
|
|
|
80
80
|
## Reporting Bugs
|
|
81
81
|
|
|
@@ -90,11 +90,11 @@ Open an issue at https://github.com/igmarin/rails-ai-bridge/issues with:
|
|
|
90
90
|
Pre-flight checklist:
|
|
91
91
|
|
|
92
92
|
1. **Name availability** — Confirm `rails-ai-bridge` is available (or owned by you) on [RubyGems](https://rubygems.org/gems/rails-ai-bridge).
|
|
93
|
-
2. **Version** — `lib/rails_ai_bridge/version.rb` must match the Git tag (release workflow expects `v#{VERSION}`).
|
|
93
|
+
2. **Version** — Bump `lib/rails_ai_bridge/version.rb`, `server.json`, and the `rails-ai-bridge (x.y.z)` lines in `Gemfile-mutation.lock` and `examples/demo_app/Gemfile.lock` together. The version must match the Git tag (the release workflow expects `v#{VERSION}`); `spec/lib/rails_ai_bridge/release_consistency_spec.rb` guards `server.json`, the CHANGELOG heading, and the lockfiles.
|
|
94
94
|
3. **Changelog** — Add a `## [x.y.z]` section in `CHANGELOG.md` (release notes are extracted from it in CI).
|
|
95
95
|
4. **Build locally** — `gem build rails-ai-bridge.gemspec` and smoke-test in a dummy Rails app (`rails generate rails_ai_bridge:install`, `rails ai:bridge`, `rails ai:serve`).
|
|
96
96
|
5. **MFA** — RubyGems account must have MFA; `spec.metadata["rubygems_mfa_required"]` is already `"true"`.
|
|
97
|
-
6. **Trusted publishing** — Prefer [OIDC trusted publishing](https://guides.rubygems.org/trusted-publishing/) with the
|
|
97
|
+
6. **Trusted publishing** — Prefer [OIDC trusted publishing](https://guides.rubygems.org/trusted-publishing/) through `.github/workflows/release.yml`, which runs on a `v*` tag and configures OIDC itself with the `RUBYGEMS_OIDC_ROLE` repository variable (`rubygems/release-gem@v1` does not work here). Configure the gem owner on RubyGems to trust this repository/workflow.
|
|
98
98
|
7. **Secrets** — Avoid API keys in the repo; rely on trusted publishing or short-lived CI secrets.
|
|
99
99
|
8. **MCP registry** — If you publish `server.json` to the MCP registry, coordinate the `name` field (`io.github.igmarin/rails-ai-bridge`) with registry requirements.
|
|
100
100
|
9. **Post-release** — Verify `bundle add rails-ai-bridge` from RubyGems and that badges in the README resolve.
|
data/README.md
CHANGED
|
@@ -41,7 +41,7 @@ Use the README as the shortest path to understanding and setup. Jump to deeper d
|
|
|
41
41
|
| Check what the AI learns | [What Your AI Learns](#what-your-ai-learns) |
|
|
42
42
|
| Choose `:standard`, `:full`, or opt-ins | [Pick the right preset for your app](#pick-the-right-preset-for-your-app) |
|
|
43
43
|
| Use MCP safely | [HTTP transport](#http-transport-alternative-for-all-clients) and [mcp-security.md](docs/mcp-security.md) |
|
|
44
|
-
| Upgrade from
|
|
44
|
+
| Upgrade from an earlier version | [UPGRADING.md](UPGRADING.md) |
|
|
45
45
|
| Improve day-to-day AI results | [Best Practices](docs/BEST_PRACTICES.md) |
|
|
46
46
|
|
|
47
47
|
## When this helps
|
|
@@ -76,7 +76,7 @@ flowchart LR
|
|
|
76
76
|
|
|
77
77
|
1. **Introspect**: built-in scanners read your Rails app structure: schema, models, routes, controllers, gems, tests, conventions, and optional full-stack details.
|
|
78
78
|
2. **Generate**: `rails ai:bridge` writes compact, assistant-specific files such as `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, and Copilot instructions.
|
|
79
|
-
3. **Serve**: `rails ai:serve` exposes 22 read-only `rails_*` tools so an assistant can drill into exact details on demand.
|
|
79
|
+
3. **Serve**: `rails ai:serve` exposes 22 read-only `rails_*` tools (20 registered by default; `enable_data_tools` adds the other 2) so an assistant can drill into exact details on demand.
|
|
80
80
|
|
|
81
81
|
This creates two complementary layers:
|
|
82
82
|
|
|
@@ -112,7 +112,7 @@ RailsAiBridge.configure do |c|
|
|
|
112
112
|
end
|
|
113
113
|
```
|
|
114
114
|
|
|
115
|
-
|
|
115
|
+
3. Only remote tools advertising `read_only_hint: true` and `destructive_hint: false` are callable; reflected credentials in provider responses are redacted before they reach MCP clients.
|
|
116
116
|
|
|
117
117
|
See [docs/v5/context-providers-design.md](docs/v5/context-providers-design.md) for the design and security model, and [docs/mcp-security.md](docs/mcp-security.md) for SSRF controls and operator checklists.
|
|
118
118
|
|
|
@@ -206,12 +206,9 @@ your-rails-app/
|
|
|
206
206
|
│ └── rails-mcp-tools.md full tool reference
|
|
207
207
|
│
|
|
208
208
|
├── 🟡 OpenAI Codex
|
|
209
|
-
│
|
|
210
|
-
│ └── .codex/
|
|
211
|
-
│ └── README.md local Codex setup notes
|
|
209
|
+
│ └── AGENTS.md project instructions for Codex
|
|
212
210
|
│
|
|
213
211
|
├── 🟢 Cursor
|
|
214
|
-
│ ├── .cursorrules legacy compat
|
|
215
212
|
│ └── .cursor/rules/
|
|
216
213
|
│ ├── rails-engineering.mdc alwaysApply: true (rules first)
|
|
217
214
|
│ ├── rails-project.mdc alwaysApply: true
|
|
@@ -220,7 +217,6 @@ your-rails-app/
|
|
|
220
217
|
│ └── rails-mcp-tools.mdc alwaysApply: true
|
|
221
218
|
│
|
|
222
219
|
├── 🔵 Devin
|
|
223
|
-
│ ├── .devinrules ≤5,800 chars (6K limit)
|
|
224
220
|
│ └── .devin/rules/
|
|
225
221
|
│ ├── rails-context.md project overview
|
|
226
222
|
│ └── rails-mcp-tools.md tool reference
|
|
@@ -296,7 +292,7 @@ The gem exposes **22 built-in tool classes** via MCP — 20 registered by defaul
|
|
|
296
292
|
| Tool | What it returns |
|
|
297
293
|
|------|----------------|
|
|
298
294
|
| `rails_get_schema` | Tables, columns, indexes, foreign keys — tagged `[VERIFIED]` (live ActiveRecord) or `[INFERRED]` (static schema.rb / structure.sql parse) |
|
|
299
|
-
| `rails_get_model_details` | Associations, validations, scopes, enums, callbacks, source macros, semantic tier, non-AR models (when enabled) — tagged `[VERIFIED]` (reflection
|
|
295
|
+
| `rails_get_model_details` | Associations, validations, scopes, enums, callbacks, source macros, semantic tier, non-AR models (when enabled) — tagged `[VERIFIED]` (reflection) or `[INFERRED]` (source regex) |
|
|
300
296
|
| `rails_get_context` | In-process composite for one model, controller, or feature: table + model + routes + controller actions + cheap related tests (no HTTP) |
|
|
301
297
|
| `rails_get_routes` | HTTP verbs, paths, controller actions |
|
|
302
298
|
| `rails_get_controllers` | Actions, inherited filters (source class at standard/full), strong params, concerns |
|
|
@@ -320,6 +316,8 @@ The gem exposes **22 built-in tool classes** via MCP — 20 registered by defaul
|
|
|
320
316
|
|
|
321
317
|
All tools are **read-only** — they never modify your application or database.
|
|
322
318
|
|
|
319
|
+
**Confidence tags legend.** Some tools label each fact with its evidence. `[VERIFIED]` means the fact is provable at runtime or from the AST. `[INFERRED]` means it comes from a pattern, a heuristic, or a schema-file parse (the `static` source label). `[STATIC]` is reserved and never emitted. `rails_get_schema` and `rails_get_model_details` tag facts, as do single-controller `rails_get_controllers` output at any detail level, full-detail `rails_get_controllers` lists, and full-detail `rails_get_view` output. The schema and model sections of `rails_get_context` are tagged too, and its controller section is tagged at full detail. Set `config.confidence_tags_enabled = false` in the `RailsAiBridge.configure` block to remove the controller and view tags; schema and model tags stay on. The guide's [Reading confidence tags](docs/GUIDE.md#reading-confidence-tags) section explains the footer and the settings.
|
|
320
|
+
|
|
323
321
|
### Smart Detail Levels
|
|
324
322
|
|
|
325
323
|
Schema, routes, models, and controllers tools support a `detail` parameter — critical for large apps:
|
|
@@ -372,10 +370,10 @@ rails-ai-bridge gives every client two things: **static context files** loaded a
|
|
|
372
370
|
| Client | Static files loaded automatically | MCP wiring |
|
|
373
371
|
|--------|----------------------------------|------------|
|
|
374
372
|
| **Claude Code** | `CLAUDE.md`, `.claude/rules/*.md` | Auto — reads `.mcp.json` |
|
|
375
|
-
| **Cursor** | `.
|
|
376
|
-
| **Devin** | `.
|
|
373
|
+
| **Cursor** | `.cursor/rules/*.mdc`, `AGENTS.md` | Auto — reads `.mcp.json` |
|
|
374
|
+
| **Devin** | `.devin/rules/*.md`, `AGENTS.md` | Manual — create `.devin/mcp.json` |
|
|
377
375
|
| **Copilot** | `.github/copilot-instructions.md`, `.github/instructions/` | Not supported natively |
|
|
378
|
-
| **Codex** | `AGENTS.md
|
|
376
|
+
| **Codex** | `AGENTS.md` | Via `.codex/mcp_servers.json` |
|
|
379
377
|
| **Gemini** | `GEMINI.md` | Via Gemini CLI config |
|
|
380
378
|
|
|
381
379
|
### Claude Code
|
|
@@ -403,11 +401,11 @@ Start your Rails server and point Cursor to `http://localhost:3000/mcp` (type: S
|
|
|
403
401
|
|
|
404
402
|
### Devin
|
|
405
403
|
|
|
406
|
-
Devin reads `.
|
|
404
|
+
Devin reads `.devin/rules/*.md` and `AGENTS.md` automatically. MCP requires one manual step.
|
|
407
405
|
|
|
408
406
|
**Step 1 — generate files:**
|
|
409
407
|
```bash
|
|
410
|
-
rails ai:bridge # all formats, including .
|
|
408
|
+
rails ai:bridge # all formats, including .devin/rules/ and AGENTS.md
|
|
411
409
|
```
|
|
412
410
|
|
|
413
411
|
**Step 2 — create `.devin/mcp.json`:**
|
|
@@ -435,7 +433,7 @@ MCP is not natively supported in the Copilot VS Code extension. The static files
|
|
|
435
433
|
|
|
436
434
|
### Codex
|
|
437
435
|
|
|
438
|
-
Codex reads `AGENTS.md` at the repository root. MCP can be configured in `.codex/mcp_servers.json`. Run `rails ai:bridge:codex` to regenerate `AGENTS.md
|
|
436
|
+
Codex reads `AGENTS.md` at the repository root. MCP can be configured in `.codex/mcp_servers.json`. Run `rails ai:bridge:codex` to regenerate `AGENTS.md`.
|
|
439
437
|
|
|
440
438
|
### HTTP transport (alternative for all clients)
|
|
441
439
|
|
|
@@ -568,6 +566,8 @@ end
|
|
|
568
566
|
<details>
|
|
569
567
|
<summary><strong>All configuration options</strong></summary>
|
|
570
568
|
|
|
569
|
+
The confidence and Prism settings also work on the `static_analysis` sub-object. See the [options reference in the guide](docs/GUIDE.md#options-reference) for both paths.
|
|
570
|
+
|
|
571
571
|
| Option | Default | Description |
|
|
572
572
|
|--------|---------|-------------|
|
|
573
573
|
| `preset` | `:standard` | Introspector preset (`:standard` or `:full`) |
|
|
@@ -601,9 +601,14 @@ end
|
|
|
601
601
|
| `watcher_formats` | `:all` | Formats regenerated by `rails ai:watch` (e.g. `%i[claude cursor]` to limit churn) |
|
|
602
602
|
| `managed_region` | `false` | Confine generated output to a marked block so hand-authored content in `CLAUDE.md` & co. survives regeneration |
|
|
603
603
|
| `anti_hallucination_rules` | `true` | Include the shared verify-before-write block in every generated context file (markdown near the top, `.ai-context.json` as an `anti_hallucination_rules` key) |
|
|
604
|
+
| `legacy_agent_files` | `false` | Also write the deprecated `.cursorrules`, `.devinrules`, and `.codex/README.md`. Cursor reads `.cursor/rules/` and `AGENTS.md`, Devin does not read `.devinrules`, and Codex reads only `AGENTS.md`. Removed in 6.0 |
|
|
604
605
|
| `parallel_introspection` | `false` | Run introspectors concurrently (requires `concurrent-ruby`, which is already a Rails dependency) |
|
|
605
606
|
| `parallel_pool_size` | `4` | Max threads in the parallel pool; capped at the number of active introspectors so no idle threads are created |
|
|
606
607
|
| `parallel_timeout_seconds` | `10` | Per-introspector future timeout (seconds); timed-out introspectors return `{ error: "timed out after Ns" }` without blocking the others |
|
|
608
|
+
| `static_analysis` | built in | Sub-object (`RailsAiBridge::Config::StaticAnalysis`) for the confidence and Prism settings below, such as `config.static_analysis.confidence_tags_enabled` |
|
|
609
|
+
| `confidence_tags_enabled` | `true` | Adds tags and footers to single-controller output at any `detail` level, to full-detail `rails_get_controllers` output, to the controller section of full-detail `rails_get_context` output, and to full-detail `rails_get_view` output. Summary and standard list output (no `controller:` argument) has no tags or footers. Schema and model tags are always on. |
|
|
610
|
+
| `prism_enabled` | `false` | Turns on the Prism pass. Strong params that Prism finds as methods in the controller source render as `[VERIFIED]`. Needs Prism, a default gem on Ruby 3.3+. |
|
|
611
|
+
| `prism_max_files` | `500` | Caps the files the Prism pass reads per introspection run. |
|
|
607
612
|
| `registry.registry_manifest_path` | `"config/rails_ai_bridge/registry.json"` | Path to the registry manifest JSON file for skill pack resolution |
|
|
608
613
|
| `registry.skill_cache_dir` | `"~/.rails-ai-bridge/cache"` | Directory for caching git repositories containing skill packs |
|
|
609
614
|
| `registry.skill_packs` | `nil` | Explicit pack names to load, or `nil` for auto-detection based on framework |
|
|
@@ -662,7 +667,7 @@ Always run `bin/rubocop` before committing.
|
|
|
662
667
|
wrap the generated part in the markers by hand before your first run to keep it.
|
|
663
668
|
|
|
664
669
|
Markdown provider files only (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
|
|
665
|
-
`.github/copilot-instructions.md
|
|
670
|
+
`.github/copilot-instructions.md`). `.ai-context.json` never
|
|
666
671
|
receives markers. Freshness skipping and `ai:doctor` staleness both read through the region,
|
|
667
672
|
so unchanged runs are still no-ops.
|
|
668
673
|
|
|
@@ -682,8 +687,8 @@ Every generated context file carries a short verify-before-write block so AI ass
|
|
|
682
687
|
query the live app (via the `rails_*` MCP tools) instead of inventing structure:
|
|
683
688
|
|
|
684
689
|
- Markdown files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md`,
|
|
685
|
-
|
|
686
|
-
`.
|
|
690
|
+
and the split-rules files under `.claude/rules/`, `.cursor/rules/`, `.devin/rules/`,
|
|
691
|
+
`.github/instructions/`) open with a
|
|
687
692
|
`## Anti-hallucination rules` section near the top — after the freshness header, before
|
|
688
693
|
content sections — so it survives compact-mode trimming and stays inside the managed
|
|
689
694
|
region on regeneration.
|
|
@@ -827,7 +832,7 @@ Frontend introspectors (views, Turbo, Stimulus, assets) degrade gracefully — t
|
|
|
827
832
|
| `rails ai:bridge` | Generate all bridge files (skips unchanged) |
|
|
828
833
|
| `rails ai:bridge:full` | Generate all files in full mode (dumps everything) |
|
|
829
834
|
| `rails ai:bridge:claude` | Generate Claude Code files only |
|
|
830
|
-
| `rails ai:bridge:codex` | Generate Codex files only (`AGENTS.md`
|
|
835
|
+
| `rails ai:bridge:codex` | Generate Codex files only (`AGENTS.md`) |
|
|
831
836
|
| `rails ai:bridge:cursor` | Generate Cursor files only |
|
|
832
837
|
| `rails ai:bridge:devin` | Generate Devin files only |
|
|
833
838
|
| `rails ai:bridge:copilot` | Generate Copilot files only |
|
|
@@ -868,7 +873,8 @@ The gem parses `db/schema.rb` as text when no database is connected. Works in CI
|
|
|
868
873
|
|
|
869
874
|
## Requirements
|
|
870
875
|
|
|
871
|
-
- Ruby
|
|
876
|
+
- Ruby **>= 3.2** (blocking CI on 3.2, 3.3, 3.4; Ruby 4.0 is a non-blocking canary). See the [Ruby support policy](docs/ruby-version-support.md) for tested combinations.
|
|
877
|
+
- Rails >= 7.1, < 10.0 (tested on 7.1, 7.2, 8.0, 8.1)
|
|
872
878
|
- [mcp](https://github.com/modelcontextprotocol/ruby-sdk) gem (installed automatically)
|
|
873
879
|
- Optional: `listen` gem for watch mode, `ripgrep` for fast code search
|
|
874
880
|
|
|
@@ -906,7 +912,7 @@ The docs are layered so new users do not need to read everything at once.
|
|
|
906
912
|
| A quick install and mental model | This README |
|
|
907
913
|
| See it working on a tiny app | [docs/EXAMPLES.md](docs/EXAMPLES.md) and [examples/](examples/) |
|
|
908
914
|
| MCP Registry listing steps | [docs/mcp-registry-submission.md](docs/mcp-registry-submission.md) |
|
|
909
|
-
| Full API reference (YARD) | [https://igmarin.github.io/rails-ai-bridge/](https://igmarin.github.io/rails-ai-bridge/) —
|
|
915
|
+
| Full API reference (YARD) | [https://igmarin.github.io/rails-ai-bridge/](https://igmarin.github.io/rails-ai-bridge/) — published on every `v*` tag release |
|
|
910
916
|
| How to get better AI output day to day | [docs/BEST_PRACTICES.md](docs/BEST_PRACTICES.md) |
|
|
911
917
|
| Every command, config option, generated file, and MCP parameter | [docs/GUIDE.md](docs/GUIDE.md) |
|
|
912
918
|
| Complete Devin setup — MCP wiring, skills, troubleshooting | [docs/devin-setup.md](docs/devin-setup.md) |
|
|
@@ -945,7 +951,7 @@ Bug reports and pull requests: [github.com/igmarin/rails-ai-bridge/issues](https
|
|
|
945
951
|
|
|
946
952
|
## Acknowledgments & Origins
|
|
947
953
|
|
|
948
|
-
This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge
|
|
954
|
+
This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
|
|
949
955
|
|
|
950
956
|
RailsMCP evolved from
|
|
951
957
|
[crisnahine/rails-ai-context](https://github.com/crisnahine/rails-ai-context),
|
data/SECURITY.md
CHANGED
|
@@ -29,6 +29,9 @@ please report it responsibly:
|
|
|
29
29
|
|
|
30
30
|
- All MCP tools are **read-only** and never modify your application or database.
|
|
31
31
|
- Code search (`rails_search_code`) uses `Open3.capture2` with array arguments to prevent shell injection.
|
|
32
|
+
Both backends skip symlinked files and reject directory aliases into excluded paths;
|
|
33
|
+
the Ruby fallback opens files with `File::NOFOLLOW` and streams lines so reaching
|
|
34
|
+
the result cap does not load the rest of a file.
|
|
32
35
|
- Symbol explanation (`rails_explain_symbol`) uses `Open3.capture3` with array arguments against a local `.codegraph/` index only (timeout enforced; never contacts a network service).
|
|
33
36
|
- File paths are validated against path traversal attacks, and invalid regex input
|
|
34
37
|
now returns a controlled tool response in the Ruby fallback path.
|
data/UPGRADING.md
CHANGED
|
@@ -1,5 +1,51 @@
|
|
|
1
1
|
# Upgrading rails-ai-bridge
|
|
2
2
|
|
|
3
|
+
## Upgrading from 5.3.x to the next release
|
|
4
|
+
|
|
5
|
+
**One behavior change.** `rails ai:bridge` no longer writes `.cursorrules`, `.devinrules`, or
|
|
6
|
+
`.codex/README.md`. No assistant needs them: Cursor reads `.cursor/rules/` and `AGENTS.md`, Devin does not
|
|
7
|
+
read `.devinrules`, and Codex reads only `AGENTS.md`. Nothing else changes, and the gem never deletes your
|
|
8
|
+
existing copies. Delete them when you are ready (and remove them from `.gitignore` or CI if you listed them).
|
|
9
|
+
|
|
10
|
+
To keep writing them until 6.0 removes the option:
|
|
11
|
+
|
|
12
|
+
```ruby
|
|
13
|
+
RailsAiBridge.configure { |config| config.output.legacy_agent_files = true }
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Upgrading from 5.2.x to 5.3.0
|
|
19
|
+
|
|
20
|
+
**No action is required.** One default changes what tools print.
|
|
21
|
+
|
|
22
|
+
- **Confidence tags are on by default.** `rails_get_controllers`, full-detail `rails_get_view`, and the
|
|
23
|
+
controller section of full-detail `rails_get_context` now mark facts `[VERIFIED]` or `[INFERRED]` and end
|
|
24
|
+
with a `Verification:` footer. To get the previous output, set
|
|
25
|
+
`config.confidence_tags_enabled = false`. See "Reading confidence tags" in [docs/GUIDE.md](docs/GUIDE.md).
|
|
26
|
+
- **Prism verification is opt-in.** `config.prism_enabled = true` lets a Prism parse confirm controller
|
|
27
|
+
strong params, which then show `[VERIFIED]`. Prism is a default gem on Ruby 3.3 and newer. On Ruby 3.2,
|
|
28
|
+
add `gem 'prism'` to your Gemfile; without it the pass is skipped and strong params stay `[INFERRED]`.
|
|
29
|
+
`config.prism_max_files` (default `500`) caps how many files one run parses.
|
|
30
|
+
- **`config.mcp.rate_limiter_key_prefix` now takes effect.** If you set it, `Mcp::CacheRateLimiter` uses it
|
|
31
|
+
when you do not pass `key_prefix:`, so existing counters start fresh once.
|
|
32
|
+
- **The unused `Services` layer is removed** (`RailsAiBridge::Services::AppIntrospectionService`,
|
|
33
|
+
`ConfigurationService`, `ContextGenerationService`, `FileManagementService`). The gem never called them.
|
|
34
|
+
If your code referenced them, use `RailsAiBridge.introspect` and `RailsAiBridge.generate_context`.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Upgrading from 5.1.x to 5.2.0
|
|
39
|
+
|
|
40
|
+
**No action is required.**
|
|
41
|
+
|
|
42
|
+
- Every generated context file now carries an `## Anti-hallucination rules` block. Set
|
|
43
|
+
`config.output.anti_hallucination_rules = false` to leave it out.
|
|
44
|
+
- `rails_query` and `rails_read_logs` are new and stay off until you set `config.enable_data_tools = true`.
|
|
45
|
+
See [docs/mcp-security.md](docs/mcp-security.md) before enabling them.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
3
49
|
## Upgrading from 5.0.0 to 5.1.0
|
|
4
50
|
|
|
5
51
|
**One action required if you are pinned to `rubydex` 0.3.x:**
|
data/docs/BEST_PRACTICES.md
CHANGED
|
@@ -50,17 +50,17 @@ Each AI client reads different files. Knowing which files matter for your tool h
|
|
|
50
50
|
| Client | Passive context (always loaded) | Live MCP | Notes |
|
|
51
51
|
|--------|---------------------------------|----------|-------|
|
|
52
52
|
| **Claude Code** | `CLAUDE.md`, `.claude/rules/*.md` | `.mcp.json` auto-detected | Rules injected per-session; MCP auto-wired via `.mcp.json` |
|
|
53
|
-
| **Cursor** | `.
|
|
54
|
-
| **Devin** | `.
|
|
53
|
+
| **Cursor** | `.cursor/rules/*.mdc`, `AGENTS.md` | `.mcp.json` auto-detected | `alwaysApply: true` rules loaded every turn; glob-scoped rules loaded per file |
|
|
54
|
+
| **Devin** | `.devin/rules/*.md`, `AGENTS.md` | Manual MCP config required | Reads `AGENTS.md`, `CLAUDE.md`, and the rules directory |
|
|
55
55
|
| **GitHub Copilot (VS Code)** | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | Not supported natively | `applyTo` glob patterns control which instructions file is injected |
|
|
56
|
-
| **OpenAI Codex** | `AGENTS.md
|
|
56
|
+
| **OpenAI Codex** | `AGENTS.md` | `.mcp.json` (when configured) | `AGENTS.md` at repo root is the primary context source |
|
|
57
57
|
| **Gemini (AI Studio / Code Assist)** | `GEMINI.md` | MCP via Gemini CLI | `GEMINI.md` provides the project briefing; MCP for live data |
|
|
58
58
|
|
|
59
59
|
### How MCP wiring works per client
|
|
60
60
|
|
|
61
61
|
- **Claude Code & Cursor**: `.mcp.json` at the project root is auto-detected. No manual setup — the client spawns `rails ai:serve` automatically.
|
|
62
62
|
- **Devin**: MCP is not auto-detected. Create `.devin/mcp.json` manually (see [docs/devin-setup.md](devin-setup.md) for the exact JSON and full walkthrough).
|
|
63
|
-
- **Codex**: Configure in `.codex/mcp_servers.json` or equivalent.
|
|
63
|
+
- **Codex**: Configure in `.codex/mcp_servers.json` or equivalent.
|
|
64
64
|
- **Copilot**: MCP is not natively supported via `.mcp.json`. The `rails_*` tools are documented in `.github/instructions/rails-mcp-tools.instructions.md` so Copilot knows about them, but cannot call them automatically.
|
|
65
65
|
|
|
66
66
|
### What "always loaded" means for token budgets
|
|
@@ -218,12 +218,12 @@ The gem only overwrites files it generated. Files you create with different name
|
|
|
218
218
|
1. The five `.cursor/rules/*.mdc` files cover different scopes — don't collapse them into one big always-on file.
|
|
219
219
|
2. `rails-engineering.mdc` and `rails-project.mdc` are the always-on rules. Keep them concise (< 100 lines each).
|
|
220
220
|
3. `rails-models.mdc` and `rails-controllers.mdc` use glob scoping — they only fire when you have model/controller files open.
|
|
221
|
-
4. `.cursorrules` is
|
|
221
|
+
4. `.cursorrules` is deprecated by Cursor and no longer generated by default. Delete an old copy; `.cursor/rules/` and `AGENTS.md` replace it.
|
|
222
222
|
5. MCP is auto-wired via `.mcp.json`. Run `rails ai:serve` once; Cursor keeps it alive.
|
|
223
223
|
|
|
224
224
|
### Devin
|
|
225
225
|
|
|
226
|
-
1.
|
|
226
|
+
1. Devin does not read `.devinrules`, so the gem no longer generates it. Context goes into `AGENTS.md` and `.devin/rules/`.
|
|
227
227
|
2. Devin also reads `AGENTS.md` — run `rails ai:bridge` (not just `rails ai:bridge:devin`) to keep both files current.
|
|
228
228
|
3. MCP requires a manual one-time step: create `.devin/mcp.json` with an absolute `cwd` path. See [docs/devin-setup.md](devin-setup.md) for the exact JSON.
|
|
229
229
|
4. If `bundle` is not on `PATH` (common with rbenv/rvm in Devin's environment), use the absolute shim path or switch to the HTTP transport (`rails ai:serve_http`).
|
|
@@ -240,7 +240,7 @@ The gem only overwrites files it generated. Files you create with different name
|
|
|
240
240
|
|
|
241
241
|
1. `AGENTS.md` is the entry point — Codex reads this at task start.
|
|
242
242
|
2. Keep personal preferences in `~/.codex/AGENTS.md`; use the repository `AGENTS.md` for shared guidance.
|
|
243
|
-
3.
|
|
243
|
+
3. Configure MCP in `.codex/mcp_servers.json` so Codex can call the live `rails_*` tools.
|
|
244
244
|
4. Codex benefits most from explicit conventions (test patterns, service object structure) — make sure `overrides.md` is activated.
|
|
245
245
|
|
|
246
246
|
### Gemini
|
|
@@ -336,13 +336,10 @@ Use this ordering as a starting point, not a replacement for live checks. When a
|
|
|
336
336
|
CLAUDE.md
|
|
337
337
|
AGENTS.md
|
|
338
338
|
GEMINI.md
|
|
339
|
-
.cursorrules
|
|
340
339
|
.cursor/rules/
|
|
341
|
-
.devinrules
|
|
342
340
|
.devin/rules/
|
|
343
341
|
.github/copilot-instructions.md
|
|
344
342
|
.github/instructions/
|
|
345
|
-
.codex/README.md
|
|
346
343
|
.mcp.json
|
|
347
344
|
config/rails_ai_bridge/overrides.md ← commit even when stub; remove guard when ready
|
|
348
345
|
```
|
data/docs/EXAMPLES.md
CHANGED
|
@@ -78,14 +78,11 @@ Captured output (abridged):
|
|
|
78
78
|
📝 Writing bridge files...
|
|
79
79
|
✅ .../demo_app/CLAUDE.md
|
|
80
80
|
✅ .../demo_app/AGENTS.md
|
|
81
|
-
✅ .../demo_app/.cursorrules
|
|
82
|
-
✅ .../demo_app/.devinrules
|
|
83
81
|
✅ .../demo_app/.github/copilot-instructions.md
|
|
84
82
|
✅ .../demo_app/GEMINI.md
|
|
85
83
|
✅ .../demo_app/.claude/rules/rails-context.md
|
|
86
84
|
✅ .../demo_app/.claude/rules/rails-schema.md
|
|
87
85
|
✅ .../demo_app/.claude/rules/rails-models.md
|
|
88
|
-
⏭️ .../demo_app/.codex/README.md (unchanged)
|
|
89
86
|
...
|
|
90
87
|
|
|
91
88
|
Done! Your AI assistants now understand your Rails app.
|
|
@@ -97,9 +94,9 @@ One run writes context for all 7 assistant targets. The committed files in
|
|
|
97
94
|
| Assistant target | File(s) | Size |
|
|
98
95
|
|---|---|---|
|
|
99
96
|
| Claude Code | `CLAUDE.md` + `.claude/rules/*.md` | 111 lines (compact) |
|
|
100
|
-
| OpenAI Codex | `AGENTS.md`
|
|
101
|
-
| Cursor | `.
|
|
102
|
-
| Devin | `.
|
|
97
|
+
| OpenAI Codex | `AGENTS.md` | 98 lines |
|
|
98
|
+
| Cursor | `.cursor/rules/*.mdc` | 108 lines |
|
|
99
|
+
| Devin | `.devin/rules/*.md` | 53 lines |
|
|
103
100
|
| GitHub Copilot | `.github/copilot-instructions.md` + `.github/instructions/*.md` | 136 lines |
|
|
104
101
|
| Gemini | `GEMINI.md` | 111 lines |
|
|
105
102
|
| JSON cache (not an assistant) | `.ai-context.json` (regenerable cache, not committed) | — |
|