skill 0.1.0

data/lib/skill/commands/update.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Skill
+  module Commands
+    # skill update [names]: fetches each skill's source again at the ref it
+    # was installed from. A commit never moves. A tag is fetched again and a
+    # tag that moved is called out. A branch moves forward. Nothing changes
+    # before the changes are shown and confirmed, with a prompt on a
+    # terminal or +--yes+ elsewhere.
+    class Update < Command
+      # One skill's update: the lockfile entry it will have, the copy to
+      # install, and the files that change.
+      Change = Struct.new(:name, :entry, :copy, :diff, :from, :to, :source, keyword_init: true)
+
+      NO_DIFF = Tree::Diff.new(added: [].freeze, changed: [].freeze, removed: [].freeze).freeze
+
+      def run
+        names = parse('update [names] [options]') { |opts| define(opts) }
+        lock = workspace.lock
+        names = lock.names if names.empty?
+        unknown = names - lock.names
+        raise NotFoundError, "Not installed: #{unknown.join(', ')}. Run `skill list`" if unknown.any?
+        return say('No skills installed.') if names.empty?
+
+        changes = names.group_by { |name| lock[name].values_at('source', 'ref', 'ref_type') }.flat_map do |key, group|
+          plan(*key, group)
+        end
+        apply(changes)
+      end
+
+      private
+
+      def define(opts)
+        opts.on('-n', '--dry-run', 'Show what would change, without changing anything') { options[:dry_run] = true }
+        opts.on('-y', '--yes', 'Apply the changes without asking') { options[:yes] = true }
+        opts.on('-f', '--force', 'Replace skills that were edited since they were installed') do
+          options[:force] = true
+        end
+      end
+
+      # Returns the Changes for the skills +names+, which share a source and
+      # a ref, fetching the source only when its ref moved.
+      def plan(source_label, ref, ref_type, names)
+        lock = workspace.lock
+        return pinned(names) if ref_type == 'commit'
+
+        source = Source.parse(source_label, root: workspace.root, ref: ref)
+        resolution = session.fetcher.resolve(source) if source.github?
+        if resolution && names.all? { |name| lock[name]['commit'] == resolution.commit }
+          at = style.dim("(#{resolution.label} at #{resolution.commit[0, 12]})")
+          names.each { |name| say done("#{style.bold(name)} up to date #{at}") }
+          return []
+        end
+
+        checkout = session.fetcher.checkout(source, resolution: resolution)
+        warn_moved_tag(names, checkout) if ref_type == 'tag'
+        names.filter_map { |name| change(checkout, name) }
+      end
+
+      def pinned(names)
+        names.each do |name|
+          commit = workspace.lock[name]['commit'][0, 12]
+          say "#{style.dim('·')} #{style.bold(name)} pinned #{style.dim("to #{commit}, skipped")}"
+        end
+        []
+      end
+
+      def warn_moved_tag(names, checkout)
+        before = workspace.lock[names.first]['commit']
+        return if before == checkout.commit
+
+        warn("#{names.join(', ')}: the tag #{checkout.resolution.label} moved from #{before.to_s[0, 12]} " \
+             "to #{checkout.commit[0, 12]}")
+      end
+
+      def change(checkout, name)
+        entry = workspace.lock[name]
+        candidate = find(checkout, name, entry)
+        return unless candidate
+
+        tree = Tree.read(candidate.path, limits: session.limits)
+        folders = workspace.folders(entry)
+        folders.each { |folder| workspace.ensure_unedited(name, folder, options[:force]) }
+        updated = updated_entry(entry, checkout, tree)
+        Change.new(name: name, entry: updated, diff: diff(name, folders, tree, updated), from: entry['commit'],
+                   to: checkout.commit, source: checkout.source,
+                   copy: Installer::Copy.new(name: name, tree: tree, targets: folders, entry: updated,
+                                             executable: updated['executable'] ? true : false))
+      end
+
+      def find(checkout, name, entry)
+        candidate = Discovery.new(checkout.root, subpath: entry['path']).candidates
+                             .find { |each| each.relative == entry['path'] }
+        if candidate&.valid? && candidate.name == name
+          return candidate unless checkout.link_inside?(candidate.relative)
+
+          raise UnsafeError, "#{candidate.relative} holds a symbolic link; skills may not hold links"
+        end
+
+        reason = candidate ? candidate.error || "it is now named #{candidate.name}" : "#{entry['path']} is gone"
+        warn("#{name}: cannot update, #{reason}. Run `skill add` again to choose what to install")
+        nil
+      end
+
+      def updated_entry(entry, checkout, tree)
+        entry.merge('commit' => checkout.commit,
+                    'ref_type' => checkout.resolution ? checkout.resolution.type.to_s : 'local',
+                    'digest' => tree.digest(executable: entry['executable'] ? true : false))
+      end
+
+      # Returns what changes from the first installed copy that differs
+      # from +tree+, or nothing when every copy already matches it.
+      def diff(name, folders, tree, entry)
+        executable = entry['executable'] ? true : false
+        folders.each do |folder|
+          path = Installer.destination(folder, name)
+          return tree.diff_from(nil) unless File.directory?(path)
+
+          installed = Tree.read(path, limits: session.limits)
+          unless installed.digest(executable: executable) == entry['digest']
+            return tree.diff_from(installed,
+                                  executable: executable)
+          end
+        end
+        NO_DIFF
+      end
+
+      def apply(changes)
+        return 0 if changes.empty?
+
+        changes.each { |change| show(change) }
+        return 0 if options[:dry_run]
+
+        changed = changes.reject { |change| change.diff.empty? }
+        return refuse if changed.any? && !confirmed?(changed.size)
+
+        Installer.new.install(changed.map(&:copy))
+        changes.each { |change| workspace.lock[change.name] = change.entry }
+        workspace.lock.save
+        say done("Updated #{changes.map { |change| style.bold(change.name) }.join(', ')}")
+      end
+
+      def confirmed?(count)
+        options[:yes] || session.confirm?(count == 1 ? 'Apply this update?' : "Apply these #{count} updates?")
+      end
+
+      def refuse
+        session.error('Nothing changed. Run `skill update --yes` to apply.')
+        1
+      end
+
+      def show(change)
+        range = [change.from, change.to].compact.map { |sha| sha[0, 12] }.join('..')
+        say "#{style.bold(change.name)}: #{change.source}#{style.dim(" #{range}") unless range.empty?}"
+        say style.dim("  #{compare_url(change)}") if compare_url(change)
+        return say(style.dim('  no file changes')) if change.diff.empty?
+
+        show_files(change.diff)
+      end
+
+      def show_files(diff)
+        { added: style.green('+'), changed: style.yellow('~'), removed: style.red('-') }.each do |kind, mark|
+          diff.public_send(kind).each { |path| say "  #{mark} #{path}" }
+        end
+      end
+
+      def compare_url(change)
+        source = change.source
+        return unless source.github? && change.from && change.to && change.from != change.to
+
+        GitHub.compare_url(source.owner, source.repo, change.from, change.to)
+      end
+    end
+  end
+end

data/lib/skill/commands.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Skill
+  # The subcommands of the command line, one class each.
+  module Commands
+    autoload :Add, 'skill/commands/add'
+    autoload :Agents, 'skill/commands/agents'
+    autoload :Command, 'skill/commands/command'
+    autoload :Find, 'skill/commands/find'
+    autoload :List, 'skill/commands/list'
+    autoload :Remove, 'skill/commands/remove'
+    autoload :Selection, 'skill/commands/selection'
+    autoload :Update, 'skill/commands/update'
+  end
+end

data/lib/skill/directory.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module Skill
+  # Searches skills.sh, the directory of Agent Skills vercel-labs/skills
+  # reads, through the same public search endpoint its CLI uses.
+  # +SKILLS_API_URL+ points it at another server with that endpoint.
+  class Directory
+    Result = Struct.new(:name, :source, :installs, keyword_init: true) do
+      # Returns the command that installs this skill.
+      def command
+        "skill add #{source}@#{name}"
+      end
+    end
+
+    DEFAULT_URL = 'https://skills.sh'
+    MAX_BYTES = 4 * 1024 * 1024
+    CONTROL = /[\u0000-\u001f\u007f-\u009f​-‏‪-‮⁦-⁩]/
+
+    def initialize(http: HTTP.new, env: ENV)
+      @http = http
+      @base = env['SKILLS_API_URL'].to_s.strip.empty? ? DEFAULT_URL : env['SKILLS_API_URL'].strip.chomp('/')
+    end
+
+    # Returns up to +limit+ Results for +query+, most installed first,
+    # optionally only from repositories of +owner+.
+    def search(query, owner: nil, limit: 20)
+      params = { 'q' => query, 'limit' => limit.to_s }
+      params['owner'] = owner if owner
+      url = "#{@base}/api/search?#{URI.encode_www_form(params)}"
+      response = @http.get(url, limit: MAX_BYTES, headers: { 'Accept' => 'application/json' })
+      raise NetworkError, "#{URI(@base).host} answered #{response.status} to the search" unless response.status == 200
+
+      results(JSON.parse(response.body.force_encoding(Encoding::UTF_8)))
+    rescue JSON::ParserError
+      raise NetworkError, "#{URI(@base).host} sent a search result that is not JSON"
+    end
+
+    private
+
+    def results(data)
+      skills = data.is_a?(Hash) && data['skills'].is_a?(Array) ? data['skills'] : []
+      results = skills.grep(Hash).filter_map do |skill|
+        name = clean(skill['skillId'] || skill['name'])
+        source = clean(skill['source'])
+        next unless Manifest.valid_name?(name) && source.match?(%r{\A[\w.-]+/[\w.-]+(?:/[\w./-]+)?\z})
+
+        Result.new(name: name, source: source, installs: skill['installs'].to_i)
+      end
+      results.sort_by { |result| -result.installs }
+    end
+
+    def clean(value)
+      value.to_s.scrub.gsub(CONTROL, '').strip
+    end
+  end
+end

data/lib/skill/discovery.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Skill
+  # Finds the skills in a repository or folder, where vercel-labs/skills
+  # looks for them: a +SKILL.md+ at the top, the conventional skill
+  # folders (+skills/+, the agents' own folders) up to three levels deep,
+  # the plugins of a Claude Code, Codex, or Cursor marketplace file, and,
+  # when those hold nothing, the whole tree.
+  class Discovery
+    # A folder holding a +SKILL.md+. +manifest+ is +nil+ and +error+ says
+    # why when the +SKILL.md+ is invalid.
+    Candidate = Struct.new(:path, :relative, :manifest, :error, :plugin, keyword_init: true) do
+      def valid?
+        !manifest.nil?
+      end
+
+      def name
+        manifest ? manifest.name : File.basename(relative)
+      end
+    end
+
+    CONTAINERS = %w[skills skills/.curated skills/.experimental skills/.system].freeze
+    MARKETPLACES = %w[.claude-plugin/marketplace.json .agents/plugins/marketplace.json
+                      .cursor-plugin/marketplace.json].freeze
+    PLUGINS = %w[.claude-plugin/plugin.json .codex-plugin/plugin.json .cursor-plugin/plugin.json].freeze
+    SKIPPED = %w[.git node_modules vendor/bundle].freeze
+    CONTAINER_DEPTH = 3
+    FULL_DEPTH = 8
+
+    # External plugins a marketplace lists in other repositories, which
+    # need a +skill add+ of their own.
+    attr_reader :external, :warnings
+
+    def initialize(root, subpath: '', full_depth: false)
+      @root = File.realpath(root.to_s)
+      @base = inside!(File.join(@root, Source.clean_path(subpath)))
+      @full_depth = full_depth
+      @found = {}
+      @external = []
+      @warnings = []
+    end
+
+    # Returns every Candidate, ordered by name.
+    def candidates
+      @candidates ||= begin
+        search
+        @found.values.sort_by { |candidate| [candidate.name, candidate.relative] }
+      end
+    end
+
+    private
+
+    def search
+      raise NotFoundError, "#{relative(@base)} is not a folder" unless File.directory?(@base) && !File.symlink?(@base)
+      return add(@base) if skill?(@base)
+
+      plugins
+      (CONTAINERS + Agents.all.map(&:project_dir)).uniq.each do |container|
+        walk(File.join(@base, container), CONTAINER_DEPTH)
+      end
+      walk(@base, FULL_DEPTH) if @found.empty? || @full_depth
+    end
+
+    def walk(dir, depth, plugin: nil)
+      return unless File.directory?(dir) && !File.symlink?(dir)
+      return add(dir, plugin: plugin) if skill?(dir)
+      return if depth.zero?
+
+      Dir.children(dir).sort.each do |child|
+        next if SKIPPED.include?(child) || SKIPPED.include?(relative(File.join(dir, child)))
+
+        walk(File.join(dir, child), depth - 1, plugin: plugin)
+      end
+    end
+
+    def skill?(dir)
+      file = File.join(dir, Manifest::FILE)
+      File.file?(file) && !File.symlink?(file)
+    end
+
+    def add(dir, plugin: nil)
+      key = relative(dir)
+      return if @found.key?(key)
+
+      manifest = Manifest.load(dir)
+      if (other = @found.values.find { |candidate| candidate.valid? && candidate.name == manifest.name })
+        @warnings << "Two skills are named #{manifest.name}: #{other.relative} and #{key}. Using #{other.relative}"
+        return
+      end
+      @found[key] = Candidate.new(path: dir, relative: key, manifest: manifest, plugin: plugin)
+    rescue InvalidSkillError => e
+      @found[key] = Candidate.new(path: dir, relative: key, error: e.message.delete_prefix("#{@root}/"), plugin: plugin)
+    end
+
+    def plugins
+      MARKETPLACES.each { |file| marketplace(File.join(@base, file)) }
+      PLUGINS.each do |file|
+        data = json(File.join(@base, file))
+        plugin_skills(@base, data['skills'], data['name']) if data
+      end
+    end
+
+    def marketplace(file)
+      data = json(file)
+      return unless data && data['plugins'].is_a?(Array)
+
+      root = data.dig('metadata', 'pluginRoot').to_s
+      data['plugins'].grep(Hash).each { |entry| marketplace_plugin(entry, root) }
+    end
+
+    def marketplace_plugin(entry, plugin_root)
+      name = entry['name'].to_s
+      source = entry['source']
+      source = source['path'] if source.is_a?(Hash) && [nil, 'local'].include?(source['source'])
+      unless source.nil? || source.is_a?(String)
+        @external << { 'plugin' => name, 'source' => external_source(source) }
+        return
+      end
+
+      path = source.to_s
+      path = File.join(plugin_root, path) unless plugin_root.empty? || path.start_with?('./', '../')
+      plugin_skills(File.join(@base, Source.clean_path(path)), entry['skills'], name)
+    rescue UnsafeError
+      @warnings << "The #{name} plugin points outside the repository; skipped"
+    end
+
+    def plugin_skills(plugin_dir, skills, name)
+      plugin_dir = inside!(plugin_dir)
+      paths = skills.is_a?(Array) ? skills.grep(String) : []
+      return walk(File.join(plugin_dir, 'skills'), CONTAINER_DEPTH, plugin: name) if paths.empty?
+
+      paths.each { |path| walk(inside!(File.join(plugin_dir, Source.clean_path(path))), 1, plugin: name) }
+    rescue UnsafeError
+      @warnings << "The #{name} plugin points outside the repository; skipped"
+    end
+
+    def external_source(source)
+      repo = source['repo'] || source['url'].to_s[%r{github\.com[/:]([\w.-]+/[\w.-]+?)(?:\.git)?/?\z}, 1]
+      repo ? [repo, source['path']].compact.join('/') : source['url'] || source['source']
+    end
+
+    def json(file)
+      return unless File.file?(file) && !File.symlink?(file)
+
+      data = JSON.parse(File.read(file, encoding: 'UTF-8').delete_prefix("\u{FEFF}"))
+      data.is_a?(Hash) ? data : nil
+    rescue JSON::ParserError
+      @warnings << "#{relative(file)} is not valid JSON; skipped"
+      nil
+    end
+
+    def inside!(path)
+      expanded = File.expand_path(path)
+      expanded = File.realpath(expanded) if File.exist?(expanded)
+      return expanded if expanded == @root || expanded.start_with?("#{@root}/")
+
+      raise UnsafeError, "#{path} leaves #{@root}"
+    end
+
+    def relative(path)
+      path == @root ? '.' : path.delete_prefix("#{@root}/")
+    end
+  end
+end

data/lib/skill/fetcher.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+
+module Skill
+  # Gives a Source's files as a folder: a local directory in place, or a
+  # GitHub commit downloaded and extracted into a temporary folder.
+  class Fetcher
+    # +root+ is the folder, +resolution+ a GitHub::Resolution (or +nil+ for a
+    # local directory), and +links+ the archive paths that were links.
+    Checkout = Struct.new(:source, :root, :resolution, :links, keyword_init: true) do
+      def commit
+        resolution&.commit
+      end
+
+      # Returns whether the archive held a link inside the folder +relative+.
+      def link_inside?(relative)
+        prefix = relative == '.' ? '' : "#{relative}/"
+        links.any? { |link| link == relative || link.start_with?(prefix) }
+      end
+    end
+
+    # Downloads go into folders under +workdir+, which the caller deletes.
+    def initialize(github:, limits:, workdir:)
+      @github = github
+      @limits = limits
+      @workdir = workdir
+    end
+
+    # Resolves +source+'s ref.
+    def resolve(source)
+      @github.resolve(source.owner, source.repo, source.ref)
+    end
+
+    # Returns a Checkout of +source+ at +resolution+ (resolved when +nil+).
+    def checkout(source, resolution: nil)
+      return local(source) if source.local?
+
+      resolution ||= resolve(source)
+      directory = Dir.mktmpdir('checkout-', @workdir)
+      archive = File.join(directory, 'source.tar.gz')
+      File.open(archive, 'wb') { |io| @github.download(source.owner, source.repo, resolution.commit, io) }
+      root = File.join(directory, 'source')
+      Dir.mkdir(root)
+      result = Archive.new(limits: @limits).extract(archive, root)
+      File.delete(archive)
+      if result.commit && result.commit != resolution.commit
+        raise NetworkError, "GitHub sent commit #{result.commit[0, 12]} for #{resolution.commit[0, 12]}"
+      end
+
+      Checkout.new(source: source, root: root, resolution: resolution, links: result.links)
+    end
+
+    private
+
+    def local(source)
+      raise NotFoundError, "No folder at #{source.path}" unless File.directory?(source.path)
+
+      Checkout.new(source: source, root: File.realpath(source.path), resolution: nil, links: [])
+    end
+  end
+end

data/lib/skill/github.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Skill
+  # Reads GitHub repositories without the API and without git: refs come
+  # from git's smart HTTP advertisement, files from one tarball of a commit.
+  # Neither counts against the API's rate limit. +GITHUB_TOKEN+ or
+  # +GH_TOKEN+, when set, opens private repositories.
+  class GitHub
+    # A ref resolved to a commit. +type+ is +:branch+, +:tag+, or +:commit+;
+    # +name+ is +nil+ for the repository's default branch.
+    Resolution = Struct.new(:type, :name, :commit, :branch, keyword_init: true) do
+      def pinned?
+        type == :commit
+      end
+
+      # Returns the ref as people read it: the tag, the branch, or the
+      # default branch's name.
+      def label
+        name || branch || 'HEAD'
+      end
+    end
+
+    SHA = /\A\h{40}\z/
+    MAX_REFS_BYTES = 32 * 1024 * 1024
+
+    def initialize(http: HTTP.new, env: ENV, limits: Limits.new(env))
+      @http = http
+      @token = [env['GITHUB_TOKEN'], env['GH_TOKEN']].map(&:to_s).find { |value| !value.strip.empty? }&.strip
+      @limits = limits
+    end
+
+    # Resolves +ref+ (a branch, a tag, a full commit SHA, or +nil+ for the
+    # default branch) in +owner/repo+. A tag wins over a branch of the same
+    # name, as in git.
+    def resolve(owner, repo, ref)
+      return Resolution.new(type: :commit, name: ref.downcase, commit: ref.downcase) if ref&.match?(SHA)
+
+      refs = advertised_refs(owner, repo)
+      return default_branch(owner, repo, refs) if ref.nil?
+
+      name = ref.delete_prefix('refs/heads/').delete_prefix('refs/tags/')
+      if (commit = refs[:tags][name]) && !ref.start_with?('refs/heads/')
+        Resolution.new(type: :tag, name: name, commit: commit)
+      elsif (commit = refs[:branches][name])
+        Resolution.new(type: :branch, name: name, commit: commit, branch: name)
+      elsif ref.match?(/\A\h{4,39}\z/)
+        raise NotFoundError,
+              "#{ref} is not a branch or tag of #{owner}/#{repo}. Pin commits by their full 40-character SHA"
+      else
+        raise NotFoundError, "#{owner}/#{repo} has no branch or tag named #{ref}"
+      end
+    end
+
+    # Downloads +commit+ of +owner/repo+ as a gzipped tarball into +io+.
+    def download(owner, repo, commit, io)
+      url, headers = archive_request(owner, repo, commit)
+      response = download_archive(url, headers, io, owner, repo)
+      return if response.status == 200
+
+      if [404, 422].include?(response.status)
+        raise NotFoundError, "#{owner}/#{repo} has no commit #{commit}#{private_hint}"
+      end
+
+      raise NetworkError, "GitHub answered #{response.status} for the archive of #{owner}/#{repo}"
+    end
+
+    # Returns a link comparing two commits, for showing what changed.
+    def self.compare_url(owner, repo, from, to)
+      "https://github.com/#{owner}/#{repo}/compare/#{from[0, 12]}...#{to[0, 12]}"
+    end
+
+    private
+
+    def download_archive(url, headers, io, owner, repo)
+      @http.get(url, headers: headers, limit: @limits.download_bytes, io: io)
+    rescue TooLargeError
+      message = "#{owner}/#{repo} is larger than #{@limits.download_bytes} bytes to download"
+      raise TooLargeError, Limits.exceeded(:download_bytes, message)
+    end
+
+    def advertised_refs(owner, repo)
+      response = @http.get("https://github.com/#{owner}/#{repo}.git/info/refs?service=git-upload-pack",
+                           headers: basic_auth, limit: MAX_REFS_BYTES)
+      if [401, 403, 404].include?(response.status)
+        raise NotFoundError, "No GitHub repository #{owner}/#{repo}#{private_hint}"
+      end
+      raise NetworkError, "GitHub answered #{response.status} for #{owner}/#{repo}" unless response.status == 200
+
+      parse_refs(response.body)
+    end
+
+    # Reads git's pkt-line ref advertisement: a service line, a flush, then
+    # one "<sha> <ref>" line per ref, the first carrying capabilities after
+    # a NUL byte. Peeled tags end in ^{}.
+    def parse_refs(body)
+      refs = { head: nil, symref: nil, branches: {}, tags: {} }
+      pkt_lines(body).each do |line|
+        line, capabilities = line.chomp.split("\0", 2)
+        refs[:symref] ||= capabilities.to_s[%r{symref=HEAD:refs/heads/(\S+)}, 1]
+        sha, name = line.split(' ', 2)
+        next unless sha&.match?(SHA) && name
+
+        add_ref(refs, sha, name)
+      end
+      refs
+    end
+
+    def add_ref(refs, sha, name)
+      case name
+      when 'HEAD' then refs[:head] = sha
+      when %r{\Arefs/heads/(.+)\z} then refs[:branches][Regexp.last_match(1)] = sha
+      when %r{\Arefs/tags/(.+)\^\{\}\z} then refs[:tags][Regexp.last_match(1)] = sha
+      when %r{\Arefs/tags/(.+)\z} then refs[:tags][Regexp.last_match(1)] ||= sha
+      end
+    end
+
+    def pkt_lines(body)
+      lines = []
+      position = 0
+      while position + 4 <= body.bytesize
+        length = Integer(body.byteslice(position, 4), 16)
+        position += 4
+        next if length.zero?
+        raise NetworkError, 'GitHub sent a malformed ref list' if length < 4
+
+        lines << body.byteslice(position, length - 4).force_encoding(Encoding::UTF_8).scrub
+        position += length - 4
+      end
+      lines.reject { |line| line.start_with?('# service=') }
+    rescue ArgumentError
+      raise NetworkError, 'GitHub sent a malformed ref list'
+    end
+
+    def default_branch(owner, repo, refs)
+      raise NotFoundError, "#{owner}/#{repo} is empty" unless refs[:head]
+
+      branch = refs[:symref] || refs[:branches].key(refs[:head])
+      Resolution.new(type: :branch, name: nil, commit: refs[:head], branch: branch)
+    end
+
+    def archive_request(owner, repo, commit)
+      return ["https://codeload.github.com/#{owner}/#{repo}/tar.gz/#{commit}", {}] unless @token
+
+      ["https://api.github.com/repos/#{owner}/#{repo}/tarball/#{commit}",
+       { 'Authorization' => "Bearer #{@token}", 'Accept' => 'application/vnd.github+json' }]
+    end
+
+    def basic_auth
+      return {} unless @token
+
+      { 'Authorization' => "Basic #{["x-access-token:#{@token}"].pack('m0')}" }
+    end
+
+    def private_hint
+      @token ? '' : ' (for a private repository, set GITHUB_TOKEN)'
+    end
+  end
+end