🛡️El Guardián Inviolable · el CI que revisa cada cambio antes de que toque a tus usuarios

El momento · cuándo aparece la necesidad

Al principio construyes solo. Cambias algo, refrescas la pantalla, ves que funciona, y listo. No hay riesgo: el único que sufre un error eres tú, en tu propia máquina, y lo arreglas en dos minutos. Esa etapa es un paraíso — y también una trampa, porque te acostumbras a que "si funciona en mi pantalla, está bien".

El momento cambia el día que alguien más depende de tu app. El primer usuario que se registra. El cliente que ya paga. El compañero que también toca el código. A partir de ahí, cada cambio que subes ya no te afecta solo a ti: puede romperle la app a gente real, o peor, filtrar sus datos. Y aquí está el problema — tú ya no ves todos los cambios uno por uno. Le pides algo a la IA, hace 8 archivos, tú lees 2, apruebas, y subes. En esos 6 que no leíste puede estar el desastre.

El dolor · de dónde sale y por qué duele tanto

El dolor no es dramático de entrada. No es una película de hackers. Es más bien una serie de accidentes pequeños que, sumados, te cuestan caro. Y todos nacen del mismo sitio: la IA en modo constructor es optimista. Está pensando en hacer que la función nueva funcione, no en las mil formas en que ese cambio puede romper otra cosa. Es su naturaleza — y también la tuya cuando estás emocionado construyendo.

El accidente más caro es la clave secreta filtrada. Le pides a la IA que conecte un servicio, y para "que funcione rápido" pega tu llave de API directamente en un archivo. Tú no lo notas, apruebas, subes a GitHub. Esa llave ahora es pública. Hay bots que escanean GitHub las 24 horas buscando exactamente eso — pueden encontrarla en minutos y empezar a gastar tu dinero o entrar a tus sistemas. No es un ataque sofisticado: es un descuido que la máquina de otro recogió del suelo, como quien recoge una cartera que se te cayó sin que te dieras cuenta.

El segundo es el hueco en la base de datos. Un cambio que, sin querer, deja una tabla de tus usuarios accesible para cualquiera, o crea una función con permisos que no debía tener. No se ve. La app sigue funcionando idéntica. Pero acabas de dejar una ventana abierta que nadie va a cerrar hasta que alguien la encuentre — y para entonces ya es tarde.

El tercero es el más común y menos glamoroso: rompiste algo que antes andaba. Arreglaste el botón A y sin darte cuenta desconectaste el botón B. En tu prueba rápida solo tocaste el A, así que no lo viste. El usuario que usaba el B se encuentra la app rota. En programación esto tiene nombre — regresión — y es el 80% del dolor real del día a día.

¿Y qué pasa si NO lo haces? Nada… durante un tiempo. Esa es la trampa. Funciona sin guardián durante semanas, te confías, y justo cuando el proyecto empieza a importar de verdad — cuando ya hay usuarios, dinero, o reputación en juego — llega el accidente que te habría costado 30 segundos evitar. El guardián es un seguro barato contra un día muy caro.

Los 7 inspectores · qué revisa cada uno

El guardián no es un bloque mágico: son 7 revisiones concretas que corren automáticamente en cada cambio. Si las 7 pasan, ves un check verde y el cambio puede seguir. Si UNA sola falla, se pone en rojo y el cambio queda bloqueado hasta que lo arregles. Así de simple, así de estricto. Vamos una por una, en el orden en que corren.

1 · Gitleaks — ¿metiste una clave secreta por accidente? Escanea todo el cambio buscando cosas que parezcan credenciales: llaves de API, contraseñas, tokens. Si encuentra algo que huele a secreto, se detiene en seco. Es el inspector que te salva del accidente más caro de todos, y por eso corre de los primerísimos — antes incluso de instalar nada, sobre el árbol limpio de git, para que esa llave no siga ni un paso más hacia el repositorio público.

2 · Gate de seguridad (Supabase advisors) — ¿este cambio abrió un hueco en la base de datos? Es el inspector jefe, y por eso corre primero de los que revisan tu código. Le pregunta a Supabase directamente: ¿alguna tabla de usuarios quedó sin su candado (RLS)? ¿alguien creó una función con permisos peligrosos? ¿se otorgó un acceso que no debía? Si la respuesta es sí, bloquea. Este es el que protege los datos de tus usuarios de un descuido silencioso.

3 · Type-check — ¿los tipos cuadran? En programación moderna, cada dato tiene un "tipo" (esto es un número, esto es un texto, esto es una fecha). Este inspector confirma que no estés, por ejemplo, sumando un texto con una fecha. Caza una familia enorme de bugs antes de que la app siquiera arranque — errores que si no, aparecerían en la cara del usuario en el peor momento.

4 · Lint — ¿el código está limpio? El linter es el inspector de malos hábitos: variables que se declaran y nunca se usan, código muerto, patrones que se sabe que causan problemas. No es estética por capricho — el código sucio es donde se esconden los bugs. Un linter obliga a mantener la casa ordenada para que se vea la suciedad de verdad.

5 · Format — ¿el formato es consistente? Que todo el código se vea igual: mismos espacios, mismas comillas, mismo estilo. Suena a manía, pero es idioma común. Cuando varias personas (o varias sesiones de IA) tocan el mismo proyecto sin un formato acordado, cada cambio mezcla lo que hiciste con un enjambre de comillas movidas y sangrías reordenadas — y ya no distingues la idea del ruido. El inspector impone el mismo dialecto para todos, de una vez y para siempre, así nadie tiene que discutirlo nunca.

6 · Tests — ¿lo que antes funcionaba sigue funcionando? Este es el que caza las regresiones, el dolor #3 de arriba. Son pruebas automáticas que verifican que las funciones clave siguen dando el resultado correcto. Arreglaste el botón A; los tests confirman que el B, el C y el D siguen andando. Es el inspector que te deja hacer cambios grandes sin miedo, porque sabes que si rompes algo, te avisa al instante.

7 · Build — ¿compila de verdad? El último inspector arma la app de cero, como si fuera a publicarse. Porque una cosa es que "funcione en tu computadora" y otra que se pueda construir limpia desde el principio. Si el build falla aquí, en la puerta, es infinitamente mejor que fallar en producción con usuarios mirando una pantalla en blanco.

El costo · por qué esto es prácticamente gratis

Uno esperaría que un guardián de nivel empresa costara dinero. No. Este cuesta ~$0 y añade unos ~15 segundos por revisión. Desglose honesto: los advisors de Supabase son gratis. GitHub Actions (el motor que corre los inspectores) te da 2.000 minutos gratis al mes en repositorios privados — y es ilimitado y gratis en repositorios públicos. Una revisión de las 7 tarda segundos, así que con 2.000 minutos haces miles de revisiones al mes sin pagar un centavo.

El repo · lo que vas a copiar

No tienes que inventar nada. Todo el guardián está empaquetado en un repositorio público, verificado, listo para copiar. Son 4 archivos que se llevan a tu proyecto, más una guía de instalación en español paso a paso. Está escrito en JavaScript puro y no depende de nada raro.

El protocolo de instalación · una sola vez, para siempre

Aquí está la parte buena: lo instalas una vez y te cuida para siempre. No hay mantenimiento diario, no hay que acordarse de correrlo. Vive en tu repositorio y se dispara solo en cada cambio. La instalación son 6 pasos, y el prompt maestro de más abajo se los pega a tu IA para que los haga contigo. Primero mira el mapa completo para entender qué va a pasar.

// Paso 3: el script que añades a tu package.json (en la sección "scripts")
{
  "scripts": {
    "db:advisors:gate": "node scripts/supabase-advisors-gate.mjs"
  }
}

# Los 2 secrets del paso 5 se crean en GitHub, NO en el código:
# Repositorio → Settings → Secrets and variables → Actions → New secret
#
#   SUPABASE_PROJECT_REF   → el ref de tu proyecto (cambia por proyecto)
#   SUPABASE_ACCESS_TOKEN  → tu token de cuenta (el mismo para todos tus proyectos)
#
# El gate está hecho para saltarse solo (con aviso) si estos secrets faltan,
# así que nunca rompe un proyecto que aún no los tiene configurados.

El prompt maestro · pégaselo a tu IA y que te lo instale

Este es el único prompt que necesitas. Se lo pegas a tu agente de código (Claude Code, Cursor, o el que uses) parado dentro de tu proyecto, y te guía por los 6 pasos, ajustando los 3 datos por ti y explicándote cada movimiento. Rellena los [corchetes] con lo tuyo antes de enviarlo.

Quiero montar en este proyecto un guardián de integración continua (CI) que revise cada cambio antes de que llegue a producción. La plantilla está en el repo público github.com/MentexDev/NeuralOS-CI-Blindaje y trae 7 inspectores: Gitleaks (secretos), gate de seguridad de Supabase advisors (que corre PRIMERO de los que revisan el código), type-check, lint, format, tests y build. Si UNO falla, el cambio se bloquea.

Contexto de mi proyecto:
- Base de datos: Supabase.
- Gestor de paquetes: [npm / pnpm / yarn].
- Nombre de mi paquete (el "name" de package.json): [nombre].

Guíame paso a paso, sin que yo tenga que saber programar, y en este orden:

1. Trae los 4 archivos de la plantilla (backend-ci.template.yml, gitleaks.toml.template, scripts/supabase-advisors-gate.mjs y scripts/supabase-advisors-allowlist.json) y colócalos donde van. El workflow debe quedar en .github/workflows/ SIN el sufijo .template.

2. Busca en los archivos los 3 marcadores <<<CAMBIAR>>> y reemplázalos por los datos reales de mi proyecto (carpeta, rutas, nombre del paquete). Muéstrame exactamente qué cambiaste en cada uno.

3. Añade a mi package.json el script "db:advisors:gate": "node scripts/supabase-advisors-gate.mjs" sin borrar mis scripts existentes.

4. Explícame EXACTAMENTE dónde encuentro mi PROJECT_REF en Supabase, y cómo genero mi ACCESS_TOKEN de cuenta.

5. Dime paso a paso cómo crear los 2 secrets en GitHub (SUPABASE_PROJECT_REF y SUPABASE_ACCESS_TOKEN). Recuérdame que NUNCA deben ir dentro de un archivo del proyecto, solo en los Secrets de GitHub.

6. Recuérdame activar "Leaked Password Protection" en Supabase (Auth → Settings).

Al final:
- Dame el comando exacto para hacer commit y push de estos archivos, y dime qué debería ver en la pestaña de checks de GitHub (los 7 inspectores corriendo, y cuál corre primero).
- Si algún inspector se pondría en rojo con mi proyecto tal como está ahora (por ejemplo, no tengo tests, o mi código tiene errores de tipo), avísame ANTES y dime la forma más simple de dejarlo en verde honestamente, sin desactivar el inspector.

El hábito · dónde vive esto en tu día a día

La belleza del guardián es que no exige disciplina de tu parte. No es un hábito que tengas que recordar como "tomar agua" o "hacer ejercicio". Una vez instalado, se dispara solo cada vez que subes un cambio. Tu único trabajo es mirar el color: verde, sigue; rojo, arregla lo que el inspector señala antes de continuar.

El momento en que lo vives es justo al subir un cambio a GitHub (o al abrir un "pull request", si trabajas con ramas — ver el recurso de ramas paralelas). Ahí GitHub lanza los 7 inspectores automáticamente. En segundos tienes el veredicto. Si trabajas con la IA, este es el punto donde su optimismo de constructor se encuentra con un auditor que no se emociona: la máquina revisa fría lo que la IA construyó caliente.

Los caminos más fáciles · qué haces tú y qué hace la máquina

Para que quede clarísimo dónde pones tú la mano y dónde no: la instalación la haces UNA vez (con el prompt de arriba, tu IA te acompaña). Después, todo es automático. Este es el reparto real de esfuerzo.

Cierre · un guardián que no duerme

Construir con IA es rápido y adictivo, y esa velocidad es justo lo que lo hace peligroso: vas tan rápido que no ves todo lo que se sube. El guardián no te frena — te deja ir rápido con red debajo. Cada cambio pasa por 7 inspectores en segundos, y si algo huele mal, se detiene antes de tocar a un solo usuario. Cuesta cero, se monta una vez, y te da algo que el dinero normalmente no compra: dormir tranquilo sabiendo que nada roto llega a producción por descuido.