caruso 0.7.5 → 0.7.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eed6a0c1f2de97f2f16bdced1953bde78c4d1687e57a2be7686f4d824cce363
-  data.tar.gz: 31ad0e3bf661f0883e852c015633e42e59c2265d899b3d987ea35b64dc10d2ea
+  metadata.gz: af75d0db21770fa0559c36964cbca4cd51e80f8c96eb8097a1d41f0281ce70e3
+  data.tar.gz: 12bff57c9d9891b5abc54d2d2dd4a854ceb34faf8e3c5ad026ac3c51a0705944
 SHA512:
-  metadata.gz: d6ec542034f0cc10881b61d008b2a49fda43cfeeaed43565b00fde4c12ae0ca8a821311a9465a6ae697353047c942047281e5fed7d7b7d32c9ca4b406daaccac
-  data.tar.gz: ba2ef61be533cfd99052705ab8d0fc8489596107cf8170410b7e2edf903c0de1541f698eeda2a65b7657a655ea536259547386bffc2d5db0af932bbeaff4fc76
+  metadata.gz: cadbe6b5022e9ae58c79d8cf3fdc9750e71f10f3d6c90f920fbb3e2be18da127977e14d725a4b36ec629cfc69008cd4c8a58203492f6748185557bf0f3567fe3
+  data.tar.gz: 616a955c75e3c1e4aff04a18f282248dbf677d01ce85be4f224db2e6b08418e59fcd4b1ba9db0dda8f485e8f9684b127153f0df44c917571683c782cb45f697b

data/AGENTS.md

@@ -6,21 +6,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Caruso is a Ruby gem CLI that bridges the gap between AI coding assistants. It fetches "steering documentation" (commands, agents, skills) from Claude Code Marketplaces and converts them to formats compatible with other IDEs, currently Cursor.
 
-## Source of Truth: Claude Code Documentation
+## Source of Truth: Official Documentation
 
-**IMPORTANT:** The official Claude Code marketplace and plugin specifications are located in `/Users/philipp/code/caruso/reference/`:
+**IMPORTANT:** The authoritative sources for Claude Code and Cursor specifications are the official docs. Reference links are in `/Users/philipp/code/caruso/reference/`:
 
-- `marketplace.md` - Marketplace structure and specification
-- `plugins.md` - Plugin format and configuration
-- `plugins_reference.md` - Component configuration fields and metadata
+- `claude_code.md` - Links to official Claude Code docs (hooks, plugins, marketplaces, skills)
+- `cursor.md` - Links to official Cursor docs (hooks, modes, rules, commands)
 
-**These reference documents are the authoritative source for:**
-- Marketplace.json schema and plugin metadata format
-- Component configuration fields (`commands`, `agents`, `skills`, `hooks`, `mcpServers`)
-- Expected directory structures and file patterns
-- Metadata requirements and validation rules
-
-When implementing features or fixing bugs related to marketplace compatibility, **always consult these reference files first**. If the implementation conflicts with the reference docs, the reference docs are correct and the code should be updated to match.
+When implementing features or fixing bugs, **always fetch the latest docs from these official URLs**. If the implementation conflicts with the official docs, the docs are correct and the code should be updated to match.
 
 ## Development Commands
 
@@ -271,6 +264,9 @@ Results are deduplicated with `.uniq`.
 
 Version is managed in `lib/caruso/version.rb`.
 
+# Rules
+- **NEVER force-push.** No `git push --force`, `git push --force-with-lease`, or `git push origin <tag> --force`. If a tag or commit was pushed wrong, fix forward with a new version.
+
 # Memory
 - The goal is a clean, correct, consistent implementation. Never implement fallbacks that hide errors or engage in defensive programming.
 - **Idempotency**: Removal commands (`marketplace remove`, `plugin uninstall`) are designed to be idempotent. They exit successfully (0) if the target does not exist. This is intentional for automation friendliness and is NOT considered "hiding errors".

data/lib/caruso/adapters/command_adapter.rb

@@ -40,9 +40,9 @@ module Caruso
         # 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
+        # Convert ```! auto-execute blocks to ```bash with run instruction
         if content.include?("`!")
-          add_bash_execution_note(content)
+          convert_auto_execute_blocks(content)
         else
           content
         end
@@ -57,14 +57,9 @@ module Caruso
         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}"
+      def convert_auto_execute_blocks(content)
+        # Replace ```! with ```bash and add instruction to run
+        content.gsub("```!\n", "```bash\n")
       end
 
       def save_command_file(relative_path, content)

data/lib/caruso/adapters/hook_adapter.rb

@@ -32,37 +32,7 @@ module Caruso
       STOP_EVENTS = %w[stop subagentStop].freeze
 
       WRAPPER_PATH = File.join(".cursor", "hooks", "caruso", "_cc_stop_wrapper.sh").freeze
-
-      # Translates Claude Code stop hook output to Cursor format.
-      # CC: {"decision":"block","reason":"..."} or exit 2 with stderr
-      # Cursor: {"followup_message":"..."}
-      CC_STOP_WRAPPER = <<~'BASH'
-        #!/bin/bash
-        set -uo pipefail
-        SCRIPT="$1"
-        shift
-        STDERR_TMP=$(mktemp) || exit 1
-        trap 'rm -f "$STDERR_TMP"' EXIT
-        OUTPUT=$("$SCRIPT" "$@" 2>"$STDERR_TMP")
-        EXIT_CODE=$?
-        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
-        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
-        [ -n "$OUTPUT" ] && echo "$OUTPUT"
-        exit $EXIT_CODE
-      BASH
+      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
@@ -145,20 +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"]
-            cursor_hook["loop_limit"] = nil if STOP_EVENTS.include?(cursor_event)
-            (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
@@ -244,7 +222,7 @@ module Caruso
 
       def install_wrapper_script
         FileUtils.mkdir_p(File.dirname(WRAPPER_PATH))
-        File.write(WRAPPER_PATH, CC_STOP_WRAPPER)
+        FileUtils.cp(WRAPPER_SOURCE, WRAPPER_PATH)
         File.chmod(0o755, WRAPPER_PATH)
         puts "Installed stop hook wrapper: #{WRAPPER_PATH}"
         WRAPPER_PATH

data/lib/caruso/scripts/cc_stop_wrapper.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# Translates Claude Code stop hook I/O to Cursor format.
+#
+# INPUT translation (stdin):
+#   Cursor may pass transcript_path: null. CC hooks that read the transcript
+#   would bail out. We provide a minimal dummy transcript so the hook can
+#   proceed past transcript gates (completion promise won't match, but the
+#   core loop/block logic still works).
+#
+# OUTPUT translation (stdout):
+#   CC: exit 2 + stderr reason       -> block
+#   CC: exit 0 + {"decision":"block","reason":"..."} -> block
+#   Cursor: exit 0 + {"followup_message":"..."} -> continue with message
+#   Cursor: 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
+FAKE_TRANSCRIPT=""
+trap 'rm -f "$STDERR_TMP" "$FAKE_TRANSCRIPT"' EXIT
+
+# Read and patch stdin: ensure transcript_path points to a readable file
+INPUT=$(cat)
+if [ -n "$INPUT" ] && command -v jq >/dev/null 2>&1; then
+  TP=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+  if [ -z "$TP" ] || [ "$TP" = "null" ] || [ ! -f "$TP" ]; then
+    FAKE_TRANSCRIPT=$(mktemp) || exit 1
+    echo '{"role":"assistant","message":{"content":[{"type":"text","text":""}]}}' > "$FAKE_TRANSCRIPT"
+    INPUT=$(echo "$INPUT" | jq --arg tp "$FAKE_TRANSCRIPT" '.transcript_path = $tp')
+  fi
+fi
+
+OUTPUT=$(echo "$INPUT" | "$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.5"
+  VERSION = "0.7.7"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caruso
 version: !ruby/object:Gem::Version
-  version: 0.7.5
+  version: 0.7.7
 platform: ruby
 authors:
 - Philipp Comans
@@ -163,6 +163,8 @@ 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.md