@archznn/xavva 2.6.0 → 2.8.0

package/src/errors/ErrorHandler.ts

@@ -0,0 +1,249 @@
+/**
+ * ErrorHandler centralizado
+ * Trata todos os erros do aplicativo de forma uniforme
+ */
+
+import { 
+    XavvaError, 
+    isOperationalError, 
+    getExitCode,
+    NetworkError,
+    FileSystemError,
+    BuildError,
+    TomcatError,
+    ConfigError
+} from "./XavvaError";
+import { Logger } from "../utils/ui";
+import { ProcessManager } from "../utils/processManager";
+
+export interface ErrorReport {
+    error: Error;
+    code: string;
+    exitCode: number;
+    isOperational: boolean;
+    context?: Record<string, unknown>;
+    timestamp: Date;
+}
+
+export class ErrorHandler {
+    private static instance: ErrorHandler;
+    private errorHistory: ErrorReport[] = [];
+    private maxHistorySize = 10;
+    private isShuttingDown = false;
+
+    private constructor() {}
+
+    static getInstance(): ErrorHandler {
+        if (!ErrorHandler.instance) {
+            ErrorHandler.instance = new ErrorHandler();
+        }
+        return ErrorHandler.instance;
+    }
+
+    /**
+     * Trata qualquer erro de forma apropriada
+     */
+    async handle(error: unknown, context?: Record<string, unknown>): Promise<void> {
+        if (this.isShuttingDown) return;
+
+        const normalizedError = this.normalizeError(error);
+        const report = this.createReport(normalizedError, context);
+        
+        // Adiciona ao histórico
+        this.addToHistory(report);
+
+        // Log apropriado baseado no tipo de erro
+        if (normalizedError instanceof XavvaError) {
+            this.handleXavvaError(normalizedError);
+        } else {
+            this.handleUnexpectedError(normalizedError);
+        }
+
+        // Se não for erro operacional, mostra stack trace em verbose
+        if (!report.isOperational) {
+            Logger.debug("Stack trace:");
+            Logger.debug(normalizedError.stack || "N/A");
+        }
+
+        // Shutdown com código apropriado
+        const processManager = ProcessManager.getInstance();
+        await processManager.shutdown(report.exitCode);
+    }
+
+    /**
+     * Trata erro sem fazer shutdown (para operações que podem continuar)
+     */
+    handleGraceful(error: unknown, context?: Record<string, unknown>): ErrorReport {
+        const normalizedError = this.normalizeError(error);
+        const report = this.createReport(normalizedError, context);
+        
+        this.addToHistory(report);
+
+        if (normalizedError instanceof XavvaError) {
+            this.logXavvaError(normalizedError, false);
+        } else {
+            Logger.warn(`Erro inesperado: ${normalizedError.message}`);
+        }
+
+        return report;
+    }
+
+    /**
+     * Normaliza qualquer valor para Error
+     */
+    private normalizeError(error: unknown): Error {
+        if (error instanceof Error) {
+            return error;
+        }
+        
+        if (typeof error === "string") {
+            return new Error(error);
+        }
+        
+        if (error && typeof error === "object" && "message" in error) {
+            return new Error(String((error as { message: unknown }).message));
+        }
+        
+        return new Error("Erro desconhecido");
+    }
+
+    /**
+     * Cria um relatório de erro estruturado
+     */
+    private createReport(error: Error, context?: Record<string, unknown>): ErrorReport {
+        return {
+            error,
+            code: error instanceof XavvaError ? error.code : "UNKNOWN_ERROR",
+            exitCode: getExitCode(error),
+            isOperational: isOperationalError(error),
+            context,
+            timestamp: new Date(),
+        };
+    }
+
+    /**
+     * Adiciona erro ao histórico (com limite)
+     */
+    private addToHistory(report: ErrorReport): void {
+        this.errorHistory.push(report);
+        if (this.errorHistory.length > this.maxHistorySize) {
+            this.errorHistory.shift();
+        }
+    }
+
+    /**
+     * Trata erros específicos do Xavva
+     */
+    private handleXavvaError(error: XavvaError): void {
+        this.logXavvaError(error, true);
+    }
+
+    /**
+     * Loga erro Xavva com formatação adequada
+     */
+    private logXavvaError(error: XavvaError, isFatal: boolean): void {
+        const logMethod = isFatal ? Logger.error : Logger.warn;
+        
+        // Cabeçalho do erro
+        logMethod.call(Logger, error.message);
+        
+        // Detalhes adicionais se houver
+        if (error instanceof NetworkError) {
+            Logger.info("Dica", "Verifique sua conexão de internet e tente novamente");
+        } else if (error instanceof FileSystemError) {
+            Logger.info("Dica", "Verifique as permissões do arquivo/diretório");
+        } else if (error instanceof BuildError) {
+            Logger.info("Dica", "Use --verbose para ver detalhes completos do build");
+        } else if (error instanceof TomcatError) {
+            Logger.info("Dica", "Verifique se o Tomcat está configurado corretamente");
+        } else if (error instanceof ConfigError) {
+            Logger.info("Dica", "Verifique seu arquivo xavva.json");
+        }
+
+        // Código do erro em debug
+        Logger.debug(`Código do erro: ${error.code} (exit ${error.exitCode})`);
+    }
+
+    /**
+     * Trata erros inesperados (bugs)
+     */
+    private handleUnexpectedError(error: Error): void {
+        Logger.error("Erro inesperado:");
+        Logger.error(error.message);
+        Logger.newline();
+        Logger.info("Isso parece ser um bug", "Por favor, reporte em github.com/leorsousa05/Xavva/issues");
+        
+        // Sempre mostra stack trace para erros inesperados
+        if (error.stack) {
+            Logger.newline();
+            Logger.dim("Stack trace:");
+            Logger.dim(error.stack.split("\n").slice(1, 5).join("\n"));
+        }
+    }
+
+    /**
+     * Obtém histórico de erros
+     */
+    getErrorHistory(): ErrorReport[] {
+        return [...this.errorHistory];
+    }
+
+    /**
+     * Limpa histórico de erros
+     */
+    clearHistory(): void {
+        this.errorHistory = [];
+    }
+
+    /**
+     * Verifica se houve erros recentes de um tipo específico
+     */
+    hasRecentError(code: string, withinMs: number = 60000): boolean {
+        const now = Date.now();
+        return this.errorHistory.some(
+            report => 
+                report.code === code && 
+                (now - report.timestamp.getTime()) < withinMs
+        );
+    }
+
+    /**
+     * Wrapper para executar função com tratamento de erro automático
+     */
+    async wrap<T>(
+        fn: () => Promise<T>, 
+        context?: Record<string, unknown>
+    ): Promise<T | undefined> {
+        try {
+            return await fn();
+        } catch (error) {
+            await this.handle(error, context);
+            return undefined;
+        }
+    }
+
+    /**
+     * Wrapper para executar função sem shutdown em caso de erro
+     */
+    wrapGraceful<T>(
+        fn: () => T, 
+        fallback: T,
+        context?: Record<string, unknown>
+    ): T {
+        try {
+            return fn();
+        } catch (error) {
+            this.handleGraceful(error, context);
+            return fallback;
+        }
+    }
+}
+
+// Helper para uso rápido
+export function handleError(error: unknown, context?: Record<string, unknown>): Promise<void> {
+    return ErrorHandler.getInstance().handle(error, context);
+}
+
+export function handleGraceful(error: unknown, context?: Record<string, unknown>): ErrorReport {
+    return ErrorHandler.getInstance().handleGraceful(error, context);
+}

package/src/errors/XavvaError.ts

@@ -0,0 +1,273 @@
+/**
+ * Hierarquia de erros específicos do Xavva
+ * Permite tratamento granular de diferentes tipos de falhas
+ */
+
+export class XavvaError extends Error {
+    public readonly code: string;
+    public readonly exitCode: number;
+    public readonly isOperational: boolean;
+
+    constructor(
+        message: string,
+        code: string = "XAVVA_ERROR",
+        exitCode: number = 1,
+        isOperational: boolean = true
+    ) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.exitCode = exitCode;
+        this.isOperational = isOperational;
+
+        // Mantém o stack trace correto
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+// ===== Erros de Build =====
+export class BuildError extends XavvaError {
+    constructor(message: string, details?: string) {
+        super(
+            details ? `${message}: ${details}` : message,
+            "BUILD_ERROR",
+            3,
+            true
+        );
+    }
+}
+
+export class MavenError extends BuildError {
+    constructor(message: string, exitCode?: number) {
+        super(
+            `Maven build failed${exitCode ? ` (exit ${exitCode})` : ""}: ${message}`,
+        );
+        this.code = "MAVEN_ERROR";
+    }
+}
+
+export class GradleError extends BuildError {
+    constructor(message: string, exitCode?: number) {
+        super(
+            `Gradle build failed${exitCode ? ` (exit ${exitCode})` : ""}: ${message}`,
+        );
+        this.code = "GRADLE_ERROR";
+    }
+}
+
+// ===== Erros de Deploy =====
+export class DeployError extends XavvaError {
+    constructor(message: string, details?: string) {
+        super(
+            details ? `${message}: ${details}` : message,
+            "DEPLOY_ERROR",
+            4,
+            true
+        );
+    }
+}
+
+export class ArtifactNotFoundError extends DeployError {
+    constructor(buildDir: string) {
+        super(
+            `Nenhum artefato (.war ou pasta exploded) encontrado em ${buildDir}`,
+            "Certifique-se de que o build foi executado com sucesso"
+        );
+        this.code = "ARTIFACT_NOT_FOUND";
+    }
+}
+
+// ===== Erros de Tomcat =====
+export class TomcatError extends XavvaError {
+    constructor(message: string, details?: string) {
+        super(
+            details ? `${message}: ${details}` : message,
+            "TOMCAT_ERROR",
+            5,
+            true
+        );
+    }
+}
+
+export class TomcatNotFoundError extends TomcatError {
+    constructor(path: string) {
+        super(
+            `Tomcat não encontrado em ${path}`,
+            "Defina TOMCAT_HOME, CATALINA_HOME ou use --path"
+        );
+        this.code = "TOMCAT_NOT_FOUND";
+    }
+}
+
+export class PortInUseError extends TomcatError {
+    constructor(port: number) {
+        super(
+            `Porta ${port} já está em uso`,
+            "Pare o processo que está usando a porta ou especifique outra com --port"
+        );
+        this.code = "PORT_IN_USE";
+    }
+}
+
+export class EmbeddedTomcatError extends TomcatError {
+    constructor(message: string) {
+        super(
+            `Falha no Tomcat embutido: ${message}`,
+            "Tente instalar manualmente ou use outra versão com --tomcat-version"
+        );
+        this.code = "EMBEDDED_TOMCAT_ERROR";
+    }
+}
+
+// ===== Erros de Configuração =====
+export class ConfigError extends XavvaError {
+    constructor(message: string, details?: string) {
+        super(
+            details ? `${message}: ${details}` : message,
+            "CONFIG_ERROR",
+            2,
+            true
+        );
+    }
+}
+
+export class InvalidConfigError extends ConfigError {
+    constructor(field: string, value: string, expected?: string) {
+        super(
+            `Configuração inválida: ${field} = '${value}'`,
+            expected || "Verifique sua configuração"
+        );
+        this.code = "INVALID_CONFIG";
+    }
+}
+
+export class MissingConfigError extends ConfigError {
+    constructor(field: string) {
+        super(
+            `Configuração obrigatória ausente: ${field}`,
+            `Defina ${field} no xavva.json ou via linha de comando`
+        );
+        this.code = "MISSING_CONFIG";
+    }
+}
+
+// ===== Erros de Projeto =====
+export class ProjectError extends XavvaError {
+    constructor(message: string, details?: string) {
+        super(
+            details ? `${message}: ${details}` : message,
+            "PROJECT_ERROR",
+            6,
+            true
+        );
+    }
+}
+
+export class BuildToolNotFoundError extends ProjectError {
+    constructor() {
+        super(
+            "Não foi possível detectar a ferramenta de build",
+            "Certifique-se de estar no diretório raiz do projeto (pom.xml ou build.gradle)"
+        );
+        this.code = "BUILD_TOOL_NOT_FOUND";
+    }
+}
+
+export class JavaNotFoundError extends ProjectError {
+    constructor() {
+        super(
+            "Java não encontrado",
+            "Defina JAVA_HOME ou certifique-se de que 'java' está no PATH"
+        );
+        this.code = "JAVA_NOT_FOUND";
+    }
+}
+
+// ===== Erros de Audit/Security =====
+export class AuditError extends XavvaError {
+    constructor(message: string) {
+        super(
+            `Erro na auditoria: ${message}`,
+            "AUDIT_ERROR",
+            7,
+            true
+        );
+    }
+}
+
+export class NetworkError extends XavvaError {
+    public readonly url: string;
+    public readonly originalError?: Error;
+    
+    constructor(url: string, originalError?: Error) {
+        super(
+            `Falha na conexão com ${url}${originalError ? `: ${originalError.message}` : ""}`,
+            "NETWORK_ERROR",
+            8,
+            true
+        );
+        this.url = url;
+        this.originalError = originalError;
+    }
+}
+
+// ===== Erros de File System =====
+export class FileSystemError extends XavvaError {
+    constructor(message: string, path?: string) {
+        super(
+            path ? `${message}: ${path}` : message,
+            "FILESYSTEM_ERROR",
+            9,
+            true
+        );
+    }
+}
+
+export class FileNotFoundError extends FileSystemError {
+    constructor(path: string) {
+        super("Arquivo não encontrado", path);
+        this.code = "FILE_NOT_FOUND";
+    }
+}
+
+export class PermissionError extends FileSystemError {
+    constructor(path: string) {
+        super("Permissão negada", path);
+        this.code = "PERMISSION_DENIED";
+    }
+}
+
+// ===== Erros de Comando =====
+export class CommandError extends XavvaError {
+    constructor(command: string, message: string) {
+        super(
+            `Erro no comando '${command}': ${message}`,
+            "COMMAND_ERROR",
+            10,
+            true
+        );
+    }
+}
+
+export class UnknownCommandError extends CommandError {
+    constructor(command: string) {
+        super(command, "Comando desconhecido");
+        this.code = "UNKNOWN_COMMAND";
+    }
+}
+
+// Helper para identificar se é erro operacional (vs programação)
+export function isOperationalError(error: Error): boolean {
+    if (error instanceof XavvaError) {
+        return error.isOperational;
+    }
+    return false;
+}
+
+// Helper para obter exit code de qualquer erro
+export function getExitCode(error: Error): number {
+    if (error instanceof XavvaError) {
+        return error.exitCode;
+    }
+    return 1; // Erro genérico
+}