@codyswann/lisa 2.121.1 → 2.122.0

package/plugins/lisa-rails-copilot/skills/ops-deploy/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: ops-deploy
+description: Deploy Rails applications via Kamal or CI/CD branch push to staging or production environments.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Deploy
+
+Deploy the Rails application to remote environments.
+
+**Argument**: `$ARGUMENTS` — environment (`staging`, `production`) and optional method (`kamal`, `ci`; default: `kamal`)
+
+## Safety
+
+**CRITICAL**: Production deployments require explicit human confirmation before proceeding. Always ask for confirmation when `$ARGUMENTS` contains `production`.
+
+## Discovery
+
+1. Read `config/deploy.yml` to discover the Kamal configuration: service name, registry, image, servers, accessories
+2. Read `config/deploy.staging.yml` and `config/deploy.production.yml` for environment-specific overrides
+3. Verify the specific environment-variable keys needed for the deploy are present in `.env.staging` / `.env.production` (or in SSM) without printing secret values
+4. Read `Dockerfile` to understand the Docker build stages
+
+## CI/CD Path (Preferred)
+
+The standard deployment path is via CI/CD — pushing to environment branches triggers auto-deploy.
+
+```bash
+# Deploy to staging via CI/CD
+git push origin HEAD:staging
+
+# Deploy to production via CI/CD (requires human confirmation first)
+git push origin HEAD:production
+```
+
+Monitor the deployment via GitHub Actions:
+
+```bash
+gh run list --branch {environment} --limit 3
+gh run watch {run-id}
+```
+
+## Kamal Deployment (Manual)
+
+### Pre-Deploy Checks
+
+1. **Verify Kamal is installed**:
+   ```bash
+   kamal version
+   ```
+
+2. **Verify Docker builds locally**:
+   ```bash
+   docker build -t {app_name}:test .
+   ```
+
+3. **Check current deployment state**:
+   ```bash
+   kamal details -d {environment}
+   ```
+
+4. **Check for deploy lock**:
+   ```bash
+   kamal lock status -d {environment}
+   ```
+   If locked from a previous interrupted deploy: `kamal lock release -d {environment}`
+
+### Deploy to Staging
+
+```bash
+kamal deploy -d staging
+```
+
+### Deploy to Production
+
+**Requires explicit human confirmation.**
+
+```bash
+kamal deploy -d production
+```
+
+### Deploy with Specific Git Ref
+
+```bash
+kamal deploy -d {environment} --version {git-sha-or-tag}
+```
+
+### Rollback
+
+If a deploy causes issues, roll back to the previous version:
+
+```bash
+# List available versions
+kamal app containers -d {environment}
+
+# Rollback to previous version
+kamal rollback {previous-version} -d {environment}
+```
+
+## Post-Deploy Verification
+
+After any deployment:
+
+1. **Health check** the deployed environment:
+   ```bash
+   curl -sf -o /dev/null -w "HTTP %{http_code} in %{time_total}s" https://{app_host}/up
+   ```
+
+2. **Verify ECS service stability** (running count matches desired count):
+   ```bash
+   aws ecs describe-services \
+     --cluster {cluster-name} \
+     --services {service-name} \
+     --region {aws-region} \
+     --query 'services[0].{Running:runningCount,Desired:desiredCount,Status:status}' \
+     --output table
+   ```
+
+3. **Check for migration status** (if migrations were included):
+   ```bash
+   kamal app exec --roles=web "bin/rails db:migrate:status" -d {environment}
+   ```
+
+4. **Check logs** for errors in the first 5 minutes (use `ops-check-logs` skill)
+
+5. **Verify Solid Queue workers** are running (use `ops-verify-jobs` skill)
+
+6. **Verify OpenTelemetry traces** are being exported (use `ops-verify-telemetry` skill)
+
+## Kamal Utility Commands
+
+| Command | Purpose |
+|---------|---------|
+| `kamal details -d {env}` | Show current deployment details |
+| `kamal app logs -d {env}` | Tail application logs |
+| `kamal app exec --roles=web "bin/rails console" -d {env}` | Open Rails console on remote |
+| `kamal audit -d {env}` | Show deploy audit log |
+| `kamal env push -d {env}` | Push updated environment variables |
+| `kamal lock status -d {env}` | Check deploy lock status |
+| `kamal lock release -d {env}` | Release a stale deploy lock |
+| `kamal traefik reboot -d {env}` | Restart the Traefik proxy |
+
+## Output Format
+
+Report deployment result as a table:
+
+| Target | Environment | Method | Status | Verification |
+|--------|-------------|--------|--------|-------------|
+| Rails app | staging | Kamal | SUCCESS/FAIL | /up returns 200 |
+| ECS tasks | staging | N/A | STABLE/UNSTABLE | running == desired |
+| Solid Queue | staging | N/A | RUNNING/DOWN | workers have heartbeat |

package/plugins/lisa-rails-copilot/skills/ops-run-local/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: ops-run-local
+description: Manage the local Docker Compose development environment for Rails applications. Supports start, stop, restart, and status for the full stack or individual services.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Run Local
+
+Manage the local Docker Compose development environment.
+
+**Argument**: `$ARGUMENTS` — `start`, `stop`, `restart`, `status`, `start-app`, `start-services` (default: `start`)
+
+## Prerequisites (run before any operation)
+
+1. Verify Docker is running:
+   ```bash
+   docker info > /dev/null 2>&1 && echo "Docker OK" || echo "ERROR: Docker is not running — start Docker Desktop"
+   ```
+
+2. Check port availability:
+   ```bash
+   lsof -i :3000 2>/dev/null | grep LISTEN
+   lsof -i :5432 2>/dev/null | grep LISTEN
+   ```
+
+3. Verify Ruby and Bundler are available:
+   ```bash
+   ruby --version && bundle --version
+   ```
+
+## Discovery
+
+Read the project's `docker-compose.yml` (or `compose.yaml`) to identify available services. Common services include:
+
+- `web` or `app` — the Rails application
+- `postgres` or `db` — PostgreSQL database
+- `worker` — Solid Queue background worker
+- `css` — Tailwind CSS watch process
+
+Read `Procfile.dev` if it exists — it defines the local development process manager configuration (typically run via `bin/dev`).
+
+Read `config/database.yml` to understand which databases need to exist locally.
+
+## Operations
+
+### start (full stack)
+
+Start all Docker Compose services and the Rails application.
+
+1. **Start infrastructure services** (PostgreSQL, etc.):
+   ```bash
+   docker compose up -d postgres
+   ```
+
+2. **Wait for PostgreSQL** (up to 30 seconds):
+   ```bash
+   for i in $(seq 1 30); do
+     docker compose exec -T postgres pg_isready -U postgres > /dev/null 2>&1 && echo "PostgreSQL ready" && break
+     sleep 1
+   done
+   ```
+
+3. **Create and migrate databases** (if needed):
+   ```bash
+   bin/rails db:prepare
+   ```
+
+4. **Start the full stack** via `bin/dev` (Procfile.dev) or Docker Compose:
+   ```bash
+   # Option A: Procfile.dev (preferred — starts web, worker, CSS watcher)
+   bin/dev
+   ```
+   Run this in the background using the Bash tool with `run_in_background: true`.
+
+   ```bash
+   # Option B: Docker Compose (if all services are containerized)
+   docker compose up -d
+   ```
+
+5. **Wait for Rails** (up to 60 seconds):
+   ```bash
+   for i in $(seq 1 60); do
+     curl -sf http://localhost:3000/up > /dev/null 2>&1 && echo "Rails ready" && break
+     sleep 1
+   done
+   ```
+
+6. Report status table.
+
+### start-services (infrastructure only)
+
+Start only infrastructure services (database, cache) without the Rails app.
+
+```bash
+docker compose up -d postgres
+```
+
+Wait for readiness:
+```bash
+for i in $(seq 1 30); do
+  docker compose exec -T postgres pg_isready -U postgres > /dev/null 2>&1 && echo "PostgreSQL ready" && break
+  sleep 1
+done
+```
+
+### start-app (Rails app only, assumes services are running)
+
+```bash
+bin/dev
+```
+
+Run in background. Verify:
+```bash
+for i in $(seq 1 60); do
+  curl -sf http://localhost:3000/up > /dev/null 2>&1 && echo "Rails ready" && break
+  sleep 1
+done
+```
+
+### stop
+
+Stop all local services.
+
+```bash
+# Stop Rails processes (bin/dev uses foreman which spawns child processes)
+lsof -ti :3000 | xargs kill -9 2>/dev/null || echo "No Rails process on :3000"
+
+# Stop Docker Compose services
+docker compose down
+```
+
+### restart
+
+1. Run **stop** (above).
+2. Wait 2 seconds: `sleep 2`
+3. Run **start** (above).
+4. Verify all services respond.
+
+### status
+
+Check what is currently running and responsive.
+
+```bash
+echo "=== Port Check ==="
+echo -n "Rails    :3000 — "; lsof -i :3000 2>/dev/null | grep LISTEN > /dev/null && echo "LISTENING" || echo "NOT LISTENING"
+echo -n "Postgres :5432 — "; lsof -i :5432 2>/dev/null | grep LISTEN > /dev/null && echo "LISTENING" || echo "NOT LISTENING"
+
+echo ""
+echo "=== Health Check ==="
+echo -n "Rails /up — "; curl -sf -o /dev/null -w "HTTP %{http_code} in %{time_total}s" http://localhost:3000/up 2>/dev/null || echo "UNREACHABLE"
+
+echo ""
+echo "=== Docker Compose ==="
+docker compose ps 2>/dev/null || echo "No Docker Compose services running"
+
+echo ""
+echo "=== Solid Queue Worker ==="
+bin/rails runner "puts SolidQueue::Process.where('last_heartbeat_at > ?', 5.minutes.ago).count.to_s + ' active workers'" 2>/dev/null || echo "Cannot query Solid Queue (app may not be running)"
+```
+
+Report results as a table:
+
+| Service | Port | Listening | Responsive |
+|---------|------|-----------|------------|
+| Rails (web) | 3000 | YES/NO | YES/NO |
+| PostgreSQL | 5432 | YES/NO | N/A |
+| Solid Queue worker | N/A | N/A | YES/NO (heartbeat) |

package/plugins/lisa-rails-copilot/skills/ops-verify-jobs/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: ops-verify-jobs
+description: Verify Solid Queue background jobs are running in Rails applications. Check worker health, queue depth, failed jobs, recurring job execution, and retry stuck jobs.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Verify Jobs
+
+Verify Solid Queue background jobs are running and healthy.
+
+**Argument**: `$ARGUMENTS` — operation (`status`, `failed`, `retry`, `recurring`, `depth`; default: `status`)
+
+## Discovery
+
+1. Read `config/solid_queue.yml` (or `config/queue.yml`) to understand the worker and dispatcher configuration
+2. Read `app/jobs/` directory to discover all job classes
+3. Read `config/recurring.yml` (if it exists) to discover scheduled/recurring jobs
+
+## Prerequisites
+
+The Rails application must be running (locally or remotely) for database-backed queries to work.
+
+## Operations
+
+### status (overall health)
+
+Check Solid Queue process health via database heartbeats:
+
+```bash
+bin/rails runner "
+  processes = SolidQueue::Process.all
+  puts '=== Solid Queue Processes ==='
+  processes.each do |p|
+    stale = p.last_heartbeat_at < 5.minutes.ago ? 'STALE' : 'OK'
+    puts \"#{p.kind} | PID #{p.pid} | #{p.hostname} | Last heartbeat: #{p.last_heartbeat_at} | #{stale}\"
+  end
+  puts ''
+  puts \"Total: #{processes.count} processes\"
+  puts \"Healthy: #{processes.select { |p| p.last_heartbeat_at > 5.minutes.ago }.count}\"
+  puts \"Stale: #{processes.select { |p| p.last_heartbeat_at <= 5.minutes.ago }.count}\"
+"
+```
+
+### depth (queue depth by queue name)
+
+```bash
+bin/rails runner "
+  puts '=== Queue Depth ==='
+  SolidQueue::Job.where(finished_at: nil).group(:queue_name).count.each do |queue, count|
+    puts \"#{queue}: #{count} pending\"
+  end
+  puts ''
+  total = SolidQueue::Job.where(finished_at: nil).count
+  puts \"Total pending: #{total}\"
+"
+```
+
+### failed (list failed jobs)
+
+```bash
+bin/rails runner "
+  failed = SolidQueue::FailedExecution.includes(:job).order(created_at: :desc).limit(20)
+  puts '=== Failed Jobs ==='
+  failed.each do |f|
+    puts \"#{f.job.class_name} | Queue: #{f.job.queue_name} | Failed at: #{f.created_at} | Error: #{f.error.to_s.truncate(120)}\"
+  end
+  puts ''
+  puts \"Total failed: #{SolidQueue::FailedExecution.count}\"
+"
+```
+
+### retry (retry failed jobs)
+
+Retry all failed jobs:
+
+```bash
+bin/rails runner "
+  count = SolidQueue::FailedExecution.count
+  SolidQueue::FailedExecution.find_each do |fe|
+    fe.retry
+  end
+  puts \"Retried #{count} failed jobs\"
+"
+```
+
+Retry a specific job class:
+
+```bash
+bin/rails runner "
+  failed = SolidQueue::FailedExecution.includes(:job).where(solid_queue_jobs: { class_name: '{JobClassName}' })
+  count = failed.count
+  failed.find_each { |fe| fe.retry }
+  puts \"Retried #{count} #{'{JobClassName}'} jobs\"
+"
+```
+
+### recurring (check recurring job schedule)
+
+```bash
+bin/rails runner "
+  puts '=== Recurring Tasks ==='
+  SolidQueue::RecurringTask.all.each do |task|
+    last_run = SolidQueue::Job.where(class_name: task.class_name).order(created_at: :desc).first
+    last_run_at = last_run&.created_at || 'NEVER'
+    puts \"#{task.key} | #{task.class_name} | Schedule: #{task.schedule} | Last run: #{last_run_at}\"
+  end
+" 2>/dev/null || echo "RecurringTask not available — check config/recurring.yml"
+```
+
+## Remote Verification (via Kamal)
+
+For checking jobs in staging/production environments:
+
+```bash
+kamal app exec --roles=web "bin/rails runner \"
+  processes = SolidQueue::Process.all
+  healthy = processes.select { |p| p.last_heartbeat_at > 5.minutes.ago }.count
+  stale = processes.select { |p| p.last_heartbeat_at <= 5.minutes.ago }.count
+  failed = SolidQueue::FailedExecution.count
+  pending = SolidQueue::Job.where(finished_at: nil).count
+  puts \\\"Processes: #{processes.count} (#{healthy} healthy, #{stale} stale)\\\"
+  puts \\\"Pending jobs: #{pending}\\\"
+  puts \\\"Failed jobs: #{failed}\\\"
+\"" -d {environment}
+```
+
+## Output Format
+
+### Process Status
+
+| Kind | PID | Hostname | Last Heartbeat | Status |
+|------|-----|----------|---------------|--------|
+| Worker | 12345 | web-1 | 30s ago | OK |
+| Dispatcher | 12346 | web-1 | 15s ago | OK |
+
+### Queue Depth
+
+| Queue | Pending | Status |
+|-------|---------|--------|
+| default | 3 | OK |
+| mailers | 0 | OK |
+| low_priority | 150 | WARN (> 100) |
+
+### Failed Jobs
+
+| Job Class | Queue | Failed At | Error (truncated) |
+|-----------|-------|-----------|-------------------|
+| SendEmailJob | mailers | 5m ago | Net::SMTPAuthenticationError |
+| ProcessPaymentJob | default | 1h ago | Stripe::CardError |
+
+Flag concerns:
+- Any stale process (heartbeat > 5 minutes ago)
+- Queue depth > 100 pending jobs
+- Any failed jobs in the last hour
+- Recurring jobs that missed their schedule

package/plugins/lisa-rails-copilot/skills/ops-verify-telemetry/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: ops-verify-telemetry
+description: Verify OpenTelemetry traces are being collected and exported to AWS X-Ray for Rails applications. Check collector health, trace export, and CloudWatch metrics.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Ops: Verify Telemetry
+
+Verify OpenTelemetry traces are being collected and exported to X-Ray.
+
+**Argument**: `$ARGUMENTS` — check type (`traces`, `metrics`, `all`; default: `all`)
+
+## Discovery
+
+1. Read `Gemfile` for OpenTelemetry gem configuration:
+   - `opentelemetry-sdk`
+   - `opentelemetry-exporter-otlp`
+   - `opentelemetry-instrumentation-all` (or individual instrumentation gems)
+2. Read `config/initializers/opentelemetry.rb` (or similar) for SDK configuration
+3. Read `config/deploy.yml` or environment files for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_SERVICE_NAME`
+4. Read `docker-compose.yml` for OpenTelemetry Collector sidecar configuration (if present)
+
+## Local Verification
+
+### Check OpenTelemetry Gems
+
+```bash
+bundle list | grep -i opentelemetry
+```
+
+### Check OpenTelemetry Configuration
+
+```bash
+grep -r "OpenTelemetry" config/initializers/ app/
+```
+
+### Verify OTLP Endpoint is Set
+
+```bash
+echo "OTEL_EXPORTER_OTLP_ENDPOINT=${OTEL_EXPORTER_OTLP_ENDPOINT:-not set}"
+echo "OTEL_SERVICE_NAME=${OTEL_SERVICE_NAME:-not set}"
+```
+
+### Generate a Test Trace (local)
+
+Make a request to the local app and check that traces are produced:
+
+```bash
+# Make a request that should generate a trace
+curl -sf http://localhost:3000/up -w "\nHTTP %{http_code}\n"
+
+# Check Rails logs for OpenTelemetry output (if configured to log)
+grep -i "otel\|opentelemetry\|trace_id" log/development.log | tail -10
+```
+
+### Check Collector Sidecar (if using Docker Compose)
+
+```bash
+docker compose logs otel-collector 2>/dev/null | tail -20 || echo "No otel-collector service in Docker Compose"
+```
+
+## Remote Verification (AWS X-Ray)
+
+### Check Recent Traces
+
+```bash
+aws xray get-trace-summaries \
+  --region {aws-region} \
+  --start-time $(ruby -r time -e 'puts (Time.now.utc - 30 * 60).iso8601') \
+  --end-time $(ruby -r time -e 'puts Time.now.utc.iso8601') \
+  --query 'TraceSummaries | length(@)' \
+  --output text
+```
+
+### Check Traces for the Application Service
+
+```bash
+aws xray get-trace-summaries \
+  --region {aws-region} \
+  --start-time $(ruby -r time -e 'puts (Time.now.utc - 30 * 60).iso8601') \
+  --end-time $(ruby -r time -e 'puts Time.now.utc.iso8601') \
+  --filter-expression "service(\"{service-name}\")" \
+  --query 'TraceSummaries[:10].{TraceId:Id,Duration:Duration,StatusCode:Http.HttpStatus,URL:Http.HttpURL,ResponseTime:ResponseTime}' \
+  --output table
+```
+
+### Check for Error Traces
+
+```bash
+aws xray get-trace-summaries \
+  --region {aws-region} \
+  --start-time $(ruby -r time -e 'puts (Time.now.utc - 3600).iso8601') \
+  --end-time $(ruby -r time -e 'puts Time.now.utc.iso8601') \
+  --filter-expression "service(\"{service-name}\") AND fault = true" \
+  --query 'TraceSummaries[:10].{TraceId:Id,Duration:Duration,StatusCode:Http.HttpStatus,URL:Http.HttpURL}' \
+  --output table
+```
+
+### Get Detailed Trace
+
+```bash
+aws xray batch-get-traces \
+  --region {aws-region} \
+  --trace-ids "{trace-id}" \
+  --query 'Traces[0].Segments[].Document' \
+  --output text | jq '.'
+```
+
+### Check X-Ray Service Map
+
+```bash
+aws xray get-service-graph \
+  --region {aws-region} \
+  --start-time $(ruby -r time -e 'puts (Time.now.utc - 3600).iso8601') \
+  --end-time $(ruby -r time -e 'puts Time.now.utc.iso8601') \
+  --query 'Services[].{Name:Name,Type:Type,Edges:Edges[].{Ref:ReferenceId,Latency:ResponseTimeHistogram[0].Average}}' \
+  --output table
+```
+
+## CloudWatch Metrics Verification
+
+### Check Custom Metrics Published by the Application
+
+```bash
+aws cloudwatch list-metrics \
+  --region {aws-region} \
+  --namespace "{app_name}" \
+  --query 'Metrics[].{MetricName:MetricName,Dimensions:Dimensions[].{Name:Name,Value:Value}}' \
+  --output table
+```
+
+### Check Recent Metric Data Points
+
+```bash
+aws cloudwatch get-metric-statistics \
+  --region {aws-region} \
+  --namespace "{app_name}" \
+  --metric-name "{metric-name}" \
+  --start-time $(ruby -r time -e 'puts (Time.now.utc - 3600).iso8601') \
+  --end-time $(ruby -r time -e 'puts Time.now.utc.iso8601') \
+  --period 300 \
+  --statistics Average Sum \
+  --output table
+```
+
+### Check CloudWatch Alarms
+
+```bash
+aws cloudwatch describe-alarms \
+  --region {aws-region} \
+  --alarm-name-prefix "{app_name}" \
+  --query 'MetricAlarms[].{Name:AlarmName,State:StateValue,Metric:MetricName,Threshold:Threshold}' \
+  --output table
+```
+
+## Remote Verification (via Kamal)
+
+For checking telemetry configuration in deployed environments:
+
+```bash
+kamal app exec --roles=web "bin/rails runner \"
+  puts 'OTEL_EXPORTER_OTLP_ENDPOINT: ' + ENV.fetch('OTEL_EXPORTER_OTLP_ENDPOINT', 'NOT SET')
+  puts 'OTEL_SERVICE_NAME: ' + ENV.fetch('OTEL_SERVICE_NAME', 'NOT SET')
+  puts 'OTEL_TRACES_EXPORTER: ' + ENV.fetch('OTEL_TRACES_EXPORTER', 'NOT SET')
+\"" -d {environment}
+```
+
+## Output Format
+
+### Trace Summary
+
+| Check | Status | Details |
+|-------|--------|---------|
+| OTel gems installed | OK/FAIL | opentelemetry-sdk v1.x.x |
+| OTel initializer present | OK/FAIL | config/initializers/opentelemetry.rb |
+| OTLP endpoint configured | OK/FAIL | https://otel-collector:4318 |
+| Traces in X-Ray (last 30m) | OK/FAIL | 245 traces found |
+| Error traces (last 1h) | OK/WARN | 3 fault traces |
+| CloudWatch metrics | OK/FAIL | 12 custom metrics published |
+| CloudWatch alarms | OK/WARN | 1 alarm in ALARM state |
+
+### Recent Traces
+
+| Trace ID | Duration | Status | URL |
+|----------|----------|--------|-----|
+| 1-abc123 | 45ms | 200 | GET /up |
+| 1-def456 | 120ms | 200 | GET /api/v1/users |
+| 1-ghi789 | 2300ms | 500 | POST /api/v1/orders |
+
+Flag concerns:
+- No traces found in the last 30 minutes
+- Error rate above 5% of total traces
+- Average trace duration above 1 second
+- OTLP endpoint not configured
+- CloudWatch alarms in ALARM state

package/plugins/lisa-rails-cursor/.claude-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "lisa-rails",
+  "version": "2.122.0",
+  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
+  "author": {
+    "name": "Cody Swann"
+  },
+  "dependencies": [
+    "lisa"
+  ],
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/rubocop-on-edit.sh"
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/sg-scan-on-edit.sh"
+          }
+        ]
+      }
+    ]
+  }
+}