@payconductor/houndsman 0.11.0 → 0.13.0

package/src/core/hunt/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Fachada do harness local (`core/hunt`).
+ *
+ * A skill `/houndsman hunt` não importa nada daqui: este módulo é exclusivo do
+ * caminho CLI (`houndsman hunt`), que usa o maki para executar os briefs.
+ */
+
+export type {
+	HuntEvent,
+	HuntReport,
+	HuntRunnerOptions,
+	HuntTotals,
+	HuntWatchdogResult,
+} from "./hunt-runner";
+export { HuntRunner } from "./hunt-runner";
+export type {
+	InstallMakiOptions,
+	InstallMakiResult,
+	MakiBinary,
+	MakiBinarySource,
+	MakiInstallManifest,
+} from "./maki-install";
+export {
+	installMaki,
+	makiCurrentFile,
+	makiInstallDir,
+	makiSourceLabel,
+	makiToolsRoot,
+	probeMakiVersion,
+	readMakiInstall,
+	requireMakiBinary,
+	resolveMakiBinary,
+	uninstallMaki,
+} from "./maki-install";
+export type { MakiModel } from "./maki-model";
+export {
+	houndsmanKeyEnvFor,
+	MAKI_API_KEY_ENV,
+	requireMakiModel,
+	resolveMakiModel,
+} from "./maki-model";
+export { renderHuntPrompt, renderRetrySuffix } from "./maki-prompt";
+export type {
+	MakiJsonOutput,
+	MakiProcessRunner,
+	MakiRunMetrics,
+	MakiRunRequest,
+	MakiRunResult,
+	MakiUsage,
+} from "./maki-runner";
+export {
+	extractJsonObject,
+	MAKI_DISALLOWED_TOOLS,
+	makiArgs,
+	metricsFrom,
+	parseMakiOutput,
+	SpawnMakiRunner,
+} from "./maki-runner";
+export { mapPool } from "./pool";

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

@@ -0,0 +1,331 @@
+/**
+ * Instalação e descoberta do binário do maki (harness local).
+ *
+ * O binário é opcional e fica fora do projeto: `<HOUNDSMAN_HOME>/tools/maki`.
+ * `houndsman hunt install` baixa o release fixado e verifica o sha256; o
+ * `houndsman update`/`setup` nunca toca nisso. A skill `/houndsman hunt`
+ * (harness externo) não usa este módulo.
+ */
+
+import { createHash } from "node:crypto";
+import {
+	chmodSync,
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { env } from "../env";
+import { displayPath } from "../paths";
+import { systemClock } from "../services/clock";
+import { houndsmanHome } from "../storage/paths";
+import {
+	checksumFor,
+	effectiveMakiVersion,
+	makiAssetFor,
+	makiBinaryName,
+	makiChecksumsUrl,
+	makiDownloadUrl,
+	normalizeMakiVersion,
+} from "./maki-release";
+
+/** Origem do binário resolvido. */
+export type MakiBinarySource = "env" | "config" | "managed" | "path";
+
+/** Binário do maki disponível para execução. */
+export type MakiBinary = {
+	path: string;
+	source: MakiBinarySource;
+	/** Versão conhecida (instalação gerenciada). */
+	version?: string;
+};
+
+/** Manifesto da instalação gerenciada (`current.json`). */
+export type MakiInstallManifest = {
+	version: string;
+	path: string;
+	asset?: string;
+	sha256?: string;
+	installedAt: string;
+};
+
+/** Raiz das versões gerenciadas do maki. */
+export function makiToolsRoot(): string {
+	return join(houndsmanHome(), "tools", "maki");
+}
+
+/** Diretório de uma versão instalada. */
+export function makiInstallDir(version: string): string {
+	return join(makiToolsRoot(), normalizeMakiVersion(version));
+}
+
+/** Caminho do ponteiro para a instalação ativa. */
+export function makiCurrentFile(): string {
+	return join(makiToolsRoot(), "current.json");
+}
+
+/** Lê o manifesto da instalação gerenciada (null se ausente/inválido). */
+export function readMakiInstall(): MakiInstallManifest | null {
+	const file = makiCurrentFile();
+	if (!existsSync(file)) return null;
+	try {
+		const parsed = JSON.parse(
+			readFileSync(file, "utf8"),
+		) as Partial<MakiInstallManifest>;
+		if (typeof parsed.version !== "string" || typeof parsed.path !== "string") {
+			return null;
+		}
+		return {
+			version: parsed.version,
+			path: parsed.path,
+			asset: parsed.asset,
+			sha256: parsed.sha256,
+			installedAt: parsed.installedAt ?? systemClock(),
+		};
+	} catch {
+		return null;
+	}
+}
+
+/** Grava o ponteiro da instalação ativa. */
+function writeInstallManifest(manifest: MakiInstallManifest): void {
+	const file = makiCurrentFile();
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+/**
+ * Resolve o binário: `HOUNDSMAN_MAKI_PATH` > `hunt.binaryPath` > instalação
+ * gerenciada > `maki` no PATH. Não valida existência (use `requireMakiBinary`).
+ */
+export function resolveMakiBinary(configPath?: string): MakiBinary | null {
+	const explicit = env.makiPath ?? configPath?.trim();
+	if (explicit && explicit.length > 0) {
+		return { path: resolve(explicit), source: env.makiPath ? "env" : "config" };
+	}
+	const managed = readMakiInstall();
+	if (managed)
+		return { path: managed.path, source: "managed", version: managed.version };
+	const which = Bun.which("maki");
+	if (which) return { path: which, source: "path" };
+	return null;
+}
+
+/** Rótulo legível da origem (diagnóstico). */
+export function makiSourceLabel(source: MakiBinarySource): string {
+	switch (source) {
+		case "env":
+			return "HOUNDSMAN_MAKI_PATH";
+		case "config":
+			return "hunt.binaryPath";
+		case "managed":
+			return "instalação gerenciada";
+		default:
+			return "PATH";
+	}
+}
+
+/** Resolve e exige um binário existente; lança erro acionável quando ausente. */
+export function requireMakiBinary(configPath?: string): MakiBinary {
+	const binary = resolveMakiBinary(configPath);
+	if (!binary) {
+		throw new Error(
+			"Capability `hunt` não instalada: rode `houndsman hunt install` (ou defina HOUNDSMAN_MAKI_PATH).",
+		);
+	}
+	if (!existsSync(binary.path)) {
+		throw new Error(
+			`Binário do maki não encontrado em ${displayPath(binary.path)} (${makiSourceLabel(binary.source)}). ` +
+				"Rode `houndsman hunt install --force` ou ajuste HOUNDSMAN_MAKI_PATH.",
+		);
+	}
+	return binary;
+}
+
+/** Lê a versão do binário (`maki --version`); `undefined` se indisponível. */
+export function probeMakiVersion(binaryPath: string): string | undefined {
+	try {
+		const result = Bun.spawnSync([binaryPath, "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		if (result.exitCode !== 0) return undefined;
+		const output = result.stdout.toString().trim();
+		return output.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/)?.[0];
+	} catch {
+		return undefined;
+	}
+}
+
+/** Opções de instalação. */
+export type InstallMakiOptions = {
+	/** Versão alvo (`vX.Y.Z` ou `X.Y.Z`). */
+	version?: string;
+	/** Reinstala mesmo se o binário já existir. */
+	force?: boolean;
+	/** Arquivo local (`.tar.gz`/`.zip`) para ambientes offline. */
+	from?: string;
+	/** Progresso textual (CLI). */
+	log?: (message: string) => void;
+	/** `fetch` injetável (testes). */
+	fetchImpl?: typeof fetch;
+};
+
+/** Resultado da instalação. */
+export type InstallMakiResult = {
+	version: string;
+	path: string;
+	skipped: boolean;
+};
+
+/** Baixa (ou extrai) o maki para `<HOUNDSMAN_HOME>/tools/maki/<versão>`. */
+export async function installMaki(
+	options: InstallMakiOptions = {},
+): Promise<InstallMakiResult> {
+	const version = effectiveMakiVersion(options.version);
+	const binaryName = makiBinaryName();
+	const target = join(makiInstallDir(version), binaryName);
+	const log = options.log ?? (() => {});
+
+	if (existsSync(target) && !options.force) {
+		writeInstallManifest({ version, path: target, installedAt: systemClock() });
+		return { version, path: target, skipped: true };
+	}
+
+	const asset = makiAssetFor(process.platform, process.arch, version);
+	if (!asset) {
+		throw new Error(
+			`Sem release do maki para ${process.platform}/${process.arch}. ` +
+				"Instale manualmente (https://github.com/tontinton/maki/releases) e defina HOUNDSMAN_MAKI_PATH.",
+		);
+	}
+
+	const temp = mkdtempSync(join(tmpdir(), "houndsman-maki-"));
+	try {
+		let archivePath: string;
+		let checksum: string | undefined;
+
+		if (options.from) {
+			archivePath = resolve(options.from);
+			if (!existsSync(archivePath)) {
+				throw new Error(
+					`Arquivo do maki não encontrado: ${displayPath(archivePath)}.`,
+				);
+			}
+			log(`Extraindo ${displayPath(archivePath)}...`);
+		} else {
+			const fetchImpl = options.fetchImpl ?? fetch;
+			const url = makiDownloadUrl(version, asset.name);
+			log(`Baixando maki v${version} (${asset.name})...`);
+			const response = await fetchImpl(url);
+			if (!response.ok) {
+				throw new Error(
+					`Falha ao baixar o maki (HTTP ${response.status}): ${url}`,
+				);
+			}
+			const bytes = new Uint8Array(await response.arrayBuffer());
+
+			const checksumsResponse = await fetchImpl(makiChecksumsUrl(version));
+			if (checksumsResponse.ok) {
+				const expected = checksumFor(await checksumsResponse.text(), asset.name);
+				if (expected) {
+					const actual = createHash("sha256").update(bytes).digest("hex");
+					if (actual !== expected) {
+						throw new Error(
+							`Checksum inválido para ${asset.name} (esperado ${expected.slice(0, 12)}…, obtido ${actual.slice(0, 12)}…).`,
+						);
+					}
+					checksum = expected;
+					log("Checksum sha256 verificado.");
+				} else {
+					log(
+						"Aviso: release sem checksum para o asset; seguindo sem verificação.",
+					);
+				}
+			} else {
+				log(
+					`Aviso: não foi possível obter sha256sums.txt (HTTP ${checksumsResponse.status}).`,
+				);
+			}
+
+			archivePath = join(temp, asset.name);
+			writeFileSync(archivePath, bytes);
+		}
+
+		const extractDir = join(temp, "extract");
+		mkdirSync(extractDir, { recursive: true });
+		extractArchive(archivePath, extractDir);
+		const found = findFile(extractDir, binaryName);
+		if (!found) {
+			throw new Error(
+				`O pacote do maki não contém '${binaryName}'. Conteúdo inesperado em ${basename(archivePath)}.`,
+			);
+		}
+
+		const installDir = makiInstallDir(version);
+		mkdirSync(installDir, { recursive: true });
+		copyFileSync(found, target);
+		chmodSync(target, 0o755);
+		writeInstallManifest({
+			version,
+			path: target,
+			asset: asset.name,
+			sha256: checksum,
+			installedAt: systemClock(),
+		});
+		return { version, path: target, skipped: false };
+	} finally {
+		rmSync(temp, { recursive: true, force: true });
+	}
+}
+
+/** Remove todas as versões gerenciadas; devolve o caminho removido (ou null). */
+export function uninstallMaki(): string | null {
+	const root = makiToolsRoot();
+	if (!existsSync(root)) return null;
+	rmSync(root, { recursive: true, force: true });
+	return root;
+}
+
+/** Extrai `.tar.gz`/`.zip` (Windows usa o `tar.exe`/bsdtar do sistema). */
+function extractArchive(archive: string, directory: string): void {
+	try {
+		const result = Bun.spawnSync(["tar", "-xf", archive, "-C", directory], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		if (result.exitCode !== 0) {
+			const detail = result.stderr.toString().trim();
+			throw new Error(
+				`Falha ao extrair ${basename(archive)}${detail ? `: ${detail}` : "."}`,
+			);
+		}
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith("Falha ao extrair")) {
+			throw error;
+		}
+		throw new Error(
+			`Falha ao extrair ${basename(archive)}: 'tar' indisponível no sistema.`,
+		);
+	}
+}
+
+/** Procura um arquivo por nome, com profundidade limitada. */
+function findFile(root: string, name: string, depth = 0): string | null {
+	if (depth > 4) return null;
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		const full = join(root, entry.name);
+		if (entry.isFile() && entry.name === name) return full;
+		if (entry.isDirectory()) {
+			const found = findFile(full, name, depth + 1);
+			if (found) return found;
+		}
+	}
+	return null;
+}

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);
+}