theus-cli 0.2.83 → 0.2.84

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

@@ -1,469 +0,0 @@
----
-name: patrones-vue
-description: Patrones de la Composition API de Vue.js 3, arquitectura de componentes, buenas prácticas de reactividad, gestión de estado con Pinia, navegación con Vue Router y patrones SSR de Nuxt. Se activa en proyectos Vue, Nuxt, Vite o Pinia.
----
-
-# Patrones y buenas prácticas de Vue.js
-
-Guía integral para el desarrollo con Vue.js 3 usando la Composition API (`<script setup>`), cubriendo diseño de componentes, reactividad, gestión de estado, enrutado, testing y patrones SSR. Se incluye orientación específica de Nuxt donde difiere de Vue puro.
-
-## Cuándo activarla
-
-Activa esta skill cuando:
-- El proyecto use Vue.js (cualquier versión), Nuxt, Vite + Vue o Pinia.
-- El usuario pregunte por arquitectura de componentes Vue, composables, reactividad o gestión de estado.
-- Estés revisando Single-File Components de Vue (archivos `.vue`).
-- Estés configurando Vue Router, stores de Pinia o la configuración de Vite/Vitest.
-- Se discutan patrones de rendimiento, seguridad o SSR específicos de Vue.
-
----
-
-## 1. Estructura del proyecto
-
-### Distribución recomendada (feature-first)
-
-```
-src/
-├── api/              # Cliente de API y definición de endpoints
-├── assets/           # Assets estáticos (imágenes, fuentes, iconos)
-├── components/       # Componentes compartidos/reutilizables
-│   ├── base/         # Primitivas de UI base (Button, Input, Modal)
-│   └── features/     # Componentes compartidos específicos de una feature
-├── composables/      # Lógica reutilizable de la Composition API
-├── layouts/          # Layouts de página (opcional)
-├── pages/            # Componentes de página a nivel de ruta
-├── router/           # Configuración de Vue Router
-├── stores/           # Stores de Pinia
-├── types/            # Definiciones de tipos TypeScript
-├── utils/            # Funciones utilitarias puras
-└── App.vue           # Componente raíz
-```
-
-### Nombres de archivo
-
-| Convención | Cuándo usarla |
-|-----------|-------------|
-| `PascalCase.vue` | Todos los componentes (lo exige `vue/multi-word-component-names`) |
-| `useCamelCase.ts` | Composables |
-| `camelCase.ts` | Utilidades, clientes de API, tipos |
-| Directorios en `kebab-case` | Segmentos de ruta, carpetas de features |
-
----
-
-## 2. Arquitectura de componentes
-
-### Orden dentro del Single-File Component
-
-```vue
-<script setup lang="ts">
-// 1. Imports (vue → ecosistema → absolutos → relativos)
-// 2. Props, Emits y Slots
-// 3. Composables
-// 4. Estado local (ref/reactive)
-// 5. Propiedades computadas
-// 6. Métodos
-// 7. Watchers
-// 8. Hooks de ciclo de vida
-</script>
-
-<template>
-  <!-- Contenido del template -->
-</template>
-
-<style scoped>
-  /* Estilos con scope */
-</style>
-```
-
-### Presentacional vs contenedor
-
-- **Componentes contenedores**: Poseen la obtención de datos, el estado y los efectos secundarios. Renderizan componentes presentacionales.
-- **Componentes presentacionales**: Reciben props, emiten eventos. Sin llamadas a API, sin acceso al store. Renderizado puro.
-
-### Buenas prácticas con props
-
-```ts
-// Props basadas en tipos con valores por defecto
-interface Props {
-  label: string;
-  variant?: "primary" | "secondary";
-  disabled?: boolean;
-  items: Item[];
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  variant: "primary",
-  disabled: false,
-});
-```
-
-- Provee siempre `type`, y `required`/`default` cuando corresponda.
-- Props booleanas: `isXxx`, `hasXxx`, `canXxx`.
-- Nunca mutes las props — emite eventos en su lugar.
-- Para el enlace v-model, usa `defineModel()` (Vue 3.4+) o `modelValue` + `update:modelValue`.
-
-### Eventos
-
-```ts
-const emit = defineEmits<{
-  submit: [];
-  "update:modelValue": [value: string];
-  select: [id: string, index: number];
-}>();
-```
-
-- Usa kebab-case en los templates (`@update:model-value`).
-- Usa camelCase en el script (`emit("update:modelValue", val)`).
-
----
-
-## 3. Composables (lógica reutilizable)
-
-### Estructura
-
-```ts
-// composables/useDebounce.ts
-export function useDebounce<T>(value: MaybeRef<T>, delay: number): Ref<T> {
-  const debounced = ref(toValue(value)) as Ref<T>;
-
-  let timer: ReturnType<typeof setTimeout>;
-  watch(
-    () => toValue(value),
-    (newVal) => {
-      clearTimeout(timer);
-      timer = setTimeout(() => { debounced.value = newVal; }, delay);
-    }
-  );
-
-  onUnmounted(() => clearTimeout(timer));
-  return readonly(debounced);
-}
-```
-
-### Reglas
-
-- Deben comenzar con el prefijo `use`.
-- Devuelve valores reactivos (`ref`, `computed`, `reactive`), nunca primitivos planos.
-- Acepta entradas reactivas vía `MaybeRef` / `toRef()` / `toValue()`.
-- Limpia los efectos secundarios en `onUnmounted` o en el `onCleanup` del watcher.
-- Sin efectos secundarios a nivel de módulo.
-
-### vs mixins
-
-Los composables reemplazan por completo a los mixins de Vue 2:
-- **Mixins**: Flujo de datos opaco, colisiones de fuente de verdad, conflictos de nombres.
-- **Composables**: Imports explícitos, valores de retorno claros, componibles y aptos para tree-shaking.
-
----
-
-## 4. Gestión de estado
-
-### Cuándo usar cada opción
-
-| Patrón | Caso de uso |
-|---------|----------|
-| `ref()` / `reactive()` | Estado local del componente |
-| Props + Emits | Comunicación padre-hijo |
-| Provide / Inject | Tema, configuración, API de plugin |
-| Store de Pinia | Estado global, compartido y complejo |
-| Composable de estado de servidor | Datos de API con caché (envolver `fetch`/TanStack Query) |
-
-### Setup Store de Pinia (preferido)
-
-```ts
-// stores/useCartStore.ts
-export const useCartStore = defineStore("cart", () => {
-  const items = ref<CartItem[]>([]);
-  const isLoading = ref(false);
-
-  const totalPrice = computed(() =>
-    items.value.reduce((sum, i) => sum + i.price * i.quantity, 0)
-  );
-  const itemCount = computed(() =>
-    items.value.reduce((sum, i) => sum + i.quantity, 0)
-  );
-
-  async function addItem(productId: string) {
-    isLoading.value = true;
-    try {
-      const item = await fetchProduct(productId);
-      const existing = items.value.find(i => i.id === item.id);
-      if (existing) existing.quantity++;
-      else items.value.push({ ...item, quantity: 1 });
-    } finally {
-      isLoading.value = false;
-    }
-  }
-
-  return { items, isLoading, totalPrice, itemCount, addItem };
-});
-```
-
-- Usa la sintaxis Setup Store (no Options Store).
-- Prefiere acciones para mutaciones de nivel de negocio y `$patch()` para actualizaciones agrupadas.
-- Cada acción asíncrona: maneja carga + éxito + error.
-
----
-
-## 5. Vue Router
-
-### Definición de rutas
-
-```ts
-const routes = [
-  {
-    path: "/users/:id",
-    name: "user-detail",
-    component: () => import("@/pages/UserDetail.vue"), // lazy
-    props: true, // pasar los params como props
-    meta: { requiresAuth: true },
-  },
-];
-```
-
-### Guardias de navegación
-
-```ts
-router.beforeEach((to, from) => {
-  const { isLoggedIn } = useAuthStore();
-  if (to.meta.requiresAuth && !isLoggedIn) {
-    return { name: "login", query: { redirect: to.fullPath } };
-  }
-});
-```
-
-### Params de ruta reactivos
-
-Cuando un componente permanece montado pero los params de la ruta cambian:
-
-```ts
-const route = useRoute();
-const id = computed(() => route.params.id as string);
-watch(id, (newId) => fetchItem(newId));
-```
-
----
-
-## 6. Patrones de template
-
-### Sintaxis de template
-
-```vue
-<!-- v-if/v-else-if/v-else -->
-<div v-if="isLoading">Cargando...</div>
-<div v-else-if="error">Error: {{ error }}</div>
-<div v-else>{{ content }}</div>
-
-<!-- v-show para alternancias frecuentes -->
-<div v-show="isOpen">Contenido alternado</div>
-
-<!-- v-for con keys estables -->
-<div v-for="item in items" :key="item.id">{{ item.name }}</div>
-
-<!-- Lista filtrada por computed (no v-if + v-for en el mismo elemento) -->
-<div v-for="item in activeItems" :key="item.id">{{ item.name }}</div>
-
-<!-- Manejo de eventos -->
-<form @submit.prevent="handleSubmit">
-  <button type="submit">Guardar</button>
-</form>
-
-<!-- v-model -->
-<input v-model="name" />
-<CustomInput v-model="value" v-model:title="title" />
-```
-
----
-
-## 7. Rendimiento
-
-| Técnica | Cuándo usarla |
-|-----------|-------------|
-| `v-memo` | Ítems de lista que rara vez cambian |
-| `v-once` | Contenido renderizado una vez y estático para siempre |
-| `shallowRef()` | Estructuras de datos grandes reemplazadas en bloque |
-| `shallowReactive()` | Solo las propiedades de nivel superior son reactivas |
-| `v-show` sobre `v-if` | Alternancias de visibilidad frecuentes |
-| `<KeepAlive :max="10">` | Cachear vistas alternadas |
-| Rutas lazy | `() => import(...)` para rutas no críticas |
-| `Suspense` | Carga de componentes asíncronos con fallback |
-
----
-
-## 8. Testing
-
-### Stack
-
-- **Vitest** para tests unitarios y de componentes
-- **Vue Test Utils** para montaje e interacción
-- **@pinia/testing** para mockear stores
-- **Playwright** para E2E
-
-### Patrón de test de componente
-
-```ts
-import { mount } from "@vue/test-utils";
-import { createPinia, setActivePinia } from "pinia";
-import UserCard from "./UserCard.vue";
-
-beforeEach(() => { setActivePinia(createPinia()); });
-
-it("renderiza y emite", async () => {
-  const wrapper = mount(UserCard, {
-    props: { user: { id: "1", name: "Alice" } },
-  });
-  expect(wrapper.text()).toContain("Alice");
-  await wrapper.find("button").trigger("click");
-  expect(wrapper.emitted("select")![0]).toEqual(["1"]);
-});
-```
-
----
-
-## 9. Patrones específicos de Nuxt
-
-### Auto-imports
-
-Nuxt auto-importa `ref`, `computed`, `watch`, `useFetch`, `useAsyncData`, etc. Úsalos directamente sin importarlos. En proyectos que no sean Nuxt, importa siempre de forma explícita.
-
-### useAsyncData / useFetch
-
-```ts
-const { data: user, pending, error, refresh } = await useAsyncData(
-  "user", // clave única para el cacheo
-  () => $fetch(`/api/users/${id}`),
-);
-
-const { data: posts } = await useFetch("/api/posts", {
-  query: { page: 1 },
-  key: "posts-page-1", // deduplica peticiones
-});
-```
-
-### Rutas de servidor
-
-```ts
-// server/api/users/[id].ts
-export default defineEventHandler(async (event) => {
-  const { id } = await getValidatedRouterParams(event, z.object({
-    id: z.string().uuid(),
-  }).parse);
-  // ... obtener y devolver
-});
-```
-
-### Runtime Config
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  runtimeConfig: {
-    // solo servidor
-    apiSecret: "",
-    // público (expuesto al cliente)
-    public: {
-      apiBase: "https://api.example.com",
-    },
-  },
-});
-```
-
----
-
-## 10. Nuevas APIs de Vue 3.5+
-
-### Desestructuración reactiva de props
-
-Vue 3.5 estabilizó la desestructuración reactiva de props — las variables desestructuradas de `defineProps()` son reactivas automáticamente:
-
-```ts
-// Vue 3.5+: las props desestructuradas son reactivas (sin necesidad de toRefs)
-const { count = 0, msg = "hello" } = defineProps<{
-  count?: number;
-  msg?: string;
-}>();
-
-// Limitación: no se puede observar una prop desestructurada directamente
-watch(() => count, (newVal) => { ... }); // se requiere un getter
-```
-
-### `useTemplateRef()`
-
-Reemplaza las refs planas emparejadas por nombre con `useTemplateRef()` para referencias de template:
-
-```ts
-import { useTemplateRef } from "vue";
-const inputEl = useTemplateRef<HTMLInputElement>("input");
-// "input" coincide con el atributo ref="input" del template, no con el nombre de la variable
-```
-
-Soporta IDs de ref dinámicos: `useTemplateRef(dynamicRefId)`.
-
-### `onWatcherCleanup()`
-
-API de limpieza de watchers importable globalmente (Vue 3.5+). Debe llamarse de forma síncrona dentro del callback del watcher:
-
-```ts
-import { watch, onWatcherCleanup } from "vue";
-
-watch(userId, async (newId) => {
-  const controller = new AbortController();
-  onWatcherCleanup(() => controller.abort());
-  // ... fetch con signal
-});
-```
-
-### `useId()`
-
-Generación de IDs únicos estables en SSR para elementos de formulario y accesibilidad:
-
-```ts
-import { useId } from "vue";
-const id = useId();
-```
-
-### Teleport con `defer`
-
-`<Teleport defer>` permite teletransportar hacia destinos renderizados en el mismo ciclo:
-
-```vue
-<Teleport defer to="#container">Contenido</Teleport>
-<div id="container"></div>
-```
-
-### Hidratación diferida (SSR)
-
-`defineAsyncComponent()` ahora soporta la estrategia `hydrate`:
-
-```ts
-import { defineAsyncComponent, hydrateOnVisible } from "vue";
-const AsyncComp = defineAsyncComponent({
-  loader: () => import("./Comp.vue"),
-  hydrate: hydrateOnVisible(),
-});
-```
-
----
-
-## Antipatrones
-
-| Antipatrón | Por qué está mal | La corrección |
-|-------------|---------------|---------|
-| Desestructurar `defineProps()` (Vue < 3.5) | Captura una instantánea, pierde la reactividad | Accede vía `props.xxx` o usa `toRefs()` |
-| `watch()` sobre una prop desestructurada (Vue 3.5+) | Error en tiempo de compilación — las props desestructuradas no se pueden observar directamente | Usa un getter: `watch(() => count, ...)` |
-| `v-if` + `v-for` en el mismo elemento | Orden de ejecución ambiguo | Usa un array filtrado por computed |
-| Key de `v-for` = índice | Estado roto al reordenar | Usa IDs estables de la base de datos |
-| Mutar props | Viola el flujo de datos unidireccional | Emite eventos o usa `v-model` |
-| `v-html` con contenido de usuario | Vulnerabilidad XSS | Sanitiza con DOMPurify |
-| Mixins en Vue 3 | Opacos, propensos a colisiones | Reemplázalos con composables |
-| Efectos secundarios a nivel de módulo en un composable | Compartidos entre instancias | Acótalos en `onMounted` + `onUnmounted` |
-| `reactive()` para estado reemplazable | El reemplazo rompe la reactividad | Usa `ref()` en su lugar |
-| Watcher sin limpieza | Fugas de memoria, condiciones de carrera | Usa `onCleanup` u `onWatcherCleanup()` (Vue 3.5+) |
-| Options API en código Vue 3 nuevo | El ecosistema migró a la Composition API | Usa `<script setup>` |
-| Ref plana para referencias de template | Sin soporte de refs dinámicas, el emparejamiento por nombre es frágil | Usa `useTemplateRef()` (Vue 3.5+) |
-
-## Skills relacionadas
-
-- `accesibilidad` — ARIA, HTML semántico, gestión del foco
-- `patrones-frontend` — Arquitectura frontend transversal a frameworks
-- `estandares-codigo` — Estándares generales de calidad de código

package/vendor/theus-arsenal/skills/persistencia-actores-swift/SKILL.md

@@ -1,148 +0,0 @@
----
-name: persistencia-actores-swift
-description: Persistencia de datos thread-safe en Swift usando actores — caché en memoria con almacenamiento respaldado en archivo, eliminando data races por diseño con el compilador como garante.
----
-
-# Actores de Swift para persistencia thread-safe
-
-Patrones para construir capas de persistencia de datos thread-safe usando actores de Swift. Combina caché en memoria con almacenamiento respaldado en archivo, aprovechando el modelo de actores para eliminar los data races en tiempo de compilación.
-
-## Cuándo activarla
-
-- Construir una capa de persistencia de datos en Swift 5.5+
-- Necesitar acceso thread-safe a estado mutable compartido
-- Querer eliminar la sincronización manual (locks, DispatchQueues)
-- Construir apps offline-first con almacenamiento local
-
-## Patrón central
-
-### Repositorio basado en actor
-
-El modelo de actores garantiza acceso serializado — sin data races, con verificación del compilador.
-
-```swift
-public actor LocalRepository<T: Codable & Identifiable> where T.ID == String {
-    private var cache: [String: T] = [:]
-    private let fileURL: URL
-
-    public init(directory: URL = .documentsDirectory, filename: String = "data.json") {
-        self.fileURL = directory.appendingPathComponent(filename)
-        // Carga síncrona durante init (el aislamiento del actor aún no está activo)
-        self.cache = Self.loadSynchronously(from: fileURL)
-    }
-
-    // MARK: - API pública
-
-    public func save(_ item: T) throws {
-        cache[item.id] = item
-        try persistToFile()
-    }
-
-    public func delete(_ id: String) throws {
-        cache[id] = nil
-        try persistToFile()
-    }
-
-    public func find(by id: String) -> T? {
-        cache[id]
-    }
-
-    public func loadAll() -> [T] {
-        Array(cache.values)
-    }
-
-    // MARK: - Privado
-
-    private func persistToFile() throws {
-        let data = try JSONEncoder().encode(Array(cache.values))
-        try data.write(to: fileURL, options: .atomic)
-    }
-
-    private static func loadSynchronously(from url: URL) -> [String: T] {
-        guard let data = try? Data(contentsOf: url),
-              let items = try? JSONDecoder().decode([T].self, from: data) else {
-            return [:]
-        }
-        return Dictionary(uniqueKeysWithValues: items.map { ($0.id, $0) })
-    }
-}
-```
-
-### Uso
-
-Todas las llamadas son automáticamente async por el aislamiento del actor:
-
-```swift
-let repository = LocalRepository<Question>()
-
-// Lectura — búsqueda O(1) rápida desde la caché en memoria
-let question = await repository.find(by: "q-001")
-let allQuestions = await repository.loadAll()
-
-// Escritura — actualiza la caché y persiste al archivo de forma atómica
-try await repository.save(newQuestion)
-try await repository.delete("q-001")
-```
-
-### Combinación con un ViewModel @Observable
-
-```swift
-@Observable
-final class QuestionListViewModel {
-    private(set) var questions: [Question] = []
-    private let repository: LocalRepository<Question>
-
-    init(repository: LocalRepository<Question> = LocalRepository()) {
-        self.repository = repository
-    }
-
-    func load() async {
-        questions = await repository.loadAll()
-    }
-
-    func add(_ question: Question) async throws {
-        try await repository.save(question)
-        questions = await repository.loadAll()
-    }
-}
-```
-
-## Decisiones de diseño clave
-
-| Decisión | Justificación |
-|----------|---------------|
-| Actor (no clase + lock) | Thread safety verificada por el compilador, sin sincronización manual |
-| Caché en memoria + persistencia en archivo | Lecturas rápidas desde caché, escrituras duraderas a disco |
-| Carga síncrona en init | Evita la complejidad de la inicialización async |
-| Diccionario indexado por ID | Búsquedas O(1) por identificador |
-| Genérico sobre `Codable & Identifiable` | Reutilizable con cualquier tipo de modelo |
-| Escrituras atómicas (`.atomic`) | Evita escrituras parciales ante un crash |
-
-## Buenas prácticas
-
-- **Usa tipos `Sendable`** para todos los datos que crucen fronteras de actores
-- **Mantén mínima la API pública del actor** — expón solo operaciones de dominio, no detalles de persistencia
-- **Usa escrituras `.atomic`** para evitar corrupción de datos si la app crashea a mitad de escritura
-- **Carga de forma síncrona en `init`** — los inicializadores async añaden complejidad con beneficio mínimo para archivos locales
-- **Combínalo con ViewModels `@Observable`** para actualizaciones reactivas de la UI
-
-## Antipatrones a evitar
-
-- Usar `DispatchQueue` o `NSLock` en lugar de actores en código nuevo de concurrencia Swift
-- Exponer el diccionario de caché interno a llamadores externos
-- Hacer configurable la URL del archivo sin validación
-- Olvidar que toda llamada a un método del actor es `await` — los llamadores deben manejar el contexto async
-- Usar `nonisolated` para saltarse el aislamiento del actor (anula su propósito)
-
-## Cuándo usarla
-
-- Almacenamiento local de datos en apps iOS/macOS (datos de usuario, ajustes, contenido cacheado)
-- Arquitecturas offline-first que sincronizan con un servidor después
-- Cualquier estado mutable compartido al que accedan concurrentemente varias partes de la app
-- Reemplazar thread safety heredada basada en `DispatchQueue` con concurrencia Swift moderna
-
-## Skills relacionadas
-
-- `concurrencia-swift-6-2`
-- `testing-protocolos-di-swift`
-- `patrones-swiftui`