7. Primer proyecto práctico (Node.js + Express)

Objetivo del tema

Acompañar la creación de un servicio HTTP minimalista con Node.js y Express, sumando pruebas con Jest y validando el flujo de aprobaciones en Codex CLI.

7.1 Plan del proyecto

Iniciaremos un directorio limpio, instalaremos dependencias, definiremos un endpoint /health y cerraremos la iteración aplicando y confirmando cambios. Visualiza el recorrido en tarjetas:

7.2 Preparar el entorno local

Comprueba que la versión de Node cumple con los requisitos del proyecto. Para Codex CLI conviene usar la misma versión que ejecutará el repositorio remoto.

node --version
mkdir codex-health-check
cd codex-health-check
npm init -y

El archivo package.json generado nos permitirá registrar scripts de arranque y pruebas. Si prefieres una estructura monorepo, crea el directorio dentro de apps/ o services/ para mantener consistencia con tus proyectos existentes.

7.3 Crear el servidor con Express

Instala Express y un runner moderno como nodemon (opcional) para reiniciar el servidor durante el desarrollo.

npm install express
npm install --save-dev nodemon

Define el servidor en src/server.js. El endpoint /health debe devolver estado 200 y un JSON sencillo, lo suficiente para que herramientas de monitoreo detecten que el servicio responde.

import express from 'express';

const app = express();

app.get('/health', (req, res) => {
  res.status(200).json({
    status: 'ok',
    timestamp: new Date().toISOString()
  });
});

export default app;

Para levantar la aplicación crea src/index.js con la lógica de arranque del servidor.

import app from './server.js';

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Servidor listo en http://localhost:${PORT}`);
});

Agrega los scripts de ejecución en package.json. La versión con nodemon queda así:

"scripts": {
  "dev": "nodemon src/index.js",
  "start": "node src/index.js"
}

7.4 Configurar Jest para pruebas automáticas

Instala Jest y supertest para ejercitar endpoints HTTP. Asegúrate de habilitar el flag --experimental-vm-modules si usas ESM puro.

npm install --save-dev jest supertest
node --experimental-vm-modules node_modules/.bin/jest --init

El asistente de configuración pregunta por tipo de proyecto, cobertura y entorno. Selecciona node como entorno de pruebas y habilita la salida en ESM modificando package.json:

"type": "module",
"jest": {
  "testEnvironment": "node",
  "transform": {}
}

Crea el archivo tests/health.test.js para validar la respuesta JSON y el código de estado.

import request from 'supertest';
import app from '../src/server.js';

describe('GET /health', () => {
  it('responde con 200 y el estado ok', async () => {
    const response = await request(app).get('/health');

    expect(response.statusCode).toBe(200);
    expect(response.body).toEqual(
      expect.objectContaining({
        status: 'ok'
      })
    );
    expect(new Date(response.body.timestamp).toString()).not.toBe('Invalid Date');
  });
});

Registra el comando de prueba en package.json para integrarlo con Codex CLI:

"scripts": {
  "dev": "nodemon src/index.js",
  "start": "node src/index.js",
  "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
}

7.5 Ejecutar y validar el servicio

Antes de involucrar a Codex CLI, asegúrate de que el endpoint funciona manualmente.

npm run dev
curl http://localhost:3000/health

El comando curl debe mostrar un JSON con estado ok y la marca temporal ISO. Interrumpe el servidor con Ctrl + C antes de continuar para evitar puertos ocupados durante las pruebas automatizadas.

7.6 Iterar con Codex CLI

Las versiones recientes del CLI se centran en la interfaz interactiva. Inicia una sesión con un prompt que describa la tarea y deja que el agente proponga los cambios:

codex --full-auto "Agregar endpoint /health con Express y configurar Jest"

Si prefieres aprobar cada comando o edición, arranca la sesión en modo supervisado:

codex --sandbox workspace-write --ask-for-approval on-request "Agregar endpoint /health con Express y configurar Jest"

Dentro de la sesión podrás pedirle a Codex acciones concretas («Instala express, jest y supertest», «Refina el controlador para manejar errores», etc.) y el CLI abrirá el panel de cambios para que revises los diffs antes de aplicarlos. Usa las opciones que aparecen en pantalla para aceptar o descartar cada archivo, y vuelve a conversar si necesitas ajustes adicionales.

Recuerda los comandos internos: /approvals cambia el modo de aprobación sin salir de la sesión y /status muestra el estado del sandbox (rutas en workspace, políticas activas). Si pausas la conversación, retómala con codex resume --last o indicando el identificador de la sesión.

7.7 Revisar pruebas y confirmar cambios

Pídele a Codex que ejecute las pruebas desde la misma sesión («Corre npm test y resume el resultado») para que la conversación registre la salida.

Si necesitas automatizarlo desde la terminal, usa el modo no interactivo:

codex exec --full-auto "Ejecuta npm test y dime si falló algo"

Repite la iteración hasta obtener un resultado satisfactorio. Al final, verifica el estado del repositorio con /status o abre una terminal aparte y ejecuta git status para confirmar que solo están los archivos esperados.

Cuando la tarea esté lista, cierra la sesión informando que quedó resuelta; la transcripción se conservará y servirá como registro de los comandos y decisiones.

Checklist de validación antes de hacer commit

Aspecto	Preguntas de control	Acción recomendada
Servidor	¿El endpoint /health responde con 200 y JSON?	Ejecuta npm run dev + curl y revisa la salida.
Pruebas	¿Jest cubre el caso feliz y posibles errores?	Añade escenarios negativos (p. ej., puerto ocupado) si tu equipo lo exige.
Codex CLI	¿Dejaste evidencia de lo que se hizo con Codex?	Guarda la sesión interactiva y solicita /status o notas finales en la conversación.
Git	¿El commit agrupa solo archivos necesarios?	Revisa git status, elimina archivos temporales y genera un mensaje claro.

7.8 Conclusión

Este primer proyecto muestra cómo Codex CLI se complementa con herramientas JavaScript tradicionales: el agente puede sugerir estructuración, escribir pruebas y ayudarte a ejecutar comandos repetitivos, mientras que tú conservas el control de la calidad. La mezcla de un endpoint sencillo, Jest y revisión guiada establece un patrón que luego se extiende a servicios más complejos.