Ir al contenido
Karajan Code

Tutorial · REST API (Node)

Backend · Tiempo estimado: ~15 min · Iteraciones Karajan: 2–3

Este tutorial te lleva desde un directorio vacío hasta un endpoint mergeado en un pequeño proyecto REST API Node + Express. Incluye el loop de tests exacto que Karajan usa para gatear merges (supertest + Vitest), para que lo puedas re-ejecutar sobre un repo real cambiando el bootstrap por cd <tu-repo>.

Prerrequisitos

Sección titulada «Prerrequisitos»

Deberías haber completado el setup común: npm install -g karajan-code, kj init dentro del proyecto y un kj doctor verde. Si kj doctor está rojo, arréglalo antes — kj run se negará a arrancar.

Tutorial

Sección titulada «Tutorial»

  1. Bootstrapea el proyecto.

    Ventana de terminal
    mkdir hello-api && cd hello-api
    npm init -y
    npm install express
    npm install --save-dev vitest supertest
    git init -b main && git add -A && git commit -m "chore: scaffold"

    Edita package.json para cablear el runner de tests:

    {
      "type": "module",
      "scripts": {
        "test": "vitest run",
        "start": "node src/server.js"
      }
    }

    Crea un esqueleto mínimo en src/app.js (sin rutas todavía) para que Karajan tenga algo que extender:

    import express from "express";
    

    export function createApp() {
      const app = express();
      app.use(express.json());
      return app;
    }

  2. Inicializa Karajan en el repo.

    Ventana de terminal
    kj init
    kj doctor

    kj init crea .karajan/ y escribe la configuración del orquestador; kj doctor confirma que los CLIs de los agentes, Docker, Ollama y los puertos están sanos.

  3. Describe el endpoint en lenguaje natural.

    Sin fichero de spec. Sin JSON. Solo la tarea como se la dirías a un compañero:

    Ventana de terminal
    kj run "Añade un endpoint GET /greet?name=<name> a src/app.js que \
    devuelva JSON { greeting: 'Hello, <name>!' }. Si 'name' falta, \
    devuelve 400 con { error: 'name is required' }. Añade tests Vitest \
    usando supertest cubriendo ambos casos." \
      --methodology tdd \
      --coder claude \
      --reviewer codex \
      --reviewer-fallback claude \
      --max-iterations 5

  4. Mira el run en el HU Board.

    Abre http://localhost:4000 en otra pestaña mientras el pipeline corre. Verás, en tiempo real:

    • Cada rol activándose (planner → coder → tester → reviewer).
    • El prompt y la respuesta exactos de cada llamada al agente.
    • El diff tras cada iteración.
    • Los traces HTTP de supertest.
    • El veredicto del reviewer.

    También puedes hacer tail del mismo trace en el terminal:

    Ventana de terminal
    kj tail

  5. Inspecciona el resultado.

    Ventana de terminal
    git status
    git diff --stat
    npm test

    Salida esperada de npm test:

    ✓ tests/greet.test.js (2)
      ✓ returns 200 + greeting JSON for a valid name (19ms)
      ✓ returns 400 + error when name is missing (6ms)
    

    Test Files  1 passed (1)
         Tests  2 passed (2)

    Comprueba en vivo:

    Ventana de terminal
    npm start &
    curl -s "http://localhost:3000/greet?name=world"
    # {"greeting":"Hello, world!"}

  6. Mergea.

    Karajan no hace push ni merge por ti por defecto — esa decisión es tuya. Cuando estés contento con el diff:

    Ventana de terminal
    git checkout -b feat/greet-endpoint
    git add -A && git commit -m "feat(api): add GET /greet endpoint"
    git push -u origin feat/greet-endpoint
    gh pr create --fill

    O, si quieres que Karajan abra la PR por ti, añade --auto-commit --auto-pr a la invocación kj run.

Errores posibles y cómo resolverlos

Sección titulada «Errores posibles y cómo resolverlos»

Variantes

Sección titulada «Variantes»

El mismo run lanzado vía MCP desde cualquier cliente MCP-capable (Cursor, Claude Desktop, Codex):

{
  "tool": "kj_run",
  "params": {
    "task": "Añade GET /greet?name=<name> con 200 camino feliz + 400 sin nombre. Tests con supertest.",
    "methodology": "tdd",
    "coder": "claude",
    "reviewer": "codex",
    "reviewerFallback": "claude",
    "maxIterations": 5
  }
}

Siguientes pasos

Sección titulada «Siguientes pasos»