caruso 0.5.4

data/IMPROVEMENTS.md

@@ -0,0 +1,337 @@
+# Caruso Gem - Improvement Checklist
+
+Based on the Ruby CLI Gem Best Practices evaluation, here are the remaining tasks to bring Caruso to production-ready standards.
+
+## ✅ Completed
+
+- [x] Fix dependency management - consolidate all dependencies to gemspec
+- [x] Update RSpec to 3.13 (was inconsistent between Gemfile and gemspec)
+- [x] Add Aruba for professional CLI testing (Note: Cucumber is a transitive dependency but won't be used)
+- [x] Add RuboCop to gemspec development dependencies
+- [x] Clean up Gemfile to only contain `source` and `gemspec`
+
+> **Note on Cucumber:** Aruba requires Cucumber as a dependency, but it won't be used in this project. We only use Aruba's RSpec integration. This is normal and harmless - Cucumber won't run unless you create `.feature` files.
+
+## 🔴 Critical Priority (Do First)
+
+- [ ] **Add GitHub Actions CI workflow** _(Deferred for later)_
+  - Create `.github/workflows/ci.yml`
+  - Test on Ruby 3.0, 3.1, 3.2, 3.3
+  - Run tests automatically on push/PR
+  - Run RuboCop in CI
+  - See template in this document below
+
+- [x] **Create CHANGELOG.md**
+  - Follow [Keep a Changelog](https://keepachangelog.com/) format
+  - Document all existing versions (0.1.0, 0.1.1, 0.1.2, 0.1.3)
+  - Add Unreleased section for upcoming changes
+
+- [x] **Add LICENSE.txt file**
+  - MIT License with proper copyright attribution
+  - Now matches gemspec declaration
+
+## 🟡 High Priority
+
+- [x] **Migrate tests to use Aruba**
+  - Updated `spec/spec_helper.rb` to configure Aruba
+  - Replaced custom `run_caruso` helper with Aruba's `run_command`
+  - Migrated all 4 integration test files to use Aruba API
+  - All 32 tests passing with improved isolation and cleaner assertions
+
+- [ ] **Add release automation workflow**
+  - Create `.github/workflows/release.yml`
+  - Auto-publish to RubyGems when git tag is pushed
+  - Add `RUBYGEMS_API_KEY` secret to GitHub repo
+  - See template in this document below
+
+- [x] **Create RuboCop configuration**
+  - Added `.rubocop.yml` with sensible defaults
+  - Configured for Ruby 3.0+ with NewCops enabled
+  - Auto-corrected 57 violations (frozen string literals, string quotes, trailing whitespace, etc.)
+  - Fixed void context issue in fetcher.rb
+  - All 16 files passing with 0 offenses
+  - Tests verified passing after corrections
+
+## 🟢 Medium Priority
+
+- [ ] **Add multi-OS testing in CI**
+  - Test on Ubuntu, macOS, and Windows
+  - Ensures cross-platform compatibility
+  - Update CI matrix to include `os: [ubuntu-latest, macos-latest, windows-latest]`
+
+- [ ] **Add bundler-audit for security**
+  - Add `bundler-audit` to dev dependencies
+  - Add security check step in CI
+  - Catches vulnerable dependencies early
+
+- [ ] **Improve release documentation**
+  - Add "Releasing" section to README.md
+  - Document the release process step-by-step
+  - Integrate with new bump tasks and GitHub Actions
+
+- [ ] **Add Dependabot configuration**
+  - Create `.github/dependabot.yml`
+  - Automatically update dependencies
+  - Keep gem secure and up-to-date
+
+## 📝 Nice to Have
+
+- [ ] **Add .editorconfig**
+  - Ensures consistent formatting across editors
+  - Standardizes indentation, line endings, etc.
+
+- [ ] **Add code coverage reporting**
+  - Use SimpleCov for test coverage
+  - Add coverage badge to README
+  - Consider integrating with Codecov or Coveralls
+
+- [ ] **Add more comprehensive tests**
+  - Edge cases for CLI argument parsing
+  - Error handling scenarios
+  - Network failure simulation
+
+---
+
+## Templates and Migration Guides
+
+### GitHub Actions CI Template
+
+Create `.github/workflows/ci.yml`:
+
+```yaml
+name: Ruby CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['3.0', '3.1', '3.2', '3.3']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake spec
+
+      - name: Run RuboCop
+        run: bundle exec rubocop
+        if: matrix.ruby-version == '3.3'  # Only run once
+```
+
+### GitHub Actions Release Template
+
+Create `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Build gem
+        run: bundle exec rake build
+
+      - name: Publish to RubyGems
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          mkdir -p ~/.gem
+          echo ":rubygems_api_key: ${GEM_HOST_API_KEY}" > ~/.gem/credentials
+          chmod 0600 ~/.gem/credentials
+          gem push pkg/*.gem
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: pkg/*.gem
+          generate_release_notes: true
+```
+
+**Setup:**
+1. Go to https://rubygems.org/settings/edit
+2. Create an API key
+3. Add it to GitHub repo: Settings → Secrets → Actions → New secret
+4. Name: `RUBYGEMS_API_KEY`
+
+### CHANGELOG.md Template
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Aruba for professional CLI testing
+- RuboCop for code quality
+
+### Changed
+- Consolidated all dependencies to gemspec
+- Updated RSpec to 3.13
+
+## [0.1.3] - 2025-11-20
+
+### Added
+- Improved error handling for missing marketplaces and plugins
+
+### Changed
+- Updated caruso gem dependencies
+
+## [0.1.2] - 2025-11-XX
+
+### Added
+- Rake tasks for automated semantic version bumping
+- Script to automate version bumping
+
+## [0.1.0] - 2025-11-XX
+
+### Added
+- Initial release
+- Marketplace management (add, list, remove)
+- Plugin installation and uninstallation
+- Support for Cursor IDE integration
+- Configuration management
+- Manifest tracking for installed plugins
+
+[Unreleased]: https://github.com/pcomans/caruso/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/pcomans/caruso/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/pcomans/caruso/compare/v0.1.0...v0.1.2
+[0.1.0]: https://github.com/pcomans/caruso/releases/tag/v0.1.0
+```
+
+### Aruba Migration Guide
+
+**Before (current custom approach):**
+
+```ruby
+# spec/spec_helper.rb
+def run_caruso(*args)
+  cmd = "caruso #{args.join(' ')}"
+  output = `#{cmd} 2>&1`
+  { output: output, exit_code: $?.exitstatus }
+end
+
+# In tests:
+result = run_caruso("marketplace add https://github.com/...")
+expect(result[:exit_code]).to eq(0)
+expect(result[:output]).to include("Added marketplace")
+```
+
+**After (with Aruba):**
+
+```ruby
+# spec/spec_helper.rb
+require 'aruba/rspec'
+
+RSpec.configure do |config|
+  config.include Aruba::Api, type: :integration
+
+  # ... rest of config ...
+end
+
+# In tests:
+RSpec.describe "Marketplace Management", type: :integration do
+  it "adds a marketplace" do
+    run_command("caruso marketplace add https://github.com/...")
+
+    expect(last_command_started).to be_successfully_executed
+    expect(last_command_started).to have_output(/Added marketplace/)
+  end
+
+  it "handles errors gracefully" do
+    run_command("caruso marketplace remove nonexistent")
+
+    expect(last_command_started).to have_exit_status(0)
+    # or check for specific error output
+  end
+end
+```
+
+**Key Aruba Benefits:**
+- Automatic command isolation
+- Better stderr/stdout separation
+- Rich matchers (`be_successfully_executed`, `have_output`)
+- Support for interactive commands
+- File system helpers (automatic cleanup)
+- Environment variable manipulation
+
+**Aruba Useful Methods:**
+- `run_command(cmd)` - Run a command
+- `last_command_started` - Access last command
+- `have_output(content)` - Check output
+- `be_successfully_executed` - Check exit code 0
+- `have_exit_status(code)` - Check specific exit code
+- `stop_all_commands` - Clean up background processes
+
+### .rubocop.yml Starter
+
+```yaml
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'pkg/**/*'
+
+# Adjust these to your preferences
+Layout/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+
+Style/Documentation:
+  Enabled: false  # Enable this if you want to enforce class documentation
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes  # or single_quotes, your choice
+```
+
+---
+
+## Progress Tracking
+
+Update this section as you complete tasks:
+
+**Completed:** 9/26 tasks (35%)
+
+**Last Updated:** 2025-11-20

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Philipp Comans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,326 @@
+# Caruso
+
+**Caruso** is a tool that bridges the gap between AI coding assistants. It allows you to take "steering documentation" (rules, context, capabilities) from **Claude Code Marketplaces** and make them available to **Cursor**.
+
+## Mission
+
+Enable Cursor to consume Claude Code plugins from marketplaces by converting them to Cursor-compatible rules.
+
+## Features
+
+*   **One-time Configuration**: Initialize once with `caruso init --ide=cursor` and all commands automatically use the right settings.
+*   **Universal Fetcher**: Downloads plugins from local paths, HTTP URLs, or GitHub repositories.
+*   **Smart Adapter**: Automatically converts Claude Plugin Markdown files into **Cursor Rules** (`.mdc`), injecting necessary metadata (`globs: []`, `alwaysApply: false`) to ensure they work out of the box.
+*   **Package Manager**: Install, uninstall, and list plugins selectively. Tracks project configuration in `caruso.json` and local state in `.caruso.local.json`.
+
+## Installation
+
+### Option 1: Install from Source (Recommended)
+
+Clone the repository and build the gem:
+
+```bash
+git clone https://github.com/pcomans/caruso.git
+cd caruso
+gem build caruso.gemspec
+gem install caruso-*.gem
+```
+
+### Option 2: Using `specific_install`
+
+If you have the `specific_install` gem, you can install directly from GitHub:
+
+```bash
+gem install specific_install
+gem specific_install -l https://github.com/pcomans/caruso.git
+```
+
+## Usage
+
+Caruso mirrors the Claude Code CLI structure, providing a familiar interface for marketplace and plugin management.
+
+### Getting Started
+
+Before using Caruso, initialize it in your project directory:
+
+```bash
+# Navigate to your project
+cd /path/to/your/project
+
+# Initialize for Cursor (currently the only supported IDE)
+caruso init --ide=cursor
+```
+
+This creates a `caruso.json` config file for project settings and `.caruso.local.json` for local state. You only need to do this once per project.
+
+**What happens during init:**
+- Creates `caruso.json` and `.caruso.local.json` in your project root
+- Configures target directory (`.cursor/rules` for Cursor)
+- All subsequent commands automatically use this configuration
+
+**Version Control:**
+- ✅ **Commit to VCS:** `caruso.json` - Contains project plugin configuration (shared with team)
+- ❌ **Add to .gitignore:** `.caruso.local.json` - Contains local state (machine-specific)
+- ❌ **Add to .gitignore:** `.cursor/rules/caruso/` - Generated plugin files (build artifacts)
+
+Add these to your `.gitignore`:
+```
+# Caruso
+.caruso.local.json
+.cursor/rules/caruso/
+```
+
+### Marketplace commands
+
+Manage plugin marketplaces to discover and install plugins from different sources.
+
+#### Add a marketplace
+
+Add the official Claude Code marketplace:
+
+```bash
+caruso marketplace add https://github.com/anthropics/claude-code
+```
+
+The marketplace name is automatically read from the `marketplace.json` file in the repository (in this case, `claude-code-plugins`).
+
+Supported marketplace sources:
+- **GitHub repositories**: `https://github.com/owner/repo`
+- **Git repositories**: Any Git URL (e.g., `https://gitlab.com/company/plugins.git`)
+- **Local paths**: `./path/to/marketplace` or `./path/to/marketplace.json`
+
+#### List marketplaces
+
+View all configured marketplaces:
+
+```bash
+caruso marketplace list
+```
+
+#### Remove a marketplace
+
+Remove a marketplace from your configuration:
+
+```bash
+caruso marketplace remove claude-code
+```
+
+<Warning>
+  Removing a marketplace will not automatically uninstall plugins from that marketplace. Uninstall plugins first if you want to remove them.
+</Warning>
+
+### Plugin commands
+
+Discover, install, and manage plugins from configured marketplaces.
+
+#### List available plugins
+
+See all available plugins across configured marketplaces:
+
+```bash
+caruso plugin list
+```
+
+This shows:
+- All plugins from each marketplace
+- Installation status for each plugin
+- Plugin descriptions
+
+#### Install a plugin
+
+Install from a specific marketplace:
+
+```bash
+caruso plugin install frontend-design@claude-code
+```
+
+Install when only one marketplace is configured (marketplace name is optional):
+
+```bash
+caruso plugin install frontend-design
+```
+
+**What happens during installation:**
+1. Fetches plugin files from the marketplace
+2. Scans `commands/`, `agents/`, and `skills/` directories
+3. Converts Claude Plugin Markdown to Cursor Rules (`.mdc` format)
+4. Injects Cursor-specific metadata (`globs: []`, `alwaysApply: false`)
+5. Saves converted files to `.cursor/rules/caruso/` (vendor directory)
+6. Updates `.caruso.local.json` with installed file list
+
+#### Uninstall a plugin
+
+Remove a plugin and update the manifest:
+
+```bash
+caruso plugin uninstall frontend-design
+```
+
+### Complete workflow example
+
+Here's a complete workflow from initialization to plugin installation:
+
+```bash
+# 1. Initialize Caruso in your project
+caruso init --ide=cursor
+
+# 2. Add the official Claude Code marketplace
+caruso marketplace add https://github.com/anthropics/claude-code
+
+# 3. Browse available plugins
+caruso plugin list
+
+# 4. Install a plugin
+caruso plugin install frontend-design@claude-code
+
+# 5. Your Cursor rules are now updated!
+# 5. Your Cursor rules are now updated!
+# Files are in .cursor/rules/caruso/ and tracked in .caruso.local.json
+```
+
+## CLI Reference
+
+### Initialization
+
+```bash
+caruso init [PATH] --ide=IDE
+```
+
+Initialize Caruso in a directory. Creates `caruso.json` and `.caruso.local.json`.
+
+**Arguments:**
+- `PATH` - Project directory (optional, defaults to current directory)
+
+**Options:**
+- `--ide` - Target IDE (required). Currently supported: `cursor`
+
+**Examples:**
+```bash
+caruso init --ide=cursor                    # Initialize current directory
+caruso init . --ide=cursor                  # Explicit current directory
+caruso init /path/to/project --ide=cursor   # Initialize specific directory
+```
+
+### Marketplace Management
+
+```bash
+caruso marketplace add URL             # Add a marketplace (name from marketplace.json)
+caruso marketplace list                # List configured marketplaces
+caruso marketplace remove NAME         # Remove a marketplace
+```
+
+### Plugin Management
+
+```bash
+caruso plugin list                     # List available and installed plugins
+caruso plugin install PLUGIN[@MARKETPLACE]  # Install a plugin
+caruso plugin uninstall PLUGIN         # Uninstall a plugin
+```
+
+### Version
+
+```bash
+caruso version                         # Print Caruso version
+```
+
+## How it works
+
+1.  **Init**: Creates `caruso.json` and `.caruso.local.json` (one-time setup)
+2.  **Fetch**: Resolves marketplace URI and clones Git repositories if needed
+3.  **Scan**: Finds "steering files" in `commands/`, `agents/`, and `skills/` directories
+4.  **Adapt**: Converts Claude Plugin Markdown to Cursor Rules (`.mdc`) with metadata injection
+5.  **Manage**: Tracks installations in `.caruso.local.json` and project plugins in `caruso.json`
+
+## Development
+
+After checking out the repo:
+
+```bash
+# Install dependencies
+bundle install
+
+# Build and install the gem locally
+gem build caruso.gemspec
+gem install caruso-*.gem
+
+# Run tests
+bundle exec rake spec
+```
+
+### Testing
+
+Caruso includes comprehensive test coverage with RSpec integration tests.
+
+#### Run Tests
+
+**Quick test (offline tests only):**
+```bash
+bundle exec rake spec
+```
+
+**All tests including live marketplace integration:**
+```bash
+bundle exec rake spec:all
+# or
+RUN_LIVE_TESTS=true bundle exec rspec
+```
+
+**Only live tests:**
+```bash
+bundle exec rake spec:live
+```
+
+**Run specific test file:**
+```bash
+bundle exec rspec spec/integration/init_spec.rb
+```
+
+#### Test Structure
+
+Integration tests are organized in `spec/integration/`:
+
+- **init_spec.rb** - Initialization and configuration tests
+- **marketplace_spec.rb** - Marketplace management (add, list, remove)
+- **plugin_spec.rb** - Plugin installation and uninstallation
+- **file_validation_spec.rb** - .mdc file structure and manifest validation
+
+#### Live Tests
+
+Tests marked with `:live` tag require network access and interact with the real Claude Code marketplace:
+- Plugin installation
+- File conversion validation
+- Marketplace fetching
+
+To run live tests, set `RUN_LIVE_TESTS=true` or use `rake spec:all`.
+
+#### Test Coverage
+
+✓ **Initialization**
+  - Config file creation and validation
+  - IDE selection
+  - Double-init prevention
+  - Error handling
+
+✓ **Marketplace Management**
+  - Adding marketplaces (GitHub, Git, local)
+  - Listing marketplaces
+  - Removing marketplaces
+  - Manifest structure
+
+✓ **Plugin Management**
+  - Listing available plugins
+  - Installing plugins (explicit/implicit marketplace)
+  - Uninstalling plugins
+  - Installation status tracking
+
+✓ **File Validation**
+  - .mdc file structure (frontmatter, globs, content)
+  - File naming conventions
+  - Manifest accuracy
+  - No orphaned files
+
+For detailed testing documentation, see [TESTING.md](TESTING.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).