theus-cli 0.2.83 → 0.2.85

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

@@ -1,420 +0,0 @@
----
-name: patrones-mysql
-description: Patrones de esquema, consultas, indexación, transacciones, replicación y pools de conexiones para MySQL y MariaDB en backends de producción.
----
-
-# Patrones de MySQL
-
-Usa esta skill al trabajar en diseño de esquemas de MySQL o MariaDB, migraciones,
-investigación de consultas lentas, transacciones de tipo cola, pools de conexiones
-o configuración de bases de datos en producción. Prefiere comprobaciones exactas de
-versión antes de aplicar un patrón específico de una funcionalidad, porque MySQL y
-MariaDB han divergido en varios detalles de SQL.
-
-## Activación
-
-- Diseñar tablas, índices y constraints de MySQL o MariaDB
-- Revisar migraciones antes de ejecutarlas sobre tablas grandes de producción
-- Depurar consultas lentas, esperas de locks, deadlocks o agotamiento de conexiones
-- Añadir paginación por keyset, upserts, búsqueda full-text, columnas JSON o colas
-- Configurar pools de conexiones de la aplicación, réplicas de lectura, TLS o logs de consultas lentas
-
-## Comprobación de versión
-
-Empieza identificando el motor y la versión:
-
-```sql
-SELECT VERSION();
-SHOW VARIABLES LIKE 'version_comment';
-```
-
-Mantén separadas las recomendaciones de MySQL y MariaDB cuando la sintaxis difiere:
-
-- MySQL documenta los alias de fila como el reemplazo de `VALUES(col)` en
-  `ON DUPLICATE KEY UPDATE`; `VALUES(col)` está deprecado ahí.
-- MariaDB documenta `VALUES(col)` como la forma soportada de referenciar los
-  valores insertados en `ON DUPLICATE KEY UPDATE`; úsalo para compatibilidad
-  entre motores.
-- `SKIP LOCKED` es apropiado solo para trabajo de tipo cola. Salta las filas
-  bloqueadas y puede devolver una vista inconsistente, así que no lo uses para
-  lecturas contables generales ni sensibles a la integridad.
-
-## Valores por defecto de esquema
-
-```sql
-CREATE TABLE orders (
-    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
-    account_id BIGINT UNSIGNED NOT NULL,
-    status VARCHAR(32) NOT NULL,
-    total DECIMAL(15, 2) NOT NULL,
-    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-    deleted_at DATETIME NULL,
-    PRIMARY KEY (id),
-    KEY idx_orders_account_status_created (account_id, status, created_at),
-    KEY idx_orders_active (account_id, deleted_at)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-```
-
-Elecciones por defecto:
-
-| Caso de uso | Prefiere | Evita |
-| --- | --- | --- |
-| Claves primarias sustitutas | `BIGINT UNSIGNED AUTO_INCREMENT` | `INT` en tablas que pueden superar 2 000 millones de filas |
-| Claves de búsqueda UUID | `BINARY(16)` con helpers de conversión | Claves primarias `VARCHAR(36)` en tablas calientes |
-| Dinero y cantidades exactas | `DECIMAL(p, s)` | `FLOAT` o `DOUBLE` |
-| Texto visible al usuario | Tablas e índices en `utf8mb4` | Los defaults `utf8` / `utf8mb3` de MySQL |
-| Timestamps de aplicación | `DATETIME` con UTC gestionado por la app | Suponer que `DATETIME` guarda metadatos de zona horaria |
-| Borrados lógicos | `deleted_at DATETIME NULL` más índices acotados | Filtrar filas borradas lógicamente sin índice |
-| Valores de estado extensibles | Tabla de catálogo o `VARCHAR` restringido | `ENUM` cuando los valores cambian a menudo |
-
-## Indexación
-
-El orden de un índice compuesto normalmente sigue primero los predicados de
-igualdad y luego las columnas de rango u ordenación:
-
-```sql
-CREATE INDEX idx_orders_account_status_created
-    ON orders (account_id, status, created_at);
-
-SELECT id, total
-FROM orders
-WHERE account_id = ?
-  AND status = 'pending'
-  AND created_at >= ?
-ORDER BY created_at DESC
-LIMIT 50;
-```
-
-Usa `EXPLAIN` antes de añadir o cambiar un índice:
-
-```sql
-EXPLAIN
-SELECT id, total
-FROM orders
-WHERE account_id = 123 AND status = 'pending'
-ORDER BY created_at DESC
-LIMIT 50;
-```
-
-Señales que conviene investigar:
-
-| Campo | Señal de riesgo |
-| --- | --- |
-| `type` | `ALL` en una tabla grande |
-| `key` | `NULL` cuando existe un predicado selectivo |
-| `rows` | Estimación de filas muy alta en una ruta interactiva |
-| `Extra` | `Using temporary`, `Using filesort` o un `Using where` amplio |
-
-Evita añadir índices a ciegas. Cada índice incrementa el costo de escritura, el
-tiempo de migración, el tamaño de los backups y la presión sobre el buffer pool.
-
-## Patrones de consulta
-
-### Upsert
-
-Forma compatible entre motores:
-
-```sql
-INSERT INTO user_settings (user_id, setting_key, setting_value)
-VALUES (?, ?, ?)
-ON DUPLICATE KEY UPDATE
-    setting_value = VALUES(setting_value),
-    updated_at = CURRENT_TIMESTAMP;
-```
-
-Forma con alias de fila de MySQL:
-
-```sql
-INSERT INTO user_settings (user_id, setting_key, setting_value)
-VALUES (?, ?, ?) AS new
-ON DUPLICATE KEY UPDATE
-    setting_value = new.setting_value,
-    updated_at = CURRENT_TIMESTAMP;
-```
-
-Usa la forma con alias de fila solo tras confirmar que el destino es MySQL. Usa
-`VALUES(col)` para MariaDB o flotas mixtas MySQL/MariaDB.
-
-### Paginación por keyset
-
-```sql
-SELECT id, name, created_at
-FROM products
-WHERE (created_at, id) < (?, ?)
-ORDER BY created_at DESC, id DESC
-LIMIT 50;
-```
-
-Respáldala con un índice que coincida con el cursor:
-
-```sql
-CREATE INDEX idx_products_created_id ON products (created_at, id);
-```
-
-No uses paginación con `OFFSET` profundo en tablas grandes; obliga al servidor a
-escanear y descartar filas antes de devolver la página.
-
-### Campos JSON
-
-Usa columnas JSON para datos de extensión, no para campos que necesiten
-filtrado relacional intensivo o constraints.
-
-```sql
-CREATE TABLE events (
-    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
-    payload JSON NOT NULL,
-    event_type VARCHAR(64)
-        GENERATED ALWAYS AS (JSON_UNQUOTE(JSON_EXTRACT(payload, '$.type'))) STORED,
-    KEY idx_events_type (event_type)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-```
-
-Para rutas JSON consultadas con frecuencia, expón una columna generada e indexa
-esa columna. Mantén relacionales las claves foráneas, la propiedad, la
-multitenencia y los campos de ciclo de vida.
-
-### Búsqueda full-text
-
-```sql
-ALTER TABLE articles ADD FULLTEXT KEY ft_articles_title_body (title, body);
-
-SELECT id, title, MATCH(title, body) AGAINST (? IN NATURAL LANGUAGE MODE) AS score
-FROM articles
-WHERE MATCH(title, body) AGAINST (? IN NATURAL LANGUAGE MODE)
-ORDER BY score DESC
-LIMIT 20;
-```
-
-Usa un buscador externo cuando necesites tolerancia a errores tipográficos,
-ranking complejo, facetas entre tablas o análisis específico por idioma más allá
-del comportamiento full-text integrado.
-
-## Transacciones
-
-Mantén las transacciones cortas y bloquea las filas en un orden consistente:
-
-```sql
-START TRANSACTION;
-
-SELECT id, balance
-FROM accounts
-WHERE id IN (?, ?)
-ORDER BY id
-FOR UPDATE;
-
-UPDATE accounts SET balance = balance - ? WHERE id = ?;
-UPDATE accounts SET balance = balance + ? WHERE id = ?;
-
-COMMIT;
-```
-
-Lista de verificación para deadlocks y esperas de locks:
-
-- Bloquea las filas en un orden determinista en todas las rutas de código.
-- Haz las llamadas a APIs externas antes de abrir la transacción, no dentro de ella.
-- Añade índices para los predicados usados en `UPDATE`, `DELETE` y lecturas con lock.
-- Ante un deadlock, haz rollback y reintenta la transacción completa con un
-  presupuesto de reintentos acotado.
-- Captura `SHOW ENGINE INNODB STATUS\G` poco después de un deadlock; los eventos
-  posteriores lo sobrescriben.
-
-Reclamo de trabajo estilo cola:
-
-```sql
-START TRANSACTION;
-
-SELECT id
-FROM jobs
-WHERE status = 'pending'
-ORDER BY created_at
-LIMIT 1
-FOR UPDATE SKIP LOCKED;
-
-UPDATE jobs
-SET status = 'processing', started_at = CURRENT_TIMESTAMP
-WHERE id = ?;
-
-COMMIT;
-```
-
-Usa `SKIP LOCKED` solo para cargas de tipo cola donde saltar una fila bloqueada
-sea aceptable. No es un reemplazo de la consistencia transaccional normal.
-
-## Pools de conexiones
-
-Ejemplo con SQLAlchemy:
-
-```python
-from sqlalchemy import create_engine
-
-engine = create_engine(
-    "mysql+mysqlconnector://app:secret@db.internal/app",
-    pool_size=10,
-    max_overflow=5,
-    pool_timeout=30,
-    pool_recycle=240,
-    pool_pre_ping=True,
-    connect_args={"connect_timeout": 5},
-)
-```
-
-Ejemplo con `mysql2` en Node.js:
-
-```javascript
-import mysql from 'mysql2/promise';
-
-const pool = mysql.createPool({
-  host: process.env.DB_HOST,
-  user: process.env.DB_USER,
-  password: process.env.DB_PASSWORD,
-  database: process.env.DB_NAME,
-  waitForConnections: true,
-  connectionLimit: 10,
-  queueLimit: 0,
-  enableKeepAlive: true,
-  keepAliveInitialDelay: 30000,
-});
-
-const [rows] = await pool.execute(
-  'SELECT id, total FROM orders WHERE account_id = ? LIMIT 50',
-  [accountId],
-);
-```
-
-Mantén el reciclado del pool de la aplicación por debajo del `wait_timeout` del
-servidor. Si el servidor usa `wait_timeout = 300`, un `pool_recycle` en torno a
-240 segundos es coherente; `pool_pre_ping` ayuda igualmente a recuperarse de
-eventos de red y de failover.
-
-## Diagnóstico
-
-Comandos útiles de primera pasada:
-
-```sql
-SHOW FULL PROCESSLIST;
-SHOW ENGINE INNODB STATUS\G;
-SHOW VARIABLES LIKE 'slow_query_log';
-SHOW VARIABLES LIKE 'long_query_time';
-```
-
-Activa el slow log en un entorno controlado:
-
-```sql
-SET GLOBAL slow_query_log = 'ON';
-SET GLOBAL long_query_time = 1;
-SET GLOBAL log_queries_not_using_indexes = 'ON';
-```
-
-Usa `EXPLAIN ANALYZE` solo cuando sea seguro ejecutar la consulta. Ejecuta la
-sentencia y puede ser costoso sobre datos de tamaño de producción.
-
-## Replicación
-
-Las réplicas de lectura pueden retrasarse. No enrutes a una réplica, justo
-después de una escritura, los flujos de leer-tu-propia-escritura, los flujos de
-checkout, las comprobaciones de permisos ni las lecturas de claves de
-idempotencia.
-
-```sql
--- Terminología heredada de MySQL, aún común en flotas existentes
-SHOW SLAVE STATUS\G;
-
--- Terminología más nueva donde esté soportada
-SHOW REPLICA STATUS\G;
-```
-
-Comprueba el motor/versión antes de estandarizar un comando. Monitorea la salud
-del hilo SQL de la réplica, la salud del hilo de IO y el lag, no solo si la
-conexión TCP sigue viva.
-
-## Seguridad
-
-```sql
-CREATE USER 'app'@'%' IDENTIFIED BY 'usa-un-gestor-de-secretos';
-GRANT SELECT, INSERT, UPDATE, DELETE ON appdb.* TO 'app'@'%';
-
-ALTER USER 'app'@'%' REQUIRE SSL;
-
-SELECT user, host
-FROM mysql.user
-WHERE user = '';
-
-DROP USER IF EXISTS ''@'localhost';
-DROP USER IF EXISTS ''@'%';
-```
-
-Puntos de revisión de seguridad:
-
-- No concedas `ALL PRIVILEGES` ni `*.*` a usuarios de aplicación.
-- Exige TLS a los usuarios de aplicación cuando el tráfico cruce hosts o redes.
-- Guarda las credenciales en el gestor de secretos de la plataforma, no en
-  ejemplos, scripts ni archivos del repositorio.
-- Separa los usuarios de migración/administración de los usuarios de runtime de
-  la aplicación.
-- Audita la exposición a redes públicas y las direcciones de bind antes de
-  ajustar el rendimiento.
-
-## Configuración
-
-Punto de partida de ejemplo para un host dedicado de base de datos:
-
-```ini
-[mysqld]
-innodb_buffer_pool_size = 4G
-innodb_flush_log_at_trx_commit = 1
-sync_binlog = 1
-
-max_connections = 300
-thread_cache_size = 50
-
-wait_timeout = 300
-interactive_timeout = 300
-innodb_lock_wait_timeout = 10
-
-slow_query_log = ON
-long_query_time = 1
-log_queries_not_using_indexes = ON
-
-log_bin = mysql-bin
-binlog_format = ROW
-binlog_expire_logs_seconds = 604800
-```
-
-Trata los valores de configuración como un punto de partida para revisión, no
-como un preset universal. Dimensiona la memoria, las conexiones, la retención de
-logs y los ajustes de durabilidad a partir de la carga de trabajo, el hardware,
-la política de backups y los objetivos de recuperación.
-
-## Antipatrones
-
-| Antipatrón | Riesgo | Patrón mejor |
-| --- | --- | --- |
-| `SELECT *` en rutas calientes | Sobre-lectura y clientes frágiles | Selecciona columnas explícitas |
-| Paginación con `OFFSET` profundo | Escaneos lineales y páginas lentas | Paginación por keyset |
-| Sin índice en joins por clave foránea | Joins lentos y deletes con muchos locks | Indexa las columnas FK de forma intencional |
-| Transacciones largas | Esperas de locks y gran historial de undo | Haz commit de unidades de trabajo pequeñas |
-| DML directo contra `mysql.user` | Riesgo de corrupción de las tablas de grants | Usa `CREATE USER`, `ALTER USER`, `DROP USER` |
-| Usuario de aplicación con grants de admin | Radio de impacto alto | Usuario de runtime con mínimo privilegio |
-| Reciclado del pool por encima de `wait_timeout` | Conexiones del pool obsoletas | Recicla por debajo del timeout y usa pre-ping |
-| Lecturas en réplica tras escrituras | Estado visible al usuario desactualizado | Fija los flujos de leer-tras-escribir al primario |
-
-## Expectativas de salida
-
-Cuando esta skill se use para revisión, devuelve:
-
-1. Supuestos de motor/versión.
-2. Los problemas de mayor riesgo de corrección, locks, seguridad y migración.
-3. Cambios exactos de SQL o de código para la ruta segura.
-4. Plan de validación: `EXPLAIN`, ensayo de la migración, verificación de
-   locks/deadlocks y criterios de rollback.
-5. Cualquier diferencia de sintaxis entre MySQL y MariaDB que afecte la
-   recomendación.
-
-## Relacionado
-
-- Skill: `patrones-postgres` — patrones de esquema y consultas específicos de PostgreSQL
-- Skill: `migraciones-bd` — planificación de migraciones y seguridad del despliegue
-- Skill: `patrones-backend` — patrones de API y de capa de servicio
-- Skill: `revision-seguridad` — manejo de secretos, autenticación y mínimo privilegio
-- Agente: `revisor-bd` — flujo más amplio de revisión de bases de datos

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

@@ -1,229 +0,0 @@
----
-name: patrones-nestjs
-description: Patrones de arquitectura NestJS para módulos, controladores, providers, validación de DTOs, guards, interceptores, configuración y backends TypeScript de nivel productivo.
----
-
-# Patrones de desarrollo con NestJS
-
-Patrones de NestJS de nivel productivo para backends TypeScript modulares.
-
-## Cuándo activarla
-
-- Al construir APIs o servicios con NestJS
-- Al estructurar módulos, controladores y providers
-- Al añadir validación de DTOs, guards, interceptores o filtros de excepciones
-- Al configurar ajustes por entorno e integraciones con bases de datos
-- Al testear unidades de NestJS o endpoints HTTP
-
-## Estructura del proyecto
-
-```text
-src/
-├── app.module.ts
-├── main.ts
-├── common/
-│   ├── filters/
-│   ├── guards/
-│   ├── interceptors/
-│   └── pipes/
-├── config/
-│   ├── configuration.ts
-│   └── validation.ts
-├── modules/
-│   ├── auth/
-│   │   ├── auth.controller.ts
-│   │   ├── auth.module.ts
-│   │   ├── auth.service.ts
-│   │   ├── dto/
-│   │   ├── guards/
-│   │   └── strategies/
-│   └── users/
-│       ├── dto/
-│       ├── entities/
-│       ├── users.controller.ts
-│       ├── users.module.ts
-│       └── users.service.ts
-└── prisma/ o database/
-```
-
-- Mantén el código de dominio dentro de módulos de funcionalidad.
-- Coloca filtros, decoradores, guards e interceptores transversales en `common/`.
-- Mantén los DTOs cerca del módulo que los posee.
-
-## Bootstrap y validación global
-
-```ts
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule, { bufferLogs: true });
-
-  app.useGlobalPipes(
-    new ValidationPipe({
-      whitelist: true,
-      forbidNonWhitelisted: true,
-      transform: true,
-      transformOptions: { enableImplicitConversion: true },
-    }),
-  );
-
-  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
-  app.useGlobalFilters(new HttpExceptionFilter());
-
-  await app.listen(process.env.PORT ?? 3000);
-}
-bootstrap();
-```
-
-- Habilita siempre `whitelist` y `forbidNonWhitelisted` en APIs públicas.
-- Prefiere un pipe de validación global en lugar de repetir la configuración de validación por ruta.
-
-## Módulos, controladores y providers
-
-```ts
-@Module({
-  controllers: [UsersController],
-  providers: [UsersService],
-  exports: [UsersService],
-})
-export class UsersModule {}
-
-@Controller('users')
-export class UsersController {
-  constructor(private readonly usersService: UsersService) {}
-
-  @Get(':id')
-  getById(@Param('id', ParseUUIDPipe) id: string) {
-    return this.usersService.getById(id);
-  }
-
-  @Post()
-  create(@Body() dto: CreateUserDto) {
-    return this.usersService.create(dto);
-  }
-}
-
-@Injectable()
-export class UsersService {
-  constructor(private readonly usersRepo: UsersRepository) {}
-
-  async create(dto: CreateUserDto) {
-    return this.usersRepo.create(dto);
-  }
-}
-```
-
-- Los controladores deben mantenerse delgados: parsear la entrada HTTP, llamar a un provider y devolver DTOs de respuesta.
-- Pon la lógica de negocio en servicios inyectables, no en controladores.
-- Exporta solo los providers que otros módulos genuinamente necesitan.
-
-## DTOs y validación
-
-```ts
-export class CreateUserDto {
-  @IsEmail()
-  email!: string;
-
-  @IsString()
-  @Length(2, 80)
-  name!: string;
-
-  @IsOptional()
-  @IsEnum(UserRole)
-  role?: UserRole;
-}
-```
-
-- Valida cada DTO de petición con `class-validator`.
-- Usa DTOs de respuesta dedicados o serializadores en lugar de devolver entidades del ORM directamente.
-- Evita filtrar campos internos como hashes de contraseñas, tokens o columnas de auditoría.
-
-## Autenticación, guards y contexto de la petición
-
-```ts
-@UseGuards(JwtAuthGuard, RolesGuard)
-@Roles('admin')
-@Get('admin/report')
-getAdminReport(@Req() req: AuthenticatedRequest) {
-  return this.reportService.getForUser(req.user.id);
-}
-```
-
-- Mantén las estrategias de auth y los guards locales al módulo salvo que sean realmente compartidos.
-- Codifica las reglas de acceso gruesas en guards, y haz la autorización específica por recurso en los servicios.
-- Prefiere tipos de petición explícitos para los objetos de petición autenticada.
-
-## Filtros de excepciones y forma del error
-
-```ts
-@Catch()
-export class HttpExceptionFilter implements ExceptionFilter {
-  catch(exception: unknown, host: ArgumentsHost) {
-    const response = host.switchToHttp().getResponse<Response>();
-    const request = host.switchToHttp().getRequest<Request>();
-
-    if (exception instanceof HttpException) {
-      return response.status(exception.getStatus()).json({
-        path: request.url,
-        error: exception.getResponse(),
-      });
-    }
-
-    return response.status(500).json({
-      path: request.url,
-      error: 'Error interno del servidor',
-    });
-  }
-}
-```
-
-- Mantén una envoltura de error consistente en toda la API.
-- Lanza excepciones del framework para los errores de cliente esperados; registra y envuelve los fallos inesperados de forma centralizada.
-
-## Configuración y validación del entorno
-
-```ts
-ConfigModule.forRoot({
-  isGlobal: true,
-  load: [configuration],
-  validate: validateEnv,
-});
-```
-
-- Valida el entorno al arrancar, no de forma perezosa en la primera petición.
-- Mantén el acceso a la configuración detrás de helpers tipados o servicios de configuración.
-- Separa las diferencias de dev/staging/prod en factorías de configuración en lugar de ramificar por todo el código de funcionalidad.
-
-## Persistencia y transacciones
-
-- Mantén el código de repositorio / ORM detrás de providers que hablen el lenguaje del dominio.
-- Con Prisma o TypeORM, aísla los flujos transaccionales en servicios que posean la unidad de trabajo.
-- No dejes que los controladores coordinen escrituras de varios pasos directamente.
-
-## Testing
-
-```ts
-describe('UsersController', () => {
-  let app: INestApplication;
-
-  beforeAll(async () => {
-    const moduleRef = await Test.createTestingModule({
-      imports: [UsersModule],
-    }).compile();
-
-    app = moduleRef.createNestApplication();
-    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
-    await app.init();
-  });
-});
-```
-
-- Testea los providers de forma unitaria y aislada con dependencias simuladas (mocks).
-- Añade tests a nivel de petición para guards, pipes de validación y filtros de excepciones.
-- Reutiliza en los tests los mismos pipes/filtros globales que usas en producción.
-
-## Valores por defecto de producción
-
-- Habilita logging estructurado e IDs de correlación de peticiones.
-- Termina el proceso ante entorno/configuración inválidos en lugar de arrancar a medias.
-- Prefiere la inicialización asíncrona de providers para clientes de BD/caché con health checks explícitos.
-- Mantén los jobs en segundo plano y los consumidores de eventos en sus propios módulos, no dentro de controladores HTTP.
-- Haz explícitos el rate limiting, la autenticación y el registro de auditoría en los endpoints públicos.

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

@@ -1,56 +0,0 @@
----
-name: patrones-nextjs
-description: Next.js 16+ moderno — bundling incremental con Turbopack, caché en sistema de archivos, velocidad de desarrollo y cuándo usar Turbopack vs webpack.
----
-
-# Patrones de Next.js
-
-Next.js 16+ usa Turbopack por defecto para el desarrollo local: un bundler incremental escrito en Rust que acelera significativamente el arranque en desarrollo y las actualizaciones en caliente.
-
-## Cuándo usar
-
-- **Turbopack (dev por defecto)**: úsalo para el desarrollo del día a día. Arranque en frío y HMR más rápidos, especialmente en aplicaciones grandes.
-- **Webpack (dev legado)**: úsalo solo si te topas con un bug de Turbopack o dependes de un plugin exclusivo de webpack en desarrollo. Desactívalo con `--webpack` (o `--no-turbopack` según tu versión de Next.js; revisa la documentación de tu release).
-- **Producción**: el comportamiento del build de producción (`next build`) puede usar Turbopack o webpack según la versión de Next.js; consulta la documentación oficial de Next.js para tu versión.
-
-Úsala cuando: desarrolles o depures aplicaciones de Next.js 16+, diagnostiques un arranque en desarrollo o un HMR lentos, u optimices los bundles de producción.
-
-## Cómo funciona
-
-- **Turbopack**: bundler incremental para el desarrollo con Next.js. Usa caché en el sistema de archivos, así que los reinicios son mucho más rápidos (p. ej. 5–14x en proyectos grandes).
-- **Por defecto en dev**: desde Next.js 16, `next dev` se ejecuta con Turbopack salvo que se desactive.
-- **Caché en sistema de archivos**: los reinicios reutilizan el trabajo previo; la caché suele estar bajo `.next`; no requiere configuración adicional para el uso básico.
-- **Bundle Analyzer (Next.js 16.1+)**: Bundle Analyzer experimental para inspeccionar la salida y encontrar dependencias pesadas; actívalo vía configuración o flag experimental (consulta la documentación de Next.js para tu versión).
-
-## Ejemplos
-
-### Comandos
-
-```bash
-next dev
-next build
-next start
-```
-
-### Uso
-
-Ejecuta `next dev` para el desarrollo local con Turbopack. Usa el Bundle Analyzer (ver la documentación de Next.js) para optimizar el code-splitting y recortar dependencias grandes. Prefiere el App Router y los server components siempre que sea posible.
-
-## Nombre del archivo de middleware
-
-Next.js 16 introdujo `proxy.ts` como nombre del archivo de middleware, en reemplazo de la convención anterior `middleware.ts`:
-
-- **Next.js 16+**: usa `proxy.ts` en la raíz del proyecto
-- **Anterior a Next.js 16**: usa `middleware.ts` en la raíz del proyecto
-
-El cambio de nombre está ligado a la **versión de Next.js**, no al bundler en uso (Turbopack o webpack). Verifica siempre la documentación oficial de la versión que estés revisando.
-
-**No marques `proxy.ts` como un archivo de middleware mal nombrado o faltante en proyectos con Next.js 16.** El archivo es correcto e intencional. Sugerir renombrarlo a `middleware.ts` romperá la ejecución del middleware.
-
-Referencia: [documentación de proxy en Next.js](https://nextjs.org/docs/app/getting-started/proxy)
-
-## Buenas prácticas
-
-- Mantente en una versión reciente de Next.js 16.x para un comportamiento estable de Turbopack y su caché.
-- Si el desarrollo va lento, asegúrate de estar usando Turbopack (el valor por defecto) y de que la caché no se esté borrando innecesariamente.
-- Para problemas de tamaño de bundle en producción, usa las herramientas oficiales de análisis de bundles de Next.js para tu versión.