Skip to content

README.md

Latest commit

 

History

History
201 lines (141 loc) · 5.39 KB

README.md

File metadata and controls

201 lines (141 loc) · 5.39 KB

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.

Screenshot 2025-10-22 at 16 40 25

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.