mysql_genius 0.7.2 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d2b3f6350a4c464b3ec546a5248a9b1db4dc933e80e2da26472012367740828
-  data.tar.gz: 13ffee6262a381bb970cf6f9e473c95e40161d191249228225b6960aec7c9313
+  metadata.gz: 637da7a2a5441d7195dc1c978e40e7289e7f0ba5db68c55b6696363dcee3c313
+  data.tar.gz: 0b37933d2a0faa1ae8803456c6c2ebb8cf179e182b2aeaac3fe1e67b22d42d10
 SHA512:
-  metadata.gz: 350005c5824825d20f187099dab6f181eb476d1b99441fdf2101f09430b4bb23abff72bbbae487f9a58bca43de02a20213e508980dbb407577678c45bbdf3f08
-  data.tar.gz: c372b88067e33f91b89840e994733ffb5a810ac0bdf38a582e32e240126d026871babe689911a4655bf7a1ba1d0e7664e4f3c7185ba1a96472a6f65d349ecfec
+  metadata.gz: 26b1727acbcd3745da3d17a4ae9837efc63a3417d73a4ac3b3ae0220b423e96f735c9d2c4cf716e351fc31d8e34b6524331c1af30e7c3e2be5a711102b045f1d
+  data.tar.gz: 0ae1270e27a4bf2183e9a1f2a14dcdf2c1c1ec4ee5fe6184a807ea96f3d0a97036182dc2968f690e9f9f4e660b98ec58546f131a41b22674ef2963feb6c2c7bf

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.8.1
+
+### Fixed
+- **Older MySQL compatibility** — the `DIGEST` column in `performance_schema.events_statements_summary_by_digest` is not present on all MySQL/MariaDB versions. `QueryStats` now checks for column existence before including it in the SELECT. Query links in the Query Stats tab gracefully degrade to plain text when the digest is unavailable.
+
+## 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

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/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.2"
+  VERSION = "0.8.1"
 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.2")
+  spec.add_dependency("mysql_genius-core", "~> 0.8.0")
   spec.add_dependency("railties", ">= 6.0", "< 9")
 end

data/ralph/prd.json

@@ -1,149 +1,117 @@
 {
   "project": "MysqlGenius",
-  "branchName": "ralph/sqlite-migration",
-  "description": "Replace in-memory StatsHistory and YAML ProfileManager with SQLite for persistent stats and clean profile CRUD in the desktop sidecar",
+  "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 sqlite3 dependency and create Database class with schema",
-      "description": "As a developer, I need a Database class that manages a SQLite file with profiles, settings, and stats_snapshots tables.",
+      "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": [
-        "Add sqlite3 ~> 2.0 to gems/mysql_genius-desktop/mysql_genius-desktop.gemspec as runtime dependency",
+        "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/database.rb",
-        "Database.new(path) creates the SQLite file if missing and runs CREATE TABLE IF NOT EXISTS for all 3 tables",
-        "profiles table: name TEXT PRIMARY KEY, host TEXT NOT NULL, port INTEGER DEFAULT 3306, username TEXT NOT NULL, password TEXT DEFAULT '', database_name TEXT NOT NULL, tls_mode TEXT DEFAULT 'preferred', created_at TEXT, updated_at TEXT",
-        "settings table: key TEXT PRIMARY KEY, value TEXT",
-        "stats_snapshots table: id INTEGER PRIMARY KEY AUTOINCREMENT, digest_text TEXT NOT NULL, timestamp TEXT NOT NULL, delta_calls INTEGER DEFAULT 0, delta_total_time_ms REAL DEFAULT 0, delta_avg_time_ms REAL DEFAULT 0",
-        "Index on stats_snapshots(digest_text, timestamp)",
-        "Profile CRUD: list_profiles returns array of hashes, find_profile(name) returns hash or nil, add_profile(attrs) inserts (raises on duplicate), update_profile(name, attrs) updates (raises if not found), delete_profile(name) deletes (raises if not found)",
-        "Settings: get_setting(key) returns string or nil, set_setting(key, value) upserts, get_ai_config returns hash of ai.* keys with prefix stripped, set_ai_config(hash) writes each key with ai. prefix",
-        "Stats: record_snapshot(digest_text, snapshot_hash) inserts + prunes rows older than 24 hours, series_for(digest_text) returns ordered array last 24hr, digests returns distinct digest_texts, clear deletes all",
-        "Create spec at gems/mysql_genius-desktop/spec/mysql_genius/desktop/database_spec.rb with tests for all CRUD operations using tmpdir",
+        "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": "Use raw sqlite3 gem calls, no ORM. Thread safety: SQLite WAL mode handles concurrent reads. Error classes: Database::DuplicateProfileError, Database::ProfileNotFoundError. The spec should use Dir.mktmpdir for isolated DB files per test."
+      "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": "Create SqliteStatsHistory as drop-in replacement for StatsHistory",
-      "description": "As a developer, I need a SQLite-backed stats history with the same API as the in-memory StatsHistory so the StatsCollector works unchanged.",
+      "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-desktop/lib/mysql_genius/desktop/sqlite_stats_history.rb",
-        "SqliteStatsHistory.new(database) takes a Database instance",
-        "record(digest_text, snapshot_hash) delegates to database.record_snapshot",
-        "series_for(digest_text) delegates to database.series_for, returns array of hashes with symbol keys (timestamp:, calls:, total_time_ms:, avg_time_ms:)",
-        "digests delegates to database.digests",
-        "clear delegates to database.clear",
-        "Same public API as MysqlGenius::Core::Analysis::StatsHistory (record, series_for, digests, clear)",
-        "Create spec at gems/mysql_genius-desktop/spec/mysql_genius/desktop/sqlite_stats_history_spec.rb",
+        "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 StatsCollector passes snapshot hashes with string keys from its tick method. SqliteStatsHistory should accept both string and symbol keys. The series_for return format must match what the query_detail template JS expects: [{timestamp:, calls:, total_time_ms:, avg_time_ms:}]."
+      "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 first-boot YAML import logic to Launcher",
-      "description": "As a user, I want my existing YAML profiles and AI config automatically imported into SQLite on first boot.",
+      "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-desktop/lib/mysql_genius/desktop/launcher.rb",
-        "After Config.load, create Database.new at ~/.config/mysql_genius/mysql_genius.db (create dir if needed)",
-        "If database.list_profiles is empty AND config.profiles is not empty, import each profile into SQLite",
-        "If database.get_setting('ai.endpoint') is nil AND config.ai.endpoint is present, import AI config into SQLite",
-        "Set App.set(:database, db)",
-        "Create SqliteStatsHistory.new(db) and pass to StatsCollector instead of StatsHistory.new",
-        "Add require statements for database and sqlite_stats_history to desktop.rb",
-        "Existing desktop specs still pass (rack_helper needs updating to inject a test Database)",
+        "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": "The rack_helper.rb needs to create a tmpdir-based Database and set it on the App via App.set(:database, db). Ensure mkdir_p for ~/.config/mysql_genius/ before creating the DB. The import only runs when the DB is empty — deleting mysql_genius.db forces re-import on next boot."
+      "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": "Rewire profile API routes to use Database",
-      "description": "As a user, I want the /connections page to read and write profiles from SQLite instead of YAML.",
+      "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": [
-        "Modify gems/mysql_genius-desktop/lib/mysql_genius/desktop/app.rb",
-        "GET /api/profiles reads from settings.database.list_profiles + settings.current_profile_name",
-        "POST /api/profiles calls settings.database.add_profile, returns updated list",
-        "PUT /api/profiles/:name calls settings.database.update_profile, returns updated list",
-        "DELETE /api/profiles/:name calls settings.database.delete_profile (rejects active profile), returns updated list",
-        "POST /api/test_connection unchanged (no storage involved)",
-        "POST /api/profiles/:name/connect reads profile from settings.database.find_profile",
-        "GET /api/ai_config reads from settings.database.get_ai_config",
-        "PUT /api/ai_config writes to settings.database.set_ai_config + reloads into running app",
-        "Remove require for profile_manager from app.rb",
-        "Update profiles_api_spec.rb to use Database instead of YAML tmpdir",
+        "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": "Error mapping: Database::DuplicateProfileError -> 409, Database::ProfileNotFoundError -> 404. The active-profile-delete check stays in the route handler (check settings.current_profile_name before calling delete). The connect route builds a MysqlConfig from the DB hash: Config::MysqlConfig.from_hash(profile_hash)."
+      "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": "Rewire SessionSwapper to use Database",
-      "description": "As a developer, I need SessionSwapper to look up profiles from SQLite instead of Config.",
+      "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-desktop/lib/mysql_genius/desktop/session_swapper.rb",
-        "Change initialize to accept (app_class, config, database) instead of (app_class, config)",
-        "switch_to looks up profile via @database.find_profile(name) instead of @config.profile_by_name(name)",
-        "Build MysqlConfig from the DB hash via Config::MysqlConfig.from_hash(profile)",
-        "Update all callers of SessionSwapper.new to pass the database",
-        "Update session_swapper_spec.rb",
+        "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 profile hash from Database has string keys (host, port, etc). MysqlConfig.from_hash handles both string and symbol keys via transform_keys. The build_switch_config method still creates a Config.allocate with profiles array for ActiveSession compatibility."
+      "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": "Delete ProfileManager and clean up",
-      "description": "As a developer, I want to remove the dead ProfileManager code now that Database handles everything.",
+      "title": "Full green sweep",
+      "description": "As a developer, I need all test suites passing.",
       "acceptanceCriteria": [
-        "Delete gems/mysql_genius-desktop/lib/mysql_genius/desktop/profile_manager.rb",
-        "Delete gems/mysql_genius-desktop/spec/mysql_genius/desktop/profile_manager_spec.rb",
-        "Remove require 'mysql_genius/desktop/profile_manager' from desktop.rb",
-        "Remove require 'mysql_genius/desktop/profile_manager' from app.rb if present",
-        "Grep the entire desktop gem for 'ProfileManager' references and remove any remaining",
-        "Desktop gem suite passes",
-        "All 3 rubocops pass",
+        "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": "Make sure no spec files reference ProfileManager. The Database class error classes (DuplicateProfileError, ProfileNotFoundError) replace ProfileManager's error classes — verify the route handlers rescue the correct class names."
-    },
-    {
-      "id": "US-007",
-      "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 (82+ examples)",
-        "Core gem rspec passes (215+ examples)",
-        "Desktop gem rspec passes (150+ examples)",
-        "Rails adapter rubocop clean",
-        "Core gem rubocop clean",
-        "Desktop gem rubocop clean",
-        "No changes to mysql_genius-core or mysql_genius Rails adapter source files",
-        "publish.yml untouched",
-        "Typecheck passes"
-      ],
-      "priority": 7,
-      "passes": true,
-      "notes": "Run all six commands. If any fail, fix before marking complete."
+      "notes": ""
     }
   ]
 }

data/ralph/progress.txt

@@ -1,138 +1,119 @@
 # Ralph Progress Log
-Started: Sun Apr 12 23:47:10 CDT 2026
+Started: Mon Apr 13 06:43:11 CDT 2026
 ---
 
 ## Codebase Patterns
-- Desktop gem specs use `Dir.mktmpdir` for isolated file-based test fixtures (DB files, YAML configs)
-- Desktop gem rubocop config inherits from root `.rubocop.yml` via `inherit_from`
-- Desktop gem Gemfile.lock is not tracked in git (gem convention)
-- Use `results_as_hash = true` on SQLite3::Database to get hash-style row access
-- Desktop app settings are injected via `App.set(:key, value)` (Sinatra pattern)
-- Launcher private methods can be stubbed via `allow(launcher).to(receive(:method_name))` in RSpec
-- First-boot import logic: only runs when DB is empty (list_profiles.empty? / get_setting returns nil)
-- rack_helper.rb must set `App.set(:database, ...)` for request specs that depend on DB settings
-- Database returns `database_name` key; `MysqlConfig.from_hash` expects `database` — remap via `mysql_hash_from_profile`
-- Profile API response must be `{name:, mysql: {host:, port:, database:, ...}}` — use `format_profile` to reshape DB rows
+- 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-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:**
+  - 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-001
-- What was implemented:
-  - Added `sqlite3 ~> 2.0` runtime dependency to `mysql_genius-desktop.gemspec`
-  - Created `Database` class at `lib/mysql_genius/desktop/database.rb` with:
-    - SQLite WAL mode for concurrent reads
-    - 3 tables: profiles, settings, stats_snapshots
-    - Composite index on stats_snapshots(digest_text, timestamp)
-    - Full profile CRUD: list_profiles, find_profile, add_profile, update_profile, delete_profile
-    - Settings: get_setting, set_setting, get_ai_config, set_ai_config
-    - Stats: record_snapshot (with 24hr pruning), series_for, digests, clear
-    - Error classes: DuplicateProfileError, ProfileNotFoundError
-  - Created comprehensive spec at `spec/mysql_genius/desktop/database_spec.rb` (29 examples)
+## 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/mysql_genius-desktop.gemspec` (added sqlite3 dep)
-  - `gems/mysql_genius-desktop/lib/mysql_genius/desktop/database.rb` (new)
-  - `gems/mysql_genius-desktop/spec/mysql_genius/desktop/database_spec.rb` (new)
+  - 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:**
-  - ISO 8601 timestamps have second precision — `sleep(0.01)` is not enough to test timestamp changes, need `sleep(1.1)`
-  - RSpec `let` is lazy — must reference the variable in the test body before asserting on side effects like file creation
-  - `Naming/AccessorMethodName` cop flags `get_`/`set_` prefixes — disable inline when API names are mandated by the PRD
-  - `add_profile` accepts both `database_name` and `database` keys for compatibility with existing config hash shapes
+  - 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-13 - US-003
-- What was implemented:
-  - Modified `launcher.rb` to create Database at `~/.config/mysql_genius/mysql_genius.db`
-  - Added first-boot YAML import: profiles imported when DB empty, AI config imported when endpoint missing
-  - Replaced `StatsHistory.new` with `SqliteStatsHistory.new(db)` for persistent stats
-  - Added `App.set(:database, db)` to wire Database into Sinatra settings
-  - Added `database` and `sqlite_stats_history` requires to `desktop.rb`
-  - Added `set :database, nil` to `app.rb` settings
-  - Updated `rack_helper.rb` to create tmpdir-based test Database for request specs
-  - Updated `launcher_spec.rb` to stub `open_database` and verify Database wiring
+- What was implemented: Wired SSH tunnel into ActiveSession connection flow with tunnel lifecycle management
 - Files changed:
-  - `gems/mysql_genius-desktop/lib/mysql_genius/desktop/launcher.rb` (modified)
-  - `gems/mysql_genius-desktop/lib/mysql_genius/desktop/app.rb` (added database setting)
-  - `gems/mysql_genius-desktop/lib/mysql_genius/desktop.rb` (added requires)
-  - `gems/mysql_genius-desktop/spec/rack_helper.rb` (inject test Database)
-  - `gems/mysql_genius-desktop/spec/mysql_genius/desktop/launcher_spec.rb` (updated)
+  - 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:**
-  - `open_database` extracted as private method so specs can stub it without touching filesystem
-  - Import logic checks DB emptiness, not config emptiness — deleting mysql_genius.db forces re-import
-  - Profile import maps `mysql.database` → `database_name` for Database schema compatibility
-  - rack_helper cleanup: must `FileUtils.remove_entry` tmpdir in after block to avoid leftover test DBs
+  - 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-13 - US-004
-- What was implemented:
-  - Rewired all profile API routes (GET/POST/PUT/DELETE) in `app.rb` to use `Database` instead of `ProfileManager`
-  - Added `GET /api/ai_config` and `PUT /api/ai_config` routes backed by Database settings
-  - Removed `require 'mysql_genius/desktop/profile_manager'` from `app.rb`
-  - Added `switch_to_config(name, mysql_config)` to `SessionSwapper` for pre-built MysqlConfig objects
-  - Inlined `test_connection` logic in the route handler (was delegated to ProfileManager)
-  - Added private helpers: `format_profile`, `profile_attrs_from_request`, `update_attrs_from_request`, `mysql_hash_from_profile`, `build_minimal_config`, `reload_ai_config_from_database`
-  - Rewrote `profiles_api_spec.rb` to seed test data via `@test_database.add_profile` instead of YAML tmpdir
-  - Added specs for `GET /api/ai_config`, `PUT /api/ai_config`, and `POST /api/profiles/:name/connect` with unknown profile
+- What was implemented: Added SSH tunnel UI fields to the connections page profile form
 - Files changed:
-  - `gems/mysql_genius-desktop/lib/mysql_genius/desktop/app.rb` (rewired routes, removed ProfileManager require)
-  - `gems/mysql_genius-desktop/lib/mysql_genius/desktop/session_swapper.rb` (added switch_to_config method)
-  - `gems/mysql_genius-desktop/spec/requests/profiles_api_spec.rb` (rewrote for Database)
+  - 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:**
-  - Database returns `database_name` key but `MysqlConfig.from_hash` expects `database` — need `mysql_hash_from_profile` helper to remap
-  - Profile API response format must be `{name:, mysql: {host:, port:, database:, ...}}` to match frontend expectations (connections.html.erb)
-  - `SessionSwapper.switch_to_config` allows callers that already have a MysqlConfig to skip the config lookup
-  - Active profile delete check stays in route handler, not in Database (Database.delete_profile has no concept of "active")
+  - 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-13 - US-005
-- What was implemented:
-  - Changed `SessionSwapper.initialize` to accept `(app_class, config, database)` instead of `(app_class, config)`
-  - Rewired `switch_to` to look up profiles via `@database.find_profile(name)` instead of `@config.profile_by_name(name)`
-  - Added `mysql_hash_from_profile` private helper to remap `database_name` → `database` for `MysqlConfig.from_hash`
-  - Changed `switch_to_config` to create `SqliteStatsHistory.new(@database)` instead of in-memory `StatsHistory.new`
-  - Updated the caller in `app.rb` connect route to pass `settings.database` as third arg
-  - Rewrote `session_swapper_spec.rb` to use a tmpdir-based Database instead of Config profile lookup
+- 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/session_swapper.rb` (rewired to use Database)
-  - `gems/mysql_genius-desktop/lib/mysql_genius/desktop/app.rb` (updated SessionSwapper.new call)
-  - `gems/mysql_genius-desktop/spec/mysql_genius/desktop/session_swapper_spec.rb` (rewrote for Database)
+  - 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:**
-  - `RSpec/MultipleMemoizedHelpers` max is 5 (subject excluded via AllowSubject). Inline tmpdir into `let(:database)` via `Dir.mktmpdir` to avoid extra helper
-  - `mysql_hash_from_profile` is duplicated between `app.rb` and `session_swapper.rb` — could be extracted to a shared module in US-006 cleanup if desired
-  - `switch_to_config` is still used by the connect route in `app.rb` which pre-builds the MysqlConfig — `switch_to` is for callers that only have a profile name
+  - 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-13 - US-006
-- What was implemented:
-  - Deleted `profile_manager.rb` source file
-  - Deleted `profile_manager_spec.rb` spec file
-  - Removed `require "mysql_genius/desktop/profile_manager"` from `desktop.rb`
-  - Verified no remaining `ProfileManager` or `profile_manager` references in the desktop gem
-  - Confirmed route handlers already rescue `Database::DuplicateProfileError` / `Database::ProfileNotFoundError` (not ProfileManager versions)
-- Files changed:
-  - `gems/mysql_genius-desktop/lib/mysql_genius/desktop/profile_manager.rb` (deleted)
-  - `gems/mysql_genius-desktop/spec/mysql_genius/desktop/profile_manager_spec.rb` (deleted)
-  - `gems/mysql_genius-desktop/lib/mysql_genius/desktop.rb` (removed require line)
-- **Learnings for future iterations:**
-  - US-004 already removed `profile_manager` require from `app.rb`, so only `desktop.rb` needed updating
-  - All error classes were already migrated to `Database::` namespace in US-001/US-004 — cleanup was straightforward
-  - 190 desktop specs pass, all 3 rubocops clean after removal
----
-
-## 2026-04-13 - US-007
-- What was implemented:
-  - Full green sweep: ran all 6 quality commands and verified all pass
-  - Rails adapter rspec: 82 examples, 0 failures
-  - Core gem rspec: 215 examples, 0 failures
-  - Desktop gem rspec: 190 examples, 0 failures
-  - Rails adapter rubocop: 152 files, no offenses
-  - Core gem rubocop: 64 files, no offenses
-  - Desktop gem rubocop: 48 files, no offenses
-  - Verified no changes to mysql_genius-core or mysql_genius Rails adapter source files
-  - Verified publish.yml untouched
-- Files changed:
-  - `ralph/prd.json` (marked US-007 passes: true)
-  - `ralph/progress.txt` (this entry)
-- **Learnings for future iterations:**
-  - All 487 examples across 3 suites (82 + 215 + 190) pass — the SQLite migration touched only the desktop gem
-  - The .DS_Store files appear as untracked — these should stay ignored (not committed)
+- 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mysql_genius
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.1
 platform: ruby
 authors:
 - Antarr Byrd
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.2
+        version: 0.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.2
+        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