theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-nuxt4/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: patrones-nuxt4
+description: Patrones de aplicaciones Nuxt 4 para seguridad de hidratación, rendimiento, route rules, carga perezosa y obtención de datos segura para SSR con useFetch y useAsyncData.
+---
+
+# Patrones de Nuxt 4
+
+Úsala al construir o depurar aplicaciones Nuxt 4 con SSR, renderizado híbrido, route rules u obtención de datos a nivel de página.
+
+## Cuándo activarla
+
+- Desajustes de hidratación entre el HTML del servidor y el estado del cliente
+- Decisiones de renderizado por ruta como prerender, SWR, ISR o secciones solo de cliente
+- Trabajo de rendimiento sobre carga perezosa, hidratación perezosa o tamaño del payload
+- Obtención de datos de página o componente con `useFetch`, `useAsyncData` o `$fetch`
+- Problemas de enrutamiento de Nuxt ligados a parámetros de ruta, middleware o diferencias SSR/cliente
+
+## Seguridad de hidratación
+
+- Mantén el primer render determinista. No pongas `Date.now()`, `Math.random()`, APIs exclusivas del navegador ni lecturas de storage directamente en el estado de plantilla renderizado por SSR.
+- Mueve la lógica exclusiva del navegador detrás de `onMounted()`, `import.meta.client`, `ClientOnly` o un componente `.client.vue` cuando el servidor no pueda producir el mismo marcado.
+- Usa el composable `useRoute()` de Nuxt, no el de `vue-router`.
+- No uses `route.fullPath` para gobernar marcado renderizado por SSR. Los fragmentos de URL son solo de cliente, lo que puede crear desajustes de hidratación.
+- Trata `ssr: false` como una vía de escape para zonas genuinamente exclusivas del navegador, no como solución por defecto a los desajustes.
+
+## Obtención de datos
+
+- Prefiere `await useFetch()` para lecturas de API seguras para SSR en páginas y componentes. Reenvía los datos obtenidos en el servidor al payload de Nuxt y evita una segunda petición en la hidratación.
+- Usa `useAsyncData()` cuando el fetcher no sea una simple llamada a `$fetch()`, cuando necesites una clave personalizada o cuando compongas varias fuentes asíncronas.
+- Dale a `useAsyncData()` una clave estable para reutilizar caché y tener un comportamiento de refresh predecible.
+- Mantén los handlers de `useAsyncData()` libres de efectos secundarios. Pueden ejecutarse durante el SSR y la hidratación.
+- Usa `$fetch()` para escrituras disparadas por el usuario o acciones solo de cliente, no para datos de página de nivel superior que deban hidratarse desde el SSR.
+- Usa `lazy: true`, `useLazyFetch()` o `useLazyAsyncData()` para datos no críticos que no deban bloquear la navegación. Maneja `status === 'pending'` en la UI.
+- Usa `server: false` solo para datos que no se necesiten para el SEO ni el primer pintado.
+- Recorta el tamaño del payload con `pick` y prefiere payloads menos profundos cuando la reactividad profunda sea innecesaria.
+
+```ts
+const route = useRoute()
+
+const { data: article, status, error, refresh } = await useAsyncData(
+  () => `article:${route.params.slug}`,
+  () => $fetch(`/api/articles/${route.params.slug}`),
+)
+
+const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {
+  lazy: true,
+  server: false,
+})
+```
+
+## Route rules
+
+Prefiere `routeRules` en `nuxt.config.ts` para la estrategia de renderizado y caché:
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/': { prerender: true },
+    '/products/**': { swr: 3600 },
+    '/blog/**': { isr: true },
+    '/admin/**': { ssr: false },
+    '/api/**': { cache: { maxAge: 60 * 60 } },
+  },
+})
+```
+
+- `prerender`: HTML estático en tiempo de build
+- `swr`: servir contenido cacheado y revalidar en segundo plano
+- `isr`: regeneración estática incremental en plataformas compatibles
+- `ssr: false`: ruta renderizada en el cliente
+- `cache` o `redirect`: comportamiento de respuesta a nivel de Nitro
+
+Elige route rules por grupo de rutas, no globalmente. Las páginas de marketing, los catálogos, los dashboards y las APIs suelen necesitar estrategias distintas.
+
+## Carga perezosa y rendimiento
+
+- Nuxt ya divide el código por página y ruta. Mantén fronteras de ruta significativas antes de micro-optimizar la división por componentes.
+- Usa el prefijo `Lazy` para importar dinámicamente componentes no críticos.
+- Renderiza condicionalmente los componentes lazy con `v-if` para que el chunk no se cargue hasta que la UI realmente lo necesite.
+- Usa hidratación perezosa para UI interactiva no crítica o por debajo del pliegue.
+
+```vue
+<template>
+  <LazyRecommendations v-if="showRecommendations" />
+  <LazyProductGallery hydrate-on-visible />
+</template>
+```
+
+- Para estrategias personalizadas, usa `defineLazyHydrationComponent()` con una estrategia de visibilidad o de inactividad.
+- La hidratación perezosa de Nuxt funciona con componentes de un solo archivo. Pasar props nuevas a un componente hidratado perezosamente dispara la hidratación de inmediato.
+- Usa `NuxtLink` para la navegación interna para que Nuxt pueda prefetchear los componentes de ruta y los payloads generados.
+
+## Lista de verificación de revisión
+
+- El primer render SSR y el render hidratado del cliente producen el mismo marcado
+- Los datos de página usan `useFetch` o `useAsyncData`, no `$fetch` de nivel superior
+- Los datos no críticos son lazy y tienen UI de carga explícita
+- Las route rules coinciden con los requisitos de SEO y frescura de la página
+- Las islas interactivas pesadas se cargan o hidratan de forma perezosa

package/vendor/theus-arsenal/skills/patrones-perl/SKILL.md

@@ -0,0 +1,508 @@
+---
+name: patrones-perl
+description: Idiomas de Perl moderno 5.36+, buenas prácticas y convenciones para construir aplicaciones Perl robustas y mantenibles.
+---
+
+# Patrones de desarrollo en Perl moderno
+
+Patrones idiomáticos de Perl 5.36+ y buenas prácticas para construir aplicaciones robustas y mantenibles.
+
+## Cuándo usarla
+
+- Al escribir código o módulos Perl nuevos.
+- Al revisar código Perl en busca de cumplimiento idiomático.
+- Al refactorizar Perl heredado hacia estándares modernos.
+- Al diseñar la arquitectura de módulos Perl.
+- Al migrar código anterior a 5.36 a Perl moderno.
+
+## Cómo funciona
+
+Aplica estos patrones como un sesgo hacia los valores por defecto de Perl 5.36+ moderno: signatures, módulos explícitos, manejo de errores enfocado y fronteras testeables. Los ejemplos siguientes están pensados para copiarse como punto de partida y luego ajustarse a la aplicación real, la pila de dependencias y el modelo de despliegue que tengas delante.
+
+## Principios fundamentales
+
+### 1. Usa el pragma `v5.36`
+
+Un único `use v5.36` reemplaza el boilerplate antiguo y habilita strict, warnings y signatures de subrutinas.
+
+```perl
+# Bien: preámbulo moderno
+use v5.36;
+
+sub greet($name) {
+    say "¡Hola, $name!";
+}
+
+# Mal: boilerplate heredado
+use strict;
+use warnings;
+use feature 'say', 'signatures';
+no warnings 'experimental::signatures';
+
+sub greet {
+    my ($name) = @_;
+    say "¡Hola, $name!";
+}
+```
+
+### 2. Signatures de subrutinas
+
+Usa signatures para dar claridad y comprobación automática de aridad.
+
+```perl
+use v5.36;
+
+# Bien: signatures con valores por defecto
+sub connect_db($host, $port = 5432, $timeout = 30) {
+    # $host es obligatorio; el resto tiene valores por defecto
+    return DBI->connect("dbi:Pg:host=$host;port=$port", undef, undef, {
+        RaiseError => 1,
+        PrintError => 0,
+    });
+}
+
+# Bien: parámetro slurpy para argumentos variables
+sub log_message($level, @details) {
+    say "[$level] " . join(' ', @details);
+}
+
+# Mal: desempaquetado manual de argumentos
+sub connect_db {
+    my ($host, $port, $timeout) = @_;
+    $port    //= 5432;
+    $timeout //= 30;
+    # ...
+}
+```
+
+### 3. Sensibilidad al contexto
+
+Entiende el contexto escalar vs. lista — un concepto central de Perl.
+
+```perl
+use v5.36;
+
+my @items = (1, 2, 3, 4, 5);
+
+my @copy  = @items;                # Contexto de lista: todos los elementos
+my $count = @items;                # Contexto escalar: la cuenta (5)
+say "Elementos: " . scalar @items; # Forzar contexto escalar
+```
+
+### 4. Desreferenciación postfija
+
+Usa la sintaxis de desreferenciación postfija para mayor legibilidad con estructuras anidadas.
+
+```perl
+use v5.36;
+
+my $data = {
+    users => [
+        { name => 'Alice', roles => ['admin', 'user'] },
+        { name => 'Bob',   roles => ['user'] },
+    ],
+};
+
+# Bien: desreferenciación postfija
+my @users = $data->{users}->@*;
+my @roles = $data->{users}[0]{roles}->@*;
+my %first = $data->{users}[0]->%*;
+
+# Mal: desreferenciación circunfija (más difícil de leer en cadenas)
+my @users = @{ $data->{users} };
+my @roles = @{ $data->{users}[0]{roles} };
+```
+
+### 5. El operador `isa` (5.32+)
+
+Comprobación de tipo infija — reemplaza `blessed($o) && $o->isa('X')`.
+
+```perl
+use v5.36;
+if ($obj isa 'My::Class') { $obj->do_something }
+```
+
+## Manejo de errores
+
+### Patrón eval/die
+
+```perl
+use v5.36;
+
+sub parse_config($path) {
+    my $content = eval { path($path)->slurp_utf8 };
+    die "Error de configuración: $@" if $@;
+    return decode_json($content);
+}
+```
+
+### Try::Tiny (manejo fiable de excepciones)
+
+```perl
+use v5.36;
+use Try::Tiny;
+
+sub fetch_user($id) {
+    my $user = try {
+        $db->resultset('User')->find($id)
+            // die "Usuario $id no encontrado\n";
+    }
+    catch {
+        warn "No se pudo obtener el usuario $id: $_";
+        undef;
+    };
+    return $user;
+}
+```
+
+### try/catch nativo (5.40+)
+
+```perl
+use v5.40;
+
+sub divide($x, $y) {
+    try {
+        die "División por cero" if $y == 0;
+        return $x / $y;
+    }
+    catch ($e) {
+        warn "Error: $e";
+        return;
+    }
+}
+```
+
+## OO moderna con Moo
+
+Prefiere Moo para OO moderna y ligera. Usa Moose solo cuando necesites su metaprotocolo.
+
+```perl
+# Bien: clase Moo
+package User;
+use Moo;
+use Types::Standard qw(Str Int ArrayRef);
+use namespace::autoclean;
+
+has name  => (is => 'ro', isa => Str, required => 1);
+has email => (is => 'ro', isa => Str, required => 1);
+has age   => (is => 'ro', isa => Int, default  => sub { 0 });
+has roles => (is => 'ro', isa => ArrayRef[Str], default => sub { [] });
+
+sub is_admin($self) {
+    return grep { $_ eq 'admin' } $self->roles->@*;
+}
+
+sub greet($self) {
+    return "Hola, soy " . $self->name;
+}
+
+1;
+
+# Uso
+my $user = User->new(
+    name  => 'Alice',
+    email => 'alice@example.com',
+    roles => ['admin', 'user'],
+);
+
+# Mal: hashref bendecido (sin validación, sin accessors)
+package User;
+sub new {
+    my ($class, %args) = @_;
+    return bless \%args, $class;
+}
+sub name { return $_[0]->{name} }
+1;
+```
+
+### Roles de Moo
+
+```perl
+package Role::Serializable;
+use Moo::Role;
+use JSON::MaybeXS qw(encode_json);
+requires 'TO_HASH';
+sub to_json($self) { encode_json($self->TO_HASH) }
+1;
+
+package User;
+use Moo;
+with 'Role::Serializable';
+has name  => (is => 'ro', required => 1);
+has email => (is => 'ro', required => 1);
+sub TO_HASH($self) { { name => $self->name, email => $self->email } }
+1;
+```
+
+### Palabra clave nativa `class` (5.38+, Corinna)
+
+```perl
+use v5.38;
+use feature 'class';
+no warnings 'experimental::class';
+
+class Point {
+    field $x :param;
+    field $y :param;
+    method magnitude() { sqrt($x**2 + $y**2) }
+}
+
+my $p = Point->new(x => 3, y => 4);
+say $p->magnitude;  # 5
+```
+
+## Expresiones regulares
+
+### Capturas con nombre y flag `/x`
+
+```perl
+use v5.36;
+
+# Bien: capturas con nombre y /x para legibilidad
+my $log_re = qr{
+    ^ (?<timestamp> \d{4}-\d{2}-\d{2} \s \d{2}:\d{2}:\d{2} )
+    \s+ \[ (?<level> \w+ ) \]
+    \s+ (?<message> .+ ) $
+}x;
+
+if ($line =~ $log_re) {
+    say "Hora: $+{timestamp}, Nivel: $+{level}";
+    say "Mensaje: $+{message}";
+}
+
+# Mal: capturas posicionales (difíciles de mantener)
+if ($line =~ /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\s+\[(\w+)\]\s+(.+)$/) {
+    say "Hora: $1, Nivel: $2";
+}
+```
+
+### Patrones precompilados
+
+```perl
+use v5.36;
+
+# Bien: compilar una vez, usar muchas
+my $email_re = qr/^[A-Za-z0-9._%+-]+\@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
+
+sub validate_emails(@emails) {
+    return grep { $_ =~ $email_re } @emails;
+}
+```
+
+## Estructuras de datos
+
+### Referencias y acceso profundo seguro
+
+```perl
+use v5.36;
+
+# Referencias a hashes y arrays
+my $config = {
+    database => {
+        host => 'localhost',
+        port => 5432,
+        options => ['utf8', 'sslmode=require'],
+    },
+};
+
+# Acceso profundo seguro (devuelve undef si falta algún nivel)
+my $port = $config->{database}{port};           # 5432
+my $missing = $config->{cache}{host};           # undef, sin error
+
+# Slices de hash
+my %subset;
+@subset{qw(host port)} = @{$config->{database}}{qw(host port)};
+
+# Slices de array
+my @first_two = $config->{database}{options}->@[0, 1];
+
+# Bucle for multivariable (experimental en 5.36, estable en 5.40)
+use feature 'for_list';
+no warnings 'experimental::for_list';
+for my ($key, $val) (%$config) {
+    say "$key => $val";
+}
+```
+
+## E/S de archivos
+
+### Open de tres argumentos
+
+```perl
+use v5.36;
+
+# Bien: open de tres argumentos con autodie (módulo core, elimina el 'or die')
+use autodie;
+
+sub read_file($path) {
+    open my $fh, '<:encoding(UTF-8)', $path;
+    local $/;
+    my $content = <$fh>;
+    close $fh;
+    return $content;
+}
+
+# Mal: open de dos argumentos (riesgo de inyección de shell, ver seguridad-perl)
+open FH, $path;            # NUNCA hagas esto
+open FH, "< $path";        # Sigue mal — datos de usuario en la cadena de modo
+```
+
+### Path::Tiny para operaciones con archivos
+
+```perl
+use v5.36;
+use Path::Tiny;
+
+my $file = path('config', 'app.json');
+my $content = $file->slurp_utf8;
+$file->spew_utf8($new_content);
+
+# Iterar un directorio
+for my $child (path('src')->children(qr/\.pl$/)) {
+    say $child->basename;
+}
+```
+
+## Organización de módulos
+
+### Estructura estándar de proyecto
+
+```text
+MyApp/
+├── lib/
+│   └── MyApp/
+│       ├── App.pm           # Módulo principal
+│       ├── Config.pm        # Configuración
+│       ├── DB.pm            # Capa de base de datos
+│       └── Util.pm          # Utilidades
+├── bin/
+│   └── myapp                # Script de entrada
+├── t/
+│   ├── 00-load.t            # Tests de compilación
+│   ├── unit/                # Tests unitarios
+│   └── integration/         # Tests de integración
+├── cpanfile                 # Dependencias
+├── Makefile.PL              # Sistema de build
+└── .perlcriticrc            # Configuración de linting
+```
+
+### Patrones con Exporter
+
+```perl
+package MyApp::Util;
+use v5.36;
+use Exporter 'import';
+
+our @EXPORT_OK   = qw(trim);
+our %EXPORT_TAGS = (all => \@EXPORT_OK);
+
+sub trim($str) { $str =~ s/^\s+|\s+$//gr }
+
+1;
+```
+
+## Herramientas
+
+### Configuración de perltidy (.perltidyrc)
+
+```text
+-i=4        # indentación de 4 espacios
+-l=100      # líneas de 100 caracteres
+-ci=4       # indentación de continuación
+-ce         # else "cuddled"
+-bar        # llave de apertura en la misma línea
+-nolq       # no desindentar strings entrecomillados largos
+```
+
+### Configuración de perlcritic (.perlcriticrc)
+
+```ini
+severity = 3
+theme = core + pbp + security
+
+[InputOutput::RequireCheckedSyscalls]
+functions = :builtins
+exclude_functions = say print
+
+[Subroutines::ProhibitExplicitReturnUndef]
+severity = 4
+
+[ValuesAndExpressions::ProhibitMagicNumbers]
+allowed_values = 0 1 2 -1
+```
+
+### Gestión de dependencias (cpanfile + carton)
+
+```bash
+cpanm App::cpanminus Carton   # Instalar herramientas
+carton install                 # Instalar deps del cpanfile
+carton exec -- perl bin/myapp  # Ejecutar con deps locales
+```
+
+```perl
+# cpanfile
+requires 'Moo', '>= 2.005';
+requires 'Path::Tiny';
+requires 'JSON::MaybeXS';
+requires 'Try::Tiny';
+
+on test => sub {
+    requires 'Test2::V0';
+    requires 'Test::MockModule';
+};
+```
+
+## Referencia rápida: idiomas de Perl moderno
+
+| Patrón heredado | Reemplazo moderno |
+|---|---|
+| `use strict; use warnings;` | `use v5.36;` |
+| `my ($x, $y) = @_;` | `sub foo($x, $y) { ... }` |
+| `@{ $ref }` | `$ref->@*` |
+| `%{ $ref }` | `$ref->%*` |
+| `open FH, "< $file"` | `open my $fh, '<:encoding(UTF-8)', $file` |
+| hashref bendecido | clase `Moo` con tipos |
+| `$1, $2, $3` | `$+{name}` (capturas con nombre) |
+| `eval { }; if ($@)` | `Try::Tiny` o `try/catch` nativo (5.40+) |
+| `BEGIN { require Exporter; }` | `use Exporter 'import';` |
+| Operaciones de archivo manuales | `Path::Tiny` |
+| `blessed($o) && $o->isa('X')` | `$o isa 'X'` (5.32+) |
+| `builtin::true / false` | `use builtin 'true', 'false';` (5.36+, experimental) |
+
+## Antipatrones
+
+```perl
+# 1. Open de dos argumentos (riesgo de seguridad)
+open FH, $filename;                     # NUNCA
+
+# 2. Sintaxis de objeto indirecta (parseo ambiguo)
+my $obj = new Foo(bar => 1);            # Mal
+my $obj = Foo->new(bar => 1);           # Bien
+
+# 3. Dependencia excesiva de $_
+map { process($_) } grep { validate($_) } @items;  # Difícil de seguir
+my @valid = grep { validate($_) } @items;           # Mejor: sepáralo
+my @results = map { process($_) } @valid;
+
+# 4. Desactivar strict refs
+no strict 'refs';                        # Casi siempre está mal
+${"My::Package::$var"} = $value;         # Usa un hash en su lugar
+
+# 5. Variables globales como configuración
+our $TIMEOUT = 30;                       # Mal: global mutable
+use constant TIMEOUT => 30;              # Mejor: constante
+# Lo mejor: atributo Moo con valor por defecto
+
+# 6. eval de string para cargar módulos
+eval "require $module";                  # Mal: riesgo de inyección de código
+eval "use $module";                      # Mal
+use Module::Runtime 'require_module';    # Bien: carga segura de módulos
+require_module($module);
+```
+
+**Recuerda**: el Perl moderno es limpio, legible y seguro. Deja que `use v5.36` se encargue del boilerplate, usa Moo para los objetos y prefiere los módulos de CPAN probados en batalla sobre las soluciones artesanales.
+
+## Skills relacionadas
+
+- `seguridad-perl`
+- `testing-perl`