rails-wayback 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 837e9fe96c57c95c97120d9763ce5f479f96de05ef809efd9ff28489a4747e33
+  data.tar.gz: 1123f82ce9d8e4a16b71fa318c881ca2fc0ec3a8ca50556a4bc3da720e1cab67
+SHA512:
+  metadata.gz: 289a30da1575e6f95f57c15ea74172d2ae7b10a97a396d18ea449008300f2345583a39ae853e0bd1e3d28281de72465e10ec9e5d2b656974c697c547a467ac40
+  data.tar.gz: 67f4833b49c5c36381f672b8b48ec2368db8ef66bc04a10e5f70feb11fbf9c4c2beba98a0a311a46506fce8f942f037e90940b2002d381653842dbf24383e4c5

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MrCesar107
+
+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,172 @@
+# rails-wayback
+
+Preview and compare Rails UI across git branches and commits, directly in the
+browser, from inside the developer's own Rails process. Toggle it on and off
+from the terminal so it never gets in the way of normal development.
+
+## Idea
+
+When enabled, `rails-wayback` overlays a small bar at the bottom of every HTML
+page of your app:
+
+- Pick a branch and a commit.
+- Hit **Travel**.
+- The current URL reloads with `?_wayback_ref=<sha>`, and the app renders
+  that exact page using the **views/layouts/partials of the chosen ref**,
+  while keeping the current controller's data and models.
+
+Design goals:
+
+- **Zero configuration.** Drop the gem in, run the installer, turn it on.
+- **One process only.** Uses the running dev app — no extra Rails server.
+- **HTML render, not screenshots.**
+- **Toggleable from the CLI.** Stays inert when you don't need it.
+
+## Install
+
+Add the gem to the host app's `Gemfile`, in the development group:
+
+```ruby
+group :development do
+  gem "rails-wayback"
+end
+```
+
+Then run the installer:
+
+```bash
+bin/rails generate rails_wayback:install
+```
+
+That adds a conditional mount to `config/routes.rb`, an initializer at
+`config/initializers/rails_wayback.rb` (optional overrides), and a
+`.gitignore` entry for `tmp/rails_wayback/`.
+
+## Usage
+
+Turn the UI on when you need it, off when you don't:
+
+```bash
+bundle exec rails-wayback on      # enable and inject the bar in every page
+bundle exec rails-wayback off     # disable it
+bundle exec rails-wayback status  # print current state
+bundle exec rails-wayback clean   # drop the tmp/rails_wayback ref cache
+```
+
+Same commands as rake tasks: `rake wayback:on`, `wayback:off`,
+`wayback:status`, `wayback:clean`.
+
+With the gem enabled, load any page of your app. A dark bar appears at the
+bottom with:
+
+- `Current branch` — dropdown of your local branches.
+- `Current commit` — dropdown of the recent commits on that branch.
+- `Travel` — reloads the current URL using views from that commit.
+- `Return to HEAD` — appears while traveling; goes back to live views.
+
+There is no dedicated `/rails-wayback` page. The gem stays quiet on assets,
+ActionCable, and every URL under `/rails-wayback/*.json` (used by the bar to
+fetch git data).
+
+## How "travel" actually works
+
+`rails-wayback` never runs a second Rails server. Travel is just:
+
+1. The bar appends `?_wayback_ref=<sha>` to the current URL and reloads.
+2. A `before_action`, auto-included in every `ActionController::Base`
+   subclass, sees `_wayback_ref` and materialises that ref under
+   `tmp/rails_wayback/refs/<sha>/` (cached per commit).
+3. The same before_action calls `prepend_view_path` with the sandbox, so
+   Action View resolves templates from the ref before falling back to the
+   current tree.
+4. Your controller runs as usual, sets its `@` variables, and renders. The
+   visual layer (layouts, partials, ERB) comes from the past; the data and
+   business logic come from the present.
+
+If a historical template references a helper or assign that no longer
+exists, you'll get the same `ActionView` error you'd get from any missing
+piece — the app itself never changes.
+
+## Configuration (optional)
+
+`config/initializers/rails_wayback.rb`:
+
+```ruby
+RailsWayback.configure do |config|
+  # config.view_paths  = %w[app/views]
+  # config.asset_paths = %w[app/assets public]
+  # config.max_commits = 50
+end
+```
+
+Everything above has a sensible default. Delete the initializer if you
+don't need to change anything.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Release
+
+Releases are cut by pushing an annotated `vX.Y.Z` git tag. GitHub Actions runs
+the specs and pushes the gem to RubyGems using
+[Trusted Publishing (OIDC)](https://guides.rubygems.org/trusted-publishing/),
+so there are no API tokens stored on GitHub and MFA on the RubyGems account is
+never in the way.
+
+### One-time setup
+
+1. On GitHub, go to **Settings → Environments → New environment** and create
+   an environment named exactly `release`. (Optionally add branch protection
+   so only `main` and tags can deploy to it.)
+2. On [rubygems.org](https://rubygems.org):
+   - For the very first release, go to **Profile → Trusted publishers →
+     Pending trusted publishers → Create** and fill in:
+     - RubyGem name: `rails-wayback`
+     - Repository owner: `MrCesar107`
+     - Repository name: `rails-wayback`
+     - Workflow filename: `release.yml`
+     - Environment: `release`
+   - For every release after 0.1.0, the pending publisher is promoted to a
+     normal trusted publisher automatically — nothing to configure again.
+3. Make sure MFA is enabled on your RubyGems account (the gemspec sets
+   `rubygems_mfa_required = true`).
+
+### Cutting a release
+
+1. Update `lib/rails_wayback/version.rb` following
+   [SemVer](https://semver.org/spec/v2.0.0.html).
+2. Move the pending entries in `CHANGELOG.md` from `[Unreleased]` into a new
+   `[X.Y.Z] - YYYY-MM-DD` section and update the compare/tag links at the
+   bottom of the file.
+3. Commit both files:
+   ```bash
+   git commit -am "Release vX.Y.Z"
+   ```
+4. Tag and push:
+   ```bash
+   git tag -a vX.Y.Z -m "Release vX.Y.Z"
+   git push origin main --follow-tags
+   ```
+5. Watch the `Release` workflow on GitHub. It refuses to publish if the tag
+   doesn't match `RailsWayback::VERSION`, so a typo in the tag will fail
+   loudly before touching RubyGems.
+
+### Manual fallback
+
+If the workflow is broken and you need to publish from your laptop:
+
+```bash
+gem build rails-wayback.gemspec
+gem push rails-wayback-X.Y.Z.gem
+```
+
+`gem push` will ask for your RubyGems credentials and MFA code the first
+time.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+  # RSpec is only available in development
+end

data/app/controllers/rails_wayback/application_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  class ApplicationController < ::ActionController::API
+    before_action :ensure_enabled!
+
+    private
+
+    def ensure_enabled!
+      return if RailsWayback.enabled?
+
+      render json: { error: "rails-wayback is disabled" }, status: :service_unavailable
+    end
+
+    def git
+      @git ||= RailsWayback::Git.new
+    end
+  end
+end

data/app/controllers/rails_wayback/pages_controller.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  # JSON endpoints consumed by the bar's JavaScript to populate the
+  # branch and commit selectors. All rendering of the actual UI lives
+  # in the middleware; this controller only exposes git metadata.
+  class PagesController < ApplicationController
+    def branches
+      current_branch = safe_call { git.current_branch }
+      current_commit = safe_call { git.current_commit }
+      branches = safe_call { git.branches }
+
+      render json: {
+        current_branch: current_branch.value,
+        current_commit: current_commit.value,
+        branches: branches.value || [],
+        errors: [branches.error].compact
+      }
+    end
+
+    def commits
+      branch = params[:branch].to_s.sub(/\.json\z/, "")
+      result = safe_call { git.commits(branch) }
+
+      list = (result.value || []).map do |commit|
+        {
+          sha: commit.sha,
+          short_sha: commit.short_sha,
+          subject: commit.subject,
+          author: commit.author,
+          date: commit.date
+        }
+      end
+
+      render json: {
+        branch: branch,
+        commits: list,
+        error: result.error
+      }
+    end
+
+    private
+
+    Result = Struct.new(:value, :error)
+
+    def safe_call
+      Result.new(yield, nil)
+    rescue RailsWayback::Git::GitError => e
+      Rails.logger.warn("[rails-wayback] #{e.class}: #{e.message}") if defined?(Rails)
+      Result.new(nil, "#{e.class}: #{e.message}")
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+RailsWayback::Engine.routes.draw do
+  # `format: false` keeps Rails from parsing a trailing `.json` as an
+  # implicit format, and the glob `*branch` allows branch names that
+  # contain slashes (e.g. "feature/foo"). The controller trims a
+  # trailing `.json` defensively in case a client still appends it.
+  get "branches", to: "pages#branches", format: false, as: :branches
+  get "commits/*branch", to: "pages#commits", format: false, as: :commits
+end

data/exe/rails-wayback

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "rails_wayback/cli"
+
+exit(RailsWayback::CLI.start(ARGV) || 0)

data/lib/generators/rails_wayback/install/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Installs rails-wayback in the current Rails application.
+
+    Adds a conditional mount to config/routes.rb and drops an initializer
+    at config/initializers/rails_wayback.rb.
+
+Example:
+    rails generate rails_wayback:install

data/lib/generators/rails_wayback/install/install_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RailsWayback
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "initializer.rb.tt", "config/initializers/rails_wayback.rb"
+      end
+
+      def mount_engine
+        route_snippet = <<~ROUTE
+          mount RailsWayback::Engine => "/rails-wayback" if defined?(RailsWayback) && RailsWayback.enabled?
+        ROUTE
+
+        routes_file = "config/routes.rb"
+
+        if File.file?(routes_file) && File.read(routes_file).include?("RailsWayback::Engine")
+          say_status :skip, "RailsWayback::Engine mount already present in #{routes_file}"
+        else
+          route route_snippet.strip
+        end
+      end
+
+      def update_gitignore
+        gitignore = ".gitignore"
+        entry = "/tmp/rails_wayback/\n"
+        if File.file?(gitignore) && !File.read(gitignore).include?("tmp/rails_wayback")
+          append_to_file(gitignore, entry)
+        elsif !File.file?(gitignore)
+          create_file(gitignore, entry)
+        end
+      end
+    end
+  end
+end

data/lib/generators/rails_wayback/install/templates/initializer.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Optional configuration for the rails-wayback engine.
+#
+# The engine is only mounted when it is toggled on from the terminal
+# (see `bundle exec rails-wayback on|off|status`). When it is on, a
+# floating bar is injected at the bottom of every HTML page of your app
+# so you can pick a branch/commit and travel to that ref's views for
+# the current URL. Delete this file if the defaults below work for you.
+RailsWayback.configure do |config|
+  # Directories (relative to Rails.root) whose contents are pulled from
+  # the target git ref and used to render the historical preview.
+  # config.view_paths  = %w[app/views]
+  # config.asset_paths = %w[app/assets public]
+
+  # How many recent commits per branch are shown in the bar dropdown.
+  # config.max_commits = 50
+end

data/lib/rails-wayback.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "rails_wayback"

data/lib/rails_wayback/bar_middleware.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "rails_wayback/bar_renderer"
+
+module RailsWayback
+  # Rack middleware that appends the wayback bar to every successful
+  # HTML response of the host application while the gem is enabled.
+  # Skips assets, ActionCable, non-2xx responses and non-HTML bodies so
+  # it never touches anything but the developer-facing pages.
+  class BarMiddleware
+    SKIP_PATH_PREFIXES = %w[
+      /assets
+      /packs
+      /rails/
+      /cable
+      /rails-wayback
+    ].freeze
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      # Always reset the per-request render tracker before invoking the
+      # app so the middleware can accurately report which templates the
+      # current page rendered. Cheap and thread-safe (Thread.current).
+      Thread.current[RailsWayback::RENDER_TRACKER_KEY] = []
+
+      status, headers, body = @app.call(env)
+      return [status, headers, body] unless inject?(env, status, headers)
+
+      html = read_body(body)
+      snippet = build_snippet(env)
+      new_html = inject(html, snippet)
+
+      new_headers = headers.dup
+      length_key = new_headers.key?("Content-Length") ? "Content-Length" : (new_headers.key?("content-length") ? "content-length" : nil)
+      new_headers[length_key] = new_html.bytesize.to_s if length_key
+
+      [status, new_headers, [new_html]]
+    end
+
+    private
+
+    def inject?(env, status, headers)
+      return false unless RailsWayback.enabled?
+      return false unless status.to_i.between?(200, 299) || status.to_i.between?(400, 499)
+
+      path = env["PATH_INFO"].to_s
+      return false if SKIP_PATH_PREFIXES.any? { |prefix| path.start_with?(prefix) }
+
+      content_type = headers["Content-Type"] || headers["content-type"] || ""
+      return false unless content_type.include?("text/html")
+
+      true
+    end
+
+    def read_body(body)
+      buffer = +""
+      body.each { |chunk| buffer << chunk.to_s }
+      buffer
+    ensure
+      body.close if body.respond_to?(:close)
+    end
+
+    def inject(html, snippet)
+      if html.include?("</body>")
+        html.sub("</body>", "#{snippet}</body>")
+      else
+        html + snippet
+      end
+    end
+
+    def build_snippet(env)
+      git = RailsWayback::Git.new
+      active_ref = extract_active_ref(env)
+      active_branch = active_ref ? active_branch_for(env, git, active_ref) : nil
+
+      renderer = BarRenderer.new(
+        current_branch: safe(:current_branch, git),
+        current_commit: safe(:current_commit, git),
+        active_ref: active_ref,
+        active_branch: active_branch,
+        engine_mount: engine_mount,
+        diff_info: active_ref ? build_diff_info(git, active_ref) : nil
+      )
+      renderer.render
+    rescue StandardError => e
+      Rails.logger.warn("[rails-wayback] failed to render bar: #{e.class}: #{e.message}") if defined?(Rails)
+      ""
+    end
+
+    def safe(method, git)
+      git.public_send(method)
+    rescue StandardError
+      ""
+    end
+
+    # Determines the branch label to show in the bar while traveling.
+    # Prefers the branch the user explicitly picked in the bar (passed
+    # via the `_wayback_branch` query param, so it survives the reload).
+    # Falls back to inferring it from git — useful when a developer opens
+    # a shared URL that only carries `_wayback_ref`.
+    def active_branch_for(env, git, ref)
+      explicit = extract_active_branch(env)
+      return explicit if explicit && !explicit.empty?
+
+      git.resolve_branch_for(ref)
+    rescue StandardError
+      nil
+    end
+
+    # Builds the diff summary shown in the bar when a ref is active.
+    # `changed_files`: view/asset paths that differ between the ref and
+    # the current working tree, always scoped to the paths the gem
+    # actually swaps. `rendered_from_ref`: relative paths (under
+    # app/views, app/components, ...) that the current request rendered
+    # from the sandbox. `matched`: intersection — the templates on this
+    # page that actually reflect a real diff between branches.
+    def build_diff_info(git, ref)
+      config = RailsWayback.configuration
+      tracked_paths = (config.view_paths + config.asset_paths).uniq
+      changed_files = git.diff_paths(ref, paths: tracked_paths)
+
+      rendered_from_ref = rendered_relative_paths(config)
+      matched = changed_files & rendered_from_ref
+
+      {
+        changed_files: changed_files,
+        rendered_from_ref: rendered_from_ref,
+        matched: matched
+      }
+    rescue StandardError => e
+      Rails.logger.warn("[rails-wayback] failed to build diff info: #{e.class}: #{e.message}") if defined?(Rails)
+      nil
+    end
+
+    def rendered_relative_paths(config)
+      tracker = Array(Thread.current[RailsWayback::RENDER_TRACKER_KEY])
+      return [] if tracker.empty?
+
+      sandbox_prefix = config.refs_cache_path.to_s
+      # Sandbox identifiers look like:
+      #   /.../tmp/rails_wayback/refs/<sha>/app/views/foo/_bar.html.haml
+      # Strip up to and including the sha directory to get back
+      # `app/views/foo/_bar.html.haml`, which matches `git diff --name-only`.
+      strip_re = %r{\A#{Regexp.escape(sandbox_prefix)}/[^/]+/}
+
+      tracker.filter_map do |identifier|
+        next unless identifier.start_with?(sandbox_prefix)
+        identifier.sub(strip_re, "")
+      end.uniq
+    end
+
+    # Query params take priority (one-off overrides / shared links);
+    # cookies keep the travel state alive as the developer navigates
+    # around the app without repeating the params in every URL.
+    def extract_active_ref(env)
+      extract_query_param(env, "_wayback_ref") ||
+        extract_cookie(env, "rails_wayback_ref")
+    end
+
+    def extract_active_branch(env)
+      extract_query_param(env, "_wayback_branch") ||
+        extract_cookie(env, "rails_wayback_branch")
+    end
+
+    def extract_query_param(env, name)
+      query = env["QUERY_STRING"].to_s
+      return nil if query.empty?
+      prefix = "#{name}="
+      match = query.split("&").find { |pair| pair.start_with?(prefix) }
+      return nil unless match
+
+      value = CGI.unescape(match.split("=", 2).last.to_s)
+      value.empty? ? nil : value
+    end
+
+    def extract_cookie(env, name)
+      header = env["HTTP_COOKIE"].to_s
+      return nil if header.empty?
+      prefix = "#{name}="
+      match = header.split(/;\s*/).find { |pair| pair.start_with?(prefix) }
+      return nil unless match
+
+      value = CGI.unescape(match.split("=", 2).last.to_s)
+      value.empty? ? nil : value
+    end
+
+    def engine_mount
+      RailsWayback::Engine.routes.default_url_options[:script_name] ||
+        RailsWayback::Engine.routes.find_script_name({}) ||
+        "/rails-wayback"
+    rescue StandardError
+      "/rails-wayback"
+    end
+  end
+end