Tutorial · Node CLI

Recomendado · Tiempo estimado: ~10 min · Iteraciones Karajan: 1–2

Este tutorial te lleva desde un directorio vacío hasta una feature mergeada en un pequeño proyecto CLI Node. La receta es deliberadamente mínima para que la puedas re-ejecutar sobre un repo real cambiando el bootstrap por cd <tu-repo>.

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

1. Bootstrapea el proyecto.

   mkdir hello-cli && cd hello-cli
   npm init -y
   npm install --save-dev vitest
   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"
     }
   }

   Por qué ESM + Vitest

   El coder y el reviewer de Karajan están entrenados sobre Node moderno (ESM, top-level await, imports node:). Quedarse en ESM evita el ida-y-vuelta donde el reviewer marca require().

2. Inicializa Karajan en el repo.

   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 la feature en lenguaje natural.

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

   kj run "Añade un comando 'greet <name>' a bin/cli.js que imprima \
   'Hello, <name>!'. Añade un test Vitest que ejecute el CLI vía execa \
   y verifique stdout para el nombre 'world'." \
     --methodology tdd \
     --coder claude \
     --reviewer codex \
     --reviewer-fallback claude \
     --max-iterations 5

   Qué pasa por debajo

   Con --methodology tdd, Karajan escribe primero el test que falla, luego la implementación, luego re-ejecuta la suite. El reviewer (Codex por defecto, Claude como fallback) revisa el diff. Si lo rechaza, Karajan vuelve a llamar al coder — hasta --max-iterations.

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.
   • El veredicto del reviewer.

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

   kj tail

5. Inspecciona el resultado.

   git status
   git diff --stat
   npm test

   Salida esperada de npm test:

   ✓ tests/cli.test.js (1)
     ✓ greets the given name (42ms)
   
   Test Files  1 passed (1)
        Tests  1 passed (1)

6. Mergea.

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

   git checkout -b feat/greet-command
   git add -A && git commit -m "feat(cli): add greet <name> command"
   git push -u origin feat/greet-command
   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

`vitest: command not found`

Te has saltado el paso npm install --save-dev vitest. Karajan detectará la dev-dep faltante en la iteración 1 y la añadirá — pero si la quieres antes del run, instálala manualmente.

El reviewer rechaza con `requires CommonJS`

No estás en "type": "module". O lo configuras, o aceptas que el coder reescriba los imports a require() — el reviewer es consistente en cualquier caso.

`kj run` sale con `no coder configured`

Ejecuta kj doctor y sigue las instrucciones de instalación del CLI del agente. La causa más común es tener Claude instalado pero sin sesión iniciada (claude login).

El pipeline se queda en `coder:hibernate`

Has tocado techo de cuota. Karajan persiste la sesión a ~/.karajan/standby/<sessionId>.json; resúmela con kj standby list y luego kj standby resume <sessionId> --force cuando se resetee la cuota.

Variantes

Con MCP

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

{
  "tool": "kj_run",
  "params": {
    "task": "Añade un comando 'greet <name>' a bin/cli.js que imprima 'Hello, <name>!'. Añade un test Vitest.",
    "methodology": "tdd",
    "coder": "claude",
    "reviewer": "codex",
    "reviewerFallback": "claude",
    "maxIterations": 5
  }
}

Quality gate más estricto

Añade --mode strict y los collectors deterministas de seguridad:

kj run "<tarea>" \
  --mode strict \
  --enable-security \
  --enable-sonarcloud \
  --methodology tdd

Esto cablea los collectors OSV-Scanner y Semgrep en el audit, y gatea el merge contra el quality gate de Sonar además del veredicto del reviewer.

Solo modelo local

Para runs air-gapped o con presupuesto ajustado, cambia el coder a OpenCode con un modelo local:

kj run "<tarea>" \
  --coder opencode \
  --coder-model gemma-local/coder \
  --reviewer claude \
  --max-iterations 8

--max-iterations sube porque los modelos locales tienden a necesitar una vuelta extra o dos.

Siguientes pasos

Otros stacks

Misma receta, distinto bootstrap: Python · Web Component · REST API (Node) · Java · Go · Rust

Volver al índice

Índice How-To · setup + troubleshooting