skill 0.1.0

data/lib/skill/cli.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Skill
+  # The +skill+ command line.
+  class CLI
+    COMMANDS = {
+      'add' => :Add, 'install' => :Add, 'a' => :Add, 'i' => :Add,
+      'list' => :List, 'ls' => :List,
+      'update' => :Update, 'upgrade' => :Update, 'up' => :Update,
+      'remove' => :Remove, 'rm' => :Remove, 'uninstall' => :Remove,
+      'find' => :Find, 'search' => :Find, 's' => :Find,
+      'agents' => :Agents
+    }.freeze
+
+    USAGE = <<~TEXT
+      Usage: skill <command> [options]
+
+      Commands:
+        add <source>       Install skills from GitHub or a local folder
+        list               List installed skills
+        update [names]     Update installed skills, showing what changes first
+        remove <names>     Remove installed skills
+        find <query>       Search the skills.sh directory
+        agents             List the agents and folders skills install to
+
+      Sources:
+        owner/repo                 a repository (asks which skills when it holds several)
+        owner/repo@pdf             one skill by name
+        owner/repo/skills/pdf      one folder of a repository
+        owner/repo#v1.2.0          a branch, tag, or full commit SHA
+        https://github.com/owner/repo/tree/main/skills/pdf
+        ./path/to/skills           a local folder
+
+      Run `skill <command> --help` for a command's options.
+    TEXT
+
+    def self.start(argv)
+      exit new(argv).run
+    end
+
+    def initialize(argv, out: $stdout, err: $stderr, input: $stdin, env: ENV, cwd: Dir.pwd, home: Dir.home,
+                   http: nil)
+      @argv = argv.dup
+      @session = Session.new(out: out, err: err, input: input, env: env, cwd: cwd, home: home, http: http)
+    end
+
+    # Runs the command and returns its exit status: 0 on success, 1 when it
+    # failed, 2 for a malformed command line.
+    def run
+      name = @argv.shift
+      case name
+      when nil, 'help', '-h', '--help' then help
+      when 'version', '-v', '--version' then version
+      else command(name).run
+      end
+    rescue OptionParser::ParseError, UsageError => e
+      fail_with(e, 2)
+    rescue Error => e
+      fail_with(e, 1)
+    rescue Interrupt
+      130
+    ensure
+      @session.cleanup
+    end
+
+    private
+
+    def command(name)
+      constant = COMMANDS.fetch(name) { raise UsageError, "Unknown command #{name.inspect}. Run `skill help`" }
+      Commands.const_get(constant).new(@session, @argv)
+    end
+
+    def help
+      @session.say USAGE
+      0
+    end
+
+    def version
+      @session.say "skill #{VERSION}"
+      0
+    end
+
+    def fail_with(error, status)
+      @session.error(error.message)
+      status
+    end
+  end
+end

data/lib/skill/commands/add.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Skill
+  module Commands
+    # skill add <source>: installs skills from a repository or folder.
+    class Add < Command
+      def run
+        arguments = parse('add <source> [options]') { |opts| define(opts) }
+        raise UsageError, "Name one source.\n\n#{usage}" unless arguments.size == 1
+
+        source = Source.parse(arguments.first, root: session.cwd, ref: options[:ref])
+        checkout = session.fetcher.checkout(source)
+        discovery = Discovery.new(checkout.root, subpath: source.subpath, full_depth: options[:full_depth])
+        discovery.warnings.each { |warning| warn(warning) }
+        return list(checkout, discovery) if options[:list]
+
+        install(checkout, Selection.new(session, checkout, discovery, options).skills)
+      end
+
+      private
+
+      def define(opts)
+        options.merge!(skills: [], plugins: [])
+        opts.on('-s', '--skill NAME', 'Install this skill (repeatable, comma-separated, * for all)') do |value|
+          options[:skills].concat(split(value))
+        end
+        opts.on('--plugin NAME', 'Install the skills of this marketplace plugin') do |value|
+          options[:plugins].concat(split(value))
+        end
+        opts.on('--all', 'Install every valid skill the source holds') { options[:all] = true }
+        opts.on('-l', '--list', 'List the skills the source holds, without installing') { options[:list] = true }
+        opts.on('--ref REF', 'Branch, tag, or full commit SHA to install from') { |value| options[:ref] = value }
+        opts.on('-x', '--keep-executable', 'Keep executable bits on scripts') { options[:executable] = true }
+        opts.on('-f', '--force', 'Replace skills this command did not install, or that were edited') do
+          options[:force] = true
+        end
+        opts.on('--full-depth', 'Also search the whole repository, beyond the usual folders') do
+          options[:full_depth] = true
+        end
+      end
+
+      def install(checkout, candidates)
+        copies = candidates.map { |candidate| copy(checkout, candidate) }
+        executable = options[:executable] ? true : false
+        warn_executables(copies) unless executable
+        Installer.new.install(copies)
+        copies.each { |copy| workspace.lock[copy.name] = copy.entry }
+        workspace.lock.save
+        report(copies)
+      end
+
+      def report(copies)
+        scope = workspace.global? ? style.dim(' (global)') : ''
+        copies.each { |copy| say done("Installed #{style.bold(copy.name)} → #{copy.labels.join(', ')}#{scope}") }
+        say style.dim("  Recorded in #{workspace.display(workspace.lock.path)}")
+      end
+
+      def copy(checkout, candidate)
+        refuse_links(checkout, candidate)
+        name = candidate.manifest.name
+        tree = Tree.read(candidate.path, limits: session.limits)
+        folders = folders_for(name, checkout, candidate)
+        folders.each { |folder| workspace.ensure_replaceable(name, folder, options[:force]) }
+        Installer::Copy.new(name: name, tree: tree, targets: folders, executable: options[:executable] ? true : false,
+                            entry: entry(checkout, candidate, tree, folders),
+                            labels: folders.map { |folder| workspace.display(File.join(folder, name)) })
+      end
+
+      # Returns the folders to install into: those asked for, plus those an
+      # earlier install from the same source recorded, so they stay alike.
+      def folders_for(name, checkout, candidate)
+        existing = workspace.lock[name]
+        same = existing && existing['source'] == workspace.source_label(checkout.source)
+        if existing && !(same && existing['path'] == candidate.relative) && !options[:force]
+          raise ConflictError,
+                "#{name} is installed from #{Workspace.describe(existing)}. Remove it first, or pass --force"
+        end
+
+        kept = same ? workspace.folders(existing) : []
+        (kept + workspace.resolve(agents: options[:agents], dirs: options[:dirs])).uniq
+      end
+
+      def refuse_links(checkout, candidate)
+        return unless checkout.link_inside?(candidate.relative)
+
+        raise UnsafeError, "#{candidate.relative} holds a symbolic link; skills may not hold links"
+      end
+
+      def entry(checkout, candidate, tree, folders)
+        executable = options[:executable] ? true : false
+        resolution = checkout.resolution
+        {
+          'source' => workspace.source_label(checkout.source),
+          'ref' => resolution&.name,
+          'ref_type' => resolution ? resolution.type.to_s : 'local',
+          'commit' => checkout.commit,
+          'path' => candidate.relative,
+          'plugin' => candidate.plugin,
+          'digest' => tree.digest(executable: executable),
+          'executable' => executable,
+          'targets' => folders.map { |folder| workspace.display(folder) }
+        }
+      end
+
+      def warn_executables(copies)
+        copies.each do |copy|
+          files = copy.tree.executables
+          next if files.empty?
+
+          count = files.size == 1 ? '1 file' : "#{files.size} files"
+          warn("#{copy.name}: dropped the executable bit from #{count} (use --keep-executable)")
+        end
+      end
+
+      def list(checkout, discovery)
+        say "#{checkout.source}#{" at #{checkout.commit[0, 12]}" if checkout.commit}:"
+        say '  (no skills)' if discovery.candidates.empty?
+        discovery.candidates.each do |candidate|
+          plugin = candidate.plugin ? " [#{candidate.plugin}]" : ''
+          detail = if candidate.valid?
+                     style.dim(truncate(candidate.manifest.description))
+                   else
+                     style.yellow("INVALID: #{candidate.error}")
+                   end
+          say "  #{style.bold(candidate.name)}#{style.dim(plugin)}  #{detail}"
+        end
+        discovery.external.each do |plugin|
+          say "  [#{plugin['plugin']}] lives in #{plugin['source']}: run `skill add #{plugin['source']}`"
+        end
+        0
+      end
+
+      def truncate(text, length = 90)
+        line = text.to_s.gsub(/\s+/, ' ')
+        line.length > length ? "#{line[0, length - 1]}…" : line
+      end
+    end
+  end
+end

data/lib/skill/commands/agents.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Skill
+  module Commands
+    # skill agents: the targets skills install to.
+    class Agents < Command
+      def run
+        parse('agents', scope: false)
+        width = Skill::Agents.all.map { |agent| agent.key.length }.max
+        Skill::Agents.all.each do |agent|
+          global = agent.global_dir&.sub(/\A\{(\w+)\}/) { Skill::Agents::HOMES.fetch(Regexp.last_match(1)).last }
+          global ||= '(project only)'
+          say "#{agent.key.ljust(width)}  #{agent.project_dir.ljust(26)}  #{global.ljust(34)}  #{agent.name}"
+        end
+        0
+      end
+    end
+  end
+end

data/lib/skill/commands/command.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Skill
+  module Commands
+    # A subcommand: parses its options, then #run returns the exit status.
+    class Command
+      def initialize(session, argv)
+        @session = session
+        @argv = argv
+        @options = { agents: [], dirs: [] }
+      end
+
+      private
+
+      attr_reader :session, :options
+
+      # Parses the arguments with the options +define+ adds, plus the scope
+      # options (+--global+, +--project+, +--agent+, +--dir+) unless +scope+
+      # is false.
+      # Returns the arguments left.
+      def parse(banner, scope: true, &define)
+        @parser = OptionParser.new do |opts|
+          opts.banner = "Usage: skill #{banner}"
+          scope_options(opts) if scope
+          define&.call(opts)
+        end
+        @parser.parse(@argv)
+      end
+
+      def usage
+        @parser.to_s
+      end
+
+      def scope_options(opts)
+        opts.on('-g', '--global', 'Use the home folder, even inside a project') { options[:global] = true }
+        opts.on('-p', '--project', 'Use the current folder as a project, even outside one') do
+          options[:global] = false
+        end
+        opts.on('-a', '--agent NAME', 'Target this agent (repeatable, comma-separated, * for all)') do |value|
+          options[:agents].concat(split(value))
+        end
+        opts.on('-d', '--dir PATH', 'Target this folder (repeatable)') do |value|
+          options[:dirs] << File.expand_path(value, session.cwd)
+        end
+      end
+
+      def workspace
+        session.workspace(global: options[:global])
+      end
+
+      # Returns the target folders the scope options name, or +nil+ when
+      # they name none.
+      def chosen_folders
+        return if options[:agents].empty? && options[:dirs].empty?
+
+        workspace.resolve(agents: options[:agents], dirs: options[:dirs])
+      end
+
+      def style
+        session.style
+      end
+
+      # Returns "✓ " and +text+, the check green on a terminal.
+      def done(text)
+        "#{style.green('✓')} #{text}"
+      end
+
+      def say(text = '')
+        session.say(text)
+        0
+      end
+
+      def warn(text)
+        session.warn(text)
+      end
+
+      def split(value)
+        value.split(',').map(&:strip).reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/skill/commands/find.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Skill
+  module Commands
+    # skill find <query>: searches the skills.sh directory.
+    class Find < Command
+      def run
+        options[:limit] = 20
+        query = parse('find <query> [options]', scope: false) do |opts|
+          opts.on('--owner OWNER', 'Only skills from this GitHub owner') { |value| options[:owner] = value }
+          opts.on('--limit N', Integer, 'Show at most N results (default 20)') { |value| options[:limit] = value }
+        end.join(' ').strip
+        raise UsageError, "Name what to search for.\n\n#{usage}" if query.empty?
+
+        owner = options[:owner]
+        raise UsageError, "#{owner} is not a GitHub owner" if owner && !owner.match?(Source::OWNER)
+
+        show(query, Directory.new(http: session.http, env: session.env)
+                             .search(query, owner: options[:owner], limit: options[:limit]))
+      end
+
+      private
+
+      def show(query, results)
+        return say("No skills found for #{query.inspect}.") if results.empty?
+
+        rows = results.map { |result| [result.name, result.source, installs(result.installs), result.command] }
+        width, sources, counts = (0..2).map { |column| rows.map { |row| row[column].length }.max }
+        rows.each do |name, source, count, command|
+          line = "#{style.bold(name.ljust(width))}  #{style.dim(source.ljust(sources))}"
+          line += "  #{style.dim(count.rjust(counts))}" unless count.empty?
+          say line.rstrip
+          say "#{' ' * width}  #{style.dim(command)}"
+        end
+        0
+      end
+
+      def installs(count)
+        return '' unless count.positive?
+        return "#{compact(count / 1_000_000.0)}M installs" if count >= 1_000_000
+        return "#{compact(count / 1000.0)}K installs" if count >= 1000
+
+        "#{count} install#{'s' unless count == 1}"
+      end
+
+      def compact(number)
+        number.round(1).to_s.delete_suffix('.0')
+      end
+    end
+  end
+end

data/lib/skill/commands/list.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Skill
+  module Commands
+    # skill list: the skills in the lockfile, whether each is still as
+    # installed, and the skill folders this command did not install.
+    class List < Command
+      def run
+        parse('list [options]') { |opts| opts.on('--json', 'Print JSON') { options[:json] = true } }
+        rows = workspace.lock.skills.map { |name, entry| [name, entry, workspace.status(name, entry)] }
+        if chosen_folders
+          rows.select! { |_name, entry, _status| workspace.recorded_folders(entry).intersect?(chosen_folders) }
+        end
+        return json(rows) if options[:json]
+
+        installed(rows)
+        unmanaged
+        0
+      end
+
+      private
+
+      def installed(rows)
+        return say("No skills installed with skill in #{workspace.display(workspace.root)}.") if rows.empty?
+
+        table = rows.map do |name, entry, state|
+          [name, source(entry), version(entry), entry['targets'].join(', '), state == 'ok' ? '' : state]
+        end
+        widths = (0..3).map { |column| table.map { |row| row[column].length }.max }
+        table.each { |row| say row_line(row, widths) }
+      end
+
+      def row_line(row, widths)
+        name, source, version, targets, state = row.each_with_index.map do |cell, column|
+          column < 4 && column != 3 ? cell.ljust(widths[column]) : cell
+        end
+        line = "#{style.bold(name)}  #{style.dim(source)}  #{style.dim(version)}  #{targets}"
+        line += "  #{style.yellow(state)}" unless state.empty?
+        line
+      end
+
+      def source(entry)
+        entry['ref'] ? "#{entry['source']}##{entry['ref']}" : entry['source']
+      end
+
+      def version(entry)
+        entry['commit'] ? "#{entry['ref_type']} #{entry['commit'][0, 12]}" : entry['ref_type'].to_s
+      end
+
+      def unmanaged
+        managed = workspace.lock.names
+        folders = workspace.targets.existing.flat_map do |target|
+          Dir.children(target.path).sort.filter_map do |child|
+            path = File.join(target.path, child)
+            next if child.start_with?('.') || managed.include?(child) || !File.file?(File.join(path, Manifest::FILE))
+
+            workspace.display(path)
+          end
+        end
+        return if folders.empty?
+
+        say
+        say style.dim('Not installed by skill:')
+        folders.each { |folder| say "  #{folder}" }
+      end
+
+      def json(rows)
+        require 'json'
+        say JSON.pretty_generate(rows.to_h { |name, entry, state| [name, entry.merge('status' => state)] })
+      end
+    end
+  end
+end

data/lib/skill/commands/remove.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Skill
+  module Commands
+    # skill remove <names>: deletes skills this command installed, from
+    # every folder it recorded, or only those +--agent+ and +--dir+ name.
+    class Remove < Command
+      def run
+        names = parse('remove <names> [options]') do |opts|
+          opts.on('--all', 'Remove every installed skill') { options[:all] = true }
+          opts.on('-f', '--force', 'Remove skills that were edited since they were installed') do
+            options[:force] = true
+          end
+        end
+        names = workspace.lock.names if options[:all]
+        raise UsageError, "Name the skills to remove, or pass --all.\n\n#{usage}" if names.empty?
+
+        plan = names.to_h { |name| [name, folders(name)] }
+        plan.each { |name, folders| remove(name, folders) }
+        workspace.lock.save
+        0
+      end
+
+      private
+
+      # Returns the folders to remove +name+ from, after checking each still
+      # holds what was installed.
+      def folders(name)
+        entry = workspace.lock[name]
+        refuse_unknown(name) unless entry
+        recorded = workspace.folders(entry)
+        folders = chosen_folders ? recorded & chosen_folders : recorded
+        folders.each { |folder| workspace.ensure_unedited(name, folder, options[:force]) }
+        folders
+      end
+
+      def refuse_unknown(name)
+        found = workspace.targets.existing.map { |target| Installer.destination(target.path, name) }
+                         .find { |path| File.exist?(path) }
+        raise NotFoundError, "#{name} is not installed" unless found
+
+        raise ConflictError, "#{workspace.display(found)} was not installed by skill. Delete it yourself"
+      end
+
+      def remove(name, folders)
+        entry = workspace.lock[name]
+        Installer.new.remove(name, folders)
+        remaining = entry['targets'].reject { |path| folders.include?(workspace.targets.expand(path)) }
+        if remaining.empty?
+          workspace.lock.delete(name)
+        else
+          workspace.lock[name] = entry.merge('targets' => remaining)
+        end
+        say done("Removed #{style.bold(name)} from " \
+                 "#{folders.map { |folder| workspace.display(File.join(folder, name)) }.join(', ')}")
+      end
+    end
+  end
+end

data/lib/skill/commands/selection.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Skill
+  module Commands
+    # Which of a source's skills +skill add+ installs: the ones named after
+    # +@+ or with +--skill+, a plugin's with +--plugin+, every valid one with
+    # +--all+, or the only one there is. Anything else asks for a choice.
+    class Selection
+      def initialize(session, checkout, discovery, options)
+        @session = session
+        @source = checkout.source
+        @candidates = discovery.candidates
+        @external = discovery.external
+        @names = @source.skills + options[:skills]
+        @plugins = options[:plugins]
+        @all = options[:all] || @names.include?('*')
+      end
+
+      # Returns the chosen Discovery::Candidates. Raises when a named skill
+      # is missing or invalid, or when the choice is unclear.
+      def skills
+        raise NotFoundError, "#{@source} holds no skills#{external_hint}" if @candidates.empty?
+
+        chosen = if @all then every
+                 elsif @names.any? || @plugins.any? then named + plugins
+                 else only
+                 end
+        chosen.uniq(&:relative)
+      end
+
+      private
+
+      def every
+        @candidates.reject(&:valid?).each do |candidate|
+          @session.warn("Skipping #{candidate.relative}: #{candidate.error}")
+        end
+        chosen = @candidates.select(&:valid?).reject { |candidate| hidden?(candidate) }
+        raise InvalidSkillError, "None of the skills in #{@source} is valid" if chosen.empty?
+
+        chosen
+      end
+
+      def named
+        @names.map do |name|
+          candidate = @candidates.find { |each| each.name == name }
+          raise NotFoundError, "No skill named #{name}. Skills: #{@candidates.map(&:name).join(', ')}" unless candidate
+          raise InvalidSkillError, candidate.error unless candidate.valid?
+
+          candidate
+        end
+      end
+
+      def plugins
+        @plugins.flat_map do |name|
+          found = @candidates.select { |candidate| candidate.plugin == name && candidate.valid? }
+          raise NotFoundError, "No plugin named #{name} with valid skills" if found.empty?
+
+          found
+        end
+      end
+
+      def only
+        if @candidates.size == 1
+          raise InvalidSkillError, @candidates.first.error unless @candidates.first.valid?
+
+          return @candidates
+        end
+
+        raise UsageError, <<~TEXT.chomp
+          #{@source} holds #{@candidates.size} skills: #{@candidates.map(&:name).join(', ')}
+          Pick with #{@source.name}@NAME, --skill NAME, --plugin NAME, or --all. See them with --list.
+        TEXT
+      end
+
+      def hidden?(candidate)
+        candidate.manifest.internal? && !@session.internal_skills?
+      end
+
+      def external_hint
+        return '' if @external.empty?
+
+        sources = @external.map { |plugin| plugin['source'] }
+        ". Its marketplace lists plugins from other repositories: #{sources.join(', ')}"
+      end
+    end
+  end
+end