flutter-pro-max-cli 2.3.4 → 2.4.0

package/assets/scripts/search.py

@@ -3,10 +3,10 @@
 """
 Flutter Pro Max Search - CLI for Flutter knowledge base search
 Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--top 5]
-       python search.py "<query>" --design-system [-p "Project Name"]
-       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+    python search.py "<query>" --design-system [-p "Project Name"]
+    python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
 
-Domains: widget, package, pattern, architect, chart, color, typography, style, ux, icon, landing, naming, product, prompt, performance, ui-reasoning, accessibility
+Domains: widget, package, pattern, architect, chart, color, typography, style, ux, icon, landing, naming, product, prompt, play-store, performance, ui-reasoning, accessibility
 Stacks: riverpod, bloc, provider
 
 Persistence (Master + Overrides pattern):
@@ -68,6 +68,7 @@ Examples:
   python search.py "ListView pagination" --top 3
   python search.py "network http" --domain package
   python search.py "state management" --stack riverpod
+    python search.py "google play store listing" --domain play-store
   python search.py "login" --json
         """
     )

package/assets/templates/base/quick-reference.md

@@ -34,6 +34,10 @@ python3 {{SCRIPT_PATH}}/search.py "state" --stack provider --top 5
 
 # JSON output
 python3 {{SCRIPT_PATH}}/search.py "login" --json --top 3
+
+# Google Play Console workflow
+python3 {{SCRIPT_PATH}}/search.py "google play listing" --domain play-store --top 5
+python3 {{SCRIPT_PATH}}/search.py "data safety content rating" --domain play-store --json --top 5
 ```
 
 ### Package Management
@@ -73,6 +77,13 @@ dart pub remove <package_name>
 
 4. **Apply results** với native state management (ValueNotifier/ChangeNotifier)
 
+### Google Play Console Workflow
+
+1. Search `play-store` for ASO, listing copy, and compliance guidance.
+2. Generate text assets with the correct limits before writing anything final.
+3. Validate content rating, data safety, screenshots, and privacy policy details.
+4. Export Markdown for humans and JSON for machine-readable handoff.
+
 5. **Validate:**
    ```bash
    dart format . && flutter analyze . && flutter test .

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

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`

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

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

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

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

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

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

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

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

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/assets/templates/base/rules/16_google_play_aso.md

@@ -0,0 +1,40 @@
+---
+description: Google Play ASO, store listing copy, keyword strategy
+globs: *
+---
+
+# Rule: Google Play ASO
+
+> Kich hoat: Khi user yeu cau tao hoac toi uu listing Google Play, app name, short description, full description, keyword set, hoac export Play Console.
+
+## Luon lam truoc khi viet copy
+
+1. Xac dinh USP thuc su cua app.
+2. Xac dinh persona chinh va pain point.
+3. Lay keyword cluster theo y nghia, khong theo spam density.
+4. Kiem tra gioi han text truoc khi tra ket qua.
+
+## Gioi han can tuan thu
+
+| Asset | Limit | Nguyen tac |
+|------|-------|------------|
+| App Name | 30 ky tu | Brand + 1 tu khoa chinh |
+| Short Description | 80 ky tu | 1 cau, ro loi ich |
+| Full Description | 4000 ky tu | Co cau truc, de scan |
+
+## Khong duoc lam
+
+- Khong dung "best", "#1", hoac claim phong dai.
+- Khong spam keyword lap lai vo nghia.
+- Khong viet copy khac voi tinh nang that.
+- Khong bo qua kha nang da ngon ngu neu app co thi truong quoc te.
+
+## Output mong doi
+
+- App name
+- Short description
+- Full description
+- Keyword set theo muc do uu tien
+- Category va tags de xuat
+
+> Neu thong tin dau vao khong du, phai ghi ro gia dinh va phan can xac minh.

package/assets/templates/base/rules/17_google_play_compliance.md

@@ -0,0 +1,39 @@
+---
+description: Google Play content rating, data safety, privacy policy
+globs: *
+---
+
+# Rule: Google Play Compliance
+
+> Kich hoat: Khi user yeu cau content rating, data safety, privacy policy, location disclosure, hoac release checklist.
+
+## Content Rating
+
+- Tra loi IARC theo tinh nang that.
+- Neu app co UGC, report, block, hoac moderation, phai de cap ro.
+- Neu app co location, phai phan biet approximate va precise.
+- Khong doan mo neu chua biet; danh dau can xac minh.
+
+## Data Safety
+
+- Chi khai bao du lieu that su thu thap hoac chia se.
+- Neu co du lieu ca nhan, phai ghi ro muc dich su dung.
+- Neu du lieu duoc ma hoa khi truyen, ghi ro "encrypted in transit".
+- Neu app ho tro xoa du lieu, ghi ro duong dan request xoa.
+
+## Privacy Policy
+
+- Phai co URL on dinh va hoat dong.
+- Phai neu ro loai du lieu, muc dich, retention, sharing, va contact.
+- Email ho tro phai khop voi domain neu co the.
+
+## Final Gate
+
+Truoc khi xuat ket qua, phai kiem tra:
+
+1. Content rating co trung thuc.
+2. Data safety khop voi hanh vi san pham.
+3. Privacy policy co link va noi dung day du.
+4. Thong tin lien he hoat dong.
+
+> Compliance sai se gay reject, nen uong dua vao facts, khong phai assumptions.

package/assets/templates/base/rules/18_google_play_visuals.md

@@ -0,0 +1,35 @@
+---
+description: Google Play screenshots, feature graphic, icon guidance
+globs: *
+---
+
+# Rule: Google Play Visuals
+
+> Kich hoat: Khi user yeu cau screenshot, feature graphic, icon guidance, hoac visual pack cho Play Store.
+
+## Screenshots
+
+- Anh dau tien phai the hien core feature manh nhat.
+- Thu tu anh nen di tu value -> feature -> trust -> CTA.
+- Khong dung device mockup qua cu.
+- Khong nhieu chu, khong lam nguoi xem phai doc qua lau.
+
+## Feature Graphic
+
+- Mot thong diep chinh, mot focal point ro rang.
+- Chu to, ngan, de nhan biet tren mobile.
+- Giu safe area sach, khong nhot qua nhieu icon.
+
+## Icon / Brand
+
+- Khong dung trademark cua ben thu ba neu khong co quyen.
+- Giữ mau sac nhat quan voi app.
+- Uu tien hinh khoi don gian, nhan dien nhanh.
+
+## Quality Gate
+
+- Co core feature ngay anh dau.
+- Device mockup hien dai va dong nhat.
+- Visual khong lam sai san pham that.
+
+> Muc tieu la tang conversion, khong phai trang tri vo nghia.

package/assets/templates/base/skill-content.md

@@ -43,7 +43,7 @@ python3 {{SCRIPT_PATH}}/search.py "<keyword>" --stack riverpod --top 5
 python3 {{SCRIPT_PATH}}/search.py "<keyword>" --json --top 5
 ```
 
-**Available domains (17):** `widget`, `package`, `pattern`, `architect`, `chart`, `color`, `typography`, `style`, `ux`, `icon`, `landing`, `naming`, `product`, `prompt`, `performance`, `ui-reasoning`, `accessibility`
+**Available domains (18):** `widget`, `package`, `pattern`, `architect`, `chart`, `color`, `typography`, `style`, `ux`, `icon`, `landing`, `naming`, `product`, `prompt`, `play-store`, `performance`, `ui-reasoning`, `accessibility`
 
 **Available stacks:** `riverpod`, `bloc`, `provider`
 
@@ -74,9 +74,38 @@ python3 {{SCRIPT_PATH}}/search.py "<keyword>" --json --top 5
 | Naming | `name_convention.csv` | Naming conventions |
 | Products | `products.csv` | Product type styling |
 | Prompts | `prompts.csv` | AI prompt templates |
+| Play Store | `play-store.csv` | ASO, store listing, compliance, privacy |
 
 ---
 
+## Google Play Console Workflow
+
+Use the `play-store` domain when the user asks for ASO, app listing copy, content rating, data safety, screenshots, privacy policy, or Play Console export.
+
+### Suggested Flow
+
+1. Analyze the app input and extract USP, persona, keywords, category, and tags.
+2. Generate store text assets with strict length limits.
+3. Validate compliance details for content rating, data safety, and privacy.
+4. Produce screenshot and feature graphic guidance.
+5. Export the result as Markdown and JSON when needed.
+
+### Example Queries
+
+```bash
+python3 {{SCRIPT_PATH}}/search.py "google play store listing" --domain play-store --top 5
+python3 {{SCRIPT_PATH}}/search.py "content rating data safety" --domain play-store --top 5
+python3 {{SCRIPT_PATH}}/search.py "app name short description" --domain play-store --json --top 5
+```
+
+### Output Targets
+
+- App Name: max 30 characters, brand + core keyword
+- Short Description: max 80 characters, concise value proposition
+- Full Description: max 4000 characters, structured and policy-safe
+- Compliance Pack: content rating answers, data safety table, privacy notes
+- Visual Pack: first screenshot guidance, feature graphic, icon rules
+
 ## Example Workflow
 
 **User Request:** "Tạo màn hình đăng nhập"

package/dist/utils/template.js

@@ -93,12 +93,13 @@ export async function renderSkillFile(config) {
     // Load base template (use config.template or default to skill-content.md)
     const templateFile = config.template || 'skill-content.md';
     let content = await loadTemplate(`base/${templateFile}`);
+    const scriptDir = dirname(config.scriptPath);
     // Load quick reference if needed
     let quickReferenceContent = '';
     if (config.sections.quickReference) {
         quickReferenceContent = await loadTemplate('base/quick-reference.md');
         // Replace script path in quick reference
-        quickReferenceContent = quickReferenceContent.replace(/\{\{SCRIPT_PATH\}\}/g, config.scriptPath);
+        quickReferenceContent = quickReferenceContent.replace(/\{\{SCRIPT_PATH\}\}/g, scriptDir);
     }
     // Build the final content
     const frontmatter = renderFrontmatter(config.frontmatter);
@@ -107,7 +108,7 @@ export async function renderSkillFile(config) {
     content = content
         .replace(/\{\{TITLE\}\}/g, config.title)
         .replace(/\{\{DESCRIPTION\}\}/g, config.description)
-        .replace(/\{\{SCRIPT_PATH\}\}/g, config.scriptPath)
+        .replace(/\{\{SCRIPT_PATH\}\}/g, scriptDir)
         .replace(/\{\{SKILL_OR_WORKFLOW\}\}/g, config.skillOrWorkflow)
         .replace(/\{\{QUICK_REFERENCE\}\}/g, quickRefWithNewline);
     return frontmatter + content;
@@ -172,11 +173,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 +189,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.4",
+    "version": "2.4.0",
     "description": "CLI to install Flutter Pro Max skill for AI coding assistants",
     "type": "module",
     "bin": {