mysql_genius 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6f79035cffd33253079d4365967dcca4ff97d1515e8e5960d23060b92052827
-  data.tar.gz: f8c05c7ab9c6408d1816e36eec7c95cf0796f37b7fba0344699e806576b9e340
+  metadata.gz: 15b1fc129dbade000c7a7467601b927804f11f73892a0f450f92f6ffc1d4b313
+  data.tar.gz: d01c43dd9e9e06212c6fa85cad829fe940c982b1a1cf412ae02336de69bde376
 SHA512:
-  metadata.gz: 5a797a52e89c12e8a266ec70b4f9264e4270450000630824789f64a19b53f4f22b5483bdcef634a97f904f9b61f7b533559f1dfa1fd37ee4ee9711f650f143db
-  data.tar.gz: 9e46e3fafff0682dbeb29ffecc855f4d00d204efe8b15517ab2f05baaadf94da50836f12dfbd928f322a9df624d4f129442602f8f7074a043a8ce11896d5cd7a
+  metadata.gz: 3b9e69fee6f8b6c79e36bdccca6c838876f10fb79b333464496f37aa14db50d42b2507a4dfd18e0162c2b612af4279bf4ea731cd765da83068a23f3e303c340e
+  data.tar.gz: cf0730102bb3ce854f669dcf77343c3f5f0704996e1fa5bbe0c08c6a02f34110c59dfa53d9a303044f5c8ac6417f9e6f2863d3cc1d2535e84f108922b3379d0e

data/.gitignore

@@ -15,3 +15,4 @@ Gemfile.lock
 *.gem
 docs/superpowers/
 /ralph
+.DS_Store

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.8.0
+
+### Added
+- **6 new AI analysis features:**
+  - **Variable Config Reviewer** — reviews my.cnf settings against observed workload
+  - **Connection Pressure Advisor** — diagnoses connection pool health
+  - **Workload Digest** — executive summary of the entire query workload
+  - **InnoDB Health Interpreter** — plain English translation of `SHOW ENGINE INNODB STATUS`
+  - **Index Consolidation Planner** — holistic drop/merge/add index plan across tables
+  - **Slow Query Pattern Grouper** — groups slow queries by shared root cause
+- AI buttons added to Server tab, Query Stats tab, and Indexes tabs
+- `mysql_genius` now declares runtime dependency on `mysql_genius-core ~> 0.8.0`
+
+## 0.7.2
+
+### Added
+- **Anthropic Messages API support** — `x-api-key` auth style with `anthropic-version` header, top-level `system` parameter, `content[0].text` response parsing.
+- **Configurable `max_tokens`** — new field on `Core::Ai::Config` (default 4096), sent to both OpenAI and Anthropic APIs.
+- **Copy response button** on all AI result sections (schema review, migration risk, optimization, describe query, rewrite, index advisor, root cause, anomaly detection).
+- **Dark mode contrast fixes** for AI result sections — proper CSS classes with dark-mode variants replace hardcoded light-mode inline styles.
+- **`capability?(:standalone_header)`** guard hides the dashboard header when rendered inside a layout that already provides one.
+
 ## 0.7.1
 
 Lockstep version bump with `mysql_genius-core 0.7.1` which fixes missing ERB templates in the gem package.

data/app/controllers/concerns/mysql_genius/ai_features.rb

@@ -232,6 +232,61 @@ module MysqlGenius
       render(json: { error: "Migration risk assessment failed: #{e.message}" }, status: :unprocessable_entity)
     end
 
+    def variable_review
+      return ai_not_configured unless mysql_genius_config.ai_enabled?
+
+      result = MysqlGenius::Core::Ai::VariableReviewer.new(ai_client, ai_config_for_core, rails_connection).call
+      render(json: result)
+    rescue StandardError => e
+      render(json: { error: "Variable review failed: #{e.message}" }, status: :unprocessable_entity)
+    end
+
+    def connection_advisor
+      return ai_not_configured unless mysql_genius_config.ai_enabled?
+
+      result = MysqlGenius::Core::Ai::ConnectionAdvisor.new(ai_client, ai_config_for_core, rails_connection).call
+      render(json: result)
+    rescue StandardError => e
+      render(json: { error: "Connection advisor failed: #{e.message}" }, status: :unprocessable_entity)
+    end
+
+    def workload_digest
+      return ai_not_configured unless mysql_genius_config.ai_enabled?
+
+      result = MysqlGenius::Core::Ai::WorkloadDigest.new(rails_connection, ai_client, ai_config_for_core).call
+      render(json: result)
+    rescue StandardError => e
+      render(json: { error: "Workload digest failed: #{e.message}" }, status: :unprocessable_entity)
+    end
+
+    def innodb_health
+      return ai_not_configured unless mysql_genius_config.ai_enabled?
+
+      result = MysqlGenius::Core::Ai::InnodbInterpreter.new(ai_client, ai_config_for_core, rails_connection).call
+      render(json: result)
+    rescue StandardError => e
+      render(json: { error: "InnoDB health analysis failed: #{e.message}" }, status: :unprocessable_entity)
+    end
+
+    def index_planner
+      return ai_not_configured unless mysql_genius_config.ai_enabled?
+
+      tables = params[:tables].present? ? Array(params[:tables]) : nil
+      result = MysqlGenius::Core::Ai::IndexPlanner.new(ai_client, ai_config_for_core, rails_connection).call(tables)
+      render(json: result)
+    rescue StandardError => e
+      render(json: { error: "Index planner failed: #{e.message}" }, status: :unprocessable_entity)
+    end
+
+    def pattern_grouper
+      return ai_not_configured unless mysql_genius_config.ai_enabled?
+
+      result = MysqlGenius::Core::Ai::PatternGrouper.new(rails_connection, ai_client, ai_config_for_core).call
+      render(json: result)
+    rescue StandardError => e
+      render(json: { error: "Pattern grouper failed: #{e.message}" }, status: :unprocessable_entity)
+    end
+
     private
 
     RAILS_DOMAIN_CONTEXT = <<~CTX

data/app/views/layouts/mysql_genius/application.html.erb

@@ -145,6 +145,17 @@
     code { font-size: 12px; word-break: break-all; background: #f0f1f3; padding: 2px 6px; border-radius: 3px; color: #24292f; }
     pre.mg-pre { background: #f4f4f4; padding: 10px; border-radius: 4px; overflow-x: auto; font-size: 12px; }
 
+    /* AI result sections */
+    .mg-ai-section { border-radius: 4px; border: 1px solid #dee2e6; border-left-width: 4px; margin-bottom: 12px; }
+    .mg-ai-section-header { padding: 8px 12px; border-bottom: 1px solid #dee2e6; font-size: 13px; }
+    .mg-ai-section-body { padding: 12px; font-size: 13px; }
+    .mg-ai-danger { border-left-color: #dc3545; background: #fff5f5; }
+    .mg-ai-danger .mg-ai-section-header { border-bottom-color: #f5c6cb; }
+    .mg-ai-warning { border-left-color: #ffc107; background: #fffbeb; }
+    .mg-ai-warning .mg-ai-section-header { border-bottom-color: #ffeeba; }
+    .mg-ai-info { border-left-color: #17a2b8; background: #f0f9ff; }
+    .mg-ai-info .mg-ai-section-header { border-bottom-color: #bee5eb; }
+
     /* Theme toggle */
     .mg-theme-toggle { background: none; border: 1px solid #ced4da; border-radius: 4px; padding: 4px 8px; cursor: pointer; font-size: 14px; line-height: 1; color: inherit; }
     .mg-theme-toggle:hover { background: #e9ecef; }
@@ -220,7 +231,13 @@
 
     /* Inline code */
     [data-theme="dark"] code { background: #21262d; color: #c9d1d9; }
+    [data-theme="dark"] pre { background: #161b22; color: #c9d1d9; border-color: #30363d; }
     [data-theme="dark"] pre.mg-pre { background: #161b22; color: #c9d1d9; }
+    [data-theme="dark"] .mg-card-body { color: #c9d1d9; }
+    [data-theme="dark"] .mg-card-body h1, [data-theme="dark"] .mg-card-body h2, [data-theme="dark"] .mg-card-body h3, [data-theme="dark"] .mg-card-body h4 { color: #c9d1d9; }
+    [data-theme="dark"] .mg-card-body p, [data-theme="dark"] .mg-card-body li, [data-theme="dark"] .mg-card-body td { color: #c9d1d9; }
+    [data-theme="dark"] .mg-card-body strong { color: #e6edf3; }
+    [data-theme="dark"] .mg-card-body a { color: #58a6ff; }
 
     /* Links */
     [data-theme="dark"] .mg-link { color: #58a6ff; }
@@ -234,6 +251,16 @@
     /* Checkboxes */
     [data-theme="dark"] .mg-check .type-hint { color: #484f58; }
 
+    /* AI result sections (dark) */
+    [data-theme="dark"] .mg-ai-section { border-color: #30363d; }
+    [data-theme="dark"] .mg-ai-danger { background: #2d0d0d; border-left-color: #f85149; }
+    [data-theme="dark"] .mg-ai-danger .mg-ai-section-header { border-bottom-color: #3d1414; color: #f85149; }
+    [data-theme="dark"] .mg-ai-warning { background: #2d2000; border-left-color: #d29922; }
+    [data-theme="dark"] .mg-ai-warning .mg-ai-section-header { border-bottom-color: #3d2e00; color: #d29922; }
+    [data-theme="dark"] .mg-ai-info { background: #0d2a3a; border-left-color: #58a6ff; }
+    [data-theme="dark"] .mg-ai-info .mg-ai-section-header { border-bottom-color: #0d3a5a; color: #58a6ff; }
+    [data-theme="dark"] .mg-ai-section-body { color: #c9d1d9; }
+
     /* Theme toggle (dark) */
     [data-theme="dark"] .mg-theme-toggle { border-color: #30363d; color: #c9d1d9; }
     [data-theme="dark"] .mg-theme-toggle:hover { background: #21262d; }

data/config/routes.rb

@@ -25,4 +25,10 @@ MysqlGenius::Engine.routes.draw do
   post "anomaly_detection", to: "queries#anomaly_detection"
   post "root_cause",       to: "queries#root_cause"
   post "migration_risk",   to: "queries#migration_risk"
+  post "variable_review",  to: "queries#variable_review"
+  post "connection_advisor", to: "queries#connection_advisor"
+  post "workload_digest",  to: "queries#workload_digest"
+  post "innodb_health",    to: "queries#innodb_health"
+  post "index_planner",    to: "queries#index_planner"
+  post "pattern_grouper",  to: "queries#pattern_grouper"
 end

data/docs/guides/ai-features.md

@@ -0,0 +1,115 @@
+# AI Features Guide
+
+MysqlGenius integrates with OpenAI-compatible LLM APIs to provide AI-powered database analysis. All AI features are optional — the dashboard works fully without them.
+
+## Supported providers
+
+| Provider | Endpoint | Auth Style |
+|---|---|---|
+| OpenAI | `https://api.openai.com/v1/chat/completions` | Bearer |
+| Anthropic | `https://api.anthropic.com/v1/messages` | x-api-key |
+| Google Gemini | `https://generativelanguage.googleapis.com/v1beta/openai/chat/completions` | Bearer |
+| Azure OpenAI | `https://YOUR-RESOURCE.openai.azure.com/...` | api-key |
+| DeepSeek | `https://api.deepseek.com/chat/completions` | Bearer |
+| Groq | `https://api.groq.com/openai/v1/chat/completions` | Bearer |
+| Ollama (local) | `http://localhost:11434/v1/chat/completions` | Bearer |
+| OpenRouter | `https://openrouter.ai/api/v1/chat/completions` | Bearer |
+| Perplexity | `https://api.perplexity.ai/chat/completions` | Bearer |
+| Any OpenAI-compatible | Your endpoint URL | Bearer or api-key |
+
+## Configuration
+
+In your Rails initializer (`config/initializers/mysql_genius.rb`):
+
+```ruby
+MysqlGenius.configure do |config|
+  config.ai_endpoint = "https://api.openai.com/v1/chat/completions"
+  config.ai_api_key = ENV["OPENAI_API_KEY"]
+  config.ai_model = "gpt-4o-mini"
+  config.ai_auth_style = :bearer  # or :api_key for Azure, :x_api_key for Anthropic
+end
+```
+
+## Available features
+
+### Query Explorer AI
+
+| Feature | What it does | Where |
+|---|---|---|
+| **AI Suggest** | Generate SQL from natural language | Query Explorer tab |
+| **AI Optimization** | Analyze EXPLAIN output, suggest improvements | After running EXPLAIN |
+| **Index Advisor** | Recommend indexes for a specific query | After running EXPLAIN |
+| **Describe Query** | Explain what a SQL query does in plain English | Query Explorer tab |
+| **Rewrite Query** | Suggest an optimized version of the SQL | Query Explorer tab |
+
+### Schema & Migration
+
+| Feature | What it does | Where |
+|---|---|---|
+| **Schema Review** | Find anti-patterns across your schema | AI Tools tab |
+| **Migration Risk** | Assess safety of a DDL/migration before deploying | AI Tools tab |
+| **AI Optimize** | Review a specific table's schema (appears on fragmented tables) | Tables tab |
+
+### Server Analysis
+
+| Feature | What it does | Where |
+|---|---|---|
+| **Variable Config Review** | Review my.cnf settings against your workload | Server tab |
+| **Connection Advisor** | Diagnose connection pool issues | Server tab |
+| **InnoDB Health** | Interpret SHOW ENGINE INNODB STATUS | Server tab |
+
+### Workload Analysis
+
+| Feature | What it does | Where |
+|---|---|---|
+| **Workload Digest** | Executive summary of your query workload | Query Stats tab |
+| **Pattern Grouper** | Group slow queries by shared root cause | Query Stats tab |
+| **Index Planner** | Holistic index optimization plan | Indexes tabs |
+
+## Settings
+
+### Max Tokens
+
+Controls the maximum response length from the LLM. Default: 4096. Adjust with the slider in AI Configuration.
+
+- **Lower (256-1024)** — faster responses, may truncate complex analyses
+- **Higher (4096-16384)** — complete analyses, slower and more expensive
+
+### System Prompt
+
+Optional context injected into every AI request. Use it to describe your application:
+
+> "This is an e-commerce platform with 50M orders. The database handles 5000 QPS during peak hours."
+
+### Domain Prompt
+
+Optional instructions for the AI's recommendations:
+
+> "Prefer window functions over correlated subqueries. Don't recommend foreign keys — we handle referential integrity in the application layer."
+
+## Using with Ollama (free, local)
+
+1. Install Ollama: `brew install ollama`
+2. Pull a model: `ollama pull llama3.2`
+3. Start Ollama: `ollama serve`
+4. In MysqlGenius, select **Ollama (local)** as the provider
+5. The endpoint and model auto-fill — just click **Save**
+
+No API key needed. All data stays on your machine.
+
+## Copying AI responses
+
+Every AI response has a **Copy response** button at the bottom right. Click it to copy the plain text to your clipboard — useful for sharing with team members or pasting into tickets.
+
+## Cost considerations
+
+Each AI feature makes one API call per invocation. Typical costs with OpenAI gpt-4o-mini:
+
+| Feature | ~Input tokens | ~Output tokens | ~Cost |
+|---|---|---|---|
+| Schema Review (all tables) | 2000-5000 | 500-2000 | $0.001-0.005 |
+| Migration Risk | 500-1000 | 500-1000 | $0.001 |
+| Query Optimization | 1000-2000 | 500-1000 | $0.001 |
+| Workload Digest | 3000-5000 | 1000-2000 | $0.003 |
+
+Using Ollama or other local models eliminates API costs entirely.

data/docs/guides/getting-started-rails.md

@@ -0,0 +1,118 @@
+# Getting Started with MysqlGenius (Rails)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "mysql_genius"
+```
+
+```bash
+bundle install
+```
+
+## Mount the engine
+
+In `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount MysqlGenius::Engine, at: "/mysql_genius"
+  # ... your other routes
+end
+```
+
+## Configuration
+
+Create an initializer at `config/initializers/mysql_genius.rb`:
+
+```ruby
+MysqlGenius.configure do |config|
+  # Authentication (required in production)
+  config.authenticate = ->(controller) {
+    # Example: restrict to admin users
+    controller.current_user&.admin?
+  }
+
+  # Tables to hide from the dashboard
+  config.blocked_tables = %w[
+    schema_migrations
+    ar_internal_metadata
+  ]
+
+  # Columns to mask in query results
+  config.masked_column_patterns = %w[
+    password
+    token
+    secret
+    ssn
+  ]
+
+  # Query limits
+  config.default_row_limit = 100
+  config.max_row_limit = 10_000
+  config.query_timeout_ms = 10_000
+
+  # AI features (optional)
+  config.ai_endpoint = ENV["MYSQL_GENIUS_AI_ENDPOINT"]
+  config.ai_api_key = ENV["MYSQL_GENIUS_AI_KEY"]
+  config.ai_model = "gpt-4o-mini"
+  config.ai_auth_style = :bearer
+
+  # Stats collection (background thread, default: true)
+  config.stats_collection = true
+
+  # Slow query monitoring via Redis (optional)
+  # config.redis_url = ENV["REDIS_URL"]
+end
+```
+
+## Visit the dashboard
+
+Start your Rails server and navigate to:
+
+```
+http://localhost:3000/mysql_genius
+```
+
+## Features
+
+### Dashboard
+Overview of server health, top slow queries, expensive queries, duplicate/unused index counts.
+
+### Query Explorer
+Run SELECT queries against your database with syntax highlighting, EXPLAIN output, and AI-powered suggestions.
+
+### Query Stats
+Top queries from `performance_schema.events_statements_summary_by_digest`. Click any query to see a detail page with time-series performance charts.
+
+### Server
+Server status, connections, InnoDB buffer pool, query activity.
+
+### Tables
+Table sizes with fragmentation detection. Tables needing optimization get an "AI Optimize" button.
+
+### Indexes
+Duplicate and unused index detection.
+
+### AI Tools (when configured)
+- **Schema Review** — find anti-patterns in your schema
+- **Migration Risk** — assess DDL safety before deploying
+- **Query Description** — explain what a query does in plain English
+- **Query Rewrite** — suggest optimized versions of slow queries
+- **Index Advisor** — recommend indexes for specific queries
+
+## Security
+
+**Always configure authentication in production.** Without it, anyone who can reach the mounted path can view your database schema and run SELECT queries.
+
+The `blocked_tables` and `masked_column_patterns` settings provide defense-in-depth but are not a substitute for authentication.
+
+## Supported databases
+
+- MySQL 5.7+
+- MySQL 8.0+
+- MariaDB 10.3+
+
+Some features (query stats, unused indexes) require `performance_schema` to be enabled.

data/docs/guides/ssh-tunnel-connections.md

@@ -0,0 +1,151 @@
+# Connecting to MySQL Through an SSH Tunnel
+
+If your MySQL server is behind a firewall, on a private network, or only accessible via a bastion/jump host, you can use an SSH tunnel to connect MysqlGenius to it.
+
+## How it works
+
+An SSH tunnel forwards a local port on your machine to the MySQL port on the remote server. MysqlGenius connects to `localhost:<local_port>` and the tunnel transparently routes traffic to the actual database server.
+
+```
+Your Machine (MysqlGenius)  →  SSH Tunnel  →  Bastion Host  →  MySQL Server
+localhost:3307                                                   db.internal:3306
+```
+
+## Step 1: Open the SSH tunnel
+
+In a terminal, run:
+
+```bash
+ssh -L 3307:db.internal:3306 user@bastion-host.example.com -N
+```
+
+**Flags explained:**
+- `-L 3307:db.internal:3306` — forward local port `3307` to `db.internal:3306` through the tunnel
+- `user@bastion-host.example.com` — your SSH login on the bastion/jump host
+- `-N` — don't open a shell, just forward the port
+
+**With an SSH key:**
+
+```bash
+ssh -L 3307:db.internal:3306 user@bastion-host.example.com -N -i ~/.ssh/my_key
+```
+
+**Keep it running in the background:**
+
+```bash
+ssh -L 3307:db.internal:3306 user@bastion-host.example.com -N -f
+```
+
+The `-f` flag sends SSH to the background after connecting.
+
+## Step 2: Configure your Rails app
+
+MysqlGenius uses your app's `ActiveRecord::Base.connection`, which reads from `database.yml`. Point it at the tunnel:
+
+```yaml
+# config/database.yml
+production:
+  adapter: mysql2
+  host: 127.0.0.1
+  port: 3307
+  username: readonly
+  password: <%= ENV["DB_PASSWORD"] %>
+  database: app_production
+```
+
+No special MysqlGenius configuration needed — it automatically uses the same connection as your Rails app.
+
+## Step 3: Verify the connection
+
+Start your Rails server and visit `/mysql_genius`. If the tunnel is running, the dashboard loads normally. If not, you'll see a connection error.
+
+## Common issues
+
+### "Connection refused"
+
+The SSH tunnel is not running. Start it first:
+
+```bash
+ssh -L 3307:db.internal:3306 user@bastion -N
+```
+
+### "Access denied"
+
+The tunnel is working but the MySQL credentials are wrong. Verify your username/password can connect to the database directly from the bastion host.
+
+### "Lost connection to MySQL server during query"
+
+The SSH tunnel dropped. This happens if the tunnel is idle for too long. Add keep-alive settings:
+
+```bash
+ssh -L 3307:db.internal:3306 user@bastion -N -o ServerAliveInterval=60 -o ServerAliveCountMax=3
+```
+
+### Port already in use
+
+Another process is using port 3307. Pick a different local port:
+
+```bash
+ssh -L 3308:db.internal:3306 user@bastion -N
+```
+
+Then update your MysqlGenius config to use port `3308`.
+
+## Multiple databases through one bastion
+
+You can tunnel to multiple MySQL servers through the same bastion:
+
+```bash
+# Production on local port 3307
+ssh -L 3307:db-prod.internal:3306 user@bastion -N -f
+
+# Staging on local port 3308
+ssh -L 3308:db-staging.internal:3306 user@bastion -N -f
+```
+
+Then create separate MysqlGenius profiles for each:
+- **Production**: `127.0.0.1:3307`
+- **Staging**: `127.0.0.1:3308`
+
+## Automating the tunnel
+
+### macOS: Launch Agent
+
+Create `~/Library/LaunchAgents/com.mysqlgenius.tunnel.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.mysqlgenius.tunnel</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>ssh</string>
+        <string>-L</string>
+        <string>3307:db.internal:3306</string>
+        <string>user@bastion</string>
+        <string>-N</string>
+        <string>-o</string>
+        <string>ServerAliveInterval=60</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+```
+
+Load it:
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.mysqlgenius.tunnel.plist
+```
+
+The tunnel will start automatically on login and restart if it drops.
+
+## Future: Built-in SSH tunnel support
+
+Built-in SSH tunnel support is planned for a future release. When available, you'll be able to configure the SSH connection directly in the MysqlGenius profile form without needing a separate terminal.

data/lib/mysql_genius/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MysqlGenius
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

data/mysql_genius.gemspec

@@ -30,6 +30,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency("activerecord", ">= 6.0", "< 9")
-  spec.add_dependency("mysql_genius-core", "~> 0.7.0")
+  spec.add_dependency("mysql_genius-core", "~> 0.8.0")
   spec.add_dependency("railties", ">= 6.0", "< 9")
 end

data/ralph/prd.json

@@ -1,174 +1,117 @@
 {
   "project": "MysqlGenius",
-  "branchName": "ralph/query-detail-page",
-  "description": "Query Detail Page with Lightweight History - background stats collector, in-memory ring buffer, SVG time-series charts, and a dedicated query detail page accessible from the Query Stats tab",
+  "branchName": "ralph/ssh-tunnel-support",
+  "description": "Add built-in SSH tunnel support to the desktop sidecar so users can connect to MySQL databases behind firewalls without manually running ssh -L",
   "userStories": [
     {
       "id": "US-001",
-      "title": "Add StatsHistory ring buffer to core gem",
-      "description": "As a developer, I need a thread-safe in-memory ring buffer to store per-digest query stats snapshots.",
+      "title": "Add net-ssh dependency and SshTunnel class",
+      "description": "As a developer, I need a class that opens an SSH tunnel forwarding a local port to a remote MySQL server.",
       "acceptanceCriteria": [
-        "Create gems/mysql_genius-core/lib/mysql_genius/core/analysis/stats_history.rb",
-        "StatsHistory.new(max_samples: 1440) initializes empty buffer",
-        "record(digest_text, {timestamp:, calls:, total_time_ms:, avg_time_ms:}) appends a snapshot",
-        "series_for(digest_text) returns ordered array oldest-to-newest",
-        "series_for returns empty array for unknown digests",
-        "Ring buffer drops oldest entry when max_samples reached",
-        "digests returns all known digest keys",
-        "clear empties all data",
-        "All operations are thread-safe via Mutex",
-        "Add require to gems/mysql_genius-core/lib/mysql_genius/core.rb",
-        "Create spec at gems/mysql_genius-core/spec/mysql_genius/core/analysis/stats_history_spec.rb with tests for all above",
-        "Core gem suite passes: (cd gems/mysql_genius-core && bundle exec rspec)",
+        "Add net-ssh ~> 7.0 to gems/mysql_genius-desktop/mysql_genius-desktop.gemspec as runtime dependency",
+        "Run bundle install in gems/mysql_genius-desktop",
+        "Create gems/mysql_genius-desktop/lib/mysql_genius/desktop/ssh_tunnel.rb",
+        "SshTunnel.new(ssh_host:, ssh_port: 22, ssh_user:, ssh_key_path: nil, ssh_password: nil, remote_host:, remote_port: 3306, local_port: 0)",
+        "start method: opens SSH connection, sets up port forwarding, returns the allocated local port",
+        "stop method: closes the SSH connection and port forwarding",
+        "running? method: returns boolean",
+        "The tunnel runs in a background thread so it doesn't block the main thread",
+        "If ssh_key_path is provided, use key-based auth. If ssh_password, use password auth. If neither, use ssh-agent",
+        "Raises SshTunnel::ConnectionError with a clear message on failure",
+        "Create spec at gems/mysql_genius-desktop/spec/mysql_genius/desktop/ssh_tunnel_spec.rb",
+        "Desktop gem suite passes",
         "Typecheck passes"
       ],
       "priority": 1,
       "passes": true,
-      "notes": "Thread safety: wrap all reads and writes in a single Mutex. The critical section is microseconds (array append/slice). Use a Hash keyed by digest_text, each value is an Array acting as ring buffer."
+      "notes": "Use Net::SSH.start for the connection and Net::SSH::Gateway or manual forwarding via Net::SSH::Service::Forward. For local_port: 0, bind to an ephemeral port and read the assigned port from the socket. The background thread should keep the SSH connection alive with keepalive packets. Spec can mock Net::SSH.start since we can't open real SSH connections in CI."
     },
     {
       "id": "US-002",
-      "title": "Add StatsCollector background sampler to core gem",
-      "description": "As a developer, I need a background thread that periodically samples performance_schema and computes delta snapshots.",
+      "title": "Add SSH fields to the Database profiles schema",
+      "description": "As a developer, I need the SQLite profiles table to store SSH tunnel configuration.",
       "acceptanceCriteria": [
-        "Create gems/mysql_genius-core/lib/mysql_genius/core/analysis/stats_collector.rb",
-        "initialize(connection_provider:, history:, interval: 60) accepts a callable for connection",
-        "start spawns a background Thread and returns self",
-        "stop signals the thread to exit and joins with 5s timeout",
-        "running? returns boolean",
-        "Each tick: queries performance_schema for top 50 digests by SUM_TIMER_WAIT",
-        "Computes deltas: delta_calls = current - previous, delta_total_time = current - previous",
-        "Records delta snapshot into the StatsHistory instance",
-        "Negative deltas (server restart) recorded as 0",
-        "If performance_schema is unavailable, logs warning and stops (no crash loop)",
-        "Add require to gems/mysql_genius-core/lib/mysql_genius/core.rb",
-        "Create spec at gems/mysql_genius-core/spec/mysql_genius/core/analysis/stats_collector_spec.rb",
-        "Core gem suite passes",
+        "Add columns to the profiles table in Database class: ssh_enabled BOOLEAN DEFAULT 0, ssh_host TEXT, ssh_port INTEGER DEFAULT 22, ssh_user TEXT, ssh_key_path TEXT, ssh_password TEXT, remote_host TEXT, remote_port INTEGER DEFAULT 3306",
+        "The schema migration must be backward-compatible: use ALTER TABLE ADD COLUMN IF NOT EXISTS (or check column existence before adding)",
+        "Database#add_profile and #update_profile accept the new SSH fields",
+        "Database#find_profile and #list_profiles return the new fields",
+        "Update database_spec.rb to test SSH fields round-trip",
+        "Desktop gem suite passes",
         "Typecheck passes"
       ],
       "priority": 2,
       "passes": true,
-      "notes": "The connection_provider is a callable (lambda/proc) that returns a Core::Connection. This lets Rails pass -> { ActiveRecordAdapter.new(ActiveRecord::Base.connection) } and the sidecar pass -> { session.checkout { |a| a } }. Use the same SQL shape as QueryStats#build_sql but hardcoded to top 50 by SUM_TIMER_WAIT. Store @previous hash of {digest => {calls:, total_time_ms:}} for delta computation."
+      "notes": "SQLite doesn't support ADD COLUMN IF NOT EXISTS directly. Use a rescue on the ALTER TABLE or check pragma_table_info for column existence before adding. The ssh_password field stores the SSH password (not the MySQL password). For Tauri app, the SSH password could later move to Keychain — for now store in SQLite alongside the MySQL password."
     },
     {
       "id": "US-003",
-      "title": "Add DIGEST hash to QueryStats return value",
-      "description": "As a developer, I need the DIGEST hex hash in QueryStats output so the detail page can use it as a URL key.",
+      "title": "Wire SSH tunnel into ActiveSession connection flow",
+      "description": "As a user, I want the sidecar to automatically open an SSH tunnel before connecting to MySQL when SSH is enabled on a profile.",
       "acceptanceCriteria": [
-        "Modify gems/mysql_genius-core/lib/mysql_genius/core/analysis/query_stats.rb",
-        "Add DIGEST column to the SELECT in build_sql",
-        "Add digest: row['DIGEST'] to the transform method return hash",
-        "Existing fields unchanged (backward compatible addition)",
-        "Update query_stats_spec to verify the new digest field is present",
-        "Core gem suite passes",
+        "Modify ActiveSession to check if the profile has SSH enabled",
+        "If ssh_enabled: open SshTunnel first, get the local forwarded port, then connect Trilogy to 127.0.0.1:local_port instead of the profile's host:port",
+        "ActiveSession stores a reference to the tunnel and closes it on session.close",
+        "On connection retry (Trilogy::ConnectionResetError), also restart the SSH tunnel",
+        "The Launcher reads SSH fields from the Database and passes them through the Config/profile to ActiveSession",
+        "If SSH connection fails, raise ConnectError with a clear message including the SSH host",
+        "Desktop gem suite passes",
         "Typecheck passes"
       ],
       "priority": 3,
       "passes": true,
-      "notes": "DIGEST is a 64-char hex string computed by MySQL. It's stable across identical query templates. The existing sql field continues to hold the truncated DIGEST_TEXT."
+      "notes": "The flow is: Launcher reads profile from DB -> if ssh_enabled, ActiveSession opens SshTunnel(ssh_host, ..., remote_host=profile.host, remote_port=profile.port) -> tunnel returns local_port -> Trilogy connects to 127.0.0.1:local_port. The profile's host/port become the REMOTE host/port (what the tunnel forwards to), not the direct Trilogy target. This is the key architectural insight."
     },
     {
       "id": "US-004",
-      "title": "Add query detail shared template with SVG charts",
-      "description": "As a user, I want to see a query's SQL, current stats, and time-series performance charts on a dedicated page.",
+      "title": "Add SSH fields to the connections page UI",
+      "description": "As a user, I want to configure SSH tunnel settings when adding or editing a profile.",
       "acceptanceCriteria": [
-        "Create gems/mysql_genius-core/lib/mysql_genius/core/views/mysql_genius/queries/query_detail.html.erb",
-        "Template shows: full SQL in mg-sql-block styled container",
-        "Template shows: Explain button that fires POST /explain",
-        "Template shows: stats summary cards (Calls, Total Time, Avg Time, Max Time, Rows Examined, Rows Sent, First Seen, Last Seen)",
-        "Template shows: three SVG charts stacked vertically (Total Time ms, Average Time ms, Calls)",
-        "SVG charts drawn by a drawChart(containerId, data, label, color) JS function",
-        "Charts use polyline with translucent fill below the line",
-        "Charts have Y axis auto-scaled with 4-5 ticks, X axis with time labels every ~4 hours",
-        "Charts use #89CFF0 line color in light mode, #58a6ff in dark mode",
-        "Chart height is 200px, width responsive (100% of container)",
-        "Page loads data via fetch to GET /api/query_history/:digest on page load",
-        "All JS is inline in the template (no external dependencies)",
+        "Add an 'Enable SSH Tunnel' checkbox to the profile form on /connections",
+        "When checked, show additional fields: SSH Host, SSH Port (default 22), SSH User, SSH Key Path, SSH Password",
+        "SSH Key Path field has a placeholder: ~/.ssh/id_rsa",
+        "SSH Password field uses type=password with the existing eye toggle",
+        "When unchecked, hide the SSH fields",
+        "The form sends ssh_enabled, ssh_host, ssh_port, ssh_user, ssh_key_path, ssh_password in the profile POST/PUT request",
+        "The existing Test Connection button tests through the tunnel when SSH is enabled",
+        "Edit mode populates the SSH fields from the saved profile",
+        "Dark mode works correctly on all new fields",
+        "Desktop gem suite passes",
         "Typecheck passes"
       ],
       "priority": 4,
       "passes": true,
-      "notes": "The template is standalone (not a tab partial). It will be rendered through each adapter's layout. The drawChart function creates an SVG element with: a viewBox for responsive scaling, a polyline for the data series, rect elements or text for axis labels. The Explain button reuses the existing POST /explain endpoint. Data fetched from /api/query_history/:digest returns {query: {...stats...}, history: [{timestamp, calls, total_time_ms, avg_time_ms}, ...]}."
+      "notes": "The checkbox should use a simple <input type='checkbox' id='mg-f-ssh-enabled'>. When it changes, toggle visibility of a div containing the SSH fields. The Test Connection flow: if SSH enabled, first open tunnel (POST /api/test_ssh_tunnel), get local port, then test MySQL connection against 127.0.0.1:local_port. Or simpler: the existing /api/test_connection route handles it server-side (check ssh_enabled in the payload, open tunnel internally, test MySQL, close tunnel)."
     },
     {
       "id": "US-005",
-      "title": "Make Query Stats tab SQL cells clickable links",
-      "description": "As a user, I want to click a query in the stats table to see its detail page.",
+      "title": "Update profile switching to handle SSH tunnels",
+      "description": "As a user, I want SSH tunnels to be properly managed when switching between profiles.",
       "acceptanceCriteria": [
-        "Modify gems/mysql_genius-core/lib/mysql_genius/core/views/mysql_genius/queries/dashboard.html.erb",
-        "In the loadQueryStats JS function, render SQL column as <a href='/queries/:digest'> link",
-        "Link uses the digest hex hash from the query_stats API response",
-        "Link styled with mg-link class or inline color to look clickable",
-        "Existing query stats table layout and sorting still work",
-        "Rails adapter suite passes: bundle exec rspec",
+        "SessionSwapper closes the old SSH tunnel (if any) when switching profiles",
+        "SessionSwapper opens a new SSH tunnel if the new profile has SSH enabled",
+        "The Launcher opens the initial SSH tunnel on boot if the default profile has SSH enabled",
+        "On sidecar shutdown (at_exit), both the MySQL session and SSH tunnel are closed",
+        "Desktop gem suite passes",
         "Typecheck passes"
       ],
       "priority": 5,
       "passes": true,
-      "notes": "The loadQueryStats function is in dashboard.html.erb's inline JS. It currently renders the SQL as plain text in a td. Change it to an anchor tag. The href should use path_for pattern but since this is in JS, just hardcode '/queries/' + digest (the sidecar's PATHS hash and Rails route both serve this path). Also update the dashboard overview's Top 5 Expensive Queries to be clickable."
+      "notes": "ActiveSession already has a close method that the SessionSwapper calls. If ActiveSession holds a reference to the tunnel, session.close should also close the tunnel. The new profile's tunnel opens as part of ActiveSession.new in the swapper."
     },
     {
       "id": "US-006",
-      "title": "Wire stats collector and detail routes into Rails adapter",
-      "description": "As a Rails developer, I want the stats collector to start on boot and the query detail page to be accessible.",
+      "title": "Full green sweep",
+      "description": "As a developer, I need all test suites passing.",
       "acceptanceCriteria": [
-        "Add stats_collection config option (default true) to lib/mysql_genius/configuration.rb",
-        "Add MysqlGenius.stats_history and MysqlGenius.stats_collector module-level accessors to lib/mysql_genius.rb",
-        "Add initializer in lib/mysql_genius/engine.rb that starts StatsCollector when enabled",
-        "Initializer creates StatsHistory, StatsCollector with ActiveRecordAdapter connection_provider, calls start",
-        "Registers at_exit to stop the collector",
-        "Add two routes to config/routes.rb: get 'queries/:digest' and get 'api/query_history/:digest'",
-        "Add query_detail action to QueriesController that renders the shared template",
-        "Add query_history action that returns JSON with current stats + history",
-        "query_history looks up the digest in performance_schema and gets history from MysqlGenius.stats_history",
-        "Add request spec for GET /queries/:digest (returns 200)",
-        "Add request spec for GET /api/query_history/:digest (returns JSON with query and history keys)",
-        "Rails adapter suite passes",
+        "Rails adapter rspec passes (94+ examples)",
+        "Core gem rspec passes (248+ examples)",
+        "Desktop gem rspec passes (202+ examples)",
+        "All rubocops clean",
         "Typecheck passes"
       ],
       "priority": 6,
       "passes": true,
-      "notes": "The connection_provider for Rails is -> { Core::Connection::ActiveRecordAdapter.new(ActiveRecord::Base.connection) }. The query_detail action just renders the template with an @digest instance variable. The query_history action queries performance_schema filtered by DIGEST = :digest for current stats, and calls MysqlGenius.stats_history.series_for(digest_text) for history. If stats_history is nil (collection disabled), return empty history array."
-    },
-    {
-      "id": "US-007",
-      "title": "Wire stats collector and detail routes into desktop sidecar",
-      "description": "As a sidecar user, I want the stats collector running and the query detail page accessible.",
-      "acceptanceCriteria": [
-        "Update gems/mysql_genius-desktop/lib/mysql_genius/desktop/launcher.rb to create StatsHistory + StatsCollector and set on App",
-        "Add App settings: :stats_history, :stats_collector",
-        "Collector uses connection_provider that checks out from the active session",
-        "Register at_exit to stop collector",
-        "Update SessionSwapper to stop old collector, clear history, start new collector on profile switch",
-        "Add GET /queries/:digest route to App (renders query_detail template through layout)",
-        "Add GET /api/query_history/:digest route to App (returns JSON)",
-        "Both new routes are under session-token auth",
-        "Add request spec for the two new routes",
-        "Desktop gem suite passes: (cd gems/mysql_genius-desktop && bundle exec rspec)",
-        "Typecheck passes"
-      ],
-      "priority": 7,
-      "passes": true,
-      "notes": "The connection_provider for the sidecar wraps session.checkout. On profile switch, SessionSwapper should: App.settings.stats_collector&.stop, App.settings.stats_history&.clear, then after swapping the session create a new collector with the new session and start it. The render_query_detail method follows the same pattern as render_dashboard (Tilt through layout)."
-    },
-    {
-      "id": "US-008",
-      "title": "Full green sweep across all suites",
-      "description": "As a developer, I need all test suites and linters passing before the PR.",
-      "acceptanceCriteria": [
-        "Rails adapter rspec passes (78+ examples)",
-        "Core gem rspec passes (194+ examples plus new StatsHistory/StatsCollector/QueryStats specs)",
-        "Desktop gem rspec passes (154+ examples plus new route specs)",
-        "Rails adapter rubocop clean",
-        "Core gem rubocop clean",
-        "Desktop gem rubocop clean",
-        "git diff main -- .github/workflows/publish.yml is empty (untouched)",
-        "No version bumps committed (version bump is a separate release task)",
-        "Typecheck passes"
-      ],
-      "priority": 8,
-      "passes": false,
-      "notes": "Run all six commands in order. If any fail, fix before proceeding. This is a verification step, not an implementation step."
+      "notes": ""
     }
   ]
 }

data/ralph/progress.txt

@@ -1,141 +1,119 @@
 # Ralph Progress Log
-Started: Sun Apr 12 13:52:29 CDT 2026
+Started: Mon Apr 13 06:43:11 CDT 2026
 ---
 
 ## Codebase Patterns
-- Core gem specs use `require "spec_helper"` (no Rails boot), FakeAdapter for connection stubs
-- Analysis classes follow `initialize(connection)` + `#call` pattern
-- Core gem has zero runtime dependencies — no Rails-specific code
-- Spec files mirror the lib directory structure: `lib/mysql_genius/core/analysis/foo.rb` → `spec/mysql_genius/core/analysis/foo_spec.rb`
-- RuboCop uses rubocop-shopify + rubocop-rspec; target Ruby 2.6
-- `Time#iso8601` requires `require 'time'` — use `strftime("%Y-%m-%dT%H:%M:%SZ")` in core gem instead
-- FakeAdapter stubs are searched with `find` (first match wins) — clear `@stubs` via `instance_variable_set(:@stubs, [])` before re-stubbing
-- Use `ConditionVariable` + `Mutex` for interruptible sleep in background threads (cleaner than polling loops)
-- Standalone templates (not partials) must duplicate JS helpers from dashboard since they run in a separate page scope
-- Shared templates use `path_for(:name)` for URLs and `@digest` instance var — adapters must set these before rendering
-- Desktop gem has NO ActiveSupport — never use `.squish` or other AS extensions; use plain string concatenation for SQL
-- Desktop `Core::Result#to_a` returns raw row arrays; use `to_hashes` to get `{column => value}` hashes
-- Desktop `rack_helper.rb` sets `@fake_adapter` via before block — specs using it must disable `RSpec/InstanceVariable`
-- Rails `ActiveRecord::Result` `to_a` returns hashes directly; for specs use `instance_double` with `to_a:` returning hash arrays
-- When adding new App settings to desktop, also reset them in `rack_helper.rb` after block and set in before block
-- `StatsCollector.new` spawns real threads — mock it in request specs via `allow(StatsCollector).to receive(:new)` in rack_helper
-- `path_for(:query_detail)` and `path_for(:query_history)` both need `@digest` to build a complete URL; both adapters handle this in their `path_for` implementation
-- Routes that need a dynamic segment (digest) use base-path + value pattern in desktop PATHS hash; Rails uses named route helpers with keyword arg
-
+- Desktop gem specs use RSpec mocking (allow/receive), NOT Mocha - Mocha is only for the Rails adapter
+- Desktop gem uses `instance_double` for test doubles (VerifiedDoubles cop is disabled)
+- Config objects are built in tests via `Config.allocate` + `instance_variable_set` pattern
+- RSpec/MultipleMemoizedHelpers max is 5 - inline simple constants to stay under the limit
+- Net::SSH is mocked at the class level: `allow(Net::SSH).to(receive(:start).and_return(ssh_session))`
+- SshTunnel event loop runs in a background Thread - test thread existence, not `session.loop` (race condition)
+- SQLite migration: use `PRAGMA table_info(table)` to check column existence before `ALTER TABLE ADD COLUMN`
+- Database profiles use string keys throughout (from `results_as_hash = true`); `ssh_enabled` is INTEGER 0/1
+- ActiveSession.open_adapter_for accepts `tunnel_port:` kwarg — pass it from `session.tunnel_port` in conn_proc lambdas
+- MysqlConfig#ssh_enabled? coerces INTEGER/boolean/string to boolean (handles DB and YAML sources)
+- When SSH enabled, profile.host/port become SshTunnel remote_host/remote_port; Trilogy connects to 127.0.0.1:tunnel_port
+- Instance doubles of ActiveSession must include `tunnel_port: nil` in specs that trigger conn_proc creation
+- Launcher `import_profiles` must include all profile fields — keep in sync when adding new columns to Database schema
+- Use `stub_boot(session:, db_name:)` helper in launcher_spec.rb for full boot mock setup
+- Eye toggle: `.mg-eye-toggle` button with `data-target="input-id"` toggles password/text input type
+- input[type="password"] must be included in both light-mode and dark-mode CSS selectors alongside text/number
+- Layout/MultilineHashKeyLineBreaks cop: each key on its own line in multiline hashes (use rubocop -A to auto-fix)
 ---
 
-## 2026-04-12 - US-001
-- Implemented `StatsHistory` ring buffer in `gems/mysql_genius-core/lib/mysql_genius/core/analysis/stats_history.rb`
-- Thread-safe via Mutex, supports record/series_for/digests/clear, drops oldest on cap
-- Added require to `gems/mysql_genius-core/lib/mysql_genius/core.rb`
-- Created spec at `gems/mysql_genius-core/spec/mysql_genius/core/analysis/stats_history_spec.rb` (9 examples)
-- Files changed: stats_history.rb (new), core.rb (require added), stats_history_spec.rb (new)
-- Core gem suite: 203 examples, 0 failures
-- RuboCop: clean
+## 2026-04-13 - US-001
+- What was implemented: SshTunnel class with start/stop/running? methods, net-ssh dependency, 22 specs
+- Files changed:
+  - gems/mysql_genius-desktop/mysql_genius-desktop.gemspec (added net-ssh ~> 7.0)
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop.rb (added require for ssh_tunnel)
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/ssh_tunnel.rb (new - SshTunnel class)
+  - gems/mysql_genius-desktop/spec/mysql_genius/desktop/ssh_tunnel_spec.rb (new - 22 examples)
 - **Learnings for future iterations:**
-  - The core gem spec suite runs fast (~0.06s) — safe to run full suite on each story
-  - FakeAdapter is only needed for connection-dependent classes; StatsHistory is pure Ruby
-  - Thread safety tests work well with 4 threads × 500 iterations pattern
+  - SshTunnel uses Net::SSH::Service::Forward for port forwarding, NOT Net::SSH::Gateway
+  - Ephemeral port allocation: bind TCPServer to port 0, read assigned port, close immediately
+  - Auth priority: ssh_key_path > ssh_password > ssh-agent (no auth options = agent fallback)
+  - The event loop thread runs `@session.loop(0.5) { @running }` - the 0.5 is the poll interval in seconds
+  - ConnectionError wraps all SSH failures with descriptive messages including host:port
 ---
 
-## 2026-04-12 - US-002
-- Implemented `StatsCollector` background sampler in `gems/mysql_genius-core/lib/mysql_genius/core/analysis/stats_collector.rb`
-- Background thread queries performance_schema for top 50 digests by SUM_TIMER_WAIT
-- Computes per-interval deltas, clamps negatives to 0 (server restart handling)
-- Uses ConditionVariable for interruptible sleep (clean stop within 5s timeout)
-- connection_provider callable pattern: adapters supply their own connection strategy
-- Added require to `gems/mysql_genius-core/lib/mysql_genius/core.rb`
-- Created spec at `gems/mysql_genius-core/spec/mysql_genius/core/analysis/stats_collector_spec.rb` (12 examples)
-- Files changed: stats_collector.rb (new), core.rb (require added), stats_collector_spec.rb (new)
-- Core gem suite: 215 examples, 0 failures
-- RuboCop: clean
+## 2026-04-13 - US-002
+- What was implemented: Added SSH tunnel columns to the profiles SQLite table with backward-compatible migration
+- Files changed:
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/database.rb (schema + migration + add_profile + update_profile)
+  - gems/mysql_genius-desktop/spec/mysql_genius/desktop/database_spec.rb (6 new SSH field specs + legacy migration test)
 - **Learnings for future iterations:**
-  - `Time#iso8601` is not available without `require 'time'` — use `strftime` in zero-dep core gem
-  - FakeAdapter stubs match first-registered-first-matched; clear `@stubs` array before re-stubbing between ticks
-  - Testing background threads: set `@running = true` in `start` (before thread spawn) to eliminate race; use `send(:tick)` to test delta logic directly without timing sensitivity
-  - SQL shape mirrors QueryStats#build_sql but selects only DIGEST_TEXT, COUNT_STAR, total_time_ms
+  - SQLite doesn't support `ADD COLUMN IF NOT EXISTS` — use `PRAGMA table_info(table)` to check column existence before ALTER TABLE
+  - The `migrate_ssh_columns` method runs after `create_schema` so it handles both fresh and legacy databases
+  - `ssh_enabled` is stored as INTEGER (0/1) since SQLite has no native boolean type — use `.to_i` when writing
+  - `find_profile` and `list_profiles` use `SELECT *` so they automatically return new columns without code changes
+  - RSpec/ExampleLength max is 25 lines — extract DB setup into helper methods for longer integration tests
+  - SSH fields use string keys throughout (matching SQLite3 `results_as_hash = true` output)
 ---
 
-## 2026-04-12 - US-003
-- Added `DIGEST` column to `build_sql` SELECT and `digest:` key to `transform` return hash in QueryStats
-- Updated spec columns/rows fixtures to include DIGEST as first column, verified new field in assertions
-- Files changed: `gems/mysql_genius-core/lib/mysql_genius/core/analysis/query_stats.rb`, `gems/mysql_genius-core/spec/mysql_genius/core/analysis/query_stats_spec.rb`
-- Core gem suite: 215 examples, 0 failures
-- Rails adapter suite: 78 examples, 0 failures
-- RuboCop: clean
+## 2026-04-13 - US-003
+- What was implemented: Wired SSH tunnel into ActiveSession connection flow with tunnel lifecycle management
+- Files changed:
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/config/mysql_config.rb (added SSH fields + ssh_enabled? method)
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/active_session.rb (tunnel start/stop/restart, open_adapter_for tunnel_port kwarg)
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/session_swapper.rb (SSH fields in mysql_hash_from_profile, tunnel_port in conn_proc)
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/launcher.rb (tunnel_port in conn_proc)
+  - gems/mysql_genius-desktop/spec/mysql_genius/desktop/active_session_spec.rb (7 new SSH tunnel specs)
+  - gems/mysql_genius-desktop/spec/mysql_genius/desktop/launcher_spec.rb (added tunnel_port to instance_double)
+  - gems/mysql_genius-desktop/spec/mysql_genius/desktop/session_swapper_spec.rb (added tunnel_port to instance_double)
+  - gems/mysql_genius-desktop/spec/requests/profiles_api_spec.rb (added tunnel_port to instance_double)
 - **Learnings for future iterations:**
-  - QueryStats spec uses positional arrays for row data — when adding a new column to the SELECT, prepend/insert it in ALL test row arrays (easy to miss the truncation test at the bottom)
-  - The `transform` method uses case-insensitive column access (`row["DIGEST"] || row["digest"]`) for MariaDB compatibility — follow this pattern for any new columns
+  - ActiveSession manages SSH tunnel lifecycle: start in initialize, stop in close, restart on retry
+  - open_adapter_for(config, tunnel_port: nil) — when tunnel_port is set, connect to 127.0.0.1:tunnel_port instead of config host/port
+  - Profile host/port become SshTunnel remote_host/remote_port — this is the key architectural pattern
+  - SshTunnel::ConnectionError is caught and re-raised as ConnectError with SSH host context
+  - Tunnel restart on Trilogy::ConnectionResetError creates a fresh SshTunnel object (stop old, start new)
+  - StatsCollector conn_proc captures tunnel_port via closure so it routes through the existing tunnel
+  - Any instance_double(ActiveSession) in specs that trigger conn_proc must stub tunnel_port
 ---
 
-## 2026-04-12 - US-004
-- Created standalone `query_detail.html.erb` shared template in core gem views
-- Template includes: full SQL display with syntax highlighting, Copy and EXPLAIN buttons
-- Stats summary cards: Calls, Total Time, Avg Time, Max Time, Rows Examined, Rows Sent, First Seen, Last Seen
-- Three SVG time-series charts: Total Time (ms), Average Time (ms), Calls
-- SVG charts use polyline with translucent fill, auto-scaled Y axis with nice tick values, responsive via viewBox
-- Light mode line color #89CFF0, dark mode #58a6ff (detected via data-theme attribute)
-- Data loaded via fetch to GET /api/query_history/:digest, EXPLAIN via POST /explain
-- All JS is inline (no external dependencies), replicates helper functions from dashboard (highlightSql, formatDuration, ajax, etc.)
-- Files changed: `gems/mysql_genius-core/lib/mysql_genius/core/views/mysql_genius/queries/query_detail.html.erb` (new)
-- Core gem suite: 215 examples, 0 failures
-- Rails adapter suite: 78 examples, 0 failures
-- RuboCop: clean
+## 2026-04-13 - US-004
+- What was implemented: Added SSH tunnel UI fields to the connections page profile form
+- Files changed:
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/connections.html.erb (SSH checkbox, conditional fields, eye toggle, JS updates)
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/app.rb (format_profile, profile_attrs_from_request, update_attrs_from_request, mysql_hash_from_profile, test_connection route with SSH tunnel support)
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/layout.html.erb (input[type="password"] in base + dark mode CSS)
+  - gems/mysql_genius-desktop/spec/requests/profiles_api_spec.rb (3 new specs: SSH create, SSH update, SSH test_connection)
 - **Learnings for future iterations:**
-  - Standalone templates (not tab partials) need their own copies of JS helper functions since they don't share the dashboard's IIFE scope
-  - The template uses `path_for(:root)` for the back link, `path_for(:explain)` for EXPLAIN, `path_for(:query_history)` for data — these routes must exist in both Rails adapter and sidecar
-  - SVG chart viewBox approach (800x200 with preserveAspectRatio="none") makes charts responsive without JS resize handlers
-  - Y-axis nice step calculation: ceil(rawStep/magnitude)*magnitude ensures clean round-number ticks
-  - The `@digest` instance variable must be set by the controller action before rendering this template
+  - Password field was type="text" — changed to type="password" with eye toggle using data-target attribute
+  - Eye toggle pattern: button with class `mg-eye-toggle` and `data-target="input-id"`, toggles input.type between password/text
+  - SSH fields are conditionally shown via `toggleSshFields()` — checkbox change listener toggles `.mg-hidden` on `#mg-ssh-fields` div
+  - `getFormData()` only includes SSH fields when checkbox is checked (sends ssh_enabled: 0 when unchecked)
+  - `fillForm()` must call `toggleSshFields()` after setting checkbox state to show/hide fields on edit
+  - test_connection route opens/closes SshTunnel inline when ssh_enabled — tunnel.stop in both success and rescue paths
+  - input[type="password"] was not in the original CSS selectors — must be added to both light and dark mode rules
+  - Layout/MultilineHashKeyLineBreaks cop requires each hash key on its own line in multiline hashes
 ---
 
-## 2026-04-11 - US-005
-- Updated `dashboard.html.erb` to linkify SQL cells in both loadQueryStats and Top 5 Expensive Queries
-- Added `query_detail: '/queries/'` to ROUTES JS object (base path, digest appended via JS)
-- SQL cells now render `<a href="/queries/:digest" class="mg-link">` when digest is present; fallback to plain text if no digest
-- Files changed: `gems/mysql_genius-core/lib/mysql_genius/core/views/mysql_genius/queries/dashboard.html.erb`
-- Rails adapter suite: 78 examples, 0 failures
-- RuboCop: clean
+## 2026-04-13 - US-005
+- What was implemented: SSH tunnel lifecycle management during profile switching, boot, and shutdown
+- Bug fix: `import_profiles` in Launcher was not importing SSH fields from YAML config to SQLite database
+- Added SessionSwapper specs: SSH fields pass-through, old session/tunnel closure, tunnel_port capture for conn_proc
+- Added Launcher specs: SSH field import, tunnel_port capture for stats collector, shutdown registration
+- Extracted `stub_boot` helper in launcher_spec.rb to keep tests under RSpec/ExampleLength limit
+- Files changed:
+  - gems/mysql_genius-desktop/lib/mysql_genius/desktop/launcher.rb (import_profiles now includes SSH fields)
+  - gems/mysql_genius-desktop/spec/mysql_genius/desktop/session_swapper_spec.rb (3 new SSH switching specs)
+  - gems/mysql_genius-desktop/spec/mysql_genius/desktop/launcher_spec.rb (4 new specs + stub_boot helper)
 - **Learnings for future iterations:**
-  - The ROUTES JS object uses hardcoded base paths (not server-rendered route helpers) for dynamic routes — append the value in JS
-  - `mg-link` class is defined in layout.html.erb (both adapters share the layout's CSS)
+  - Most SSH tunnel lifecycle was already implemented in US-003 via ActiveSession — US-005 was about verifying integration points
+  - import_profiles must be kept in sync with any new profile fields — it's easy to miss when adding columns
+  - Launcher `register_shutdown` uses at_exit — test by capturing the arguments passed to it, not by invoking at_exit
+  - Use `stub_boot` helper in launcher_spec.rb for tests that need the full boot mock setup
+  - StatsCollector conn_proc captures tunnel_port via closure — test by capturing the proc from StatsCollector.new kwargs
 ---
 
-## 2026-04-11 - US-006
-- Added `stats_collection` config option (default: true) to `lib/mysql_genius/configuration.rb`
-- Added `MysqlGenius.stats_history` and `MysqlGenius.stats_collector` module-level accessors to `lib/mysql_genius.rb`
-- Added `config.after_initialize` block in engine.rb that starts StatsCollector when `stats_collection` is enabled
-- Added routes: `get "queries/:digest"` and `get "api/query_history/:digest"` to `config/routes.rb`
-- Added `query_detail` and `query_history` actions to `QueriesController`
-- Updated `SharedViewHelpers#path_for` to auto-inject `@digest` for `:query_detail` and `:query_history` routes
-- Added private helpers `fetch_query_history_current`, `fetch_query_history_series`, `lookup_digest_text`
-- Added request specs in `spec/requests/mysql_genius/query_detail_spec.rb` (4 examples)
-- Files changed: configuration.rb, lib/mysql_genius.rb, engine.rb, config/routes.rb, queries_controller.rb, shared_view_helpers.rb, query_detail_spec.rb (new)
-- Rails adapter suite: 82 examples, 0 failures
-- RuboCop: clean
-- **Learnings for future iterations:**
-  - `ActiveRecord::Result` `instance_double` — use `to_a:` returning hash arrays; use `result.to_a.first` not `result.first` (which needs Enumerable)
-  - Engine's `config.after_initialize` creates the collector in test env too, causing a benign "StatsCollector stopped" warning in tests — this is expected
-  - `path_for` needs to know about digest routes: use an allowlist `%i[query_detail query_history]` and conditionally pass `digest:` param
----
-
-## 2026-04-11 - US-007
-- Updated `Launcher#call` to create StatsHistory + StatsCollector, set on App, register collector in at_exit
-- Added `set :stats_history, nil` and `set :stats_collector, nil` to App settings
-- Updated App `path_for` helper to append `@digest` for `:query_detail` and `:query_history` routes
-- Added `GET /queries/:digest` and `GET /api/query_history/:digest` routes to App (under session-token auth)
-- Added `render_query_detail`, `fetch_query_history_current`, `fetch_query_history_series` private methods
-- Updated SessionSwapper to stop old collector, clear history, create new collector after session swap
-- Added `:root`, `:query_detail`, `:query_history` to desktop PATHS hash
-- Updated `rack_helper.rb` to reset stats settings and stub `StatsCollector.new` globally to prevent background threads in specs
-- Updated `session_swapper_spec.rb` to mock StatsCollector/StatsHistory and handle new `set` keys
-- Added `spec/requests/query_detail_spec.rb` for desktop (4 examples)
-- Files changed: app.rb, paths.rb, launcher.rb, session_swapper.rb, rack_helper.rb, session_swapper_spec.rb, query_detail_spec.rb (new)
-- Desktop suite: 158 examples, 0 failures (was 154)
-- RuboCop: clean
-- **Learnings for future iterations:**
-  - Desktop gem has NO ActiveSupport — never use `.squish`; use explicit string concatenation
-  - `Core::Result#to_a` returns raw row arrays (not hashes) — use `to_hashes` for hash access
-  - When new `SessionSwapper#switch_to` logic creates real background objects, existing integration tests can fail — mock the constructor in rack_helper to prevent threads
-  - Add `# rubocop:disable RSpec/InstanceVariable` at file top + `enable` at bottom when using `@fake_adapter` directly in specs
+## 2026-04-13 - US-006
+- What was verified: Full green sweep across all three gems
+- Results:
+  - Rails adapter: 94 examples, 0 failures
+  - Core gem: 248 examples, 0 failures
+  - Desktop gem: 246 examples, 0 failures
+  - All rubocops clean (166 + 76 + 50 files inspected, no offenses)
+- No code changes required — all suites passed after US-005 commit
 ---

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mysql_genius
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Antarr Byrd
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-12 00:00:00.000000000 Z
+date: 2026-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 0.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.0
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -96,6 +96,9 @@ files:
 - bin/console
 - bin/setup
 - config/routes.rb
+- docs/guides/ai-features.md
+- docs/guides/getting-started-rails.md
+- docs/guides/ssh-tunnel-connections.md
 - docs/screenshots/ai_tools.png
 - docs/screenshots/dashboard.png
 - docs/screenshots/duplicate_indexes.png