source_monitor 0.2.0 → 0.3.0

data/.claude/skills/active-storage-setup/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: active-storage-setup
+description: Configures Active Storage for file uploads with variants and direct uploads. Use when adding file uploads, image attachments, document storage, generating thumbnails, or when user mentions Active Storage, file upload, attachments, or image processing.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Active Storage Setup for Rails 8
+
+## Overview
+
+Active Storage handles file uploads in Rails:
+- Cloud storage (S3, GCS, Azure) or local disk
+- Image variants (thumbnails, resizing)
+- Direct uploads from browser
+- Polymorphic attachments
+
+## Quick Start
+
+```bash
+bin/rails active_storage:install
+bin/rails db:migrate
+bundle add image_processing
+```
+
+## Configuration
+
+```yaml
+# config/storage.yml
+local:
+  service: Disk
+  root: <%= Rails.root.join("storage") %>
+
+test:
+  service: Disk
+  root: <%= Rails.root.join("tmp/storage") %>
+
+amazon:
+  service: S3
+  access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
+  secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
+  region: eu-west-1
+  bucket: <%= Rails.application.credentials.dig(:aws, :bucket) %>
+```
+
+```ruby
+# config/environments/development.rb
+config.active_storage.service = :local
+
+# config/environments/production.rb
+config.active_storage.service = :amazon
+```
+
+## Model Attachments
+
+### Single Attachment
+
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar do |attachable|
+    attachable.variant :thumb, resize_to_limit: [100, 100]
+    attachable.variant :medium, resize_to_limit: [300, 300]
+  end
+end
+```
+
+### Multiple Attachments
+
+```ruby
+class Event < ApplicationRecord
+  has_many_attached :photos
+  has_many_attached :documents
+end
+```
+
+## Validations
+
+### Manual Validation
+
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+
+  validate :acceptable_avatar
+
+  private
+
+  def acceptable_avatar
+    return unless avatar.attached?
+
+    unless avatar.blob.byte_size <= 5.megabytes
+      errors.add(:avatar, "is too large (max 5MB)")
+    end
+
+    acceptable_types = ["image/jpeg", "image/png", "image/webp"]
+    unless acceptable_types.include?(avatar.content_type)
+      errors.add(:avatar, "must be a JPEG, PNG, or WebP")
+    end
+  end
+end
+```
+
+### With active_storage_validations Gem
+
+```ruby
+gem "active_storage_validations"
+
+class User < ApplicationRecord
+  has_one_attached :avatar
+
+  validates :avatar,
+    content_type: ["image/png", "image/jpeg", "image/webp"],
+    size: { less_than: 5.megabytes }
+end
+```
+
+## Image Variants
+
+```ruby
+# Resize to fit (maintains aspect ratio)
+resize_to_limit: [300, 300]
+
+# Resize and crop to exact dimensions
+resize_to_fill: [300, 300]
+
+# With format conversion
+resize_to_limit: [300, 300], format: :webp, saver: { quality: 80 }
+```
+
+### Using in Views
+
+```erb
+<% if user.avatar.attached? %>
+  <%= image_tag user.avatar.variant(:thumb), alt: user.name %>
+<% else %>
+  <%= image_tag "default-avatar.png", alt: "Default" %>
+<% end %>
+```
+
+## Testing Attachments (Minitest)
+
+### Model Test
+
+```ruby
+# test/models/user_test.rb
+require "test_helper"
+
+class UserAttachmentTest < ActiveSupport::TestCase
+  setup do
+    @user = users(:one)
+  end
+
+  test "attaches an avatar" do
+    @user.avatar.attach(
+      io: File.open(Rails.root.join("test/fixtures/files/avatar.jpg")),
+      filename: "avatar.jpg",
+      content_type: "image/jpeg"
+    )
+
+    assert @user.avatar.attached?
+  end
+
+  test "rejects oversized avatar" do
+    @user.avatar.attach(
+      io: StringIO.new("x" * 6.megabytes),
+      filename: "large.jpg",
+      content_type: "image/jpeg"
+    )
+
+    assert_not @user.valid?
+    assert_includes @user.errors[:avatar], "is too large (max 5MB)"
+  end
+
+  test "rejects invalid content type" do
+    @user.avatar.attach(
+      io: File.open(Rails.root.join("test/fixtures/files/document.pdf")),
+      filename: "doc.pdf",
+      content_type: "application/pdf"
+    )
+
+    assert_not @user.valid?
+    assert @user.errors[:avatar].any?
+  end
+end
+```
+
+### Controller Test
+
+```ruby
+# test/controllers/users_controller_test.rb
+require "test_helper"
+
+class UsersUploadTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:one)
+    sign_in @user
+  end
+
+  test "uploads avatar" do
+    avatar = fixture_file_upload("avatar.jpg", "image/jpeg")
+
+    patch user_path(@user), params: { user: { avatar: avatar } }
+
+    assert @user.reload.avatar.attached?
+  end
+
+  test "removes avatar" do
+    @user.avatar.attach(
+      io: File.open(Rails.root.join("test/fixtures/files/avatar.jpg")),
+      filename: "avatar.jpg",
+      content_type: "image/jpeg"
+    )
+
+    delete remove_avatar_user_path(@user)
+
+    assert_not @user.reload.avatar.attached?
+  end
+end
+```
+
+### Fixtures Setup
+
+Place test files in `test/fixtures/files/`:
+```
+test/fixtures/files/
+├── avatar.jpg
+├── document.pdf
+└── photo.png
+```
+
+## Controller Handling
+
+```ruby
+class UsersController < ApplicationController
+  def update
+    if @user.update(user_params)
+      redirect_to @user, notice: "Profile updated"
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  def remove_avatar
+    @user.avatar.purge
+    redirect_to edit_user_path(@user), notice: "Avatar removed"
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:name, :email, :avatar)
+  end
+end
+```
+
+### Multiple Uploads
+
+```ruby
+def event_params
+  params.require(:event).permit(:name, photos: [], documents: [])
+end
+```
+
+## Forms
+
+```erb
+<%= form_with model: @user do |f| %>
+  <div>
+    <%= f.label :avatar %>
+    <%= f.file_field :avatar, accept: "image/png,image/jpeg,image/webp" %>
+
+    <% if @user.avatar.attached? %>
+      <%= image_tag @user.avatar.variant(:thumb), class: "rounded mt-2" %>
+    <% end %>
+  </div>
+  <%= f.submit %>
+<% end %>
+```
+
+## Direct Uploads
+
+```javascript
+// app/javascript/application.js
+import * as ActiveStorage from "@rails/activestorage"
+ActiveStorage.start()
+```
+
+```erb
+<%= f.file_field :photos, multiple: true, direct_upload: true %>
+```
+
+## Performance Tips
+
+```ruby
+# Prevent N+1 on attachments
+User.with_attached_avatar.limit(10)
+
+# Multiple attachments
+Event.with_attached_photos.with_attached_documents
+```
+
+## Checklist
+
+- [ ] Active Storage installed and migrated
+- [ ] Storage service configured
+- [ ] Image processing gem added
+- [ ] Attachment added to model
+- [ ] Validations added (type, size)
+- [ ] Variants defined
+- [ ] Controller permits attachment params
+- [ ] Tests written for attachments
+- [ ] All tests GREEN

data/.claude/skills/api-versioning/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: api-versioning
+description: Implements RESTful API design with versioning and request tests. Use when building APIs, adding API endpoints, versioning APIs, or when user mentions REST, JSON API, or API design.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# API Versioning for Rails 8
+
+## Overview
+
+Well-structured APIs need versioning for backwards compatibility and clear organization.
+
+**Recommended**: URL Path versioning (`/api/v1/users`)
+
+## Quick Setup
+
+### Routes
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      resources :users, only: [:index, :show, :create, :update, :destroy]
+      resources :events, only: [:index, :show, :create]
+    end
+  end
+end
+```
+
+### Directory Structure
+
+```
+app/controllers/
+├── api/
+│   ├── base_controller.rb
+│   ├── v1/
+│   │   ├── base_controller.rb
+│   │   ├── users_controller.rb
+│   │   └── events_controller.rb
+│   └── v2/
+│       ├── base_controller.rb
+│       └── users_controller.rb
+```
+
+### Base Controller
+
+```ruby
+# app/controllers/api/base_controller.rb
+module Api
+  class BaseController < ApplicationController
+    skip_before_action :verify_authenticity_token
+
+    rescue_from ActiveRecord::RecordNotFound, with: :not_found
+    rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
+    rescue_from ActionController::ParameterMissing, with: :bad_request
+
+    private
+
+    def not_found(exception)
+      render json: { error: exception.message }, status: :not_found
+    end
+
+    def unprocessable_entity(exception)
+      render json: { errors: exception.record.errors }, status: :unprocessable_entity
+    end
+
+    def bad_request(exception)
+      render json: { error: exception.message }, status: :bad_request
+    end
+  end
+end
+```
+
+### Version Base Controller
+
+```ruby
+# app/controllers/api/v1/base_controller.rb
+module Api
+  module V1
+    class BaseController < Api::BaseController
+    end
+  end
+end
+```
+
+### Resource Controller
+
+```ruby
+# app/controllers/api/v1/users_controller.rb
+module Api
+  module V1
+    class UsersController < BaseController
+      before_action :set_user, only: [:show, :update, :destroy]
+
+      def index
+        @users = User.page(params[:page]).per(25)
+        render json: { data: @users, meta: pagination_meta(@users) }
+      end
+
+      def show
+        render json: { data: @user }
+      end
+
+      def create
+        @user = User.create!(user_params)
+        render json: { data: @user }, status: :created
+      end
+
+      def update
+        @user.update!(user_params)
+        render json: { data: @user }
+      end
+
+      def destroy
+        @user.destroy
+        head :no_content
+      end
+
+      private
+
+      def set_user
+        @user = User.find(params[:id])
+      end
+
+      def user_params
+        params.require(:user).permit(:name, :email)
+      end
+
+      def pagination_meta(collection)
+        {
+          current_page: collection.current_page,
+          total_pages: collection.total_pages,
+          total_count: collection.total_count
+        }
+      end
+    end
+  end
+end
+```
+
+## API Authentication
+
+### Bearer Token Auth
+
+```ruby
+# app/controllers/api/base_controller.rb
+module Api
+  class BaseController < ApplicationController
+    before_action :authenticate_api_user!
+
+    private
+
+    def authenticate_api_user!
+      token = request.headers["Authorization"]&.split(" ")&.last
+      @current_api_user = Session.find_by(token: token)&.user
+
+      render json: { error: "Unauthorized" }, status: :unauthorized unless @current_api_user
+    end
+
+    def current_api_user
+      @current_api_user
+    end
+  end
+end
+```
+
+## Response Format
+
+```json
+// Success (single)
+{ "data": { "id": 1, "name": "John", "email": "john@example.com" } }
+
+// Success (collection)
+{ "data": [...], "meta": { "current_page": 1, "total_pages": 10 } }
+
+// Error
+{ "error": "Record not found" }
+
+// Validation errors
+{ "errors": { "email": ["has already been taken"] } }
+```
+
+## Testing APIs (Minitest)
+
+### Request Test Template
+
+```ruby
+# test/controllers/api/v1/users_controller_test.rb
+require "test_helper"
+
+class Api::V1::UsersControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:one)
+    @headers = {
+      "Accept" => "application/json",
+      "Content-Type" => "application/json",
+      "Authorization" => "Bearer #{api_token_for(@user)}"
+    }
+  end
+
+  # -- index --
+  test "GET /api/v1/users returns all users" do
+    get "/api/v1/users", headers: @headers
+
+    assert_response :success
+    data = json_response["data"]
+    assert_kind_of Array, data
+  end
+
+  # -- show --
+  test "GET /api/v1/users/:id returns the user" do
+    get "/api/v1/users/#{@user.id}", headers: @headers
+
+    assert_response :success
+    assert_equal @user.id, json_response["data"]["id"]
+  end
+
+  test "GET /api/v1/users/:id returns 404 for missing user" do
+    get "/api/v1/users/999999", headers: @headers
+
+    assert_response :not_found
+    assert json_response["error"].present?
+  end
+
+  # -- create --
+  test "POST /api/v1/users creates a user" do
+    params = { user: { name: "New User", email: "new@example.com" } }
+
+    assert_difference("User.count", 1) do
+      post "/api/v1/users", params: params.to_json, headers: @headers
+    end
+
+    assert_response :created
+  end
+
+  test "POST /api/v1/users with invalid params returns errors" do
+    params = { user: { name: "", email: "" } }
+
+    assert_no_difference("User.count") do
+      post "/api/v1/users", params: params.to_json, headers: @headers
+    end
+
+    assert_response :unprocessable_entity
+    assert json_response["errors"].present?
+  end
+
+  # -- update --
+  test "PATCH /api/v1/users/:id updates the user" do
+    params = { user: { name: "Updated" } }
+
+    patch "/api/v1/users/#{@user.id}", params: params.to_json, headers: @headers
+
+    assert_response :success
+    assert_equal "Updated", @user.reload.name
+  end
+
+  # -- destroy --
+  test "DELETE /api/v1/users/:id destroys the user" do
+    assert_difference("User.count", -1) do
+      delete "/api/v1/users/#{@user.id}", headers: @headers
+    end
+
+    assert_response :no_content
+  end
+
+  # -- authentication --
+  test "returns 401 without token" do
+    get "/api/v1/users", headers: { "Accept" => "application/json" }
+
+    assert_response :unauthorized
+  end
+
+  private
+
+  def json_response
+    JSON.parse(response.body)
+  end
+
+  def api_token_for(user)
+    user.sessions.create!.token
+  end
+end
+```
+
+## Checklist
+
+- [ ] Routes namespaced under `api/v1`
+- [ ] Base controller with error handling
+- [ ] Authentication configured
+- [ ] Standard response format
+- [ ] Request tests written
+- [ ] 404/422/401 error cases tested
+- [ ] All tests GREEN