flutter-pro-max-cli 2.3.1 → 2.3.3

package/assets/scripts/core.py

@@ -23,7 +23,7 @@ def _get_data_dir() -> Path:
         script_dir.parent.parent / "data",
         # When running from root/scripts/
         script_dir.parent / ".shared" / "data",
-        # When running from .agent/workflows/scripts/ (nested 3 levels deep)
+        # When running from .agents/workflows/scripts/ (nested 3 levels deep)
         script_dir.parent.parent.parent / ".shared" / "data",
         # When running from .claude/skills/flutter-pro-max/scripts/ (reference mode)
         script_dir.parent.parent.parent.parent / ".shared" / "data",

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

@@ -0,0 +1,22 @@
+# Rule: Tự động sử dụng Skill
+
+> Kích hoạt: Khi làm việc với Flutter/Dart files
+
+**TRƯỚC KHI viết code Flutter**, bạn PHẢI tự động sử dụng skill để lấy knowledge phù hợp. Không được bỏ qua bước này.
+
+| Tình huống | Domains cần search |
+|------------|-------------------|
+| Tạo UI/Screen mới | `style`, `pattern`, `color`, `typography`, `landing` |
+| Chọn package/thư viện | `package` (kèm `--stack` filter nếu có) |
+| Thiết kế kiến trúc | `architect`, `pattern` |
+| Tối ưu performance | `performance` |
+| Accessibility | `accessibility` |
+| Không chắc UI style | Dùng `--design-system` để generate design system |
+
+**Workflow bắt buộc:**
+
+```
+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.

package/assets/templates/base/{rules.md → rules/02_code_quality.md}

@@ -1,44 +1,43 @@
-# Flutter Pro Max — Agent Rules
+# Rule: Code Quality & Hard Constraints
 
-> Các rules này được tự động generate bởi `flutter-pro-max-cli`.
-> Chúng là project-level rules, TÁCH BIỆT khỏi skill content.
+> Kích hoạt: Khi tạo/chỉnh sửa files `.dart`
 
----
+## Think-Before-Code Protocol
 
-## Rule 1: Tự động sử dụng Skill
+**TRƯỚC KHI tạo file mới hoặc viết widget**, bạn PHẢI trả lời 5 câu hỏi:
 
-**TRƯỚC KHI viết code Flutter**, bạn PHẢI tự động sử dụng skill để lấy knowledge phù hợp. Không được bỏ qua bước này.
+1. **File này có vượt 300 dòng không?** → Nếu có khả năng, TÁCH ngay từ đầu
+2. **Widget/Component này đã tồn tại chưa?** → Search codebase trước, REUSE nếu có
+3. **Widget này có thể reuse cho nơi khác không?** → Nếu có, đặt vào `core/widgets/` hoặc shared folder
+4. **Logic này thuộc layer nào?** → UI / Domain / Data — KHÔNG được trộn layers
+5. **Có widget/hàm nào đang lặp logic tương tự không?** → Nếu có, REFACTOR thành shared component
 
-| Tình huống | Domains cần search |
-|------------|-------------------|
-| Tạo UI/Screen mới | `style`, `pattern`, `color`, `typography`, `landing` |
-| Chọn package/thư viện | `package` (kèm `--stack` filter nếu có) |
-| Thiết kế kiến trúc | `architect`, `pattern` |
-| Tối ưu performance | `performance` |
-| Accessibility | `accessibility` |
-| Không chắc UI style | Dùng `--design-system` để generate design system |
+## Hard Constraints (Vùng Cấm)
 
-**Workflow bắt buộc:**
+### 🚫 NO GOD CLASSES
 
-```
-User request → Search skill (≥2 domains) → Đọc kết quả → Áp dụng vào code
-```
+| Indicator | Threshold | Action |
+|-----------|-----------|--------|
+| Public methods | > 10 methods | 🔴 **REFACTOR** |
+| Lines of logic | > 200 lines | 🔴 **REFACTOR** |
+| Mixed concerns | Logic + UI + DB | 🔴 **TÁCH NGAY** |
 
-> ⚠️ Viết code Flutter mà không tham khảo skill trước = thiếu context = code chất lượng thấp.
+### 🚫 NO GOD FILES
 
----
+| Rule | Limit |
+|------|-------|
+| **File size** | ≤ 300 dòng (tối đa 500) |
+| **Classes per file** | 1 Class chính duy nhất |
 
-## Rule 2: Think-Before-Code Protocol
+### 🚫 NO LOGIC LEAKAGE
 
-**TRƯỚC KHI tạo file mới hoặc viết widget**, bạn PHẢI trả lời 5 câu hỏi:
-
-1. **File này có vượt 300 dòng không?** → Nếu có khả năng, TÁCH ngay từ đầu
-2. **Widget/Component này đã tồn tại chưa?** → Search codebase trước, REUSE nếu có
-3. **Widget này có thể reuse cho nơi khác không?** → Nếu có, đặt vào `core/widgets/` hoặc shared folder
-4. **Logic này thuộc layer nào?** → UI / Domain / Data — KHÔNG được trộn layers
-5. **Có widget/hàm nào đang lặp logic tương tự không?** → Nếu có, REFACTOR thành shared component
+| Violation | Correct Layer |
+|-----------|---------------|
+| Business Logic trong Widget | ➜ Move to `UseCase` / `Service` |
+| SQL/Query trong Controller | ➜ Move to `Repository` |
+| API calls trong UI | ➜ Move to `DataSource` |
 
-### Nguyên tắc cứng
+## Nguyên tắc cứng
 
 | ❌ Sai | ✅ Đúng |
 |--------|---------|

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

@@ -0,0 +1,21 @@
+# Rule: Interaction Flow (ABCR)
+
+> Kích hoạt: Khi review, refactor, hoặc fix bugs
+
+Khi nhận request liên quan đến code hiện tại, luôn tuân thủ quy trình:
+
+1. **AUDIT** - Quét code smells, kiểm tra God Class/File
+2. **BLOCK** - Cảnh báo nếu vi phạm, giải thích Technical Debt
+3. **REFACTOR** - Sửa kiến trúc trước khi fix bug
+4. **EXPLAIN** - Giải thích lý do tách/refactor
+
+### Khi nào áp dụng ABCR?
+
+| Tình huống | Áp dụng? |
+|------------|----------|
+| User yêu cầu fix bug | ✅ AUDIT trước, refactor nếu có code smell |
+| User yêu cầu thêm feature | ✅ AUDIT file đích trước khi thêm code |
+| 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.

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

@@ -0,0 +1,58 @@
+# Rule: App Consistency
+
+> Kích hoạt: Khi tạo UI, thêm screen, hoặc chỉnh sửa widget
+
+## Nguyên tắc: Mọi thứ phải nhất quán
+
+**TRƯỚC KHI viết UI code**, bạn PHẢI kiểm tra các pattern hiện có trong project để đảm bảo consistency.
+
+## 1. Design Tokens — Dùng chung, không hardcode
+
+| ❌ Sai | ✅ Đúng |
+|--------|---------|
+| `Color(0xFF1A73E8)` | `Theme.of(context).colorScheme.primary` |
+| `EdgeInsets.all(16)` | `EdgeInsets.all(AppSpacing.md)` hoặc constant |
+| `TextStyle(fontSize: 14)` | `Theme.of(context).textTheme.bodyMedium` |
+| `BorderRadius.circular(8)` | `BorderRadius.circular(AppRadius.sm)` |
+| `Duration(milliseconds: 300)` | `AppDurations.normal` |
+
+## 2. Widget Patterns — Copy style từ existing screens
+
+**TRƯỚC KHI tạo screen mới:**
+
+1. Tìm screen tương tự trong codebase (list, detail, form, dashboard)
+2. Sao chép cấu trúc, spacing, và layout pattern
+3. Dùng cùng widget wrappers (Scaffold, AppBar style, padding)
+
+| Element | Quy tắc |
+|---------|---------|
+| **AppBar** | Dùng chung 1 style/component cho toàn app |
+| **Empty States** | Dùng chung widget, không tạo mới mỗi screen |
+| **Loading States** | Dùng chung shimmer/skeleton, không mỗi chỗ 1 kiểu |
+| **Error States** | Dùng chung error widget với retry action |
+| **List Items** | Cùng padding, divider style, tap behavior |
+| **Forms** | Cùng validation style, field spacing, button placement |
+| **Dialogs** | Cùng shape, padding, button alignment |
+
+## 3. Navigation & Transitions
+
+- Dùng chung transition animations (không mỗi screen 1 kiểu)
+- Consistent back button behavior
+- Cùng pattern cho bottom sheets, modals, popups
+
+## 4. Spacing System
+
+Định nghĩa và tuân thủ spacing scale:
+
+```dart
+// ✅ Dùng constants
+abstract class AppSpacing {
+  static const double xs = 4;
+  static const double sm = 8;
+  static const double md = 16;
+  static const double lg = 24;
+  static const double xl = 32;
+}
+```
+
+> 🔴 **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

@@ -0,0 +1,43 @@
+# Rule: Error Handling
+
+> Kích hoạt: Khi viết logic xử lý dữ liệu, API calls, hoặc async operations
+
+## Nguyên tắc: Không bao giờ fail im lặng
+
+### Bắt buộc
+
+| Tình huống | Cách xử lý |
+|------------|------------|
+| API call | Luôn wrap trong `try-catch`, log lỗi, hiển thị message cho user |
+| Parse JSON/data | Dùng `tryParse` hoặc `try-catch`, KHÔNG để crash |
+| File I/O | Handle `FileSystemException` cụ thể |
+| Navigation args | Validate params trước khi dùng |
+
+### Pattern chuẩn
+
+```dart
+// ✅ Structured error handling
+Future<Result<User>> fetchUser(String id) async {
+  try {
+    final response = await api.getUser(id);
+    return Result.success(User.fromJson(response));
+  } on DioException catch (e) {
+    developer.log('API failed', name: 'user.fetch', error: e);
+    return Result.failure(e.toAppError());
+  } catch (e, s) {
+    developer.log('Unexpected', name: 'user.fetch', error: e, stackTrace: s);
+    return Result.failure(AppError.unexpected(e));
+  }
+}
+```
+
+### Cấm
+
+| ❌ Sai | Lý do |
+|--------|-------|
+| `catch (e) {}` (empty catch) | Nuốt lỗi, debug nightmare |
+| `print(e)` | Dùng `developer.log()` thay vì print |
+| 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.

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

@@ -0,0 +1,48 @@
+# Rule: Testing
+
+> Kích hoạt: Khi tạo feature mới, fix bug, hoặc refactor logic
+
+## Nguyên tắc: Không có test = Không hoàn thành
+
+### Khi nào PHẢI viết test
+
+| Loại code | Test bắt buộc | Ví dụ |
+|-----------|---------------|-------|
+| Business logic | Unit test | UseCase, Service, Validator |
+| Repository/DataSource | Unit test với mock | API calls, DB queries |
+| Widget có logic | Widget test | Form validation, state changes |
+| User flow quan trọng | Integration test | Login, checkout, onboarding |
+
+### Khi nào KHÔNG cần test
+
+- Pure UI widget không có logic (chỉ layout/styling)
+- Generated code (`.g.dart`, `.freezed.dart`)
+- Constants, enums đơn giản
+
+### Pattern chuẩn
+
+```dart
+// ✅ Test structure: Arrange → Act → Assert
+test('should return user when API succeeds', () async {
+  // Arrange
+  when(mockApi.getUser('123')).thenAnswer(
+    (_) async => {'name': 'John'},
+  );
+
+  // Act
+  final result = await useCase.execute('123');
+
+  // Assert
+  expect(result, isA<Success<User>>());
+  expect(result.data.name, equals('John'));
+});
+```
+
+### Quy tắc
+
+- File test đặt cùng tên: `user_service.dart` → `user_service_test.dart`
+- Dùng `package:mocktail` hoặc `package:mockito` cho mocking
+- 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.

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

@@ -0,0 +1,47 @@
+# Rule: Performance
+
+> Kích hoạt: Khi viết widget, xử lý danh sách, hoặc async operations
+
+## Nguyên tắc: Performance là requirement, không phải nice-to-have
+
+### Widget Performance
+
+| ❌ Sai | ✅ Đúng | Impact |
+|--------|---------|--------|
+| `Container()` cho spacing | `const SizedBox(height: 16)` | Giảm rebuild |
+| `ListView(children: [...])` | `ListView.builder(itemBuilder:)` | Lazy loading |
+| Widget không có `const` | `const MyWidget()` | Prevent rebuild |
+| Inline function trong `build()` | Extract method hoặc cached | Tránh tạo closure mỗi frame |
+| Rebuild toàn tree | `ValueListenableBuilder` scoped | Chỉ rebuild phần thay đổi |
+
+### Async & Computation
+
+| Quy tắc | Lý do |
+|----------|-------|
+| KHÔNG gọi API/async trong `build()` | Block UI thread |
+| Heavy JSON parsing → dùng `compute()` | Chạy trên isolate riêng |
+| Image caching → dùng `CachedNetworkImage` | Tránh download lại |
+| Debounce search input (300-500ms) | Giảm API calls |
+
+### State Management Performance
+
+```dart
+// ❌ Toàn widget tree rebuild
+setState(() => _counter++);
+
+// ✅ Chỉ rebuild phần cần thiết
+ValueListenableBuilder<int>(
+  valueListenable: _counter,
+  builder: (_, value, child) => Text('$value'),
+  child: const ExpensiveWidget(), // Không bị rebuild
+);
+```
+
+### Checklist trước ship
+
+- [ ] Tất cả widget có `const` constructor nếu có thể
+- [ ] ListView/GridView dùng `.builder` hoặc `.separated`
+- [ ] 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.

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

@@ -0,0 +1,41 @@
+# Rule: Security
+
+> Kích hoạt: Khi xử lý authentication, API keys, user data, hoặc storage
+
+## Nguyên tắc: Bảo mật không phải optional
+
+### API Keys & Secrets
+
+| ❌ KHÔNG BAO GIỜ | ✅ Thay bằng |
+|-------------------|-------------|
+| Hardcode API key trong source | Dùng `--dart-define` hoặc `.env` |
+| Commit `.env` file | Thêm vào `.gitignore` |
+| Log sensitive data | Mask/redact trước khi log |
+| Lưu token trong `SharedPreferences` | Dùng `flutter_secure_storage` |
+
+### Authentication
+
+| Quy tắc | Chi tiết |
+|----------|----------|
+| Token storage | `flutter_secure_storage` (encrypted) |
+| Token refresh | Interceptor tự động refresh khi 401 |
+| Logout | Clear ALL tokens + secure storage |
+| Deep link auth | Validate state parameter |
+
+### Data Protection
+
+| Tình huống | Xử lý |
+|------------|-------|
+| User input | Sanitize trước khi gửi API |
+| Hiển thị PII (email, phone) | Mask một phần: `john***@gmail.com` |
+| Cache sensitive data | Encrypt hoặc không cache |
+| Screenshot prevention | `FLAG_SECURE` cho screens nhạy cảm |
+
+### Network Security
+
+- HTTPS only (không HTTP)
+- Certificate pinning cho apps quan trọng
+- 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.

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

@@ -0,0 +1,54 @@
+# Rule: State Management
+
+> Kích hoạt: Khi quản lý state trong widget, screen, hoặc app-level
+
+## Nguyên tắc: Native-First, Escalate khi cần
+
+### Hierarchy (Ưu tiên từ trên xuống)
+
+| Level | Giải pháp | Khi nào dùng |
+|-------|-----------|-------------|
+| 1️⃣ | `StatelessWidget` | UI tĩnh, không có state |
+| 2️⃣ | `ValueNotifier` + `ValueListenableBuilder` | State đơn giản (counter, toggle, loading) |
+| 3️⃣ | `ChangeNotifier` + `ListenableBuilder` | State phức tạp có nhiều fields (form, cart) |
+| 4️⃣ | `InheritedWidget` / `Provider` | Shared state giữa nhiều widgets |
+| 5️⃣ | Riverpod / Bloc | **CHỈ KHI user yêu cầu rõ ràng** |
+
+### Quy tắc cứng
+
+| ❌ Sai | ✅ Đúng |
+|--------|---------|
+| Dùng Riverpod cho counter đơn giản | `ValueNotifier<int>` |
+| `setState` rebuild toàn screen | `ValueListenableBuilder` scoped |
+| Global state cho state chỉ 1 screen dùng | Local state trong widget |
+| Mutable state trực tiếp | Immutable state + `copyWith` |
+
+### Pattern chuẩn
+
+```dart
+// ✅ Simple: ValueNotifier
+class CounterWidget extends StatelessWidget {
+  final _count = ValueNotifier<int>(0);
+
+  @override
+  Widget build(BuildContext context) {
+    return ValueListenableBuilder<int>(
+      valueListenable: _count,
+      builder: (_, value, __) => Text('$value'),
+    );
+  }
+}
+
+// ✅ Complex: ChangeNotifier
+class CartNotifier extends ChangeNotifier {
+  final List<Item> _items = [];
+  List<Item> get items => List.unmodifiable(_items);
+
+  void add(Item item) {
+    _items.add(item);
+    notifyListeners();
+  }
+}
+```
+
+> ⚠️ **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

@@ -0,0 +1,70 @@
+# Rule: Naming & Conventions
+
+> Kích hoạt: Khi tạo files, classes, functions, hoặc variables
+
+## Nguyên tắc: Tên phải tự giải thích, cấu trúc phải nhất quán
+
+### Naming Convention
+
+| Element | Convention | Ví dụ |
+|---------|-----------|-------|
+| Files | `snake_case` | `user_profile_page.dart` |
+| Classes | `PascalCase` | `UserProfilePage` |
+| Functions/Methods | `camelCase` | `fetchUserProfile()` |
+| Variables | `camelCase` | `userName`, `isLoading` |
+| Constants | `camelCase` hoặc `SCREAMING_SNAKE` | `maxRetryCount`, `API_BASE_URL` |
+| Private | Prefix `_` | `_buildHeader()`, `_items` |
+| Enums | `PascalCase` values | `UserRole.admin` |
+
+### File Naming theo Layer
+
+| Layer | Pattern | Ví dụ |
+|-------|---------|-------|
+| Page/Screen | `*_page.dart` | `login_page.dart` |
+| Widget | `*_widget.dart` hoặc tên mô tả | `user_avatar.dart` |
+| Model | `*_model.dart` | `user_model.dart` |
+| Repository | `*_repository.dart` | `auth_repository.dart` |
+| Service/UseCase | `*_service.dart` / `*_use_case.dart` | `auth_service.dart` |
+| Provider/Notifier | `*_provider.dart` / `*_notifier.dart` | `cart_notifier.dart` |
+| Extension | `*_extension.dart` | `string_extension.dart` |
+
+### Folder Structure
+
+```
+lib/
+├── core/              # Shared: theme, utils, widgets, constants
+│   ├── theme/
+│   ├── widgets/       # Reusable widgets
+│   ├── utils/
+│   └── constants/
+├── features/          # Feature-first organization
+│   ├── auth/
+│   │   ├── data/      # Repository implementations, models
+│   │   ├── domain/    # Entities, use cases, repo interfaces
+│   │   └── presentation/  # Pages, widgets, notifiers
+│   └── home/
+└── main.dart
+```
+
+### Git Commit Convention
+
+```
+<type>(<scope>): <description>
+
+feat(auth): add biometric login support
+fix(cart): resolve item count not updating
+refactor(core): extract shared AppBar widget
+docs(readme): update installation guide
+test(auth): add login use case unit tests
+```
+
+| Type | Khi nào |
+|------|---------|
+| `feat` | Feature mới |
+| `fix` | Sửa bug |
+| `refactor` | Restructure code, không đổi behavior |
+| `docs` | Documentation only |
+| `test` | Thêm/sửa tests |
+| `chore` | Config, dependencies, tooling |
+
+> 🔴 **Đặt tên file/class sai convention?** Rename ngay, không để nợ.

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

@@ -0,0 +1,56 @@
+# Rule: Accessibility
+
+> Kích hoạt: Khi tạo UI, interactive elements, hoặc form inputs
+
+## Nguyên tắc: App phải dùng được cho MỌI NGƯỜI
+
+### Bắt buộc cho mọi widget
+
+| Requirement | Standard | Cách check |
+|-------------|----------|------------|
+| **Contrast** | Minimum 4.5:1 cho text | Dùng contrast checker tool |
+| **Large Text** | Minimum 3:1 (18pt hoặc 14pt bold) | Visual check |
+| **Touch Target** | Minimum 48x48dp | `SizedBox` wrapper nếu cần |
+| **Semantics** | Label tất cả interactive elements | `Semantics()` widget |
+| **Dynamic Scaling** | Hỗ trợ lên đến 200% font size | Test với `textScaleFactor` |
+
+### Code Patterns
+
+```dart
+// ✅ Semantics cho interactive elements
+Semantics(
+  label: 'Xóa sản phẩm khỏi giỏ hàng',
+  button: true,
+  child: IconButton(
+    icon: const Icon(Icons.delete),
+    onPressed: onDelete,
+  ),
+);
+
+// ✅ Form field accessible
+TextFormField(
+  decoration: const InputDecoration(
+    labelText: 'Email', // Screen reader đọc được
+    hintText: 'example@email.com',
+  ),
+);
+
+// ✅ Image có description
+Image.network(
+  url,
+  semanticLabel: 'Ảnh đại diện của người dùng',
+);
+```
+
+### Checklist
+
+| Element | Kiểm tra |
+|---------|----------|
+| Buttons/Icons | Có `tooltip` hoặc `Semantics.label` |
+| Images | Có `semanticLabel` |
+| Forms | Có `labelText`, không chỉ `hintText` |
+| Alerts/Dialogs | Có title mô tả rõ |
+| 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`.