@payconductor/houndsman 0.12.0 → 0.13.0

package/src/index.ts

@@ -80,13 +80,18 @@ export type {
 	HoundsmanConcurrency,
 	HoundsmanConfig,
 	HoundsmanConfigInput,
+	HoundsmanHunt,
 	HoundsmanStorage,
 } from "./core/config";
 export {
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
 	DEFAULT_AST_MAX_FILE_BYTES,
 	DEFAULT_AST_MAX_IMPACT_FILES,
+	DEFAULT_HUNT_CONCURRENCY,
+	DEFAULT_HUNT_RETRIES,
+	DEFAULT_HUNT_TIMEOUT_MS,
 	DEFAULT_JEV_CONCURRENCY,
+	DEFAULT_MAKI_VERSION,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 	defineHoundsmanConfig,
 	resolveJevConcurrency,
@@ -181,6 +186,50 @@ export {
 	syncState,
 } from "./core/findings-state";
 export type { GitResult, GitRunner } from "./core/git-runner";
+export type {
+	HuntEvent,
+	HuntReport,
+	HuntRunnerOptions,
+	HuntTotals,
+	HuntWatchdogResult,
+	InstallMakiOptions,
+	InstallMakiResult,
+	MakiBinary,
+	MakiBinarySource,
+	MakiInstallManifest,
+	MakiModel,
+	MakiProcessRunner,
+	MakiRunMetrics,
+	MakiRunRequest,
+	MakiRunResult,
+	MakiUsage,
+} from "./core/hunt";
+export {
+	extractJsonObject,
+	HuntRunner,
+	houndsmanKeyEnvFor,
+	installMaki,
+	MAKI_API_KEY_ENV,
+	MAKI_DISALLOWED_TOOLS,
+	makiArgs,
+	makiCurrentFile,
+	makiInstallDir,
+	makiSourceLabel,
+	makiToolsRoot,
+	mapPool,
+	metricsFrom,
+	parseMakiOutput,
+	probeMakiVersion,
+	readMakiInstall,
+	renderHuntPrompt,
+	renderRetrySuffix,
+	requireMakiBinary,
+	requireMakiModel,
+	resolveMakiBinary,
+	resolveMakiModel,
+	SpawnMakiRunner,
+	uninstallMaki,
+} from "./core/hunt";
 export {
 	CORE_DIR,
 	CORE_SKILL_DIR,

package/src/skill/README.md

@@ -14,6 +14,16 @@ Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `t
 | `fix` | Correção dos findings marcados como `execute`. |
 | `verify` | Confere se as violações foram resolvidas, sem re-revisar a PR. |
 
+## Dois caminhos para o `hunt`
+
+| Caminho | Quem usa | Requisitos |
+|---|---|---|
+| Skill `/houndsman hunt` | agente externo (Copilot/Claude/etc.) | nenhum |
+| CLI `houndsman hunt` | operador/CI, sem agente | `houndsman hunt install` |
+
+Os dois usam o mesmo `prepare`/`finalize`, o mesmo staging e o mesmo schema de findings.
+O CLI só substitui o despacho manual dos subagentes por processos maki headless.
+
 ## Terminologia
 
 - **houndsman** — o orquestrador/treinador (CLI + motor).
@@ -53,6 +63,8 @@ Um único skill (`/houndsman`), quatro capabilities (detalhadas em `hunt.md`, `t
 | `houndsman` | Passo 1 — preparar (gera os briefs) |
 | `houndsman --pr <n>` | Passo 1 em worktree dedicado (revisões paralelas) |
 | `houndsman --finalize` | Passo 3 — gerar o relatório (`--pr <n>` reusa o worktree) |
+| `houndsman hunt [--pr <n>]` | Harness local opcional (maki): prepare → watchdogs → finalize |
+| `houndsman hunt install` | Baixa o maki fixado para `<HOUNDSMAN_HOME>/tools/maki` |
 | `houndsman worktree <ação>` | `list`/`add`/`remove`/`prune`/`path` dos worktrees |
 | `houndsman watchdog <id>` | Contexto de um watchdog (`--json`, `--rules`) |
 | `houndsman findings <sub>` | Triagem/correção dos findings (`list`/`set`/`done`/`sync`/`batch`/`verify`/...) |

package/src/skill/SETUP.md

@@ -76,6 +76,25 @@ Depois do setup, invoque o skill `/houndsman` no seu harness:
 | `/houndsman train` | Adicionar/ajustar/remover regras dos watchdogs. |
 | `/houndsman fix` | Corrigir os findings marcados como `execute`. |
 
+## Harness local (opcional) — `houndsman hunt`
+
+Quem não quer rodar a skill dentro de um agente externo pode executar a revisão 100% pelo
+CLI. O maki é instalado sob demanda, fora do projeto, e reaproveita a credencial já existente:
+
+```bash
+houndsman hunt install      # baixa o maki fixado (sha256) em <HOUNDSMAN_HOME>/tools/maki
+houndsman hunt doctor       # binário, modelo e credencial (opcional; não falha sem maki)
+houndsman hunt --pr 456     # prepare → maki (um processo por brief) → finalize
+```
+
+- A skill `/houndsman hunt` continua sendo o caminho canônico e não depende do maki.
+- `HOUNDSMAN_MAKI_PATH` aponta um binário já instalado; `HOUNDSMAN_MAKI_VERSION` troca a
+  versão baixada.
+- Config opcional em `houndsman.config.ts`: `hunt: { model?, concurrency?, timeoutMs?,
+  retries?, binaryPath?, enabled? }`.
+- Se algum watchdog falhar, o comando **não finaliza** (preserva o staging); use
+  `--allow-partial` para finalizar com findings vazios registrados em `skipped`.
+
 ## Contrato do motor (`HoundsmanConfig`)
 
 Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.ts` (gerado):
@@ -91,6 +110,7 @@ Definido em `src/core/config.ts` (pacote) e espelhado em `.houndsman/core/types.
 | `budgets` | **Opcional** — teto de arquivos por brief (`maxFilesPerBrief`, default `40`); o excedente vira "fora do orçamento" (registrar em `skipped`). |
 | `concurrency` | **Opcional** — chamadas Jev simultâneas (`jev`, default `5`). |
 | `ast` | **Opcional** — AST determinístico para TS/JS (`enabled`, `maxFileBytes`, `maxImpactFiles`, `languages`, `aliases`). Default: ligado; falhas são fail-open. |
+| `hunt` | **Opcional** — harness local (`model`, `concurrency`, `timeoutMs`, `retries`, `binaryPath`, `enabled`). Só afeta `houndsman hunt`; a skill não depende. |
 
 > O motor **não contém** ids, paths ou regras do projeto — tudo chega por `HoundsmanConfig`,
 > carregado em runtime a partir de `houndsman.config.ts` (ou `--config <path>`).
@@ -103,7 +123,7 @@ houndsman/
 └── src/
     ├── index.ts              # API pública (defineWatchdog, defineHoundsmanConfig, tipos)
     ├── cli/index.ts          # CLI único — bin `houndsman`
-    ├── core/                 # bibliotecas genéricas (config, orchestrator, brief, jev/, …)
+    ├── core/                 # bibliotecas genéricas (config, orchestrator, brief, jev/, hunt/, …)
     ├── skill/*.md            # assets markdown (embarcados no pacote)
     └── tests/                # suíte da lib (project-agnóstica, "project fake")
 ```

package/src/skill/SKILL.md

@@ -38,6 +38,10 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 Um argumento extra é o alvo da capability. Escolha a capability pelo que o usuário quer,
 leia o documento correspondente em `.houndsman/core/skill/<capability>.md` e siga-o.
 
+> **Harness local (opcional):** para rodar sem agente externo, o operador pode instalar o
+> maki (`houndsman hunt install`) e usar `houndsman hunt --pr 456`. Isso não muda esta
+> skill: se você é o agente, siga o fluxo normal e não rode `houndsman hunt`.
+
 ### Alvo da revisão (PR × branch)
 
 Interprete o alvo em linguagem natural **antes** de rodar o CLI:

package/src/skill/hunt.md

@@ -8,6 +8,20 @@ Invocação: `/houndsman` (default), `/houndsman hunt` ou `/houndsman hunt pr 45
 O motor é o CLI **`houndsman`**; as regras do projeto ficam em `houndsman.config.ts` +
 `.houndsman/`.
 
+## Dois modos de execução
+
+| Modo | Quem usa | Requisitos | Quem despacha os briefs |
+|---|---|---|---|
+| **Skill `/houndsman hunt`** (padrão) | agente externo (Copilot/Claude/etc.) | nenhum | o próprio agente, via subagentes |
+| **CLI `houndsman hunt`** | operador/CI, sem agente | `houndsman hunt install` uma vez | o houndsman, via maki headless |
+
+Os dois modos produzem os mesmos artefatos, usam o mesmo staging e o mesmo ciclo
+`prepare → findings → finalize`. Nada muda no fluxo abaixo para quem usa a skill.
+
+> **Se você é o agente executando esta skill, NÃO rode `houndsman hunt`.** Ele instala/usa o
+> maki e despacha outro harness. Siga os passos 0–3 normalmente; o comando CLI é para quem
+> quer rodar tudo no terminal.
+
 ## Alvo da revisão
 
 Traduza o pedido do usuário para flags **antes** de começar:
@@ -306,6 +320,28 @@ completo) · `--no-jev` · `--no-ast` · `--fail-on-blocking` (com `--finalize`)
 
 ---
 
+## Harness local (opcional, fora da skill)
+
+Para rodar a revisão inteira pelo terminal, sem agente externo, o mesmo `hunt` existe como
+comando. A instalação é única e fica fora do projeto:
+
+```bash
+houndsman hunt install            # baixa o maki fixado em <HOUNDSMAN_HOME>/tools/maki
+houndsman hunt doctor             # diagnóstico (não falha se o maki não existir)
+houndsman hunt --pr 456           # prepare → um processo maki por brief → finalize
+houndsman hunt --pr 456 --allow-partial  # finaliza mesmo se algum watchdog falhar
+```
+
+- Reaproveita a credencial já configurada (`HOUNDSMAN_DEEP_SEEK_API_KEY` → `DEEPSEEK_API_KEY`)
+  e o modelo de `ai.model` (default `deepseek/deepseek-v4-pro`).
+- O watchdog **não recebe escrita**: o maki devolve o JSON na resposta final e o houndsman
+  valida e grava `findings/<watchdog>.json`. `bash`, rede e edição ficam negados.
+- Sem maki instalado, nada muda para a skill: `setup`, `doctor` e `/houndsman hunt` seguem
+  funcionando.
+- O relatório do harness fica em `hunt-report.json` (sessões, custo e tokens por watchdog).
+
+---
+
 ## Anti-padrões
 
 - ❌ Enviar git diff completo para qualquer watchdog

package/src/tests/__snapshots__/baseline.test.ts.snap

@@ -238,6 +238,10 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 Um argumento extra é o alvo da capability. Escolha a capability pelo que o usuário quer,
 leia o documento correspondente em \`.houndsman/core/skill/<capability>.md\` e siga-o.
 
+> **Harness local (opcional):** para rodar sem agente externo, o operador pode instalar o
+> maki (\`houndsman hunt install\`) e usar \`houndsman hunt --pr 456\`. Isso não muda esta
+> skill: se você é o agente, siga o fluxo normal e não rode \`houndsman hunt\`.
+
 ### Alvo da revisão (PR × branch)
 
 Interprete o alvo em linguagem natural **antes** de rodar o CLI:
@@ -323,6 +327,10 @@ especialista por domínio · **finding** = um achado da revisão · **Jev** = pr
 Um argumento extra é o alvo da capability. Escolha a capability pelo que o usuário quer,
 leia o documento correspondente em \`.houndsman/core/skill/<capability>.md\` e siga-o.
 
+> **Harness local (opcional):** para rodar sem agente externo, o operador pode instalar o
+> maki (\`houndsman hunt install\`) e usar \`houndsman hunt --pr 456\`. Isso não muda esta
+> skill: se você é o agente, siga o fluxo normal e não rode \`houndsman hunt\`.
+
 ### Alvo da revisão (PR × branch)
 
 Interprete o alvo em linguagem natural **antes** de rodar o CLI:
@@ -516,6 +524,16 @@ export type HoundsmanAi = {
 	watchdogs?: Record<string, HoundsmanAiWatchdog>;
 };
 
+/** Harness local da capability \`hunt\` (\`houndsman hunt\`) — opcional. */
+export type HoundsmanHunt = {
+	enabled?: boolean;
+	model?: string;
+	concurrency?: number;
+	timeoutMs?: number;
+	retries?: number;
+	binaryPath?: string;
+};
+
 /** Contrato de configuração do motor. */
 export type HoundsmanConfig<TId extends string = string> = {
 	projectName: string;
@@ -529,6 +547,7 @@ export type HoundsmanConfig<TId extends string = string> = {
 	concurrency?: HoundsmanConcurrency;
 	ast?: HoundsmanAst;
 	ai?: HoundsmanAi;
+	hunt?: HoundsmanHunt;
 };
 
 /** Helper de autoria (identidade) — apenas tipagem. */
@@ -654,11 +673,11 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/README.md",
-    "sha256": "9aadf51b48c7f304",
+    "sha256": "2ecf43f34a624011",
   },
   {
     "file": ".houndsman/core/skill/SETUP.md",
-    "sha256": "5e5335870f493aba",
+    "sha256": "5720c48ede6c84ea",
   },
   {
     "file": ".houndsman/core/skill/example-review.md",
@@ -670,7 +689,7 @@ exports[`baseline — camada gerada setup gera os mesmos arquivos e conteúdos 3
   },
   {
     "file": ".houndsman/core/skill/hunt.md",
-    "sha256": "dfaec1a665d7ee65",
+    "sha256": "d31198580d894427",
   },
   {
     "file": ".houndsman/core/skill/train.md",

package/src/tests/ai-core.test.ts

@@ -6,7 +6,11 @@ import { describe, expect, test } from "bun:test";
 import type { LanguageModel } from "ai";
 import { z } from "zod";
 import { AiClient, AiUsageBudget, AiUsageRecorder } from "../core/ai";
-import { buildGenerateTextArgs } from "../core/ai/ai-sdk-model-provider";
+import {
+	buildGenerateTextArgs,
+	formatSdkWarning,
+	formatSdkWarnings,
+} from "../core/ai/ai-sdk-model-provider";
 import { temperatureApplies } from "../core/ai/provider-capabilities";
 import { defineHoundsmanConfig } from "../core/config";
 import { DEFAULT_AI_MODEL } from "../core/defaults";
@@ -153,6 +157,39 @@ describe("temperature e providerOptions", () => {
 	});
 });
 
+describe("avisos do AI SDK", () => {
+	test("normaliza os avisos do provider em texto", () => {
+		expect(
+			formatSdkWarning({
+				type: "compatibility",
+				feature: "responseFormat JSON schema",
+				details: "JSON response schema is injected into the system message.",
+			}),
+		).toBe(
+			"compatibility: responseFormat JSON schema — JSON response schema is injected into the system message.",
+		);
+		expect(
+			formatSdkWarning({
+				type: "unsupported",
+				feature: "user message part type: image",
+			}),
+		).toBe("unsupported: user message part type: image");
+		expect(
+			formatSdkWarning({
+				type: "deprecated",
+				setting: "temperature",
+				message: "gone",
+			}),
+		).toBe("deprecated: temperature — gone");
+		expect(formatSdkWarning(null)).toBe("aviso");
+		expect(formatSdkWarnings(undefined)).toEqual([]);
+	});
+
+	test("logger default do SDK fica silencioso após carregar o adapter", () => {
+		expect(typeof globalThis.AI_SDK_LOG_WARNINGS).toBe("function");
+	});
+});
+
 describe("AiUsageBudget / AiUsageRecorder", () => {
 	test("acumula uso e bloqueia no teto", () => {
 		const budget = new AiUsageBudget({ maxCalls: 2 });

package/src/tests/cli.test.ts

@@ -192,6 +192,7 @@ describe("cli smoke — imports dinâmicos", () => {
 			const result = runCli(project.cwd, ["doctor", "--no-ping"]);
 			expect(result.code).toBe(0);
 			expect(result.stdout).toContain("Validando");
+			expect(result.stdout).toContain("maki (hunt local)");
 		} finally {
 			project.cleanup();
 		}

package/src/tests/hunt-cli.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Smoke test do comando `hunt` (harness local).
+ *
+ * Não executa o maki real: cobre help, doctor e os erros acionáveis antes do
+ * prepare. A skill `/houndsman hunt` continua coberta pelos testes da camada.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const CLI = join(import.meta.dir, "..", "cli", "index.ts");
+
+const CONFIG = (hunt = "") => `export default {
+	projectName: "Hunt Smoke",
+	storage: { provider: "sqlite", path: "./houndsman.db" },
+	watchdogs: {
+		alpha: {
+			id: "alpha",
+			name: "Alpha",
+			description: "Watchdog de smoke.",
+			scope: "src/**",
+			classify: [{ value: "^src/" }],
+			rules: [{ severity: "attention", text: "Evitar any." }],
+			contextFiles: [],
+		},
+	},
+	exclusions: [],
+	docMappings: [],
+	${hunt}
+};
+`;
+
+type Project = { cwd: string; home: string; cleanup: () => void };
+
+function makeProject(hunt = ""): Project {
+	const cwd = mkdtempSync(join(tmpdir(), "houndsman-hunt-cli-"));
+	const home = mkdtempSync(join(tmpdir(), "houndsman-hunt-home-"));
+	writeFileSync(join(cwd, "houndsman.config.ts"), CONFIG(hunt));
+	return {
+		cwd,
+		home,
+		cleanup: () => {
+			rmSync(cwd, { recursive: true, force: true });
+			rmSync(home, { recursive: true, force: true });
+		},
+	};
+}
+
+type CliResult = { code: number; stdout: string; stderr: string };
+
+function runCli(
+	cwd: string,
+	args: string[],
+	env: Record<string, string> = {},
+): CliResult {
+	const proc = Bun.spawnSync(["bun", CLI, ...args], {
+		cwd,
+		env: { ...process.env, NO_COLOR: "1", ...env },
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	return {
+		code: proc.exitCode ?? -1,
+		stdout: proc.stdout.toString(),
+		stderr: proc.stderr.toString(),
+	};
+}
+
+describe("hunt — help e diagnóstico", () => {
+	test("--help distingue a skill do comando CLI", () => {
+		const result = runCli(process.cwd(), ["hunt", "--help"]);
+		expect(result.code).toBe(0);
+		expect(result.stdout).toContain("/houndsman hunt");
+		expect(result.stdout).toContain("houndsman hunt install");
+		expect(result.stdout).toContain("--allow-partial");
+	});
+
+	test("doctor não falha sem maki e trata o harness como opcional", () => {
+		const project = makeProject();
+		try {
+			const result = runCli(project.cwd, ["hunt", "doctor"], {
+				HOUNDSMAN_HOME: project.home,
+				HOUNDSMAN_MAKI_PATH: join(project.cwd, "maki-inexistente"),
+			});
+			expect(result.code).toBe(0);
+			expect(result.stdout).toContain("Harness local");
+			expect(result.stdout).toContain("modelo:");
+			expect(result.stdout).toContain("harness:");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("doctor funciona sem projeto configurado (diagnóstico global)", () => {
+		const cwd = mkdtempSync(join(tmpdir(), "houndsman-hunt-nocfg-"));
+		const home = mkdtempSync(join(tmpdir(), "houndsman-hunt-home-"));
+		try {
+			const result = runCli(cwd, ["hunt", "doctor"], {
+				HOUNDSMAN_HOME: home,
+				HOUNDSMAN_MAKI_PATH: join(cwd, "maki-inexistente"),
+			});
+			expect(result.code).toBe(0);
+			expect(result.stdout).toContain("Harness local");
+		} finally {
+			rmSync(cwd, { recursive: true, force: true });
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("hunt — erros antes do prepare", () => {
+	test("sem binário, orienta a instalar (e não toca na review)", () => {
+		const project = makeProject();
+		try {
+			const result = runCli(project.cwd, ["hunt", "--branch", "main"], {
+				HOUNDSMAN_HOME: project.home,
+				HOUNDSMAN_MAKI_PATH: join(project.cwd, "maki-inexistente"),
+				HOUNDSMAN_DEEP_SEEK_API_KEY: "sk-test",
+			});
+			expect(result.code).toBe(1);
+			expect(result.stderr).toContain("hunt install");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("sem credencial, aponta a env correta", () => {
+		const project = makeProject();
+		try {
+			const env = { ...process.env };
+			delete env.HOUNDSMAN_DEEP_SEEK_API_KEY;
+			const proc = Bun.spawnSync(["bun", CLI, "hunt", "--branch", "main"], {
+				cwd: project.cwd,
+				env: {
+					...env,
+					NO_COLOR: "1",
+					HOUNDSMAN_HOME: project.home,
+					HOUNDSMAN_MAKI_PATH: join(project.cwd, "maki-inexistente"),
+				},
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			expect(proc.exitCode).toBe(1);
+			expect(proc.stderr.toString()).toContain("HOUNDSMAN_DEEP_SEEK_API_KEY");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("respeita hunt.enabled: false", () => {
+		const project = makeProject("hunt: { enabled: false },");
+		try {
+			const result = runCli(project.cwd, ["hunt"], {
+				HOUNDSMAN_HOME: project.home,
+				HOUNDSMAN_DEEP_SEEK_API_KEY: "sk-test",
+			});
+			expect(result.code).toBe(1);
+			expect(result.stderr).toContain("desligado");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("rejeita --finalize (o hunt já finaliza)", () => {
+		const project = makeProject();
+		try {
+			const result = runCli(project.cwd, ["hunt", "--finalize"], {
+				HOUNDSMAN_HOME: project.home,
+			});
+			expect(result.code).toBe(1);
+			expect(result.stderr).toContain("já finaliza");
+		} finally {
+			project.cleanup();
+		}
+	});
+
+	test("subcomando desconhecido mostra o help", () => {
+		const result = runCli(process.cwd(), ["hunt", "foo"]);
+		expect(result.code).toBe(1);
+		expect(result.stderr).toContain("desconhecido");
+		expect(result.stdout).toContain("houndsman hunt install");
+	});
+});

package/src/tests/hunt-install.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Instalação local do maki (sem rede).
+ *
+ * Valida a resolução de asset/versão/checksum e a instalação a partir de um
+ * arquivo local (`--from`), além do ponteiro gerenciado e do uninstall.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	installMaki,
+	makiCurrentFile,
+	makiInstallDir,
+	makiSourceLabel,
+	readMakiInstall,
+	resolveMakiBinary,
+	uninstallMaki,
+} from "../core/hunt/maki-install";
+import {
+	effectiveMakiVersion,
+	makiAssetFor,
+	makiBinaryName,
+	makiChecksumsUrl,
+	makiDownloadUrl,
+	parseChecksums,
+} from "../core/hunt/maki-release";
+
+const original = {
+	home: process.env.HOUNDSMAN_HOME,
+	makiPath: process.env.HOUNDSMAN_MAKI_PATH,
+	makiVersion: process.env.HOUNDSMAN_MAKI_VERSION,
+};
+const dirs: string[] = [];
+
+afterEach(() => {
+	restoreEnv("HOUNDSMAN_HOME", original.home);
+	restoreEnv("HOUNDSMAN_MAKI_PATH", original.makiPath);
+	restoreEnv("HOUNDSMAN_MAKI_VERSION", original.makiVersion);
+	for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function restoreEnv(name: string, value: string | undefined): void {
+	if (value === undefined) delete process.env[name];
+	else process.env[name] = value;
+}
+
+function tempDir(prefix: string): string {
+	const dir = mkdtempSync(join(tmpdir(), prefix));
+	dirs.push(dir);
+	return dir;
+}
+
+describe("maki-release", () => {
+	test("resolve asset por plataforma/arquitetura", () => {
+		expect(makiAssetFor("win32", "x64", "0.6.5")?.name).toBe(
+			"maki-v0.6.5-x86_64-pc-windows-msvc.zip",
+		);
+		expect(makiAssetFor("darwin", "arm64", "v0.6.5")?.name).toBe(
+			"maki-v0.6.5-aarch64-apple-darwin.tar.gz",
+		);
+		expect(makiAssetFor("linux", "x64", "0.6.5")?.name).toBe(
+			"maki-v0.6.5-x86_64-unknown-linux-musl.tar.gz",
+		);
+		expect(makiAssetFor("solaris", "x64", "0.6.5")).toBeNull();
+	});
+
+	test("versão normaliza v e aceita override por env", () => {
+		expect(effectiveMakiVersion("v1.2.3")).toBe("1.2.3");
+		process.env.HOUNDSMAN_MAKI_VERSION = "v2.0.0";
+		expect(effectiveMakiVersion()).toBe("2.0.0");
+		expect(() => effectiveMakiVersion("../../x")).toThrow("Versão do maki inválida");
+	});
+
+	test("URLs e parse de sha256sums", () => {
+		expect(makiDownloadUrl("0.6.5", "maki.tar.gz")).toContain(
+			"/releases/download/v0.6.5/maki.tar.gz",
+		);
+		expect(makiChecksumsUrl("0.6.5").endsWith("/v0.6.5/sha256sums.txt")).toBe(true);
+		const checksums = parseChecksums(
+			[
+				`${"a".repeat(64)}  maki-a.tar.gz`,
+				`${"b".repeat(64)} *maki-b.zip`,
+				"linha inválida",
+			].join("\n"),
+		);
+		expect(checksums.get("maki-a.tar.gz")).toBe("a".repeat(64));
+		expect(checksums.get("maki-b.zip")).toBe("b".repeat(64));
+	});
+});
+
+describe("resolução do binário", () => {
+	test("HOUNDSMAN_MAKI_PATH tem precedência", () => {
+		const root = tempDir("houndsman-maki-resolve-");
+		const binary = join(root, "maki-custom");
+		writeFileSync(binary, "fake");
+		process.env.HOUNDSMAN_MAKI_PATH = binary;
+		const resolved = resolveMakiBinary();
+		expect(resolved?.path).toBe(binary);
+		expect(resolved?.source).toBe("env");
+		expect(makiSourceLabel("env")).toBe("HOUNDSMAN_MAKI_PATH");
+	});
+});
+
+describe("installMaki (arquivo local)", () => {
+	const hasTar = Boolean(Bun.which("tar"));
+
+	test.skipIf(!hasTar)("extrai, grava o ponteiro e remove", async () => {
+		const home = tempDir("houndsman-maki-home-");
+		process.env.HOUNDSMAN_HOME = home;
+
+		const src = tempDir("houndsman-maki-src-");
+		const name = makiBinaryName();
+		mkdirSync(join(src, "nested"), { recursive: true });
+		writeFileSync(join(src, "nested", name), "#!/bin/sh\necho fake\n");
+		const archive = join(tempDir("houndsman-maki-archive-"), "maki.tar.gz");
+		const tar = Bun.spawnSync(["tar", "-czf", archive, "-C", src, "."], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		expect(tar.exitCode).toBe(0);
+
+		const first = await installMaki({ version: "9.9.9", from: archive });
+		expect(first.skipped).toBe(false);
+		expect(existsSync(first.path)).toBe(true);
+		expect(first.path).toBe(join(makiInstallDir("9.9.9"), name));
+		expect(readFileSync(first.path, "utf8")).toContain("echo fake");
+
+		const manifest = readMakiInstall();
+		expect(manifest?.version).toBe("9.9.9");
+		expect(manifest?.path).toBe(first.path);
+		expect(existsSync(makiCurrentFile())).toBe(true);
+
+		const resolved = resolveMakiBinary();
+		expect(resolved?.source).toBe("managed");
+		expect(resolved?.version).toBe("9.9.9");
+
+		const second = await installMaki({ version: "9.9.9", from: archive });
+		expect(second.skipped).toBe(true);
+
+		const removed = uninstallMaki();
+		expect(removed).toBe(join(home, "tools", "maki"));
+		expect(existsSync(join(home, "tools", "maki"))).toBe(false);
+	});
+});