@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/flutter/retrofit-networking/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: Flutter Networking (Retrofit & Dio)
+description: HTTP networking standards using Dio and Retrofit with Auth interceptors.
+metadata:
+  labels: [networking, retrofit, dio]
+  triggers:
+    files: ['**/data_sources/**', '**/api/**']
+    keywords: [Retrofit, Dio, RestClient, GET, POST, Interceptor, refreshing]
+---
+
+# Retrofit & Dio Networking
+
+## **Priority: P0 (CRITICAL)**
+
+Type-safe REST API communication using `Dio` and `Retrofit`.
+
+## Structure
+
+```text
+infrastructure/
+├── data_sources/
+│   ├── remote/ # Retrofit abstract classes
+│   └── local/ # Cache/Storage
+└── network/
+    ├── dio_client.dart # Custom Dio setup
+    └── interceptors/ # Auth, Logging, Cache
+```
+
+## Implementation Guidelines
+
+- **Retrofit Clients**: Define abstract classes with `@RestApi()`. Use standard HTTP annotations (`@GET`, `@POST`).
+- **DTOs (Data Transfer Objects)**: Use `@freezed` and `json_serializable` for all response/request bodies.
+- **Mapping**: Data sources MUST map DTOs to Domain Entities (e.g., `userDto.toDomain()`).
+- **AuthInterceptor**: Logic for `Authorization: Bearer <token>` injection in `onRequest`.
+- **Token Refresh**: Handle `401 Unauthorized` in `onError` by locking Dio, refreshing, and retrying.
+- **Failures**: Map `DioException` to custom `Failure` objects (ServerFailure, NetworkFailure).
+
+## Anti-Patterns
+
+- **No Manual JSON Parsing**: Do not use `jsonDecode(response.body)`; use Retrofit's generated mappers.
+- **No Global Dio**: Do not use a static global Dio instance; use dependency injection.
+- **No Try-Catch in API**: Do not put `try-catch` inside the Retrofit interface methods.
+
+## Reference & Examples
+
+For RestClient definitions and Auth Interceptor implementation:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+feature-based-clean-architecture | error-handling

package/rules/flutter/retrofit-networking/references/REFERENCE.md

@@ -0,0 +1,19 @@
+# Retrofit & Dio Reference
+
+Standards for API communication and networking logic.
+
+## References
+
+- [**RestClient Setup**](client-definition.md) - Standard Retrofit interface examples.
+- [**Auth Interceptors**](auth-interceptor.md) - Handling Bearer tokens and Auth headers.
+- [**Token Refresh Logic**](token-refresh.md) - The 401 Lock-Refresh-Retry pattern.
+
+## **Quick Definition**
+
+```dart
+@RestApi()
+abstract class ApiClient {
+  @GET("/items")
+  Future<List<ItemDto>> getItems(@Query("limit") int limit);
+}
+```

package/rules/flutter/retrofit-networking/references/token-refresh.md

@@ -0,0 +1,40 @@
+# Token Refresh Pattern
+
+When a `401 Unauthorized` error occurs, the networking layer should handle the refresh cycle transparently.
+
+## **Implementation Flow (Dio Interceptor)**
+
+```dart
+class AuthInterceptor extends QueuedInterceptorsWrapper {
+  final Dio dio;
+  final SecureStorage storage;
+
+  AuthInterceptor(this.dio, this.storage);
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    if (err.response?.statusCode == 401) {
+      // 1. Refresh the token
+      final newToken = await _performRefresh();
+      
+      if (newToken != null) {
+        // 2. Retry the original request with new token
+        final options = err.requestOptions;
+        options.headers['Authorization'] = 'Bearer $newToken';
+        
+        final response = await dio.fetch(options);
+        return handler.resolve(response);
+      }
+    }
+    return handler.next(err);
+  }
+
+  Future<String?> _performRefresh() async {
+    // Logic to call refresh endpoint and update storage
+  }
+}
+```
+
+## **Why QueuedInterceptorsWrapper?**
+
+Using `QueuedInterceptorsWrapper` ensures that if multiple requests trigger a 401 at the same time, they are queued while the first one performs the token refresh, preventing multiple redundant refresh calls.

package/rules/flutter/riverpod-state-management/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: Flutter Riverpod State Management
+description: Reactive state management using Riverpod 2.0 with code generation.
+metadata:
+  labels: [state-management, riverpod, dependency-injection, reactive]
+  triggers:
+    files: ['**_provider.dart', '**_notifier.dart']
+    keywords: [riverpod, ProviderScope, ConsumerWidget, Notifier, AsyncValue, ref.watch, "@riverpod"]
+---
+
+# Riverpod State Management
+
+## **Priority: P0 (CRITICAL)**
+
+Type-safe, compile-time safe reactive state management using `riverpod` and `riverpod_generator`.
+
+## Structure
+
+```text
+lib/
+├── providers/ # Global providers and services
+└── features/
+    └── user/
+        ├── providers/ # Feature-specific providers
+        └── models/    # @freezed domain models
+```
+
+## Implementation Guidelines
+
+- **Generator First**: Use `@riverpod` annotations and `riverpod_generator`. Avoid manual `Provider` definitions.
+- **Immutability**: Maintain immutable states. Use `Freezed` for all state models.
+- **Provider Methods**:
+  - `ref.watch()`: Use inside `build()` to rebuild on changes.
+  - `ref.listen()`: Use for side-effects (navigation, dialogs).
+  - `ref.read()`: Use ONLY in callbacks (onPressed).
+- **Asynchronous Data**: Use `AsyncNotifier` for complex async logic. Access data via `.when()` or `AsyncValue` pattern-matching.
+- **Architecture**: Enforce 3-layer separation (Data, Domain, Presentation).
+- **Linting**: Enable `riverpod_lint` and `custom_lint` for dependency cycle detection.
+
+## Anti-Patterns
+
+- **Building Inside Providers**: Don't perform side-effects inside provider initialization.
+- **Context Access**: Never pass `BuildContext` into a Notifier/Provider.
+- **Dynamic Providers**: Avoid local provider instantiation; keep them global.
+
+## Reference & Examples
+
+For architecture details, best practices, and testing overrides:
+See [references/architecture.md](references/architecture.md), [references/best-practices.md](references/best-practices.md), and [references/testing.md](references/testing.md).
+
+## Related Topics
+
+feature-based-clean-architecture | dependency-injection | testing

package/rules/flutter/riverpod-state-management/references/architecture.md

@@ -0,0 +1,124 @@
+# Architecture & Layers
+
+## 1. Data Layer: Repository Interface & Providers
+
+Always separate interface from implementation to enable easy mocking.
+
+```dart
+// domain/repository/user_repository.dart
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../../data/repository/api_user_repository.dart';
+import '../models/user.dart';
+
+part 'user_repository.g.dart';
+
+// 1. Define the Provider returning the INTERFACE
+@riverpod
+UserRepository userRepository(UserRepositoryRef ref) {
+  // Return the specific implementation here.
+  // Can be swapped for MockUserRepository based on environment flags.
+  return ApiUserRepository(ref.watch(apiClientProvider));
+}
+
+// 2. Define the Interface
+abstract interface class UserRepository {
+  Future<List<User>> getAllUsers();
+  Future<void> deleteUser(String id);
+}
+```
+
+```dart
+// data/repository/api_user_repository.dart
+class ApiUserRepository implements UserRepository {
+  final UserApiClient _client;
+
+  ApiUserRepository(this._client);
+
+  @override
+  Future<List<User>> getAllUsers() async {
+    return _client.fetchUsers();
+  }
+}
+```
+
+## 2. Presentation Layer: AsyncNotifier Controller
+
+Use `AsyncNotifier` (via `@riverpod` class) to handle loading/error/data states naturally.
+
+```dart
+// features/users/user_controller.dart
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+import '../../domain/repository/user_repository.dart';
+import '../../domain/models/user.dart';
+
+part 'user_controller.g.dart';
+
+@riverpod
+class UserController extends _$UserController {
+  @override
+  FutureOr<List<User>> build() async {
+    // 1. Fetch initial data
+    return ref.watch(userRepositoryProvider).getAllUsers();
+  }
+
+  // 2. Mutation Methods
+  Future<void> deleteUser(String id) async {
+    // Set loading state (optional, for optimisic UI usually prefer local)
+    // state = const AsyncLoading();
+
+    // Perform action
+    state = await AsyncValue.guard(() async {
+      await ref.read(userRepositoryProvider).deleteUser(id);
+      // Refresh logic:
+      // Option A: Refetch everything
+      return ref.refresh(userRepositoryProvider).getAllUsers();
+
+      // Option B: Optimistic Update (Better performance)
+      // final currentList = state.requireValue;
+      // return currentList.where((u) => u.id != id).toList();
+    });
+  }
+}
+```
+
+## 3. UI Layer: ConsumerWidget
+
+Handle all 3 states (`data`, `loading`, `error`) using `.when`.
+
+```dart
+// features/users/user_list_screen.dart
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+class UserListScreen extends ConsumerWidget {
+  const UserListScreen({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    // 1. Watch the Notifier Provider
+    final state = ref.watch(userControllerProvider);
+
+    return Scaffold(
+      body: state.when(
+        data: (users) => ListView.builder(
+          itemCount: users.length,
+          itemBuilder: (ctx, index) {
+            final user = users[index];
+            return ListTile(
+              title: Text(user.name),
+              // 2. Call mutation methods via .read()
+              trailing: IconButton(
+                icon: const Icon(Icons.delete),
+                onPressed: () {
+                  ref.read(userControllerProvider.notifier).deleteUser(user.id);
+                },
+              ),
+            );
+          },
+        ),
+        loading: () => const Center(child: CircularProgressIndicator()),
+        error: (err, st) => Center(child: Text('Error: $err')),
+      ),
+    );
+  }
+}
+```

package/rules/flutter/riverpod-state-management/references/best-practices.md

@@ -0,0 +1,89 @@
+# Best Practices & DCM Rules
+
+## Code Generation (`riverpod_generator`)
+
+Always use code generation. It prevents syntax errors and handles "family" parameters automatically.
+
+**❌ Bad (Legacy)**
+
+```dart
+final myProvider = Provider<String>((ref) => 'Hello'); // Manual typing, error prone
+```
+
+**✅ Good (Generated)**
+
+```dart
+@riverpod
+String my(MyRef ref) => 'Hello'; // Type-safe, auto-disposal by default
+```
+
+## Immutability & State Updates
+
+Riverpod relies on strict object equality (`==`) to detect changes.
+
+**❌ Bad (Mutation)**
+
+```dart
+state.add(newItem); // Same reference, listeners won't fire
+state = state;
+```
+
+**✅ Good (New Reference)**
+
+```dart
+state = [...state, newItem]; // New list, new reference
+```
+
+## DCM & Linter Rules (`riverpod_lint`)
+
+Enable strict rules in `analysis_options.yaml` via `custom_lint`.
+
+### 1. `avoid-ref-read-inside-build`
+
+**Rule**: Never use `ref.read` inside the `build()` method. It causes bugs where widgets don't update on change.
+**Correct**: Use `ref.watch`.
+
+### 2. `avoid-calling-notifier-members-inside-build`
+
+**Rule**: Do not trigger side effects (API calls, internal mutations) inside `build`.
+**Correct**: Use `build()` purely for initialization. Trigger actions via user interaction (onPressed) or `useEffect` (flutter_hooks).
+
+### 3. `dispose-provided-instances`
+
+**Rule**: If a provider creates a `ChangeNotifier` or stream controller, make sure it is disposed.
+**Correct**:
+
+```dart
+@riverpod
+StreamController myController(Ref ref) {
+  final controller = StreamController();
+  ref.onDispose(controller.close); // ✅ Register disposal
+  return controller;
+}
+```
+
+### 4. `use-ref-and-state-synchronously`
+
+**Rule**: Don't use `ref` or setter `state` after an `await` without checking if the provider is still active.
+**Context**: If a provider is disposed (e.g. user leaves screen) while an async task is running, setting state will throw.
+
+**✅ Good**:
+
+```dart
+final result = await repo.fetch();
+if (ref.context.mounted) { // Or simply rely on `AsyncValue.guard` which handles this somewhat safely
+   state = AsyncData(result);
+}
+```
+
+## `keepAlive` Strategy
+
+By default, auto-generated providers are `autoDispose`. This is good for memory but bad for caching.
+
+- **Use `keepAlive: true`** for global data (User Session, App Config).
+- **Use Default (`keepAlive: false`)** for screen-specific data (Product Details), so it clears to save memory when the screen is popped.
+
+```dart
+@Riverpod(keepAlive: true)
+class UserSession extends _$UserSession { ... }
+```

package/rules/flutter/riverpod-state-management/references/testing.md

@@ -0,0 +1,73 @@
+# Testing with Riverpod
+
+Riverpod is designed for testability. You do not need complex dependency injection containers; you simply "override" providers in the test scope.
+
+## Unit Testing (Notifiers)
+
+Test notifiers in isolation using a `ProviderContainer`.
+
+```dart
+test('increment adds 1 to state', () {
+  // 1. Create container
+  final container = ProviderContainer();
+  addTearDown(container.dispose);
+
+  // 2. Listen to provider (required to initialize it)
+  container.listen(counterProvider, (_, __) {});
+
+  // 3. Act
+  container.read(counterProvider.notifier).increment();
+
+  // 4. Assert
+  expect(container.read(counterProvider), 1);
+});
+```
+
+## Widget/Integration Testing (Overrides)
+
+When testing widgets, wrap them in a `ProviderScope` and override the repository providers with mocks.
+
+```dart
+testWidgets('shows loading then data', (tester) async {
+  final mockRepo = MockUserRepository();
+  when(() => mockRepo.getAllUsers()).thenAnswer((_) async => [User(id: 1, name: 'Bob')]);
+
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        // 🔑 Replace the REAL repository with the MOCK
+        userRepositoryProvider.overrideWithValue(mockRepo),
+      ],
+      child: const MaterialApp(home: UserListScreen()),
+    ),
+  );
+
+  // Assert Loading
+  expect(find.byType(CircularProgressIndicator), findsOneWidget);
+
+  // Assert Data
+  await tester.pumpAndSettle();
+  expect(find.text('Bob'), findsOneWidget);
+});
+```
+
+## Mocking `AsyncNotifiers`
+
+Sometimes you want to mock the _entire_ Controller/Notifier state, not just the repository.
+
+```dart
+// 1. Extend the generated class (or create a mock)
+class MockUserController extends AutoDisposeAsyncNotifier<List<User>>
+    implements UserController {
+  @override
+  FutureOr<List<User>> build() => [];
+}
+
+// 2. Override in ProviderScope
+ProviderScope(
+  overrides: [
+    userControllerProvider.overrideWith(() => MockUserController()),
+  ],
+  child: ...
+)
+```

package/rules/flutter/riverpod.rule.md

@@ -0,0 +1,78 @@
+---
+id: flutter-riverpod
+version: 1.0.0
+triggers: [riverpod, provider, state]
+---
+
+# Riverpod
+
+State management with Riverpod 2.x and code generation.
+
+## Setup
+
+```yaml
+dependencies:
+  flutter_riverpod: ^2.4.0
+  riverpod_annotation: ^2.3.0
+
+dev_dependencies:
+  riverpod_generator: ^2.3.0
+  build_runner: ^2.4.0
+```
+
+## Provider Types
+
+```dart
+// Simple value
+@riverpod
+String greeting(GreetingRef ref) => 'Hello';
+
+// Async data
+@riverpod
+Future<User> user(UserRef ref) async {
+  return ref.watch(apiProvider).getUser();
+}
+
+// Notifier for mutable state
+@riverpod
+class Counter extends _$Counter {
+  @override
+  int build() => 0;
+
+  void increment() => state++;
+}
+```
+
+## Consumer Usage
+
+```dart
+class MyWidget extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final count = ref.watch(counterProvider);
+    return Text('$count');
+  }
+}
+```
+
+## Async Handling
+
+```dart
+ref.watch(userProvider).when(
+  data: (user) => UserCard(user),
+  loading: () => const CircularProgressIndicator(),
+  error: (e, st) => ErrorText(e.toString()),
+);
+```
+
+## Family Providers
+
+```dart
+@riverpod
+Future<Post> post(PostRef ref, int id) async {
+  return ref.watch(apiProvider).getPost(id);
+}
+
+// Usage
+ref.watch(postProvider(42));
+```

package/rules/flutter/security/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: Flutter Security
+description: Security standards for Flutter applications based on OWASP Mobile.
+metadata:
+  labels: [security, owasp, pii, encryption]
+  triggers:
+    files: ['lib/infrastructure/**', 'pubspec.yaml']
+    keywords: [secure_storage, obfuscate, jailbreak, pinning, PII, OWASP]
+---
+
+# Mobile Security
+
+## **Priority: P0 (CRITICAL)**
+
+Standards for basic mobile security and PII protection.
+
+## Implementation Guidelines
+
+- **Secure Storage**: Use `flutter_secure_storage` for tokens/PII. Never use `shared_preferences`.
+- **Hardcoding**: Never store API keys or secrets in Dart code. Use `--dart-define` or `.env`.
+- **Obfuscation**: Always release with `--obfuscate` and `--split-debug-info`.
+- **SSL Pinning**: For high-security apps, use `dio_certificate_pinning`.
+- **Root Detection**: Use `flutter_jailbreak_detection` for financial/sensitive applications.
+- **PII Masking**: Mask sensitive data (email, phone) in logs and analytics.
+
+## Reference & Examples
+
+For SSL Pinning and Secure Storage implementation details:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+layer-based-clean-architecture | performance

package/rules/flutter/security/references/REFERENCE.md

@@ -0,0 +1,15 @@
+# Mobile Security Reference
+
+Detailed implementation patterns for OWASP Mobile compliance.
+
+## References
+
+- [**Network Security**](network-security.md) - SSL Pinning and Security Headers.
+- [**Secure Storage**](secure-storage-impl.md) - PII and Token management.
+
+## **CI/CD Security Flag**
+
+```bash
+# Obfuscation during build
+flutter build apk --obfuscate --split-debug-info=./debug-info
+```

package/rules/flutter/security/references/network-security.md

@@ -0,0 +1,28 @@
+# Network Security & Certificate Pinning
+
+## **SSL Pinning with Dio**
+
+```dart
+import 'package:dio/dio.dart';
+import 'package:dio_certificate_pinning/dio_certificate_pinning.dart';
+
+final dio = Dio();
+dio.interceptors.add(CertificatePinningInterceptor(
+  allowedSHAFingerprints: [
+    "70:99:27:8B:54:4A:40:F5:30:DB:73:E3:64:36:0F:70:3D:09:A6:49",
+  ],
+));
+```
+
+## **Security Headers Interceptor**
+
+```dart
+class SecurityInterceptor extends Interceptor {
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    options.headers['X-Content-Type-Options'] = 'nosniff';
+    options.headers['X-Frame-Options'] = 'DENY';
+    super.onRequest(options, handler);
+  }
+}
+```

package/rules/flutter/testing/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: Flutter Testing Standards
+description: Unit, widget, and integration testing using mocktail and bloc_test.
+metadata:
+  labels: [testing, junit, mocktail, bloc_test, golden-tests]
+  triggers:
+    files: ['**/test/**.dart']
+    keywords: [test, group, expect, mocktail, blocTest, when, any]
+---
+
+# Testing Standards
+
+## **Priority: P1 (HIGH)**
+
+Ensuring code reliability through multi-layered testing strategies.
+
+## Structure
+
+```text
+test/
+├── unit/ # Business logic & mapping (Blocs, Repositories, UseCases)
+├── widget/ # UI component behavior (Screens, Widgets)
+└── integration/ # End-to-end flows
+```
+
+## Implementation Guidelines
+
+- **Testing Pyramid**: Maintain ~70% Unit Tests, ~20% Widget Tests, ~10% Integration Tests.
+- **Mocks**: Use `mocktail` for type-safe, boilerplate-free mocking.
+- **Unit Tests**: Test logic in isolation. Verify all edge cases (Success, Failure, Exception).
+- **Widget Tests**: Test high-value interactions (Button clicks, Error states, Loading indicators).
+- **BLoC Tests**: Use `blocTest` to verify state emission sequences.
+- **Code Coverage**: Aim for 80%+ coverage on Domain and Presentation (Logic) layers.
+
+## Deep Dive References
+
+- [Unit Testing Strategies](./references/unit-testing.md) (Test Data Builders, Mocktail)
+- [Widget Testing Strategies](./references/widget-testing.md) (Robot Pattern)
+- [Integration Testing](./references/integration-testing.md) (Shared Robots, Real Device)
+- [Robot Pattern Implementation](./references/robot-pattern.md)
+
+## Related Topics
+
+layer-based-clean-architecture | dependency-injection | cicd

package/rules/flutter/testing/references/REFERENCE.md

@@ -0,0 +1,21 @@
+# Testing Standards Reference
+
+Practical patterns for Unit, Widget, and Golden tests.
+
+## References
+
+- [**Unit Testing**](unit-testing.md) - Mocking, AAA pattern, Repository testing.
+- [**Widget Testing**](widget-testing.md) - UI interactions, Finders, Pumping frames.
+- [**BLoC Testing**](bloc-testing.md) - Using `blocTest` for state transitions.
+
+## **Quick Assertions**
+
+```dart
+// Mocktail Stub
+when(() => repository.fetchData()).thenAnswer((_) async => right(data));
+
+// Expect Matchers
+expect(state.isLoading, isTrue);
+expect(find.text('Hello'), findsOneWidget);
+verify(() => repository.fetchData()).called(1);
+```