claude-agent-framework 1.0.0

package/framework/skills/core/file-uploads.md

@@ -0,0 +1,351 @@
+# Skill: File Uploads
+
+## Purpose
+Handle file uploads using Active Storage with local disk storage.
+
+## Setup
+
+### Install Active Storage
+```bash
+rails active_storage:install
+rails db:migrate
+```
+
+### Configure Storage
+```yaml
+# config/storage.yml
+local:
+  service: Disk
+  root: <%= Rails.root.join("storage") %>
+```
+
+```ruby
+# config/environments/development.rb
+config.active_storage.service = :local
+
+# config/environments/production.rb
+config.active_storage.service = :local  # Or cloud service
+```
+
+## Model Attachments
+
+### Single Attachment
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+
+  # With validation
+  validates :avatar, content_type: ['image/png', 'image/jpeg'],
+                     size: { less_than: 5.megabytes }
+end
+```
+
+### Multiple Attachments
+```ruby
+class Article < ApplicationRecord
+  has_many_attached :images
+
+  validates :images, content_type: ['image/png', 'image/jpeg', 'image/webp'],
+                     size: { less_than: 10.megabytes },
+                     limit: { max: 10 }
+end
+```
+
+### With Variants (Image Processing)
+```ruby
+# Gemfile
+gem "image_processing", "~> 1.2"
+```
+
+```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]
+    attachable.variant :large, resize_to_limit: [800, 800]
+  end
+end
+```
+
+## Controller Handling
+
+### Single File Upload
+```ruby
+class UsersController < ApplicationController
+  def update
+    if current_user.update(user_params)
+      redirect_to current_user, notice: "Profile updated."
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:name, :email, :avatar)
+  end
+end
+```
+
+### Multiple File Upload
+```ruby
+class ArticlesController < ApplicationController
+  def create
+    @article = current_user.articles.build(article_params)
+
+    if @article.save
+      redirect_to @article
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    @article = Article.find(params[:id])
+
+    if @article.update(article_params)
+      redirect_to @article
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def article_params
+    params.require(:article).permit(:title, :body, images: [])
+  end
+end
+```
+
+### Removing Attachments
+```ruby
+class UsersController < ApplicationController
+  def remove_avatar
+    current_user.avatar.purge
+    redirect_to edit_user_path(current_user), notice: "Avatar removed."
+  end
+end
+
+# Routes
+resources :users do
+  member do
+    delete :remove_avatar
+  end
+end
+```
+
+## Form Helpers
+
+### Single File
+```erb
+<%= form_with model: @user do |f| %>
+  <div>
+    <%= f.label :avatar %>
+    <%= f.file_field :avatar,
+        accept: "image/png,image/jpeg",
+        class: "block w-full text-sm text-gray-500
+               file:mr-4 file:py-2 file:px-4
+               file:rounded file:border-0
+               file:text-sm file:font-semibold
+               file:bg-blue-50 file:text-blue-700
+               hover:file:bg-blue-100" %>
+  </div>
+
+  <% if @user.avatar.attached? %>
+    <div class="mt-2">
+      <%= image_tag @user.avatar.variant(:thumb), class: "rounded" %>
+      <%= link_to "Remove", remove_avatar_user_path(@user),
+          method: :delete,
+          data: { turbo_confirm: "Remove avatar?" },
+          class: "text-red-600 text-sm" %>
+    </div>
+  <% end %>
+
+  <%= f.submit "Save" %>
+<% end %>
+```
+
+### Multiple Files
+```erb
+<%= form_with model: @article do |f| %>
+  <div>
+    <%= f.label :images %>
+    <%= f.file_field :images,
+        multiple: true,
+        accept: "image/*",
+        class: "block w-full" %>
+  </div>
+
+  <% if @article.images.attached? %>
+    <div class="grid grid-cols-3 gap-4 mt-4">
+      <% @article.images.each do |image| %>
+        <div class="relative">
+          <%= image_tag image.variant(resize_to_limit: [200, 200]), class: "rounded" %>
+          <%= button_to "×",
+              purge_image_article_path(@article, image_id: image.id),
+              method: :delete,
+              class: "absolute top-1 right-1 bg-red-500 text-white rounded-full w-6 h-6" %>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+
+  <%= f.submit "Save" %>
+<% end %>
+```
+
+### Direct Upload (JavaScript)
+```erb
+<%= form_with model: @article, data: { controller: "upload" } do |f| %>
+  <%= f.file_field :images,
+      multiple: true,
+      direct_upload: true,
+      data: {
+        upload_target: "input",
+        action: "change->upload#upload"
+      } %>
+
+  <div data-upload-target="progress" class="hidden">
+    <div class="bg-blue-600 h-2 rounded" data-upload-target="bar" style="width: 0%"></div>
+  </div>
+<% end %>
+```
+
+```javascript
+// app/javascript/controllers/upload_controller.js
+import { Controller } from "@hotwired/stimulus"
+import { DirectUpload } from "@rails/activestorage"
+
+export default class extends Controller {
+  static targets = ["input", "progress", "bar"]
+
+  upload() {
+    Array.from(this.inputTarget.files).forEach(file => {
+      const upload = new DirectUpload(file, this.inputTarget.dataset.directUploadUrl, this)
+
+      upload.create((error, blob) => {
+        if (error) {
+          console.error(error)
+        } else {
+          // Append hidden field with signed_id
+          const hiddenField = document.createElement("input")
+          hiddenField.type = "hidden"
+          hiddenField.name = this.inputTarget.name
+          hiddenField.value = blob.signed_id
+          this.element.appendChild(hiddenField)
+        }
+      })
+    })
+  }
+
+  directUploadWillStoreFileWithXHR(request) {
+    this.progressTarget.classList.remove("hidden")
+    request.upload.addEventListener("progress", event => {
+      const progress = (event.loaded / event.total) * 100
+      this.barTarget.style.width = `${progress}%`
+    })
+  }
+}
+```
+
+## Displaying Attachments
+
+### Images
+```erb
+<%# Original %>
+<%= image_tag @user.avatar %>
+
+<%# With variant %>
+<%= image_tag @user.avatar.variant(:thumb) %>
+
+<%# With fallback %>
+<% if @user.avatar.attached? %>
+  <%= image_tag @user.avatar.variant(:medium), class: "rounded-full" %>
+<% else %>
+  <%= image_tag "default-avatar.png", class: "rounded-full" %>
+<% end %>
+```
+
+### Files/Documents
+```erb
+<% if @document.file.attached? %>
+  <div class="flex items-center gap-2">
+    <span><%= @document.file.filename %></span>
+    <span class="text-gray-500">(<%= number_to_human_size(@document.file.byte_size) %>)</span>
+    <%= link_to "Download", rails_blob_path(@document.file, disposition: "attachment"),
+        class: "text-blue-600" %>
+  </div>
+<% end %>
+```
+
+### PDF Preview
+```erb
+<% if @document.file.content_type == "application/pdf" %>
+  <iframe src="<%= rails_blob_path(@document.file) %>"
+          class="w-full h-96 border rounded"></iframe>
+<% end %>
+```
+
+## Validations
+
+### Custom Validator
+```ruby
+# app/validators/content_type_validator.rb
+class ContentTypeValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return unless value.attached?
+
+    allowed = Array(options[:in] || options[:with])
+
+    files = value.is_a?(ActiveStorage::Attached::Many) ? value : [value]
+
+    files.each do |file|
+      unless allowed.include?(file.content_type)
+        record.errors.add(attribute, :invalid_content_type)
+      end
+    end
+  end
+end
+```
+
+### Usage
+```ruby
+class Article < ApplicationRecord
+  has_many_attached :images
+
+  validates :images, content_type: { in: %w[image/png image/jpeg image/webp] }
+  validates :images, size: { less_than: 5.megabytes }
+end
+```
+
+## Background Processing
+
+### Analyze on Upload
+```ruby
+# Active Storage analyzes files automatically in background
+# Configure in config/application.rb
+config.active_storage.queues.analysis = :default
+config.active_storage.queues.purge = :default
+```
+
+### Custom Processing Job
+```ruby
+class ProcessImageJob < ApplicationJob
+  queue_as :default
+
+  def perform(image_id)
+    image = ActiveStorage::Blob.find(image_id)
+    # Custom processing
+  end
+end
+```
+
+## Best Practices
+
+1. **Validate content types** - Prevent malicious uploads
+2. **Set size limits** - Protect storage and bandwidth
+3. **Use variants** - Don't serve original large images
+4. **Enable direct uploads** - Better UX for large files
+5. **Purge unused files** - Clean up orphaned attachments

package/framework/skills/core/hotwire-native.md

@@ -0,0 +1,296 @@
+# Skill: Hotwire Native
+
+## Purpose
+Build native iOS and Android apps using the existing Rails views with Hotwire Native (formerly Turbo Native).
+
+## Overview
+
+Hotwire Native wraps your Rails web app in a native shell, providing:
+- Native navigation (push/pop)
+- Native UI elements (tab bars, toolbars)
+- Bridge components for native features
+- Offline support
+- Push notifications
+
+## iOS Setup
+
+### Project Structure
+```
+ios/
+├── App/
+│   ├── AppDelegate.swift
+│   ├── SceneDelegate.swift
+│   └── Configuration.swift
+├── Navigation/
+│   ├── Navigator.swift
+│   └── PathConfiguration.swift
+└── Bridge/
+    └── Components/
+```
+
+### Basic Configuration
+```swift
+// Configuration.swift
+import HotwireNative
+
+struct Configuration {
+    static let baseURL = URL(string: "https://yourapp.com")!
+
+    static var pathConfiguration: PathConfiguration {
+        PathConfiguration(sources: [
+            .server(baseURL.appendingPathComponent("/configurations/ios_v1.json"))
+        ])
+    }
+}
+```
+
+### Scene Delegate
+```swift
+// SceneDelegate.swift
+import UIKit
+import HotwireNative
+
+class SceneDelegate: UIResponder, UIWindowSceneDelegate {
+    var window: UIWindow?
+    private let navigator = Navigator()
+
+    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options: UIScene.ConnectionOptions) {
+        guard let windowScene = scene as? UIWindowScene else { return }
+
+        window = UIWindow(windowScene: windowScene)
+        window?.rootViewController = navigator.rootViewController
+        window?.makeKeyAndVisible()
+
+        navigator.route(Configuration.baseURL)
+    }
+}
+```
+
+## Android Setup
+
+### Project Structure
+```
+android/
+├── app/src/main/
+│   ├── java/com/yourapp/
+│   │   ├── MainActivity.kt
+│   │   ├── MainSessionNavHostFragment.kt
+│   │   └── bridge/
+│   └── res/
+│       └── navigation/
+│           └── main.xml
+```
+
+### Main Activity
+```kotlin
+// MainActivity.kt
+import android.os.Bundle
+import dev.hotwire.navigation.activities.HotwireActivity
+import dev.hotwire.navigation.navigator.NavigatorConfiguration
+
+class MainActivity : HotwireActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_main)
+    }
+
+    override fun navigatorConfigurations() = listOf(
+        NavigatorConfiguration(
+            name = "main",
+            startLocation = "https://yourapp.com",
+            navigatorHostId = R.id.main_nav_host
+        )
+    )
+}
+```
+
+## Path Configuration
+
+### Server-Side JSON
+```json
+// public/configurations/ios_v1.json
+{
+  "settings": {
+    "screenshots_enabled": true
+  },
+  "rules": [
+    {
+      "patterns": ["/"],
+      "properties": {
+        "presentation": "default"
+      }
+    },
+    {
+      "patterns": ["/new$", "/edit$"],
+      "properties": {
+        "presentation": "modal"
+      }
+    },
+    {
+      "patterns": ["/articles/\\d+"],
+      "properties": {
+        "presentation": "push"
+      }
+    }
+  ]
+}
+```
+
+### Presentation Types
+- `default` - Standard push navigation
+- `modal` - Present as modal sheet
+- `replace` - Replace current screen
+- `pop` - Pop back
+- `refresh` - Refresh current
+- `none` - Handle in native code
+
+## Bridge Components
+
+### Rails Helper
+```ruby
+# app/helpers/hotwire_native_helper.rb
+module HotwireNativeHelper
+  def hotwire_native_app?
+    request.user_agent&.include?("Hotwire Native")
+  end
+
+  def hotwire_native_ios?
+    request.user_agent&.include?("Hotwire Native iOS")
+  end
+
+  def hotwire_native_android?
+    request.user_agent&.include?("Hotwire Native Android")
+  end
+end
+```
+
+### Conditional Rendering
+```erb
+<% if hotwire_native_app? %>
+  <%# Native-specific UI %>
+  <div data-bridge-component="navbar" data-bridge-title="<%= @article.title %>"></div>
+<% else %>
+  <%# Web navigation %>
+  <%= render "shared/navigation" %>
+<% end %>
+```
+
+### Bridge Component (JavaScript)
+```javascript
+// app/javascript/controllers/bridge/button_controller.js
+import { BridgeComponent } from "@hotwired/hotwire-native-bridge"
+
+export default class extends BridgeComponent {
+  static component = "button"
+  static targets = ["button"]
+
+  connect() {
+    super.connect()
+    this.send("connect", { title: this.buttonTarget.textContent })
+  }
+
+  // Called from native
+  clicked() {
+    this.buttonTarget.click()
+  }
+}
+```
+
+### iOS Bridge Handler
+```swift
+// ButtonComponent.swift
+import HotwireNative
+
+final class ButtonComponent: BridgeComponent {
+    override class var name: String { "button" }
+
+    override func onReceive(message: Message) {
+        guard let event = Event(rawValue: message.event) else { return }
+
+        switch event {
+        case .connect:
+            handleConnect(message: message)
+        }
+    }
+
+    private func handleConnect(message: Message) {
+        guard let data: ConnectData = message.data() else { return }
+        // Add native button to toolbar
+        addButton(title: data.title)
+    }
+
+    private func addButton(title: String) {
+        let button = UIBarButtonItem(title: title, style: .plain, target: self, action: #selector(buttonTapped))
+        delegate?.webView?.viewController?.navigationItem.rightBarButtonItem = button
+    }
+
+    @objc private func buttonTapped() {
+        reply(to: "connect", with: MessageData(action: "clicked"))
+    }
+}
+
+private extension ButtonComponent {
+    enum Event: String {
+        case connect
+    }
+
+    struct ConnectData: Decodable {
+        let title: String
+    }
+}
+```
+
+## Native Features
+
+### Pull to Refresh
+```erb
+<%# Enable in layout %>
+<body data-turbo-refresh-method="morph" data-turbo-refresh-scroll="preserve">
+```
+
+### Native Form Inputs
+```erb
+<% if hotwire_native_app? %>
+  <%= f.date_field :date, data: { bridge_component: "date-picker" } %>
+<% else %>
+  <%= f.date_field :date %>
+<% end %>
+```
+
+### Camera/Photos
+```erb
+<div data-controller="bridge--photo" data-bridge-component="photo">
+  <button data-action="bridge--photo#capture">Take Photo</button>
+  <input type="hidden" name="photo_data" data-bridge--photo-target="input">
+</div>
+```
+
+## Styling for Native
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<html class="<%= 'hotwire-native' if hotwire_native_app? %>">
+
+<%# In CSS %>
+<style>
+  /* Hide web-only elements in native */
+  .hotwire-native .web-only {
+    display: none;
+  }
+
+  /* Safe area insets */
+  .hotwire-native body {
+    padding-top: env(safe-area-inset-top);
+    padding-bottom: env(safe-area-inset-bottom);
+  }
+</style>
+```
+
+## Best Practices
+
+1. **Mobile-first design** - Views should work well on small screens
+2. **Use semantic HTML** - Native can style based on elements
+3. **Minimize JavaScript** - Let native handle interactions
+4. **Test on devices** - Simulator ≠ real device
+5. **Handle offline** - Show appropriate messages
+6. **Fast responses** - Native users expect instant feedback