@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/flutter/cicd/references/fastlane.md

@@ -0,0 +1,139 @@
+# Advanced Fastlane Standards
+
+Automates signing, build versioning, flavors, and multi-channel distribution (Firebase vs. Stores).
+
+## Prerequisites
+
+1. **Versioning**: Use `flutter_version` or `cider` to sync Fastlane with `pubspec.yaml`.
+2. **Firebase**: Install plugin: `bundle exec fastlane add_plugin firebase_app_distribution`.
+3. **Flavors**: Ensure your Flutter app is set up with Flavors (e.g., `dev`, `prod` schemes).
+
+## Android Configuration (`android/fastlane/Fastfile`)
+
+Supported lanes:
+
+- `staging`: Builds `dev` flavor -> Firebase App Distribution.
+- `prod`: Builds `prod` flavor -> Play Store (Internal Track).
+
+```ruby
+default_platform(:android)
+
+platform :android do
+  # Helper: Read version from pubspec
+  def load_version
+    # Requires: gem install yaml
+    require 'yaml'
+    pubspec = YAML.load_file("../../pubspec.yaml")
+    return pubspec['version'].split('+') # Returns [version, build]
+  end
+
+  desc "Deploy Staging to Firebase"
+  lane :staging do
+    version_name, version_code = load_version
+
+    # 1. Build APK (Flavor: Dev, Type: Release)
+    gradle(
+      task: "assemble",
+      flavor: "Dev",
+      build_type: "Release",
+      properties: {
+        "android.injected.version.code" => version_code,
+        "android.injected.version.name" => version_name
+      }
+    )
+
+    # 2. Upload to Firebase
+    firebase_app_distribution(
+      app: ENV["FIREBASE_APP_ID_ANDROID_DEV"],
+      groups: "qa-team",
+      release_notes: "Staging Build v#{version_name} (#{version_code})"
+    )
+  end
+
+  desc "Deploy Production to Play Store"
+  lane :prod do
+    version_name, version_code = load_version
+
+    # 1. Build Bundle (Flavor: Prod)
+    gradle(
+      task: "bundle",
+      flavor: "Prod",
+      build_type: "Release",
+      properties: {
+        "android.injected.version.code" => version_code,
+        "android.injected.version.name" => version_name
+      }
+    )
+
+    # 2. Upload to Play Store
+    upload_to_play_store(
+      track: "internal",
+      json_key: ENV["PLAY_STORE_JSON_KEY_FILE"],
+      skip_upload_metadata: true,
+      skip_upload_images: true,
+      skip_upload_screenshots: true
+    )
+  end
+end
+```
+
+## iOS Configuration (`ios/fastlane/Fastfile`)
+
+Supported lanes:
+
+- `staging`: Builds `Dev` Scheme -> Firebase (AdHoc).
+- `prod`: Builds `Prod` Scheme -> TestFlight (AppStore).
+
+**Note**: Creates separate `Matchfile` logic for AdHoc vs AppStore.
+
+```ruby
+default_platform(:ios)
+
+platform :ios do
+  before_all do
+    setup_ci if ENV['CI']
+  end
+
+  desc "Deploy Staging to Firebase (AdHoc)"
+  lane :staging do
+    # 1. Sync Signing (AdHoc for restricted devices)
+    match(type: "adhoc", app_identifier: "com.example.app.dev", readonly: is_ci)
+
+    # 2. Build IPA (Scheme: Dev)
+    build_app(
+      scheme: "Dev",
+      export_method: "ad-hoc",
+      include_bitcode: false
+    )
+
+    # 3. Upload to Firebase
+    firebase_app_distribution(
+      app: ENV["FIREBASE_APP_ID_IOS_DEV"],
+      groups: "qa-team"
+    )
+  end
+
+  desc "Deploy Production to TestFlight"
+  lane :prod do
+    # 1. Sync Signing (AppStore)
+    match(type: "appstore", app_identifier: "com.example.app", readonly: is_ci)
+
+    # 2. Build IPA (Scheme: Prod)
+    build_app(
+      scheme: "Prod",
+      export_method: "app-store"
+    )
+
+    # 3. Upload to TestFlight
+    upload_to_testflight(
+      skip_waiting_for_build_processing: true
+    )
+  end
+end
+```
+
+## Setup Checklist
+
+1. **Google Play Key**: Define `PLAY_STORE_JSON_KEY_FILE`.
+2. **Match Repo**: Ensure `git_url` in `Matchfile` points to your private cert repo.
+3. **Firebase CLI**: Ensure firebase-tools is installed or the plugin authenticated via `FIREBASE_TOKEN`.

package/rules/flutter/cicd/references/github-actions.md

@@ -0,0 +1,59 @@
+# GitHub Actions Workflow
+
+This workflow builds the application, runs tests, and analyzes code.
+
+## `flutter-ci.yml`
+
+```yaml
+name: Flutter CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: '17'
+
+      - name: Set up Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          channel: 'stable'
+          cache: true
+
+      - name: Install dependencies
+        run: flutter pub get
+
+      - name: Format check
+        run: dart format --output=none --set-exit-if-changed .
+
+      - name: Analyze
+        run: flutter analyze
+
+      - name: Run tests
+        run: flutter test --coverage
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage/lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+```
+
+## Fastlane (Optional)
+
+For automated store deployment, consider integrating `fastlane` into a separate `deploy` job that runs only on `push` to `main`.

package/rules/flutter/dependency-injection/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: Flutter Dependency Injection (Injectable)
+description: Standards for automated service locator setup using injectable and get_it.
+metadata:
+  labels: [dependency-injection, injectable, get_it]
+  triggers:
+    files: ['**/injection.dart', '**/locator.dart']
+    keywords: [GetIt, injectable, singleton, module, lazySingleton, factory]
+---
+
+# Dependency Injection
+
+## **Priority: P1 (HIGH)**
+
+Automated class dependency management using `get_it` and `injectable`.
+
+## Structure
+
+```text
+core/injection/
+├── injection.dart # Initialization & setup
+└── modules/ # Third-party dependency modules (Dio, Storage)
+```
+
+## Implementation Guidelines
+
+- **Automated Registration**: Use `@injectable` annotations; avoid manual registry calls.
+- **@LazySingleton**: Default for repositories, services, and data sources (init on demand).
+- **@injectable (Factory)**: Default for BLoCs to ensure state resets on every request.
+- **Abstract Injection**: Always register implementations as abstract interfaces (`as: IService`).
+- **Modules**: Use `@module` for registering third-party instances (e.g., `Dio`, `SharedPreferences`).
+- **Constructor Injection**: Use mandatory constructor parameters; `injectable` resolves them.
+- **Test Mocks**: Swap implementations in `setUp` using `getIt.registerLazySingleton` for testing.
+
+## Reference & Examples
+
+For module configuration and initialization templates:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+layer-based-clean-architecture | testing

package/rules/flutter/dependency-injection/references/REFERENCE.md

@@ -0,0 +1,15 @@
+# Dependency Injection Reference
+
+Implementation patterns for `injectable` and `get_it` in massive Flutter projects.
+
+## References
+
+- [**Injection Modules**](modules.md) - Registering third-party libraries (Dio, Hive).
+- [**Production Initialization**](initialization.md) - Wiring everything in `main.dart`.
+- [**Testing Mocks**](testing-mocks.md) - How to swap services during unit tests.
+
+## **Quick Registration Guide**
+
+- **@injectable**: Use for BLoCs (New instance every time).
+- **@LazySingleton**: Use for Repositories and DataSources (Global, lazy-init).
+- **@singleton**: Use only for truly shared resources (init on startup).

package/rules/flutter/dependency-injection/references/modules.md

@@ -0,0 +1,37 @@
+# Third-party Dependency Modules
+
+Since you cannot annotate third-party classes (like `Dio` or `SharedPreferences`) directly, use a `@module`.
+
+## **Example: Network & Storage Module**
+
+```dart
+import 'package:injectable/injectable.dart';
+import 'package:dio/dio.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+@module
+abstract class NetworkingModule {
+  @lazySingleton
+  Dio get dio => Dio(BaseOptions(baseUrl: 'https://api.example.com'));
+
+  @preResolve // Waits for this before finishing injection setup
+  Future<SharedPreferences> get prefs => SharedPreferences.getInstance();
+}
+```
+
+## **Named Injection**
+
+Use for multiple instances of the same type:
+
+```dart
+@module
+abstract class ServiceModule {
+  @Named("AuthDio")
+  Dio get authDio => Dio();
+
+  @Named("PublicDio")
+  Dio get publicDio => Dio();
+}
+
+// Consumption: Repo(@Named("AuthDio") Dio dio)
+```

package/rules/flutter/error-handling/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: Flutter Error Handling
+description: Functional error handling using Dartz and Either.
+metadata:
+  labels: [error-handling, dartz, functional]
+  triggers:
+    files: ['lib/domain/**', 'lib/infrastructure/**']
+    keywords: [Either, fold, Left, Right, Failure, dartz]
+---
+
+# Error Handling
+
+## **Priority: P1 (HIGH)**
+
+Standardized functional error handling using `dartz` and `freezed` failures.
+
+## Implementation Guidelines
+
+- **Either Pattern**: Return `Either<Failure, T>` from repositories. No exceptions in UI/BLoC.
+- **Failures**: Define domain-specific failures using `@freezed` unions.
+- **Mapping**: Infrastructure catches `Exception` and returns `Left(Failure)`.
+- **Consumption**: Use `.fold(failure, success)` in BLoC to emit corresponding states.
+- **Typed Errors**: Use `left(Failure())` and `right(Value())` from `Dartz`.
+
+## Reference & Examples
+
+For Failure definitions and API error mapping:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+layer-based-clean-architecture | bloc-state-management

package/rules/flutter/error-handling/references/REFERENCE.md

@@ -0,0 +1,19 @@
+# Error Handling Reference
+
+Detailed patterns for functional error management in Flutter.
+
+## References
+
+- [**Error Mapping**](error-mapping.md) - Mapping Dio/Network exceptions to Failures.
+- [**Consumption Patterns**](consumption.md) - Using `.fold()` in Clean Architecture.
+
+## **Quick Syntax**
+
+```dart
+// Result handling in BLoC
+final failureOrData = await repository.getData();
+emit(failureOrData.fold(
+  (failure) => State.error(failure),
+  (data) => State.success(data),
+));
+```

package/rules/flutter/error-handling/references/error-mapping.md

@@ -0,0 +1,31 @@
+# Functional Failure Patterns
+
+## **Global Failures (@freezed)**
+
+```dart
+@freezed
+class ApiFailure with _$ApiFailure {
+  const factory ApiFailure.serverError() = _ServerError;
+  const factory ApiFailure.networkError() = _NetworkError;
+  const factory ApiFailure.unauthenticated() = _Unauthenticated;
+  const factory ApiFailure.badRequest(String message) = _BadRequest;
+}
+```
+
+## **Infrastructure Mapper**
+
+```dart
+extension DioErrorX on DioException {
+  ApiFailure toFailure() {
+    switch (type) {
+      case DioExceptionType.connectionTimeout:
+        return const ApiFailure.networkError();
+      case DioExceptionType.badResponse:
+        if (response?.statusCode == 401) return const ApiFailure.unauthenticated();
+        return const ApiFailure.serverError();
+      default:
+        return const ApiFailure.serverError();
+    }
+  }
+}
+```

package/rules/flutter/feature-based-clean-architecture/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: Flutter Feature-Based Clean Architecture
+description: Standards for organizing code by feature at the root level to improve scalability and maintainability.
+metadata:
+  labels: [architecture, clean-architecture, feature-driven, ddd, modularity]
+  triggers:
+    files: ['lib/features/**']
+    keywords: [feature, domain, infrastructure, application, presentation, modular]
+---
+
+# Feature-Based Clean Architecture
+
+## **Priority: P0 (CRITICAL)**
+
+Standard for modular Clean Architecture organized by business features in `lib/features/`.
+
+## Structure
+
+```text
+lib/
+├── features/ <feature_name>/
+│   ├── domain/ # Business Logic (Pure Dart): entities, interfaces, use_cases
+│   ├── data/ # Implementation: data_sources, dtos, repositories
+│   └── presentation/ # UI & State: blocs, pages, widgets
+├── core/ # Shared infrastructure & utilities
+└── shared/ # Common UI components & shared entities
+```
+
+## Implementation Guidelines
+
+- **Feature Encapsulation**: Keep logic, models, and UI internal to the feature directory.
+- **Strict Layering**: Maintain 3-layer separation (Domain/Data/Presentation) within each feature.
+- **Dependency Rule**: `Presentation -> Domain <- Data`. Domain must have zero external dependencies.
+- **Cross-Feature Communication**: Features only depend on the **Domain** layer of other features.
+- **Flat features**: Keep `lib/features/` flat; avoid nested features.
+- **No DTO Leakage**: Never expose DTOs or Data Sources to UI or other features; return Domain Entities.
+- **Shared logic**: Move cross-cutting concerns to `lib/shared/` or `lib/core/`.
+
+## Reference & Examples
+
+For feature folder blueprints and cross-layer dependency templates:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+layer-based-clean-architecture | retrofit-networking | go-router-navigation | bloc-state-management | dependency-injection

package/rules/flutter/feature-based-clean-architecture/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# Feature-Based Architecture Reference
+
+Detailed examples for organizing large-scale Flutter apps by business domain.
+
+## References
+
+- [**Standard Folder Structure**](folder-structure.md) - Deep dive into feature-level directory nesting.
+- [**Shared vs Core**](shared-core.md) - When to put code in `lib/core` versus `lib/shared`.
+- [**Modular Injection**](modular-injection.md) - How to register dependencies per feature.
+
+## **Quick Implementation Rule**
+
+- Never import from `lib/features/x/data/` or `lib/features/x/presentation/` from outside `feature/x`.
+- Only `lib/features/x/domain/` is "public" to other features.

package/rules/flutter/feature-based-clean-architecture/references/folder-structure.md

@@ -0,0 +1,36 @@
+# Feature Folder Structure
+
+A complete blueprint for a single feature directory (e.g., `lib/features/authentication/`).
+
+```text
+lib/features/authentication/
+├── domain/
+│   ├── entities/
+│   │   └── auth_user.dart
+│   ├── repositories/
+│   │   └── i_auth_repository.dart
+│   └── use_cases/
+│       └── login_use_case.dart
+├── data/
+│   ├── data_sources/
+│   │   ├── auth_remote_data_source.dart
+│   │   └── auth_local_data_source.dart
+│   ├── dtos/
+│   │   └── user_dto.dart
+│   └── repositories/
+│       └── auth_repository_impl.dart
+└── presentation/
+    ├── blocs/
+    │   └── auth/
+    ├── pages/
+    │   ├── login_page.dart
+    │   └── profile_page.dart
+    └── widgets/
+        └── auth_form.dart
+```
+
+## **Key Constraints**
+
+1. **Barrel Files**: Use `authentication.dart` at the feature root to export ONLY the domain layer.
+2. **Sub-directories**: Do not create more levels than shown above unless the feature has 20+ files.
+3. **Mappers**: Should be kept in the `data/` layer, typically as extensions on DTOs.

package/rules/flutter/getx-navigation/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: Flutter GetX Navigation
+description: Context-less navigation, named routes, and middleware using GetX.
+metadata:
+  labels: [navigation, getx, routing, middleware]
+  triggers:
+    files: ['**/app_pages.dart', '**/app_routes.dart']
+    keywords: [GetPage, Get.to, Get.off, Get.offAll, Get.toNamed, GetMiddleware]
+---
+
+# GetX Navigation
+
+## **Priority: P0 (CRITICAL)**
+
+Decoupled navigation system allowing UI transitions without `BuildContext`.
+
+## Implementation Guidelines
+
+- **Prefer Named Routes**: Use `Get.toNamed('/path')` for better maintainability. Define routes in a centralized `AppPages` class.
+- **No Context Navigation**: Leverage `Get.to()`, `Get.back()`, etc., directly from controllers.
+- **Navigation Methods**:
+  - `Get.to()`: Navigate to next screen.
+  - `Get.off()`: Navigate and replace current screen (e.g., Splash -> Home).
+  - `Get.offAll()`: Clear stack and navigate (e.g., Logout -> Login).
+  - `Get.back()`: Close current screen, dialog, or bottom sheet.
+- **Bindings Everywhere**: Always link routes with `Bindings` to manage controller lifecycles.
+- **Middleware**: Use `GetMiddleware` for route guards (Auth, Permissions) instead of logic inside views.
+
+## Code Example
+
+```dart
+// Route Definition
+static final routes = [
+  GetPage(
+    name: _Paths.HOME,
+    page: () => HomeView(),
+    binding: HomeBinding(),
+    middlewares: [AuthMiddleware()],
+  ),
+];
+
+// Usage in Controller
+void logout() {
+  _authService.clear();
+  Get.offAllNamed(Routes.LOGIN);
+}
+
+// Route Guard
+class AuthMiddleware extends GetMiddleware {
+  @override
+  RouteSettings? redirect(String? route) {
+    return isAuthenticated ? null : RouteSettings(name: Routes.LOGIN);
+  }
+}
+```
+
+## Anti-Patterns
+
+- **Mixing Context and GetX**: Do not use `Navigator.of(context)` when GetX is the primary router.
+- **Hardcoded Strings**: Always use a `Routes` constant class for names.
+- **Dialogs without GetX**: Use `Get.dialog()` and `Get.snackbar()` for consistency.
+
+## Reference & Examples
+
+For centralized route configuration and middleware guards:
+See [references/app-pages.md](references/app-pages.md) and [references/middleware-example.md](references/middleware-example.md).
+
+## Related Topics
+
+getx-state-management | feature-based-clean-architecture

package/rules/flutter/getx-navigation/references/app-pages.md

@@ -0,0 +1,40 @@
+# Centralized Route Management
+
+Organizing routes in a single location for scalability.
+
+```dart
+// app_routes.dart
+abstract class Routes {
+  static const HOME = _Paths.HOME;
+  static const LOGIN = _Paths.LOGIN;
+}
+
+abstract class _Paths {
+  static const HOME = '/home';
+  static const LOGIN = '/login';
+}
+
+// app_pages.dart
+class AppPages {
+  static const INITIAL = Routes.LOGIN;
+
+  static final routes = [
+    GetPage(
+      name: _Paths.HOME,
+      page: () => HomeView(),
+      binding: HomeBinding(),
+    ),
+    GetPage(
+      name: _Paths.LOGIN,
+      page: () => LoginView(),
+      binding: LoginBinding(),
+    ),
+  ];
+}
+
+// main.dart
+GetMaterialApp(
+  initialRoute: AppPages.INITIAL,
+  getPages: AppPages.routes,
+)
+```

package/rules/flutter/getx-navigation/references/middleware-example.md

@@ -0,0 +1,29 @@
+# Route Middleware (Guards)
+
+Use middleware to protect routes from unauthorized access or handle redirections.
+
+```dart
+class AuthMiddleware extends GetMiddleware {
+  @override
+  int? get priority => 1;
+
+  @override
+  RouteSettings? redirect(String? route) {
+    bool isAuthenticated = AuthService.to.isLoggedInValue;
+
+    if (isAuthenticated) {
+      return null; // Continue to target route
+    } else {
+      // Redirect to login if user is not authenticated
+      return const RouteSettings(name: Routes.LOGIN);
+    }
+  }
+}
+
+// Usage in AppPages
+GetPage(
+  name: Routes.PROFILE,
+  page: () => ProfileView(),
+  middlewares: [AuthMiddleware()],
+)
+```