@payconductor/houndsman 0.12.0 → 0.13.0

package/src/core/hunt/maki-model.ts

@@ -0,0 +1,101 @@
+/**
+ * Resolução do modelo/credencial do maki (harness local).
+ *
+ * O houndsman reaproveita a config de IA (`ai.provider`/`ai.model`) e a env já
+ * preenchida (`HOUNDSMAN_DEEP_SEEK_API_KEY` etc.). O maki lê o nome nativo do
+ * provider (`DEEPSEEK_API_KEY`); a chave é injetada só no processo filho.
+ */
+
+import type { AiProviderKind } from "../config";
+import { ENV_NAMES, env } from "../env";
+import type { ProjectConfig } from "../project-config";
+
+/** Modelo e credencial no formato esperado pelo maki. */
+export type MakiModel = {
+	/** Spec `provider/model-id` passada em `--model`. */
+	spec: string;
+	provider: AiProviderKind;
+	/** Variável nativa que o maki lê (ex.: `DEEPSEEK_API_KEY`). */
+	apiKeyEnv: string;
+	/** Chave do houndsman (pode faltar; `requireMakiModel` exige). */
+	apiKey?: string;
+};
+
+/** Env nativa do maki por provider. */
+export const MAKI_API_KEY_ENV: Record<AiProviderKind, string> = {
+	deepseek: "DEEPSEEK_API_KEY",
+	openai: "OPENAI_API_KEY",
+	anthropic: "ANTHROPIC_API_KEY",
+};
+
+/** Chave do houndsman por provider (para mensagens acionáveis). */
+const HOUNDSMAN_KEY_ENV: Record<AiProviderKind, string> = {
+	deepseek: ENV_NAMES.deepSeekApiKey,
+	openai: ENV_NAMES.openAiApiKey,
+	anthropic: ENV_NAMES.anthropicApiKey,
+};
+
+/** Nome da env do houndsman que guarda a chave do provider. */
+export function houndsmanKeyEnvFor(provider: AiProviderKind): string {
+	return HOUNDSMAN_KEY_ENV[provider];
+}
+
+/** `true` para um slug de provider suportado. */
+function isAiProvider(value: string): value is AiProviderKind {
+	return value === "deepseek" || value === "openai" || value === "anthropic";
+}
+
+/** Chave do houndsman para o provider. */
+function providerKey(provider: AiProviderKind): string | undefined {
+	switch (provider) {
+		case "deepseek":
+			return env.deepSeekApiKey;
+		case "openai":
+			return env.openAiApiKey;
+		case "anthropic":
+			return env.anthropicApiKey;
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Resolve o modelo: override → `hunt.model` → `ai.model`.
+ *
+ * Um prefixo reconhecido (`openai/...`, `anthropic/...`) troca o provider do
+ * harness e, junto, a variável de credencial usada.
+ */
+export function resolveMakiModel(project: ProjectConfig, override?: string): MakiModel {
+	const configured = override?.trim() || project.huntModel;
+	let provider = project.aiProvider;
+	let modelId = configured;
+
+	const [prefix, ...tail] = configured.split("/");
+	if (tail.length > 0 && isAiProvider(prefix)) {
+		provider = prefix;
+		modelId = tail.join("/");
+	}
+
+	const spec = `${provider}/${modelId}`;
+	return {
+		spec,
+		provider,
+		apiKeyEnv: MAKI_API_KEY_ENV[provider],
+		apiKey: providerKey(provider),
+	};
+}
+
+/** Como `resolveMakiModel`, mas lança quando a credencial falta. */
+export function requireMakiModel(
+	project: ProjectConfig,
+	override?: string,
+): MakiModel & { apiKey: string } {
+	const model = resolveMakiModel(project, override);
+	if (!model.apiKey) {
+		throw new Error(
+			`Harness local sem credencial: defina ${HOUNDSMAN_KEY_ENV[model.provider]} ` +
+				`(o maki usa ${model.apiKeyEnv}).`,
+		);
+	}
+	return { ...model, apiKey: model.apiKey };
+}

package/src/core/hunt/maki-prompt.ts

@@ -0,0 +1,71 @@
+/**
+ * Prompt do watchdog no harness local.
+ *
+ * O brief original manda gravar o JSON em `findings/<id>.json`. No maki o
+ * watchdog **não** recebe permissão de escrita: ele devolve o JSON na resposta
+ * final e o houndsman valida e grava. Este módulo só acrescenta o contrato;
+ * não altera o brief usado pela skill `/houndsman hunt`.
+ */
+
+/** Dados do prompt de um watchdog. */
+export type HuntPromptInput = {
+	projectName: string;
+	watchdogId: string;
+	/** Conteúdo do brief renderizado pelo prepare. */
+	brief: string;
+};
+
+/** Schema compacto repetido no prompt (evita depender de arquivo externo). */
+function outputSchema(watchdogId: string): string {
+	return `{
+  "watchdogId": "${watchdogId}",
+  "reviewedFiles": ["caminho/relativo.ts"],
+  "skipped": ["arquivo não lido + motivo"],
+  "findings": [
+    {
+      "rule": "regra do brief",
+      "severity": "blocking | attention | suggestion | nit",
+      "file": "caminho/relativo.ts",
+      "line": 123,
+      "message": "o que está errado",
+      "action": "o que fazer",
+      "evidence": "trecho que comprova"
+    }
+  ]
+}`;
+}
+
+/** Monta o prompt enviado ao maki para um brief. */
+export function renderHuntPrompt(input: HuntPromptInput): string {
+	return [
+		`Você é o watchdog \`${input.watchdogId}\` do projeto ${input.projectName}.`,
+		"Execute o brief abaixo e devolva os achados como JSON.",
+		"",
+		"## Contrato do harness local",
+		"",
+		"- Use apenas leitura e busca; **não escreva arquivos** e não rode comandos.",
+		"- Ignore a instrução do brief sobre gravar `outputPath`: o houndsman grava por você.",
+		"- Responda **somente** com um objeto JSON válido (sem markdown, sem texto antes/depois).",
+		"- `watchdogId` deve ser exatamente o id acima; use `findings: []` quando não houver achado.",
+		"- `line` deve estar dentro do escopo do diff descrito no brief.",
+		"",
+		"### Schema",
+		"",
+		outputSchema(input.watchdogId),
+		"",
+		"## Brief",
+		"",
+		input.brief.trim(),
+	].join("\n");
+}
+
+/** Sufixo corretivo das retentativas (saída inválida). */
+export function renderRetrySuffix(error: string): string {
+	return [
+		"",
+		"## Correção obrigatória",
+		"",
+		`A resposta anterior foi rejeitada: ${error}`,
+		"Responda APENAS com o objeto JSON completo, no schema acima, sem markdown.",
+	].join("\n");
+}

package/src/core/hunt/maki-release.ts

@@ -0,0 +1,104 @@
+/**
+ * Releases do maki (harness local) — resolução pura de versão, asset e checksum.
+ *
+ * O houndsman fixa uma versão testada (`DEFAULT_MAKI_VERSION`) e baixa o binário
+ * do GitHub Releases. Nada aqui acessa rede: são funções puras para teste.
+ */
+
+import { DEFAULT_MAKI_VERSION } from "../defaults";
+import { env } from "../env";
+
+/** Repositório oficial do maki (binários por plataforma). */
+export const MAKI_REPO = "tontinton/maki";
+
+/** Base dos downloads de release. */
+export const MAKI_RELEASE_BASE = `https://github.com/${MAKI_REPO}/releases/download`;
+
+/** Asset de release para uma combinação plataforma/arquitetura. */
+export type MakiAsset = {
+	/** Nome do arquivo no release. */
+	name: string;
+	/** Formato de compressão (só informativo; a extração usa `tar`). */
+	format: "tar.gz" | "zip";
+};
+
+/** Assets publicados por plataforma/arquitetura. */
+const MAKI_ASSETS: Record<string, MakiAsset> = {
+	"win32-x64": { name: "maki-v{version}-x86_64-pc-windows-msvc.zip", format: "zip" },
+	"darwin-x64": {
+		name: "maki-v{version}-x86_64-apple-darwin.tar.gz",
+		format: "tar.gz",
+	},
+	"darwin-arm64": {
+		name: "maki-v{version}-aarch64-apple-darwin.tar.gz",
+		format: "tar.gz",
+	},
+	"linux-x64": {
+		name: "maki-v{version}-x86_64-unknown-linux-musl.tar.gz",
+		format: "tar.gz",
+	},
+	"linux-arm64": {
+		name: "maki-v{version}-aarch64-unknown-linux-musl.tar.gz",
+		format: "tar.gz",
+	},
+};
+
+/** Nome do executável do maki na plataforma atual. */
+export function makiBinaryName(platform: string = process.platform): string {
+	return platform === "win32" ? "maki.exe" : "maki";
+}
+
+/** Normaliza a versão (`v0.6.5` → `0.6.5`) e valida os caracteres. */
+export function normalizeMakiVersion(value: string): string {
+	const normalized = value.trim().replace(/^v/i, "");
+	if (!/^[0-9A-Za-z][0-9A-Za-z._-]*$/.test(normalized)) {
+		throw new Error(`Versão do maki inválida: '${value}'.`);
+	}
+	return normalized;
+}
+
+/** Versão efetiva: flag/env (`HOUNDSMAN_MAKI_VERSION`) ou a fixada no pacote. */
+export function effectiveMakiVersion(override?: string): string {
+	const value = override?.trim() || env.makiVersion || DEFAULT_MAKI_VERSION;
+	return normalizeMakiVersion(value);
+}
+
+/** Asset da plataforma/arquitetura informada, ou `null` se não houver release. */
+export function makiAssetFor(
+	platform: string,
+	arch: string,
+	version: string,
+): MakiAsset | null {
+	const asset = MAKI_ASSETS[`${platform}-${arch}`];
+	if (!asset) return null;
+	return {
+		name: asset.name.replace("{version}", normalizeMakiVersion(version)),
+		format: asset.format,
+	};
+}
+
+/** URL do asset no GitHub Releases. */
+export function makiDownloadUrl(version: string, asset: string): string {
+	return `${MAKI_RELEASE_BASE}/v${normalizeMakiVersion(version)}/${asset}`;
+}
+
+/** URL do arquivo de checksums do release. */
+export function makiChecksumsUrl(version: string): string {
+	return `${MAKI_RELEASE_BASE}/v${normalizeMakiVersion(version)}/sha256sums.txt`;
+}
+
+/** Converte o `sha256sums.txt` (`<hash>  <arquivo>`) em mapa. */
+export function parseChecksums(text: string): Map<string, string> {
+	const checksums = new Map<string, string>();
+	for (const line of text.split(/\r?\n/)) {
+		const match = line.trim().match(/^([0-9a-f]{64})\s+\*?(.+)$/i);
+		if (!match) continue;
+		checksums.set(match[2].trim(), match[1].toLowerCase());
+	}
+	return checksums;
+}
+
+/** Checksum esperado de um asset (ou `undefined` se o release não listar). */
+export function checksumFor(checksumsText: string, asset: string): string | undefined {
+	return parseChecksums(checksumsText).get(asset);
+}

package/src/core/hunt/maki-runner.ts

@@ -0,0 +1,276 @@
+/**
+ * Execução headless do maki (harness local).
+ *
+ * Um processo por watchdog, sem TUI: o prompt vai por stdin (`maki -p`) e o
+ * houndsman lê o JSON de `--output-format json`. O watchdog não recebe
+ * permissão de escrita: `write`/`edit`/`bash`/rede/`task` são negados (deny
+ * vence qualquer yolo). Nenhuma config global do maki é alterada.
+ */
+
+/** Ferramentas negadas ao watchdog (deny vence `--yolo`). */
+export const MAKI_DISALLOWED_TOOLS =
+	"bash,webfetch,websearch,write,edit,multiedit,edit_lines,insert_lines,task";
+
+/** Pedido de execução de um watchdog. */
+export type MakiRunRequest = {
+	/** Prompt completo (brief + contrato). */
+	prompt: string;
+	/** Raiz de leitura (worktree ou clone principal). */
+	cwd: string;
+	/** Spec `provider/model-id`. */
+	model: string;
+	/** Variável nativa que o maki lê (`DEEPSEEK_API_KEY` etc.). */
+	apiKeyEnv: string;
+	/** Valor da chave (injetado só no processo filho). */
+	apiKey: string;
+	/** Timeout do processo (ms). */
+	timeoutMs: number;
+};
+
+/** Uso de tokens normalizado. */
+export type MakiUsage = {
+	inputTokens?: number;
+	outputTokens?: number;
+	totalTokens?: number;
+	cacheReadInputTokens?: number;
+};
+
+/** Métricas de uma execução. */
+export type MakiRunMetrics = {
+	sessionId?: string;
+	durationMs: number;
+	numTurns?: number;
+	costUsd?: number;
+	usage?: MakiUsage;
+};
+
+/** Resultado de uma execução. */
+export type MakiRunResult =
+	| {
+			ok: true;
+			/** Texto final do agente (deve conter o JSON dos findings). */
+			text: string;
+			metrics: MakiRunMetrics;
+			stderr: string;
+			exitCode: number;
+	  }
+	| {
+			ok: false;
+			error: string;
+			metrics: MakiRunMetrics;
+			stderr: string;
+			exitCode?: number;
+			timedOut?: boolean;
+	  };
+
+/** Runner injetável (testes usam um fake sem processo). */
+export interface MakiProcessRunner {
+	run(request: MakiRunRequest): Promise<MakiRunResult>;
+}
+
+/** Saída JSON do `maki --print --output-format json`. */
+export type MakiJsonOutput = {
+	type?: string;
+	subtype?: string;
+	is_error?: boolean;
+	result?: string;
+	session_id?: string;
+	duration_ms?: number;
+	num_turns?: number;
+	total_cost_usd?: number;
+	usage?: {
+		input_tokens?: number;
+		output_tokens?: number;
+		total_tokens?: number;
+		cache_read_input_tokens?: number;
+	};
+};
+
+/** Argumentos do processo (o prompt vai por stdin). */
+export function makiArgs(model: string): string[] {
+	return [
+		"-p",
+		"--output-format",
+		"json",
+		"--model",
+		model,
+		"--disallowed-tools",
+		MAKI_DISALLOWED_TOOLS,
+	];
+}
+
+/** Runner real, via `Bun.spawn`. */
+export class SpawnMakiRunner implements MakiProcessRunner {
+	private readonly binary: string;
+
+	constructor(binary: string) {
+		this.binary = binary;
+	}
+
+	async run(request: MakiRunRequest): Promise<MakiRunResult> {
+		const started = Date.now();
+		let timedOut = false;
+		try {
+			const proc = Bun.spawn([this.binary, ...makiArgs(request.model)], {
+				cwd: request.cwd,
+				env: { ...process.env, [request.apiKeyEnv]: request.apiKey },
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+
+			try {
+				proc.stdin.write(request.prompt);
+				void Promise.resolve(proc.stdin.end()).catch(() => {});
+			} catch {
+				// O processo pode ter encerrado antes de ler o stdin; o exit code
+				// e o stderr abaixo explicam o motivo.
+			}
+
+			// Consome os pipes desde já para não travar em saídas grandes.
+			const stdoutPromise = new Response(proc.stdout).text();
+			const stderrPromise = new Response(proc.stderr).text();
+			const timer = setTimeout(
+				() => {
+					timedOut = true;
+					proc.kill();
+				},
+				Math.max(1_000, request.timeoutMs),
+			);
+			const exitCode = await proc.exited;
+			clearTimeout(timer);
+			const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+			const durationMs = Date.now() - started;
+			const parsed = parseMakiOutput(stdout);
+			const metrics = metricsFrom(parsed, durationMs);
+
+			if (timedOut) {
+				return {
+					ok: false,
+					error: `Timeout após ${Math.round(durationMs / 1000)}s no maki.`,
+					metrics,
+					stderr,
+					exitCode,
+					timedOut: true,
+				};
+			}
+			if (exitCode !== 0 || parsed?.is_error === true) {
+				return {
+					ok: false,
+					error:
+						parsed?.result?.trim() ||
+						stderr.trim() ||
+						`maki saiu com código ${exitCode}.`,
+					metrics,
+					stderr,
+					exitCode,
+				};
+			}
+			if (typeof parsed?.result !== "string" || parsed.result.trim().length === 0) {
+				return {
+					ok: false,
+					error: "maki não retornou `result` (esperado com --output-format json).",
+					metrics,
+					stderr,
+					exitCode,
+				};
+			}
+			return {
+				ok: true,
+				text: parsed.result,
+				metrics,
+				stderr,
+				exitCode,
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error:
+					error instanceof Error
+						? `Falha ao executar o maki: ${error.message}`
+						: `Falha ao executar o maki: ${String(error)}`,
+				metrics: { durationMs: Date.now() - started },
+				stderr: "",
+			};
+		}
+	}
+}
+
+/** Extrai o objeto JSON do stdout do maki (linha única ou objeto completo). */
+export function parseMakiOutput(stdout: string): MakiJsonOutput | null {
+	const whole = tryParseJson(stdout.trim());
+	if (whole.ok && isObject(whole.value)) return whole.value as MakiJsonOutput;
+
+	const lines = stdout.split(/\r?\n/);
+	for (let index = lines.length - 1; index >= 0; index--) {
+		const line = lines[index].trim();
+		if (!line.startsWith("{")) continue;
+		const parsed = tryParseJson(line);
+		if (parsed.ok && isObject(parsed.value)) return parsed.value as MakiJsonOutput;
+	}
+	return null;
+}
+
+/**
+ * Extrai o JSON dos findings da resposta final do agente.
+ * Aceita JSON puro, bloco markdown ou objeto cercado por texto.
+ */
+export function extractJsonObject(text: string): unknown | null {
+	const trimmed = text.trim();
+	if (trimmed.length === 0) return null;
+
+	const direct = tryParseJson(trimmed);
+	if (direct.ok) return direct.value;
+
+	const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+	if (fenced) {
+		const parsed = tryParseJson(fenced[1].trim());
+		if (parsed.ok) return parsed.value;
+	}
+
+	const start = trimmed.indexOf("{");
+	const end = trimmed.lastIndexOf("}");
+	if (start >= 0 && end > start) {
+		const parsed = tryParseJson(trimmed.slice(start, end + 1));
+		if (parsed.ok) return parsed.value;
+	}
+	return null;
+}
+
+/** Normaliza as métricas do JSON do maki. */
+export function metricsFrom(
+	output: MakiJsonOutput | null,
+	durationMs: number,
+): MakiRunMetrics {
+	const usage = output?.usage;
+	return {
+		sessionId: typeof output?.session_id === "string" ? output.session_id : undefined,
+		durationMs: numberOr(output?.duration_ms) ?? durationMs,
+		numTurns: numberOr(output?.num_turns),
+		costUsd: numberOr(output?.total_cost_usd),
+		usage: usage
+			? {
+					inputTokens: numberOr(usage.input_tokens),
+					outputTokens: numberOr(usage.output_tokens),
+					totalTokens: numberOr(usage.total_tokens),
+					cacheReadInputTokens: numberOr(usage.cache_read_input_tokens),
+				}
+			: undefined,
+	};
+}
+
+function numberOr(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function tryParseJson(text: string): { ok: true; value: unknown } | { ok: false } {
+	try {
+		return { ok: true, value: JSON.parse(text) };
+	} catch {
+		return { ok: false };
+	}
+}

package/src/core/hunt/pool.ts

@@ -0,0 +1,30 @@
+/**
+ * Pool de concorrência mínimo (harness local).
+ *
+ * Mantém no máximo `limit` promessas ativas e preserva a ordem dos resultados.
+ * Não trata erros: o chamador decide se cada item falha isoladamente.
+ */
+
+/** Executa `mapper` para cada item com concorrência limitada. */
+export async function mapPool<T, R>(
+	items: readonly T[],
+	limit: number,
+	mapper: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+	const results = new Array<R>(items.length);
+	if (items.length === 0) return results;
+
+	let next = 0;
+	const workers = Array.from(
+		{ length: Math.max(1, Math.min(limit, items.length)) },
+		async () => {
+			while (true) {
+				const index = next++;
+				if (index >= items.length) return;
+				results[index] = await mapper(items[index], index);
+			}
+		},
+	);
+	await Promise.all(workers);
+	return results;
+}

package/src/core/logging/index.ts

@@ -15,3 +15,5 @@ export type {
 	SpinnerLike,
 } from "./logger";
 export { Logger, SilentLogger } from "./logger";
+export type { ProgressBoardOptions } from "./progress";
+export { formatDuration, PhaseReporter, ProgressBoard } from "./progress";

package/src/core/logging/logger.ts

@@ -38,6 +38,10 @@ export interface LoggerLike {
 		text: string,
 		run: (spinner: SpinnerLike | null) => Promise<T>,
 	): Promise<T>;
+	/** `true` quando a saída é um TTY e o modo quiet está desligado. */
+	readonly interactive: boolean;
+	/** Stream de saída (usado pelos blocos de progresso). */
+	readonly stream: NodeJS.WritableStream;
 }
 
 /** Opções do logger (injetáveis nos testes). */
@@ -82,6 +86,16 @@ export class Logger implements LoggerLike {
 		this.tty = options.isTTY ?? Boolean(process.stdout.isTTY);
 	}
 
+	/** Loader/blocos só fazem sentido em terminal interativo. */
+	get interactive(): boolean {
+		return this.tty && !this.quiet;
+	}
+
+	/** Stream dos blocos de progresso. */
+	get stream(): NodeJS.WritableStream {
+		return this.out;
+	}
+
 	/** Só aparece em `--verbose`. */
 	debug(message: string): void {
 		if (!this.verbose || this.quiet) return;
@@ -164,6 +178,11 @@ export class Logger implements LoggerLike {
 
 /** Logger silencioso para testes/serviços. */
 export class SilentLogger implements LoggerLike {
+	readonly interactive = false;
+	readonly stream: NodeJS.WritableStream = {
+		write: () => true,
+	} as unknown as NodeJS.WritableStream;
+
 	debug(_message?: string): void {}
 	info(_message?: string): void {}
 	success(_message?: string): void {}