caruso 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e38c7a5007af96bb708d286a62909f07f1c1aa3b3aa800baa4a23f36c1a35814
-  data.tar.gz: 18a217953c0ec7c87bc6d9476c89bbca442fde6b45aec4614e4f58c183a3a760
+  metadata.gz: 8f7f1e5f2c4af1c26c2592aaa0cd5be588fa105ae3e7c8faf009275e881b2800
+  data.tar.gz: d740248a46af8e1559f7b02fb70b2660ff907b66e1acd7522c4e7a2692255938
 SHA512:
-  metadata.gz: 427385d4dca6b37150a1bcf487884db8979883d1e7e3d6caa353217b55609ad43dd97dfd1c85860379a6807c62eb37646eabe491540a54a683ec347e17edbc99
-  data.tar.gz: f04abed100aef554d47572af9507c4d7701782b6321e5f48cfdee677f5cbe5ecd82dffab4e719b2328231ea8bee1a1a041c476ee3322fbdc8653c23333d81ed5
+  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/impl.md

@@ -0,0 +1,111 @@
+# Implementation Plan - Evolve Caruso for Claude Code Support
+
+Refining caruso to provide robust support for Claude Code's Commands, Skills, and Hooks, adapting them specifically for the Cursor environment.
+
+## Goal Description
+
+The goal is to transform caruso from a simple markdown copier into a smart adapter that bridges the gap between Claude Code's plugin architecture and Cursor's steering mechanisms. This involves:
+
+- **Skills**: deeply adapting skills by not just copying the markdown, but also bundling associated scripts/ and making them executable.
+- **Commands**: mapping Claude Code commands to Cursor's new .cursor/commands/ structure.
+- **Hooks**: translating Claude Code's hooks/hooks.json events into Cursor's .cursor/hooks.json format.
+- **Fetcher**: upgrading the fetcher to retrieve auxiliary files (scripts, configs) beyond just `.md` files.
+
+## User Review Required
+
+> [!NOTE]
+> **Script Execution Security:** We will trust the "trusted workspace" model of Cursor. This means we will automatically fetch scripts and make them executable (`chmod +x`). Users relying on Caruso are expected to audit the plugins they install, similar to how they would audit an npm package.
+
+## Proposed Changes
+
+### 1. Fetcher Upgrades (`lib/caruso/fetcher.rb`)
+
+The current fetcher is overly focused on *.md files. We need to broaden it to fetch associated resources using an Additive Strategy.
+
+#### [MODIFY] `fetcher.rb`
+
+- **Additive Discovery**: In `fetch_plugin`:
+  - **Logic**:
+    1. **Check Manifest**: Look for `skills` field in `plugin` object (string or array).
+    2. **If Present**: Recursively fetch all files in those specific paths.
+    3. **If Absent**: Fallback to scanning the default `skills/` directory (recursively).
+    4. **Other Components**: Continue scanning for `commands/`, `agents/`, `hooks/` as before.
+
+- **Support Resource Types**:
+  - `skills`: Fetch `SKILL.md` AND recursively fetch `scripts/` directories if found within the skill path.
+
+  - `hooks`: Fetch the `hooks/hooks.json` file (or inline config).
+  - `commands`: Fetch markdown files.
+  - `agents`: Fetch markdown files.
+
+### 2. Adapter Architecture Refactor (`lib/caruso/`)
+
+Refactor the monolithic Adapter class into a dispatcher with specialized strategies.
+
+#### [MODIFY] `adapter.rb`
+Change `Adapter#adapt` to identify the component type and delegate to the appropriate sub-adapter.
+
+#### [NEW] `adapters/base.rb`
+Shared logic for file writing, frontmatter injection, and path sanitization.
+
+#### [NEW] `adapters/skill_adapter.rb`
+**Input:** `skills/<name>/SKILL.md` + `skills/<name>/scripts/*`
+**Output:**
+- `.cursor/rules/caruso/<marketplace>/<skill>/<skill>.mdc` (The rule)
+- `.cursor/scripts/caruso/<marketplace>/<skill>/*` (The scripts)
+
+**Logic:**
+1. Copy scripts to `.cursor/scripts/caruso/<marketplace>/<skill>/`.
+2. Ensure scripts are executable (`chmod +x`).
+3. **Paths:** Do NOT rewrite paths in the markdown (to avoid messiness).
+4. **Context:** Inject a location hint into the Rule's frontmatter `description` or prepended content:
+   ```yaml
+   description: Imported from <skill>. Scripts located at: .cursor/scripts/caruso/<marketplace>/<skill>/
+   ```
+
+#### [NEW] `adapters/agent_adapter.rb`
+**Input:** `agents/<name>.md`
+**Output:** `.cursor/rules/caruso/<marketplace>/agents/<name>.mdc`
+**Logic:**
+- Copy content.
+- Wrap as a "Persona" rule if needed, or simple markdown rule.
+
+#### [NEW] `adapters/command_adapter.rb`
+**Input:** `commands/<name>.md`
+**Output:** `.cursor/commands/<name>.md`
+**Logic:**
+- Basic markdown copy.
+- Frontmatter cleanup (remove Claude-specific fields if necessary).
+
+#### [NEW] `adapters/hook_adapter.rb`
+**Input:** `hooks/hooks.json`
+**Output:** Merged/Updated `.cursor/hooks.json`
+**Logic:**
+- Parse source JSON.
+- Map events (e.g., `PostToolUse` -> `afterFileEdit`).
+- Write/Merge into project's `hooks.json`.
+
+### 3. CLI Updates (`lib/caruso/cli.rb`)
+
+#### [MODIFY] `cli.rb`
+- Update `install` command to handle multiple file types returned by the upgraded fetcher.
+- Ensure `uninstall` cleans up the directories (scripts, etc) correctly.
+
+## Verification Plan
+
+### Automated Tests
+- **Fetcher Tests**: Mock a plugin structure with `scripts/` and verify they are returned in the file list.
+- **Adapter Tests**:
+  - Feed a `SKILL.md` + script to `SkillAdapter` and verify output structure and chmod.
+  - Feed a `hooks.json` and verify the event translation.
+
+### Manual Verification
+- **Skills**: Install a plugin with a script (e.g., a "linter" skill).
+  - Verify file exists at `.cursor/scripts/.../lint.sh`.
+  - Verify it is executable.
+  - Verify the Rule markdown is present.
+- **Commands**: Install a command plugin.
+  - Verify file exists at `.cursor/commands/...`.
+  - Test running the command in Cursor (Cmd+K `/command`).
+- **Hooks**: Install a hook plugin.
+  - Check `.cursor/hooks.json` contains the mapped event.

data/lib/caruso/adapter.rb

@@ -1,113 +1,33 @@
 # frozen_string_literal: true
 
-require "fileutils"
-require "yaml"
-require_relative "safe_file"
-require_relative "path_sanitizer"
+require_relative "adapters/dispatcher"
 
 module Caruso
   class Adapter
-    attr_reader :files, :target_dir, :agent, :marketplace_name, :plugin_name
+    # 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
       @target_dir = target_dir
-      @agent = agent
       @marketplace_name = marketplace_name
       @plugin_name = plugin_name
-      FileUtils.mkdir_p(@target_dir)
+      @agent = agent
+      @installed_hooks = {}
     end
 
     def adapt
-      created_files = []
-      files.each do |file_path|
-        content = SafeFile.read(file_path)
-
-        adapted_content = inject_metadata(content, file_path)
-        created_file = save_file(file_path, adapted_content)
-        created_files << created_file
-      end
-      created_files
-    end
-
-    private
-
-    def inject_metadata(content, file_path)
-      # Check if frontmatter exists
-      if content.match?(/\A---\s*\n.*?\n---\s*\n/m)
-        # If it exists, we might need to append to it or modify it
-        # For now, we assume existing frontmatter is "good enough" but might need 'globs' for Cursor
-        ensure_cursor_globs(content) if agent == :cursor
-      else
-        # No frontmatter, prepend it
-        create_frontmatter(file_path) + content
-      end
-    end
-
-    def ensure_cursor_globs(content)
-      # Add required Cursor metadata fields if missing
-      # globs: [] enables semantic search (Apply Intelligently)
-      # alwaysApply: false means it won't apply to every chat session
-
-      unless content.include?("globs:")
-        content.sub!(/\A---\s*\n/, "---\nglobs: []\n")
-      end
-
-      unless content.include?("alwaysApply:")
-        # Add after the first line of frontmatter
-        content.sub!(/\A---\s*\n/, "---\nalwaysApply: false\n")
-      end
-
-      content
-    end
-
-    def create_frontmatter(file_path)
-      filename = File.basename(file_path)
-      <<~YAML
-        ---
-        description: Imported rule from #{filename}
-        globs: []
-        alwaysApply: false
-        ---
-      YAML
-    end
-
-    def save_file(original_path, content)
-      filename = File.basename(original_path, ".*")
-
-      # Rename SKILL.md to the skill name (parent directory) to avoid collisions
-      if filename.casecmp("skill").zero?
-        filename = File.basename(File.dirname(original_path))
-      end
-
-      extension = agent == :cursor ? ".mdc" : ".md"
-      output_filename = "#{filename}#{extension}"
-
-      # Extract component type from original path (commands/agents/skills)
-      component_type = extract_component_type(original_path)
-
-      # Build nested directory structure for Cursor
-      # Build nested directory structure for Cursor
-      # Structure: .cursor/rules/caruso/marketplace/plugin/component-type/file.mdc
-      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)
-
-      File.write(target_path, content)
-      puts "Saved: #{target_path}"
-
-      # Return relative path from target_dir
-      File.join(subdirs, output_filename)
-    end
-
-    def extract_component_type(file_path)
-      # Extract component type (commands/agents/skills) from path
-      return "commands" if file_path.include?("/commands/")
-      return "agents" if file_path.include?("/agents/")
-      return "skills" if file_path.include?("/skills/")
-
-      raise Caruso::Error, "Cannot determine component type from path: #{file_path}"
+      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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+require_relative "../safe_file"
+require_relative "../path_sanitizer"
+
+module Caruso
+  module Adapters
+    class Base
+      attr_reader :files, :target_dir, :agent, :marketplace_name, :plugin_name
+
+      def initialize(files, target_dir:, marketplace_name:, plugin_name:, agent: :cursor)
+        @files = files
+        @target_dir = target_dir
+        @agent = agent
+        @marketplace_name = marketplace_name
+        @plugin_name = plugin_name
+        FileUtils.mkdir_p(@target_dir)
+      end
+
+      def adapt
+        raise NotImplementedError, "#{self.class.name}#adapt must be implemented"
+      end
+
+      protected
+
+      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?
+          filename = File.basename(File.dirname(relative_path))
+        end
+
+        output_filename = "#{filename}#{ext}"
+
+        # Build nested directory structure: .cursor/rules/caruso/marketplace/plugin/component/file
+        # 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)
+
+        File.write(target_path, content)
+        puts "Saved: #{target_path}"
+
+        File.join(subdirs, output_filename)
+      end
+
+      def extract_component_type(file_path)
+        # Extract component type (commands/agents/skills) from path
+        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
+
+      def inject_metadata(content, file_path)
+        if content.match?(/\A---\s*\n.*?\n---\s*\n/m)
+          ensure_cursor_globs(content) if agent == :cursor
+        else
+          create_frontmatter(file_path) + content
+        end
+      end
+
+      def ensure_cursor_globs(content)
+        unless content.include?("globs:")
+          content.sub!(/\A---\s*\n/, "---\nglobs: []\n")
+        end
+
+        unless content.include?("alwaysApply:")
+          content.sub!(/\A---\s*\n/, "---\nalwaysApply: false\n")
+        end
+
+        content
+      end
+
+      def create_frontmatter(file_path)
+        filename = File.basename(file_path)
+        <<~YAML
+          ---
+          description: Imported rule from #{filename}
+          globs: []
+          alwaysApply: false
+          ---
+        YAML
+      end
+    end
+  end
+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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "markdown_adapter"
+require_relative "skill_adapter"
+require_relative "command_adapter"
+require_relative "hook_adapter"
+
+module Caruso
+  module Adapters
+    class Dispatcher
+      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
+
+        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
+
+        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
+end