@silasfmartins/testhub 1.0.0

package/dist/src/ssh/SSHActions.js

@@ -0,0 +1,790 @@
+import fs from 'fs';
+import { createRequire } from 'module';
+import SftpClient from 'ssh2-sftp-client';
+import { BaseError, IntegrationError, ValidationError, } from '../functions/errors/index.js';
+import { ExecutionTracker } from '../hubdocs/ExecutionTracker.js';
+import { StatementTracker } from '../hubdocs/StatementTracker.js';
+import { TestContext } from '../testContext/TestContext.js';
+import { UnifiedReportManager } from '../testContext/UnifiedReportManager.js';
+import { Logger } from '../utils/Logger.js';
+import { SSHClient } from './SSHClient.js';
+import path from 'node:path';
+const require = createRequire(import.meta.url);
+// 🤖 IMPORTAÇÃO CRÍTICA: Força inicialização do StatementTracker para projetos SSH
+import '../hubdocs/StatementTracker.js';
+// 🚫 REMOVIDO: import './SSHAutoDisconnect.js' - Causava erro em projetos não-SSH
+// ✅ Desconexão agora é feita no UnifiedTeardown automaticamente
+// 🚫 REMOVIDO: import { installDatabaseInterceptor } from '../utils/DatabaseInterceptor.js'
+/**
+ * Classe principal de ações SSH, inspirada no padrão Java Actions.
+ * Permite executar comandos, ler saídas, validar resultados e registrar logs/unificados.
+ */
+export class SSHActions {
+    /** Instância única de SSHClient para uso nas ações */
+    static client = null;
+    static inicioExecucao;
+    static fimExecucao;
+    static duracoes = [];
+    /**
+     * Conecta ao servidor SSH usando chave privada.
+     *
+     * 🆕 HOST e USERNAME vêm automaticamente do AutoCore Hub!
+     * A chave privada é o único parâmetro obrigatório.
+     *
+     * @param keyPath Caminho para a chave privada.
+     * @param options Opções para sobrescrever valores do Hub (opcional)
+     */
+    // NOTE: Legacy Portuguese-named convenience methods were removed.
+    // Use `SSHActions.connectWithKey(relativePath)` or `SSHActions.connectWithPassword(...)` if needed.
+    /**
+     * Conecta ao SSH usando chave privada relativa ao diretório do projeto.
+     *
+     * 🆕 HOST e USERNAME vêm automaticamente do AutoCore Hub!
+     * Basta chamar TestAnnotations.setSystem('SEU_SISTEMA') antes.
+     * A chave privada é o único parâmetro obrigatório (local).
+     *
+     * @param relativePath Caminho relativo à raiz do projeto (ex: 'secrets/key', './secrets/key')
+     * @param options Opções opcionais para sobrescrever valores do Hub
+     *
+     * @example
+     * // ✅ Simples - host/user vêm do Hub, só passa a chave
+     * await TestAnnotations.setSystem('SANITY_SSH')
+     * await SSHActions.connectWithKey('secrets/UserSistAutBRM')
+     *
+     * // ✅ Também funciona com ./
+     * await SSHActions.connectWithKey('./secrets/UserSistAutBRM')
+     *
+     * // ✅ Sobrescrevendo valores do Hub se necessário
+     * await SSHActions.connectWithKey('secrets/key', { host: 'outro-host.com' })
+     */
+    static async connectWithKey(relativePath, options) {
+        // Se já é caminho absoluto, usa direto
+        const cleanPath = path.isAbsolute(relativePath)
+            ? relativePath
+            : relativePath.startsWith('./')
+                ? path.resolve(process.cwd(), relativePath.slice(2))
+                : path.resolve(process.cwd(), relativePath);
+        // Valida se arquivo existe
+        if (!fs.existsSync(cleanPath)) {
+            throw new IntegrationError('SSH_KEY_NOT_FOUND', `SSH private key not found: ${cleanPath}`, `Chave privada SSH não encontrada: ${cleanPath}`, undefined, {
+                metadata: {
+                    relativePath,
+                    absolutePath: cleanPath,
+                    cwd: process.cwd(),
+                    action: 'connectWithKey',
+                },
+            });
+        }
+        // Create and configure SSH client directly
+        if (SSHActions.client) {
+            await SSHActions.client.disconnect();
+        }
+        SSHActions.client = new SSHClient();
+        await SSHActions.client.setPrivateKeyPath(cleanPath, options);
+        SSHActions.registrarInicioExecucao();
+        SSHActions.adicionarLog('Conexão SSH estabelecida com chave privada', 'success');
+        Logger.info(`🔑 Usando chave SSH: ${cleanPath}`);
+        Logger.info(`🔌 Host/User do Hub: ${process.env.SSH_HOST}@${process.env.SSH_USER}`);
+    }
+    /**
+     * 🆕 Conecta ao servidor SSH usando usuário e senha do AutoCore Hub.
+     * Chamado automaticamente pelo setSystem() quando PROJECT_TYPE=SSH.
+     *
+     * @param host Host do servidor SSH
+     * @param port Porta SSH (default: 22)
+     * @param username Usuário SSH
+     * @param password Senha SSH
+     *
+     * @example
+     * // Conexão manual com senha
+     * await SSHActions.conectarComSenha('servidor.com', 22, 'user', 'senha')
+     *
+     * // Ou use auto-conexão (recomendado):
+     * await SSHActions.autoConectar() // Usa credenciais do Hub
+     */
+    static async connectWithPassword(host, port = 22, username, password) {
+        if (SSHActions.client) {
+            await SSHActions.client.disconnect();
+        }
+        SSHActions.client = new SSHClient();
+        await SSHActions.client.connectWithPassword(host, port, username, password);
+        SSHActions.registrarInicioExecucao();
+        SSHActions.adicionarLog(`Conexão SSH estabelecida com usuário/senha em ${host}:${port}`, 'success');
+    }
+    /**
+     * 🆕 Auto-conexão SSH usando credenciais do AutoCore Hub.
+     * Usa as variáveis SSH_HOST, SSH_USER e SSH_PASSWORD injetadas pelo setSystem().
+     *
+     * @throws {IntegrationError} Se as credenciais não estiverem configuradas
+     *
+     * @example
+     * // No teste:
+     * test('CT01', async ({}, testInfo) => {
+     *   TestAnnotations.SSH.testInfo = testInfo
+     *   await TestAnnotations.setSystem('MEU_SISTEMA_SSH')
+     *   await SSHActions.autoConnect() // 👈 Usa credenciais do Hub automaticamente
+     *   await SSHActions.write('ls -la', 'Listar arquivos')
+     * })
+     */
+    static async autoConnect() {
+        // Já conectado? Retorna sem fazer nada
+        if (SSHActions.client !== null) {
+            Logger.info('🔌 SSH já conectado, reutilizando conexão existente');
+            return;
+        }
+        const host = process.env.SSH_HOST;
+        const port = Number.parseInt(process.env.SSH_PORT || '22', 10);
+        const username = process.env.SSH_USER;
+        const password = process.env.SSH_PASSWORD;
+        // Validar credenciais obrigatórias
+        if (!host || host === 'não definido') {
+            throw new IntegrationError('SSH_HOST_NOT_CONFIGURED', 'SSH_HOST not configured. Call TestAnnotations.setSystem() first.', `SSH_HOST não configurado. Chame TestAnnotations.setSystem('NOME_DO_SISTEMA') antes de conectar.`, undefined, {
+                metadata: {
+                    SSH_HOST: process.env.SSH_HOST || '(não definido)',
+                    SSH_USER: process.env.SSH_USER || '(não definido)',
+                    action: 'autoConnect',
+                },
+            });
+        }
+        if (!username || username === 'não definido') {
+            throw new IntegrationError('SSH_USER_NOT_CONFIGURED', 'SSH_USER not configured. Call TestAnnotations.setSystem() first.', `SSH_USER não configurado. Chame TestAnnotations.setSystem('NOME_DO_SISTEMA') antes de conectar.`, undefined, {
+                metadata: {
+                    SSH_HOST: process.env.SSH_HOST || '(não definido)',
+                    SSH_USER: process.env.SSH_USER || '(não definido)',
+                    action: 'autoConnect',
+                },
+            });
+        }
+        if (!password || password === 'não definido') {
+            throw new IntegrationError('SSH_PASSWORD_NOT_CONFIGURED', 'SSH_PASSWORD not configured. Call TestAnnotations.setSystem() first or use connectWithKey() for key-based auth.', `SSH_PASSWORD não configurado. Chame TestAnnotations.setSystem('NOME_DO_SISTEMA') ou use connectWithKey() para autenticação por chave.`, undefined, {
+                metadata: {
+                    SSH_HOST: process.env.SSH_HOST || '(não definido)',
+                    SSH_USER: process.env.SSH_USER || '(não definido)',
+                    action: 'autoConnect',
+                },
+            });
+        }
+        Logger.bloco('🔌 Auto-conexão SSH usando credenciais do Hub');
+        Logger.info(`Host: ${host}`);
+        Logger.info(`Porta: ${port}`);
+        Logger.info(`Usuário: ${username}`);
+        Logger.info(`Senha: ********`);
+        await SSHActions.connectWithPassword(host, port, username, password);
+        Logger.success(`✅ SSH conectado automaticamente em ${host}:${port}`);
+    }
+    /**
+     * 🆕 Verifica se o cliente SSH está conectado.
+     * @returns true se conectado, false caso contrário
+     */
+    static isConnected() {
+        return SSHActions.client !== null;
+    }
+    /**
+     * 🆕 Garante que o cliente SSH está conectado, tentando auto-conexão se necessário.
+     * @param actionName Nome da ação para mensagens de erro
+     * @throws IntegrationError se não conseguir conectar
+     */
+    static async ensureConnected(actionName) {
+        if (SSHActions.client)
+            return;
+        Logger.info('🔌 SSH não conectado, tentando auto-conexão...');
+        try {
+            await SSHActions.autoConnect();
+        }
+        catch (autoConnectError) {
+            throw new IntegrationError('SSH_NOT_CONNECTED', `SSH client is not connected and auto-connect failed. Call SSHActions.autoConnect() or SSHActions.connectWithKey() first.`, `Cliente SSH não conectado e auto-conexão falhou. Chame SSHActions.autoConnect() ou SSHActions.connectWithKey() antes de executar comandos.\n\nDica: Verifique se SSH_HOST, SSH_USER e SSH_PASSWORD estão configurados no ambiente.\n\nErro: ${autoConnectError}`, autoConnectError instanceof Error ? autoConnectError : undefined, { metadata: { action: actionName, autoConnectError: String(autoConnectError) } });
+        }
+    }
+    /**
+     * Desconecta do servidor SSH.
+     */
+    static async desconectar() {
+        if (SSHActions.client) {
+            await SSHActions.client.disconnect();
+            SSHActions.client = null;
+            SSHActions.adicionarLog('Conexão SSH encerrada', 'info');
+        }
+    }
+    /**
+     * Envia um comando SSH para o servidor remoto.
+     * @param command Comando SSH a ser enviado.
+     * @param descriptionToAction Descrição da ação, usada no relatório.
+     * @returns this
+     */
+    static async write(command, descriptionToAction) {
+        // 🆕 AUTO-CONEXÃO: Se não estiver conectado, tenta conectar automaticamente
+        await SSHActions.ensureConnected('write');
+        // 🆕 CRÍTICO: Registrar início de execução SSH se ainda não foi registrado
+        if (!SSHActions.inicioExecucao) {
+            SSHActions.registrarInicioExecucao();
+            Logger.info('⏱️ Início da execução SSH registrado');
+        }
+        const startTime = Date.now();
+        // 🆕 Interceptar para AutoDocs com ExecutionTracker
+        const sshCommand = {
+            command,
+            output: '',
+            host: process.env.SSH_HOST || 'ssh-server',
+            timestamp: new Date().toISOString(),
+            testName: TestContext.getSafeTestInfo()?.title || 'SSH Command',
+            user: process.env.SSH_USER || 'user',
+            duration: 0,
+            exitCode: 0,
+        };
+        try {
+            // Registrar no ExecutionTracker
+            const testInfo = TestContext.getSafeTestInfo();
+            await SSHActions.client.write(command, descriptionToAction);
+            const duration = Date.now() - startTime;
+            // 🆕 Atualizar comando SSH com sucesso
+            sshCommand.duration = duration;
+            sshCommand.output = 'Comando enviado com sucesso';
+            sshCommand.exitCode = 0;
+            // 🆕 Registrar no ExecutionTracker
+            ExecutionTracker.trackSSH(sshCommand);
+            // 📝 NOVO: Registrar ação automaticamente no Statement ativo
+            try {
+                StatementTracker.recordAction('SSH', `${descriptionToAction}: ${command}`, true, duration, {
+                    command,
+                });
+            }
+            catch (error) {
+                // Falha silenciosa - não afetar funcionalidade principal
+            }
+            SSHActions.adicionarLog(`${descriptionToAction} >> ${command}`, 'info');
+            return SSHActions;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            // 🆕 Atualizar comando SSH com erro
+            sshCommand.duration = duration;
+            sshCommand.output = `Erro: ${error}`;
+            sshCommand.exitCode = 1;
+            // 🆕 Registrar no ExecutionTracker mesmo com erro
+            ExecutionTracker.trackSSH(sshCommand);
+            // 📝 NOVO: Registrar ação com falha no Statement ativo
+            try {
+                StatementTracker.recordAction('SSH', `${descriptionToAction}: ${command}`, false, duration, {
+                    command,
+                });
+            }
+            catch (error) {
+                // Falha silenciosa - não afetar funcionalidade principal
+            }
+            SSHActions.adicionarLog(`Erro em ${descriptionToAction}: ${error}`, 'error');
+            throw error;
+        }
+    }
+    /**
+     * Envia um comando SSH e verifica o resultado do comando (usando "$?").
+     * @param command Comando SSH a ser enviado.
+     * @param descriptionToAction Descrição da ação, usada no relatório.
+     * @returns true se sucesso, false caso contrário.
+     */
+    static async writeAndReturnCommand(command, descriptionToAction) {
+        await SSHActions.ensureConnected('writeAndReturnCommand');
+        await SSHActions.client.write(`${command}; $?`, descriptionToAction);
+        const output = SSHActions.client.read(descriptionToAction);
+        const isSuccess = output.trim().endsWith('0');
+        SSHActions.adicionarLog(`${descriptionToAction} >> ${command} - ${isSuccess ? 'Sucesso' : 'Falha'}`, isSuccess ? 'success' : 'error');
+        return isSuccess;
+    }
+    /**
+     * Lê a saída do log do servidor remoto.
+     * @param descriptionToAction Descrição da ação, usada no relatório.
+     * @returns Saída do log como string.
+     */
+    static read(descriptionToAction) {
+        if (!SSHActions.client)
+            throw new IntegrationError('SSH_NOT_CONNECTED', 'SSH client is not connected. Use SSHActions.autoConnect() first.', 'Cliente SSH não conectado. Use SSHActions.autoConnect() antes.', undefined, { metadata: { action: 'read' } });
+        // Registrar statement no StatementTracker
+        let statementTimestamp = null;
+        try {
+            const { StatementTracker } = require('../hubdocs/StatementTracker.js');
+            statementTimestamp = StatementTracker.startStatement('SSHActions', `read: ${descriptionToAction}`);
+        }
+        catch (error) {
+            Logger.warning(`Não foi possível registrar statement no StatementTracker: ${error}`);
+        }
+        const startTime = Date.now();
+        const output = SSHActions.client.read(descriptionToAction);
+        const duration = Date.now() - startTime;
+        // 🆕 Registrar leitura de SSH no AutoDocs
+        // ✅ CORRIGIDO: read() sempre é sucesso se não lança exceção
+        const sshCommand = {
+            command: `read: ${descriptionToAction}`,
+            output,
+            host: process.env.SSH_HOST || 'ssh-server',
+            timestamp: new Date().toISOString(),
+            testName: TestContext.getSafeTestInfo()?.title || 'SSH Read',
+            user: process.env.SSH_USER || 'user',
+            duration,
+            exitCode: 0, // ✅ Sempre 0 se chegou até aqui sem exceção
+        };
+        ExecutionTracker.trackSSH(sshCommand);
+        // 📝 NOVO: Registrar ação automaticamente no Statement ativo
+        try {
+            StatementTracker.recordAction('SSH', `Read: ${descriptionToAction}`, true, duration);
+        }
+        catch (error) {
+            // Falha silenciosa - não afetar funcionalidade principal
+        }
+        // Finalizar statement
+        if (statementTimestamp) {
+            try {
+                const { StatementTracker } = require('../hubdocs/StatementTracker.js');
+                StatementTracker.finishStatement(statementTimestamp, true, `✅ ${descriptionToAction}: Saída capturada com sucesso`);
+            }
+            catch (error) {
+                Logger.warning(`Não foi possível finalizar statement no StatementTracker: ${error}`);
+            }
+        }
+        SSHActions.adicionarLog(`Leitura: ${descriptionToAction}`, 'info');
+        return output;
+    }
+    /**
+     * Verifica a saída do comando enviado ao servidor remoto.
+     * @returns true se o comando foi executado com sucesso, false caso contrário.
+     */
+    static async readOutputCommand() {
+        await SSHActions.ensureConnected('readOutputCommand');
+        const output = SSHActions.client.read('Verificando saída do comando');
+        return output.trim().endsWith('0');
+    }
+    /**
+     * Faz download de arquivo do servidor remoto para o caminho de destino especificado.
+     * @param sourcePath Caminho do arquivo no servidor remoto.
+     * @param destinyPath Caminho de destino para salvar o arquivo.
+     * @param descriptionToAction Descrição da ação, usada no relatório.
+     */
+    static async download(sourcePath, destinyPath, descriptionToAction) {
+        await SSHActions.ensureConnected('download');
+        const sftp = new SftpClient();
+        const startTime = Date.now();
+        // 🆕 Registrar download SSH no AutoDocs
+        const sshCommand = {
+            command: `download: ${sourcePath} → ${destinyPath}`,
+            output: '',
+            host: process.env.SSH_HOST || 'ssh-server',
+            timestamp: new Date().toISOString(),
+            testName: TestContext.getSafeTestInfo()?.title || 'SSH Download',
+            user: process.env.SSH_USER || 'user',
+            duration: 0,
+            exitCode: 1,
+        };
+        try {
+            await sftp.connect({
+                host: process.env.SSH_HOST,
+                port: Number.parseInt(process.env.SSH_PORT || '22', 10),
+                username: process.env.SSH_USER,
+                privateKey: fs.readFileSync(process.env.SSH_PRIVATE_KEY_PATH || '', 'utf-8'),
+                passphrase: process.env.SSH_PASSPHRASE,
+            });
+            await sftp.fastGet(sourcePath, destinyPath);
+            const duration = Date.now() - startTime;
+            // 🆕 Atualizar comando SSH com sucesso
+            sshCommand.duration = duration;
+            sshCommand.output = `Download concluído: ${sourcePath} → ${destinyPath}`;
+            sshCommand.exitCode = 0;
+            // 🆕 Registrar no ExecutionTracker
+            ExecutionTracker.trackSSH(sshCommand);
+            // 📝 NOVO: Registrar ação automaticamente no Statement ativo
+            try {
+                StatementTracker.recordAction('SSH', `Download: ${sourcePath} → ${destinyPath}`, true, duration, {
+                    command: `download ${sourcePath}`,
+                });
+            }
+            catch (error) {
+                // Falha silenciosa - não afetar funcionalidade principal
+            }
+            SSHActions.adicionarLog(`Download concluído: ${sourcePath} → ${destinyPath} (${descriptionToAction})`, 'success');
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            // 🆕 Atualizar comando SSH com erro
+            sshCommand.duration = duration;
+            sshCommand.output = `Erro no download: ${error}`;
+            sshCommand.exitCode = 1;
+            // 🆕 Registrar no ExecutionTracker mesmo com erro
+            ExecutionTracker.trackSSH(sshCommand);
+            // 📝 NOVO: Registrar ação automaticamente no Statement ativo (erro)
+            try {
+                StatementTracker.recordAction('SSH', `Download FALHOU: ${sourcePath} → ${destinyPath}`, false, duration, {
+                    command: `download ${sourcePath}`,
+                });
+            }
+            catch (recordError) {
+                // Falha silenciosa - não afetar funcionalidade principal
+            }
+            SSHActions.adicionarLog(`Erro no download: ${error}`, 'error');
+            if (error instanceof BaseError) {
+                throw error;
+            }
+            throw new IntegrationError('SSH_DOWNLOAD_FAILED', `SSH download failed: ${error}`, `Falha no download SSH: ${error}`, error instanceof Error ? error : new Error(String(error)), { metadata: { sourcePath, destinyPath, action: descriptionToAction } });
+        }
+        finally {
+            await sftp.end();
+        }
+    }
+    /**
+     * Registra o início da execução e limpa o contexto SSH.
+     */
+    static registrarInicioExecucao() {
+        SSHActions.inicioExecucao = new Date();
+        Logger.info('⏱️ Início da execução SSH registrado');
+    }
+    /**
+     * Registra o fim da execução.
+     */
+    static registrarFimExecucao() {
+        SSHActions.fimExecucao = new Date();
+        if (SSHActions.inicioExecucao) {
+            const duration = (SSHActions.fimExecucao.getTime() -
+                SSHActions.inicioExecucao.getTime()) /
+                1000;
+            Logger.info(`⏱️  Execução SSH concluída em ${duration.toFixed(2)}s`);
+        }
+    }
+    /**
+     * Registra um evento de log no contexto SSH.
+     * @param message Mensagem de log.
+     */
+    static logEvent(message) {
+        const testInfo = TestContext.getSafeTestInfo();
+        if (testInfo?.title) {
+            try {
+                UnifiedReportManager.adicionarLog(testInfo.title, message);
+            }
+            catch {
+                Logger.info(`📝 SSH Log: ${message}`);
+            }
+        }
+        else {
+            Logger.info(`📝 SSH Log: ${message}`);
+        }
+        if (testInfo &&
+            testInfo.annotations &&
+            Array.isArray(testInfo.annotations)) {
+            testInfo.annotations.push({ type: 'log', description: message });
+        }
+    }
+    /**
+     * Registra a duração de um teste SSH.
+     * @param nome Nome do teste.
+     * @param duracao Duração em milissegundos.
+     */
+    static registrarDuracaoDoTeste(nome, duracao) {
+        SSHActions.duracoes.push({ nome, duracao });
+        Logger.info(`⏱️  Duração registrada para "${nome}": ${duracao}ms`);
+        const testInfo = TestContext.getSafeTestInfo();
+        if (testInfo?.title) {
+            try {
+                UnifiedReportManager.setTestDuration(testInfo.title, duracao / 1000);
+            }
+            catch { }
+        }
+    }
+    /**
+     * Valida se a saída contém o texto esperado.
+     * @param output Saída do comando SSH.
+     * @param expected Texto esperado.
+     * @param message Mensagem descritiva da validação.
+     * @throws {Error} Se o texto não for encontrado.
+     */
+    static validateContains(output, expected, message) {
+        // Registrar statement no StatementTracker
+        let statementTimestamp = null;
+        try {
+            const { StatementTracker } = require('../hubdocs/StatementTracker.js');
+            statementTimestamp = StatementTracker.startStatement('SSHActions', `validateContains: ${message}`);
+        }
+        catch (error) {
+            Logger.warning(`Não foi possível registrar statement no StatementTracker: ${error}`);
+        }
+        if (!output.includes(expected)) {
+            const errorMsg = `❌ ${message}: esperado conter "${expected}", mas não encontrado.`;
+            SSHActions.logEvent(errorMsg);
+            Logger.error(message);
+            if (statementTimestamp) {
+                try {
+                    const { StatementTracker } = require('../hubdocs/StatementTracker.js');
+                    StatementTracker.finishStatement(statementTimestamp, false, errorMsg);
+                }
+                catch (error) {
+                    Logger.warning(`Não foi possível finalizar statement no StatementTracker: ${error}`);
+                }
+            }
+            throw new ValidationError('SSH_VALIDATION_CONTAINS_FAILED', `Validation failed: expected to contain "${expected}", but not found`, `${message}: esperado conter "${expected}", mas não encontrado.`, undefined, { metadata: { expected, actual: output, context: message } });
+        }
+        const successMsg = `✅ ${message}: encontrado "${expected}"`;
+        SSHActions.logEvent(successMsg);
+        Logger.success(successMsg);
+        if (statementTimestamp) {
+            try {
+                const { StatementTracker } = require('../hubdocs/StatementTracker.js');
+                StatementTracker.finishStatement(statementTimestamp, true, successMsg);
+            }
+            catch (error) {
+                Logger.warning(`Não foi possível finalizar statement no StatementTracker: ${error}`);
+            }
+        }
+    }
+    /**
+     * Valida se a saída NÃO contém o texto especificado.
+     * @param output Saída do comando SSH.
+     * @param notExpected Texto que não deve estar presente.
+     * @param message Mensagem descritiva da validação.
+     * @throws {Error} Se o texto for encontrado.
+     */
+    static validateNotContains(output, notExpected, message) {
+        if (output.includes(notExpected)) {
+            const errorMsg = `❌ ${message}: não esperado encontrar "${notExpected}", mas foi encontrado.`;
+            SSHActions.logEvent(errorMsg);
+            Logger.error(message);
+            throw new ValidationError('SSH_VALIDATION_NOT_CONTAINS_FAILED', `Validation failed: not expected to find "${notExpected}", but was found`, `${message}: não esperado encontrar "${notExpected}", mas foi encontrado.`, undefined, { metadata: { notExpected, actual: output, context: message } });
+        }
+        const successMsg = `✅ ${message}: "${notExpected}" não encontrado (como esperado)`;
+        SSHActions.logEvent(successMsg);
+        Logger.success(successMsg);
+    }
+    /**
+     * Valida se a saída corresponde a uma expressão regular.
+     * @param output Saída do comando SSH.
+     * @param pattern Padrão regex.
+     * @param message Mensagem descritiva da validação.
+     * @throws {Error} Se a saída não corresponder ao padrão.
+     */
+    static validateMatches(output, pattern, message) {
+        if (!pattern.test(output)) {
+            const errorMsg = `❌ ${message}: saída não corresponde ao padrão ${pattern.toString()}`;
+            SSHActions.logEvent(errorMsg);
+            Logger.error(message);
+            throw new Error(`${message}: saída não corresponde ao padrão ${pattern.toString()}`);
+        }
+        const successMsg = `✅ ${message}: saída corresponde ao padrão ${pattern.toString()}`;
+        SSHActions.logEvent(successMsg);
+        Logger.success(successMsg);
+    }
+    /**
+     * Adiciona log personalizado ao contexto SSH.
+     * @param mensagem Mensagem de log.
+     * @param tipo Tipo do log ('info', 'success', 'error', 'warning').
+     */
+    static adicionarLog(mensagem, tipo = 'info') {
+        const emojis = {
+            info: 'ℹ️',
+            success: '✅',
+            error: '❌',
+            warning: '⚠️',
+        };
+        const emoji = emojis[tipo];
+        const logEntry = `${emoji} ${mensagem}`;
+        SSHActions.logEvent(logEntry);
+        switch (tipo) {
+            case 'error':
+                Logger.error(mensagem);
+                break;
+            case 'success':
+                Logger.success(mensagem);
+                break;
+            case 'warning':
+                Logger.warning(mensagem);
+                break;
+            default:
+                Logger.info(mensagem);
+        }
+    }
+    /**
+     * Anexa o relatório final do teste SSH ao UnifiedReportManager.
+     */
+    static async anexarRelatorioFinal() {
+        try {
+            await UnifiedReportManager.finalizarTeste();
+        }
+        catch (error) {
+            Logger.error('❌ Erro ao anexar relatórios finais via UnifiedReportManager', error);
+        }
+    }
+    /**
+     * Limpa todos os dados e métricas SSH.
+     */
+    static limparTudo() {
+        SSHActions.duracoes = [];
+        SSHActions.inicioExecucao = undefined;
+        SSHActions.fimExecucao = undefined;
+        Logger.info('🗂️ Todos os dados SSH limpos');
+    }
+    /**
+     * Obtém estatísticas do teste SSH atual.
+     * @returns Objeto com total de logs, sucessos, erros, comandos executados e duração total.
+     */
+    static obterEstatisticas() {
+        const testInfo = TestContext.getSafeTestInfo();
+        let logs = [];
+        if (testInfo?.title) {
+            try {
+                const teste = UnifiedReportManager.getMetrics().testes.find((t) => t.nome === testInfo.title);
+                logs = teste?.logs || [];
+            }
+            catch {
+                logs = [];
+            }
+        }
+        return {
+            totalLogs: logs.length,
+            sucessos: logs.filter((log) => log.includes('✅')).length,
+            erros: logs.filter((log) => log.includes('❌')).length,
+            comandosExecutados: SSHActions.duracoes.length,
+            duracaoTotal: SSHActions.duracoes.reduce((total, item) => total + item.duracao, 0),
+        };
+    }
+    /**
+     * Verifica se há logs registrados para o teste SSH atual.
+     * @returns true se houver logs, false caso contrário.
+     */
+    static temLogs() {
+        const testInfo = TestContext.getSafeTestInfo();
+        if (testInfo?.title) {
+            try {
+                const teste = UnifiedReportManager.getMetrics().testes.find((t) => t.nome === testInfo.title);
+                return (teste?.logs || []).length > 0;
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+    /**
+     * Obtém todos os logs registrados para o teste SSH atual.
+     * @returns Array de logs.
+     */
+    static obterLogs() {
+        const testInfo = TestContext.getSafeTestInfo();
+        if (testInfo?.title) {
+            try {
+                const teste = UnifiedReportManager.getMetrics().testes.find((t) => t.nome === testInfo.title);
+                return [...(teste?.logs || [])];
+            }
+            catch {
+                return [];
+            }
+        }
+        return [];
+    }
+    /**
+     * Verifica se houve falhas no teste SSH atual.
+     * @returns true se houver falhas, false caso contrário.
+     */
+    static temFalhas() {
+        const logs = SSHActions.obterLogs();
+        return logs.some((log) => log.includes('❌'));
+    }
+    /**
+     * Obtém um resumo do teste SSH atual.
+     * @returns Objeto com informações de logs, falhas, estatísticas e datas.
+     */
+    static obterResumo() {
+        return {
+            temLogs: SSHActions.temLogs(),
+            temFalhas: SSHActions.temFalhas(),
+            estatisticas: SSHActions.obterEstatisticas(),
+            inicioExecucao: SSHActions.inicioExecucao,
+            fimExecucao: SSHActions.fimExecucao,
+        };
+    }
+    /**
+     * Indica se o SSHActions foi utilizado no teste atual.
+     * @returns true se utilizado, false caso contrário.
+     */
+    static foiUtilizado() {
+        return Boolean(SSHActions.inicioExecucao) || SSHActions.duracoes.length > 0;
+    }
+    /**
+     * Obtém métricas resumidas do teste SSH atual.
+     * @returns Objeto com comandosExecutados, sucessos, erros e duracaoTotal.
+     */
+    static getMetrics() {
+        const stats = SSHActions.obterEstatisticas();
+        return {
+            comandosExecutados: stats.comandosExecutados,
+            sucessos: stats.sucessos,
+            erros: stats.erros,
+            duracaoTotal: stats.duracaoTotal,
+        };
+    }
+    /**
+     * Valida se a saída contém o texto esperado dentro de um timeout.
+     * @param output Saída do comando SSH.
+     * @param expected Texto esperado.
+     * @param message Mensagem descritiva da validação.
+     * @param timeout Tempo máximo em ms para aguardar.
+     * @throws {Error} Se o texto não for encontrado no tempo especificado.
+     */
+    static async validateContainsWithTimeout(output, expected, message, timeout = TestContext.getProjectTimeout()) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            if (output.includes(expected)) {
+                const successMsg = `✅ ${message}: encontrado "${expected}" em ${Date.now() - startTime}ms`;
+                SSHActions.logEvent(successMsg);
+                Logger.success(successMsg);
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        const errorMsg = `❌ ${message}: timeout aguardando "${expected}" (${timeout}ms)`;
+        SSHActions.logEvent(errorMsg);
+        Logger.error(message);
+        throw new Error(`${message}: timeout aguardando "${expected}"`);
+    }
+    /**
+     * Valida se todos os textos esperados estão presentes na saída.
+     * @param output Saída do comando SSH.
+     * @param expectedTexts Array de textos esperados.
+     * @param message Mensagem descritiva da validação.
+     * @throws {Error} Se algum texto não for encontrado.
+     */
+    static validateContainsAll(output, expectedTexts, message) {
+        const missing = expectedTexts.filter((text) => !output.includes(text));
+        if (missing.length > 0) {
+            const errorMsg = `❌ ${message}: textos não encontrados: ${missing.join(', ')}`;
+            SSHActions.logEvent(errorMsg);
+            Logger.error(message);
+            throw new Error(`${message}: textos não encontrados: ${missing.join(', ')}`);
+        }
+        const successMsg = `✅ ${message}: todos os textos encontrados (${expectedTexts.length} itens)`;
+        SSHActions.logEvent(successMsg);
+        Logger.success(successMsg);
+    }
+    /**
+     * Valida se pelo menos um dos textos esperados está presente na saída.
+     * @param output Saída do comando SSH.
+     * @param expectedTexts Array de textos esperados.
+     * @param message Mensagem descritiva da validação.
+     * @throws {Error} Se nenhum texto for encontrado.
+     */
+    static validateContainsAny(output, expectedTexts, message) {
+        const found = expectedTexts.filter((text) => output.includes(text));
+        if (found.length === 0) {
+            const errorMsg = `❌ ${message}: nenhum dos textos esperados encontrado: ${expectedTexts.join(', ')}`;
+            SSHActions.logEvent(errorMsg);
+            Logger.error(message);
+            throw new Error(`${message}: nenhum dos textos esperados encontrado`);
+        }
+        const successMsg = `✅ ${message}: encontrado(s): ${found.join(', ')}`;
+        SSHActions.logEvent(successMsg);
+        Logger.success(successMsg);
+    }
+}
+// 🚫 AUTO-ATIVAÇÃO REMOVIDA: SSHActions são métodos internos que não devem ser interceptados
+// SSHActions.validateContains(), .write(), etc. não são CTs válidos e devem ser filtrados
+// A interceptação foi removida para evitar falsos CTs nos relatórios
+// CTs reais vêm das classes Statement (StatementsSSH, etc.) via InterceptacaoMagica.ts
+// CÓDIGO REMOVIDO:
+// try {
+//   installDatabaseInterceptor(SSHActions, 'SSHActions')
+// } catch (error) {
+//   if (process.env.AUTOCORE_DEBUG_LOGS === 'true') {
+//     process.stderr.write(`[DatabaseInterceptor] Falha na auto-ativação SSHActions: ${String(error)}\n`)
+//   }
+// }