source_monitor 0.2.0 → 0.3.0

data/.claude/skills/rails-presenter/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: rails-presenter
+description: Creates presenter objects for view formatting using SimpleDelegator pattern with TDD. Use when extracting view logic from models, formatting data for display, creating badges/labels, or when user mentions presenters, view models, formatting, or display helpers.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Rails Presenter Generator (TDD)
+
+Creates presenters that wrap models for view-specific formatting with tests first.
+
+## Quick Start
+
+1. Write failing test in `test/presenters/`
+2. Run test to confirm RED
+3. Implement presenter extending `BasePresenter`
+4. Run test to confirm GREEN
+
+## Project Conventions
+
+Presenters in this project:
+- Extend `BasePresenter < SimpleDelegator`
+- Include ActionView helpers for formatting
+- Delegate model methods via SimpleDelegator
+- Return HTML-safe strings for badges/formatted output
+- Use I18n for all user-facing text
+
+## BasePresenter (Already Exists)
+
+```ruby
+# app/presenters/base_presenter.rb
+class BasePresenter < SimpleDelegator
+  include ActionView::Helpers::NumberHelper
+  include ActionView::Helpers::DateHelper
+  include ActionView::Helpers::UrlHelper
+  include ActionView::Helpers::TagHelper
+  include ActionView::Helpers::TextHelper
+
+  def initialize(model, view_context = nil)
+    super(model)
+    @view_context = view_context
+  end
+
+  def model
+    __getobj__
+  end
+
+  alias_method :object, :model
+end
+```
+
+## TDD Workflow
+
+### Step 1: Create Presenter Test (RED)
+
+```ruby
+# test/presenters/event_presenter_test.rb
+require "test_helper"
+
+class EventPresenterTest < ActiveSupport::TestCase
+  setup do
+    @event = events(:one)
+    @presenter = EventPresenter.new(@event)
+  end
+
+  test "delegates to the model" do
+    assert_equal @event.name, @presenter.name
+  end
+
+  test "responds to model methods" do
+    assert_respond_to @presenter, :name
+    assert_respond_to @presenter, :status
+    assert_respond_to @presenter, :created_at
+  end
+
+  test "exposes the underlying model" do
+    assert_equal @event, @presenter.model
+  end
+
+  test "#display_name returns the formatted name" do
+    assert_equal @event.name, @presenter.display_name
+  end
+
+  test "#formatted_date returns formatted date when present" do
+    @event.update(event_date: Date.new(2026, 7, 15))
+    result = @presenter.formatted_date
+    assert_includes result, "2026"
+  end
+
+  test "#formatted_date returns placeholder when nil" do
+    @event.update(event_date: nil)
+    result = @presenter.formatted_date
+    assert_includes result, "text-slate-400"
+    assert_includes result, "italic"
+  end
+
+  test "#status_badge returns HTML-safe string" do
+    assert_predicate @presenter.status_badge, :html_safe?
+  end
+
+  test "#status_badge includes status text" do
+    assert_includes @presenter.status_badge, @event.status.humanize
+  end
+
+  test "#status_badge uses correct color for active" do
+    @event.update(status: :active)
+    presenter = EventPresenter.new(@event)
+    assert_includes presenter.status_badge, "bg-green-100"
+  end
+
+  test "#status_badge uses correct color for inactive" do
+    @event.update(status: :inactive)
+    presenter = EventPresenter.new(@event)
+    assert_includes presenter.status_badge, "bg-red-100"
+  end
+
+  test "#formatted_amount formats cents as currency" do
+    @event.update(amount_cents: 15000)
+    assert_equal "150,00 EUR", @presenter.formatted_amount
+  end
+end
+```
+
+### Step 2: Run Test (Confirm RED)
+
+```bash
+bin/rails test test/presenters/event_presenter_test.rb
+```
+
+### Step 3: Implement Presenter (GREEN)
+
+```ruby
+# app/presenters/event_presenter.rb
+class EventPresenter < BasePresenter
+  STATUS_COLORS = {
+    active: "bg-green-100 text-green-800",
+    inactive: "bg-red-100 text-red-800",
+    pending: "bg-yellow-100 text-yellow-800"
+  }.freeze
+
+  DEFAULT_COLOR = "bg-slate-100 text-slate-800"
+
+  def display_name
+    name
+  end
+
+  def formatted_date
+    return not_specified_span if event_date.nil?
+    I18n.l(event_date, format: :long)
+  end
+
+  def status_badge
+    tag.span(
+      status_text,
+      class: "inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium #{status_color}"
+    )
+  end
+
+  def formatted_amount
+    return "0,00 EUR" if amount_cents.nil? || amount_cents.zero?
+    number_to_currency(
+      amount_cents / 100.0,
+      unit: "EUR",
+      separator: ",",
+      delimiter: " ",
+      format: "%n %u"
+    )
+  end
+
+  private
+
+  def status_text
+    I18n.t("activerecord.attributes.event.statuses.#{status}", default: status.to_s.humanize)
+  end
+
+  def status_color
+    STATUS_COLORS.fetch(status.to_sym, DEFAULT_COLOR)
+  end
+
+  def not_specified_span
+    tag.span(
+      I18n.t("presenters.common.not_specified"),
+      class: "text-slate-400 italic"
+    )
+  end
+end
+```
+
+### Step 4: Run Test (Confirm GREEN)
+
+```bash
+bin/rails test test/presenters/event_presenter_test.rb
+```
+
+## Common Presenter Methods
+
+### Date Formatting
+
+```ruby
+def formatted_event_date
+  return not_specified_span if event_date.nil?
+  I18n.l(event_date, format: :long)
+end
+
+def short_date
+  return "\u2014" if event_date.nil?
+  event_date.strftime("%d/%m/%Y")
+end
+```
+
+### Currency Formatting
+
+```ruby
+def formatted_budget
+  return not_specified_span if budget_cents.nil?
+  number_to_currency(
+    budget_cents / 100.0,
+    unit: "EUR",
+    separator: ",",
+    delimiter: " ",
+    format: "%n %u",
+    precision: 0
+  )
+end
+```
+
+### Badge/Tag Generation
+
+```ruby
+def type_badge
+  tag.span(
+    display_type,
+    class: "inline-flex items-center px-2 py-1 rounded text-xs font-medium #{type_color}"
+  )
+end
+```
+
+### Contact Links
+
+```ruby
+def display_email
+  return not_specified_span if email.blank?
+  mail_to(email, email, class: "text-blue-600 hover:underline")
+end
+
+def display_phone
+  return not_specified_span if phone.blank?
+  link_to(phone, "tel:#{phone}", class: "text-blue-600 hover:underline")
+end
+```
+
+## Usage in Controllers
+
+```ruby
+# Single resource
+@event = EventPresenter.new(@event)
+
+# Collection
+@events = events.map { |e| EventPresenter.new(e) }
+
+# With view context (for route helpers)
+@event = EventPresenter.new(@event, view_context)
+```
+
+## Checklist
+
+- [ ] Test written first (RED)
+- [ ] Extends `BasePresenter`
+- [ ] Delegation tested
+- [ ] HTML output is `html_safe`
+- [ ] Uses I18n for all text
+- [ ] Currency stored in cents, displayed formatted
+- [ ] Color mappings use constants (Open/Closed)
+- [ ] `not_specified_span` for nil values
+- [ ] All tests GREEN

data/.claude/skills/rails-query-object/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: rails-query-object
+description: Creates query objects for complex database queries following TDD. Use when encapsulating complex queries, aggregating statistics, building reports, or when user mentions queries, stats, dashboards, or data aggregation.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Rails Query Object Generator (TDD)
+
+Creates query objects that encapsulate complex database queries with tests first.
+
+## Quick Start
+
+1. Write failing test in `test/queries/`
+2. Run test to confirm RED
+3. Implement query object in `app/queries/`
+4. Run test to confirm GREEN
+
+## When to Use Query Objects vs Scopes
+
+| Scenario | Use |
+|----------|-----|
+| Simple WHERE clause | **Scope** on the model |
+| Single-condition filter | **Scope** on the model |
+| Multi-table joins with conditions | **Query object** |
+| Dashboard aggregations | **Query object** |
+| Report generation | **Query object** |
+| Queries needing constructor params | **Query object** |
+| Reusable across controllers | **Query object** |
+
+**Rule of thumb:** If the query fits in one line and needs no context, use a scope. If it needs parameters, joins multiple tables, or returns computed data, use a query object.
+
+## Project Conventions
+
+Query objects in this project:
+- Accept context via constructor (`user:` or `account:`)
+- Return `ActiveRecord::Relation` for chainability OR `Hash` for aggregations
+- Have a `call` method for primary operation
+- Support multi-tenancy (scoped to account)
+
+## TDD Workflow
+
+### Step 1: Create Query Test (RED)
+
+```ruby
+# test/queries/stale_leads_query_test.rb
+require "test_helper"
+
+class StaleLeadsQueryTest < ActiveSupport::TestCase
+  setup do
+    @account = accounts(:one)
+    @other_account = accounts(:two)
+  end
+
+  test "requires an account parameter" do
+    assert_raises(ArgumentError) { StaleLeadsQuery.new }
+  end
+
+  test "#call returns ActiveRecord::Relation" do
+    query = StaleLeadsQuery.new(account: @account)
+    assert_kind_of ActiveRecord::Relation, query.call
+  end
+
+  test "#call returns only leads for the account (multi-tenant)" do
+    own_lead = leads(:stale_one)
+    other_lead = leads(:other_account_stale)
+
+    results = StaleLeadsQuery.new(account: @account).call
+
+    assert_includes results, own_lead
+    assert_not_includes results, other_lead
+  end
+
+  test "#call returns only stale leads" do
+    stale = leads(:stale_one)
+    fresh = leads(:fresh_one)
+
+    results = StaleLeadsQuery.new(account: @account).call
+
+    assert_includes results, stale
+    assert_not_includes results, fresh
+  end
+
+  test "multi-tenant isolation" do
+    other_query = StaleLeadsQuery.new(account: @other_account)
+    own_query = StaleLeadsQuery.new(account: @account)
+
+    assert_empty(other_query.call.where(id: leads(:stale_one).id))
+    assert_not_empty(own_query.call.where(id: leads(:stale_one).id))
+  end
+end
+```
+
+### Step 2: Run Test (Confirm RED)
+
+```bash
+bin/rails test test/queries/stale_leads_query_test.rb
+```
+
+### Step 3: Implement Query Object (GREEN)
+
+```ruby
+# app/queries/stale_leads_query.rb
+class StaleLeadsQuery
+  attr_reader :account
+
+  def initialize(account:)
+    @account = account
+  end
+
+  def call
+    account.leads.stale
+  end
+end
+```
+
+### Step 4: Run Test (Confirm GREEN)
+
+```bash
+bin/rails test test/queries/stale_leads_query_test.rb
+```
+
+## Query Object Patterns
+
+### Pattern 1: Simple Filtered Query
+
+```ruby
+# app/queries/stale_leads_query.rb
+class StaleLeadsQuery
+  attr_reader :account
+
+  def initialize(account:)
+    @account = account
+  end
+
+  def call
+    account.leads.stale
+  end
+end
+```
+
+### Pattern 2: Aggregation Query (Multiple Methods)
+
+```ruby
+# app/queries/dashboard_stats_query.rb
+class DashboardStatsQuery
+  attr_reader :user, :account
+
+  def initialize(user:)
+    @user = user
+    @account = user.account
+  end
+
+  def upcoming_events(limit: 3)
+    account.events
+      .where("event_date >= ?", Date.today)
+      .order(event_date: :asc)
+      .limit(limit)
+  end
+
+  def pending_commissions_total
+    EventVendor
+      .joins(:event)
+      .where(events: { account_id: account.id })
+      .where(commission_status: :to_invoice)
+      .sum(:commission_value)
+  end
+
+  def top_vendors(limit: 5)
+    account.vendors
+      .left_joins(:event_vendors)
+      .select("vendors.*, COUNT(event_vendors.id) as events_count")
+      .group("vendors.id")
+      .order("events_count DESC")
+      .limit(limit)
+  end
+
+  def leads_by_status
+    account.leads.group(:status).count
+  end
+end
+```
+
+### Pattern 3: Grouping Query
+
+```ruby
+# app/queries/leads_by_status_query.rb
+class LeadsByStatusQuery
+  attr_reader :account
+
+  def initialize(account:)
+    @account = account
+  end
+
+  def call
+    leads = account.leads.order(created_at: :desc)
+    result = Lead.statuses.keys.map(&:to_sym).index_with { [] }
+
+    leads.group_by(&:status).each do |status, status_leads|
+      result[status.to_sym] = status_leads
+    end
+
+    result
+  end
+end
+```
+
+### Testing Aggregation Queries
+
+```ruby
+# test/queries/dashboard_stats_query_test.rb
+require "test_helper"
+
+class DashboardStatsQueryTest < ActiveSupport::TestCase
+  setup do
+    @user = users(:one)
+    @query = DashboardStatsQuery.new(user: @user)
+  end
+
+  test "#upcoming_events returns future events only" do
+    results = @query.upcoming_events
+    results.each do |event|
+      assert event.event_date >= Date.today
+    end
+  end
+
+  test "#upcoming_events respects limit" do
+    results = @query.upcoming_events(limit: 2)
+    assert results.size <= 2
+  end
+
+  test "#leads_by_status returns hash of status to count" do
+    result = @query.leads_by_status
+    assert_kind_of Hash, result
+  end
+
+  test "scoped to user account only" do
+    other_user = users(:other_account)
+    other_query = DashboardStatsQuery.new(user: other_user)
+
+    own_events = @query.upcoming_events
+    other_events = other_query.upcoming_events
+
+    own_events.each do |event|
+      assert_equal @user.account_id, event.account_id
+    end
+  end
+end
+```
+
+## Usage in Controllers
+
+```ruby
+# Simple query
+def index
+  @leads_by_status = LeadsByStatusQuery.new(account: current_account).call
+end
+
+# Aggregation query with presenter
+def index
+  stats_query = DashboardStatsQuery.new(user: current_user)
+  @stats = DashboardStatsPresenter.new(stats_query)
+end
+```
+
+## Directory Structure
+
+```
+app/queries/
+  stale_leads_query.rb
+  leads_by_status_query.rb
+  dashboard_stats_query.rb
+  events/
+    upcoming_query.rb
+    by_vendor_query.rb
+test/queries/
+  stale_leads_query_test.rb
+  dashboard_stats_query_test.rb
+```
+
+## Checklist
+
+- [ ] Test written first (RED)
+- [ ] Constructor accepts context (`user:` or `account:`)
+- [ ] Multi-tenant isolation tested
+- [ ] Return type documented
+- [ ] Methods have clear, descriptive names
+- [ ] Complex queries use `.includes()` to prevent N+1
+- [ ] Database-agnostic (no PostgreSQL-specific SQL)
+- [ ] All tests GREEN