@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/flutter/auto-route-navigation/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: Flutter AutoRoute Navigation
+description: Typed routing, nested routes, and guards using auto_route.
+metadata:
+  labels: [navigation, auto-route, routing]
+  triggers:
+    files: ['**/router.dart', '**/app_router.dart']
+    keywords: [AutoRoute, AutoRouter, router, guards, navigate, push]
+---
+
+# AutoRoute Navigation
+
+## **Priority: P1 (HIGH)**
+
+Type-safe routing system with code generation using `auto_route`.
+
+## Structure
+
+```text
+core/router/
+├── app_router.dart # Router configuration
+└── app_router.gr.dart # Generated routes
+```
+
+## Implementation Guidelines
+
+- **@RoutePage**: Annotate all screen/page widgets with `@RoutePage()`.
+- **Router Config**: Extend `_$AppRouter` and annotate with `@AutoRouterConfig`.
+- **Typed Navigation**: Use generated route classes (e.g., `HomeRoute()`). Never use strings.
+- **Nested Routes & Tabs**: Use `children` in `AutoRoute` for tabs. When navigating to a route with nested tabs, use the `children` parameter to define the initial active sub-route (e.g., `context.navigateTo(OrdersTabRoute(children: [ViewByOrdersPageRoute()]))`).
+- **Guards**: Implement `AutoRouteGuard` for authentication/authorization logic.
+
+- **Parameters**: Constructors of `@RoutePage` widgets automatically become route parameters.
+- **Declarative**: Prefer `context.pushRoute()` or `context.replaceRoute()`.
+
+## Reference & Examples
+
+For full Router configuration and Auth Guard implementation:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+go-router-navigation | layer-based-clean-architecture

package/rules/flutter/auto-route-navigation/references/REFERENCE.md

@@ -0,0 +1,19 @@
+# AutoRoute Routing Reference
+
+Detailed examples for implementing a scalable, type-safe routing system in Flutter.
+
+## References
+
+- [**AppRouter Configuration**](router-config.md) - Standard setup with `@AutoRouterConfig`.
+- [**Auth Guards**](guards.md) - Protecting routes based on authentication state.
+- [**Nested Routes & Tabs**](nested-routes.md) - Implementation for bottom navigation bars or sub-flows.
+
+## **Quick Navigation Command**
+
+```dart
+// Navigating to a page with parameters
+context.pushRoute(ProfileRoute(userId: '123'));
+
+// Popping and returning a value
+context.maybePop(true);
+```

package/rules/flutter/auto-route-navigation/references/router-config.md

@@ -0,0 +1,62 @@
+# AppRouter Configuration
+
+Standard setup for `auto_route` to ensure code generation and type-safety.
+
+## **Router File (`app_router.dart`)**
+
+```dart
+import 'package:auto_route/auto_route.dart';
+import 'app_router.gr.dart'; // Inherited generated classes
+
+@AutoRouterConfig(replaceInRouteName: 'Page|Screen,Route')
+class AppRouter extends _$AppRouter {
+  @override
+  List<AutoRoute> get routes => [
+    // 1. Initial Route
+    AutoRoute(page: SplashRoute.page, initial: true),
+    
+    // 2. Protected Routes (with Guards)
+    AutoRoute(
+      page: DashboardRoute.page, 
+      guards: [AuthGuard()],
+    ),
+    
+    // 3. Nested Routes (Tabs)
+    AutoRoute(
+      page: HomeTabsRoute.page,
+      children: [
+        AutoRoute(page: PostsRoute.page),
+        AutoRoute(page: SettingsRoute.page),
+      ],
+    ),
+  ];
+}
+```
+
+## **Dynamic Tab Initialization**
+
+If you need to navigate to a tabbed route and set a specific initial tab based on logic:
+
+```dart
+context.navigateTo(
+  OrdersTabRoute(
+    children: params.tab == OrderTab.orders()
+        ? [const ViewByOrdersPageRoute()]
+        : [const ViewByItemsPageRoute()],
+  ),
+);
+```
+
+## **Typed Parameters**
+
+When you define a Screen with a constructor, `auto_route` generates matching parameters:
+
+```dart
+@RoutePage()
+class UserProfilePage extends StatelessWidget {
+  final String userId;
+  const UserProfilePage({required this.userId});
+  
+  // Navigation: context.pushRoute(UserProfileRoute(userId: '123'));
+}
+```

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

@@ -0,0 +1,64 @@
+---
+name: Flutter BLoC State Management
+description: Standards for predictable state management using flutter_bloc, freezed, and equatable.
+metadata:
+  labels: [state-management, bloc, cubit, freezed, equatable]
+  triggers:
+    files: ['**_bloc.dart', '**_cubit.dart', '**_state.dart', '**_event.dart']
+    keywords:
+      [
+        BlocProvider,
+        BlocBuilder,
+        BlocListener,
+        Cubit,
+        Emitter,
+        transformer,
+        Equatable,
+      ]
+---
+
+# BLoC State Management
+
+## **Priority: P0 (CRITICAL)**
+
+Predictable state management separating business logic from UI using `bloc`, `freezed`, or `equatable`.
+
+## Structure
+
+```text
+presentation/blocs/
+├── auth/
+│   ├── auth_bloc.dart
+│   ├── auth_event.dart # (@freezed or Equatable)
+│   └── auth_state.dart # (@freezed or Equatable)
+```
+
+## Implementation Guidelines
+
+- **States & Events**: Default to `@freezed` (Priority). Use `Equatable` if the library is present in `pubspec.yaml`.
+  - **freezed**: Use for union states (initial, loading, success) and automatic `copyWith`.
+  - **Equatable**: Apply if code generation (build_runner) is avoided or `equatable` is the only comparison library in `pubspec.yaml`.
+  - Choose strategy:
+    - **Union State**: Exclusive UI phases (loading vs data).
+    - **Property-based State**: Complex forms (Option<$Either>, flags).
+- **State Properties**: Use enums, sealed classes, or `Status` objects.
+- **Error Handling**: Use `Failure` objects; avoid throwing exceptions.
+- **Async Data**: Use `emit.forEach` or `emit.onEach` for streams.
+- **Concurrency**: Use `transformer` (restartable, droppable) for event debouncing.
+- **Testing**: Use `blocTest` for state transition verification.
+- **Injection**: Register BLoCs as `@injectable` (Factory).
+
+## Anti-Patterns
+
+- **No Manual Emit**: Do not call `emit()` inside `Future.then`; always use `await` or `emit.forEach`.
+- **No UI Logic**: Do not perform calculations or data formatting inside `BlocBuilder`.
+- **No Cross-Bloc Reference**: Do not pass a BLoC instance into another BLoC; use streams or the UI layer to coordinate.
+
+## Reference & Examples
+
+For full BLoC/Cubit implementations and concurrency patterns:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+feature-based-clean-architecture | dependency-injection

package/rules/flutter/bloc-state-management/references/REFERENCE.md

@@ -0,0 +1,20 @@
+# BLoC State Management Reference
+
+Detailed patterns for implementing BLoC/Cubit in production.
+
+## References
+
+- [**Full Auth BLoC (Union State)**](auth-bloc-example.md) - Best for distinct app phases.
+- [**Property-Based State (Forms)**](property-based-state.md) - Best for persistent data and forms.
+- [**Equatable Usage**](equatable-usage.md) - Lightweight alternative to Freezed.
+- [**Cubit Minimal**](cubit-minimal.md) - Simple state management without events.
+
+## **Concurrency Transformer**
+
+```dart
+// Restartable prevents multiple simultaneous requests
+on<SearchEvent>(
+  _onSearch,
+  transformer: restartable(),
+);
+```

package/rules/flutter/bloc-state-management/references/auth-bloc-example.md

@@ -0,0 +1,52 @@
+# Auth BLoC Full Implementation
+
+## **Events (@freezed)**
+
+```dart
+@freezed
+class AuthEvent with _$AuthEvent {
+  const factory AuthEvent.started() = _Started;
+  const factory AuthEvent.loginSubmitted(String email, String password) = _LoginSubmitted;
+  const factory AuthEvent.logoutPressed() = _LogoutPressed;
+}
+```
+
+## **States (@freezed)**
+
+```dart
+@freezed
+class AuthState with _$AuthState {
+  const factory AuthState.initial() = _Initial;
+  const factory AuthState.loading() = _Loading;
+  const factory AuthState.authenticated(User user) = _Authenticated;
+  const factory AuthState.unauthenticated() = _Unauthenticated;
+  const factory AuthState.error(String message) = _Error;
+}
+```
+
+## **BLoC Implementation**
+
+```dart
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  final IAuthRepository _repository;
+
+  AuthBloc(this._repository) : super(const AuthState.initial()) {
+    on<_LoginSubmitted>(_onLogin);
+    on<_LogoutPressed>(_onLogout);
+  }
+
+  Future<void> _onLogin(_LoginSubmitted event, Emitter<AuthState> emit) async {
+    emit(const AuthState.loading());
+    final result = await _repository.login(event.email, event.password);
+    result.fold(
+      (failure) => emit(AuthState.error(failure.message)),
+      (user) => emit(AuthState.authenticated(user)),
+    );
+  }
+
+  Future<void> _onLogout(_LogoutPressed event, Emitter<AuthState> emit) async {
+    await _repository.logout();
+    emit(const AuthState.unauthenticated());
+  }
+}
+```

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.