chore: update README and CLI usage for cursor_gen, version bump to 1.0.1
- Changed CLI usage instructions from `dart run cursor_gen` to `cursor_gen` for global activation. - Updated project-brief.yaml example and README to reflect new command usage. - Added app_context section in project-brief.yaml for theme variants and RBAC roles. - Fixed bundled template resolution for local and global installs to prevent 'Template not found' errors. - Version bump to 1.0.1 with corresponding updates in CHANGELOG and pubspec.yaml.
This commit is contained in:
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: api-client-gen
|
||||
description: "Generates type-safe API clients for {{PROJECT_NAME}} from {{API_DOCS_FORMAT}} spec. Ask: '@api-client-gen generate client for /products endpoint'"
|
||||
model: claude-sonnet-4-20250514
|
||||
context: auto
|
||||
allowed-tools: [read_file, write_file, list_files]
|
||||
---
|
||||
|
||||
You are an API client generator for **{{PROJECT_NAME}}**.
|
||||
API docs: `{{API_DOCS_PATH}}` (format: {{API_DOCS_FORMAT}})
|
||||
|
||||
## Generation steps
|
||||
1. Read the API spec at `{{API_DOCS_PATH}}`
|
||||
2. For the requested endpoint(s), generate:
|
||||
- Request DTO (`@JsonSerializable` or Freezed)
|
||||
- Response DTO (`@JsonSerializable` or Freezed)
|
||||
- Repository method with error handling
|
||||
- Dio/Retrofit client method (if Retrofit in codegen)
|
||||
|
||||
## Output structure
|
||||
```dart
|
||||
// data/models/product_dto.dart
|
||||
@freezed
|
||||
class ProductDto with _$ProductDto {
|
||||
factory ProductDto({...}) = _ProductDto;
|
||||
factory ProductDto.fromJson(Map<String, dynamic> json) => _$ProductDtoFromJson(json);
|
||||
}
|
||||
|
||||
// data/datasources/product_remote_datasource.dart
|
||||
class ProductRemoteDataSource {
|
||||
final Dio _dio;
|
||||
Future<List<ProductDto>> getProducts() async { ... }
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: code-reviewer
|
||||
description: "Reviews {{PROJECT_NAME}} code for {{STATE_MANAGEMENT}} patterns, {{ARCHITECTURE}} boundaries, and {{BACKEND}} usage. Ask: 'Review this code' or '@code-reviewer check PR'"
|
||||
model: claude-opus-4-5
|
||||
context: auto
|
||||
allowed-tools: [read_file, list_files]
|
||||
---
|
||||
|
||||
You are a senior Flutter engineer reviewing code for **{{PROJECT_NAME}}**.
|
||||
|
||||
## Your review checklist
|
||||
|
||||
### {{STATE_MANAGEMENT}} patterns
|
||||
- Are state classes immutable and sealed?
|
||||
- Is state management correctly separated from UI logic?
|
||||
- Are streams/subscriptions properly cancelled in dispose()?
|
||||
- Check for anti-patterns specific to {{STATE_MANAGEMENT}}
|
||||
|
||||
### {{ARCHITECTURE}} boundaries
|
||||
{{ARCH_IMPORT_RULES}}
|
||||
- Flag any violation of these import rules immediately
|
||||
|
||||
### {{BACKEND}} usage
|
||||
- Are all exceptions caught and mapped to domain errors?
|
||||
- Are streams vs futures used appropriately?
|
||||
- Are connections/subscriptions disposed correctly?
|
||||
|
||||
### Security (always check)
|
||||
- No hardcoded API keys or secrets
|
||||
- No PII logged to console or crash reporters
|
||||
- Sensitive data using flutter_secure_storage, not SharedPreferences
|
||||
- All user inputs validated before sending to backend
|
||||
|
||||
### General Flutter
|
||||
- `const` used where possible
|
||||
- `dispose()` overridden for all controllers/subscriptions
|
||||
- No `print()` in production paths
|
||||
- Loading/empty/error states all handled
|
||||
|
||||
## Output format
|
||||
For each issue found:
|
||||
```
|
||||
[SEVERITY: critical/major/minor] File:line — Issue description
|
||||
WHY: Why this matters
|
||||
FIX: Specific fix recommendation
|
||||
```
|
||||
|
||||
Severity guide:
|
||||
- **critical**: Security issue, data loss risk, crash potential
|
||||
- **major**: Incorrect pattern, boundary violation, missing error handling
|
||||
- **minor**: Style, naming, optimization opportunity
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: migration-agent
|
||||
description: "Migrates GetX controllers to Riverpod Notifiers for {{PROJECT_NAME}}. Consult before adding any new GetX code — suggest Riverpod equivalent. Ask: '@migration-agent migrate [feature]'"
|
||||
model: claude-opus-4-5
|
||||
context: fork
|
||||
allowed-tools: [read_file, write_file, list_files]
|
||||
---
|
||||
|
||||
You are a Flutter migration specialist for **{{PROJECT_NAME}}**.
|
||||
This project currently uses GetX ({{ARCHITECTURE}}). Your goal is incremental,
|
||||
safe migration to Riverpod without breaking existing features.
|
||||
|
||||
## Migration mapping
|
||||
| GetX | Riverpod equivalent |
|
||||
|------|---------------------|
|
||||
| `GetxController` with `.obs` | `AsyncNotifier` or `Notifier` |
|
||||
| `Obx()` | `ref.watch()` in `ConsumerWidget` |
|
||||
| `Get.find<Controller>()` | `ref.read(provider.notifier)` |
|
||||
| `Get.toNamed()` | `context.go()` (after GoRouter migration) |
|
||||
| `GetxController.onInit()` | `build()` method in `AsyncNotifier` |
|
||||
| `GetxController.onClose()` | `ref.onDispose()` |
|
||||
|
||||
## Migration process (feature by feature)
|
||||
1. **Read** the existing `GetxController` in full
|
||||
2. **Write tests** for the existing GetX version first (if none exist)
|
||||
3. **Map** `.obs` variables → state class fields
|
||||
4. **Write** the new `AsyncNotifier` with equivalent logic
|
||||
5. **Write tests** for the Riverpod version using `ProviderContainer`
|
||||
6. **Migrate** the View: `GetView<C>` → `ConsumerWidget`, `Obx()` → `ref.watch()`
|
||||
7. **Verify** all tests pass for both old and new
|
||||
8. **Remove** GetX code from that feature
|
||||
|
||||
## When NOT to migrate (mark with TODO: MIGRATE-LATER)
|
||||
- Controller shared across 5+ screens (high blast radius — plan separately)
|
||||
- Feature ships in the next sprint (postpone — don't hold up a release)
|
||||
- No tests exist AND you can't write them first (write GetX tests first)
|
||||
|
||||
## Output per migration
|
||||
1. New Riverpod provider file
|
||||
2. Updated ConsumerWidget screen file
|
||||
3. Test file for the new provider
|
||||
4. Diff showing what GetX code is removed
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
name: security-agent
|
||||
description: "Deep security review for {{PROJECT_NAME}}. Consult for auth flows, payment screens, and sensitive data handling. Ask: '@security-agent review auth flow'"
|
||||
model: claude-opus-4-5
|
||||
context: fork
|
||||
allowed-tools: [read_file, list_files]
|
||||
---
|
||||
|
||||
You are a mobile security expert conducting a deep review for **{{PROJECT_NAME}}**.
|
||||
|
||||
> Note: This agent provides deep security analysis.
|
||||
> The `security-standards.mdc` rule provides always-on enforcement.
|
||||
> This agent is for detailed consultations on specific security concerns.
|
||||
|
||||
## Deep review focus areas
|
||||
|
||||
### Auth flow ({{AUTH}})
|
||||
- Token storage: is `flutter_secure_storage` used for ALL tokens?
|
||||
- Token refresh: is refresh handled atomically (no race condition)?
|
||||
- Session expiry: does the app handle 401 gracefully without data loss?
|
||||
- Certificate pinning: configured and tested?
|
||||
|
||||
### Data at rest
|
||||
- SQLite/Hive encryption: sensitive DBs encrypted?
|
||||
- Cache poisoning: cached API responses validated before use?
|
||||
- Keychain/Keystore usage for cryptographic keys
|
||||
|
||||
### Network security
|
||||
- All endpoints HTTPS — any http:// URLs?
|
||||
- Certificate validation — any `badCertificateCallback: true`?
|
||||
- Sensitive data in URL params/query strings?
|
||||
- Request/response logging in production? (must be off)
|
||||
|
||||
### Code injection risks
|
||||
- Dynamic code execution patterns
|
||||
- WebView usage — JavaScript interface security
|
||||
- Deep link parameter validation (no path traversal)
|
||||
|
||||
## Output format
|
||||
For each finding:
|
||||
```
|
||||
[RISK: Critical/High/Medium/Low]
|
||||
LOCATION: File / function
|
||||
ISSUE: Detailed description
|
||||
CVSS-like impact: Confidentiality/Integrity/Availability
|
||||
REMEDIATION: Specific code fix
|
||||
```
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
name: test-writer
|
||||
description: "Writes {{STATE_MANAGEMENT}} unit tests for {{PROJECT_NAME}}. Ask: 'Write tests for [class]' or '@test-writer generate tests'"
|
||||
model: claude-sonnet-4-20250514
|
||||
context: auto
|
||||
allowed-tools: [read_file, write_file, list_files]
|
||||
---
|
||||
|
||||
You are a Flutter test engineer for **{{PROJECT_NAME}}** using **{{STATE_MANAGEMENT}}**.
|
||||
|
||||
## Test pattern to follow
|
||||
```dart
|
||||
{{TEST_PATTERN}}
|
||||
```
|
||||
|
||||
## When asked to write tests:
|
||||
1. Read the source file completely
|
||||
2. Identify all public methods and state transitions
|
||||
3. Write tests for:
|
||||
- Happy path (successful operation)
|
||||
- Error path (failure, exception handling)
|
||||
- Edge cases (empty data, boundary values)
|
||||
4. Use `mocktail` for all mocking
|
||||
5. Follow `Given/When/Then` naming: `'given X, when Y, then emits Z'`
|
||||
|
||||
## File placement
|
||||
- Unit tests: `test/features/[feature]/[file]_test.dart`
|
||||
- Widget tests: `test/features/[feature]/[screen]_widget_test.dart`
|
||||
- Coverage target: 80% minimum for business logic classes
|
||||
|
||||
## Output
|
||||
Write the complete test file, ready to run. Include all imports.
|
||||
After writing, run: `dart test path/to/test_file.dart`
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
name: ui-validator
|
||||
description: "Validates {{PROJECT_NAME}} UI against design system and UX standards. Ask: 'Validate this screen' or '@ui-validator check'"
|
||||
model: claude-sonnet-4-20250514
|
||||
context: auto
|
||||
allowed-tools: [read_file, list_files]
|
||||
---
|
||||
|
||||
You are a UI/UX validator for **{{PROJECT_NAME}}**.
|
||||
|
||||
## Validate every screen for:
|
||||
|
||||
### State coverage ({{STATE_MANAGEMENT}})
|
||||
- Loading state: shows shimmer (NOT spinner unless brief)
|
||||
- Empty state: shows illustration + CTA (NOT blank screen)
|
||||
- Error state: shows message + retry button (NOT toast-only)
|
||||
- Data state: renders content correctly
|
||||
|
||||
### Accessibility
|
||||
- All interactive widgets have semantic labels
|
||||
- Minimum touch targets: 48×48dp
|
||||
- Sufficient color contrast (4.5:1 minimum)
|
||||
|
||||
### Responsive layout
|
||||
- No hardcoded pixel widths
|
||||
- Tested at 375px and 414px viewport widths
|
||||
- `SafeArea` used correctly on iOS
|
||||
|
||||
### Platform-specific ({{PLATFORMS_LIST}})
|
||||
{{#if web}}
|
||||
- No dart:io imports in web-targeted code
|
||||
- PWA-compatible (no native-only APIs without fallbacks)
|
||||
{{/if}}
|
||||
{{#if ios}}
|
||||
- Safe area respected (notch, Dynamic Island)
|
||||
- iOS Human Interface Guidelines followed
|
||||
{{/if}}
|
||||
|
||||
### Security (UI layer)
|
||||
- No credentials shown in plaintext
|
||||
- Sensitive screens wrapped with screenshot prevention
|
||||
|
||||
## Output
|
||||
List each violation with:
|
||||
- Location (file:widget)
|
||||
- What's wrong
|
||||
- How to fix it
|
||||
@@ -0,0 +1,141 @@
|
||||
#!/usr/bin/env ts-node
|
||||
// arch-guard.ts — Pre-commit hook: enforces {{ARCHITECTURE}} import boundaries
|
||||
// Generated for {{PROJECT_NAME}} ({{ARCHITECTURE}} architecture)
|
||||
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import { execSync } from 'child_process';
|
||||
|
||||
const RED = '\x1b[31m';
|
||||
const YELLOW = '\x1b[33m';
|
||||
const GREEN = '\x1b[32m';
|
||||
const RESET = '\x1b[0m';
|
||||
|
||||
interface ArchRule {
|
||||
sourcePattern: RegExp;
|
||||
forbiddenImports: RegExp[];
|
||||
message: string;
|
||||
}
|
||||
|
||||
// Architecture-specific rules for {{ARCHITECTURE}}
|
||||
const ARCH_RULES: ArchRule[] = [
|
||||
...getArchRules()
|
||||
];
|
||||
|
||||
function getArchRules(): ArchRule[] {
|
||||
const arch = '{{ARCH_RAW}}';
|
||||
|
||||
if (arch === 'clean') {
|
||||
return [
|
||||
{
|
||||
sourcePattern: /features\/\w+\/domain\//,
|
||||
forbiddenImports: [/features\/\w+\/data\//, /features\/\w+\/presentation\//],
|
||||
message: 'domain/ must not import from data/ or presentation/',
|
||||
},
|
||||
{
|
||||
sourcePattern: /features\/\w+\/presentation\//,
|
||||
forbiddenImports: [/features\/\w+\/data\//],
|
||||
message: 'presentation/ must not import from data/ directly (use domain interfaces)',
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
if (arch === 'feature_first') {
|
||||
return [
|
||||
{
|
||||
// A feature file must not import from another feature
|
||||
sourcePattern: /features\/(\w+)\//,
|
||||
forbiddenImports: [], // checked dynamically below
|
||||
message: 'Features must not import from other feature folders',
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
if (arch === 'mvvm') {
|
||||
return [
|
||||
{
|
||||
sourcePattern: /viewmodels\//,
|
||||
forbiddenImports: [/package:flutter\//, /widgets\//],
|
||||
message: 'ViewModels must not import Flutter widgets — they must be plain Dart testable',
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
return [];
|
||||
}
|
||||
|
||||
function getChangedDartFiles(): string[] {
|
||||
try {
|
||||
const result = execSync('git diff --cached --name-only --diff-filter=ACM', { encoding: 'utf8' });
|
||||
return result.split('\n').filter(f => f.endsWith('.dart') && fs.existsSync(f));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
function checkFile(filePath: string): string[] {
|
||||
const violations: string[] = [];
|
||||
const content = fs.readFileSync(filePath, 'utf8');
|
||||
const imports = content.match(/^import\s+'[^']+'/gm) ?? [];
|
||||
|
||||
for (const rule of ARCH_RULES) {
|
||||
if (!rule.sourcePattern.test(filePath)) continue;
|
||||
|
||||
// Feature-first cross-feature check
|
||||
if ('{{ARCH_RAW}}' === 'feature_first') {
|
||||
const srcFeatureMatch = filePath.match(/features\/(\w+)\//);
|
||||
if (srcFeatureMatch) {
|
||||
const srcFeature = srcFeatureMatch[1];
|
||||
for (const imp of imports) {
|
||||
const impFeatureMatch = imp.match(/features\/(\w+)\//);
|
||||
if (impFeatureMatch && impFeatureMatch[1] !== srcFeature) {
|
||||
violations.push(
|
||||
`${RED}ARCH VIOLATION${RESET} in ${filePath}:\n` +
|
||||
` ${YELLOW}${rule.message}${RESET}\n` +
|
||||
` Import: ${imp}\n` +
|
||||
` Fix: Move shared code to core/ or shared/`
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
// Standard forbidden import check
|
||||
for (const imp of imports) {
|
||||
for (const forbidden of rule.forbiddenImports) {
|
||||
if (forbidden.test(imp)) {
|
||||
violations.push(
|
||||
`${RED}ARCH VIOLATION${RESET} in ${filePath}:\n` +
|
||||
` ${YELLOW}${rule.message}${RESET}\n` +
|
||||
` Import: ${imp}`
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return violations;
|
||||
}
|
||||
|
||||
const changedFiles = getChangedDartFiles();
|
||||
if (changedFiles.length === 0) {
|
||||
console.log(`${GREEN}✔ arch-guard: no Dart files changed${RESET}`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
console.log(`🏛 arch-guard checking ${changedFiles.length} file(s) for {{ARCHITECTURE}} violations...`);
|
||||
|
||||
const allViolations: string[] = [];
|
||||
for (const file of changedFiles) {
|
||||
allViolations.push(...checkFile(file));
|
||||
}
|
||||
|
||||
if (allViolations.length > 0) {
|
||||
console.error(`\n${RED}✘ Architecture boundary violations detected:${RESET}\n`);
|
||||
for (const v of allViolations) console.error(v + '\n');
|
||||
console.error(`Total: ${allViolations.length} violation(s). Fix before committing.`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(`${GREEN}✔ arch-guard: no violations found${RESET}`);
|
||||
@@ -0,0 +1,32 @@
|
||||
#!/usr/bin/env ts-node
|
||||
// flutter-analyze.ts — Pre-commit hook: runs dart analyze and dart format check
|
||||
import { execSync } from 'child_process';
|
||||
|
||||
const RED = '\x1b[31m';
|
||||
const GREEN = '\x1b[32m';
|
||||
const RESET = '\x1b[0m';
|
||||
|
||||
function run(cmd: string): { stdout: string; code: number } {
|
||||
try {
|
||||
const stdout = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
|
||||
return { stdout, code: 0 };
|
||||
} catch (e: any) {
|
||||
return { stdout: e.stdout ?? e.message, code: e.status ?? 1 };
|
||||
}
|
||||
}
|
||||
|
||||
console.log('🔍 Running flutter analyze...');
|
||||
const analyze = run('flutter analyze --no-congratulate');
|
||||
if (analyze.code !== 0) {
|
||||
console.error(`${RED}✘ flutter analyze failed:\n${analyze.stdout}${RESET}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log('🎨 Checking dart format...');
|
||||
const format = run('dart format --output=none --set-exit-if-changed lib/ test/');
|
||||
if (format.code !== 0) {
|
||||
console.error(`${RED}✘ Unformatted files detected. Run: dart format lib/ test/${RESET}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(`${GREEN}✔ flutter analyze + dart format passed${RESET}`);
|
||||
@@ -0,0 +1,16 @@
|
||||
#!/usr/bin/env ts-node
|
||||
// grind-tests.ts — Pre-push hook: runs flutter test
|
||||
import { execSync } from 'child_process';
|
||||
|
||||
const RED = '\x1b[31m';
|
||||
const GREEN = '\x1b[32m';
|
||||
const RESET = '\x1b[0m';
|
||||
|
||||
console.log('🧪 Running flutter test...');
|
||||
try {
|
||||
execSync('flutter test --coverage', { stdio: 'inherit' });
|
||||
console.log(`${GREEN}✔ All tests passed${RESET}`);
|
||||
} catch {
|
||||
console.error(`${RED}✘ Tests failed. Fix failing tests before pushing.${RESET}`);
|
||||
process.exit(1);
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"name": "pre-commit: flutter analyze",
|
||||
"command": "npx ts-node .cursor/hooks/flutter-analyze.ts",
|
||||
"events": ["pre-commit"]
|
||||
},
|
||||
{
|
||||
"name": "pre-commit: arch guard",
|
||||
"command": "npx ts-node .cursor/hooks/arch-guard.ts",
|
||||
"events": ["pre-commit"]
|
||||
},
|
||||
{
|
||||
"name": "pre-push: run tests",
|
||||
"command": "npx ts-node .cursor/hooks/grind-tests.ts",
|
||||
"events": ["pre-push"]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
description: "Clean Architecture conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Clean Architecture — {{PROJECT_NAME}}
|
||||
|
||||
## Layer structure
|
||||
```
|
||||
lib/features/[feature]/
|
||||
├── domain/
|
||||
│ ├── entities/ ← Pure Dart, no framework imports
|
||||
│ ├── repositories/ ← Abstract interfaces only
|
||||
│ └── usecases/ ← Single-responsibility business operations
|
||||
├── data/
|
||||
│ ├── datasources/ ← Remote (API) + Local (cache) implementations
|
||||
│ ├── models/ ← DTOs with fromJson/toJson (can use Freezed)
|
||||
│ └── repositories/ ← Implements domain/repositories interfaces
|
||||
└── presentation/
|
||||
├── bloc/ or notifiers/
|
||||
├── pages/
|
||||
└── widgets/
|
||||
```
|
||||
|
||||
## Import rules (STRICTLY ENFORCED by arch-guard hook)
|
||||
{{ARCH_IMPORT_RULES}}
|
||||
|
||||
## UseCase pattern
|
||||
```dart
|
||||
// One UseCase = one operation = one method
|
||||
class GetProductsUseCase {
|
||||
final ProductRepository _repository;
|
||||
const GetProductsUseCase(this._repository);
|
||||
|
||||
Future<Either<AppError, List<Product>>> call(ProductFilter filter) =>
|
||||
_repository.getProducts(filter);
|
||||
}
|
||||
```
|
||||
|
||||
## Entity rules
|
||||
- Entities are pure Dart — zero Flutter or framework imports
|
||||
- Entities are immutable — use `final` fields + factory constructors
|
||||
- Entities NEVER have `fromJson`/`toJson` — that belongs in the data layer model
|
||||
|
||||
## Repository rules
|
||||
- Domain defines the **interface** (abstract class)
|
||||
- Data layer **implements** it
|
||||
- Use `Either<Failure, T>` or `Result<T>` return types — never throw in domain
|
||||
|
||||
## Dependency injection
|
||||
- Use `injectable` + `get_it` if `codegen` includes `injectable`
|
||||
- All UseCases injected into BLoC/Notifier via constructor
|
||||
- `DataSource → Repository → UseCase → Bloc` dependency direction
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
---
|
||||
description: "Feature-First architecture conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Feature-First Architecture — {{PROJECT_NAME}}
|
||||
|
||||
## Folder structure
|
||||
```
|
||||
lib/
|
||||
features/
|
||||
auth/
|
||||
auth_screen.dart
|
||||
auth_provider.dart (or auth_bloc.dart)
|
||||
auth_repository.dart
|
||||
auth_model.dart
|
||||
widgets/
|
||||
login_form.dart
|
||||
social_login_button.dart
|
||||
home/
|
||||
home_screen.dart
|
||||
home_provider.dart
|
||||
...
|
||||
core/
|
||||
di/ ← Dependency injection setup
|
||||
network/ ← HTTP client, interceptors
|
||||
storage/ ← Local storage abstraction
|
||||
widgets/ ← Shared widgets used by 3+ features
|
||||
theme/ ← App theme, colors, text styles
|
||||
routing/ ← Router config
|
||||
shared/
|
||||
models/ ← Models shared across features
|
||||
utils/ ← Pure utility functions
|
||||
```
|
||||
|
||||
## Import rules (STRICTLY ENFORCED by arch-guard hook)
|
||||
{{ARCH_IMPORT_RULES}}
|
||||
|
||||
## Feature isolation rules
|
||||
- A feature folder is self-contained: its own screen, state, model, repository
|
||||
- Features MUST NOT import from other feature folders
|
||||
- Shared code MUST be extracted to `core/` or `shared/` before sharing
|
||||
- The 3-feature rule: if 3+ features need the same widget → move it to `core/widgets/`
|
||||
|
||||
## File naming within a feature
|
||||
- `[feature]_screen.dart` — the main screen widget
|
||||
- `[feature]_provider.dart` — Riverpod providers (or `[feature]_bloc.dart`)
|
||||
- `[feature]_repository.dart` — data fetching + caching
|
||||
- `[feature]_model.dart` — data model (Freezed or plain Dart)
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
description: "Layered architecture conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Layered Architecture — {{PROJECT_NAME}}
|
||||
|
||||
## Layers (top → bottom)
|
||||
```
|
||||
Presentation → Service/BLoC → Repository → Data Source
|
||||
```
|
||||
|
||||
## Rules
|
||||
- Dependencies flow downward only — upper layers depend on lower layers
|
||||
- Each layer communicates via interfaces (abstract classes)
|
||||
- Data transformations happen at layer boundaries (DTOs → domain models)
|
||||
{{ARCH_IMPORT_RULES}}
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
description: "MVC architecture conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# MVC Architecture — {{PROJECT_NAME}}
|
||||
|
||||
## Layer responsibilities
|
||||
- **Model**: Data + business logic. Pure Dart.
|
||||
- **View**: Renders UI, observes Controller state. No business logic.
|
||||
- **Controller** (GetX): Connects Model ↔ View. Manages state transitions.
|
||||
|
||||
## Import rules
|
||||
{{ARCH_IMPORT_RULES}}
|
||||
|
||||
## Controller rules
|
||||
- Controllers are injected via `Binding`, never created in widgets
|
||||
- One Controller per feature screen (not per widget)
|
||||
- Controllers fetch data in `onInit()`, clean up in `onClose()`
|
||||
- All reactive state marked with `.obs`
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: "MVVM architecture conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# MVVM Architecture — {{PROJECT_NAME}}
|
||||
|
||||
## Layer responsibilities
|
||||
- **View** (Widget): Renders UI, dispatches user actions to ViewModel. Zero business logic.
|
||||
- **ViewModel**: Holds UI state, calls Model/Repository, exposes streams/notifiers. Zero Flutter imports.
|
||||
- **Model**: Plain Dart data structures + repository interfaces.
|
||||
|
||||
## Import rules
|
||||
{{ARCH_IMPORT_RULES}}
|
||||
|
||||
## ViewModel rules
|
||||
```dart
|
||||
// ViewModel has NO Flutter imports — testable with plain dart test
|
||||
class AuthViewModel extends ChangeNotifier {
|
||||
final AuthRepository _repository;
|
||||
AuthViewModel(this._repository);
|
||||
|
||||
AuthViewState _state = const AuthViewState.initial();
|
||||
AuthViewState get state => _state;
|
||||
|
||||
Future<void> login(String email, String password) async {
|
||||
_state = const AuthViewState.loading();
|
||||
notifyListeners();
|
||||
final result = await _repository.login(email, password);
|
||||
_state = result.fold(
|
||||
(error) => AuthViewState.error(error.message),
|
||||
(user) => AuthViewState.success(user),
|
||||
);
|
||||
notifyListeners();
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
description: "Firebase conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Firebase Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Firestore
|
||||
- Collection names: `camelCase` plural — `users`, `products`, `orderItems`
|
||||
- Document IDs: use Firebase auto-IDs unless a natural key exists
|
||||
- **Streams vs Futures**: use `snapshots()` for live data, `get()` for one-time reads
|
||||
- Always handle `FirebaseException` explicitly — catch by `e.code` not generic `Exception`
|
||||
- Paginate large collections with `startAfterDocument` — never fetch unbounded collections
|
||||
|
||||
```dart
|
||||
// ✅ Stream-based real-time listener
|
||||
Stream<List<Product>> watchProducts() {
|
||||
return _firestore.collection('products')
|
||||
.where('isActive', isEqualTo: true)
|
||||
.snapshots()
|
||||
.map((snap) => snap.docs.map(Product.fromDoc).toList());
|
||||
}
|
||||
|
||||
// ✅ Handle FirebaseException by code
|
||||
try {
|
||||
await _firestore.collection('orders').add(order.toMap());
|
||||
} on FirebaseException catch (e) {
|
||||
switch (e.code) {
|
||||
case 'permission-denied': throw AppError.authError('Insufficient permissions');
|
||||
case 'unavailable': throw AppError.networkError();
|
||||
default: throw AppError.unknown(e);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Firebase Auth
|
||||
- Always use `authStateChanges()` stream — never cache auth state locally
|
||||
- Handle all error codes: `user-not-found`, `wrong-password`, `email-already-in-use`, `network-request-failed`
|
||||
- Sign-out: clear all local state AND call `FirebaseAuth.instance.signOut()`
|
||||
|
||||
## Cloud Functions
|
||||
- Call via `FirebaseFunctions.instance.httpsCallable('functionName')`
|
||||
- Handle `FirebaseFunctionsException` with `.code` and `.message`
|
||||
- Never expose internal errors to client — functions return structured error responses
|
||||
|
||||
## Security (complement to security-standards.mdc)
|
||||
- Firestore Security Rules must be tested with the emulator before deploying
|
||||
- No `allow read, write: if true` — even in development
|
||||
- Rule coverage: every collection must have explicit rules
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
description: "Real-time feature conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Real-time Features — {{PROJECT_NAME}}
|
||||
|
||||
## Connection management
|
||||
- Always expose a `connectionState` stream — UI must show "offline" indicator
|
||||
- Implement exponential backoff for reconnection (1s, 2s, 4s, 8s, max 60s)
|
||||
- Cancel all subscriptions in `dispose()` — memory leaks are the #1 bug in real-time apps
|
||||
|
||||
## Offline-first strategy
|
||||
- Cache last known state locally (Hive, Drift, or Isar)
|
||||
- Show stale data with a "last updated" timestamp while reconnecting
|
||||
- Queue mutations offline, replay on reconnect (use `connectivity_plus`)
|
||||
|
||||
## WebSocket / SSE
|
||||
- Use `web_socket_channel` for WebSocket — never raw `dart:io` WebSocket
|
||||
- Implement heartbeat/ping to detect dead connections
|
||||
- Parse and validate all incoming messages — never trust raw server data
|
||||
|
||||
## UI indicators
|
||||
- Show a persistent banner when offline: "You're offline — changes will sync when reconnected"
|
||||
- Animate the banner away on reconnection — don't just hide it abruptly
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
description: "REST API conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# REST API Standards — {{PROJECT_NAME}}
|
||||
|
||||
## HTTP client setup (Dio)
|
||||
```dart
|
||||
// In core/network/dio_client.dart
|
||||
Dio createDioClient({required AppConfig config}) {
|
||||
final dio = Dio(BaseOptions(
|
||||
baseUrl: config.baseUrl,
|
||||
connectTimeout: const Duration(seconds: 10),
|
||||
receiveTimeout: const Duration(seconds: 30),
|
||||
headers: {'Content-Type': 'application/json', 'Accept': 'application/json'},
|
||||
));
|
||||
|
||||
dio.interceptors.addAll([
|
||||
AuthInterceptor(tokenStorage: getIt<TokenStorage>()),
|
||||
LoggingInterceptor(), // debug builds only
|
||||
RetryInterceptor(dio), // 3 retries on network errors
|
||||
]);
|
||||
return dio;
|
||||
}
|
||||
```
|
||||
|
||||
## DTOs (Data Transfer Objects)
|
||||
- DTOs live in the `data/` layer — **never** pass raw JSON maps to the domain layer
|
||||
- Use Freezed for DTOs if `codegen` includes `json_serializable` or `freezed`
|
||||
- `fromJson` factory must handle null fields gracefully — API response fields are not guaranteed
|
||||
|
||||
## Error handling
|
||||
```dart
|
||||
// Map HTTP errors → AppError domain types
|
||||
AppError _mapDioError(DioException e) => switch (e.type) {
|
||||
DioExceptionType.connectionTimeout => const NetworkError(statusCode: null),
|
||||
DioExceptionType.receiveTimeout => const NetworkError(statusCode: null),
|
||||
DioExceptionType.badResponse => _mapStatusCode(e.response?.statusCode),
|
||||
DioExceptionType.connectionError => const NetworkError(statusCode: null),
|
||||
_ => UnknownError(e),
|
||||
};
|
||||
```
|
||||
|
||||
## API versioning
|
||||
- Base URL includes version: `https://api.{{PROJECT_NAME}}.com/v1/`
|
||||
- When upgrading API version, keep old version working until all clients migrate
|
||||
|
||||
## Auth token interceptor
|
||||
- Inject `Authorization: Bearer <token>` automatically on every request
|
||||
- On 401: refresh token once, retry original request, then logout if refresh fails
|
||||
- On 403: map to `AppError.authError('Insufficient permissions')`
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
description: "Supabase conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Supabase Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Row Level Security (RLS) awareness
|
||||
- **ALWAYS** assume RLS is enabled — never write queries that assume full table access
|
||||
- Test queries in the Supabase dashboard before implementing in Flutter
|
||||
- If a query returns empty unexpectedly, check RLS policies first
|
||||
|
||||
## Queries
|
||||
```dart
|
||||
// ✅ Type-safe query with error handling
|
||||
Future<List<Product>> getProducts() async {
|
||||
final response = await _supabase
|
||||
.from('products')
|
||||
.select('id, name, price, category_id, categories(name)')
|
||||
.eq('is_active', true)
|
||||
.order('created_at', ascending: false)
|
||||
.limit(50);
|
||||
return response.map(Product.fromMap).toList();
|
||||
}
|
||||
```
|
||||
|
||||
## Realtime subscriptions
|
||||
```dart
|
||||
StreamSubscription<List<Map<String, dynamic>>>? _sub;
|
||||
|
||||
void watchOrders(String userId) {
|
||||
_sub = _supabase
|
||||
.from('orders')
|
||||
.stream(primaryKey: ['id'])
|
||||
.eq('user_id', userId)
|
||||
.listen(
|
||||
(data) => _updateOrders(data),
|
||||
onError: (e) => _handleError(e),
|
||||
);
|
||||
}
|
||||
|
||||
@override
|
||||
void dispose() {
|
||||
_sub?.cancel(); // ALWAYS cancel in dispose()
|
||||
super.dispose();
|
||||
}
|
||||
```
|
||||
|
||||
## Auth session
|
||||
- Use `supabase.auth.onAuthStateChange` stream — never poll auth state
|
||||
- Persist session: `supabase-flutter` handles this automatically via secure storage
|
||||
- `session.accessToken` expires — check `session.isExpired` before sensitive operations
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
description: "Freezed code generation conventions for {{PROJECT_NAME}} — Pillar 4"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Freezed Standards — {{PROJECT_NAME}}
|
||||
|
||||
## When to use Freezed
|
||||
- All domain entities and data models — use `@freezed`
|
||||
- Union types / sealed classes — use `@freezed` with multiple constructors
|
||||
- BLoC states and events — use `@freezed`
|
||||
|
||||
## Model pattern
|
||||
```dart
|
||||
@freezed
|
||||
class Product with _$Product {
|
||||
const factory Product({
|
||||
required String id,
|
||||
required String name,
|
||||
required double price,
|
||||
@Default(0) int stockCount,
|
||||
String? imageUrl,
|
||||
}) = _Product;
|
||||
|
||||
factory Product.fromJson(Map<String, dynamic> json) => _$ProductFromJson(json);
|
||||
}
|
||||
```
|
||||
|
||||
## Union type pattern
|
||||
```dart
|
||||
@freezed
|
||||
sealed class ProductState with _$ProductState {
|
||||
const factory ProductState.initial() = ProductInitial;
|
||||
const factory ProductState.loading() = ProductLoading;
|
||||
const factory ProductState.loaded(List<Product> products) = ProductLoaded;
|
||||
const factory ProductState.error(String message) = ProductError;
|
||||
}
|
||||
|
||||
// Usage — exhaustive switch
|
||||
final widget = state.when(
|
||||
initial: () => const SizedBox.shrink(),
|
||||
loading: () => const ProductShimmer(),
|
||||
loaded: (products) => ProductList(products: products),
|
||||
error: (msg) => ErrorWidget(message: msg),
|
||||
);
|
||||
```
|
||||
|
||||
## Critical rules
|
||||
- **NEVER** edit `.freezed.dart` or `.g.dart` files — they are generated
|
||||
- Run `dart run build_runner build --delete-conflicting-outputs` after changes
|
||||
- Run `dart run build_runner watch` during development
|
||||
- Add `*.freezed.dart` and `*.g.dart` to `.gitignore` (or commit them — team must decide)
|
||||
- Always define `copyWith` via Freezed — never write manual `copyWith`
|
||||
|
||||
## Patterns to avoid
|
||||
```dart
|
||||
// ❌ Manual copyWith — replaced by Freezed
|
||||
Product copyWith({String? name, double? price}) => Product(
|
||||
id: id, name: name ?? this.name, price: price ?? this.price,
|
||||
);
|
||||
|
||||
// ✅ Let Freezed generate it
|
||||
product.copyWith(name: 'New Name', price: 9.99)
|
||||
```
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
---
|
||||
description: "Injectable dependency injection conventions for {{PROJECT_NAME}} — Pillar 4"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Injectable (get_it) Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Setup
|
||||
```dart
|
||||
// lib/core/di/injection.dart
|
||||
@InjectableInit()
|
||||
void configureDependencies() => getIt.init();
|
||||
```
|
||||
|
||||
## Annotations
|
||||
```dart
|
||||
@singleton // One instance for app lifetime
|
||||
@lazySingleton // Created on first access (preferred for most services)
|
||||
@injectable // New instance each time (use sparingly)
|
||||
@factoryMethod // Custom factory logic
|
||||
```
|
||||
|
||||
## Example
|
||||
```dart
|
||||
@lazySingleton
|
||||
class ProductRepository {
|
||||
final DioClient _client;
|
||||
const ProductRepository(this._client); // Constructor injection
|
||||
}
|
||||
|
||||
@injectable
|
||||
class GetProductsUseCase {
|
||||
final ProductRepository _repo;
|
||||
const GetProductsUseCase(this._repo);
|
||||
}
|
||||
```
|
||||
|
||||
## Rules
|
||||
- Run `dart run build_runner build` after adding/modifying `@injectable` annotations
|
||||
- **NEVER** use `getIt<T>()` in widget `build()` methods — inject via constructor or provider
|
||||
- Use `@module` for third-party registrations (Dio, SharedPreferences, etc.)
|
||||
- Register environment-specific implementations with `@Environment('dev')` / `@Environment('prod')`
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: "json_serializable conventions for {{PROJECT_NAME}} — Pillar 4"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# json_serializable Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Model annotation
|
||||
```dart
|
||||
@JsonSerializable(explicitToJson: true) // explicitToJson for nested objects
|
||||
class ProductDto {
|
||||
final String id;
|
||||
final String name;
|
||||
@JsonKey(name: 'unit_price') // snake_case API → camelCase Dart
|
||||
final double unitPrice;
|
||||
@JsonKey(defaultValue: false)
|
||||
final bool isActive;
|
||||
final DateTime createdAt; // auto-converted from ISO 8601 string
|
||||
|
||||
const ProductDto({
|
||||
required this.id,
|
||||
required this.name,
|
||||
required this.unitPrice,
|
||||
required this.isActive,
|
||||
required this.createdAt,
|
||||
});
|
||||
|
||||
factory ProductDto.fromJson(Map<String, dynamic> json) => _$ProductDtoFromJson(json);
|
||||
Map<String, dynamic> toJson() => _$ProductDtoToJson(this);
|
||||
}
|
||||
```
|
||||
|
||||
## Critical rules
|
||||
- **NEVER** edit `*.g.dart` files
|
||||
- Use `@JsonKey(defaultValue: ...)` for nullable API fields — API contracts change
|
||||
- Use `explicitToJson: true` whenever the model has nested objects
|
||||
- Null safety: API fields not guaranteed to be non-null should be `String?` not `String`
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
description: "Retrofit (Dio) API client conventions for {{PROJECT_NAME}} — Pillar 4"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Retrofit Standards — {{PROJECT_NAME}}
|
||||
|
||||
## API client definition
|
||||
```dart
|
||||
@RestApi()
|
||||
abstract class ProductApiClient {
|
||||
factory ProductApiClient(Dio dio, {String? baseUrl}) = _ProductApiClient;
|
||||
|
||||
@GET('/products')
|
||||
Future<List<ProductDto>> getProducts(@Query('category') String? category);
|
||||
|
||||
@GET('/products/{id}')
|
||||
Future<ProductDto> getProduct(@Path('id') String id);
|
||||
|
||||
@POST('/products')
|
||||
Future<ProductDto> createProduct(@Body() CreateProductDto dto);
|
||||
}
|
||||
```
|
||||
|
||||
## Rules
|
||||
- **NEVER** edit `*.g.dart` files
|
||||
- Run `dart run build_runner build` after modifying API client
|
||||
- All DTOs used in Retrofit must have `fromJson`/`toJson` (via `json_serializable` or Freezed)
|
||||
- Handle `DioException` in the repository layer — never let it reach the presentation layer
|
||||
- Use `@Headers({'Content-Type': 'application/json'})` at class level, not per-method
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
---
|
||||
description: "Global error handling strategy for {{PROJECT_NAME}} — always applied"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Global Error Handling — {{PROJECT_NAME}}
|
||||
|
||||
## Flutter error boundaries
|
||||
Configure in `main.dart` — do this ONCE and never bypass it:
|
||||
|
||||
```dart
|
||||
void main() {
|
||||
FlutterError.onError = (details) {
|
||||
FlutterError.presentError(details);
|
||||
// TODO: Send to crash reporter (Sentry/Firebase Crashlytics)
|
||||
crashReporter.recordFlutterError(details);
|
||||
};
|
||||
|
||||
PlatformDispatcher.instance.onError = (error, stack) {
|
||||
// TODO: Send to crash reporter
|
||||
crashReporter.recordError(error, stack, fatal: true);
|
||||
return true;
|
||||
};
|
||||
|
||||
runApp(const MyApp());
|
||||
}
|
||||
```
|
||||
|
||||
## Error types hierarchy
|
||||
Define a sealed class for domain errors — never throw raw exceptions in business logic:
|
||||
|
||||
```dart
|
||||
sealed class AppError {
|
||||
const AppError();
|
||||
}
|
||||
class NetworkError extends AppError { final int? statusCode; const NetworkError({this.statusCode}); }
|
||||
class AuthError extends AppError { final String reason; const AuthError(this.reason); }
|
||||
class NotFoundError extends AppError { final String resource; const NotFoundError(this.resource); }
|
||||
class UnknownError extends AppError { final Object cause; const UnknownError(this.cause); }
|
||||
```
|
||||
|
||||
## Repository layer
|
||||
- Wrap ALL external calls in try/catch and return `Either<AppError, T>` or `Result<T>`
|
||||
- NEVER let raw exceptions bubble to the presentation layer
|
||||
- Log at the repository layer, not the UI layer
|
||||
|
||||
## Presentation layer
|
||||
- Every async widget MUST handle error state explicitly — no silent failures
|
||||
- Show user-friendly error messages: map `AppError` subtype → readable string
|
||||
- Provide a "Try again" action for recoverable errors (network, timeout)
|
||||
- For fatal errors (auth expired), redirect to login — never show a dead screen
|
||||
|
||||
## Crash reporting
|
||||
- Integrate Sentry or Firebase Crashlytics before first TestFlight / Play beta
|
||||
- Set `user` context on crash reporter after login (id only, no PII)
|
||||
- Add `breadcrumbs` for key user actions to aid reproduction
|
||||
|
||||
## Logging strategy
|
||||
```
|
||||
Level | Use case
|
||||
DEBUG | Development only (strip from release)
|
||||
INFO | Key user flows (login, purchase, etc.)
|
||||
WARNING | Recoverable errors, fallbacks used
|
||||
ERROR | Unrecoverable errors, unexpected states
|
||||
```
|
||||
- Use `logger` package — never bare `print()`
|
||||
- Logger instance per class: `final _log = Logger('ClassName');`
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
description: "Localization / i18n conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Localization Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Supported locales: {{LOCALES_LIST}}
|
||||
|
||||
## Setup
|
||||
- Use Flutter's built-in `AppLocalizations` (generated from `.arb` files)
|
||||
- ARB files: `lib/l10n/app_en.arb`, `lib/l10n/app_fr.arb`, etc.
|
||||
- Never hardcode user-facing strings — always use `context.l10n.stringKey`
|
||||
|
||||
## AppLocalizations access
|
||||
```dart
|
||||
// In widgets:
|
||||
final l10n = AppLocalizations.of(context)!;
|
||||
Text(l10n.welcomeMessage) // ✅
|
||||
|
||||
// Extension for convenience:
|
||||
extension LocalizationX on BuildContext {
|
||||
AppLocalizations get l10n => AppLocalizations.of(this)!;
|
||||
}
|
||||
Text(context.l10n.welcomeMessage) // ✅
|
||||
```
|
||||
|
||||
## ARB file format
|
||||
```json
|
||||
{
|
||||
"welcomeMessage": "Welcome back, {name}!",
|
||||
"@welcomeMessage": {
|
||||
"description": "Shown on home screen after login",
|
||||
"placeholders": {
|
||||
"name": { "type": "String", "example": "Alice" }
|
||||
}
|
||||
},
|
||||
"itemCount": "{count, plural, =0{No items} =1{1 item} other{{count} items}}",
|
||||
"@itemCount": {
|
||||
"placeholders": {
|
||||
"count": { "type": "int" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rules
|
||||
- **NEVER** hardcode user-facing strings as string literals in widget files
|
||||
- **Technical keys** (route paths, storage/analytics keys, JSON fields): one shared module (e.g. `lib/core/constants/app_strings.dart`) — no duplicated literals across features
|
||||
- All new strings added to ALL locale ARB files simultaneously — broken translations break builds
|
||||
- Use ICU message format for plurals and gendered strings
|
||||
- Date/time formatting: use `intl` package `DateFormat` — never `date.toString()`
|
||||
- Currency: use `NumberFormat.currency(locale: locale)` — never manual formatting
|
||||
- RTL support: wrap with `Directionality` where needed; test with Arabic locale
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
description: "Android-specific conventions for {{PROJECT_NAME}} — Pillar 4"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Android Platform Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Target SDK
|
||||
- `compileSdkVersion` / `targetSdkVersion`: 34 (Android 14) minimum for new apps
|
||||
- `minSdkVersion`: 21 (Android 5.0) unless brief specifies otherwise
|
||||
- Update `android/app/build.gradle` when bumping target SDK
|
||||
|
||||
## Permissions
|
||||
- Declare only needed permissions in `AndroidManifest.xml`
|
||||
- Runtime permissions: use `permission_handler` — never skip rationale step
|
||||
- Android 13+: granular media permissions (`READ_MEDIA_IMAGES` not `READ_EXTERNAL_STORAGE`)
|
||||
- Android 14+: `FOREGROUND_SERVICE_TYPE` required for foreground services
|
||||
|
||||
## Adaptive icons
|
||||
- Provide both foreground and background layers in `android/app/src/main/res/`
|
||||
- Test on dark theme, coloured theme, and themed icons (Android 13+)
|
||||
|
||||
## Deep links / App Links
|
||||
- Verify domain ownership: `.well-known/assetlinks.json` on your server
|
||||
- Test with: `adb shell am start -a android.intent.action.VIEW -d "https://{{PROJECT_NAME}}.com/products/123"`
|
||||
|
||||
## ProGuard / R8
|
||||
- Obfuscation rules in `android/app/proguard-rules.pro`
|
||||
- Keep rules for: Dio, Freezed models, `@JsonKey` annotated classes
|
||||
- Test release build thoroughly — obfuscation can break reflection-based code
|
||||
|
||||
## Notifications
|
||||
- Create notification channels before showing any notification (Android 8+)
|
||||
- Notification icons must be monochrome on Android 5+
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
description: "Flutter Desktop conventions for {{PROJECT_NAME}} — Pillar 4"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Flutter Desktop Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Window management
|
||||
- Use `window_manager` package for window title, size, minimize/maximize controls
|
||||
- Set minimum window size to prevent unusable UI: `windowManager.setMinimumSize(const Size(800, 600))`
|
||||
- Remember window position/size across sessions using `shared_preferences`
|
||||
|
||||
## Keyboard shortcuts
|
||||
- All primary actions must have keyboard shortcuts
|
||||
- Use `Shortcuts` widget + `Actions` widget for app-wide shortcuts
|
||||
- Follow platform conventions: `Cmd+S` (macOS), `Ctrl+S` (Windows/Linux) for save
|
||||
|
||||
## Context menus
|
||||
- Right-click context menus: use `ContextMenuRegion` widget
|
||||
- Desktop users expect right-click everywhere
|
||||
|
||||
## Platform-specific behavior
|
||||
```dart
|
||||
if (Platform.isMacOS) {
|
||||
// macOS: use mac_window_manager for traffic lights placement
|
||||
} else if (Platform.isWindows) {
|
||||
// Windows: custom title bar with min/max/close buttons
|
||||
} else if (Platform.isLinux) {
|
||||
// Linux: respect window manager decorations
|
||||
}
|
||||
```
|
||||
|
||||
## File system
|
||||
- `path_provider` provides platform-appropriate directories
|
||||
- `file_picker` for open/save dialogs — never hardcode paths
|
||||
- Handle file permission errors gracefully (especially on macOS with sandboxing)
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
description: "iOS-specific conventions for {{PROJECT_NAME}} — Pillar 4"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# iOS Platform Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Platform-specific imports
|
||||
- Use `dart:io` checks: `if (Platform.isIOS)` for conditional code
|
||||
- iOS-only plugins: declare in `pubspec.yaml` with platform filter
|
||||
- **NEVER** call `dart:io` directly in shared code — use `platform_channel` or `universal_io`
|
||||
|
||||
## iOS-specific requirements
|
||||
- Minimum deployment target: iOS 13.0 (or as specified in `ios/Podfile`)
|
||||
- Privacy manifests: `ios/Runner/PrivacyInfo.xcprivacy` — required for App Store since 2024
|
||||
- Required `Info.plist` keys before using:
|
||||
- Camera: `NSCameraUsageDescription`
|
||||
- Photo library: `NSPhotoLibraryUsageDescription`
|
||||
- Location: `NSLocationWhenInUseUsageDescription`
|
||||
- Notifications: handled via `permission_handler`
|
||||
|
||||
## Push notifications (iOS)
|
||||
- Configure APNs certificates in Xcode signing & capabilities
|
||||
- Request permission with `permission_handler` — show rationale screen first
|
||||
- Handle foreground vs background vs terminated app states separately
|
||||
- Test on a physical device — iOS simulator does not support push
|
||||
|
||||
## Safe area
|
||||
- Always wrap root scaffold with `SafeArea` or use `MediaQuery.of(context).padding`
|
||||
- Dynamic Island / notch: test on iPhone 14 Pro and iPhone 15 Pro simulators
|
||||
|
||||
## App Store compliance
|
||||
- Screenshot: use `ScreenshotController` to exclude sensitive screens
|
||||
- Sign in with Apple: required if any third-party social login is offered
|
||||
- IPv6 compatibility required — no IPv4-only network code
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
description: "Flutter Web conventions for {{PROJECT_NAME}} — Pillar 4"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Flutter Web Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Critical: No dart:io on web
|
||||
- **NEVER** import `dart:io` in shared code — it crashes on web
|
||||
- Use `dart:html` or `universal_io` for platform-specific I/O
|
||||
- Use `path_provider` alternatives: `universal_html` for web file access
|
||||
- Check: `kIsWeb` constant before any platform-specific code
|
||||
|
||||
```dart
|
||||
// ✅ Platform-safe
|
||||
import 'package:universal_io/io.dart';
|
||||
|
||||
// ❌ Crashes on web
|
||||
import 'dart:io';
|
||||
```
|
||||
|
||||
## Web rendering
|
||||
- Choose renderer carefully:
|
||||
- `canvaskit` — pixel-perfect, larger initial load, better for graphics
|
||||
- `html` — smaller load, uses DOM elements, inconsistent rendering
|
||||
- Set in `index.html`: `flutterWebRenderer: "canvaskit"`
|
||||
|
||||
## PWA requirements
|
||||
- Update `web/manifest.json`: name, icons (192×192, 512×512), theme_color
|
||||
- Service worker: configure for offline caching of app shell
|
||||
- Test with Chrome DevTools → Lighthouse → PWA audit
|
||||
|
||||
## Web-specific rendering caveats
|
||||
- `BackdropFilter` has limited support on `html` renderer
|
||||
- `Canvas` operations differ between renderers — test both
|
||||
- Text selection differs — use `SelectableText` not `Text` where appropriate
|
||||
- Scrollbars appear automatically on web — style or hide with `ScrollbarTheme`
|
||||
|
||||
## URL strategy
|
||||
- Use `usePathUrlStrategy()` in `main.dart` for clean URLs (no `#`)
|
||||
- Configure server to redirect all paths to `index.html` (SPA routing)
|
||||
|
||||
## Performance
|
||||
- Lazy-load routes — use `GoRouter` deferred loading
|
||||
- Initial load budget: < 3MB (canvaskit) or < 1MB (html renderer)
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
description: "Auto Route conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Auto Route Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Route definitions
|
||||
```dart
|
||||
@AutoRouterConfig()
|
||||
class AppRouter extends $AppRouter {
|
||||
@override
|
||||
List<AutoRoute> get routes => [
|
||||
AutoRoute(page: HomeRoute.page, initial: true),
|
||||
AutoRoute(page: ProductRoute.page, path: '/products/:id'),
|
||||
AutoRoute(page: LoginRoute.page, guards: [AuthGuard]),
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
## Navigation
|
||||
```dart
|
||||
context.router.push(ProductRoute(id: product.id));
|
||||
context.router.pop();
|
||||
context.router.replace(HomeRoute());
|
||||
```
|
||||
|
||||
## Rules
|
||||
- Always use typed `Route` classes — never string paths
|
||||
- Guards implement `AutoRouteGuard`
|
||||
- **NEVER** use `Navigator.push` directly
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
description: "GetX Navigation conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# GetX Navigation — {{PROJECT_NAME}}
|
||||
|
||||
## Named routes
|
||||
```dart
|
||||
// app_pages.dart — central route definitions
|
||||
abstract class AppPages {
|
||||
static const initial = Routes.home;
|
||||
static final routes = [
|
||||
GetPage(name: Routes.home, page: () => const HomeView(), binding: HomeBinding()),
|
||||
GetPage(name: Routes.product, page: () => const ProductView(), binding: ProductBinding()),
|
||||
];
|
||||
}
|
||||
|
||||
// Navigate — always use named routes
|
||||
Get.toNamed(Routes.product, arguments: product); // push
|
||||
Get.offAllNamed(Routes.home); // replace stack
|
||||
Get.back(); // pop
|
||||
```
|
||||
|
||||
## Bindings
|
||||
- Every route has a `Binding` class that creates and injects dependencies
|
||||
- **NEVER** use `Get.put()` in a widget — only in Bindings
|
||||
- Use `Get.lazyPut()` for deferred creation
|
||||
|
||||
## Rules
|
||||
- **NEVER** use `Navigator.push/pop`
|
||||
- All route strings in `lib/core/routing/routes.dart` as constants
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
description: "GoRouter conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# GoRouter Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Typed routes (mandatory)
|
||||
```dart
|
||||
// Define typed routes — never use string paths directly in navigation calls
|
||||
@TypedGoRoute<HomeRoute>(path: '/')
|
||||
class HomeRoute extends GoRouteData {
|
||||
const HomeRoute();
|
||||
@override Widget build(BuildContext ctx, GoRouterState state) => const HomeScreen();
|
||||
}
|
||||
|
||||
@TypedGoRoute<ProductRoute>(path: '/products/:id')
|
||||
class ProductRoute extends GoRouteData {
|
||||
final String id;
|
||||
const ProductRoute({required this.id});
|
||||
@override Widget build(BuildContext ctx, GoRouterState state) => ProductScreen(id: id);
|
||||
}
|
||||
|
||||
// Navigate with type safety
|
||||
const ProductRoute(id: product.id).go(context); // ✅
|
||||
context.go('/products/${product.id}'); // ❌ — don't do this
|
||||
```
|
||||
|
||||
## Auth guard
|
||||
```dart
|
||||
// Redirect logic in router config
|
||||
redirect: (context, state) {
|
||||
final isLoggedIn = ref.read(authProvider).isAuthenticated;
|
||||
final isLoginRoute = state.matchedLocation == '/login';
|
||||
if (!isLoggedIn && !isLoginRoute) return '/login';
|
||||
if (isLoggedIn && isLoginRoute) return '/';
|
||||
return null;
|
||||
},
|
||||
```
|
||||
|
||||
## Shell routes for bottom navigation
|
||||
```dart
|
||||
ShellRoute(
|
||||
builder: (ctx, state, child) => MainScaffold(child: child),
|
||||
routes: [
|
||||
GoRoute(path: '/home', builder: (_, __) => const HomeScreen()),
|
||||
GoRoute(path: '/search', builder: (_, __) => const SearchScreen()),
|
||||
GoRoute(path: '/profile', builder: (_, __) => const ProfileScreen()),
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
## Deep links
|
||||
- Register URL schemes in `Info.plist` (iOS) and `AndroidManifest.xml`
|
||||
- Test deep links with: `adb shell am start -a android.intent.action.VIEW -d "app://{{PACKAGE_ID}}/products/123"`
|
||||
- Handle `GoRouter.of(context).routerDelegate.currentConfiguration` for dynamic links
|
||||
|
||||
## Rules
|
||||
- **NEVER** use `Navigator.push/pop` — use `context.go()`, `context.push()`, `context.pop()`
|
||||
- All routes declared in one file: `lib/core/routing/app_router.dart`
|
||||
- `BlocProvider`s for route-level blocs created inside the `builder` of each route
|
||||
+109
@@ -0,0 +1,109 @@
|
||||
---
|
||||
description: "Security standards for {{PROJECT_NAME}} — ALWAYS APPLIED on every file write"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Security Standards — {{PROJECT_NAME}}
|
||||
> **Pillar 5**: Security is an always-on rule, not just a reactive agent.
|
||||
> These rules apply to EVERY file write, regardless of feature or context.
|
||||
|
||||
## Credential & secret management
|
||||
- **NEVER** hardcode API keys, tokens, or secrets in source code
|
||||
- **NEVER** commit `.env` files — use `.gitignore` and document required vars in `.env.example`
|
||||
- API keys belong in: flavored `--dart-define` build args, or a secrets manager (e.g. AWS Secrets)
|
||||
- Use `flutter_secure_storage` for tokens/credentials — **NEVER** `SharedPreferences` for sensitive data
|
||||
- Obfuscation: enable `--obfuscate --split-debug-info=build/debug-symbols/` for release builds
|
||||
|
||||
## Authentication & sessions
|
||||
- JWT/session tokens: stored in `flutter_secure_storage`, never in `SharedPreferences` or local DB
|
||||
- Implement token refresh with retry logic — never let a 401 show a raw error to the user
|
||||
- Certificate pinning: required for production builds on {{AUTH}} — use `dio_pinning_interceptor`
|
||||
- Biometric re-auth: require for any transaction > defined threshold
|
||||
|
||||
## Data & privacy
|
||||
- **NEVER** log PII (names, emails, phone numbers, addresses) to console or crash reporters
|
||||
- Sanitize all user inputs before sending to backend
|
||||
- Use `SensitiveWidget` wrapper to exclude screens from screenshots / app switcher thumbnails
|
||||
- Comply with platform privacy requirements: iOS `NSPrivacyAccessedAPITypes`, Android permissions
|
||||
|
||||
## Network security
|
||||
- All API calls use HTTPS — no http:// in production
|
||||
- Validate SSL certificates — never bypass with `badCertificateCallback: (_,_,_) => true`
|
||||
- Add a timeout to every HTTP call: `connectTimeout: Duration(seconds: 10)`
|
||||
- Rate-limit sensitive endpoints: auth, OTP, password reset
|
||||
|
||||
## Dependency security
|
||||
- Run `dart pub outdated` monthly — flag packages with known CVEs
|
||||
- Never use a package with <100 pub points without explicit tech lead approval
|
||||
- Pin critical security packages to exact versions in `pubspec.yaml`
|
||||
|
||||
## Secure coding patterns
|
||||
```dart
|
||||
// ✅ Correct: secure token storage
|
||||
final storage = FlutterSecureStorage();
|
||||
await storage.write(key: 'access_token', value: token);
|
||||
|
||||
// ❌ Wrong: SharedPreferences for sensitive data
|
||||
final prefs = await SharedPreferences.getInstance();
|
||||
prefs.setString('access_token', token); // NEVER do this
|
||||
|
||||
// ✅ Correct: PII-safe logging
|
||||
logger.info('User authenticated: userId=${user.id}'); // ok — id, not email
|
||||
logger.debug('Payment processed: orderId=$orderId'); // ok — no card data
|
||||
|
||||
// ❌ Wrong: PII in logs
|
||||
logger.info('Login: email=${user.email}, phone=${user.phone}'); // NEVER
|
||||
|
||||
// ✅ Correct: --dart-define for secrets (build arg, not in code)
|
||||
// flutter build apk --dart-define=API_KEY=$API_KEY
|
||||
const apiKey = String.fromEnvironment('API_KEY'); // acceptable
|
||||
|
||||
// ✅ Correct: certificate pinning with Dio
|
||||
(dio.httpClientAdapter as IOHttpClientAdapter).createHttpClient = () {
|
||||
final client = HttpClient();
|
||||
client.badCertificateCallback = (cert, host, port) => false; // strict
|
||||
return client;
|
||||
};
|
||||
```
|
||||
|
||||
## Deep linking & intent security
|
||||
- Validate all incoming deep link parameters — never trust raw URL params
|
||||
- Use `app_links` package for verified deep link handling
|
||||
- Restrict URL schemes to known patterns — reject unknown schemes
|
||||
- For OAuth callbacks: validate `state` parameter to prevent CSRF
|
||||
|
||||
## Storage security
|
||||
- Encrypt locally cached sensitive data using `hive` with `HiveAesCipher`
|
||||
- Clear sensitive data from memory after use (set to null, trigger GC)
|
||||
- Do NOT cache auth tokens in network layer (no `dio_cache_interceptor` for auth endpoints)
|
||||
- Use `SecureRandom` for nonce/token generation — never `Random()`
|
||||
|
||||
## Code obfuscation & binary protection
|
||||
```yaml
|
||||
# android/app/build.gradle — release config
|
||||
buildTypes {
|
||||
release {
|
||||
minifyEnabled true
|
||||
shrinkResources true
|
||||
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
|
||||
}
|
||||
}
|
||||
```
|
||||
```bash
|
||||
# Flutter release build with obfuscation
|
||||
flutter build apk --release --obfuscate --split-debug-info=build/debug-symbols/
|
||||
flutter build ipa --release --obfuscate --split-debug-info=build/debug-symbols/
|
||||
```
|
||||
|
||||
## Release checklist
|
||||
Before every production release, verify:
|
||||
- [ ] No hardcoded secrets (`grep -r "api_key\|secret\|password\|token" lib/`)
|
||||
- [ ] Debug flags disabled (`kDebugMode` guards on all debug-only paths)
|
||||
- [ ] Obfuscation enabled in release build config
|
||||
- [ ] Certificate pinning active and tested on both platforms
|
||||
- [ ] Crash reporter PII filters configured (Sentry `beforeSend`, Firebase `setConsentType`)
|
||||
- [ ] `flutter_secure_storage` used for all tokens — no `SharedPreferences` for sensitive keys
|
||||
- [ ] Network calls all HTTPS — scan for `http://` in lib/
|
||||
- [ ] Dependencies audited: `dart pub outdated --json | jq '.packages[] | select(.isDiscontinued)'`
|
||||
- [ ] Deep link parameters validated
|
||||
- [ ] App transport security / network security config reviewed
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
description: "BLoC / Cubit conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# BLoC / Cubit Standards — {{PROJECT_NAME}}
|
||||
|
||||
## When to use BLoC vs Cubit
|
||||
- **Cubit**: simple state with no meaningful event history (toggle, counter, pagination)
|
||||
- **BLoC**: event-driven flows where event history or transitions matter (auth, checkout, form wizard)
|
||||
|
||||
## Event and State classes
|
||||
```dart
|
||||
// Events — sealed class (exhaustive switch)
|
||||
sealed class AuthEvent { const AuthEvent(); }
|
||||
final class AuthLoginRequested extends AuthEvent {
|
||||
final String email, password;
|
||||
const AuthLoginRequested({required this.email, required this.password});
|
||||
}
|
||||
final class AuthLogoutRequested extends AuthEvent { const AuthLogoutRequested(); }
|
||||
|
||||
// States — sealed class, immutable
|
||||
sealed class AuthState { const AuthState(); }
|
||||
final class AuthInitial extends AuthState { const AuthInitial(); }
|
||||
final class AuthLoading extends AuthState { const AuthLoading(); }
|
||||
final class AuthAuthenticated extends AuthState {
|
||||
final User user;
|
||||
const AuthAuthenticated(this.user);
|
||||
}
|
||||
final class AuthUnauthenticated extends AuthState { const AuthUnauthenticated(); }
|
||||
final class AuthFailure extends AuthState {
|
||||
final String message;
|
||||
const AuthFailure(this.message);
|
||||
}
|
||||
```
|
||||
|
||||
## BlocProvider placement
|
||||
- Create `BlocProvider` at the **route level** (in {{ROUTING}} route definitions)
|
||||
- `MultiBlocProvider` at route level for screens needing multiple blocs
|
||||
- **NEVER** create `BlocProvider` inside a widget's `build()` method
|
||||
|
||||
## Usage rules
|
||||
- **NEVER** call `bloc.add()` inside `build()` — only in gesture callbacks or `initState()`
|
||||
- Use `BlocConsumer` only when BOTH `listen` + `build` logic are needed
|
||||
- Use `BlocSelector` when only a subset of state triggers a rebuild
|
||||
- Every BLoC must override `close()` and cancel `StreamSubscription`s
|
||||
|
||||
## BlocBuilder patterns
|
||||
```dart
|
||||
BlocBuilder<AuthBloc, AuthState>(
|
||||
builder: (context, state) => switch (state) {
|
||||
AuthInitial() => const SizedBox.shrink(),
|
||||
AuthLoading() => const LoadingIndicator(),
|
||||
AuthAuthenticated(user: final u) => HomeScreen(user: u),
|
||||
AuthUnauthenticated() => const LoginScreen(),
|
||||
AuthFailure(message: final m) => ErrorScreen(message: m),
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
## File locations in {{PROJECT_NAME}}
|
||||
- `lib/features/[feature]/presentation/bloc/[feature]_bloc.dart`
|
||||
- `lib/features/[feature]/presentation/bloc/[feature]_event.dart`
|
||||
- `lib/features/[feature]/presentation/bloc/[feature]_state.dart`
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
description: "GetX conventions for {{PROJECT_NAME}} (legacy — migration available)"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# GetX Standards — {{PROJECT_NAME}}
|
||||
> ⚠️ This project uses GetX. See `migration-agent` for incremental migration to Riverpod.
|
||||
|
||||
## Controller structure
|
||||
```dart
|
||||
class ProductsController extends GetxController {
|
||||
final ProductRepository _repo;
|
||||
ProductsController(this._repo);
|
||||
|
||||
final RxList<Product> products = <Product>[].obs;
|
||||
final RxBool isLoading = false.obs;
|
||||
final Rx<String?> error = Rx(null);
|
||||
|
||||
@override
|
||||
void onInit() {
|
||||
super.onInit();
|
||||
fetchProducts();
|
||||
}
|
||||
|
||||
Future<void> fetchProducts() async {
|
||||
isLoading.value = true;
|
||||
error.value = null;
|
||||
try {
|
||||
products.value = await _repo.getProducts();
|
||||
} catch (e) {
|
||||
error.value = e.toString();
|
||||
} finally {
|
||||
isLoading.value = false;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## View pattern
|
||||
```dart
|
||||
// Views extend GetView<Controller> — never GetWidget or raw StatelessWidget
|
||||
class ProductsView extends GetView<ProductsController> {
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
return Scaffold(
|
||||
body: Obx(() {
|
||||
if (controller.isLoading.value) return const ProductShimmer();
|
||||
if (controller.error.value != null) return ErrorWidget(controller.error.value!);
|
||||
return ProductList(controller.products);
|
||||
}),
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rules
|
||||
- **NEVER** pass `BuildContext` into a controller
|
||||
- Use `Binding` classes for dependency injection — never `Get.put()` in a widget
|
||||
- Use `.obs` for all reactive state — never call `update()` on non-observable state
|
||||
- Use `Get.find<Controller>()` only in `Binding` classes, not in widgets
|
||||
- **No business logic in Views** — controllers handle all logic
|
||||
|
||||
## File locations in {{PROJECT_NAME}}
|
||||
- `lib/features/[feature]/views/[feature]_view.dart`
|
||||
- `lib/features/[feature]/controllers/[feature]_controller.dart`
|
||||
- `lib/features/[feature]/bindings/[feature]_binding.dart`
|
||||
- `lib/features/[feature]/models/[feature]_model.dart`
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
---
|
||||
description: "Hooks + Riverpod conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Hooks + Riverpod Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Widget base classes
|
||||
- `HookConsumerWidget` — when you need BOTH hooks and Riverpod providers
|
||||
- `HookWidget` — when you need ONLY hooks (no Riverpod)
|
||||
- `ConsumerWidget` — when you need ONLY Riverpod (no hooks)
|
||||
|
||||
## Hook rules
|
||||
```dart
|
||||
class ProductSearchWidget extends HookConsumerWidget {
|
||||
@override
|
||||
Widget build(BuildContext context, WidgetRef ref) {
|
||||
// Hooks at the TOP of build() — never inside conditions or loops
|
||||
final searchQuery = useState('');
|
||||
final searchCtrl = useTextEditingController();
|
||||
final focusNode = useFocusNode();
|
||||
final debounced = useDebounced(searchQuery.value, const Duration(milliseconds: 300));
|
||||
|
||||
// Riverpod below hooks
|
||||
final results = ref.watch(searchResultsProvider(debounced));
|
||||
|
||||
return // ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## What goes in hooks vs providers
|
||||
| Concern | Tool |
|
||||
|---------|------|
|
||||
| Local UI state (text controller, animation, focus) | `useState`, `useAnimationController` |
|
||||
| Server/async state | Riverpod `AsyncNotifier` |
|
||||
| Cross-widget/feature state | Riverpod providers |
|
||||
| Lifecycle side effects | `useEffect` |
|
||||
|
||||
## Rules
|
||||
- **NEVER** call hooks inside `if`, `for`, or callbacks
|
||||
- `useEffect` cleanup MUST return a dispose function
|
||||
- Custom hooks: prefix with `use`, live in `lib/core/hooks/`
|
||||
- Do not use `flutter_riverpod` `ref.watch` inside `useEffect` — use `useRef` + `ref.listen`
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
description: "Riverpod conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Riverpod Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Provider types
|
||||
| Type | Use case |
|
||||
|------|----------|
|
||||
| `AsyncNotifier` | Async state from {{BACKEND}} |
|
||||
| `Notifier` | Synchronous derived/local UI state |
|
||||
| `StreamNotifier` | Real-time subscriptions |
|
||||
| `@riverpod` function | Simple computed/derived values |
|
||||
|
||||
## Code generation (mandatory)
|
||||
```dart
|
||||
// ✅ Always use @riverpod annotation
|
||||
@riverpod
|
||||
class AuthNotifier extends _$AuthNotifier {
|
||||
@override
|
||||
Future<User?> build() => ref.watch(authRepositoryProvider).currentUser();
|
||||
|
||||
Future<void> login(String email, String password) async {
|
||||
state = const AsyncLoading();
|
||||
state = await AsyncValue.guard(
|
||||
() => ref.read(authRepositoryProvider).login(email, password),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ Never write manual provider declarations
|
||||
final authProvider = StateNotifierProvider<AuthNotifier, AsyncValue<User?>>(
|
||||
(ref) => AuthNotifier(),
|
||||
); // DON'T DO THIS
|
||||
```
|
||||
|
||||
## Rules
|
||||
- `ref.watch()` inside `build()` ONLY — **never** `ref.read()` inside `build()`
|
||||
- `ref.read(provider.notifier).method()` for mutations in gesture handlers
|
||||
- `ref.invalidate(provider)` to refresh — never manually reset state to `AsyncLoading()`
|
||||
- Family providers for parameterized data: `productDetailsProvider(productId)`
|
||||
- Providers scoped at feature level; core providers in `lib/core/di/`
|
||||
|
||||
## AsyncValue in widgets
|
||||
Every `AsyncValue` MUST handle all three states:
|
||||
```dart
|
||||
ref.watch(productsProvider).when(
|
||||
data: (products) => ProductList(products: products),
|
||||
loading: () => const ProductListShimmer(), // required
|
||||
error: (e, _) => ErrorWidget(error: e), // required
|
||||
)
|
||||
```
|
||||
|
||||
## File locations in {{PROJECT_NAME}}
|
||||
- `lib/features/[feature]/[feature]_provider.dart` (generated: `[feature]_provider.g.dart`)
|
||||
- `lib/features/[feature]/[feature]_repository.dart`
|
||||
- Run `dart run build_runner watch` during development
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
description: "BLoC testing conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# BLoC Testing Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Test pattern (bloc_test)
|
||||
```dart
|
||||
// {{TEST_PATTERN}}
|
||||
|
||||
void main() {
|
||||
late AuthBloc authBloc;
|
||||
late MockAuthRepository mockRepo;
|
||||
|
||||
setUp(() {
|
||||
mockRepo = MockAuthRepository();
|
||||
authBloc = AuthBloc(repository: mockRepo);
|
||||
});
|
||||
|
||||
tearDown(() => authBloc.close());
|
||||
|
||||
group('AuthBloc', () {
|
||||
blocTest<AuthBloc, AuthState>(
|
||||
'emits [Loading, Authenticated] when login succeeds',
|
||||
build: () {
|
||||
when(() => mockRepo.login(any(), any()))
|
||||
.thenAnswer((_) async => const Right(User(id: '1', email: 'test@test.com')));
|
||||
return authBloc;
|
||||
},
|
||||
act: (bloc) => bloc.add(const AuthLoginRequested(email: 'test@test.com', password: 'pass')),
|
||||
expect: () => [
|
||||
const AuthLoading(),
|
||||
isA<AuthAuthenticated>(),
|
||||
],
|
||||
);
|
||||
|
||||
blocTest<AuthBloc, AuthState>(
|
||||
'emits [Loading, Failure] when login fails',
|
||||
build: () {
|
||||
when(() => mockRepo.login(any(), any()))
|
||||
.thenAnswer((_) async => const Left(AuthError('Invalid credentials')));
|
||||
return authBloc;
|
||||
},
|
||||
act: (bloc) => bloc.add(const AuthLoginRequested(email: 'bad', password: 'bad')),
|
||||
expect: () => [
|
||||
const AuthLoading(),
|
||||
const AuthFailure('Invalid credentials'),
|
||||
],
|
||||
);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Rules
|
||||
- Use `mocktail` for mocking — never `mockito`
|
||||
- Every BLoC test file: `test/features/[feature]/[feature]_bloc_test.dart`
|
||||
- Coverage requirement: all state transitions must be tested
|
||||
- Use `Given/When/Then` naming in test descriptions
|
||||
- Test error paths as thoroughly as success paths
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
---
|
||||
description: "Patrol E2E testing conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Patrol E2E Testing — {{PROJECT_NAME}}
|
||||
|
||||
## Test structure
|
||||
```dart
|
||||
void main() {
|
||||
patrolTest('User can complete checkout flow', ($) async {
|
||||
await $.pumpWidgetAndSettle(const App());
|
||||
|
||||
// Login
|
||||
await $(LoginScreen).waitUntilVisible();
|
||||
await $(#emailField).enterText('test@example.com');
|
||||
await $(#passwordField).enterText('password123');
|
||||
await $('Sign In').tap();
|
||||
|
||||
// Add to cart
|
||||
await $(ProductCard).at(0).tap();
|
||||
await $('Add to Cart').tap();
|
||||
|
||||
// Checkout
|
||||
await $('Cart').tap();
|
||||
await $('Checkout').tap();
|
||||
await $(CheckoutSuccessScreen).waitUntilVisible();
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Rules
|
||||
- E2E tests in `integration_test/` — separate from unit tests
|
||||
- Use `patrolTest` not `testWidgets` for E2E scenarios
|
||||
- Tag tests with `@Tags(['slow'])` so CI can skip on PRs
|
||||
- Run against real emulators/simulators, not mocked environments
|
||||
- Test on minimum supported OS version for each platform
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
description: "GetX testing conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# GetX Testing Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Test pattern
|
||||
```dart
|
||||
void main() {
|
||||
late ProductsController controller;
|
||||
late MockProductRepository mockRepo;
|
||||
|
||||
setUp(() {
|
||||
mockRepo = MockProductRepository();
|
||||
Get.testMode = true;
|
||||
controller = Get.put(ProductsController(mockRepo));
|
||||
});
|
||||
|
||||
tearDown(() => Get.deleteAll());
|
||||
|
||||
test('loads products on init', () async {
|
||||
when(() => mockRepo.getProducts()).thenAnswer((_) async => [fakeProduct]);
|
||||
await controller.fetchProducts();
|
||||
expect(controller.products, [fakeProduct]);
|
||||
expect(controller.isLoading.value, false);
|
||||
});
|
||||
|
||||
testWidgets('ProductsView shows shimmer while loading', (tester) async {
|
||||
controller.isLoading.value = true;
|
||||
await tester.pumpWidget(GetMaterialApp(home: ProductsView()));
|
||||
expect(find.byType(ProductShimmer), findsOneWidget);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Rules
|
||||
- Use `Get.testMode = true` in setUp
|
||||
- Always call `Get.deleteAll()` in tearDown
|
||||
- Wrap widget tests in `GetMaterialApp`, not `MaterialApp`
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
description: "Riverpod testing conventions for {{PROJECT_NAME}}"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Riverpod Testing Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Test pattern
|
||||
```dart
|
||||
// {{TEST_PATTERN}}
|
||||
|
||||
void main() {
|
||||
late ProviderContainer container;
|
||||
late MockProductRepository mockRepo;
|
||||
|
||||
setUp(() {
|
||||
mockRepo = MockProductRepository();
|
||||
container = ProviderContainer(overrides: [
|
||||
productRepositoryProvider.overrideWithValue(mockRepo),
|
||||
]);
|
||||
});
|
||||
|
||||
tearDown(() => container.dispose()); // ALWAYS dispose
|
||||
|
||||
test('ProductsNotifier loads products successfully', () async {
|
||||
when(() => mockRepo.getProducts()).thenAnswer((_) async => [fakeProduct]);
|
||||
|
||||
final notifier = container.read(productsProvider.notifier);
|
||||
await notifier.loadProducts();
|
||||
|
||||
final state = container.read(productsProvider);
|
||||
expect(state, isA<AsyncData<List<Product>>>());
|
||||
expect(state.value, [fakeProduct]);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Widget tests with Riverpod
|
||||
```dart
|
||||
testWidgets('ProductScreen shows shimmer while loading', (tester) async {
|
||||
await tester.pumpWidget(
|
||||
ProviderScope(
|
||||
overrides: [
|
||||
productsProvider.overrideWith((ref) => const AsyncLoading()),
|
||||
],
|
||||
child: const MaterialApp(home: ProductScreen()),
|
||||
),
|
||||
);
|
||||
expect(find.byType(ProductShimmer), findsOneWidget);
|
||||
});
|
||||
```
|
||||
|
||||
## Rules
|
||||
- **Never** use a real `ProviderScope` in unit tests — always use `ProviderContainer` with overrides
|
||||
- `addTearDown(container.dispose)` in every test that creates a container
|
||||
- Test all three `AsyncValue` states: loading, data, error
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
description: "Core Flutter conventions for {{PROJECT_NAME}} — always applied"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Flutter Core Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Const and performance
|
||||
- Use `const` constructors wherever possible — compile-time guarantee of no rebuild
|
||||
- Prefer `const` widgets at the leaf level: `const SizedBox.shrink()`, `const Padding(...)`
|
||||
- Never use `const` with mutable values; lint: `prefer_const_constructors` is enabled
|
||||
|
||||
## Null safety
|
||||
- Never use `!` (bang operator) unless you have a 100% safe runtime guarantee with a comment
|
||||
- Prefer `??`, `?.`, and `if (x != null)` guards
|
||||
- Use `required` for all non-nullable named parameters
|
||||
- Never use `late` without a guarantee of initialisation before first access
|
||||
|
||||
## Widget lifecycle
|
||||
- Override `dispose()` in every `StatefulWidget` that uses controllers, streams, or timers
|
||||
- Cancel `StreamSubscription` in `dispose()`, not in `didUpdateWidget`
|
||||
- Use `WidgetsBinding.instance.addPostFrameCallback` for post-build logic, not `Future.delayed(Duration.zero)`
|
||||
|
||||
## Naming conventions
|
||||
- Files: `snake_case.dart`
|
||||
- Classes: `PascalCase`
|
||||
- Variables/functions: `camelCase`
|
||||
- Constants: `kCamelCase` or `SCREAMING_SNAKE` for true compile-time constants
|
||||
- Private members: `_camelCase`
|
||||
|
||||
## Imports
|
||||
- Order: dart: → package: → relative
|
||||
- Use relative imports within a feature; absolute for cross-feature
|
||||
- Never import a feature's internal files from outside that feature
|
||||
|
||||
## Code quality
|
||||
- Max function length: 40 lines. Extract widgets and helpers aggressively
|
||||
- No `print()` in production code — use a logging package
|
||||
- All `TODO:` comments must include a ticket number: `// TODO: PROJ-123 — fix this`
|
||||
- Run `dart format` before every commit
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
description: "Project context for {{PROJECT_NAME}} — always applied"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Project Context — {{PROJECT_NAME}}
|
||||
|
||||
## Project identity
|
||||
- **Name:** {{PROJECT_NAME}}
|
||||
- **Package:** {{PACKAGE_ID}}
|
||||
- **Description:** {{DESCRIPTION}}
|
||||
- **Scale:** {{SCALE}}
|
||||
|
||||
## Technology stack
|
||||
- **State management:** {{STATE_MANAGEMENT}}
|
||||
- **Architecture:** {{ARCHITECTURE}}
|
||||
- **Routing:** {{ROUTING}}
|
||||
- **Backend:** {{BACKEND}}
|
||||
- **Auth:** {{AUTH}}
|
||||
- **Platforms:** {{PLATFORMS_LIST}}
|
||||
- **Code generation:** {{CODEGEN_LIST}}
|
||||
|
||||
## Feature modules
|
||||
{{FEATURES_LIST}}
|
||||
|
||||
## Special capabilities
|
||||
{{SPECIAL_FEATURES}}
|
||||
|
||||
## Environments / flavors
|
||||
- Flavors: {{FLAVORS_LIST}}
|
||||
- CI/CD: {{CICD_TOOL}}
|
||||
|
||||
## Design & API references
|
||||
- Design source: {{DESIGN_SOURCE}}
|
||||
- API docs: {{API_DOCS_FORMAT}} at `{{API_DOCS_PATH}}`
|
||||
|
||||
## Code references
|
||||
### Git repositories
|
||||
{{GIT_REFS_BLOCK}}
|
||||
|
||||
### Local paths
|
||||
{{LOCAL_PATHS_BLOCK}}
|
||||
|
||||
## Product UX / themes & roles
|
||||
- **Theme variants:** {{THEME_SUMMARY}}
|
||||
- **Roles:** {{ROLES_SUMMARY}}
|
||||
|
||||
{{HIGH_CONTRAST_NOTE}}
|
||||
## Reviews — which rule owns what
|
||||
- **Theme, colors, typography, spacing/radius tokens** → `ui-ux-standards.mdc` (widgets read `Theme.of(context)` only)
|
||||
- **User-visible copy & locales** → `localization.mdc` (ARB / `AppLocalizations`; no UI string literals)
|
||||
- **Imports, structure, naming** → `flutter-core.mdc` + architecture rule
|
||||
|
||||
## Architecture boundaries
|
||||
{{ARCH_IMPORT_RULES}}
|
||||
|
||||
## When generating code for this project
|
||||
1. Always use {{STATE_MANAGEMENT}} patterns — never suggest alternatives
|
||||
2. Always follow {{ARCHITECTURE}} folder structure
|
||||
3. Always use {{ROUTING}} for navigation — never `Navigator.push` directly
|
||||
4. Always target platforms: {{PLATFORMS_LIST}}
|
||||
5. If code generation tools are used ({{CODEGEN_LIST}}), follow their conventions
|
||||
6. Apply visuals only through theme (`ColorScheme`, `TextTheme`, `ThemeExtension`) — never ad-hoc colors/fonts in feature widgets
|
||||
7. No user-facing string literals in widgets — l10n or shared constants per localization rule
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
description: "UI/UX standards for {{PROJECT_NAME}} — always applied"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# UI / UX Standards — {{PROJECT_NAME}}
|
||||
|
||||
## Theme & design tokens (single source of truth)
|
||||
- Define **one** light/dark `ThemeData` (and optional `ThemeExtension`s for brand spacing, radii, semantic colors). Feature code reads `Theme.of(context)` only.
|
||||
- **Colors:** `colorScheme` / extensions — never hex/`Color(...)` literals in widgets except inside the theme definition file(s).
|
||||
- **Typography:** `textTheme` / `primaryTextTheme` — never raw `TextStyle(fontSize:, fontFamily:)` in feature UI.
|
||||
- **Spacing & shapes:** `ThemeExtension` or documented constants consumed consistently — avoid one-off magic numbers for padding/radius.
|
||||
|
||||
## Loading states
|
||||
- Every async operation MUST show a loading skeleton (shimmer), NOT a spinner unless < 300ms
|
||||
- Use `shimmer` package with a shimmer that matches the final layout shape
|
||||
- Never show a blank screen during loading — skeleton must fill the same space as the content
|
||||
|
||||
## Empty states
|
||||
- Every list/grid MUST have a distinct empty state widget: illustration + headline + CTA
|
||||
- Empty state is different from error state — never reuse the same widget for both
|
||||
- Empty state copy: positive framing ("No items yet — add your first one")
|
||||
|
||||
## Error states
|
||||
- Every async failure MUST show: error message + retry button
|
||||
- Never swallow errors silently
|
||||
- Error text: user-friendly, never expose stack traces or raw API messages
|
||||
|
||||
## Navigation & transitions
|
||||
- Use `IndexedStack` for bottom nav tabs — preserves scroll position
|
||||
- Named routes only — never `Navigator.push(context, MaterialPageRoute(...))`
|
||||
- Page transitions: use `CustomTransitionPage` with `FadeTransition` for modal sheets
|
||||
|
||||
## Responsive layout
|
||||
- Use `LayoutBuilder` or `MediaQuery` for breakpoints, not hardcoded pixel values
|
||||
- Minimum touch target: 48×48 logical pixels (Material guideline)
|
||||
- Test on 375px (iPhone SE) and 414px (iPhone Pro Max) widths minimum
|
||||
|
||||
## Haptics
|
||||
- Use `HapticFeedback.lightImpact()` on primary CTAs
|
||||
- Use `HapticFeedback.selectionClick()` on toggle/checkbox interactions
|
||||
- Never add haptics to destructive actions without confirmation
|
||||
|
||||
## Accessibility
|
||||
- All interactive widgets must have a `Semantics` label or `tooltip`
|
||||
- Minimum contrast ratio: 4.5:1 (WCAG AA)
|
||||
- Test with TalkBack / VoiceOver before each release
|
||||
{{HIGH_CONTRAST_UX_LINE}}
|
||||
@@ -0,0 +1,18 @@
|
||||
# Create Build Flavor — {{PROJECT_NAME}}
|
||||
|
||||
Creates a new build flavor/environment. Current flavors: {{FLAVORS_LIST}}.
|
||||
|
||||
## Usage
|
||||
```
|
||||
Create a new flavor called [flavor_name]
|
||||
```
|
||||
|
||||
## What gets created
|
||||
1. Android: new `productFlavors` block in `android/app/build.gradle`
|
||||
2. iOS: new scheme + configuration in Xcode (instructions provided)
|
||||
3. `lib/core/config/[flavor_name]_config.dart`
|
||||
4. `.env.[flavor_name]` template
|
||||
5. {{CICD_TOOL}} pipeline update
|
||||
|
||||
## CI/CD: {{CICD_TOOL}}
|
||||
Generate the pipeline config snippet for the new flavor in {{CICD_TOOL}} format.
|
||||
@@ -0,0 +1,21 @@
|
||||
# Deploy — {{PROJECT_NAME}}
|
||||
|
||||
Guides through deployment to {{CICD_TOOL}} for any of the flavors: {{FLAVORS_LIST}}.
|
||||
|
||||
## Usage
|
||||
```
|
||||
Deploy [flavor] to [store/environment]
|
||||
```
|
||||
|
||||
## {{CICD_TOOL}} pipeline
|
||||
The AI will generate or update the {{CICD_RAW}} configuration file for:
|
||||
- Build signing
|
||||
- Running tests
|
||||
- Distributing to Firebase App Distribution (beta) or App Store / Play Store (prod)
|
||||
|
||||
## Pre-deploy checklist
|
||||
- [ ] Version bump in `pubspec.yaml`
|
||||
- [ ] Obfuscation enabled for prod: `--obfuscate --split-debug-info=build/debug-symbols/`
|
||||
- [ ] No debug flags in production code
|
||||
- [ ] Security checklist from `security-standards.mdc` passed
|
||||
- [ ] `cursor_gen --validate` passes
|
||||
@@ -0,0 +1,16 @@
|
||||
# Generate API Client — {{PROJECT_NAME}}
|
||||
|
||||
Generates type-safe API clients from {{API_DOCS_FORMAT}} spec at `{{API_DOCS_PATH}}`.
|
||||
|
||||
## Usage
|
||||
```
|
||||
Generate API client for [endpoint or resource name]
|
||||
```
|
||||
|
||||
## Generated files
|
||||
1. **DTO** (`data/models/[resource]_dto.dart`) — request/response models with json_serializable
|
||||
2. **DataSource** (`data/datasources/[resource]_remote_datasource.dart`) — Dio calls with error handling
|
||||
3. **Repository impl** (`data/repositories/[resource]_repository_impl.dart`)
|
||||
|
||||
## After generation
|
||||
Run: `dart run build_runner build --delete-conflicting-outputs`
|
||||
@@ -0,0 +1,41 @@
|
||||
# Generate Tests — {{PROJECT_NAME}}
|
||||
|
||||
Generates comprehensive unit, widget, and integration tests for **{{STATE_MANAGEMENT}}** patterns.
|
||||
|
||||
## Usage
|
||||
```
|
||||
Generate tests for [ClassName or file path]
|
||||
```
|
||||
|
||||
## Test generation process
|
||||
1. Read the source file completely
|
||||
2. Identify all testable units (public methods, state transitions, UI states)
|
||||
3. Generate tests following this pattern:
|
||||
```
|
||||
{{TEST_PATTERN}}
|
||||
```
|
||||
4. Create mocks with `mocktail` for all dependencies
|
||||
5. Place test file at `test/[mirror of source path]_test.dart`
|
||||
|
||||
## Coverage targets
|
||||
- Business logic (UseCases, Repositories, BLoC/Notifiers): **80% minimum**
|
||||
- Widget tests: all three states (loading/error/data) must be tested
|
||||
- E2E: only critical user flows
|
||||
|
||||
## Test file structure
|
||||
```dart
|
||||
void main() {
|
||||
// Setup
|
||||
group('[ClassName]', () {
|
||||
// Happy path tests
|
||||
group('success cases', () { ... });
|
||||
// Error path tests
|
||||
group('error cases', () { ... });
|
||||
// Edge cases
|
||||
group('edge cases', () { ... });
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Naming convention
|
||||
`'given [precondition], when [action], then [expected outcome]'`
|
||||
@@ -0,0 +1,69 @@
|
||||
# Scaffold Feature — {{PROJECT_NAME}}
|
||||
|
||||
Scaffolds a complete new feature module following **{{ARCHITECTURE}}** architecture with **{{STATE_MANAGEMENT}}** state management.
|
||||
|
||||
## Usage
|
||||
```
|
||||
Create a feature called [feature_name] with [description]
|
||||
```
|
||||
|
||||
## What gets generated
|
||||
|
||||
### For {{ARCHITECTURE}} architecture:
|
||||
The AI will create all necessary files for the `[feature_name]` feature following {{ARCHITECTURE}} patterns.
|
||||
|
||||
### File structure to create:
|
||||
|
||||
**Clean Architecture:**
|
||||
```
|
||||
lib/features/[feature_name]/
|
||||
domain/
|
||||
entities/[feature_name].dart
|
||||
repositories/[feature_name]_repository.dart
|
||||
usecases/
|
||||
get_[feature_name]_usecase.dart
|
||||
create_[feature_name]_usecase.dart
|
||||
data/
|
||||
models/[feature_name]_dto.dart
|
||||
datasources/[feature_name]_remote_datasource.dart
|
||||
repositories/[feature_name]_repository_impl.dart
|
||||
presentation/
|
||||
[state_files]/ ← based on {{STATE_MANAGEMENT}}
|
||||
pages/[feature_name]_page.dart
|
||||
widgets/
|
||||
```
|
||||
|
||||
**Feature-First:**
|
||||
```
|
||||
lib/features/[feature_name]/
|
||||
[feature_name]_screen.dart
|
||||
[feature_name]_provider.dart ← or [feature_name]_bloc.dart
|
||||
[feature_name]_repository.dart
|
||||
[feature_name]_model.dart
|
||||
widgets/
|
||||
```
|
||||
|
||||
## State management boilerplate
|
||||
|
||||
### For {{STATE_MANAGEMENT}}:
|
||||
Generate the appropriate state management files with:
|
||||
- Initial/loading/success/error states
|
||||
- All necessary events (for BLoC)
|
||||
- Repository connection
|
||||
- Dependency injection registration
|
||||
|
||||
## Steps the AI takes
|
||||
1. Ask: "What is the feature name and brief description?"
|
||||
2. Ask: "What data does this feature manage? (e.g., list of products, single user profile)"
|
||||
3. Generate all files with correct imports and patterns
|
||||
4. Add the feature to the DI container
|
||||
5. Add the route to {{ROUTING}} router
|
||||
6. Create a placeholder test file
|
||||
|
||||
## Code generation
|
||||
{{#if codegen_freezed}}
|
||||
- Generate Freezed model: run `dart run build_runner build` after scaffolding
|
||||
{{/if}}
|
||||
{{#if codegen_injectable}}
|
||||
- Register in injectable: add `@lazySingleton` to repository
|
||||
{{/if}}
|
||||
@@ -0,0 +1,61 @@
|
||||
# Scaffold Screen — {{PROJECT_NAME}}
|
||||
|
||||
Creates a complete screen widget with all states handled, following **{{STATE_MANAGEMENT}}** patterns.
|
||||
|
||||
## Usage
|
||||
```
|
||||
Create a screen for [screen_name] that shows [content description]
|
||||
```
|
||||
|
||||
## Generated screen template
|
||||
|
||||
### {{STATE_MANAGEMENT}} screen pattern:
|
||||
|
||||
**BLoC:**
|
||||
```dart
|
||||
class [ScreenName]Screen extends StatelessWidget {
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
return BlocBuilder<[Feature]Bloc, [Feature]State>(
|
||||
builder: (context, state) => switch (state) {
|
||||
[Feature]Initial() || [Feature]Loading() => const [ScreenName]Shimmer(),
|
||||
[Feature]Loaded(:final data) => [ScreenName]Content(data: data),
|
||||
[Feature]Empty() => const [ScreenName]EmptyState(),
|
||||
[Feature]Error(:final message) => [ScreenName]ErrorState(
|
||||
message: message,
|
||||
onRetry: () => context.read<[Feature]Bloc>().add(const [Feature]LoadRequested()),
|
||||
),
|
||||
},
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Riverpod:**
|
||||
```dart
|
||||
class [ScreenName]Screen extends ConsumerWidget {
|
||||
@override
|
||||
Widget build(BuildContext context, WidgetRef ref) {
|
||||
final state = ref.watch([feature]Provider);
|
||||
return state.when(
|
||||
loading: () => const [ScreenName]Shimmer(),
|
||||
data: (data) => [ScreenName]Content(data: data),
|
||||
error: (e, _) => [ScreenName]ErrorState(error: e),
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Required sub-widgets to generate
|
||||
1. `[ScreenName]Shimmer` — skeleton loading layout matching final content
|
||||
2. `[ScreenName]EmptyState` — illustration + headline + CTA button
|
||||
3. `[ScreenName]ErrorState` — error message + retry button
|
||||
4. `[ScreenName]Content` — the actual data display
|
||||
|
||||
## Platform considerations ({{PLATFORMS_LIST}})
|
||||
{{#if platform_web}}
|
||||
- Web: ensure no dart:io usage; test at 375px and 1280px widths
|
||||
{{/if}}
|
||||
{{#if platform_desktop}}
|
||||
- Desktop: add keyboard shortcut support for primary actions
|
||||
{{/if}}
|
||||
Reference in New Issue
Block a user