theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/rules/arkts/hooks.md

@@ -1,80 +0,0 @@
----
-paths:
-  - "**/*.ets"
-  - "**/*.ts"
-  - "**/module.json5"
-  - "**/oh-package.json5"
----
-# Hooks para HarmonyOS / ArkTS
-
-> Este archivo extiende [common/hooks.md](../common/hooks.md) con hooks de compilación y validación específicos de HarmonyOS.
-
-## Comandos de build
-
-### Compilar el paquete HAP
-
-```bash
-# Compilar el paquete HAP (entorno hvigor global)
-hvigorw assembleHap -p product=default
-
-# Compilar un módulo concreto
-hvigorw assembleHap -p module=entry -p product=default
-
-# Compilación limpia
-hvigorw clean
-```
-
-### CLI de DevEco Studio
-
-```bash
-# Comprobar la estructura del proyecto
-hvigorw --version
-
-# Instalar dependencias
-ohpm install
-
-# Actualizar dependencias
-ohpm update
-```
-
-## Hooks PostToolUse recomendados
-
-Configúralos en `~/.theus/settings.json`:
-
-- **Tras editar archivos `.ets`/`.ts`**: ejecuta el build de hvigor para detectar errores de compilación de ArkTS. Comando sugerido (asíncrono, timeout amplio, ~60 s):
-
-  ```bash
-  hvigorw assembleHap -p product=default 2>&1 | tail -20
-  ```
-
-- **Tras editar `module.json5`**: emite un recordatorio para verificar las declaraciones de permisos y abilities, por ejemplo:
-
-  ```bash
-  echo '[HarmonyOS] module.json5 modificado - verifica permisos y abilities'
-  ```
-
-- **Tras editar `oh-package.json5`**: reinstala las dependencias (asíncrono, ~30 s):
-
-  ```bash
-  ohpm install 2>&1 | tail -10
-  ```
-
-## Hooks PreToolUse
-
-- **Guardia de decoradores V1**: antes de escribir o editar archivos `.ets`, emite un recordatorio de que los decoradores V1 están prohibidos:
-
-  ```bash
-  echo '[HarmonyOS] Recordatorio: usa @ComponentV2 / @Local / @Param - los decoradores V1 (@State, @Prop, @Link) están prohibidos'
-  ```
-
-## Checklist de validación
-
-Después de cada ciclo de implementación, verifica:
-
-- [ ] `hvigorw assembleHap` termina sin errores
-- [ ] No hay decoradores V1 en archivos `.ets` nuevos o modificados
-- [ ] No hay imports de `@ohos.router` en archivos nuevos o modificados
-- [ ] Todos los permisos de API están declarados en `module.json5`
-- [ ] Todas las dependencias están listadas en `oh-package.json5`
-- [ ] Las cadenas de recursos están añadidas en todos los directorios de i18n
-- [ ] Los recursos de color nuevos incluyen su variante para tema oscuro

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

@@ -1,236 +0,0 @@
----
-paths:
-  - "**/*.ets"
-  - "**/*.ts"
----
-# Patrones de HarmonyOS / ArkTS
-
-> Este archivo extiende [common/patterns.md](../common/patterns.md) con patrones específicos de HarmonyOS y ArkTS.
-
-## Gestión de estado: solo V2
-
-**DEBES usar** ArkUI State Management V2. Los decoradores V1 están obsoletos y no deben usarse.
-
-### Decoradores V2
-
-| Decorador | Propósito |
-|-----------|-----------|
-| `@ComponentV2` | Marca un struct como componente V2 |
-| `@Local` | Estado local dentro de un componente |
-| `@Param` | Props recibidas del padre (solo lectura) |
-| `@Event` | Eventos callback de hijo a padre |
-| `@Provider` | Provee estado a los componentes descendientes |
-| `@Consumer` | Consume estado de un `@Provider` ancestro |
-| `@Monitor` | Observa cambios de estado (reemplaza al `@Watch` de V1) |
-| `@Computed` | Valores derivados/calculados |
-| `@ObservedV2` | Hace observable una clase para la gestión de estado V2 |
-| `@Trace` | Marca propiedades observables en clases `@ObservedV2` |
-
-### Decoradores V1 prohibidos
-
-Nunca uses: `@State`, `@Prop`, `@Link`, `@ObjectLink`, `@Observed`, `@Provide`, `@Consume`, `@Watch`, `@Component` (usa `@ComponentV2` en su lugar).
-
-### Ejemplo de componente V2
-
-```typescript
-@ObservedV2
-class UserModel {
-  @Trace name: string = ''
-  @Trace age: number = 0
-}
-
-@ComponentV2
-struct UserCard {
-  @Param user: UserModel = new UserModel()
-  @Event onDelete: () => void = () => {}
-
-  build() {
-    Column() {
-      Text(this.user.name)
-        .fontSize($r('app.float.font_size_title'))
-      Text(`${this.user.age}`)
-        .fontSize($r('app.float.font_size_body'))
-      Button($r('app.string.delete'))
-        .onClick(() => this.onDelete())
-    }
-  }
-}
-```
-
-### Sincronización de estado
-
-```typescript
-@ComponentV2
-struct ParentPage {
-  @Provider('userState') userModel: UserModel = new UserModel()
-
-  build() {
-    Column() {
-      ChildComponent()  // recibe automáticamente @Consumer('userState')
-    }
-  }
-}
-
-@ComponentV2
-struct ChildComponent {
-  @Consumer('userState') userModel: UserModel = new UserModel()
-
-  build() {
-    Text(this.userModel.name)
-  }
-}
-```
-
-## Enrutamiento: solo Navigation
-
-**DEBES usar** el componente `Navigation` con `NavPathStack`. Nunca uses `@ohos.router`.
-
-### Configuración de Navigation
-
-```typescript
-@ComponentV2
-struct MainPage {
-  @Local navPathStack: NavPathStack = new NavPathStack()
-
-  build() {
-    Navigation(this.navPathStack) {
-      // Contenido de la pantalla principal
-    }
-    .navDestination(this.routerMap)
-  }
-
-  @Builder
-  routerMap(name: string, param: ESObject) {
-    if (name === 'detail') {
-      DetailPage()
-    } else if (name === 'settings') {
-      SettingsPage()
-    }
-  }
-}
-```
-
-### Navegación entre páginas
-
-```typescript
-// Apilar una página nueva
-this.navPathStack.pushPath({ name: 'detail', param: { id: '123' } })
-
-// Reemplazar la página actual
-this.navPathStack.replacePath({ name: 'settings' })
-
-// Volver atrás
-this.navPathStack.pop()
-
-// Volver a la raíz
-this.navPathStack.clear()
-```
-
-### Subpágina NavDestination
-
-```typescript
-@ComponentV2
-struct DetailPage {
-  build() {
-    NavDestination() {
-      Column() {
-        Text($r('app.string.detail_title'))
-      }
-    }
-    .title($r('app.string.detail_nav_title'))
-  }
-}
-```
-
-## Patrón de arquitectura: MVVM
-
-Arquitectura recomendada para aplicaciones HarmonyOS:
-
-```
-feature/
-  |-- model/           # Modelos de datos (clases @ObservedV2)
-  |-- viewmodel/       # Lógica de negocio (clases ViewModel)
-  |-- view/            # Componentes de UI (structs @ComponentV2)
-  |-- service/         # Llamadas a API, acceso a datos
-```
-
-- **View**: solo lógica de renderizado; nada de lógica de negocio en `build()`
-- **ViewModel**: toda la lógica de negocio encapsulada aquí
-- **Model**: clases de datos puras con `@ObservedV2` y `@Trace`
-- **Service**: peticiones de red, operaciones de base de datos, E/S de archivos
-
-## Patrones de animación en ArkUI
-
-### Animación dirigida por estado
-
-```typescript
-@ComponentV2
-struct AnimatedCard {
-  @Local isExpanded: boolean = false
-  @Local cardScale: number = 0.8
-
-  build() {
-    Column() {
-      // Contenido
-    }
-    .scale({ x: this.cardScale, y: this.cardScale })
-    .animation({ duration: 300, curve: Curve.EaseInOut })
-    .onClick(() => {
-      this.isExpanded = !this.isExpanded
-      this.cardScale = this.isExpanded ? 1.0 : 0.8
-    })
-  }
-}
-```
-
-### Reglas de animación
-
-- Prefiere las APIs de animación nativas de HarmonyOS y las plantillas avanzadas
-- Usa UI declarativa con animaciones dirigidas por estado (cambia variables de estado para disparar animaciones)
-- Activa `renderGroup(true)` en animaciones de subcomponentes complejas para reducir los lotes de renderizado
-- **NUNCA** cambies con frecuencia `width`, `height`, `padding` o `margin` durante una animación: el impacto en rendimiento es severo
-- Usa `animateTo` para el control explícito de animaciones
-- Prefiere `transform` (translate, scale, rotate) y `opacity` para animaciones con buen rendimiento
-
-## Patrones de rendimiento
-
-### LazyForEach para listas grandes
-
-```typescript
-@ComponentV2
-struct LargeList {
-  @Local dataSource: MyDataSource = new MyDataSource()
-
-  build() {
-    List() {
-      LazyForEach(this.dataSource, (item: ItemModel) => {
-        ListItem() {
-          ItemComponent({ item: item })
-        }
-      }, (item: ItemModel) => item.id)
-    }
-  }
-}
-```
-
-### Reutilización de componentes
-
-- Extrae los componentes reutilizables a archivos separados
-- Usa `@Builder` para fragmentos de UI ligeros dentro de un componente
-- Usa `@Param` para componentes configurables
-
-## Referencias a recursos
-
-Define siempre las constantes de UI como recursos y referéncialas con `$r()`:
-
-```typescript
-// INCORRECTO: valores codificados
-Text('Hola')
-  .fontSize(16)
-  .fontColor('#333333')
-
-// CORRECTO: referencias a recursos
-Text($r('app.string.greeting'))
-  .fontSize($r('app.float.font_size_body'))
-  .fontColor($r('app.color.text_primary'))
-```

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

@@ -1,141 +0,0 @@
----
-paths:
-  - "**/*.ets"
-  - "**/*.ts"
-  - "**/module.json5"
----
-# Seguridad en HarmonyOS / ArkTS
-
-> Este archivo extiende [common/security.md](../common/security.md) con prácticas de seguridad específicas de HarmonyOS.
-
-## Gestión de permisos
-
-### Declarar los permisos en module.json5
-
-Toda llamada a APIs del sistema que requiera permisos debe declararse:
-
-```json5
-{
-  "module": {
-    "requestPermissions": [
-      {
-        "name": "ohos.permission.INTERNET",
-        "reason": "$string:internet_permission_reason",
-        "usedScene": {
-          "abilities": ["EntryAbility"],
-          "when": "always"
-        }
-      }
-    ]
-  }
-}
-```
-
-### Checklist de permisos
-
-Antes de llamar a APIs del sistema, verifica:
-
-- [ ] El permiso está declarado en `module.json5`
-- [ ] La cadena con la razón del permiso está definida en los recursos (para permisos visibles al usuario)
-- [ ] La solicitud de permiso en tiempo de ejecución está implementada para permisos sensibles (cámara, ubicación, etc.)
-- [ ] Se comprueba el permiso antes de la llamada a la API, con un fallback controlado si se deniega
-
-### Solicitud de permisos en tiempo de ejecución
-
-```typescript
-import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit';
-
-async function checkAndRequestPermission(permission: Permissions): Promise<boolean> {
-  const atManager = abilityAccessCtrl.createAtManager();
-  const bundleInfo = await bundleManager.getBundleInfoForSelf(
-    bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
-  );
-  const tokenId = bundleInfo.appInfo.accessTokenId;
-  const grantStatus = await atManager.checkAccessToken(tokenId, permission);
-
-  if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
-    return true;
-  }
-
-  const result = await atManager.requestPermissionsFromUser(getContext(), [permission]);
-  return result.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
-}
-```
-
-## Gestión de secretos
-
-- **NUNCA** codifiques API keys, tokens ni contraseñas en archivos fuente `.ets`/`.ts`
-- Usa la API Preferences de HarmonyOS para configuración no sensible
-- Usa el Keystore de HarmonyOS para credenciales sensibles
-- Gestiona la configuración por entorno mediante build profiles
-
-```typescript
-// INCORRECTO: secreto codificado
-const API_KEY: string = 'sk-xxxxxxxxxxxx';
-
-// CORRECTO: desde la configuración del build profile (no sensible)
-import { BuildProfile } from 'BuildProfile';
-const endpoint = BuildProfile.API_ENDPOINT;
-
-// CORRECTO: usar HUKS para cifrar/descifrar datos sin exponer el material de la clave
-import { huks } from '@kit.UniversalKeystoreKit';
-async function decryptWithKeystore(alias: string, nonce: Uint8Array, aad: Uint8Array, cipherData: Uint8Array): Promise<Uint8Array> {
-  const options: huks.HuksOptions = {
-    properties: [
-      { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES },
-      { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT },
-      { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_GCM },
-      { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE },
-      { tag: huks.HuksTag.HUKS_TAG_NONCE, value: nonce },
-      { tag: huks.HuksTag.HUKS_TAG_ASSOCIATED_DATA, value: aad }
-    ],
-    inData: cipherData
-  };
-  const handle = await huks.initSession(alias, options);
-  const result = await huks.finishSession(handle.handle, options);
-  return result.outData;
-}
-```
-
-## Validación de entrada
-
-- Valida toda entrada del usuario antes de procesarla
-- Sanea los datos antes de mostrarlos en la UI para prevenir inyecciones
-- Valida los parámetros de los deep links antes de navegar
-
-```typescript
-// Validar antes de navegar
-function handleDeepLink(uri: string): void {
-  const allowedPaths: string[] = ['detail', 'settings', 'profile'];
-  const parsed = new URL(uri);
-  const path = parsed.pathname.replace('/', '');
-
-  if (!allowedPaths.includes(path)) {
-    hilog.warn(0x0000, 'DeepLink', 'Ruta de deep link inválida: %{public}s', path);
-    return;
-  }
-
-  navPathStack.pushPath({ name: path });
-}
-```
-
-## Seguridad de red
-
-- Usa siempre HTTPS en las peticiones de red
-- Valida los certificados del servidor
-- Implementa políticas de timeout y reintentos en las peticiones
-- Nunca registres datos sensibles (tokens, credenciales de usuario) en los logs de peticiones/respuestas de red
-
-## Seguridad del almacenamiento de datos
-
-- Usa preferences cifradas para los datos locales sensibles
-- Borra los datos sensibles de la memoria cuando ya no se necesiten
-- Implementa una gestión adecuada del ciclo de vida de los datos
-- Considera la clasificación de los datos (públicos, internos, confidenciales) al elegir el mecanismo de almacenamiento
-
-## Seguridad de dependencias
-
-- Usa solo dependencias de fuentes confiables (el registro oficial de ohpm)
-- Verifica las versiones de las dependencias en `oh-package.json5`
-- Revisa con regularidad las vulnerabilidades conocidas de las librerías de terceros
-- Fija (pin) las versiones de las dependencias para evitar actualizaciones inesperadas

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

@@ -1,126 +0,0 @@
----
-paths:
-  - "**/*.ets"
-  - "**/*.ts"
-  - "**/ohosTest/**"
----
-# Testing en HarmonyOS / ArkTS
-
-> Este archivo extiende [common/testing.md](../common/testing.md) con prácticas de testing específicas de HarmonyOS.
-
-## Framework de tests
-
-HarmonyOS usa el framework de tests integrado con las capacidades de `@ohos.test`:
-
-- **Tests unitarios**: ubicados en `src/ohosTest/ets/test/`
-- **Tests de UI**: usa `@ohos.UiTest` para probar componentes
-- **Tests instrumentados**: se ejecutan en dispositivo o emulador
-
-## Estructura del directorio de tests
-
-```
-module/
-  |-- src/
-  |   |-- main/ets/          # Código de producción
-  |   |-- ohosTest/ets/      # Código de tests
-  |       |-- test/
-  |       |   |-- Ability.test.ets
-  |       |   |-- List.test.ets
-  |       |-- TestAbility.ets
-  |       |-- TestRunner.ets
-```
-
-## Ejecutar los tests
-
-```bash
-# Ejecutar todos los tests de un módulo
-hvigorw testHap -p product=default
-
-# Ejecutar los tests en un dispositivo conectado
-hdc shell aa test -b com.example.app -m entry_test -s unittest /ets/TestRunner/OpenHarmonyTestRunner
-```
-
-## Ejemplo de test unitario
-
-```typescript
-import { describe, it, expect } from '@ohos/hypium';
-
-export default function UserViewModelTest() {
-  describe('UserViewModel', () => {
-    it('debe_inicializarse_con_estado_vacio', 0, () => {
-      const vm = new UserViewModel();
-      expect(vm.userName).assertEqual('');
-      expect(vm.isLoading).assertFalse();
-    });
-
-    it('debe_actualizar_el_nombre_de_usuario', 0, () => {
-      const vm = new UserViewModel();
-      vm.updateUserName('Alice');
-      expect(vm.userName).assertEqual('Alice');
-    });
-
-    it('debe_manejar_entrada_vacia', 0, () => {
-      const vm = new UserViewModel();
-      vm.updateUserName('');
-      expect(vm.userName).assertEqual('');
-      expect(vm.hasError).assertFalse();
-    });
-  });
-}
-```
-
-## Ejemplo de test de UI
-
-```typescript
-import { describe, it, expect } from '@ohos/hypium';
-import { Driver, ON } from '@ohos.UiTest';
-
-export default function HomePageUITest() {
-  describe('HomePage_UI', () => {
-    it('debe_mostrar_el_titulo', 0, async () => {
-      const driver = Driver.create();
-      await driver.delayMs(1000);
-
-      const title = await driver.findComponent(ON.text('Home'));
-      expect(title !== null).assertTrue();
-    });
-
-    it('debe_navegar_al_detalle_al_hacer_clic', 0, async () => {
-      const driver = Driver.create();
-      const button = await driver.findComponent(ON.id('detailButton'));
-      await button.click();
-      await driver.delayMs(500);
-
-      const detailTitle = await driver.findComponent(ON.text('Detail'));
-      expect(detailTitle !== null).assertTrue();
-    });
-  });
-}
-```
-
-## Flujo TDD para HarmonyOS
-
-Sigue el ciclo TDD estándar adaptado a HarmonyOS:
-
-1. **ROJO**: escribe un test que falle en `ohosTest/ets/test/`
-2. **VERDE**: implementa el código mínimo en `main/ets/` para que pase
-3. **REFACTOR**: limpia el código manteniendo los tests en verde
-4. **BUILD**: ejecuta `hvigorw assembleHap` para verificar la compilación
-5. **VERIFICA**: ejecuta los tests en dispositivo o emulador
-
-## Requisitos de cobertura
-
-- Cobertura mínima del 80 % para todo el código crítico de la aplicación (ViewModels, servicios, utilidades)
-- **Tests unitarios**: todas las funciones de utilidad, la lógica de los ViewModels y los modelos de datos
-- **Tests de integración**: llamadas a API, operaciones de base de datos, interacciones entre módulos
-- **Tests E2E / de UI**: los flujos de usuario críticos (inicio de sesión, navegación, envío de datos)
-- Prueba los casos límite: datos vacíos, errores de red, denegación de permisos
-
-## Buenas prácticas de testing
-
-- Mantén los tests independientes: sin estado mutable compartido entre tests
-- Simula (mock) las llamadas de red y las APIs del sistema en los tests unitarios
-- Usa nombres de test significativos: `debe_[comportamiento_esperado]_cuando_[condicion]`
-- Prueba la reactividad de la gestión de estado V2: verifica que las propiedades `@Trace` disparan actualizaciones de UI
-- Prueba los flujos de Navigation: verifica las operaciones push/pop/replace de `NavPathStack`
-- Evita probar los internos del framework: céntrate en la lógica de negocio y el comportamiento visible para el usuario

package/vendor/theus-arsenal/rules/common/agents.md

@@ -1,49 +0,0 @@
-# Orquestación de agentes
-
-## Agentes disponibles
-
-Ubicados en `~/.theus/agents/`:
-
-| Agente | Propósito | Cuándo usarlo |
-|--------|-----------|---------------|
-| planificador | Planificación de implementación | Funcionalidades complejas, refactorizaciones |
-| arquitecto-codigo | Diseño de sistemas | Decisiones arquitectónicas |
-| guia-tdd | Desarrollo guiado por tests | Nuevas funcionalidades, corrección de bugs |
-| revisor-codigo | Revisión de código | Después de escribir código |
-| revisor-seguridad | Análisis de seguridad | Antes de hacer commits |
-| resolutor-builds | Corrección de errores de build | Cuando el build falla |
-| ejecutor-e2e | Testing E2E | Flujos de usuario críticos |
-| limpiador-refactors | Limpieza de código muerto | Mantenimiento del código |
-| actualizador-docs | Documentación | Actualización de docs |
-
-## Uso inmediato de agentes
-
-Sin necesidad de que el usuario lo pida:
-1. Solicitudes de funcionalidades complejas — usa el agente **planificador**
-2. Código recién escrito o modificado — usa el agente **revisor-codigo**
-3. Corrección de bug o nueva funcionalidad — usa el agente **guia-tdd**
-4. Decisión arquitectónica — usa el agente **arquitecto-codigo**
-
-## Ejecución de tareas en paralelo
-
-Usa SIEMPRE la ejecución de tareas (Task) en paralelo para operaciones independientes:
-
-```markdown
-# BIEN: ejecución en paralelo
-Lanza 3 agentes en paralelo:
-1. Agente 1: análisis de seguridad del módulo de autenticación
-2. Agente 2: revisión de rendimiento del sistema de caché
-3. Agente 3: verificación de tipos de las utilidades
-
-# MAL: secuencial sin necesidad
-Primero el agente 1, luego el agente 2, luego el agente 3
-```
-
-## Análisis desde múltiples perspectivas
-
-Para problemas complejos, usa subagentes con roles divididos:
-- Revisor factual
-- Ingeniero senior
-- Experto en seguridad
-- Revisor de consistencia
-- Verificador de redundancias