caruso 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f6520caf8c5e8a4946369e9722ca36685a6c79b933b67336bc02b39b0fca359
-  data.tar.gz: d1b2f7b52ae5746909e173b75fc31e601417bca1ef55af889a56f802a8ae1d24
+  metadata.gz: 8f7f1e5f2c4af1c26c2592aaa0cd5be588fa105ae3e7c8faf009275e881b2800
+  data.tar.gz: d740248a46af8e1559f7b02fb70b2660ff907b66e1acd7522c4e7a2692255938
 SHA512:
-  metadata.gz: 48d8c7c701c7c1a380672ac77f3025dc69c90c4a5ef7d6fd6e72e50358e69440a9c57ff022f52f94c4970faead782ba04c223246bf766045e4508bca427cf4f8
-  data.tar.gz: 293893a825850e919ca8141203f307c300e9fdba931f80aafadad15a766dd5f28ff6bd061eae53891c5a4da41f061e2b4b6bea5f0108d9b79396e63d82f49296
+  metadata.gz: f77816058f4901d123ba754005869b7e40d8f15be411df9c9fa1c96a261513a4aa420886396aa2cc32f719beaf5876b7ab102c4ee1e9105980402e4c5192a549
+  data.tar.gz: 7d85e8b21768c2978db8b29089920baa39a679163561eeba8ce8e012ad807068ff866d39a37e9411f1dec861232e5c19387c00daf4bb83e6e11673b294df1709

data/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-01-31
+
+### Added
+- **Hooks Support**: Full translation of Claude Code hooks to Cursor hooks format
+  - Event translation: `PreToolUse` → `beforeShellExecution`, `PostToolUse` → `afterFileEdit`/`afterShellExecution`, `UserPromptSubmit` → `beforeSubmitPrompt`, `Stop` → `stop`
+  - Script copying with `${CLAUDE_PLUGIN_ROOT}` path rewriting
+  - Merges all plugin hooks into single `.cursor/hooks.json` file
+  - Tracks installed hooks for surgical removal on uninstall
+  - Skips unsupported events (`SessionStart`, `SessionEnd`, etc.) with warnings
+  - Skips prompt-based hooks (Cursor doesn't support LLM evaluation in hooks)
+- **Commands Support**: New `CommandAdapter` writes slash commands to `.cursor/commands/`
+  - Commands now output as `.md` files in `.cursor/commands/caruso/<marketplace>/<plugin>/`
+  - Preserves frontmatter (`description`, `argument-hint`, `allowed-tools`, `model`)
+  - Converts bash execution markers (`!` prefix) to documentation notes
+- **Plugin.json Parsing**: Reads component paths and inline configs from `.claude-plugin/plugin.json`
+  - Marketplace.json fields take precedence over plugin.json (conflict resolution)
+  - Supports inline hooks configuration
+  - Enables plugin-level metadata tracking
+- **Comprehensive Test Coverage**: 14 new integration tests for hooks
+  - Two-plugin merge scenarios, cross-component plugins, marketplace removal cascade
+  - Plugin update idempotency, edge cases (malformed hooks, agent skipping, no-hooks plugins)
+  - Clean filesystem verification (orphan directory cleanup)
+
+### Changed
+- **Dispatcher Architecture**: Refactored with class methods and step-by-step processing
+  - Skills → Commands → Hooks → Agents (skip with warning) → Unprocessed warnings
+  - Returns structured result: `{ files: [...], hooks: {...} }`
+- **ConfigManager**: Now tracks installed hooks in `.caruso.local.json` for clean uninstall
+  - `add_plugin` accepts `hooks:` keyword argument
+  - `remove_plugin` returns `{ files: [...], hooks: {...} }`
+  - Added `get_installed_hooks` method
+- **Remover**: Enhanced hook removal and orphan directory cleanup
+  - Removes specific hook commands from merged `.cursor/hooks.json` using tracked metadata
+  - Walks up directory tree removing empty dirs after file deletion
+  - Deletes `.cursor/hooks.json` if empty after plugin removal
+- **CLI**: Updated `plugin install` and `plugin update` to pass hooks to ConfigManager
+
+### Fixed
+- Orphan directories no longer left behind after uninstalling plugins with hook scripts
+- Rubocop compliance across all source and spec files (0 offenses)
+
 ## [0.6.2] - 2025-12-17
 
 ### Fixed

data/lib/caruso/adapter.rb

@@ -4,6 +4,10 @@ require_relative "adapters/dispatcher"
 
 module Caruso
   class Adapter
+    # Hook commands installed by this adapter, keyed by Cursor event name.
+    # Populated after adapt() is called. Used for tracking during install.
+    attr_reader :installed_hooks
+
     # Preserving the interface for CLI compatibility
     def initialize(files, target_dir:, marketplace_name:, plugin_name:, agent: :cursor)
       @files = files
@@ -11,16 +15,19 @@ module Caruso
       @marketplace_name = marketplace_name
       @plugin_name = plugin_name
       @agent = agent
+      @installed_hooks = {}
     end
 
     def adapt
-      Caruso::Adapters::Dispatcher.adapt(
+      result = Caruso::Adapters::Dispatcher.adapt(
         @files,
         target_dir: @target_dir,
         marketplace_name: @marketplace_name,
         plugin_name: @plugin_name,
         agent: @agent
       )
+      @installed_hooks = result.is_a?(Hash) ? (result[:hooks] || {}) : {}
+      result.is_a?(Hash) ? result[:files] : result
     end
   end
 end

data/lib/caruso/adapters/base.rb

@@ -27,10 +27,10 @@ module Caruso
 
       def save_file(relative_path, content, extension: nil)
         filename = File.basename(relative_path, ".*")
-        
+
         # Preserve original extension if none provided
         ext = extension || File.extname(relative_path)
-        
+
         # Rename SKILL.md to the skill name (parent directory) to avoid collisions
         # This is specific to Skills, might move to SkillAdapter later, but keeping behavior for now
         if filename.casecmp("skill").zero?
@@ -43,11 +43,11 @@ module Caruso
         # Component type is derived from the class name or passed in?
         # For base, we might need a way to determine output path more flexibly.
         # But sticking to current behavior:
-        
+
         component_type = extract_component_type(relative_path)
         subdirs = File.join("caruso", marketplace_name, plugin_name, component_type)
         output_dir = File.join(target_dir, subdirs)
-        
+
         FileUtils.mkdir_p(output_dir)
         target_path = File.join(output_dir, output_filename)
 
@@ -62,7 +62,7 @@ module Caruso
         return "commands" if file_path.include?("/commands/")
         return "agents" if file_path.include?("/agents/")
         return "skills" if file_path.include?("/skills/")
-        
+
         # Fallback or specific handling for other types
         "misc"
       end

data/lib/caruso/adapters/command_adapter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Caruso
+  module Adapters
+    class CommandAdapter < Base
+      def adapt
+        created_files = []
+        files.each do |file_path|
+          content = SafeFile.read(file_path)
+          adapted_content = adapt_command_content(content, file_path)
+
+          # Commands are flat .md files in .cursor/commands/
+          # NOT nested like rules, so we override the save behavior
+          created_file = save_command_file(file_path, adapted_content)
+
+          created_files << created_file
+        end
+        created_files
+      end
+
+      private
+
+      def adapt_command_content(content, file_path)
+        # Preserve or add frontmatter, but don't add Cursor-specific rule fields
+        if content.match?(/\A---\s*\n.*?\n---\s*\n/m)
+          # Frontmatter exists - preserve command-specific fields
+          preserve_command_frontmatter(content, file_path)
+        else
+          # No frontmatter - create minimal description
+          create_command_frontmatter(file_path) + content
+        end
+      end
+
+      def preserve_command_frontmatter(content, _file_path)
+        # Commands support: description, argument-hint, allowed-tools, model
+        # We don't need globs or alwaysApply (those are for rules)
+        # Just return content as-is, Claude Code commands are already compatible
+
+        # Add note about bash execution if it contains ! prefix
+        if content.include?("!`")
+          add_bash_execution_note(content)
+        else
+          content
+        end
+      end
+
+      def create_command_frontmatter(file_path)
+        filename = File.basename(file_path)
+        <<~YAML
+          ---
+          description: Command from #{filename}
+          ---
+        YAML
+      end
+
+      def add_bash_execution_note(content)
+        match = content.match(/\A---\s*\n(.*?)\n---\s*\n/m)
+        return content unless match
+
+        note = "\n**Note:** This command originally used Claude Code's `!` prefix for bash execution. " \
+               "Cursor does not support this feature. The bash commands are documented below for reference.\n"
+
+        "---\n#{match[1]}\n---\n#{note}#{match.post_match}"
+      end
+
+      def save_command_file(relative_path, content)
+        filename = File.basename(relative_path, ".*")
+        output_filename = "#{filename}.md"
+
+        # Commands go to .cursor/commands/caruso/<marketplace>/<plugin>/
+        # Flat structure, no component subdirectory
+        subdirs = File.join("caruso", marketplace_name, plugin_name)
+        output_dir = File.join(".cursor", "commands", subdirs)
+
+        FileUtils.mkdir_p(output_dir)
+        target_path = File.join(output_dir, output_filename)
+
+        File.write(target_path, content)
+        puts "Saved command: #{target_path}"
+
+        # Return relative path for tracking
+        File.join(".cursor/commands", subdirs, output_filename)
+      end
+    end
+  end
+end

data/lib/caruso/adapters/dispatcher.rb

@@ -2,51 +2,81 @@
 
 require_relative "markdown_adapter"
 require_relative "skill_adapter"
+require_relative "command_adapter"
+require_relative "hook_adapter"
 
 module Caruso
   module Adapters
     class Dispatcher
-      def self.adapt(files, target_dir:, marketplace_name:, plugin_name:, agent: :cursor)
-        created_files = []
-        remaining_files = files.dup
-
-        # 1. Identify and Process Skill Clusters
-        # Find all SKILL.md files to serve as anchors
-        skill_anchors = remaining_files.select { |f| File.basename(f).casecmp("skill.md").zero? }
-
-        skill_anchors.each do |anchor|
-          skill_dir = File.dirname(anchor)
-          
-          # Find all files that belong to this skill's directory (recursive)
-          skill_cluster = remaining_files.select { |f| f.start_with?(skill_dir) }
-          
-          # Use SkillAdapter for this cluster
-          adapter = SkillAdapter.new(
-            skill_cluster,
-            target_dir: target_dir,
-            marketplace_name: marketplace_name,
-            plugin_name: plugin_name,
-            agent: agent
-          )
-          created_files.concat(adapter.adapt)
-          
-          # Remove processed files
-          remaining_files -= skill_cluster
+      class << self
+        def adapt(files, target_dir:, marketplace_name:, plugin_name:, agent: :cursor)
+          ctx = { target_dir: target_dir, marketplace_name: marketplace_name, plugin_name: plugin_name, agent: agent }
+          remaining = files.dup
+          created = []
+
+          created.concat(process_skills(remaining, ctx))
+          created.concat(process_commands(remaining, ctx))
+
+          hook_result = process_hooks(remaining, ctx)
+          created.concat(hook_result[:created])
+
+          skip_agents(remaining)
+          warn_unprocessed(remaining)
+
+          { files: created, hooks: hook_result[:hooks] }
         end
 
-        # 2. Process Remaining Files (Commands, Agents, etc.) via MarkdownAdapter
-        if remaining_files.any?
-          adapter = MarkdownAdapter.new(
-            remaining_files,
-            target_dir: target_dir,
-            marketplace_name: marketplace_name,
-            plugin_name: plugin_name,
-            agent: agent
-          )
-          created_files.concat(adapter.adapt)
+        private
+
+        def process_skills(remaining, ctx)
+          created = []
+          skill_anchors = remaining.select { |f| File.basename(f).casecmp("skill.md").zero? }
+
+          skill_anchors.each do |anchor|
+            skill_dir = File.dirname(anchor)
+            skill_cluster = remaining.select { |f| f.start_with?(skill_dir) }
+
+            adapter = SkillAdapter.new(skill_cluster, **ctx)
+            created.concat(adapter.adapt)
+            remaining.delete_if { |f| skill_cluster.include?(f) }
+          end
+
+          created
         end
 
-        created_files
+        def process_commands(remaining, ctx)
+          commands = remaining.select { |f| f.include?("/commands/") }
+          return [] unless commands.any?
+
+          adapter = CommandAdapter.new(commands, **ctx)
+          remaining.delete_if { |f| commands.include?(f) }
+          adapter.adapt
+        end
+
+        def process_hooks(remaining, ctx)
+          hooks_files = remaining.select { |f| File.basename(f) =~ /hooks\.json\z/ }
+          return { created: [], hooks: {} } unless hooks_files.any?
+
+          adapter = HookAdapter.new(hooks_files, **ctx)
+          created = adapter.adapt
+          remaining.delete_if { |f| hooks_files.include?(f) }
+          { created: created, hooks: adapter.translated_hooks }
+        end
+
+        def skip_agents(remaining)
+          agents = remaining.select { |f| f.include?("/agents/") }
+          return unless agents.any?
+
+          puts "Skipping #{agents.size} agent(s): Agents require context isolation not available in Cursor"
+          remaining.delete_if { |f| agents.include?(f) }
+        end
+
+        def warn_unprocessed(remaining)
+          return unless remaining.any?
+
+          puts "Warning: #{remaining.size} file(s) could not be categorized and were skipped:"
+          remaining.each { |f| puts "  - #{f}" }
+        end
       end
     end
   end

data/lib/caruso/adapters/hook_adapter.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "base"
+
+module Caruso
+  module Adapters
+    class HookAdapter < Base
+      # Claude Code events that map to Cursor events.
+      # Each CC event maps to a single Cursor event name.
+      # Matchers are lost in translation (Cursor has no matcher concept).
+      EVENT_MAP = {
+        "PreToolUse" => "beforeShellExecution",
+        "PostToolUse" => "afterShellExecution",
+        "UserPromptSubmit" => "beforeSubmitPrompt",
+        "Stop" => "stop"
+      }.freeze
+
+      # PostToolUse with Write|Edit matchers should map to afterFileEdit instead.
+      # We detect this via the matcher pattern.
+      FILE_EDIT_MATCHERS = /\A(Write|Edit|Write\|Edit|Edit\|Write|Notebook.*)\z/i
+
+      # Events that have no Cursor equivalent and must be skipped.
+      UNSUPPORTED_EVENTS = %w[
+        SessionStart
+        SessionEnd
+        SubagentStop
+        PreCompact
+        Notification
+        PermissionRequest
+      ].freeze
+
+      # After adapt(), contains the translated hook commands keyed by event.
+      # Used by callers to track which hooks were installed for clean uninstall.
+      attr_reader :translated_hooks
+
+      def adapt
+        @translated_hooks = {}
+
+        hooks_file = find_hooks_file
+        return [] unless hooks_file
+
+        plugin_hooks = parse_hooks_file(hooks_file)
+        return [] if plugin_hooks.nil? || plugin_hooks.empty?
+
+        cursor_hooks = translate_hooks(plugin_hooks)
+        return [] if cursor_hooks.empty?
+
+        # Copy any referenced scripts
+        copied_scripts = copy_hook_scripts(cursor_hooks, hooks_file)
+
+        # Merge into existing .cursor/hooks.json
+        merge_hooks(cursor_hooks)
+
+        # Store for tracking
+        @translated_hooks = cursor_hooks
+
+        # Return list of created/modified files for tracking
+        created = [".cursor/hooks.json"]
+        created += copied_scripts
+        created
+      end
+
+      private
+
+      def find_hooks_file
+        # files array contains the hooks.json path passed in by the Dispatcher.
+        # Also matches .caruso_inline_hooks.json written by Fetcher for inline plugin.json hooks.
+        files.find { |f| File.basename(f) =~ /hooks\.json\z/ }
+      end
+
+      def parse_hooks_file(hooks_file)
+        content = SafeFile.read(hooks_file)
+        data = JSON.parse(content)
+        data["hooks"]
+      rescue JSON::ParserError => e
+        puts "Warning: Could not parse hooks.json: #{e.message}"
+        nil
+      end
+
+      def translate_hooks(plugin_hooks)
+        cursor_hooks = {}
+        skipped_events = []
+        skipped_prompts = 0
+
+        plugin_hooks.each do |event_name, matchers|
+          if UNSUPPORTED_EVENTS.include?(event_name)
+            skipped_events << event_name
+            next
+          end
+
+          result = translate_event_hooks(event_name, matchers)
+          result[:hooks].each { |event, entries| (cursor_hooks[event] ||= []).concat(entries) }
+          skipped_prompts += result[:skipped_prompts]
+        end
+
+        warn_skipped(skipped_events, skipped_prompts)
+        cursor_hooks
+      end
+
+      def translate_event_hooks(event_name, matchers)
+        hooks = {}
+        skipped = 0
+
+        matchers.each do |matcher_entry|
+          matcher = matcher_entry["matcher"]
+          (matcher_entry["hooks"] || []).each do |hook|
+            if hook["type"] == "prompt"
+              skipped += 1
+              next
+            end
+
+            command = hook["command"]
+            next unless command
+
+            cursor_event = resolve_cursor_event(event_name, matcher)
+            cursor_hook = { "command" => command }
+            cursor_hook["timeout"] = hook["timeout"] if hook["timeout"]
+            (hooks[cursor_event] ||= []) << cursor_hook
+          end
+        end
+
+        { hooks: hooks, skipped_prompts: skipped }
+      end
+
+      def warn_skipped(skipped_events, skipped_prompts)
+        if skipped_events.any?
+          unique_skipped = skipped_events.uniq
+          puts "Skipping #{unique_skipped.size} unsupported hook event(s): #{unique_skipped.join(', ')}"
+          puts "  (Cursor has no equivalent for these Claude Code lifecycle events)"
+        end
+
+        return unless skipped_prompts.positive?
+
+        puts "Skipping #{skipped_prompts} prompt-based hook(s): Cursor does not support LLM evaluation in hooks"
+      end
+
+      def resolve_cursor_event(cc_event, matcher)
+        # PostToolUse with file-related matchers maps to afterFileEdit
+        if cc_event == "PostToolUse" && matcher && FILE_EDIT_MATCHERS.match?(matcher)
+          return "afterFileEdit"
+        end
+
+        EVENT_MAP[cc_event] || "afterShellExecution"
+      end
+
+      def rewrite_script_path(command)
+        plugin_script_dir = File.join("hooks", "caruso", marketplace_name, plugin_name)
+        command.gsub("${CLAUDE_PLUGIN_ROOT}", plugin_script_dir)
+      end
+
+      def plugin_root_from_hooks_file(hooks_file)
+        # ${CLAUDE_PLUGIN_ROOT} refers to the plugin root directory.
+        # hooks.json is typically at <plugin_root>/hooks/hooks.json,
+        # so the plugin root is the parent of the hooks/ directory.
+        hooks_dir = File.dirname(hooks_file)
+        if File.basename(hooks_dir) == "hooks"
+          File.dirname(hooks_dir)
+        else
+          hooks_dir
+        end
+      end
+
+      def copy_hook_scripts(cursor_hooks, hooks_file)
+        plugin_root = plugin_root_from_hooks_file(hooks_file)
+
+        cursor_hooks.each_value.flat_map do |hook_entries|
+          hook_entries.filter_map { |hook| copy_single_script(hook, plugin_root) }
+        end
+      end
+
+      def copy_single_script(hook, plugin_root)
+        command = hook["command"]
+        return unless command&.include?("${CLAUDE_PLUGIN_ROOT}")
+
+        relative_path = command.sub("${CLAUDE_PLUGIN_ROOT}/", "")
+        source_path = File.join(plugin_root, relative_path)
+        return unless File.exist?(source_path)
+
+        target_path = File.join(".cursor", "hooks", "caruso", marketplace_name, plugin_name, relative_path)
+        FileUtils.mkdir_p(File.dirname(target_path))
+        FileUtils.cp(source_path, target_path)
+        File.chmod(0o755, target_path)
+        puts "Copied hook script: #{target_path}"
+
+        hook["command"] = rewrite_script_path(command)
+        target_path
+      end
+
+      def merge_hooks(new_hooks)
+        hooks_path = File.join(".cursor", "hooks.json")
+        existing = read_existing_hooks(hooks_path)
+
+        # Merge: append new hook entries to existing event arrays
+        new_hooks.each do |event, entries|
+          existing[event] ||= []
+          entries.each do |entry|
+            # Deduplicate: don't add if an identical command already exists
+            unless existing[event].any? { |e| e["command"] == entry["command"] }
+              existing[event] << entry
+            end
+          end
+        end
+
+        FileUtils.mkdir_p(".cursor")
+        File.write(hooks_path, JSON.pretty_generate({ "version" => 1, "hooks" => existing }))
+        puts "Merged hooks into #{hooks_path}"
+      end
+
+      def read_existing_hooks(hooks_path)
+        return {} unless File.exist?(hooks_path)
+
+        data = JSON.parse(File.read(hooks_path))
+        data["hooks"] || {}
+      rescue JSON::ParserError
+        puts "Warning: Existing hooks.json is malformed, starting fresh"
+        {}
+      end
+    end
+  end
+end

data/lib/caruso/adapters/markdown_adapter.rb

@@ -10,10 +10,10 @@ module Caruso
         files.each do |file_path|
           content = SafeFile.read(file_path)
           adapted_content = inject_metadata(content, file_path)
-          
+
           extension = agent == :cursor ? ".mdc" : ".md"
           created_file = save_file(file_path, adapted_content, extension: extension)
-          
+
           created_files << created_file
         end
         created_files

data/lib/caruso/adapters/skill_adapter.rb

@@ -6,50 +6,30 @@ module Caruso
   module Adapters
     class SkillAdapter < Base
       def adapt
-        created_files = []
-        
-        # Separate SKILL.md from other files (scripts, etc.)
         skill_file = files.find { |f| File.basename(f).casecmp("skill.md").zero? }
-        other_files = files - [skill_file]
+        return [] unless skill_file
 
-        if skill_file
-          skill_root = File.dirname(skill_file)
-          skill_name = File.basename(skill_root)
-          
-          # Inject script location hint
-          # Targeted script location: .cursor/scripts/caruso/<market>/<plugin>/<skill_name>/
-          script_location = ".cursor/scripts/caruso/#{marketplace_name}/#{plugin_name}/#{skill_name}/"
-          
-          content = SafeFile.read(skill_file)
-          adapted_content = inject_skill_metadata(content, skill_file, script_location)
-          
-          # Save as Rule (.mdc)
-          extension = agent == :cursor ? ".mdc" : ".md"
-          created_file = save_file(skill_file, adapted_content, extension: extension)
-          created_files << created_file
-          
-          # Process Scripts/Assets -> .cursor/scripts/...
-          other_files.each do |file_path|
-            # Calculate path relative to the skill root
-            # e.g. source: .../skills/auth/scripts/login.sh
-            #      root:   .../skills/auth
-            #      rel:    scripts/login.sh
-            relative_path_from_root = file_path.sub(skill_root + "/", "")
-            
-            created_script = save_script(file_path, skill_name, relative_path_from_root)
-            created_files << created_script
-          end
-        end
+        skill_root = File.dirname(skill_file)
+        skill_name = File.basename(skill_root)
+        other_files = files - [skill_file]
 
-        created_files
+        [adapt_skill(skill_file, skill_name)] + copy_assets(other_files, skill_root, skill_name)
       end
 
       private
 
+      def adapt_skill(skill_file, skill_name)
+        script_location = ".cursor/scripts/caruso/#{marketplace_name}/#{plugin_name}/#{skill_name}/"
+        content = SafeFile.read(skill_file)
+        adapted_content = inject_skill_metadata(content, skill_file, script_location)
+        extension = agent == :cursor ? ".mdc" : ".md"
+        save_file(skill_file, adapted_content, extension: extension)
+      end
+
       def inject_skill_metadata(content, file_path, script_location)
         # Inject script location into description
         hint = "Scripts located at: #{script_location}"
-        
+
         if content.match?(/\A---\s*\n.*?\n---\s*\n/m)
           # Update existing frontmatter
           content.sub!(/^description: (.*)$/, "description: \\1. #{hint}")
@@ -71,25 +51,32 @@ module Caruso
         YAML
       end
 
+      def copy_assets(asset_files, skill_root, skill_name)
+        asset_files.map do |file_path|
+          relative_path = file_path.sub("#{skill_root}/", "")
+          save_script(file_path, skill_name, relative_path)
+        end
+      end
+
       def save_script(source_path, skill_name, relative_sub_path)
         # Construct target path in .cursor/scripts
         # .cursor/scripts/caruso/<marketplace>/<plugin>/<skill_name>/<relative_sub_path>
-        
+
         scripts_root = File.join(target_dir, "..", "scripts", "caruso", marketplace_name, plugin_name, skill_name)
-        # Note: target_dir passed to adapter is usually .cursor/rules.
+        # NOTE: target_dir passed to adapter is usually .cursor/rules.
         # So .. -> .cursor -> scripts
-        
+
         target_path = File.join(scripts_root, relative_sub_path)
         output_dir = File.dirname(target_path)
-        
+
         FileUtils.mkdir_p(output_dir)
         FileUtils.cp(source_path, target_path)
-        
+
         # Make executable
-        File.chmod(0755, target_path)
-        
+        File.chmod(0o755, target_path)
+
         puts "Saved script: #{target_path}"
-        
+
         # Return relative path for tracking/reporting
         # We start from .cursor (parent of target_dir) ideally?
         # Or just return the absolute path for now?

data/lib/caruso/cli.rb

@@ -227,12 +227,21 @@ module Caruso
       )
       created_filenames = adapter.adapt
 
-      # Convert filenames to relative paths from project root
-      created_files = created_filenames.map { |f| File.join(config_manager.target_dir, f) }
+      # Convert filenames to project-relative paths.
+      # Paths already starting with .cursor/ (commands, hooks) are already project-relative.
+      # Others (rules from SkillAdapter/MarkdownAdapter) are relative to target_dir.
+      created_files = created_filenames.map do |f|
+        if f.start_with?(".cursor/") || File.absolute_path?(f)
+          f
+        else
+          File.join(config_manager.target_dir, f)
+        end
+      end
 
       # Use composite key for uniqueness
       plugin_key = "#{plugin_name}@#{marketplace_name}"
-      config_manager.add_plugin(plugin_key, created_files, marketplace_name: marketplace_name)
+      config_manager.add_plugin(plugin_key, created_files, marketplace_name: marketplace_name,
+                                                           hooks: adapter.installed_hooks)
       puts "Installed #{plugin_name}!"
     end
 
@@ -455,8 +464,14 @@ module Caruso
       )
       created_filenames = adapter.adapt
 
-      # Convert filenames to relative paths from project root
-      created_files = created_filenames.map { |f| File.join(config_manager.target_dir, f) }
+      # Convert filenames to project-relative paths (same logic as install)
+      created_files = created_filenames.map do |f|
+        if f.start_with?(".cursor/") || File.absolute_path?(f)
+          f
+        else
+          File.join(config_manager.target_dir, f)
+        end
+      end
 
       # Cleanup: Delete files that are no longer present
       old_files = config_manager.get_installed_files(plugin_key)
@@ -470,7 +485,8 @@ module Caruso
       end
 
       # Update plugin in config
-      config_manager.add_plugin(plugin_key, created_files, marketplace_name: marketplace_name)
+      config_manager.add_plugin(plugin_key, created_files, marketplace_name: marketplace_name,
+                                                           hooks: adapter.installed_hooks)
     end
 
     def load_config

data/lib/caruso/config_manager.rb

@@ -54,11 +54,7 @@ module Caruso
         raise Error, "Caruso not initialized. Run 'caruso init --ide=cursor' first."
       end
 
-      project_data = load_project_config
-      local_data = load_local_config
-
-      # Merge data for easier access, but keep them conceptually separate
-      project_data.merge(local_data)
+      load_project_config.merge(load_local_config)
     end
 
     def config_exists?
@@ -77,9 +73,7 @@ module Caruso
       load["ide"]
     end
 
-    # Plugin Management
-
-    def add_plugin(name, files, marketplace_name:)
+    def add_plugin(name, files, marketplace_name:, hooks: {})
       # Update project config (Intent)
       project_data = load_project_config
       project_data["plugins"] ||= {}
@@ -88,23 +82,32 @@ module Caruso
       }
       save_project_config(project_data)
 
-      # Update local config (Files)
+      # Update local config (Files and Hooks)
       local_data = load_local_config
       local_data["installed_files"] ||= {}
       local_data["installed_files"][name] = files
+
+      # Track installed hook commands for clean uninstall
+      local_data["installed_hooks"] ||= {}
+      if hooks.empty?
+        local_data["installed_hooks"].delete(name)
+      else
+        local_data["installed_hooks"][name] = hooks
+      end
+
       save_local_config(local_data)
     end
 
     def remove_plugin(name)
-      # Get files to remove from local config
+      # Get files and hooks to remove from local config
       local_data = load_local_config
       files = local_data.dig("installed_files", name) || []
+      hooks = local_data.dig("installed_hooks", name) || {}
 
       # Remove from local config
-      if local_data["installed_files"]
-        local_data["installed_files"].delete(name)
-        save_local_config(local_data)
-      end
+      local_data["installed_files"]&.delete(name)
+      local_data["installed_hooks"]&.delete(name)
+      save_local_config(local_data)
 
       # Remove from project config
       project_data = load_project_config
@@ -113,7 +116,7 @@ module Caruso
         save_project_config(project_data)
       end
 
-      files
+      { files: files, hooks: hooks }
     end
 
     def list_plugins
@@ -121,15 +124,16 @@ module Caruso
     end
 
     def plugin_installed?(name)
-      plugins = list_plugins
-      plugins.key?(name)
+      list_plugins.key?(name)
     end
 
     def get_installed_files(name)
       load_local_config.dig("installed_files", name) || []
     end
 
-    # Marketplace Management
+    def get_installed_hooks(name)
+      load_local_config.dig("installed_hooks", name) || {}
+    end
 
     def add_marketplace(name, url, source: "git", ref: nil)
       data = load_project_config
@@ -151,20 +155,23 @@ module Caruso
     end
 
     def remove_marketplace_with_plugins(marketplace_name)
-      files_to_remove = []
+      result = { files: [], hooks: {} }
 
       # Find and remove all plugins associated with this marketplace
       installed_plugins = list_plugins
       installed_plugins.each do |plugin_key, details|
-        if details["marketplace"] == marketplace_name
-          files_to_remove.concat(remove_plugin(plugin_key))
-        end
+        next unless details["marketplace"] == marketplace_name
+
+        plugin_result = remove_plugin(plugin_key)
+        result[:files].concat(plugin_result[:files])
+        result[:hooks].merge!(plugin_result[:hooks])
       end
 
       # Remove the marketplace itself
       remove_marketplace(marketplace_name)
 
-      files_to_remove.uniq
+      result[:files] = result[:files].uniq
+      result
     end
 
     def list_marketplaces
@@ -175,11 +182,6 @@ module Caruso
       load_project_config.dig("marketplaces", name)
     end
 
-    def get_marketplace_url(name)
-      details = get_marketplace_details(name)
-      details ? details["url"] : nil
-    end
-
     private
 
     def load_project_config

data/lib/caruso/fetcher.rb

@@ -180,12 +180,41 @@ module Caruso
 
       return [] unless SafeDir.exist?(plugin_path)
 
-      # Start with default directories
-      files = find_steering_files(plugin_path, plugin)
+      # Merge marketplace entry with plugin.json (marketplace takes precedence)
+      merged_plugin_data = merge_with_plugin_json(plugin, plugin_path)
+
+      files = find_steering_files(plugin_path, merged_plugin_data)
 
       files.uniq
     end
 
+    # Read plugin.json and merge with marketplace entry.
+    # Marketplace fields override plugin.json fields for component paths.
+    def merge_with_plugin_json(marketplace_entry, plugin_path)
+      plugin_json_path = File.join(plugin_path, ".claude-plugin", "plugin.json")
+      return marketplace_entry unless File.exist?(plugin_json_path)
+
+      begin
+        plugin_data = JSON.parse(SafeFile.read(plugin_json_path))
+      rescue JSON::ParserError => e
+        puts "Warning: Could not parse plugin.json: #{e.message}"
+        return marketplace_entry
+      end
+
+      component_fields = %w[commands agents skills hooks mcpServers]
+      merged = marketplace_entry.dup
+
+      component_fields.each do |field|
+        # Only use plugin.json value if marketplace entry doesn't specify this field
+        next if merged.key?(field)
+        next unless plugin_data.key?(field)
+
+        merged[field] = plugin_data[field]
+      end
+
+      merged
+    end
+
     def resolve_plugin_path(source)
       if source.is_a?(Hash) && %w[git github].include?(source["source"])
         clone_git_repo(source)
@@ -213,13 +242,13 @@ module Caruso
       # 1. ALWAYS scan default directories (Additive Strategy)
       files += glob_plugin_files(plugin_path, "commands", "**", "*.md")
       files += glob_plugin_files(plugin_path, "agents", "**", "*.md")
-      
+
       # For skills, we want recursive default scan if 'skills/' exists
       # But careful: if we scan default 'skills' recursively here, and then scan strict paths from manifest...
       # Duplicate handling is fine via uniq.
       default_skills_path = File.join(plugin_path, "skills")
       if SafeDir.exist?(default_skills_path)
-         files += find_recursive_component_files(plugin_path, "skills") 
+        files += find_recursive_component_files(plugin_path, "skills")
       end
 
       # 2. Add manifest-defined paths (if present)
@@ -229,6 +258,9 @@ module Caruso
         files += find_recursive_component_files(plugin_path, plugin_data["skills"]) if plugin_data["skills"]
       end
 
+      # 3. Detect hooks files
+      files += find_hooks_files(plugin_path, plugin_data)
+
       # Filter out noise
       files.uniq.reject do |file|
         basename = File.basename(file).downcase
@@ -238,8 +270,8 @@ module Caruso
 
     # Helper to glob files safely
     def glob_plugin_files(plugin_path, *parts)
-       pattern = PathSanitizer.safe_join(plugin_path, *parts)
-       SafeDir.glob(pattern, base_dir: plugin_path)
+      pattern = PathSanitizer.safe_join(plugin_path, *parts)
+      SafeDir.glob(pattern, base_dir: plugin_path)
     end
 
     # For Commands/Agents: typically just markdown files, flat or shallow
@@ -263,35 +295,71 @@ module Caruso
       end
       files
     end
-    
+
     # For SKILLS: Recursive fetch of EVERYTHING (scripts, assets, md)
     def find_recursive_component_files(plugin_path, paths)
-       paths = [paths] if paths.is_a?(String)
-       return [] unless paths.is_a?(Array)
-       
-       files = []
-       paths.each do |path|
-         full_path = resolve_safe_path(plugin_path, path)
-         next unless full_path
-         
-         if File.file?(full_path)
-            files << full_path
-         elsif SafeDir.exist?(full_path, base_dir: plugin_path)
-            # Grab EVERYTHING recursively
-            glob_pattern = PathSanitizer.safe_join(full_path, "**", "*")
-            files += SafeDir.glob(glob_pattern, base_dir: plugin_path)
-         end
-       end
-       files
+      paths = [paths] if paths.is_a?(String)
+      return [] unless paths.is_a?(Array)
+
+      files = []
+      paths.each do |path|
+        full_path = resolve_safe_path(plugin_path, path)
+        next unless full_path
+
+        if File.file?(full_path)
+          files << full_path
+        elsif SafeDir.exist?(full_path, base_dir: plugin_path)
+          # Grab EVERYTHING recursively
+          glob_pattern = PathSanitizer.safe_join(full_path, "**", "*")
+          files += SafeDir.glob(glob_pattern, base_dir: plugin_path)
+        end
+      end
+      files
     end
-    
-    def resolve_safe_path(plugin_path, relative_path)
-        begin
-          PathSanitizer.sanitize_path(File.expand_path(relative_path, plugin_path), base_dir: plugin_path)
-        rescue PathSanitizer::PathTraversalError => e
-          warn "Skipping path outside plugin directory '#{relative_path}': #{e.message}"
-          nil
+
+    def find_hooks_files(plugin_path, plugin_data)
+      files = []
+
+      # Default hooks/ directory
+      default_hooks = File.join(plugin_path, "hooks", "hooks.json")
+      files << default_hooks if File.exist?(default_hooks)
+
+      # Custom hooks from manifest (inline config or path-based)
+      return files unless plugin_data&.key?("hooks")
+
+      hooks_value = plugin_data["hooks"]
+      if hooks_value.is_a?(Hash)
+        inline_path = File.join(plugin_path, ".caruso_inline_hooks.json")
+        File.write(inline_path, JSON.pretty_generate(hooks_value))
+        files << inline_path
+      else
+        files += find_custom_hooks_paths(plugin_path, hooks_value)
+      end
+
+      files
+    end
+
+    def find_custom_hooks_paths(plugin_path, hooks_value)
+      files = []
+      [hooks_value].flatten.each do |path|
+        full_path = resolve_safe_path(plugin_path, path)
+        next unless full_path
+
+        if File.file?(full_path) && File.basename(full_path) == "hooks.json"
+          files << full_path
+        elsif SafeDir.exist?(full_path, base_dir: plugin_path)
+          candidate = File.join(full_path, "hooks.json")
+          files << candidate if File.exist?(candidate)
         end
+      end
+      files
+    end
+
+    def resolve_safe_path(plugin_path, relative_path)
+      PathSanitizer.sanitize_path(File.expand_path(relative_path, plugin_path), base_dir: plugin_path)
+    rescue PathSanitizer::PathTraversalError => e
+      warn "Skipping path outside plugin directory '#{relative_path}': #{e.message}"
+      nil
     end
 
     def local_path?

data/lib/caruso/remover.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "marketplace_registry"
 
 module Caruso
@@ -11,12 +12,12 @@ module Caruso
     end
 
     def remove_marketplace(name)
-      # 1. Remove from config and get associated plugin files
-      # This updates both project config (plugins) and local config (files)
-      files_to_remove = config_manager.remove_marketplace_with_plugins(name)
+      # 1. Remove from config and get associated plugin files/hooks
+      result = config_manager.remove_marketplace_with_plugins(name)
 
-      # 2. Delete the actual files
-      delete_files(files_to_remove)
+      # 2. Delete the actual files and remove hooks
+      delete_files(result[:files])
+      remove_plugin_hooks(result[:hooks]) if result[:hooks] && !result[:hooks].empty?
 
       # 3. Clean up registry cache
       remove_from_registry(name)
@@ -24,21 +25,80 @@ module Caruso
 
     def remove_plugin(name)
       # 1. Remove from config
-      files_to_remove = config_manager.remove_plugin(name)
+      result = config_manager.remove_plugin(name)
 
-      # 2. Delete files
-      delete_files(files_to_remove)
+      # 2. Delete files and remove hooks
+      delete_files(result[:files])
+      remove_plugin_hooks(result[:hooks]) if result[:hooks] && !result[:hooks].empty?
     end
 
     private
 
     def delete_files(files)
-      files.each do |file|
+      # Skip hooks.json — it's a merged file handled separately by remove_plugin_hooks
+      files.reject { |f| File.basename(f) == "hooks.json" && f.include?(".cursor") }.each do |file|
         full_path = File.join(config_manager.project_dir, file)
-        if File.exist?(full_path)
-          File.delete(full_path)
-          puts "  Deleted #{file}"
-        end
+        next unless File.exist?(full_path)
+
+        File.delete(full_path)
+        puts "  Deleted #{file}"
+        cleanup_empty_parents(full_path)
+      end
+    end
+
+    # Walk up from a deleted file's parent, removing empty directories
+    # until we hit .cursor/ itself or a non-empty directory.
+    def cleanup_empty_parents(file_path)
+      cursor_dir = File.join(config_manager.project_dir, ".cursor")
+      dir = File.dirname(file_path)
+
+      while dir != cursor_dir && dir.start_with?(cursor_dir)
+        break unless Dir.exist?(dir) && Dir.empty?(dir)
+
+        Dir.rmdir(dir)
+        dir = File.dirname(dir)
+      end
+    end
+
+    # Remove specific hook entries from .cursor/hooks.json using tracked metadata.
+    # installed_hooks is a hash: { "event_name" => [{ "command" => "..." }, ...] }
+    def remove_plugin_hooks(installed_hooks)
+      hooks_path = File.join(config_manager.project_dir, ".cursor", "hooks.json")
+      return unless File.exist?(hooks_path)
+
+      begin
+        data = JSON.parse(File.read(hooks_path))
+        hooks = data["hooks"] || {}
+      rescue JSON::ParserError
+        return
+      end
+
+      return unless remove_tracked_commands(hooks, installed_hooks)
+
+      hooks.reject! { |_, entries| entries.empty? }
+      write_or_delete_hooks(hooks_path, hooks)
+    end
+
+    def remove_tracked_commands(hooks, installed_hooks)
+      changed = false
+      installed_hooks.each do |event, entries|
+        next unless hooks[event]
+
+        commands_to_remove = entries.map { |e| e["command"] }.compact.to_set
+        before_count = hooks[event].length
+        hooks[event].reject! { |entry| commands_to_remove.include?(entry["command"]) }
+        changed = true if hooks[event].length != before_count
+      end
+      changed
+    end
+
+    def write_or_delete_hooks(hooks_path, hooks)
+      if hooks.empty?
+        File.delete(hooks_path)
+        puts "  Deleted .cursor/hooks.json (empty after plugin removal)"
+      else
+        File.write(hooks_path, JSON.pretty_generate({ "version" => 1, "hooks" => hooks }))
+        puts "  Updated .cursor/hooks.json (removed plugin hooks)"
       end
     end
 

data/lib/caruso/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Caruso
-  VERSION = "0.6.3"
+  VERSION = "0.7.0"
 end

data/package-lock.json

@@ -0,0 +1,6 @@
+{
+  "name": "identify-missing-features",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caruso
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Philipp Comans
@@ -147,7 +147,9 @@ files:
 - lib/caruso.rb
 - lib/caruso/adapter.rb
 - lib/caruso/adapters/base.rb
+- lib/caruso/adapters/command_adapter.rb
 - lib/caruso/adapters/dispatcher.rb
+- lib/caruso/adapters/hook_adapter.rb
 - lib/caruso/adapters/markdown_adapter.rb
 - lib/caruso/adapters/skill_adapter.rb
 - lib/caruso/cli.rb
@@ -159,6 +161,7 @@ files:
 - lib/caruso/safe_dir.rb
 - lib/caruso/safe_file.rb
 - lib/caruso/version.rb
+- package-lock.json
 - reference/claude_code_create_marketplaces.md
 - reference/claude_code_hooks.md
 - reference/claude_code_marketplaces.md