rails-hyperdrive-layered-rails 0.1.0

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/gems/action-policy.md

@@ -0,0 +1,437 @@
+# Action Policy
+
+Authorization framework for Ruby and Rails applications.
+
+**GitHub**: https://github.com/palkan/action_policy
+**Layer**: Application
+
+## Contents
+
+- Installation
+- Basic Usage
+- Scoping
+- Rule Aliases
+- Minimal CRUD Rules
+- Reason Tracking with `check?`
+- Policy Composition
+- Pre-Checks
+- Authorization Context
+- Error Handling
+- Gotchas
+- Testing
+
+## Installation
+
+```ruby
+# Gemfile
+gem "action_policy"
+
+# Generate policy
+rails generate action_policy:policy Post
+```
+
+## Basic Usage
+
+### Define Policy
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  def show?
+    true
+  end
+
+  def update?
+    owner? || user.admin?
+  end
+
+  def destroy?
+    user.admin?
+  end
+
+  private
+
+  def owner?
+    record.author_id == user.id
+  end
+end
+```
+
+### Controller Integration
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+    authorize! @post
+  end
+
+  def update
+    @post = Post.find(params[:id])
+    authorize! @post
+
+    @post.update!(post_params)
+    redirect_to @post
+  end
+end
+```
+
+### View Integration
+
+```erb
+<% if allowed_to?(:update?, @post) %>
+  <%= link_to "Edit", edit_post_path(@post) %>
+<% end %>
+```
+
+## Scoping
+
+Load only authorized records:
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts = authorized_scope(Post.all)
+  end
+
+  def destroy
+    @post = authorized_scope(Post.all, as: :destroyable).find(params[:id])
+    @post.destroy!
+  end
+end
+
+class PostPolicy < ApplicationPolicy
+  # Default scope for index
+  relation_scope do |scope|
+    if user.admin?
+      scope.all
+    else
+      scope.published.or(scope.where(author: user))
+    end
+  end
+
+  # Named scope
+  relation_scope(:destroyable) do |scope|
+    user.admin? ? scope.all : scope.where(author: user)
+  end
+end
+```
+
+## Rule Aliases
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  def manage?
+    owner? || user.admin?
+  end
+
+  # Alias multiple rules to manage?
+  alias_rule :create?, :update?, :destroy?, to: :manage?
+end
+```
+
+## Minimal CRUD Rules
+
+Keep policies small. Most policies need only two rules:
+
+```ruby
+class BoardPolicy < ApplicationPolicy
+  def show?
+    # Visibility - who can see this resource
+    record.all_access? || has_access?
+  end
+
+  def manage?
+    # Management - who can modify this resource
+    board_admin?
+  end
+
+  # update?, edit?, destroy? automatically fall back to manage?
+end
+```
+
+Action Policy provides:
+- **Default rule:** `manage?` as fallback for undefined rules
+- **Default alias:** `new? -> create?`
+
+### When Custom Rules Make Sense
+
+Custom rules are appropriate for:
+
+**Domain operations** beyond CRUD:
+```ruby
+class AccountPolicy < ApplicationPolicy
+  def transfer?
+    owner? && record.transferable?
+  end
+
+  def cancel?
+    owner? || admin?
+  end
+end
+
+class ReportPolicy < ApplicationPolicy
+  def show_sources?
+    allowed_to?(:show?) && user.researcher?
+  end
+end
+```
+
+**Parent policy groupings** for related resources:
+```ruby
+class OrganizationPolicy < ApplicationPolicy
+  def manage_billing?
+    owner? || billing_admin?
+  end
+
+  def manage_members?
+    owner? || admin?
+  end
+end
+
+# Used across multiple controllers
+authorize! @organization, to: :manage_billing?
+```
+
+### When to Consider New Resources
+
+If a custom rule maps directly to a controller action with its own views and routes, consider a dedicated resource:
+
+```ruby
+# If you have:
+# POST /cards/:id/archive
+# GET /cards/:id/archive (confirmation page)
+# DELETE /cards/:id/archive (unarchive)
+
+# Consider: Cards::ArchivesController with ArchivePolicy
+# Instead of: CardPolicy#can_archive?, #can_unarchive?
+```
+
+The goal is clarity, not strict adherence to patterns.
+
+## Reason Tracking with `check?`
+
+Use `check?` instead of direct predicate calls to track failure reasons:
+
+```ruby
+class AccountPolicy < ApplicationPolicy
+  def manage?
+    check?(:admin?)  # Tracks "admin?" as failure reason
+  end
+
+  def destroy?
+    check?(:owner?)  # Tracks "owner?" as failure reason
+  end
+end
+```
+
+This enables debugging authorization failures:
+```ruby
+policy = AccountPolicy.new(user, account)
+policy.apply(:manage?)
+policy.result.reasons  #=> { admin?: false }
+```
+
+## Policy Composition
+
+Delegate to other policies for nested authorization:
+
+```ruby
+class CommentPolicy < ApplicationPolicy
+  authorize :card, optional: true
+
+  def create?
+    allowed_to?(:show?, card)  # Delegates to CardPolicy
+  end
+
+  def show?
+    allowed_to?(:show?, record.card)  # Uses record's association
+  end
+
+  def manage?
+    allowed_to?(:show?) && check?(:creator?)  # Combines both
+  end
+end
+```
+
+## Pre-Checks
+
+Run before every rule:
+
+```ruby
+class ApplicationPolicy < ActionPolicy::Base
+  pre_check :allow_admins
+
+  private
+
+  def allow_admins
+    allow! if user.admin?
+  end
+end
+```
+
+## Authorization Context
+
+For `create?` and `index?` rules where `record` isn't available, use authorization contexts:
+
+```ruby
+class WebhookPolicy < ApplicationPolicy
+  authorize :board, optional: true  # optional: only needed for create?/index?
+
+  def index?
+    allowed_to?(:manage?, board)  # Uses context
+  end
+
+  def create?
+    allowed_to?(:manage?, board)  # Uses context
+  end
+
+  def show?
+    allowed_to?(:manage?, record.board)  # Uses record
+  end
+end
+```
+
+Register contexts via controller concerns:
+
+```ruby
+module BoardScoped
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :set_board
+    authorize :board, through: -> { @board }
+  end
+
+  private
+
+  def set_board
+    @board = Current.account.boards.find_by!(slug: params[:board_id])
+    authorize! @board, to: :show?
+  end
+end
+
+class WebhooksController < ApplicationController
+  include BoardScoped
+
+  def index
+    authorize!  # Uses WebhookPolicy with board context
+    @webhooks = @board.webhooks
+  end
+end
+```
+
+## Error Handling
+
+Return 404 for visibility failures (don't leak existence), 403 for permission failures:
+
+```ruby
+module Authorization
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from ActionPolicy::Unauthorized, with: :handle_unauthorized
+  end
+
+  private
+
+  def handle_unauthorized(exception)
+    if exception.rule == :show?
+      raise ActiveRecord::RecordNotFound  # 404
+    else
+      head :forbidden  # 403
+    end
+  end
+end
+```
+
+## Gotchas
+
+### View Context Syntax
+
+Context must use `context:` hash:
+
+```ruby
+# Wrong
+allowed_to?(:create?, Webhook, board: @board)
+
+# Correct
+allowed_to?(:create?, Webhook, context: {board: @board})
+```
+
+### Optional Contexts
+
+Mark context as `optional: true` when only needed for some rules:
+
+```ruby
+authorize :board, optional: true  # Required for create?, not show?
+```
+
+## Testing
+
+### Policy Unit Tests
+
+```ruby
+# RSpec
+RSpec.describe PostPolicy do
+  let(:user) { create(:user) }
+  let(:post) { create(:post) }
+
+  describe "#update?" do
+    it "allows owner" do
+      post = create(:post, author: user)
+      expect(described_class.new(user, post).update?).to be true
+    end
+
+    it "denies non-owner" do
+      expect(described_class.new(user, post).update?).to be false
+    end
+  end
+end
+
+# Minitest
+class BoardPolicyTest < ActiveSupport::TestCase
+  test "board creator can manage" do
+    policy = BoardPolicy.new(@board, user: users(:david), account: @account)
+    assert policy.apply(:manage?)
+  end
+
+  test "create uses board context" do
+    # Pass context as named argument, no record
+    policy = WebhookPolicy.new(board: @board, user: users(:david), account: @account)
+    assert policy.apply(:create?)
+  end
+end
+```
+
+### Controller Authorization Tests
+
+```ruby
+# RSpec
+RSpec.describe PostsController do
+  include ActionPolicy::TestHelper
+
+  it "authorizes update" do
+    expect {
+      put :update, params: { id: post.id, post: { title: "New" } }
+    }.to be_authorized_to(:update?, post)
+  end
+end
+
+# Minitest
+class WebhooksControllerTest < ActionDispatch::IntegrationTest
+  include ActionPolicy::TestHelper
+
+  test "index authorizes" do
+    assert_authorized_to(:index?, Webhook) do
+      get board_webhooks_path(boards(:writebook))
+    end
+  end
+
+  test "show authorizes specific record" do
+    webhook = webhooks(:active)
+    assert_authorized_to(:show?, webhook) do
+      get board_webhook_path(webhook.board, webhook)
+    end
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/gems/active-agent.md

@@ -0,0 +1,275 @@
+# Active Agent
+
+Framework for building AI agents in Rails applications.
+
+**GitHub**: https://github.com/activeagents/activeagent
+**Layer**: Infrastructure (LLM calls) / Application (orchestration)
+
+## Contents
+
+- Installation
+- Basic Usage
+- Agents with Tools
+- System Prompts
+- Structured Output
+- Service Integration
+- Background Processing
+- Configuration
+- Testing
+- Error Handling
+
+## Installation
+
+```ruby
+# Gemfile
+gem "activeagent"
+```
+
+## Basic Usage
+
+### Define Agent
+
+```ruby
+# app/agents/application_agent.rb
+class ApplicationAgent < ActiveAgent::Base
+  # Default provider configuration
+end
+
+# app/agents/summarizer_agent.rb
+class SummarizerAgent < ApplicationAgent
+  def summarize(text, max_length: 200)
+    prompt <<~PROMPT
+      Summarize the following text in #{max_length} characters or less.
+      Maintain the key points and tone.
+
+      Text:
+      #{text}
+    PROMPT
+  end
+end
+```
+
+### Use Agent
+
+```ruby
+agent = SummarizerAgent.new
+summary = agent.summarize(article.body, max_length: 150)
+```
+
+## Agents with Tools
+
+```ruby
+class ResearchAgent < ApplicationAgent
+  tool :search_web,
+       description: "Search the web for information" do |query|
+    WebSearchService.search(query).map do |result|
+      { title: result.title, url: result.url, snippet: result.snippet }
+    end
+  end
+
+  tool :read_url,
+       description: "Read and extract content from a URL" do |url|
+    UrlReaderService.read(url)
+  end
+
+  tool :save_note,
+       description: "Save a research note" do |title, content|
+    ResearchNote.create!(title: title, content: content)
+    "Note saved: #{title}"
+  end
+
+  def research(topic)
+    prompt <<~PROMPT
+      Research the topic: #{topic}
+
+      Use the search_web tool to find relevant information.
+      Use read_url to get more details from promising results.
+      Use save_note to record important findings.
+
+      Provide a comprehensive summary of your research.
+    PROMPT
+  end
+end
+```
+
+## System Prompts
+
+```ruby
+class CustomerSupportAgent < ApplicationAgent
+  system_prompt <<~PROMPT
+    You are a helpful customer support agent for Acme Corp.
+    Be polite, professional, and helpful.
+    If you don't know something, say so honestly.
+    Never make up information about products or policies.
+  PROMPT
+
+  def respond(customer_message, context: {})
+    prompt <<~PROMPT
+      Customer: #{customer_message}
+
+      Context:
+      - Customer name: #{context[:customer_name]}
+      - Account type: #{context[:account_type]}
+      - Previous interactions: #{context[:interaction_count]}
+
+      Respond helpfully to the customer's message.
+    PROMPT
+  end
+end
+```
+
+## Structured Output
+
+```ruby
+class ClassifierAgent < ApplicationAgent
+  def classify(content)
+    response = prompt <<~PROMPT
+      Classify the following content into one of these categories:
+      - technology
+      - business
+      - entertainment
+      - sports
+      - science
+
+      Also provide a confidence score from 0 to 1.
+
+      Content: #{content}
+
+      Respond in JSON format:
+      {"category": "...", "confidence": 0.XX}
+    PROMPT
+
+    JSON.parse(response)
+  end
+end
+```
+
+## Service Integration
+
+```ruby
+class SummarizeArticle
+  def initialize(agent: SummarizerAgent.new)
+    @agent = agent
+  end
+
+  def call(article)
+    return article.summary if article.summary.present?
+
+    summary = agent.summarize(article.body)
+    article.update!(summary: summary, summarized_at: Time.current)
+    summary
+  rescue ActiveAgent::Error => e
+    Rails.logger.error("Summarization failed: #{e.message}")
+    article.body.truncate(200)  # Fallback
+  end
+
+  private
+
+  attr_reader :agent
+end
+```
+
+## Background Processing
+
+```ruby
+class SummarizeArticleJob < ApplicationJob
+  retry_on ActiveAgent::RateLimitError,
+           wait: :polynomially_longer,
+           attempts: 5
+
+  discard_on ActiveAgent::InvalidRequestError
+
+  def perform(article_id)
+    article = Article.find(article_id)
+    SummarizeArticle.new.call(article)
+  end
+end
+```
+
+## Configuration
+
+```ruby
+# config/initializers/active_agent.rb
+ActiveAgent.configure do |config|
+  config.default_provider = :anthropic
+  config.default_model = "claude-3-sonnet"
+
+  config.providers[:anthropic] = {
+    api_key: Rails.application.credentials.anthropic_api_key
+  }
+
+  config.providers[:openai] = {
+    api_key: Rails.application.credentials.openai_api_key
+  }
+end
+```
+
+## Testing
+
+```ruby
+RSpec.describe SummarizeArticle do
+  let(:article) { create(:article, body: "Long article content...") }
+
+  describe "#call" do
+    it "generates and saves summary" do
+      mock_agent = instance_double(SummarizerAgent)
+      allow(mock_agent).to receive(:summarize).and_return("Brief summary")
+
+      service = described_class.new(agent: mock_agent)
+      result = service.call(article)
+
+      expect(result).to eq("Brief summary")
+      expect(article.reload.summary).to eq("Brief summary")
+    end
+
+    it "handles API errors gracefully" do
+      mock_agent = instance_double(SummarizerAgent)
+      allow(mock_agent).to receive(:summarize)
+        .and_raise(ActiveAgent::RateLimitError)
+
+      service = described_class.new(agent: mock_agent)
+      result = service.call(article)
+
+      expect(result).to eq(article.body.truncate(200))
+    end
+  end
+end
+
+RSpec.describe ResearchAgent do
+  describe "#research" do
+    it "uses tools to gather information" do
+      agent = described_class.new
+
+      # Mock tool responses
+      allow(WebSearchService).to receive(:search)
+        .and_return([{ title: "Result", url: "http://...", snippet: "..." }])
+
+      result = agent.research("Ruby on Rails best practices")
+
+      expect(result).to be_present
+    end
+  end
+end
+```
+
+## Error Handling
+
+```ruby
+class AIService
+  def call(prompt)
+    agent.prompt(prompt)
+  rescue ActiveAgent::RateLimitError
+    # Retry after delay
+    sleep(60)
+    retry
+  rescue ActiveAgent::InvalidRequestError => e
+    # Log and return fallback
+    Rails.logger.error("Invalid AI request: #{e.message}")
+    nil
+  rescue ActiveAgent::AuthenticationError
+    # Critical - alert ops
+    Rails.logger.fatal("AI authentication failed")
+    raise
+  end
+end
+```