Skip to content

Add AGENTS.md with Cursor Cloud development environment setup #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
JoDavidsson wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Add AGENTS.md with Cursor Cloud development environment setup #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
51 changes: 51 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# AGENTS.md

## Cursor Cloud specific instructions

### Architecture overview

Swiper is a furniture discovery app ("Tinder for sofas"). Three main services:

| Service | Tech | Location | Dev port |
|---|---|---|---|
| Firebase Emulators (Firestore + Functions + Auth) | Node.js 20 / TypeScript | `firebase/functions/` | Firestore: 8180, Functions: 5002, Auth: 9099, UI: 4100 |
| Flutter Web App | Flutter/Dart | `apps/Swiper_flutter/` | 8080 |
| Supply Engine | Python 3.11+ / FastAPI | `services/supply_engine/` | 8081 |

### Running services

Standard commands are documented in `README.md` (Quick start) and `docs/RUNBOOK_LOCAL_DEV.md`.

**Start order:** Emulators first, then ingest sample data, then Flutter web.

```
# Terminal 1: Firebase emulators (must be first)
./scripts/run_emulators.sh

# Terminal 2: Ingest sample data (one-time per emulator session)
FIRESTORE_EMULATOR_HOST=localhost:8180 ./scripts/ingest_sample_feed.sh

# Terminal 3: Flutter web (headless-friendly)
flutter run -d web-server --web-port=8080 \
--dart-define=USE_FIREBASE_AUTH_EMULATOR=true \
--dart-define=FIREBASE_AUTH_EMULATOR_HOST=localhost \
--dart-define=FIREBASE_AUTH_EMULATOR_PORT=9099
```

### Gotchas & caveats

- **Flutter web-server device:** In headless/CI environments (no display), use `-d web-server` instead of `-d chrome`. This serves the app at `http://localhost:8080` without requiring a display.
- **Node version mismatch:** The Functions `package.json` declares `"node": "20"` but Node 22 works fine; the emulator warns but runs.
- **Flutter analyze exit code:** `flutter analyze` exits with code 1 due to ~76 pre-existing info/warning-level issues (no errors). This is expected; do not treat it as a failure.
- **Emulator data persistence:** `run_emulators.sh` auto-exports Firestore data to `emulator-data/` on exit and re-imports on next start. If you need a clean state, delete `emulator-data/` before starting.
- **Supply Engine virtualenv:** Python deps are installed in `services/supply_engine/.venv`. The `ingest_sample_feed.sh` script auto-detects this venv.
- **Admin password:** Set `ADMIN_PASSWORD` in `.env` for admin console access at `/admin`.
- **CHROME_EXECUTABLE:** Set `CHROME_EXECUTABLE=/usr/local/bin/google-chrome` if Flutter can't find Chrome.

### Testing

- **Jest (Functions):** `cd firebase/functions && npx jest` — 86 tests, all should pass.
- **TypeScript check:** `cd firebase/functions && npx tsc --noEmit` — should be clean.
- **Flutter analyze:** `cd apps/Swiper_flutter && flutter analyze` — info/warnings only, no errors.
- **API smoke test:** `./scripts/smoke_test_api.sh` — requires emulators running + data ingested.
- **Integration tests:** See `docs/RUNBOOK_LOCAL_DEV.md` "Integration tests" section.
Loading