flutter-pro-max-cli 2.3.3 → 2.3.5

package/assets/templates/base/rules/01_skill_usage.md

@@ -1,3 +1,8 @@
+---
+description: Tự động sử dụng skill search trước khi viết code Flutter
+globs: *
+---
+
 # Rule: Tự động sử dụng Skill
 
 > Kích hoạt: Khi làm việc với Flutter/Dart files
@@ -19,4 +24,4 @@
 User request → Search skill (≥2 domains) → Đọc kết quả → Áp dụng vào code
 ```
 
-> ⚠️ Viết code Flutter mà không tham khảo skill trước = thiếu context = code chất lượng thấp.
+> ⚠️ Viết code Flutter mà không tham khảo skill trước = thiếu context = code chất lượng thấp.

package/assets/templates/base/rules/02_code_quality.md

@@ -1,3 +1,8 @@
+---
+description: Tiêu chuẩn Code Quality, Think-Before-Code, Hard Constraints
+globs: lib/**/*.dart
+---
+
 # Rule: Code Quality & Hard Constraints
 
 > Kích hoạt: Khi tạo/chỉnh sửa files `.dart`
@@ -47,4 +52,4 @@
 | Hardcode colors, padding, font sizes | Dùng `Theme.of(context)`, design tokens, constants |
 | Business logic trong Widget `build()` | Tách vào UseCase / Service / Provider |
 
-> 🔴 **REUSE > CREATE.** Không bao giờ tạo file mới mà không kiểm tra codebase hiện tại trước.
+> 🔴 **REUSE > CREATE.** Không bao giờ tạo file mới mà không kiểm tra codebase hiện tại trước.

package/assets/templates/base/rules/03_interaction_flow.md

@@ -1,3 +1,8 @@
+---
+description: Quy trình làm việc ABCR (Audit-Block-Critique-Refactor) khi nhận request
+globs: *
+---
+
 # Rule: Interaction Flow (ABCR)
 
 > Kích hoạt: Khi review, refactor, hoặc fix bugs
@@ -18,4 +23,4 @@ Khi nhận request liên quan đến code hiện tại, luôn tuân thủ quy tr
 | User yêu cầu tạo file mới | ⚠️ Chỉ AUDIT các file liên quan |
 | User hỏi kiến thức chung | ❌ Không cần ABCR |
 
-> 💡 **Mục đích:** Không bao giờ thêm code rác lên code rác. Fix nền tảng trước.
+> 💡 **Mục đích:** Không bao giờ thêm code rác lên code rác. Fix nền tảng trước.

package/assets/templates/base/rules/04_app_consistency.md

@@ -1,3 +1,8 @@
+---
+description: Đảm bảo tính nhất quán (Consistency) của UI, Design Tokens, Widget Patterns
+globs: lib/presentation/**/*.dart, lib/ui/**/*.dart, lib/widgets/**/*.dart
+---
+
 # Rule: App Consistency
 
 > Kích hoạt: Khi tạo UI, thêm screen, hoặc chỉnh sửa widget
@@ -55,4 +60,4 @@ abstract class AppSpacing {
 }
 ```
 
-> 🔴 **Khi có nghi ngờ:** Mở screen hiện tại có cùng chức năng → copy exact spacing và layout pattern. **Không sáng tạo riêng.**
+> 🔴 **Khi có nghi ngờ:** Mở screen hiện tại có cùng chức năng → copy exact spacing và layout pattern. **Không sáng tạo riêng.**

package/assets/templates/base/rules/05_error_handling.md

@@ -1,3 +1,8 @@
+---
+description: Xử lý lỗi, Try-catch, Result pattern, Không fail im lặng
+globs: lib/data/**/*.dart, lib/services/**/*.dart, lib/repositories/**/*.dart, lib/domain/**/*.dart
+---
+
 # Rule: Error Handling
 
 > Kích hoạt: Khi viết logic xử lý dữ liệu, API calls, hoặc async operations
@@ -40,4 +45,4 @@ Future<Result<User>> fetchUser(String id) async {
 | Throw generic `Exception('Error')` | Tạo custom exceptions có context |
 | Ignore `StackTrace` | Luôn log cả `stackTrace` để debug |
 
-> 🔴 **Mỗi `try` phải có `catch` có ý nghĩa.** Log + User message + Recovery action.
+> 🔴 **Mỗi `try` phải có `catch` có ý nghĩa.** Log + User message + Recovery action.

package/assets/templates/base/rules/06_testing.md

@@ -1,3 +1,8 @@
+---
+description: Viết Unit Test, Widget Test, Integration Test
+globs: test/**/*.dart, lib/**/*.dart
+---
+
 # Rule: Testing
 
 > Kích hoạt: Khi tạo feature mới, fix bug, hoặc refactor logic
@@ -45,4 +50,4 @@ test('should return user when API succeeds', () async {
 - Mỗi test case chỉ test 1 behavior
 - Tên test mô tả behavior: `should [expected] when [condition]`
 
-> 🔴 **Fix bug?** Viết test reproduce bug TRƯỚC, rồi mới fix.
+> 🔴 **Fix bug?** Viết test reproduce bug TRƯỚC, rồi mới fix.

package/assets/templates/base/rules/07_performance.md

@@ -1,3 +1,8 @@
+---
+description: Tối ưu hiệu năng, const, ListView.builder, Async computation
+globs: lib/presentation/**/*.dart, lib/ui/**/*.dart, lib/widgets/**/*.dart
+---
+
 # Rule: Performance
 
 > Kích hoạt: Khi viết widget, xử lý danh sách, hoặc async operations
@@ -37,11 +42,21 @@ ValueListenableBuilder<int>(
 );
 ```
 
+### 4. Performance (Bài toán Scale)
+
+Code chạy mượt ở 10 items có thể crash app ở 10,000 items. Lỗi tràn RAM (OOM - Out of Memory) thường âm thầm và khó debug.
+
+| Quy mô | Giải pháp Render |
+|--------|------------------|
+| Ít items (< 20) | `Column` bọc trong `SingleChildScrollView` (Có thể chấp nhận) |
+| Nhiều items (Hàng ngàn) | **BẮT BUỘC** dùng `ListView.builder` kết hợp Pagination/Infinite Scroll |
+| Bảng dữ liệu lớn | PaginatedDataTable hoặc Virtualized Lists |
+
 ### Checklist trước ship
 
 - [ ] Tất cả widget có `const` constructor nếu có thể
 - [ ] ListView/GridView dùng `.builder` hoặc `.separated`
+- [ ] Màn hình danh sách có hỗ trợ phân trang (Pagination) nếu data có thể phình to
 - [ ] Không có `print()` còn sót (dùng `developer.log`)
-- [ ] Images có loading/error builders
 
-> 🔴 **Nếu list > 20 items → BẮT BUỘC dùng `.builder`.** Không exceptions.
+> 🔴 **Nếu list > 20 items → BẮT BUỘC dùng `.builder`.** Luôn tự hỏi: *"Nếu user có 1 triệu record thì sao?"*

package/assets/templates/base/rules/08_security.md

@@ -1,3 +1,8 @@
+---
+description: Bảo mật, API Keys, Authentication, Data Protection
+globs: lib/data/**/*.dart, lib/services/**/*.dart, lib/core/env/*.dart
+---
+
 # Rule: Security
 
 > Kích hoạt: Khi xử lý authentication, API keys, user data, hoặc storage
@@ -38,4 +43,4 @@
 - Timeout cho mọi API call (30s max)
 - Không trust user input từ deep links
 
-> 🔴 **Mỗi lần thêm API key hay xử lý auth**, kiểm tra checklist trên.
+> 🔴 **Mỗi lần thêm API key hay xử lý auth**, kiểm tra checklist trên.

package/assets/templates/base/rules/09_state_management.md

@@ -1,3 +1,8 @@
+---
+description: Quản lý state theo cấp độ (Native-first), ValueNotifier
+globs: lib/presentation/**/*.dart, lib/ui/**/*.dart
+---
+
 # Rule: State Management
 
 > Kích hoạt: Khi quản lý state trong widget, screen, hoặc app-level
@@ -51,4 +56,4 @@ class CartNotifier extends ChangeNotifier {
 }
 ```
 
-> ⚠️ **KHÔNG tự ý thêm Riverpod/Bloc/GetX.** Hỏi user trước nếu cần escalate.
+> ⚠️ **KHÔNG tự ý thêm Riverpod/Bloc/GetX.** Hỏi user trước nếu cần escalate.

package/assets/templates/base/rules/10_naming_conventions.md

@@ -1,3 +1,8 @@
+---
+description: Quy tắc đặt tên (Naming), Cấu trúc thư mục (Folder Structure), Git Commit
+globs: lib/**/*.dart, test/**/*.dart
+---
+
 # Rule: Naming & Conventions
 
 > Kích hoạt: Khi tạo files, classes, functions, hoặc variables
@@ -67,4 +72,4 @@ test(auth): add login use case unit tests
 | `test` | Thêm/sửa tests |
 | `chore` | Config, dependencies, tooling |
 
-> 🔴 **Đặt tên file/class sai convention?** Rename ngay, không để nợ.
+> 🔴 **Đặt tên file/class sai convention?** Rename ngay, không để nợ.

package/assets/templates/base/rules/11_accessibility.md

@@ -1,3 +1,8 @@
+---
+description: Tiêu chuẩn tiếp cận (Accessibility), Semantics, Contrast
+globs: lib/presentation/**/*.dart, lib/widgets/**/*.dart
+---
+
 # Rule: Accessibility
 
 > Kích hoạt: Khi tạo UI, interactive elements, hoặc form inputs
@@ -53,4 +58,4 @@ Image.network(
 | Navigation | Focus order hợp lý |
 | Colors | Không dùng màu là cách duy nhất truyền thông tin |
 
-> 🔴 **Mỗi `IconButton` PHẢI có `tooltip`.** Mỗi `Image` PHẢI có `semanticLabel`.
+> 🔴 **Mỗi `IconButton` PHẢI có `tooltip`.** Mỗi `Image` PHẢI có `semanticLabel`.

package/assets/templates/base/rules/12_network_resiliency.md

@@ -0,0 +1,22 @@
+---
+description: Xử lý Network Failures, Tránh bão Request, Exponential Backoff, Circuit Breaker
+globs: lib/data/**/*.dart, lib/services/**/*.dart, lib/repositories/**/*.dart
+---
+
+# Rule: Network & API Resiliency
+
+> Kích hoạt: Khi viết API calls, cấu hình HTTP clients (Dio/Http), xử lý timeout
+
+## Nguyên tắc: Tránh bão Request
+
+Khi API lỗi do server quá tải, **TUYỆT ĐỐI KHÔNG** dùng vòng lặp retry vô tội vạ, vì sẽ tạo thêm gánh nặng làm sập hẳn server đang "thở oxy".
+
+### Giải pháp bắt buộc
+
+| Tình huống | Kỹ thuật áp dụng |
+|------------|------------------|
+| Lỗi 5xx / Timeout | **Exponential Backoff**: Tăng thời gian chờ sau mỗi lần thử (vd: 1s, 2s, 4s, 8s...) |
+| Server chết liên tục | **Circuit Breaker**: Ngắt hoàn toàn request trong 1 khoảng thời gian nhất định để server phục hồi. |
+| Mạng chập chờn | Cảnh báo UI thanh lịch (Snackbar / Retry button), không quăng exception đỏ màn hình. |
+
+> 🔴 **Luôn tự hỏi:** *"Nếu API endpoint này sập, app của mình có sập theo hay không bị treo cứng không?"*

package/assets/templates/base/rules/13_offline_first.md

@@ -0,0 +1,25 @@
+---
+description: Tư duy Offline-First, Cache dữ liệu, Đồng bộ ngầm, Xử lý khi mất mạng
+globs: lib/data/**/*.dart, lib/repositories/**/*.dart, lib/presentation/**/*.dart
+---
+
+# Rule: Offline-First Experience
+
+> Kích hoạt: Khi thiết kế luồng dữ liệu, fetch data cho màn hình chính (Dashboard, List)
+
+## Nguyên tắc: Sống sót không cần mạng
+
+Khi thiết bị lọt vào vùng mất mạng, **TUYỆT ĐỐI KHÔNG** để vòng xoay loading chạy vô tận hoặc văng ra màn hình trắng trơn.
+
+### Kiến trúc Offline-First
+
+1. **Lớp Cache Cache:** Bắt buộc có Local DB (SQLite, Isar, Hive) để lưu dữ liệu quan trọng.
+2. **Luồng ưu tiên Local:**
+   - Khi mở màn hình: Load data từ Local DB hiển thị lên UI **ngay lập tức**.
+   - Kích hoạt đồng bộ ngầm (background fetch) với server.
+   - Khi có data mới từ server: Cập nhật DB nội bộ, luồng stream tự động đẩy data thiết kế mới lên UI một cách mượt mà.
+
+### Checklist Offline
+- [ ] Mở app khi ngắt Wi-Fi vẫn thấy được dữ liệu cũ.
+- [ ] Thao tác (Like, Xoá, Nút bấm) được lưu tạm hàng đợi (Queue) để sync lại khi có mạng.
+- [ ] Có thông báo tinh tế báo hiệu đang xài ở chế độ Offline.

package/assets/templates/base/rules/14_ui_graceful_degradation.md

@@ -0,0 +1,23 @@
+---
+description: Xử lý Graceful Degradation, Fallback UI khi component/dữ liệu lỗi
+globs: lib/presentation/**/*.dart, lib/ui/**/*.dart, lib/widgets/**/*.dart
+---
+
+# Rule: Graceful Degradation (UI Fallback)
+
+> Kích hoạt: Khi build UI components, handle Image Network, List Items
+
+## Nguyên tắc: Lỗi cục bộ không được sập toàn cục
+
+Khi một thành phần UI hoặc dữ liệu bị fail, **đừng làm sập cả màn hình**. Tính thanh lịch của app nằm ở việc fallback giấu lỗi.
+
+### Các Fallback Pattern Bắt Buộc
+
+| Lỗi Component | Giải pháp UI (Fallback) |
+|---------------|-------------------------|
+| Hình ảnh (Avatar, Banner) lỗi tải (CDN down/404) | Hiển thị Default Image Icon, Placeholder, hoặc Chữ cái đầu của Tên (Initials Avatar). |
+| 1 Item lỗi trong ListView | Hiển thị `ErrorItemWidget` nhỏ cho riêng dòng đó, thay vì ném Exception break toàn list. |
+| Font chữ không tải được | Cấu hình Fallback về System Font mặc định. |
+| Widget tương tác lỗi | Vô hiệu hoá (Disable) nút bấm đó và đổi màu xám thay vì crash khi bấm. |
+
+> 🔴 **Quy tắc vàng:** Luôn định nghĩa thuộc tính `errorBuilder` cho mọi Network Image.

package/assets/templates/base/rules/15_state_lifecycle.md

@@ -0,0 +1,30 @@
+---
+description: Xử lý Vòng đời thiêt bị (Lifecycle), Orientation Change, Background State
+globs: lib/presentation/**/*.dart, lib/logic/**/*.dart, lib/providers/**/*.dart
+---
+
+# Rule: State & Lifecycle Resilience
+
+> Kích hoạt: Khi quản lý State (Bloc/Provider/Riverpod), xử lý orientation, handle app background state
+
+## Nguyên tắc: Chống hao pin & lag vô ích
+
+Quản lý vòng đời (lifecycle) kém sẽ làm máy nóng, lag và hao pin nhanh chóng, đặc biệt trên thiết bị Android yếu.
+
+### Xử lý Lifecycle Events
+
+1. **Xoay màn hình (Orientation Change):** 
+   - Việc xoay dọc/ngang không được làm trigger lại các API requests. 
+   - State phải được giữ nguyên bằng cơ chế State Management chuyên biệt, widget chỉ rebuild UI Layout.
+
+2. **App chuyển vào nền (Backgrounded):**
+   - Lập tức ngắt (Pause/Cancel) các Streams liên tục (như vị trí GPS, socket).
+   - Tạm dừng các `Timer` đếm ngược.
+
+3. **Memory Warning (Cảnh báo RAM):**
+   - Clear cache hình ảnh trong bộ nhớ (ví dụ: xoá cache network images).
+   - Giải phóng tài nguyên memory lớn không dùng tới.
+
+### Rò rỉ bộ nhớ (Memory Leaks)
+- Luôn gọi `dispose()` trên các Controller (AnimationController, ScrollController, TextEditingController).
+- Đảm bảo huỷ (cancel) StreamSubscription khi Widget bị huỷ.

package/dist/utils/template.js

@@ -172,11 +172,15 @@ async function generateRulesFile(targetDir, config) {
             }
             existing += '\n\n';
         }
+        // Helper to strip YAML frontmatter for appended files
+        const stripFrontmatter = (content) => {
+            return content.replace(/^---\n[\s\S]*?\n---\n+/, '');
+        };
         // Concatenate all rule files
         const allRules = ['# Flutter Pro Max — Agent Rules\n'];
         for (const file of ruleFiles) {
             const content = await readFile(join(rulesDir, file), 'utf-8');
-            allRules.push(content);
+            allRules.push(stripFrontmatter(content));
         }
         await writeFile(rulesFilePath, existing + allRules.join('\n---\n\n'), 'utf-8');
     }
@@ -184,9 +188,12 @@ async function generateRulesFile(targetDir, config) {
         // Create mode: generate separate files in rules directory
         const rulesTargetDir = dirname(join(targetDir, config.rulesFile.path));
         await mkdir(rulesTargetDir, { recursive: true });
+        // If rulesFile.path ends with .mdc, we use .mdc extension for files
+        const useMdc = config.rulesFile.path.endsWith('.mdc');
         for (const file of ruleFiles) {
             const content = await readFile(join(rulesDir, file), 'utf-8');
-            const targetPath = join(rulesTargetDir, file);
+            const targetExt = useMdc ? '.mdc' : '.md';
+            const targetPath = join(rulesTargetDir, file.replace(/\.md$/, targetExt));
             await writeFile(targetPath, content, 'utf-8');
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flutter-pro-max-cli",
-    "version": "2.3.3",
+    "version": "2.3.5",
     "description": "CLI to install Flutter Pro Max skill for AI coding assistants",
     "type": "module",
     "bin": {