smoonb 0.0.60 → 0.0.62

package/README.md

@@ -244,20 +244,28 @@ npx smoonb restore
 
 ### Importar Backup do Dashboard do Supabase
 
-Se você baixou um backup diretamente do Dashboard do Supabase (formato `.backup.gz`), você pode importá-lo para o formato esperado pelo smoonb:
+Se você baixou um backup diretamente do Dashboard do Supabase (formato `.backup.gz`), você pode importá-lo para o formato esperado pelo smoonb. O comando também suporta importar arquivos de storage (`.storage.zip`) opcionalmente.
 
+**Importar apenas database:**
 ```bash
 npx smoonb import --file "caminho/completo/para/db_cluster-04-03-2024@14-16-59.backup.gz"
 ```
 
-**O que o comando faz:**
-1. Lê o arquivo `.backup.gz` do Dashboard
-2. Extrai informações do nome do arquivo (data e hora)
-3. Cria uma pasta de backup no formato esperado (`backup-YYYY-MM-DD-HH-MM-SS`)
-4. Copia o arquivo para a pasta criada
-5. Deixa o backup pronto para ser encontrado pelo comando `restore`
+**Importar database e storage juntos:**
+```bash
+npx smoonb import --file "backup.backup.gz" --storage "meu-projeto.storage.zip"
+```
 
-**Exemplo completo:**
+**O que o comando faz:**
+1. Lê o arquivo `.backup.gz` do Dashboard (obrigatório)
+2. Se fornecido, lê o arquivo `.storage.zip` do Dashboard (opcional)
+3. Extrai informações do nome do arquivo de backup (data e hora)
+4. Cria uma pasta de backup no formato esperado (`backup-YYYY-MM-DD-HH-MM-SS`)
+5. Copia o arquivo de backup para a pasta criada
+6. Se fornecido, copia o arquivo de storage para a mesma pasta
+7. Deixa o backup pronto para ser encontrado pelo comando `restore`
+
+**Exemplo completo - Apenas database:**
 ```bash
 # 1. Baixar backup do Dashboard do Supabase
 #    Arquivo: db_cluster-04-03-2024@14-16-59.backup.gz
@@ -270,8 +278,26 @@ npx smoonb restore
 # O backup importado aparecerá na lista de backups disponíveis
 ```
 
+**Exemplo completo - Database e Storage:**
+```bash
+# 1. Baixar backup e storage do Dashboard do Supabase
+#    Arquivos: 
+#    - db_cluster-04-03-2024@14-16-59.backup.gz
+#    - meu-projeto.storage.zip
+
+# 2. Importar ambos os arquivos
+npx smoonb import --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz" --storage "C:\Downloads\meu-projeto.storage.zip"
+
+# 3. Restaurar o backup importado
+npx smoonb restore
+# O backup importado aparecerá na lista de backups disponíveis
+```
+
 **Importante:**
-- O arquivo deve estar no formato do Dashboard: `db_cluster-DD-MM-YYYY@HH-MM-SS.backup.gz`
+- O arquivo de backup é **obrigatório** e deve estar no formato do Dashboard: `db_cluster-DD-MM-YYYY@HH-MM-SS.backup.gz`
+- O arquivo de storage é **opcional** e deve estar no formato: `*.storage.zip`
+- O storage depende de um backup, mas o backup não depende do storage
+- Ambos os arquivos serão copiados para a mesma pasta de backup
 - O caminho pode ser absoluto ou relativo
 - O comando criará a estrutura de pastas necessária automaticamente
 
@@ -296,7 +322,7 @@ npx smoonb check
 |---------|-----------|
 | `npx smoonb backup` | Backup completo interativo usando Docker |
 | `npx smoonb restore` | Restauração interativa usando psql (Docker) |
-| `npx smoonb import --file <path>` | Importar arquivo .backup.gz do Dashboard do Supabase |
+| `npx smoonb import --file <path> [--storage <path>]` | Importar arquivo .backup.gz e opcionalmente .storage.zip do Dashboard do Supabase |
 | `npx smoonb check` | Verificação de integridade pós-restore |
 
 ## 🏗️ Arquitetura Técnica

package/bin/smoonb.js

@@ -40,6 +40,37 @@ program
 
 🔄 ATUALIZAR PARA ÚLTIMA VERSÃO:
    npm install smoonb@latest
+
+📚 MANUAL DE USO - EXEMPLOS COMPLETOS:
+
+${chalk.yellow.bold('1. BACKUP - Fazer backup completo do projeto:')}
+   ${chalk.white('npx smoonb backup')}
+   ${chalk.gray('# Processo interativo que captura todos os componentes do Supabase')}
+   
+   ${chalk.white('npx smoonb backup --skip-realtime')}
+   ${chalk.gray('# Pula a captura interativa de Realtime Settings')}
+
+${chalk.yellow.bold('2. RESTORE - Restaurar backup em um projeto:')}
+   ${chalk.white('npx smoonb restore')}
+   ${chalk.gray('# Processo interativo que lista backups disponíveis e permite escolher')}
+
+${chalk.yellow.bold('3. IMPORT - Importar backup do Dashboard do Supabase:')}
+   ${chalk.white('npx smoonb import --file "C:\\Downloads\\db_cluster-04-03-2024@14-16-59.backup.gz"')}
+   ${chalk.gray('# Importa apenas o arquivo de database')}
+   
+   ${chalk.white('npx smoonb import --file "backup.backup.gz" --storage "meu-projeto.storage.zip"')}
+   ${chalk.gray('# Importa database e storage juntos (storage é opcional)')}
+
+${chalk.yellow.bold('4. CHECK - Verificar integridade após restauração:')}
+   ${chalk.white('npx smoonb check')}
+   ${chalk.gray('# Verifica conexão, extensões, tabelas, RLS, Realtime e Storage')}
+
+${chalk.yellow.bold('💡 DICAS IMPORTANTES:')}
+   ${chalk.white('• O comando import requer um arquivo de backup (.backup.gz), mas o storage (.storage.zip) é opcional')}
+   ${chalk.white('• O storage depende de um backup, mas o backup não depende do storage')}
+   ${chalk.white('• Use caminhos absolutos ou relativos para os arquivos no comando import')}
+   ${chalk.white('• O formato do arquivo de backup deve ser: db_cluster-DD-MM-YYYY@HH-MM-SS.backup.gz')}
+   ${chalk.white('• O formato do arquivo de storage deve ser: *.storage.zip')}
 `);
   });
 
@@ -47,28 +78,95 @@ program
 program
   .command('backup')
   .description('Fazer backup completo do projeto Supabase usando Supabase CLI')
-  .option('-o, --output <dir>', 'Diretório de saída do backup')
   .option('--skip-realtime', 'Pular captura interativa de Realtime Settings')
+  .addHelpText('after', `
+${chalk.yellow.bold('Exemplos:')}
+  ${chalk.white('npx smoonb backup')}
+  ${chalk.gray('# Processo interativo completo')}
+  
+  ${chalk.white('npx smoonb backup --skip-realtime')}
+  ${chalk.gray('# Pula configuração de Realtime Settings')}
+
+${chalk.yellow.bold('O que é capturado:')}
+  • Database PostgreSQL (pg_dumpall + SQL separado)
+  • Database Extensions and Settings
+  • Custom Roles
+  • Edge Functions (download automático)
+  • Auth Settings (via Management API)
+  • Storage Buckets (metadados via Management API)
+  • Realtime Settings (7 parâmetros interativos)
+  • Supabase .temp (arquivos temporários)
+  • Migrations (todas as migrations do projeto)
+`)
   .action(commands.backup);
 
 program
   .command('restore')
   .description('Restaurar backup completo usando psql (modo interativo)')
-  .option('--db-url <url>', 'URL da database de destino (override)')
+  .addHelpText('after', `
+${chalk.yellow.bold('Exemplos:')}
+  ${chalk.white('npx smoonb restore')}
+  ${chalk.gray('# Processo interativo que lista backups disponíveis')}
+
+${chalk.yellow.bold('Fluxo do restore:')}
+  1. Validação Docker
+  2. Consentimento para ler/escrever .env.local
+  3. Mapeamento de variáveis de ambiente
+  4. Seleção de backup disponível
+  5. Seleção de componentes para restaurar
+  6. Resumo detalhado e confirmação
+  7. Execução da restauração
+
+${chalk.yellow.bold('Formatos suportados:')}
+  • .backup.gz (compactado) - Descompacta automaticamente
+  • .backup (descompactado) - Restaura diretamente
+`)
   .action(commands.restore);
 
 program
   .command('check')
   .description('Verificar integridade do projeto Supabase após restauração')
-  .option('-o, --output <file>', 'Arquivo de saída do relatório', 'check-report.json')
+  .addHelpText('after', `
+${chalk.yellow.bold('Exemplos:')}
+  ${chalk.white('npx smoonb check')}
+  ${chalk.gray('# Verifica integridade e exibe relatório no console')}
+
+${chalk.yellow.bold('O que é verificado:')}
+  • Conexão com database
+  • Extensões PostgreSQL instaladas
+  • Tabelas criadas
+  • Políticas RLS (Row Level Security)
+  • Publicações Realtime
+  • Buckets de Storage
+`)
   .action(commands.check);
 
 program
   .command('import')
-  .description('Importar arquivo .backup.gz do Dashboard do Supabase')
-  .requiredOption('-f, --file <path>', 'Caminho completo do arquivo .backup.gz a importar')
+  .description('Importar arquivo .backup.gz e opcionalmente .storage.zip do Dashboard do Supabase')
+  .requiredOption('--file <path>', 'Caminho completo do arquivo .backup.gz a importar')
+  .option('--storage <path>', 'Caminho completo do arquivo .storage.zip a importar (opcional)')
+  .addHelpText('after', `
+${chalk.yellow.bold('Exemplos:')}
+  ${chalk.white('npx smoonb import --file "C:\\Downloads\\db_cluster-04-03-2024@14-16-59.backup.gz"')}
+  ${chalk.gray('# Importa apenas o arquivo de database')}
+  
+  ${chalk.white('npx smoonb import --file "backup.backup.gz" --storage "meu-projeto.storage.zip"')}
+  ${chalk.gray('# Importa database e storage juntos')}
+
+${chalk.yellow.bold('Formato dos arquivos:')}
+  • Backup: db_cluster-DD-MM-YYYY@HH-MM-SS.backup.gz (obrigatório)
+  • Storage: *.storage.zip (opcional)
+
+${chalk.yellow.bold('Importante:')}
+  • O arquivo de backup é obrigatório
+  • O arquivo de storage é opcional e depende de um backup
+  • Ambos os arquivos serão copiados para a mesma pasta de backup
+  • O backup importado ficará disponível para o comando restore
+  • Use caminhos absolutos ou relativos
+`)
   .action(async (options) => {
-    await commands.import({ file: options.file });
+    await commands.import({ file: options.file, storage: options.storage });
   });
 
 // Tratamento de erros

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoonb",
-  "version": "0.0.60",
+  "version": "0.0.62",
   "description": "Complete Supabase backup and migration tool - EXPERIMENTAL VERSION - USE AT YOUR OWN RISK",
   "preferGlobal": false,
   "preventGlobalInstall": true,

package/src/commands/backup/index.js

@@ -66,8 +66,7 @@ module.exports = async (options) => {
     const second = String(now.getSeconds()).padStart(2, '0');
 
     // Resolver diretório de saída
-    const defaultOutput = options.output || defaultOutputDir;
-    const backupDir = path.join(defaultOutput, `backup-${year}-${month}-${day}-${hour}-${minute}-${second}`);
+    const backupDir = path.join(defaultOutputDir, `backup-${year}-${month}-${day}-${hour}-${minute}-${second}`);
     await ensureDir(backupDir);
 
     // Backup e mapeamento do .env.local
@@ -78,11 +77,11 @@ module.exports = async (options) => {
     console.log(chalk.blue(`📁 Backup do .env.local: ${path.relative(process.cwd(), envBackupPath)}`));
 
     const expectedKeys = [
+      'SUPABASE_PROJECT_ID',
       'NEXT_PUBLIC_SUPABASE_URL',
       'NEXT_PUBLIC_SUPABASE_ANON_KEY',
       'SUPABASE_SERVICE_ROLE_KEY',
       'SUPABASE_DB_URL',
-      'SUPABASE_PROJECT_ID',
       'SUPABASE_ACCESS_TOKEN',
       'SMOONB_OUTPUT_DIR'
     ];
@@ -98,7 +97,7 @@ module.exports = async (options) => {
     }
 
     // Recalcular outputDir a partir do ENV mapeado
-    const resolvedOutputDir = options.output || getValue('SMOONB_OUTPUT_DIR') || defaultOutputDir;
+    const resolvedOutputDir = getValue('SMOONB_OUTPUT_DIR') || defaultOutputDir;
 
     // Se mudou o outputDir, movemos o backupDir inicial para o novo local mantendo timestamp
     const finalBackupDir = backupDir.startsWith(path.resolve(resolvedOutputDir))

package/src/commands/check.js

@@ -7,7 +7,7 @@ const { IntrospectionService } = require('../services/introspect');
 const { showBetaBanner } = require('../utils/banner');
 
 // Exportar FUNÇÃO em vez de objeto Command
-module.exports = async (options) => {
+module.exports = async () => {
   showBetaBanner();
   
   try {
@@ -37,7 +37,7 @@ module.exports = async (options) => {
     const report = await performChecks(config, databaseUrl);
 
     // Salvar relatório
-    const reportPath = path.resolve(options.output || 'check-report.json');
+    const reportPath = path.resolve('check-report.json');
     await writeJson(reportPath, report);
 
     // Mostrar resumo

package/src/commands/import.js

@@ -4,38 +4,71 @@ const fs = require('fs').promises;
 const { ensureDir } = require('../utils/fsx');
 const { readEnvFile } = require('../utils/env');
 const { showBetaBanner } = require('../utils/banner');
+const { confirm } = require('../utils/prompt');
 
 /**
- * Comando para importar arquivo .backup.gz do Dashboard do Supabase
+ * Comando para importar arquivo .backup.gz e opcionalmente .storage.zip do Dashboard do Supabase
  */
 module.exports = async (options) => {
   showBetaBanner();
   
   try {
-    // Validar que o arquivo foi fornecido
+    // Termo de uso e aviso de risco
+    console.log(chalk.yellow.bold('\n⚠️  TERMO DE USO E AVISO DE RISCO\n'));
+    console.log(chalk.white('Ao prosseguir, você reconhece e concorda que o Supa Moonbase (smoonb) é fornecido "NO ESTADO EM QUE SE ENCONTRA" ("AS IS") e "CONFORME DISPONIBILIDADE", sem garantias de qualquer natureza—expressas, implícitas ou legais—incluindo, sem limitação, garantias de comercialização, adequação a um fim específico e não violação, na máxima extensão permitida pela lei aplicável. Operações de backup e restauração envolvem riscos, os ambientes variam amplamente e não é possível prever ou validar todas as configurações dos usuários. Você é o único responsável por validar seu ambiente, manter cópias independentes e verificar os resultados antes de utilizá-los em produção. O Supa Moonbase (smoonb) é construído com repositórios públicos, auditáveis e software livre, para auxiliar pessoas a simplificar seus fluxos, sem com isso criar qualquer garantia, promessa de suporte ou compromisso de nível de serviço.\n'));
+    console.log(chalk.white('Limitação de responsabilidade (PT-BR) — Na máxima extensão permitida por lei, a Goalmoon, seus contribuidores e licenciadores não serão responsáveis por danos indiretos, incidentais, especiais, consequentes, exemplares ou punitivos (incluindo perda de dados, interrupção de negócios ou lucros cessantes) decorrentes do uso, incapacidade de uso, das operações de backup/restauração realizadas com, ou dos resultados gerados pelo Supa Moonbase (smoonb). Em qualquer hipótese, a responsabilidade total por todas as reivindicações relacionadas ao Supa Moonbase (smoonb) não excederá o valor pago por você pelo Supa Moonbase (smoonb) nos 12 meses anteriores ao evento. Nada neste aviso exclui ou limita responsabilidades onde tais limites sejam proibidos por lei, incluindo (conforme aplicável) dolo ou culpa grave.\n'));
+    console.log(chalk.white('Observação para consumidores no Brasil (PT-BR) — Para consumidores brasileiros, este aviso não afasta direitos irrenunciáveis previstos no Código de Defesa do Consumidor (CDC); qualquer limitação aqui prevista só se aplica nos limites da lei e não impede a indenização obrigatória quando cabível.\n'));
+    
+    const termsAccepted = await confirm('Você aceita os Termos de Uso e o Aviso de Risco de Importação?', true);
+    if (!termsAccepted) {
+      console.log(chalk.red('🚫 Operação cancelada pelo usuário.'));
+      process.exit(1);
+    }
+
+    // Validar que o arquivo de backup foi fornecido
     if (!options.file) {
-      console.error(chalk.red('❌ Arquivo não fornecido'));
-      console.log(chalk.yellow('💡 Use: npx smoonb --import --file <caminho-completo-do-arquivo>'));
-      console.log(chalk.gray('   Exemplo: npx smoonb --import --file "C:\\Downloads\\db_cluster-04-03-2024@14-16-59.backup.gz"'));
+      console.error(chalk.red('❌ Arquivo de backup não fornecido'));
+      console.log(chalk.yellow('💡 Use: npx smoonb import --file <caminho-do-backup> [--storage <caminho-do-storage>]'));
+      console.log(chalk.white('   Exemplo: npx smoonb import --file "C:\\Downloads\\db_cluster-04-03-2024@14-16-59.backup.gz"'));
+      console.log(chalk.white('   Exemplo com storage: npx smoonb import --file "backup.backup.gz" --storage "meu-projeto.storage.zip"'));
       process.exit(1);
     }
 
     const sourceFile = path.resolve(options.file);
     
-    // Verificar se o arquivo existe
+    // Verificar se o arquivo de backup existe
     try {
       await fs.access(sourceFile);
     } catch {
-      console.error(chalk.red(`❌ Arquivo não encontrado: ${sourceFile}`));
+      console.error(chalk.red(`❌ Arquivo de backup não encontrado: ${sourceFile}`));
       process.exit(1);
     }
 
-    // Verificar se é um arquivo .backup.gz
+    // Verificar se é um arquivo .backup.gz ou .backup
     if (!sourceFile.endsWith('.backup.gz') && !sourceFile.endsWith('.backup')) {
-      console.error(chalk.red('❌ Arquivo deve ser .backup.gz ou .backup'));
+      console.error(chalk.red('❌ Arquivo de backup deve ser .backup.gz ou .backup'));
       process.exit(1);
     }
 
+    // Validar arquivo de storage se fornecido
+    let sourceStorageFile = null;
+    if (options.storage) {
+      sourceStorageFile = path.resolve(options.storage);
+      
+      try {
+        await fs.access(sourceStorageFile);
+      } catch {
+        console.error(chalk.red(`❌ Arquivo de storage não encontrado: ${sourceStorageFile}`));
+        process.exit(1);
+      }
+
+      // Verificar se é um arquivo .storage.zip
+      if (!sourceStorageFile.endsWith('.storage.zip')) {
+        console.error(chalk.red('❌ Arquivo de storage deve ser .storage.zip'));
+        process.exit(1);
+      }
+    }
+
     // Ler .env.local para obter SMOONB_OUTPUT_DIR
     const envPath = path.join(process.cwd(), '.env.local');
     let outputDir = './backups';
@@ -48,15 +81,15 @@ module.exports = async (options) => {
       console.log(chalk.yellow('⚠️  Não foi possível ler .env.local, usando diretório padrão: ./backups'));
     }
 
-    // Extrair informações do nome do arquivo
+    // Extrair informações do nome do arquivo de backup
     // Formato esperado: db_cluster-DD-MM-YYYY@HH-MM-SS.backup.gz
     const fileName = path.basename(sourceFile);
     const match = fileName.match(/db_cluster-(\d{2})-(\d{2})-(\d{4})@(\d{2})-(\d{2})-(\d{2})\.backup(\.gz)?/);
     
     if (!match) {
-      console.error(chalk.red('❌ Nome do arquivo não está no formato esperado do Dashboard'));
+      console.error(chalk.red('❌ Nome do arquivo de backup não está no formato esperado do Dashboard'));
       console.log(chalk.yellow('💡 Formato esperado: db_cluster-DD-MM-YYYY@HH-MM-SS.backup.gz'));
-      console.log(chalk.gray(`   Arquivo recebido: ${fileName}`));
+      console.log(chalk.white(`   Arquivo recebido: ${fileName}`));
       process.exit(1);
     }
 
@@ -70,17 +103,31 @@ module.exports = async (options) => {
     await ensureDir(backupDir);
     console.log(chalk.blue(`📁 Criando diretório de backup: ${backupDirName}`));
     
-    // Copiar arquivo para o diretório de backup
+    // Copiar arquivo de backup para o diretório de backup
     const destFile = path.join(backupDir, fileName);
     await fs.copyFile(sourceFile, destFile);
     
-    // Obter tamanho do arquivo
+    // Obter tamanho do arquivo de backup
     const stats = await fs.stat(destFile);
     const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
     
-    console.log(chalk.green(`✅ Arquivo importado com sucesso!`));
+    console.log(chalk.green(`✅ Arquivo de backup importado com sucesso!`));
+    console.log(chalk.blue(`📦 Backup: ${fileName} (${sizeMB} MB)`));
+    
+    // Copiar arquivo de storage se fornecido
+    if (sourceStorageFile) {
+      const storageFileName = path.basename(sourceStorageFile);
+      const destStorageFile = path.join(backupDir, storageFileName);
+      await fs.copyFile(sourceStorageFile, destStorageFile);
+      
+      const storageStats = await fs.stat(destStorageFile);
+      const storageSizeMB = (storageStats.size / (1024 * 1024)).toFixed(2);
+      
+      console.log(chalk.green(`✅ Arquivo de storage importado com sucesso!`));
+      console.log(chalk.blue(`📦 Storage: ${storageFileName} (${storageSizeMB} MB)`));
+    }
+    
     console.log(chalk.blue(`📁 Localização: ${backupDir}`));
-    console.log(chalk.blue(`📦 Arquivo: ${fileName} (${sizeMB} MB)`));
     console.log(chalk.cyan(`\n💡 Próximo passo: Execute 'npx smoonb restore' para restaurar este backup`));
     
   } catch (error) {

package/src/commands/restore/index.js

@@ -65,11 +65,11 @@ module.exports = async (_options) => {
     // Leitura e mapeamento interativo
     const currentEnv = await readEnvFile(envPath);
     const expectedKeys = [
+      'SUPABASE_PROJECT_ID',
       'NEXT_PUBLIC_SUPABASE_URL',
       'NEXT_PUBLIC_SUPABASE_ANON_KEY',
       'SUPABASE_SERVICE_ROLE_KEY',
       'SUPABASE_DB_URL',
-      'SUPABASE_PROJECT_ID',
       'SUPABASE_ACCESS_TOKEN',
       'SMOONB_OUTPUT_DIR'
     ];

package/src/interactive/envMapper.js

@@ -7,18 +7,92 @@ async function mapEnvVariablesInteractively(env, expectedKeys) {
   const dePara = {};
 
   const allKeys = Object.keys(env);
+  let projectId = null;
+
+  // Função auxiliar para obter Project ID já mapeado
+  function getProjectId() {
+    if (projectId) return projectId;
+    // Tentar encontrar Project ID já mapeado
+    const projectIdKey = Object.keys(dePara).find(k => dePara[k] === 'SUPABASE_PROJECT_ID');
+    if (projectIdKey && finalEnv[projectIdKey]) {
+      projectId = finalEnv[projectIdKey];
+      return projectId;
+    }
+    // Tentar encontrar no env original
+    const originalKey = Object.keys(env).find(k => k === 'SUPABASE_PROJECT_ID' || env[k]?.match(/^[a-z]{20}$/));
+    if (originalKey && env[originalKey]) {
+      projectId = env[originalKey];
+      return projectId;
+    }
+    return null;
+  }
+
+  // Função para obter instruções e links específicos para cada variável
+  function getVariableInstructions(expected, currentProjectId) {
+    const instructions = {
+      'SUPABASE_PROJECT_ID': {
+        notFound: 'Não foi encontrada uma entrada para a variável SUPABASE_PROJECT_ID.',
+        help: 'Encontre em: Dashboard -> Project Settings -> General -> General Settings -> Project ID',
+        link: null
+      },
+      'NEXT_PUBLIC_SUPABASE_URL': {
+        notFound: 'Não foi encontrada uma entrada para a variável NEXT_PUBLIC_SUPABASE_URL.',
+        help: currentProjectId 
+          ? `Acesse: https://supabase.com/dashboard/project/${currentProjectId}/settings/api`
+          : 'Acesse: Dashboard -> Project Settings -> API -> Project URL',
+        link: currentProjectId ? `https://supabase.com/dashboard/project/${currentProjectId}/settings/api` : null
+      },
+      'NEXT_PUBLIC_SUPABASE_ANON_KEY': {
+        notFound: 'Não foi encontrada uma entrada para a variável NEXT_PUBLIC_SUPABASE_ANON_KEY.',
+        help: currentProjectId
+          ? `Acesse: https://supabase.com/dashboard/project/${currentProjectId}/settings/api-keys`
+          : 'Acesse: Dashboard -> Project Settings -> API -> API Keys -> anon public',
+        link: currentProjectId ? `https://supabase.com/dashboard/project/${currentProjectId}/settings/api-keys` : null
+      },
+      'SUPABASE_SERVICE_ROLE_KEY': {
+        notFound: 'Não foi encontrada uma entrada para a variável SUPABASE_SERVICE_ROLE_KEY.',
+        help: currentProjectId
+          ? `Acesse: https://supabase.com/dashboard/project/${currentProjectId}/settings/api-keys`
+          : 'Acesse: Dashboard -> Project Settings -> API -> API Keys -> service_role secret',
+        link: currentProjectId ? `https://supabase.com/dashboard/project/${currentProjectId}/settings/api-keys` : null
+      },
+      'SUPABASE_DB_URL': {
+        notFound: 'Não foi encontrada uma entrada para a variável SUPABASE_DB_URL.',
+        help: currentProjectId
+          ? `Formato: postgresql://postgres:[DATABASE_PASSWORD]@db.${currentProjectId}.supabase.co:5432/postgres\nPara resetar senha: https://supabase.com/dashboard/project/${currentProjectId}/database/settings`
+          : 'Formato: postgresql://postgres:[DATABASE_PASSWORD]@db.[PROJECT_ID].supabase.co:5432/postgres\nPara resetar senha: Dashboard -> Project Settings -> Database -> Database Settings',
+        link: currentProjectId ? `https://supabase.com/dashboard/project/${currentProjectId}/database/settings` : null
+      },
+      'SUPABASE_ACCESS_TOKEN': {
+        notFound: 'Não foi encontrada uma entrada para a variável SUPABASE_ACCESS_TOKEN.',
+        help: 'Acesse: https://supabase.com/dashboard/account/tokens',
+        link: 'https://supabase.com/dashboard/account/tokens'
+      },
+      'SMOONB_OUTPUT_DIR': {
+        notFound: 'Não foi encontrada uma entrada para a variável SMOONB_OUTPUT_DIR.',
+        help: 'Diretório padrão para armazenar backups',
+        link: null,
+        default: './backups'
+      }
+    };
+
+    return instructions[expected] || {
+      notFound: `Não foi encontrada uma entrada para a variável ${expected}.`,
+      help: '',
+      link: null
+    };
+  }
 
   for (const expected of expectedKeys) {
     console.log(chalk.blue(`\n🔧 Mapeando variável: ${expected}`));
 
     let clientKey = undefined;
 
-    // 3) Se existir chave exatamente igual, pular seleção e ir direto para confirmação
+    // Se existir chave exatamente igual, pular seleção e ir direto para confirmação
     if (Object.prototype.hasOwnProperty.call(finalEnv, expected)) {
       clientKey = expected;
     } else {
-      // 2) Remover o caractere '?' do início da pergunta definindo prefix: ''
-      // 4) Opção explícita para adicionar nova chave
+      // Opção explícita para adicionar nova chave
       const choices = [
         ...allKeys.map((k, idx) => ({ name: `${idx + 1}. ${k}`, value: k })),
         new inquirer.Separator(),
@@ -48,30 +122,71 @@ async function mapEnvVariablesInteractively(env, expectedKeys) {
     }
 
     const currentValue = finalEnv[clientKey] ?? '';
-    const isCorrect = await confirm(`Valor atual: ${currentValue || '(vazio)'}\nEste é o valor correto do projeto alvo?`, true);
+    const currentProjectId = getProjectId();
+    const instructions = getVariableInstructions(expected, currentProjectId);
 
-    let valueToWrite = currentValue;
-    if (!isCorrect) {
+    // Se não tem valor, mostrar mensagem específica
+    if (!currentValue) {
+      console.log(chalk.yellow(instructions.notFound));
+      if (instructions.help) {
+        console.log(chalk.white(instructions.help));
+      }
+      if (instructions.link) {
+        console.log(chalk.cyan(`🔗 ${instructions.link}`));
+      }
+    } else {
+      // Se tem valor, perguntar se está correto
+      const isCorrect = await confirm(`Valor atual: ${currentValue}\nEste é o valor correto do projeto alvo?`, true);
+      if (isCorrect) {
+        finalEnv[clientKey] = currentValue;
+        if (expected === 'SUPABASE_PROJECT_ID') {
+          projectId = currentValue;
+        }
+        if (dePara[clientKey] && dePara[clientKey] !== expected) {
+          throw new Error(`Duplicidade de mapeamento detectada para ${clientKey}`);
+        }
+        dePara[clientKey] = expected;
+        continue;
+      }
+    }
+
+    // Solicitar novo valor
+    let valueToWrite = '';
+    if (expected === 'SMOONB_OUTPUT_DIR') {
+      // Para SMOONB_OUTPUT_DIR, pré-preencher com ./backups
       const { newValue } = await inquirer.prompt([{
         type: 'input',
         name: 'newValue',
-        message: `Cole o novo valor para ${clientKey}:`,
+        message: `Confirme o novo valor para ${expected}:`,
+        default: instructions.default || './backups',
+        prefix: ''
+      }]);
+      valueToWrite = newValue || instructions.default || './backups';
+    } else {
+      const { newValue } = await inquirer.prompt([{
+        type: 'input',
+        name: 'newValue',
+        message: `Cole o novo valor para ${expected}:`,
         prefix: ''
       }]);
       valueToWrite = newValue || '';
     }
 
-    if (!valueToWrite) {
+    // Validar valor obrigatório (exceto SMOONB_OUTPUT_DIR que tem default)
+    if (!valueToWrite && expected !== 'SMOONB_OUTPUT_DIR') {
       const { newValueRequired } = await inquirer.prompt([{
         type: 'input',
         name: 'newValueRequired',
-        message: `Valor obrigatório. Informe valor para ${clientKey}:`,
+        message: `Valor obrigatório. Informe valor para ${expected}:`,
         prefix: ''
       }]);
       valueToWrite = newValueRequired || '';
     }
 
-    finalEnv[clientKey] = valueToWrite;
+    finalEnv[clientKey] = valueToWrite || (expected === 'SMOONB_OUTPUT_DIR' ? './backups' : '');
+    if (expected === 'SUPABASE_PROJECT_ID') {
+      projectId = valueToWrite;
+    }
     if (dePara[clientKey] && dePara[clientKey] !== expected) {
       throw new Error(`Duplicidade de mapeamento detectada para ${clientKey}`);
     }