theus-cli 0.2.83 → 0.2.85

package/vendor/theus-arsenal/skills/patrones-dart-flutter/SKILL.md

@@ -1,566 +0,0 @@
----
-name: patrones-dart-flutter
-description: Patrones de producción para Dart y Flutter — null safety, estado inmutable, composición
-  async, arquitectura de widgets, gestión de estado (BLoC, Riverpod, Provider), navegación con
-  GoRouter, networking con Dio, generación de código con Freezed y arquitectura limpia.
----
-
-# Patrones de Dart/Flutter
-
-## Cuándo usarla
-
-Usa esta skill cuando:
-- Empieces una funcionalidad nueva de Flutter y necesites patrones idiomáticos de gestión de estado, navegación o acceso a datos.
-- Revises o escribas código Dart y necesites guía sobre null safety, tipos sellados o composición async.
-- Montes un proyecto Flutter nuevo y debas elegir entre BLoC, Riverpod o Provider.
-- Implementes clientes HTTP seguros, integración de WebView o almacenamiento local.
-- Escribas tests para widgets de Flutter, Cubits o providers de Riverpod.
-- Configures GoRouter con guardas de autenticación.
-
-## Cómo funciona
-
-Esta skill provee patrones de código Dart/Flutter listos para copiar, organizados por tema:
-1. **Null safety** — evitar `!`, preferir `?.`/`??`/pattern matching
-2. **Estado inmutable** — clases selladas, `freezed`, `copyWith`
-3. **Composición async** — `Future.wait` concurrente, `BuildContext` seguro tras `await`
-4. **Arquitectura de widgets** — extraer a clases (no métodos), propagación de `const`, rebuilds acotados
-5. **Gestión de estado** — eventos de BLoC/Cubit, notifiers y providers derivados de Riverpod
-6. **Navegación** — GoRouter con guardas de auth reactivas vía `refreshListenable`
-7. **Networking** — Dio con interceptores, refresh de token con guarda de reintento único
-8. **Manejo de errores** — captura global, `ErrorWidget.builder`, cableado de reporte de crashes
-9. **Testing** — unitario (BLoC test), de widget (overrides de ProviderScope), fakes antes que mocks
-
-## Ejemplos
-
-```dart
-// Estado sellado — impide estados imposibles
-sealed class AsyncState<T> {}
-final class Loading<T> extends AsyncState<T> {}
-final class Success<T> extends AsyncState<T> { final T data; const Success(this.data); }
-final class Failure<T> extends AsyncState<T> { final Object error; const Failure(this.error); }
-
-// GoRouter con redirección de auth reactiva
-final router = GoRouter(
-  refreshListenable: GoRouterRefreshStream(authCubit.stream),
-  redirect: (context, state) {
-    final authed = context.read<AuthCubit>().state is AuthAuthenticated;
-    if (!authed && !state.matchedLocation.startsWith('/login')) return '/login';
-    return null;
-  },
-  routes: [...],
-);
-
-// Provider derivado de Riverpod con firstWhereOrNull seguro
-@riverpod
-double cartTotal(Ref ref) {
-  final cart = ref.watch(cartNotifierProvider);
-  final products = ref.watch(productsProvider).valueOrNull ?? [];
-  return cart.fold(0.0, (total, item) {
-    final product = products.firstWhereOrNull((p) => p.id == item.productId);
-    return total + (product?.price ?? 0) * item.quantity;
-  });
-}
-```
-
----
-
-Patrones prácticos, listos para producción, para aplicaciones Dart y Flutter. Agnósticos de librería donde es posible, con cobertura explícita de los paquetes más comunes del ecosistema.
-
----
-
-## 1. Fundamentos de null safety
-
-### Prefiere patrones sobre el operador bang
-
-```dart
-// MAL — revienta en runtime si es null
-final name = user!.name;
-
-// BIEN — provee un valor por defecto
-final name = user?.name ?? 'Desconocido';
-
-// BIEN — pattern matching de Dart 3 (preferido para casos complejos)
-final display = switch (user) {
-  User(:final name, :final email) => '$name <$email>',
-  null => 'Invitado',
-};
-
-// BIEN — guarda con retorno temprano
-String getUserName(User? user) {
-  if (user == null) return 'Desconocido';
-  return user.name; // promovido a no-nulo tras la comprobación
-}
-```
-
-### Evita abusar de `late`
-
-```dart
-// MAL — difiere el error de null al runtime
-late String userId;
-
-// BIEN — nullable con inicialización explícita
-String? userId;
-
-// OK — usa late solo cuando la inicialización está garantizada antes del primer acceso
-// (p. ej., en initState() antes de cualquier interacción con el widget)
-late final AnimationController _controller;
-
-@override
-void initState() {
-  super.initState();
-  _controller = AnimationController(vsync: this, duration: const Duration(milliseconds: 300));
-}
-```
-
----
-
-## 2. Estado inmutable
-
-### Clases selladas para jerarquías de estado
-
-```dart
-sealed class UserState {}
-
-final class UserInitial extends UserState {}
-
-final class UserLoading extends UserState {}
-
-final class UserLoaded extends UserState {
-  const UserLoaded(this.user);
-  final User user;
-}
-
-final class UserError extends UserState {
-  const UserError(this.message);
-  final String message;
-}
-
-// Switch exhaustivo — el compilador exige todas las ramas
-Widget buildFrom(UserState state) => switch (state) {
-  UserInitial() => const SizedBox.shrink(),
-  UserLoading() => const CircularProgressIndicator(),
-  UserLoaded(:final user) => UserCard(user: user),
-  UserError(:final message) => ErrorText(message),
-};
-```
-
-### Freezed para inmutabilidad sin boilerplate
-
-```dart
-import 'package:freezed_annotation/freezed_annotation.dart';
-
-part 'user.freezed.dart';
-part 'user.g.dart';
-
-@freezed
-class User with _$User {
-  const factory User({
-    required String id,
-    required String name,
-    required String email,
-    @Default(false) bool isAdmin,
-  }) = _User;
-
-  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
-}
-
-// Uso
-final user = User(id: '1', name: 'Alice', email: 'alice@example.com');
-final updated = user.copyWith(name: 'Alice Smith'); // actualización inmutable
-final json = user.toJson();
-final fromJson = User.fromJson(json);
-```
-
----
-
-## 3. Composición async
-
-### Concurrencia estructurada con Future.wait
-
-```dart
-Future<DashboardData> loadDashboard(UserRepository users, OrderRepository orders) async {
-  // Ejecutar en concurrencia — no esperar en secuencia
-  final (userList, orderList) = await (
-    users.getAll(),
-    orders.getRecent(),
-  ).wait; // destructuring de records de Dart 3 + extensión Future.wait
-
-  return DashboardData(users: userList, orders: orderList);
-}
-```
-
-### Patrones de streams
-
-```dart
-// El repositorio expone streams reactivos para datos en vivo
-Stream<List<Item>> watchCartItems() => _db
-    .watchTable('cart_items')
-    .map((rows) => rows.map(Item.fromRow).toList());
-
-// En la capa de widgets — declarativo, sin suscripción manual
-StreamBuilder<List<Item>>(
-  stream: cartRepository.watchCartItems(),
-  builder: (context, snapshot) => switch (snapshot) {
-    AsyncSnapshot(connectionState: ConnectionState.waiting) =>
-        const CircularProgressIndicator(),
-    AsyncSnapshot(:final error?) => ErrorWidget(error.toString()),
-    AsyncSnapshot(:final data?) => CartList(items: data),
-    _ => const SizedBox.shrink(),
-  },
-)
-```
-
-### BuildContext después de un await
-
-```dart
-// CRÍTICO — comprueba siempre mounted tras cualquier await en un StatefulWidget
-Future<void> _handleSubmit() async {
-  setState(() => _isLoading = true);
-  try {
-    await authService.login(_email, _password);
-    if (!mounted) return; // ← guarda antes de usar context
-    context.go('/home');
-  } on AuthException catch (e) {
-    if (!mounted) return;
-    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(e.message)));
-  } finally {
-    if (mounted) setState(() => _isLoading = false);
-  }
-}
-```
-
----
-
-## 4. Arquitectura de widgets
-
-### Extrae a clases, no a métodos
-
-```dart
-// MAL — método privado que devuelve un widget, impide optimizaciones
-Widget _buildHeader() {
-  return Container(
-    padding: const EdgeInsets.all(16),
-    child: Text(title, style: Theme.of(context).textTheme.headlineMedium),
-  );
-}
-
-// BIEN — clase de widget separada, habilita const y reutilización del element
-class _PageHeader extends StatelessWidget {
-  const _PageHeader(this.title);
-  final String title;
-
-  @override
-  Widget build(BuildContext context) {
-    return Container(
-      padding: const EdgeInsets.all(16),
-      child: Text(title, style: Theme.of(context).textTheme.headlineMedium),
-    );
-  }
-}
-```
-
-### Propagación de const
-
-```dart
-// MAL — instancias nuevas en cada rebuild
-child: Padding(
-  padding: EdgeInsets.all(16.0),       // no es const
-  child: Icon(Icons.home, size: 24.0), // no es const
-)
-
-// BIEN — const frena la propagación de rebuilds
-child: const Padding(
-  padding: EdgeInsets.all(16.0),
-  child: Icon(Icons.home, size: 24.0),
-)
-```
-
-### Rebuilds acotados
-
-```dart
-// MAL — la página entera se reconstruye con cada cambio del contador
-class CounterPage extends ConsumerWidget {
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final count = ref.watch(counterProvider); // reconstruye todo
-    return Scaffold(
-      body: Column(children: [
-        const ExpensiveHeader(), // reconstruido sin necesidad
-        Text('$count'),
-        const ExpensiveFooter(), // reconstruido sin necesidad
-      ]),
-    );
-  }
-}
-
-// BIEN — aísla la parte que se reconstruye
-class CounterPage extends StatelessWidget {
-  const CounterPage({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    return const Scaffold(
-      body: Column(children: [
-        ExpensiveHeader(),        // nunca se reconstruye (const)
-        _CounterDisplay(),        // solo esto se reconstruye
-        ExpensiveFooter(),        // nunca se reconstruye (const)
-      ]),
-    );
-  }
-}
-
-class _CounterDisplay extends ConsumerWidget {
-  const _CounterDisplay();
-
-  @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final count = ref.watch(counterProvider);
-    return Text('$count');
-  }
-}
-```
-
----
-
-## 5. Gestión de estado: BLoC/Cubit
-
-```dart
-// Cubit — estado síncrono o async simple
-class AuthCubit extends Cubit<AuthState> {
-  AuthCubit(this._authService) : super(const AuthState.initial());
-  final AuthService _authService;
-
-  Future<void> login(String email, String password) async {
-    emit(const AuthState.loading());
-    try {
-      final user = await _authService.login(email, password);
-      emit(AuthState.authenticated(user));
-    } on AuthException catch (e) {
-      emit(AuthState.error(e.message));
-    }
-  }
-
-  void logout() {
-    _authService.logout();
-    emit(const AuthState.initial());
-  }
-}
-
-// En el widget
-BlocBuilder<AuthCubit, AuthState>(
-  builder: (context, state) => switch (state) {
-    AuthInitial() => const LoginForm(),
-    AuthLoading() => const CircularProgressIndicator(),
-    AuthAuthenticated(:final user) => HomePage(user: user),
-    AuthError(:final message) => ErrorView(message: message),
-  },
-)
-```
-
----
-
-## 6. Gestión de estado: Riverpod
-
-```dart
-// Provider async con auto-dispose
-@riverpod
-Future<List<Product>> products(Ref ref) async {
-  final repo = ref.watch(productRepositoryProvider);
-  return repo.getAll();
-}
-
-// Notifier con mutaciones complejas
-@riverpod
-class CartNotifier extends _$CartNotifier {
-  @override
-  List<CartItem> build() => [];
-
-  void add(Product product) {
-    final existing = state.where((i) => i.productId == product.id).firstOrNull;
-    if (existing != null) {
-      state = [
-        for (final item in state)
-          if (item.productId == product.id) item.copyWith(quantity: item.quantity + 1)
-          else item,
-      ];
-    } else {
-      state = [...state, CartItem(productId: product.id, quantity: 1)];
-    }
-  }
-
-  void remove(String productId) =>
-      state = state.where((i) => i.productId != productId).toList();
-
-  void clear() => state = [];
-}
-
-// Provider derivado (patrón selector)
-@riverpod
-int cartCount(Ref ref) => ref.watch(cartNotifierProvider).length;
-
-@riverpod
-double cartTotal(Ref ref) {
-  final cart = ref.watch(cartNotifierProvider);
-  final products = ref.watch(productsProvider).valueOrNull ?? [];
-  return cart.fold(0.0, (total, item) {
-    // firstWhereOrNull (del paquete collection) evita StateError si falta el producto
-    final product = products.firstWhereOrNull((p) => p.id == item.productId);
-    return total + (product?.price ?? 0) * item.quantity;
-  });
-}
-```
-
----
-
-## 7. Navegación con GoRouter
-
-```dart
-final router = GoRouter(
-  initialLocation: '/',
-  // refreshListenable reevalúa redirect cuando cambia el estado de auth
-  refreshListenable: GoRouterRefreshStream(authCubit.stream),
-  redirect: (context, state) {
-    final isLoggedIn = context.read<AuthCubit>().state is AuthAuthenticated;
-    final isGoingToLogin = state.matchedLocation == '/login';
-    if (!isLoggedIn && !isGoingToLogin) return '/login';
-    if (isLoggedIn && isGoingToLogin) return '/';
-    return null;
-  },
-  routes: [
-    GoRoute(path: '/login', builder: (_, __) => const LoginPage()),
-    ShellRoute(
-      builder: (context, state, child) => AppShell(child: child),
-      routes: [
-        GoRoute(path: '/', builder: (_, __) => const HomePage()),
-        GoRoute(
-          path: '/products/:id',
-          builder: (context, state) =>
-              ProductDetailPage(id: state.pathParameters['id']!),
-        ),
-      ],
-    ),
-  ],
-);
-```
-
----
-
-## 8. HTTP con Dio
-
-```dart
-final dio = Dio(BaseOptions(
-  baseUrl: const String.fromEnvironment('API_URL'),
-  connectTimeout: const Duration(seconds: 10),
-  receiveTimeout: const Duration(seconds: 30),
-  headers: {'Content-Type': 'application/json'},
-));
-
-// Interceptor de autenticación
-dio.interceptors.add(InterceptorsWrapper(
-  onRequest: (options, handler) async {
-    final token = await secureStorage.read(key: 'auth_token');
-    if (token != null) options.headers['Authorization'] = 'Bearer $token';
-    handler.next(options);
-  },
-  onError: (error, handler) async {
-    // Guarda contra bucles infinitos de reintento: solo un intento de refresh por petición
-    final isRetry = error.requestOptions.extra['_isRetry'] == true;
-    if (!isRetry && error.response?.statusCode == 401) {
-      final refreshed = await attemptTokenRefresh();
-      if (refreshed) {
-        error.requestOptions.extra['_isRetry'] = true;
-        return handler.resolve(await dio.fetch(error.requestOptions));
-      }
-    }
-    handler.next(error);
-  },
-));
-
-// Repositorio usando Dio
-class UserApiDataSource {
-  const UserApiDataSource(this._dio);
-  final Dio _dio;
-
-  Future<User> getById(String id) async {
-    final response = await _dio.get<Map<String, dynamic>>('/users/$id');
-    return User.fromJson(response.data!);
-  }
-}
-```
-
----
-
-## 9. Arquitectura de manejo de errores
-
-```dart
-// Captura global de errores — configúrala en main()
-void main() {
-  FlutterError.onError = (details) {
-    FlutterError.presentError(details);
-    crashlytics.recordFlutterFatalError(details);
-  };
-
-  PlatformDispatcher.instance.onError = (error, stack) {
-    crashlytics.recordError(error, stack, fatal: true);
-    return true;
-  };
-
-  runApp(const App());
-}
-
-// ErrorWidget personalizado para producción
-class App extends StatelessWidget {
-  @override
-  Widget build(BuildContext context) {
-    ErrorWidget.builder = (details) => ProductionErrorWidget(details);
-    return MaterialApp.router(routerConfig: router);
-  }
-}
-```
-
----
-
-## 10. Referencia rápida de testing
-
-```dart
-// Test unitario — caso de uso
-test('GetUserUseCase devuelve null para un usuario inexistente', () async {
-  final repo = FakeUserRepository();
-  final useCase = GetUserUseCase(repo);
-  expect(await useCase('missing-id'), isNull);
-});
-
-// Test de BLoC
-blocTest<AuthCubit, AuthState>(
-  'emite loading y luego error ante un login fallido',
-  build: () => AuthCubit(FakeAuthService(throwsOn: 'login')),
-  act: (cubit) => cubit.login('user@test.com', 'wrong'),
-  expect: () => [const AuthState.loading(), isA<AuthError>()],
-);
-
-// Test de widget
-testWidgets('CartBadge muestra la cantidad de ítems', (tester) async {
-  await tester.pumpWidget(
-    ProviderScope(
-      overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier(count: 3))],
-      child: const MaterialApp(home: CartBadge()),
-    ),
-  );
-  expect(find.text('3'), findsOneWidget);
-});
-```
-
----
-
-## Referencias
-
-- [Effective Dart: Design](https://dart.dev/effective-dart/design)
-- [Buenas prácticas de rendimiento de Flutter](https://docs.flutter.dev/perf/best-practices)
-- [Documentación de Riverpod](https://riverpod.dev/)
-- [Librería BLoC](https://bloclibrary.dev/)
-- [GoRouter](https://pub.dev/packages/go_router)
-- [Freezed](https://pub.dev/packages/freezed)
-
-## Skills relacionadas
-
-- `revision-codigo-flutter-dart` — checklist completo de revisión