Guía del taller

1. ¿Qué es este proyecto?

Es el MVP de una Plataforma de Publicación de Agentes de IA: una aplicación web donde distintas personas pueden registrarse, pedir permiso para crear "agentes" (una entidad con nombre, objetivo, prompt, modelo y temperatura) y publicarlos en un catálogo. Todavía no ejecuta ningún agente de verdad ni se conecta a OpenAI — eso viene en etapas futuras. Por ahora es infraestructura: usuarios, permisos, y el CRUD de agentes.

Se construyó a propósito por etapas chicas, cada una con su propio commit, en vez de pedir "hacé toda la app" de una sola vez.

2. Conceptos básicos

Si nunca trabajaste con una aplicación web como esta, estos son los conceptos que vas a necesitar:

• Servidor: un programa (acá, hecho con Node.js y Express) que queda escuchando pedidos en un puerto (por ejemplo, el 3000) y responde con páginas HTML o datos.
• Ruta (route): una combinación de método HTTP y URL que el servidor sabe responder. Por ejemplo, GET /login muestra el formulario de login; POST /login procesa ese formulario cuando lo enviás.
• Base de datos (SQLite): donde se guardan los datos de forma permanente (usuarios, solicitudes, agentes). Acá se usa SQLite porque es un solo archivo, sin necesidad de instalar un servidor de base de datos aparte.
• Sesión: cuando iniciás sesión, el servidor te da una "cookie" que tu navegador manda en cada pedido siguiente, para que la app sepa quién sos sin pedirte la contraseña de nuevo en cada página.
• CSRF: una protección para que nadie pueda hacerte enviar una acción (como cerrar sesión o borrar algo) desde un sitio que no sea esta app, aprovechando que tu navegador ya te tiene logueado acá. Por eso vas a ver un campo oculto _csrf en los formularios.

3. Poné el proyecto a andar en tu máquina

1. Cloná el repositorio y entrá a la carpeta.
2. Copiá .env.example como .env. Para desarrollo local podés dejar los valores tal cual vienen.
3. Instalá las dependencias:

   npm install

4. Inicializá la base de datos y creá el superadmin (usa el email y la contraseña que pusiste en .env):

   npm run db:init

5. Arrancá el servidor:

   npm start

6. Abrí http://localhost:3000 en tu navegador. La ruta /health te sirve para confirmar que el servidor está vivo.

Si más adelante querés que el servidor se reinicie solo cada vez que cambiás un archivo, usá npm run dev en lugar de npm start.

4. Cómo se construyó (metodología con IA)

Este proyecto se hizo trabajando junto a un asistente de IA (Codex y, en algunas etapas, Claude Code) como compañero de programación. La regla más importante fue: nunca pedir "hacé toda la app". En cambio, cada etapa siguió siempre el mismo ciclo:

1. Analizar y definir el alcance — qué entra en esta etapa y qué se deja explícitamente para después.
2. Diseñar el modelo — rutas, validaciones, quién puede hacer qué. Todavía sin escribir código.
3. Aprobar el plan — una persona lo revisa y lo aprueba antes de que se toque un solo archivo.
4. Implementar — recién ahí se escribe el código, de una etapa completa por vez.
5. Verificar — se prueba de verdad, levantando el servidor y mandando pedidos HTTP reales, no solo leyendo el código.
6. Revisar (review) — se pide una revisión de seguridad y calidad antes de dar la etapa por cerrada.
7. Documentar — se agrega una entrada a docs/BITACORA.md explicando qué se hizo y por qué.
8. Commitear — recién al final, con un mensaje claro. El commit lo aprueba y lo hace una persona, no la IA sola.

Los roles que puede asumir la IA

Un mismo asistente de IA puede asumir distintos roles en distintos momentos de ese ciclo — no es solo "el que escribe código":

• Arquitecto — propone el diseño (paso 2) antes de que exista una sola línea de código.
• Programador — implementa lo ya aprobado (paso 4).
• Reviewer — busca activamente problemas en el código ya escrito (paso 6), con una mirada distinta a la de quien lo implementó.
• QA — verifica que el comportamiento real coincida con lo diseñado (paso 5), probando la aplicación como lo haría un usuario o un atacante.
• Documentador — traduce lo que pasó a una narrativa entendible en la bitácora (paso 7).
• DevOps — piensa en cómo el proyecto corre de verdad: configuración por entorno, migraciones seguras, qué pasa en un despliegue real (más sobre esto en la Etapa 6, ver docs/arquitectura/004-roadmap.md).

Nombrarlos por separado ayuda a entender que ninguno reemplaza la aprobación humana en los pasos 3 y 8 del ciclo.

Por qué el paso de "revisar" importa (un ejemplo real)

En la Etapa 2, un review encontró que el sistema de bloqueo por intentos fallidos de login (pensado para frenar ataques de fuerza bruta) tenía un problema: guardaba un registro en memoria por cada intento fallido y nunca los borraba. Cualquiera podía mandar intentos de login con emails inventados, sin parar, y hacer crecer la memoria del servidor indefinidamente — un ataque de denegación de servicio bastante barato de ejecutar.

La corrección agregó una limpieza automática cada 5 minutos y un tope máximo de registros. Ese fix, a su vez, hizo que un review posterior encontrara un problema relacionado en cómo se identificaba la IP de cada cliente detrás de un proxy. Cada ronda de revisión encontró algo real que las pruebas básicas de "¿arranca el servidor?" no hubieran detectado nunca.

La lección: que una aplicación arranque y funcione no significa que esté lista para confiar en ella. Revisar antes de cada commit no es burocracia — es la diferencia entre descubrir un problema de seguridad ahora, en un commit chico y fácil de entender, o descubrirlo después, cuando ya está mezclado con otros cien cambios.

5. Recorré la aplicación

Las etapas que ya están construidas y commiteadas:

1. Etapa 1 — Estructura base: servidor, base de datos, sesiones, seed del superadmin.
2. Etapa 2 — Autenticación: registro, login, logout, protegido con CSRF y un límite de intentos fallidos.
3. Etapa 3 — Solicitudes de creador: desde Solicitar permiso de creador (necesitás una cuenta y sesión iniciada), un usuario común pide permiso para crear agentes; el superadmin lo aprueba o rechaza en /admin/creator-requests.
4. Etapa 4 — CRUD de agentes: quien tiene permiso administra sus propios agentes en /agents — crear, editar, publicar, desactivar, eliminar.
5. Etapa 5 — Catálogo: cualquier usuario logueado ve los agentes publicados en /catalog, con información limitada (nombre, descripción, autor, fecha) — nunca el prompt ni la configuración interna.

Recorrido sugerido: registrate con una cuenta nueva → pedí permiso de creador → iniciá sesión como superadmin ([email protected], o el email que hayas puesto en tu .env) y aprobá tu propia solicitud → volvé a entrar con tu cuenta → creá un agente y publicalo → mirá cómo aparece en /catalog.

6. Tu ejercicio

Te proponemos construir una funcionalidad chica, siguiendo exactamente la misma metodología de la sección 4 (diseñar → aprobar → implementar → verificar → revisar → documentar → commitear):

Agregar un buscador por nombre al catálogo. Hoy /catalog muestra todos los agentes publicados. La idea es sumar un campo de búsqueda que filtre la lista por nombre (por ejemplo, /catalog?q=soporte debería mostrar solo los agentes cuyo nombre contenga "soporte").

Antes de escribir código, pensá y escribí (aunque sea en un par de líneas):

• ¿Cómo llega el término de búsqueda al servidor? (pista: query string, req.query)
• ¿Cómo se arma la consulta SQL para buscar por un texto parcial sin abrir la puerta a inyección SQL? (pista: seguí usando db.prepare(...).all(valor) con placeholders, nunca concatenando el texto del usuario directo en el SQL)
• ¿Qué pasa si el campo de búsqueda viene vacío? ¿Y si nadie lo manda?
• ¿Hace falta CSRF acá? (pensá: es un formulario que lee datos, no uno que los modifica — repasá por qué el CSRF se aplicó en la Etapa 2 solo a los formularios que cambian algo)

Cuando tengas el diseño, pedile a tu compañero de IA que te ayude a implementarlo, pero primero hacé que te lo explique de vuelta y aprobalo vos antes de que toque código — así es como se construyó todo lo que ya ves funcionando.