@payconductor/houndsman 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Houndsman contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
-
-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.
+# houndsman
+
+Orquestrador de revisão de Pull Requests. Classifica o diff, despacha **watchdogs**
+especializados por domínio (um subagente por watchdog) e consolida os achados em um
+relatório único.
+
+> Review de PR no piloto automático: alguém aprova no "LGTM" sem ler, um `catch {}` engole
+> o erro e ninguém nota. Sexta às 18h a produção cobra a conta — e aí todo mundo lembra
+> daquela linha.
+
+![houndsman](assets/houndsman.png)
+
+**Terminologia:** **houndsman** = orquestrador/treinador (CLI + motor) · **watchdog** = cada
+agente especialista por domínio que audita o diff · **review/revisão** = o processo ·
+**Jev** = pré-análise opcional. O vocabulário completo (brief, findings, manifest, budget,
+overflow, churn, candidato…) está em [`docs/GLOSSARY.md`](docs/GLOSSARY.md).
+
+---
+
+## Como iniciar
+
+Você monta o **seu time de cães de caça** (os watchdogs), cada um farejando um domínio
+diferente das PRs. O motor só coordena a caçada — as regras são problema seu.
+
+### 1. Pré-requisitos
+
+- **Bun** — runtime obrigatório.
+- **git** — o diff usa `git diff <base>...<head>`.
+- Opcionais: **`gh`** (contexto da PR) e **`TYPESAFE_API_KEY`** (pré-análise Jev). A revisão
+  funciona normalmente sem eles; o `houndsman doctor` valida a credencial Jev quando presente.
+
+### 2. Instale o CLI (global)
+
+```bash
+bun add -g @payconductor/houndsman
+```
+
+### 3. Configure o projeto (uma vez)
+
+Na raiz do projeto:
+
+```bash
+bun run houndsman setup
+```
+
+Cria a camada `.houndsman/`, que é **autocontida** (não instala nada no seu projeto):
+
+| Caminho | Dono | O que é |
+|---|---|---|
+| `houndsman.config.ts` | você | Configuração do projeto (um objeto de dados) |
+| `.houndsman/watchdogs/` | você | Suas regras — começa com **1 watchdog de exemplo** |
+| `.houndsman/exclusions.ts` | você | Arquivos que nunca entram na revisão |
+| `.houndsman/doc-mappings.ts` | você | path → documentação de contexto |
+| `.houndsman/core/**` | auto | Tipos + docs do skill (sincronizados por `houndsman update`) |
+
+> **Não existe "modo completo".** O `setup` já cria a camada inicial com um watchdog de
+> exemplo — troque o exemplo pelas regras reais do seu projeto (ou use `/houndsman-update`).
+
+### 4. Escreva suas regras
+
+Edite `.houndsman/watchdogs/` — veja [Escrevendo boas regras](docs/AVANCADO.md#escrevendo-boas-regras).
+
+### 5. Valide
+
+```bash
+bun run houndsman doctor
+```
+
+### 6. Rode a primeira revisão
+
+No seu harness (Claude Code / agents), invoque o skill:
+
+```
+/houndsman
+```
+
+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 fluxo de trabalho
+
+```
+/houndsman
+   ├─ Passo 0  contexto da PR (gh, opcional)
+   ├─ Passo 1  classifica o diff → briefs por watchdog
+   ├─ Passo 2  N subagentes revisam em paralelo
+   ├─ Passo 3  consolida em review.md + state.json
+   └─ Passo 4  triagem (UI local ou agente)
+```
+
+- Revisão normal: só `/houndsman` (a branch é detectada; base default `main`).
+- Revisar outra branch: `/houndsman feature/minha-branch`.
+- Manual (sem skill): `houndsman context` → `houndsman --base main` → *(subagentes)* →
+  `houndsman --finalize`.
+- CI: `houndsman --finalize --fail-on-blocking` (exit 1 se houver bloqueantes).
+
+---
+
+## 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
+**UI local** ou pelo **agente** (auto-fix) — sem abrir o JSON à mão:
+
+```bash
+bun run houndsman server --open     # UI: triar, comentar, marcar feito, ler artefatos
+```
+
+- **decision:** `pending` · `execute` · `ignore` (+ comentário).
+- **execState:** `pending` · `in_progress` · `done` · `stale`.
+
+**Auto-fix pelo agente** — as linhas mudam depois do fix, e o motor reancora por conteúdo:
+
+```bash
+bun run houndsman findings list --decision execute --json
+bun run houndsman findings sync
+bun run houndsman findings done <id>
+```
+
+> 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).
+
+---
+
+## Mantendo a configuração
+
+- **Alterar regras** → use o skill **`/houndsman-update`**. Ele 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:
+
+  ```bash
+  bun run houndsman update
+  bun run houndsman doctor
+  ```
+
+  O `update` reescreve **só** `.houndsman/core/**` e `.houndsman/.gitignore`. Seus arquivos
+  (`watchdogs/`, `exclusions.ts`, `doc-mappings.ts`, `houndsman.config.ts`) nunca são tocados.
+- **Recomeçar a camada do zero** → `houndsman setup --force` (sobrescreve só os arquivos do
+  usuário; sem `--force` o `setup` é idempotente).
+
+---
+
+## Documentação
+
+- `docs/AVANCADO.md` — como funciona por dentro (diagrama do fluxo e onde o Jev entra),
+  referência de comandos e boas práticas para escrever regras.
+- `docs/GLOSSARY.md` — glossário do vocabulário de domínio (brief, findings, manifest,
+  budget, overflow, churn, candidato, Jev…): o que cada termo significa **neste** projeto.
+- `docs/CONTRIBUTING.md` — arquitetura, fluxos internos, princípios e desenvolvimento da
+  lib (para quem vai contribuir).
+
+- `src/skill/SETUP.md` — referência de configuração passo a passo.
+- `src/skill/houndsman.md` — orquestração do skill `/houndsman`.
+- `src/skill/houndsman-update.md` — manutenção das regras dos watchdogs.

package/package.json

@@ -1,6 +1,65 @@
 {
-  "name": "@payconductor/houndsman",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@payconductor/houndsman",
+	"version": "0.1.1",
+	"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",
+	"bin": {
+		"houndsman": "./src/cli/index.ts"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"assets",
+		"README.md",
+		"LICENSE"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/payconductor-ai/houndsman.git"
+	},
+	"bugs": {
+		"url": "https://github.com/payconductor-ai/houndsman/issues"
+	},
+	"homepage": "https://github.com/payconductor-ai/houndsman#readme",
+	"author": "PayConductor",
+	"keywords": [
+		"pull-request",
+		"code-review",
+		"cli",
+		"bun",
+		"ai-agents",
+		"orchestrator"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"bun": ">=1.1.0"
+	},
+	"scripts": {
+		"houndsman": "bun run ./src/cli/index.ts",
+		"build": "bun build ./src/cli/index.ts --target bun --outdir dist",
+		"test": "bun test ./src/tests",
+		"typecheck": "tsc -b",
+		"lint": "biome check .",
+		"format": "biome format --write .",
+		"ci": "biome ci . && tsc -b",
+		"ci:check": "biome check",
+		"ci:check:fix": "biome check --fix",
+		"ci:fix": "bun run ci:check:fix && bun run ci:format:fix",
+		"ci:format": "biome format",
+		"ci:format:fix": "biome format --fix"
+	},
+	"dependencies": {
+		"axios": "^1.12.2",
+		"preact": "^11.0.1"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.2.4",
+		"bun-types": "^1.3.14",
+		"typescript": "^7.0.2"
+	}
+}

package/src/cli/index.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env bun
+
+/**
+ * Entrypoint único do `houndsman` — `houndsman [comando]`.
+ *
+ * Carrega a configuração do projeto (`HoundsmanConfig`) em runtime (a partir do
+ * cwd) e orquestra funções/classes de `core/`. Não importa nenhum caminho do
+ * projeto consumidor estaticamente.
+ *
+ * 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 dos findings (list/set/done/sync/...)
+ *   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)
+ *   doctor               Valida a configuração, o ambiente e a credencial Jev (anti-drift)
+ *   test                 Roda a suíte de testes da lib
+ *   watchdog <id>        Contexto de um watchdog (`--rules`, `--json`)
+ *
+ * Flags: `--base <b>` · `--head <ref>` · `--branch <b>` · `--dir <d>` ·
+ *   `--config <path>` · `--clean` · `--no-jev` · `--fail-on-blocking`.
+ */
+
+import { runContextCommand } from "../core/commands/context";
+import { runFindingsCommand } 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 dos findings (list · show · set · done · reset · sync · summary · 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
+  --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)
+  --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)`;
+
+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"),
+		}),
+	);
+}
+
+/**
+ * Subcomando `findings` — triagem dos findings (list/show/set/done/reset/
+ * sync/summary/path). Deixa o agente interagir com o estado sem abrir o JSON.
+ */
+function runFindings(config: HoundsmanConfig, args: string[]): void {
+	const result = 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.
+ */
+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 { 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":
+			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);
+	}
+}
+
+if (import.meta.main) {
+	await main().catch((error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}

package/src/core/assets.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolução dos assets embarcados no pacote (`src/skill/`) — biblioteca.
+ *
+ * Usados para **gerar** a camada de projeto (`houndsman setup`/`update`), não
+ * para resolver caminhos em runtime. Derivados da localização do módulo — não
+ * do cwd.
+ */
+
+import { join } from "node:path";
+
+/** Diretório de assets markdown embarcados no pacote. */
+export const SKILL_DIR = join(import.meta.dir, "..", "skill");
+
+/** Diretório de assets de mídia do pacote (root `assets/` — logo etc.). */
+export const MEDIA_DIR = join(import.meta.dir, "..", "..", "assets");
+
+/** Nome do arquivo de schema de output dos watchdogs. */
+export const OUTPUT_FORMAT_FILE = "OUTPUT-FORMAT.md";
+
+/** Caminho absoluto de um asset embarcado em `src/skill/`. */
+export function assetPath(fileName: string): string {
+	return join(SKILL_DIR, fileName);
+}
+
+/** Caminho absoluto de um asset de mídia em `assets/` (ex.: a logo). */
+export function mediaPath(fileName: string): string {
+	return join(MEDIA_DIR, fileName);
+}