ruby-skills 0.1.0

data/lib/ruby_skills/installer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RubySkills
+  # Installs skills declared in the Skillfile.
+  #
+  # Resolves each skill, copies it into +.ruby-skills+, notifies tool
+  # adapters, and records the result in +Skills.lock+.
+  #
+  # @example Install every declared skill
+  #   RubySkills::Installer.new.install
+  #
+  # @example Install one skill
+  #   RubySkills::Installer.new.install("rails-performance")
+  #
+  # @see RubySkills::Manifest
+  # @see RubySkills::Resolver
+  # @since 0.1.0
+  class Installer
+    # @param config [RubySkills::Config] project paths used during install
+    def initialize(config: Config.new)
+      @config = config
+    end
+
+    # Install one skill or every skill declared in the Skillfile.
+    #
+    # @param skill_name [String, nil] skill to install, or +nil+ to install all
+    # @return [void]
+    # @raise [RubySkills::Error] if the Skillfile is missing or a skill cannot be installed
+    def install(skill_name = nil)
+      load_skills(skill_name).each do |skill|
+        install_skill(skill)
+      end
+    end
+
+    private
+
+    # @api private
+    # @param skill_name [String, nil]
+    # @return [Array<RubySkills::Manifest::Skill>]
+    # @raise [RubySkills::Error] if the named skill is not in the Skillfile
+    def load_skills(skill_name)
+      manifest = Manifest.new.load!
+
+      return manifest.skills if skill_name.nil?
+
+      skill = manifest.skills.find { |declared| declared.name == skill_name }
+      raise RubySkills::Error, "Skill `#{skill_name}` is not in the Skillfile" unless skill
+
+      [skill]
+    end
+
+    # @api private
+    # @param skill [RubySkills::Manifest::Skill]
+    # @return [void]
+    def install_skill(skill)
+      resolved = Resolver.new.resolve(skill)
+      destination = @config.skills_path.join(resolved.name)
+
+      FileUtils.rm_rf(destination)
+      FileUtils.mkdir_p(@config.skills_path)
+      FileUtils.cp_r(resolved.path, destination)
+
+      adapters.each do |adapter|
+        adapter.new.install(resolved.name, destination)
+      end
+
+      Lockfile.new(config: @config).add(
+        resolved.name,
+        version: skill.version || "unspecified",
+        source: resolved.source
+      )
+
+      puts "✓ Installed #{resolved.name}"
+    end
+
+    # @api private
+    # @return [Array<Class>] adapter classes notified when a skill is installed
+    def adapters
+      [
+        Adapters::Claude,
+        Adapters::Codex,
+        Adapters::Cursor,
+        Adapters::Vscode
+      ]
+    end
+  end
+end

data/lib/ruby_skills/lockfile.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RubySkills
+  # Reads and writes the project +Skills.lock+ file.
+  #
+  # The lockfile records installed skill names, versions, and sources so
+  # later installs and removals stay consistent.
+  #
+  # @example List installed skills
+  #   RubySkills::Lockfile.new.skills
+  #
+  # @see RubySkills::Config#lockfile_path
+  # @since 0.1.0
+  class Lockfile
+    # @param config [RubySkills::Config] project paths used to locate Skills.lock
+    def initialize(config: Config.new)
+      @config = config
+    end
+
+    # Installed skills stored in the lockfile.
+    #
+    # @return [Hash{String => Hash}] skill names mapped to +version+ and +source+
+    def skills
+      return {} unless @config.lockfile_path.exist?
+
+      data = YAML.safe_load_file(
+        @config.lockfile_path,
+        permitted_classes: [],
+        aliases: true
+      )
+
+      data.fetch("skills", {})
+    end
+
+    # Record an installed skill in the lockfile.
+    #
+    # @param name [String] skill identifier
+    # @param version [String] installed skill version
+    # @param source [String] origin used to install the skill
+    # @return [void]
+    def add(name, version:, source:)
+      data = load_data
+
+      data["skills"][name] = {
+        "version" => version,
+        "source" => source
+      }
+
+      write(data)
+    end
+
+    # Drop a skill from the lockfile.
+    #
+    # @param name [String] skill identifier to remove
+    # @return [void]
+    def remove(name)
+      data = load_data
+
+      data["skills"].delete(name)
+
+      write(data)
+    end
+
+    private
+
+    # @api private
+    # @return [Hash] lockfile payload with a +version+ header and +skills+ map
+    def load_data
+      {
+        "version" => 1,
+        "skills" => skills
+      }
+    end
+
+    # @api private
+    # @param data [Hash] lockfile payload to persist
+    # @return [void]
+    def write(data)
+      @config.lockfile_path.write(
+        YAML.dump(data)
+      )
+    end
+  end
+end

data/lib/ruby_skills/manifest.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RubySkills
+  # Loads and evaluates a project +Skillfile+.
+  #
+  # The Skillfile is Ruby DSL. Each +skill+ declaration becomes a
+  # {RubySkills::Manifest::Skill} stored in {#skills}.
+  #
+  # @example Load the Skillfile from the current project
+  #   manifest = RubySkills::Manifest.new.load!
+  #   manifest.skills
+  #
+  # @since 0.1.0
+  class Manifest
+    # Declared skill entry loaded from a Skillfile.
+    #
+    # @!attribute [rw] name
+    #   @return [String] skill identifier
+    # @!attribute [rw] github
+    #   @return [String, nil] GitHub repository in +owner/name+ form
+    # @!attribute [rw] path
+    #   @return [String, nil] local filesystem path to the skill
+    # @!attribute [rw] version
+    #   @return [String, nil] optional pinned version
+    Skill = Struct.new(
+      :name,
+      :github,
+      :path,
+      :version,
+      keyword_init: true
+    )
+
+    # @return [Array<Skill>] skills declared in the Skillfile
+    attr_reader :skills
+
+    # @param path [Pathname, String] path to the Skillfile
+    def initialize(path: default_skill_path)
+      @path = path
+      @skills = []
+    end
+
+    # Read and evaluate the Skillfile, populating {#skills}.
+    #
+    # @return [Manifest] self
+    # @raise [RubySkills::Error] if the Skillfile is missing or invalid
+    def load!
+      unless @path.exist?
+        raise RubySkills::Error,
+              "Skillfile not found. Run `ruby-skills init` first."
+      end
+
+      instance_eval(@path.read, @path.to_s, 1)
+
+      self
+    rescue SyntaxError => e
+      raise RubySkills::Error, "Invalid Skillfile: #{e.message}"
+    end
+
+    # Declare a skill in the Skillfile DSL.
+    #
+    # Exactly one source must be provided: +github+ or +path+.
+    #
+    # @param name [String] skill identifier
+    # @param github [String, nil] GitHub repository in +owner/name+ form
+    # @param path [String, nil] local filesystem path to the skill
+    # @param version [String, nil] optional pinned version
+    # @return [void]
+    # @raise [RubySkills::Error] if neither +github+ nor +path+ is given
+    def skill(name, github: nil, path: nil, version: nil)
+      unless github || path
+        raise RubySkills::Error,
+              "#{name}: either github or path: must be provided"
+      end
+
+      @skills << Skill.new(
+        name: name,
+        github: github,
+        path: path,
+        version: version
+      )
+    end
+
+    private
+
+    # @api private
+    # @return [Pathname] default path used when none is given to {#initialize}
+    def default_skill_path
+      Config.new.skills_path
+    end
+  end
+end

data/lib/ruby_skills/remover.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RubySkills
+  # Uninstalls a skill from the project, adapters, and lockfile.
+  #
+  # @example Remove an installed skill
+  #   RubySkills::Remover.new.remove("rails-performance")
+  #
+  # @see RubySkills::Lockfile
+  # @see RubySkills::Adapters
+  # @since 0.1.0
+  class Remover
+    # @param config [RubySkills::Config] project paths used to locate skills
+    def initialize(config: Config.new)
+      @config = config
+    end
+
+    # Remove an installed skill from disk, tool adapters, and the lockfile.
+    #
+    # @param name [String] skill identifier to remove
+    # @return [void]
+    # @raise [RubySkills::Error] if the skill is not installed
+    def remove(name)
+      path = @config.skills_path.join(name)
+
+      unless path.exist?
+        raise RubySkills::Error,
+              "Skill `#{name}` is not installed"
+      end
+
+      adapters.each do |adapter|
+        adapter.new.remove(name)
+      end
+
+      FileUtils.rm_rf(path)
+
+      Lockfile.new.remove(name)
+
+      puts "✓ Removed #{name}"
+    end
+
+    private
+
+    # @api private
+    # @return [Array<Class>] adapter classes notified when a skill is removed
+    def adapters
+      RubySkills::Adapters.all
+    end
+  end
+end

data/lib/ruby_skills/resolver.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module RubySkills
+  # Turns a declared skill into a local directory that can be installed.
+  #
+  # Local skills are resolved from {RubySkills::Manifest::Skill#path}.
+  # Remote skills are cloned from GitHub into a temporary directory.
+  #
+  # @example Resolve a declared skill
+  #   skill = RubySkills::Manifest::Skill.new(
+  #     name: "rails-performance",
+  #     path: "./skills/rails-performance"
+  #   )
+  #   RubySkills::Resolver.new.resolve(skill)
+  #
+  # @see RubySkills::Manifest::Skill
+  # @since 0.1.0
+  class Resolver
+    # Skill directory ready to be installed.
+    #
+    # @!attribute [rw] name
+    #   @return [String] skill identifier
+    # @!attribute [rw] path
+    #   @return [Pathname] local directory containing the skill
+    # @!attribute [rw] source
+    #   @return [String] origin used to resolve the skill
+    ResolvedSkill = Struct.new(
+      :name,
+      :path,
+      :source,
+      keyword_init: true
+    )
+
+    # Resolve a skill from a local path or a remote repository.
+    #
+    # @param skill [RubySkills::Manifest::Skill] declared skill to resolve
+    # @return [ResolvedSkill] skill directory ready to install
+    # @raise [RubySkills::Error] if the skill has no usable source
+    def resolve(skill)
+      if skill.path
+        resolve_local(skill)
+      elsif skill.github
+        resolve_remote(skill)
+      else
+        raise RubySkills::Error,
+              "Unable to resolve #{skill.name}"
+      end
+    end
+
+    private
+
+    # @api private
+    # @param skill [RubySkills::Manifest::Skill]
+    # @return [ResolvedSkill]
+    # @raise [RubySkills::Error] if the local skill path is not a directory
+    def resolve_local(skill)
+      path = Pathname.new(skill.path).expand_path
+
+      unless path.directory?
+        raise RubySkills::Error,
+              "Skill path does not exist: #{path}"
+      end
+
+      ResolvedSkill.new(
+        name: skill.name,
+        path: path,
+        source: "path:#{path}"
+      )
+    end
+
+    # @api private
+    # @param skill [RubySkills::Manifest::Skill]
+    # @return [ResolvedSkill] skill cloned into a temporary directory
+    # @raise [RubySkills::Error] if the GitHub repository cannot be cloned
+    def resolve_remote(skill)
+      directory = Pathname.new(
+        Dir.mktmpdir("ruby-skills")
+      )
+
+      repository = "https://github.com/#{skill.github}.git"
+
+      success = system(
+        "git",
+        "clone",
+        "--depth",
+        "1",
+        repository,
+        directory.to_s,
+        out: File::NULL,
+        err: File::NULL
+      )
+
+      unless success
+        raise RubySkills::Error,
+              "Unable to clone #{skill.github}"
+      end
+
+      ResolvedSkill.new(
+        name: skill.name,
+        path: directory,
+        source: "github:#{skill.github}"
+      )
+    end
+  end
+end

data/lib/ruby_skills/updater.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RubySkills
+  # Reinstalls skills to pick up newer versions.
+  #
+  # Delegates the work to {RubySkills::Installer}. When +skill_name+ is
+  # omitted, every skill in the Skillfile is updated.
+  #
+  # @example Update a single skill
+  #   RubySkills::Updater.new.update("rails-performance")
+  #
+  # @example Update every declared skill
+  #   RubySkills::Updater.new.update
+  #
+  # @see RubySkills::Installer
+  # @since 0.1.0
+  class Updater
+    # Update one skill or every skill declared in the Skillfile.
+    #
+    # @param skill_name [String, nil] skill to update, or +nil+ to update all
+    # @return [void]
+    def update(skill_name = nil)
+      Installer.new.install(skill_name)
+
+      if skill_name
+        puts "✓ Updated #{skill_name}"
+      else
+        puts "✓ All skills updated"
+      end
+    end
+  end
+end

data/lib/ruby_skills/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RubySkills
+  # Current gem version.
+  #
+  # @return [String]
+  VERSION = "0.1.0"
+end

data/lib/ruby_skills.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "pathname"
+
+# Package manager for installing, updating, removing and sharing AI
+# development skills in Ruby and Rails projects.
+#
+# @see RubySkills::CLI
+# @see RubySkills::Config
+# @since 0.1.0
+module RubySkills
+  # Base error for all Ruby Skills failures.
+  class Error < StandardError; end
+end
+
+Dir.glob("ruby_skills/**/*.rb", base: __dir__).sort.each do |path|
+  require path.delete_suffix(".rb")
+end

data/ruby-skills.gemspec

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "lib/ruby_skills/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ruby-skills"
+  spec.version = RubySkills::VERSION
+  spec.authors = ["Renato Franco"]
+  spec.email = ["renator.franco93@gmail.com"]
+
+  spec.summary = "Package, share, and install Ruby engineering knowledge."
+  spec.description = <<~DESCRIPTION
+    Ruby Skills is a package manager for distributing engineering
+    knowledge to Ruby development tools and coding agents.
+  DESCRIPTION
+
+  spec.homepage = "https://rubyskills.org"
+  spec.license = "MIT"
+
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/renatofranco/ruby-skills",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir.chdir(__dir__) {
+    `git ls-files -z`.split("\x0").reject do |file|
+      file.start_with?(
+        "test/",
+        "spec/",
+        "features/",
+        ".git",
+        ".github"
+      )
+    end
+  }
+
+  spec.bindir = "bin"
+  spec.executables = ["ruby-skills"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "thor", "~> 1.3"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.58"
+  spec.add_development_dependency "rubocop-performance", "~> 1.20"
+  spec.add_development_dependency "rubocop-rspec", "~> 3.0"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

metadata

@@ -0,0 +1,169 @@
+--- !ruby/object:Gem::Specification
+name: ruby-skills
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Renato Franco
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.58'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.58'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.20'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  Ruby Skills is a package manager for distributing engineering
+  knowledge to Ruby development tools and coding agents.
+email:
+- renator.franco93@gmail.com
+executables:
+- ruby-skills
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".yardopts"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- bin/ruby-skills
+- lib/ruby_skills.rb
+- lib/ruby_skills/adapters/base.rb
+- lib/ruby_skills/adapters/claude.rb
+- lib/ruby_skills/adapters/codex.rb
+- lib/ruby_skills/adapters/cursor.rb
+- lib/ruby_skills/adapters/vscode.rb
+- lib/ruby_skills/cli.rb
+- lib/ruby_skills/config.rb
+- lib/ruby_skills/installer.rb
+- lib/ruby_skills/lockfile.rb
+- lib/ruby_skills/manifest.rb
+- lib/ruby_skills/remover.rb
+- lib/ruby_skills/resolver.rb
+- lib/ruby_skills/updater.rb
+- lib/ruby_skills/version.rb
+- ruby-skills.gemspec
+homepage: https://rubyskills.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://rubyskills.org
+  source_code_uri: https://github.com/renatofranco/ruby-skills
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Package, share, and install Ruby engineering knowledge.
+test_files: []