sync

.kiro/specs/applescript-calendar-sync/design.md

@@ -0,0 +1,209 @@
+# Design Document
+
+## Overview
+
+The AppleScript Calendar Sync system is designed as a standalone AppleScript application that synchronizes calendar events between two calendar accounts for the current day only. The system uses macOS Calendar app's AppleScript interface to read events from a source calendar and mirror them to a destination calendar, including removal of events that no longer exist in the source.
+
+## Architecture
+
+The system follows a simple pipeline architecture:
+
+```
+[Source Calendar] → [Event Reader] → [Event Processor] → [Destination Calendar]
+                                          ↓
+                                   [Duplicate Detector]
+                                          ↓
+                                   [Cleanup Manager]
+```
+
+### Core Components
+
+1. **Calendar Manager**: Handles calendar account and calendar selection/validation
+2. **Event Reader**: Retrieves events from source calendar for current day
+3. **Event Processor**: Processes and transforms events for destination calendar
+4. **Sync Engine**: Coordinates the synchronization process including cleanup
+5. **Logger**: Provides user feedback and error reporting
+
+## Components and Interfaces
+
+### Calendar Manager
+```applescript
+-- Validates and retrieves calendar references
+on getCalendar(accountName, calendarName)
+on validateCalendarAccess(calendar)
+on listAvailableCalendars()
+```
+
+**Responsibilities:**
+- Validate calendar account and calendar names exist
+- Return calendar object references for AppleScript operations
+- Handle calendar access permissions and errors
+
+### Event Reader
+```applescript
+-- Reads events from source calendar for current day
+on getEventsForToday(sourceCalendar)
+on parseEventProperties(event)
+```
+
+**Responsibilities:**
+- Query source calendar for events occurring on current date
+- Extract event properties (title, start time, end time, description, etc.)
+- Handle different event types (all-day, timed, recurring)
+
+### Event Processor
+```applescript
+-- Processes events for destination calendar
+on createEventInDestination(eventData, destinationCalendar)
+on updateExistingEvent(existingEvent, newEventData)
+on compareEvents(event1, event2)
+```
+
+**Responsibilities:**
+- Create new events in destination calendar
+- Update modified events
+- Compare events for duplicate detection
+
+### Sync Engine
+```applescript
+-- Main synchronization coordinator
+on performSync(sourceCalendar, destinationCalendar)
+on cleanupRemovedEvents(sourceEvents, destinationEvents, destinationCalendar)
+on generateSyncReport(results)
+```
+
+**Responsibilities:**
+- Coordinate the entire sync process
+- Manage event cleanup (removal of events not in source)
+- Generate sync reports and statistics
+
+### Logger
+```applescript
+-- Logging and user feedback
+on logMessage(message, level)
+on displayProgress(current, total)
+on showSyncSummary(summary)
+```
+
+**Responsibilities:**
+- Display progress information to user
+- Log errors and warnings
+- Show final sync summary
+
+## Data Models
+
+### Event Data Structure
+```applescript
+record EventData
+    title: string
+    startDate: date
+    endDate: date
+    isAllDay: boolean
+    description: string
+    location: string
+    uid: string (for duplicate detection)
+end record
+```
+
+### Sync Result Structure
+```applescript
+record SyncResult
+    eventsCreated: integer
+    eventsUpdated: integer
+    eventsRemoved: integer
+    eventsSkipped: integer
+    errors: list of strings
+end record
+```
+
+## Error Handling
+
+### Error Categories
+1. **Calendar Access Errors**: Invalid calendar names, permission issues
+2. **Event Processing Errors**: Malformed events, property access failures
+3. **Sync Operation Errors**: Network issues, calendar service unavailable
+
+### Error Handling Strategy
+- Graceful degradation: Continue processing other events when individual events fail
+- Detailed error logging with specific error messages
+- User-friendly error reporting with suggested solutions
+- Rollback capability for critical failures
+
+### Error Recovery
+```applescript
+on handleCalendarError(errorMessage)
+    -- Log error details
+    -- Provide user-friendly error message
+    -- Suggest corrective actions
+end handleCalendarError
+```
+
+## Testing Strategy
+
+### Unit Testing Approach
+Since AppleScript has limited testing frameworks, testing will focus on:
+
+1. **Manual Testing Scenarios**:
+   - Test with empty source calendar
+   - Test with events spanning multiple days
+   - Test with all-day events
+   - Test with recurring events
+   - Test calendar access errors
+
+2. **Integration Testing**:
+   - Test full sync workflow with real calendar data
+   - Test cleanup functionality (event removal)
+   - Test duplicate detection accuracy
+   - Test error handling with invalid inputs
+
+3. **Edge Case Testing**:
+   - Very long event titles and descriptions
+   - Events with special characters
+   - Overlapping events
+   - Events created/modified during sync
+
+### Test Data Requirements
+- Test calendars with known event sets
+- Events with various properties (all-day, timed, recurring)
+- Events with special characters and long descriptions
+- Calendar accounts with different permission levels
+
+## Implementation Considerations
+
+### AppleScript Calendar Integration
+- Use `Calendar` application's AppleScript dictionary
+- Handle calendar app launch and focus management
+- Manage calendar selection and event creation timing
+
+### Performance Optimization
+- Batch event operations where possible
+- Minimize calendar app UI interactions
+- Cache calendar references to avoid repeated lookups
+
+### User Experience
+- Provide clear progress indicators
+- Show meaningful error messages
+- Allow user to cancel long-running operations
+- Display comprehensive sync results
+
+### Security and Privacy
+- Request calendar access permissions appropriately
+- Handle sensitive calendar data securely
+- Provide clear information about what data is accessed
+
+## Configuration Management
+
+### User Configuration
+```applescript
+-- Configuration properties
+property sourceAccountName : "Work Account"
+property sourceCalendarName : "Main Calendar"
+property destinationAccountName : "Personal Account"
+property destinationCalendarName : "Synced Events"
+property enableLogging : true
+```
+
+### Runtime Configuration
+- Allow users to modify calendar names without editing script
+- Provide configuration validation before sync starts
+- Save user preferences for repeated use