@payconductor/houndsman 0.4.0 → 0.6.0

package/src/core/jev/jev-client.ts

@@ -5,13 +5,14 @@
  * pipeline de review sem dependências novas de SDK e com tipagem explícita
  * do request/response (`./jev-types`).
  *
- * Config: apenas `TYPESAFE_API_KEY` (via env). Origem e modelo da API são
- * fixos no código (constantes abaixo).
+ * Config: apenas `HOUNDSMAN_TYPE_SAFE_API_KEY` (via `core/env.ts`). Origem e
+ * modelo da API são fixos no código (constantes abaixo).
  *
  * Erros são normalizados em `JevError` — o chamador decide falhar-aberto.
  */
 
 import axios, { type AxiosInstance, isAxiosError } from "axios";
+import { ENV_NAMES, env } from "../env";
 import type { JevEvaluateRequest, JevEvaluateResponse } from "./jev-types";
 
 const DEFAULT_BASE_URL = "https://api.typesafe.ai";
@@ -19,7 +20,7 @@ const DEFAULT_MODEL = "jev-latest";
 const DEFAULT_TIMEOUT_MS = 20_000;
 /** Timeout da verificação de credencial do `doctor` (mais curto que o de review). */
 const DEFAULT_PING_TIMEOUT_MS = 10_000;
-/** Caminho fixo do endpoinft System One. */
+/** Caminho fixo do endpoint System One. */
 const JEV_PATH = "/v1/systemone";
 
 export class JevError extends Error {
@@ -39,7 +40,7 @@ export type JevCredentialCheck =
 	| { ok: false; kind: "invalid" | "unreachable"; detail: string };
 
 export type JevClientOptions = {
-	/** Chave de API (default: `process.env.TYPESAFE_API_KEY`). */
+	/** Chave de API (default: `env.typeSafeApiKey`). */
 	apiKey?: string;
 	/** Sobreposição da origem da API (default: constante `DEFAULT_BASE_URL`). */
 	baseURL?: string;
@@ -57,7 +58,7 @@ export class JevClient {
 	readonly model: string;
 
 	constructor(options: JevClientOptions = {}) {
-		this.apiKey = options.apiKey ?? process.env.TYPESAFE_API_KEY;
+		this.apiKey = options.apiKey ?? env.typeSafeApiKey;
 		this.model = options.model ?? DEFAULT_MODEL;
 		const baseURL = options.baseURL ?? DEFAULT_BASE_URL;
 		this.http =
@@ -79,7 +80,7 @@ export class JevClient {
 	 */
 	async evaluate(request: JevEvaluateRequest): Promise<JevEvaluateResponse> {
 		if (!this.apiKey) {
-			throw new JevError("TYPESAFE_API_KEY não configurada.");
+			throw new JevError(`${ENV_NAMES.typeSafeApiKey} não configurada.`);
 		}
 		try {
 			const { data } = await this.http.post<JevEvaluateResponse>(
@@ -105,7 +106,7 @@ export class JevClient {
 			return {
 				ok: false,
 				kind: "unreachable",
-				detail: "TYPESAFE_API_KEY não configurada.",
+				detail: `${ENV_NAMES.typeSafeApiKey} não configurada.`,
 			};
 		}
 		const request: JevEvaluateRequest = {

package/src/core/jev/jev-verify.ts

@@ -7,6 +7,7 @@
  * decide. O custo é uma chamada por arquivo ambíguo, não uma revisão completa.
  */
 
+import { ENV_NAMES } from "../env";
 import { diffPatch, readFileAt } from "../git-revision";
 import type { JevClient } from "./jev-client";
 import type { JevAnswer, JevQuestion } from "./jev-types";
@@ -104,7 +105,7 @@ export class JevVerifier {
 				confidence,
 				checked: 0,
 				skipped: cases.length,
-				reason: "TYPESAFE_API_KEY não configurada",
+				reason: `${ENV_NAMES.typeSafeApiKey} não configurada`,
 			};
 		}
 

package/src/core/logging/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Instância pronta do logger (`import { logger } from "../core/logging"`).
+ *
+ * Infraestrutura compartilhada por `cli`, `harness` e `server`. Módulos de
+ * negócio do core não escrevem saída.
+ */
+
+import { Logger } from "./logger";
+
+export const logger = new Logger();
+
+export type {
+	LoggerLike,
+	LoggerOptions,
+	SpinnerLike,
+} from "./logger";
+export { Logger, SilentLogger } from "./logger";

package/src/core/logging/logger.ts

@@ -0,0 +1,187 @@
+/**
+ * Logger único do CLI/harness (infraestrutura).
+ *
+ * Usa `chalk` para cor e `ora` para spinner, mas cai para texto puro quando a
+ * saída não é TTY, `NO_COLOR` está definido, `TERM=dumb` ou `--quiet`.
+ *
+ * Não é usado por módulos de negócio do `core/`: só `cli/`, `harness/` e
+ * `server/` escrevem saída.
+ */
+
+import { Chalk, type ChalkInstance } from "chalk";
+import ora, { type Ora } from "ora";
+import { env } from "../env";
+
+/** Spinner mínimo (compatível com `ora` e com o modo silencioso). */
+export type SpinnerLike = {
+	start(): SpinnerLike;
+	stop(): void;
+	succeed(text?: string): void;
+	fail(text?: string): void;
+	warn(text?: string): void;
+	readonly text: string;
+};
+
+/** Superfície de log usada por comandos e reporter. */
+export interface LoggerLike {
+	debug(message: string): void;
+	info(message: string): void;
+	success(message: string): void;
+	warn(message: string): void;
+	error(message: string): void;
+	step(message: string): void;
+	bullet(message: string): void;
+	table(rows: readonly (readonly string[])[]): void;
+	progress(message: string): void;
+	spinner(text: string): SpinnerLike | null;
+	withSpinner<T>(
+		text: string,
+		run: (spinner: SpinnerLike | null) => Promise<T>,
+	): Promise<T>;
+}
+
+/** Opções do logger (injetáveis nos testes). */
+export type LoggerOptions = {
+	/** `auto` (default), `true` (força cor) ou `false` (plain). */
+	color?: boolean | "auto";
+	quiet?: boolean;
+	verbose?: boolean;
+	stdout?: NodeJS.WritableStream;
+	stderr?: NodeJS.WritableStream;
+	/** Sobrescreve a detecção de TTY (testes). */
+	isTTY?: boolean;
+};
+
+/** `true` quando cores devem ser desabilitadas pelo ambiente. */
+function colorsDisabled(): boolean {
+	return Boolean(env.noColor) || env.term === "dumb";
+}
+
+/** Cria a instância de chalk respeitando as opções. */
+function createChalk(color: LoggerOptions["color"]): ChalkInstance {
+	if (color === false || colorsDisabled()) return new Chalk({ level: 0 });
+	if (color === true) return new Chalk({ level: 1 });
+	return new Chalk();
+}
+
+/** Logger com saída injetável. */
+export class Logger implements LoggerLike {
+	private readonly out: NodeJS.WritableStream;
+	private readonly err: NodeJS.WritableStream;
+	private readonly chalk: ChalkInstance;
+	private readonly quiet: boolean;
+	private readonly verbose: boolean;
+	private readonly tty: boolean;
+
+	constructor(options: LoggerOptions = {}) {
+		this.out = options.stdout ?? process.stdout;
+		this.err = options.stderr ?? process.stderr;
+		this.chalk = createChalk(options.color ?? "auto");
+		this.quiet = options.quiet === true;
+		this.verbose = options.verbose === true;
+		this.tty = options.isTTY ?? Boolean(process.stdout.isTTY);
+	}
+
+	/** Só aparece em `--verbose`. */
+	debug(message: string): void {
+		if (!this.verbose || this.quiet) return;
+		this.out.write(`${this.chalk.dim(`[debug] ${message}`)}\n`);
+	}
+
+	info(message: string): void {
+		if (this.quiet) return;
+		this.out.write(`${message}\n`);
+	}
+
+	success(message: string): void {
+		if (this.quiet) return;
+		this.out.write(`${this.chalk.green("✔")} ${message}\n`);
+	}
+
+	warn(message: string): void {
+		if (this.quiet) return;
+		this.err.write(`${this.chalk.yellow("⚠")} ${message}\n`);
+	}
+
+	error(message: string): void {
+		this.err.write(`${this.chalk.red("✖")} ${message}\n`);
+	}
+
+	step(message: string): void {
+		if (this.quiet) return;
+		this.out.write(`${this.chalk.cyan("→")} ${message}\n`);
+	}
+
+	bullet(message: string): void {
+		if (this.quiet) return;
+		this.out.write(`  ${this.chalk.dim("•")} ${message}\n`);
+	}
+
+	/** Tabela simples com colunas alinhadas (sem ANSI nos valores). */
+	table(rows: readonly (readonly string[])[]): void {
+		if (this.quiet || rows.length === 0) return;
+		const width = Math.max(...rows.map((row) => row.length));
+		const sizes = Array.from({ length: width }, (_, column) =>
+			Math.max(...rows.map((row) => (row[column] ?? "").length)),
+		);
+		rows.forEach((row, index) => {
+			const line = row
+				.map((cell, column) => (cell ?? "").padEnd(sizes[column] ?? 0))
+				.join("  ")
+				.trimEnd();
+			this.out.write(`${index === 0 ? this.chalk.bold(line) : line}\n`);
+		});
+	}
+
+	/** Progresso textual (usado pelo `AgentReporter`). */
+	progress(message: string): void {
+		this.info(message);
+	}
+
+	/** Spinner habilitado apenas em TTY e fora do modo quiet. */
+	spinner(text: string): SpinnerLike | null {
+		if (!this.tty || this.quiet) return null;
+		return ora({ text, stream: this.out as NodeJS.WriteStream, isEnabled: true });
+	}
+
+	/** Executa `run` com um spinner opcional; sempre para o spinner. */
+	async withSpinner<T>(
+		text: string,
+		run: (spinner: SpinnerLike | null) => Promise<T>,
+	): Promise<T> {
+		const spinner = this.spinner(text);
+		spinner?.start();
+		try {
+			const result = await run(spinner);
+			spinner?.succeed();
+			return result;
+		} catch (error) {
+			spinner?.fail();
+			throw error;
+		}
+	}
+}
+
+/** Logger silencioso para testes/serviços. */
+export class SilentLogger implements LoggerLike {
+	debug(_message?: string): void {}
+	info(_message?: string): void {}
+	success(_message?: string): void {}
+	warn(_message?: string): void {}
+	error(_message?: string): void {}
+	step(_message?: string): void {}
+	bullet(_message?: string): void {}
+	table(_rows?: readonly (readonly string[])[]): void {}
+	progress(_message?: string): void {}
+	spinner(_text?: string): SpinnerLike | null {
+		return null;
+	}
+	async withSpinner<T>(
+		_text: string,
+		run: (spinner: SpinnerLike | null) => Promise<T>,
+	): Promise<T> {
+		return run(null);
+	}
+}
+
+export type { Ora };