@roboto-studio/cursor-rules-sync

🚀 Industry-standard Cursor rules syncing utility for consistent development across repositories

A powerful NPM package that enables teams to version, sync, and manage Cursor IDE rules across multiple projects, ensuring consistent coding standards and development workflows.

✨ Features

• 🔄 Rules Syncing: Automatically sync curated rule sets across projects
• 📦 Version Management: Semantic versioning for rule sets with update tracking
• 🛠️ Thoughtful CLI: Intuitive commands for all rule management operations
• 🏗️ Clean Architecture: Industry-standard package structure with TypeScript
• 🎯 Zero Config: Works out of the box with sensible defaults
• 🔍 Discovery: Find and filter rule sets by tags and descriptions
• 💾 Backup & Recovery: Automatic backups before updates
• 🔔 Update Notifications: Automatic checks for package updates with smart caching
• 🌐 Cross-Platform: Works on macOS, Windows, and Linux

📦 Installation

# Install globally for CLI usage
npm install -g @roboto-studio/cursor-rules-sync

# Or install locally in your project
npm install @roboto-studio/cursor-rules-sync

🚀 Quick Start

1. Initialize in Your Project

# Interactive setup
cursor-sync init --interactive

# Quick setup with specific rulesets
cursor-sync init --rulesets roboto-frontend,modern-web

# Custom target directory
cursor-sync init --directory .cursor/rules --name "My Project"

2. Sync Rules

# Sync all configured rulesets
cursor-sync sync

# Sync specific rulesets only
cursor-sync sync --rulesets roboto-frontend

# Dry run to see what would change
cursor-sync sync --dry-run

3. Manage Rule Sets

# List available rule sets
cursor-sync list --all

# Show current status
cursor-sync status --check-updates

# Update to latest versions
cursor-sync update

# Add new rule sets
cursor-sync config add-ruleset modern-web

🎯 CLI Commands

Core Commands

| Command | Description | Example | |---------|-------------|---------| | init | Initialize cursor-sync in your project | cursor-sync init --interactive | | sync | Sync rules from configured rulesets | cursor-sync sync --force | | status | Show current sync status | cursor-sync status --check-updates | | update | Update rules to latest versions | cursor-sync update --dry-run | | list | List available rulesets | cursor-sync list --tags react |

Configuration Commands

| Command | Description | Example | |---------|-------------|---------| | config show | Display current configuration | cursor-sync config show --json | | config set | Update configuration values | cursor-sync config set settings.autoUpdate true | | config add-ruleset | Add a new ruleset | cursor-sync config add-ruleset roboto-sanity | | config remove-ruleset | Remove a ruleset | cursor-sync config remove-ruleset old-rules | | config enable | Enable a ruleset | cursor-sync config enable roboto-frontend | | config disable | Disable a ruleset | cursor-sync config disable experimental |

Utility Commands

| Command | Description | Example | |---------|-------------|---------| | check-updates | Check for available package updates | cursor-sync check-updates --force |

Global Options

• --verbose, -v: Enable verbose logging
• --quiet, -q: Suppress output except errors
• --debug: Enable debug logging
• --help, -h: Show help information

🏗️ Available Rule Sets

Roboto Frontend (roboto-frontend)

Comprehensive frontend development rules including:

• React best practices and patterns
• TypeScript standards
• Next.js App Router guidelines
• Component structure and styling
• Internationalization support

Roboto Sanity (roboto-sanity)

Sanity CMS development standards including:

• Schema design patterns
• GROQ query optimization
• Content modeling best practices
• Type generation workflows

Modern Web (modern-web)

Essential modern web development rules:

• TypeScript coding standards
• React development patterns
• Performance best practices
• Code organization guidelines

⚙️ Configuration

Cursor-sync uses a .cursor-sync.yml configuration file:

version: "1.0.0"
projectName: "My Awesome Project"
rulesets:
  roboto-frontend:
    version: "1.0.0"
    lastSync: "2025-01-08T10:30:00.000Z"
    enabled: true
  modern-web:
    version: "latest"
    lastSync: "2025-01-08T10:30:00.000Z"
    enabled: true
settings:
  autoUpdate: false
  targetDirectory: ".cursor/rules"
  conflictResolution: "prompt"
  backupOnUpdate: true

Settings Options

• autoUpdate: Automatically check for updates (default: false)
• targetDirectory: Where to place rule files (default: .cursor/rules)
• conflictResolution: How to handle conflicts (overwrite, skip, prompt)
• backupOnUpdate: Create backups before updates (default: true)

🔄 Workflow Examples

New Project Setup

# Initialize with interactive setup
cursor-sync init --interactive

# Or quick setup for a React/Next.js project
cursor-sync init --rulesets roboto-frontend,modern-web --name "My App"

# Commit the configuration
git add .cursor-sync.yml .cursor/rules/
git commit -m "Add cursor-sync configuration and rules"

Team Synchronization

# After cloning a project with cursor-sync
cursor-sync sync

# Check if your rules are up to date
cursor-sync status --check-updates

# Update to latest versions
cursor-sync update

Maintaining Rules

# Add new rule sets as your project evolves
cursor-sync config add-ruleset roboto-sanity

# Disable rule sets you no longer need
cursor-sync config disable experimental-rules

# Check overall status
cursor-sync status

📚 Programmatic Usage

You can also use cursor-rules-sync programmatically:

import { CursorRulesSync } from '@roboto-studio/cursor-rules-sync';

const sync = new CursorRulesSync();

// Initialize
await sync.init({
  projectName: 'My Project',
  rulesets: ['roboto-frontend', 'modern-web'],
  targetDirectory: '.cursor/rules'
});

// Sync rules
const result = await sync.sync({ force: true });

// Check for updates
const updates = await sync.checkForUpdates();

// Get available rule sets
const available = await sync.getAvailableRuleSets();

🔧 Advanced Usage

Custom Rule Sets

You can create custom rule sets by following the package structure:

rules/
  my-custom-ruleset/
    ruleset.json
    rules/
      rule1.mdc
      rule2.mdc

CI/CD Integration

# .github/workflows/sync-rules.yml
name: Sync Cursor Rules

on:
  schedule:
    - cron: '0 9 * * MON'  # Weekly on Monday
  workflow_dispatch:

jobs:
  sync-rules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install cursor-sync
        run: npm install -g @roboto-studio/cursor-rules-sync
      
      - name: Check for updates
        run: cursor-sync status --check-updates
      
      - name: Update rules
        run: cursor-sync update --dry-run

Environment Variables

• CURSOR_SYNC_CONFIG: Path to configuration file (default: .cursor-sync.yml)
• CURSOR_SYNC_LOG_LEVEL: Log level (debug, info, warn, error)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © Roboto Studio

🔗 Links

• GitHub Repository
• Package Directory
• NPM Package
• Documentation
• Issue Tracker