Rules Manager

Important

This is alpha stage and will change significantly.

A native macOS application for managing Cursor rules across multiple projects with change tracking and synchronization capabilities.

Features

• Rules Source Management: Track .mdc rule files from a source directory
• Multi-Project Support: Manage rules across multiple projects simultaneously
• Directory Tree Visualization: Navigate project structures with .gitignore support
• Rule Application Tracking: Track which rules are applied to which directories
• Change Detection: Automatically detect when source rules are modified
• Batch Synchronization: Update all affected projects with a single click
• IDE Configuration: Per-project IDE settings (Cursor, VSCode, etc.)
• Filesystem Scanning: Detect manually added rules and missing files
• JSON Persistence: Human-readable state storage for version control

Requirements

• macOS 14.0 or later
• Swift 6.0 or later
• Xcode 16.0 or later (for development)

Installation

From Source

git clone https://github.com/sangdth/rules-manager.git
cd rules-manager
swift build -c release
.build/release/RulesManager

Quick Start

1. Set Up Sources Directory: Create a ./sources directory containing your .mdc rule files
2. Add Projects: Import projects you want to manage
3. Apply Rules: Navigate directory trees and apply rules to specific directories
4. Sync Changes: When source rules change, sync all affected projects

Usage

Managing Rule Sources

• Place your .mdc files in the ./sources directory
• The app monitors this directory for changes automatically
• Use "Reveal in Finder" to quickly access your sources folder
• Copy manually added rules to sources using the context menu

Working with Projects

• Click the + button to add a new project
• Select a project to view its directory structure
• Directory tree respects .gitignore patterns
• Configure IDE settings per project (default: Cursor)

Applying Rules

• Select a directory in the tree view
• Choose rules from the "Available Rules" panel
• Rules matching existing files are auto-checked
• Click "Confirm Apply" to batch apply/remove rules
• Applied rules appear as children in the directory tree

Synchronizing Changes

• Update Affected: Updates only rules that have changed
• Sync All: Force-syncs all tracked rules across all projects
• Both operations show confirmation before proceeding

Viewing State

• Switch to "JSON" tab to inspect application state
• Copy state for debugging or issue reporting
• View detected rules with status indicators:
  • ✅ Green checkmark: Applied by this app
  • ⚠️ Orange question: Manually added
  • ❌ Red warning: Tracked but file missing

Architecture

Technology Stack

• Language: Swift 6+ with strict concurrency
• UI Framework: SwiftUI with Observation framework
• Platform: macOS 14.0+
• Build System: Swift Package Manager
• Persistence: JSON files (Codable)
• File Monitoring: FSEvents

Design Pattern

MVVM architecture with actor-based services:

• Views: SwiftUI components (@MainActor isolated)
• ViewModels: Observable state management
• Services: Actor-isolated business logic
• Models: Sendable, Codable domain types

Project Structure

Sources/RulesManager/
├── Models/              # Domain models and errors
├── Services/            # Actor-based services
│   └── Protocols/       # Service protocols
├── ViewModels/          # Observable ViewModels
└── Views/               # SwiftUI views

Tests/RulesManagerTests/
├── Models/              # Model tests
├── Services/            # Service tests
├── Integration/         # Integration tests
└── Fixtures/            # Test fixtures

Development

Building

swift build

Running Tests

swift test

Running the App

swift run

Code Quality

Type checking is enforced on all changes:

swift build --build-tests

All code uses Swift 6's strict concurrency checking.

Data Storage

Application state is persisted to:

~/Library/Application Support/RulesManager/tracking-data.json

Applied rules are written to:

[Project]/.cursor/rules/         # For Cursor IDE (default)
[Project]/.vscode/rules/         # For VSCode (configurable)

Testing

• Unit Tests: 60 tests covering all models and services
• Integration Tests: Full workflow validation
• Test Coverage: 98%+ across core functionality
• Fixtures: Isolated test projects and source files

Contributing

This project is in alpha. Major changes expected.

License

TBD

Roadmap

• Enhanced file watching with debouncing
• Rule templates and snippets
• Conflict resolution UI
• Performance optimization for large projects
• Support for additional IDEs
• Import/export configurations
• Command-line interface

Known Limitations

• File watch integration test can be flaky (expected behavior)
• Large directory indexing may take time (>1000 directories)
• No real-time collaboration support
• No rule validation or parsing

Support

This is an alpha project. Use at your own risk.