theus-cli-linux-arm64 0.2.84

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

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

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

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

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

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