rails_claude_skills 0.1.0

data/lib/generators/claude/skills_library/rails-debugging/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: rails-debugging
+description: Use when debugging Rails issues - provides Rails-specific debugging tools (logs, console, byebug, SQL logging) integrated with systematic debugging process
+---
+
+# Rails Debugging Tools & Techniques
+
+<superpowers-integration>
+**REQUIRED BACKGROUND:** Use superpowers:systematic-debugging for investigation process
+  - That skill defines 4-phase framework (Root Cause → Pattern → Hypothesis → Implementation)
+  - This skill provides Rails-specific debugging tools for each phase
+</superpowers-integration>
+
+<when-to-use>
+- Rails application behaving unexpectedly
+- Tests failing with unclear errors
+- Performance issues or N+1 queries
+- Production errors need investigation
+</when-to-use>
+
+<verification-checklist>
+Before completing debugging work:
+- ✅ Root cause identified (not just symptoms)
+- ✅ Regression test added (prevents recurrence)
+- ✅ Fix verified in development and test environments
+- ✅ All tests passing (bin/ci passes)
+- ✅ Logs reviewed for related issues
+- ✅ Performance impact verified (if applicable)
+</verification-checklist>
+
+<phase1-root-cause-investigation>
+
+<tool name="rails-logs">
+<description>Check Rails logs for errors and request traces</description>
+
+```bash
+# Development logs
+tail -f log/development.log
+
+# Production logs (Kamal)
+kamal app logs --tail
+
+# Filter by severity
+grep ERROR log/production.log
+
+# Filter by request
+grep "Started GET" log/development.log
+
+```
+</tool>
+
+<tool name="rails-console">
+<description>Interactive Rails console for testing models/queries</description>
+
+```ruby
+# Start console
+rails console
+
+# Or production console (Kamal)
+kamal app exec 'bin/rails console'
+
+# Test models
+user = User.find(1)
+user.valid?  # Check validations
+user.errors.full_messages  # See errors
+
+# Test queries
+User.where(email: "test@example.com").to_sql  # See SQL
+User.includes(:posts).where(posts: { published: true })  # Avoid N+1
+
+```
+</tool>
+
+<tool name="byebug">
+<description>Breakpoint debugger for stepping through code</description>
+
+```ruby
+# Add to any Rails file
+def some_method
+  byebug  # Execution stops here
+  # ... rest of method
+end
+
+# Byebug commands:
+# n  - next line
+# s  - step into method
+# c  - continue execution
+# pp variable  - pretty print
+# var local  - show local variables
+# exit  - quit debugger
+
+```
+</tool>
+
+<tool name="sql-logging">
+<description>Enable verbose SQL logging to see queries</description>
+
+```ruby
+# In rails console or code
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+# Now all SQL queries print to console
+User.all
+# => SELECT "users".* FROM "users"
+
+```
+</tool>
+
+</phase1-root-cause-investigation>
+
+<phase2-pattern-analysis>
+
+<tool name="rails-routes">
+<description>Check route definitions and paths</description>
+
+```bash
+# List all routes
+rails routes
+
+# Filter routes
+rails routes | grep users
+
+# Show routes for controller
+rails routes -c users
+
+```
+</tool>
+
+<tool name="rails-db-status">
+<description>Check migration status and schema</description>
+
+```bash
+# Migration status
+rails db:migrate:status
+
+# Show schema version
+rails db:version
+
+# Check pending migrations
+rails db:abort_if_pending_migrations
+
+```
+</tool>
+
+</phase2-pattern-analysis>
+
+<phase3-hypothesis-testing>
+
+<tool name="rails-runner">
+<description>Run Ruby code in Rails environment</description>
+
+```bash
+# Run one-liner
+rails runner "puts User.count"
+
+# Run script
+rails runner scripts/investigate_users.rb
+
+# Production environment
+RAILS_ENV=production rails runner "User.pluck(:email)"
+
+```
+</tool>
+
+</phase3-hypothesis-testing>
+
+<phase4-implementation>
+
+<tool name="rails-test-verbose">
+<description>Run tests with detailed output</description>
+
+```bash
+# Run single test with backtrace
+rails test test/models/user_test.rb --verbose
+
+# Run with warnings enabled
+RUBYOPT=-W rails test
+
+# Run with seed for reproducibility
+rails test --seed 12345
+
+```
+</tool>
+
+</phase4-implementation>
+
+<common-issues>
+
+<issue name="n-plus-one-queries">
+<detection>
+Check logs for many similar queries:
+
+```
+
+User Load (0.1ms)  SELECT * FROM users WHERE id = 1
+Post Load (0.1ms)  SELECT * FROM posts WHERE user_id = 1
+Post Load (0.1ms)  SELECT * FROM posts WHERE user_id = 2
+Post Load (0.1ms)  SELECT * FROM posts WHERE user_id = 3
+
+```
+</detection>
+<solution>
+Use includes/preload:
+
+```ruby
+# Bad
+users.each { |user| user.posts.count }
+
+# Good
+users.includes(:posts).each { |user| user.posts.count }
+
+```
+</solution>
+</issue>
+
+<issue name="missing-migration">
+<detection>
+Error: "ActiveRecord::StatementInvalid: no such column"
+</detection>
+<solution>
+
+```bash
+# Check migration status
+rails db:migrate:status
+
+# Run pending migrations
+rails db:migrate
+
+# Or rollback and retry
+rails db:rollback
+rails db:migrate
+
+```
+</solution>
+</issue>
+
+</common-issues>
+
+<related-skills>
+- superpowers:systematic-debugging (4-phase framework)
+- rails-ai:models (Query optimization, N+1 debugging)
+- rails-ai:controllers (Request debugging, parameter inspection)
+- rails-ai:testing (Test debugging, failure investigation)
+</related-skills>
+
+<resources>
+
+**Official Documentation:**
+- [Rails Guides - Debugging Rails Applications](https://guides.rubyonrails.org/debugging_rails_applications.html)
+- [Rails API - ActiveSupport::Logger](https://api.rubyonrails.org/classes/ActiveSupport/Logger.html)
+- [Ruby Debugging Guide](https://ruby-doc.org/stdlib-3.0.0/libdoc/debug/rdoc/index.html)
+
+**Gems & Libraries:**
+- [byebug](https://github.com/deivid-rodriguez/byebug) - Ruby debugger
+- [bullet](https://github.com/flyerhzm/bullet) - N+1 query detection
+
+**Tools:**
+- [Rack Mini Profiler](https://github.com/MiniProfiler/rack-mini-profiler) - Performance profiling
+
+</resources>

data/lib/generators/claude/skills_library/rails-deployment/SKILL.md

@@ -0,0 +1,437 @@
+---
+name: rails-deployment
+description: Deploy Rails applications to production using Kamal, Docker, and modern deployment strategies. Covers zero-downtime deployments, environment management, database migrations, SSL/TLS, and production configurations.
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash
+---
+
+# Rails Deployment with Kamal
+
+Deploy Rails 8 applications to production using Kamal for zero-downtime Docker deployments. Covers Kamal configuration, Docker setup, environment secrets, database migrations, SSL certificates, and production best practices.
+
+<when-to-use>
+- Setting up new Rails application for production deployment
+- Deploying with Kamal to VPS (DigitalOcean, Hetzner, AWS EC2)
+- Configuring Docker for Rails applications
+- Managing environment variables and secrets
+- Running database migrations in production
+- Setting up zero-downtime deployments
+- Configuring SSL/TLS certificates
+- Managing multiple environments (staging, production)
+</when-to-use>
+
+<benefits>
+- **Zero-Downtime** - Rolling deployments with health checks
+- **Simple Setup** - SSH-based deployment, no complex orchestration
+- **Docker Native** - Consistent environments from dev to production
+- **Built-in SSL** - Automatic Let's Encrypt certificate management
+- **Fast Deployments** - Optimized Docker layer caching
+- **Rollback Support** - Easy rollback to previous versions
+- **Multi-Server** - Deploy to multiple servers with load balancing
+</benefits>
+
+<verification-checklist>
+Before deploying to production:
+- ✅ Kamal configuration file (config/deploy.yml) properly configured
+- ✅ Dockerfile optimized with multi-stage build
+- ✅ Environment secrets set up (.env, Rails credentials)
+- ✅ Database configured and migrations ready
+- ✅ SSL certificates configured (Let's Encrypt or custom)
+- ✅ Health check endpoint responding
+- ✅ Asset precompilation working in Docker
+- ✅ Background jobs (Solid Queue) configured
+- ✅ Monitoring and logging set up
+</verification-checklist>
+
+<standards>
+- Use Kamal for deployments (included in Rails 8)
+- Multi-stage Dockerfile for optimized images
+- Store secrets in Rails credentials or environment variables
+- Run database migrations before deployment with --skip-push
+- Use health checks for zero-downtime deployments
+- Configure SSL with Let's Encrypt or custom certificates
+- Set up log aggregation (stdout/stderr)
+- Use Docker registry for image caching (Docker Hub, GitHub Container Registry)
+- Configure proper resource limits in Docker
+- Monitor application health and performance
+</standards>
+
+---
+
+## Kamal Overview
+
+Kamal (formerly MRSK) is a deployment tool for Rails 8 that uses Docker and SSH to deploy applications to any server. No Kubernetes, no complex orchestration - just simple, reliable deployments.
+
+**Key Features:**
+- Zero-downtime deployments with health checks
+- Automatic SSL with Let's Encrypt
+- Multi-server deployments
+- Rolling restarts
+- Easy rollbacks
+- Built-in load balancing with Traefik
+
+---
+
+## Quick Start
+
+### 1. Install Kamal
+
+```bash
+# Kamal comes with Rails 8
+gem install kamal
+
+# Verify installation
+kamal version
+```
+
+### 2. Initialize Kamal
+
+```bash
+# Generate Kamal configuration files
+kamal init
+
+# Creates:
+# - config/deploy.yml        # Main configuration
+# - .env.erb                  # Environment template
+# - .kamal/                   # Kamal directory
+```
+
+### 3. Configure Server
+
+```yaml
+# config/deploy.yml
+service: my-blog-app
+image: your-username/my-blog-app
+
+servers:
+  web:
+    hosts:
+      - 192.168.1.100  # Your server IP
+    labels:
+      traefik.http.routers.my-blog-app.rule: Host(`example.com`)
+      traefik.http.routers.my-blog-app-secure.entrypoints: websecure
+      traefik.http.routers.my-blog-app-secure.rule: Host(`example.com`)
+      traefik.http.routers.my-blog-app-secure.tls: true
+      traefik.http.routers.my-blog-app-secure.tls.certresolver: letsencrypt
+
+registry:
+  username: your-username
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+env:
+  secret:
+    - RAILS_MASTER_KEY
+  clear:
+    RAILS_ENV: production
+    RAILS_LOG_TO_STDOUT: true
+
+builder:
+  multiarch: false
+```
+
+### 4. Setup Server
+
+```bash
+# Install Docker on remote server
+kamal server bootstrap
+
+# Verify setup
+kamal setup
+```
+
+### 5. Deploy
+
+```bash
+# First deployment
+kamal deploy
+
+# Subsequent deployments
+kamal deploy
+```
+
+---
+
+## Code Examples & Patterns
+
+For detailed deployment patterns and examples, see **[examples.md](examples.md)**.
+
+### Pattern Categories
+
+**examples.md contains:**
+- **Kamal Configuration** - Complete deploy.yml examples for various setups
+- **Docker Configuration** - Multi-stage Dockerfile optimization
+- **Environment Management** - Secrets, credentials, environment variables
+- **Database Migrations** - Safe migration strategies in production
+- **SSL/TLS Setup** - Let's Encrypt and custom certificates
+- **Multi-Server Deployment** - Load balancing across servers
+- **Background Jobs** - Deploying Solid Queue workers
+- **Health Checks** - Endpoint configuration for zero-downtime
+- **Rollback Procedures** - Recovering from failed deployments
+- **Monitoring & Logging** - Production observability setup
+- **CI/CD Integration** - GitHub Actions deployment workflows
+
+Refer to examples.md for complete code examples.
+
+---
+
+## Kamal Commands
+
+### Deployment Commands
+
+```bash
+# Initial setup (first time only)
+kamal setup
+
+# Deploy application
+kamal deploy
+
+# Deploy without building new image
+kamal deploy --skip-push
+
+# Run migrations before deployment
+kamal deploy --skip-push
+kamal app exec "bin/rails db:migrate"
+```
+
+### Application Management
+
+```bash
+# Restart application
+kamal app restart
+
+# Stop application
+kamal app stop
+
+# Start application
+kamal app start
+
+# View application logs
+kamal app logs -f
+
+# Execute command in container
+kamal app exec "bin/rails console"
+kamal app exec "bin/rails db:migrate:status"
+```
+
+### Rollback
+
+```bash
+# List versions
+kamal app version
+
+# Rollback to previous version
+kamal rollback [VERSION]
+```
+
+### Server Management
+
+```bash
+# SSH into server
+kamal app exec --interactive bash
+
+# View Docker containers
+kamal app containers
+
+# View server details
+kamal server details
+```
+
+---
+
+## Dockerfile for Rails
+
+### Multi-Stage Dockerfile
+
+Rails 8 includes an optimized Dockerfile by default:
+
+```dockerfile
+# Dockerfile (Rails 8 default, optimized)
+ARG RUBY_VERSION=3.4.7
+FROM ruby:$RUBY_VERSION-slim AS base
+
+WORKDIR /rails
+
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y \
+    curl libjemalloc2 libvips sqlite3 && \
+    rm -rf /var/lib/apt/lists /var/cache/apt/archives
+
+ENV RAILS_ENV="production" \
+    BUNDLE_DEPLOYMENT="1" \
+    BUNDLE_PATH="/usr/local/bundle" \
+    BUNDLE_WITHOUT="development:test"
+
+FROM base AS build
+
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y \
+    build-essential git pkg-config && \
+    rm -rf /var/lib/apt/lists /var/cache/apt/archives
+
+COPY Gemfile Gemfile.lock ./
+RUN bundle install && \
+    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git
+
+COPY . .
+
+RUN bundle exec bootsnap precompile --gemfile app/ lib/
+RUN ./bin/rails assets:precompile
+
+FROM base
+
+COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
+COPY --from=build /rails /rails
+
+RUN groupadd --system --gid 1000 rails && \
+    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \
+    chown -R 1000:1000 db log storage tmp
+USER 1000:1000
+
+ENTRYPOINT ["/rails/bin/docker-entrypoint"]
+
+EXPOSE 3000
+CMD ["./bin/thrust", "./bin/rails", "server"]
+```
+
+---
+
+## Environment Management
+
+### Rails Credentials
+
+```bash
+# Edit production credentials
+EDITOR=nano rails credentials:edit --environment production
+
+# Generates config/credentials/production.yml.enc
+# and config/credentials/production.key
+```
+
+```yaml
+# config/credentials/production.yml.enc (encrypted)
+secret_key_base: <generated>
+database:
+  password: <db_password>
+smtp:
+  username: <smtp_user>
+  password: <smtp_pass>
+```
+
+### Environment Variables
+
+```ruby
+# .env (not committed to git, for local deployment)
+KAMAL_REGISTRY_PASSWORD=<docker_hub_password>
+RAILS_MASTER_KEY=<from config/credentials/production.key>
+DATABASE_URL=postgresql://user:pass@host:5432/dbname
+```
+
+---
+
+## Database Migrations
+
+### Safe Migration Strategy
+
+```bash
+# 1. Deploy without running migrations
+kamal deploy --skip-push
+
+# 2. Run migrations separately
+kamal app exec "bin/rails db:migrate"
+
+# 3. Restart application
+kamal app restart
+```
+
+### Pre-Deployment Checks
+
+```bash
+# Check migration status before deploying
+kamal app exec "bin/rails db:migrate:status"
+
+# Run migrations in a transaction
+kamal app exec "bin/rails db:migrate"
+
+# Verify migration success
+kamal app exec "bin/rails db:version"
+```
+
+---
+
+<testing>
+
+## Testing Deployment
+
+### Local Docker Testing
+
+```bash
+# Build Docker image locally
+docker build -t my-app .
+
+# Run container locally
+docker run -p 3000:3000 \
+  -e RAILS_MASTER_KEY=<key> \
+  -e DATABASE_URL=<url> \
+  my-app
+
+# Test in browser
+open http://localhost:3000
+```
+
+### Staging Environment
+
+```yaml
+# config/deploy.staging.yml
+service: my-blog-app-staging
+image: your-username/my-blog-app
+
+servers:
+  web:
+    hosts:
+      - staging.example.com
+
+env:
+  secret:
+    - RAILS_MASTER_KEY
+  clear:
+    RAILS_ENV: staging
+```
+
+```bash
+# Deploy to staging
+kamal deploy -c config/deploy.staging.yml
+```
+
+</testing>
+
+---
+
+<related-skills>
+- rails-models - Database setup and migrations
+- rails-jobs - Background job configuration for production
+- rails-api - API deployment considerations
+- rails-debugging - Production debugging and monitoring
+</related-skills>
+
+<resources>
+
+**Official Documentation:**
+- [Kamal Documentation](https://kamal-deploy.org/) - Official Kamal guide
+- [Docker Documentation](https://docs.docker.com/) - Docker reference
+- [Rails Deployment Guide](https://guides.rubyonrails.org/configuring.html#running-in-production) - Rails production config
+
+**Deployment Platforms:**
+- [DigitalOcean](https://www.digitalocean.com/) - Simple VPS hosting
+- [Hetzner](https://www.hetzner.com/) - Cost-effective VPS
+- [AWS EC2](https://aws.amazon.com/ec2/) - Scalable cloud hosting
+
+**Monitoring & Logging:**
+- [AppSignal](https://appsignal.com/) - Rails monitoring
+- [Sentry](https://sentry.io/) - Error tracking
+- [Lograge](https://github.com/roidrage/lograge) - Structured logging
+
+**CI/CD:**
+- [GitHub Actions](https://github.com/features/actions) - CI/CD automation
+- [Kamal GitHub Action](https://github.com/basecamp/kamal) - Official action
+
+</resources>