[READ ONLY MIRROR] Open Source TikTok alternative built on AT Protocol
github.com/sprksocial/client
flutter
atproto
video
dart
chore: improve agents.md
+27
-10
+27
-10
AGENTS.md
+27
-10
AGENTS.md
···
7
7
- Generated files in use: `*.g.dart`, `*.freezed.dart`, `*.gr.dart`
8
8
9
9
## Setup
10
-
1. Use Flutter `3.41.3` (stable, CI-aligned)
11
-
2. Ensure `.env` exists: `touch .env`
12
-
3. Install deps: `flutter pub get --enforce-lockfile`
10
+
1. Flutter `3.41.3` (stable, CI-aligned)
11
+
2. `touch .env` (required before `pub get`; see `.env.example` for keys)
12
+
3. `flutter pub get --enforce-lockfile`
13
+
4. `dart run build_runner build --delete-conflicting-outputs`
14
+
15
+
## Environment variables
16
+
- `.env` is loaded at startup via `flutter_dotenv`
17
+
- Typical keys: `VIDEO_SERVICE_URL`, `SPRK_APPVIEW_URL`, `MESSAGES_SERVICE_URL`, `AIP_BASE_URL`
18
+
- Never commit `.env` or platform credentials
13
19
14
20
## Common commands (repo root)
15
21
- Deps: `flutter pub get --enforce-lockfile`
16
-
- Codegen: `dart run build_runner build --delete-conflicting-outputs`
22
+
- Codegen (app): `dart run build_runner build --delete-conflicting-outputs`
23
+
- Codegen (widgetbook): `cd widgetbook && dart run build_runner build --delete-conflicting-outputs`
17
24
- Format: `dart format .`
18
25
- Format check: `dart format --set-exit-if-changed .`
19
-
- Analyze all: `flutter analyze .`
26
+
- Analyze app only: `flutter analyze lib`
27
+
- Analyze all (includes widgetbook): `flutter analyze .`
28
+
- Run tests: `flutter test --reporter=expanded`
20
29
- Run app: `flutter run`
21
30
22
31
## Code conventions
···
30
39
- Use GetIt (`GetIt.I` / `sl`) for DI-managed services
31
40
- Never hand-edit generated files; regenerate instead
32
41
42
+
## Localization (l10n)
43
+
- All user-facing strings must go through `intl_en.arb` (`lib/src/core/l10n/intl_en.arb`), never hardcoded in widgets
44
+
- Access: `AppLocalizations.of(context).someKey`
45
+
- Import: `package:spark/src/core/l10n/app_localizations.dart`
46
+
- Flutter regenerates l10n on build
47
+
33
48
## Reliability and logging
34
49
- Wrap fallible async work in `try/catch`
35
50
- After `await`: check `mounted` in widgets, `ref.mounted` in providers
36
51
- Prefer graceful failures over crashes (`AsyncValue.error`, typed/null fallback)
37
52
- Use `LogService` / `SparkLogger`, not `print`
38
-
- Log context + stack traces; use proper levels (`d`, `i`, `w`, `e`, `f`)
53
+
- Log context + stack traces; use proper levels (`v`, `d`, `i`, `w`, `e`, `f`)
39
54
40
55
## Agent workflow
41
56
1. Read nearby feature files for local patterns
42
57
2. Edit source files; run codegen when annotations/models change
43
58
3. Format touched code (`dart format .`)
44
59
4. Analyze (`flutter analyze lib`, or `flutter analyze .` for wider impact)
45
-
5. Run targeted tests first, then broader tests
60
+
5. Run targeted tests first, then broader tests (`flutter test`)
46
61
6. Keep comments minimal and only when needed
62
+
7. Only add tests for logic that actually needs verification; avoid trivial or redundant test coverage
47
63
48
64
## References
49
-
- `analysis_options.yaml`
65
+
- `analysis_options.yaml` (strict-casts, strict-raw-types; excludes `**/*.g.dart`)
50
66
- `lib/src/features/README.md`
51
67
- `lib/src/core/utils/logging/README.md`
52
-
- `.github/workflows/flutter_lint.yml`
53
-
- `.github/workflows/flutter-test.yml`
68
+
- `.github/workflows/lint.yml`
69
+
- `.github/workflows/test.yml`
54
70
- `.github/workflows/android.yml`
71
+
- `CONTRIBUTING.md`
55
72
56
73
## Safety
57
74
- Never commit secrets (`.env`, platform credentials)