dr_talon 0.1.0

data/lib/dr_talon/engine/fetchers.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+require "fileutils"
+require "json"
+require "open3"
+require "tmpdir"
+
+module DrTalon
+  module Engine
+    # Download the latest engine of a tier for this machine. Each fetcher's
+    # #fetch returns a zip or directory to hand to {Importer#import}; the
+    # caller deletes it afterwards.
+    module Fetchers
+      ZIP_MAGIC = "PK\x03\x04".b
+
+      # @param tier [String] one of {TIERS}
+      # @param options [Hash] passed to the fetcher (http:, downloads_dir:, platform:, ...)
+      # @return [DragonRubyAPI, ItchJam, Butler]
+      def self.for(tier, **options)
+        case tier
+        when "pro", "indie" then DragonRubyAPI.new(tier, **options)
+        when "jam" then ItchJam.new(**options.except(:butler))
+        when "standard" then Butler.new(**options.slice(:platform, :downloads_dir, :butler))
+        else raise Error, "Unknown tier \"#{tier}\". Expected one of #{TIERS.join(", ")}."
+        end
+      end
+
+      # @param path [String]
+      # @return [Boolean]
+      def self.zip?(path)
+        File.file?(path) && File.binread(path, 4) == ZIP_MAGIC
+      end
+
+      # Downloads +url+ to +path+, deleting a partial or non-zip result.
+      #
+      # @return [String] +path+
+      # @raise [Error]
+      def self.download_zip(http, url, path, auth: nil, &progress)
+        FileUtils.mkdir_p(File.dirname(path))
+        http.download(url, path, auth: auth, &progress)
+        raise Error, "The download from #{URI(url).host} isn't a zip." unless zip?(path)
+
+        path
+      rescue Exception # rubocop:disable Lint/RescueException -- also clean up on Ctrl-C
+        FileUtils.rm_f(path)
+        raise
+      end
+
+      # Pro and Indie, from dragonruby.org's subscription API with the
+      # account's login. The API answers with the zip's URL (as its body or a
+      # redirect) or with the zip itself; all three are handled.
+      class DragonRubyAPI
+        API = "https://dragonruby.org/api/download_%<tier>s_subscription_%<os>s"
+
+        # dragonruby.org's name for each platform it has downloads for.
+        OS_NAMES = {"linux-amd64" => "linux", "macos" => "mac", "windows-amd64" => "windows"}.freeze
+
+        # @return [String]
+        attr_reader :tier
+
+        # @param tier [String] "pro" or "indie"
+        # @param http [HTTP]
+        # @param downloads_dir [String] where the zip is saved
+        # @param platform [String]
+        # @param api [String] format string for the API URL (+tier+, +os+)
+        def initialize(tier, http: HTTP.new, downloads_dir: Paths.new.downloads_dir, platform: Engine.host_platform, api: API)
+          @tier = tier
+          @http = http
+          @downloads_dir = downloads_dir
+          @platform = platform
+          @api = api
+        end
+
+        # @return [Boolean]
+        def credentials?
+          true
+        end
+
+        # @return [String] the API URL for this machine
+        # @raise [Error] if dragonruby.org has no download for the platform
+        def api_url
+          os = OS_NAMES.fetch(@platform) do
+            raise Error, "dragonruby.org has no #{tier} download for #{@platform}. " \
+              "Download it by hand and run `talon engine import`."
+          end
+          format(@api, tier: tier, os: os)
+        end
+
+        # Checks a login without downloading the engine.
+        #
+        # @param credentials [Credentials]
+        # @return [void]
+        # @raise [HTTP::Unauthorized, HTTP::Error]
+        def verify(credentials)
+          Dir.mktmpdir("talon-login") do |dir|
+            # Stop early in case the answer is the zip itself.
+            catch(:enough) do
+              @http.download(api_url, File.join(dir, "response"), auth: credentials.to_auth) do |received, _total|
+                throw :enough if received > 64 * 1024
+              end
+            end
+          end
+        end
+
+        # @param credentials [Credentials]
+        # @return [String] path to the downloaded zip
+        # @raise [HTTP::Unauthorized, HTTP::Error, Error]
+        def fetch(credentials:, &progress)
+          raise Error, "A dragonruby.org login is needed for #{tier}." unless credentials
+
+          path = File.join(@downloads_dir, "dragonruby-#{tier}-#{@platform}.zip")
+          FileUtils.mkdir_p(@downloads_dir)
+          @http.download(api_url, path, auth: credentials.to_auth, &progress)
+          return path if Fetchers.zip?(path)
+
+          url = File.read(path, 4096).to_s.strip
+          FileUtils.rm_f(path)
+          unless url.match?(%r{\Ahttps?://\S+\z})
+            raise Error, "dragonruby.org answered with something other than a download link or zip."
+          end
+
+          Fetchers.download_zip(@http, url, path, &progress)
+        rescue Exception # rubocop:disable Lint/RescueException -- also clean up on Ctrl-C
+          FileUtils.rm_f(path) if path
+          raise
+        end
+      end
+
+      # Jam, DragonRuby's free license, from the demo uploads on its itch.io
+      # page. No account is needed: the page's download button posts to
+      # itch.io for a short-lived link, and so does this.
+      class ItchJam
+        PAGE = "https://dragonruby.itch.io/dragonruby-gtk"
+
+        # The itch.io upload names for each platform.
+        UPLOADS = {
+          "linux-amd64" => "x64 Linux Jam License",
+          "linux-arm64" => "arm64 Linux Jam License",
+          "macos" => "macOS Jam License",
+          "windows-amd64" => "Windows Jam License"
+        }.freeze
+
+        # @param http [HTTP]
+        # @param downloads_dir [String]
+        # @param platform [String]
+        # @param page [String] the itch.io game page
+        def initialize(http: HTTP.new, downloads_dir: Paths.new.downloads_dir, platform: Engine.host_platform, page: PAGE)
+          @http = http
+          @downloads_dir = downloads_dir
+          @platform = platform
+          @page = page
+        end
+
+        # @return [String]
+        def tier
+          "jam"
+        end
+
+        # @return [Boolean]
+        def credentials?
+          false
+        end
+
+        # @return [String] path to the downloaded zip
+        # @raise [HTTP::Error, Error]
+        def fetch(credentials: nil, &progress)
+          name = UPLOADS.fetch(@platform) { raise Error, "There's no Jam license download for #{@platform}." }
+          html = @http.get(@page)
+          token = html.scan(/<(?:meta|input)\b[^>]*>/).map { |tag| attributes(tag) }
+            .find { |attrs| attrs["name"] == "csrf_token" }&.dig("value")
+          id = demo_uploads(html)[name]
+          unless token && id
+            raise Error, "Couldn't find the \"#{name}\" download on #{@page}; itch.io's page may have changed. " \
+              "Download it by hand and run `talon engine import`."
+          end
+
+          answer = JSON.parse(@http.post_form("#{@page}/file/#{id}?source=view_game&as_props=1&after_download_lightbox=true",
+            "csrf_token" => token))
+          url = answer["url"] if answer.is_a?(Hash)
+          raise Error, "itch.io didn't return a download link for \"#{name}\"." unless url.is_a?(String)
+
+          Fetchers.download_zip(@http, url, File.join(@downloads_dir, "dragonruby-gtk-#{@platform}-jam.zip"), &progress)
+        rescue JSON::ParserError
+          raise Error, "itch.io answered the download request with something other than JSON."
+        end
+
+        private
+
+        # @return [Hash{String => String}] upload name => upload id, from the
+        #   page's "Download demo" section. itch.io doesn't keep attribute
+        #   order stable between requests, so tags are parsed attribute by
+        #   attribute.
+        def demo_uploads(html)
+          section = html[/class="[^"]*\bfor_demo\b.*?(?=<section\b|\z)/m].to_s
+          section.split(/(?=<div\b[^>]*\bclass="upload")/).filter_map do |upload|
+            id = upload.scan(/<a\b[^>]*>/).filter_map { |tag| attributes(tag)["data-upload_id"] }.first
+            title = upload.scan(/<strong\b[^>]*>/).filter_map { |tag| attributes(tag)["title"] }.first
+            [CGI.unescapeHTML(title), id] if id && title
+          end.to_h
+        end
+
+        # @return [Hash{String => String}]
+        def attributes(tag)
+          tag.scan(/([\w-]+)="([^"]*)"/).to_h
+        end
+      end
+
+      # Standard, from itch.io with butler (after `butler login`).
+      class Butler
+        GAME = "dragonruby/dragonruby-gtk"
+
+        # @param platform [String] also the itch.io channel name
+        # @param downloads_dir [String] where butler's directory is created
+        # @param butler [String] the butler executable
+        def initialize(platform: Engine.host_platform, downloads_dir: Paths.new.downloads_dir, butler: "butler")
+          @platform = platform
+          @downloads_dir = downloads_dir
+          @butler = butler
+        end
+
+        # @return [String]
+        def tier
+          "standard"
+        end
+
+        # @return [Boolean]
+        def credentials?
+          false
+        end
+
+        # @return [String] a directory containing the engine
+        # @raise [Error] if butler is missing or the fetch fails
+        def fetch(credentials: nil)
+          FileUtils.mkdir_p(@downloads_dir)
+          dir = Dir.mktmpdir("butler-", @downloads_dir)
+          _out, err, status = Open3.capture3(@butler, "fetch", "#{GAME}:#{@platform}", dir)
+          return dir if status.success?
+
+          FileUtils.rm_rf(dir)
+          raise Error, "butler fetch failed: #{err.strip}. If you haven't yet, run `butler login`."
+        rescue Errno::ENOENT
+          FileUtils.rm_rf(dir) if dir
+          raise Error, "Standard engines download with itch.io's butler, which isn't installed. " \
+            "See https://itch.io/docs/butler/installing.html, then run `butler login`. " \
+            "The free Jam license needs neither: `talon engine fetch --tier jam`."
+        end
+      end
+    end
+  end
+end

data/lib/dr_talon/engine/git_ignore.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module DrTalon
+  module Engine
+    # Maintains a marked block in a project's +.gitignore+ that ignores the
+    # installed engine, for projects that restore it with +talon engine use+
+    # instead of committing it. The block is regenerated on every install so
+    # it follows engines that add or drop files.
+    module GitIgnore
+      BEGIN_MARKER = "# >>> talon: DragonRuby engine, restored by `talon engine use` from .dragonruby-version"
+      END_MARKER = "# <<< talon"
+      BLOCK = /^#{Regexp.escape(BEGIN_MARKER)}\n.*?^#{Regexp.escape(END_MARKER)}\n?/m
+
+      module_function
+
+      # @param files [Array<String>] project-relative engine files
+      # @return [Array<String>] gitignore patterns, top-level entries only
+      def patterns(files)
+        tops = files.map do |relative|
+          top, rest = relative.split("/", 2)
+          rest ? "/#{top}/" : "/#{top}"
+        end
+        ["/.talon/", *tops.uniq.sort]
+      end
+
+      # @param path [String] the .gitignore
+      # @return [Boolean]
+      def block?(path)
+        File.file?(path) && File.foreach(path).any? { |line| line.chomp == BEGIN_MARKER }
+      end
+
+      # Replaces the block, or appends it if there isn't one.
+      #
+      # @param path [String] the .gitignore
+      # @param files [Array<String>]
+      # @return [void]
+      def write(path, files)
+        block = [BEGIN_MARKER, *patterns(files), END_MARKER].join("\n") + "\n"
+        content = File.file?(path) ? File.read(path) : ""
+
+        content =
+          if content.match?(BLOCK)
+            content.sub(BLOCK) { block }
+          else
+            [content.empty? ? nil : content.chomp, block].compact.join("\n\n")
+          end
+
+        File.write(path, content)
+      end
+
+      # Rewrites the block only if the .gitignore already has one, so projects
+      # that commit their engine are left alone.
+      #
+      # @return [Boolean] whether it was rewritten
+      def refresh(path, files)
+        return false unless block?(path)
+
+        write(path, files)
+        true
+      end
+    end
+  end
+end

data/lib/dr_talon/engine/importer.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "time"
+require "zip"
+
+module DrTalon
+  module Engine
+    # Adds a DragonRuby distribution to the {Store}, from either the zip as
+    # downloaded or a directory it was already extracted to.
+    class Importer
+      # @!attribute [r] installation
+      #   @return [Installation]
+      # @!attribute [r] status
+      #   @return [Symbol] +:installed+, +:replaced+ or +:unchanged+ (the same
+      #     zip was already imported)
+      Result = Data.define(:installation, :status)
+
+      # @param store [Store]
+      # @param tier [String, nil] overrides tier detection
+      # @param platform [String, nil] overrides platform detection
+      # @param force [Boolean] replace an already cached engine with the same id
+      def initialize(store, tier: nil, platform: nil, force: false)
+        @store = store
+        @tier = tier
+        @platform = platform
+        @force = force
+      end
+
+      # @param source [String] path to a .zip or an extracted engine directory
+      # @return [Result]
+      # @raise [Error] if the source is missing or isn't a DragonRuby engine
+      # @raise [AlreadyInstalled] if the id is taken and +force+ is off
+      def import(source)
+        source = File.expand_path(source)
+
+        @store.stage do |staging|
+          root, hints, sha256 =
+            if File.directory?(source)
+              copy_directory(source, staging)
+            elsif File.file?(source)
+              extract_zip(source, staging)
+            else
+              raise Error, "#{source} does not exist."
+            end
+
+          details = Inspector.new(root, hints: hints, tier: @tier, platform: @platform).details
+          installation = Installation.new(
+            **details,
+            path: @store.path_for("#{details[:version]}-#{details[:tier]}-#{details[:platform]}"),
+            sha256: sha256,
+            source: File.basename(source),
+            imported_at: Time.now.utc.iso8601
+          )
+
+          install(installation, root)
+        end
+      end
+
+      private
+
+      def copy_directory(source, staging)
+        root = Inspector.find_root(source)
+        FileUtils.cp_r(root, staging, preserve: true)
+
+        hints = [File.basename(source), File.basename(File.dirname(root))]
+        [File.join(staging, File.basename(root)), hints, nil]
+      end
+
+      def extract_zip(source, staging)
+        Zip::File.open(source, restore_permissions: true) { |zip| zip.extract_all(staging) }
+
+        [Inspector.find_root(staging), [File.basename(source, ".*")], Digest::SHA256.file(source).hexdigest]
+      rescue Zip::Error => e
+        raise Error, "Can't read #{source} as a zip: #{e.message}"
+      end
+
+      def install(installation, root)
+        status = :installed
+
+        if (existing = @store.get(installation.id))
+          if !@force && existing.sha256 && existing.sha256 == installation.sha256
+            return Result.new(installation: existing, status: :unchanged)
+          end
+
+          unless @force
+            raise AlreadyInstalled, "#{installation.id} is already cached (imported from #{existing.source}). " \
+              "Pass --force to replace it."
+          end
+
+          @store.remove(existing)
+          status = :replaced
+        end
+
+        installation.write_metadata(root)
+        File.rename(root, installation.path)
+
+        Result.new(installation: installation, status: status)
+      end
+    end
+  end
+end

data/lib/dr_talon/engine/inspector.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module DrTalon
+  module Engine
+    # Reads identifying details out of an unpacked DragonRuby distribution.
+    #
+    # - version: the first "* X.Y" heading in +CHANGELOG-CURR.txt+
+    #   (+VERSION.txt+ only has the build date and git sha)
+    # - platform: from the root directory name, +dragonruby-<platform>+
+    # - tier: from names such as the zip's, +dragonruby-pro-linux-amd64.zip+;
+    #   the engine files themselves don't say
+    class Inspector
+      CHANGELOG = "CHANGELOG-CURR.txt"
+      VERSION_FILE = "VERSION.txt"
+      BINARIES = %w[dragonruby dragonruby.exe].freeze
+
+      # Finds the engine root at +dir+ or directly inside it, which covers both
+      # an extracted zip (+dragonruby-pro-linux-amd64/dragonruby-linux-amd64/+)
+      # and the engine directory itself.
+      #
+      # @param dir [String]
+      # @return [String]
+      # @raise [InvalidEngine] if there isn't exactly one engine root
+      def self.find_root(dir)
+        return dir if engine_root?(dir)
+
+        candidates = Dir.children(dir).map { |child| File.join(dir, child) }.select { |path| engine_root?(path) }
+        return candidates.first if candidates.one?
+
+        if candidates.empty?
+          raise InvalidEngine, "#{dir} doesn't look like a DragonRuby engine " \
+            "(no directory with #{CHANGELOG} and a dragonruby binary)."
+        end
+
+        raise InvalidEngine, "#{dir} contains more than one DragonRuby engine: " \
+          "#{candidates.map { |path| File.basename(path) }.join(", ")}"
+      end
+
+      # @param dir [String]
+      # @return [Boolean]
+      def self.engine_root?(dir)
+        File.directory?(dir) &&
+          File.file?(File.join(dir, CHANGELOG)) &&
+          BINARIES.any? { |binary| File.file?(File.join(dir, binary)) }
+      end
+
+      # @param root [String] the engine root, see {.find_root}
+      # @param hints [Array<String>] names to look for a tier in, such as the
+      #   zip's basename
+      # @param tier [String, nil] overrides tier detection
+      # @param platform [String, nil] overrides platform detection
+      def initialize(root, hints: [], tier: nil, platform: nil)
+        @root = root
+        @hints = hints
+        @tier = tier
+        @platform = platform
+      end
+
+      # @return [Hash{Symbol => String, nil}] +version+, +tier+, +platform+,
+      #   +build_date+ and +git_sha+
+      # @raise [InvalidEngine] if a required detail can't be determined
+      def details
+        {version: version, tier: tier, platform: platform, **build_info}
+      end
+
+      private
+
+      def version
+        File.foreach(File.join(@root, CHANGELOG)) do |line|
+          match = /\A\* (\d+(?:\.\d+)+)\s*\z/.match(line)
+          return match[1] if match
+        end
+
+        raise InvalidEngine, "Can't find a version heading (e.g. \"* 7.23\") in #{CHANGELOG}."
+      end
+
+      def tier
+        return validate_tier(@tier) if @tier
+
+        names = [*@hints, File.basename(@root)]
+        found = names.filter_map { |name| /(?:\A|[-_])(#{TIERS.join("|")})(?=[-_.]|\z)/.match(name)&.[](1) }.uniq
+        return found.first if found.one?
+
+        raise InvalidEngine, "Can't tell the license tier from #{names.uniq.join(", ")}. " \
+          "Pass --tier #{TIERS.join("|")}."
+      end
+
+      def platform
+        return @platform if @platform
+
+        match = /\Adragonruby-([a-z0-9-]+)\z/.match(File.basename(@root))
+        return match[1] if match
+
+        raise InvalidEngine, "Can't tell the platform from #{File.basename(@root)}. " \
+          "Pass --platform, e.g. --platform #{Engine.host_platform}."
+      end
+
+      def validate_tier(tier)
+        return tier if TIERS.include?(tier)
+
+        raise InvalidEngine, "Unknown tier \"#{tier}\". Expected one of #{TIERS.join(", ")}."
+      end
+
+      def build_info
+        path = File.join(@root, VERSION_FILE)
+        lines = File.file?(path) ? File.readlines(path, chomp: true) : []
+        fields = lines.filter_map { |line| line.split(": ", 2) if line.include?(": ") }.to_h
+
+        {build_date: fields["date"], git_sha: fields["git"]}
+      end
+    end
+  end
+end

data/lib/dr_talon/engine/installation.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "time"
+require "yaml"
+
+module DrTalon
+  module Engine
+    Installation = Data.define(
+      :version, :tier, :platform, :path, :build_date, :git_sha, :sha256, :source, :imported_at
+    )
+
+    # An engine unpacked in the {Store}. Its details are recorded in a
+    # +.talon-engine.yml+ file at the engine root.
+    #
+    # @!attribute [r] version
+    #   @return [String] release number from +CHANGELOG-CURR.txt+, e.g. "7.23"
+    # @!attribute [r] tier
+    #   @return [String] one of {TIERS}
+    # @!attribute [r] platform
+    #   @return [String] e.g. "linux-amd64", "macos", "windows-amd64"
+    # @!attribute [r] path
+    #   @return [String] the engine root directory
+    # @!attribute [r] build_date
+    #   @return [String, nil] +date:+ from +VERSION.txt+
+    # @!attribute [r] git_sha
+    #   @return [String, nil] +git:+ from +VERSION.txt+
+    # @!attribute [r] sha256
+    #   @return [String, nil] digest of the imported zip; nil for directories
+    # @!attribute [r] source
+    #   @return [String, nil] basename of what was imported
+    # @!attribute [r] imported_at
+    #   @return [String, nil] ISO 8601 UTC timestamp
+    class Installation
+      METADATA_FILE = ".talon-engine.yml"
+      RECORDED = %i[version tier platform build_date git_sha sha256 source imported_at].freeze
+
+      # @param path [String] an engine root containing {METADATA_FILE}
+      # @return [Installation]
+      # @raise [InvalidEngine] if the metadata is missing or unreadable
+      def self.load(path)
+        file = File.join(path, METADATA_FILE)
+        data = YAML.safe_load_file(file)
+        raise InvalidEngine, "#{file} is not a mapping" unless data.is_a?(Hash)
+
+        new(**RECORDED.to_h { |key| [key, data[key.to_s]] }, path: path)
+      rescue Errno::ENOENT, Psych::SyntaxError => e
+        raise InvalidEngine, "Can't read engine metadata at #{file}: #{e.message}"
+      end
+
+      # @return [String] e.g. "7.23-pro-linux-amd64"
+      def id
+        "#{version}-#{tier}-#{platform}"
+      end
+
+      # @return [Gem::Version]
+      def gem_version
+        Gem::Version.new(version)
+      end
+
+      # @return [String, nil] the build date as YYYY-MM-DD when it parses
+      def built_on
+        build_date && Time.parse(build_date).strftime("%Y-%m-%d")
+      rescue ArgumentError
+        build_date
+      end
+
+      # Writes {METADATA_FILE} into +dir+ (defaults to {#path}).
+      #
+      # @param dir [String]
+      # @return [void]
+      def write_metadata(dir = path)
+        data = RECORDED.to_h { |key| [key.to_s, public_send(key)] }
+        File.write(File.join(dir, METADATA_FILE), YAML.dump(data))
+      end
+    end
+  end
+end