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

Objetivo del tema

Aplicar todo lo aprendido en un proyecto real: crear desde cero un servicio HTTP minimalista con Node.js y Express, usando el flujo completo de OpenCode: inicializar, planificar, construir, probar y revisar.

10.1 Plan del proyecto

Construiremos un microservicio con un endpoint /health verificado mediante pruebas automatizadas. El recorrido completo:

1. Preparar entorno

Crear la carpeta del proyecto, inicializar Git y npm, instalar dependencias.

2. Inicializar agente

Ejecutar /init para que OpenCode genere el AGENTS.md con los comandos del proyecto.

3. Planificar (Plan)

Pedir al agente en modo Plan el diseño del endpoint y de sus pruebas.

4. Construir (Build)

Aprobar el plan y dejar que el agente implemente código y tests.

5. Validar y confirmar

Revisar el diff, correr la suite completa y crear el commit.

10.2 Preparación del entorno

Desde tu terminal, crea el proyecto y sus dependencias:

mkdir servicio-salud && cd servicio-salud
git init
npm init -y
npm install express
npm install --save-dev jest supertest

Edita package.json para definir el script de pruebas:

{
  "name": "servicio-salud",
  "scripts": {
    "test": "jest --runInBand"
  },
  "dependencies": { "express": "^4.19.0" },
  "devDependencies": { "jest": "^29.7.0", "supertest": "^7.0.0" }
}

10.3 Inicialización con OpenCode

Abre el agente dentro del proyecto y genera las reglas base:

opencode
/init

/init detectará que es un proyecto npm con Jest y dejará en el AGENTS.md los comandos de instalación y prueba. Complementalo a mano con una convención propia, por ejemplo: "las respuestas JSON deben incluir siempre un campo status". Recuerda hacer commit del archivo.

10.4 Planificar en modo Plan

Presiona Tab hasta ver el indicador Plan en la esquina inferior derecha y describe la tarea:

Queremos un endpoint GET /health que responda 200 con { "status": "ok", "uptime": <segundos activo>, "timestamp": <ISO> }. La lógica debe vivir en src/app.js exportando el app de Express, y un archivo src/server.js separado debe encargarse de escuchar en el puerto definido por PORT (3000 por defecto). Agrega pruebas en tests/health.test.js con supertest cubriendo: código 200, formato del body y presencia de los tres campos. Ejecuta npm test antes de terminar.

El agente explorará el proyecto sin modificarlo y devolverá un plan: estructura de archivos, dependencias necesarias y orden de implementación. Si algo no convence, corrígelo en la conversación: "usa la variable de entorno NODE_ENV para logs verbosos en desarrollo".

Fíjate en dos detalles del prompt: define dónde va cada cosa (archivos y carpetas) y cómo validar el resultado (los casos de prueba). Esa combinación evita la mayoría de las iteraciones innecesarias.

10.5 Construir en modo Build

Cuando el plan te convenza, pulsa Tab para cambiar a Build y confirma:

El plan está bien. Implementa todo y ejecuta npm test al finalizar.

OpenCode creará los archivos, lanzará las pruebas y reportará el resultado. Al terminar deberías tener algo así:

// src/app.js
const express = require('express');

const app = express();

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

module.exports = app;
// tests/health.test.js
const request = require('supertest');
const app = require('../src/app');

describe('GET /health', () => {
  it('responde 200 con status ok', async () => {
    const res = await request(app).get('/health');
    expect(res.statusCode).toBe(200);
    expect(res.body.status).toBe('ok');
    expect(typeof res.body.uptime).toBe('number');
    expect(new Date(res.body.timestamp).toString()).not.toBe('Invalid Date');
  });
});

10.6 Validación del resultado

Checklist final de la iteración
Verificación Cómo Esperado
Suite de pruebas npm test Todos los tests en verde.
Prueba manual node src/server.js y abrir http://localhost:3000/health JSON con los tres campos y código 200.
Revisión del diff git diff o el resumen de archivos tocados en la TUI Sólo los archivos acordados en el plan.
Arrepentimiento /undo y luego /redo si cambias de opinión Vuelve atrás el mensaje y sus cambios; ajusta el prompt y reintenta.

10.7 Cierre: commit y siguientes pasos

Si el diff te convence, pide al agente que cree el commit o hazlo tú mismo:

git add -A
git commit -m "feat: endpoint /health con pruebas supertest"

Buenos ejercicios para continuar sobre este mismo proyecto:

  • Agregar un endpoint /ready que verifique una dependencia externa.
  • Incluir validación de variables de entorno (PORT) con su test correspondiente.
  • Usar opencode run para generar automáticamente el README del servicio.

Conclusión: en este proyecto aplicaste el ciclo completo profesional: entorno preparado, reglas en AGENTS.md, plan aprobado en modo Plan, implementación verificada en modo Build y revisión humana del resultado antes de confirmar. En el próximo tema repetiremos el ejercicio con Python y FastAPI para consolidar el flujo en otro ecosistema.

Retornar