@payconductor/houndsman 0.4.0 → 0.6.0

package/src/core/commands/status.ts

@@ -0,0 +1,63 @@
+/**
+ * Status da run (biblioteca) — leitura e heartbeat para a UI.
+ *
+ * `status ping` é o sinal de vida de uma skill em execução (revisão ou
+ * correção). O heartbeat é separado de `updatedAt`: triagem/sync atualizam o
+ * segundo, mas não fingem que existe uma execução em andamento.
+ */
+
+import { currentBranch } from "../pr-context";
+import { type RunStatus, touchRunStatus } from "../run-status";
+import type { RepoIdentity, ReviewRecord, StorageProvider } from "../storage/types";
+
+export type StatusResult = {
+	branch: string;
+	status: RunStatus | null;
+	startedAt?: string;
+	heartbeatAt?: string;
+	updatedAt: string;
+};
+
+function toResult(review: ReviewRecord): StatusResult {
+	return {
+		branch: review.branch,
+		status: review.status,
+		startedAt: review.startedAt,
+		heartbeatAt: review.heartbeatAt,
+		updatedAt: review.updatedAt,
+	};
+}
+
+/** Resolve a review da branch (explícita ou a atual do git). */
+function findReview(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+): ReviewRecord {
+	const target = branch ?? currentBranch();
+	const review = storage.findReview(repo.key, target);
+	if (!review) {
+		throw new Error(`Nenhuma revisão para '${target}'.`);
+	}
+	return review;
+}
+
+/** Lê o status atual da run. */
+export function readStatus(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+): StatusResult {
+	return toResult(findReview(storage, repo, branch));
+}
+
+/** Renova o heartbeat de uma execução ativa (`reviewing`/`fixing`). */
+export function pingStatus(
+	storage: StorageProvider,
+	repo: RepoIdentity,
+	branch?: string,
+	now?: string,
+): StatusResult {
+	const review = findReview(storage, repo, branch);
+	return toResult(touchRunStatus(storage, review.id, now));
+}

package/src/core/commands/update.ts

@@ -1,9 +1,11 @@
 /**
  * Subcomando `update` — sincroniza os arquivos **auto-gerados** da camada `.houndsman/`.
  *
- * Reescreve `core/types.ts`, `core/skill/*.md`, `.houndsman/.gitignore` e os
- * ponteiros de skill dos harnesses. Nunca toca nos arquivos do usuário
- * (`watchdogs/`, `doc-mappings.ts`, `exclusions.ts`, `houndsman.config.ts`).
+ * Reescreve `core/types.ts`, `core/skill/*.md`, `core/grammars/*.wasm`,
+ * `.houndsman/.gitignore` e os ponteiros de skill dos harnesses. Nunca toca nos
+ * arquivos do usuário (`watchdogs/`, `doc-mappings.ts`, `exclusions.ts`,
+ * `houndsman.config.ts`). As grammars do AST são sincronizadas aqui — o
+ * consumidor não precisa rodar nenhum comando extra.
  */
 
 import { createScaffoldContext, syncGeneratedFiles } from "./scaffold";

package/src/core/config.ts

@@ -6,11 +6,21 @@
  * (camada `houndsman/`) — único ponto de troca ao portar para outro repositório.
  */
 
+import type { AstLanguage } from "./ast/types";
 import { ProjectConfig } from "./project-config";
 import type { WatchdogDefinition } from "./types";
 
 export {
+	DEFAULT_AI_CONCURRENCY,
+	DEFAULT_AI_MAX_CALLS_PER_REVIEW,
+	DEFAULT_AI_MAX_OUTPUT_TOKENS,
+	DEFAULT_AI_MAX_STEPS,
+	DEFAULT_AI_MODEL,
+	DEFAULT_AI_PROVIDER,
+	DEFAULT_AI_TIMEOUT_MS,
 	DEFAULT_ALWAYS_INCLUDE_DOCS,
+	DEFAULT_AST_MAX_FILE_BYTES,
+	DEFAULT_AST_MAX_IMPACT_FILES,
 	DEFAULT_JEV_CONCURRENCY,
 	DEFAULT_MAX_FILES_PER_BRIEF,
 } from "./defaults";
@@ -21,12 +31,83 @@ export type HoundsmanBudgets = {
 	maxFilesPerBrief?: number;
 };
 
+/** Configuração do subsistema AST (determinístico, sem LLM). */
+export type HoundsmanAst = {
+	/**
+	 * Liga/desliga o AST (default: `true`). Com grammars ausentes ou ABI
+	 * incompatível, o motor segue sem AST (fail-open).
+	 */
+	enabled?: boolean;
+	/** Teto de bytes por arquivo (default: 512_000). */
+	maxFileBytes?: number;
+	/** Teto de arquivos candidatos na análise de impacto (default: 200). */
+	maxImpactFiles?: number;
+	/** Override de extensão → linguagem (`".vue": "typescript"`). */
+	languages?: Record<string, AstLanguage>;
+	/** Aliases de import (`"@/": "src/"`). */
+	aliases?: Record<string, string>;
+};
+
 /** Concorrência das fases paralelas internas. */
 export type HoundsmanConcurrency = {
 	/** Chamadas Jev simultâneas (default: 5). */
 	jev?: number;
 };
 
+/** Providers suportados pela camada de IA. */
+export type AiProviderKind = "deepseek" | "openai" | "anthropic";
+
+/** Features de IA do fluxo determinístico (todas fail-open). */
+export type HoundsmanAiFeatures = {
+	/** Resume o contexto da PR (`context-summary`) quando o subagente não gerou. */
+	context?: boolean;
+	/** Enriquece os briefs com um plano de revisão sugerido. */
+	brief?: boolean;
+	/** Classifica arquivos que nenhum watchdog casou. */
+	classification?: boolean;
+	/** Gera candidatos de pré-análise (substitui o Jev quando disponível). */
+	preAnalysis?: boolean;
+	/** Confirma/refuta findings ambíguos no `verify`. */
+	verify?: boolean;
+};
+
+/** Overrides de IA por watchdog. */
+export type HoundsmanAiWatchdog = {
+	model?: string;
+	maxSteps?: number;
+	maxOutputTokens?: number;
+};
+
+/** Configuração da camada de IA (genérica; o harness nativo também a consome). */
+export type HoundsmanAi = {
+	/** Liga a IA do fluxo normal (default: `true`; sem chave é fail-open). */
+	enabled?: boolean;
+	/** Provider de modelo (default: `deepseek`). */
+	provider?: AiProviderKind;
+	/** Modelo (default em `defaults.ts`). */
+	model?: string;
+	/** Base URL customizada do provider. */
+	baseURL?: string;
+	/** Chamadas simultâneas (default: 2). */
+	concurrency?: number;
+	/** Passos por agente (default: 12). */
+	maxSteps?: number;
+	/** Teto de tokens de saída por chamada. */
+	maxOutputTokens?: number;
+	/** Temperatura (default: 0). */
+	temperature?: number;
+	/** Timeout por chamada em ms (default: 120_000). */
+	timeoutMs?: number;
+	/** Teto de chamadas por review (default: 40). */
+	maxCallsPerReview?: number;
+	/** Teto de tokens por review. */
+	maxTokensPerReview?: number;
+	/** Features do fluxo normal. */
+	features?: HoundsmanAiFeatures;
+	/** Overrides por watchdog. */
+	watchdogs?: Record<string, HoundsmanAiWatchdog>;
+};
+
 /** Backend de persistência (reviews, findings e artefatos). */
 export type HoundsmanStorage = {
 	/**
@@ -68,6 +149,10 @@ export type HoundsmanConfig<TId extends string = string> = {
 	budgets?: HoundsmanBudgets;
 	/** Concorrência das fases paralelas internas. */
 	concurrency?: HoundsmanConcurrency;
+	/** AST determinístico (classificação estrutural, brief e impacto). */
+	ast?: HoundsmanAst;
+	/** Camada de IA (briefs, contexto, classificação e o harness nativo). */
+	ai?: HoundsmanAi;
 };
 
 /** Entrada de `defineHoundsmanConfig` — `watchdogIds` é derivado, não informado. */

package/src/core/defaults.ts

@@ -18,3 +18,30 @@ export const DEFAULT_MAX_FILES_PER_BRIEF = 40;
 
 /** Concorrência default das chamadas simultâneas ao Jev. */
 export const DEFAULT_JEV_CONCURRENCY = 5;
+
+/** Teto default de bytes por arquivo no AST (evita bundles/minificados). */
+export const DEFAULT_AST_MAX_FILE_BYTES = 512_000;
+
+/** Teto default de arquivos candidatos na análise de impacto. */
+export const DEFAULT_AST_MAX_IMPACT_FILES = 200;
+
+/** Provider default da camada de IA (DeepSeek). */
+export const DEFAULT_AI_PROVIDER = "deepseek" as const;
+
+/** Modelo default da camada de IA. */
+export const DEFAULT_AI_MODEL = "deepseek-v4.1-flash";
+
+/** Concorrência default das chamadas de IA. */
+export const DEFAULT_AI_CONCURRENCY = 2;
+
+/** Passos default por agente (loop de tools + saída). */
+export const DEFAULT_AI_MAX_STEPS = 12;
+
+/** Timeout default de uma chamada de modelo (ms). */
+export const DEFAULT_AI_TIMEOUT_MS = 120_000;
+
+/** Teto default de chamadas de IA por review. */
+export const DEFAULT_AI_MAX_CALLS_PER_REVIEW = 40;
+
+/** Teto default de tokens de saída por chamada. */
+export const DEFAULT_AI_MAX_OUTPUT_TOKENS = 4096;

package/src/core/domain/watchdog.ts

@@ -6,6 +6,7 @@
  * render do brief) sem alterar o contrato do consumidor.
  */
 
+import type { AstFacts } from "../ast/types";
 import { renderBrief } from "../brief";
 import {
 	type ClassifyRule,
@@ -18,16 +19,51 @@ import {
 /** Tipo assumido quando `type` é omitido. */
 const DEFAULT_CLASSIFY_TYPE: NonNullable<ClassifyRule["type"]> = "filename";
 
+/** `true` se algum valor do conjunto casa o padrão. */
+function matchesAny(values: readonly string[], pattern: RegExp): boolean {
+	return values.some((value) => pattern.test(value));
+}
+
 /** `true` se o arquivo casa a entrada de classificação. */
 export function matchesClassifyRule(
 	filePath: string,
 	rule: ClassifyRule,
 	content: string | undefined,
+	facts?: AstFacts,
 ): boolean {
-	if ((rule.type ?? DEFAULT_CLASSIFY_TYPE) === "content") {
-		return content !== undefined && new RegExp(rule.value).test(content);
+	const pattern = new RegExp(rule.value);
+	switch (rule.type ?? DEFAULT_CLASSIFY_TYPE) {
+		case "content":
+			return content !== undefined && pattern.test(content);
+		case "symbol":
+			return (
+				facts !== undefined &&
+				matchesAny(
+					facts.symbols.flatMap((symbol) => [symbol.name, symbol.kind]),
+					pattern,
+				)
+			);
+		case "import":
+			return (
+				facts !== undefined &&
+				matchesAny(
+					facts.imports.flatMap((item) => [item.source, ...item.names]),
+					pattern,
+				)
+			);
+		case "export":
+			return (
+				facts !== undefined &&
+				matchesAny(
+					facts.exports.map((item) => item.name),
+					pattern,
+				)
+			);
+		case "decorator":
+			return facts !== undefined && matchesAny(facts.decorators, pattern);
+		default:
+			return pattern.test(filePath);
 	}
-	return new RegExp(rule.value).test(filePath);
 }
 
 /** Contexto "essencial" do watchdog — SEM regras (docs/UI/inspeção). */
@@ -71,8 +107,10 @@ export class Watchdog {
 	}
 
 	/** `true` se o arquivo é deste domínio. */
-	matches(filePath: string, content?: string): boolean {
-		return this.classify.some((rule) => matchesClassifyRule(filePath, rule, content));
+	matches(filePath: string, content?: string, facts?: AstFacts): boolean {
+		return this.classify.some((rule) =>
+			matchesClassifyRule(filePath, rule, content, facts),
+		);
 	}
 
 	/** Regras ordenadas por severidade (mais grave primeiro). */

package/src/core/engine/houndsman-engine.ts

@@ -6,6 +6,8 @@
  * de instanciar/importar tudo diretamente.
  */
 
+import { AiClient } from "../ai/ai-client";
+import { AstService } from "../ast/service";
 import type { HoundsmanConfig } from "../config";
 import type { ReviewOptions } from "../orchestrator";
 import { ProjectConfig } from "../project-config";
@@ -26,6 +28,8 @@ export type EngineDeps = {
 	fixBatch?: FixBatchBuilder;
 	storage?: StorageProvider;
 	repo?: RepoIdentity;
+	ast?: AstService;
+	ai?: AiClient;
 };
 
 /** Composition root do motor. */
@@ -37,6 +41,8 @@ export class HoundsmanEngine {
 	readonly fixBatch: FixBatchBuilder;
 	readonly storage: StorageProvider;
 	readonly repo: RepoIdentity;
+	readonly ast: AstService;
+	readonly ai: AiClient;
 
 	constructor(raw: HoundsmanConfig, deps: EngineDeps = {}) {
 		this.project = new ProjectConfig(raw);
@@ -46,6 +52,8 @@ export class HoundsmanEngine {
 		this.fixBatch = deps.fixBatch ?? new FixBatchBuilder();
 		this.storage = deps.storage ?? createStorage(raw);
 		this.repo = deps.repo ?? resolveRepoIdentity(this.git);
+		this.ast = deps.ast ?? new AstService(raw, this.git);
+		this.ai = deps.ai ?? new AiClient({ project: this.project });
 	}
 
 	/** Configuração crua (contrato do consumidor). */
@@ -55,7 +63,14 @@ export class HoundsmanEngine {
 
 	/** Abre uma sessão de revisão (prepare/finalize). */
 	session(options: ReviewOptions): ReviewSession {
-		return ReviewSession.from(this.config, options, this.storage, this.repo);
+		return ReviewSession.from(
+			this.config,
+			options,
+			this.storage,
+			this.repo,
+			this.ast,
+			this.ai,
+		);
 	}
 
 	/** Libera o provider (fecha o SQLite e faz checkpoint do WAL). */

package/src/core/engine/review-scope.ts

@@ -5,11 +5,14 @@
  * carrega os findings de arquivos inalterados (carry-over).
  */
 
+import type { AstService } from "../ast/service";
+import type { AstAnalysis, AstFacts } from "../ast/types";
 import type { HoundsmanConfig } from "../config";
 import { churnToRecord, collectDiff, type DiffSource } from "../diff-source";
-import type { ClassificationResult } from "../file-classifier";
+import { type ClassificationResult, parseEntries } from "../file-classifier";
 import type { FindingsStateFile } from "../findings-state";
 import { collectDiffSince, diffEntries, isAncestor } from "../git-revision";
+import { runGit, tryGit } from "../git-runner";
 import type { MergedFinding } from "../report-builder";
 import { FileClassifier } from "../services/file-classifier";
 import { buildCarryover } from "./carryover";
@@ -34,42 +37,80 @@ export type RunClassification = ClassificationResult & {
 	carryover?: MergedFinding[];
 };
 
-/** Resultado da resolução de escopo. */
-export type ReviewScope = {
-	classification: RunClassification;
-	diff: DiffSource;
-	reviewedFrom?: string;
-};
+/** Resultado da resolução de escopo: revisar ou nada a fazer. */
+export type ReviewScope =
+	| {
+			/** O `HEAD` é o mesmo commit já revisado — não há o que re-revisar. */
+			kind: "noop";
+			headSha: string;
+			/** Commit já coberto pelo review anterior. */
+			reviewedFrom: string;
+	  }
+	| {
+			kind: "review";
+			classification: RunClassification;
+			diff: DiffSource;
+			reviewedFrom?: string;
+			/** Fatos/delta por arquivo alterado (quando o AST está habilitado). */
+			ast?: Map<string, AstAnalysis>;
+	  };
 
 /** Decide entre review completo e incremental. */
 export class ReviewScopeResolver {
 	private readonly options: ScopeOptions;
 	private readonly classifier: FileClassifier;
+	private readonly ast?: AstService;
 
-	constructor(options: ScopeOptions, config: HoundsmanConfig) {
+	constructor(options: ScopeOptions, config: HoundsmanConfig, ast?: AstService) {
 		this.options = options;
 		this.classifier = new FileClassifier(config);
+		this.ast = ast;
 	}
 
 	/**
+	 * No-op quando o `HEAD` é exatamente o commit já revisado (sem
+	 * `--full`/`--clean`): re-revisar a PR inteira seria desperdício, e o
+	 * relatório anterior continua válido.
+	 *
 	 * Incremental só quando há um `reviewed.headSha` anterior, o `HEAD` atual o
 	 * sucede (sem rebase) e não veio `--full`/`--clean`.
 	 */
-	resolve(previous: FindingsStateFile | null, headSha: string): ReviewScope {
+	async resolve(
+		previous: FindingsStateFile | null,
+		headSha: string,
+	): Promise<ReviewScope> {
 		const prevSha = previous?.reviewed?.headSha;
+
+		if (!this.options.full && !this.options.clean && prevSha === headSha) {
+			return { kind: "noop", headSha, reviewedFrom: headSha };
+		}
+
 		if (
 			this.options.full ||
 			this.options.clean ||
 			!prevSha ||
-			prevSha === headSha ||
 			!isAncestor(prevSha, headSha)
 		) {
 			const diff = collectDiff(this.options.base, this.options.head);
+			const entries = parseEntries(
+				runGit([
+					"diff",
+					`${this.options.base}...${this.options.head}`,
+					"--name-status",
+				]),
+			);
+			const baseRef =
+				mergeBase(this.options.base, this.options.head) ?? this.options.base;
+			const ast = this.ast
+				? await this.ast.analyze(entries, diff, baseRef)
+				: undefined;
 			return {
+				kind: "review",
 				diff,
+				ast,
 				classification: {
 					...this.classifier
-						.classifyRange(this.options.base, this.options.head, diff)
+						.classify(entries, churnToRecord(diff.churn), factsOf(ast))
 						.toJSON(),
 					headSha,
 					mode: "full",
@@ -81,8 +122,11 @@ export class ReviewScopeResolver {
 		const diff = collectDiffSince(prevSha, headSha);
 		const entries = diffEntries(range);
 		const changedPaths = new Set(entries.map((entry) => entry.path));
+		const ast = this.ast ? await this.ast.analyze(entries, diff, prevSha) : undefined;
 		const classification: RunClassification = {
-			...this.classifier.classify(entries, churnToRecord(diff.churn)).toJSON(),
+			...this.classifier
+				.classify(entries, churnToRecord(diff.churn), factsOf(ast))
+				.toJSON(),
 			base: prevSha,
 			head: this.options.head,
 			headSha,
@@ -90,6 +134,26 @@ export class ReviewScopeResolver {
 			reviewedFrom: prevSha,
 			carryover: buildCarryover(previous, changedPaths),
 		};
-		return { classification, diff, reviewedFrom: prevSha };
+		return { kind: "review", classification, diff, reviewedFrom: prevSha, ast };
 	}
 }
+
+/** Fatos apenas dos arquivos presentes (deletados não classificam). */
+function factsOf(
+	analyses: ReadonlyMap<string, AstAnalysis> | undefined,
+): ReadonlyMap<string, AstFacts> | undefined {
+	if (!analyses) return undefined;
+	const facts = new Map<string, AstFacts>();
+	for (const [path, analysis] of analyses) {
+		if (!analysis.deleted) facts.set(path, analysis.facts);
+	}
+	return facts;
+}
+
+/** SHA do merge-base entre base e head (best effort). */
+function mergeBase(base: string, head: string): string | null {
+	const result = tryGit(["merge-base", base, head]);
+	if (!result.ok) return null;
+	const sha = result.stdout.trim();
+	return sha.length > 0 ? sha : null;
+}

package/src/core/engine/review-session.ts

@@ -4,6 +4,8 @@
  * É o ponto de entrada do `prepare`/`finalize` para o CLI e para o engine.
  */
 
+import type { AiClient } from "../ai/ai-client";
+import type { AstService } from "../ast/service";
 import type { HoundsmanConfig } from "../config";
 import {
 	type FinalizeResult,
@@ -24,6 +26,8 @@ export class ReviewSession {
 	readonly options: ReviewOptions;
 	readonly branch: string;
 	readonly context: ReviewContext;
+	private readonly ast?: AstService;
+	private readonly ai?: AiClient;
 
 	constructor(
 		config: HoundsmanConfig,
@@ -31,10 +35,14 @@ export class ReviewSession {
 		branch: string,
 		storage: StorageProvider,
 		repo: RepoIdentity,
+		ast?: AstService,
+		ai?: AiClient,
 	) {
 		this.config = config;
 		this.options = options;
 		this.branch = branch;
+		this.ast = ast;
+		this.ai = ai;
 		const review = options.finalize
 			? storage.findReview(repo.key, branch)
 			: storage.getOrCreateReview({
@@ -58,13 +66,30 @@ export class ReviewSession {
 		options: ReviewOptions,
 		storage: StorageProvider,
 		repo: RepoIdentity,
+		ast?: AstService,
+		ai?: AiClient,
 	): ReviewSession {
-		return new ReviewSession(config, options, resolveBranch(options), storage, repo);
+		return new ReviewSession(
+			config,
+			options,
+			resolveBranch(options),
+			storage,
+			repo,
+			ast,
+			ai,
+		);
 	}
 
 	/** Passo 1 — preparar. */
 	prepare(): Promise<PrepareResult> {
-		return prepare(this.options, this.branch, this.config, this.context);
+		return prepare(
+			this.options,
+			this.branch,
+			this.config,
+			this.context,
+			this.ast,
+			this.ai,
+		);
 	}
 
 	/** Passo 3 — finalizar. */

package/src/core/env.ts

@@ -0,0 +1,101 @@
+/**
+ * Variáveis de ambiente do houndsman (fonte única).
+ *
+ * O Bun carrega `.env` do diretório atual automaticamente; o motor lê tudo
+ * daqui em vez de espalhar `process.env.*` pelo código. Chaves ausentes ou
+ * vazias viram `undefined` — o chamador decide se o recurso é opcional.
+ */
+
+/**
+ * Nomes canônicos das variáveis.
+ *
+ * Toda chave de integração do houndsman usa o prefixo `HOUNDSMAN_` — evita
+ * colisão com envs do projeto consumidor. Apenas variáveis nativas do SO/CI
+ * (`LOCALAPPDATA`, `XDG_DATA_HOME`, `NO_COLOR`, `TERM`, `CI`) mantêm o nome
+ * global, porque são convenções do ambiente.
+ */
+export const ENV_NAMES = {
+	typeSafeApiKey: "HOUNDSMAN_TYPE_SAFE_API_KEY",
+	deepSeekApiKey: "HOUNDSMAN_DEEP_SEEK_API_KEY",
+	openAiApiKey: "HOUNDSMAN_OPENAI_API_KEY",
+	anthropicApiKey: "HOUNDSMAN_ANTHROPIC_API_KEY",
+	home: "HOUNDSMAN_HOME",
+	localAppData: "LOCALAPPDATA",
+	xdgDataHome: "XDG_DATA_HOME",
+	noColor: "NO_COLOR",
+	term: "TERM",
+	ci: "CI",
+} as const;
+
+/** Snapshot tipado do ambiente (sem expor segredos). */
+export type HoundsmanEnv = {
+	typeSafeApiKey?: string;
+	deepSeekApiKey?: string;
+	openAiApiKey?: string;
+	anthropicApiKey?: string;
+	home?: string;
+	localAppData?: string;
+	xdgDataHome?: string;
+	noColor?: string;
+	term?: string;
+	ci?: string;
+};
+
+/** Lê uma variável, apara espaços e trata vazio como ausente. */
+function read(name: string): string | undefined {
+	const value = process.env[name]?.trim();
+	return value && value.length > 0 ? value : undefined;
+}
+
+/** Snapshot do ambiente no momento da chamada. */
+export function readEnv(): HoundsmanEnv {
+	return {
+		typeSafeApiKey: read(ENV_NAMES.typeSafeApiKey),
+		deepSeekApiKey: read(ENV_NAMES.deepSeekApiKey),
+		openAiApiKey: read(ENV_NAMES.openAiApiKey),
+		anthropicApiKey: read(ENV_NAMES.anthropicApiKey),
+		home: read(ENV_NAMES.home),
+		localAppData: read(ENV_NAMES.localAppData),
+		xdgDataHome: read(ENV_NAMES.xdgDataHome),
+		noColor: read(ENV_NAMES.noColor),
+		term: read(ENV_NAMES.term),
+		ci: read(ENV_NAMES.ci),
+	};
+}
+
+/**
+ * Acesso sob demanda. Getter (em vez de constante congelada) mantém testes e
+ * processos que alteram o ambiente em runtime funcionando.
+ */
+export const env = {
+	get typeSafeApiKey(): string | undefined {
+		return read(ENV_NAMES.typeSafeApiKey);
+	},
+	get deepSeekApiKey(): string | undefined {
+		return read(ENV_NAMES.deepSeekApiKey);
+	},
+	get openAiApiKey(): string | undefined {
+		return read(ENV_NAMES.openAiApiKey);
+	},
+	get anthropicApiKey(): string | undefined {
+		return read(ENV_NAMES.anthropicApiKey);
+	},
+	get home(): string | undefined {
+		return read(ENV_NAMES.home);
+	},
+	get localAppData(): string | undefined {
+		return read(ENV_NAMES.localAppData);
+	},
+	get xdgDataHome(): string | undefined {
+		return read(ENV_NAMES.xdgDataHome);
+	},
+	get noColor(): string | undefined {
+		return read(ENV_NAMES.noColor);
+	},
+	get term(): string | undefined {
+		return read(ENV_NAMES.term);
+	},
+	get ci(): string | undefined {
+		return read(ENV_NAMES.ci);
+	},
+} as const;