@ketchao/nextup 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# nextup (nombre provisional)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Menú de "siguientes pasos" para agentes de código. MVP: **Claude Code** y **Codex** (mismo protocolo de hooks).
+
+> El nombre es un placeholder. Ojo: la captura de referencia es de un producto llamado "Then", así que conviene no usar ese nombre.
+
+Al terminar cada turno sustancial, muestra hasta 4 opciones contextuales (con indicador de consumo). El usuario responde escribiendo el número en la caja normal de Claude Code.
+
+```
+◆ ¿Cómo seguimos?  Escribe un número · +1 2 = varias
+                                                      consumo ▾
+  1  Hacer commit ★ sugerida                          ■□□ bajo
+  2  Revisar mis cambios                              ■■□ medio
+  3  Escribir pruebas                                 ■■■ alto
+  4  Dejarlo así                                      □□□ nada
+  5  Otra cosa (libre)
+```
+
+## Probarlo (5 minutos)
+
+```bash
+npm install
+npm test                      # 76 pruebas
+npm run preview               # ver el menú sin Claude (itera el diseño aquí)
+npm run preview -- --scenario failed --width 60
+npm run build
+
+# en un repo de prueba, desde el paquete publicado:
+npm install -g @ketchao/nextup
+nextup init --agent codex
+claude                        # pide un cambio pequeño y mira qué pasa al terminar
+```
+
+`init --user` instala los hooks globalmente; `init --remove` los quita. Hace un backup `settings.json.nextup.bak` la primera vez.
+
+Probar un hook sin Claude:
+
+```bash
+cat fixtures/stop.json | NEXTUP_ALWAYS=1 node dist/cli.js hook stop
+cat fixtures/prompt-submit.json | node dist/cli.js hook prompt-submit
+```
+
+## Probar con Codex (experimental)
+
+Los comandos `hook stop` y `hook prompt-submit` leen y escriben el mismo formato JSON que usa Codex, así que no hay adaptador nuevo: solo cambia dónde se registran.
+
+```bash
+node dist/cli.js init --agent codex      # escribe .codex/hooks.json (o --user para ~/.codex/hooks.json)
+codex                                    # luego escribe /hooks y aprueba (trust) los 2 hooks de nextup
+```
+
+Notas:
+- Codex ignora los hooks nuevos o modificados hasta que los revisas con `/hooks`.
+- En Windows nativo (Codex CLI 0.166.0, cmd) los hooks **sí se ejecutan**. El `systemMessage` aparece como "Hook · ..." con los colores ANSI y la alineación intactos.
+- El lector de transcript (`transcript.ts`) es *best effort* y entiende los formatos de Claude Code y de Codex. Solo lee lo ocurrido en el turno actual (el hook `UserPromptSubmit` anota dónde empieza). Si algo no cuadra, activa `debug` y revisa `debug.jsonl`: la entrada `stop-signals` muestra los comandos y códigos de salida detectados, y un resumen de las líneas leídas.
+- Codex ejecuta los hooks desde un servidor en segundo plano que **no hereda tus variables de entorno**: usa `~/.nextup/config.json` (ver abajo) o abre `codex --no-daemon`.
+
+## Configuración
+
+Variables de entorno **o** el archivo `~/.nextup/config.json` (las variables mandan sobre el archivo):
+
+```json
+{
+  "language": "es",
+  "suggestions": 4,
+  "showCustomOption": true,
+  "showTokenEstimation": true,
+  "autoSuggest": true,
+  "backgroundCheck": true,
+  "consumption": "measured",
+  "providers": { "claude": true, "codex": true, "opencode": true },
+  "debug": false,
+  "theme": "default"
+}
+```
+
+`suggestions` es el tope de filas, contando "Dejarlo así" (1–4). `showCustomOption` es la fila "Otra cosa". `showTokenEstimation` es la columna de consumo. `autoSuggest: false` deja de mostrar menús nuevos; un menú que ya está en pantalla sigue aceptando el número. `backgroundCheck` corre `npm test` (y `npm run lint` si existe) antes de armar el menú, con un tope de unos segundos: si 3 pruebas fallan, la fila dice «3 pruebas fallan, arreglarlas». `false` lo apaga. `consumption` es `measured` (el tiempo real: `1.5s`, o `—` si esa acción todavía no se midió) o `estimated` (bajo, medio, alto, nada). `providers` apaga un agente: Codex se reconoce por la ruta `.codex` del transcript. OpenCode todavía no tiene adaptador, así que su flag se guarda y no corta nada. `language` es el idioma cuando el prompt no alcanza para saberlo (un número, un «ok» o una mezcla). Si el prompt es una frase en inglés, el menú sale en inglés; si es en español, en español. Siguen valiendo `lang`, `mode`, `color`, `width`, `always` y `disabled`. El entorno manda sobre el archivo.
+
+Para verlo o cambiarlo sin editar el JSON:
+
+```
+nextup config
+nextup config set autoSuggest false
+nextup config set providers.codex false
+nextup config set showCustomOption true
+nextup config set suggestions 3
+nextup config set theme blue
+nextup config set language es
+nextup config set consumption estimated
+```
+
+Los interruptores aceptan `true`/`false` (también `on`/`off` y `si`/`no`). En la caja del agente, sin salir de Codex y sin tener `nextup` en el PATH:
+
+```
+nextup theme blue
+nextup config set consumption estimated
+```
+
+El cambio se guarda y el agente no lo ejecuta. Se ve en el menú siguiente. `color` y `default` pintan cada fila según el consumo. `blue`, `green`, `amber`, `pink`, `teal` y `violet` pintan todo el menú de un color. `mono` lo deja sin color. También valen `azul`, `ambar`, `rosa` y `cian`. `nextup init` crea el archivo con todo activo si todavía no existe, y no pisa el que ya tengas.
+
+Con `"debug": true`, cada hook guarda lo que recibió y devolvió en `~/.nextup/state/debug.jsonl` (contiene rutas y texto de tu sesión; es solo local). Aparte, cada menú deja una línea en `~/.nextup/state/choices.jsonl`: si elegiste un número, si lo dejaste así, o si escribiste otra cosa. No guarda la frase. Si una fila sale tres veces en turnos parecidos y no la eliges, baja.
+
+## Cómo funciona
+
+1. **Hook `Stop`**: lee el payload, junta señales baratas (cambios en `git status`, comandos `Bash` del turno en el transcript, mensaje final), genera el menú y lo muestra con `systemMessage`. Guarda el menú pendiente en `~/.nextup/state/<session_id>.json`.
+2. El usuario escribe el número de la fila (`2`) o varios a la vez (`+2 4`, `1 3`, `1 y 3`). El `+` es opcional.
+3. **Hook `UserPromptSubmit`**: si hay menú pendiente y la respuesta es una selección, inyecta las instrucciones como `additionalContext` (el hook no puede reescribir el prompt; Claude recibe "3" + el contexto que lo explica). "Dejarlo así" y "Otra cosa" bloquean el prompt y no gastan tokens. Cualquier otro texto descarta el menú y pasa intacto.
+
+Decisiones de diseño (vienen de la crítica a la maqueta):
+- **No sugiere lo que ya pasó**: si las pruebas ya pasaron, no ofrece correrlas otra vez.
+- **No repite lo que acabas de elegir** (solo para el menú siguiente) **ni ofrece correr pruebas si el repo no tiene ninguna configurada**: en su lugar sugiere el commit.
+- **0 a 4 opciones, y a veces ninguna**: no hay menú si no hubo cambios, o si el agente terminó con una pregunta.
+- **La sugerida nunca es saliente**: el esquema (`SuggestionSchema`) rechaza `recommended` + `outward` (push, deploy...).
+- **El menú por defecto pinta la fila**: verde, ámbar, rojo o gris según el consumo, y "Otra cosa" en azul. El número va en una pastilla más clara. `blue`, `green`, `amber`, `pink`, `teal` y `violet` pintan todo el menú de un solo color. `mono` y `color: false` lo dejan en texto plano. El `☐` no se marca: se elige con el número. En la caja del agente, sin barra: `nextup theme blue` (también `verde`, `azul`, `ambar`, `rosa`, `cian`). La barra es de Codex y rechaza `/nextup`.
+
+## Spike: lo que hay que verificar primero
+
+Estas cuatro cosas **no están confirmadas**; todo el diseño depende de ellas:
+
+| # | Pregunta | Cómo probarla | Si falla |
+|---|----------|---------------|----------|
+| 1 | ¿Se ve el `systemMessage` de un Stop sin bloqueo? | Correr `claude`, pedir un cambio, mirar al terminar | Usar `NEXTUP_MODE=block` |
+| 2 | ¿Respeta ANSI y saltos de línea? | Comparar con `NEXTUP_COLOR=0` | Dejar color apagado por defecto |
+| 3 | ¿Claude actúa bien con `"3"` + contexto inyectado? | Elegir opciones varias veces | Reforzar el texto de `additionalContext` |
+| 4 | ¿El ancho detectado es correcto? | Redimensionar la terminal; probar `NEXTUP_WIDTH` | Ancho fijo o más compacto |
+
+Además: mide la latencia real del turno (el hook arranca en ~60 ms; las reglas son locales, así que hoy no hay llamada a un modelo) y prueba también en la extensión de VS Code/Cursor, cuya interfaz puede mostrar los hooks distinto a la terminal.
+
+## Límites conocidos
+
+- El menú mira solo los archivos cuyo diff cambió en este turno (baseline guardado en `UserPromptSubmit`). Si esa marca no está, cae al `git status` completo.
+- El transcript JSONL no es un contrato público: `transcript.ts` es *best effort* y degrada a "sin señales".
+- Detección de pruebas: usa los comandos y códigos de salida del transcript (formato real de Codex verificado con `fixtures/codex-rollout-sample.jsonl`). Si el fallo parece del entorno (EPERM, "Access is denied"...), se trata como *bloqueado*, no como "pruebas rotas": la sugerida pasa a ser revisar el diff. Sin código de salida, cae a una heurística sobre el mensaje final.
+- Sin detección de ejecuciones headless (`claude -p`); si más adelante llamas a `claude -p` desde el hook, exporta `NEXTUP_INNER=1` en esa llamada para evitar recursión.
+- Claude y Codex comparten el protocolo de hooks (`systemMessage` / `additionalContext`). OpenCode necesita un presentador propio (añadir al prompt).
+
+## Siguientes pasos
+
+1. Pasar el spike (tabla de arriba) y usarlo una semana propia; registrar qué opciones se eligen.
+2. `llm.ts`: 1 o 2 sugerencias específicas con un modelo pequeño (API key o `claude -p`), manteniendo las reglas deterministas como base.
+3. Consumo medido (duración real de la última corrida de pruebas) en vez de fijo por tipo de acción.
+4. Presentador de OpenCode (añadir al prompt). Claude y Codex ya comparten `src/adapters/shared/`.
+
+## Estructura
+
+```
+src/core/                 independiente del agente: tipos (zod), reglas, render, parser, estado
+src/adapters/shared/      protocolo de hooks: payloads, transcript, contexto, Stop y UserPromptSubmit
+src/adapters/claude/      instalación en .claude/settings.json
+src/adapters/codex/       instalación en .codex/hooks.json (timeoutSec)
+src/cli/                  preview, init, config, entrada de los hooks
+test/                     parse, suggest, render, hooks (con repo git temporal), adaptadores
+fixtures/                 payloads de ejemplo
+```