theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-tinystruct/references/system-usage.md

@@ -0,0 +1,97 @@
+# Referencia de sistema y uso de tinystruct
+
+## Cuándo usarla
+
+Usa estos patrones para manejar el estado de la petición, gestionar sesiones web, implementar Server-Sent Events (SSE), manejar subidas de archivos o realizar peticiones HTTP salientes.
+
+## Cómo funciona
+
+### Context y argumentos de la CLI
+`Context` es el almacén principal de estado específico de la petición. Los flags de la CLI pasados como `--clave valor` se guardan en `Context` como `"--clave"`.
+
+### Gestión de sesiones
+Arquitectura conectable. El valor por defecto es `MemorySessionRepository`. Configura Redis en `application.properties`:
+```properties
+default.session.repository=org.tinystruct.http.RedisSessionRepository
+redis.host=127.0.0.1
+redis.port=6379
+```
+
+### Server-Sent Events (SSE)
+Soporte integrado para push en tiempo real. El `HttpServer` maneja automáticamente el ciclo de vida SSE cuando detecta la cabecera `Accept: text/event-stream`. Las conexiones se rastrean por ID de sesión en `SSEPushManager`.
+
+### Redes salientes
+Usa `URLRequest` y `HTTPHandler` para hacer peticiones HTTP a servicios externos.
+
+## Ejemplos
+
+### Context y argumentos de la CLI
+```java
+@Action("echo")
+public String echo() {
+    // CLI: bin/dispatcher echo --words "Hola mundo"
+    Object words = getContext().getAttribute("--words");
+    if (words != null) return words.toString();
+    return "No se proporcionaron palabras";
+}
+```
+
+### Gestión de sesiones
+```java
+@Action(value = "login", mode = Mode.HTTP_POST)
+public String login(Request<?, ?> request) {
+    request.getSession().setAttribute("userId", "42");
+    return "Sesión iniciada";
+}
+```
+
+### Server-Sent Events (SSE)
+```java
+@Action("sse/connect")
+public String connect() {
+    return "{\"type\":\"connect\",\"message\":\"Conectado\"}";
+}
+
+// En otro método o manejador de eventos:
+String sessionId = getContext().getId();
+SSEPushManager.getInstance().push(sessionId, new Builder().put("msg", "hola"));
+```
+
+### Subida de archivos
+```java
+import org.tinystruct.data.FileEntity;
+
+@Action(value = "upload", mode = Mode.HTTP_POST)
+public String upload(Request<?, ?> request) throws ApplicationException {
+    List<FileEntity> files = request.getAttachments();
+    if (files != null) {
+        for (FileEntity file : files) {
+            // file.getFilename(), file.getContent()
+        }
+    }
+    return "Subido";
+}
+```
+
+### HTTP saliente
+```java
+import org.tinystruct.net.URLRequest;
+import org.tinystruct.net.handlers.HTTPHandler;
+
+URLRequest request = new URLRequest(new URL("https://api.example.com"));
+request.setMethod("POST").setBody("{\"data\":\"val\"}");
+
+HTTPHandler handler = new HTTPHandler();
+var response = handler.handleRequest(request);
+if (response.getStatusCode() == 200) {
+    String body = response.getBody();
+}
+```
+
+### Sistema de eventos
+Registra manejadores en `init()` para ejecutar tareas asíncronas.
+```java
+EventDispatcher.getInstance().registerHandler(MyEvent.class, event -> {
+    CompletableFuture.runAsync(() -> doHeavyWork(event.getPayload()));
+});
+```

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

@@ -0,0 +1,72 @@
+# Patrones de testing en tinystruct
+
+## Cuándo usarla
+
+Usa estos patrones al escribir tests unitarios para tus aplicaciones con **JUnit 5**. Esenciales para verificar la lógica de las acciones, el registro de rutas y el comportamiento de los modos HTTP.
+
+## Cómo funciona
+
+### Tests unitarios de aplicaciones
+`ActionRegistry` es un singleton. Para probar una aplicación:
+1. Instancia la aplicación.
+2. Proporciona un objeto `Settings` (dispara `init()` y el procesamiento de anotaciones).
+3. Usa `app.invoke(path, args)` para probar la lógica directamente.
+
+### Tests de integración HTTP
+Para tests que involucren el servidor HTTP integrado:
+1. Arranca `HttpServer` en un hilo en segundo plano.
+2. Usa `ApplicationManager.call("start", context, Action.Mode.CLI)` para iniciarlo.
+3. Espera a que el puerto esté abierto usando un `Socket`.
+4. Usa `URLRequest` y `HTTPHandler` para realizar peticiones reales.
+
+## Ejemplos
+
+### Test unitario
+```java
+import org.junit.jupiter.api.*;
+import org.tinystruct.system.Settings;
+
+class MyAppTest {
+    private MyApp app;
+
+    @BeforeEach
+    void setUp() {
+        app = new MyApp();
+        app.setConfiguration(new Settings());
+        app.init(); // dispara el procesamiento de @Action y registra todas las acciones
+    }
+
+    @Test
+    void testHello() throws Exception {
+        Object result = app.invoke("hello");
+        Assertions.assertEquals("Hello!", result);
+    }
+
+    @Test
+    void testGreet() throws Exception {
+        Object result = app.invoke("greet", new Object[]{"James"});
+        Assertions.assertEquals("Hello, James!", result);
+    }
+}
+```
+
+### Test de coincidencia en ActionRegistry
+```java
+@Test
+void testRouting() {
+    ActionRegistry registry = ActionRegistry.getInstance();
+    Action action = registry.getAction("greet/James");
+    Assertions.assertNotNull(action);
+}
+```
+
+### Patrón de integración HTTP
+Referencia: `src/test/java/org/tinystruct/system/HttpServerHttpModeTest.java`
+
+```java
+// Patrón:
+// 1. Arranca el servidor en un hilo
+// 2. Sondea la disponibilidad del puerto
+// 3. Envía la petición HTTP vía HTTPHandler
+// 4. Comprueba el cuerpo/estado de la respuesta
+```

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

@@ -0,0 +1,449 @@
+---
+name: patrones-vite
+description: Patrones de la herramienta de build Vite, incluyendo configuración, plugins, HMR, variables de entorno, configuración de proxy, SSR, modo librería, pre-bundling de dependencias y optimización del build. Actívala al trabajar con vite.config.ts, plugins de Vite o proyectos basados en Vite.
+---
+
+# Patrones de Vite
+
+Patrones de herramienta de build y servidor de desarrollo para proyectos con Vite 8+. Cubre configuración, variables de entorno, configuración de proxy, modo librería, pre-bundling de dependencias y errores comunes en producción.
+
+## Cuándo usarla
+
+- Al configurar `vite.config.ts` o `vite.config.js`
+- Al configurar variables de entorno o archivos `.env`
+- Al configurar el proxy del servidor de desarrollo hacia backends de API
+- Al optimizar la salida del build (chunks, minificación, assets)
+- Al publicar librerías con `build.lib`
+- Al depurar el pre-bundling de dependencias o la interoperabilidad CJS/ESM
+- Al depurar errores de HMR, del servidor de desarrollo o del build
+- Al elegir u ordenar plugins de Vite
+
+## Cómo funciona
+
+- **El modo dev** sirve los archivos fuente como ESM nativo — sin bundling. Las transformaciones ocurren bajo demanda por cada petición de módulo, y por eso los arranques en frío son rápidos y el HMR es preciso.
+- **El modo build** usa Rolldown (v7+) o Rollup (v5–v6) para empaquetar la aplicación para producción con tree-shaking, code-splitting y minificación basada en Oxc.
+- **El pre-bundling de dependencias** convierte una sola vez las dependencias CJS/UMD a ESM mediante esbuild y cachea el resultado en `node_modules/.vite`, de modo que los arranques siguientes se saltan el trabajo.
+- **Los plugins** comparten una interfaz unificada entre dev y build — el mismo objeto de plugin funciona tanto para las transformaciones bajo demanda del servidor de desarrollo como para la tubería de producción.
+- **Las variables de entorno** se incrustan estáticamente en tiempo de build. Las variables con prefijo `VITE_` se convierten en constantes públicas dentro del bundle; todo lo que no lleve prefijo es invisible para el código del cliente.
+
+## Ejemplos
+
+### Estructura de la configuración
+
+#### Configuración básica
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: { '@': new URL('./src', import.meta.url).pathname },
+  },
+})
+```
+
+#### Configuración condicional
+
+```typescript
+// vite.config.ts
+import { defineConfig, loadEnv } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig(({ command, mode }) => {
+  const env = loadEnv(mode, process.cwd())   // solo prefijo VITE_ (seguro)
+
+  return {
+    plugins: [react()],
+    server: command === 'serve' ? { port: 3000 } : undefined,
+    define: {
+      __API_URL__: JSON.stringify(env.VITE_API_URL),
+    },
+  }
+})
+```
+
+#### Opciones clave de configuración
+
+| Clave | Valor por defecto | Descripción |
+|-----|---------|-------------|
+| `root` | `'.'` | Raíz del proyecto (donde vive `index.html`) |
+| `base` | `'/'` | Ruta base pública de los assets desplegados |
+| `envPrefix` | `'VITE_'` | Prefijo de las variables de entorno expuestas al cliente |
+| `build.outDir` | `'dist'` | Directorio de salida |
+| `build.minify` | `'oxc'` | Minificador (`'oxc'`, `'terser'` o `false`) |
+| `build.sourcemap` | `false` | `true`, `'inline'` u `'hidden'` |
+
+### Plugins
+
+#### Plugins esenciales
+
+La mayoría de necesidades de plugins están cubiertas por un puñado de paquetes bien mantenidos. Recurre a estos antes de escribir el tuyo.
+
+| Plugin | Propósito | Cuándo usarlo |
+|--------|---------|-------------|
+| `@vitejs/plugin-react-swc` | HMR de React + Fast Refresh vía SWC | Opción por defecto para apps React (más rápido que la variante Babel) |
+| `@vitejs/plugin-react` | HMR de React + Fast Refresh vía Babel | Solo si necesitas plugins de Babel (emotion, decoradores de MobX) |
+| `@vitejs/plugin-vue` | Soporte de SFC de Vue 3 | Apps Vue |
+| `vite-plugin-checker` | Ejecuta `tsc` + ESLint en un hilo worker con overlay de HMR | **Cualquier app TypeScript** — Vite NO chequea tipos durante `vite build` |
+| `vite-tsconfig-paths` | Respeta los alias `paths` de `tsconfig.json` | Siempre que ya tengas alias en `tsconfig.json` |
+| `vite-plugin-dts` | Emite archivos `.d.ts` en modo librería | Al publicar librerías TypeScript |
+| `vite-plugin-svgr` | Importa SVGs como componentes React | Apps React que usan SVGs como componentes |
+| `rollup-plugin-visualizer` | Reporte treemap/sunburst del bundle | Auditorías periódicas del tamaño del bundle (usa `enforce: 'post'`) |
+| `vite-plugin-pwa` | PWA sin configuración + Workbox | Apps con soporte offline |
+
+**Advertencia crítica:** `vite build` transpila pero NO chequea tipos. Los errores de tipos llegan silenciosamente a producción a menos que agregues `vite-plugin-checker` o ejecutes `tsc --noEmit` en CI.
+
+#### Creación de plugins propios
+
+Escribir plugins propios es poco frecuente — la mayoría de necesidades ya están cubiertas por plugins existentes. Cuando de verdad necesites uno, empieza en línea dentro de `vite.config.ts` y extráelo solo si se reutiliza.
+
+```typescript
+// vite.config.ts — plugin mínimo en línea
+function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',                       // obligatorio, debe ser único
+    enforce: 'pre',                           // 'pre' | 'post' (opcional)
+    apply: 'build',                           // 'build' | 'serve' (opcional)
+    transform(code, id) {
+      if (!id.endsWith('.custom')) return
+      return { code: transformCustom(code), map: null }
+    },
+  }
+}
+```
+
+**Hooks clave:** `transform` (modificar el código fuente), `resolveId` + `load` (módulos virtuales), `transformIndexHtml` (inyectar en el HTML), `configureServer` (añadir middleware de dev), `hotUpdate` (HMR personalizado — reemplaza al obsoleto `handleHotUpdate` en v7+).
+
+**Los módulos virtuales** usan la convención del prefijo `\0` — `resolveId` devuelve `'\0virtual:my-id'` para que los demás plugins lo omitan. El código de usuario importa `'virtual:my-id'`.
+
+Para la API completa de plugins, consulta [vite.dev/guide/api-plugin](https://vite.dev/guide/api-plugin). Usa `vite-plugin-inspect` durante el desarrollo para depurar la tubería de transformación.
+
+### API de HMR
+
+Los plugins de framework (`@vitejs/plugin-react`, `@vitejs/plugin-vue`, etc.) gestionan el HMR automáticamente. Recurre a `import.meta.hot` directamente solo al construir stores de estado personalizados, herramientas de desarrollo o utilidades agnósticas de framework que necesiten persistir estado entre actualizaciones.
+
+```typescript
+// src/store.ts — HMR manual para un módulo vanilla
+if (import.meta.hot) {
+  // Persistir estado entre actualizaciones (hay que MUTAR, nunca reasignar .data)
+  import.meta.hot.data.count = import.meta.hot.data.count ?? 0
+
+  // Limpiar efectos secundarios antes de que el módulo sea reemplazado
+  import.meta.hot.dispose((data) => clearInterval(data.intervalId))
+
+  // Aceptar las actualizaciones del propio módulo
+  import.meta.hot.accept()
+}
+```
+
+Todo el código de `import.meta.hot` se elimina por tree-shaking de los builds de producción — no hace falta retirar los guards.
+
+### Variables de entorno
+
+Vite carga `.env`, `.env.local`, `.env.[mode]` y `.env.[mode].local` en ese orden (lo posterior sobrescribe lo anterior); los archivos `*.local` están en gitignore y se destinan a secretos locales.
+
+#### Acceso desde el cliente
+
+Solo las variables con prefijo `VITE_` se exponen al código del cliente:
+
+```typescript
+import.meta.env.VITE_API_URL   // string
+import.meta.env.MODE            // 'development' | 'production' | personalizado
+import.meta.env.BASE_URL        // valor de la config base
+import.meta.env.DEV             // boolean
+import.meta.env.PROD            // boolean
+import.meta.env.SSR             // boolean
+```
+
+#### Uso de variables de entorno en la configuración
+
+```typescript
+// vite.config.ts
+import { defineConfig, loadEnv } from 'vite'
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd())          // solo prefijo VITE_ (seguro)
+  return {
+    define: {
+      __API_URL__: JSON.stringify(env.VITE_API_URL),
+    },
+  }
+})
+```
+
+### Seguridad
+
+#### El prefijo `VITE_` NO es una frontera de seguridad
+
+Cualquier variable con prefijo `VITE_` se **incrusta estáticamente en el bundle del cliente en tiempo de build**. La minificación, la codificación base64 y desactivar los source maps NO la ocultan. Un atacante decidido puede extraer cualquier variable `VITE_` del JavaScript publicado.
+
+**Regla:** Solo los valores públicos (URLs de API, feature flags, claves públicas) van en variables `VITE_`. Los secretos (tokens de API, URLs de base de datos, claves privadas) DEBEN vivir del lado del servidor detrás de una API o una función serverless.
+
+#### La trampa de `loadEnv('')`
+
+```typescript
+// MAL: pasar '' como tercer argumento carga TODAS las variables de entorno — incluidos
+// los secretos del servidor — y las deja disponibles para incrustarse en el código
+// del cliente vía `define`.
+const env = loadEnv(mode, process.cwd(), '')
+
+// BIEN: lista explícita de prefijos
+const env = loadEnv(mode, process.cwd(), ['VITE_', 'APP_'])
+```
+
+#### Source maps en producción
+
+Los source maps de producción filtran tu código fuente original. Desactívalos salvo que los subas a un rastreador de errores (Sentry, Bugsnag) y los borres localmente después:
+
+```typescript
+build: {
+  sourcemap: false,                                  // valor por defecto — mantenlo así
+}
+```
+
+#### Checklist de `.gitignore`
+
+- `.env.local`, `.env.*.local` — sobrescrituras locales con secretos
+- `dist/` — salida del build
+- `node_modules/.vite` — caché del pre-bundle (las entradas obsoletas causan errores fantasma)
+
+### Proxy del servidor
+
+```typescript
+// vite.config.ts — server.proxy
+server: {
+  proxy: {
+    '/foo': 'http://localhost:4567',                    // atajo con string
+
+    '/api': {
+      target: 'http://localhost:8080',
+      changeOrigin: true,                               // necesario para backends con virtual hosting
+      rewrite: (path) => path.replace(/^\/api/, ''),
+    },
+  },
+}
+```
+
+Para hacer proxy de WebSocket, añade `ws: true` a la configuración de la ruta.
+
+### Optimización del build
+
+#### Chunks manuales
+
+```typescript
+// vite.config.ts — build.rolldownOptions
+build: {
+  rolldownOptions: {
+    output: {
+      // Forma de objeto: agrupar paquetes específicos
+      manualChunks: {
+        'react-vendor': ['react', 'react-dom'],
+        'ui-vendor': ['@radix-ui/react-dialog', '@radix-ui/react-popover'],
+      },
+    },
+  },
+}
+```
+
+```typescript
+// Forma de función: dividir por heurística
+manualChunks(id) {
+  if (id.includes('node_modules/react')) return 'react-vendor'
+  if (id.includes('node_modules')) return 'vendor'
+}
+```
+
+### Rendimiento
+
+#### Evita los barrel files
+
+Los barrel files (un `index.ts` que reexporta todo lo de un directorio) obligan a Vite a cargar cada archivo reexportado aunque importes un solo símbolo. Es la causa #1 de lentitud del servidor de desarrollo señalada por la documentación oficial.
+
+```typescript
+// MAL — importar una sola utilidad obliga a Vite a cargar el barrel completo
+import { slash } from '@/utils'
+
+// BIEN — import directo, solo se carga ese archivo
+import { slash } from '@/utils/slash'
+```
+
+#### Sé explícito con las extensiones de import
+
+Cada extensión implícita fuerza hasta 6 comprobaciones del sistema de archivos vía `resolve.extensions`. En bases de código grandes, esto se acumula.
+
+```typescript
+// MAL
+import Component from './Component'
+
+// BIEN
+import Component from './Component.tsx'
+```
+
+Acota `allowImportingTsExtensions` en `tsconfig.json` y `resolve.extensions` a solo las extensiones que realmente uses.
+
+#### Precalienta las rutas de camino caliente
+
+`server.warmup.clientFiles` pre-transforma las entradas calientes conocidas antes de que el navegador las solicite — eliminando la cascada de peticiones de la carga en frío en apps grandes.
+
+```typescript
+// vite.config.ts
+server: {
+  warmup: {
+    clientFiles: ['./src/main.tsx', './src/routes/**/*.tsx'],
+  },
+}
+```
+
+#### Perfilado de servidores de desarrollo lentos
+
+Cuando `vite dev` se siente lento, empieza con `vite --profile`, interactúa con la app y luego pulsa `p+enter` para guardar un `.cpuprofile`. Cárgalo en [Speedscope](https://www.speedscope.app) para encontrar qué plugins consumen el tiempo — normalmente los hooks `buildStart`, `config` o `configResolved` de plugins de la comunidad.
+
+### Modo librería
+
+Al publicar un paquete npm, usa `build.lib`. Dos trampas importan más que el detalle de la configuración:
+
+1. **Los tipos no se emiten** — añade `vite-plugin-dts` o ejecuta `tsc --emitDeclarationOnly` por separado.
+2. **Las peer dependencies DEBEN externalizarse** — las peers no listadas quedan empaquetadas dentro de tu librería, causando errores de runtime duplicado en los consumidores.
+
+```typescript
+// vite.config.ts
+build: {
+  lib: {
+    entry: 'src/index.ts',
+    formats: ['es', 'cjs'],
+    fileName: (format) => `my-lib.${format}.js`,
+  },
+  rolldownOptions: {
+    external: ['react', 'react-dom', 'react/jsx-runtime'],  // cada peer dependency
+  },
+}
+```
+
+### Externals en SSR
+
+Los montajes desnudos con `createServer({ middlewareMode: true })` son territorio de autores de frameworks. La mayoría de apps deberían usar Nuxt, Remix, SvelteKit, Astro o TanStack Start en su lugar. Lo que sí ajustarás como usuario de framework es la configuración de externals cuando alguna dependencia se rompa en SSR:
+
+```typescript
+// vite.config.ts — opciones ssr
+ssr: {
+  external: ['node-native-package'],           // mantener como require() en el bundle SSR
+  noExternal: ['esm-only-package'],            // forzar su empaquetado en la salida SSR (arregla la mayoría de errores de SSR)
+  target: 'node',                              // 'node' o 'webworker'
+}
+```
+
+### Pre-bundling de dependencias
+
+Vite pre-empaqueta las dependencias para convertir CJS/UMD a ESM y reducir el número de peticiones.
+
+```typescript
+// vite.config.ts — optimizeDeps
+optimizeDeps: {
+  include: [
+    'lodash-es',                              // forzar el pre-bundle de dependencias pesadas conocidas
+    'cjs-package',                            // dependencias CJS que causan problemas de interoperabilidad
+    'deep-lib/components/**',                 // glob para imports profundos
+  ],
+  exclude: ['local-esm-package'],             // debe ser ESM válido si se excluye
+  force: true,                                // ignorar la caché, re-optimizar (depuración temporal)
+}
+```
+
+### Errores comunes
+
+#### Dev no coincide con build
+
+Dev usa esbuild/Rolldown para las transformaciones; build usa Rolldown para el empaquetado. Las librerías CJS pueden comportarse de forma diferente entre ambos. Verifica siempre con `vite build && vite preview` antes de desplegar.
+
+#### Chunks obsoletos tras un despliegue
+
+Los builds nuevos producen hashes de chunk nuevos. Los usuarios con sesiones activas piden nombres de archivo antiguos que ya no existen. Vite no tiene solución integrada. Mitigaciones:
+
+- Mantén vivos los archivos antiguos de `dist/assets/` durante una ventana de despliegue
+- Captura los errores de import dinámico en tu router y fuerza una recarga de página
+
+#### Docker y contenedores
+
+Vite se enlaza a `localhost` por defecto, que es inalcanzable desde fuera de un contenedor:
+
+```typescript
+// vite.config.ts — configuración para Docker/contenedores
+server: {
+  host: true,                                  // enlazar a 0.0.0.0
+  hmr: { clientPort: 3000 },                   // si está detrás de un proxy inverso
+}
+```
+
+#### Acceso a archivos en monorepos
+
+Vite restringe el servido de archivos a la raíz del proyecto. Los paquetes fuera de la raíz quedan bloqueados:
+
+```typescript
+// vite.config.ts — acceso a archivos en monorepo
+server: {
+  fs: {
+    allow: ['..'],                             // permitir el directorio padre (raíz del workspace)
+  },
+}
+```
+
+### Antipatrones
+
+```typescript
+// MAL: fijar envPrefix a '' expone TODAS las variables de entorno (incluidos secretos) al cliente
+envPrefix: ''
+
+// MAL: asumir que require() funciona en el código fuente de la app — Vite es ESM-first
+const lib = require('some-lib')                // usa import en su lugar
+
+// MAL: dividir cada node_module en su propio chunk — crea cientos de archivos diminutos
+manualChunks(id) {
+  if (id.includes('node_modules')) {
+    return id.split('node_modules/')[1].split('/')[0]   // un chunk por paquete
+  }
+}
+
+// MAL: no externalizar las peer deps en modo librería — causa errores de runtime duplicado
+// build.lib sin rolldownOptions.external
+
+// MAL: usar el minificador esbuild obsoleto
+build: { minify: 'esbuild' }                  // usa 'oxc' (por defecto) o 'terser'
+
+// MAL: mutar import.meta.hot.data por reasignación
+import.meta.hot.data = { count: 0 }           // INCORRECTO: hay que mutar propiedades, no reasignar
+import.meta.hot.data.count = 0                 // CORRECTO
+```
+
+**Antipatrones de proceso:**
+
+- **`vite preview` NO es un servidor de producción** — es una prueba de humo del bundle compilado. Despliega `dist/` en un host estático real (NGINX, Cloudflare Pages, Vercel estático) o usa un Dockerfile multi-stage.
+- **Esperar que `vite build` chequee tipos** — solo transpila. Los errores de tipos llegan silenciosamente a producción. Añade `vite-plugin-checker` o ejecuta `tsc --noEmit` en CI.
+- **Incluir `@vitejs/plugin-legacy` por defecto** — infla los bundles ~40%, rompe los analizadores de bundle basados en source maps y es innecesario para el 95%+ de usuarios en navegadores modernos. Actívalo según analítica real, no por suposición.
+- **Escribir a mano 30+ entradas de `resolve.alias` que duplican los paths de `tsconfig.json`** — usa `vite-tsconfig-paths` en su lugar. Observado en Excalidraw y PostHog; evítalo en proyectos nuevos.
+- **Dejar un `node_modules/.vite` obsoleto tras cambios de dependencias** — la caché del pre-bundle causa errores fantasma. Límpiala al cambiar de rama o después de parchar dependencias.
+
+## Referencia rápida
+
+| Patrón | Cuándo usarlo |
+|---------|-------------|
+| `defineConfig` | Siempre — aporta inferencia de tipos |
+| `loadEnv(mode, root, ['VITE_'])` | Acceder a variables de entorno en la config (prefijo explícito) |
+| `vite-plugin-checker` | Cualquier app TypeScript (cubre el hueco del chequeo de tipos) |
+| `vite-tsconfig-paths` | En lugar de un `resolve.alias` escrito a mano |
+| `optimizeDeps.include` | Dependencias CJS con problemas de interoperabilidad |
+| `server.proxy` | Enrutar peticiones de API al backend en dev |
+| `server.host: true` | Docker, contenedores, acceso remoto |
+| `server.warmup.clientFiles` | Pre-transformar las rutas de camino caliente |
+| `build.lib` + `external` | Publicar paquetes npm |
+| `manualChunks` (objeto) | División del bundle de vendors |
+| `vite --profile` | Depurar un servidor de desarrollo lento |
+| `vite build && vite preview` | Prueba de humo local del bundle de producción (NO es un servidor de producción) |
+
+## Skills relacionadas
+
+- `patrones-frontend` — patrones de componentes React
+- `patrones-docker` — desarrollo en contenedores con Vite
+- `patrones-nextjs` — bundler alternativo para Next.js