dr_talon 0.1.0

data/lib/dr_talon/engine/materializer.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module DrTalon
+  module Engine
+    # Copies a cached engine into a {Project} and records what it placed in a
+    # manifest, so switching engines later removes exactly those files and
+    # never touches the game or anything else in the project.
+    class Materializer
+      MANIFEST = File.join(".talon", "engine.yml")
+
+      # Top-level files a +:game_only+ project gets: enough to run the game
+      # and its tests. Windows builds may also need the DLLs next to the exe.
+      GAME_ONLY_FILES = %w[dragonruby dragonruby.exe font.ttf].freeze
+
+      # Files talon never copies into a project.
+      SKIPPED = [Installation::METADATA_FILE].freeze
+
+      # File names never copied, wherever they are (DragonRuby's zips include
+      # macOS Finder metadata).
+      SKIPPED_NAMES = %w[.DS_Store].freeze
+
+      # Project files that differ from the engine's and aren't from a previous
+      # install, so overwriting them could lose someone's work.
+      class Conflict < Error; end
+
+      # @!attribute [r] engine
+      #   @return [String, nil] the installed {Installation#id}
+      # @!attribute [r] files
+      #   @return [Array<String>] project-relative paths talon placed
+      Manifest = Data.define(:engine, :files)
+
+      # @!attribute [r] copied
+      #   @return [Integer] files written
+      # @!attribute [r] removed
+      #   @return [Integer] files from the previous engine that were deleted
+      # @!attribute [r] cloned
+      #   @return [Integer] how many of the copies were reflinks
+      Result = Data.define(:copied, :removed, :cloned)
+
+      # @param project [Project]
+      def initialize(project)
+        @project = project
+      end
+
+      # @return [Manifest, nil]
+      def manifest
+        path = @project.path(MANIFEST)
+        return nil unless File.file?(path)
+
+        data = YAML.safe_load_file(path)
+        raise Error, "#{MANIFEST} is not a mapping" unless data.is_a?(Hash)
+
+        files = Array(data["files"]).map(&:to_s)
+        # Entries are deleted on the next install, so never trust one that
+        # points outside the project.
+        unsafe = files.find { |relative| relative.start_with?("/") || relative.split(%r{[/\\]}).include?("..") }
+        raise Error, "#{MANIFEST} lists a path outside the project: #{unsafe}" if unsafe
+
+        Manifest.new(engine: data["engine"], files: files)
+      rescue Psych::SyntaxError => e
+        raise Error, "Can't read #{MANIFEST}: #{e.message}"
+      end
+
+      # The engine files a project of this layout gets, relative to both the
+      # engine root and the project root.
+      #
+      # @param installation [Installation]
+      # @return [Array<String>]
+      def files_for(installation)
+        all = Dir.glob("**/*", File::FNM_DOTMATCH, base: installation.path).select do |relative|
+          path = File.join(installation.path, relative)
+          (File.file?(path) || File.symlink?(path)) && !File.basename(relative).match?(/\A\.\.?\z/)
+        end
+        all.reject! do |relative|
+          relative.start_with?("mygame/") || SKIPPED.include?(relative) || SKIPPED_NAMES.include?(File.basename(relative))
+        end
+
+        if @project.layout == :game_only
+          all.select! { |relative| GAME_ONLY_FILES.include?(relative) || relative.match?(%r{\A[^/]+\.dll\z}i) }
+        end
+
+        all.sort
+      end
+
+      # Project paths that would be overwritten but weren't placed by talon
+      # and differ from the engine's copy. Identical files are adopted
+      # silently, which covers projects started from an unzipped engine.
+      #
+      # @param installation [Installation]
+      # @return [Array<String>]
+      def conflicts(installation)
+        previous = manifest&.files || []
+
+        (files_for(installation) - previous).select do |relative|
+          target = @project.path(relative)
+          next false unless File.exist?(target) || File.symlink?(target)
+
+          source = File.join(installation.path, relative)
+          File.symlink?(target) || !File.file?(target) || !FileUtils.compare_file(source, target)
+        end
+      end
+
+      # Removes the previous engine's files and copies in +installation+.
+      #
+      # @param installation [Installation]
+      # @param force [Boolean] overwrite {#conflicts}
+      # @return [Result]
+      # @raise [Conflict]
+      def install(installation, force: false)
+        conflicting = conflicts(installation)
+        if conflicting.any? && !force
+          listed = conflicting.first(10).map { |relative| "  #{relative}" }.join("\n")
+          more = (conflicting.size > 10) ? "\n  ...and #{conflicting.size - 10} more" : ""
+          raise Conflict, "These project files differ from #{installation.id}'s and weren't installed by talon:\n" \
+            "#{listed}#{more}\nMove them aside, or pass --force to overwrite them."
+        end
+
+        files = files_for(installation)
+        removed = remove_files(manifest&.files || [])
+
+        # Record the new files before copying, so a failed copy can be cleaned
+        # up by the next install rather than reported as conflicts.
+        write_manifest(Manifest.new(engine: installation.id, files: files))
+
+        cloned = files.count do |relative|
+          target = @project.path(relative)
+          FileUtils.mkdir_p(File.dirname(target))
+          FileCopy.copy(File.join(installation.path, relative), target)
+        end
+
+        Result.new(copied: files.size, removed: removed, cloned: cloned)
+      end
+
+      private
+
+      def remove_files(files)
+        removed = files.count do |relative|
+          target = @project.path(relative)
+          next false unless File.exist?(target) || File.symlink?(target)
+
+          File.unlink(target)
+          true
+        end
+
+        prune_empty_dirs(files)
+        removed
+      end
+
+      # Deletes directories emptied by {#remove_files}, deepest first, without
+      # ever going above the project root.
+      def prune_empty_dirs(files)
+        dirs = files.flat_map do |relative|
+          parts = File.dirname(relative).split("/")
+          parts.each_index.map { |i| parts[0..i].join("/") }
+        end
+        dirs.uniq.reject { |dir| dir == "." }.sort_by { |dir| -dir.count("/") }.each do |dir|
+          path = @project.path(dir)
+          Dir.rmdir(path) if File.directory?(path) && Dir.empty?(path)
+        end
+      end
+
+      def write_manifest(manifest)
+        path = @project.path(MANIFEST)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, YAML.dump({"engine" => manifest.engine, "files" => manifest.files}))
+      end
+    end
+  end
+end

data/lib/dr_talon/engine/spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module DrTalon
+  module Engine
+    Spec = Data.define(:version, :tier, :platform)
+
+    # A possibly partial engine identifier given on the command line:
+    # "7.23", "7.23-pro" or "7.23-pro-linux-amd64".
+    class Spec
+      PATTERN = /\A(?<version>\d+(?:\.\d+)+)(?:-(?<tier>#{TIERS.join("|")})(?:-(?<platform>[a-z0-9-]+))?)?\z/
+
+      # @param string [String]
+      # @return [Spec]
+      # @raise [Error] if +string+ isn't a valid spec
+      def self.parse(string)
+        match = PATTERN.match(string.to_s.strip)
+        unless match
+          raise Error, "Invalid engine \"#{string}\". Expected VERSION[-TIER[-PLATFORM]], e.g. 7.23 or 7.23-pro."
+        end
+
+        new(version: match[:version], tier: match[:tier], platform: match[:platform])
+      end
+
+      # @param installation [Installation]
+      # @return [Boolean] whether every part this spec names matches
+      def match?(installation)
+        installation.version == version &&
+          (tier.nil? || installation.tier == tier) &&
+          (platform.nil? || installation.platform == platform)
+      end
+
+      # @return [String]
+      def to_s
+        [version, tier, platform].compact.join("-")
+      end
+    end
+  end
+end

data/lib/dr_talon/engine/store.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module DrTalon
+  module Engine
+    # The global cache of unpacked engines, one directory per {Installation#id}.
+    #
+    # DragonRuby only offers its latest release for download, so this cache is
+    # also the only archive of older versions.
+    class Store
+      # @return [String]
+      attr_reader :root
+
+      # @param root [String] usually {Paths#engines_dir}
+      # @param host_platform [String] preferred when a spec omits the platform
+      def initialize(root, host_platform: Engine.host_platform)
+        @root = root
+        @host_platform = host_platform
+      end
+
+      # @return [Array<Installation>] newest version first, then the most
+      #   capable tier (see {TIERS})
+      def installations
+        return [] unless File.directory?(root)
+
+        Dir.children(root)
+          .reject { |name| name.start_with?(".") }
+          .map { |name| File.join(root, name) }
+          .select { |path| File.file?(File.join(path, Installation::METADATA_FILE)) }
+          .map { |path| Installation.load(path) }
+          .sort { |a, b| sort_key(b) <=> sort_key(a) }
+      end
+
+      # @param id [String] a full {Installation#id}
+      # @return [Installation, nil]
+      def get(id)
+        path = path_for(id)
+        Installation.load(path) if File.file?(File.join(path, Installation::METADATA_FILE))
+      end
+
+      # Resolves a possibly partial spec to one installation. When the spec
+      # omits the platform, engines for the host platform win.
+      #
+      # @param spec [String, Spec]
+      # @return [Installation]
+      # @raise [NotFound, Ambiguous]
+      def find(spec)
+        spec = Spec.parse(spec) unless spec.is_a?(Spec)
+        matches = installations.select { |installation| spec.match?(installation) }
+        raise NotFound, "No cached engine matches #{spec}. Run `talon engine list` to see what's installed." if matches.empty?
+
+        if matches.size > 1 && spec.platform.nil?
+          native = matches.select { |installation| installation.platform == @host_platform }
+          matches = native unless native.empty?
+        end
+        return matches.first if matches.one?
+
+        raise Ambiguous, "#{spec} matches more than one engine: #{matches.map(&:id).join(", ")}. Use a full id."
+      end
+
+      # Resolves +spec+ to an engine built for this machine, since a project
+      # can only run its host's build.
+      #
+      # @param spec [Spec]
+      # @param default_tier [String, nil] used when +spec+ omits the tier
+      # @return [Installation]
+      # @raise [Error] if +spec+ names another platform
+      # @raise [NotFound, Ambiguous]
+      def find_native(spec, default_tier: nil)
+        if spec.platform && spec.platform != @host_platform
+          raise Error, "This machine runs #{@host_platform} engines; #{spec} is for #{spec.platform}."
+        end
+
+        find(Spec.new(version: spec.version, tier: spec.tier || default_tier, platform: @host_platform))
+      end
+
+      # @return [Installation, nil] the newest engine for this machine
+      def latest_native
+        installations.find { |installation| installation.platform == @host_platform }
+      end
+
+      # @param id [String]
+      # @return [String]
+      def path_for(id)
+        File.join(root, id)
+      end
+
+      # Larger sorts first: newer versions, then more capable tiers.
+      def sort_key(installation)
+        [installation.gem_version, -(TIERS.index(installation.tier) || TIERS.size), installation.platform]
+      end
+      private :sort_key
+
+      # Deletes an installation from the cache.
+      #
+      # @param installation [Installation]
+      # @return [void]
+      def remove(installation)
+        FileUtils.rm_rf(installation.path)
+      end
+
+      # Yields an empty directory inside the store, on the same filesystem, so
+      # a finished import can be moved into place with a rename. The directory
+      # is removed afterwards.
+      #
+      # @yieldparam dir [String]
+      # @return [Object] the block's result
+      def stage
+        FileUtils.mkdir_p(root)
+        dir = Dir.mktmpdir(".staging-", root)
+        yield dir
+      ensure
+        FileUtils.rm_rf(dir) if dir
+      end
+    end
+  end
+end

data/lib/dr_talon/engine.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module DrTalon
+  # Cached DragonRuby engines: identifying, importing and looking them up.
+  module Engine
+    # License tiers, most capable first. Jam is DragonRuby's free license:
+    # Standard's API, but it only exports to the web.
+    TIERS = %w[pro indie standard jam].freeze
+
+    # The engine path doesn't look like a DragonRuby distribution, or a detail
+    # such as its version can't be determined.
+    class InvalidEngine < Error; end
+
+    # No cached engine matches a requested spec.
+    class NotFound < Error; end
+
+    # More than one cached engine matches a requested spec.
+    class Ambiguous < Error; end
+
+    # An engine with the same id is already cached.
+    class AlreadyInstalled < Error; end
+
+    # The DragonRuby platform name for the machine talon is running on, as used
+    # in DragonRuby's zip and directory names (+dragonruby-linux-amd64+).
+    #
+    # @param host_os [String]
+    # @param host_cpu [String]
+    # @return [String]
+    def self.host_platform(host_os: RbConfig::CONFIG["host_os"], host_cpu: RbConfig::CONFIG["host_cpu"])
+      arch = /arm|aarch64/.match?(host_cpu) ? "arm64" : "amd64"
+
+      case host_os
+      when /darwin/ then "macos"
+      when /mswin|mingw|cygwin/ then "windows-#{arch}"
+      else "linux-#{arch}"
+      end
+    end
+  end
+end
+
+require_relative "engine/installation"
+require_relative "engine/spec"
+require_relative "engine/inspector"
+require_relative "engine/store"
+require_relative "engine/importer"
+require_relative "engine/materializer"
+require_relative "engine/git_ignore"
+require_relative "engine/fetchers"

data/lib/dr_talon/errors.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DrTalon
+  class Error < StandardError; end
+end

data/lib/dr_talon/file_copy.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module DrTalon
+  # Copies single files, cloning them (reflinks) where the filesystem allows so
+  # copies of the same engine into many projects share storage. Falls back to
+  # a byte copy across filesystems or on filesystems without cloning.
+  module FileCopy
+    # Linux +ioctl(dst, FICLONE, src)+; supported by btrfs and XFS.
+    FICLONE = 0x40049409
+    CLONE_UNSUPPORTED = [
+      Errno::EOPNOTSUPP, Errno::EXDEV, Errno::EINVAL, Errno::ENOTTY, Errno::EPERM, Errno::EBADF, NotImplementedError
+    ].freeze
+
+    module_function
+
+    # Copies +src+ to +dst+, keeping the mode and timestamps. An existing
+    # +dst+ (including a symlink) is replaced rather than written through.
+    #
+    # @param src [String]
+    # @param dst [String]
+    # @return [Boolean] whether the file was cloned rather than byte-copied
+    def copy(src, dst)
+      File.unlink(dst) if File.symlink?(dst) || File.exist?(dst)
+
+      cloned = File.open(src, "rb") do |input|
+        File.open(dst, File::WRONLY | File::CREAT | File::EXCL | File::BINARY) do |output|
+          try_clone(input, output).tap { |done| IO.copy_stream(input, output) unless done }
+        end
+      end
+
+      stat = File.stat(src)
+      File.chmod(stat.mode & 0o7777, dst)
+      File.utime(stat.atime, stat.mtime, dst)
+      cloned
+    end
+
+    # @return [Boolean] whether the clone succeeded
+    def try_clone(input, output)
+      return false unless RbConfig::CONFIG["host_os"].include?("linux")
+
+      output.ioctl(FICLONE, input.fileno)
+      true
+    rescue *CLONE_UNSUPPORTED
+      false
+    end
+  end
+end