@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/flutter/bloc-state-management/references/equatable-usage.md

@@ -0,0 +1,56 @@
+# BLoC with Equatable
+
+Use `Equatable` as a lightweight alternative to `freezed` for state and event comparison.
+
+```dart
+import 'package:equatable/equatable.dart';
+
+// --- Event ---
+abstract class CounterEvent extends Equatable {
+  const CounterEvent();
+
+  @override
+  List<Object?> get props => [];
+}
+
+class IncrementPressed extends CounterEvent {
+  final int amount;
+  const IncrementPressed(this.amount);
+
+  @override
+  List<Object?> get props => [amount];
+}
+
+// --- State ---
+class CounterState extends Equatable {
+  final int count;
+  final bool isSubmitting;
+
+  const CounterState({
+    required this.count,
+    this.isSubmitting = false,
+  });
+
+  CounterState copyWith({
+    int? count,
+    bool? isSubmitting,
+  }) {
+    return CounterState(
+      count: count ?? this.count,
+      isSubmitting: isSubmitting ?? this.isSubmitting,
+    );
+  }
+
+  @override
+  List<Object?> get props => [count, isSubmitting];
+}
+```
+
+## When to use Equatable over Freezed
+
+- **Library Presence**: Primary choice when `equatable` is present in `pubspec.yaml` and code generation is not desired.
+- **Minimal Dependencies**: When you want to avoid code generation (build_runner).
+- **Simple Comparison**: When states don't have many properties or union cases.
+- **Legacy Projects**: maintaining older codebases that already utilize Equatable.
+
+> **Note**: For complex applications, `@freezed` is still prioritized due to exhaustive switch cases and built-in `copyWith` safety.

package/rules/flutter/bloc-state-management/references/property-based-state.md

@@ -0,0 +1,68 @@
+# Property-Based State Pattern (Forms & Complex Data)
+
+This pattern uses a single data class to maintain the entire state of a feature. It is the preferred approach for forms, multi-step wizards, and screens with persistent filtering.
+
+## **Pattern Implementation**
+
+```dart
+@freezed
+class NewRequestState with _$NewRequestState {
+  const factory NewRequestState({
+    // 1. Feature Data
+    required List<ReturnMaterial> selectedItems,
+    required String returnReference,
+    required SalesOrg salesOrg,
+    
+    // 2. UI Flags
+    required bool showErrorMessages,
+    required bool isSubmitting,
+    
+    // 3. Functional Communication (Failure/Success)
+    // - None: Operation not started
+    // - Some(Left): Operation failed
+    // - Some(Right): Operation succeeded
+    required Option<Either<ApiFailure, String>> failureOrSuccessOption,
+  }) = _NewRequestState;
+
+  factory NewRequestState.initial() => NewRequestState(
+    selectedItems: [],
+    returnReference: '',
+    salesOrg: SalesOrg.empty(),
+    showErrorMessages: false,
+    isSubmitting: false,
+    failureOrSuccessOption: none(),
+  );
+}
+```
+
+## **When to use this vs. Union States?**
+
+### **1. Use Property-Based (Flat) State when:**
+
+- **Preservation is key**: You are building a **Form** or a **wizard** where users enter data. If you used a Union `Loading` state, the user's current input would be lost unless passed forward manually.
+- **Overlapping UI**: You need to show a loading indicator *on top* of existing data (e.g., a "loading" overlay on a list).
+- **Complex Filtering**: Multiple filters (search, date, category) that all need to persist.
+
+### **2. Use Union States (Sealed Classes) when:**
+
+- **Exclusive Phases**: The screen looks completely different in each state (e.g., Login Screen -> Loading Spinner -> Dashboard).
+- **Simple Lifecycle**: Fetch data once -> Display it. No complex user input involved.
+- **Type Safety**: The UI *must* have data in the `Success` state and *must not* have it in `Initial`.
+
+## **UI Consumption (Option/Either)**
+
+```dart
+BlocListener<NewRequestBloc, NewRequestState>(
+  listenWhen: (p, c) => p.failureOrSuccessOption != c.failureOrSuccessOption,
+  listener: (context, state) {
+    state.failureOrSuccessOption.fold(
+      () => null, // Do nothing
+      (either) => either.fold(
+        (failure) => showErrorSnackbar(failure.message),
+        (success) => navigateToSummary(),
+      ),
+    );
+  },
+  child: ...,
+)
+```

package/rules/flutter/bloc.rule.md

@@ -0,0 +1,76 @@
+---
+id: flutter-bloc
+version: 1.0.0
+triggers: [bloc, state management, flutter bloc]
+---
+
+# BLoC Pattern
+
+State management using flutter_bloc package.
+
+## Structure
+
+```
+lib/
+├── blocs/
+│   ├── auth/
+│   │   ├── auth_bloc.dart
+│   │   ├── auth_event.dart
+│   │   └── auth_state.dart
+```
+
+## Event Naming
+
+Events as actions in past tense:
+- `AuthLoginRequested`
+- `AuthLogoutRequested`
+- `UserProfileUpdated`
+
+## State Patterns
+
+Use sealed classes (Dart 3+):
+
+```dart
+sealed class AuthState {}
+
+final class AuthInitial extends AuthState {}
+
+final class AuthLoading extends AuthState {}
+
+final class AuthAuthenticated extends AuthState {
+  final User user;
+  AuthAuthenticated(this.user);
+}
+
+final class AuthError extends AuthState {
+  final String message;
+  AuthError(this.message);
+}
+```
+
+## BlocBuilder Usage
+
+```dart
+BlocBuilder<AuthBloc, AuthState>(
+  builder: (context, state) => switch (state) {
+    AuthInitial() => const LoginScreen(),
+    AuthLoading() => const LoadingIndicator(),
+    AuthAuthenticated(user: final user) => HomeScreen(user: user),
+    AuthError(message: final msg) => ErrorWidget(message: msg),
+  },
+)
+```
+
+## Testing
+
+```dart
+blocTest<AuthBloc, AuthState>(
+  'emits [AuthLoading, AuthAuthenticated] on successful login',
+  build: () => AuthBloc(authRepo),
+  act: (bloc) => bloc.add(AuthLoginRequested(email, password)),
+  expect: () => [
+    isA<AuthLoading>(),
+    isA<AuthAuthenticated>(),
+  ],
+);
+```

package/rules/flutter/cicd/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: Flutter CI/CD
+description: Continuous Integration and Deployment standards for Flutter apps.
+metadata:
+  labels: [cicd, github-actions, automation, codemagic, fastlane]
+  triggers:
+    files:
+      [
+        '.github/workflows/**.yml',
+        'fastlane/**',
+        'android/fastlane/**',
+        'ios/fastlane/**',
+      ]
+    keywords: [ci, cd, pipeline, build, deploy, release, action, workflow]
+---
+
+# CI/CD Standards
+
+## **Priority: P1 (HIGH)**
+
+Automates code quality checks, testing, and deployment to prevent regressions and accelerate delivery.
+
+## Core Pipeline Steps
+
+1. **Environment Setup**: Use stable Flutter channel. Cache dependencies (pub, gradle, cocoapods).
+2. **Static Analysis**: Enforce `flutter analyze` and `dart format`. Fail on any warning in strict mode.
+3. **Testing**: Run unit, widget, and integration tests. Upload coverage reports (e.g., Codecov).
+4. **Build**:
+   - **Android**: Build App Bundle (`.aab`) for Play Store.
+   - **iOS**: Sign and build `.ipa` (requires macOS runner).
+5. **Deployment** (CD): Automated upload to TestFlight/Play Console using standard tools (Fastlane, Codemagic).
+
+## Best Practices
+
+- **Timeout Limits**: Always set `timeout-minutes` (e.g., 30m) to save costs on hung jobs.
+- **Fail Fast**: Run Analyze/Format _before_ Tests/Builds.
+- **Secrets**: Never commit keys. Use GitHub Secrets or secure vaults for `keystore.jks` and `.p8` certs.
+- **Versioning**: Automate version bumping based on git tags or semantic version scripts.
+
+## Reference
+
+- [**GitHub Actions Template**](references/github-actions.md) - Standard workflow file.
+- [**Advanced Large-Scale Workflow**](references/advanced-workflow.md) - Parallel jobs, Caching, Strict Mode.
+- [**Fastlane Standards**](references/fastlane.md) - Automated Signing & Deployment.
+
+## Related Topics
+
+flutter/testing | dart/tooling

package/rules/flutter/cicd/references/advanced-workflow.md

@@ -0,0 +1,66 @@
+# Advanced Large-Scale CI/CD
+
+For large projects, a linear workflow is too slow. Use parallel jobs and aggressive caching.
+
+## Optimized Workflow (`main.yml`)
+
+Split your pipeline into parallel stages to fail fast.
+
+```yaml
+name: Production CI
+
+on: [push, pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # 1. SETUP: Install & Cache Dependencies
+  # This job prepares the environment so others can just reuse the cache.
+  setup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: 'stable'
+          cache: true
+      - name: Install Dependencies
+        run: flutter pub get
+
+  # 2. QUALITY: Static Analysis & Formatting (Runs parallel to Test)
+  quality:
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+      - run: flutter pub get
+      - name: Verify Formatting
+        run: dart format --output=none --set-exit-if-changed .
+      - name: Static Analysis
+        run: flutter analyze --fatal-infos
+
+  # 3. TEST: Unit & Widget Tests
+  test:
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+      - run: flutter pub get
+      - name: Run Tests
+        # Usage of concurrency to speed up execution
+        run: flutter test --coverage --concurrency=4
+      - name: Upload Coverage
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+```
+
+## Key Optimizations
+
+1. **Concurrency Group**: `cancel-in-progress: true` stops old runs when new code is pushed to the same PR, saving minutes.
+2. **Parallel Jobs**: `quality` and `test` trigger at the same time. If formatting fails, you don't wait for tests to finish.
+3. **Fatal Infos**: Enforce higher quality by treating info-level logic hints as failures.

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();
+    }
+  }
+}
+```