npm package: @roboto-studio/cursor-rules-sync
Description: Industry-standard Cursor rules syncing utility for consistent development across repositories
Author: Roboto Studio
Latest version: 1.1.0

# @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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```yaml
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
```bash
# 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
```bash
# 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
```bash
# 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:

```typescript
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

```yaml
# .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](CONTRIBUTING.md) for details.

## 📄 License

MIT © [Roboto Studio](https://robotostudio.com)

## 🔗 Links

- [GitHub Repository](https://github.com/robotostudio/shared-modules)
- [Package Directory](https://github.com/robotostudio/shared-modules/tree/main/packages/cursor-rules-sync)
- [NPM Package](https://www.npmjs.com/package/@roboto-studio/cursor-rules-sync)
- [Documentation](https://github.com/robotostudio/shared-modules/tree/main/packages/cursor-rules-sync#readme)
- [Issue Tracker](https://github.com/robotostudio/shared-modules/issues)

---

<div align="center">
  <strong>Built with ❤️ by <a href="https://robotostudio.com">Roboto Studio</a></strong>
</div>