agents_skill_vault 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b05e0650894ce571b50930b4aac065e83d6581483a0598f16e013438b6072b90
-  data.tar.gz: d4eb75579062ff3f3b40b3c4a86afc73a5ff09a032507c4197ee84719eb328c4
+  metadata.gz: b339666f25ca1e000fff3b11d41645fa5bbab46427c90c80c7cae4b12642558e
+  data.tar.gz: 72692513935d521f5e478775eacd31a1e3cc79850f2b1381756671345ff0c06e
 SHA512:
-  metadata.gz: 83157f20b44848507c3704957254d7fa7498054aeafdfdff1c3d1e59f465f2e2bee67b3c9b4f9aa35b2723e56331479695b5ac936378ea21ca9303ef14693d33
-  data.tar.gz: 4735da42f45aebb580afd1cb9cd205bf09260b6e80e8196f8afb5d9626edd2004a2c6c3397efe55763b2847719b556d7ecf8acc0c003baaddc3c27ae933f2b31
+  metadata.gz: c4fe6bd713ef790c672b153cf57b4297dbad448d52c2534a6ed50ee685a4d568c451edd66f774b00f1af502a79417d39d6bd1f605901e42ec732630302d85d6d
+  data.tar.gz: c53947f7a8f7aaea9ca83b1b382d18dfa238149110d4c93b71aefb3599b96cbebdfd18fdc7dbe6885a508747de3c5433a2da1f035004e946b616a88b8d43f13d

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-01-29
+
+### Breaking Changes
+
+- Renamed `UrlParser::ParseResult#is_skill_file?` to `skill_file?` (follows Ruby naming conventions)
+
+### Refactoring
+
+- Decomposed `Vault` class into 4 included modules:
+  - `Vault::ResourceAdder` - resource addition logic
+  - `Vault::ResourceSyncer` - resource sync logic
+  - `Vault::ResourceValidator` - resource validation logic
+  - `Vault::ManifestOperations` - manifest import/export operations
+- Reduced `Vault` class from 450 to ~150 lines
+- Extracted helper methods to keep all methods under 20 lines
+- Reduced `Resource#initialize` parameter count from 15 to 11 using `**validation_attrs` splat
+- Simplified `Resource#==` method using `equality_attributes` helper
+- Extracted `Resource.from_h` logic into `extract_core_attrs` and `extract_validation_attrs` helpers
+- Refactored `SkillValidator.validate` method by extracting `build_skill_data` and `validate_fields` helpers
+- Split `UrlParser.parse_path_segments` into smaller methods: `parse_tree_segments`, `parse_blob_segments`, `default_path_data`, `parse_skill_file_segments`
+
+### Code Quality
+
+- All 33 RuboCop offenses resolved (0 remaining)
+- All methods under 20 lines (excl. tests)
+- All classes under 150 lines (excl. tests)
+- Reduced parameter counts to meet style guidelines
+
+## [0.1.0] - 2026-01-25
+
 ## [0.1.0] - 2026-01-25
 
 ### Features

data/lib/agents_skill_vault/manifest.rb

@@ -92,7 +92,7 @@ module AgentsSkillVault
     # @param resource [Resource] The resource with updated attributes
     # @return [Boolean] true if the resource was found and updated, false otherwise
     #
-    def update_resource(resource)
+    def update_resource(resource) # rubocop:disable Naming/PredicateMethod
       data = load
       data[:resources] ||= []
       index = data[:resources].find_index { |r| r[:label] == resource.label }

data/lib/agents_skill_vault/resource.rb

@@ -78,14 +78,14 @@ module AgentsSkillVault
     # @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
+    # @param validation_attrs [Hash] Validation-related attributes
+    # @option validation_attrs [Symbol] :validation_status Validation status (default: :unvalidated)
+    # @option validation_attrs [Array] :validation_errors Validation errors (default: [])
+    # @option validation_attrs [String] :skill_name The name of the skill (default: nil)
+    # @option validation_attrs [Boolean] :is_skill Whether this is a skill (default: derived from skill_name)
     #
     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)
+                   relative_path: nil, added_at: nil, synced_at: nil, **validation_attrs)
       @label = label
       @url = url
       @username = username
@@ -97,10 +97,10 @@ module AgentsSkillVault
       @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
+      @validation_status = validation_attrs.fetch(:validation_status, :unvalidated)
+      @validation_errors = validation_attrs.fetch(:validation_errors, [])
+      @skill_name = validation_attrs[:skill_name]
+      @is_skill = validation_attrs.fetch(:is_skill, !@skill_name.nil?)
     end
 
     # Returns the local filesystem path where the resource is stored.
@@ -155,18 +155,16 @@ module AgentsSkillVault
     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
+      equality_attributes.all? { |attr| public_send(attr) == other.public_send(attr) }
+    end
+
+    # Returns list of attributes used for equality comparison.
+    #
+    # @return [Array<Symbol>] Attribute names to compare
+    #
+    def equality_attributes
+      %i[label url username repo folder type branch relative_path
+         validation_status validation_errors skill_name is_skill]
     end
 
     # Creates a Resource from a hash.
@@ -182,19 +180,16 @@ module AgentsSkillVault
     #   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(**extract_core_attrs(hash), **extract_validation_attrs(hash), storage_path:)
+    end
 
-      new(
+    # Extracts core resource attributes from a hash.
+    #
+    # @param hash [Hash] Resource attributes as a hash
+    # @return [Hash] Core attributes with proper defaults
+    #
+    private_class_method def self.extract_core_attrs(hash)
+      {
         label: hash[:label] || hash["label"],
         url: hash[:url] || hash["url"],
         username: hash[:username] || hash["username"],
@@ -202,15 +197,37 @@ module AgentsSkillVault
         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"],
+        relative_path: extract_relative_path(hash),
         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:
-      )
+        synced_at: parse_time(hash[:synced_at] || hash["synced_at"])
+      }
+    end
+
+    # Extracts relative path with backward compatibility.
+    #
+    # @param hash [Hash] Resource attributes
+    # @return [String, nil] Relative path
+    #
+    private_class_method def self.extract_relative_path(hash)
+      hash[:relative_path] || hash["relative_path"] || hash["path_in_repo"] || hash["path_in_repo"]
+    end
+
+    # Extracts validation-related attributes from a hash with backward compatibility.
+    #
+    # @param hash [Hash] Resource attributes as a hash
+    # @return [Hash] Validation attributes with proper defaults
+    #
+    private_class_method def self.extract_validation_attrs(hash)
+      validation_status = hash[:validation_status] || hash["validation_status"] || :unvalidated
+      validation_status = validation_status.to_sym if validation_status.is_a?(String)
+
+      is_skill = hash[:is_skill] || hash["is_skill"]
+      skill_name = hash[:skill_name] || hash["skill_name"]
+      is_skill ||= !skill_name.nil?
+
+      validation_errors = hash[:validation_errors] || hash["validation_errors"] || []
+
+      { validation_status:, skill_name:, is_skill:, validation_errors: }
     end
 
     # Parses a time value from various formats.

data/lib/agents_skill_vault/skill_validator.rb

@@ -62,29 +62,9 @@ module AgentsSkillVault
       parsed_data = parse_yaml(frontmatter, errors)
       return { valid: false, errors:, skill_data: {} } if parsed_data.nil?
 
-      # Validate required fields
-      validate_required_fields(parsed_data, errors)
-
-      # Validate name field
-      validate_name(parsed_data, errors) if parsed_data["name"]
-
-      # Validate description field
-      validate_description(parsed_data, errors) if parsed_data["description"]
-
-      # Validate optional fields if present
-      validate_optional_fields(parsed_data, errors)
-
-      # Build skill data hash
-      skill_data = {
-        name: parsed_data["name"],
-        description: parsed_data["description"],
-        license: parsed_data["license"],
-        compatibility: parsed_data["compatibility"],
-        metadata: parsed_data["metadata"],
-        allowed_tools: parsed_data["allowed-tools"]
-      }
+      validate_fields(parsed_data, errors)
 
-      { valid: errors.empty?, errors:, skill_data: }
+      { valid: errors.empty?, errors:, skill_data: build_skill_data(parsed_data) }
     end
 
     # Extracts YAML frontmatter from content.
@@ -144,7 +124,8 @@ module AgentsSkillVault
 
       return if name.match?(NAME_PATTERN)
 
-      errors << "Field 'name' must contain only lowercase letters, numbers, and hyphens (no consecutive or leading/trailing hyphens)"
+      errors << "Field 'name' must contain only lowercase letters, numbers, and hyphens " \
+                "(no consecutive or leading/trailing hyphens)"
     end
 
     # Validates the description field.
@@ -197,5 +178,33 @@ module AgentsSkillVault
 
       errors << "Field 'allowed-tools' must be a string"
     end
+
+    # Validates all fields for the parsed data.
+    #
+    # @param data [Hash] Parsed YAML data
+    # @param errors [Array] Array to append errors to
+    #
+    def self.validate_fields(data, errors)
+      validate_required_fields(data, errors)
+      validate_name(data, errors) if data["name"]
+      validate_description(data, errors) if data["description"]
+      validate_optional_fields(data, errors)
+    end
+
+    # Builds skill data hash from parsed YAML.
+    #
+    # @param data [Hash] Parsed YAML data
+    # @return [Hash] Skill data with symbolized keys
+    #
+    def self.build_skill_data(data)
+      {
+        name: data["name"],
+        description: data["description"],
+        license: data["license"],
+        compatibility: data["compatibility"],
+        metadata: data["metadata"],
+        allowed_tools: data["allowed-tools"]
+      }
+    end
   end
 end

data/lib/agents_skill_vault/url_parser.rb

@@ -82,7 +82,7 @@ module AgentsSkillVault
       def label
         if type == :repo
           "#{username}/#{repo}"
-        elsif is_skill_file?
+        elsif skill_file?
           "#{username}/#{repo}/#{skill_name}"
         else
           parts = relative_path&.split("/") || []
@@ -95,7 +95,7 @@ module AgentsSkillVault
       #
       # @return [Boolean] true if this is a SKILL.md file URL
       #
-      def is_skill_file?
+      def skill_file?
         type == :file && skill_name && !skill_name.empty?
       end
     end
@@ -156,52 +156,81 @@ module AgentsSkillVault
     # @return [PathSegmentsData] Structured data with type, branch, and relative_path
     #
     private_class_method def self.parse_path_segments(segments)
-      if segments.length <= 2
-        return PathSegmentsData.new(type: :repo, branch: "main", relative_path: nil, skill_name: nil,
-                                    skill_folder_path: nil)
-      end
+      return default_path_data if segments.length <= 2
 
       case segments[2]
-      when "tree"
-        branch = segments[3] || "main"
-        path_parts = segments[4..] || []
-        if path_parts.empty?
-          PathSegmentsData.new(type: :repo, branch: branch, relative_path: nil, skill_name: nil, skill_folder_path: nil)
-        else
-          PathSegmentsData.new(type: :folder, branch: branch, relative_path: path_parts.join("/"), skill_name: nil,
-                               skill_folder_path: nil)
-        end
-      when "blob"
-        branch = segments[3] || "main"
-        path_parts = segments[4..] || []
-        relative_path = path_parts.join("/")
-
-        # Check if this is a SKILL.md file
-        filename = path_parts.last
-        if filename == "SKILL.md"
-          # Extract skill name from parent folder
-          if path_parts.length >= 2
-            skill_name = path_parts[-2]
-            skill_folder_path = path_parts[0..-2].join("/")
-          else
-            # SKILL.md is at root, use repo name as skill name
-            skill_name = segments[1]
-            skill_folder_path = "."
-          end
-
-          PathSegmentsData.new(
-            type: :file,
-            branch: branch,
-            relative_path:,
-            skill_name:,
-            skill_folder_path:
-          )
-        else
-          PathSegmentsData.new(type: :file, branch: branch, relative_path:, skill_name: nil, skill_folder_path: nil)
-        end
+      when "tree" then parse_tree_segments(segments)
+      when "blob" then parse_blob_segments(segments)
+      else default_path_data
+      end
+    end
+
+    # Returns the default PathSegmentsData for a repository URL.
+    #
+    # @return [PathSegmentsData] Default path data
+    #
+    private_class_method def self.default_path_data
+      PathSegmentsData.new(type: :repo, branch: "main", relative_path: nil, skill_name: nil, skill_folder_path: nil)
+    end
+
+    # Parses tree (folder) URL segments.
+    #
+    # @param segments [Array<String>] The split path segments
+    # @return [PathSegmentsData] Path data for tree URLs
+    #
+    private_class_method def self.parse_tree_segments(segments)
+      branch = segments[3] || "main"
+      path_parts = segments[4..] || []
+      if path_parts.empty?
+        PathSegmentsData.new(type: :repo, branch: branch, relative_path: nil, skill_name: nil, skill_folder_path: nil)
       else
-        PathSegmentsData.new(type: :repo, branch: "main", relative_path: nil, skill_name: nil, skill_folder_path: nil)
+        PathSegmentsData.new(type: :folder, branch: branch, relative_path: path_parts.join("/"), skill_name: nil,
+                             skill_folder_path: nil)
       end
     end
+
+    # Parses blob (file) URL segments.
+    #
+    # @param segments [Array<String>] The split path segments
+    # @return [PathSegmentsData] Path data for blob URLs
+    #
+    private_class_method def self.parse_blob_segments(segments)
+      branch = segments[3] || "main"
+      path_parts = segments[4..] || []
+      relative_path = path_parts.join("/")
+      filename = path_parts.last
+
+      if filename == "SKILL.md"
+        parse_skill_file_segments(segments, branch, path_parts, relative_path)
+      else
+        PathSegmentsData.new(type: :file, branch: branch, relative_path:, skill_name: nil, skill_folder_path: nil)
+      end
+    end
+
+    # Parses SKILL.md file segments to extract skill name and folder path.
+    #
+    # @param segments [Array<String>] The split path segments
+    # @param branch [String] Branch name
+    # @param path_parts [Array<String>] Path parts after branch
+    # @param relative_path [String] Full relative path
+    # @return [PathSegmentsData] Path data for SKILL.md files
+    #
+    private_class_method def self.parse_skill_file_segments(segments, branch, path_parts, relative_path)
+      if path_parts.length >= 2
+        skill_name = path_parts[-2]
+        skill_folder_path = path_parts[0..-2].join("/")
+      else
+        skill_name = segments[1]
+        skill_folder_path = "."
+      end
+
+      PathSegmentsData.new(
+        type: :file,
+        branch: branch,
+        relative_path:,
+        skill_name:,
+        skill_folder_path:
+      )
+    end
   end
 end

data/lib/agents_skill_vault/vault/manifest_operations.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module AgentsSkillVault
+  class Vault
+    # Module for manifest operations in vault.
+    #
+    module ManifestOperations
+      # Exports manifest to a file for backup or sharing.
+      #
+      # @param export_path [String] Path where manifest should be exported
+      # @return [void]
+      #
+      # @example
+      #   vault.export_manifest("/backups/manifest.json")
+      #
+      def export_manifest(export_path)
+        FileUtils.cp(@manifest_path, export_path)
+      end
+
+      # Imports and merges a manifest from another vault.
+      #
+      # Resources from imported manifest are merged with existing resources.
+      # If a label exists in both, imported resource overwrites existing one.
+      # Note: This only updates manifest; files are not downloaded automatically.
+      #
+      # @param import_path [String] Path to manifest file to import
+      # @return [void]
+      #
+      # @example
+      #   vault.import_manifest("/shared/manifest.json")
+      #   vault.redownload_all  # Download imported resources
+      #
+      def import_manifest(import_path)
+        imported_data = JSON.parse(File.read(import_path), symbolize_names: true)
+        current_data = manifest.load
+
+        merged_resources = merge_resources(current_data[:resources] || [], imported_data[:resources] || [])
+
+        manifest.save(version: Manifest::VERSION, resources: merged_resources)
+      end
+
+      # Re-downloads all resources from scratch.
+      #
+      # Deletes local files and performs a fresh clone/checkout for each resource.
+      # Useful for recovering from corruption or ensuring a clean state.
+      #
+      # @return [void]
+      #
+      def redownload_all
+        list.each do |resource|
+          FileUtils.rm_rf(resource.local_path) if resource.local_path
+          download_resource(resource)
+          updated_resource = Resource.from_h(resource.to_h.merge(synced_at: Time.now), storage_path: storage_path)
+          manifest.update_resource(updated_resource)
+        end
+      end
+
+      private
+
+      # Merges current and imported resources.
+      #
+      # @param current_resources [Array<Hash>] Current resource hashes
+      # @param imported_resources [Array<Hash>] Imported resource hashes
+      # @return [Array<Hash>] Merged resources
+      #
+      def merge_resources(current_resources, imported_resources)
+        merged = current_resources.dup
+
+        imported_resources.each do |imported|
+          existing_index = merged.find_index { |r| r[:label] == imported[:label] }
+
+          if existing_index
+            merged[existing_index] = imported
+          else
+            merged << imported
+          end
+        end
+
+        merged
+      end
+    end
+  end
+end