← All repositories

crossmate

A collaborative crossword app for iPhone and iPad

git clone https://code.inqk.net/crossmate.git


AGENTS.md (2765B)

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
12Use 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
23CloudKit sync uses raw `CKSyncEngine` with per-game zones and `CKShare` collaboration. It does not use NSPersistentCloudKitContainer or SwiftData.
24
25Puzzles 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## Versioning
37
38- The version recorded in `HEAD` represents an unreleased version of Crossmate.
39- Bump the version only after the preceding version has been released on the App Store; the bump begins development of the next release.
40
41## Running Tests
42
43- Run the unit suite via `bash Scripts/test-unit.sh`; the script picks a simulator automatically.
44- 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:
45  ```bash
46  bash Scripts/test-unit.sh > /tmp/test.log 2>&1; grep "Test case" /tmp/test.log; echo "---"; tail -15 /tmp/test.log
47  ```
48  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`.
49- Run the Cloudflare Worker tests via `bash Scripts/test-workers.sh` (Node's built-in test runner, no dependencies; suite lives in `Tests/Workers/`). These are fast — no capture-to-file pattern needed.