crossmate

A collaborative crossword app for iOS
Log | Files | Refs | LICENSE

AGENTS.md (2328B)

      1 # AGENTS.md
      2 
      3 ## Project Context
      4 
      5 - This app is called Crossmate.
      6 - Crossmate is a collaborative crossword app for iOS and iPadOS.
      7 - Crossmate syncs shared game state using Apple's CloudKit.
      8 - Scripts for common tasks, including running tests, live in `Scripts/`.
      9 
     10 ## Code Structure
     11 
     12 Use this file for orientation only; inspect the current filesystem and code before assuming detailed structure or ownership.
     13 
     14 - `Crossmate/` is the iOS/iPadOS app.
     15 - `NotificationService/` is the notification service extension.
     16 - `Shared/` contains code shared by the app and extension.
     17 - `Tests/` contains the unit test suite.
     18 - `Scripts/` contains common build/test/development scripts.
     19 - `Puzzles/` contains bundled and debug puzzle resources.
     20 - `Workers/` contains Cloudflare Workers for realtime engagement and push notifications.
     21 - `Crossmake/` is the separate offline crossword generation utility. It is an SPM package used to author bundled puzzles, not part of the app build.
     22 
     23 CloudKit sync uses raw `CKSyncEngine` with per-game zones and `CKShare` collaboration. It does not use NSPersistentCloudKitContainer or SwiftData.
     24 
     25 Puzzles are plain-text `.xd` files. Other supported puzzle formats are converted to XD on import.
     26 
     27 ## Working Notes
     28 
     29 - If `.agents/local.md` exists, read it for private machine-local instructions. Do not commit it.
     30 
     31 ## Building
     32 
     33 - The Xcode project is generated from `project.yml` using XcodeGen. Do not edit `Crossmate.xcodeproj/project.pbxproj` directly; run `xcodegen generate` after changing project structure.
     34 - Compile-check changes via `bash Scripts/build.sh`; the script picks a simulator automatically. Use this for a quick build instead of running the full unit suite.
     35 
     36 ## Running Tests
     37 
     38 - Run the unit suite via `bash Scripts/test-unit.sh`; the script picks a simulator automatically.
     39 - Capture the full output to a file on the first run, then grep + tail — never re-run the suite just to look at different parts of the output. One-shot pattern:
     40   ```bash
     41   bash Scripts/test-unit.sh > /tmp/test.log 2>&1; grep "Test case" /tmp/test.log; echo "---"; tail -15 /tmp/test.log
     42   ```
     43   This surfaces every per-case result and the trailing summary (totals on success, `.xcresult` path on failure). For more context on a failure, grep around the failure line in the same log file or open the `.xcresult`.