caruso 0.5.4 → 0.6.0

data/lib/caruso/config_manager.rb

@@ -167,6 +167,7 @@ module Caruso
 
     def load_project_config
       return {} unless File.exist?(@project_config_path)
+
       JSON.parse(File.read(@project_config_path))
     rescue JSON::ParserError
       {}
@@ -178,6 +179,7 @@ module Caruso
 
     def load_local_config
       return {} unless File.exist?(@local_config_path)
+
       JSON.parse(File.read(@local_config_path))
     rescue JSON::ParserError
       {}

data/lib/caruso/fetcher.rb

@@ -5,6 +5,9 @@ require "faraday"
 require "fileutils"
 require "uri"
 require "git"
+require_relative "safe_file"
+require_relative "safe_dir"
+require_relative "path_sanitizer"
 
 module Caruso
   class Fetcher
@@ -49,7 +52,7 @@ module Caruso
     end
 
     def update_cache
-      return unless Dir.exist?(cache_dir)
+      return unless SafeDir.exist?(cache_dir)
 
       Dir.chdir(cache_dir) do
         git = Git.open(".")
@@ -61,7 +64,7 @@ module Caruso
       end
 
       @registry.update_timestamp(@marketplace_name)
-    rescue => e
+    rescue StandardError => e
       handle_git_error(e)
     end
 
@@ -69,10 +72,10 @@ module Caruso
       url = source_config["url"] || source_config["repo"]
       url = "https://github.com/#{url}.git" if source_config["source"] == "github" && !url.match?(/\Ahttps?:/)
 
-      repo_name = URI.parse(url).path.split("/").last.sub(".git", "")
+      URI.parse(url).path.split("/").last.sub(".git", "")
       target_path = cache_dir
 
-      unless Dir.exist?(target_path)
+      unless SafeDir.exist?(target_path)
         # Clone the repository
         FileUtils.mkdir_p(File.dirname(target_path))
         Git.clone(url, target_path)
@@ -105,7 +108,7 @@ module Caruso
     def load_marketplace
       if local_path?
         # If marketplace_uri is a directory, find marketplace.json in it
-        if File.directory?(@marketplace_uri)
+        if SafeDir.exist?(@marketplace_uri)
           json_path = File.join(@marketplace_uri, ".claude-plugin", "marketplace.json")
           json_path = File.join(@marketplace_uri, "marketplace.json") unless File.exist?(json_path)
 
@@ -122,7 +125,7 @@ module Caruso
           @base_dir = File.dirname(@base_dir)
         end
 
-        JSON.parse(File.read(@marketplace_uri))
+        JSON.parse(SafeFile.read(@marketplace_uri))
       elsif github_repo?
         # Clone repo and read marketplace.json from it
         repo_path = clone_git_repo("url" => @marketplace_uri, "source" => "github")
@@ -138,7 +141,7 @@ module Caruso
         @marketplace_uri = json_path
         @base_dir = repo_path # Base dir is the repo root, regardless of where json is
 
-        JSON.parse(File.read(json_path))
+        JSON.parse(SafeFile.read(json_path))
       else
         response = Faraday.get(@marketplace_uri)
         JSON.parse(response.body)
@@ -146,6 +149,10 @@ module Caruso
     end
 
     def github_repo?
+      # Fixed ReDoS: Add length check to prevent catastrophic backtracking
+      # GitHub URLs and owner/repo format should be reasonably short
+      return false if @marketplace_uri.length > 512
+
       @marketplace_uri.match?(%r{\Ahttps://github\.com/[^/]+/[^/]+}) ||
         @marketplace_uri.match?(%r{\A[^/]+/[^/]+\z}) # owner/repo format
     end
@@ -153,7 +160,25 @@ module Caruso
     def fetch_plugin(plugin)
       source = plugin["source"]
       plugin_path = resolve_plugin_path(source)
-      return [] unless plugin_path && Dir.exist?(plugin_path)
+      return [] unless plugin_path
+
+      # Validate that plugin_path is safe before using it
+      # resolve_plugin_path returns paths from trusted sources:
+      # - cache_dir (under ~/.caruso/marketplaces/)
+      # - validated local paths relative to @base_dir
+      # However, we still validate to ensure no path traversal
+      begin
+        # For paths under ~/.caruso, validate against home directory
+        # For local paths, they're already validated in resolve_plugin_path
+        if plugin_path.start_with?(File.join(Dir.home, ".caruso"))
+          PathSanitizer.sanitize_path(plugin_path, base_dir: File.join(Dir.home, ".caruso"))
+        end
+      rescue PathSanitizer::PathTraversalError => e
+        warn "Invalid plugin path '#{plugin_path}': #{e.message}"
+        return []
+      end
+
+      return [] unless SafeDir.exist?(plugin_path)
 
       # Start with default directories
       files = find_steering_files(plugin_path)
@@ -186,7 +211,12 @@ module Caruso
     end
 
     def find_steering_files(plugin_path)
-      Dir.glob(File.join(plugin_path, "{commands,agents,skills}/**/*.md")).reject do |file|
+      # Validate plugin_path before using it in glob
+      # This is safe because plugin_path comes from resolve_plugin_path which returns trusted paths
+      # (either from cache_dir which is under ~/.caruso, or validated local paths)
+      glob_pattern = PathSanitizer.safe_join(plugin_path, "{commands,agents,skills}", "**", "*.md")
+
+      SafeDir.glob(glob_pattern, base_dir: plugin_path).reject do |file|
         basename = File.basename(file).downcase
         ["readme.md", "license.md"].include?(basename)
       end
@@ -199,16 +229,23 @@ module Caruso
 
       files = []
       paths.each do |path|
-        # Resolve the path relative to plugin_path
-        full_path = File.expand_path(path, plugin_path)
+        # Resolve and sanitize the path relative to plugin_path
+        # This ensures the path stays within plugin_path boundaries
+        begin
+          full_path = PathSanitizer.sanitize_path(File.expand_path(path, plugin_path), base_dir: plugin_path)
+        rescue PathSanitizer::PathTraversalError => e
+          warn "Skipping path outside plugin directory '#{path}': #{e.message}"
+          next
+        end
 
         # Handle both files and directories
         if File.file?(full_path) && full_path.end_with?(".md")
           basename = File.basename(full_path).downcase
           files << full_path unless ["readme.md", "license.md"].include?(basename)
-        elsif Dir.exist?(full_path)
-          # Find all .md files in this directory
-          Dir.glob(File.join(full_path, "**/*.md")).each do |file|
+        elsif SafeDir.exist?(full_path, base_dir: plugin_path)
+          # Find all .md files in this directory using safe_join
+          glob_pattern = PathSanitizer.safe_join(full_path, "**", "*.md")
+          SafeDir.glob(glob_pattern, base_dir: plugin_path).each do |file|
             basename = File.basename(file).downcase
             files << file unless ["readme.md", "license.md"].include?(basename)
           end

data/lib/caruso/marketplace_registry.rb

@@ -15,7 +15,7 @@ module Caruso
     def add_marketplace(name, url, install_location, ref: nil, source: "git")
       data = load_registry
       data[name] = {
-        "source" => source,  # github, git, url, local, directory
+        "source" => source, # github, git, url, local, directory
         "url" => url,
         "install_location" => install_location,
         "last_updated" => Time.now.iso8601,
@@ -51,7 +51,7 @@ module Caruso
 
     # Enhancement #3: Schema validation
     def validate_marketplace_entry(entry)
-      required = ["url", "install_location", "last_updated"]
+      required = %w[url install_location last_updated]
       missing = required - entry.keys
 
       unless missing.empty?
@@ -71,7 +71,7 @@ module Caruso
       data = JSON.parse(File.read(@registry_path))
 
       # Validate each entry
-      data.each do |name, entry|
+      data.each_value do |entry|
         validate_marketplace_entry(entry)
       end
 

data/lib/caruso/path_sanitizer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Caruso
+  # PathSanitizer provides utilities to validate and sanitize file paths
+  # to prevent path traversal attacks and ensure paths stay within expected boundaries
+  module PathSanitizer
+    class PathTraversalError < StandardError; end
+
+    # Validates that a path doesn't contain path traversal sequences
+    # and stays within the expected base directory
+    #
+    # @param path [String] The path to validate
+    # @param base_dir [String] Optional base directory to validate against
+    # @return [String] The validated, normalized path
+    # @raise [PathTraversalError] if path contains traversal sequences or escapes base_dir
+    def self.sanitize_path(path, base_dir: nil)
+      return nil if path.nil? || path.empty?
+
+      # Normalize the path to resolve any . or .. components
+      normalized_path = Pathname.new(path).expand_path
+
+      # If base_dir is provided, ensure the path stays within it
+      if base_dir
+        normalized_base = Pathname.new(base_dir).expand_path
+
+        # Check if path is within base using relative_path_from
+        # This will raise ArgumentError if path is not within base
+        begin
+          relative = normalized_path.relative_path_from(normalized_base)
+          # Check that the relative path doesn't start with ..
+          if relative.to_s.start_with?("..")
+            raise PathTraversalError, "Path escapes base directory: #{path}"
+          end
+        rescue ArgumentError
+          # Paths on different drives/volumes
+          raise PathTraversalError, "Path is not within base directory: #{path}"
+        end
+      end
+
+      normalized_path.to_s
+    end
+
+    # Safely joins path components, ensuring no traversal attacks
+    #
+    # @param base [String] The base directory
+    # @param *parts [String] Path components to join
+    # @return [String] The sanitized joined path
+    # @raise [PathTraversalError] if result would escape base directory
+    def self.safe_join(base, *parts)
+      # Join the parts
+      joined = File.join(base, *parts)
+
+      # Validate the result stays within base
+      sanitize_path(joined, base_dir: base)
+    end
+  end
+end

data/lib/caruso/safe_dir.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "path_sanitizer"
+
+module Caruso
+  class SafeDir
+    class Error < StandardError; end
+    class SecurityError < Error; end
+
+    # Safely checks if a directory exists
+    #
+    # @param path [String] The path to check
+    # @param base_dir [String] Optional base directory to restrict access to
+    # @return [Boolean] true if directory exists and is safe
+    def self.exist?(path, base_dir: nil)
+      safe_path = sanitize(path, base_dir)
+      Dir.exist?(safe_path)
+    rescue SecurityError
+      false
+    end
+
+    # Safely globs files
+    #
+    # @param pattern [String] The glob pattern
+    # @param base_dir [String] Optional base directory to restrict access to
+    # @return [Array<String>] Matching file paths
+    def self.glob(pattern, base_dir: nil)
+      # For glob, we need to be careful. Ideally we validate the base of the pattern.
+      # If pattern contains wildcards, we can't easily sanitize the whole string as a path.
+      # So we rely on the caller to have constructed the pattern safely (e.g. using safe_join).
+      # But we can still check if the resolved paths are safe if base_dir is provided.
+
+      Dir.glob(pattern).select do |path|
+        if base_dir
+          begin
+            PathSanitizer.sanitize_path(path, base_dir: base_dir)
+            true
+          rescue PathSanitizer::PathTraversalError
+            false
+          end
+        else
+          true
+        end
+      end
+    end
+
+    def self.sanitize(path, base_dir)
+      PathSanitizer.sanitize_path(path, base_dir: base_dir)
+    rescue PathSanitizer::PathTraversalError => e
+      raise SecurityError, "Invalid directory path: #{e.message}"
+    end
+    private_class_method :sanitize
+  end
+end

data/lib/caruso/safe_file.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "path_sanitizer"
+
+module Caruso
+  class SafeFile
+    class Error < StandardError; end
+    class NotFoundError < Error; end
+    class SecurityError < Error; end
+
+    # Safely reads a file from the filesystem
+    #
+    # @param path [String] The path to the file to read
+    # @param base_dir [String] Optional base directory to restrict access to
+    # @return [String] The file content
+    # @raise [NotFoundError] if the file does not exist or is not a file
+    # @raise [SecurityError] if the path is unsafe or outside base_dir
+    def self.read(path, base_dir: nil)
+      # 1. Sanitize and validate path
+      begin
+        safe_path = PathSanitizer.sanitize_path(path, base_dir: base_dir)
+      rescue PathSanitizer::PathTraversalError => e
+        raise SecurityError, "Invalid file path: #{e.message}"
+      end
+
+      # 2. Check existence and type
+      unless File.exist?(safe_path)
+        raise NotFoundError, "File not found: #{path}"
+      end
+
+      unless File.file?(safe_path)
+        raise NotFoundError, "Path is not a regular file: #{path}"
+      end
+
+      # 3. Read content
+      File.read(safe_path)
+    end
+  end
+end

data/lib/caruso/version.rb

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

data/lib/caruso.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "caruso/safe_file"
+require_relative "caruso/safe_dir"
 require_relative "caruso/version"
 require_relative "caruso/config_manager"
 require_relative "caruso/fetcher"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: caruso
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.0
 platform: ruby
 authors:
 - Philipp Comans
@@ -132,12 +132,14 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - IMPROVEMENTS.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- SECURITY.md
 - bin/caruso
 - caruso.gemspec
 - lib/caruso.rb
@@ -146,6 +148,9 @@ files:
 - lib/caruso/config_manager.rb
 - lib/caruso/fetcher.rb
 - lib/caruso/marketplace_registry.rb
+- lib/caruso/path_sanitizer.rb
+- lib/caruso/safe_dir.rb
+- lib/caruso/safe_file.rb
 - lib/caruso/version.rb
 - reference/marketplace.md
 - reference/plugins.md
@@ -163,7 +168,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/CLAUDE.md

@@ -1,276 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Mission
-
-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
-
-**IMPORTANT:** The official Claude Code marketplace and plugin specifications are located 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
-
-**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.
-
-## Development Commands
-
-### Build and Install
-```bash
-# Build the gem
-gem build caruso.gemspec
-
-# Install locally
-gem install caruso-*.gem
-
-# Verify installation
-caruso version
-```
-
-### Testing
-```bash
-# Run offline tests only (default)
-bundle exec rake spec
-# or
-bundle exec rspec
-
-# Run all tests including live marketplace integration
-bundle exec rake spec:all
-# or
-RUN_LIVE_TESTS=1 bundle exec rspec
-
-# Run only live tests
-bundle exec rake spec:live
-
-# Run specific test file
-bundle exec rspec spec/integration/plugin_spec.rb
-
-# Run specific test
-bundle exec rspec spec/integration/plugin_spec.rb:42
-```
-
-**Important:** Live tests (tagged with `:live`) interact with real marketplaces (anthropics/skills) and require network access. They can be slow (~7 minutes). Marketplace cache is stored in `~/.caruso/marketplaces/`. Integration tests set `CARUSO_TESTING_SKIP_CLONE=true` to skip Git cloning for fast offline testing.
-
-### Linting
-```bash
-bundle exec rubocop
-```
-
-### Version Management
-```bash
-# Bump patch version (0.1.3 → 0.1.4)
-bundle exec rake bump:patch
-
-# Bump minor version (0.1.4 → 0.2.0)
-bundle exec rake bump:minor
-
-# Bump major version (0.1.4 → 1.0.0)
-bundle exec rake bump:major
-```
-
-## Architecture
-
-### Core Pipeline: Fetch → Adapt → Track
-
-Caruso follows a three-stage pipeline for plugin management:
-
-1. **Fetch** (`Fetcher`) - Clones Git repositories, resolves marketplace.json, finds plugin markdown files
-2. **Adapt** (`Adapter`) - Converts Claude Code markdown to target IDE format with metadata injection
-3. **Track** (`ConfigManager`) - Records installations in `caruso.json` and `.caruso.local.json`
-
-### Key Components
-
-#### ConfigManager (`lib/caruso/config_manager.rb`)
-Manages configuration and state. Splits data between:
-
-**1. Project Config (`caruso.json`)**
-- `ide`: Target IDE (currently only "cursor" supported)
-- `target_dir`: Where to write converted files (`.cursor/rules` for Cursor)
-- `marketplaces`: Name → URL mapping
-- `plugins`: Name → metadata (marketplace source)
-- `version`: Config schema version
-
-**2. Local Config (`.caruso.local.json`)**
-- `installed_files`: Plugin Name → Array of file paths
-- `initialized_at`: Timestamp
-
-Must run `caruso init --ide=cursor` before other commands. ConfigManager handles loading/saving both files and ensures `.caruso.local.json` is gitignored.
-
-#### MarketplaceRegistry (`lib/caruso/marketplace_registry.rb`)
-Manages persistent marketplace metadata registry at `~/.caruso/known_marketplaces.json`. Contains:
-- `source`: Marketplace type (git, github, url, local, directory)
-- `url`: Original marketplace URL
-- `install_location`: Local cache path (e.g., `~/.caruso/marketplaces/skills/`)
-- `last_updated`: ISO8601 timestamp of last update
-- `ref`: Optional Git ref/branch/tag for pinning
-
-**Key features:**
-- **Schema validation**: Validates required fields and timestamp format on load
-- **Corruption handling**: Backs up corrupted registry to `.corrupted.<timestamp>` and continues with empty registry
-- **Timestamp tracking**: Updates `last_updated` when marketplace cache is refreshed
-- **Source type tracking**: Enables future support for multiple marketplace sources
-
-This registry enables persistent tracking of marketplace state across reboots, unlike the previous `/tmp` approach.
-
-#### Fetcher (`lib/caruso/fetcher.rb`)
-Resolves and fetches plugins from marketplaces. Supports:
-- GitHub repos: `https://github.com/owner/repo`
-- Git URLs: Any Git-cloneable URL
-- Local paths: `./path/to/marketplace` or `./path/to/marketplace.json`
-
-**Key behavior:**
-- Clones Git repos to `~/.caruso/marketplaces/<marketplace-name>/` (persistent across reboots)
-- Registers marketplace metadata in `~/.caruso/known_marketplaces.json` (via MarketplaceRegistry)
-- Supports Git ref/branch pinning for version control
-- Reads `marketplace.json` to find available plugins
-- Supports custom component paths: plugins can specify `commands`, `agents`, `skills` arrays pointing to non-standard locations
-- Scans standard directories: `{commands,agents,skills}/**/*.md`
-- Excludes README.md and LICENSE.md files
-- **Custom paths supplement (not replace) default directories** - this is critical
-- Detects SSH authentication errors and provides helpful error messages
-
-**marketplace.json structure:**
-```json
-{
-  "plugins": [
-    {
-      "name": "document-skills",
-      "description": "Work with documents",
-      "source": "./document-skills",
-      "skills": ["./document-skills/xlsx", "./document-skills/pdf"]
-    }
-  ]
-}
-```
-
-The `commands`, `agents`, and `skills` fields accept:
-- String: `"./custom/path"`
-- Array: `["./path1", "./path2"]`
-
-Both files and directories are supported. Fetcher recursively finds all `.md` files.
-
-#### Adapter (`lib/caruso/adapter.rb`)
-Converts Claude Code markdown files to target IDE format. For Cursor:
-- Renames `.md` → `.mdc`
-- Injects YAML frontmatter with required Cursor metadata:
-  - `globs: []` - Enables semantic search (Apply Intelligently)
-  - `alwaysApply: false` - Prevents auto-application to every chat
-  - `description` - Preserved from original or generated
-- Preserves existing frontmatter if present, adds missing fields
-- Handles special case: `SKILL.md` → named after parent directory to avoid collisions
-
-Returns array of created filenames (not full paths) for manifest tracking.
-
-#### CLI (`lib/caruso/cli.rb`)
-Thor-based CLI with nested commands:
-- `caruso init [PATH] --ide=cursor`
-- `caruso marketplace add URL [--ref=BRANCH]` - Add marketplace with optional Git ref pinning (name comes from marketplace.json)
-- `caruso marketplace list` - List configured marketplaces
-- `caruso marketplace remove NAME` - Remove marketplace from manifest and registry
-- `caruso marketplace update [NAME]` - Update marketplace cache (all if no name given)
-- `caruso marketplace info NAME` - Show detailed marketplace information from registry
-- `caruso plugin install|uninstall|list|update|outdated`
-
-**Important patterns:**
-- All commands except `init` require existing `caruso.json` (enforced by `load_config` helper)
-- Plugin install format: `plugin@marketplace` or just `plugin` (if only one marketplace configured)
-- Update commands refresh marketplace cache (git pull) before fetching latest plugin files
-- Marketplace add eagerly clones repos unless `CARUSO_TESTING_SKIP_CLONE` env var is set (used in tests)
-- **Marketplace names always come from marketplace.json `name` field (required)** - no custom names allowed
-- Errors use descriptive messages with suggestions (e.g., "use 'caruso marketplace add <url>'")
-
-### Data Flow Example
-
-User runs: `caruso plugin install document-skills@skills`
-
-1. **CLI** parses command, loads config from `caruso.json`
-2. **ConfigManager** looks up marketplace "skills" URL
-3. **Fetcher** clones/updates marketplace repo to `~/.caruso/marketplaces/skills/`
-4. **Fetcher** registers/updates marketplace metadata in MarketplaceRegistry
-5. **Fetcher** reads `marketplace.json`, finds document-skills plugin
-6. **Fetcher** scans standard directories + custom paths from `skills: [...]` array
-7. **Fetcher** returns list of `.md` file paths
-8. **Adapter** converts each file: adds frontmatter, renames to `.mdc`, writes to `.cursor/rules/caruso/`
-9. **Adapter** returns created filenames
-10. **ConfigManager** records plugin in `caruso.json` and files in `.caruso.local.json`
-11. **CLI** prints success message
-
-### Testing Architecture
-
-Uses **Aruba** for CLI integration testing. Test structure:
-- `spec/unit/` - Direct class testing (ConfigManager, Fetcher logic)
-- `spec/integration/` - Full CLI workflow tests via Aruba subprocess execution
-
-**Aruba helpers in spec_helper.rb:**
-- `init_caruso(ide: "cursor")` - Runs init command with success assertion
-- `add_marketplace(url, name)` - Adds marketplace with success assertion
-- `config_file`, `manifest_file`, `load_config`, `load_manifest` - File access helpers
-- `mdc_files` - Glob for `.cursor/rules/*.mdc` files
-
-**Critical testing pattern:**
-```ruby
-run_command("caruso plugin install foo@bar")
-expect(last_command_started).to be_successfully_executed  # Always verify success first!
-manifest = load_manifest  # Then access results
-```
-
-**Why this matters:** If command fails, manifest might not exist (nil). Always assert success before accessing command results to prevent confusing test failures.
-
-**Live tests:**
-- Tagged with `:live` metadata
-- Run only when `RUN_LIVE_TESTS=1` environment variable set
-- Interact with real anthropics/skills marketplace
-- Cache cleared once at test suite start for performance
-- Use `sleep` for timestamp resolution (not `Timecop`) because Caruso runs as subprocess
-
-**Timecop limitation:** Cannot mock time in subprocesses. When testing timestamp updates in plugin reinstall scenarios, use `sleep 1.1` (ISO8601 has second precision) instead of `Timecop.travel`.
-
-## Marketplace Compatibility
-
-Caruso supports the Claude Code marketplace specification with custom component paths:
-
-- Standard structure: `{commands,agents,skills}/**/*.md`
-- Custom paths: `"commands": ["./custom/path"]` in marketplace.json
-- Both string and array formats supported
-- Custom paths **supplement** defaults (they don't replace)
-
-Example: anthropics/skills marketplace uses custom paths:
-```json
-{
-  "name": "document-skills",
-  "skills": ["./document-skills/xlsx", "./document-skills/pdf"]
-}
-```
-
-Fetcher will scan both:
-1. `./document-skills/skills/**/*.md` (default)
-2. `./document-skills/xlsx/**/*.md` (custom)
-3. `./document-skills/pdf/**/*.md` (custom)
-
-Results are deduplicated with `.uniq`.
-
-## Release Process
-
-1. Run tests: `bundle exec rake spec:all`
-2. Bump version: `bundle exec rake bump:patch` (or minor/major)
-3. Update CHANGELOG.md with release notes
-4. Commit: `git commit -m "chore: Bump version to X.Y.Z"`
-5. Tag: `git tag -a vX.Y.Z -m "Release version X.Y.Z"`
-6. Build: `gem build caruso.gemspec`
-7. Install and test: `gem install caruso-X.Y.Z.gem && caruso version`
-8. Push: `git push origin main --tags`
-
-Version is managed in `lib/caruso/version.rb`.
-
-# Memory
-- The goal is a clean, correct, consistent implementation. Never implement fallbacks that hide errors or engage in defensive programming.
-- Treat the vendor directory .cursor/rules/caruso/ as a build artifact