@ngxtm/devkit 3.3.0 → 3.4.1

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()],
+)
+```

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

@@ -0,0 +1,76 @@
+---
+name: Flutter GetX State Management
+description: Simple and powerful reactive state management using GetX.
+metadata:
+  labels: [state-management, getx, controller, reactive]
+  triggers:
+    files: ['**_controller.dart', '**/bindings/*.dart']
+    keywords:
+      [GetxController, Obx, GetBuilder, .obs, Get.put, Get.find, Get.lazyPut]
+---
+
+# GetX State Management
+
+## **Priority: P0 (CRITICAL)**
+
+Reactive and lightweight state management separating business logic from UI using `GetX`.
+
+## Structure
+
+```text
+lib/app/modules/home/
+├── controllers/
+│   └── home_controller.dart
+├── bindings/
+│   └── home_binding.dart
+└── views/
+    └── home_view.dart
+```
+
+## Implementation Guidelines
+
+- **Controllers**: Extend `GetxController`. Store logic and state variables here.
+- **Reactivity**:
+  - Use `.obs` for observable variables (e.g., `final count = 0.obs;`).
+  - Wrap UI in `Obx(() => ...)` to listen for changes.
+  - For simple state, use `update()` in controller and `GetBuilder` in UI.
+- **Dependency Injection**:
+  - **Bindings**: Use `Bindings` class to decouple DI from UI.
+  - **Lazy Load**: Prefer `Get.lazyPut(() => Controller())` in Bindings.
+  - **Lifecycle**: Let GetX handle disposal. Avoid `permanent: true`.
+- **Hooks**: Use `onInit()`, `onReady()`, `onClose()` instead of `initState`/`dispose`.
+- **Architecture**: Use `get_cli` for modular MVVM (data, models, modules).
+
+## Anti-Patterns
+
+- **Ctx in Logic**: Pass no `BuildContext` to controllers.
+- **Inline DI**: Avoid `Get.put()` in widgets; use Bindings + `Get.find`.
+- **Fat Views**: Keep views pure UI; delegate all logic to controller.
+
+## Code Example
+
+```dart
+class UserController extends GetxController {
+  final name = "User".obs;
+  void updateName(String val) => name.value = val;
+}
+
+class UserView extends GetView<UserController> {
+  @override
+  Widget build(ctx) => Scaffold(
+    body: Obx(() => Text(controller.name.value)),
+    floatingActionButton: FloatingActionButton(
+      onPressed: () => controller.updateName("New"),
+    ),
+  );
+}
+```
+
+## Reference & Examples
+
+For DI Bindings and Reactive patterns:
+See [references/binding-example.md](references/binding-example.md) and [references/reactive-vs-simple.md](references/reactive-vs-simple.md).
+
+## Related Topics
+
+getx-navigation | feature-based-clean-architecture | dependency-injection

package/rules/flutter/getx-state-management/references/binding-example.md

@@ -0,0 +1,32 @@
+# GetX Binding Example
+
+Using Bindings ensures that dependencies are only in memory when the associated route is active.
+
+```dart
+// 1. Define the Binding
+class HomeBinding extends Bindings {
+  @override
+  void dependencies() {
+    // lazyPut only initializes the controller when it's first used (Get.find)
+    Get.lazyPut<HomeController>(() => HomeController());
+    Get.lazyPut<HomeRepository>(() => HomeRepositoryImpl());
+  }
+}
+
+// 2. Attach to Route
+GetPage(
+  name: '/home',
+  page: () => HomeView(),
+  binding: HomeBinding(),
+)
+
+// 3. Use in View via GetView (automatically finds the controller)
+class HomeView extends GetView<HomeController> {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Obx(() => Text(controller.title.value)),
+    );
+  }
+}
+```

package/rules/flutter/getx-state-management/references/reactive-vs-simple.md

@@ -0,0 +1,39 @@
+# Reactive vs. Simple State Management
+
+GetX provides two ways to manage state. Choose based on complexity and performance needs.
+
+## 1. Reactive (.obs + Obx)
+
+Best for: Highly interactive UIs, streams, and granular updates.
+
+```dart
+class UserController extends GetxController {
+  final name = "Guest".obs;
+  final age = 18.obs;
+
+  void updateName(String newName) => name.value = newName;
+}
+
+// UI
+Obx(() => Text(controller.name.value));
+```
+
+### 2. Simple state management
+
+Best for: Large objects, low-frequency updates, or reducing memory overhead of many streams.
+
+```dart
+class UserController extends GetxController {
+  String name = "Guest";
+
+  void updateName(String newName) {
+    name = newName;
+    update(); // Manually notify listeners
+  }
+}
+
+// UI
+GetBuilder<UserController>(
+  builder: (controller) => Text(controller.name),
+);
+```

package/rules/flutter/go-router-navigation/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: Flutter GoRouter Navigation
+description: Typed routes, route state, and redirection using go_router.
+metadata:
+  labels: [navigation, go-router, routing]
+  triggers:
+    files: ['**/router.dart', '**/app_router.dart']
+    keywords: [GoRouter, GoRoute, StatefulShellRoute, redirection, typed-routes]
+---
+
+# GoRouter Navigation
+
+## **Priority: P0 (CRITICAL)**
+
+Type-safe deep linking and routing system using `go_router` and `go_router_builder`.
+
+## Structure
+
+```text
+core/router/
+├── app_router.dart # Router configuration
+└── routes.dart # Typed route definitions (GoRouteData)
+```
+
+## Implementation Guidelines
+
+- **Typed Routes**: Always use `GoRouteData` from `go_router_builder`. Never use raw path strings.
+- **Root Router**: One global `GoRouter` instance registered in DI.
+- **Sub-Routes**: Nest related routes using `TypedGoRoute` and children lists.
+- **Redirection**: Handle Auth (Login check) in the `redirect` property of the `GoRouter` config.
+- **Parameters**: Use `@TypedGoRoute` to define paths with `:id` parameters.
+- **Transitions**: Define standard transitions (Fade, Slide) in `buildPage`.
+- **Navigation**: Use `MyRoute().go(context)` or `MyRoute().push(context)`.
+
+## Code
+
+```dart
+// Route Definition
+@TypedGoRoute<HomeRoute>(path: '/')
+class HomeRoute extends GoRouteData {
+  @override
+  Widget build(context, state) => const HomePage();
+}
+
+// Router Config
+final router = GoRouter(
+  routes: $appRoutes,
+  redirect: (context, state) {
+    if (notAuthenticated) return '/login';
+    return null;
+  },
+);
+```
+
+## Related Topics
+
+layer-based-clean-architecture | auto-route-navigation | security

package/rules/flutter/idiomatic-flutter/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: Idiomatic Flutter
+description: Modern layout and widget composition standards.
+metadata:
+  labels: [flutter, clean-code, widgets]
+  triggers:
+    files: ['lib/presentation/**/*.dart']
+    keywords: [context.mounted, SizedBox, Gap, composition, shrink]
+---
+
+# Idiomatic Flutter (P1)
+
+- **Async Gaps**: Check `if (context.mounted)` before using `BuildContext` after `await`.
+- **Composition**: Extract complex UI into small widgets. Avoid deep nesting or large helper methods.
+- **Layout**:
+  - Spacing: Use `Gap(n)` or `SizedBox` over `Padding` for simple gaps.
+  - Empty UI: Use `const SizedBox.shrink()`.
+  - Intrinsic: Avoid `IntrinsicWidth/Height`; use `Stack` + `FractionallySizedBox` for overlays.
+- **Optimization**: Use `ColoredBox`/`Padding`/`DecoratedBox` instead of `Container` when possible.
+- **Themes**: Use extensions for `Theme.of(context)` access.

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

@@ -0,0 +1,50 @@
+---
+name: Flutter Layer-based Clean Architecture + DDD
+description: Standards for separation of concerns, layer dependency rules, and DDD in Flutter.
+metadata:
+  labels: [architecture, clean-architecture, layers, ddd]
+  triggers:
+    files: ['lib/domain/**', 'lib/infrastructure/**', 'lib/application/**']
+    keywords: [domain, infrastructure, application, presentation, layers, dto, mapper]
+---
+
+# Layer-Based Clean Architecture
+
+## **Priority: P0 (CRITICAL)**
+
+Standardized separation of concerns and dependency flow using DDD principles.
+
+## Structure
+
+```text
+lib/
+├── domain/ # Pure Dart: entities (@freezed), failures, repository interfaces
+├── infrastructure/ # Implementation: DTOs, data sources, mappers, repo impls
+├── application/ # Orchestration: BLoCs / Cubits
+└── presentation/ # UI: Screens, reusable components
+```
+
+## Implementation Guidelines
+
+- **Dependency Flow**: `Presentation -> Application -> Domain <- Infrastructure`. Dependencies point inward.
+- **Pure Domain**: No Flutter (Material/Store) or Infrastructure (Dio/Hive) dependencies in `Domain`.
+- **Functional Error Handling**: Repositories must return `Either<Failure, Success>`.
+- **Always Map**: Infrastructure must map DTOs to Domain Entities; do not leak DTOs to UI.
+- **Immutability**: Use `@freezed` for all entities and failures.
+- **Logic Placement**: No business logic in UI; widgets only display state and emit events.
+- **Inversion of Control**: Use `get_it` to inject repository implementations into BLoCs.
+
+## Anti-Patterns
+
+- **No DTOs in UI**: Never import a `.g.dart` or Data class directly in a Widget.
+- **No Material in Domain**: Do not import `package:flutter/material.dart` in the `domain` layer.
+- **No Shared Prefs in Repo**: Do not use `shared_preferences` directly in a Repository; use a Data Source.
+
+## Reference & Examples
+
+For full implementation templates and DTO-to-Domain mapping examples:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+feature-based-clean-architecture | bloc-state-management | dependency-injection | error-handling

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

@@ -0,0 +1,60 @@
+# Reference: Layer-based Clean Architecture Examples
+
+## **Full Layer Implementation**
+
+### 1. Domain Layer (Entity)
+
+```dart
+@freezed
+class Bank with _$Bank {
+  const factory Bank({
+    required String id,
+    required String name,
+    required String branchCode,
+  }) = _Bank;
+
+  factory Bank.fromJson(Map<String, dynamic> json) => _$BankFromJson(json);
+}
+```
+
+### 2. Infrastructure Layer (DTO & Mapper)
+
+```dart
+@freezed
+class BankDto with _$BankDto {
+  const factory BankDto({
+    @JsonKey(name: 'bank_id') required String id,
+    @JsonKey(name: 'bank_name') required String name,
+    @JsonKey(name: 'code') required String branchCode,
+  }) = _BankDto;
+
+  factory BankDto.fromJson(Map<String, dynamic> json) => _$BankDtoFromJson(json);
+
+  Bank toDomain() => Bank(
+    id: id,
+    name: name,
+    branchCode: branchCode,
+  );
+}
+```
+
+### 3. Application Layer (BLoC)
+
+```dart
+class BankBloc extends Bloc<BankEvent, BankState> {
+  final IBankRepository repository;
+
+  BankBloc(this.repository) : super(const BankState.initial()) {
+    on<_Fetch>(_onFetch);
+  }
+
+  Future<void> _onFetch(_Fetch event, Emitter<BankState> emit) async {
+    emit(const BankState.loading());
+    final failureOrBanks = await repository.fetchBanks();
+    emit(failureOrBanks.fold(
+      (f) => BankState.error(f.message),
+      (banks) => BankState.loaded(banks),
+    ));
+  }
+}
+```

package/rules/flutter/layer-based-clean-architecture/references/repository-mapping.md

@@ -0,0 +1,50 @@
+# Repositories & DTO Mapping Reference
+
+## **Data Transfer Object (DTO)**
+
+DTOs live in the **Infrastructure** layer and represent the raw JSON response.
+
+```dart
+@freezed
+class BankDto with _$BankDto {
+  const BankDto._();
+  
+  const factory BankDto({
+    @JsonKey(name: 'bank_id') required String id,
+    @JsonKey(name: 'bank_name') required String name,
+    @JsonKey(name: 'code') required String branchCode,
+  }) = _BankDto;
+
+  factory BankDto.fromJson(Map<String, dynamic> json) => _$BankDtoFromJson(json);
+
+  // Mapping to Domain Entity
+  Bank toDomain() => Bank(
+    id: id,
+    name: name,
+    branchCode: branchCode,
+  );
+}
+```
+
+## **Repository Implementation**
+
+The implementation handles the actual data fetching (Remote/Local) and mapping.
+
+```dart
+class BankRepository implements IBankRepository {
+  final BankRemoteDataSource remoteDataSource;
+
+  BankRepository(this.remoteDataSource);
+
+  @override
+  Future<Either<ApiFailure, List<Bank>>> fetchBanks() async {
+    try {
+      final dtoList = await remoteDataSource.getBanks();
+      // Perform the mapping here
+      return right(dtoList.map((dto) => dto.toDomain()).toList());
+    } catch (e) {
+      return left(ApiFailure.fromException(e));
+    }
+  }
+}
+```

package/rules/flutter/localization/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: Flutter Localization
+description: Standards for multi-language support using easy_localization and JSON/CSV assets.
+metadata:
+  labels: [localization, l10n, i18n, easy_localization]
+  triggers:
+    files: ['**/assets/translations/*.json', 'main.dart']
+    keywords:
+      [localization, multi-language, translation, tr(), easy_localization]
+---
+
+# Localization
+
+## **Priority: P1 (STANDARD)**
+
+Consistent multi-language support using `easy_localization`.
+
+## Structure
+
+```text
+assets/
+└── translations/
+    ├── en.json
+    └── vi.json
+```
+
+## Implementation Guidelines
+
+- **Bootstrap**: Wrap root with `EasyLocalization`. Always use `await EasyLocalization.ensureInitialized()`.
+- **Format**: Default to JSON. Store in `assets/translations/`.
+- **Lookup**: Use `.tr()` extension on strings.
+- **Locale**: Change via `context.setLocale(Locale('code'))`.
+- **Params**: Use `{}` in JSON; pass via `tr(args: [...])`.
+- **Counting**: Use `plural()` for quantities.
+- **Sheets**: Sync via `sheet_loader_localization` from Google Sheets for Online file storage to JSON/CSV.
+
+## Anti-Patterns
+
+- **Hardcoding**: No raw strings in UI; use keys.
+- **Manual L10n**: Avoid standard `Localizations.of`; use GetX or `easy_localization` context methods.
+- **Desync**: Keep keys identical across all locale files.
+
+## Reference & Examples
+
+For setup and Google Sheets automation:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+idiomatic-flutter | widgets