theus-cli 0.2.83 → 0.2.84

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

@@ -1,261 +0,0 @@
----
-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

@@ -1,135 +0,0 @@
----
-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

@@ -1,215 +0,0 @@
----
-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