caruso 0.5.4 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c64aeb60f2cf2507b6b3cad6756d9730775931e2b059384f3c43febceec1aec3
-  data.tar.gz: ba8c515ffa913873789826bb4f704445106cc8cfbf7cbedb39ab50f68289ef83
+  metadata.gz: e38c7a5007af96bb708d286a62909f07f1c1aa3b3aa800baa4a23f36c1a35814
+  data.tar.gz: 18a217953c0ec7c87bc6d9476c89bbca442fde6b45aec4614e4f58c183a3a760
 SHA512:
-  metadata.gz: d81e5ab8c88206fb14523eb0a906dfd1cb4fe98e2154580242d9cd63e7d73127497d623adb0fcf5b17c32d77cf9c1091f1bd3fab49eeeef9de1fa367d149fac8
-  data.tar.gz: 52d8eb203ad04f396b66a00b54e5235bc3f609ea394036e7d76adaf16bc9a46bc77017901a4836f3ba2451ff905f91edea747b2845c86330b32b96a38012f981
+  metadata.gz: 427385d4dca6b37150a1bcf487884db8979883d1e7e3d6caa353217b55609ad43dd97dfd1c85860379a6807c62eb37646eabe491540a54a683ec347e17edbc99
+  data.tar.gz: f04abed100aef554d47572af9507c4d7701782b6321e5f48cfdee677f5cbe5ecd82dffab4e719b2328231ea8bee1a1a041c476ee3322fbdc8653c23333d81ed5

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2
   NewCops: enable
   SuggestExtensions: false
   Exclude:
@@ -31,6 +31,7 @@ Metrics/MethodLength:
   Exclude:
     - 'spec/**/*'
     - 'lib/caruso/cli.rb'  # CLI command methods can be longer
+    - 'lib/caruso/fetcher.rb'  # Marketplace loading is complex
 
 # Line length - modern screens can handle more
 Layout/LineLength:
@@ -38,6 +39,7 @@ Layout/LineLength:
   Exclude:
     - 'spec/**/*'
     - '*.gemspec'
+    - 'lib/caruso/cli.rb'  # CLI methods can have longer conditional lines
 
 # Allow longer parameter lists for complex methods
 Metrics/ParameterLists:
@@ -56,6 +58,8 @@ Metrics/ClassLength:
   Max: 150
   Exclude:
     - 'spec/**/*'
+    - 'lib/caruso/cli.rb'  # CLI class has many Thor commands
+    - 'lib/caruso/fetcher.rb'  # Fetcher handles multiple sources
 
 # Prefer descriptive block parameter names
 Lint/UnusedBlockArgument:
@@ -140,6 +144,7 @@ Metrics/PerceivedComplexity:
   Max: 12
   Exclude:
     - 'lib/caruso/cli.rb'
+    - 'lib/caruso/fetcher.rb'  # Security validation requires complex checks
 
 # Duplicate branches are acceptable for error handling with different contexts
 Lint/DuplicateBranch:

data/AGENTS.md

@@ -0,0 +1,277 @@
+# 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.
+- **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".
+- Treat the vendor directory .cursor/rules/caruso/ as a build artifact

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.2] - 2025-12-17
+
+### Fixed
+- `marketplace remove` now exits gracefully (code 0) when marketplace is not found, making it idempotent
+- Documented idempotent behavior of `marketplace remove` and `plugin uninstall` in README
+
+## [0.6.0] - 2025-11-24
+
+### Security
+- **CRITICAL**: Addressed "Uncontrolled data used in path expression" vulnerabilities (CodeQL)
+- Introduced `Caruso::SafeFile` for secure file reading with strict path sanitization
+- Introduced `Caruso::SafeDir` for secure directory operations (globbing, existence checks)
+- Replaced all vulnerable `File` and `Dir` calls in `Adapter` and `Fetcher` with safe alternatives
+- Removed redundant string-based path validation in favor of robust `Pathname` canonicalization
+
+### Changed
+- `Adapter` now strictly validates file existence and raises errors instead of silently skipping invalid files
+- `Fetcher` now filters glob results to ensure they remain within trusted plugin directories
+
+
 ## [0.5.3] - 2025-11-23
 
 ### Changed

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/README.md

@@ -15,24 +15,27 @@ Enable Cursor to consume Claude Code plugins from marketplaces by converting the
 
 ## Installation
 
-### Option 1: Install from Source (Recommended)
+### Install from RubyGems
 
-Clone the repository and build the gem:
+```bash
+gem install caruso
+```
+
+Verify the installation:
 
 ```bash
-git clone https://github.com/pcomans/caruso.git
-cd caruso
-gem build caruso.gemspec
-gem install caruso-*.gem
+caruso version
 ```
 
-### Option 2: Using `specific_install`
+### Install from Source (Development)
 
-If you have the `specific_install` gem, you can install directly from GitHub:
+For development or testing unreleased features:
 
 ```bash
-gem install specific_install
-gem specific_install -l https://github.com/pcomans/caruso.git
+git clone https://github.com/pcomans/caruso.git
+cd caruso
+gem build caruso.gemspec
+gem install caruso-*.gem
 ```
 
 ## Usage

data/SECURITY.md

@@ -0,0 +1,98 @@
+# Security Policy
+
+## Supported Versions
+
+We release patches for security vulnerabilities in the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.5.x   | :white_check_mark: |
+| < 0.5   | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of Caruso seriously. If you discover a security vulnerability, please follow these steps:
+
+### 1. **Do Not** Open a Public Issue
+
+Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.
+
+### 2. Report Privately
+
+Please report security vulnerabilities using GitHub's private vulnerability reporting:
+
+- Go to the [Security tab](https://github.com/pcomans/caruso/security)
+- Click "Report a vulnerability"
+- Fill out the form with details about the vulnerability
+
+### 3. Include Details
+
+Please include as much of the following information as possible:
+
+- Type of vulnerability (e.g., command injection, path traversal, etc.)
+- Step-by-step instructions to reproduce the issue
+- Proof of concept or exploit code (if possible)
+- Impact of the vulnerability
+- Suggested fix (if you have one)
+
+### 4. What to Expect
+
+- **Acknowledgment**: We'll acknowledge your report within 48 hours
+- **Updates**: We'll keep you informed about our progress
+- **Fix Timeline**: We aim to release a fix within 7-14 days for critical vulnerabilities
+- **Credit**: With your permission, we'll credit you in the security advisory
+
+## Security Considerations
+
+When using Caruso, keep these security practices in mind:
+
+### Marketplace Sources
+
+- Only add marketplaces from trusted sources
+- Review plugin code before installation when possible
+- Be cautious with marketplaces requiring authentication
+
+### Git Credentials
+
+- Caruso uses Git to clone marketplace repositories
+- Ensure your Git credentials are properly secured
+- Use SSH keys or personal access tokens instead of passwords
+
+### File Permissions
+
+- Caruso writes files to `.cursor/rules/caruso/`
+- Ensure proper file permissions in your project directory
+- Review generated files before committing to version control
+
+### Dependencies
+
+- Keep Caruso updated to the latest version
+- Regularly update Ruby and gem dependencies
+- Run `gem update caruso` to get security patches
+
+## Scope
+
+This security policy applies to:
+
+- The Caruso gem and CLI tool
+- Official marketplace repositories maintained by this project
+- Documentation and examples in this repository
+
+It does not cover:
+
+- Third-party marketplaces or plugins
+- User-created custom plugins
+- Vulnerabilities in Ruby itself or system dependencies
+
+## Security Updates
+
+Security updates will be announced through:
+
+- GitHub Security Advisories
+- Release notes in CHANGELOG.md
+- RubyGems.org security alerts
+
+## Additional Resources
+
+- [RubyGems Security Guide](https://guides.rubygems.org/security/)
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)

data/caruso.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "A tool to fetch Claude Code plugins and adapt them into Cursor Rules or other agent contexts."
   spec.homepage = "https://github.com/pcomans/caruso"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.required_ruby_version = ">= 3.2.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/pcomans/caruso"

data/caruso.json

@@ -0,0 +1,5 @@
+{
+  "version": "1.0.0",
+  "marketplaces": {},
+  "plugins": {}
+}

data/lib/caruso/adapter.rb

@@ -2,6 +2,8 @@
 
 require "fileutils"
 require "yaml"
+require_relative "safe_file"
+require_relative "path_sanitizer"
 
 module Caruso
   class Adapter
@@ -19,7 +21,8 @@ module Caruso
     def adapt
       created_files = []
       files.each do |file_path|
-        content = File.read(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