|
| 1 | +--- |
| 2 | +description: Cursor Cloud environment setup and run notes for T3 Code (Cursor-specific; not for other editors/CI) |
| 3 | +alwaysApply: true |
| 4 | +--- |
| 5 | + |
| 6 | +# Cursor Cloud specific instructions |
| 7 | + |
| 8 | +These notes apply only to Cursor Cloud agents (kept out of the shared `AGENTS.md` since T3 Code is |
| 9 | +developed in many places). They cover the pre-provisioned VM environment and non-obvious run caveats. |
| 10 | + |
| 11 | +## Toolchain |
| 12 | + |
| 13 | +Pre-installed and wired into login shells (`~/.bashrc`/`~/.profile`): Node 24 (via nvm), the global |
| 14 | +`vp` (Vite+) CLI, and its bundled pnpm. `vp` is the package manager + task runner for this repo |
| 15 | +(`vp i`, `vp check`, `vp run typecheck`, `vp test`, `vp run --filter <pkg> <script>`). |
| 16 | + |
| 17 | +- Node gotcha: the base image also ships an older Node on `/exec-daemon` that wins on `PATH` in |
| 18 | + non-login shells. Run commands in a login shell (`bash -lc '...'`) or prepend |
| 19 | + `$HOME/.nvm/versions/node/v24.13.1/bin` so Node 24 (`engines.node: ^24.13.1`) is used. |
| 20 | +- `vp check` also runs the formatter (not just lint); markdown edits must be formatter-clean. Run |
| 21 | + `vp check --fix` before committing. |
| 22 | + |
| 23 | +## Running the web app |
| 24 | + |
| 25 | +- `npm run dev` (from repo root) starts contracts (watch), web (Vite, port 5733), and the server |
| 26 | + (`node --watch`, port 13773) together, auto-wiring `VITE_HTTP_URL`/`VITE_WS_URL`. Use |
| 27 | + `npm run dev:server` / `npm run dev:web` for one side. If base ports are taken it auto-offsets to |
| 28 | + the next free pair, so read the actual ports from stdout. Avoid production `build`/`start` in dev. |
| 29 | +- Auth/pairing: the server is unauthenticated by default and prints a pairing URL to stdout on startup |
| 30 | + (e.g. `http://localhost:5733/pair#token=XXXX`). Open that URL in the browser to pair before the web |
| 31 | + UI can talk to the server. Server state (SQLite, auth, projects) lives under `~/.t3` |
| 32 | + (`T3CODE_HOME`); multiple `npm run dev` instances bind different ports but share that same DB. |
| 33 | +- Agent providers are external CLIs (`codex`, `claude`, `cursor-agent`, `opencode`) probed on `PATH`. |
| 34 | + Without one installed the UI loads but no agent can run. Claude Code |
| 35 | + (`npm i -g @anthropic-ai/claude-code`) works headlessly using `ANTHROPIC_API_KEY` from the |
| 36 | + environment (the server forwards `process.env` to the child; no interactive `claude auth login` |
| 37 | + needed). Provider probing runs at startup and refreshes roughly every 5 minutes — restart the dev |
| 38 | + server to pick up a newly installed provider CLI immediately. |
| 39 | + |
| 40 | +## Android native builds (apps/mobile) |
| 41 | + |
| 42 | +The Android toolchain is pre-installed and wired into login shells: OpenJDK 17 |
| 43 | +(`JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64`; the base image's default `java` is 21, so builds must |
| 44 | +use `JAVA_HOME`), and the Android SDK at `$HOME/Android/Sdk` (`ANDROID_HOME`/`ANDROID_SDK_ROOT`) with |
| 45 | +platform-tools, `platforms;android-36`, `build-tools;36.0.0`, `ndk;27.1.12297006`, and `cmake;3.22.1`. |
| 46 | +Gradle auto-downloads any additional pinned SDK packages on demand. |
| 47 | + |
| 48 | +- Generate the native project first: from `apps/mobile`, |
| 49 | + `EXPO_NO_GIT_STATUS=1 APP_VARIANT=development npx expo prebuild --clean --platform android` |
| 50 | + (the `android/` folder is generated, not committed). RN 0.85 defaults: compileSdk/targetSdk 36, |
| 51 | + minSdk 24, NDK `27.1.12297006` (see `react-native/gradle/libs.versions.toml`). |
| 52 | +- Build with Gradle from `apps/mobile/android`, e.g. `./gradlew :app:assembleDebug`. First build is |
| 53 | + slow (Kotlin + C++/NDK codegen). Limit ABIs to speed things up, e.g. |
| 54 | + `-PreactNativeArchitectures=arm64-v8a`. Verified working end-to-end on a native module: |
| 55 | + `./gradlew :react-native-worklets:assembleDebug` compiles Kotlin + C++ and emits an AAR + `.so`s. |
| 56 | +- No emulator: this VM has no `/dev/kvm` (nested virtualization), so a hardware-accelerated Android |
| 57 | + emulator will not run. Use a physical device (`adb`) or EAS cloud builds (`vp run eas:android:*`) to |
| 58 | + actually run the app. The full IDE GUI is unnecessary here — the SDK/NDK/Gradle toolchain that |
| 59 | + Android Studio bundles is what is installed. |
| 60 | +- Known blocker for the full-app `:app:assembleDebug` (pre-existing, app-level — not the environment): |
| 61 | + `:react-native-screens:compileDebugKotlin` fails because `patches/react-native-screens@4.25.2.patch` |
| 62 | + adds new codegen props (`subtitle`, `largeSubtitle`, `navigationItemStyle`, |
| 63 | + `headerCenterBarButtonItems`, `headerToolbarItems`) to the JS spec + iOS native code but includes no |
| 64 | + Android Kotlin setters, so the generated `ScreenStackHeaderConfigManagerInterface` is unimplemented. |
| 65 | + The mobile README documents only iOS for local builds and routes Android through EAS. Fixing local |
| 66 | + Android app builds requires an app/patch change (add the Android Kotlin setters), which is out of |
| 67 | + scope for environment setup. |
| 68 | + |
| 69 | +## Known flaky tests (unrelated to setup) |
| 70 | + |
| 71 | +- `apps/server/src/git/GitManager.test.ts` (cross-repo PR metadata, can time out at 12s). |
| 72 | +- `apps/server/src/provider/Layers/ProviderRegistry.test.ts` (codex binaryPath re-probe ordering). |
0 commit comments