specbook 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fbe6bd3cae173a5362be3eba0fa808aa86b61710b7b73fcd62a0cc3e0d2cdde2
+  data.tar.gz: d25e69ae37f61f774b7ba69d8852a2a20d086ee25f3b6192580d7507b94517ca
+SHA512:
+  metadata.gz: 61f255a8d466af91f661b3dd9bbff207bea0ba6f05fe165818bde828c0d8ee9dbe80e3647936c53f8815a9acf292d543b7fd237c3b886b51cfe129ff3be8c961
+  data.tar.gz: b87c652c342e17667ad19e1cace665473ffee25813055dc24d0d35df1157e7764fd9d12541bd064fa1619aa5b908886148013c9b1814285b5d0ca2b0ab04c272

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to Specbook are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-04-28
+
+First public release.
+
+### Added
+- Mountable Rails engine (`mount Specbook::Engine => "/specs"`).
+- Screenshot recorder (`RECORD_SPECS=1`) — captures Capybara screenshots + element bounding boxes after each step.
+- Playwright trace recorder (`RECORD_TRACES=1`) — captures Playwright traces and serves them via `npx playwright show-trace`.
+- Configurable seams: `authorize_with`, `screenshot_root`, `trace_root`, `feature_root`, `actor_colors`, `ui_domains`, `setup_overlay_rules`, `back_link`, `editor_base`, `max_runs`, `trace_viewer_port`.
+- Sensible default overlay rules (login → 🔑, exists → 🔧, redirected → ✅).
+- Install generator: `rails generate specbook:install`.
+- Engine-internal test suite with dummy Rails app at `spec/dummy/`.
+- GitHub Actions CI matrix: Ruby 3.1–3.3 × Rails 7.1–8.0.
+
+## [0.1.0.alpha] — 2026-04-25
+
+Internal vendoring milestone; not published.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Leung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# Specbook
+
+**Storybook for your Rails specs. Record. Replay. Review.**
+
+Specbook is a Rails engine that turns your RSpec system specs and Turnip features into a browsable, animated walkthrough — screenshots with element overlays, Gherkin step cards with syntax-highlighted Ruby source, and a Playwright trace viewer launcher.
+
+## Why
+
+Reading test output is fine for CI. But when you want to:
+
+- Show a designer what the new flow actually looks like
+- Onboard a new dev to the codebase by showing what the specs cover
+- Debug a flaky test by replaying the screenshot timeline
+- Demo to a stakeholder what's been built without spinning up the app
+
+…you want a viewer, not a log file.
+
+## Install
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "specbook"
+end
+```
+
+```bash
+bundle install
+```
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+mount Specbook::Engine => "/specs"
+```
+
+Configure in `config/initializers/specbook.rb`:
+
+```ruby
+Specbook.configure do |config|
+  # Authorize who can view the player. Default: dev/test only.
+  config.authorize_with = ->(controller) { controller.current_user&.admin? }
+
+  # Optional: a "back" link in the top bar.
+  config.back_link = { href: "/admin", text: "← Back to admin" }
+
+  # Optional: VS Code link base for jumping to spec source.
+  config.editor_base = "vscode://file#{Rails.root}"
+
+  # Optional: per-actor colors for visual differentiation in the viewer.
+  config.actor_colors = { "Alice" => "#3b82f6", "Bob" => "#f59e0b" }
+
+  # Optional: directory groupings for the sidebar.
+  config.ui_domains = %w[admin public mobile]
+end
+```
+
+Add the recorder hooks to `spec/rails_helper.rb`:
+
+```ruby
+require "specbook/rspec"
+```
+
+## Record specs
+
+Run your system specs with `RECORD_SPECS=1` to capture screenshots:
+
+```bash
+CI=1 RECORD_SPECS=1 bundle exec rspec spec/system/
+```
+
+For Playwright traces:
+
+```bash
+RECORD_TRACES=1 bundle exec rspec spec/system/
+```
+
+Visit your mount point (e.g. `/specs`) to view.
+
+## Configuration
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `authorize_with` | Proc | dev/test only | Lambda receiving the controller; return truthy to allow access |
+| `screenshot_root` | Pathname | `Rails.root.join("tmp/spec_screenshots")` | Where screenshots + manifest land |
+| `trace_root` | Pathname | `Rails.root.join("tmp/spec_traces")` | Where Playwright traces land |
+| `feature_root` | Pathname | `Rails.root` | Project root for resolving `.feature` paths in the manifest |
+| `max_runs` | Integer | 20 | Number of historical runs kept |
+| `trace_viewer_port` | Integer | 9322 | Port for Playwright trace server |
+| `actor_colors` | Hash | `{}` | Name → hex color for spec actors |
+| `ui_domains` | Array | `[]` | Top-level sidebar groupings |
+| `setup_overlay_rules` | Array | login/exists/redirect | Pattern → icon for non-screenshot steps |
+| `back_link` | Hash | `nil` | `{ href:, text: }` — top-bar back link |
+| `editor_base` | String | `nil` | URL prefix for opening files in editor (e.g. `"vscode://file/path"`) |
+
+## Compatibility
+
+- Rails 7.1+
+- RSpec + Capybara
+- Turnip (optional but supported)
+- Capybara drivers: Selenium and Playwright tested
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/app/controllers/specbook/application_controller.rb

@@ -0,0 +1,4 @@
+module Specbook
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/specbook/viewer_controller.rb

@@ -0,0 +1,179 @@
+module Specbook
+  class ViewerController < ApplicationController
+    before_action :authenticate_user!, if: :devise_present?
+    before_action :require_authorization
+
+    def show
+      @manifest = load_manifest
+      @traces = load_traces
+      @features = load_features
+      @specbook_js_config = build_js_config
+      render "specbook/viewer/show", layout: false
+    end
+
+    def screenshot
+      filename = params[:filename]
+      return head(:bad_request) unless filename.match?(/\Astep_\d{4}_\d{3}\.png\z/)
+
+      path = screenshot_dir.join(filename)
+      return head(:not_found) unless File.exist?(path)
+
+      send_file path, type: "image/png", disposition: "inline"
+    end
+
+    def trace
+      filename = params[:filename]
+      return head(:bad_request) unless filename.match?(/\A[\w\-]+\.zip\z/)
+
+      path = Specbook.config.trace_root.join(filename)
+      return head(:not_found) unless File.exist?(path)
+
+      send_file path, type: "application/zip", disposition: "attachment"
+    end
+
+    def view_trace
+      filename = params[:filename]
+      return head(:bad_request) unless filename.match?(/\A[\w\-]+\.zip\z/)
+
+      path = Specbook.config.trace_root.join(filename)
+      return head(:not_found) unless File.exist?(path)
+
+      port = Specbook.config.trace_viewer_port
+
+      # Kill any existing trace viewer on this port
+      system("lsof -ti:#{port} | xargs kill -9 2>/dev/null")
+      sleep 0.2
+
+      # Launch Playwright trace viewer on fixed port (headless — no browser open)
+      spawn(
+        "npx playwright show-trace --port #{port} --host 127.0.0.1 #{path}",
+        [:out, :err] => "/dev/null"
+      )
+
+      # Wait for server to be ready
+      5.times do
+        sleep 0.3
+        break if port_open?(port)
+      end
+
+      render json: { url: "http://127.0.0.1:#{port}" }
+    end
+
+    private
+
+    def build_js_config
+      rules = (Specbook.config.setup_overlay_rules || []).map do |r|
+        pattern = r[:pattern]
+        if pattern.is_a?(Regexp)
+          { pattern: pattern.source,
+            flags:   regexp_flags_to_string(pattern),
+            icon:    r[:icon],
+            note:    r[:note] }
+        else
+          { pattern: pattern.to_s,
+            flags:   r[:flags] || "",
+            icon:    r[:icon],
+            note:    r[:note] }
+        end
+      end
+
+      {
+        actorColors:       Specbook.config.actor_colors || {},
+        uiDomains:         Specbook.config.ui_domains || [],
+        setupOverlayRules: rules,
+        editorBase:        Specbook.config.editor_base
+      }
+    end
+
+    def regexp_flags_to_string(regexp)
+      opts = regexp.options
+      flags = +""
+      flags << "i" if (opts & Regexp::IGNORECASE) != 0
+      flags << "m" if (opts & Regexp::MULTILINE) != 0
+      flags
+    end
+
+    def devise_present?
+      defined?(Devise) && respond_to?(:authenticate_user!)
+    end
+
+    def require_authorization
+      allowed = if Specbook.config.authorize_with
+                  Specbook.config.authorize_with.call(self)
+                else
+                  Rails.env.development? || Rails.env.test?
+                end
+      redirect_to main_app.root_path unless allowed
+    end
+
+    def screenshot_dir
+      # Use "latest" symlink, fall back to base dir for old-style flat layout
+      base = Specbook.config.screenshot_root
+      latest = base.join("latest")
+      File.exist?(latest) ? Pathname.new(File.realpath(latest)) : base
+    end
+
+    def load_manifest
+      path = screenshot_dir.join("manifest.json")
+      return [] unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    end
+
+    def load_features
+      # Find all .feature files referenced in the manifest
+      feature_files = @manifest.map { |e| e["file"] }.uniq.select { |f| f.end_with?(".feature") }
+      features = {}
+      feature_files.each do |rel_path|
+        path = Specbook.config.feature_root.join(rel_path)
+        next unless File.exist?(path)
+        features[rel_path] = parse_feature(File.read(path))
+      end
+      features
+    end
+
+    def parse_feature(content)
+      result = { name: "", description: [], background: [], scenarios: [] }
+      current = nil # :description, :background, :scenario
+
+      content.each_line do |line|
+        stripped = line.rstrip
+        if stripped =~ /^\s*Feature:\s*(.+)/
+          result[:name] = $1.strip
+          current = :description
+        elsif stripped =~ /^\s*Background:/
+          current = :background
+        elsif stripped =~ /^\s*(@\S+.*)/
+          # Tag line — store for next scenario
+          @pending_tags = $1.strip
+        elsif stripped =~ /^\s*Scenario:\s*(.+)/
+          scenario = { name: $1.strip, steps: [], tags: @pending_tags }
+          @pending_tags = nil
+          result[:scenarios] << scenario
+          current = :scenario
+        elsif current == :description && stripped =~ /^\s+(.+)/
+          result[:description] << $1.strip
+        elsif current == :background && stripped =~ /^\s+(Given|And|When|Then)\s+(.+)/
+          result[:background] << { keyword: $1, text: $2.strip }
+        elsif current == :scenario && stripped =~ /^\s+(Given|And|When|Then)\s+(.+)/
+          result[:scenarios].last[:steps] << { keyword: $1, text: $2.strip }
+        end
+      end
+      @pending_tags = nil
+      result
+    end
+
+    def load_traces
+      path = Specbook.config.trace_root.join("manifest.json")
+      return [] unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    end
+
+    def port_open?(port)
+      Socket.tcp("127.0.0.1", port, connect_timeout: 0.3) { true }
+    rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT
+      false
+    end
+  end
+end