oh-my-customcode 0.30.7 → 0.30.9

package/templates/guides/flutter/index.yaml

@@ -0,0 +1,44 @@
+# Flutter Guide
+
+metadata:
+  name: flutter
+  description: Flutter cross-platform development reference documentation
+
+source:
+  type: external
+  origin: flutter.dev
+  urls:
+    - https://docs.flutter.dev/
+    - https://docs.flutter.dev/app-architecture
+    - https://riverpod.dev/docs/introduction/getting_started
+    - https://bloclibrary.dev/
+    - https://dart.dev/effective-dart
+  last_fetched: "2026-03-11"
+
+documents:
+  - name: fundamentals
+    path: ./fundamentals.md
+    description: Flutter widget system, BuildContext, rendering pipeline
+
+  - name: state-management
+    path: ./state-management.md
+    description: Riverpod 3.0, BLoC 9.0, Provider patterns and selection guide
+
+  - name: architecture
+    path: ./architecture.md
+    description: MVVM structure, project organization, go_router, freezed
+
+  - name: performance
+    path: ./performance.md
+    description: DevTools, const optimization, RepaintBoundary, Isolate
+
+  - name: testing
+    path: ./testing.md
+    description: Widget tests, golden tests, integration tests, mocking
+
+  - name: security
+    path: ./security.md
+    description: OWASP Mobile Top 10, secure storage, certificate pinning, platform security
+
+used_by:
+  - fe-flutter-agent

package/templates/guides/flutter/performance.md

@@ -0,0 +1,119 @@
+# Flutter Performance
+
+> Reference: docs.flutter.dev/perf/best-practices
+
+## Frame Budget
+
+- Target: **<8ms build + <8ms render = 16.67ms** (60fps)
+- Profile with: `flutter run --profile` (not debug mode)
+- Tool: DevTools Performance view → identify jank frames
+
+## Build-Time Optimization
+
+### const Constructors
+
+```dart
+// GOOD — zero rebuild cost
+const Text('Hello');
+const SizedBox(height: 8);
+const Icon(Icons.star);
+
+// BAD — new instance every build
+Text('Hello');
+SizedBox(height: 8);
+```
+
+### Localize setState
+
+```dart
+// BAD — rebuilds entire screen
+class _ScreenState extends State<Screen> {
+  int count = 0;
+  Widget build(BuildContext context) {
+    return Column(children: [
+      ExpensiveHeader(), // rebuilt unnecessarily
+      Text('$count'),
+      ElevatedButton(onPressed: () => setState(() => count++), child: Text('+'))
+    ]);
+  }
+}
+
+// GOOD — only counter rebuilds
+class _ScreenState extends State<Screen> {
+  Widget build(BuildContext context) {
+    return Column(children: [
+      const ExpensiveHeader(), // not rebuilt
+      CounterWidget(), // isolated StatefulWidget
+    ]);
+  }
+}
+```
+
+### Extract Widgets (not methods)
+
+```dart
+// BAD — no Element identity, always rebuilds
+Widget _buildHeader() => Container(...);
+
+// GOOD — has Element identity, diffed efficiently
+class HeaderWidget extends StatelessWidget {
+  const HeaderWidget({super.key});
+  @override
+  Widget build(BuildContext context) => Container(...);
+}
+```
+
+## Rendering Optimization
+
+### RepaintBoundary
+
+```dart
+// Wrap frequently repainting subtrees
+RepaintBoundary(
+  child: AnimatedWidget(...), // only this subtree repaints
+)
+```
+
+Detect with: DevTools → Rendering → "Highlight repaints"
+
+### Avoid Expensive Widgets
+
+| Avoid | Use Instead | Reason |
+|-------|-------------|--------|
+| `Opacity` widget | `color.withValues(alpha: 0.5)` | Opacity widget triggers saveLayer |
+| `ClipRRect` in animations | Pre-clip static content | saveLayer per frame |
+| `Container` for sizing | `SizedBox` | Lighter, no decoration |
+
+## List Performance
+
+```dart
+// GOOD — lazy construction, O(visible) not O(total)
+ListView.builder(
+  itemCount: items.length,
+  itemExtent: 72.0, // skip intrinsic layout passes
+  itemBuilder: (context, index) => ProductTile(items[index]),
+);
+
+// BAD — builds ALL children upfront
+ListView(children: items.map((i) => ProductTile(i)).toList());
+```
+
+## Compute Offloading
+
+```dart
+// CPU-intensive work (>16ms) on isolate
+final result = await Isolate.run(() {
+  return heavyJsonParsing(rawData);
+});
+
+// Web-compatible alternative
+final result = await compute(heavyJsonParsing, rawData);
+```
+
+## DevTools Workflow
+
+1. **Inspector** → identify widget causing rebuild
+2. **Performance view** → identify jank frames (>16ms)
+3. **CPU Profiler** → identify expensive Dart methods
+4. **Memory view** → detect object leaks
+5. **Network** → monitor API call timing

package/templates/guides/flutter/state-management.md

@@ -0,0 +1,144 @@
+# Flutter State Management
+
+> Reference: riverpod.dev, bloclibrary.dev, docs.flutter.dev/data-and-backend/state-mgmt
+
+## Selection Guide
+
+| Approach | Complexity | Scalability | Best For |
+|----------|-----------|-------------|----------|
+| **Riverpod 3.0** | Medium | Excellent | New projects (default) |
+| **BLoC 9.0** | High | Excellent | Enterprise, regulated industries |
+| **Provider** | Low | Moderate | Simple apps, learning |
+| **setState** | Low | Poor | Ephemeral local UI state |
+| **GetX** | Low | Poor | **AVOID** for new projects |
+
+## Riverpod 3.0 (Default)
+
+### Provider Types
+
+```dart
+// Simple value provider
+@riverpod
+String greeting(Ref ref) => 'Hello, World!';
+
+// Async data provider
+@riverpod
+Future<List<Product>> products(Ref ref) async {
+  final api = ref.watch(apiClientProvider);
+  return api.getProducts();
+}
+
+// Stateful notifier
+@riverpod
+class Counter extends _$Counter {
+  @override
+  int build() => 0;
+
+  void increment() => state++;
+  void decrement() => state--;
+}
+
+// Async stateful notifier
+@riverpod
+class ProductList extends _$ProductList {
+  @override
+  Future<List<Product>> build() async {
+    return ref.watch(productRepositoryProvider).getAll();
+  }
+
+  Future<void> addProduct(Product product) async {
+    await ref.read(productRepositoryProvider).add(product);
+    ref.invalidateSelf();
+  }
+}
+```
+
+### UI Consumption
+
+```dart
+class ProductListScreen extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final state = ref.watch(productListProvider);
+
+    return state.when(
+      loading: () => const CircularProgressIndicator(),
+      error: (e, st) => Text('Error: $e'),
+      data: (products) => ListView.builder(
+        itemCount: products.length,
+        itemBuilder: (_, i) => ProductCard(products[i]),
+      ),
+    );
+  }
+}
+```
+
+### Key Rules
+
+- `ref.watch()` in build methods only (reactive)
+- `ref.read()` in callbacks and event handlers (one-time)
+- Never call `ref.watch()` inside non-build methods
+- Use `family` for parameterized providers
+- Use `keepAlive` sparingly (expensive computations only)
+
+## BLoC 9.0 (Enterprise)
+
+### Cubit (Simple)
+
+```dart
+class CounterCubit extends Cubit<int> {
+  CounterCubit() : super(0);
+
+  void increment() => emit(state + 1);
+  void decrement() => emit(state - 1);
+}
+
+// UI
+BlocBuilder<CounterCubit, int>(
+  builder: (context, count) => Text('$count'),
+)
+```
+
+### Bloc (Full Events)
+
+```dart
+// Events
+sealed class AuthEvent {}
+class LoginRequested extends AuthEvent {
+  final String email, password;
+  LoginRequested(this.email, this.password);
+}
+
+// States
+sealed class AuthState {}
+class AuthInitial extends AuthState {}
+class AuthLoading extends AuthState {}
+class AuthSuccess extends AuthState { final User user; AuthSuccess(this.user); }
+class AuthFailure extends AuthState { final String error; AuthFailure(this.error); }
+
+// Bloc
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  AuthBloc(this._authRepo) : super(AuthInitial()) {
+    on<LoginRequested>(_onLogin);
+  }
+
+  final AuthRepository _authRepo;
+
+  Future<void> _onLogin(LoginRequested event, Emitter<AuthState> emit) async {
+    emit(AuthLoading());
+    final result = await _authRepo.login(event.email, event.password);
+    switch (result) {
+      case Ok(:final value): emit(AuthSuccess(value));
+      case Error(:final error): emit(AuthFailure(error.toString()));
+    }
+  }
+}
+```
+
+### Key Rules
+
+- One event per user action
+- Cubit for simple state, Bloc when audit trail needed
+- Never emit state in constructor
+- `BlocListener` for side effects, `BlocBuilder` for UI
+- Cancel subscriptions in `close()`

package/templates/guides/flutter/testing.md

@@ -0,0 +1,155 @@
+# Flutter Testing
+
+> Reference: docs.flutter.dev/testing/overview
+
+## Test Pyramid
+
+| Level | Speed | Confidence | Tool |
+|-------|-------|------------|------|
+| Unit | Fast | Low | `flutter_test` |
+| Widget | Fast | Medium | `testWidgets`, `WidgetTester` |
+| Integration | Slow | High | `integration_test` package |
+| Golden | Fast | Visual | `matchesGoldenFile()` |
+
+## Widget Tests (Primary)
+
+```dart
+testWidgets('ProductCard displays name and price', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(
+      home: ProductCard(
+        product: Product(id: 1, name: 'Widget', price: 9.99),
+      ),
+    ),
+  );
+
+  expect(find.text('Widget'), findsOneWidget);
+  expect(find.text('\$9.99'), findsOneWidget);
+});
+
+testWidgets('tapping add button calls onAdd', (tester) async {
+  var called = false;
+  await tester.pumpWidget(
+    MaterialApp(
+      home: AddButton(onAdd: () => called = true),
+    ),
+  );
+
+  await tester.tap(find.byType(ElevatedButton));
+  expect(called, isTrue);
+});
+```
+
+## Riverpod Testing
+
+```dart
+testWidgets('ProductListScreen shows products', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        productListProvider.overrideWith(
+          () => FakeProductListNotifier(),
+        ),
+      ],
+      child: const MaterialApp(home: ProductListScreen()),
+    ),
+  );
+
+  await tester.pumpAndSettle();
+  expect(find.byType(ProductCard), findsNWidgets(3));
+});
+```
+
+## BLoC Testing
+
+```dart
+blocTest<CounterCubit, int>(
+  'increment emits [1] when initial state is 0',
+  build: () => CounterCubit(),
+  act: (cubit) => cubit.increment(),
+  expect: () => [1],
+);
+
+blocTest<AuthBloc, AuthState>(
+  'login emits [loading, success] on valid credentials',
+  build: () => AuthBloc(FakeAuthRepository()),
+  act: (bloc) => bloc.add(LoginRequested('user@test.com', 'pass123')),
+  expect: () => [
+    isA<AuthLoading>(),
+    isA<AuthSuccess>(),
+  ],
+);
+```
+
+## Mocking with mocktail
+
+```dart
+class MockProductRepository extends Mock implements ProductRepository {}
+
+void main() {
+  late MockProductRepository mockRepo;
+
+  setUp(() {
+    mockRepo = MockProductRepository();
+  });
+
+  test('getProducts returns list', () async {
+    when(() => mockRepo.getAll()).thenAnswer(
+      (_) async => Ok([Product(id: 1, name: 'Test', price: 9.99)]),
+    );
+
+    final result = await mockRepo.getAll();
+    expect(result, isA<Ok<List<Product>>>());
+  });
+}
+```
+
+## Golden Tests
+
+```dart
+testWidgets('ProductCard matches golden', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(
+      home: ProductCard(product: testProduct),
+    ),
+  );
+
+  await expectLater(
+    find.byType(ProductCard),
+    matchesGoldenFile('goldens/product_card.png'),
+  );
+});
+
+// Update goldens: flutter test --update-goldens
+```
+
+## Accessibility Testing
+
+```dart
+testWidgets('meets accessibility guidelines', (tester) async {
+  final handle = tester.ensureSemantics();
+  await tester.pumpWidget(const MaterialApp(home: MyScreen()));
+
+  await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(textContrastGuideline));
+
+  handle.dispose();
+});
+```
+
+## Test Organization
+
+```
+test/
+├── unit/
+│   ├── repositories/product_repository_test.dart
+│   └── viewmodels/home_viewmodel_test.dart
+├── widget/
+│   ├── screens/product_list_screen_test.dart
+│   └── widgets/product_card_test.dart
+├── goldens/
+│   └── product_card.png
+integration_test/
+└── app_test.dart
+```

package/templates/guides/index.yaml

@@ -9,6 +9,14 @@ guides:
       type: internal
 
   # Frontend
+  - name: flutter
+    description: Flutter/Dart development patterns and best practices
+    path: ./flutter/
+    source:
+      type: external
+      origin: flutter.dev
+      url: https://docs.flutter.dev/
+
   - name: web-design
     description: Web design best practices and accessibility reference
     path: ./web-design/

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.30.7",
+  "version": "0.30.9",
   "lastUpdated": "2026-03-09T00:00:00.000Z",
   "components": [
     {
@@ -12,19 +12,19 @@
       "name": "agents",
       "path": ".claude/agents",
       "description": "AI agent definitions (flat .md files with prefixes)",
-      "files": 43
+      "files": 44
     },
     {
       "name": "skills",
       "path": ".claude/skills",
       "description": "Reusable skill modules (includes slash commands)",
-      "files": 67
+      "files": 68
     },
     {
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 23
+      "files": 24
     },
     {
       "name": "hooks",