@payconductor/houndsman 0.1.4 → 0.3.0

package/src/cli/index.ts

@@ -7,11 +7,14 @@
  * cwd) e orquestra funções/classes de `core/`. Não importa nenhum caminho do
  * projeto consumidor estaticamente.
  *
+ * Cada comando carrega seus módulos por import dinâmico (lazy) — o startup não
+ * paga por `server`, Jev (axios) ou `orchestrator` que o comando não usa.
+ *
  * Comandos:
  *   (default)            Passo 1 — preparar (classificação + briefs + manifesto)
  *   --finalize           Passo 3 — consolidar os findings em review.md
  *   context              Passo 0 — coletar o contexto da PR via `gh`
- *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/...)
+ *   findings <sub>       Triagem/correção dos findings (list/set/done/sync/batch/verify/submit/...)
  *   server               Sobe a UI local de triagem (Bun.serve)
  *   setup                Cria a configuração inicial do projeto (config + skills)
  *   update               Sincroniza os arquivos auto-gerados (.houndsman/core)
@@ -23,274 +26,73 @@
  *   `--config <path>` · `--clean` · `--full` · `--no-jev` · `--fail-on-blocking`.
  */
 
-import { runContextCommand } from "../core/commands/context";
-import { runFindingsCommand, runVerifyCommand } from "../core/commands/findings";
-import { parseReviewArgs } from "../core/commands/review";
-import { runSetupCommand } from "../core/commands/setup";
-import { runLibTests } from "../core/commands/test";
-import { runUpdateCommand } from "../core/commands/update";
-import { renderWatchdogContext } from "../core/commands/watchdog";
-import { type HoundsmanConfig, resolveArtifactDir } from "../core/config";
 import { loadConfig } from "../core/config-loader";
-import { JevClient } from "../core/jev";
-import { finalize, prepare, resolveBranch } from "../core/orchestrator";
-import { relFromRoot } from "../core/paths";
-import { checkRegistry } from "../core/registry-check";
-import { startServer } from "../server";
-
-const HELP = `Uso: houndsman [comando] [flags]
-
-Comandos:
-  (nenhum)            Prepara a revisão (classification + briefs + manifesto)
-  --finalize          Consolida os findings em review.md
-  context             Coleta o contexto da PR via gh (Passo 0)
-  findings <sub>      Triagem/correção dos findings (list · show · set · done · reset · sync · summary · batch · verify · path)
-  server              Sobe a UI local de triagem (--port, --host, --open)
-  setup               Cria a configuração inicial do projeto (config + skills)
-  update              Sincroniza os arquivos auto-gerados (.houndsman/core)
-  doctor              Valida a configuração, o ambiente e a credencial Jev
-  test                Roda a suíte de testes da lib
-  watchdog <id>       Contexto de um watchdog (--rules, --json)
-
-Flags:
-  --config <path>     Caminho do houndsman.config.* (default: detecta no cwd)
-  --base <branch>     Base do diff (default: main)
-  --head <ref>        Head do diff (default: HEAD)
-  --branch <nome>     Branch alvo (default: detecta do git)
-  --dir <dir>         Diretório dos artefatos
-  --clean             Descarta findings anteriores
-  --full              Força review completo (ignora o modo incremental)
-  --no-jev            Desativa a pré-análise Jev
-  --fail-on-blocking  Exit 1 se houver bloqueantes (com --finalize)
-
-Flags de findings:
-  --decision <d>      pending | execute | ignore
-  --exec <e>          pending | in_progress | done | stale
-  --comment <text>    Comentário/instrução adicional
-  --watchdog <id>     Filtra por watchdog (list)
-  --severity <s>      Filtra por severidade (list, batch)
-  --file <text>       Filtra por trecho do caminho (list)
-  --all               Inclui findings ausentes do último relatório
-  --json              Saída JSON
-  --limit <n>         Limita o nº de itens (list)
-  --group <key>       Grupo alvo no batch (default: o primeiro)
-  --offset <n>        Paginação dentro do grupo (batch)
-  --include-done      Inclui já concluídos no batch
-  --apply             (verify) Marca os resolvidos como done
-  --fail-on-persisting (verify) Exit 1 se algum blocking persistir`;
-
-function readFlag(args: string[], flag: string): string | undefined {
-	const index = args.indexOf(flag);
-	return index >= 0 ? args[index + 1] : undefined;
-}
-
-/** Passo 0 — contexto da PR via `gh`. */
-function runContext(config: HoundsmanConfig, args: string[]): void {
-	const { paths, context } = runContextCommand(config, {
-		branch: readFlag(args, "--branch"),
-		dir: readFlag(args, "--dir"),
-	});
-
-	if (context.available) {
-		const src = context.source;
-		const label = [src?.number ? `#${src.number}` : "", src?.title ?? ""]
-			.filter(Boolean)
-			.join(" ");
-		console.log(
-			`[houndsman] PR ${label} (${src?.head} → ${src?.base}), ${context.stats?.files ?? 0} arquivo(s).`,
-		);
-		console.log(`[houndsman] contexto: ${relFromRoot(paths.context)}`);
-		console.log(`[houndsman] brief: ${relFromRoot(paths.brief)}`);
-		console.log(
-			`[houndsman] próximo passo: subagente resume em ${relFromRoot(paths.summary)}`,
-		);
-	} else {
-		console.log(
-			`[houndsman] contexto indisponível (${context.reason}): ${context.detail}`,
-		);
-		console.log(`[houndsman] marcador: ${relFromRoot(paths.context)}`);
-	}
-}
-
-/** Valida a configuração do projeto e o ambiente. */
-async function runDoctor(config: HoundsmanConfig): Promise<void> {
-	console.log("→ Validando configuração do projeto...");
-	const { problems, warnings, jevQuestions } = checkRegistry(config);
-
-	if (problems.length > 0) {
-		console.error("\n❌ Problemas na configuração de revisão:\n");
-		for (const problem of problems) console.error(`  - ${problem}`);
-		process.exit(1);
-	}
-	console.log(
-		`  ✅ ${config.watchdogIds.length} watchdogs, ${jevQuestions} pergunta(s) Jev.`,
-	);
-
-	if (warnings.length > 0) {
-		console.log(`\n⚠️  ${warnings.length} aviso(s) (não bloqueantes):`);
-		for (const warning of warnings) console.log(`  - ${warning}`);
-	}
-
-	console.log("\n→ Ambiente:");
-	console.log(`  ${Bun.which("git") ? "✅" : "❌"} git`);
-	console.log(`  ${Bun.which("gh") ? "✅" : "⚠️ "} gh (opcional — contexto da PR)`);
-	await reportJevCredential();
-}
-
-/**
- * Reporta o estado da credencial Jev: presença e validade (chamada mínima).
- * Fail-open — nunca altera o exit code (`doctor` é diagnóstico).
- */
-async function reportJevCredential(): Promise<void> {
-	const client = new JevClient();
-	if (!client.isConfigured()) {
-		console.log("  ⚠️  TYPESAFE_API_KEY (opcional — pré-análise Jev)");
-		return;
-	}
-	const check = await client.validateCredential();
-	if (check.ok) {
-		console.log(`  ✅ Jev: credencial válida (modelo ${check.model}).`);
-	} else if (check.kind === "invalid") {
-		console.log(`  ❌ Jev: credencial inválida — ${check.detail}`);
-	} else {
-		console.log(`  ⚠️  Jev: não foi possível validar — ${check.detail}`);
-	}
-}
-
-/** Contexto de um watchdog. */
-function runWatchdog(config: HoundsmanConfig, args: string[]): void {
-	const id = args.find((arg) => !arg.startsWith("-"));
-
-	if (!id || renderWatchdogContext(config, id) === null) {
-		console.error(
-			id
-				? `Watchdog '${id}' não existe.`
-				: "Informe o id do watchdog: houndsman watchdog <id>",
-		);
-		console.error(`Ids válidos: ${config.watchdogIds.join(", ")}`);
-		process.exit(1);
-	}
-
-	console.log(
-		renderWatchdogContext(config, id, {
-			withRules: args.includes("--rules"),
-			json: args.includes("--json"),
-		}),
-	);
+import { HoundsmanEngine } from "../core/engine/houndsman-engine";
+import { ArgParser } from "./arg-parser";
+import type { CliContext } from "./commands/command";
+import { ContextCommand } from "./commands/context-command";
+import { DoctorCommand } from "./commands/doctor-command";
+import { FindingsCommand } from "./commands/findings-command";
+import { HelpCommand } from "./commands/help-command";
+import { CommandRegistry } from "./commands/registry";
+import { ReviewCommand } from "./commands/review-command";
+import { ServerCommand } from "./commands/server-command";
+import { SetupCommand, TestCommand, UpdateCommand } from "./commands/setup-command";
+import { WatchdogCommand } from "./commands/watchdog-command";
+import { HELP } from "./help";
+
+// ---------------------------------------------------------------------------
+// Registry de comandos
+// ---------------------------------------------------------------------------
+
+/** Monta o registry com todos os comandos do binário. */
+function buildRegistry(): CommandRegistry {
+	const doctor = new DoctorCommand();
+	return new CommandRegistry()
+		.register(new ReviewCommand(), { fallback: true })
+		.register(new HelpCommand())
+		.register(new ContextCommand())
+		.register(new FindingsCommand())
+		.register(new WatchdogCommand())
+		.register(new ServerCommand())
+		.register(new SetupCommand())
+		.register(new UpdateCommand())
+		.register(new TestCommand())
+		.register(doctor)
+		.registerAs("check", doctor);
 }
 
 /**
- * Subcomando `findings` — triagem/correção dos findings (list/show/set/done/reset/
- * sync/summary/batch/verify/path). Deixa o agente interagir com o estado sem abrir
- * o JSON. O `verify` é assíncrono (consulta opcional ao Jev) — roteado à parte.
- */
-async function runFindings(config: HoundsmanConfig, args: string[]): Promise<void> {
-	const sub = args.find((arg) => !arg.startsWith("-"));
-	const result =
-		sub === "verify"
-			? await runVerifyCommand(config, args)
-			: runFindingsCommand(config, args);
-	if (result.exitCode !== 0) {
-		console.error(result.output);
-		process.exit(result.exitCode);
-	}
-	console.log(result.output);
-}
-
-/** Abre a URL no navegador padrão (best-effort, por plataforma). */
-function openBrowser(url: string): void {
-	try {
-		const command =
-			process.platform === "win32"
-				? ["cmd", "/c", "start", "", url]
-				: process.platform === "darwin"
-					? ["open", url]
-					: ["xdg-open", url];
-		Bun.spawn(command, { stdout: "ignore", stderr: "ignore" });
-	} catch {
-		// best-effort — se não abrir, o usuário copia a URL.
-	}
-}
-
-/** Subcomando `server` — sobe a UI local de triagem. */
-function runServer(config: HoundsmanConfig, args: string[]): void {
-	const port = Number(readFlag(args, "--port")) || 7331;
-	const host = readFlag(args, "--host") ?? "127.0.0.1";
-	const { url } = startServer({ config, port, host });
-	console.log(`[houndsman] servidor em ${url}`);
-	console.log("[houndsman] Ctrl+C para encerrar.");
-	if (args.includes("--open")) openBrowser(url);
-}
-
-/** Passo 1/3 — preparar ou finalizar. */
-async function runReview(config: HoundsmanConfig, args: string[]): Promise<void> {
-	const opts = parseReviewArgs(args, resolveArtifactDir(config));
-	const branch = resolveBranch(opts);
-
-	if (opts.finalize) {
-		const result = finalize(opts, branch, config);
-		if (opts.failOnBlocking && result.blockers > 0) process.exit(1);
-	} else {
-		await prepare(opts, branch, config);
-	}
-}
-
-/**
- * Executa um subcomando. `--config` sobrepõe a descoberta automática.
- * Comandos que não precisam de projeto (`test`, `setup`) são tratados antes do load.
+ * Bootstrap do CLI: resolve o comando no registry, carrega a config sob demanda
+ * e delega a execução (o comando decide log/exit).
  */
 export async function main(): Promise<void> {
 	const argv = process.argv.slice(2);
-	const first = argv[0];
-	const command = first && !first.startsWith("-") ? first : undefined;
-	const rest = command ? argv.slice(1) : argv;
-
-	if (command === "test") {
-		process.exit(runLibTests());
-	}
-	if (command === "setup") {
-		await runSetupCommand({ cwd: process.cwd(), args: rest });
-		return;
-	}
-	if (command === "update") {
-		await runUpdateCommand({ cwd: process.cwd(), args: rest });
-		return;
-	}
-
-	if (command === "help") {
-		console.info(HELP);
-		return;
+	const parser = ArgParser.from(argv);
+	const commandName = parser.command();
+	const registry = buildRegistry();
+	const command = registry.resolve(commandName);
+
+	if (!command) {
+		console.error(`Subcomando desconhecido: '${commandName}'.\n`);
+		console.error(HELP);
+		process.exit(1);
 	}
 
-	const { config } = await loadConfig({
-		configPath: readFlag(argv, "--config"),
-	});
-
-	switch (command) {
-		case "context":
-			runContext(config, rest);
-			return;
-		case "doctor":
-		case "check":
-			await runDoctor(config);
-			return;
-		case "watchdog":
-			runWatchdog(config, rest);
-			return;
-		case "findings":
-			await runFindings(config, rest);
-			return;
-		case "server":
-			runServer(config, rest);
-			return;
-		case undefined:
-			await runReview(config, rest);
-			return;
-		default:
-			console.error(`Subcomando desconhecido: '${command}'.\n`);
-			console.error(HELP);
-			process.exit(1);
-	}
+	const context: CliContext = {
+		cwd: process.cwd(),
+		out: (message) => console.log(message),
+		err: (message) => console.error(message),
+		engine: async () => {
+			const { config } = await loadConfig({
+				configPath: parser.value("--config"),
+			});
+			return new HoundsmanEngine(config);
+		},
+	};
+
+	const code = await command.run(parser.rest(), context);
+	if (code !== 0) process.exit(code);
 }
 
 if (import.meta.main) {

package/src/core/arg-parser.ts

@@ -0,0 +1,48 @@
+/**
+ * Parser simples de argv (biblioteca) — compartilhado por CLI e comandos.
+ *
+ * Não valida flags: só lê valores/booleanos e separa o subcomando.
+ */
+
+/** argv com leitura de flags por nome. */
+export class ArgParser {
+	readonly argv: string[];
+
+	constructor(argv: readonly string[]) {
+		this.argv = [...argv];
+	}
+
+	static from(argv: readonly string[]): ArgParser {
+		return new ArgParser(argv);
+	}
+
+	/** Valor da flag (`--x y`), se presente. */
+	value(flag: string): string | undefined {
+		const index = this.argv.indexOf(flag);
+		return index >= 0 ? this.argv[index + 1] : undefined;
+	}
+
+	/** `true` se a flag está presente. */
+	has(flag: string): boolean {
+		return this.argv.includes(flag);
+	}
+
+	/** Primeiro token que não é flag (subcomando). */
+	command(): string | undefined {
+		const first = this.argv[0];
+		return first && !first.startsWith("-") ? first : undefined;
+	}
+
+	/** Argumentos sem o subcomando. */
+	rest(): string[] {
+		const command = this.command();
+		if (!command) return this.argv;
+		const index = this.argv.indexOf(command);
+		return [...this.argv.slice(0, index), ...this.argv.slice(index + 1)];
+	}
+
+	/** Todos os tokens que não começam com `-`. */
+	positionals(): string[] {
+		return this.argv.filter((arg) => !arg.startsWith("-"));
+	}
+}