Skip to content

[setup] add Cursor Cloud development environment instructions #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
honghaoz wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

[setup] add Cursor Cloud development environment instructions #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,3 +76,33 @@ You are an expert iOS/macOS developer with a passion for writing clean, maintain
Add short, actionable rules here when a pattern repeats.

- TODO: Add lessons and conventions here (remove this placeholder when done)

## Cursor Cloud specific instructions

### Environment overview

This is a pure Swift framework for Apple platforms (macOS/iOS/tvOS/visionOS/watchOS). The Cursor Cloud VM runs Ubuntu 24.04 (x86_64), so Apple-only frameworks (Combine, QuartzCore, AppKit, UIKit) are unavailable. This constrains what can be done on the VM:

- **Linting works fully**: `make lint` and `make format` run SwiftFormat 0.59.1 and SwiftLint 0.63.2 (Linux binaries in `bin/`).
- **Building and testing do NOT work**: `swift build` and `swift test` fail because the source code imports Apple-only frameworks without Linux `#if canImport()` guards. This is by design — the project targets Apple platforms only.

### What you CAN do on this VM

- Run `make lint` to check code style (SwiftFormat + SwiftLint).
- Run `make format` to auto-fix formatting issues.
- Read, search, and edit Swift source files.
- Validate Swift syntax via the Swift 6.0.3 toolchain (e.g. `swift -parse` on individual files that don't import Apple frameworks).

### What you CANNOT do on this VM

- `swift build` / `swift test` / `make build` — these require macOS + Xcode.
- Build or run playground projects — these require Xcode.
- Run the full test suite — tests depend on Apple-only frameworks.

### Linting tool setup

The `bin/swiftformat` and `bin/swiftlint` binaries are gitignored. The update script downloads the correct Linux versions automatically. Versions are pinned in `bin/.versions`.

### Key gotcha

The `scripts/lint.sh` script requires `bc` (for timing). The update script installs it.
Loading