openclacky 0.6.1 → 0.6.3

data/lib/clacky/skill.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Clacky
+  # Represents a skill with its metadata and content.
+  # A skill is defined by a SKILL.md file with optional YAML frontmatter.
+  class Skill
+    # Frontmatter fields that are recognized
+    FRONTMATTER_FIELDS = %w[
+      name
+      description
+      disable-model-invocation
+      user-invocable
+      allowed-tools
+      context
+      agent
+      argument-hint
+      hooks
+    ].freeze
+
+    attr_reader :directory, :frontmatter, :source_path
+    attr_reader :name, :description, :content
+    attr_reader :disable_model_invocation, :user_invocable
+    attr_reader :allowed_tools, :context, :agent_type, :argument_hint, :hooks
+
+    # @param directory [Pathname, String] Path to the skill directory
+    # @param source_path [Pathname, String, nil] Optional source path for priority resolution
+    def initialize(directory, source_path: nil)
+      @directory = Pathname.new(directory)
+      @source_path = source_path ? Pathname.new(source_path) : @directory
+
+      load_skill
+    end
+
+    # Get the skill identifier (uses name from frontmatter or directory name)
+    # @return [String]
+    def identifier
+      @name || @directory.basename.to_s
+    end
+
+    # Check if skill can be invoked by user via slash command
+    # @return [Boolean]
+    def user_invocable?
+      @user_invocable.nil? || @user_invocable
+    end
+
+    # Check if skill can be automatically invoked by the model
+    # @return [Boolean]
+    def model_invocation_allowed?
+      !@disable_model_invocation
+    end
+
+    # Check if skill runs in a forked subagent context
+    # @return [Boolean]
+    def forked_context?
+      @context == "fork"
+    end
+
+    # Get the slash command for this skill
+    # @return [String] e.g., "/explain-code"
+    def slash_command
+      "/#{identifier}"
+    end
+
+    # Get the description for context loading
+    # Returns the description from frontmatter, or first paragraph of content
+    # @return [String]
+    def context_description
+      @description || extract_first_paragraph
+    end
+
+    # Get all supporting files in the skill directory (excluding SKILL.md)
+    # @return [Array<Pathname>]
+    def supporting_files
+      return [] unless @directory.exist?
+
+      @directory.children.reject { |p| p.basename.to_s == "SKILL.md" }
+    end
+
+    # Check if this skill has supporting files
+    # @return [Boolean]
+    def has_supporting_files?
+      supporting_files.any?
+    end
+
+    # Process the skill content with argument substitution
+    # @param arguments [String] Arguments passed to the skill
+    # @param shell_output [Hash] Shell command outputs for !command` syntax (optional)
+    # @return [String] Processed content
+    def process_content(arguments = "", shell_output: {})
+      processed_content = @content.dup
+
+      # Replace argument placeholders
+      processed_content = substitute_arguments(processed_content, arguments)
+
+      # Replace shell command outputs
+      shell_output.each do |command, output|
+        placeholder = "!`#{command}`"
+        processed_content.gsub!(placeholder, output.to_s)
+      end
+
+      processed_content
+    end
+
+    # Convert to a hash representation
+    # @return [Hash]
+    def to_h
+      {
+        name: identifier,
+        description: context_description,
+        directory: @directory.to_s,
+        source_path: @source_path.to_s,
+        user_invocable: user_invocable?,
+        model_invocation_allowed: model_invocation_allowed?,
+        forked_context: forked_context?,
+        allowed_tools: @allowed_tools,
+        argument_hint: @argument_hint,
+        content_length: @content.length
+      }
+    end
+
+    # Load content of a supporting file
+    # @param filename [String] Relative path from skill directory
+    # @return [String, nil] File contents or nil if not found
+    def read_supporting_file(filename)
+      file_path = @directory.join(filename)
+      file_path.exist? ? file_path.read : nil
+    end
+
+    private
+
+    def load_skill
+      skill_file = @directory.join("SKILL.md")
+
+      unless skill_file.exist?
+        raise Clacky::Error, "SKILL.md not found in skill directory: #{@directory}"
+      end
+
+      content = skill_file.read
+
+      # Parse frontmatter if present
+      if content.start_with?("---")
+        parse_frontmatter(content)
+      else
+        @frontmatter = {}
+        @content = content
+      end
+
+      # Set defaults
+      @user_invocable = true if @user_invocable.nil?
+      @disable_model_invocation = false if @disable_model_invocation.nil?
+
+      validate_frontmatter
+    end
+
+    def parse_frontmatter(content)
+      # Extract frontmatter between first and second "---"
+      frontmatter_match = content.match(/^---\n(.*?)\n---/m)
+
+      unless frontmatter_match
+        raise Clacky::Error, "Invalid frontmatter format in SKILL.md: missing closing ---"
+      end
+
+      yaml_content = frontmatter_match[1]
+      @frontmatter = YAML.safe_load(yaml_content) || {}
+
+      # Extract content after frontmatter
+      @content = content[frontmatter_match.end(0)..-1].to_s.strip
+
+      # Extract fields from frontmatter
+      @name = @frontmatter["name"]
+      @description = @frontmatter["description"]
+      @disable_model_invocation = @frontmatter["disable-model-invocation"]
+      @user_invocable = @frontmatter["user-invocable"]
+      @allowed_tools = @frontmatter["allowed-tools"]
+      @context = @frontmatter["context"]
+      @agent_type = @frontmatter["agent"]
+      @argument_hint = @frontmatter["argument-hint"]
+      @hooks = @frontmatter["hooks"]
+    end
+
+    def validate_frontmatter
+      # Validate name if provided
+      if @name
+        unless @name.match?(/^[a-z0-9][a-z0-9-]*$/)
+          raise Clacky::Error,
+            "Invalid skill name '#{@name}'. Use lowercase letters, numbers, and hyphens only (max 64 chars)."
+        end
+        if @name.length > 64
+          raise Clacky::Error, "Skill name '#{@name}' exceeds 64 characters."
+        end
+      end
+
+      # Validate context
+      if @context && @context != "fork"
+        raise Clacky::Error, "Invalid context '#{@context}'. Only 'fork' is supported."
+      end
+
+      # Validate allowed-tools format
+      if @allowed_tools && !@allowed_tools.is_a?(Array)
+        raise Clacky::Error, "allowed-tools must be an array of tool names"
+      end
+    end
+
+    def extract_first_paragraph
+      @content.split(/\n\n/).first.to_s
+    end
+
+    def substitute_arguments(content, arguments)
+      # Parse arguments as shell words for indexed access
+      args_array = arguments.shellsplit
+
+      # Replace $ARGUMENTS with all arguments
+      result = content.gsub("$ARGUMENTS", arguments.to_s)
+
+      # Replace $ARGUMENTS[N] with specific argument
+      result.gsub!(/\$ARGUMENTS\[(\d+)\]/) do
+        index = $1.to_i
+        args_array[index] || ""
+      end
+
+      # Replace $N shorthand ($0, $1, etc.)
+      result.gsub!(/\$([0-9]+)/) do
+        index = $1.to_i
+        args_array[index] || ""
+      end
+
+      # Replace ${CLAUDE_SESSION_ID} with empty string (session not available in current context)
+      result.gsub!(/\${CLAUDE_SESSION_ID}/, "")
+
+      result
+    end
+  end
+end

data/lib/clacky/skill_loader.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "fileutils"
+require "clacky"
+
+module Clacky
+  # Loader and registry for skills.
+  # Discovers skills from multiple locations and provides lookup functionality.
+  class SkillLoader
+    # Skill discovery locations (in priority order: lower index = lower priority)
+    LOCATIONS = [
+      :default,            # gem's built-in default skills (lowest priority)
+      :global_claude,      # ~/.claude/skills/ (compatibility)
+      :global_clacky,      # ~/.clacky/skills/
+      :project_claude,     # .claude/skills/ (project-level compatibility)
+      :project_clacky      # .clacky/skills/ (highest priority)
+    ].freeze
+
+    # Initialize the skill loader and automatically load all skills
+    # @param working_dir [String] Current working directory for project-level discovery
+    def initialize(working_dir = nil)
+      @working_dir = working_dir || Dir.pwd
+      @skills = {}           # Map identifier -> Skill
+      @skills_by_command = {} # Map slash_command -> Skill
+      @errors = []           # Store loading errors
+      @loaded_from = {}      # Track which location each skill was loaded from
+      
+      # Automatically load all skills on initialization
+      load_all
+    end
+
+    # Load all skills from configured locations
+    # Clears previously loaded skills before loading to ensure idempotency
+    # @return [Array<Skill>] Loaded skills
+    def load_all
+      # Clear existing skills to ensure idempotent reloading
+      clear
+      
+      load_default_skills
+      load_global_claude_skills
+      load_global_clacky_skills
+      load_project_claude_skills
+      load_project_clacky_skills
+
+      all_skills
+    end
+
+    # Load skills from ~/.claude/skills/ (lowest priority, compatibility)
+    # @return [Array<Skill>]
+    def load_global_claude_skills
+      global_claude_dir = Pathname.new(ENV.fetch("HOME", "~")).join(".claude", "skills")
+      load_skills_from_directory(global_claude_dir, :global_claude)
+    end
+
+    # Load skills from ~/.clacky/skills/ (user global)
+    # @return [Array<Skill>]
+    def load_global_clacky_skills
+      global_clacky_dir = Pathname.new(ENV.fetch("HOME", "~")).join(".clacky", "skills")
+      load_skills_from_directory(global_clacky_dir, :global_clacky)
+    end
+
+    # Load skills from .claude/skills/ (project-level compatibility)
+    # @return [Array<Skill>]
+    def load_project_claude_skills
+      project_claude_dir = Pathname.new(@working_dir).join(".claude", "skills")
+      load_skills_from_directory(project_claude_dir, :project_claude)
+    end
+
+    # Load skills from .clacky/skills/ (project-level, highest priority)
+    # @return [Array<Skill>]
+    def load_project_clacky_skills
+      project_clacky_dir = Pathname.new(@working_dir).join(".clacky", "skills")
+      load_skills_from_directory(project_clacky_dir, :project_clacky)
+    end
+
+    # Load skills from nested .claude/skills/ directories (monorepo support)
+    # @return [Array<Skill>]
+    def load_nested_project_skills
+      working_path = Pathname.new(@working_dir)
+
+      # Find all nested .claude/skills/ directories
+      nested_dirs = []
+      begin
+        Dir.glob("**/.claude/skills/", base: @working_dir).each do |relative_path|
+          nested_dirs << working_path.join(relative_path)
+        end
+      rescue ArgumentError
+        # Skip if working_dir contains special characters
+      end
+
+      # Filter out the main project .claude/skills/ (already loaded)
+      main_project_skills = working_path.join(".claude", "skills").realpath
+
+      nested_dirs.each do |dir|
+        next if dir.realpath == main_project_skills
+
+        # Determine the source path for priority resolution
+        # Use the parent directory of .claude as the source
+        source_path = dir.parent
+
+        # Determine skill identifier based on relative path from working_dir
+        relative_to_working = dir.relative_path_from(working_path).to_s
+        skill_name = relative_to_working.gsub(".claude/skills/", "").gsub("/", "-")
+
+        load_single_skill(dir, source_path, skill_name)
+      end
+    end
+
+    # Get all loaded skills
+    # @return [Array<Skill>]
+    def all_skills
+      @skills.values
+    end
+
+    # Get a skill by its identifier
+    # @param identifier [String] Skill name or directory name
+    # @return [Skill, nil]
+    def [](identifier)
+      @skills[identifier]
+    end
+
+    # Find a skill by its slash command
+    # @param command [String] e.g., "/explain-code"
+    # @return [Skill, nil]
+    def find_by_command(command)
+      @skills_by_command[command]
+    end
+
+    # Get skills that can be invoked by user
+    # @return [Array<Skill>]
+    def user_invocable_skills
+      all_skills.select(&:user_invocable?)
+    end
+
+    # Get the count of loaded skills
+    # @return [Integer]
+    def count
+      @skills.size
+    end
+
+    # Get loading errors
+    # @return [Array<String>]
+    def errors
+      @errors.dup
+    end
+
+    # Get the source location for each loaded skill
+    # @return [Hash{String => Symbol}] Map of skill identifier to source location
+    def loaded_from
+      @loaded_from.dup
+    end
+
+    # Clear loaded skills and errors
+    def clear
+      @skills.clear
+      @skills_by_command.clear
+      @errors.clear
+    end
+
+    # Create a new skill directory and SKILL.md file
+    # @param name [String] Skill name (will be used for directory and slash command)
+    # @param content [String] Skill content (SKILL.md body)
+    # @param description [String] Skill description
+    # @param location [Symbol] Where to create: :global or :project
+    # @return [Skill] The created skill
+    def create_skill(name, content, description = nil, location: :global)
+      # Validate name
+      unless name.match?(/^[a-z0-9][a-z0-9-]*$/)
+        raise Clacky::Error,
+          "Invalid skill name '#{name}'. Use lowercase letters, numbers, and hyphens only."
+      end
+
+      # Determine directory path
+      skill_dir = case location
+      when :global
+        Pathname.new(ENV.fetch("HOME", "~")).join(".clacky", "skills", name)
+      when :project
+        Pathname.new(@working_dir).join(".clacky", "skills", name)
+      else
+        raise Clacky::Error, "Unknown skill location: #{location}"
+      end
+
+      # Create directory if it doesn't exist
+      FileUtils.mkdir_p(skill_dir)
+
+      # Build frontmatter
+      frontmatter = { "name" => name, "description" => description }
+
+      # Write SKILL.md
+      skill_content = build_skill_content(frontmatter, content)
+      skill_file = skill_dir.join("SKILL.md")
+      skill_file.write(skill_content)
+
+      # Load the newly created skill
+      source_type = case location
+      when :global then :global_clacky
+      when :project then :project_clacky
+      else :global_clacky
+      end
+      load_single_skill(skill_dir, skill_dir, name, source_type)
+    end
+
+    # Delete a skill
+    # @param name [String] Skill name
+    # @return [Boolean] True if deleted, false if not found
+    def delete_skill(name)
+      skill = @skills[name]
+      return false unless skill
+
+      # Remove from registry
+      @skills.delete(name)
+      @skills_by_command.delete(skill.slash_command)
+
+      # Delete directory
+      FileUtils.rm_rf(skill.directory)
+
+      true
+    end
+
+    private
+
+    def load_skills_from_directory(dir, source_type)
+      return [] unless dir.exist?
+
+      skills = []
+      dir.children.select(&:directory?).each do |skill_dir|
+        source_path = case source_type
+        when :global_claude
+          Pathname.new(ENV.fetch("HOME", "~")).join(".claude")
+        when :global_clacky
+          Pathname.new(ENV.fetch("HOME", "~")).join(".clacky")
+        when :project_claude, :project_clacky
+          Pathname.new(@working_dir)
+        else
+          skill_dir
+        end
+
+        skill_name = skill_dir.basename.to_s
+        skill = load_single_skill(skill_dir, source_path, skill_name, source_type)
+        skills << skill if skill
+      end
+      skills
+    end
+
+    def load_single_skill(skill_dir, source_path, skill_name, source_type)
+      skill = Skill.new(skill_dir, source_path: source_path)
+
+      # Check for duplicate names
+      existing = @skills[skill.identifier]
+      if existing
+        # Skip duplicate (lower priority)
+        existing_source = @loaded_from[skill.identifier]
+        priority_order = [:global_claude, :global_clacky, :project_claude, :project_clacky]
+
+        if priority_order.index(source_type) > priority_order.index(existing_source)
+          # Replace with higher priority skill
+          @skills.delete(existing.identifier)
+          @skills_by_command.delete(existing.slash_command)
+          @loaded_from.delete(existing.identifier)
+        else
+          @errors << "Skipping duplicate skill '#{skill.identifier}' at #{skill_dir}"
+          return nil
+        end
+      end
+
+      # Register skill
+      @skills[skill.identifier] = skill
+      @skills_by_command[skill.slash_command] = skill
+      @loaded_from[skill.identifier] = source_type
+
+      skill
+    rescue Clacky::Error => e
+      @errors << "Error loading skill '#{skill_name}' from #{skill_dir}: #{e.message}"
+      nil
+    rescue StandardError => e
+      @errors << "Unexpected error loading skill '#{skill_name}' from #{skill_dir}: #{e.message}"
+      nil
+    end
+
+    def build_skill_content(frontmatter, content)
+      yaml = frontmatter
+        .reject { |_, v| v.nil? || v.to_s.empty? }
+        .to_yaml(line_width: 80)
+
+      "---\n#{yaml}---\n\n#{content}"
+    end
+
+    # Load default skills from gem's default_skills directory
+    private def load_default_skills
+      # Get the gem's lib directory
+      gem_lib_dir = File.expand_path("../", __dir__)
+      default_skills_dir = File.join(gem_lib_dir, "clacky", "default_skills")
+      
+      return unless Dir.exist?(default_skills_dir)
+      
+      # Load each skill directory
+      Dir.glob(File.join(default_skills_dir, "*/SKILL.md")).each do |skill_file|
+        skill_dir = File.dirname(skill_file)
+        skill_name = File.basename(skill_dir)
+        
+        begin
+          skill = Skill.new(Pathname.new(skill_dir))
+          
+          # Check for duplicates (higher priority skills override)
+          if @skills.key?(skill.identifier)
+            next  # Skip if already loaded from higher priority location
+          end
+          
+          # Register skill
+          @skills[skill.identifier] = skill
+          @skills_by_command[skill.slash_command] = skill
+          @loaded_from[skill.identifier] = :default
+        rescue StandardError => e
+          @errors << "Failed to load default skill #{skill_name}: #{e.message}"
+        end
+      end
+    end
+  end
+end