rblundon/homelab
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sync

Browse Source
This commit is contained in:
Ryan Blundon
2025-10-19 17:02:16 -05:00
parent 3f31f77bc8
commit 702c71fcff
222 changed files with 2834 additions and 10845 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
.kiro/specs/applescript-calendar-sync/design.md Normal file
View File

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

73
.kiro/specs/applescript-calendar-sync/requirements.md Normal file
View File

@@ -0,0 +1,73 @@
# Requirements Document
## Introduction
This feature enables automatic synchronization of calendar entries between two different calendar accounts using AppleScript. The system will copy events from a source calendar account to a destination calendar account, maintaining event details while avoiding duplicates and providing configurable sync options.
## Requirements
### Requirement 1
**User Story:** As a user with multiple calendar accounts, I want to sync events from one account to another, so that I can maintain consistent scheduling across different calendar systems.
#### Acceptance Criteria
1. WHEN the sync script is executed THEN the system SHALL read all events from the specified source calendar
2. WHEN events are found in the source calendar THEN the system SHALL copy them to the specified destination calendar
3. WHEN copying events THEN the system SHALL preserve event title, date, time, duration, and description
4. IF an event already exists in the destination calendar THEN the system SHALL skip creating a duplicate
### Requirement 2
**User Story:** As a user, I want to configure which calendars to sync between, so that I can control the data flow between my accounts.
#### Acceptance Criteria
1. WHEN configuring the sync THEN the system SHALL allow selection of source calendar account and specific calendar
2. WHEN configuring the sync THEN the system SHALL allow selection of destination calendar account and specific calendar
3. WHEN invalid calendar names are provided THEN the system SHALL display an error message and exit gracefully
4. WHEN calendar accounts are not accessible THEN the system SHALL provide clear error messaging
### Requirement 3
**User Story:** As a user, I want the sync to focus on today's events only, so that I maintain current day synchronization without overwhelming the destination calendar.
#### Acceptance Criteria
1. WHEN the sync runs THEN the system SHALL only process events occurring on the current day
2. WHEN determining current day THEN the system SHALL use the local system date
3. WHEN events span multiple days THEN the system SHALL include events that start or occur on the current day
4. WHEN no events exist for the current day THEN the system SHALL complete successfully with appropriate messaging
### Requirement 4
**User Story:** As a user, I want the destination calendar to mirror the source calendar for the current day, so that removed events are also cleaned up automatically.
#### Acceptance Criteria
1. WHEN checking for duplicates THEN the system SHALL compare event title, start date, and start time
2. WHEN a matching event is found in the destination THEN the system SHALL skip creating the duplicate
3. WHEN an event exists in the destination but not in the source for the current day THEN the system SHALL remove it from the destination
4. WHEN an event has been modified in the source THEN the system SHALL update the corresponding event in the destination
### Requirement 5
**User Story:** As a user, I want to see progress and results of the sync operation, so that I can verify the synchronization was successful.
#### Acceptance Criteria
1. WHEN the sync starts THEN the system SHALL display the source and destination calendar information
2. WHEN processing events THEN the system SHALL show progress indicators for each event processed
3. WHEN the sync completes THEN the system SHALL display a summary of events copied, skipped, and any errors
4. WHEN errors occur THEN the system SHALL log detailed error information for troubleshooting
### Requirement 6
**User Story:** As a user, I want the sync to handle different event types and properties, so that all my calendar data is accurately transferred.
#### Acceptance Criteria
1. WHEN syncing events THEN the system SHALL handle all-day events correctly
2. WHEN syncing events THEN the system SHALL preserve recurring event patterns when possible
3. WHEN syncing events THEN the system SHALL handle events with attendees and meeting details
4. WHEN event properties cannot be transferred THEN the system SHALL log which properties were skipped

125
.kiro/specs/applescript-calendar-sync/tasks.md Normal file
View File

@@ -0,0 +1,125 @@
# Implementation Plan
- [x] 1. Set up project structure and configuration
- Create main AppleScript file with basic structure and configuration properties
- Define configuration properties for source and destination calendars
- Set up logging and error handling framework
- _Requirements: 2.1, 2.2, 5.1_
- [ ] 2. Implement Calendar Manager component
- [ ] 2.1 Create calendar validation and access functions
- Write functions to validate calendar account and calendar names exist
- Implement calendar object retrieval with error handling
- Create function to list available calendars for debugging
- _Requirements: 2.1, 2.2, 2.3, 2.4_
- [ ]* 2.2 Write unit tests for calendar access
- Create test scenarios for invalid calendar names
- Test calendar access permission handling
- _Requirements: 2.3, 2.4_
- [ ] 3. Implement Event Reader component
- [ ] 3.1 Create current day event retrieval function
- Write function to get today's date and create date range
- Implement event query for current day from source calendar
- Handle different event types (all-day, timed events)
- _Requirements: 1.1, 3.1, 3.2, 3.3_
- [ ] 3.2 Implement event property extraction
- Create function to extract event title, dates, description, location
- Handle event property access errors gracefully
- Parse recurring events for current day occurrences
- _Requirements: 1.3, 6.1, 6.2, 6.3_
- [ ]* 3.3 Write tests for event reading functionality
- Test event retrieval with various event types
- Test property extraction accuracy
- _Requirements: 1.1, 1.3_
- [ ] 4. Implement Event Processor component
- [ ] 4.1 Create event comparison and duplicate detection
- Write function to compare events by title, start date, and start time
- Implement duplicate detection logic for existing events
- Handle event matching edge cases
- _Requirements: 4.1, 4.2_
- [ ] 4.2 Implement event creation and update functions
- Create function to add new events to destination calendar
- Implement event update functionality for modified events
- Handle event creation errors and property limitations
- _Requirements: 1.2, 1.3, 4.4, 6.4_
- [ ]* 4.3 Write tests for event processing
- Test duplicate detection accuracy
- Test event creation with various properties
- _Requirements: 4.1, 4.2, 4.4_
- [ ] 5. Implement Sync Engine component
- [ ] 5.1 Create main synchronization workflow
- Implement the main sync function that coordinates all components
- Add progress tracking and user feedback during sync
- Handle sync workflow errors and recovery
- _Requirements: 1.1, 1.2, 5.2, 5.3_
- [ ] 5.2 Implement cleanup functionality for removed events
- Create function to identify events in destination not in source
- Implement event removal from destination calendar
- Add safety checks to prevent accidental deletions
- _Requirements: 4.3_
- [ ] 5.3 Create sync reporting and statistics
- Implement sync result tracking (created, updated, removed, skipped)
- Create summary display function with detailed results
- Add error reporting and logging
- _Requirements: 5.3, 5.4_
- [ ]* 5.4 Write integration tests for sync engine
- Test complete sync workflow with test data
- Test cleanup functionality accuracy
- Test error handling and recovery
- _Requirements: 4.3, 5.3_
- [ ] 6. Implement Logger component
- [ ] 6.1 Create logging and progress display functions
- Implement message logging with different severity levels
- Create progress indicator for sync operations
- Add user-friendly error message formatting
- _Requirements: 5.1, 5.2, 5.4_
- [ ] 6.2 Implement sync summary display
- Create formatted summary of sync results
- Display statistics for events processed
- Show any errors or warnings encountered
- _Requirements: 5.3, 5.4_
- [ ] 7. Integrate all components and create main script
- [ ] 7.1 Wire together all components in main execution flow
- Create main script entry point that calls all components
- Implement proper error handling and user feedback flow
- Add configuration validation before sync starts
- _Requirements: 2.3, 2.4, 5.1_
- [ ] 7.2 Add user interaction and configuration management
- Implement user prompts for calendar selection if needed
- Add configuration validation and error messaging
- Create user-friendly script execution experience
- _Requirements: 2.1, 2.2, 2.3, 2.4_
- [ ]* 7.3 Create comprehensive end-to-end tests
- Test complete sync workflow with real calendar data
- Test all error scenarios and edge cases
- Validate sync accuracy and cleanup functionality
- _Requirements: 1.1, 1.2, 4.3, 5.3_
- [ ] 8. Finalize and optimize the script
- [ ] 8.1 Add performance optimizations and error recovery
- Optimize calendar access and event processing performance
- Add robust error recovery and rollback capabilities
- Implement proper resource cleanup and calendar app management
- _Requirements: 5.4_
- [ ] 8.2 Create user documentation and usage instructions
- Write clear instructions for script configuration and usage
- Document calendar permission requirements
- Create troubleshooting guide for common issues
- _Requirements: 2.3, 2.4, 5.4_