agents_skill_vault 0.1.0

data/lib/agents_skill_vault/errors/duplicate_label.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module AgentsSkillVault
+  module Errors
+    class DuplicateLabel < Error; end
+  end
+end

data/lib/agents_skill_vault/errors/git_not_installed.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module AgentsSkillVault
+  module Errors
+    class GitNotInstalled < Error; end
+  end
+end

data/lib/agents_skill_vault/errors/git_version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module AgentsSkillVault
+  module Errors
+    class GitVersion < Error; end
+  end
+end

data/lib/agents_skill_vault/errors/invalid_url.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module AgentsSkillVault
+  module Errors
+    class InvalidUrl < Error; end
+  end
+end

data/lib/agents_skill_vault/errors/not_found.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module AgentsSkillVault
+  module Errors
+    class NotFound < Error; end
+  end
+end

data/lib/agents_skill_vault/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AgentsSkillVault
+  module Errors
+  end
+end

data/lib/agents_skill_vault/git_operations.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module AgentsSkillVault
+  # Provides Git operations for cloning, syncing, and managing repositories.
+  #
+  # All methods are class methods that execute git commands via the shell.
+  # Requires Git 2.25.0+ for sparse checkout support.
+  #
+  # @example Clone a repository
+  #   GitOperations.clone_repo("https://github.com/user/repo", "/path/to/target")
+  #
+  # @example Sparse checkout for a specific folder
+  #   GitOperations.sparse_checkout(
+  #     "https://github.com/user/repo",
+  #     "/path/to/target",
+  #     branch: "main",
+  #     paths: ["lib/skills"]
+  #   )
+  #
+  class GitOperations
+    # Minimum required Git version for sparse checkout support
+    MIN_VERSION = "2.25.0"
+
+    class << self
+      # Checks if git is installed and available in PATH.
+      #
+      # @raise [Errors::GitNotInstalled] if git is not available
+      # @return [void]
+      #
+      def check_git_available!
+        return if git_installed?
+
+        raise Errors::GitNotInstalled, "Git is not installed or not available in PATH"
+      end
+
+      # Checks if the installed git version meets minimum requirements.
+      #
+      # @raise [Errors::GitVersion] if git version is below 2.25.0
+      # @return [void]
+      #
+      def check_git_version!
+        version = git_version
+        return unless version < Gem::Version.new(MIN_VERSION)
+
+        raise Errors::GitVersion, "Git version #{version} is too old. Minimum required: #{MIN_VERSION}"
+      end
+
+      # Clones a git repository.
+      #
+      # @param url [String] The repository URL to clone
+      # @param target_path [String] Local path where the repository will be cloned
+      # @param branch [String, nil] Specific branch to clone (optional)
+      # @return [void]
+      # @raise [Error] if the clone command fails
+      #
+      # @example Clone with default branch
+      #   GitOperations.clone_repo("https://github.com/user/repo", "/local/path")
+      #
+      # @example Clone specific branch
+      #   GitOperations.clone_repo("https://github.com/user/repo", "/local/path", branch: "develop")
+      #
+      def clone_repo(url, target_path, branch: nil)
+        branch_flag = branch ? "--branch #{branch}" : ""
+        run_command("git clone #{branch_flag} #{url} #{target_path}")
+      end
+
+      # Performs a sparse checkout to clone only specific paths.
+      #
+      # Uses modern git sparse-checkout commands to download only the specified
+      # directories or files from the repository (requires Git 2.25.0+).
+      #
+      # @param url [String] The repository URL
+      # @param target_path [String] Local path for the checkout
+      # @param branch [String] Branch to checkout
+      # @param paths [Array<String>] Paths within the repository to include
+      # @return [void]
+      # @raise [Error] if any git command fails
+      #
+      # @example Checkout a single folder
+      #   GitOperations.sparse_checkout(
+      #     "https://github.com/user/repo",
+      #     "/local/path",
+      #     branch: "main",
+      #     paths: ["lib/skills/my-skill"]
+      #   )
+      #
+      def sparse_checkout(url, target_path, branch:, paths:)
+        run_command("git init #{target_path}")
+        Dir.chdir(target_path) do
+          run_command("git remote add origin #{url}")
+          run_command("git sparse-checkout init --no-cone")
+          run_command("git sparse-checkout set #{paths.join(" ")}")
+          run_command("git fetch origin #{branch}")
+          run_command("git checkout #{branch}")
+        end
+      end
+
+      # Pulls the latest changes from the remote.
+      #
+      # Performs a fetch and hard reset to match the remote branch.
+      #
+      # @param path [String] Path to the local repository
+      # @return [void]
+      # @raise [Error] if the pull command fails
+      #
+      def pull(path)
+        Dir.chdir(path) do
+          run_command("git fetch origin")
+          run_command("git reset --hard origin/$(git branch --show-current)")
+        end
+      end
+
+      # Gets the current branch name of a repository.
+      #
+      # @param path [String] Path to the local repository
+      # @return [String] The current branch name
+      #
+      def current_branch(path)
+        Dir.chdir(path) do
+          stdout, = run_command("git branch --show-current")
+          stdout.strip
+        end
+      end
+
+      private
+
+      def git_installed?
+        system("which git > /dev/null 2>&1")
+      end
+
+      def git_version
+        stdout, = run_command("git --version")
+        version_string = stdout.match(/git version (\d+\.\d+\.\d+)/)[1]
+        Gem::Version.new(version_string)
+      end
+
+      def run_command(command)
+        stdout, stderr, status = Open3.capture3(command)
+
+        raise Error, "Command failed: #{command}\n#{stderr}" unless status.success?
+
+        [stdout, stderr]
+      end
+    end
+  end
+end

data/lib/agents_skill_vault/manifest.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AgentsSkillVault
+  # Manages the JSON manifest file that tracks all resources in a vault.
+  #
+  # The manifest stores metadata about each resource including labels, URLs,
+  # and sync timestamps. It persists to disk as a JSON file.
+  #
+  # @example
+  #   manifest = Manifest.new(path: "/vault/manifest.json")
+  #   manifest.add_resource(resource)
+  #   manifest.find_resource("user/repo")
+  #
+  class Manifest
+    # Current manifest file format version
+    VERSION = "1.0"
+
+    # @return [String] Absolute path to the manifest JSON file
+    attr_reader :path
+
+    # Creates a new Manifest instance.
+    #
+    # @param path [String] Path to the manifest JSON file
+    #
+    def initialize(path:)
+      @path = path
+    end
+
+    # Loads the manifest data from disk.
+    #
+    # @return [Hash] The manifest data with :version and :resources keys
+    #
+    def load
+      return default_manifest unless File.exist?(path)
+
+      JSON.parse(File.read(path), symbolize_names: true)
+    end
+
+    # Saves manifest data to disk.
+    #
+    # @param data [Hash] The manifest data to save
+    # @return [void]
+    #
+    def save(data)
+      File.write(path, JSON.pretty_generate(data))
+    end
+
+    # Returns all resource hashes from the manifest.
+    #
+    # @return [Array<Hash>] Array of resource attribute hashes
+    #
+    def resources
+      load[:resources] || []
+    end
+
+    # Adds a new resource to the manifest.
+    #
+    # @param resource [Resource] The resource to add
+    # @raise [Errors::DuplicateLabel] if a resource with the same label exists
+    # @return [void]
+    #
+    def add_resource(resource)
+      data = load
+      data[:resources] ||= []
+
+      if data[:resources].any? { |r| r[:label] == resource.label }
+        raise Errors::DuplicateLabel, "Resource with label '#{resource.label}' already exists. " \
+                                      "Use a custom label with: add(url, label: 'custom-label')"
+      end
+
+      data[:resources] << resource.to_h
+      save(data)
+    end
+
+    # Removes a resource from the manifest by label.
+    #
+    # Does nothing if the label doesn't exist (no error raised).
+    #
+    # @param label [String] The label of the resource to remove
+    # @return [void]
+    #
+    def remove_resource(label)
+      data = load
+      data[:resources]&.reject! { |r| r[:label] == label }
+      save(data)
+    end
+
+    # Updates an existing resource in the manifest.
+    #
+    # @param resource [Resource] The resource with updated attributes
+    # @return [Boolean] true if the resource was found and updated, false otherwise
+    #
+    def update_resource(resource)
+      data = load
+      data[:resources] ||= []
+      index = data[:resources].find_index { |r| r[:label] == resource.label }
+
+      return false unless index
+
+      data[:resources][index] = resource.to_h
+      save(data)
+      true
+    end
+
+    # Finds a resource by its label.
+    #
+    # @param label [String] The label to search for
+    # @param storage_path [String, nil] Storage path to set on the returned Resource
+    # @return [Resource, nil] The resource if found, nil otherwise
+    #
+    def find_resource(label, storage_path: nil)
+      hash = resources.find { |r| r[:label] == label }
+      return nil unless hash
+
+      Resource.from_h(hash, storage_path: storage_path || storage_path_from_manifest)
+    end
+
+    # Clears all resources from the manifest.
+    #
+    # @return [void]
+    #
+    def clear
+      save(default_manifest)
+    end
+
+    private
+
+    def default_manifest
+      { version: VERSION, resources: [] }
+    end
+
+    def storage_path_from_manifest
+      File.dirname(path)
+    end
+  end
+end

data/lib/agents_skill_vault/resource.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "time"
+
+module AgentsSkillVault
+  # Represents a GitHub resource tracked in the vault.
+  #
+  # A Resource can be a full repository, a folder within a repository,
+  # or a single file. It tracks metadata like the source URL, local path,
+  # and sync timestamps.
+  #
+  # @example Create a repository resource
+  #   resource = Resource.new(
+  #     label: "user/repo",
+  #     url: "https://github.com/user/repo",
+  #     username: "user",
+  #     repo: "repo",
+  #     type: :repo,
+  #     storage_path: "/path/to/vault"
+  #   )
+  #
+  class Resource
+    # @return [String] Unique identifier for this resource in the vault
+    attr_reader :label
+
+    # @return [String] GitHub URL of the repository
+    attr_reader :url
+
+    # @return [String] GitHub username/organization that owns the repository
+    attr_reader :username
+
+    # @return [String] Name of the repository
+    attr_reader :repo
+
+    # @return [String, nil] Folder name for folder/file resources
+    attr_reader :folder
+
+    # @return [Symbol] Type of resource (:repo, :folder, or :file)
+    attr_reader :type
+
+    # @return [String] Git branch name
+    attr_reader :branch
+
+    # @return [String, nil] Path relative to repository root (for folder/file resources)
+    attr_reader :relative_path
+
+    # @return [Time] When the resource was added to the vault
+    attr_reader :added_at
+
+    # @return [Time] When the resource was last synced
+    attr_reader :synced_at
+
+    # @return [String, nil] Base path where resources are stored
+    attr_reader :storage_path
+
+    # @return [Symbol] Validation status (:valid_skill, :invalid_skill, :not_a_skill, :unvalidated)
+    attr_reader :validation_status
+
+    # @return [Array<String>] Validation errors (for invalid skills)
+    attr_reader :validation_errors
+
+    # @return [String, nil] The name of the skill (nil for non-skill resources)
+    attr_reader :skill_name
+
+    # @return [Boolean] Whether this resource is a skill
+    attr_reader :is_skill
+
+    # Creates a new Resource instance.
+    #
+    # @param label [String] Unique identifier for this resource
+    # @param url [String] GitHub URL of the repository
+    # @param username [String] GitHub username/organization
+    # @param repo [String] Repository name
+    # @param type [Symbol] Resource type (:repo, :folder, or :file)
+    # @param storage_path [String, nil] Base path for local storage
+    # @param folder [String, nil] Folder name for non-repo resources
+    # @param branch [String, nil] Git branch (defaults to "main")
+    # @param relative_path [String, nil] Path relative to repository root
+    # @param added_at [Time, nil] When added (defaults to now)
+    # @param synced_at [Time, nil] When last synced (defaults to now)
+    # @param validation_status [Symbol, nil] Validation status
+    # @param validation_errors [Array, nil] Validation errors
+    # @param skill_name [String, nil] The name of the skill
+    # @param is_skill [Boolean, nil] Whether this is a skill
+    #
+    def initialize(label:, url:, username:, repo:, type:, storage_path:, folder: nil, branch: nil,
+                   relative_path: nil, added_at: nil, synced_at: nil, validation_status: :unvalidated,
+                   validation_errors: [], skill_name: nil, is_skill: nil)
+      @label = label
+      @url = url
+      @username = username
+      @repo = repo
+      @folder = folder
+      @type = type
+      @branch = branch || "main"
+      @relative_path = relative_path
+      @added_at = added_at || Time.now
+      @synced_at = synced_at || Time.now
+      @storage_path = storage_path
+      @validation_status = validation_status
+      @validation_errors = validation_errors || []
+      @skill_name = skill_name
+      @is_skill = is_skill.nil? ? !skill_name.nil? : is_skill
+    end
+
+    # Returns the local filesystem path where the resource is stored.
+    #
+    # @return [String, nil] Absolute path to the resource, or nil if no storage_path
+    #
+    # @example
+    #   resource.local_path
+    #   # => "/path/to/vault/user/repo"
+    #
+    def local_path
+      return nil unless storage_path
+
+      if type == :repo
+        File.join(storage_path, username, repo)
+      else
+        File.join(storage_path, username, repo, relative_path || folder || "")
+      end
+    end
+
+    # Converts the resource to a hash for serialization.
+    #
+    # @return [Hash] Resource attributes as a hash
+    #
+    def to_h
+      {
+        label: label,
+        url: url,
+        username: username,
+        repo: repo,
+        folder: folder,
+        type: type,
+        branch: branch,
+        relative_path: relative_path,
+        added_at: added_at.iso8601,
+        synced_at: synced_at.iso8601,
+        validation_status: validation_status,
+        validation_errors: validation_errors,
+        skill_name: skill_name,
+        is_skill: is_skill
+      }
+    end
+
+    # Compares two resources for equality.
+    #
+    # Two resources are equal if they have the same label, URL, username,
+    # repo, folder, type, branch, and relative_path.
+    #
+    # @param other [Object] The object to compare with
+    # @return [Boolean] true if resources are equal
+    #
+    def ==(other)
+      return false unless other.is_a?(Resource)
+
+      label == other.label &&
+        url == other.url &&
+        username == other.username &&
+        repo == other.repo &&
+        folder == other.folder &&
+        type == other.type &&
+        branch == other.branch &&
+        relative_path == other.relative_path &&
+        validation_status == other.validation_status &&
+        validation_errors == other.validation_errors &&
+        skill_name == other.skill_name &&
+        is_skill == other.is_skill
+    end
+
+    # Creates a Resource from a hash.
+    #
+    # Supports both symbol and string keys for compatibility with
+    # different JSON parsing options.
+    #
+    # @param hash [Hash] Resource attributes as a hash
+    # @param storage_path [String, nil] Base path for local storage
+    # @return [Resource] A new Resource instance
+    #
+    # @example
+    #   Resource.from_h({ label: "user/repo", ... }, storage_path: "/vault")
+    #
+    def self.from_h(hash, storage_path: nil)
+      # Handle backward compatibility: if validation_status is missing, default to :unvalidated
+      validation_status = hash[:validation_status] || hash["validation_status"] || :unvalidated
+      validation_status = validation_status.to_sym if validation_status.is_a?(String)
+
+      # Handle backward compatibility: if is_skill is missing, derive from skill_name
+      is_skill = hash[:is_skill] || hash["is_skill"]
+      skill_name = hash[:skill_name] || hash["skill_name"]
+      is_skill ||= !skill_name.nil?
+
+      # Handle backward compatibility: if validation_errors is missing, default to empty array
+      validation_errors = hash[:validation_errors] || hash["validation_errors"] || []
+
+      new(
+        label: hash[:label] || hash["label"],
+        url: hash[:url] || hash["url"],
+        username: hash[:username] || hash["username"],
+        repo: hash[:repo] || hash["repo"],
+        folder: hash[:folder] || hash["folder"],
+        type: (hash[:type] || hash["type"]).to_sym,
+        branch: hash[:branch] || hash["branch"],
+        relative_path: hash[:relative_path] || hash["relative_path"] || hash["path_in_repo"] || hash["path_in_repo"],
+        added_at: parse_time(hash[:added_at] || hash["added_at"]),
+        synced_at: parse_time(hash[:synced_at] || hash["synced_at"]),
+        validation_status:,
+        validation_errors:,
+        skill_name:,
+        is_skill:,
+        storage_path:
+      )
+    end
+
+    # Parses a time value from various formats.
+    #
+    # @param time_value [String, Time, nil] The time value to parse
+    # @return [Time, nil] Parsed Time object, or nil if input was nil
+    # @raise [ArgumentError] if time_value is not a valid type
+    #
+    def self.parse_time(time_value)
+      case time_value
+      when nil
+        nil
+      when String
+        Time.iso8601(time_value)
+      when Time
+        time_value
+      else
+        raise ArgumentError, "Invalid time value: #{time_value.inspect}"
+      end
+    end
+  end
+end

data/lib/agents_skill_vault/skill_scanner.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module AgentsSkillVault
+  # Scans directories for SKILL.md files.
+  #
+  # Recursively searches for SKILL.md files and extracts metadata
+  # including the skill name and folder path.
+  #
+  # @example Scan a directory for skills
+  #   skills = SkillScanner.scan_directory("/path/to/repo")
+  #   skills.each do |skill|
+  #     puts "Found skill: #{skill[:skill_name]} at #{skill[:relative_path]}"
+  #   end
+  #
+  class SkillScanner
+    SKILL_FILE_NAME = "SKILL.md"
+
+    # Scans a directory for all SKILL.md files.
+    #
+    # @param base_path [String] The base directory to scan
+    # @return [Array<Hash>] Array of skill metadata with keys:
+    #   - :relative_path [String] Path relative to base_path
+    #   - :skill_folder [String] Full folder path containing SKILL.md
+    #   - :skill_name [String] The name of the skill (parent folder name)
+    #   - :folder_path [String] Alias for skill_folder
+    #
+    # @raise [ArgumentError] if base_path is nil or doesn't exist
+    #
+    def self.scan_directory(base_path)
+      raise ArgumentError, "base_path cannot be nil" if base_path.nil?
+      raise ArgumentError, "base_path does not exist: #{base_path}" unless Dir.exist?(base_path)
+
+      skills = []
+      scan_recursive(base_path, base_path, skills)
+      skills
+    end
+
+    # Recursively scans directory for SKILL.md files.
+    #
+    # @param current_dir [String] Current directory being scanned
+    # @param base_path [String] Original base path for relative path calculation
+    # @param skills [Array] Array to collect found skills
+    #
+    def self.scan_recursive(current_dir, base_path, skills)
+      # Check if current directory has a SKILL.md file
+      skill_file = File.join(current_dir, SKILL_FILE_NAME)
+      skills << extract_skill_metadata(skill_file, base_path) if File.exist?(skill_file)
+
+      # Scan subdirectories
+      Dir.glob(File.join(current_dir, "*")).each do |entry|
+        scan_recursive(entry, base_path, skills) if File.directory?(entry)
+      end
+    end
+
+    # Extracts skill metadata from a SKILL.md file path.
+    #
+    # @param skill_file_path [String] Full path to SKILL.md file
+    # @param base_path [String] Base path for calculating relative paths
+    # @return [Hash] Skill metadata
+    #
+    def self.extract_skill_metadata(skill_file_path, base_path)
+      skill_dir = File.dirname(skill_file_path)
+      skill_name = File.basename(skill_dir)
+      relative_path = Pathname.new(skill_dir).relative_path_from(Pathname.new(base_path)).to_s
+
+      {
+        relative_path:,
+        skill_folder: relative_path,
+        skill_name:,
+        folder_path: relative_path
+      }
+    end
+  end
+end