@payconductor/houndsman 0.2.0 → 0.4.0

package/README.md

@@ -74,8 +74,9 @@ No seu harness (Claude Code / agents), invoque o skill:
 /houndsman hunt
 ```
 
-O skill orquestra tudo e grava o relatório em `.houndsman/.runs/<branch-slug>/review.md`.
-Não precisa rodar nenhum script à mão.
+O skill orquestra tudo e persiste o relatório no storage global (SQLite em
+`<HOUNDSMAN_HOME>/houndsman.db`); a UI lê os artefatos direto do storage. Não precisa rodar
+nenhum script à mão.
 
 ---
 
@@ -86,9 +87,9 @@ Não precisa rodar nenhum script à mão.
    ├─ Passo 0  contexto da PR (gh, opcional)
    ├─ Passo 1  classifica o diff → briefs por watchdog (incremental quando possível)
    ├─ Passo 2  N subagentes revisam em paralelo
-   ├─ Passo 3  consolida em review.md + state.json
+   ├─ Passo 3  consolida em review.md + triagem no storage
    ├─ Passo 4  valida na UI (server) e marca os achados a executar
-   ├─ Passo 5  fix corrige o grupo atual → run.json (fix_done)
+   ├─ Passo 5  fix corrige o grupo atual → status fix_done
    └─ Passo 6  verify confere o que resolveu, sem re-revisar
 ```
 
@@ -111,7 +112,7 @@ O skill tem **4 capabilities**, todas em `/houndsman`:
 ## Triando os findings (opcional)
 
 Depois do `--finalize`, cada finding tem um `id` curto e um `fingerprint` de **conteúdo**
-no `.houndsman/.runs/<branch-slug>/state.json`. Você decide o que fazer com cada um — pela
+no storage global. Você decide o que fazer com cada um — pela
 **UI local** ou pelo **agente** (auto-fix) — sem abrir o JSON à mão:
 
 ```bash
@@ -136,12 +137,23 @@ bun run houndsman findings verify           # confere o que resolveu (barato, se
 > o review completo.
 
 > A identidade do finding é o **conteúdo** (fingerprint), não a linha: itens deslocados
-> pelo fix não se perdem. O estado é local e mora em `.runs/<slug>/state.json` (gitignored).
+> pelo fix não se perdem. O estado mora no storage global (`<HOUNDSMAN_HOME>/houndsman.db`).
 
 ---
 
 ## Mantendo a configuração
 
+- **Persistência** → por default, SQLite global em `<HOUNDSMAN_HOME>/houndsman.db`
+  (`HOUNDSMAN_HOME` sobrescreve o diretório de dados). Para voltar ao backend de arquivos,
+  troque só o provider — a interface `StorageProvider` é a mesma:
+
+  ```ts
+  export const houndsmanConfig = {
+    // ...
+    storage: { provider: "file", path: "./houndsman-runs" },
+  };
+  ```
+
 - **Alterar regras** → use a capability **`train`** (`/houndsman train`). Ela prova no código
   que o padrão existe (evidência) antes de editar e roda as validações.
 - **Atualizou a lib?** Sincronize os arquivos auto-gerados sem tocar nas suas regras:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@payconductor/houndsman",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "Orquestrador de revisão de Pull Requests: classifica o diff, despacha watchdogs especializados por domínio e consolida o relatório.",
 	"type": "module",
 	"license": "MIT",

package/src/cli/arg-parser.ts

@@ -0,0 +1,8 @@
+/**
+ * Parser de argv do CLI — reexporta a implementação de `core/`.
+ *
+ * O parser vive em `core/` para ser reutilizado pelos comandos da biblioteca
+ * (`parseReviewArgs`) sem inverter a camada `core → cli`.
+ */
+
+export { ArgParser } from "../core/arg-parser";

package/src/cli/commands/command.ts

@@ -0,0 +1,23 @@
+/**
+ * Contrato dos comandos do CLI.
+ *
+ * `core/` continua devolvendo dados; os comandos decidem o que imprimir e o
+ * exit code. O engine é carregado sob demanda (comandos sem projeto não pagam).
+ */
+
+import type { HoundsmanEngine } from "../../core/engine/houndsman-engine";
+
+/** Contexto de execução de um comando. */
+export type CliContext = {
+	cwd: string;
+	/** Carrega a config do projeto e devolve o engine (lazy). */
+	engine: () => Promise<HoundsmanEngine>;
+	out: (message: string) => void;
+	err: (message: string) => void;
+};
+
+/** Um subcomando do binário. */
+export interface Command {
+	readonly name: string;
+	run(args: string[], context: CliContext): Promise<number>;
+}

package/src/cli/commands/context-command.ts

@@ -0,0 +1,40 @@
+/** Comando `context` — coleta o contexto da PR via `gh` (Passo 0). */
+
+import { runContextCommand } from "../../core/commands/context";
+import { displayPath } from "../../core/paths";
+import { ArgParser } from "../arg-parser";
+import type { CliContext, Command } from "./command";
+
+export class ContextCommand implements Command {
+	readonly name = "context";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const engine = await context.engine();
+		const parser = ArgParser.from(args);
+		const { paths, context: pr } = runContextCommand(
+			engine.config,
+			engine.storage,
+			engine.repo,
+			{ branch: parser.value("--branch") },
+		);
+
+		if (pr.available) {
+			const src = pr.source;
+			const label = [src?.number ? `#${src.number}` : "", src?.title ?? ""]
+				.filter(Boolean)
+				.join(" ");
+			context.out(
+				`[houndsman] PR ${label} (${src?.head} → ${src?.base}), ${pr.stats?.files ?? 0} arquivo(s).`,
+			);
+			context.out(`[houndsman] contexto: ${displayPath(paths.context)}`);
+			context.out(`[houndsman] brief: ${displayPath(paths.brief)}`);
+			context.out(
+				`[houndsman] próximo passo: subagente resume em ${displayPath(paths.summary)}`,
+			);
+		} else {
+			context.out(`[houndsman] contexto indisponível (${pr.reason}): ${pr.detail}`);
+			context.out(`[houndsman] marcador: ${displayPath(paths.context)}`);
+		}
+		return 0;
+	}
+}

package/src/cli/commands/doctor-command.ts

@@ -0,0 +1,60 @@
+/** Comando `doctor` (alias `check`) — valida config, ambiente e credencial Jev. */
+
+import { checkRegistry } from "../../core/registry-check";
+import { storageLocation } from "../../core/storage/paths";
+import type { CliContext, Command } from "./command";
+
+export class DoctorCommand implements Command {
+	readonly name = "doctor";
+
+	async run(_args: string[], context: CliContext): Promise<number> {
+		const engine = await context.engine();
+		context.out("→ Validando configuração do projeto...");
+		const { problems, warnings, jevQuestions } = checkRegistry(engine.config);
+
+		if (problems.length > 0) {
+			context.err("\n❌ Problemas na configuração de revisão:\n");
+			for (const problem of problems) context.err(`  - ${problem}`);
+			return 1;
+		}
+		context.out(
+			`  ✅ ${engine.config.watchdogIds.length} watchdogs, ${jevQuestions} pergunta(s) Jev.`,
+		);
+
+		if (warnings.length > 0) {
+			context.out(`\n⚠️  ${warnings.length} aviso(s) (não bloqueantes):`);
+			for (const warning of warnings) context.out(`  - ${warning}`);
+		}
+
+		context.out("\n→ Ambiente:");
+		context.out(`  ${Bun.which("git") ? "✅" : "❌"} git`);
+		context.out(`  ${Bun.which("gh") ? "✅" : "⚠️ "} gh (opcional — contexto da PR)`);
+		context.out("\n→ Persistência:");
+		context.out(`  provider: ${engine.storage.kind}`);
+		context.out(`  ${storageLocation(engine.config)}`);
+		context.out(`  repo: ${engine.repo.key}`);
+		await this.reportJevCredential(context);
+		return 0;
+	}
+
+	/**
+	 * Reporta o estado da credencial Jev: presença e validade (chamada mínima).
+	 * Fail-open — nunca altera o exit code (`doctor` é diagnóstico).
+	 */
+	private async reportJevCredential(context: CliContext): Promise<void> {
+		const { JevClient } = await import("../../core/jev");
+		const client = new JevClient();
+		if (!client.isConfigured()) {
+			context.out("  ⚠️  TYPESAFE_API_KEY (opcional — pré-análise Jev)");
+			return;
+		}
+		const check = await client.validateCredential();
+		if (check.ok) {
+			context.out(`  ✅ Jev: credencial válida (modelo ${check.model}).`);
+		} else if (check.kind === "invalid") {
+			context.out(`  ❌ Jev: credencial inválida — ${check.detail}`);
+		} else {
+			context.out(`  ⚠️  Jev: não foi possível validar — ${check.detail}`);
+		}
+	}
+}

package/src/cli/commands/findings-command.ts

@@ -0,0 +1,38 @@
+/** Comando `findings` — triagem/correção (inclui verify/submit). */
+
+import {
+	runFindingsCommand,
+	runSubmitCommand,
+	runVerifyCommand,
+} from "../../core/commands/findings";
+import { ArgParser } from "../arg-parser";
+import type { CliContext, Command } from "./command";
+
+export class FindingsCommand implements Command {
+	readonly name = "findings";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const engine = await context.engine();
+		const sub = ArgParser.from(args).command();
+		const result =
+			sub === "verify"
+				? await runVerifyCommand(engine.config, engine.storage, engine.repo, args)
+				: sub === "submit"
+					? await runSubmitCommand(
+							engine.config,
+							engine.storage,
+							engine.repo,
+							args,
+						)
+					: runFindingsCommand(
+							engine.config,
+							engine.storage,
+							engine.repo,
+							args,
+						);
+
+		if (result.exitCode !== 0) context.err(result.output);
+		else context.out(result.output);
+		return result.exitCode;
+	}
+}

package/src/cli/commands/help-command.ts

@@ -0,0 +1,13 @@
+/** Comando `help` — imprime o uso e encerra. */
+
+import { HELP } from "../help";
+import type { CliContext, Command } from "./command";
+
+export class HelpCommand implements Command {
+	readonly name = "help";
+
+	async run(_args: string[], context: CliContext): Promise<number> {
+		context.out(HELP);
+		return 0;
+	}
+}

package/src/cli/commands/registry.ts

@@ -0,0 +1,34 @@
+/**
+ * Registry de comandos (CLI) — resolve nome → comando e guarda o fallback.
+ */
+
+import type { Command } from "./command";
+
+/** Mapa de comandos por nome, com um comando default. */
+export class CommandRegistry {
+	private readonly commands = new Map<string, Command>();
+	private fallback: Command | undefined;
+
+	/** Registra um comando (ou o fallback, quando `fallback`). */
+	register(command: Command, options: { fallback?: boolean } = {}): this {
+		if (options.fallback) this.fallback = command;
+		else this.commands.set(command.name, command);
+		return this;
+	}
+
+	/** Registra o mesmo comando sob outro nome (alias). */
+	registerAs(name: string, command: Command): this {
+		this.commands.set(name, command);
+		return this;
+	}
+
+	/** Resolve o comando pelo nome; sem nome → fallback. */
+	resolve(name: string | undefined): Command | undefined {
+		return name ? this.commands.get(name) : this.fallback;
+	}
+
+	/** Nomes registrados (sem o fallback). */
+	names(): string[] {
+		return [...this.commands.keys()];
+	}
+}

package/src/cli/commands/review-command.ts

@@ -0,0 +1,21 @@
+/** Comando default — prepara ou finaliza a revisão. */
+
+import { parseReviewArgs } from "../../core/commands/review";
+import type { CliContext, Command } from "./command";
+
+export class ReviewCommand implements Command {
+	readonly name = "";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const engine = await context.engine();
+		const options = parseReviewArgs(args);
+		const result = await engine.session(options).run();
+
+		for (const message of result.messages) context.out(message);
+
+		if ("blockers" in result && options.failOnBlocking && result.blockers > 0) {
+			return 1;
+		}
+		return 0;
+	}
+}

package/src/cli/commands/server-command.ts

@@ -0,0 +1,37 @@
+/** Comando `server` — sobe a UI local de triagem. */
+
+import { ArgParser } from "../arg-parser";
+import type { CliContext, Command } from "./command";
+
+/** 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.
+	}
+}
+
+export class ServerCommand implements Command {
+	readonly name = "server";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const engine = await context.engine();
+		const parser = ArgParser.from(args);
+		const port = Number(parser.value("--port")) || 7331;
+		const host = parser.value("--host") ?? "127.0.0.1";
+
+		const { startServer } = await import("../../server");
+		const { url } = startServer({ config: engine.config, port, host });
+		context.out(`[houndsman] servidor em ${url}`);
+		context.out("[houndsman] Ctrl+C para encerrar.");
+		if (parser.has("--open")) openBrowser(url);
+		return 0;
+	}
+}

package/src/cli/commands/setup-command.ts

@@ -0,0 +1,34 @@
+/** Comandos que não dependem da config do projeto: setup, update e test. */
+
+import type { CliContext, Command } from "./command";
+
+export class SetupCommand implements Command {
+	readonly name = "setup";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const { runSetupCommand } = await import("../../core/commands/setup");
+		const messages = await runSetupCommand({ cwd: context.cwd, args });
+		for (const message of messages) context.out(message);
+		return 0;
+	}
+}
+
+export class UpdateCommand implements Command {
+	readonly name = "update";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const { runUpdateCommand } = await import("../../core/commands/update");
+		const messages = await runUpdateCommand({ cwd: context.cwd, args });
+		for (const message of messages) context.out(message);
+		return 0;
+	}
+}
+
+export class TestCommand implements Command {
+	readonly name = "test";
+
+	async run(_args: string[], _context: CliContext): Promise<number> {
+		const { runLibTests } = await import("../../core/commands/test");
+		return runLibTests();
+	}
+}

package/src/cli/commands/watchdog-command.ts

@@ -0,0 +1,34 @@
+/** Comando `watchdog` — contexto de um watchdog. */
+
+import { renderWatchdogContext } from "../../core/commands/watchdog";
+import { ArgParser } from "../arg-parser";
+import type { CliContext, Command } from "./command";
+
+export class WatchdogCommand implements Command {
+	readonly name = "watchdog";
+
+	async run(args: string[], context: CliContext): Promise<number> {
+		const engine = await context.engine();
+		const parser = ArgParser.from(args);
+		const id = args.find((arg) => !arg.startsWith("-"));
+
+		if (!id) {
+			context.err("Informe o id do watchdog: houndsman watchdog <id>");
+			context.err(`Ids válidos: ${engine.config.watchdogIds.join(", ")}`);
+			return 1;
+		}
+
+		const output = renderWatchdogContext(engine.config, id, {
+			withRules: parser.has("--rules"),
+			json: parser.has("--json"),
+		});
+		if (output === null) {
+			context.err(`Watchdog '${id}' não existe.`);
+			context.err(`Ids válidos: ${engine.config.watchdogIds.join(", ")}`);
+			return 1;
+		}
+
+		context.out(output);
+		return 0;
+	}
+}

package/src/cli/help.ts

@@ -0,0 +1,47 @@
+/** Texto de ajuda do CLI (mantido fora do bootstrap para reduzir acoplamento). */
+export 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 · submit · 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)
+  --clean             Descarta findings brutos do staging anterior
+  --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
+  --include-sent      (submit) Reenvia findings já enviados à PR
+  --dry-run           (submit) Só a prévia do envio, sem postar
+
+Persistência:
+  Runs, findings e artefatos ficam no storage global (SQLite em
+  <HOUNDSMAN_HOME>/houndsman.db). Use storage.provider: "file" na config para
+  voltar ao backend de arquivos. Nada é gravado em .houndsman/.runs.`;