ask-rails-harness 0.1.0

data/lib/ask/rails/harness.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "rails"
+require "ask/agent"
+require "ask/auth"
+
+module Ask
+  module Rails
+    module Harness
+      class << self
+        def configure
+          yield configuration
+        end
+
+        def configuration
+          @configuration ||= Configuration.new
+        end
+
+        def agent_session(**extra)
+          # Auto-prune if configured
+          cleanup! if configuration.max_session_age || configuration.max_sessions
+
+          tools = configuration.tools.map { |t| t.is_a?(Class) ? t.new : t }
+          prompt = extra.delete(:system_prompt) || configuration.system_prompt || default_system_prompt
+
+          # Resolve environment-specific permissions and wire into agent hooks
+          hooks = build_environment_hooks
+
+          Ask::Agent::Session.new(
+            model: configuration.default_model,
+            max_turns: configuration.max_turns,
+            system_prompt: prompt,
+            tools: tools,
+            state: configuration.persistence_adapter,
+            hooks: hooks,
+            **extra
+          )
+        end
+
+        def discover_tools!
+          self.configuration.tools = Ask::Tools::Shell::TOOLS.map(&:new) + core_rails_tools + discovered_user_tools
+        end
+
+        # Prune old sessions and audit logs based on configuration limits.
+        #
+        # Removes sessions older than +max_session_age+ seconds, and limits the
+        # total number of sessions to +max_sessions+ (deleting the oldest first).
+        # Audit log entries older than the oldest kept session are also removed.
+        #
+        # Call manually via rake task or cron, or configure limits to auto-prune
+        # on agent_session creation.
+        def cleanup!
+          prune_old_sessions
+          limit_session_count
+        end
+
+        def root
+          @root ||= Pathname.new(File.expand_path("../..", __dir__))
+        end
+
+        private
+
+        def build_environment_hooks
+          env_mode = configuration.effective_mode
+          return {} unless env_mode
+
+          perms = Ask::Agent::Extensions::Permissions.new(mode: env_mode)
+          { before_tool: [perms.method(:before_tool_call)] }
+        rescue ArgumentError => e
+          warn "[ask-rails-harness] Invalid environment mode: #{e.message}"
+          {}
+        end
+
+        def prune_old_sessions
+          age = configuration.max_session_age
+          return unless age&.> 0
+          return unless persistence_available?
+
+          cutoff = age.seconds.ago
+          count = 0
+
+          configuration.persistence_adapter.list.each do |id|
+            data = configuration.persistence_adapter.load(id)
+            created = data&.dig(:metadata, :created_at)
+            if created && Time.parse(created) < cutoff
+              configuration.persistence_adapter.delete(id)
+              count += 1
+            end
+          end
+
+          count
+        rescue StandardError
+          nil
+        end
+
+        def limit_session_count
+          max = configuration.max_sessions
+          return unless max&.> 0
+          return unless persistence_available?
+
+          sessions = configuration.persistence_adapter.list
+          excess = sessions.size - max
+          return unless excess > 0
+
+          # Delete oldest sessions first
+          with_timestamps = sessions.map { |id|
+            data = configuration.persistence_adapter.load(id)
+            created = data&.dig(:metadata, :created_at)
+            [id, created ? Time.parse(created) : Time.at(0)]
+          }.sort_by(&:last)
+
+          with_timestamps.first(excess).each do |id, _|
+            configuration.persistence_adapter.delete(id)
+          end
+
+          excess
+        rescue StandardError
+          nil
+        end
+
+        def persistence_available?
+          defined?(ActiveRecord::Base) &&
+            ActiveRecord::Base.connection.data_source_exists?("ask_sessions")
+        rescue StandardError
+          false
+        end
+
+        def core_rails_tools
+          CORE_RAILS_TOOLS.map(&:new)
+        end
+
+        def discovered_user_tools
+          tools = []
+          files = Dir[::Rails.root.join("app", "tools", "*.rb")]
+          files.each do |f|
+            require f
+            klass = File.basename(f, ".rb").camelize.constantize rescue next
+            tools << klass if klass < Ask::Rails::Harness::Tool
+          end
+          tools
+        rescue
+          tools
+        end
+
+        def default_system_prompt
+          <<~PROMPT
+            You are a Ruby on Rails software engineer.
+            You have direct access to the application's code, database, and runtime.
+            Use your tools to inspect and modify the codebase.
+            Once you have enough information, stop calling tools and give your answer.
+          PROMPT
+        end
+      end
+    end
+  end
+end
+
+require_relative "harness/version"
+require_relative "harness/engine"
+require_relative "harness/configuration"
+require_relative "harness/audit_log"
+require_relative "harness/environment_permissions"
+require_relative "harness/auth"
+require_relative "harness/persistence"
+require_relative "harness/service_discovery"
+require_relative "harness/tool"
+require_relative "harness/tools/read_file"
+require_relative "harness/tools/run_command"
+require_relative "harness/tools/search_codebase"
+require_relative "harness/tools/read_routes"
+require_relative "harness/tools/query_database"
+require_relative "harness/tools/read_model"
+require_relative "harness/tools/read_log"
+require_relative "harness/tools/schema_graph"
+require_relative "harness/tools/route_inspector"
+
+# Railtie is loaded only when Rails is fully available
+if defined?(::Rails::Railtie)
+  require_relative "harness/railtie"
+end
+
+# Define after all tool files are loaded so the constants resolve
+Ask::Rails::Harness::CORE_RAILS_TOOLS = [
+  Ask::Rails::Harness::Tools::ReadFile, Ask::Rails::Harness::Tools::RunCommand,
+  Ask::Rails::Harness::Tools::SearchCodebase, Ask::Rails::Harness::Tools::ReadRoutes,
+  Ask::Rails::Harness::Tools::QueryDatabase, Ask::Rails::Harness::Tools::ReadModel,
+  Ask::Rails::Harness::Tools::ReadLog, Ask::Rails::Harness::Tools::SchemaGraph,
+  Ask::Rails::Harness::Tools::RouteInspector
+].freeze

data/lib/ask/skills/rails.db_debug/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: rails.db_debug
+description: Step-by-step methodology for debugging database performance issues in Rails
+---
+
+Use this skill when investigating slow queries, N+1 problems, missing indexes, or
+general database performance issues in a Rails application.
+
+## Step 1: Identify the Slow Queries
+
+Use `ReadLog.new.call(lines: 200, search: "SELECT")` to find recent database
+queries in the application log. Look for:
+
+- Queries taking > 100ms (look for "duration:" or "↳" markers in Rails logs)
+- Repetitive queries with the same structure (potential N+1)
+- Queries running in loops (same query, different IDs)
+
+If you need more detail, narrow the search: `ReadLog.new.call(lines: 500, level: "WARN")`.
+
+## Step 2: Understand the Schema
+
+For each model involved in the slow queries, inspect it:
+
+```ruby
+ReadModel.new.call(name: "User")
+ReadModel.new.call(name: "Post")
+```
+
+Focus on:
+- **Columns** — are there columns that look like foreign keys without indexes?
+- **Associations** — what associations exist and what `class_name` do they use?
+- **Validators** — any database-level constraints that could be missing?
+
+Run `ReadModel.new.call(name: "User", detail: "columns")` if you only need columns.
+
+## Step 3: Check for Missing Indexes
+
+Query the database for actual indexes:
+
+```ruby
+QueryDatabase.new.call(
+  sql: "SELECT tablename, indexname, indexdef FROM pg_indexes WHERE schemaname = 'public' ORDER BY tablename, indexname",
+  limit: 200
+)
+```
+
+Look for:
+- Foreign key columns that lack indexes (e.g. `user_id` without index)
+- Columns used in `WHERE` clauses without indexes
+- Composite indexes that could cover multiple query patterns
+
+If an index is missing, check if adding one would help:
+```ruby
+QueryDatabase.new.call(
+  sql: "EXPLAIN ANALYZE SELECT * FROM posts WHERE user_id = 1",
+  limit: 10
+)
+```
+
+## Step 4: Detect N+1 Queries
+
+N+1 manifests as the same query repeated with different IDs:
+
+```ruby
+# Search for repetitive query patterns
+ReadLog.new.call(lines: 500, search: "WHERE.*IN")
+```
+
+Common N+1 patterns:
+- Loading `Post.all` then accessing `post.comments` individually
+- Loading `User.all` then accessing `user.profile` individually
+- Serializing associations in views without eager loading
+
+Fix with `.includes(:association)`, `.eager_load(:association)`, or
+`.preload(:association)`.
+
+## Step 5: Profile Slow Queries with EXPLAIN
+
+For any identified slow query, get the execution plan:
+
+```ruby
+QueryDatabase.new.call(
+  sql: "EXPLAIN (ANALYZE, BUFFERS) SELECT posts.* FROM posts WHERE posts.user_id = 1 ORDER BY posts.created_at DESC LIMIT 20",
+  limit: 10
+)
+```
+
+What to look for in explain output:
+- **Sequential scans** (`Seq Scan`) — missing index
+- **Sort operations** — missing index on sort column
+- **Nested loop joins** with high row counts — missing composite index
+- **Bitmap heap scans** with high costs — index may be suboptimal
+
+If `ANALYZE` takes too long, use `EXPLAIN (BUFFERS)` without `ANALYZE` for cost estimates.
+
+## Step 6: Check Bulk Loading and Batch Operations
+
+If the issue involves importing or updating many records:
+
+```ruby
+QueryDatabase.new.call(
+  sql: "SELECT schemaname, tablename, seq_scan, seq_tup_read, idx_scan, idx_tup_fetch FROM pg_stat_user_tables ORDER BY seq_scan DESC",
+  limit: 20
+)
+```
+
+High `seq_scan` counts compared to `idx_scan` indicate tables where indexes
+are missing and sequential scans are happening frequently.
+
+## Failure Mode Guide
+
+| Symptom | Likely Cause | Action |
+|---------|-------------|--------|
+| Query takes >1s | Missing index on WHERE column | Check pg_indexes, add index |
+| Same query 50x in log | N+1 in controller/view | Add `.includes()` |
+| Query slow AFTER adding index | Wrong index type or order | Verify index column order matches query |
+| `EXPLAIN ANALYZE` hanging | Table lock or very large table | Use `EXPLAIN (BUFFERS)` without ANALYZE |
+| Missing `pg_indexes` output | Not Postgres | Use `SHOW INDEX FROM <table>` for MySQL |

data/lib/ask/skills/rails.deploy_pipeline/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: rails.deploy_pipeline
+description: Pre-deployment checklist for Rails applications — migrations, assets, credentials, jobs, and logs
+---
+
+Use this skill before or during a Rails deployment to ensure nothing is missed.
+Follow the steps in order — each builds on the previous.
+
+## Step 1: Check Pending Migrations
+
+Before deploying, always check for unapplied migrations:
+
+```ruby
+RunCommand.new.call(command: "bin/rails db:migrate:status | grep 'down'")
+```
+
+If there are pending migrations:
+1. Review them with `ReadFile.new.call(path: "db/migrate/<TIMESTAMP>_migration_name.rb")`
+2. Verify they're reversible: check `change`, `up`/`down`, or `reversible` blocks
+3. Check for data migrations (e.g., backfills) that should run separately
+4. Estimate execution time — large tables may need locking strategy
+
+## Step 2: Verify Assets Pipeline
+
+For Rails with assets (Sprockets or Propshaft):
+
+```ruby
+# Precompile locally to catch errors early
+RunCommand.new.call(command: "bin/rails assets:precompile 2>&1")
+```
+
+Check for:
+- Missing asset references (SCSS variables, image references)
+- JavaScript compilation errors
+- Asset fingerprint changes (manifold fingerprints if CSS changed)
+
+For importmap or esbuild/vite setups:
+
+```ruby
+# Check build config
+ReadFile.new.call(path: "package.json")
+ReadFile.new.call(path: "vite.config.ts") if File.exist?("Rails.root.join('vite.config.ts')")
+```
+
+## Step 3: Review Credentials and Secrets
+
+Verify that all required credentials exist in the target environment:
+
+```ruby
+# For production credentials
+RunCommand.new.call(command: "bin/rails credentials:show --environment production 2>&1")
+```
+
+Check for common secrets that may need updating:
+- `secret_key_base`
+- `database_password`
+- Third-party API keys (AWS, Stripe, SendGrid, etc.)
+- JWT signing keys
+- Any env vars referenced in `config/` files that aren't in credentials
+
+## Step 4: Check Background Jobs
+
+Review sidekiq/active job configuration before deploy:
+
+```ruby
+# Check job files for any that need queue configuration
+Glob.new.call(pattern: "app/jobs/**/*.rb")
+```
+
+For any new or modified jobs:
+1. Verify the queue adapter is configured in `production.rb`
+2. Check for job retry logic that might affect rollback
+3. Review `ReadFile.new.call(path: "config/sidekiq.yml")` if using Sidekiq
+4. Verify scheduled/cron jobs if using `sidekiq-cron` or `whenever`
+
+## Step 5: Review Production Log for Pre-deploy Issues
+
+Check that the current production environment is healthy before deploying:
+
+```ruby
+ReadLog.new.call(lines: 100, level: "ERROR")
+```
+
+If there are recent errors, investigate before deploying more changes.
+
+## Step 6: Verify Dependencies and Gem Versions
+
+Check for critical gem updates or changes:
+
+```ruby
+# Review Gemfile for new/modified gems
+RunCommand.new.call(command: "git diff HEAD -- Gemfile")
+```
+
+If adding a gem that needs system dependencies or native extensions:
+```ruby
+RunCommand.new.call(command: "bundle platform")
+```
+
+## Step 7: Config File Checklist
+
+Verify configuration files for the target environment:
+
+```ruby
+ReadFile.new.call(path: "config/environments/production.rb")
+ReadFile.new.call(path: "config/database.yml")
+ReadFile.new.call(path: "config/cable.yml") if File.exist?("config/cable.yml")
+ReadFile.new.call(path: "config/storage.yml") if File.exist?("config/storage.yml")
+```
+
+Key production checks:
+- `config.force_ssl = true`
+- `config.consider_all_requests_local = false`
+- Proper cache store configured (`:mem_cache_store`, `:redis_cache_store`)
+- Active Storage service configured for production
+
+## Step 8: Quick Rollback Checklist
+
+Before deploying, know how to roll back:
+
+1. **Database**: `RunCommand.new.call(command: "bin/rails db:migrate:down VERSION=<previous>")`
+2. **Code**: Git revert the deploy commit
+3. **Assets**: Previous version's assets should still be cached
+4. **Jobs**: Check if backward-incompatible changes won't replay failed jobs
+5. **Feature flags**: If using flipper or similar, toggle off new features first

data/lib/ask/skills/rails.route_trouble/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: rails.route_trouble
+description: Step-by-step methodology for debugging routing issues in Rails
+---
+
+Use this skill when a route is returning 404, you're getting route matching errors,
+or routes aren't behaving as expected in a Rails application.
+
+## Step 1: Read the Routes File
+
+Start by examining the routes configuration:
+
+```ruby
+ReadRoutes.new.call
+```
+
+This reads `config/routes.rb` — the source of truth for all route definitions.
+
+Look for:
+- The overall structure (namespaced, nested, shallow routes?)
+- Resources that might be missing
+- Constraints or conditions that could block matching
+- Route ordering (more specific routes should come before less specific)
+
+## Step 2: Check the Compiled Routes
+
+Rails routes have a specific matching order. Use `RunCommand` to inspect the live routes:
+
+```ruby
+RunCommand.new.call(command: "bin/rails routes")
+```
+
+If you know the path you're trying to match, grep for it:
+
+```ruby
+RunCommand.new.call(command: "bin/rails routes | grep users")
+```
+
+For a specific route name:
+
+```ruby
+RunCommand.new.call(command: "bin/rails routes --grep user_profile")
+```
+
+## Step 3: Check Route Parameters and Constraints
+
+Routes often fail because of parameter mismatches or constraints. Check for:
+
+**Required parameters:** Does the route define `:id` but the URL doesn't include it?
+
+**Format constraints:** Routes with `:format` (like `.json`, `.html`) constraints
+can fail silently. Check if there's a default format:
+
+```ruby
+# In routes.rb:
+resources :posts, defaults: { format: :json }
+```
+
+**Constraint classes:** Custom route constraints like `subdomain` or request-based
+constraints can prevent matching:
+
+```ruby
+# In routes.rb:
+get "admin", to: "admin/dashboard#show", constraints: ->(req) { req.subdomain == "admin" }
+```
+
+Check the constraints against the actual request parameters.
+
+## Step 4: Trace the Match
+
+For a failing request, trace how Rails would match it:
+
+```ruby
+RunCommand.new.call(
+  command: "bin/rails runner \"puts Rails.application.routes.recognize_path('/users/1/edit', method: :get)\""
+)
+```
+
+This will raise `ActionController::RoutingError` if no route matches — the
+error message tells you what routes were tried before failing.
+
+If the route exists but the controller isn't found:
+
+```ruby
+ReadFile.new.call(path: "app/controllers/users_controller.rb")
+```
+
+## Step 5: Check Namespace and Module Nesting
+
+Routes in namespaced controllers fail when the controller file is in the wrong
+directory or the module is misnamed:
+
+```ruby
+# Route:
+namespace :admin do
+  resources :users
+end
+
+# Expects:
+# app/controllers/admin/users_controller.rb
+# class Admin::UsersController < ApplicationController
+```
+
+Use `Glob` to verify the controller exists:
+
+```ruby
+# Via RunCommand:
+RunCommand.new.call(command: "ls app/controllers/admin/")
+```
+
+## Step 6: Verify Helper Paths and Named Routes
+
+If you're debugging a `No route matches` error from a view (link_to, form_with):
+
+1. Check the route name: `RunCommand.new.call(command: "bin/rails routes | grep user_path")`
+2. Verify the route helper: `RunCommand.new.call(command: "bin/rails routes --grep user")`
+3. Check for route helper overrides in custom constraints or defaults
+
+## Failure Mode Guide
+
+| Symptom | Likely Cause | Action |
+|---------|-------------|--------|
+| 404 for existing route | Route constraint blocking | Check `constraints:` block in routes.rb |
+| `No route matches` | Missing resource definition | Add `resources :model_name` |
+| Route works in dev, not prod | Different route ordering | Check routes file isn't conditionally loaded |
+| `Missing controller` | Wrong namespace or filename | Verify file path matches module structure |
+| Path helper not responding | Wrong route name or params mismatch | Check `bin/rails routes --grep helper_name` |

data/lib/ask-rails-harness.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "ask/rails/harness"

data/lib/generators/ask/rails/harness/install/install_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Ask
+  module Rails
+    module Harness
+      module Generators
+        class InstallGenerator < ::Rails::Generators::Base
+          source_root File.expand_path("templates", __dir__)
+
+          desc "Creates ask-rails-harness configuration and migration"
+
+          def create_initializer
+            template "initializer.rb", "config/initializers/ask_rails_harness.rb"
+          end
+
+          def create_migration
+            timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+            template "migration.rb", "db/migrate/#{timestamp}_create_ask_sessions.rb"
+          end
+
+          def create_audit_log_migration
+            timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+            template "audit_log_migration.rb", "db/migrate/#{timestamp}_create_ask_audit_logs.rb"
+          end
+
+          def create_tools_directory
+            empty_directory "app/tools"
+            create_file "app/tools/.keep", ""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/ask/rails/harness/install/templates/audit_log_migration.rb

@@ -0,0 +1,22 @@
+class CreateAskAuditLogs < ActiveRecord::Migration[7.1]
+  def change
+    create_table :ask_audit_logs do |t|
+      t.string :session_id, null: false
+      t.string :tool_name, null: false
+      t.jsonb :params
+      t.jsonb :result_summary
+      t.string :status, null: false, default: "success"
+      t.text :error_message
+      t.integer :duration_ms
+      t.jsonb :user_context
+      t.string :environment
+      t.datetime :recorded_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :ask_audit_logs, :session_id
+    add_index :ask_audit_logs, [:recorded_at, :tool_name]
+    add_index :ask_audit_logs, :status
+  end
+end

data/lib/generators/ask/rails/harness/install/templates/initializer.rb

@@ -0,0 +1,5 @@
+Ask::Rails::Harness.configure do |config|
+  config.default_model = ENV.fetch("ASK_DEFAULT_MODEL", "gpt-4o")
+  config.max_turns = ENV.fetch("ASK_MAX_TURNS", 25).to_i
+  config.persistence_adapter = Ask::Rails::Harness::Persistence.new
+end

data/lib/generators/ask/rails/harness/install/templates/migration.rb

@@ -0,0 +1,12 @@
+class CreateAskSessions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :ask_sessions do |t|
+      t.string :session_id, null: false
+      t.string :model
+      t.jsonb :data, default: {}
+      t.timestamps
+    end
+
+    add_index :ask_sessions, :session_id, unique: true
+  end
+end