flutter-pro-max-cli 2.0.0 → 2.1.3

package/assets/scripts/search.py

@@ -3,9 +3,15 @@
 """
 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"]
 
 Domains: widget, package, pattern, architect, chart, color, typography, style, ux, icon, landing, naming, product, prompt, performance, ui-reasoning, accessibility
 Stacks: riverpod, bloc, provider
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
 """
 
 import argparse
@@ -18,9 +24,11 @@ from core import (
     search, 
     search_with_stack
 )
+from design_system import generate_design_system, persist_design_system
+from typing import Any
 
 
-def format_output(result):
+def format_output(result: dict[str, Any]) -> str:
     """Format results for human-readable output (token-optimized for AI)"""
     if "error" in result:
         return f"❌ Error: {result['error']}"
@@ -86,9 +94,72 @@ Examples:
         action="store_true", 
         help="Output as JSON"
     )
+    # Design system generation
+    parser.add_argument(
+        "--design-system", "-ds",
+        action="store_true",
+        help="Generate complete design system recommendation"
+    )
+    parser.add_argument(
+        "--project-name", "-p",
+        type=str,
+        default=None,
+        help="Project name for design system output"
+    )
+    parser.add_argument(
+        "--format", "-f",
+        choices=["ascii", "markdown"],
+        default="ascii",
+        help="Output format for design system"
+    )
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument(
+        "--persist",
+        action="store_true",
+        help="Save design system to design-system/MASTER.md (creates hierarchical structure)"
+    )
+    parser.add_argument(
+        "--page",
+        type=str,
+        default=None,
+        help="Create page-specific override file in design-system/pages/"
+    )
+    parser.add_argument(
+        "--output-dir", "-o",
+        type=str,
+        default=None,
+        help="Output directory for persisted files (default: current directory)"
+    )
 
     args = parser.parse_args()
 
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query,
+            args.project_name,
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Screen Overrides)")
+            print("")
+            print(f"📖 Usage: When building a screen, check design-system/{project_slug}/pages/[screen].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+        return
+
     # Perform search
     if args.stack:
         result = search_with_stack(args.query, args.stack, args.domain, args.top)

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

@@ -3,6 +3,25 @@
 
 ## Quick Reference
 
+### AI Tools Commands
+
+```bash
+# Format code (ALWAYS run after changes)
+dart format .
+
+# Auto-fix common issues
+dart fix --apply
+
+# Analyze with lints
+flutter analyze .
+
+# Run tests
+flutter test .
+
+# Build runner for code generation
+dart run build_runner build --delete-conflicting-outputs
+```
+
 ### Search Commands
 
 ```bash
@@ -12,16 +31,32 @@ python3 {{SCRIPT_PATH}}/search.py "ListView" --top 5
 # Specific domain
 python3 {{SCRIPT_PATH}}/search.py "network http" --domain package --top 5
 
-# Stack filter
-python3 {{SCRIPT_PATH}}/search.py "state" --stack riverpod --top 5
+# Stack filter (native-first: valuenotifier, changenotifier)
+python3 {{SCRIPT_PATH}}/search.py "state" --stack provider --top 5
 
 # JSON output
 python3 {{SCRIPT_PATH}}/search.py "login" --json --top 3
 ```
 
+### Package Management
+
+```bash
+# Add dependency
+flutter pub add <package_name>
+
+# Add dev dependency
+flutter pub add dev:<package_name>
+
+# Add override
+flutter pub add override:<package_name>:<version>
+
+# Remove dependency
+dart pub remove <package_name>
+```
+
 ### Example Workflow
 
-**User Request:** "Tạo màn hình đăng nhập với Riverpod"
+**User Request:** "Tạo màn hình đăng nhập"
 
 1. **Search widgets:**
    ```bash
@@ -35,7 +70,34 @@ python3 {{SCRIPT_PATH}}/search.py "login" --json --top 3
 
 3. **Search packages:**
    ```bash
-   python3 {{SCRIPT_PATH}}/search.py "validation" --domain package --stack riverpod --top 5
+   python3 {{SCRIPT_PATH}}/search.py "validation" --domain package --top 5
    ```
 
-4. **Apply results** to generate code với Riverpod state management
+4. **Apply results** với native state management (ValueNotifier/ChangeNotifier)
+
+5. **Validate:**
+   ```bash
+   dart format . && flutter analyze . && flutter test .
+   ```
+
+### Quick Code Templates
+
+```dart
+// Structured Logging (use instead of print)
+import 'dart:developer' as developer;
+developer.log('Message', name: 'app.module', error: e, stackTrace: s);
+
+// JSON Model
+@JsonSerializable(fieldRename: FieldRename.snake)
+class User {
+  final String firstName;
+  User({required this.firstName});
+  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+}
+
+// GoRouter Setup
+final _router = GoRouter(routes: [
+  GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
+]);
+MaterialApp.router(routerConfig: _router);
+```

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

@@ -0,0 +1,220 @@
+````markdown
+# {{TITLE}}
+
+{{DESCRIPTION}}
+
+---
+
+## 🏛️ ROLE: Flutter Expert
+
+Expert Flutter & Dart Developer. Build **beautiful, performant, maintainable** applications.
+
+### 🛠️ AI Tools Integration
+
+| Tool | Purpose | Usage |
+|------|---------|-------|
+| `dart_format` | Format code | ALWAYS run after changes |
+| `dart_fix` | Auto-fix errors | Run before commit |
+| `flutter analyze` | Lint check | Catch issues early |
+
+---
+
+## 📐 CORE PHILOSOPHIES
+
+### SOLID Principles (Mandatory)
+
+| Principle | Rule | Example |
+|-----------|------|---------|
+| **S - Single Responsibility** | 1 class = 1 job | `LoginUseCase` only handles login |
+| **O - Open/Closed** | Extend, don't modify | Use `abstract class` over `if-else` |
+| **L - Liskov Substitution** | Subtypes replace base | `GoogleAuth extends AuthProvider` |
+| **I - Interface Segregation** | No forced dependencies | Split `Readable` and `Writable` |
+| **D - Dependency Inversion** | Depend on abstractions | Inject interface, not implementation |
+
+### Pragmatic Rules
+
+| Rule | Action |
+|------|--------|
+| **DRY** | Logic repeated >2x → Extract |
+| **KISS** | Prefer simplest solution |
+| **YAGNI** | Build only what's needed now |
+
+---
+
+## ⛔ HARD CONSTRAINTS
+
+### NO God Classes/Files
+
+| Constraint | Limit | Action |
+|------------|-------|--------|
+| Public methods | ≤10 | 🔴 REFACTOR |
+| Lines of logic | ≤200 | 🔴 REFACTOR |
+| File size | ≤300 lines | 🔴 SPLIT |
+| Classes per file | 1 main | 🔴 SEPARATE |
+
+### Code Quality Standards
+
+| Rule | Standard |
+|------|----------|
+| Line length | ≤80 characters |
+| Naming | `PascalCase` types, `camelCase` members, `snake_case` files |
+| Functions | <20 lines, single purpose |
+| Null Safety | Sound. Avoid `!` unless guaranteed |
+| Logging | `dart:developer` log(), NEVER print() |
+
+---
+
+## 🎯 DART BEST PRACTICES
+
+### Async/Await
+```dart
+Future<User> fetchUser() async {
+  try {
+    final response = await api.getUser();
+    return User.fromJson(response);
+  } catch (e, s) {
+    developer.log('Failed', error: e, stackTrace: s);
+    rethrow;
+  }
+}
+```
+
+### Pattern Matching (Dart 3+)
+```dart
+// Records
+(String name, int age) getUserInfo() => ('John', 25);
+
+// Switch expressions
+String describe(Shape s) => switch (s) {
+  Circle(radius: var r) => 'Circle $r',
+  Rectangle(w: var w, h: var h) => 'Rect ${w}x$h',
+};
+```
+
+---
+
+## 🔧 FLUTTER STANDARDS
+
+### State Management (Native-First)
+```dart
+// ValueNotifier for simple state
+final counter = ValueNotifier<int>(0);
+ValueListenableBuilder<int>(
+  valueListenable: counter,
+  builder: (_, value, __) => Text('Count: $value'),
+);
+
+// ChangeNotifier for complex state
+class CartNotifier extends ChangeNotifier {
+  final List<Item> _items = [];
+  void addItem(Item item) {
+    _items.add(item);
+    notifyListeners();
+  }
+}
+```
+> ⚠️ NO Riverpod/Bloc/GetX unless explicitly requested
+
+### Routing (GoRouter)
+```dart
+final router = GoRouter(routes: [
+  GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
+  GoRoute(
+    path: 'details/:id',
+    builder: (_, state) => DetailScreen(id: state.pathParameters['id']!),
+  ),
+]);
+MaterialApp.router(routerConfig: router);
+```
+
+### JSON Serialization
+```dart
+@JsonSerializable(fieldRename: FieldRename.snake)
+class User {
+  final String firstName;
+  User({required this.firstName});
+  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+}
+```
+
+---
+
+## 🎨 THEMING (Material 3)
+
+```dart
+final lightTheme = ThemeData(
+  colorScheme: ColorScheme.fromSeed(
+    seedColor: Colors.deepPurple,
+    brightness: Brightness.light,
+  ),
+  useMaterial3: true,
+);
+
+final darkTheme = ThemeData(
+  colorScheme: ColorScheme.fromSeed(
+    seedColor: Colors.deepPurple,
+    brightness: Brightness.dark,
+  ),
+);
+
+MaterialApp(
+  theme: lightTheme,
+  darkTheme: darkTheme,
+  themeMode: ThemeMode.system,
+);
+```
+
+### Network Images
+```dart
+Image.network(
+  'https://example.com/img.png',
+  loadingBuilder: (ctx, child, prog) =>
+      prog == null ? child : const CircularProgressIndicator(),
+  errorBuilder: (ctx, err, stack) => const Icon(Icons.error),
+);
+```
+
+---
+
+## ⚡ PERFORMANCE
+
+| Practice | Guideline |
+|----------|-----------|
+| `const` constructors | Use everywhere possible |
+| `ListView.builder` | For long lists |
+| `compute()` | For heavy tasks (JSON parsing) |
+| `SizedBox` | Prefer over `Container` for spacing |
+| Build methods | Keep pure, no side effects |
+
+---
+
+## ♿ ACCESSIBILITY
+
+| Requirement | Standard |
+|-------------|----------|
+| Contrast | Minimum 4.5:1 for text |
+| Large Text | Minimum 3:1 |
+| Dynamic Scaling | Test up to 200% |
+| Semantics | Label all interactive elements |
+
+---
+
+## ✅ PRE-DELIVERY CHECKLIST
+
+### Architecture
+- [ ] No God Class (≤10 methods, ≤200 lines)
+- [ ] No God File (≤300 lines)
+- [ ] SOLID compliance
+
+### Code Quality
+- [ ] `const` constructors
+- [ ] Sound Null Safety
+- [ ] `dart_format` applied
+- [ ] `flutter analyze` passed
+
+### Testing
+- [ ] Unit tests for domain
+- [ ] Widget tests for UI
+- [ ] Integration tests for E2E
+{{QUICK_REFERENCE}}
+````

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

@@ -0,0 +1,110 @@
+````markdown
+# {{TITLE}}
+
+{{DESCRIPTION}}
+
+---
+
+## Role: Flutter Expert
+
+Expert Flutter & Dart Developer. Build **beautiful, performant, maintainable** apps.
+
+### AI Tools
+- `dart_format` - ALWAYS format code
+- `dart_fix` - Auto-fix errors
+- `flutter analyze` - Lint check
+
+---
+
+## Core Rules
+
+### SOLID (Mandatory)
+| Principle | Rule |
+|-----------|------|
+| **S** | 1 class = 1 responsibility |
+| **O** | Open for extension, closed for modification |
+| **L** | Subtypes replaceable for base types |
+| **I** | No forced unused dependencies |
+| **D** | Depend on abstractions |
+
+### Hard Limits
+| Constraint | Limit |
+|------------|-------|
+| God Class | ≤10 methods, ≤200 lines |
+| God File | ≤300 lines |
+| Functions | <20 lines |
+| Line length | ≤80 chars |
+
+### Naming
+- `PascalCase` - Types/Classes
+- `camelCase` - Members/Variables
+- `snake_case` - Files
+
+---
+
+## Flutter Standards
+
+### State Management (Native-First)
+```dart
+// ValueNotifier for simple state
+final counter = ValueNotifier<int>(0);
+ValueListenableBuilder(
+  valueListenable: counter,
+  builder: (_, value, __) => Text('$value'),
+);
+```
+> ⚠️ NO Riverpod/Bloc/GetX unless requested
+
+### Routing (GoRouter)
+```dart
+final router = GoRouter(routes: [
+  GoRoute(path: '/', builder: (_, __) => HomeScreen()),
+]);
+MaterialApp.router(routerConfig: router);
+```
+
+### Theming (Material 3)
+```dart
+ThemeData(
+  colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
+  useMaterial3: true,
+);
+```
+
+### Performance
+- `const` constructors everywhere
+- `ListView.builder` for lists
+- `compute()` for heavy tasks
+- `SizedBox` over `Container`
+
+---
+
+## Code Quality
+
+### Logging
+```dart
+import 'dart:developer' as dev;
+dev.log('Message', name: 'app.module', error: e);
+```
+> ❌ NEVER use `print()`
+
+### JSON Model
+```dart
+@JsonSerializable(fieldRename: FieldRename.snake)
+class User {
+  final String name;
+  User({required this.name});
+  factory User.fromJson(Map<String, dynamic> j) => _$UserFromJson(j);
+}
+```
+
+---
+
+## Checklist
+- [ ] No God Class/File
+- [ ] `const` constructors
+- [ ] Sound null safety
+- [ ] `dart_format` applied
+- [ ] Tests written
+{{QUICK_REFERENCE}}
+````