From 52f5e9d55f683abe29090e4c9103eaa7acfef666 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 16 May 2026 10:07:29 +0000 Subject: [PATCH 1/2] chore: add AGENTS.md with Cursor Cloud development instructions Co-authored-by: Nitish R.G. --- AGENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e15fd5f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# AGENTS.md + +## Cursor Cloud specific instructions + +### Project overview + +RoadSOS is a Flutter mobile app (Dart) with Supabase Edge Functions (TypeScript/Deno) as the backend. The primary development loop is Flutter-based: `flutter pub get`, `dart analyze`, `flutter test`, `flutter build web`. + +### Flutter SDK + +The CI pins **Flutter 3.41.9** (Dart 3.11.5). The `pubspec.yaml` SDK constraint is `^3.11.0`. Flutter must be installed at `/opt/flutter` with `/opt/flutter/bin` on `PATH` (the update script handles this). + +### Key commands + +| Action | Command | +|---|---| +| Install deps | `flutter pub get` | +| Lint | `dart analyze` | +| Test | `flutter test` | +| Build web | `flutter build web` | +| Serve locally | `python3 -m http.server 8080` (from repo root) | + +### Environment file + +Copy `assets/env.template` to `assets/.env` before running the Flutter app. The app needs `SUPABASE_URL` and `SUPABASE_ANON_KEY` to initialize — without them the Flutter web app shows a blank page. The standalone demo at `demo/index.html` works without any env vars. + +### Testing without external services + +- `dart analyze` and `flutter test` work without any secrets or external services. +- The standalone HTML demo (`demo/index.html`) supports an **Offline Fallback** triage mode that runs keyword-based classification without a Google AI API key. +- The full Flutter web app (`flutter build web` then serve `build/web/`) requires Supabase credentials to initialize. + +### Gotchas + +- The `flutter_blue_plus_winrt` warnings during `pub get` / build are harmless (Windows-only plugin, irrelevant on Linux). +- Localization warnings about untranslated messages in `bn`, `hi`, `mr`, `ta`, `te` are expected and non-blocking. +- The Wasm dry-run warnings during `flutter build web` are informational only; the JS build succeeds. +- `assets/.env` is gitignored; it must be created from `assets/env.template` for local dev. + +### Supabase Edge Functions + +Located in `supabase/functions/`. Deploying requires the Supabase CLI and project credentials. Not required for running tests or the standalone demo. From c3443aea71d66cb51432f9f09e7741294ea45f3a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 16 May 2026 10:52:12 +0000 Subject: [PATCH 2/2] docs: update AGENTS.md with dart-define and web serving instructions Co-authored-by: Nitish R.G. --- AGENTS.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e15fd5f..4e62bd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,8 +17,9 @@ The CI pins **Flutter 3.41.9** (Dart 3.11.5). The `pubspec.yaml` SDK constraint | Install deps | `flutter pub get` | | Lint | `dart analyze` | | Test | `flutter test` | -| Build web | `flutter build web` | -| Serve locally | `python3 -m http.server 8080` (from repo root) | +| Build web | `flutter build web --dart-define=SUPABASE_URL="$SUPABASE_URL" --dart-define=SUPABASE_ANON_KEY="$SUPABASE_ANON_KEY"` | +| Serve demo | `python3 -m http.server 8080` (from repo root, then visit `/demo/index.html`) | +| Serve Flutter web | `cd build/web && python3 -m http.server 8081` | ### Environment file @@ -28,14 +29,32 @@ Copy `assets/env.template` to `assets/.env` before running the Flutter app. The - `dart analyze` and `flutter test` work without any secrets or external services. - The standalone HTML demo (`demo/index.html`) supports an **Offline Fallback** triage mode that runs keyword-based classification without a Google AI API key. -- The full Flutter web app (`flutter build web` then serve `build/web/`) requires Supabase credentials to initialize. +- The full Flutter web app requires Supabase credentials to initialize (see below). + +### Building and serving the Flutter web app + +The web build is a **release build** by default, so `.env` files are not loaded. Pass secrets via `--dart-define`: + +```bash +flutter build web \ + --dart-define=SUPABASE_URL="$SUPABASE_URL" \ + --dart-define=SUPABASE_ANON_KEY="$SUPABASE_ANON_KEY" +``` + +Serve from the build output directory directly (not the repo root), so relative asset paths resolve: + +```bash +cd build/web && python3 -m http.server 8081 +``` + +Serving from the repo root (e.g. `http://localhost:8080/build/web/`) will cause 404s for `flutter_bootstrap.js` and `manifest.json`. ### Gotchas - The `flutter_blue_plus_winrt` warnings during `pub get` / build are harmless (Windows-only plugin, irrelevant on Linux). - Localization warnings about untranslated messages in `bn`, `hi`, `mr`, `ta`, `te` are expected and non-blocking. - The Wasm dry-run warnings during `flutter build web` are informational only; the JS build succeeds. -- `assets/.env` is gitignored; it must be created from `assets/env.template` for local dev. +- `assets/.env` is not gitignored at the `assets/` path (only `/.env` at root is ignored); do not commit it with secrets. ### Supabase Edge Functions