agents_skill_vault 0.1.0

data/lib/agents_skill_vault/skill_validator.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module AgentsSkillVault
+  # Validates SKILL.md files against the Agent Skills specification.
+  #
+  # Checks for required fields, field formats, and constraints.
+  #
+  # @example Validate a skill file
+  #   result = SkillValidator.validate("/path/to/SKILL.md")
+  #   if result[:valid]
+  #     puts "Valid skill: #{result[:skill_data][:name]}"
+  #   else
+  #     puts "Errors: #{result[:errors].join(', ')}"
+  #   end
+  #
+  class SkillValidator
+    REQUIRED_FIELDS = %w[name description].freeze
+    NAME_MAX_LENGTH = 64
+    NAME_MIN_LENGTH = 1
+    DESCRIPTION_MAX_LENGTH = 1024
+    DESCRIPTION_MIN_LENGTH = 1
+    COMPATIBILITY_MAX_LENGTH = 500
+    NAME_PATTERN = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+
+    # Validates a SKILL.md file.
+    #
+    # @param skill_file_path [String] Path to the SKILL.md file
+    # @return [Hash] Validation result with keys:
+    #   - :valid [Boolean] Whether the skill is valid
+    #   - :errors [Array<String>] List of validation errors
+    #   - :skill_data [Hash] Parsed skill data (name, description, license, etc.)
+    #
+    # @raise [ArgumentError] if skill_file_path is nil or empty
+    #
+    def self.validate(skill_file_path)
+      raise ArgumentError, "skill_file_path cannot be nil" if skill_file_path.nil?
+      raise ArgumentError, "skill_file_path cannot be empty" if skill_file_path.empty?
+
+      errors = []
+
+      # Check file exists and is readable
+      unless File.exist?(skill_file_path)
+        return { valid: false, errors: ["File does not exist: #{skill_file_path}"], skill_data: {} }
+      end
+
+      unless File.readable?(skill_file_path)
+        return { valid: false, errors: ["File is not readable: #{skill_file_path}"], skill_data: {} }
+      end
+
+      content = File.read(skill_file_path)
+
+      # Parse YAML frontmatter
+      frontmatter, = extract_frontmatter(content)
+      if frontmatter.nil?
+        errors << "No YAML frontmatter found (missing '---' delimiters)"
+        return { valid: false, errors:, skill_data: {} }
+      end
+
+      # Parse YAML
+      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"]
+      }
+
+      { valid: errors.empty?, errors:, skill_data: }
+    end
+
+    # Extracts YAML frontmatter from content.
+    #
+    # @param content [String] The full content of the file
+    # @return [Array<String, String>] Frontmatter and body, or [nil, nil] if not found
+    #
+    def self.extract_frontmatter(content)
+      return [nil, nil] unless content.start_with?("---")
+
+      parts = content.split(/^---\s*$/)
+      return [nil, nil] unless parts.length >= 2
+
+      [parts[1].strip, parts[2..]&.join("---")]
+    end
+
+    # Parses YAML string.
+    #
+    # @param yaml_string [String] The YAML string to parse
+    # @param errors [Array] Array to append errors to
+    # @return [Hash, nil] Parsed data, or nil if parsing fails
+    #
+    def self.parse_yaml(yaml_string, errors)
+      YAML.safe_load(yaml_string)
+    rescue Psych::SyntaxError => e
+      errors << "Invalid YAML syntax: #{e.message}"
+      nil
+    end
+
+    # Validates that all required fields are present.
+    #
+    # @param data [Hash] Parsed YAML data
+    # @param errors [Array] Array to append errors to
+    #
+    def self.validate_required_fields(data, errors)
+      REQUIRED_FIELDS.each do |field|
+        errors << "Required field '#{field}' is missing" unless data[field]
+      end
+    end
+
+    # Validates the name field.
+    #
+    # @param data [Hash] Parsed YAML data
+    # @param errors [Array] Array to append errors to
+    #
+    def self.validate_name(data, errors)
+      name = data["name"]
+
+      if name.empty?
+        errors << "Field 'name' cannot be empty"
+        return
+      end
+
+      errors << "Field 'name' exceeds maximum length of #{NAME_MAX_LENGTH} characters" if name.length > NAME_MAX_LENGTH
+
+      errors << "Field 'name' must be at least #{NAME_MIN_LENGTH} character" if name.length < NAME_MIN_LENGTH
+
+      return if name.match?(NAME_PATTERN)
+
+      errors << "Field 'name' must contain only lowercase letters, numbers, and hyphens (no consecutive or leading/trailing hyphens)"
+    end
+
+    # Validates the description field.
+    #
+    # @param data [Hash] Parsed YAML data
+    # @param errors [Array] Array to append errors to
+    #
+    def self.validate_description(data, errors)
+      description = data["description"]
+
+      if description.empty?
+        errors << "Field 'description' cannot be empty"
+        return
+      end
+
+      if description.length > DESCRIPTION_MAX_LENGTH
+        errors << "Field 'description' exceeds maximum length of #{DESCRIPTION_MAX_LENGTH} characters"
+      end
+
+      return unless description.length < DESCRIPTION_MIN_LENGTH
+
+      errors << "Field 'description' must be at least #{DESCRIPTION_MIN_LENGTH} character"
+    end
+
+    # Validates optional fields if present.
+    #
+    # @param data [Hash] Parsed YAML data
+    # @param errors [Array] Array to append errors to
+    #
+    def self.validate_optional_fields(data, errors)
+      # Validate compatibility field if present
+      if data["compatibility"]
+        compatibility = data["compatibility"]
+        if compatibility.length > COMPATIBILITY_MAX_LENGTH
+          errors << "Field 'compatibility' exceeds maximum length of #{COMPATIBILITY_MAX_LENGTH} characters"
+        end
+      end
+
+      # Validate metadata field if present
+      if data["metadata"]
+        metadata = data["metadata"]
+        errors << "Field 'metadata' must be a hash/object" unless metadata.is_a?(Hash)
+      end
+
+      # Validate allowed-tools field if present
+      return unless data["allowed-tools"]
+
+      allowed_tools = data["allowed-tools"]
+      return if allowed_tools.is_a?(String)
+
+      errors << "Field 'allowed-tools' must be a string"
+    end
+  end
+end

data/lib/agents_skill_vault/sync_result.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module AgentsSkillVault
+  # Immutable result object representing the outcome of a sync operation.
+  #
+  # Uses Ruby 3.2+ Data.define for a clean, immutable value object.
+  #
+  # @example Successful sync with changes
+  #   result = SyncResult.new(success: true, changes: true)
+  #   result.success?  # => true
+  #   result.changes?  # => true
+  #
+  # @example Failed sync
+  #   result = SyncResult.new(success: false, error: "Network error")
+  #   result.success?  # => false
+  #   result.error     # => "Network error"
+  #
+  # @!attribute [r] success
+  #   @return [Boolean] Whether the sync operation succeeded
+  #
+  # @!attribute [r] changes
+  #   @return [Boolean] Whether the sync resulted in changes (default: false)
+  #
+  # @!attribute [r] error
+  #   @return [String, nil] Error message if sync failed (default: nil)
+  #
+  SyncResult = Data.define(:success, :changes, :error) do
+    # Creates a new SyncResult with sensible defaults.
+    #
+    # @param success [Boolean] Whether the sync succeeded
+    # @param changes [Boolean] Whether changes occurred (default: false)
+    # @param error [String, nil] Error message if failed (default: nil)
+    #
+    def initialize(success:, changes: false, error: nil)
+      super
+    end
+
+    # @return [Boolean] Whether the sync operation succeeded
+    def success? = success
+
+    # @return [Boolean] Whether the sync resulted in changes
+    def changes? = changes
+  end
+end

data/lib/agents_skill_vault/url_parser.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "addressable/uri"
+
+module AgentsSkillVault
+  # Parses GitHub URLs into their component parts.
+  #
+  # Supports repository URLs, folder URLs (tree), and file URLs (blob).
+  #
+  # @example Parse a repository URL
+  #   result = UrlParser.parse("https://github.com/user/repo")
+  #   result.username    # => "user"
+  #   result.repo        # => "repo"
+  #   result.type        # => :repo
+  #
+  # @example Parse a folder URL
+  #   result = UrlParser.parse("https://github.com/user/repo/tree/main/lib/skills")
+  #   result.type           # => :folder
+  #   result.relative_path  # => "lib/skills"
+  #
+  class UrlParser
+    GITHUB_HOST = "github.com"
+
+    # Data object for parsed path segments
+    PathSegmentsData = Data.define(:type, :branch, :relative_path, :skill_name, :skill_folder_path)
+
+    # Result object returned by UrlParser.parse
+    #
+    # Contains the parsed components of a GitHub URL.
+    #
+    class ParseResult
+      # @return [String] GitHub username or organization
+      attr_reader :username
+
+      # @return [String] Repository name
+      attr_reader :repo
+
+      # @return [String] Branch name (defaults to "main")
+      attr_reader :branch
+
+      # @return [String, nil] Path within the repository (for folder/file URLs)
+      attr_reader :relative_path
+
+      # @return [Symbol] Type of URL (:repo, :folder, or :file)
+      attr_reader :type
+
+      # @return [String, nil] The name of the skill (for SKILL.md file URLs)
+      attr_reader :skill_name
+
+      # @return [String, nil] The full path to the skill folder (for SKILL.md file URLs)
+      attr_reader :skill_folder_path
+
+      # Creates a new ParseResult.
+      #
+      # @param username [String] GitHub username
+      # @param repo [String] Repository name
+      # @param type [Symbol] URL type (:repo, :folder, or :file)
+      # @param branch [String] Branch name (default: "main")
+      # @param relative_path [String, nil] Path within repository
+      # @param skill_name [String, nil] The name of the skill (for SKILL.md files)
+      # @param skill_folder_path [String, nil] Full path to skill folder (for SKILL.md files)
+      #
+      def initialize(username:, repo:, type:, branch: "main", relative_path: nil, skill_name: nil,
+                     skill_folder_path: nil)
+        @username = username
+        @repo = repo
+        @branch = branch
+        @relative_path = relative_path
+        @type = type
+        @skill_name = skill_name
+        @skill_folder_path = skill_folder_path
+      end
+
+      # Generates a default label for this URL.
+      #
+      # For repositories: "username/repo"
+      # For SKILL.md files: "username/skill-name"
+      # For other folders/files: "username/last-path-component"
+      #
+      # @return [String] Generated label
+      #
+      def label
+        if type == :repo
+          "#{username}/#{repo}"
+        elsif is_skill_file?
+          "#{username}/#{repo}/#{skill_name}"
+        else
+          parts = relative_path&.split("/") || []
+          folder = parts.last
+          "#{username}/#{repo}/#{folder}"
+        end
+      end
+
+      # Checks if this URL points to a SKILL.md file.
+      #
+      # @return [Boolean] true if this is a SKILL.md file URL
+      #
+      def is_skill_file?
+        type == :file && skill_name && !skill_name.empty?
+      end
+    end
+
+    # Parses a GitHub URL into its components.
+    #
+    # Uses Addressable::URI for robust URL parsing with proper encoding/decoding.
+    #
+    # @param url [String] A GitHub URL (repository, tree, or blob)
+    # @return [ParseResult] Parsed URL components
+    # @raise [Errors::InvalidUrl] if the URL is not a valid GitHub URL
+    #
+    # @example Parse different URL types
+    #   UrlParser.parse("https://github.com/user/repo")
+    #   UrlParser.parse("https://github.com/user/repo/tree/main/folder")
+    #   UrlParser.parse("https://github.com/user/repo/blob/main/file.rb")
+    #
+    # @example Parse URL with encoded characters
+    #   result = UrlParser.parse("https://github.com/user/repo/tree/main/folder%20name")
+    #   result.relative_path  # => "folder name"
+    #
+    def self.parse(url)
+      uri = Addressable::URI.parse(url)
+      validate_github_url!(uri, url)
+
+      segments = uri.path.sub(%r{^/}, "").split("/").map { |s| Addressable::URI.unencode(s) }
+      username = segments[0]
+      repo = segments[1]
+
+      path_data = parse_path_segments(segments)
+
+      ParseResult.new(
+        username: username,
+        repo: repo,
+        branch: path_data.branch,
+        relative_path: path_data.relative_path,
+        type: path_data.type,
+        skill_name: path_data.skill_name,
+        skill_folder_path: path_data.skill_folder_path
+      )
+    end
+
+    # Validates that the URI is a GitHub URL with http or https scheme.
+    #
+    # @param uri [Addressable::URI, nil] The parsed URI
+    # @param original_url [String] The original URL string for error messages
+    # @raise [Errors::InvalidUrl] if the URL is not a valid GitHub URL
+    #
+    private_class_method def self.validate_github_url!(uri, original_url)
+      return if uri&.host == GITHUB_HOST && %w[http https].include?(uri&.scheme)
+
+      raise Errors::InvalidUrl, "Invalid GitHub URL: #{original_url}. Expected format: https://github.com/username/repo[/tree/branch/path]"
+    end
+
+    # Parses URL path segments to determine URL type, branch, and relative path.
+    #
+    # @param segments [Array<String>] The split path segments
+    # @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
+
+      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
+      else
+        PathSegmentsData.new(type: :repo, branch: "main", relative_path: nil, skill_name: nil, skill_folder_path: nil)
+      end
+    end
+  end
+end