feat: add scheduled CloudKit sync workflow with environment support

Add GitHub Actions workflow that automatically syncs macOS restore images,
Xcode versions, and Swift versions to CloudKit every 12 hours.

Code changes:
- Add environment parameter to BushelCloudKitService for dev/prod selection
- Update SyncEngine to support both file-based and environment variable PEM authentication
- Add --environment flag and CLOUDKIT_ENVIRONMENT support to SyncCommand
- Support PEM content via CLOUDKIT_PRIVATE_KEY environment variable (CI/CD friendly)

Workflow features:
- Runs every 12 hours (00:00 and 12:00 UTC) on ubuntu-latest
- Swift 6.2 with build caching for 2-4 minute runtime after initial run
- Respects fetch intervals to avoid API rate limits
- Manual trigger available via workflow_dispatch
- Cost-efficient: ~120-240 Linux minutes/month (within free tier)

Documentation:
- CLOUDKIT_SYNC_SETUP.md: comprehensive setup guide with troubleshooting
- SECRETS_SETUP.md: quick checklist for GitHub secrets configuration

Single key pair approach:
- Same S2S key works for both development and production environments
- Environment selected via CLOUDKIT_ENVIRONMENT variable, not separate keys
- Simpler setup with just 2 GitHub secrets (CLOUDKIT_KEY_ID, CLOUDKIT_PRIVATE_KEY)

Resolves #8

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: leogdion

.github/CLOUDKIT_SYNC_SETUP.md

@@ -0,0 +1,288 @@
+# CloudKit Sync Workflow Setup
+
+This document explains how to configure the scheduled CloudKit sync workflow.
+
+## Prerequisites
+
+1. Access to the CloudKit Dashboard: https://icloud.developer.apple.com/dashboard/
+2. GitHub repository admin permissions (to add secrets)
+3. Server-to-Server authentication key created in CloudKit
+
+## Setup Steps
+
+### 1. Create Server-to-Server Key (If Not Already Created)
+
+1. Visit https://icloud.developer.apple.com/dashboard/
+2. Select your container: `iCloud.com.brightdigit.Bushel`
+3. Navigate to: **API Access → Server-to-Server Keys**
+4. Click **+** to create a new key
+5. Download the `.pem` file immediately (you can only download it once)
+6. Save the file securely (e.g., `~/Downloads/AuthKey_XXXXXXXXXX.pem`)
+7. Note the **Key ID** (32-character hex string)
+
+### 2. Add GitHub Secrets
+
+**Note**: A single S2S key works for both development and production environments. The environment is selected via the `CLOUDKIT_ENVIRONMENT` variable, not the key itself.
+
+1. Go to your repository on GitHub
+2. Navigate to: **Settings → Secrets and variables → Actions**
+3. Click **New repository secret**
+
+#### Add CLOUDKIT_KEY_ID
+
+- **Name:** `CLOUDKIT_KEY_ID`
+- **Value:** Your 32-character key ID from step 1.7
+- Click **Add secret**
+
+#### Add CLOUDKIT_PRIVATE_KEY
+
+- **Name:** `CLOUDKIT_PRIVATE_KEY`
+- **Value:** Full contents of your `.pem` file
+
+  To get the content:
+  ```bash
+  cat ~/Downloads/AuthKey_XXXXXXXXXX.pem | pbcopy
+  ```
+
+  Or open in a text editor and copy all lines including:
+  ```
+  -----BEGIN PRIVATE KEY-----
+  [base64 encoded key data]
+  -----END PRIVATE KEY-----
+  ```
+
+- Click **Add secret**
+
+#### Optional: Separate Keys for Production (Advanced)
+
+For enhanced security in production environments, you can optionally use separate keys:
+
+**Benefits:**
+- Compromised dev key doesn't affect production
+- Different access controls per environment
+- Independent key rotation schedules
+
+**Setup:**
+- Create a second S2S key in CloudKit Dashboard for production
+- Add `CLOUDKIT_PROD_KEY_ID` and `CLOUDKIT_PROD_PRIVATE_KEY` secrets
+- Update workflow to use prod secrets when `CLOUDKIT_ENVIRONMENT: production`
+
+This is optional and recommended only for production deployments with real user data.
+
+### 3. Verify Setup
+
+#### Option 1: Manual Trigger (Recommended)
+
+1. Go to: **Actions → Scheduled CloudKit Sync**
+2. Click **Run workflow**
+3. Select branch: `main`
+4. Click **Run workflow**
+5. Monitor the run for errors
+
+#### Option 2: Wait for Scheduled Run
+
+The workflow runs automatically every 12 hours at:
+- 00:00 UTC (midnight)
+- 12:00 UTC (noon)
+
+### 4. Monitor Sync Status
+
+- **Actions tab:** View workflow run history and logs
+- **Email notifications:** GitHub sends emails on workflow failures (configure in Settings → Notifications)
+- **Status badge (optional):** Add to README.md:
+  ```markdown
+  ![CloudKit Sync](https://github.com/brightdigit/BushelCloud-Schedule/actions/workflows/cloudkit-sync.yml/badge.svg)
+  ```
+
+## Troubleshooting
+
+### Authentication Failed
+
+**Error:** `AUTHENTICATION_FAILED` or credential errors
+
+**Solution:**
+- Verify `CLOUDKIT_KEY_ID` matches the key in CloudKit Dashboard
+- Ensure `CLOUDKIT_PRIVATE_KEY` includes header/footer lines
+- Check for extra whitespace or newlines in secret values
+- Confirm the PEM format is correct (use `-----BEGIN PRIVATE KEY-----`, not `-----BEGIN EC PRIVATE KEY-----`)
+
+### Container Not Found
+
+**Error:** `Cannot find container`
+
+**Solution:**
+- Verify container ID: `iCloud.com.brightdigit.Bushel`
+- Ensure your Apple Developer account has access to this container
+- Check that the S2S key has permissions for this container
+
+### Quota Exceeded
+
+**Error:** `QUOTA_EXCEEDED`
+
+**Solution:**
+- This is expected if the workflow runs too frequently
+- The workflow respects default fetch intervals to prevent this
+- Do not use manual triggers more than once per hour
+
+### Build Failures
+
+**Error:** Swift build errors
+
+**Solution:**
+- Check if dependencies are accessible (MistKit, BushelKit)
+- Verify Package.resolved is committed to repository
+- Review workflow logs for specific compilation errors
+- Try clearing the cache: Delete the cache key in Actions → Caches
+
+### Network Timeout
+
+**Error:** Timeout during data fetch or sync
+
+**Solution:**
+- External data sources may be temporarily unavailable
+- The workflow will retry on the next scheduled run
+- Check status of data sources: ipsw.me, xcodereleases.com, etc.
+
+## Security Best Practices
+
+1. **Never commit `.pem` files to version control**
+2. **Rotate keys every 90 days**
+3. **Audit key usage in CloudKit Dashboard regularly**
+4. **Revoke compromised keys immediately**
+5. **Consider separate keys for production** (optional, for enhanced security when handling real user data)
+
+## Updating Secrets
+
+### Rotating Keys (Recommended Every 90 Days)
+
+1. Create a new S2S key in CloudKit Dashboard
+2. Update GitHub secrets with new values:
+   - Go to Settings → Secrets and variables → Actions
+   - Click on `CLOUDKIT_KEY_ID` → Update secret
+   - Click on `CLOUDKIT_PRIVATE_KEY` → Update secret
+3. Test with a manual workflow run
+4. Revoke the old key in CloudKit Dashboard (only after confirming new key works)
+
+**Tip**: The same key works for both development and production, so you only need to update it once.
+
+## Performance & Cost
+
+### Resource Usage
+
+- **Estimated runtime:**
+  - First run (cache miss): 8-12 minutes
+  - Subsequent runs (cache hit): 2-4 minutes
+- **Frequency:** 2 runs per day = 60 runs per month
+- **GitHub Actions usage:** ~120-240 Linux minutes per month
+- **Cost:** Well within GitHub free tier (2,000 minutes/month)
+
+### Build Caching
+
+The workflow caches the Swift build directory (`.build`) to speed up subsequent runs:
+- Cache key: Based on `Package.resolved` file hash
+- Cache invalidation: Automatic when dependencies change
+- Cache size: ~50-100 MB
+
+To clear the cache:
+1. Go to: **Actions → Caches**
+2. Find caches starting with `Linux-swift-build-`
+3. Click delete icon
+
+## CloudKit Considerations
+
+### Development vs Production
+
+This workflow currently uses the **development** CloudKit environment:
+- Changes don't affect production data
+- Free API calls for public database
+- Ideal for testing and demos
+- Uses the same S2S key as production (environment is selected via `CLOUDKIT_ENVIRONMENT`)
+
+**Switching to Production** (when ready):
+
+Simply change the environment variable in `.github/workflows/cloudkit-sync.yml`:
+
+```yaml
+- name: Run CloudKit sync
+  env:
+    CLOUDKIT_KEY_ID: ${{ secrets.CLOUDKIT_KEY_ID }}
+    CLOUDKIT_PRIVATE_KEY: ${{ secrets.CLOUDKIT_PRIVATE_KEY }}
+    CLOUDKIT_ENVIRONMENT: production  # ← Change from 'development' to 'production'
+    CLOUDKIT_CONTAINER_ID: iCloud.com.brightdigit.Bushel
+```
+
+**Important**: The same key works for both environments. The environment parameter tells CloudKit which database to use.
+
+**Recommended Approach**: Create a separate workflow file (e.g., `cloudkit-sync-production.yml`) for production syncs with manual trigger only (`workflow_dispatch`). This prevents accidental production changes and allows you to test workflow modifications in development first.
+
+### Data Sources
+
+The sync fetches from these sources (with default fetch intervals):
+- **ipsw.me** (12 hours) - macOS restore images
+- **TheAppleWiki** (12 hours) - macOS restore images
+- **Apple MESU** (1 hour) - macOS restore images signing status
+- **Mr. Macintosh** (12 hours) - macOS restore images
+- **xcodereleases.com** (12 hours) - Xcode versions
+- **swiftversion.net** (12 hours) - Swift versions
+
+The workflow respects these intervals to avoid overwhelming data sources.
+
+## Advanced Configuration
+
+### Changing Sync Frequency
+
+Edit `.github/workflows/cloudkit-sync.yml`:
+
+```yaml
+schedule:
+  - cron: '0 0 * * *'  # Once daily at midnight UTC
+  - cron: '0 */6 * * *'  # Every 6 hours
+  - cron: '0 0 * * 0'  # Weekly on Sundays
+```
+
+### Changing CloudKit Environment
+
+The workflow uses the `CLOUDKIT_ENVIRONMENT` environment variable:
+
+```yaml
+env:
+  CLOUDKIT_ENVIRONMENT: development  # or 'production'
+```
+
+Or override with command-line flag:
+
+```yaml
+.build/x86_64-unknown-linux-gnu/release/bushel-cloud sync \
+  --verbose \
+  --environment production
+```
+
+**Valid values**: `development`, `dev`, `production`, `prod`
+
+### Sync Specific Record Types Only
+
+Add flags to the sync command in the workflow:
+
+```yaml
+.build/x86_64-unknown-linux-gnu/release/bushel-cloud sync \
+  --verbose \
+  --restore-images-only  # Or --xcode-only, --swift-only
+```
+
+### Force Fetch (Ignore Intervals)
+
+Add `--force` flag to bypass fetch throttling:
+
+```yaml
+.build/x86_64-unknown-linux-gnu/release/bushel-cloud sync \
+  --verbose \
+  --force  # Fetch fresh data regardless of intervals
+```
+
+**Warning:** This increases load on external data sources and may trigger rate limits.
+
+## Questions or Issues?
+
+- Review project documentation: [CLAUDE.md](../CLAUDE.md)
+- Check S2S authentication details: [.claude/s2s-auth-details.md](../.claude/s2s-auth-details.md)
+- File an issue: https://github.com/brightdigit/BushelCloud-Schedule/issues

.github/SECRETS_SETUP.md

@@ -0,0 +1,106 @@
+# GitHub Secrets Setup Checklist
+
+This file lists exactly what secrets you need to configure for the scheduled CloudKit sync workflow.
+
+## Prerequisites
+
+Before adding secrets, you need a CloudKit Server-to-Server key:
+
+1. Visit https://icloud.developer.apple.com/dashboard/
+2. Select container: `iCloud.com.brightdigit.Bushel`
+3. Navigate to: **API Access → Server-to-Server Keys**
+4. Click **+** to create a new key
+5. Download the `.pem` file (you can only download once!)
+6. Copy the Key ID (32-character hex string)
+
+## Required Secrets
+
+You need to add **2 secrets** to your GitHub repository:
+
+### 1. CLOUDKIT_KEY_ID
+
+**Where to add:**
+- Repository → Settings → Secrets and variables → Actions → New repository secret
+
+**Secret configuration:**
+- **Name:** `CLOUDKIT_KEY_ID`
+- **Value:** Your 32-character key ID from CloudKit Dashboard
+- **Example:** `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6`
+
+### 2. CLOUDKIT_PRIVATE_KEY
+
+**Where to add:**
+- Repository → Settings → Secrets and variables → Actions → New repository secret
+
+**Secret configuration:**
+- **Name:** `CLOUDKIT_PRIVATE_KEY`
+- **Value:** Full contents of your `.pem` file
+
+**Getting the PEM content:**
+
+Option A - Using terminal:
+```bash
+cat ~/Downloads/AuthKey_XXXXXXXXXX.pem | pbcopy
+```
+
+Option B - Using text editor:
+1. Open the `.pem` file in a text editor
+2. Copy **everything** including the header and footer lines:
+```
+-----BEGIN PRIVATE KEY-----
+MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQg...
+[multiple lines of base64 encoded data]
+...
+-----END PRIVATE KEY-----
+```
+
+**Important:** Make sure to include the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines!
+
+## Verification Checklist
+
+After adding secrets, verify:
+
+- [ ] Secret `CLOUDKIT_KEY_ID` exists in repository secrets
+- [ ] Secret `CLOUDKIT_PRIVATE_KEY` exists in repository secrets
+- [ ] PEM content includes header and footer lines
+- [ ] No extra whitespace or line breaks in key ID
+- [ ] Original `.pem` file stored securely (not in git!)
+
+## Testing the Setup
+
+1. Go to: **Actions → Scheduled CloudKit Sync**
+2. Click **Run workflow**
+3. Select branch: `main` (or current branch)
+4. Click **Run workflow**
+5. Monitor the run - it should complete successfully
+
+If you see authentication errors, double-check:
+- Key ID matches exactly (no typos)
+- PEM content is complete (including headers)
+- No extra spaces or formatting issues
+
+## Important Notes
+
+- **One key for both environments:** The same key works for development AND production CloudKit environments
+- **Environment selection:** The environment (dev/prod) is controlled by `CLOUDKIT_ENVIRONMENT` variable in the workflow file, not by the key
+- **Security:** Never commit the `.pem` file to git
+- **Rotation:** Rotate keys every 90 days for security
+
+## Quick Reference
+
+| Secret Name | Where to Get It | Format |
+|-------------|-----------------|--------|
+| `CLOUDKIT_KEY_ID` | CloudKit Dashboard → API Access → Server-to-Server Keys | 32-character hex (e.g., `a1b2c3...`) |
+| `CLOUDKIT_PRIVATE_KEY` | Downloaded `.pem` file | Multi-line PEM format with headers |
+
+## Next Steps
+
+After secrets are configured:
+- Workflow will run automatically every 12 hours
+- You can trigger manually anytime via Actions tab
+- Check workflow logs to verify successful syncs
+- Monitor CloudKit Dashboard to see synced data
+
+## Need Help?
+
+See the full setup guide: [CLOUDKIT_SYNC_SETUP.md](CLOUDKIT_SYNC_SETUP.md)