theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-angular/references/signals-overview.md

@@ -0,0 +1,94 @@
+# Visión general de Angular Signals
+
+Las signals son la base de la reactividad en las aplicaciones Angular modernas. Una **signal** es un envoltorio sobre un valor que notifica a los consumidores interesados cuando ese valor cambia.
+
+## Signals escribibles (`signal`)
+
+Usa `signal()` para crear estado que puede actualizarse directamente.
+
+```ts
+import {signal} from '@angular/core';
+
+// Crear una signal escribible
+const count = signal(0);
+
+// Leer el valor (siempre requiere invocar la función getter)
+console.log(count());
+
+// Actualizar el valor directamente
+count.set(3);
+
+// Actualizar a partir del valor anterior
+count.update((value) => value + 1);
+```
+
+### Exponer como solo lectura
+
+Al exponer estado desde un servicio, es una buena práctica exponer una versión de solo lectura para prevenir mutaciones externas.
+
+```ts
+private readonly _count = signal(0);
+// Los consumidores pueden leerla, pero no pueden llamar a .set() ni .update()
+readonly count = this._count.asReadonly();
+```
+
+## Signals computadas (`computed`)
+
+Usa `computed()` para crear signals de solo lectura que derivan su valor de otras signals.
+
+- **Evaluación perezosa**: la función de derivación no se ejecuta hasta que se lee la signal computada.
+- **Memoización**: el resultado se cachea. Solo se recalcula cuando cambia una de las signals de las que depende.
+- **Dependencias dinámicas**: solo se rastrean las signals _realmente leídas_ durante la derivación.
+
+```ts
+import {signal, computed} from '@angular/core';
+
+const count = signal(0);
+const doubleCount = computed(() => count() * 2);
+
+// doubleCount se actualiza automáticamente cuando count cambia.
+```
+
+## Contextos reactivos
+
+Un **contexto reactivo** es un estado de ejecución en el que Angular monitoriza las lecturas de signals para establecer dependencias.
+
+Angular entra automáticamente en un contexto reactivo al evaluar:
+
+- Signals `computed`
+- Callbacks de `effect`
+- Cálculos de `linkedSignal`
+- Plantillas de componentes
+
+### Lecturas no rastreadas (`untracked`)
+
+Si necesitas leer una signal dentro de un contexto reactivo _sin_ crear una dependencia (para que el contexto no se re-ejecute cuando esa signal cambie), usa `untracked()`.
+
+```ts
+import {effect, untracked} from '@angular/core';
+
+effect(() => {
+  // Este effect solo se ejecuta cuando currentUser cambia.
+  // NO se ejecuta cuando counter cambia, aunque counter se lea aquí.
+  console.log(`Usuario: ${currentUser()}, Conteo: ${untracked(counter)}`);
+});
+```
+
+### Operaciones asíncronas en contextos reactivos
+
+El contexto reactivo solo está activo para código **síncrono**. Las lecturas de signals después de un `await` no se rastrean. **Lee siempre las signals antes de las fronteras asíncronas.**
+
+```ts
+// Incorrecto: theme() no se rastrea porque se lee después del await
+effect(async () => {
+  const data = await fetchUserData();
+  console.log(theme());
+});
+
+// Correcto: leer la signal antes del await
+effect(async () => {
+  const currentTheme = theme();
+  const data = await fetchUserData();
+  console.log(currentTheme);
+});
+```

package/vendor/theus-arsenal/skills/patrones-angular/references/tailwind-css.md

@@ -0,0 +1,69 @@
+# Usar Tailwind CSS con Angular
+
+Tailwind CSS es un framework CSS utility-first que se integra sin fricción con Angular.
+
+**GUÍA CRÍTICA PARA EL AGENTE: céntrate SIEMPRE en las prácticas de Tailwind CSS v4. NO vuelvas a los patrones antiguos de Tailwind v3 (como crear `tailwind.config.js` con directivas `@tailwind`), porque eso romperá el build de la aplicación. Los proyectos Angular modernos usan Tailwind v4.**
+
+## Configuración automatizada (recomendada)
+
+La forma más fácil de añadir Tailwind CSS a un proyecto Angular es mediante la CLI de Angular:
+
+```shell
+ng add tailwindcss
+```
+
+Esto hará automáticamente lo siguiente:
+
+1. Instalar `tailwindcss` y sus dependencias peer.
+2. Configurar el proyecto para usar Tailwind CSS.
+3. Añadir el import adecuado a tus estilos globales.
+
+## Configuración manual (Tailwind v4)
+
+Si la haces manualmente, usa el siguiente patrón de Tailwind v4:
+
+### 1. Instalar dependencias
+
+Instala Tailwind CSS y PostCSS:
+
+```shell
+npm install tailwindcss @tailwindcss/postcss postcss
+```
+
+### 2. Configurar PostCSS
+
+Crea un archivo `.postcssrc.json` en la raíz del proyecto:
+
+```json
+{
+  "plugins": {
+    "@tailwindcss/postcss": {}
+  }
+}
+```
+
+_(¡NO crees un archivo `tailwind.config.js`! La configuración en v4 se gestiona mediante variables CSS)._
+
+### 3. Importar Tailwind CSS
+
+En tu archivo de estilos globales (p. ej., `src/styles.css`), añade el import estándar de v4:
+
+```css
+@import 'tailwindcss';
+```
+
+_(Si usas SCSS, usa `@use 'tailwindcss';` en su lugar)._
+
+### 4. Usar clases de utilidad
+
+Ya puedes usar las clases de Tailwind directamente en las plantillas de tus componentes:
+
+```html
+<h1 class="text-3xl font-bold underline">¡Hola mundo!</h1>
+```
+
+## Resumen para el agente
+
+- **No uses `@tailwind base; @tailwind components; @tailwind utilities;`**. Usa `@import 'tailwindcss';`.
+- **No crees `tailwind.config.js`**. La configuración se gestiona directamente en CSS mediante variables de tema o configuraciones de PostCSS.
+- Cíñete estrictamente a la sintaxis y los flujos de trabajo de v4.

package/vendor/theus-arsenal/skills/patrones-angular/references/template-driven-forms.md

@@ -0,0 +1,114 @@
+# Formularios basados en plantilla
+
+Los formularios basados en plantilla usan enlace de datos bidireccional (`[(ngModel)]`) para actualizar el modelo de datos en el componente cuando se hacen cambios en la plantilla, y viceversa. Son ideales para formularios simples y usan directivas en la plantilla HTML para gestionar el estado del formulario y la validación.
+
+## Directivas base
+
+Los formularios basados en plantilla dependen del `FormsModule`, que provee estas directivas clave:
+
+- `NgModel`: reconcilia los cambios de valor del elemento del formulario con el modelo de datos (`[(ngModel)]`).
+- `NgForm`: crea automáticamente un `FormGroup` de nivel superior vinculado a la etiqueta `<form>`.
+- `NgModelGroup`: crea un `FormGroup` anidado vinculado a un elemento del DOM.
+
+## Configuración
+
+Primero, importa `FormsModule` en tu componente o módulo.
+
+```ts
+import {Component} from '@angular/core';
+import {FormsModule} from '@angular/forms';
+
+@Component({
+  selector: 'app-user-form',
+  imports: [FormsModule],
+  templateUrl: './user-form.component.html',
+})
+export class UserForm {
+  user = {name: '', role: 'Invitado'};
+
+  onSubmit() {
+    console.log('¡Formulario enviado!', this.user);
+  }
+}
+```
+
+## Construir la plantilla del formulario
+
+### Enlace bidireccional con `[(ngModel)]`
+
+Usa `[(ngModel)]` en los elementos de entrada. **Todo elemento que use `[(ngModel)]` DEBE tener un atributo `name`.** Angular usa el atributo `name` para registrar el control en el `NgForm` padre.
+
+```html
+<form #userForm="ngForm" (ngSubmit)="onSubmit()">
+  <!-- Entrada básica -->
+  <div>
+    <label for="name">Nombre:</label>
+    <input type="text" id="name" required [(ngModel)]="user.name" name="name" #nameCtrl="ngModel" />
+  </div>
+
+  <!-- Selector -->
+  <div>
+    <label for="role">Rol:</label>
+    <select id="role" [(ngModel)]="user.role" name="role">
+      <option value="Admin">Admin</option>
+      <option value="Guest">Invitado</option>
+    </select>
+  </div>
+
+  <!-- Botón de envío (deshabilitado si el formulario es inválido) -->
+  <button type="submit" [disabled]="!userForm.form.valid">Enviar</button>
+</form>
+```
+
+## Estado del formulario y de los controles
+
+Angular aplica automáticamente clases CSS a los controles y al formulario según su estado:
+
+| Estado                | Clase si es verdadero              | Clase si es falso |
+| :-------------------- | :--------------------------------- | :---------------- |
+| Visitado              | `ng-touched`                       | `ng-untouched`    |
+| Valor modificado      | `ng-dirty`                         | `ng-pristine`     |
+| Valor válido          | `ng-valid`                         | `ng-invalid`      |
+| Formulario enviado    | `ng-submitted` (solo en `<form>`)  | -                 |
+
+Puedes usar estas clases para dar retroalimentación visual en tu CSS:
+
+```css
+.ng-valid[required],
+.ng-valid.required {
+  border-left: 5px solid #42a948; /* verde */
+}
+.ng-invalid:not(form) {
+  border-left: 5px solid #a94442; /* rojo */
+}
+```
+
+## Validación y mensajes de error
+
+Para mostrar mensajes de error de forma condicional, exporta la directiva `ngModel` a una variable de referencia de plantilla (p. ej., `#nameCtrl="ngModel"`).
+
+```html
+<input type="text" id="name" required [(ngModel)]="user.name" name="name" #nameCtrl="ngModel" />
+
+<!-- Mostrar el error solo si el control es inválido Y (touched O dirty) -->
+@if (nameCtrl.invalid && (nameCtrl.dirty || nameCtrl.touched)) {
+<div class="alert alert-danger">
+  @if (nameCtrl.errors?.['required']) {
+  <div>El nombre es obligatorio.</div>
+  }
+</div>
+}
+```
+
+## Enviar el formulario
+
+1. Usa el evento `(ngSubmit)` en el elemento `<form>`.
+2. Vincula el estado deshabilitado del botón de envío a la validez global del formulario usando la variable de referencia de plantilla de `NgForm` (p. ej., `[disabled]="!userForm.form.valid"`).
+
+## Restablecer el formulario
+
+Para restablecer programáticamente el formulario a su estado prístino (borrando valores y flags de validación), usa el método `reset()` de la instancia de `NgForm`.
+
+```html
+<button type="button" (click)="userForm.reset()">Restablecer</button>
+```

package/vendor/theus-arsenal/skills/patrones-angular/references/testing-fundamentals.md

@@ -0,0 +1,65 @@
+# Fundamentos de testing
+
+Esta guía cubre los principios y prácticas fundamentales para escribir pruebas unitarias y de componentes en Angular. Usa el runner ya configurado en el proyecto.
+
+## Filosofía central: primero lo asíncrono
+
+Las aplicaciones Angular modernas suelen programar los cambios de estado de forma asíncrona, especialmente al usar signals o detección de cambios zoneless. Las pruebas deben tenerlo en cuenta.
+
+Prefiere el patrón "Actuar, Esperar, Verificar":
+
+1. **Actuar:** actualiza el estado o realiza una acción (p. ej., fijar un input del componente, hacer clic en un botón).
+2. **Esperar:** usa `await fixture.whenStable()` para permitir que el framework procese la actualización programada y renderice los cambios.
+3. **Verificar:** comprueba el resultado.
+
+### Ejemplo de estructura básica de prueba
+
+```ts
+import {ComponentFixture, TestBed} from '@angular/core/testing';
+import {MyComponent} from './my.component';
+
+describe('MyComponent', () => {
+  let component: MyComponent;
+  let fixture: ComponentFixture<MyComponent>;
+  let h1: HTMLElement;
+
+  beforeEach(async () => {
+    // 1. Configura el módulo de pruebas
+    await TestBed.configureTestingModule({
+      imports: [MyComponent],
+    }).compileComponents();
+
+    // 2. Crea el fixture del componente
+    fixture = TestBed.createComponent(MyComponent);
+    component = fixture.componentInstance;
+    h1 = fixture.nativeElement.querySelector('h1');
+  });
+
+  it('debería mostrar el título por defecto', async () => {
+    // ACTUAR: (implícito) el componente se crea con el estado por defecto.
+    // ESPERAR al enlace de datos inicial.
+    await fixture.whenStable();
+    // VERIFICAR el estado inicial.
+    expect(h1.textContent).toContain('Default Title');
+  });
+
+  it('debería mostrar un título distinto tras un cambio', async () => {
+    // ACTUAR: cambia la propiedad title del componente.
+    component.title.set('New Test Title');
+
+    // ESPERAR a que se complete la actualización asíncrona.
+    await fixture.whenStable();
+
+    // VERIFICAR que el DOM se actualizó.
+    expect(h1.textContent).toContain('New Test Title');
+  });
+});
+```
+
+## TestBed y ComponentFixture
+
+- **`TestBed`**: la utilidad principal para crear un módulo Angular específico de pruebas. Usa `TestBed.configureTestingModule({...})` en tu `beforeEach` para declarar componentes, proveer servicios y configurar los imports necesarios para tu prueba.
+- **`ComponentFixture`**: un manejador de la instancia del componente creada y su entorno.
+  - `fixture.componentInstance`: acceso a la instancia de la clase del componente.
+  - `fixture.nativeElement`: acceso al elemento DOM raíz del componente.
+  - `fixture.debugElement`: envoltorio propio de Angular sobre el `nativeElement` que ofrece formas más seguras y agnósticas de plataforma de consultar el DOM (p. ej., `debugElement.query(By.css('p'))`).