theus-cli 0.2.83 → 0.2.84

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

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

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