rpremote 0.1.0

data/lib/rpremote/flash_command.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Rpremote
+  class FlashCommand
+    def self.run(args, defaults:, output: $stdout, flasher: Flasher)
+      options = parse_options(args, defaults)
+      raise ArgumentError, "flash does not accept arguments; use --firmware FILE" unless args.empty?
+
+      target = Target.new(**options.slice(:language, :language_version, :board, :cache_dir, :firmware))
+      result = flasher.new(timeout: options[:timeout]).flash(
+        target.firmware_path(root: Dir.pwd),
+        mount: options[:mount],
+        port: options[:port]
+      )
+      output.puts("flashed firmware #{File.basename(target.firmware_path)}: #{result.port}")
+    end
+
+    def self.parse_options(args, defaults)
+      options = {
+        timeout: defaults.fetch(:timeout, Flasher::DEFAULT_TIMEOUT),
+        mount: defaults[:mount],
+        port: defaults[:port],
+        cache_dir: defaults.fetch(:cache, Target::DEFAULT_CACHE_DIR),
+        firmware: defaults[:firmware],
+        language: defaults.fetch(:language, Target::DEFAULT_LANGUAGE),
+        language_version: defaults.fetch(:language_version, Target::DEFAULT_LANGUAGE_VERSION),
+        board: defaults.fetch(:board, Target::DEFAULT_BOARD)
+      }
+      OptionParser.new do |parser|
+        parser.on("--cache DIR") { |value| options[:cache_dir] = value }
+        parser.on("--firmware FILE") { |value| options[:firmware] = value }
+        parser.on("--language LANGUAGE") { |value| options[:language] = value }
+        parser.on("--language-version VERSION") { |value| options[:language_version] = value }
+        parser.on("--board BOARD") { |value| options[:board] = value }
+        parser.on("--mount DIR") { |value| options[:mount] = value }
+        parser.on("--port PORT") { |value| options[:port] = value }
+        parser.on("--timeout SECONDS", Float) { |value| options[:timeout] = value }
+      end.parse!(args)
+      options
+    end
+    private_class_method :parse_options
+  end
+end

data/lib/rpremote/flasher.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Rpremote
+  class Flasher
+    DEFAULT_VOLUMES_ROOT = "/Volumes"
+    DEFAULT_TIMEOUT = 10.0
+    INFO_FILE = "INFO_UF2.TXT"
+    UF2_BLOCK_SIZE = 512
+    UF2_MAGIC_START0 = 0x0A324655
+    UF2_MAGIC_START1 = 0x9E5D5157
+    UF2_MAGIC_END = 0x0AB16F30
+
+    Result = Data.define(:mount, :destination, :port)
+
+    class Error < Rpremote::Error; end
+    class MountNotFoundError < Error; end
+    class InvalidTargetError < Error; end
+    class TimeoutError < Error; end
+
+    attr_reader :volumes_root, :timeout
+
+    def initialize(
+      volumes_root: DEFAULT_VOLUMES_ROOT,
+      timeout: DEFAULT_TIMEOUT,
+      mount_probe: nil,
+      port_probe: nil,
+      sleeper: nil
+    )
+      @volumes_root = volumes_root
+      @timeout = Float(timeout)
+      @mount_probe = mount_probe || ->(path) { Dir.exist?(path) }
+      @port_probe = port_probe || -> { Device.main_port }
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      raise ArgumentError, "timeout must be positive" unless @timeout.positive?
+    end
+
+    def flash(uf2_path, mount: nil, port: nil)
+      validate_firmware!(uf2_path)
+      target = find_mount(mount)
+      destination = File.join(target, File.basename(uf2_path))
+      copy_firmware(uf2_path, destination)
+      wait_until("BOOTSEL drive to disappear") { !mount_probe.call(target) }
+      detected_port = wait_until("R2P2 serial port to appear") { detect_port(port) }
+      Result.new(mount: target, destination: destination, port: detected_port)
+    end
+
+    def find_mount(explicit_mount = nil)
+      return validate_mount!(File.expand_path(explicit_mount)) if explicit_mount
+
+      matches = Dir.glob(File.join(volumes_root, "*")).select do |path|
+        Dir.exist?(path) && valid_target?(path)
+      end
+      case matches.length
+      when 0
+        raise MountNotFoundError,
+              "Pico 2 BOOTSEL drive not found; reconnect it while holding BOOTSEL or use --mount DIR"
+      when 1
+        matches.first
+      else
+        raise MountNotFoundError, "multiple Pico 2 BOOTSEL drives found; use --mount DIR"
+      end
+    end
+
+    private
+
+    attr_reader :mount_probe, :port_probe, :sleeper
+
+    def validate_firmware!(path)
+      raise InvalidTargetError, "UF2 file not found: #{path}" unless File.file?(path)
+      raise InvalidTargetError, "firmware file must have a .uf2 extension" unless File.extname(path).casecmp?(".uf2")
+      raise InvalidTargetError, "UF2 file is empty: #{path}" unless File.size?(path)
+      raise InvalidTargetError, "firmware is not a valid UF2 file: #{path}" unless valid_uf2?(path)
+    end
+
+    def validate_mount!(path)
+      raise MountNotFoundError, "BOOTSEL mount not found: #{path}" unless Dir.exist?(path)
+      raise InvalidTargetError, "mount is not an RP2350 BOOTSEL drive: #{path}" unless valid_target?(path)
+
+      path
+    end
+
+    def valid_target?(path)
+      info_path = File.join(path, INFO_FILE)
+      return false unless File.file?(info_path)
+
+      File.basename(path).casecmp?("RP2350") || File.read(info_path).match?(/RP2350|Pico 2/i)
+    rescue SystemCallError
+      false
+    end
+
+    def copy_firmware(source, destination)
+      FileUtils.copy_file(source, destination)
+    rescue SystemCallError => e
+      raise Error, "failed to copy UF2 firmware: #{e.message}"
+    end
+
+    def wait_until(description)
+      deadline = monotonic_time + timeout
+      loop do
+        result = yield
+        return result if result
+        raise TimeoutError, "timed out waiting for #{description}" if monotonic_time >= deadline
+
+        sleeper.call(0.1)
+      end
+    end
+
+    def valid_uf2?(path)
+      size = File.size(path)
+      return false if size < UF2_BLOCK_SIZE || (size % UF2_BLOCK_SIZE).positive?
+
+      start_magic = File.binread(path, 8).unpack("V2")
+      end_magic = File.binread(path, 4, UF2_BLOCK_SIZE - 4).unpack1("V")
+      start_magic == [UF2_MAGIC_START0, UF2_MAGIC_START1] && end_magic == UF2_MAGIC_END
+    end
+
+    def detect_port(explicit_port)
+      return explicit_port if explicit_port && File.exist?(explicit_port)
+
+      port_probe.call
+    rescue Device::NotFoundError, Device::MultipleDevicesError
+      nil
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/rpremote/help.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rpremote
+  module Help
+    TEXT = <<~HELP
+      rpremote - R2P2 remote control for Raspberry Pi Pico 2
+
+      Usage:
+        rpremote setup [--language LANGUAGE] [--language-version VERSION] [--force] [--cache DIR]
+        rpremote build [--language LANGUAGE] [--language-version VERSION] [--board BOARD]
+                       [--firmware FILE] [--cache DIR]
+                       [--mrbgems FILE|--no-mrbgems]
+        rpremote build clean
+        rpremote dfu app FILE [--type ruby|rite] [--port PORT] [--baud RATE] [--timeout SEC]
+        rpremote dfu compile FILE [--output FILE] [--language picoruby]
+                             [--language-version VERSION] [--cache DIR]
+        rpremote dfu status [--port PORT] [--baud RATE] [--timeout SEC]
+        rpremote mrbgems check|list|lock|update [--file FILE] [--lockfile FILE]
+        rpremote flash [--firmware FILE] [--language LANGUAGE] [--language-version VERSION]
+                       [--board BOARD] [--cache DIR] [--mount DIR] [--port PORT] [--timeout SEC]
+        rpremote ports
+        rpremote run FILE [--port PORT] [--timeout SEC] [--language LANGUAGE]
+        rpremote monitor [--port PORT]
+        rpremote repl [--port PORT]
+        rpremote exec CODE [--port PORT] [--timeout SEC] [--language LANGUAGE]
+        rpremote reset [--port PORT]
+        rpremote fs cp FILE :/REMOTE/PATH [--port PORT]
+        rpremote fs cp :/REMOTE/PATH FILE [--port PORT]
+        rpremote fs cat :/REMOTE/PATH [--port PORT]
+        rpremote fs ls :/REMOTE/PATH [--port PORT]
+        rpremote fs rm :/REMOTE/PATH [--port PORT]
+        rpremote fs mkdir :/REMOTE/PATH [--port PORT]
+
+      `rpremote build clean` removes only the project's generated `build/` directory.
+
+      Configuration:
+        config/setting.json  default project options
+
+      Options:
+        --force           download the PicoRuby source again during setup
+        --language-version VERSION
+                          use R2P2/PicoRuby 4.0.3 or 3.4.2 (default: 4.0.3)
+        --cache DIR       use another project cache directory
+        --mrbgems FILE    use an explicit Mrbgems definition during build
+        --no-mrbgems      build without the automatically detected Mrbgems
+        --board BOARD
+                          select pico2 or pico2_w (default: pico2)
+        --firmware FILE   build to, or flash from, this UF2 path
+        --language LANGUAGE
+                          select the remote language (default: picoruby)
+        --config FILE     use another configuration file
+        --mount DIR       use an explicit RP2350 BOOTSEL drive
+        --port PORT       use an explicit R2P2 CDC 0 device
+        --baud RATE       serial baud rate (default: 115200)
+        --timeout SEC     timeout in seconds (default: 10)
+        -h, --help        show this help
+        -V, --version     show the version
+    HELP
+  end
+end

data/lib/rpremote/language.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Rpremote
+  module Language
+    SUPPORTED = %w[picoruby].freeze
+
+    module_function
+
+    def validate!(language)
+      return language if SUPPORTED.include?(language)
+
+      raise ArgumentError, "unsupported language: #{language}"
+    end
+  end
+end

data/lib/rpremote/language_source.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "net/http"
+require "timeout"
+require "uri"
+
+module Rpremote
+  class LanguageSource
+    MAX_REDIRECTS = 5
+
+    class Error < Rpremote::Error; end
+    class DownloadError < Error; end
+    class ExtractError < Error; end
+
+    attr_reader :language, :version, :cache_dir
+
+    def initialize(language: Target::DEFAULT_LANGUAGE, version: Target::DEFAULT_LANGUAGE_VERSION,
+                   cache_dir: Target::DEFAULT_CACHE_DIR,
+                   fetcher: nil, extractor: nil, preparer: nil)
+      Language.validate!(language)
+
+      @language = language
+      @version = version
+      @cache_dir = File.expand_path(cache_dir.gsub("{version}", version))
+      @fetcher = fetcher || method(:download)
+      @extractor = extractor || method(:extract)
+      @preparer = preparer || method(:prepare_repository)
+    end
+
+    def setup(force: false)
+      FileUtils.mkdir_p(cache_dir)
+      fetch_archive if force || !File.size?(archive_path)
+      unless File.directory?(source_dir) && !force
+        FileUtils.rm_rf(source_dir) if force
+        extractor.call(archive_path, cache_dir)
+      end
+      raise ExtractError, "PicoRuby source was not extracted: #{source_dir}" unless File.directory?(source_dir)
+
+      preparer.call(source_dir)
+      source_dir
+    end
+
+    def archive_url
+      "https://github.com/picoruby/picoruby/archive/refs/tags/#{version}.zip"
+    end
+
+    def archive_path
+      File.join(cache_dir, "picoruby-#{version}.zip")
+    end
+
+    def source_dir
+      File.join(cache_dir, "picoruby-#{version}")
+    end
+
+    private
+
+    attr_reader :fetcher, :extractor, :preparer
+
+    def fetch_archive
+      temporary = "#{archive_path}.part"
+      File.binwrite(temporary, fetcher.call(archive_url))
+      raise DownloadError, "downloaded PicoRuby archive is empty" unless File.size?(temporary)
+
+      File.rename(temporary, archive_path)
+    rescue SystemCallError => e
+      raise DownloadError, "cannot store PicoRuby source: #{e.message}"
+    ensure
+      FileUtils.rm_f(temporary) if temporary
+    end
+
+    def extract(archive, destination)
+      success = system("/usr/bin/ditto", "-x", "-k", archive, destination)
+      raise ExtractError, "cannot extract PicoRuby archive: #{archive}" unless success
+    end
+
+    def prepare_repository(source)
+      mruby_core = File.join(source, "mrbgems/picoruby-mruby/lib/mruby/lib/mruby/core_ext.rb")
+      pico_sdk = File.join(source, "mrbgems/picoruby-r2p2/lib/pico-sdk/CMakeLists.txt")
+      return if File.file?(mruby_core) && File.file?(pico_sdk)
+
+      commands = []
+      unless File.directory?(File.join(source, ".git"))
+        commands << %w[git init]
+        commands << ["git", "remote", "add", "origin", "https://github.com/picoruby/picoruby.git"]
+      end
+      commands.push(
+        ["git", "fetch", "--depth", "1", "origin", "refs/tags/#{version}"],
+        ["git", "checkout", "--force", "FETCH_HEAD"],
+        ["git", "submodule", "update", "--init", "--recursive", "--depth", "1"]
+      )
+      commands.each do |command|
+        next if system(*command, chdir: source)
+
+        raise ExtractError, "cannot prepare PicoRuby submodules: #{command.join(" ")}"
+      end
+    end
+
+    def download(url, redirects = MAX_REDIRECTS)
+      raise DownloadError, "too many redirects while downloading PicoRuby" if redirects.negative?
+
+      uri = URI(url)
+      raise DownloadError, "PicoRuby download requires HTTPS" unless uri.is_a?(URI::HTTPS)
+
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = "rpremote/#{Rpremote::VERSION}"
+      response = Net::HTTP.start(
+        uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 60
+      ) { |http| http.request(request) }
+
+      case response
+      when Net::HTTPSuccess
+        response.body
+      when Net::HTTPRedirection
+        location = response["location"]
+        raise DownloadError, "PicoRuby download redirect has no location" unless location
+
+        download(URI.join(url, location).to_s, redirects - 1)
+      else
+        raise DownloadError, "PicoRuby download failed: HTTP #{response.code} #{response.message}"
+      end
+    rescue SocketError, SystemCallError, Timeout::Error => e
+      raise DownloadError, "PicoRuby download failed: #{e.message}"
+    end
+  end
+end

data/lib/rpremote/mrbgems.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "open3"
+
+module Rpremote
+  class Mrbgems
+    DEFAULT_PATH = "Mrbgems"
+    DEFAULT_LOCK_PATH = "Mrbgems.lock"
+    LOCK_VERSION = 1
+    GITHUB_PATTERN = %r{\A[\w.-]+/[\w.-]+\z}
+    COMMIT_PATTERN = /\A[0-9a-f]{40,64}\z/i
+    VMS = %i[mruby mrubyc].freeze
+
+    Dependency = Data.define(:type, :source, :branch, :commit, :path)
+    Overlay = Data.define(:path, :fingerprint)
+
+    class Error < Rpremote::Error; end
+    class DefinitionError < Error; end
+    class LockError < Error; end
+
+    attr_reader :path, :lock_path
+
+    def initialize(path: DEFAULT_PATH, lock_path: nil, cwd: Dir.pwd, resolver: nil)
+      @path = File.expand_path(path, cwd)
+      @lock_path = File.expand_path(lock_path || DEFAULT_LOCK_PATH, File.dirname(@path))
+      @resolver = resolver || method(:resolve_github)
+    end
+
+    def exist?
+      File.file?(path)
+    end
+
+    def dependencies
+      @dependencies ||= load_definition
+    end
+
+    def vm
+      dependencies
+      @definition.vm_name
+    end
+
+    def check
+      dependencies.each { |dependency| validate_local!(dependency) if dependency.type == :path }
+      dependencies
+    end
+
+    def lock(update: false)
+      check
+      previous = update ? nil : read_lock(required: false)
+      entries = dependencies.map { |dependency| lock_entry(dependency, previous) }
+      contents = { "version" => LOCK_VERSION, "vm" => vm&.to_s, "gems" => entries }.compact
+      write_json(lock_path, contents)
+      contents
+    end
+
+    def read_lock(required: true)
+      contents = JSON.parse(File.read(lock_path))
+      validate_lock!(contents)
+      contents
+    rescue Errno::ENOENT
+      raise LockError, "mrbgems lock file does not exist: #{lock_path}" if required
+
+      nil
+    rescue JSON::ParserError => e
+      raise LockError, "invalid mrbgems lock file #{lock_path}: #{e.message}"
+    end
+
+    def generate_overlay(base_config:, target:, directory:, update: false)
+      lock_data = lock(update: update)
+      fingerprint = build_fingerprint(base_config, lock_data)
+      output_dir = File.join(File.expand_path(directory), fingerprint)
+      output_path = File.join(output_dir, "build_config.rb")
+      FileUtils.mkdir_p(output_dir)
+      write_file(output_path, overlay_source(base_config, target, lock_data.fetch("gems")))
+      Overlay.new(path: output_path, fingerprint: fingerprint)
+    end
+
+    private
+
+    attr_reader :resolver
+
+    def load_definition
+      dsl = Definition.new(path)
+      dsl.instance_eval(File.read(path), path, 1)
+      @definition = dsl
+      dsl.dependencies.freeze
+    rescue Errno::ENOENT
+      raise DefinitionError, "mrbgems definition does not exist: #{path}"
+    rescue SyntaxError => e
+      raise DefinitionError, "invalid mrbgems definition #{path}: #{e.message}"
+    rescue DefinitionError
+      raise
+    rescue StandardError => e
+      raise DefinitionError, "cannot load mrbgems definition #{path}: #{e.message}"
+    end
+
+    def validate_local!(dependency)
+      return if File.file?(File.join(dependency.path, "mrbgem.rake"))
+
+      raise DefinitionError, "local mrbgem has no mrbgem.rake: #{dependency.path}"
+    end
+
+    def lock_entry(dependency, previous)
+      if dependency.type == :github
+        commit = dependency.commit || previous_commit(previous, dependency) || resolver.call(
+          dependency.source, dependency.branch
+        )
+        { "type" => "github", "source" => dependency.source,
+          "branch" => dependency.branch, "commit" => validate_commit!(commit) }
+      else
+        { "type" => "path", "source" => dependency.source,
+          "sha256" => digest_directory(dependency.path) }
+      end
+    end
+
+    def previous_commit(lock_data, dependency)
+      return unless lock_data
+
+      entry = lock_data.fetch("gems").find do |gem|
+        gem["type"] == "github" && gem["source"] == dependency.source &&
+          gem["branch"] == dependency.branch
+      end
+      entry&.fetch("commit", nil)
+    end
+
+    def validate_commit!(commit)
+      value = commit.to_s.downcase
+      raise LockError, "invalid Git commit: #{commit.inspect}" unless COMMIT_PATTERN.match?(value)
+
+      value
+    end
+
+    def resolve_github(source, branch)
+      url = "https://github.com/#{source}.git"
+      stdout, stderr, status = Open3.capture3(
+        "git", "ls-remote", "--exit-code", url, "refs/heads/#{branch}"
+      )
+      unless status.success?
+        detail = stderr.strip
+        detail = "branch not found" if detail.empty?
+        raise LockError, "cannot resolve #{source} #{branch}: #{detail}"
+      end
+
+      validate_commit!(stdout.split.first)
+    rescue Errno::ENOENT
+      raise LockError, "git is required to resolve GitHub mrbgems"
+    end
+
+    def digest_directory(directory)
+      digest = Digest::SHA256.new
+      files = Dir.glob(File.join(directory, "**", "*"), File::FNM_DOTMATCH)
+                 .select { |file| File.file?(file) }
+                 .reject { |file| ignored_local_file?(file, directory) }
+                 .sort
+      files.each do |file|
+        relative = file.delete_prefix("#{directory}/")
+        digest.update(relative).update("\0").update(File.binread(file)).update("\0")
+      end
+      digest.hexdigest
+    end
+
+    def ignored_local_file?(file, directory)
+      relative = file.delete_prefix("#{directory}/")
+      relative.split(File::SEPARATOR).intersect?(%w[.git build tmp])
+    end
+
+    def validate_lock!(contents)
+      unless contents.is_a?(Hash) && contents["version"] == LOCK_VERSION && contents["gems"].is_a?(Array)
+        raise LockError, "unsupported mrbgems lock format: #{lock_path}"
+      end
+      unless contents["vm"].nil? || VMS.map(&:to_s).include?(contents["vm"])
+        raise LockError, "invalid mrbgems VM in lock file: #{contents["vm"].inspect}"
+      end
+
+      contents["gems"].each do |entry|
+        type = entry["type"]
+        valid = type == "github" ? valid_github_lock?(entry) : valid_path_lock?(entry)
+        raise LockError, "invalid mrbgems lock entry: #{entry.inspect}" unless valid
+      end
+    end
+
+    def valid_github_lock?(entry)
+      GITHUB_PATTERN.match?(entry["source"].to_s) && !entry["branch"].to_s.empty? &&
+        COMMIT_PATTERN.match?(entry["commit"].to_s)
+    end
+
+    def valid_path_lock?(entry)
+      entry["type"] == "path" && !entry["source"].to_s.empty? &&
+        /\A[0-9a-f]{64}\z/.match?(entry["sha256"].to_s)
+    end
+
+    def build_fingerprint(base_config, lock_data)
+      Digest::SHA256.hexdigest(
+        [File.binread(path), File.binread(base_config), JSON.generate(lock_data)].join("\0")
+      ).slice(0, 12)
+    end
+
+    def overlay_source(base_config, target, locked_entries)
+      lines = [
+        "# Generated by rpremote. Do not edit.",
+        "load #{File.expand_path(base_config).inspect}",
+        "conf = MRuby.targets.fetch(#{target.inspect})"
+      ]
+      dependencies.zip(locked_entries).each do |dependency, locked|
+        lines << if dependency.type == :github
+                   "conf.gem github: #{dependency.source.inspect}, " \
+                     "branch: #{dependency.branch.inspect}, checksum_hash: #{locked.fetch("commit").inspect}"
+                 else
+                   "conf.gem #{dependency.path.inspect}"
+                 end
+      end
+      "#{lines.join("\n")}\n"
+    end
+
+    def write_json(filename, contents)
+      write_file(filename, "#{JSON.pretty_generate(contents)}\n")
+    end
+
+    def write_file(filename, contents)
+      return if File.file?(filename) && File.binread(filename) == contents
+
+      FileUtils.mkdir_p(File.dirname(filename))
+      temporary = "#{filename}.tmp-#{Process.pid}"
+      File.binwrite(temporary, contents)
+      File.rename(temporary, filename)
+    ensure
+      FileUtils.rm_f(temporary) if temporary
+    end
+
+    class Definition
+      attr_reader :dependencies, :vm_name
+
+      def initialize(filename)
+        @directory = File.dirname(filename)
+        @dependencies = []
+      end
+
+      def vm(name)
+        value = name.to_sym
+        raise DefinitionError, "unsupported mrbgems VM: #{name.inspect}" unless VMS.include?(value)
+        raise DefinitionError, "mrbgems VM specified more than once" if vm_name
+
+        @vm_name = value
+      end
+
+      def gem(github: nil, path: nil, branch: "main", commit: nil)
+        sources = [github, path].compact
+        raise DefinitionError, "gem requires exactly one of github or path" unless sources.length == 1
+
+        dependency = if github
+                       github_dependency(github, branch, commit)
+                     else
+                       path_dependency(path, branch, commit)
+                     end
+        key = [dependency.type, dependency.source]
+        raise DefinitionError, "duplicate mrbgem: #{dependency.source}" if dependencies.any? do |item|
+          [item.type, item.source] == key
+        end
+
+        dependencies << dependency
+      end
+
+      private
+
+      attr_reader :directory
+
+      def github_dependency(source, branch, commit)
+        raise DefinitionError, "invalid GitHub mrbgem: #{source.inspect}" unless GITHUB_PATTERN.match?(source.to_s)
+        raise DefinitionError, "GitHub mrbgem branch must not be empty" if branch.to_s.empty?
+        raise DefinitionError, "invalid Git commit: #{commit.inspect}" if commit && !COMMIT_PATTERN.match?(commit.to_s)
+
+        Dependency.new(type: :github, source: source, branch: branch,
+                       commit: commit&.downcase, path: nil)
+      end
+
+      def path_dependency(source, branch, commit)
+        raise DefinitionError, "local mrbgem path must not be empty" if source.to_s.empty?
+        raise DefinitionError, "local mrbgem does not accept branch or commit" if branch != "main" || commit
+
+        Dependency.new(type: :path, source: source, branch: nil, commit: nil,
+                       path: File.expand_path(source, directory))
+      end
+    end
+  end
+end