Sportstime/.planning/phases/05-cloudkit-crud/05-02-PLAN.md

phase, plan, type, domain

phase	plan	type	domain
05-cloudkit-crud	02	execute	data-pipeline

Add sync verification and individual record management to cloudkit_import.py.

Purpose: Enable verification that CloudKit matches local data, plus ability to manage individual records. Output: Enhanced cloudkit_import.py with --verify, --get, --update-record, and --delete-record flags.

<execution_context> ~/.claude/get-shit-done/workflows/execute-phase.md ~/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/05-cloudkit-crud/05-01-PLAN.md

Relevant source files: @Scripts/cloudkit_import.py

Tech stack available: Python 3, requests, cryptography, CloudKit server-to-server API Established patterns: query_all() for full record retrieval, compute_diff() for change detection, sync_diff() for smart sync

Prior plan context:

• Plan 05-01 adds change detection and smart sync
• query_all() returns dict of recordName -> record data
• compute_diff() identifies new/updated/unchanged/deleted

Task 1: Add sync verification with --verify flag Scripts/cloudkit_import.py Add sync verification to confirm CloudKit matches local canonical data.

1. Add --verify flag to argparse:

   • Query CloudKit for all record types
   • Compare counts with local data
   • Report discrepancies

2. Add verify_sync(ck, data_dir, verbose) function:

   • For each record type (Stadium, Team, Game, LeagueStructure, TeamAlias, StadiumAlias):
     • Query CloudKit count
     • Get local count from JSON files
     • Compare and report
   • Output format per type:

     Stadium: CloudKit=32, Local=32 [OK]
     Game: CloudKit=5758, Local=5760 [MISMATCH: 2 missing in CloudKit]
     

3. Add spot-check verification:

   • Random sample 5 records per type (if count matches)
   • Verify field values match between CloudKit and local
   • Report any field mismatches found

4. Add --verify-deep flag:

   • Full field-by-field comparison of ALL records (not just sample)
   • Report each mismatch with recordName and field name
   • Warning: "Deep verification may take several minutes for large datasets"

5. Menu integration:

   • Add option 14: "Verify sync (quick)"
   • Add option 15: "Verify sync (deep)"

Avoid: Modifying any data during verification. This is read-only.

cd Scripts && python cloudkit_import.py --verify --verbose

Should output verification report showing CloudKit vs local counts with OK/MISMATCH status. --verify flag reports accurate comparison between CloudKit and local data for all record types

Task 2: Add individual record management commands Scripts/cloudkit_import.py Add commands for managing individual records by ID.

1. Add --get <type> <id> flag:

   • Query single record by recordName
   • Print all field values in formatted output
   • Example: --get Stadium stadium_nba_td_garden

2. Add CloudKit lookup(record_names) method:

   • Use records/lookup endpoint for efficient single/batch lookup
   • Return list of records

3. Add --update-record <type> <id> <field>=<value> flag:

   • Lookup record to get current recordChangeTag
   • Update specified field(s)
   • Handle CONFLICT error with retry
   • Example: --update-record Stadium stadium_nba_td_garden capacity=19156

4. Add --delete-record <type> <id> flag:

   • Lookup record to get recordChangeTag
   • Delete single record
   • Confirm before delete (unless --force)
   • Example: --delete-record Game game_mlb_2025_ari_phi_0401

5. Add --list <type> flag:

   • Query all records of type
   • Print recordNames (one per line)
   • Support --list <type> --count for just the count
   • Example: --list Stadium prints all stadium IDs

6. Error handling:

   • Record not found: "Error: No Stadium with id 'xyz' found in CloudKit"
   • Invalid type: "Error: Unknown record type 'Foo'. Valid types: Stadium, Team, Game, ..."

Avoid: Deleting records without confirmation. Updating records without checking conflict.

cd Scripts && python cloudkit_import.py --get Stadium stadium_nba_td_garden

Should print all fields for the specified stadium record.

cd Scripts && python cloudkit_import.py --list Game --count

Should print the count of Game records in CloudKit. Individual record management commands work: --get, --list, --update-record, --delete-record

Before declaring plan complete: - [ ] `--verify` reports accurate count comparison for all record types - [ ] `--verify-deep` performs full field comparison with mismatch reporting - [ ] `--get ` retrieves and displays single record - [ ] `--list ` lists all recordNames for type - [ ] `--update-record` updates field with conflict handling - [ ] `--delete-record` deletes with confirmation - [ ] Interactive menu has options 14-15 - [ ] No regressions to existing functionality

<success_criteria>

• Verification accurately detects sync discrepancies
• Individual record operations work for all record types
• Conflict handling prevents data corruption
• All CRUD operations now fully supported
• Phase 5 complete </success_criteria>

After completion, create `.planning/phases/05-cloudkit-crud/05-02-SUMMARY.md`