agents_skill_vault 0.1.0 → 0.2.0

data/lib/agents_skill_vault/vault/resource_adder.rb

@@ -0,0 +1,410 @@
+# frozen_string_literal: true
+
+module AgentsSkillVault
+  class Vault
+    # Module for adding resources to the vault.
+    #
+    module ResourceAdder
+      private
+
+      # Adds a repository resource, scanning for all skills.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param label [String, nil] Custom label
+      # @return [Array<Resource>] Created resources (one per skill found)
+      #
+      def add_repository_resource(parsed_url, label:)
+        clone_repository(parsed_url)
+        skills = SkillScanner.scan_directory(local_repo_path(parsed_url))
+
+        if skills.empty?
+          add_non_skill_repo(parsed_url, label:)
+        else
+          add_skill_repo_resources(parsed_url, skills, label:)
+        end
+      end
+
+      # Adds a folder resource.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param label [String, nil] Custom label
+      # @return [Resource, Array<Resource>] Created resource(s)
+      #
+      def add_folder_resource(parsed_url, label:)
+        setup_repo_folder(parsed_url)
+        target_path = File.join(local_repo_path(parsed_url), parsed_url.relative_path)
+        skills = SkillScanner.scan_directory(target_path)
+
+        case skills.length
+        when 0 then add_non_skill_folder(parsed_url, label:)
+        when 1 then add_single_skill_folder(parsed_url, skills.first, label:, target_path:)
+        else add_multi_skill_folder(parsed_url, skills, label:, target_path:)
+        end
+      end
+
+      # Adds a file resource.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param label [String, nil] Custom label
+      # @return [Resource] Created resource
+      #
+      def add_file_resource(parsed_url, label:)
+        repo_url = "https://github.com/#{parsed_url.username}/#{parsed_url.repo}"
+
+        if parsed_url.skill_file?
+          add_skill_file(parsed_url, repo_url, label:)
+        else
+          add_non_skill_file(parsed_url, repo_url, label:)
+        end
+      end
+
+      # Creates a resource from parsed URL with optional label.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param label [String, nil] Custom label
+      # @return [Resource] Created resource
+      #
+      def create_resource(parsed_url, label:)
+        label ||= parsed_url.label
+
+        Resource.new(
+          label: label,
+          url: "https://github.com/#{parsed_url.username}/#{parsed_url.repo}",
+          username: parsed_url.username,
+          repo: parsed_url.repo,
+          folder: parsed_url.type == :repo ? nil : File.basename(parsed_url.relative_path || ""),
+          type: parsed_url.type,
+          branch: parsed_url.branch,
+          relative_path: parsed_url.relative_path,
+          storage_path: storage_path
+        )
+      end
+
+      # Clones a repository to the vault.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @return [void]
+      #
+      def clone_repository(parsed_url)
+        target_path = local_repo_path(parsed_url)
+        FileUtils.mkdir_p(File.dirname(target_path))
+        repo_url = "https://github.com/#{parsed_url.username}/#{parsed_url.repo}"
+        GitOperations.clone_repo(repo_url, target_path, branch: parsed_url.branch)
+      end
+
+      # Adds a non-skill repository resource.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param label [String, nil] Custom label
+      # @return [Array<Resource>] Created resources
+      #
+      def add_non_skill_repo(parsed_url, label:)
+        resource = create_resource(parsed_url, label: label || parsed_url.label)
+        resource = Resource.from_h(
+          resource.to_h.merge(
+            validation_status: :not_a_skill,
+            is_skill: false
+          ),
+          storage_path: storage_path
+        )
+        manifest.add_resource(resource)
+        [resource]
+      end
+
+      # Adds skill resources for a repository.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param skills [Array<Hash>] List of skills found
+      # @param label [String, nil] Custom label
+      # @return [Array<Resource>] Created resources
+      #
+      def add_skill_repo_resources(parsed_url, skills, label:)
+        target_path = local_repo_path(parsed_url)
+        repo_url = "https://github.com/#{parsed_url.username}/#{parsed_url.repo}"
+
+        skills.map do |skill|
+          skill_label = if label
+                          "#{label}-#{skill[:skill_name]}"
+                        else
+                          "#{parsed_url.username}/#{parsed_url.repo}/#{skill[:skill_name]}"
+                        end
+
+          resource = build_skill_resource(
+            skill_label, repo_url, parsed_url, skill[:folder_path],
+            skill[:folder_path], target_path
+          )
+
+          validate_and_update_resource(resource, skill[:folder_path], target_path)
+          manifest.add_resource(resource)
+          resource
+        end
+      end
+
+      # Adds a non-skill folder resource.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param label [String, nil] Custom label
+      # @return [Resource] Created resource
+      #
+      def add_non_skill_folder(parsed_url, label:)
+        skill_name = File.basename(parsed_url.relative_path)
+        resource_label = label || "#{parsed_url.username}/#{parsed_url.repo}/#{skill_name}"
+        repo_url = "https://github.com/#{parsed_url.username}/#{parsed_url.repo}"
+
+        resource = Resource.new(
+          label: resource_label,
+          url: repo_url,
+          username: parsed_url.username,
+          repo: parsed_url.repo,
+          folder: parsed_url.relative_path,
+          type: :folder,
+          branch: parsed_url.branch,
+          relative_path: parsed_url.relative_path,
+          storage_path: storage_path,
+          validation_status: :not_a_skill,
+          validation_errors: [],
+          skill_name: nil,
+          is_skill: false
+        )
+
+        manifest.add_resource(resource)
+        resource
+      end
+
+      # Adds a single skill folder resource.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param skill [Hash] Skill data
+      # @param label [String, nil] Custom label
+      # @param target_path [String] Target path for validation
+      # @return [Resource] Created resource
+      #
+      def add_single_skill_folder(parsed_url, skill, label:, target_path:)
+        skill_name = skill[:skill_name]
+        resource_label = label || "#{parsed_url.username}/#{parsed_url.repo}/#{skill_name}"
+
+        skill_relative_path = if skill[:relative_path] == "."
+                                parsed_url.relative_path
+                              else
+                                File.join(parsed_url.relative_path, skill[:relative_path])
+                              end
+
+        repo_url = "https://github.com/#{parsed_url.username}/#{parsed_url.repo}"
+
+        resource = build_skill_resource(
+          resource_label, repo_url, parsed_url, parsed_url.relative_path,
+          skill_relative_path, target_path, skill[:relative_path]
+        )
+
+        validate_and_update_resource(resource, skill[:relative_path], target_path)
+        manifest.add_resource(resource)
+        resource
+      end
+
+      # Adds multiple skill folder resources.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param skills [Array<Hash>] List of skills found
+      # @param label [String, nil] Custom label
+      # @param target_path [String] Target path for validation
+      # @return [Array<Resource>] Created resources
+      #
+      def add_multi_skill_folder(parsed_url, skills, label:, target_path:)
+        repo_url = "https://github.com/#{parsed_url.username}/#{parsed_url.repo}"
+
+        skills.map do |skill|
+          skill_name = skill[:skill_name]
+          skill_label = label ? "#{label}/#{skill_name}" : "#{parsed_url.username}/#{parsed_url.repo}/#{skill_name}"
+
+          skill_relative_path = if skill[:relative_path] == "."
+                                  parsed_url.relative_path
+                                else
+                                  File.join(parsed_url.relative_path, skill[:relative_path])
+                                end
+
+          resource = build_skill_resource(
+            skill_label, repo_url, parsed_url, parsed_url.relative_path,
+            skill_relative_path, target_path, skill[:relative_path]
+          )
+
+          validate_and_update_resource(resource, skill[:relative_path], target_path)
+          manifest.add_resource(resource)
+          resource
+        end
+      end
+
+      # Adds a skill file resource.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param repo_url [String] Repository URL
+      # @param label [String, nil] Custom label
+      # @return [Resource] Created resource
+      #
+      def add_skill_file(parsed_url, repo_url, label:)
+        setup_skill_file_path(parsed_url)
+        target_path = File.join(local_repo_path(parsed_url), parsed_url.skill_folder_path)
+        result = SkillValidator.validate(File.join(target_path, "SKILL.md"))
+
+        resource = create_skill_file_resource(parsed_url, repo_url, label, result)
+        manifest.add_resource(resource)
+        resource
+      end
+
+      # Creates a skill file resource.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param repo_url [String] Repository URL
+      # @param label [String, nil] Custom label
+      # @param result [Hash] Validation result
+      # @return [Resource] Created resource
+      #
+      def create_skill_file_resource(parsed_url, repo_url, label, result)
+        resource_label = label || "#{parsed_url.username}/#{parsed_url.repo}/#{parsed_url.skill_name}"
+
+        Resource.new(
+          label: resource_label,
+          url: repo_url,
+          username: parsed_url.username,
+          repo: parsed_url.repo,
+          folder: parsed_url.skill_folder_path,
+          type: :file,
+          branch: parsed_url.branch,
+          relative_path: parsed_url.skill_folder_path,
+          storage_path: storage_path,
+          validation_status: result[:valid] ? :valid_skill : :invalid_skill,
+          validation_errors: result[:errors],
+          skill_name: parsed_url.skill_name,
+          is_skill: true
+        )
+      end
+
+      # Adds a non-skill file resource.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param repo_url [String] Repository URL
+      # @param label [String, nil] Custom label
+      # @return [Resource] Created resource
+      #
+      def add_non_skill_file(parsed_url, _repo_url, label:)
+        parent_path = File.dirname(parsed_url.relative_path)
+        setup_non_skill_file_path(parsed_url, parent_path)
+
+        resource = Resource.new(
+          label: label || parsed_url.label,
+          url: parsed_url.url,
+          username: parsed_url.username,
+          repo: parsed_url.repo,
+          folder: parent_path,
+          type: :file,
+          branch: parsed_url.branch,
+          relative_path: parsed_url.relative_path,
+          storage_path: storage_path,
+          validation_status: :not_a_skill,
+          validation_errors: [],
+          skill_name: nil,
+          is_skill: false
+        )
+
+        manifest.add_resource(resource)
+        resource
+      end
+
+      # Builds a skill resource from parsed data.
+      #
+      # @param label [String] Resource label
+      # @param repo_url [String] Repository URL
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param folder [String] Folder path
+      # @param relative_path [String] Relative path
+      # @param target_path [String] Target path for type detection
+      # @param skill_relative_path [String, nil] Relative path for skill
+      # @return [Resource] Created resource
+      #
+      def build_skill_resource(label, repo_url, parsed_url, folder, relative_path, _target_path,
+                               skill_relative_path = nil)
+        Resource.new(
+          label: label,
+          url: repo_url,
+          username: parsed_url.username,
+          repo: parsed_url.repo,
+          folder: folder,
+          type: parsed_url.type,
+          branch: parsed_url.branch,
+          relative_path: relative_path,
+          storage_path: storage_path,
+          skill_name: skill_relative_path ? label.split("/").last : nil,
+          is_skill: true
+        )
+      end
+
+      # Validates and updates a resource.
+      #
+      # @param resource [Resource] Resource to validate
+      # @param relative_path [String] Relative path for validation
+      # @param target_path [String] Target path
+      # @return [Resource] Updated resource
+      #
+      def validate_and_update_resource(resource, relative_path, target_path)
+        skill_file = File.join(target_path, relative_path, "SKILL.md")
+        result = SkillValidator.validate(skill_file)
+
+        Resource.from_h(
+          resource.to_h.merge(
+            validation_status: result[:valid] ? :valid_skill : :invalid_skill,
+            validation_errors: result[:errors]
+          ),
+          storage_path: storage_path
+        )
+      end
+
+      # Returns the local path for a repository.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @return [String] Local path
+      #
+      def local_repo_path(parsed_url)
+        File.join(storage_path, parsed_url.username, parsed_url.repo)
+      end
+
+      # Sets up repository folder for sparse checkout.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @return [void]
+      #
+      def setup_repo_folder(parsed_url)
+        repo_path = local_repo_path(parsed_url)
+        FileUtils.mkdir_p(repo_path)
+        repo_url = "https://github.com/#{parsed_url.username}/#{parsed_url.repo}"
+        paths = [parsed_url.relative_path]
+        GitOperations.sparse_checkout(repo_url, repo_path, branch: parsed_url.branch, paths: paths)
+      end
+
+      # Sets up skill file path for download.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @return [void]
+      #
+      def setup_skill_file_path(parsed_url)
+        repo_path = local_repo_path(parsed_url)
+        FileUtils.mkdir_p(repo_path)
+        repo_url = "https://github.com/#{parsed_url.username}/#{parsed_url.repo}"
+        paths = [parsed_url.skill_folder_path]
+        GitOperations.sparse_checkout(repo_url, repo_path, branch: parsed_url.branch, paths: paths)
+      end
+
+      # Sets up non-skill file path for download.
+      #
+      # @param parsed_url [UrlParser::ParseResult] Parsed URL
+      # @param parent_path [String] Parent path
+      # @return [void]
+      #
+      def setup_non_skill_file_path(parsed_url, parent_path)
+        repo_path = local_repo_path(parsed_url)
+        FileUtils.mkdir_p(repo_path)
+        repo_url = "https://github.com/#{parsed_url.username}/#{parsed_url.repo}"
+        paths = [parent_path]
+        GitOperations.sparse_checkout(repo_url, repo_path, branch: parsed_url.branch, paths: paths)
+      end
+    end
+  end
+end

data/lib/agents_skill_vault/vault/resource_syncer.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module AgentsSkillVault
+  class Vault
+    # Module for syncing resources in vault.
+    #
+    module ResourceSyncer
+      private
+
+      # Syncs a resource by pulling latest changes.
+      #
+      # @param resource [Resource] Resource to sync
+      # @return [SyncResult] Sync result
+      #
+      def sync_resource(resource)
+        return SyncResult.new(success: false, error: "Resource has no local path") unless resource.local_path
+
+        unless Dir.exist?(resource.local_path)
+          return SyncResult.new(success: false, error: "Path does not exist: #{resource.local_path}")
+        end
+
+        sync_by_type(resource)
+        update_synced_at(resource)
+
+        SyncResult.new(success: true, changes: true)
+      rescue Errors::Error => e
+        SyncResult.new(success: false, error: e.message)
+      end
+
+      # Syncs a repository-type resource, re-scanning for skills.
+      #
+      # @param resource [Resource] The resource to sync
+      # @return [void]
+      #
+      def sync_repository_resource(resource)
+        skills = SkillScanner.scan_directory(resource.local_path)
+        existing_resources = repo_resources(resource)
+
+        skills.each do |skill|
+          process_skill_sync(resource, skill, existing_resources)
+        end
+      end
+
+      # Downloads a resource from GitHub.
+      #
+      # @param resource [Resource] Resource to download
+      # @return [void]
+      #
+      def download_resource(resource)
+        target_path = resource.local_path
+        parent_dir = File.dirname(target_path)
+        FileUtils.mkdir_p(parent_dir)
+
+        if resource.type == :repo
+          GitOperations.clone_repo(resource.url, target_path, branch: resource.branch)
+        else
+          paths = [resource.relative_path]
+          GitOperations.sparse_checkout(resource.url, target_path, branch: resource.branch, paths: paths)
+        end
+      end
+
+      # Syncs resource based on its type.
+      #
+      # @param resource [Resource] Resource to sync
+      # @return [void]
+      #
+      def sync_by_type(resource)
+        GitOperations.pull(resource.local_path)
+
+        if resource.type == :repo
+          sync_repository_resource(resource)
+        else
+          validate_resource(resource.label)
+        end
+      end
+
+      # Updates synced_at timestamp for all repo resources.
+      #
+      # @param resource [Resource] Resource to update
+      # @return [void]
+      #
+      def update_synced_at(resource)
+        repo_resources = list.select { |r| r.repo == resource.repo && r.username == resource.username }
+        repo_resources.each do |r|
+          updated = Resource.from_h(r.to_h.merge(synced_at: Time.now), storage_path: storage_path)
+          manifest.update_resource(updated)
+        end
+      end
+
+      # Returns all resources for a repository.
+      #
+      # @param resource [Resource] Resource to match
+      # @return [Array<Resource>] Matching resources
+      #
+      def repo_resources(resource)
+        list.select do |r|
+          r.repo == resource.repo && r.username == resource.username && r.type == :repo
+        end
+      end
+
+      # Processes skill during sync (add or update).
+      #
+      # @param resource [Resource] Parent resource
+      # @param skill [Hash] Skill data
+      # @param existing_resources [Array<Resource>] Existing resources
+      # @return [void]
+      #
+      def process_skill_sync(resource, skill, existing_resources)
+        skill_label = "#{resource.username}/#{resource.repo}/#{skill[:skill_name]}"
+        existing = existing_resources.find { |r| r.skill_name == skill[:skill_name] }
+
+        if existing
+          revalidate_existing_skill(resource, existing, skill)
+        else
+          add_new_skill_from_sync(resource, skill, skill_label)
+        end
+      end
+
+      # Re-validates an existing skill.
+      #
+      # @param resource [Resource] Parent resource
+      # @param existing [Resource] Existing skill resource
+      # @param skill [Hash] Skill data
+      # @return [void]
+      #
+      def revalidate_existing_skill(resource, existing, skill)
+        skill_file = File.join(resource.local_path, skill[:folder_path], "SKILL.md")
+        result = SkillValidator.validate(skill_file)
+
+        updated = Resource.from_h(
+          existing.to_h.merge(
+            validation_status: result[:valid] ? :valid_skill : :invalid_skill,
+            validation_errors: result[:errors]
+          ),
+          storage_path: storage_path
+        )
+        manifest.update_resource(updated)
+      end
+
+      # Adds a new skill found during sync.
+      #
+      # @param resource [Resource] Parent resource
+      # @param skill [Hash] Skill data
+      # @param skill_label [String] Skill label
+      # @return [void]
+      #
+      def add_new_skill_from_sync(resource, skill, skill_label)
+        new_resource = create_new_skill_resource(resource, skill, skill_label)
+        new_resource = validate_and_update_skill(resource, new_resource, skill)
+        manifest.add_resource(new_resource)
+      end
+
+      # Creates a new skill resource.
+      #
+      # @param resource [Resource] Parent resource
+      # @param skill [Hash] Skill data
+      # @param skill_label [String] Skill label
+      # @return [Resource] Created resource
+      #
+      def create_new_skill_resource(resource, skill, skill_label)
+        Resource.new(
+          label: skill_label,
+          url: resource.url,
+          username: resource.username,
+          repo: resource.repo,
+          folder: skill[:folder_path],
+          type: :repo,
+          branch: resource.branch,
+          relative_path: skill[:folder_path],
+          storage_path: storage_path,
+          validation_status: :unvalidated,
+          validation_errors: [],
+          skill_name: skill[:skill_name],
+          is_skill: true
+        )
+      end
+
+      # Validates and updates a skill resource.
+      #
+      # @param resource [Resource] Parent resource
+      # @param new_resource [Resource] Skill resource to validate
+      # @param skill [Hash] Skill data
+      # @return [Resource] Updated resource
+      #
+      def validate_and_update_skill(resource, new_resource, skill)
+        skill_file = File.join(resource.local_path, skill[:folder_path], "SKILL.md")
+        result = SkillValidator.validate(skill_file)
+
+        Resource.from_h(
+          new_resource.to_h.merge(
+            validation_status: result[:valid] ? :valid_skill : :invalid_skill,
+            validation_errors: result[:errors]
+          ),
+          storage_path: storage_path
+        )
+      end
+    end
+  end
+end

data/lib/agents_skill_vault/vault/resource_validator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module AgentsSkillVault
+  class Vault
+    # Module for validating resources in vault.
+    #
+    module ResourceValidator
+      # Validates a specific resource.
+      #
+      # Re-validates the skill file and updates the validation status.
+      #
+      # @param label [String] The label of the resource to validate
+      # @return [Resource] The updated resource
+      # @raise [Errors::NotFound] if the resource doesn't exist
+      #
+      def validate_resource(label)
+        resource = fetch(label)
+
+        updated_resource = if resource.is_skill
+                             validate_skill_resource(resource)
+                           else
+                             Resource.from_h(
+                               resource.to_h.merge(validation_status: :not_a_skill),
+                               storage_path: storage_path
+                             )
+                           end
+
+        manifest.update_resource(updated_resource)
+        updated_resource
+      end
+
+      # Validates all resources in the vault.
+      #
+      # Re-validates all resources and updates their validation status.
+      #
+      # @return [Hash] Summary of validation results
+      #   - :valid [Integer] Count of valid skills
+      #   - :invalid [Integer] Count of invalid skills
+      #   - :not_a_skill [Integer] Count of non-skill resources
+      #   - :unvalidated [Integer] Count of resources that couldn't be validated
+      #
+      def validate_all
+        results = { valid: 0, invalid: 0, not_a_skill: 0, unvalidated: 0 }
+
+        list.each do |resource|
+          validate_resource(resource.label)
+
+          case resource.validation_status
+          when :valid_skill
+            results[:valid] += 1
+          when :invalid_skill
+            results[:invalid] += 1
+          when :not_a_skill
+            results[:not_a_skill] += 1
+          else
+            results[:unvalidated] += 1
+          end
+        end
+
+        results
+      end
+
+      # Removes all invalid skills from the vault.
+      #
+      # Deletes local files and removes from manifest for all resources with
+      # validation_status == :invalid_skill.
+      #
+      # @return [Integer] Number of skills removed
+      #
+      def cleanup_invalid_skills
+        invalid_resources = list_invalid_skills
+
+        invalid_resources.each do |resource|
+          FileUtils.rm_rf(resource.local_path) if resource.local_path
+          manifest.remove_resource(resource.label)
+        end
+
+        invalid_resources.size
+      end
+
+      private
+
+      # Validates a skill resource.
+      #
+      # @param resource [Resource] Skill resource to validate
+      # @return [Resource] Updated resource
+      #
+      def validate_skill_resource(resource)
+        skill_file = File.join(resource.local_path, "SKILL.md")
+        result = SkillValidator.validate(skill_file)
+
+        Resource.from_h(
+          resource.to_h.merge(
+            validation_status: result[:valid] ? :valid_skill : :invalid_skill,
+            validation_errors: result[:errors]
+          ),
+          storage_path: storage_path
+        )
+      end
+    end
+  end
+end