red64-cli 0.1.0 → 0.2.0

package/framework/stacks/rails/code-quality.md

@@ -0,0 +1,287 @@
+# Code Quality Standards
+
+Project memory for code quality conventions, testing patterns, and maintainability standards in MediaPulse.
+
+---
+
+## Linting and Style
+
+### RuboCop Configuration
+- **Style**: `rubocop-rails-omakase` - Rails default conventions
+- Configuration: `.rubocop.yml` inherits from gem
+- Run: `bundle exec rubocop`
+
+```ruby
+# .rubocop.yml pattern: inherit defaults, override sparingly
+inherit_gem: { rubocop-rails-omakase: rubocop.yml }
+
+# Only add project-specific overrides when necessary
+```
+
+### Naming Conventions
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Models | Singular, CamelCase | `Source`, `CollectedContent` |
+| Controllers | Plural + Controller | `SourcesController` |
+| Services | Action-oriented | `ContentCollectionService` |
+| Jobs | Descriptive + Job | `CollectContentJob` |
+| Tests | Subject + Test | `SourceTest` |
+
+---
+
+## Testing Patterns
+
+### Framework
+- **Minitest** (Rails default) with Capybara for system tests
+- **WebMock** for HTTP stubbing
+- Parallel execution: `parallelize(workers: :number_of_processors)`
+- Fixtures: `test/fixtures/*.yml`
+
+### Test Organization
+Tests organized by type in `test/` directory:
+- `test/models/` - Unit tests for ActiveRecord models
+- `test/controllers/` - Controller action tests
+- `test/services/` - Service object tests
+- `test/integration/` - Multi-component workflow tests
+- `test/system/` - Full browser tests (Capybara/Selenium)
+- `test/helpers/` - View helper tests
+- `test/views/` - View rendering tests
+- `test/jobs/` - Background job tests
+
+### Test Style Pattern
+```ruby
+# Pattern: Descriptive test blocks with setup and clear assertions
+class SourceTest < ActiveSupport::TestCase
+  setup do
+    # Stub external dependencies
+    stub_request(:head, /example\.com/).to_return(status: 200)
+  end
+
+  # Test naming: describe behavior, not implementation
+  test "validates url presence" do
+    project = Project.create!(name: "Test", user: users(:one))
+    source = Source.new(project: project)
+
+    assert_not source.valid?
+    assert_includes source.errors[:url], "can't be blank"
+  end
+
+  # Pattern: Test behavior scenarios, not implementation details
+  test "detects youtube.com as youtube type" do
+    project = Project.create!(name: "Test", user: users(:one))
+    source = Source.create!(url: "https://www.youtube.com/watch?v=abc123", project: project)
+
+    assert source.youtube?
+  end
+end
+```
+
+### Service Testing Pattern
+```ruby
+# Pattern: Inject dependencies for testability
+class ContentCollectionServiceTest < ActiveSupport::TestCase
+  test "returns error when source is already collecting" do
+    source = sources(:one)
+    source.update!(status: :collecting)
+
+    service = ContentCollectionService.new(source: source)
+    result = service.call
+
+    assert result.error?
+    assert_equal :already_collecting, result.error_type
+  end
+
+  # Pattern: Use dependency injection for external services
+  test "enqueues collection job on success" do
+    job_enqueued = false
+    mock_enqueuer = ->(id) { job_enqueued = true; OpenStruct.new(job_id: "test-123") }
+
+    service = ContentCollectionService.new(
+      source: source,
+      skip_credential_check: true,
+      job_enqueuer: mock_enqueuer
+    )
+
+    result = service.call
+    assert result.success?
+    assert job_enqueued
+  end
+end
+```
+
+---
+
+## Code Organization
+
+### Service Objects
+Place in `app/services/` when logic:
+- Spans multiple models
+- Involves external APIs
+- Has complex business rules
+- Needs extensive testing in isolation
+
+```ruby
+# Pattern: Result objects for service outcomes
+class ContentCollectionService
+  class Result
+    attr_reader :job_id, :error_type, :error_message
+
+    def initialize(success:, job_id: nil, error_type: nil, error_message: nil)
+      @success = success
+      @job_id = job_id
+      @error_type = error_type
+      @error_message = error_message
+      freeze
+    end
+
+    def success?
+      @success
+    end
+
+    def error?
+      !@success
+    end
+
+    # Factory methods for clarity
+    def self.success(job_id:)
+      new(success: true, job_id: job_id)
+    end
+
+    def self.error(type:, message:)
+      new(success: false, error_type: type, error_message: message)
+    end
+  end
+end
+```
+
+### Error Handling Pattern
+```ruby
+# Pattern: Custom error hierarchy for services
+class LlmService
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
+  class RateLimitError < Error; end
+  class ApiError < Error; end
+
+  # Map external errors to domain errors
+  def generate_ideas(prompt:, system_prompt: nil, model: DEFAULT_MODEL)
+    chat = build_chat(model: model, system_prompt: system_prompt)
+    response = chat.ask(prompt)
+    build_response(response)
+  rescue RubyLLM::UnauthorizedError => e
+    raise AuthenticationError, e.message
+  rescue RubyLLM::RateLimitError => e
+    raise RateLimitError, e.message
+  end
+end
+```
+
+### Model Patterns
+```ruby
+# Pattern: Lean models with clear responsibilities
+class Source < ApplicationRecord
+  # 1. Includes
+  include Turbo::Broadcastable
+
+  # 2. Associations
+  belongs_to :project
+  belongs_to :feed, optional: true
+  has_many :ideas, through: :idea_sources
+
+  # 3. Enums
+  enum :source_type, { web: 0, youtube: 1, substack: 2 }
+  enum :status, { pending: 0, collecting: 1, collected: 2, failed: 3 }
+
+  # 4. Validations
+  validates :url, presence: true, format: { with: URI::DEFAULT_PARSER.make_regexp(%w[http https]) }
+  validates :url, uniqueness: { scope: [:project_id, :feed_id], case_sensitive: false }
+
+  # 5. Scopes
+  scope :from_feed, ->(feed) { where(feed: feed) }
+  scope :manually_added, -> { where(feed: nil) }
+  scope :search, ->(query) { where("url LIKE ? OR title LIKE ?", "%#{query}%", "%#{query}%") }
+
+  # 6. Callbacks (use sparingly)
+  before_validation :detect_source_type, on: :create
+
+  # 7. Public instance methods
+  def has_full_metadata?
+    title.present? && description.present? && published_at.present?
+  end
+
+  private
+
+  # 8. Private methods
+  def detect_source_type
+    # implementation
+  end
+end
+```
+
+---
+
+## Security Analysis Tools
+
+### Static Analysis
+- **Brakeman**: Security vulnerability scanner
+  - Run: `bundle exec brakeman`
+  - Check before deployment for SQL injection, XSS, CSRF issues
+
+- **bundler-audit**: Gem vulnerability scanning
+  - Configuration: `config/bundler-audit.yml` for ignoring known issues
+  - Run: `bundle audit`
+
+### Credential Management
+- Use Rails credentials: `bin/rails credentials:edit`
+- Access: `Rails.application.credentials.dig(:service, :api_key)`
+- Never commit unencrypted secrets
+- Filter sensitive params (see `config/initializers/filter_parameter_logging.rb`)
+
+---
+
+## Documentation Standards
+
+### Method Documentation
+```ruby
+# Pattern: Document public interfaces
+# Unified service wrapping ruby_llm gem for multi-provider LLM access
+#
+# Usage:
+#   response = LlmService.generate_ideas(prompt: "...", system_prompt: "...")
+#   response.content #=> "Generated ideas..."
+#
+class LlmService
+  # Generate ideas from source content
+  #
+  # @param prompt [String] Formatted prompt with source content
+  # @param system_prompt [String, nil] System instructions
+  # @param model [String] Model identifier (default: claude-sonnet-4-20250514)
+  # @return [LlmResponse] Response with content and metadata
+  # @raise [ConfigurationError] if API key not configured
+  def generate_ideas(prompt:, system_prompt: nil, model: DEFAULT_MODEL)
+    # implementation
+  end
+end
+```
+
+---
+
+## Quality Commands
+
+```bash
+# Run all quality checks
+bundle exec rubocop          # Style
+bundle exec brakeman         # Security
+bundle exec rake test        # Tests
+bundle exec rake test:system # System tests
+
+# Development workflow
+bin/rails test               # Fast feedback
+bin/rails test test/models/  # Focused testing
+```
+
+---
+
+_Focus on patterns over exhaustive rules. Code should be readable, testable, and secure._

package/framework/stacks/rails/code-refactoring.md

@@ -0,0 +1,299 @@
+# Code Refactoring Patterns
+
+Project memory for safe code refactoring strategies in MediaPulse.
+
+---
+
+## Refactoring Philosophy
+
+Refactoring in MediaPulse follows three core principles:
+1. **Safety first**: Tests pass before and after every change
+2. **Small steps**: Incremental changes that can be reverted independently
+3. **Preserve behavior**: Refactoring changes structure, not functionality
+
+---
+
+## Extraction Patterns
+
+### Service Extraction
+
+Extract business logic from controllers/models when it:
+- Spans multiple models
+- Involves external APIs
+- Has complex business rules
+- Needs extensive testing
+
+**Pattern**: Controller to Service
+```ruby
+# Before: Fat controller action
+class CollectionsController < ApplicationController
+  def create
+    source = @project.sources.find(params[:source_id])
+    return render_error if source.collecting?
+
+    credential = Rails.application.credentials.dig(:service, :api_key)
+    return render_error("Missing credentials") if credential.blank?
+
+    source.update!(status: :collecting)
+    CollectContentJob.perform_later(source.id)
+    # ...
+  end
+end
+
+# After: Thin controller, extracted service
+class CollectionsController < ApplicationController
+  def create
+    result = ContentCollectionService.new(source: @source).call
+
+    if result.success?
+      redirect_to @source, notice: "Collection started"
+    else
+      redirect_to @source, alert: result.error_message
+    end
+  end
+end
+```
+
+**Key elements**:
+- Service returns Result object (success/error pattern)
+- Controller only handles HTTP concerns
+- Business logic fully testable in isolation
+
+### Concern Extraction
+
+Extract shared model behavior into concerns when:
+- Same logic appears in 3+ models
+- Behavior is cohesive and nameable
+- Logic is self-contained
+
+**Pattern**: Model to Concern
+```ruby
+# Before: Duplicated broadcast logic in models
+class Source < ApplicationRecord
+  after_update_commit :broadcast_status_change, if: :saved_change_to_status?
+
+  def dom_target
+    "source_#{id}"
+  end
+
+  def broadcast_status_change
+    broadcast_replace_later_to(project, target: dom_target, ...)
+  end
+end
+
+# After: Extracted concern
+# app/models/concerns/turbo_broadcastable.rb
+module TurboBroadcastable
+  extend ActiveSupport::Concern
+
+  included do
+    include Turbo::Broadcastable
+  end
+
+  def dom_target
+    "#{model_name.singular}_#{id}"
+  end
+end
+```
+
+### Strategy Pattern Extraction
+
+Use when type-based conditionals grow complex:
+
+```ruby
+# Before: Growing case statement
+def process_content(source)
+  case source.source_type
+  when :youtube then # 50 lines
+  when :web then # 40 lines
+  when :twitter then # 45 lines
+  end
+end
+
+# After: Strategy pattern via registry
+# ExtractorRegistry.for(:youtube) => YoutubeExtractor
+result = ExtractorRegistry.extract(source)
+```
+
+**Established patterns**:
+- `ExtractorRegistry` maps source types to extractors
+- `FeedTypeStrategy` provides type-specific configurations
+- New types require only adding entry to registry + implementing class
+
+---
+
+## Safe Refactoring Workflow
+
+### Step 1: Ensure Test Coverage
+
+Before refactoring, verify tests exist:
+```bash
+# Check existing coverage
+bin/rails test test/models/source_test.rb
+bin/rails test test/services/
+
+# Add characterization tests if missing
+test "current behavior for X" do
+  # Document existing behavior before changing
+end
+```
+
+### Step 2: Make Small, Reversible Changes
+
+**Good**: One concept per commit
+```
+commit 1: Extract Result class from service
+commit 2: Move validation logic to private method
+commit 3: Rename extracted method for clarity
+```
+
+**Avoid**: Large refactors that touch many files
+
+### Step 3: Verify After Each Change
+
+```bash
+# Run related tests
+bin/rails test test/services/content_collection_service_test.rb
+
+# Run full suite before pushing
+bin/rails test
+bundle exec rubocop
+```
+
+---
+
+## Dependency Injection for Testability
+
+Services use dependency injection for external calls:
+
+```ruby
+class ContentCollectionService
+  def initialize(source:, credentials_checker: nil, job_enqueuer: nil)
+    @source = source
+    @credentials_checker = credentials_checker || method(:default_credentials_checker)
+    @job_enqueuer = job_enqueuer || method(:default_job_enqueuer)
+  end
+end
+
+# In tests: inject mocks
+service = ContentCollectionService.new(
+  source: source,
+  job_enqueuer: ->(id) { OpenStruct.new(job_id: "test-123") }
+)
+```
+
+**Pattern**: Default to production behavior, override in tests.
+
+---
+
+## Refactoring Signals
+
+### When to Extract
+
+| Signal | Action |
+|--------|--------|
+| Controller action > 15 lines | Extract to service |
+| Model > 150 lines | Consider concerns or query objects |
+| Case statement > 3 branches | Consider strategy pattern |
+| Same 5+ lines in multiple places | Extract to shared method/concern |
+| External API call in model | Move to client class |
+
+### When NOT to Extract
+
+- Single-use logic that fits naturally in one place
+- Simple CRUD without business rules
+- Premature abstraction (wait for 3+ uses)
+
+---
+
+## Backward Compatibility
+
+### API Deprecation Pattern
+
+When changing public interfaces:
+
+```ruby
+# Step 1: Add new method, keep old
+def self.config_for(feed_type, custom_rules: nil)
+  # new implementation
+end
+
+# @deprecated Use config_for instead
+def self.prompt_for(feed_type, custom_rules: nil)
+  config_for(feed_type, custom_rules: custom_rules).prompt
+end
+
+# Step 2: Add deprecation warning (future release)
+# Step 3: Remove old method (after deprecation period)
+```
+
+### Database Migration Safety
+
+For schema changes that affect running code:
+
+```ruby
+# Safe: Add column with default
+add_column :sources, :priority, :integer, default: 0
+
+# Safe: Add index concurrently (PostgreSQL)
+# For SQLite: migrations run quickly, less concern
+
+# Risky: Rename column
+# Use two-step: add new, migrate data, remove old
+```
+
+---
+
+## Common Refactoring Targets
+
+### Fat Models
+
+Move to services when models handle:
+- Complex state transitions
+- Multi-model coordination
+- External service calls
+
+Keep in models:
+- Validations and associations
+- Simple scopes
+- Attribute helpers
+
+### Complex Conditionals
+
+Replace nested conditionals with:
+- Guard clauses (early returns)
+- Strategy/registry patterns
+- Polymorphism where appropriate
+
+### Test Duplication
+
+Extract to test helpers:
+```ruby
+# test/test_helper.rb
+def stub_external_services
+  stub_request(:head, /example\.com/).to_return(status: 200)
+end
+```
+
+---
+
+## Refactoring Checklist
+
+Before starting:
+- [ ] Tests pass for affected code
+- [ ] Understand current behavior fully
+- [ ] Plan incremental steps
+
+During refactoring:
+- [ ] One logical change per commit
+- [ ] Tests pass after each step
+- [ ] No behavior changes (unless intentional)
+
+After completing:
+- [ ] Full test suite passes
+- [ ] RuboCop passes
+- [ ] Manual smoke test of affected features
+
+---
+
+_Refactoring improves code structure while preserving behavior. Small, tested steps over large rewrites._

package/framework/stacks/rails/feedback.md

@@ -0,0 +1,130 @@
+# Feedback Configuration
+
+Project-specific commands for automated feedback during Rails implementation.
+
+---
+
+## Test Commands
+
+Commands to run tests during implementation. The agent will use these to verify code changes.
+
+```yaml
+# Primary test command (REQUIRED)
+test: bin/rails test
+
+# Test with verbose output
+test_verbose: bin/rails test -v
+
+# Run specific test file (use {file} as placeholder)
+test_file: bin/rails test {file}
+
+# Run system tests (browser-based)
+test_system: bin/rails test:system
+
+# Run all tests including system
+test_all: bin/rails test:all
+```
+
+---
+
+## Linting Commands
+
+Commands for code quality checks.
+
+```yaml
+# Primary lint command (RuboCop)
+lint: bundle exec rubocop
+
+# Lint with auto-fix
+lint_fix: bundle exec rubocop -A
+
+# Security check (Brakeman)
+security: bundle exec brakeman -q
+
+# Bundle audit for dependencies
+bundle_audit: bundle exec bundle-audit check --update
+```
+
+---
+
+## Development Server
+
+Commands for starting the development server (required for UI verification).
+
+```yaml
+# Start dev server (Rails)
+dev_server: bin/rails server
+
+# Dev server port
+dev_port: 3000
+
+# Dev server base URL
+dev_url: http://localhost:3000
+
+# Start with binding (for Docker)
+dev_server_docker: bin/rails server -b 0.0.0.0
+```
+
+---
+
+## Database Commands
+
+Commands for database operations.
+
+```yaml
+# Run migrations
+db_migrate: bin/rails db:migrate
+
+# Setup test database
+db_test_prepare: bin/rails db:test:prepare
+
+# Reset database
+db_reset: bin/rails db:reset
+```
+
+---
+
+## UI Verification
+
+Settings for agent-browser UI verification.
+
+```yaml
+# Enable UI verification for this project
+ui_verification_enabled: true
+
+# Default wait time after navigation (milliseconds)
+navigation_wait: 3000
+
+# Screenshot directory
+screenshot_dir: /tmp/ui-captures
+
+# Common routes to verify
+routes:
+  - /
+  - /health
+```
+
+---
+
+## Asset Pipeline
+
+Commands for asset management.
+
+```yaml
+# Precompile assets
+assets_precompile: bin/rails assets:precompile
+
+# Clean assets
+assets_clean: bin/rails assets:clean
+```
+
+---
+
+## Notes
+
+- Uses Minitest by default (or RSpec if configured)
+- RuboCop for Ruby style enforcement
+- Brakeman for security scanning
+- Rails dev server on port 3000 by default
+- System tests use Capybara with Selenium
+- For Hotwire/Turbo projects, UI verification is essential