mysql_genius 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a35fb751622eaa5cd7bc6fad555020fb5dbf2a9a2f50d50d27ee9b3da6440818
-  data.tar.gz: 1423b66748df1f05b0a9e9ff3868d35905953218443823e9cf2b0a554e88c4db
+  metadata.gz: 4cec94802aff95468c29e6a4612651afa8c31ad134fd67fb44747487f94b02b0
+  data.tar.gz: 5a51de5742dc12032509e115ccc3dfc891f40d72ffb73e2ae048b58e99094289
 SHA512:
-  metadata.gz: 8fbd465309eb1068b2c78cc47e56e93ac98badd97f8df834a306cbda5c114f903f410c5a7e927c6e9079556d2a240e44521290a28b959e9af91805f13b1fe22d
-  data.tar.gz: 2f3fe565bd970da7f1a1ac0f331bc435a59cc5508b1094fdc91003ef01f5fd3fb7782618cc7d55e24e5aec243f597895b5d4bd1238e90b150d5d92ba2cf611ef
+  metadata.gz: bd85efe1037646a105930e8d02b29de18b77a5cc1b410dfa7252674ecdc2e1f8513ec4d1c0228a4f60530d0d623c667bdf83153218313929854961e8440f8eac
+  data.tar.gz: 4ae937b2f2eaad1baf08a9c5010a7fcaa76f87f5de83051dd025d2b78421e00be4c58b51996498175b041e218827f7c76bd123dc82352f3654af23b9c716439a

data/.github/workflows/ci.yml

@@ -65,3 +65,26 @@ jobs:
 
       - name: Run specs
         run: bundle exec rspec
+
+  desktop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Ruby 3.2
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: false
+
+      - name: Install desktop gem dependencies
+        working-directory: gems/mysql_genius-desktop
+        run: bundle install
+
+      - name: Run desktop specs
+        working-directory: gems/mysql_genius-desktop
+        run: bundle exec rspec
+
+      - name: Run desktop rubocop
+        working-directory: gems/mysql_genius-desktop
+        run: bundle exec rubocop

data/.gitignore

@@ -14,3 +14,4 @@ CLAUDE.md
 Gemfile.lock
 *.gem
 docs/superpowers/
+/ralph

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.7.0
+
+### Added
+- **`capability?(name)` helper** in `SharedViewHelpers`. The Rails adapter returns `true` for all capabilities; the desktop sidecar uses it to hide Redis-backed features (slow_queries, anomaly_detection, root_cause) from the shared dashboard templates.
+- **Query detail page** at `GET /queries/:digest` with syntax-highlighted SQL, Explain button, aggregate stats cards, and three inline SVG time-series charts (Total Time, Average Time, Calls).
+- **`Core::Analysis::StatsHistory`** — thread-safe in-memory ring buffer for per-digest query stats snapshots (24hr retention at 60s intervals).
+- **`Core::Analysis::StatsCollector`** — background thread that samples `performance_schema.events_statements_summary_by_digest` every 60s, computes deltas, and records to StatsHistory.
+- **`DIGEST` hash** added to `Core::Analysis::QueryStats` return value for stable URL keys.
+- **Stats collection config option** (`stats_collection`, default `true`) — controls whether the background collector starts on boot.
+- **Query Stats tab linkification** — SQL cells in the Query Stats table are now clickable links to the query detail page.
+- `mysql_genius` now declares runtime dependency on `mysql_genius-core ~> 0.7.0`.
+
 ## 0.6.0
 
 ### Changed

data/Makefile

@@ -0,0 +1,39 @@
+.PHONY: test test-rails test-core test-desktop lint lint-rails lint-core lint-desktop setup sidecar
+
+# Run all test suites
+test: test-rails test-core test-desktop
+
+test-rails:
+	bundle exec rspec
+
+test-core:
+	cd gems/mysql_genius-core && bundle exec rspec
+
+test-desktop:
+	cd gems/mysql_genius-desktop && bundle exec rspec
+
+# Run all linters
+lint: lint-rails lint-core lint-desktop
+
+lint-rails:
+	bundle exec rubocop
+
+lint-core:
+	cd gems/mysql_genius-core && bundle exec rubocop
+
+lint-desktop:
+	cd gems/mysql_genius-desktop && bundle exec rubocop
+
+# Run everything (tests + lint)
+check: test lint
+
+# Install dependencies for all gems
+setup:
+	bundle install
+	cd gems/mysql_genius-core && bundle install
+	cd gems/mysql_genius-desktop && bundle install
+
+# Start the desktop sidecar
+# Usage: make sidecar CONFIG=/path/to/mg.yml
+sidecar:
+	cd gems/mysql_genius-desktop && bundle exec exe/mysql-genius-sidecar $(if $(CONFIG),--config $(CONFIG),)

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

@@ -5,13 +5,21 @@ module MysqlGenius
     extend ActiveSupport::Concern
 
     included do
-      helper_method :path_for, :render_partial
+      helper_method :path_for, :render_partial, :capability?
     end
 
     # URL path helper for shared templates.
     #   path_for(:execute) # => "/mysql_genius/execute" (from engine route helpers)
+    #
+    # When @digest is set (query detail page), routes that require a digest
+    # param (query_detail, query_history) are generated with it automatically.
     def path_for(name)
-      mysql_genius.public_send("#{name}_path")
+      digest_routes = [:query_detail, :query_history]
+      if digest_routes.include?(name) && @digest
+        mysql_genius.public_send("#{name}_path", digest: @digest)
+      else
+        mysql_genius.public_send("#{name}_path")
+      end
     end
 
     # Partial renderer for shared templates.
@@ -19,5 +27,15 @@ module MysqlGenius
     def render_partial(name)
       view_context.render(partial: "mysql_genius/queries/#{name}")
     end
+
+    # Capability flag for shared templates. The Rails adapter always
+    # reports every capability as present because it owns all routes
+    # (including the Redis-backed slow_queries / anomaly_detection /
+    # root_cause features). The Phase 2b sidecar overrides this with a
+    # narrower list in its own Sinatra app, which is why shared templates
+    # gate the associated UI via `<% if capability?(:slow_queries) %>` etc.
+    def capability?(_name)
+      true
+    end
   end
 end

data/app/controllers/mysql_genius/queries_controller.rb

@@ -35,6 +35,27 @@ module MysqlGenius
       end
     end
 
+    def query_detail
+      @digest = params[:digest].to_s
+      render("mysql_genius/queries/query_detail")
+    end
+
+    def query_history
+      digest = params[:digest].to_s
+      db = begin
+        ActiveRecord::Base.connection.current_database
+      rescue
+        nil
+      end
+
+      current_query = fetch_query_history_current(digest, db)
+      history = fetch_query_history_series(digest)
+
+      render(json: { query: current_query, history: history })
+    rescue StandardError => e
+      render(json: { error: e.message }, status: :unprocessable_entity)
+    end
+
     def slow_queries
       unless mysql_genius_config.redis_url.present?
         return render(json: [], status: :ok)
@@ -59,5 +80,54 @@ module MysqlGenius
     def queryable_tables
       ActiveRecord::Base.connection.tables - mysql_genius_config.blocked_tables
     end
+
+    def fetch_query_history_current(digest, db)
+      sql = <<~SQL.squish
+        SELECT DIGEST_TEXT, COUNT_STAR AS calls,
+               ROUND(SUM_TIMER_WAIT / 1000000000.0, 2) AS total_time_ms,
+               ROUND(AVG_TIMER_WAIT / 1000000000.0, 2) AS avg_time_ms,
+               ROUND(MAX_TIMER_WAIT / 1000000000.0, 2) AS max_time_ms,
+               SUM_ROWS_EXAMINED AS rows_examined,
+               SUM_ROWS_SENT AS rows_sent,
+               FIRST_SEEN, LAST_SEEN
+        FROM performance_schema.events_statements_summary_by_digest
+        WHERE DIGEST = '#{digest.gsub("'", "''")}'
+        #{"AND SCHEMA_NAME = '#{db.to_s.gsub("'", "''")}'" if db}
+        LIMIT 1
+      SQL
+      result = ActiveRecord::Base.connection.exec_query(sql)
+      return if result.rows.empty?
+
+      row = result.to_a.first
+      {
+        sql: row["DIGEST_TEXT"],
+        calls: row["calls"],
+        total_time_ms: row["total_time_ms"].to_f,
+        avg_time_ms: row["avg_time_ms"].to_f,
+        max_time_ms: row["max_time_ms"].to_f,
+        rows_examined: row["rows_examined"],
+        rows_sent: row["rows_sent"],
+        first_seen: row["FIRST_SEEN"].to_s,
+        last_seen: row["LAST_SEEN"].to_s,
+      }
+    end
+
+    def fetch_query_history_series(digest)
+      return [] unless MysqlGenius.stats_history
+
+      digest_text = lookup_digest_text(digest)
+      return [] unless digest_text
+
+      MysqlGenius.stats_history.series_for(digest_text)
+    end
+
+    def lookup_digest_text(digest)
+      sql = <<~SQL.squish
+        SELECT DIGEST_TEXT FROM performance_schema.events_statements_summary_by_digest
+        WHERE DIGEST = '#{digest.gsub("'", "''")}' LIMIT 1
+      SQL
+      result = ActiveRecord::Base.connection.exec_query(sql)
+      result.rows.empty? ? nil : result.to_a.first["DIGEST_TEXT"]
+    end
   end
 end

data/config/routes.rb

@@ -6,6 +6,8 @@ MysqlGenius::Engine.routes.draw do
   get  "columns",      to: "queries#columns"
   post "execute",      to: "queries#execute"
   post "explain",      to: "queries#explain"
+  get  "queries/:digest", to: "queries#query_detail", as: "query_detail"
+  get  "api/query_history/:digest", to: "queries#query_history", as: "query_history"
   post "suggest",      to: "queries#suggest"
   post "optimize",     to: "queries#optimize"
   get  "slow_queries",      to: "queries#slow_queries"

data/lib/mysql_genius/configuration.rb

@@ -66,6 +66,12 @@ module MysqlGenius
     # Defaults to "ActionController::Base".
     attr_accessor :base_controller
 
+    # Whether to start the background stats collector on boot.
+    # When enabled, performance_schema is sampled periodically and stored
+    # in an in-memory ring buffer accessible via MysqlGenius.stats_history.
+    # Defaults to true.
+    attr_accessor :stats_collection
+
     def initialize
       @featured_tables = []
       @blocked_tables = [
@@ -89,6 +95,7 @@ module MysqlGenius
       @redis_url = nil
       @audit_logger = nil
       @base_controller = "ActionController::Base"
+      @stats_collection = true
     end
 
     def ai_enabled?

data/lib/mysql_genius/engine.rb

@@ -13,6 +13,19 @@ module MysqlGenius
         require "mysql_genius/slow_query_monitor"
         MysqlGenius::SlowQueryMonitor.subscribe!
       end
+
+      if MysqlGenius.configuration.stats_collection
+        history = MysqlGenius::Core::Analysis::StatsHistory.new
+        connection_provider = -> { MysqlGenius::Core::Connection::ActiveRecordAdapter.new(ActiveRecord::Base.connection) }
+        collector = MysqlGenius::Core::Analysis::StatsCollector.new(
+          connection_provider: connection_provider,
+          history: history,
+        )
+        MysqlGenius.stats_history = history
+        MysqlGenius.stats_collector = collector
+        collector.start
+        at_exit { collector.stop }
+      end
     end
   end
 end

data/lib/mysql_genius/version.rb

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

data/lib/mysql_genius.rb

@@ -20,6 +20,9 @@ module MysqlGenius
     def reset_configuration!
       @configuration = Configuration.new
     end
+
+    attr_accessor :stats_history
+    attr_accessor :stats_collector
   end
 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.6.0")
+  spec.add_dependency("mysql_genius-core", "~> 0.7.0")
   spec.add_dependency("railties", ">= 6.0", "< 9")
 end

data/ralph/prd.json

@@ -0,0 +1,174 @@
+{
+  "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",
+  "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.",
+      "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)",
+        "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."
+    },
+    {
+      "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.",
+      "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",
+        "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."
+    },
+    {
+      "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.",
+      "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",
+        "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."
+    },
+    {
+      "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.",
+      "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)",
+        "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}, ...]}."
+    },
+    {
+      "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.",
+      "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",
+        "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."
+    },
+    {
+      "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.",
+      "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",
+        "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."
+    }
+  ]
+}

data/ralph/progress.txt

@@ -0,0 +1,141 @@
+# Ralph Progress Log
+Started: Sun Apr 12 13:52:29 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
+
+---
+
+## 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
+- **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
+---
+
+## 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
+- **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
+---
+
+## 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
+- **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
+---
+
+## 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
+- **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
+---
+
+## 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
+- **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)
+---
+
+## 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
+---

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mysql_genius
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Antarr Byrd
@@ -36,14 +36,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.7.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.7.0
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -83,6 +83,7 @@ files:
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
+- Makefile
 - README.md
 - Rakefile
 - app/controllers/concerns/mysql_genius/ai_features.rb
@@ -111,6 +112,8 @@ files:
 - lib/mysql_genius/slow_query_monitor.rb
 - lib/mysql_genius/version.rb
 - mysql_genius.gemspec
+- ralph/prd.json
+- ralph/progress.txt
 homepage: https://github.com/antarr/mysql_genius
 licenses:
 - MIT