rails-wayback 0.1.0

data/lib/rails_wayback/git.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "open3"
+require "pathname"
+
+module RailsWayback
+  # Thin wrapper around shell git for the host application repository.
+  #
+  # We shell out to git instead of pulling in a dependency to keep the
+  # gem light. All commands are scoped to the host app root and return
+  # plain Ruby data structures.
+  class Git
+    Commit = Struct.new(:sha, :short_sha, :subject, :author, :date, keyword_init: true)
+
+    class GitError < StandardError; end
+
+    def initialize(root: nil)
+      @root = Pathname.new(root || RailsWayback.configuration.app_root_path)
+    end
+
+    def repository?
+      Dir.exist?(@root.join(".git")) || run("rev-parse", "--is-inside-work-tree").strip == "true"
+    rescue GitError
+      false
+    end
+
+    def current_branch
+      run("rev-parse", "--abbrev-ref", "HEAD").strip
+    end
+
+    def current_commit
+      run("rev-parse", "HEAD").strip
+    end
+
+    def branches
+      output = run("for-each-ref", "--format=%(refname:short)", "refs/heads/")
+      output.split("\n").map(&:strip).reject(&:empty?)
+    end
+
+    def commits(branch, limit: RailsWayback.configuration.max_commits)
+      output = run(
+        "log",
+        branch,
+        "--max-count=#{limit.to_i}",
+        "--pretty=format:%H%x1f%h%x1f%s%x1f%an%x1f%ad",
+        "--date=iso-strict"
+      )
+      output.split("\n").reject(&:empty?).map do |line|
+        sha, short, subject, author, date = line.split("\x1f", 5)
+        Commit.new(sha: sha, short_sha: short, subject: subject, author: author, date: date)
+      end
+    end
+
+    def resolve_ref(ref)
+      run("rev-parse", "--verify", "#{ref}^{commit}").strip
+    rescue GitError
+      raise RefNotFoundError, "Unknown git ref: #{ref.inspect}"
+    end
+
+    def show(ref, path)
+      run("show", "#{ref}:#{path}")
+    end
+
+    # Returns the local branch names that contain `sha` in their history.
+    # Used by the bar to reflect the branch you are RENDERING with when
+    # you travel, instead of the branch that is checked out on disk
+    # (which never moves — the gem never touches your working tree).
+    def branches_containing(sha)
+      output = run("branch", "--contains", sha, "--format=%(refname:short)")
+      output.split("\n").map(&:strip).reject(&:empty?)
+    rescue GitError
+      []
+    end
+
+    # Same as `branches_containing`, but picks the most contextual one
+    # for display in the bar when the developer did NOT provide an
+    # explicit branch alongside the sha:
+    # * if the current branch contains the sha, prefer it (keeps you in
+    #   your own context — the sha is on your history line),
+    # * otherwise pick the first non-current local branch that contains
+    #   it (typical case of traveling AWAY from your branch),
+    # * returns nil if no local branch contains the sha (detached ref).
+    def resolve_branch_for(sha)
+      candidates = branches_containing(sha)
+      return nil if candidates.empty?
+
+      here = current_branch
+      return here if candidates.include?(here)
+
+      candidates.first
+    end
+
+    # Returns the list of files that differ between `ref` and the current
+    # working tree (unstaged changes included). Optionally scoped to a set
+    # of pathspecs so we only report files inside the paths the gem
+    # actually swaps for rendering. Never raises: on git failure we log
+    # and return an empty list so a missing/broken ref never breaks the
+    # bar.
+    def diff_paths(ref, paths: [])
+      args = ["diff", "--name-only", ref]
+      args += ["--", *paths] unless paths.empty?
+      output = run(*args)
+      output.split("\n").map(&:strip).reject(&:empty?)
+    rescue GitError => e
+      if defined?(Rails) && Rails.respond_to?(:logger)
+        Rails.logger.warn("[rails-wayback] diff_paths(#{ref.inspect}) failed: #{e.message}")
+      end
+      []
+    end
+
+    def checkout_ref(ref, into:)
+      target = Pathname.new(into)
+      FileUtils.mkdir_p(target)
+      # `git --work-tree` + `checkout` writes the ref's contents into a
+      # detached directory without touching the developer's HEAD or index.
+      env = { "GIT_INDEX_FILE" => target.join(".rails_wayback_index").to_s }
+      run_with_env(env, "--work-tree=#{target}", "read-tree", ref)
+      run_with_env(env, "--work-tree=#{target}", "checkout-index", "--all", "--force")
+      target
+    ensure
+      FileUtils.rm_f(target.join(".rails_wayback_index")) if target
+    end
+
+    def root
+      @root
+    end
+
+    private
+
+    def run(*args)
+      run_with_env({}, *args)
+    end
+
+    def run_with_env(env, *args)
+      stdout, stderr, status = Open3.capture3(env, "git", "-C", @root.to_s, *args)
+      raise GitError, stderr.strip unless status.success?
+      stdout
+    end
+  end
+end

data/lib/rails_wayback/toggle.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RailsWayback
+  # Persists whether the engine should be mounted in the host app.
+  #
+  # The flag is a plain file inside `tmp/rails_wayback/enabled` (ignored by
+  # git). We keep it as a file so the CLI, rake tasks and running Rails
+  # process all agree on the same state without booting extra services.
+  class Toggle
+    def initialize(configuration = RailsWayback.configuration)
+      @configuration = configuration
+    end
+
+    def enabled?
+      configuration.toggle_file_path.exist?
+    end
+
+    def enable!
+      FileUtils.mkdir_p(configuration.toggle_file_path.dirname)
+      FileUtils.touch(configuration.toggle_file_path)
+      touch_routes_reload_marker
+      true
+    end
+
+    def disable!
+      FileUtils.rm_f(configuration.toggle_file_path)
+      touch_routes_reload_marker
+      true
+    end
+
+    def status
+      enabled? ? :on : :off
+    end
+
+    private
+
+    attr_reader :configuration
+
+    # Rails reloads routes in development when config/routes.rb changes.
+    # After toggling we bump its mtime so the next request picks up the
+    # conditional `mount` immediately, without asking the developer to
+    # touch files manually.
+    def touch_routes_reload_marker
+      routes_file = configuration.app_root_path.join("config", "routes.rb")
+      FileUtils.touch(routes_file) if routes_file.file?
+    rescue StandardError
+      # Best-effort: never fail toggling because of a filesystem hiccup.
+      nil
+    end
+  end
+end

data/lib/rails_wayback/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsWayback
+  VERSION = "0.1.0"
+end

data/lib/rails_wayback/view_source.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "pathname"
+
+module RailsWayback
+  # Materialises the view/asset directories of a given git ref into a
+  # sandbox under tmp/, so a controller can prepend that sandbox as a
+  # view path and render the historical templates.
+  #
+  # Only the directories listed in `configuration.view_paths` and
+  # `configuration.asset_paths` are pulled from the ref. Nothing is
+  # executed, and the developer's real files are never mutated.
+  class ViewSource
+    # Bumped whenever the materialization format changes so stale
+    # sandboxes from earlier gem versions get rebuilt instead of
+    # being reused.
+    MATERIALIZATION_VERSION = "2"
+
+    attr_reader :configuration, :git
+
+    def initialize(configuration: RailsWayback.configuration, git: RailsWayback::Git.new)
+      @configuration = configuration
+      @git = git
+    end
+
+    def materialize(ref)
+      sha = git.resolve_ref(ref)
+      target = configuration.refs_cache_path.join(sha)
+      return target if fresh?(target, sha)
+
+      FileUtils.rm_rf(target)
+      FileUtils.mkdir_p(target)
+      tracked_paths.each { |path| extract_path(sha, path, target) }
+      write_marker(target, sha)
+      target
+    end
+
+    def view_root_for(ref)
+      target = materialize(ref)
+      configuration.view_paths.map { |p| target.join(p) }.select(&:directory?)
+    end
+
+    def cleanup!
+      FileUtils.rm_rf(configuration.refs_cache_path)
+    end
+
+    private
+
+    def tracked_paths
+      (configuration.view_paths + configuration.asset_paths).uniq
+    end
+
+    def marker_path(target)
+      target.join(".rails_wayback.sha")
+    end
+
+    def fresh?(target, sha)
+      marker = marker_path(target)
+      return false unless marker.file?
+
+      contents = marker.read.strip
+      expected = "#{MATERIALIZATION_VERSION}:#{sha}"
+      contents == expected
+    end
+
+    def write_marker(target, sha)
+      marker_path(target).write("#{MATERIALIZATION_VERSION}:#{sha}")
+    end
+
+    # Uses `git archive | tar -x` to extract a subtree at a given ref.
+    # This avoids the pitfalls of hand-rolled ls-tree + show pipelines
+    # (encoding, binary files, missing directories, permissions) and
+    # works with any subdirectory a git version supports.
+    def extract_path(sha, path, target)
+      spec = "#{sha}:#{path}"
+      return unless tree_exists?(sha, path)
+
+      dest = target.join(path)
+      FileUtils.mkdir_p(dest)
+
+      archive_cmd = ["git", "-C", git.root.to_s, "archive", "--format=tar", spec]
+      tar_cmd     = ["tar", "-xf", "-", "-C", dest.to_s]
+
+      Open3.pipeline(archive_cmd, tar_cmd)
+    end
+
+    def tree_exists?(sha, path)
+      # `git cat-file -t <sha>:<path>` prints "tree" for directories and
+      # "blob" for files. Anything else (or a non-zero exit) means the
+      # path is not present at that ref, in which case we skip it.
+      out, _err, status = Open3.capture3(
+        "git", "-C", git.root.to_s, "cat-file", "-t", "#{sha}:#{path}"
+      )
+      status.success? && out.strip == "tree"
+    end
+  end
+end

data/lib/rails_wayback.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rails_wayback/version"
+require "rails_wayback/configuration"
+require "rails_wayback/toggle"
+require "rails_wayback/git"
+require "rails_wayback/view_source"
+
+module RailsWayback
+  class Error < StandardError; end
+  class DisabledError < Error; end
+  class RefNotFoundError < Error; end
+  class RenderError < Error; end
+
+  # Thread-local key where the render subscriber accumulates the
+  # `identifier` of every template resolved during a single request.
+  # The middleware resets this at the start of each request and reads
+  # it back to report per-page diff coverage in the bar.
+  RENDER_TRACKER_KEY = :rails_wayback_rendered_templates
+
+  class << self
+    def configure
+      yield configuration if block_given?
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      @toggle = nil
+    end
+
+    def toggle
+      @toggle ||= Toggle.new(configuration)
+    end
+
+    def enabled?
+      toggle.enabled?
+    end
+
+    def enable!
+      toggle.enable!
+    end
+
+    def disable!
+      toggle.disable!
+    end
+
+    def root
+      return Rails.root if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+      Pathname.new(Dir.pwd)
+    end
+  end
+end
+
+require "rails_wayback/engine" if defined?(Rails::Engine)

data/lib/tasks/rails_wayback.rake

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails_wayback/cli"
+
+namespace :wayback do
+  desc "Enable the rails-wayback UI"
+  task on: :environment do
+    RailsWayback::CLI.start(["on"])
+  end
+
+  desc "Disable the rails-wayback UI"
+  task off: :environment do
+    RailsWayback::CLI.start(["off"])
+  end
+
+  desc "Print the current rails-wayback state"
+  task status: :environment do
+    RailsWayback::CLI.start(["status"])
+  end
+
+  desc "Remove the rails-wayback ref cache under tmp/"
+  task clean: :environment do
+    RailsWayback::CLI.start(["clean"])
+  end
+end

data/rails-wayback.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "lib/rails_wayback/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rails-wayback"
+  spec.version = RailsWayback::VERSION
+  spec.authors = ["MrCesar107"]
+  spec.email = ["cesar.rodriguez.lara54@gmail.com"]
+
+  spec.summary = "Preview and compare Rails UI across git branches and commits."
+  spec.description = <<~DESC
+    rails-wayback is a Rails engine that lets you travel through git history to
+    render past versions of your application's views inside the browser. It runs
+    inside the same Rails process the developer is already using and can be
+    toggled on/off from the terminal so it never gets in the way of normal
+    development.
+  DESC
+  spec.homepage = "https://github.com/MrCesar107/rails-wayback"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir[
+    "{app,config,lib,exe}/**/*",
+    "MIT-LICENSE",
+    "Rakefile",
+    "README.md",
+    "rails-wayback.gemspec"
+  ].reject { |f| File.directory?(f) }
+
+  spec.bindir = "exe"
+  spec.executables = ["rails-wayback"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", ">= 7.0"
+
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: rails-wayback
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- MrCesar107
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  rails-wayback is a Rails engine that lets you travel through git history to
+  render past versions of your application's views inside the browser. It runs
+  inside the same Rails process the developer is already using and can be
+  toggled on/off from the terminal so it never gets in the way of normal
+  development.
+email:
+- cesar.rodriguez.lara54@gmail.com
+executables:
+- rails-wayback
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/rails_wayback/application_controller.rb
+- app/controllers/rails_wayback/pages_controller.rb
+- config/routes.rb
+- exe/rails-wayback
+- lib/generators/rails_wayback/install/USAGE
+- lib/generators/rails_wayback/install/install_generator.rb
+- lib/generators/rails_wayback/install/templates/initializer.rb.tt
+- lib/rails-wayback.rb
+- lib/rails_wayback.rb
+- lib/rails_wayback/bar_middleware.rb
+- lib/rails_wayback/bar_renderer.rb
+- lib/rails_wayback/cli.rb
+- lib/rails_wayback/configuration.rb
+- lib/rails_wayback/controller_extensions.rb
+- lib/rails_wayback/engine.rb
+- lib/rails_wayback/git.rb
+- lib/rails_wayback/toggle.rb
+- lib/rails_wayback/version.rb
+- lib/rails_wayback/view_source.rb
+- lib/tasks/rails_wayback.rake
+- rails-wayback.gemspec
+homepage: https://github.com/MrCesar107/rails-wayback
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/MrCesar107/rails-wayback
+  bug_tracker_uri: https://github.com/MrCesar107/rails-wayback/issues
+  changelog_uri: https://github.com/MrCesar107/rails-wayback/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Preview and compare Rails UI across git branches and commits.
+test_files: []