caruso 0.7.4 → 0.7.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8b934cb6295f95d2246260f6eb77a4b31c999bb35e73a379457fa9c9d27d7d2
-  data.tar.gz: 9da817fab3ff58b8a363c631ad945d206f3d4ed3f9fc65efd8f0225b3d731a6b
+  metadata.gz: c881250221622ad116a1da441ca090a80fa1830f3d51b675b4a0919853d82287
+  data.tar.gz: 4276216066d112d8bed3e99c5d2928bd6d28ba1b44c4d2847f95f0f9447b803f
 SHA512:
-  metadata.gz: 4d135ab13fc7b995cfb1fa029900902d458f1ec84d8eb7d7a1e2a54daeecf757cbfceee0a8491b8e9aeb427e7f18c01800dd227652859ea01f40fd472a55ca67
-  data.tar.gz: 94aeb96c6fb123a76d0056785ce12489fc5d4d2d176491e5da2d35c93f3d74e4c2d53509c7932958d687abd22510e95ef30ba3fffe2cfc141389434143166332
+  metadata.gz: ebf987777a3b98062f132330f17ba646840085cd63a123c04d944997002c42c1049cb325f0eb66dfee4ecb0dfb4127b279a96e6a298aa73b1bb61f56ce7caba5
+  data.tar.gz: fe109bde2907c60ef0c15f3eaa4e4ea7fc1a4f98d2f0c05f7ceaad78b7e2ab0ea7c632fa7851497df8630aeff7adb145f7bab093059af136519cfdb80ad62e5d

data/.claude/agents/cursor-spec-reviewer.md

@@ -0,0 +1,76 @@
+---
+name: cursor-spec-reviewer
+description: "Use this agent when you need to verify that converted Cursor rule files (.mdc) produced by Caruso strictly conform to the official Cursor documentation and specifications. This includes reviewing frontmatter structure, metadata fields, file naming conventions, and content formatting. Launch this agent after any conversion operation to validate output correctness.\\n\\nExamples:\\n\\n- Example 1:\\n  user: \"caruso plugin install document-skills@skills\"\\n  assistant: \"I've installed the document-skills plugin and converted the files to Cursor format. Let me now verify the output is correct.\"\\n  <commentary>\\n  Since a conversion just happened, use the Task tool to launch the cursor-spec-reviewer agent to validate all generated .mdc files in .cursor/rules/caruso/ against the official Cursor specification.\\n  </commentary>\\n  assistant: \"Now let me use the cursor-spec-reviewer agent to validate the converted files against the Cursor specification.\"\\n\\n- Example 2:\\n  user: \"Can you check if these .mdc files are valid Cursor rules?\"\\n  assistant: \"I'll use the cursor-spec-reviewer agent to thoroughly validate these files against the official Cursor documentation.\"\\n  <commentary>\\n  The user is asking for validation of Cursor rule files. Use the Task tool to launch the cursor-spec-reviewer agent to perform a detailed specification review.\\n  </commentary>\\n\\n- Example 3:\\n  user: \"I just ran caruso plugin update and want to make sure everything still looks right\"\\n  assistant: \"Let me launch the cursor-spec-reviewer agent to verify the updated files conform to Cursor's specifications.\"\\n  <commentary>\\n  After a plugin update, converted files may have changed. Use the Task tool to launch the cursor-spec-reviewer agent to re-validate all output files.\\n  </commentary>"
+model: opus
+memory: project
+---
+
+You are a Cursor IDE specification reviewer. Your job is to review ALL output produced by Caruso's conversion pipeline and verify it conforms to the official Cursor documentation.
+
+## Step 1: Fetch the Official Cursor Documentation
+
+**MANDATORY.** Before reviewing ANY file, use WebFetch to read the current official Cursor docs:
+
+1. `https://cursor.com/docs/agent/hooks` — hooks specification
+2. `https://cursor.com/docs/context/rules` — rules specification
+3. `https://cursor.com/docs/context/commands` — commands specification
+
+These are the ONLY authoritative sources. Do not rely on your training data, assumptions, or third-party sources. If a fetch fails, note the gap in your report.
+
+Read each page carefully and extract the exact specification: required fields, valid values, supported events, JSON schemas, file formats, and any constraints or defaults.
+
+## Step 2: Inventory Caruso Output
+
+Find all files Caruso generated. Check these locations:
+- `.cursor/rules/caruso/` — converted rule files (`.mdc`)
+- `.cursor/hooks.json` — merged hooks configuration
+- `.cursor/hooks/caruso/` — hook scripts and wrappers
+- `.cursor/commands/caruso/` — converted command files
+- `.cursor/scripts/caruso/` — copied skill scripts
+
+## Step 3: Validate Each File Against the Fetched Specs
+
+For every file found, validate it against the specification you extracted in Step 1. Check:
+- File format and structure match the spec exactly
+- All required fields are present with correct types
+- No invalid or unknown fields
+- Field values are within the allowed set (e.g., valid event names, correct boolean types)
+- Referenced file paths (scripts, commands) actually exist on disk
+- No leftover `${CLAUDE_PLUGIN_ROOT}` placeholders (these should have been rewritten)
+- Scripts are executable and non-empty
+
+Use the spec as your checklist — if the docs say a field is required, verify it exists. If the docs list valid values, verify the value is in that list. Do not invent requirements beyond what the docs state.
+
+## Step 4: Report
+
+For each file, report:
+- **Status**: PASS | WARNING | FAIL
+- **Issues**: what's wrong and why (cite the spec)
+
+End with a summary: total files, pass/warn/fail counts, overall verdict.
+
+## Rules
+
+1. **The fetched docs are your only authority.** If you can't confirm something from the docs, say so — don't guess.
+2. **Be precise about types.** String `"false"` vs boolean `false` matters. A wrong type is FAIL.
+3. **Spec violations are FAIL. Style concerns are WARNING.** Keep them separate.
+4. **Record learnings in your agent memory** for future reviews.
+
+# Persistent Agent Memory
+
+You have a persistent Persistent Agent Memory directory at `/Users/philipp/.superset/worktrees/caruso/ralph/.claude/agent-memory/cursor-spec-reviewer/`. Its contents persist across conversations.
+
+As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
+
+Guidelines:
+- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
+- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
+- Record insights about problem constraints, strategies that worked or failed, and lessons learned
+- Update or remove memories that turn out to be wrong or outdated
+- Organize memory semantically by topic, not chronologically
+- Use the Write and Edit tools to update your memory files
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+
+## MEMORY.md
+
+Your MEMORY.md is currently empty. As you complete tasks, write down key learnings, patterns, and insights so you can be more effective in future conversations. Anything saved in MEMORY.md will be included in your system prompt next time.

data/lib/caruso/adapters/command_adapter.rb

@@ -41,7 +41,7 @@ module Caruso
         # Just return content as-is, Claude Code commands are already compatible
 
         # Add note about bash execution if it contains ! prefix
-        if content.include?("!`")
+        if content.include?("`!")
           add_bash_execution_note(content)
         else
           content

data/lib/caruso/adapters/hook_adapter.rb

@@ -28,6 +28,12 @@ module Caruso
         PermissionRequest
       ].freeze
 
+      # Cursor stop events need output format translation and loop_limit.
+      STOP_EVENTS = %w[stop subagentStop].freeze
+
+      WRAPPER_PATH = File.join(".cursor", "hooks", "caruso", "_cc_stop_wrapper.sh").freeze
+      WRAPPER_SOURCE = File.expand_path("../scripts/cc_stop_wrapper.sh", __dir__).freeze
+
       # Contains translated hook commands keyed by event (for clean uninstall tracking).
       attr_reader :translated_hooks
 
@@ -46,6 +52,9 @@ module Caruso
         # Copy any referenced scripts
         copied_scripts = copy_hook_scripts(cursor_hooks, hooks_file)
 
+        # Wrap stop hook commands for Cursor compatibility (CC→Cursor output translation)
+        wrapper_scripts = wrap_stop_hooks(cursor_hooks)
+
         # Merge into existing .cursor/hooks.json
         merge_hooks(cursor_hooks)
 
@@ -55,6 +64,7 @@ module Caruso
         # Return list of created/modified files for tracking
         created = [".cursor/hooks.json"]
         created += copied_scripts
+        created += wrapper_scripts
         created
       end
 
@@ -105,19 +115,28 @@ module Caruso
               next
             end
 
-            command = hook["command"]
-            next unless command
+            cursor_entry = build_cursor_hook(event_name, matcher, hook)
+            next unless cursor_entry
 
-            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
+            event, entry = cursor_entry
+            (hooks[event] ||= []) << entry
           end
         end
 
         { hooks: hooks, skipped_prompts: skipped }
       end
 
+      def build_cursor_hook(event_name, matcher, hook)
+        command = hook["command"]
+        return unless command
+
+        cursor_event = resolve_cursor_event(event_name, matcher)
+        cursor_hook = { "command" => command }
+        cursor_hook["timeout"] = hook["timeout"] if hook["timeout"]
+        cursor_hook["loop_limit"] = nil if STOP_EVENTS.include?(cursor_event)
+        [cursor_event, cursor_hook]
+      end
+
       def warn_skipped(skipped_events, skipped_prompts)
         if skipped_events.any?
           unique_skipped = skipped_events.uniq
@@ -184,6 +203,31 @@ module Caruso
         target_path
       end
 
+      def wrap_stop_hooks(cursor_hooks)
+        has_stop = STOP_EVENTS.any? { |event| cursor_hooks.key?(event) }
+        return [] unless has_stop
+
+        wrapper_path = install_wrapper_script
+
+        STOP_EVENTS.each do |event|
+          next unless cursor_hooks[event]
+
+          cursor_hooks[event].each do |hook|
+            hook["command"] = "#{WRAPPER_PATH} #{hook['command']}"
+          end
+        end
+
+        [wrapper_path]
+      end
+
+      def install_wrapper_script
+        FileUtils.mkdir_p(File.dirname(WRAPPER_PATH))
+        FileUtils.cp(WRAPPER_SOURCE, WRAPPER_PATH)
+        File.chmod(0o755, WRAPPER_PATH)
+        puts "Installed stop hook wrapper: #{WRAPPER_PATH}"
+        WRAPPER_PATH
+      end
+
       def merge_hooks(new_hooks)
         hooks_path = File.join(".cursor", "hooks.json")
         existing = read_existing_hooks(hooks_path)

data/lib/caruso/scripts/cc_stop_wrapper.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Translates Claude Code stop hook output to Cursor format.
+#
+# CC stop hooks communicate via:
+#   Exit 2 + stderr reason       -> block (continue conversation)
+#   Exit 0 + {"decision":"block","reason":"..."} -> block
+#   Exit 0 + anything else       -> allow stop
+#
+# Cursor stop hooks expect:
+#   Exit 0 + {"followup_message":"..."} -> continue with message
+#   Exit 0 + no output                 -> allow stop
+#
+# Usage: cc_stop_wrapper.sh <original-script> [args...]
+
+set -uo pipefail
+
+SCRIPT="$1"
+shift
+
+STDERR_TMP=$(mktemp) || exit 1
+trap 'rm -f "$STDERR_TMP"' EXIT
+
+OUTPUT=$("$SCRIPT" "$@" 2>"$STDERR_TMP")
+EXIT_CODE=$?
+
+# CC exit 2 = block with stderr reason
+if [ $EXIT_CODE -eq 2 ]; then
+  REASON=$(cat "$STDERR_TMP")
+  if [ -n "$REASON" ] && command -v jq >/dev/null 2>&1; then
+    jq -n --arg msg "$REASON" '{"followup_message": $msg}'
+  fi
+  exit 0
+fi
+
+# CC exit 0 + JSON {"decision":"block"} -> translate to followup_message
+if [ $EXIT_CODE -eq 0 ] && [ -n "$OUTPUT" ] && command -v jq >/dev/null 2>&1; then
+  DECISION=$(echo "$OUTPUT" | jq -r '.decision // empty' 2>/dev/null)
+  if [ "$DECISION" = "block" ]; then
+    REASON=$(echo "$OUTPUT" | jq -r '.reason // empty' 2>/dev/null)
+    [ -n "$REASON" ] && jq -n --arg msg "$REASON" '{"followup_message": $msg}'
+    exit 0
+  fi
+fi
+
+# Pass through anything else unchanged
+[ -n "$OUTPUT" ] && echo "$OUTPUT"
+exit $EXIT_CODE

data/lib/caruso/stop_hook_translator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Caruso
+  # Translates Claude Code stop hook output to Cursor format.
+  #
+  # Claude Code stop hooks communicate via:
+  #   - Exit 2 + stderr message        → block (continue the conversation)
+  #   - Exit 0 + {"decision":"block","reason":"..."} → block
+  #   - Exit 0 + no decision           → allow stop
+  #
+  # Cursor stop hooks expect:
+  #   - Exit 0 + {"followup_message":"..."} → continue with message
+  #   - Exit 0 + no output                 → allow stop
+  class StopHookTranslator
+    def self.translate(stdout:, stderr:, exit_code:)
+      new(stdout: stdout, stderr: stderr, exit_code: exit_code).translate
+    end
+
+    def initialize(stdout:, stderr:, exit_code:)
+      @stdout = stdout.to_s.strip
+      @stderr = stderr.to_s.strip
+      @exit_code = exit_code
+    end
+
+    def translate
+      return translate_exit2 if @exit_code == 2
+      return translate_json_decision if @exit_code.zero? && block_decision?
+
+      # Pass through: non-blocking exit 0 or any other exit code
+      { stdout: @stdout, exit_code: @exit_code }
+    end
+
+    private
+
+    def translate_exit2
+      if @stderr.empty?
+        { stdout: "", exit_code: 0 }
+      else
+        { stdout: JSON.generate({ "followup_message" => @stderr }), exit_code: 0 }
+      end
+    end
+
+    def translate_json_decision
+      reason = parsed_output&.fetch("reason", nil).to_s
+      if reason.empty?
+        { stdout: "", exit_code: 0 }
+      else
+        { stdout: JSON.generate({ "followup_message" => reason }), exit_code: 0 }
+      end
+    end
+
+    def block_decision?
+      parsed_output&.fetch("decision", nil) == "block"
+    end
+
+    def parsed_output
+      return @parsed_output if defined?(@parsed_output)
+
+      @parsed_output = @stdout.empty? ? nil : JSON.parse(@stdout)
+    rescue JSON::ParserError
+      @parsed_output = nil
+    end
+  end
+end

data/lib/caruso/version.rb

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

data/reference/claude_code.md

@@ -0,0 +1,13 @@
+# Claude Code Reference
+
+Official documentation: https://code.claude.com/docs
+
+- Hooks: https://code.claude.com/docs/en/hooks
+- Hooks guide: https://code.claude.com/docs/en/hooks-guide
+- Plugins: https://code.claude.com/docs/en/plugins
+- Plugins reference: https://code.claude.com/docs/en/plugins-reference
+- Create plugins: https://code.claude.com/docs/en/create-plugins
+- Discover plugins: https://code.claude.com/docs/en/discover-plugins
+- Plugin marketplaces: https://code.claude.com/docs/en/plugin-marketplaces
+- Skills: https://code.claude.com/docs/en/skills
+- Sub-agents: https://code.claude.com/docs/en/sub-agents

data/reference/cursor.md

@@ -0,0 +1,8 @@
+# Cursor Reference
+
+Official documentation: https://cursor.com/docs
+
+- Hooks: https://cursor.com/docs/agent/hooks
+- Modes: https://cursor.com/docs/agent/modes
+- Rules: https://cursor.com/docs/context/rules
+- Commands: https://cursor.com/docs/context/commands

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caruso
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.7.6
 platform: ruby
 authors:
 - Philipp Comans
@@ -130,6 +130,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/agents/cursor-spec-reviewer.md"
 - ".claude/hooks/check-gemfile-lock.sh"
 - ".claude/settings.json"
 - ".rspec"
@@ -162,19 +163,12 @@ files:
 - lib/caruso/remover.rb
 - lib/caruso/safe_dir.rb
 - lib/caruso/safe_file.rb
+- lib/caruso/scripts/cc_stop_wrapper.sh
+- lib/caruso/stop_hook_translator.rb
 - lib/caruso/version.rb
 - package-lock.json
-- reference/claude_code_create_marketplaces.md
-- reference/claude_code_hooks.md
-- reference/claude_code_marketplaces.md
-- reference/claude_code_plugins.md
-- reference/claude_code_slash_commands.md
-- reference/cursor_commands.md
-- reference/cursor_hooks.md
-- reference/cursor_modes.md
-- reference/cursor_rules.md
-- reference/plugins.md
-- reference/steering_docs.md
+- reference/claude_code.md
+- reference/cursor.md
 - tasks.md
 homepage: https://github.com/pcomans/caruso
 licenses: