rails_claude_skills 0.1.0

data/lib/generators/claude/skills_library/rails-api-controllers/references/serialization.md

@@ -0,0 +1,456 @@
+# JSON Serialization Patterns
+
+Control how your models are serialized to JSON for API responses. Choose the right serialization approach based on your needs.
+
+## Default Rails Serialization
+
+Rails provides basic JSON serialization out of the box:
+
+### as_json / to_json
+
+```ruby
+# In controller
+def show
+  render json: @article
+end
+
+# Customize in model
+class Article < ApplicationRecord
+  def as_json(options = {})
+    super(
+      only: [:id, :title, :body, :status],
+      include: {
+        author: { only: [:id, :name, :email] },
+        comments: { only: [:id, :body, :created_at] }
+      },
+      methods: [:word_count]
+    )
+  end
+
+  def word_count
+    body.split.size
+  end
+end
+```
+
+**Pros:** Built-in, no dependencies
+**Cons:** Mixes presentation logic with models, not reusable
+
+## Jbuilder (Rails Default)
+
+Jbuilder uses view templates for JSON responses:
+
+### Basic Usage
+
+```ruby
+# app/views/api/v1/articles/show.json.jbuilder
+json.article do
+  json.id @article.id
+  json.title @article.title
+  json.body @article.body
+  json.status @article.status
+  json.created_at @article.created_at
+
+  json.author do
+    json.id @article.author.id
+    json.name @article.author.name
+    json.email @article.author.email
+  end
+end
+```
+
+### Collections
+
+```ruby
+# app/views/api/v1/articles/index.json.jbuilder
+json.data @articles do |article|
+  json.id article.id
+  json.title article.title
+  json.excerpt article.body.truncate(100)
+  json.author_name article.author.name
+end
+
+json.meta do
+  json.current_page @articles.current_page
+  json.total_pages @articles.total_pages
+  json.total_count @articles.total_count
+end
+```
+
+### Partials
+
+```ruby
+# app/views/api/v1/articles/_article.json.jbuilder
+json.extract! article, :id, :title, :body, :status, :created_at
+
+json.author do
+  json.partial! 'api/v1/users/user', user: article.author
+end
+
+# app/views/api/v1/articles/show.json.jbuilder
+json.article do
+  json.partial! 'article', article: @article
+end
+```
+
+**Pros:** Familiar view-based approach, good for complex nested data
+**Cons:** Slower than other options, requires view files
+
+## ActiveModelSerializers (AMS)
+
+Class-based serializers with conventions:
+
+### Installation
+
+```ruby
+# Gemfile
+gem 'active_model_serializers', '~> 0.10.0'
+```
+
+### Basic Serializer
+
+```ruby
+# app/serializers/article_serializer.rb
+class ArticleSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body, :status, :created_at, :word_count
+
+  belongs_to :author
+  has_many :comments
+
+  def word_count
+    object.body.split.size
+  end
+end
+
+# app/serializers/author_serializer.rb
+class AuthorSerializer < ActiveModel::Serializer
+  attributes :id, :name, :email
+end
+
+# Controller automatically uses serializer
+def show
+  render json: @article  # Uses ArticleSerializer
+end
+```
+
+### Conditional Attributes
+
+```ruby
+class ArticleSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body, :draft_notes
+
+  def draft_notes
+    object.draft_notes if object.status == 'draft'
+  end
+
+  def include_draft_notes?
+    object.status == 'draft'
+  end
+end
+```
+
+### Custom Serializers
+
+```ruby
+# Use specific serializer
+render json: @article, serializer: ArticleDetailSerializer
+
+# Disable serializer
+render json: @article, serializer: nil
+
+# Collection with meta
+render json: @articles,
+       meta: { total_count: @articles.total_count },
+       meta_key: 'pagination'
+```
+
+**Pros:** Convention over configuration, automatic associations
+**Cons:** Slower than simpler alternatives, less active maintenance
+
+## Blueprinter (Recommended)
+
+Fast, declarative serialization with great performance:
+
+### Installation
+
+```ruby
+# Gemfile
+gem 'blueprinter'
+```
+
+### Basic Blueprint
+
+```ruby
+# app/blueprints/article_blueprint.rb
+class ArticleBlueprint < Blueprinter::Base
+  identifier :id
+
+  fields :title, :body, :status, :created_at
+
+  field :word_count do |article|
+    article.body.split.size
+  end
+
+  association :author, blueprint: AuthorBlueprint
+  association :comments, blueprint: CommentBlueprint
+end
+
+# app/blueprints/author_blueprint.rb
+class AuthorBlueprint < Blueprinter::Base
+  identifier :id
+  fields :name, :email
+end
+
+# In controller
+def show
+  render json: ArticleBlueprint.render(@article)
+end
+
+def index
+  render json: ArticleBlueprint.render(@articles)
+end
+```
+
+### Views (Different Representations)
+
+```ruby
+class ArticleBlueprint < Blueprinter::Base
+  identifier :id
+
+  # Default view
+  fields :title, :status, :created_at
+
+  # Extended view with more fields
+  view :extended do
+    fields :body, :updated_at
+    association :author, blueprint: AuthorBlueprint
+  end
+
+  # Summary view with minimal fields
+  view :summary do
+    field :title
+    field :excerpt do |article|
+      article.body.truncate(100)
+    end
+  end
+end
+
+# Usage
+ArticleBlueprint.render(@article)                      # Default view
+ArticleBlueprint.render(@article, view: :extended)     # Extended view
+ArticleBlueprint.render(@articles, view: :summary)     # Summary for list
+```
+
+### Conditional Fields
+
+```ruby
+class ArticleBlueprint < Blueprinter::Base
+  fields :id, :title, :body
+
+  field :draft_notes, if: ->(article, _options) { article.status == 'draft' }
+
+  field :edit_url, if: ->(article, options) {
+    options[:current_user]&.can_edit?(article)
+  }
+end
+
+# Usage
+ArticleBlueprint.render(@article, current_user: current_user)
+```
+
+### Meta and Root
+
+```ruby
+# With meta
+render json: ArticleBlueprint.render(@articles, meta: {
+  total_count: @articles.total_count,
+  current_page: @articles.current_page
+})
+
+# Output:
+# {
+#   "data": [...articles...],
+#   "meta": { "total_count": 42, "current_page": 1 }
+# }
+
+# Custom root
+ArticleBlueprint.render(@articles, root: :articles)
+# { "articles": [...] }
+```
+
+**Pros:** Fast (5-10x faster than AMS), simple, flexible views
+**Cons:** Less magic, more explicit
+
+## JSONAPI::Serializer (formerly fast_jsonapi)
+
+JSON:API specification compliant serialization:
+
+### Installation
+
+```ruby
+# Gemfile
+gem 'jsonapi-serializer'
+```
+
+### Basic Serializer
+
+```ruby
+# app/serializers/article_serializer.rb
+class ArticleSerializer
+  include JSONAPI::Serializer
+
+  attributes :title, :body, :status, :created_at
+
+  attribute :word_count do |article|
+    article.body.split.size
+  end
+
+  belongs_to :author
+  has_many :comments
+end
+
+# In controller
+def show
+  render json: ArticleSerializer.new(@article).serializable_hash
+end
+```
+
+### JSON:API Response Format
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "article",
+    "attributes": {
+      "title": "Rails API Guide",
+      "body": "Content here...",
+      "status": "published",
+      "created_at": "2025-01-15T10:00:00Z"
+    },
+    "relationships": {
+      "author": {
+        "data": { "id": "5", "type": "user" }
+      }
+    }
+  },
+  "included": [
+    {
+      "id": "5",
+      "type": "user",
+      "attributes": {
+        "name": "John Doe"
+      }
+    }
+  ]
+}
+```
+
+### With Includes
+
+```ruby
+# Include related resources
+options = { include: [:author, :comments] }
+ArticleSerializer.new(@article, options).serializable_hash
+
+# Conditional includes based on params
+def show
+  options = {}
+  options[:include] = params[:include].split(',') if params[:include].present?
+
+  render json: ArticleSerializer.new(@article, options).serializable_hash
+end
+```
+
+**Pros:** JSON:API compliant, fast, handles includes well
+**Cons:** Opinionated format, more verbose responses
+
+## Comparison Table
+
+| Gem | Speed | Flexibility | Learning Curve | Use Case |
+|-----|-------|-------------|----------------|----------|
+| **as_json** | Fast | Low | Easy | Simple APIs, prototypes |
+| **Jbuilder** | Slow | High | Easy | Complex nested data, familiar views |
+| **AMS** | Slow | Medium | Medium | Rails conventions, associations |
+| **Blueprinter** | Very Fast | High | Easy | Production APIs, performance-critical |
+| **JSONAPI::Serializer** | Fast | Medium | Medium | JSON:API clients, standardized APIs |
+
+## Recommendation by Project Size
+
+### Small Projects / Prototypes
+Use Rails default `as_json` or Jbuilder:
+```ruby
+render json: @article.as_json(only: [:id, :title], include: :author)
+```
+
+### Medium Projects
+Use Blueprinter for simplicity and speed:
+```ruby
+ArticleBlueprint.render(@article, view: :detailed)
+```
+
+### Large Projects / JSON:API Clients
+Use JSONAPI::Serializer for spec compliance:
+```ruby
+ArticleSerializer.new(@article, include: [:author]).serializable_hash
+```
+
+## Performance Tips
+
+1. **Select Only Needed Fields**
+   ```ruby
+   # Bad - loads all columns
+   @articles = Article.all
+
+   # Good - only loads needed columns
+   @articles = Article.select(:id, :title, :body, :created_at)
+   ```
+
+2. **Eager Load Associations**
+   ```ruby
+   # Bad - N+1 queries
+   @articles = Article.all
+
+   # Good - single query
+   @articles = Article.includes(:author, :comments)
+   ```
+
+3. **Use Caching**
+   ```ruby
+   # In serializer/blueprint
+   def show
+     json = Rails.cache.fetch([@article, 'v1']) do
+       ArticleBlueprint.render(@article)
+     end
+     render json: json
+   end
+   ```
+
+4. **Paginate Collections**
+   ```ruby
+   @articles = Article.page(params[:page]).per(20)
+   ```
+
+## Testing Serializers
+
+```ruby
+# spec/blueprints/article_blueprint_spec.rb
+RSpec.describe ArticleBlueprint do
+  let(:article) { create(:article, title: 'Test') }
+
+  it 'serializes basic fields' do
+    result = JSON.parse(ArticleBlueprint.render(article))
+
+    expect(result['id']).to eq(article.id)
+    expect(result['title']).to eq('Test')
+    expect(result).to have_key('created_at')
+  end
+
+  it 'includes author in extended view' do
+    result = JSON.parse(ArticleBlueprint.render(article, view: :extended))
+
+    expect(result).to have_key('author')
+    expect(result['author']['name']).to eq(article.author.name)
+  end
+end
+```

data/lib/generators/claude/skills_library/rails-auth-with-devise/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: rails-auth-with-devise
+description: "Complete authentication setup for Ruby on Rails applications using Devise. Use when: (1) Setting up user authentication in a Rails app, (2) Adding sign in/sign up/sign out functionality, (3) Implementing email confirmation, password recovery, or account locking, (4) Configuring OmniAuth social login, (5) Adding multiple user models (User/Admin), (6) Customizing Devise views or controllers, (7) Testing authentication with RSpec/Minitest, (8) API authentication setup"
+---
+
+# Rails Authentication with Devise
+
+Devise is the most popular authentication solution for Rails, providing a complete MVC solution with 10 modular components.
+
+## Quick Setup
+
+```bash
+# Add to Gemfile
+bundle add devise
+
+# Install Devise
+rails generate devise:install
+
+# Generate User model with authentication
+rails generate devise User
+
+# Run migrations
+rails db:migrate
+```
+
+## Essential Configuration
+
+After `devise:install`, configure in `config/environments/development.rb`:
+```ruby
+config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }
+```
+
+Set root route in `config/routes.rb`:
+```ruby
+root to: 'home#index'
+```
+
+## Devise Modules Reference
+
+Enable modules in the model (e.g., `app/models/user.rb`):
+
+| Module | Purpose | Migration Columns |
+|--------|---------|-------------------|
+| `:database_authenticatable` | Password hashing/storage | `email`, `encrypted_password` |
+| `:registerable` | Sign up, edit, destroy account | - |
+| `:recoverable` | Password reset via email | `reset_password_token`, `reset_password_sent_at` |
+| `:rememberable` | "Remember me" cookie | `remember_created_at` |
+| `:trackable` | Sign in stats | `sign_in_count`, `current_sign_in_at`, `last_sign_in_at`, `current_sign_in_ip`, `last_sign_in_ip` |
+| `:validatable` | Email/password validations | - |
+| `:confirmable` | Email confirmation | `confirmation_token`, `confirmed_at`, `confirmation_sent_at`, `unconfirmed_email` |
+| `:lockable` | Lock after failed attempts | `failed_attempts`, `unlock_token`, `locked_at` |
+| `:timeoutable` | Session expiration | - |
+| `:omniauthable` | OAuth provider support | - |
+
+## Controller Helpers
+
+```ruby
+# Require authentication
+before_action :authenticate_user!
+
+# Check if signed in
+user_signed_in?
+
+# Get current user
+current_user
+
+# Access session
+user_session
+```
+
+For other models (e.g., Admin):
+```ruby
+before_action :authenticate_admin!
+admin_signed_in?
+current_admin
+admin_session
+```
+
+## Common Tasks
+
+### Add Custom Fields (e.g., username)
+
+1. Generate migration:
+```bash
+rails g migration AddUsernameToUsers username:string:uniq
+rails db:migrate
+```
+
+2. Permit in `ApplicationController`:
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :configure_permitted_parameters, if: :devise_controller?
+
+  protected
+
+  def configure_permitted_parameters
+    devise_parameter_sanitizer.permit(:sign_up, keys: [:username])
+    devise_parameter_sanitizer.permit(:account_update, keys: [:username])
+  end
+end
+```
+
+### Customize Views
+
+```bash
+# Generate all views
+rails generate devise:views
+
+# Scoped views for specific model
+rails generate devise:views users
+
+# Specific modules only
+rails generate devise:views -v registrations confirmations
+```
+
+### Customize Controllers
+
+```bash
+# Generate controllers
+rails generate devise:controllers users
+
+# Or specific controller
+rails generate devise:controllers users -c sessions registrations
+```
+
+Update routes:
+```ruby
+devise_for :users, controllers: {
+  sessions: 'users/sessions',
+  registrations: 'users/registrations'
+}
+```
+
+### Custom Redirect After Sign In
+
+In `ApplicationController`:
+```ruby
+def after_sign_in_path_for(resource)
+  stored_location_for(resource) || dashboard_path
+end
+
+def after_sign_out_path_for(resource_or_scope)
+  root_path
+end
+```
+
+## Hotwire/Turbo Configuration (Rails 7+)
+
+In `config/initializers/devise.rb`:
+```ruby
+Devise.setup do |config|
+  config.responder.error_status = :unprocessable_entity
+  config.responder.redirect_status = :see_other
+end
+```
+
+Ensure `responders` gem version >= 3.1.0.
+
+## Testing
+
+### RSpec Setup
+
+In `spec/support/devise.rb`:
+```ruby
+RSpec.configure do |config|
+  config.include Devise::Test::ControllerHelpers, type: :controller
+  config.include Devise::Test::ControllerHelpers, type: :view
+  config.include Devise::Test::IntegrationHelpers, type: :feature
+  config.include Devise::Test::IntegrationHelpers, type: :request
+end
+```
+
+Usage:
+```ruby
+sign_in user
+sign_out user
+```
+
+### Minitest Setup
+
+```ruby
+class ActionDispatch::IntegrationTest
+  include Devise::Test::IntegrationHelpers
+end
+```
+
+## Additional Guides
+
+- **OmniAuth setup**: See [references/omniauth.md](references/omniauth.md)
+- **API authentication**: See [references/api-auth.md](references/api-auth.md)
+- **Advanced patterns**: See [references/advanced.md](references/advanced.md)