Initial commit

2025-11-30 08:42:29 +08:00
commit bece5178ef
31 changed files with 9410 additions and 0 deletions
--- a/skills/rails-api-lookup/SKILL.md
+++ b/skills/rails-api-lookup/SKILL.md
@@ -0,0 +1,330 @@
+# Rails API Lookup
+
+---
+name: rails-api-lookup
+description: Looks up Rails API documentation for specific classes/methods using Ref (primary) or WebFetch (fallback) with API reference
+version: 1.2.0
+author: Rails Workflow Team
+tags: [rails, api, documentation, reference, ref]
+priority: 3
+---
+
+## Purpose
+
+Fetches precise API documentation from official Rails API docs for specific classes, modules, and methods. Returns signatures, parameters, return values, and usage examples.
+
+**Replaces**: `mcp__rails__search_docs` MCP tool (API-specific queries)
+
+## Usage
+
+**Auto-invoked** when agents need API details:
+```
+Agent: "What parameters does validates :email accept?"
+*invokes rails-api-lookup class="ActiveModel::Validations" method="validates"*
+```
+
+**Manual invocation**:
+```
+@rails-api-lookup class="ActiveRecord::Base" method="where"
+@rails-api-lookup class="ActionController::Base"
+@rails-api-lookup module="ActiveSupport::Concern"
+```
+
+## Supported Lookups
+
+See `reference.md` for complete class/module list. Common APIs:
+
+### Active Record
+- `ActiveRecord::Base` - Model base class
+- `ActiveRecord::Relation` - Query interface (where, joins, etc.)
+- `ActiveRecord::Associations` - Association methods
+- `ActiveRecord::Validations` - Validation methods
+- `ActiveRecord::Callbacks` - Callback methods
+
+### Action Controller
+- `ActionController::Base` - Controller base class
+- `ActionController::Metal` - Minimal controller
+- `ActionController::API` - API controller
+
+### Action View
+- `ActionView::Base` - View rendering
+- `ActionView::Helpers` - View helpers
+- `ActionView::Template` - Template handling
+
+### Active Support
+- `ActiveSupport::Concern` - Module mixins
+- `ActiveSupport::Callbacks` - Callback framework
+- `ActiveSupport::TimeWithZone` - Time handling
+
+## Search Process
+
+### Step 1: Version Detection
+```
+Invokes: @rails-version-detector
+Result: Rails 7.1.3
+Maps to: https://api.rubyonrails.org/v7.1/
+```
+
+### Step 2: Class/Method Mapping
+```
+Input: class="ActiveRecord::Base" method="where"
+Lookup: reference.md → "ActiveRecord/QueryMethods.html#method-i-where"
+URL: https://api.rubyonrails.org/v7.1/ActiveRecord/QueryMethods.html#method-i-where
+```
+
+### Step 3: Content Fetch
+
+**Method 1: Context7 (Fastest)**:
+```
+Tool: context7_fetch
+Query: "Rails [version] [class] [method] API"
+```
+
+**Method 2: Ref (Token-Efficient)**:
+```
+Tool: ref_search_documentation
+Query: "Rails [version] [class] [method] API documentation"
+Then: ref_read_url
+```
+
+**Method 3: Tavily (Search)**:
+```
+Tool: tavily_search
+Query: "Rails [version] [class] [method] API documentation"
+```
+
+**Method 4: WebFetch (Fallback)**:
+```
+Tool: WebFetch
+URL: [constructed URL from reference.md]
+Prompt: "Extract method signature, parameters, and examples for [method]"
+```
+
+### Step 4: Response Formatting
+```ruby
+## ActiveRecord::QueryMethods#where (v7.1)
+
+**Signature**: `where(**opts)`
+
+**Parameters**:
+- `opts` (Hash) - Conditions as key-value pairs
+- `opts` (String) - Raw SQL conditions
+- `opts` (Array) - SQL with placeholders
+
+**Returns**: `ActiveRecord::Relation`
+
+**Examples**:
+User.where(name: 'Alice')
+User.where("age > ?", 18)
+User.where(age: 18..65)
+
+**Source**: https://api.rubyonrails.org/v7.1/ActiveRecord/QueryMethods.html#method-i-where
+```
+
+## Reference Lookup
+
+**Class/Method → API URL mapping** in `reference.md`:
+
+```yaml
+ActiveRecord::Base:
+  url_path: "ActiveRecord/Base.html"
+  common_methods:
+    - save: "method-i-save"
+    - update: "method-i-update"
+    - destroy: "method-i-destroy"
+
+ActiveRecord::QueryMethods:
+  url_path: "ActiveRecord/QueryMethods.html"
+  common_methods:
+    - where: "method-i-where"
+    - joins: "method-i-joins"
+    - includes: "method-i-includes"
+```
+
+## Output Format
+
+### Class Overview
+```ruby
+## ActiveRecord::Base (v7.1)
+
+Active Record base class for all models.
+
+**Inherits from**: Object
+**Includes**: ActiveModel::Validations, ActiveRecord::Persistence
+
+**Common Methods**:
+- `.create` - Creates and saves record
+- `#save` - Saves record to database
+- `#update` - Updates attributes and saves
+- `#destroy` - Deletes record from database
+
+**Source**: https://api.rubyonrails.org/v7.1/ActiveRecord/Base.html
+```
+
+### Method Details
+```ruby
+## ActiveRecord::Base#save (v7.1)
+
+**Signature**: `save(options = {})`
+
+**Parameters**:
+- `validate` (Boolean, default: true) - Run validations before saving
+- `context` (Symbol) - Validation context
+- `touch` (Boolean, default: true) - Update timestamps
+
+**Returns**:
+- `true` if saved successfully
+- `false` if validation failed
+
+**Raises**:
+- `ActiveRecord::RecordInvalid` if `save!` and validation fails
+
+**Examples**:
+```ruby
+user.save                    # => true/false
+user.save(validate: false)   # skip validations
+user.save!                   # raises on failure
+```
+
+**Source**: [full URL]
+```
+
+### Not Found Response
+```markdown
+## Class/Method Not Found: [class]#[method]
+
+Searched in: Rails [version] API docs
+
+Suggestions:
+- Check spelling: "ActiveRecord::Base" (not "ActiveRecords::Base")
+- Try class overview: @rails-api-lookup class="ActiveRecord::Base"
+- Search guides instead: @rails-docs-search topic="active_record_basics"
+
+Common classes:
+- ActiveRecord::Base
+- ActionController::Base
+- ActiveSupport::Concern
+```
+
+## Implementation Details
+
+**Tools used** (in order of preference):
+1. **@rails-version-detector** - Get project Rails version
+2. **Read** - Load `reference.md` API mappings
+3. **context7_fetch** (primary) - Fetch API docs via Context7 MCP
+4. **ref_search_documentation** (secondary) - Search Rails API docs via Ref MCP
+5. **tavily_search** (tertiary) - Optimized search via Tavily MCP
+6. **WebFetch** (fallback) - Fetch API docs if MCPs not available
+7. **Grep** (optional) - Search for method names in cached docs
+
+**Optional dependencies**:
+- **context7-mcp**: Fastest API documentation
+- **ref-tools-mcp**: Token-efficient API doc fetching
+- **tavily-mcp**: Optimized search for LLMs
+- If neither installed: Falls back to WebFetch (still works!)
+
+**URL construction**:
+```
+Base: https://api.rubyonrails.org/
+Versioned: https://api.rubyonrails.org/v7.1/
+Class: https://api.rubyonrails.org/v7.1/ActiveRecord/Base.html
+Method: https://api.rubyonrails.org/v7.1/ActiveRecord/Base.html#method-i-save
+```
+
+**Version handling**:
+- Rails 8.x → `/v8.0/`
+- Rails 7.1.x → `/v7.1/`
+- Rails 7.0.x → `/v7.0/`
+- Rails 6.1.x → `/v6.1/`
+
+**Caching strategy**:
+- Cache API documentation for session
+- Re-fetch if version changes
+- Cache key: `{class}:{method}:{version}`
+
+**Prompt Caching (Opus 4.5 Optimized)**:
+- Use 1-hour cache duration for extended thinking tasks
+- API signatures rarely change - maximize cache reuse
+- Cache prefix: Include Rails version + common class list in system prompt
+- Reduces token costs significantly for repeated API lookups
+
+## Error Handling
+
+**Network failure**:
+```markdown
+⚠️ Failed to fetch API docs from api.rubyonrails.org
+
+Fallback: Use Claude's knowledge (may be less accurate)
+URL attempted: [URL]
+```
+
+**Invalid class name**:
+```markdown
+❌ Unknown class: "[class]"
+
+Did you mean: [closest match from reference.md]?
+
+Tip: Use full module path (e.g., "ActiveRecord::Base", not "Base")
+```
+
+**Method not found**:
+```markdown
+⚠️ Method "[method]" not found in [class]
+
+Class exists, but method not documented or name incorrect.
+
+Available methods in [class]:
+- [method1]
+- [method2]
+[...from reference.md...]
+```
+
+## Integration
+
+**Auto-invoked by**:
+- All 7 Rails agents when they need precise API signatures
+- @rails-model-specialist for ActiveRecord methods
+- @rails-controller-specialist for ActionController methods
+- @rails-view-specialist for ActionView helpers
+
+**Complements**:
+- @rails-docs-search (concepts vs API details)
+- @rails-pattern-finder (API usage vs code patterns)
+
+## Special Features
+
+### Multiple methods lookup
+```
+@rails-api-lookup class="ActiveRecord::Base" method="save,update,destroy"
+→ Returns all three method signatures
+```
+
+### Inheritance chain
+```
+@rails-api-lookup class="User" inherit=true
+→ Shows methods from User, ApplicationRecord, ActiveRecord::Base
+```
+
+### Version comparison
+```
+@rails-api-lookup class="ActiveRecord::Base" method="save" compare="7.0,7.1"
+→ Shows differences between versions
+```
+
+## Testing
+
+**Test cases**:
+1. class="ActiveRecord::Base" method="save" → Exact signature
+2. class="UnknownClass" → Error with suggestions
+3. Network down → Graceful fallback
+4. Rails 8.0 method lookup → Uses v8.0 docs
+5. Method with multiple signatures → Lists all variants
+
+## Notes
+
+- API docs fetched live (not stored in plugin)
+- Reference mappings maintained in `reference.md`
+- Version-appropriate URLs ensure API accuracy
+- WebFetch tool handles HTML parsing
+- This skill focuses on **API signatures**, use @rails-docs-search for **concepts**
+- Method anchors use Rails convention: `#method-i-name` (instance), `#method-c-name` (class)
--- a/skills/rails-api-lookup/reference.md
+++ b/skills/rails-api-lookup/reference.md
@@ -0,0 +1,451 @@
+# Rails API Reference Mappings
+
+**Purpose**: Maps Rails classes/modules to API documentation URLs
+
+**Version**: 1.0.0 (supports Rails 6.1 - 8.0)
+
+---
+
+## Active Record Classes
+
+### Core Classes
+
+```yaml
+ActiveRecord::Base:
+  url_path: "ActiveRecord/Base.html"
+  description: "Base class for all models"
+  common_methods:
+    save: "method-i-save"
+    save!: "method-i-save-21"
+    update: "method-i-update"
+    update!: "method-i-update-21"
+    destroy: "method-i-destroy"
+    destroy!: "method-i-destroy-21"
+    reload: "method-i-reload"
+    persisted?: "method-i-persisted-3F"
+    new_record?: "method-i-new_record-3F"
+
+ActiveRecord::Relation:
+  url_path: "ActiveRecord/Relation.html"
+  description: "Query result collection"
+  common_methods:
+    to_a: "method-i-to_a"
+    each: "method-i-each"
+    map: "method-i-map"
+    pluck: "method-i-pluck"
+    ids: "method-i-ids"
+```
+
+### Query Interface
+
+```yaml
+ActiveRecord::QueryMethods:
+  url_path: "ActiveRecord/QueryMethods.html"
+  description: "Query building methods"
+  common_methods:
+    where: "method-i-where"
+    not: "method-i-not"
+    order: "method-i-order"
+    limit: "method-i-limit"
+    offset: "method-i-offset"
+    joins: "method-i-joins"
+    left_joins: "method-i-left_joins"
+    includes: "method-i-includes"
+    eager_load: "method-i-eager_load"
+    preload: "method-i-preload"
+    references: "method-i-references"
+    group: "method-i-group"
+    having: "method-i-having"
+    distinct: "method-i-distinct"
+    select: "method-i-select"
+    reorder: "method-i-reorder"
+    reverse_order: "method-i-reverse_order"
+```
+
+### Associations
+
+```yaml
+ActiveRecord::Associations::ClassMethods:
+  url_path: "ActiveRecord/Associations/ClassMethods.html"
+  description: "Association declarations"
+  common_methods:
+    belongs_to: "method-i-belongs_to"
+    has_one: "method-i-has_one"
+    has_many: "method-i-has_many"
+    has_and_belongs_to_many: "method-i-has_and_belongs_to_many"
+    has_one_attached: "method-i-has_one_attached"
+    has_many_attached: "method-i-has_many_attached"
+```
+
+### Validations
+
+```yaml
+ActiveModel::Validations::ClassMethods:
+  url_path: "ActiveModel/Validations/ClassMethods.html"
+  description: "Validation declarations"
+  common_methods:
+    validates: "method-i-validates"
+    validates_each: "method-i-validates_each"
+    validates_with: "method-i-validates_with"
+    validate: "method-i-validate"
+
+ActiveModel::Validations::HelperMethods:
+  url_path: "ActiveModel/Validations/HelperMethods.html"
+  description: "Built-in validators"
+  common_methods:
+    validates_presence_of: "method-i-validates_presence_of"
+    validates_absence_of: "method-i-validates_absence_of"
+    validates_length_of: "method-i-validates_length_of"
+    validates_size_of: "method-i-validates_size_of"
+    validates_numericality_of: "method-i-validates_numericality_of"
+    validates_inclusion_of: "method-i-validates_inclusion_of"
+    validates_exclusion_of: "method-i-validates_exclusion_of"
+    validates_format_of: "method-i-validates_format_of"
+    validates_uniqueness_of: "method-i-validates_uniqueness_of"
+```
+
+### Callbacks
+
+```yaml
+ActiveRecord::Callbacks:
+  url_path: "ActiveRecord/Callbacks.html"
+  description: "Model lifecycle callbacks"
+  common_methods:
+    after_initialize: "method-i-after_initialize"
+    after_find: "method-i-after_find"
+    before_validation: "method-i-before_validation"
+    after_validation: "method-i-after_validation"
+    before_save: "method-i-before_save"
+    around_save: "method-i-around_save"
+    after_save: "method-i-after_save"
+    before_create: "method-i-before_create"
+    around_create: "method-i-around_create"
+    after_create: "method-i-after_create"
+    before_update: "method-i-before_update"
+    around_update: "method-i-around_update"
+    after_update: "method-i-after_update"
+    before_destroy: "method-i-before_destroy"
+    around_destroy: "method-i-around_destroy"
+    after_destroy: "method-i-after_destroy"
+    after_commit: "method-i-after_commit"
+    after_rollback: "method-i-after_rollback"
+```
+
+### Migrations
+
+```yaml
+ActiveRecord::Migration:
+  url_path: "ActiveRecord/Migration.html"
+  description: "Database migration base class"
+  common_methods:
+    change: "method-i-change"
+    up: "method-i-up"
+    down: "method-i-down"
+    reversible: "method-i-reversible"
+
+ActiveRecord::ConnectionAdapters::SchemaStatements:
+  url_path: "ActiveRecord/ConnectionAdapters/SchemaStatements.html"
+  description: "Schema manipulation methods"
+  common_methods:
+    create_table: "method-i-create_table"
+    drop_table: "method-i-drop_table"
+    rename_table: "method-i-rename_table"
+    add_column: "method-i-add_column"
+    remove_column: "method-i-remove_column"
+    rename_column: "method-i-rename_column"
+    change_column: "method-i-change_column"
+    add_index: "method-i-add_index"
+    remove_index: "method-i-remove_index"
+    add_foreign_key: "method-i-add_foreign_key"
+    remove_foreign_key: "method-i-remove_foreign_key"
+    add_reference: "method-i-add_reference"
+    remove_reference: "method-i-remove_reference"
+```
+
+---
+
+## Action Controller Classes
+
+### Core Classes
+
+```yaml
+ActionController::Base:
+  url_path: "ActionController/Base.html"
+  description: "Base controller class"
+  common_methods:
+    render: "method-i-render"
+    redirect_to: "method-i-redirect_to"
+    head: "method-i-head"
+
+ActionController::API:
+  url_path: "ActionController/API.html"
+  description: "API-only controller base"
+  version_support: "5.0+"
+
+ActionController::Metal:
+  url_path: "ActionController/Metal.html"
+  description: "Minimal controller implementation"
+```
+
+### Controller Features
+
+```yaml
+ActionController::StrongParameters:
+  url_path: "ActionController/StrongParameters.html"
+  description: "Parameter filtering"
+  common_methods:
+    params: "method-i-params"
+    permit: "method-i-permit"
+    require: "method-i-require"
+
+ActionController::Helpers:
+  url_path: "ActionController/Helpers.html"
+  description: "Helper method declarations"
+  common_methods:
+    helper_method: "method-i-helper_method"
+
+ActionController::Cookies:
+  url_path: "ActionController/Cookies.html"
+  description: "Cookie handling"
+  common_methods:
+    cookies: "method-i-cookies"
+
+ActionController::Flash:
+  url_path: "ActionController/Flash.html"
+  description: "Flash message handling"
+  common_methods:
+    flash: "method-i-flash"
+```
+
+---
+
+## Action View Classes
+
+### Core Classes
+
+```yaml
+ActionView::Base:
+  url_path: "ActionView/Base.html"
+  description: "View rendering base class"
+
+ActionView::Helpers:
+  url_path: "ActionView/Helpers.html"
+  description: "View helper modules"
+```
+
+### View Helpers
+
+```yaml
+ActionView::Helpers::FormHelper:
+  url_path: "ActionView/Helpers/FormHelper.html"
+  description: "Form building helpers"
+  common_methods:
+    form_with: "method-i-form_with"
+    form_for: "method-i-form_for"
+    text_field: "method-i-text_field"
+    text_area: "method-i-text_area"
+    select: "method-i-select"
+    check_box: "method-i-check_box"
+    radio_button: "method-i-radio_button"
+
+ActionView::Helpers::UrlHelper:
+  url_path: "ActionView/Helpers/UrlHelper.html"
+  description: "URL generation helpers"
+  common_methods:
+    link_to: "method-i-link_to"
+    button_to: "method-i-button_to"
+    url_for: "method-i-url_for"
+
+ActionView::Helpers::TagHelper:
+  url_path: "ActionView/Helpers/TagHelper.html"
+  description: "HTML tag helpers"
+  common_methods:
+    content_tag: "method-i-content_tag"
+    tag: "method-i-tag"
+
+ActionView::Helpers::AssetTagHelper:
+  url_path: "ActionView/Helpers/AssetTagHelper.html"
+  description: "Asset inclusion helpers"
+  common_methods:
+    javascript_include_tag: "method-i-javascript_include_tag"
+    stylesheet_link_tag: "method-i-stylesheet_link_tag"
+    image_tag: "method-i-image_tag"
+```
+
+---
+
+## Active Support Classes
+
+### Core Extensions
+
+```yaml
+ActiveSupport::Concern:
+  url_path: "ActiveSupport/Concern.html"
+  description: "Module mixin pattern"
+  common_methods:
+    included: "method-i-included"
+    class_methods: "method-i-class_methods"
+
+ActiveSupport::Callbacks:
+  url_path: "ActiveSupport/Callbacks.html"
+  description: "Callback framework"
+  common_methods:
+    define_callbacks: "method-i-define_callbacks"
+    set_callback: "method-i-set_callback"
+    skip_callback: "method-i-skip_callback"
+    run_callbacks: "method-i-run_callbacks"
+```
+
+### Time & Date
+
+```yaml
+ActiveSupport::TimeWithZone:
+  url_path: "ActiveSupport/TimeWithZone.html"
+  description: "Timezone-aware time"
+  common_methods:
+    in_time_zone: "method-i-in_time_zone"
+    utc: "method-i-utc"
+    local: "method-i-local"
+
+ActiveSupport::Duration:
+  url_path: "ActiveSupport/Duration.html"
+  description: "Time duration"
+  common_methods:
+    ago: "method-i-ago"
+    since: "method-i-since"
+    from_now: "method-i-from_now"
+```
+
+---
+
+## Action Mailer Classes
+
+```yaml
+ActionMailer::Base:
+  url_path: "ActionMailer/Base.html"
+  description: "Mailer base class"
+  common_methods:
+    mail: "method-i-mail"
+    deliver_now: "method-i-deliver_now"
+    deliver_later: "method-i-deliver_later"
+```
+
+---
+
+## Action Cable Classes
+
+```yaml
+ActionCable::Channel::Base:
+  url_path: "ActionCable/Channel/Base.html"
+  description: "Cable channel base class"
+  common_methods:
+    stream_from: "method-i-stream_from"
+    stream_for: "method-i-stream_for"
+    transmit: "method-i-transmit"
+
+ActionCable::Connection::Base:
+  url_path: "ActionCable/Connection/Base.html"
+  description: "Cable connection base class"
+```
+
+---
+
+## Active Job Classes
+
+```yaml
+ActiveJob::Base:
+  url_path: "ActiveJob/Base.html"
+  description: "Background job base class"
+  common_methods:
+    perform_later: "method-i-perform_later"
+    perform_now: "method-i-perform_now"
+    set: "method-i-set"
+```
+
+---
+
+## Active Storage Classes
+
+```yaml
+ActiveStorage::Attached::One:
+  url_path: "ActiveStorage/Attached/One.html"
+  description: "Single file attachment"
+  version_support: "5.2+"
+  common_methods:
+    attach: "method-i-attach"
+    attached?: "method-i-attached-3F"
+    purge: "method-i-purge"
+
+ActiveStorage::Attached::Many:
+  url_path: "ActiveStorage/Attached/Many.html"
+  description: "Multiple file attachments"
+  version_support: "5.2+"
+  common_methods:
+    attach: "method-i-attach"
+    attached?: "method-i-attached-3F"
+    purge: "method-i-purge"
+```
+
+---
+
+## URL Construction
+
+**Pattern**: `https://api.rubyonrails.org/v{MAJOR.MINOR}/{url_path}#{method_anchor}`
+
+**Examples**:
+
+**Class page**:
+```
+https://api.rubyonrails.org/v7.1/ActiveRecord/Base.html
+```
+
+**Instance method**:
+```
+https://api.rubyonrails.org/v7.1/ActiveRecord/Base.html#method-i-save
+```
+
+**Class method**:
+```
+https://api.rubyonrails.org/v7.1/ActiveRecord/Base.html#method-c-create
+```
+
+**Special characters in anchor**:
+- `?` → `-3F`
+- `!` → `-21`
+- `=` → `-3D`
+
+**Examples**:
+- `persisted?` → `#method-i-persisted-3F`
+- `save!` → `#method-i-save-21`
+- `==` → `#method-i--3D-3D`
+
+---
+
+## Usage in rails-api-lookup
+
+```ruby
+# Pseudocode for API lookup
+class_name = "ActiveRecord::Base"
+method_name = "save"
+mapping = reference[class_name]
+version = detect_rails_version() # e.g., "7.1"
+anchor = mapping.common_methods[method_name] # e.g., "method-i-save"
+url = "https://api.rubyonrails.org/v#{version}/#{mapping.url_path}##{anchor}"
+content = WebFetch(url, prompt: "Extract method signature and documentation")
+```
+
+---
+
+## Maintenance
+
+**Update frequency**: Quarterly or when new Rails version released
+
+**Adding new APIs**:
+1. Check official Rails API docs index
+2. Add mapping with url_path and common_methods
+3. Test URL accessibility
+4. Update this file
+
+**Version-specific APIs**:
+- Mark with `version_support`
+- Skill should gracefully handle unavailable APIs for older Rails versions