@jpkme/diff-review 0.1.5 → 0.1.7

package/README.md

@@ -32,13 +32,44 @@ Desde un **repo git**, el default es terminal-first:
 
 Si pasás `--branch` y `--base` juntos, saltea los selects. Si quedan iguales (diff vacío), abre la UI.
 
+Si ya hay un JSON válido para esos mismos commits, pregunta si abrir el existente o generarlo de nuevo; en ese
+caso el archivo viejo no cuenta hasta que el agente lo reescriba. Sin terminal interactiva no pregunta: con
+`--agent` lo genera de nuevo y sin `--agent` abre el existente.
+
+### Lanzar el agente (`--agent`)
+
+Si hay agentes instalados, después de branch y base un solo select lista copiar el prompt al portapapeles (primera
+opción) y cada agente detectado. Con `--agent` saltea esa lista y va directo a elegir agente y modelo:
+
+```bash
+diff-review --agent
+```
+
+Al enviarlo a un agente, en vez de copiar el prompt pregunta el modelo (con `--agent`, primero el agente):
+
+1. **Agente**: los instalados que encuentra (Claude Code, Codex, Cursor CLI, GitHub Copilot CLI, Gemini CLI). Si ya lo elegiste en la lista anterior, este paso no se repite. Se buscan por nombre en el `PATH` y en algunas rutas fijas: en Windows, el Claude Code que trae la app de
+   escritorio (`%APPDATA%\Claude\claude-code\<versión>\…\claude.exe`) y `%LOCALAPPDATA%\cursor-agent\cursor-agent.cmd`;
+   en Linux/macOS, `~/.local/bin/claude`, `~/.claude/local/claude` y `~/.local/bin/cursor-agent`.
+2. **Modelo**: arranca en el default del agente (el configurado en `~/.claude/settings.json` /
+   `ANTHROPIC_MODEL`, `~/.codex/config.toml`, `~/.cursor/cli-config.json`, `~/.copilot/settings.json` o
+   `~/.gemini/settings.json`; si no hay, no se pasa `--model`). También lista los conocidos (para Claude, los
+   alias `opus` / `sonnet` / `haiku`; para Copilot, `auto`) y "Otro…" para escribir un id.
+
+El prompt viaja por stdin y la salida del agente se ve en la terminal. Claude Code y Copilot corren con permisos
+acotados: leer, `git`, el `validate` y escribir solo el JSON del review (Copilot no puede acotar por argumentos,
+así que permite `npx` en general). Cursor corre con `--force` (no tiene
+flag para pasar una allowlist y sin él bloquearía el `validate`) y Gemini con `--yolo`. Si no hay agentes
+instalados, sigue con el portapapeles. Sin terminal interactiva usa el primer agente con su modelo por defecto.
+
+El agente tiene que estar logueado (p. ej. `claude /login` una vez).
+
 Para abrir la UI primero (sin esperar el JSON):
 
 ```bash
 diff-review --ui
 ```
 
-Opciones: `--port`, `--host`, `--base`, `--branch`, `--no-open`.
+Opciones: `--port` (si está ocupado, usa el siguiente libre), `--host`, `--base`, `--branch`, `--agent`, `--no-open`.
 
 Si lo lanzás desde un repositorio git, la UI precarga esa ruta y el branch actual.
 
@@ -55,7 +86,7 @@ npm start                # mismo que el bin global
 
 1. Pegá la ruta (o URL) del repo y elegí branch / base — o lanzá `diff-review` / `diff-review --ui` desde el repo.
 2. Copiá el prompt (o el comando de skill `/diff-review`).
-3. Corrélo en tu agente; que escriba `diff-rev_{branchTip}_{baseTip}.json` (también acepta nombres legacy).
+3. Corrélo en tu agente; que escriba `diff-rev_{branchTip}_{baseTip}.json` y lo valide con `npx --yes @jpkme/diff-review validate <archivo>` (también acepta nombres legacy).
 4. Arrastrá ese JSON a la dropzone (o dejá que el CLI lo importe solo). La UI hidrata los diffs con git.
 
 "Ver ejemplo" carga un reporte de muestra sin tocar un repo.

package/bin/diff-review.mjs

@@ -6,6 +6,7 @@
  *
  *   diff-review --port 5191
  *   diff-review --branch x --base y   → saltea selects de Clack
+ *   diff-review --agent      → elegir agente + modelo y lanzarlo con el prompt (sin portapapeles)
  *   diff-review --no-open
  */
 
@@ -15,12 +16,14 @@ import { createServer } from 'node:net';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
+import { AGENTS, detectAgents, modelChoices, OTHER_MODEL, runAgent } from '../lib/agents.mjs';
 import { autocompleteEs } from '../lib/autocomplete-es.mjs';
 import { copyTextToClipboard } from '../lib/clipboard.mjs';
 import { branchTips, getRemoteUrl, listBranches, tryResolveGitRoot } from '../lib/git.mjs';
 import { makeOutputFilename } from '../lib/output-name.mjs';
 import { buildPrompt } from '../lib/prompt.mjs';
-import { waitForReviewOutput } from '../lib/wait-output.mjs';
+import { existingReviewOutput, waitForReviewOutput } from '../lib/wait-output.mjs';
+import { runValidateCli } from '../lib/check-report.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(here, '..');
@@ -50,18 +53,24 @@ function printHelp() {
 
 Usage:
   diff-review [options]
+  diff-review validate <file.json>
 
 Por defecto (desde un repo git): elegís branch/base en la terminal (Clack),
-copia el prompt, espera el JSON y abre el viewer.
+copia el prompt, espera el JSON y abre el viewer. Si hay agentes instalados,
+un solo select lista el portapapeles y cada agente detectado.
+\`validate\` revisa el JSON y, si falla, dice cómo seguir (exit 0 = OK).
 Si pasás --branch y --base juntos, saltea los selects.
+Con --agent: saltea esa lista; elegís un agente instalado y el modelo,
+y diff-review lo lanza con el prompt.
 Con --ui: abre la UI de inmediato (web-first).
 
 Options:
-  -p, --port <n>   Puerto (default ${DEFAULT_PORT})
+  -p, --port <n>   Puerto (default ${DEFAULT_PORT}; si está ocupado, el siguiente libre)
       --host <h>   Host (default ${DEFAULT_HOST})
       --ui         Abrir la UI primero (sin esperar JSON)
       --base <b>   Base del merge-base (salta el select de base)
       --branch <b> Branch a revisar (salta el select de branch)
+      --agent      Lanzar un agente instalado (${AGENTS.map((a) => a.bins[0]).join(', ')}) con el prompt
       --no-open    No abrir el navegador
   -h, --help       Esta ayuda
 
@@ -76,6 +85,7 @@ function parseArgs(argv) {
 		open: true,
 		help: false,
 		ui: false,
+		agent: false,
 		base: '',
 		branch: ''
 	};
@@ -84,6 +94,7 @@ function parseArgs(argv) {
 		if (a === '-h' || a === '--help') opts.help = true;
 		else if (a === '--no-open') opts.open = false;
 		else if (a === '--ui') opts.ui = true;
+		else if (a === '--agent') opts.agent = true;
 		else if (a === '--host') opts.host = argv[++i] || opts.host;
 		else if (a === '--base') opts.base = argv[++i] || opts.base;
 		else if (a === '--branch') opts.branch = argv[++i] || opts.branch;
@@ -133,6 +144,18 @@ function canListen(host, port) {
 	});
 }
 
+const PORT_SCAN = 50;
+
+/** Primer puerto libre desde `start`, o `null` si ninguno de los siguientes cabe. */
+async function findFreePort(host, start) {
+	const first = Math.max(1, Math.floor(start));
+	const last = Math.min(65535, first + PORT_SCAN - 1);
+	for (let port = first; port <= last; port++) {
+		if (await canListen(host, port)) return port;
+	}
+	return null;
+}
+
 /**
  * @returns {{
  *   repo: string,
@@ -167,6 +190,11 @@ function branchOptions(listed) {
 	}));
 }
 
+/** Selects solo con terminal interactiva. (`p.isTTY` de Clack es una función, no un booleano.) */
+function isInteractive() {
+	return p.isTTY(process.stdin) && p.isTTY(process.stdout);
+}
+
 function ensureValue(value, label) {
 	if (p.isCancel(value)) {
 		p.cancel('Cancelado.');
@@ -193,7 +221,7 @@ async function resolveBranchBase(launch, opts) {
 		return { branch: flagBranch, base: flagBase, prompted: false };
 	}
 
-	if (!p.isTTY) {
+	if (!isInteractive()) {
 		const branch = flagBranch || defaultBranch(launch.listed);
 		const base = flagBase || defaultBase(launch.listed, branch);
 		return { branch, base, prompted: false };
@@ -278,6 +306,142 @@ function copyPromptOrWarn(prompt) {
 	return false;
 }
 
+/**
+ * Modelo del agente: select con TTY; sin TTY, el modelo por defecto (string vacío).
+ * @param {import('../lib/agents.mjs').DetectedAgent} agent
+ */
+async function pickModel(agent) {
+	if (!isInteractive()) return '';
+
+	const { options, initialValue } = modelChoices(agent.def);
+	const choice = await p.select({ message: 'Modelo', options, initialValue });
+	if (p.isCancel(choice)) {
+		p.cancel('Cancelado.');
+		process.exit(0);
+	}
+	if (choice !== OTHER_MODEL) return /** @type {string} */ (choice);
+
+	const typed = ensureValue(
+		await p.text({
+			message: 'Id del modelo',
+			validate: (v) => (String(v ?? '').trim() ? undefined : 'Escribí el id del modelo.')
+		}),
+		'modelo'
+	);
+	return typed.trim();
+}
+
+/**
+ * Agente y modelo: selects con TTY; sin TTY, el primer agente detectado con su modelo por defecto.
+ * Si `preset` ya viene elegido, solo pregunta el modelo.
+ * @param {import('../lib/agents.mjs').DetectedAgent[]} detected
+ * @param {import('../lib/agents.mjs').DetectedAgent} [preset]
+ */
+async function pickAgentAndModel(detected, preset) {
+	if (!isInteractive()) return { agent: preset ?? detected[0], model: '' };
+
+	let agent = preset;
+	if (!agent) {
+		const id = ensureValue(
+			await p.select({
+				message: 'Agente',
+				options: detected.map((a) => ({ value: a.def.id, label: a.def.label, hint: a.path })),
+				initialValue: detected[0].def.id
+			}),
+			'agente'
+		);
+		agent = detected.find((a) => a.def.id === id) ?? detected[0];
+	}
+
+	return { agent, model: await pickModel(agent) };
+}
+
+/**
+ * Portapapeles primero y después cada agente detectado.
+ * @param {import('../lib/agents.mjs').DetectedAgent[]} detected
+ * @returns {Promise<import('../lib/agents.mjs').DetectedAgent | null>} `null` = portapapeles
+ */
+async function pickDelivery(detected) {
+	const choice = ensureValue(
+		await p.select({
+			message: '¿Cómo generás el review?',
+			options: [
+				{ value: 'clipboard', label: 'Copiar el prompt al portapapeles', hint: 'lo pegás en tu agente' },
+				...detected.map((a) => ({ value: a.def.id, label: a.def.label, hint: a.path }))
+			],
+			initialValue: 'clipboard'
+		}),
+		'modo'
+	);
+	if (choice === 'clipboard') return null;
+	return detected.find((a) => a.def.id === choice) ?? detected[0];
+}
+
+/**
+ * Ya hay un review válido para estos commits: pregunta si abrirlo o generarlo de nuevo.
+ * @param {{ path: string }} existing
+ * @returns {Promise<{ path: string } | null>} el existente, o `null` para generar de nuevo
+ */
+async function reuseExistingReview(existing, outputFilename) {
+	const choice = ensureValue(
+		await p.select({
+			message: `Ya hay un review válido para estos commits (${outputFilename})`,
+			options: [
+				{ value: 'open', label: 'Abrir el existente' },
+				{ value: 'regenerate', label: 'Generar de nuevo', hint: 'el agente lo reemplaza' }
+			],
+			initialValue: 'open'
+		}),
+		'review'
+	);
+	if (choice !== 'open') return null;
+	p.outro('Abro el review existente.');
+	return existing;
+}
+
+/**
+ * Lanza el agente y espera el JSON. Devuelve el reporte válido; si el agente termina sin dejarlo, sale con error.
+ * @param {import('../lib/agents.mjs').DetectedAgent} agent
+ * @param {{ repo: string, prompt: string, model: string, outputFilename: string, useClack: boolean }} run
+ */
+async function runAgentAndWait(agent, { repo, prompt, model, outputFilename, useClack }) {
+	const what = `${agent.def.label} (${model || 'modelo por defecto'})`;
+	const msg = `Lanzando ${what}. Espera ${outputFilename} en la raíz del repo; Ctrl+C cancela.`;
+	if (useClack) p.outro(msg);
+	else console.log(msg);
+
+	// Solo cuenta lo que escriba este agente: un JSON anterior de los mismos commits no es el resultado.
+	const since = Date.now();
+	const { exited } = runAgent(agent, { cwd: repo, prompt, model, outputFilename });
+	const waiting = waitForReviewOutput(repo, outputFilename, {
+		since,
+		onInvalid: (errors) => {
+			console.log(`JSON encontrado pero inválido (${errors.length} error(es)). El agente puede corregirlo…`);
+			for (const e of errors.slice(0, 5)) console.log(`  · ${e}`);
+		}
+	});
+
+	let code;
+	try {
+		code = await exited;
+	} catch (err) {
+		console.error(`No se pudo lanzar ${agent.path}: ${err instanceof Error ? err.message : err}`);
+		process.exit(1);
+	}
+	// El watcher puede ir un tick atrás de la última escritura del agente.
+	const result = await Promise.race([waiting, new Promise((r) => setTimeout(() => r(null), 2000))]);
+	if (!result) {
+		console.error(
+			code === 0
+				? `${agent.def.label} terminó sin dejar un ${outputFilename} válido.`
+				: `${agent.def.label} terminó con código ${code} sin dejar un ${outputFilename} válido.`
+		);
+		process.exit(1);
+	}
+	if (code !== 0) console.warn(`${agent.def.label} terminó con código ${code}, pero el JSON es válido.`);
+	return /** @type {{ path: string }} */ (result);
+}
+
 function explainWaitingForAgent(outputFilename, { copied, useClack }) {
 	const copyMsg = copied
 		? 'Se copió un prompt al portapapeles: pegalo en el chat de tu agente de IA para generar el contenido de la review.'
@@ -306,12 +470,17 @@ O reinstalá el paquete (el tarball de npm incluye el build).`);
 		process.exit(1);
 	}
 
-	if (!(await canListen(cfg.host, cfg.port))) {
-		console.error(`No se pudo usar ${cfg.host}:${cfg.port} (¿ocupado?). Probá --port otro.`);
+	const port = await findFreePort(cfg.host, cfg.port);
+	if (port == null) {
+		const last = Math.min(65535, cfg.port + PORT_SCAN - 1);
+		console.error(`No encontré un puerto libre entre ${cfg.port} y ${last} en ${cfg.host}.`);
 		process.exit(1);
 	}
+	if (port !== cfg.port) {
+		console.log(`Puerto ${cfg.port} ocupado; la UI usa ${port}.`);
+	}
 
-	const origin = `http://${cfg.host}:${cfg.port}`;
+	const origin = `http://${cfg.host}:${port}`;
 	const openUrl = cfg.openPath ? `${origin}${cfg.openPath}` : origin;
 	const nodeBin = resolveNodeBin();
 	const child = spawn(nodeBin, [entry], {
@@ -319,7 +488,7 @@ O reinstalá el paquete (el tarball de npm incluye el build).`);
 		env: {
 			...process.env,
 			HOST: cfg.host,
-			PORT: String(cfg.port),
+			PORT: String(port),
 			ORIGIN: origin,
 			DIFF_REVIEW_LAUNCH_CWD: cfg.launchCwd,
 			...(cfg.importFile ? { DIFF_REVIEW_IMPORT_FILE: cfg.importFile } : {})
@@ -398,12 +567,19 @@ async function runUiMode(opts, launch, launchCwd) {
 		port: opts.port,
 		open: opts.open,
 		launchCwd,
-		openPath: launch ? `/?notify=prompt&out=${encodeURIComponent(outputFilename)}` : '/'
+		openPath: launch
+			? `/?watch=1&notify=prompt&out=${encodeURIComponent(outputFilename)}`
+			: '/'
 	});
 }
 
 async function main() {
-	const opts = parseArgs(process.argv.slice(2));
+	const rawArgv = process.argv.slice(2);
+	if (rawArgv[0] === 'validate') {
+		process.exit(runValidateCli(rawArgv.slice(1)));
+	}
+
+	const opts = parseArgs(rawArgv);
 	if (opts.help) {
 		printHelp();
 		process.exit(0);
@@ -461,15 +637,51 @@ async function main() {
 		{ outputFilename }
 	);
 
-	const copied = copyPromptOrWarn(prompt);
-	explainWaitingForAgent(outputFilename, { copied, useClack: prompted });
+	// Sin --agent también se detectan (con terminal interactiva) para ofrecer lanzar uno en vez del portapapeles.
+	const detected = opts.agent || isInteractive() ? detectAgents() : [];
+	if (opts.agent && !detected.length) {
+		const names = AGENTS.map((a) => a.bins[0]).join(', ');
+		const warn = `No encontré agentes instalados (${names}). Sigo copiando el prompt.`;
+		if (prompted) p.log.warn(warn);
+		else console.warn(warn);
+	}
 
-	const result = await waitForReviewOutput(launch.repo, outputFilename, {
-		onInvalid: (errors) => {
-			console.log(`JSON encontrado pero inválido (${errors.length} error(es)). Esperando corrección…`);
-			for (const e of errors.slice(0, 5)) console.log(`  · ${e}`);
-		}
-	});
+	// Hay selects (agente/modelo, o abrir vs. regenerar un review existente) solo con terminal interactiva.
+	const existing = isInteractive() ? existingReviewOutput(launch.repo, outputFilename) : null;
+	const useClack = prompted || (isInteractive() && (detected.length > 0 || existing != null));
+	// Con flags de branch/base no hubo intro, pero estos selects abren sesión de Clack igual.
+	if (useClack && !prompted) p.intro('diff-review');
+
+	let result = existing ? await reuseExistingReview(existing, outputFilename) : null;
+	/** @type {import('../lib/agents.mjs').DetectedAgent | null} */
+	let chosen = null;
+	if (!result && detected.length > 0 && !opts.agent && isInteractive()) {
+		chosen = await pickDelivery(detected);
+	}
+	const useAgent = !result && detected.length > 0 && (opts.agent || chosen != null);
+	if (useAgent) {
+		const { agent, model } = await pickAgentAndModel(detected, chosen ?? undefined);
+		result = await runAgentAndWait(agent, {
+			repo: launch.repo,
+			prompt,
+			model,
+			outputFilename,
+			useClack
+		});
+	} else if (!result) {
+		// Si eligió generar de nuevo, el JSON existente no cuenta hasta que el agente lo reescriba.
+		const since = existing ? Date.now() : undefined;
+		const copied = copyPromptOrWarn(prompt);
+		explainWaitingForAgent(outputFilename, { copied, useClack });
+
+		result = await waitForReviewOutput(launch.repo, outputFilename, {
+			since,
+			onInvalid: (errors) => {
+				console.log(`JSON encontrado pero inválido (${errors.length} error(es)). Esperando corrección…`);
+				for (const e of errors.slice(0, 5)) console.log(`  · ${e}`);
+			}
+		});
+	}
 
 	console.log('JSON OK. Abriendo la UI web…');
 	await startServer({