mirrorfile 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b29787fe3ec7d699137a8bc8f02dbfafd0ac95693dece15bf7199c977d3aa0e
+  data.tar.gz: df9541b78b01255029986e18f3144294f4e60b436b8d928c7e8ff8937177cadc
+SHA512:
+  metadata.gz: b3fd0d4747c159d0cf957012a7ba997b0dfc062278ef5d3b0b0bd823e23e96df11d78ebd863a1dbfe91beabac0a8e1a207e84cdbca662c0d2fa70a2ef5706172
+  data.tar.gz: b0fea1083d5ec020119d35d775d19545662223110306e0ac6ce87598c80bc190a952dcb4113ed7f056845b0074651097b17add026c7743f90cbdc23ac1b1895c

data/.yardopts

@@ -0,0 +1,7 @@
+--markup markdown
+--markup-provider redcarpet
+--charset utf-8
+--output-dir doc
+--readme README.md
+--title "GitMirror Documentation"
+lib/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-01-01
+
+### Added
+
+- Initial release
+- `mirror init` command to initialize projects
+- `mirror install` command to clone repositories
+- `mirror update` command to pull latest changes
+- `mirror list` command to show defined mirrors
+- Mirrorfile DSL with `source` and `mirror` methods
+- Rails/Zeitwerk integration for autoloading mirrored code
+- Automatic `.gitignore` management

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Your Name
+
+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,77 @@
+# Mirrorfile
+
+Clone git repositories into a local `mirrors/` folder and keep them updated. Uses a `Mirrorfile` with Bundler-like syntax.
+
+## Why use this
+
+- You want to vendor gems or libraries without git submodules
+- You need local copies of repos for reference or offline work
+- You want Zeitwerk to autoload code from external repos in Rails
+
+## Why not use this
+
+- Git submodules already work fine for you
+- You need pinned versions or tags (this just pulls `HEAD`)
+- You want proper dependency management (use Bundler)
+
+
+## Install
+```ruby
+gem install mirrorfile
+```
+
+## Usage
+```bash
+mirror init      # creates Mirrorfile, .gitignore entry, zeitwerk initializer
+mirror install   # clones missing repos
+mirror update    # pulls existing repos
+mirror list      # shows defined mirrors
+```
+
+## Example Mirrorfile
+
+You can change sources mid-file:
+
+```ruby
+# frozen_string_literal: true
+
+# Rails ecosystem
+source "https://github.com"
+
+mirror "rails/rails", as: "rails-source"
+mirror "hotwired/turbo-rails"
+mirror "hotwired/stimulus-rails"
+
+# Internal gems
+source "https://git.company.com"
+
+mirror "platform/shared-models", as: "shared-models"
+mirror "platform/api-client"
+
+# One-off from different host
+mirror "https://gitlab.com/someorg/special-gem"
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## Development
+
+After checking out the repo:
+
+```bash
+bin/setup
+bundle exec rake test
+```
+
+Generate documentation:
+
+```bash
+bundle exec yard doc
+bundle exec yard server  # Browse at http://localhost:8808
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "yard"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
+  t.options = ["--markup", "markdown"]
+end
+
+task default: :test

data/exe/mirror

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/mirrorfile"
+
+exit Mirrorfile::CLI.new.call(ARGV)

data/lib/mirrorfile/cli.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Mirrorfile
+  # Command-line interface for Mirrorfile.
+  #
+  # CLI parses command-line arguments and dispatches to the appropriate
+  # {Mirror} methods. It provides a simple, git-like interface for
+  # managing mirrored repositories.
+  #
+  # @example Running from command line
+  #   $ mirror init      # Initialize project
+  #   $ mirror install   # Clone repositories
+  #   $ mirror update    # Pull latest changes
+  #   $ mirror list      # Show all mirrors
+  #
+  # @example Programmatic usage
+  #   cli = Mirrorfile::CLI.new
+  #   cli.call(["install"])
+  #
+  # @since 0.1.0
+  class CLI
+    # Available CLI commands
+    # @return [Array<String>] list of valid commands
+    COMMANDS = %w[init install update list help].freeze
+
+    # Creates a new CLI instance.
+    #
+    # @param stdout [IO] output stream for normal messages (default: $stdout)
+    # @param stderr [IO] output stream for error messages (default: $stderr)
+    # @return [CLI] a new CLI instance
+    def initialize(stdout: $stdout, stderr: $stderr)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    # Parses arguments and executes the appropriate command.
+    #
+    # @param args [Array<String>] command-line arguments (typically ARGV)
+    # @return [Integer] exit status code (0 for success, 1 for error)
+    #
+    # @example
+    #   cli = Mirrorfile::CLI.new
+    #   exit_code = cli.call(["install"])
+    #
+    # @example With error handling
+    #   cli = Mirrorfile::CLI.new
+    #   exit cli.call(ARGV)
+    def call(args)
+      command = args.first
+
+      case command
+      when "init"    then init
+      when "install" then install
+      when "update"  then update
+      when "list"    then list
+      when "help"    then help
+      when "-h", "--help" then help
+      when "-v", "--version" then version
+      else                usage
+      end
+
+      0
+    rescue MirrorfileNotFound => e
+      @stderr.puts "Error: #{e.message}"
+      1
+    rescue StandardError => e
+      @stderr.puts "Error: #{e.message}"
+      @stderr.puts e.backtrace.first(5).map { "  #{_1}" } if ENV["DEBUG"]
+      1
+    end
+
+    private
+
+    # Executes the init command.
+    #
+    # @return [void]
+    # @api private
+    def init
+      Mirror.new.init
+    end
+
+    # Executes the install command.
+    #
+    # @return [void]
+    # @api private
+    def install
+      @stdout.puts "Installing mirrors..."
+      Mirror.new.install
+      @stdout.puts "Done."
+    end
+
+    # Executes the update command.
+    #
+    # @return [void]
+    # @api private
+    def update
+      @stdout.puts "Updating mirrors..."
+      Mirror.new.update
+      @stdout.puts "Done."
+    end
+
+    # Executes the list command.
+    #
+    # @return [void]
+    # @api private
+    def list
+      entries = Mirror.new.list
+
+      entries.empty? ? @stdout.puts("No mirrors defined.") : entries.each { @stdout.puts _1 }
+    end
+
+    # Displays help information.
+    #
+    # @return [void]
+    # @api private
+    def help
+      @stdout.puts <<~HELP
+        Mirrorfile - Manage local mirrors of git repositories
+
+        Usage: mirror <command>
+
+        Commands:
+          init      Initialize project with Mirrorfile, .gitignore entry,
+                    and Zeitwerk initializer for Rails projects
+          install   Clone repositories that don't exist locally
+          update    Pull latest changes for existing repositories
+          list      Show all defined mirrors
+          help      Show this help message
+
+        Options:
+          -h, --help     Show this help message
+          -v, --version  Show version number
+
+        Examples:
+          $ mirror init
+          $ mirror install
+          $ mirror update
+
+        Mirrorfile syntax:
+          source "https://github.com"
+
+          mirror "rails/rails", as: "rails-source"
+          mirror "hotwired/turbo-rails"
+
+          source "https://gitlab.com"
+
+          mirror "org/project"
+
+        For more information, see: https://github.com/n-at-han-k/mirrorfile
+      HELP
+    end
+
+    # Displays version information.
+    #
+    # @return [void]
+    # @api private
+    def version
+      @stdout.puts "mirrorfile #{Mirrorfile::VERSION}"
+    end
+
+    # Displays usage information for unknown commands.
+    #
+    # @return [void]
+    # @api private
+    def usage
+      @stderr.puts <<~USAGE
+        Usage: mirror <command>
+
+        Commands:
+          init      Create Mirrorfile, .gitignore entry, and Zeitwerk initializer
+          install   Clone repositories that don't exist locally
+          update    Pull latest changes for existing repositories
+          list      Show all defined mirrors
+          help      Show detailed help
+
+        Run 'mirror help' for more information.
+      USAGE
+    end
+  end
+end

data/lib/mirrorfile/entry.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Mirrorfile
+  # Represents a single repository entry to be mirrored.
+  #
+  # Entry is an immutable data object that holds the URL and local name
+  # for a mirrored repository. It provides methods for cloning and updating
+  # the repository.
+  #
+  # @example Creating an entry
+  #   entry = Mirrorfile::Entry.new(
+  #     url: "https://github.com/rails/rails",
+  #     name: "rails-source"
+  #   )
+  #   entry.install(Pathname.new("mirrors"))
+  #
+  # @!attribute [r] url
+  #   @return [String] the full git URL of the repository
+  #
+  # @!attribute [r] name
+  #   @return [String] the local directory name for the clone
+  #
+  # @since 0.1.0
+  Entry = Data.define(:url, :name) do
+    # Returns the local path where this repository will be cloned.
+    #
+    # @param base_dir [Pathname] the base directory containing all mirrors
+    # @return [Pathname] the full path to this repository's local directory
+    #
+    # @example
+    #   entry = Entry.new(url: "https://github.com/rails/rails", name: "rails")
+    #   entry.local_path(Pathname.new("/project/mirrors"))
+    #   #=> #<Pathname:/project/mirrors/rails>
+    def local_path(base_dir)
+      base_dir.join(name)
+    end
+
+    # Clones the repository if it doesn't already exist locally.
+    #
+    # This method is idempotent - calling it multiple times will only
+    # clone the repository once. If the local directory already exists,
+    # no action is taken.
+    #
+    # @param base_dir [Pathname] the base directory to clone into
+    # @return [Boolean, nil] true if clone succeeded, false if failed,
+    #   nil if already exists
+    #
+    # @example
+    #   entry.install(Pathname.new("mirrors"))
+    #
+    # @see #update
+    def install(base_dir)
+      dir = local_path(base_dir)
+      system("git", "clone", url, dir.to_s) unless dir.exist?
+    end
+
+    # Updates an existing repository by pulling the latest changes.
+    #
+    # Uses fast-forward only merges to avoid creating merge commits.
+    # If the local directory doesn't exist, no action is taken.
+    #
+    # @param base_dir [Pathname] the base directory containing the clone
+    # @return [Boolean, nil] true if pull succeeded, false if failed,
+    #   nil if directory doesn't exist
+    #
+    # @example
+    #   entry.update(Pathname.new("mirrors"))
+    #
+    # @see #install
+    def update(base_dir)
+      dir = local_path(base_dir)
+      system("git", "-C", dir.to_s, "pull", "--ff-only") if dir.exist?
+    end
+
+    # Returns a human-readable representation of the entry.
+    #
+    # @return [String] formatted string showing url and name
+    def to_s
+      "#{name} (#{url})"
+    end
+  end
+end

data/lib/mirrorfile/mirror.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Mirrorfile
+  # Orchestrates mirror operations: init, install, and update.
+  #
+  # Mirror is the main interface for performing operations on mirrored
+  # repositories. It handles loading the Mirrorfile, creating necessary
+  # directories and files, and delegating to individual entries.
+  #
+  # @example Initializing a new project
+  #   mirror = Mirrorfile::Mirror.new
+  #   mirror.init
+  #
+  # @example Installing and updating mirrors
+  #   mirror = Mirrorfile::Mirror.new
+  #   mirror.install  # Clone missing repositories
+  #   mirror.update   # Pull latest changes
+  #
+  # @since 0.1.0
+  class Mirror
+    # @return [Pathname] the project root directory
+    attr_reader :root
+
+    # @return [Pathname] the mirrors directory path
+    attr_reader :mirrors_dir
+
+    # @return [Pathname] the .gitignore file path
+    attr_reader :gitignore_path
+
+    # @return [Pathname] the Mirrorfile path
+    attr_reader :mirrorfile_path
+
+    # @return [Pathname] the Rails initializer path
+    attr_reader :initializer_path
+
+    # Creates a new Mirror instance.
+    #
+    # @param root [Pathname, String] the project root directory
+    #   (defaults to current working directory)
+    # @return [Mirror] a new Mirror instance
+    #
+    # @example With default root
+    #   mirror = Mirrorfile::Mirror.new
+    #
+    # @example With custom root
+    #   mirror = Mirrorfile::Mirror.new(root: "/path/to/project")
+    def initialize(root: Dir.pwd)
+      @root = Pathname.new(root)
+      @mirrors_dir = @root.join("mirrors")
+      @gitignore_path = @root.join(".gitignore")
+      @mirrorfile_path = @root.join("Mirrorfile")
+      @initializer_path = @root.join("config/initializers/mirrors.rb")
+      @mirrorfile = load_mirrorfile if @mirrorfile_path.exist?
+    end
+
+    # Clones all repositories that don't exist locally.
+    #
+    # Creates the mirrors directory if it doesn't exist, then iterates
+    # through all entries in the Mirrorfile and clones any that are missing.
+    #
+    # @return [void]
+    # @raise [MirrorfileNotFound] if Mirrorfile doesn't exist
+    #
+    # @example
+    #   mirror = Mirrorfile::Mirror.new
+    #   mirror.install
+    #
+    # @see Entry#install
+    def install
+      ensure_mirrorfile!
+      mirrors_dir.mkpath
+      @mirrorfile.entries.each { _1.install(mirrors_dir) }
+    end
+
+    # Updates all existing local repositories.
+    #
+    # Iterates through all entries in the Mirrorfile and pulls the latest
+    # changes for any that exist locally. Repositories that haven't been
+    # cloned are skipped.
+    #
+    # @return [void]
+    # @raise [MirrorfileNotFound] if Mirrorfile doesn't exist
+    #
+    # @example
+    #   mirror = Mirrorfile::Mirror.new
+    #   mirror.update
+    #
+    # @see Entry#update
+    def update
+      ensure_mirrorfile!
+      @mirrorfile.entries.each { _1.update(mirrors_dir) }
+    end
+
+    # Initializes a new project with mirror support.
+    #
+    # This method creates all necessary files and directories for using
+    # Mirrorfile in a project:
+    #
+    # - Creates a Mirrorfile with example syntax
+    # - Adds /mirrors to .gitignore (creates file if needed)
+    # - Creates a Rails initializer for Zeitwerk autoloading
+    #
+    # Existing files are not overwritten.
+    #
+    # @return [void]
+    #
+    # @example
+    #   mirror = Mirrorfile::Mirror.new
+    #   mirror.init
+    #   # => Creates Mirrorfile, updates .gitignore, creates initializer
+    #
+    # @see #create_mirrorfile
+    # @see #setup_gitignore
+    # @see #setup_zeitwerk
+    def init
+      create_mirrorfile
+      setup_gitignore
+      setup_zeitwerk
+      puts "Initialized mirrors in #{root}"
+    end
+
+    # Lists all entries in the Mirrorfile.
+    #
+    # @return [Array<Entry>] array of all mirror entries
+    # @raise [MirrorfileNotFound] if Mirrorfile doesn't exist
+    #
+    # @example
+    #   mirror.list.each { |entry| puts entry }
+    def list
+      ensure_mirrorfile!
+      @mirrorfile.entries.to_a
+    end
+
+    private
+
+    # Loads and parses the Mirrorfile.
+    #
+    # @return [Mirrorfile] the parsed Mirrorfile
+    # @api private
+    def load_mirrorfile
+      Mirrorfile.load(mirrorfile_path)
+    end
+
+    # Raises an error if Mirrorfile doesn't exist.
+    #
+    # @raise [MirrorfileNotFound] if Mirrorfile doesn't exist
+    # @return [void]
+    # @api private
+    def ensure_mirrorfile!
+      raise MirrorfileNotFound, "Run 'mirror init' first" unless @mirrorfile
+    end
+
+    # Creates a new Mirrorfile with example syntax.
+    #
+    # Does nothing if Mirrorfile already exists.
+    #
+    # @return [Integer, nil] bytes written or nil if file exists
+    # @api private
+    def create_mirrorfile
+      mirrorfile_path.exist? || mirrorfile_path.write(<<~RUBY)
+        # frozen_string_literal: true
+
+        # Mirror repositories
+        #
+        # Set a source for subsequent mirror declarations:
+        #
+        #   source "https://github.com"
+        #
+        # Then declare mirrors with optional custom names:
+        #
+        #   mirror "user/repo"
+        #   mirror "user/other-repo", as: "custom-name"
+        #
+        # You can change sources mid-file:
+        #
+        #   source "https://gitlab.com"
+        #
+        #   mirror "org/project"
+        #
+        # Or use full URLs without a source:
+        #
+        #   mirror "https://bitbucket.org/team/repo"
+
+        source "https://github.com"
+
+        # mirror "rails/rails", as: "rails-source"
+      RUBY
+    end
+
+    # Adds /mirrors to .gitignore.
+    #
+    # Creates .gitignore if it doesn't exist. Appends the ignore
+    # pattern only if not already present.
+    #
+    # @return [Integer, nil] bytes written or nil if already ignored
+    # @api private
+    def setup_gitignore
+      gitignore_path.exist? || gitignore_path.write("")
+
+      lines = gitignore_path.readlines.map(&:chomp)
+      lines.include?("/mirrors") || gitignore_path.write([*lines, "/mirrors"].join("\n") + "\n")
+    end
+
+    # Creates a Rails initializer for Zeitwerk autoloading.
+    #
+    # The initializer configures Zeitwerk to autoload code from
+    # lib/ directories within mirrored repositories.
+    #
+    # Does nothing if initializer already exists.
+    #
+    # @return [Integer, nil] bytes written or nil if file exists
+    # @api private
+    def setup_zeitwerk
+      initializer_path.dirname.mkpath
+      initializer_path.exist? || initializer_path.write(<<~RUBY)
+        # frozen_string_literal: true
+
+        # Autoload mirrored repositories
+        #
+        # This initializer configures Zeitwerk to autoload code from
+        # lib/ directories within mirrored repositories.
+        #
+        # @see https://github.com/fxn/zeitwerk
+
+        Rails.autoloaders.main.tap do |loader|
+          mirrors = Rails.root.join("mirrors")
+
+          mirrors.glob("*/lib").each do |lib_path|
+            loader.push_dir(lib_path)
+          end if mirrors.exist?
+        end
+      RUBY
+    end
+  end
+end

data/lib/mirrorfile/mirrorfile.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Mirrorfile
+  # Provides the DSL for parsing and evaluating Mirrorfile contents.
+  #
+  # Mirrorfile implements a domain-specific language similar to Bundler's
+  # Gemfile. It allows users to specify repository sources and mirror
+  # definitions in a readable, declarative format.
+  #
+  # @example Mirrorfile DSL
+  #   source "https://github.com"
+  #
+  #   mirror "rails/rails", as: "rails-source"
+  #   mirror "hotwired/turbo-rails"
+  #
+  #   source "https://gitlab.com"
+  #
+  #   mirror "org/project"
+  #
+  # @example Programmatic usage
+  #   mirrorfile = Mirrorfile::Mirrorfile.new
+  #   mirrorfile.source("https://github.com")
+  #   mirrorfile.mirror("rails/rails", as: "rails")
+  #   mirrorfile.entries.each { |e| puts e.url }
+  #
+  # @since 0.1.0
+  class Mirrorfile
+    # Creates a new Mirrorfile instance.
+    #
+    # @return [Mirrorfile] a new instance with no entries or source
+    def initialize
+      @entries = []
+      @source = nil
+    end
+
+    # Sets the base URL for subsequent mirror declarations.
+    #
+    # The source URL is prepended to repository paths in following
+    # {#mirror} calls until a new source is declared. This allows
+    # grouping repositories by host without repeating the full URL.
+    #
+    # @param url [String] the base URL for repositories (e.g., "https://github.com")
+    # @return [String] the normalized source URL (trailing slash removed)
+    #
+    # @example Setting a GitHub source
+    #   source "https://github.com"
+    #   mirror "rails/rails"  # clones from https://github.com/rails/rails
+    #
+    # @example Multiple sources
+    #   source "https://github.com"
+    #   mirror "user/repo1"
+    #
+    #   source "https://gitlab.com"
+    #   mirror "user/repo2"  # clones from https://gitlab.com/user/repo2
+    def source(url)
+      @source = url.chomp("/")
+    end
+
+    # Declares a repository to be mirrored.
+    #
+    # If a {#source} has been set, the path is appended to it to form
+    # the full URL. Otherwise, the path is treated as a complete URL.
+    #
+    # @param path [String] the repository path or full URL
+    # @param as [String] the local directory name (defaults to repo name)
+    # @return [Entry] the newly created entry
+    #
+    # @example With source set
+    #   source "https://github.com"
+    #   mirror "rails/rails"                    # uses source + path
+    #   mirror "hotwired/turbo", as: "turbo"    # custom local name
+    #
+    # @example Without source (full URL)
+    #   mirror "https://github.com/rails/rails"
+    #   mirror "git@github.com:rails/rails.git", as: "rails"
+    #
+    # @see #source
+    def mirror(path, as: File.basename(path, ".git"))
+      url = @source ? "#{@source}/#{path}" : path
+      Entry.new(url:, name: as).tap { @entries << _1 }
+    end
+
+    # Returns a lazy enumerator of all declared entries.
+    #
+    # Using a lazy enumerator allows for efficient iteration over
+    # entries without loading them all into memory at once, and
+    # enables chaining with other enumerable methods.
+    #
+    # @return [Enumerator::Lazy<Entry>] lazy enumerator of Entry objects
+    #
+    # @example Iterating over entries
+    #   mirrorfile.entries.each { |entry| entry.install(base_dir) }
+    #
+    # @example Filtering entries
+    #   mirrorfile.entries
+    #     .select { |e| e.name.start_with?("rails") }
+    #     .each { |e| e.update(base_dir) }
+    def entries
+      @entries.lazy
+    end
+
+    # Returns the number of declared entries.
+    #
+    # @return [Integer] the count of mirror entries
+    def size
+      @entries.size
+    end
+
+    # Loads and evaluates a Mirrorfile from disk.
+    #
+    # @param path [Pathname, String] path to the Mirrorfile
+    # @return [Mirrorfile] a new instance with entries from the file
+    # @raise [MirrorfileNotFound] if the file doesn't exist
+    # @raise [SyntaxError] if the file contains invalid Ruby
+    #
+    # @example
+    #   mirrorfile = Mirrorfile::Mirrorfile.load("Mirrorfile")
+    #   mirrorfile.entries.each { |e| puts e.url }
+    def self.load(path)
+      path = Pathname.new(path)
+      raise MirrorfileNotFound, "Mirrorfile not found at #{path}" unless path.exist?
+
+      new.tap { _1.instance_eval(path.read, path.to_s) }
+    end
+  end
+end

data/lib/mirrorfile/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Mirrorfile
+  # Current version of the Mirrorfile gem
+  # @return [String] the semantic version string
+  VERSION = "0.1.0"
+end

data/lib/mirrorfile.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "mirrorfile/version"
+require_relative "mirrorfile/entry"
+require_relative "mirrorfile/mirrorfile"
+require_relative "mirrorfile/mirror"
+require_relative "mirrorfile/cli"
+
+# Mirrorfile is a gem for managing local mirrors of git repositories.
+#
+# It provides a DSL similar to Bundler's Gemfile for specifying repositories
+# to clone and keep updated locally. This is useful for vendoring dependencies,
+# referencing source code, or maintaining offline copies of repositories.
+#
+# @example Basic usage with a Mirrorfile
+#   # Mirrorfile
+#   source "https://github.com"
+#
+#   mirror "rails/rails", as: "rails-source"
+#   mirror "hotwired/turbo-rails"
+#
+# @example Command line usage
+#   $ bin/mirror init     # Initialize project with Mirrorfile
+#   $ bin/mirror install  # Clone all repositories
+#   $ bin/mirror update   # Pull latest changes
+#
+# @author Your Name
+# @since 0.1.0
+module Mirrorfile
+  class Error < StandardError; end
+
+  # Error raised when Mirrorfile is not found
+  class MirrorfileNotFound < Error; end
+
+  # Error raised when a git operation fails
+  class GitOperationError < Error; end
+
+  class << self
+    # Returns the root path for mirror operations
+    #
+    # @return [Pathname] the current working directory as a Pathname
+    def root
+      Pathname.new(Dir.pwd)
+    end
+
+    # Returns the path to the mirrors directory
+    #
+    # @return [Pathname] path to the mirrors directory
+    def mirrors_dir
+      root.join("mirrors")
+    end
+
+    # Returns the path to the Mirrorfile
+    #
+    # @return [Pathname] path to the Mirrorfile
+    def mirrorfile_path
+      root.join("Mirrorfile")
+    end
+  end
+end

data/mirrorfile.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "lib/mirrorfile/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "mirrorfile"
+  spec.version = Mirrorfile::VERSION
+  spec.authors = ["Nathan Kidd"]
+  spec.email = ["nathankidd@hey.com"]
+
+  spec.summary = "Manage local mirrors of git repositories"
+
+  spec.description = <<~DESC
+    Mirrorfile provides a DSL similar to Bundler's Gemfile for managing local
+    mirrors of git repositories. Clone and keep repositories updated with
+    simple commands. Includes Rails/Zeitwerk integration for autoloading
+    mirrored code.
+  DESC
+
+  spec.homepage = "https://github.com/n-at-han-k/mirrorfile"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = ["mirror"]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.21"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: mirrorfile
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nathan Kidd
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  Mirrorfile provides a DSL similar to Bundler's Gemfile for managing local
+  mirrors of git repositories. Clone and keep repositories updated with
+  simple commands. Includes Rails/Zeitwerk integration for autoloading
+  mirrored code.
+email:
+- nathankidd@hey.com
+executables:
+- mirror
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/mirror
+- lib/mirrorfile.rb
+- lib/mirrorfile/cli.rb
+- lib/mirrorfile/entry.rb
+- lib/mirrorfile/mirror.rb
+- lib/mirrorfile/mirrorfile.rb
+- lib/mirrorfile/version.rb
+- mirrorfile.gemspec
+homepage: https://github.com/n-at-han-k/mirrorfile
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/n-at-han-k/mirrorfile
+  source_code_uri: https://github.com/n-at-han-k/mirrorfile
+  changelog_uri: https://github.com/n-at-han-k/mirrorfile/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/n-at-han-k/mirrorfile
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Manage local mirrors of git repositories
+test_files: []