theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/rules/dart/patterns.md

@@ -0,0 +1,261 @@
+---
+paths:
+  - "**/*.dart"
+  - "**/pubspec.yaml"
+---
+# Patrones de Dart/Flutter
+
+> Este archivo extiende [common/patterns.md](../common/patterns.md) con contenido específico de Dart, Flutter y su ecosistema habitual.
+
+## Patrón Repository
+
+```dart
+abstract interface class UserRepository {
+  Future<User?> getById(String id);
+  Future<List<User>> getAll();
+  Stream<List<User>> watchAll();
+  Future<void> save(User user);
+  Future<void> delete(String id);
+}
+
+class UserRepositoryImpl implements UserRepository {
+  const UserRepositoryImpl(this._remote, this._local);
+
+  final UserRemoteDataSource _remote;
+  final UserLocalDataSource _local;
+
+  @override
+  Future<User?> getById(String id) async {
+    final local = await _local.getById(id);
+    if (local != null) return local;
+    final remote = await _remote.getById(id);
+    if (remote != null) await _local.save(remote);
+    return remote;
+  }
+
+  @override
+  Future<List<User>> getAll() async {
+    final remote = await _remote.getAll();
+    for (final user in remote) {
+      await _local.save(user);
+    }
+    return remote;
+  }
+
+  @override
+  Stream<List<User>> watchAll() => _local.watchAll();
+
+  @override
+  Future<void> save(User user) => _local.save(user);
+
+  @override
+  Future<void> delete(String id) async {
+    await _remote.delete(id);
+    await _local.delete(id);
+  }
+}
+```
+
+## Gestión de estado: BLoC/Cubit
+
+```dart
+// Cubit — transiciones de estado simples
+class CounterCubit extends Cubit<int> {
+  CounterCubit() : super(0);
+
+  void increment() => emit(state + 1);
+  void decrement() => emit(state - 1);
+}
+
+// BLoC — dirigido por eventos
+@immutable
+sealed class CartEvent {}
+class CartItemAdded extends CartEvent { CartItemAdded(this.item); final Item item; }
+class CartItemRemoved extends CartEvent { CartItemRemoved(this.id); final String id; }
+class CartCleared extends CartEvent {}
+
+@immutable
+class CartState {
+  const CartState({this.items = const []});
+  final List<Item> items;
+  CartState copyWith({List<Item>? items}) => CartState(items: items ?? this.items);
+}
+
+class CartBloc extends Bloc<CartEvent, CartState> {
+  CartBloc() : super(const CartState()) {
+    on<CartItemAdded>((event, emit) =>
+        emit(state.copyWith(items: [...state.items, event.item])));
+    on<CartItemRemoved>((event, emit) =>
+        emit(state.copyWith(items: state.items.where((i) => i.id != event.id).toList())));
+    on<CartCleared>((_, emit) => emit(const CartState()));
+  }
+}
+```
+
+## Gestión de estado: Riverpod
+
+```dart
+// Provider simple
+@riverpod
+Future<List<User>> users(Ref ref) async {
+  final repo = ref.watch(userRepositoryProvider);
+  return repo.getAll();
+}
+
+// Notifier para estado mutable
+@riverpod
+class CartNotifier extends _$CartNotifier {
+  @override
+  List<Item> build() => [];
+
+  void add(Item item) => state = [...state, item];
+  void remove(String id) => state = state.where((i) => i.id != id).toList();
+  void clear() => state = [];
+}
+
+// ConsumerWidget
+class CartPage extends ConsumerWidget {
+  const CartPage({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final items = ref.watch(cartNotifierProvider);
+    return ListView(
+      children: items.map((item) => CartItemTile(item: item)).toList(),
+    );
+  }
+}
+```
+
+## Inyección de dependencias
+
+Se prefiere la inyección por constructor. Usa `get_it` o providers de Riverpod en la raíz de composición:
+
+```dart
+// Registro con get_it (en un archivo de configuración)
+void setupDependencies() {
+  final di = GetIt.instance;
+  di.registerSingleton<ApiClient>(ApiClient(baseUrl: Env.apiUrl));
+  di.registerSingleton<UserRepository>(
+    UserRepositoryImpl(di<ApiClient>(), di<LocalDatabase>()),
+  );
+  di.registerFactory(() => UserListViewModel(di<UserRepository>()));
+}
+```
+
+## Patrón ViewModel (sin BLoC/Riverpod)
+
+```dart
+class UserListViewModel extends ChangeNotifier {
+  UserListViewModel(this._repository);
+
+  final UserRepository _repository;
+
+  AsyncState<List<User>> _state = const Loading();
+  AsyncState<List<User>> get state => _state;
+
+  Future<void> load() async {
+    _state = const Loading();
+    notifyListeners();
+    try {
+      final users = await _repository.getAll();
+      _state = Success(users);
+    } on Exception catch (e) {
+      _state = Failure(e);
+    }
+    notifyListeners();
+  }
+}
+```
+
+## Patrón UseCase
+
+```dart
+class GetUserUseCase {
+  const GetUserUseCase(this._repository);
+  final UserRepository _repository;
+
+  Future<User?> call(String id) => _repository.getById(id);
+}
+
+class CreateUserUseCase {
+  const CreateUserUseCase(this._repository, this._idGenerator);
+  final UserRepository _repository;
+  final IdGenerator _idGenerator; // inyectado — la capa de dominio no debe depender del paquete uuid directamente
+
+  Future<void> call(CreateUserInput input) async {
+    // Validar, aplicar las reglas de negocio y luego persistir
+    final user = User(id: _idGenerator.generate(), name: input.name, email: input.email);
+    await _repository.save(user);
+  }
+}
+```
+
+## Estado inmutable con freezed
+
+```dart
+@freezed
+class UserState with _$UserState {
+  const factory UserState({
+    @Default([]) List<User> users,
+    @Default(false) bool isLoading,
+    String? errorMessage,
+  }) = _UserState;
+}
+```
+
+## Límites de capas de Clean Architecture
+
+```
+lib/
+├── domain/              # Dart puro — sin Flutter, sin paquetes externos
+│   ├── entities/
+│   ├── repositories/    # Interfaces abstractas
+│   └── usecases/
+├── data/                # Implementa las interfaces del dominio
+│   ├── datasources/
+│   ├── models/          # DTOs con fromJson/toJson
+│   └── repositories/
+└── presentation/        # Widgets de Flutter + gestión de estado
+    ├── pages/
+    ├── widgets/
+    └── providers/ (o blocs/ o viewmodels/)
+```
+
+- El dominio no debe importar `package:flutter` ni ningún paquete de la capa de datos
+- La capa de datos mapea los DTO a entidades de dominio en los límites de los repositorios
+- La presentación llama a los casos de uso, no a los repositorios directamente
+
+## Navegación (GoRouter)
+
+```dart
+final router = GoRouter(
+  routes: [
+    GoRoute(
+      path: '/',
+      builder: (context, state) => const HomePage(),
+    ),
+    GoRoute(
+      path: '/users/:id',
+      builder: (context, state) {
+        final id = state.pathParameters['id']!;
+        return UserDetailPage(userId: id);
+      },
+    ),
+  ],
+  // refreshListenable reevalúa redirect cada vez que cambia el estado de autenticación
+  refreshListenable: GoRouterRefreshStream(authCubit.stream),
+  redirect: (context, state) {
+    final isLoggedIn = context.read<AuthCubit>().state is AuthAuthenticated;
+    if (!isLoggedIn && !state.matchedLocation.startsWith('/login')) {
+      return '/login';
+    }
+    return null;
+  },
+);
+```
+
+## Referencias
+
+Consulta la skill `revision-codigo-flutter-dart` para el checklist de revisión completo.
+Consulta la skill `patrones-compose-multiplatform` para patrones de interoperabilidad Kotlin Multiplatform/Flutter.

package/vendor/theus-arsenal/rules/dart/security.md

@@ -0,0 +1,135 @@
+---
+paths:
+  - "**/*.dart"
+  - "**/pubspec.yaml"
+  - "**/AndroidManifest.xml"
+  - "**/Info.plist"
+---
+# Seguridad en Dart/Flutter
+
+> Este archivo extiende [common/security.md](../common/security.md) con contenido específico de Dart, Flutter y móvil.
+
+## Gestión de secretos
+
+- Nunca codifiques API keys, tokens ni credenciales en el código fuente Dart
+- Usa `--dart-define` o `--dart-define-from-file` para configuración en tiempo de compilación (los valores no son realmente secretos — usa un proxy en el backend para los secretos del lado servidor)
+- Usa `flutter_dotenv` o equivalente, con los archivos `.env` listados en `.gitignore`
+- Guarda los secretos de runtime en almacenamiento seguro de plataforma: `flutter_secure_storage` (Keychain en iOS, EncryptedSharedPreferences en Android)
+
+```dart
+// INCORRECTO
+const apiKey = 'sk-abc123...';
+
+// CORRECTO — configuración en tiempo de compilación (no es secreta, solo configurable)
+const apiKey = String.fromEnvironment('API_KEY');
+
+// CORRECTO — secreto de runtime desde almacenamiento seguro
+final token = await secureStorage.read(key: 'auth_token');
+```
+
+## Seguridad de red
+
+- Impón HTTPS — sin llamadas `http://` en producción
+- Configura `network_security_config.xml` en Android para bloquear tráfico en claro
+- Configura `NSAppTransportSecurity` en `Info.plist` para prohibir cargas arbitrarias
+- Define timeouts en todos los clientes HTTP — nunca dejes los valores por defecto
+- Considera certificate pinning para endpoints de alta seguridad
+
+```dart
+// Dio con timeout e imposición de HTTPS
+final dio = Dio(BaseOptions(
+  baseUrl: 'https://api.example.com',
+  connectTimeout: const Duration(seconds: 10),
+  receiveTimeout: const Duration(seconds: 30),
+));
+```
+
+## Validación de entrada
+
+- Valida y sanea toda entrada del usuario antes de enviarla a la API o al almacenamiento
+- Nunca pases entrada sin sanear a consultas SQL — usa consultas parametrizadas (sqflite, drift)
+- Sanea las URLs de deep links antes de navegar — valida el esquema, el host y los parámetros de la ruta
+- Usa `Uri.tryParse` y valida antes de navegar
+
+```dart
+// INCORRECTO — inyección SQL
+await db.rawQuery("SELECT * FROM users WHERE email = '$userInput'");
+
+// CORRECTO — parametrizado
+await db.query('users', where: 'email = ?', whereArgs: [userInput]);
+
+// INCORRECTO — deep link sin validar
+final uri = Uri.parse(incomingLink);
+context.go(uri.path); // podría navegar a cualquier ruta
+
+// CORRECTO — deep link validado
+final uri = Uri.tryParse(incomingLink);
+if (uri != null && uri.host == 'myapp.com' && _allowedPaths.contains(uri.path)) {
+  context.go(uri.path);
+}
+```
+
+## Protección de datos
+
+- Guarda tokens, PII y credenciales solo en `flutter_secure_storage`
+- Nunca escribas datos sensibles en `SharedPreferences` ni en archivos locales en texto plano
+- Limpia el estado de autenticación al cerrar sesión: tokens, datos de usuario en caché, cookies
+- Usa autenticación biométrica (`local_auth`) para operaciones sensibles
+- Evita registrar datos sensibles — nada de `print(token)` ni `debugPrint(password)`
+
+## Específico de Android
+
+- Declara solo los permisos necesarios en `AndroidManifest.xml`
+- Exporta componentes de Android (`Activity`, `Service`, `BroadcastReceiver`) solo cuando sea necesario; añade `android:exported="false"` donde no haga falta
+- Revisa los intent filters — los componentes exportados con intent filters implícitos son accesibles por cualquier app
+- Usa `FLAG_SECURE` en pantallas que muestren datos sensibles (impide capturas de pantalla)
+
+```xml
+<!-- AndroidManifest.xml — restringir los componentes exportados -->
+<activity android:name=".MainActivity" android:exported="true">
+    <!-- Solo la activity lanzadora necesita exported=true -->
+</activity>
+<activity android:name=".SensitiveActivity" android:exported="false" />
+```
+
+## Específico de iOS
+
+- Declara solo las descripciones de uso necesarias en `Info.plist` (`NSCameraUsageDescription`, etc.)
+- Guarda los secretos en el Keychain — `flutter_secure_storage` usa el Keychain en iOS
+- Usa App Transport Security (ATS) — prohíbe las cargas arbitrarias
+- Habilita el entitlement de protección de datos para los archivos sensibles
+
+## Seguridad en WebView
+
+- Usa `webview_flutter` v4+ (`WebViewController` / `WebViewWidget`) — el widget `WebView` heredado fue eliminado
+- Deshabilita JavaScript salvo que sea explícitamente necesario (`JavaScriptMode.disabled`)
+- Valida las URLs antes de cargarlas — nunca cargues URLs arbitrarias provenientes de deep links
+- Nunca expongas callbacks de Dart a JavaScript salvo que sea absolutamente necesario y esté cuidadosamente aislado
+- Usa `NavigationDelegate.onNavigationRequest` para interceptar y validar las peticiones de navegación
+
+```dart
+// API de webview_flutter v4+ (WebViewController + WebViewWidget)
+final controller = WebViewController()
+  ..setJavaScriptMode(JavaScriptMode.disabled) // deshabilitado salvo que se requiera
+  ..setNavigationDelegate(
+    NavigationDelegate(
+      onNavigationRequest: (request) {
+        final uri = Uri.tryParse(request.url);
+        if (uri == null || uri.host != 'trusted.example.com') {
+          return NavigationDecision.prevent;
+        }
+        return NavigationDecision.navigate;
+      },
+    ),
+  );
+
+// En el árbol de widgets:
+WebViewWidget(controller: controller)
+```
+
+## Ofuscación y seguridad del build
+
+- Habilita la ofuscación en builds de release: `flutter build apk --obfuscate --split-debug-info=./debug-info/`
+- Mantén la salida de `--split-debug-info` fuera del control de versiones (se usa solo para simbolizar crashes)
+- Asegúrate de que las reglas de ProGuard/R8 no expongan inadvertidamente clases serializadas
+- Ejecuta `flutter analyze` y resuelve todas las advertencias antes del release

package/vendor/theus-arsenal/rules/dart/testing.md

@@ -0,0 +1,215 @@
+---
+paths:
+  - "**/*.dart"
+  - "**/pubspec.yaml"
+  - "**/analysis_options.yaml"
+---
+# Testing en Dart/Flutter
+
+> Este archivo extiende [common/testing.md](../common/testing.md) con contenido específico de Dart y Flutter.
+
+## Framework de testing
+
+- **flutter_test** / **dart:test** — el runner de tests integrado
+- **mockito** (con `@GenerateMocks`) o **mocktail** (sin codegen) para mocks
+- **bloc_test** para tests unitarios de BLoC/Cubit
+- **fake_async** para controlar el tiempo en tests unitarios
+- **integration_test** para tests de extremo a extremo en dispositivo
+
+## Tipos de test
+
+| Tipo | Herramienta | Ubicación | Cuándo escribirlo |
+|------|-------------|-----------|-------------------|
+| Unitario | `dart:test` | `test/unit/` | Toda la lógica de dominio, gestores de estado, repositorios |
+| Widget | `flutter_test` | `test/widget/` | Todos los widgets con comportamiento significativo |
+| Golden | `flutter_test` | `test/golden/` | Componentes de UI críticos para el diseño |
+| Integración | `integration_test` | `integration_test/` | Flujos de usuario críticos en dispositivo real/emulador |
+
+## Tests unitarios: gestores de estado
+
+### BLoC con `bloc_test`
+
+```dart
+group('CartBloc', () {
+  late CartBloc bloc;
+  late MockCartRepository repository;
+
+  setUp(() {
+    repository = MockCartRepository();
+    bloc = CartBloc(repository);
+  });
+
+  tearDown(() => bloc.close());
+
+  blocTest<CartBloc, CartState>(
+    'emite los ítems actualizados cuando llega CartItemAdded',
+    build: () => bloc,
+    act: (b) => b.add(CartItemAdded(testItem)),
+    expect: () => [CartState(items: [testItem])],
+  );
+
+  blocTest<CartBloc, CartState>(
+    'emite un carrito vacío cuando llega CartCleared',
+    seed: () => CartState(items: [testItem]),
+    build: () => bloc,
+    act: (b) => b.add(CartCleared()),
+    expect: () => [const CartState()],
+  );
+});
+```
+
+### Riverpod con `ProviderContainer`
+
+```dart
+test('usersProvider carga los usuarios desde el repositorio', () async {
+  final container = ProviderContainer(
+    overrides: [userRepositoryProvider.overrideWithValue(FakeUserRepository())],
+  );
+  addTearDown(container.dispose);
+
+  final result = await container.read(usersProvider.future);
+  expect(result, isNotEmpty);
+});
+```
+
+## Tests de widgets
+
+```dart
+testWidgets('CartPage muestra el contador de ítems', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        cartNotifierProvider.overrideWith(() => FakeCartNotifier([testItem])),
+      ],
+      child: const MaterialApp(home: CartPage()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('1'), findsOneWidget);
+  expect(find.byType(CartItemTile), findsOneWidget);
+});
+
+testWidgets('muestra el estado vacío cuando el carrito está vacío', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier([]))],
+      child: const MaterialApp(home: CartPage()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('Tu carrito está vacío'), findsOneWidget);
+});
+```
+
+## Fakes antes que mocks
+
+Prefiere fakes escritos a mano para dependencias complejas:
+
+```dart
+class FakeUserRepository implements UserRepository {
+  final _users = <String, User>{};
+  Object? fetchError;
+
+  @override
+  Future<User?> getById(String id) async {
+    if (fetchError != null) throw fetchError!;
+    return _users[id];
+  }
+
+  @override
+  Future<List<User>> getAll() async {
+    if (fetchError != null) throw fetchError!;
+    return _users.values.toList();
+  }
+
+  @override
+  Stream<List<User>> watchAll() => Stream.value(_users.values.toList());
+
+  @override
+  Future<void> save(User user) async {
+    _users[user.id] = user;
+  }
+
+  @override
+  Future<void> delete(String id) async {
+    _users.remove(id);
+  }
+
+  void addUser(User user) => _users[user.id] = user;
+}
+```
+
+## Testing asíncrono
+
+```dart
+// Usa fake_async para controlar timers y Futures
+test('el debounce se dispara después de 300 ms', () {
+  fakeAsync((async) {
+    final debouncer = Debouncer(delay: const Duration(milliseconds: 300));
+    var callCount = 0;
+    debouncer.run(() => callCount++);
+    expect(callCount, 0);
+    async.elapse(const Duration(milliseconds: 200));
+    expect(callCount, 0);
+    async.elapse(const Duration(milliseconds: 200));
+    expect(callCount, 1);
+  });
+});
+```
+
+## Tests golden
+
+```dart
+testWidgets('test golden de UserCard', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(home: UserCard(user: testUser)),
+  );
+
+  await expectLater(
+    find.byType(UserCard),
+    matchesGoldenFile('goldens/user_card.png'),
+  );
+});
+```
+
+Ejecuta `flutter test --update-goldens` cuando haya cambios visuales intencionales.
+
+## Nombres de los tests
+
+Usa nombres descriptivos y centrados en el comportamiento:
+
+```dart
+test('devuelve null cuando el usuario no existe', () { ... });
+test('lanza NotFoundException cuando el id es una cadena vacía', () { ... });
+testWidgets('deshabilita el botón de envío mientras el formulario es inválido', (tester) async { ... });
+```
+
+## Organización de los tests
+
+```
+test/
+├── unit/
+│   ├── domain/
+│   │   └── usecases/
+│   └── data/
+│       └── repositories/
+├── widget/
+│   └── presentation/
+│       └── pages/
+└── golden/
+    └── widgets/
+
+integration_test/
+└── flows/
+    ├── login_flow_test.dart
+    └── checkout_flow_test.dart
+```
+
+## Cobertura
+
+- Apunta a 80%+ de cobertura de líneas para la lógica de negocio (dominio + gestores de estado)
+- Todas las transiciones de estado deben tener tests: loading → success, loading → error, reintento
+- Ejecuta `flutter test --coverage` e inspecciona `lcov.info` con un reporter de cobertura
+- Los fallos de cobertura deben bloquear el CI cuando estén por debajo del umbral