@saulwade/swl-ses 1.0.0

package/habilidades/build-errors-kotlin/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: build-errors-kotlin
+description: >
+  Resolución de errores de compilación Kotlin: kotlinc, Gradle KTS, Android
+  build y Jetpack Compose. Incluye errores de Hilt, recursos Android y
+  conflictos de versiones en Gradle.
+  Cargar cuando un build Kotlin/Android falle o haya errores de compilación.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash, Grep]
+exclusiones:
+  - "No cargar para bugs de UI en Compose en runtime (composables que renderizan mal) cuando el build pasa — si `./gradlew assembleDebug` compila pero la pantalla no se ve bien, es un error de lógica de UI; cargar `kotlin-compose`."
+  - "No cargar para fallos de tests unitarios Kotlin (JUnit, Kotest assertions) cuando el build compila — si el build pasa pero los tests fallan por valores incorrectos, es un error de lógica de tests."
+  - "No cargar para errores de Hilt en runtime (NullPointerException al inyectar en producción) cuando el build compila — si el APK se genera pero crashea por DI en runtime, revisar la configuración de Hilt directamente."
+  - "No cargar para diseñar la arquitectura del proyecto Android/Kotlin desde cero — si la pregunta es cómo organizar módulos, capas y features en un proyecto multi-módulo, cargar `kotlin-experto` o `kotlin-patrones`."
+evolvable: true  # default para skill estandar
+---
+# Build Errors Kotlin — Diagnóstico y Solución
+
+## Cuándo NO cargar
+
+- El build compila pero los Composables renderizan mal en pantalla — es un error de lógica de UI; cargar `kotlin-compose`.
+- Los tests Kotest/JUnit fallan en assertions aunque compilan — es un error de lógica de tests.
+- La pregunta es cómo organizar la arquitectura Android multi-módulo — para diseño cargar `kotlin-experto`.
+
+## Cuándo cargar
+
+- `./gradlew build` o `./gradlew assembleDebug` falla
+- Errores de kotlinc (type mismatch, unresolved reference)
+- Errores del compilador de Compose (stability, composable context)
+- Conflictos de versiones en Gradle KTS (`buildscript`, `plugin resolution`)
+- Errores de Hilt (missing binding, component hierarchy)
+- Errores de recursos Android (R class, manifest merge)
+
+---
+
+## Kotlinc — Errores del Compilador
+
+### `type mismatch: inferred type is X but Y was expected`
+
+**Causa**: el tipo inferido no coincide con el esperado. Frecuente con nullable vs non-null.
+
+```kotlin
+// MAL
+fun obtenerNombre(): String {
+    val nombre: String? = buscarEnDB()
+    return nombre  // error: String? no es String
+}
+
+// BIEN — opcion 1: null check con throw
+fun obtenerNombre(): String {
+    return buscarEnDB() ?: throw IllegalStateException("Nombre no encontrado")
+}
+
+// BIEN — opcion 2: retornar nullable en la firma
+fun obtenerNombre(): String? = buscarEnDB()
+
+// BIEN — opcion 3: valor por defecto
+fun obtenerNombre(): String = buscarEnDB() ?: "Sin nombre"
+```
+
+### `unresolved reference: X`
+
+**Causa**: clase, función o propiedad no importada, o dependencia Gradle faltante.
+
+```kotlin
+// MAL — usar Flow sin import ni dependencia
+val flujo: Flow<Int> = flow { emit(1) }  // unresolved: Flow
+
+// BIEN — agregar import explícito
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.flow
+
+// En build.gradle.kts si falta la dependencia:
+dependencies {
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
+}
+```
+
+### `none of the following candidates is applicable because of receiver type mismatch`
+
+**Causa**: se llama una función de extensión sobre el tipo incorrecto.
+
+```kotlin
+// MAL — trim() es para String, no para String?
+fun limpiar(texto: String?): String {
+    return texto.trim()  // error: trim() no existe en String?
+}
+
+// BIEN
+fun limpiar(texto: String?): String {
+    return texto?.trim() ?: ""
+}
+```
+
+---
+
+## Gradle KTS — Errores de Configuración
+
+### `Unresolved reference` en build.gradle.kts
+
+**Causa**: el DSL de Gradle KTS es estricto con tipos. Diferencias respecto a Groovy.
+
+```kotlin
+// MAL — sintaxis Groovy en KTS
+android {
+    compileSdkVersion 34      // error: funcion deprecated en KTS
+    buildToolsVersion "34.0"  // puede fallar
+}
+
+// BIEN — DSL moderno en KTS
+android {
+    compileSdk = 34
+    defaultConfig {
+        minSdk = 24
+        targetSdk = 34
+    }
+}
+```
+
+### Plugin no encontrado en `plugins {}` block
+
+```kotlin
+// MAL — plugin sin version ni alias de catalog
+plugins {
+    id("com.google.dagger.hilt.android")  // error si no hay version
+}
+
+// BIEN — con versión explícita
+plugins {
+    id("com.google.dagger.hilt.android") version "2.51.1" apply false
+}
+
+// BIEN — con version catalog (libs.versions.toml)
+plugins {
+    alias(libs.plugins.hilt)
+}
+```
+
+### `Could not resolve com.example:lib:1.0` — dependencia no encontrada
+
+```kotlin
+// Verificar repositorios en settings.gradle.kts
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+        // Si es repositorio privado:
+        maven {
+            url = uri("https://repo.empresa.com/maven")
+            credentials {
+                username = providers.gradleProperty("repoUser").get()
+                password = providers.gradleProperty("repoPass").get()
+            }
+        }
+    }
+}
+```
+
+---
+
+## Android Build — Errores de Recursos y Manifest
+
+### `error: cannot find symbol class R`
+
+**Causa**: el archivo R.java no se generó correctamente o hay error en un recurso XML.
+
+```bash
+# Diagnostico: limpiar y reconstruir
+./gradlew clean assembleDebug
+
+# Ver error raiz del recurso XML
+./gradlew assembleDebug --stacktrace 2>&1 | grep "error:"
+
+# Causas comunes:
+# - Nombre de recurso con guion (usar guion_bajo en su lugar)
+# - Etiqueta XML mal cerrada en layout
+# - Valor de color/dimension con formato incorrecto
+```
+
+### Manifest merge conflict
+
+```xml
+<!-- Error típico: herramientas:node="merge" conflicto de atributo -->
+<!-- En el AndroidManifest.xml de la app, forzar valor -->
+<activity
+    android:name=".MainActivity"
+    tools:node="merge"
+    tools:replace="android:theme">
+```
+
+### `D8: Dex file larger than 64K methods` (MultiDex)
+
+```kotlin
+// En build.gradle.kts del modulo app:
+android {
+    defaultConfig {
+        multiDexEnabled = true
+    }
+}
+dependencies {
+    implementation("androidx.multidex:multidex:2.0.1")
+}
+```
+
+---
+
+## Jetpack Compose — Errores del Compilador
+
+### `@Composable invocations can only happen from the context of a @Composable function`
+
+**Causa**: se llama un Composable desde una lambda no anotada o desde código no-Compose.
+
+```kotlin
+// MAL
+fun configurarUI() {
+    MiComponente()  // error: no es contexto Composable
+}
+
+// MAL — lambda sin anotación
+val accion: () -> Unit = {
+    MiComponente()  // error
+}
+
+// BIEN — solo dentro de funciones @Composable
+@Composable
+fun PantallaInicio() {
+    MiComponente()  // correcto
+}
+```
+
+### Stability issues — `Parameter X is not stable`
+
+**Causa**: el compilador de Compose no puede inferir la estabilidad de un tipo,
+lo que deshabilita el smart recomposition.
+
+```kotlin
+// MAL — clase mutable sin anotación
+data class Estado(var contador: Int)  // var hace al tipo inestable
+
+// BIEN — opción 1: usar val (inmutable)
+data class Estado(val contador: Int)
+
+// BIEN — opción 2: anotación explícita si la clase es external
+@Stable
+class EstadoExterno(private val wrapped: ExternalClass)
+
+// BIEN — opcion 3: en compose_compiler_config.conf marcar clases externas
+// ver: https://developer.android.com/develop/ui/compose/performance/stability/fix
+```
+
+---
+
+## Hilt — Errores de Inyección de Dependencias
+
+### `[Hilt] Missing binding for X`
+
+**Causa**: Hilt no sabe cómo proveer el tipo solicitado.
+
+```kotlin
+// MAL — interfaz sin @Binds ni @Provides
+interface Repositorio
+class RepositorioImpl @Inject constructor() : Repositorio
+
+// Para que Hilt resuelva la interfaz, se necesita un modulo:
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class RepositorioModule {
+    @Binds
+    @Singleton
+    abstract fun bindRepositorio(impl: RepositorioImpl): Repositorio
+}
+```
+
+### `@HiltAndroidApp` no encontrado
+
+```kotlin
+// En Application class — sin esto Hilt no inicializa
+@HiltAndroidApp
+class MiAplicacion : Application()
+
+// En AndroidManifest.xml:
+// <application android:name=".MiAplicacion" ...>
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **`./gradlew build` falla con "Could not resolve com.android.tools.build:gradle:X.Y.Z"** aunque la versión existe en Maven Central: el repositorio `google()` no está declarado en `settings.gradle.kts` antes de `mavenCentral()`. Causa: AGP (Android Gradle Plugin) está en el repositorio de Google, no en Maven Central; si `google()` no está o está en el orden incorrecto, la resolución falla. Solución: asegurarse que `settings.gradle.kts` tiene `google()` primero en el bloque `pluginManagement.repositories` Y en `dependencyResolutionManagement.repositories`.
+- **Compose BOM actualizado produce error `Unresolved reference: LazyColumn`** aunque la función existe en la misma versión de Compose UI: el BOM alinea versiones pero el IDE puede cachear las versiones antiguas del árbol de dependencias. Causa: el cache de Gradle tiene la versión anterior del artefacto `compose.foundation` sin invalidar. Solución: ejecutar `./gradlew cleanBuildCache` y sincronizar el proyecto en Android Studio — si persiste, verificar con `./gradlew :app:dependencies | grep compose-foundation` que la versión del BOM es la que se espera.
+- **Hilt `@Binds` en un módulo abstracto produce "MissingBinding" aunque la implementación existe**: la clase `RepositorioImpl` está en un feature module diferente al módulo donde está instalado el componente Hilt. Causa: los módulos Hilt solo ven las dependencias del componente en el que están instalados (`SingletonComponent`, `ActivityComponent`, etc.) — las dependencias entre feature modules no se ven automáticamente. Solución: instalar el módulo de Hilt con `@InstallIn(SingletonComponent::class)` en el feature module que provee la implementación, asegurando que ese módulo tiene dependencia del módulo que lo necesita.
+- **`kotlinc` compila el módulo de library pero el módulo de app falla con "unresolved reference"** apuntando a una clase de la library**: la library tiene `internal` en la clase en lugar de `public`. Causa: `internal` en Kotlin restringe la visibilidad al mismo módulo de Kotlin — una clase `internal` en `:core` no es visible en `:app`. Solución: cambiar la visibilidad a `public` (o dejar sin modificador, que es `public` por defecto en Kotlin) y revisar que la clase no tiene restricciones de API pública que justifiquen `internal`.
+
+## Checklist de Diagnóstico
+
+- [ ] Ejecutar `./gradlew build --stacktrace` para ver la causa raíz del error.
+- [ ] `./gradlew dependencies` para ver el árbol de dependencias y conflictos.
+- [ ] Limpiar caché de Gradle si hay errores inexplicables: `./gradlew cleanBuildCache`.
+- [ ] Verificar compatibilidad de versiones en `libs.versions.toml` (Kotlin, AGP, Compose BOM).
+- [ ] Para errores de Compose: habilitar reportes del compilador con `reportsDestination`.
+- [ ] Si el error es de Hilt: revisar que `@HiltAndroidApp` está en Application.
+- [ ] Para R class: revisar XMLs de recursos por errores de sintaxis o nombres inválidos.
+- [ ] `./gradlew lint` para detectar problemas antes de compilar.

package/habilidades/build-errors-nextjs/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: build-errors-nextjs
+description: >
+  Resolución de errores de compilación Next.js: next build, React Server
+  Components, hydration mismatch, Turbopack y middleware. Incluye errores de
+  ISR, optimización de imágenes, CSS modules y variables de entorno.
+  Cargar cuando un build Next.js falle o haya errores de renderizado.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash, Grep]
+exclusiones:
+  - "No cargar para errores de TypeScript puros en un proyecto Next.js (TS2322, TS2345, errores de tipos en archivos .ts/.tsx) — para esos cargar `build-errors-typescript`; este skill cubre errores específicos de la plataforma Next.js."
+  - "No cargar para bugs de lógica de la aplicación en runtime cuando `next build` compila (fetch que retorna datos incorrectos, routing que no funciona como se espera) — si el build pasa, es un error de lógica, no de build."
+  - "No cargar para diseñar la arquitectura App Router de un proyecto nuevo (estructura de rutas, layouts, data fetching patterns) — para eso cargar `nextjs-experto` o `nextjs-patrones`."
+  - "No cargar para errores de estado de React (useState, useReducer, Zustand) en componentes que ya compilan — si el build pasa pero el estado no se actualiza correctamente, es un bug de lógica de state management."
+evolvable: true  # default para skill estandar
+---
+# Build Errors Next.js — Diagnóstico y Solución
+
+## Cuándo NO cargar
+
+- El error es de TypeScript puro (TS2322, TS2345) sin relación con Next.js — cargar `build-errors-typescript` para esos.
+- `next build` compila pero la app falla en lógica de negocio — es un bug de lógica, no de build.
+- La pregunta es cómo diseñar la estructura de App Router — para arquitectura cargar `nextjs-experto`.
+
+## Cuándo cargar
+
+- `next build` falla con errores de compilación o runtime
+- Hydration mismatch en producción o desarrollo
+- Errores de React Server Components (`"use client"` faltante o incorrecto)
+- Errores de Turbopack (incompatibilidad de plugins, loaders)
+- Errores de middleware, ISR revalidation o image optimization
+- Variables de entorno no disponibles en el cliente o en build time
+
+---
+
+## Hydration Mismatch
+
+### `Error: Hydration failed because the initial UI does not match what was rendered on the server`
+
+**Causa**: el HTML generado en el servidor difiere del que React intenta hidratar en el cliente.
+
+```tsx
+// MAL — acceso a APIs del browser en render (solo existen en cliente)
+export default function Componente() {
+    const ancho = window.innerWidth;  // window no existe en servidor
+    return <div>Ancho: {ancho}</div>;
+}
+
+// MAL — Date() produce valores distintos en servidor y cliente
+export default function Timestamp() {
+    return <span>{new Date().toLocaleString()}</span>;  // mismatch
+}
+
+// BIEN — usar useEffect para lógica solo-cliente
+"use client";
+import { useState, useEffect } from "react";
+
+export default function Timestamp() {
+    const [fecha, setFecha] = useState<string>("");
+    useEffect(() => {
+        setFecha(new Date().toLocaleString());
+    }, []);
+    return <span>{fecha || "Cargando..."}</span>;
+}
+
+// BIEN — suppressHydrationWarning para diferencias inevitables
+<time suppressHydrationWarning>{new Date().toISOString()}</time>
+```
+
+### Hydration mismatch por nesting HTML inválido
+
+```tsx
+// MAL — <p> no puede contener <div>
+function Tarjeta() {
+    return (
+        <p>
+            <div>Contenido</div>  {/* inválido: div dentro de p */}
+        </p>
+    );
+}
+
+// BIEN
+function Tarjeta() {
+    return (
+        <div>
+            <p>Contenido</p>
+        </div>
+    );
+}
+```
+
+---
+
+## React Server Components — Errores de Directivas
+
+### `You're importing a component that needs "use client"`
+
+**Causa**: un Server Component importa un módulo que usa APIs del browser o hooks de React.
+
+```tsx
+// MAL — ServerPage.tsx (Server Component) importa componente con estado
+import Contador from "./Contador";  // Contador usa useState
+
+export default function ServerPage() {
+    return <Contador />;  // error en build
+}
+
+// BIEN — agregar "use client" al componente que necesita estado/browser APIs
+// Contador.tsx
+"use client";
+import { useState } from "react";
+
+export default function Contador() {
+    const [n, setN] = useState(0);
+    return <button onClick={() => setN(n + 1)}>{n}</button>;
+}
+// ServerPage.tsx no necesita cambios
+```
+
+### `Server Component cannot use client-only hooks`
+
+```tsx
+// MAL — useRouter, usePathname, useSearchParams en Server Component
+// app/pagina/page.tsx (Server Component por defecto)
+import { useRouter } from "next/navigation";  // error: hook de cliente
+
+export default function Pagina() {
+    const router = useRouter();  // solo funciona en Client Components
+}
+
+// BIEN — si se necesita router: extraer a Client Component
+// app/pagina/BotonNavegar.tsx
+"use client";
+import { useRouter } from "next/navigation";
+
+export function BotonNavegar() {
+    const router = useRouter();
+    return <button onClick={() => router.push("/")}>Inicio</button>;
+}
+```
+
+---
+
+## Variables de Entorno — Errores Comunes
+
+### Variable undefined en el cliente
+
+**Causa**: variable sin prefijo `NEXT_PUBLIC_` usada en Client Component.
+
+```bash
+# MAL — variable privada referenciada en cliente
+# .env.local
+DATABASE_URL=postgres://...
+API_SECRET=clave_secreta
+
+# componente-cliente.tsx
+"use client"
+const url = process.env.DATABASE_URL  // undefined en cliente — correcto por seguridad
+```
+
+```tsx
+// BIEN — variables publicas con prefijo NEXT_PUBLIC_
+// .env.local
+NEXT_PUBLIC_API_URL=https://api.ejemplo.com
+
+// componente-cliente.tsx
+"use client"
+const apiUrl = process.env.NEXT_PUBLIC_API_URL  // disponible en cliente
+```
+
+### Variable undefined en build time (Static Generation)
+
+```tsx
+// BIEN — verificar presencia en build y lanzar error descriptivo
+// lib/config.ts
+export function getConfig() {
+    const apiKey = process.env.API_KEY;
+    if (!apiKey) {
+        throw new Error(
+            "API_KEY no está definida. " +
+            "Agregar al archivo .env.local o a las variables de entorno del servidor."
+        );
+    }
+    return { apiKey };
+}
+```
+
+---
+
+## Dynamic Import y Carga Diferida
+
+### `Module not found` con dynamic import en Server Component
+
+```tsx
+// MAL — dynamic import de módulo solo-cliente en Server Component
+import dynamic from "next/dynamic";
+const Mapa = dynamic(() => import("leaflet-maps"), { ssr: false });
+// Si Mapa se usa en Server Component el { ssr: false } no tiene efecto completo
+
+// BIEN — dynamic con ssr:false solo en Client Components
+"use client";
+import dynamic from "next/dynamic";
+
+const MapaDinamico = dynamic(
+    () => import("./MapaInteractivo"),
+    {
+        ssr: false,
+        loading: () => <div>Cargando mapa...</div>,
+    }
+);
+```
+
+---
+
+## ISR y Revalidación
+
+### `revalidatePath` / `revalidateTag` no funciona como se espera
+
+```tsx
+// MAL — revalidar desde Client Component
+"use client";
+import { revalidatePath } from "next/cache";  // error: solo en Server Actions/Route Handlers
+
+// BIEN — revalidar en Server Action
+// app/actions.ts
+"use server";
+import { revalidatePath } from "next/cache";
+
+export async function actualizarDatos() {
+    await db.actualizar(/* ... */);
+    revalidatePath("/dashboard");  // correcto: Server Action
+}
+```
+
+---
+
+## Turbopack — Problemas de Compatibilidad
+
+### Plugin de webpack no compatible con Turbopack
+
+```js
+// next.config.js
+// MAL — plugin de webpack que no tiene equivalente en Turbopack
+const withBundleAnalyzer = require("@next/bundle-analyzer")({ enabled: true });
+module.exports = withBundleAnalyzer({
+    experimental: { turbo: true }  // conflicto probable
+});
+
+// BIEN — verificar compatibilidad en https://nextjs.org/docs/app/api-reference/turbopack
+// Usar loaders Turbopack para transformaciones custom
+module.exports = {
+    experimental: {
+        turbo: {
+            rules: {
+                "*.svg": {
+                    loaders: ["@svgr/webpack"],
+                    as: "*.js",
+                },
+            },
+        },
+    },
+};
+```
+
+---
+
+## Optimización de Imágenes
+
+### `Error: Invalid src prop on next/image`
+
+```tsx
+// MAL — dominio externo no configurado
+import Image from "next/image";
+<Image src="https://imagenes-externas.com/foto.jpg" ... />
+// Error: hostname no está en la lista permitida
+
+// BIEN — agregar en next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+    images: {
+        remotePatterns: [
+            {
+                protocol: "https",
+                hostname: "imagenes-externas.com",
+                port: "",
+                pathname: "/**",
+            },
+        ],
+    },
+};
+module.exports = nextConfig;
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Hydration mismatch solo en producción, no en desarrollo**: `next dev` no detecta el mismatch porque usa renderizado del lado del cliente más permisivo, pero `next build` + `next start` (o producción) aplica comparación estricta del HTML. Causa: el componente usa `new Date()`, `Math.random()`, o `window` en el render inicial, que producen valores diferentes entre servidor y cliente. Solución: mover las llamadas a `new Date()` y valores dinámicos a `useEffect` o `useState` con valor inicial `null`, renderizando el contenido dinámico solo en cliente.
+- **`"use client"` en un componente que importa un Server Component produce error "cannot import Server Component in Client Component"**: el grafo de importaciones tiene un Client Component importando un Server Component directamente. Causa: en el App Router, los Server Components no pueden ser importados por Client Components — el componente debe pasarse como `children` o prop. Solución: reestructurar para que el Server Component sea un padre que pase el Client Component como children, o usar `Suspense` con `lazy()` para la porción cliente.
+- **Variables de entorno NEXT_PUBLIC_* configuradas en Vercel pero no disponibles en el bundle**: las variables se definieron en el proyecto de Vercel pero no se volvió a hacer deploy después de agregarlas. Causa: `NEXT_PUBLIC_*` se embeben en el bundle durante `next build` — si se agregan después del build, el build existente no las contiene. Solución: hacer un redeploy completo después de agregar o cambiar variables `NEXT_PUBLIC_*`; para variables solo de servidor (sin prefijo) basta con un restart sin rebuild.
+- **`next build` falla con "Module not found" para un alias de path configurado en `tsconfig.json`**: tsconfig paths no se propagan automáticamente a la resolución de módulos de Next.js. Causa: Next.js lee `tsconfig.json` para paths solo si hay configuración explícita en `next.config.js` o si el alias está bajo `@/`. Solución: agregar el alias también en `next.config.js` bajo `webpack.resolve.alias` (o en la sección `experimental.turbo.resolveAlias` para Turbopack) — los tsconfig paths solos no son suficientes para el bundler de Next.js.
+
+## Checklist de Diagnóstico
+
+- [ ] `next build 2>&1 | grep "Error"` para filtrar solo errores en el output completo.
+- [ ] Para hydration: revisar si el componente usa `window`, `document`, `localStorage` o `Date` en render inicial.
+- [ ] Verificar que todo componente con hooks o event handlers tiene `"use client"` al inicio.
+- [ ] Variables de entorno en cliente: deben tener prefijo `NEXT_PUBLIC_`.
+- [ ] Para ISR: `revalidatePath` y `revalidateTag` solo funcionan en Server Actions y Route Handlers.
+- [ ] `next build --debug` para diagnóstico verbose de la compilación.
+- [ ] Revisar `next.config.js` al migrar de Pages Router a App Router: algunas opciones cambian.
+- [ ] Para Turbopack: verificar en la documentación oficial si el plugin/loader tiene equivalente.