smoonb 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -4,84 +4,66 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [1.0.4] - 2025-01-29
+## [1.0.6] - 2026-02-21
 
 ### Changed
 
-- Release 1.0.4 – Build and lint verification.
+- **Storage backup (step 6) — robustness and feedback:**
+  - Added `withTimeout` helper: each Storage `.list()` call times out after 30s; each file `.download()` times out after 2 minutes.
+  - Added `withRetry` helper: up to 3 attempts with exponential backoff (2s → 4s → 8s) on both listing and download failures.
+  - Inline progress during file listing: live `\r`-updated line shows the current folder being scanned and the running file count (`→ Scanning bucket/folder (N found)`). No more silent hangs.
+  - After listing completes, a summary line shows the total files found.
+  - Retry warnings show attempt number, failure reason and next retry delay.
+  - Download failures after all retries are counted as `filesSkipped` and reported in the bucket summary.
+  - Bucket summary now distinguishes between full success and partial success with skips.
 
 ---
 
-## [1.0.3] - 2025-01-29
+## [1.0.5] - 2026-02-21
 
 ### Added
 
-- **License binding by installation** – One license is bound to a single installation (machine). On first use, the license is linked to a persistent `installationId` and cannot be moved. To use smoonb on another machine, revoke the license in the desktop app and generate a new one.
-- **Installation ID** – Generated and stored on first run via `env-paths` (Windows: `%APPDATA%/smoonb-nodejs/Config`, macOS/Linux: `~/.config/smoonb-nodejs`). File: `config.json` with `installationId` (uuid v4) and `createdAt`. Never stores the license key.
-- **Validation payload** – License validation now sends `installationId` and `cliVersion` with `licenseKey` and `correlationId`.
+- **Flexible Supabase CLI version check** – Instead of requiring the exact latest version, smoonb now accepts any CLI version that is at most 1 minor behind the latest (same major). The minimum accepted version is computed as `major.(minor_latest - 1).0` at runtime from the npm registry. Special case: if `minor_latest === 0`, only the same major.minor is accepted.
+- **`--skip-supabase-version-check` flag** – New opt-in flag for both `backup` and `restore` commands. When set, the Supabase CLI version check is skipped entirely and a warning is displayed. Useful when package managers (e.g. Scoop on Windows) lag behind on updates and the user wants to proceed at their own risk.
 
 ### Changed
 
-- **LICENSE_ALREADY_BOUND** – When the server returns this reason, the CLI shows a clear message: "This license is already linked to another machine and cannot be moved" and instructs to revoke and generate a new license at https://www.smoonb.com.
-- **Diagnostic bundle** – Includes masked `InstallationId` (e.g. `2f3a…91bc`) and server `Reason` (or reason code) on validation failure; HTTP status and response body (truncated) on network/HTTP errors.
-- **Telemetry** – Uses the same `installationId` as license validation (shared util); removed duplicate persistence in `~/.smoonb/installation-id`.
-
-### Fixed
-
-- No offline cache: if validation fails (network or backend), the CLI does not run and shows the full diagnostic bundle.
+- Error message for outdated Supabase CLI now shows the computed minimum accepted version (`minVersion`) and the current latest, instead of only the latest.
+- README (EN and PT-BR): updated Supabase CLI prerequisites section with the new version policy, added examples with `--skip-supabase-version-check`, updated commands table and troubleshooting section.
+- i18n strings (`en.json`, `pt-BR.json`): removed specific version number references in favour of evergreen language ("always use the latest version").
 
 ---
 
-## [1.0.2] - 2025-01-29
-
-### Fixed
-
-- **Backup report** – When Realtime settings are reused from a previous backup file, the final summary now correctly shows "Settings imported from backup {name}" (or the pt-BR equivalent) instead of "Configurations captured interactively"
-
----
-
-## [1.0.1] - 2025-01-29
-
-### Removed
-
-- **`check` command** – Post-restore integrity verification command removed from CLI, help and documentation
-- **`--skip-realtime`** – Backup option removed; Realtime settings are always captured interactively
-- **`--file` and `--storage` on restore** – Restore no longer accepts direct file paths; use `import` then `restore` to select from the list
-- **`--lang`** – CLI language option removed; language is determined by `SMOONB_LANG` (env or `.env.local`) and system locale only
+## [1.0.4] - 2025-01-29
 
 ### Changed
 
-- README and README.pt-BR: all `#` comment lines removed from code blocks (replaced with normal text) to avoid light-gray rendering issues
-- Restore flow: backup selection is always interactive (no skip via `--file`)
-- i18n: `detectLocale` no longer reads `--lang` from argv; precedence is SMOONB_LANG → system locale → en
+- Release 1.0.4 – Build and lint verification.
 
 ---
 
-## [1.0.0] - 2025-01-29
+## [1.0.3] - 2025-01-29
 
 ### Added
 
-- Commercial release. Use requires an active license and valid subscription (or trial). See https://www.smoonb.com/#price
-- License validation (step 00) at the start of backup and restore; CLI aborts if validation fails
-- Restore disclaimer before execution: expected errors during DB restore, link to Supabase docs, wait for completion and test result
-- Environment variables: `SMOONB_LICENSE_KEY` (required), `SMOONB_TELEMETRY_ENABLED` (optional), `SUPABASE_POSTGRES_MAJOR` (required for backup and restore)
-- i18n (en, pt-BR) for all user-facing messages and help
+- **License binding by installation** – One license is bound to a single installation (machine). On first use, the license is linked to a persistent `installationId` and cannot be moved. To use smoonb on another machine, revoke the license in the desktop app and generate a new one.
+- **Installation ID** – Generated and stored on first run via `env-paths` (Windows: `%APPDATA%/smoonb-nodejs/Config`, macOS/Linux: `~/.config/smoonb-nodejs`). File: `config.json` with `installationId` (uuid v4) and `createdAt`. Never stores the license key.
+- **Validation payload** – License validation now sends `installationId` and `cliVersion` with `licenseKey` and `correlationId`.
 
 ### Changed
 
-- Backup flow: terms → license validation → Docker → consent → variable mapping (license not in wizard) → component selection → summary → execution
-- Restore flow: terms → license validation → Docker → consent → mapping (includes `SUPABASE_POSTGRES_MAJOR`) → backup selection → component selection → summary → disclaimer → execution
-- Help and README aligned with commercial product; legal disclaimers unchanged
-- Documentation and links point to https://www.smoonb.com (terms, privacy, #price, #faq)
+- **LICENSE_ALREADY_BOUND** – When the server returns this reason, the CLI shows a clear message: "This license is already linked to another machine and cannot be moved" and instructs to revoke and generate a new license at https://www.smoonb.com.
+- **Diagnostic bundle** – Includes masked `InstallationId` (e.g. `2f3a…91bc`) and server `Reason` (or reason code) on validation failure; HTTP status and response body (truncated) on network/HTTP errors.
+- **Telemetry** – Uses the same `installationId` as license validation (shared util); removed duplicate persistence in `~/.smoonb/installation-id`.
 
 ### Fixed
 
-- `instructions` used before definition in interactive env mapper; blocks moved after `getVariableInstructions()`
+- No offline cache: if validation fails (network or backend), the CLI does not run and shows the full diagnostic bundle.
+
+---
 
 ---
 
+[1.0.6]: https://github.com/almmello/smoonb/releases/tag/v1.0.6
+[1.0.5]: https://github.com/almmello/smoonb/releases/tag/v1.0.5
 [1.0.4]: https://github.com/almmello/smoonb/releases/tag/v1.0.4
-[1.0.3]: https://github.com/almmello/smoonb/releases/tag/v1.0.3
-[1.0.2]: https://github.com/almmello/smoonb/releases/tag/v1.0.2
-[1.0.1]: https://github.com/almmello/smoonb/releases/tag/v1.0.1
-[1.0.0]: https://github.com/almmello/smoonb/releases/tag/v1.0.0

package/README.md

@@ -92,7 +92,11 @@ docker ps
 npm install -g supabase
 ```
 
-We recommend **Supabase CLI v2.72 or newer** for new features and bug fixes. To update: [Updating the Supabase CLI](https://supabase.com/docs/guides/cli/getting-started#updating-the-supabase-cli).
+**Version policy:** smoonb accepts any Supabase CLI version that is **at most 1 minor behind the latest** (same major). We recommend always using the latest version. Versions that are too old are blocked with an error message.
+
+If your package manager (e.g. **Scoop** on Windows) lags behind on updates and you want to proceed anyway, use the `--skip-supabase-version-check` flag (see usage section below).
+
+To update the Supabase CLI: [Updating the Supabase CLI](https://supabase.com/docs/guides/cli/getting-started#updating-the-supabase-cli).
 
 ### 3. Supabase Personal Access Token
 You need to obtain a Supabase personal access token to use the Management API:
@@ -190,6 +194,17 @@ Language is detected automatically in the following order of precedence:
 npx smoonb backup
 ```
 
+**Available options:**
+
+| Flag | Description |
+|------|-------------|
+| `--skip-supabase-version-check` | Skips the Supabase CLI version check. Use when your package manager (e.g. Scoop) lags behind on updates. A warning is shown and the user assumes the risk. |
+
+**Example with flag:**
+```bash
+npx smoonb backup --skip-supabase-version-check
+```
+
 **Interactive backup flow:**
 
 1. **Terms of use** - Displays and requests acceptance of terms
@@ -252,6 +267,17 @@ backups/backup-2025-10-31-09-37-54/
 npx smoonb restore
 ```
 
+**Available options:**
+
+| Flag | Description |
+|------|-------------|
+| `--skip-supabase-version-check` | Skips the Supabase CLI version check. Use when your package manager (e.g. Scoop) lags behind on updates. A warning is shown and the user assumes the risk. |
+
+**Example with flag:**
+```bash
+npx smoonb restore --skip-supabase-version-check
+```
+
 **Interactive restore flow:**
 
 1. **Terms of use** - Displays and requests acceptance of terms
@@ -345,7 +371,9 @@ After running `import`, run `restore` to choose the imported backup from the lis
 | Command | Description |
 |---------|-------------|
 | `npx smoonb backup` | Full interactive backup using Docker |
+| `npx smoonb backup --skip-supabase-version-check` | Backup skipping the Supabase CLI version check |
 | `npx smoonb restore` | Interactive restoration using psql (Docker) |
+| `npx smoonb restore --skip-supabase-version-check` | Restore skipping the Supabase CLI version check |
 | `npx smoonb import --file <path> [--storage <path>]` | Import .backup.gz file and optionally .storage.zip from Supabase Dashboard |
 
 ## 🏗️ Technical Architecture
@@ -519,6 +547,28 @@ If not, start Docker Desktop (Windows/macOS) or run `sudo systemctl start docker
 npm install -g supabase
 ```
 
+### Supabase CLI outdated (below minimum accepted version)
+
+smoonb accepts versions up to **1 minor behind the latest**. If your installed version is below that threshold, you will see a message like:
+
+```
+❌ Supabase CLI X.Y.Z is below the minimum accepted version (X.W.0). Latest: X.V.Z. Update to at least version X.W.0.
+```
+
+**Option 1 — Update the Supabase CLI:**
+```bash
+npm install -g supabase@latest   # global install
+npm install supabase@latest       # local/project install
+```
+
+**Option 2 — Skip the check (temporary, user assumes the risk):**
+```bash
+npx smoonb backup --skip-supabase-version-check
+npx smoonb restore --skip-supabase-version-check
+```
+
+> **Note for Scoop users (Windows):** the Scoop repository may take a few days to update after a release. Use `--skip-supabase-version-check` until Scoop ships the updated version.
+
 ### Invalid or missing Personal Access Token
 
 1. Verify if `SUPABASE_ACCESS_TOKEN` is in `.env.local`

package/README.pt-BR.md

@@ -92,7 +92,11 @@ docker ps
 npm install -g supabase
 ```
 
-Recomendamos **Supabase CLI v2.72 ou mais recente** para novos recursos e correções. Para atualizar: [Atualizando o Supabase CLI](https://supabase.com/docs/guides/cli/getting-started#updating-the-supabase-cli).
+**Política de versão:** o smoonb aceita qualquer versão do Supabase CLI que esteja **no máximo 1 minor atrás da latest** (mesma major). Recomendamos sempre usar a versão mais recente. Versões muito antigas são bloqueadas com mensagem de erro.
+
+Se o seu gerenciador de pacotes (ex.: **Scoop** no Windows) instala com atraso e você quer avançar mesmo assim, use a flag `--skip-supabase-version-check` (veja a seção de uso abaixo).
+
+Para atualizar o Supabase CLI: [Atualizando o Supabase CLI](https://supabase.com/docs/guides/cli/getting-started#updating-the-supabase-cli).
 
 ### 3. Personal Access Token do Supabase
 É necessário obter um token de acesso pessoal do Supabase para usar a Management API:
@@ -190,6 +194,17 @@ O idioma é detectado automaticamente na seguinte ordem de precedência:
 npx smoonb backup
 ```
 
+**Opções disponíveis:**
+
+| Flag | Descrição |
+|------|-----------|
+| `--skip-supabase-version-check` | Pula a checagem de versão do Supabase CLI. Use quando seu gerenciador de pacotes (ex.: Scoop) instala com atraso. Um aviso é exibido e o usuário assume o risco. |
+
+**Exemplo com a flag:**
+```bash
+npx smoonb backup --skip-supabase-version-check
+```
+
 **Fluxo interativo do backup:**
 
 1. **Termo de uso** - Exibe e solicita aceitação dos termos
@@ -252,6 +267,17 @@ backups/backup-2025-10-31-09-37-54/
 npx smoonb restore
 ```
 
+**Opções disponíveis:**
+
+| Flag | Descrição |
+|------|-----------|
+| `--skip-supabase-version-check` | Pula a checagem de versão do Supabase CLI. Use quando seu gerenciador de pacotes (ex.: Scoop) instala com atraso. Um aviso é exibido e o usuário assume o risco. |
+
+**Exemplo com a flag:**
+```bash
+npx smoonb restore --skip-supabase-version-check
+```
+
 **Fluxo interativo do restore:**
 
 1. **Termo de uso** - Exibe e solicita aceitação dos termos
@@ -345,7 +371,9 @@ Após executar `import`, execute `restore` para escolher o backup importado na l
 | Comando | Descrição |
 |---------|-----------|
 | `npx smoonb backup` | Backup completo interativo usando Docker |
+| `npx smoonb backup --skip-supabase-version-check` | Backup pulando a checagem de versão do Supabase CLI |
 | `npx smoonb restore` | Restauração interativa usando psql (Docker) |
+| `npx smoonb restore --skip-supabase-version-check` | Restore pulando a checagem de versão do Supabase CLI |
 | `npx smoonb import --file <path> [--storage <path>]` | Importar arquivo .backup.gz e opcionalmente .storage.zip do Dashboard do Supabase |
 
 ## 🏗️ Arquitetura Técnica
@@ -519,6 +547,28 @@ Se não estiver, inicie o Docker Desktop (Windows/macOS) ou execute `sudo system
 npm install -g supabase
 ```
 
+### Supabase CLI desatualizado (abaixo da versão mínima aceita)
+
+O smoonb aceita versões até **1 minor atrás da latest**. Se sua versão instalada estiver abaixo desse limite, você verá uma mensagem como:
+
+```
+❌ Supabase CLI X.Y.Z está abaixo da versão mínima aceita (X.W.0). Versão latest: X.V.Z. Atualize para pelo menos a versão X.W.0.
+```
+
+**Opção 1 — Atualizar o Supabase CLI:**
+```bash
+npm install -g supabase@latest   # instalação global
+npm install supabase@latest       # instalação local/projeto
+```
+
+**Opção 2 — Pular a checagem (temporariamente, risco do usuário):**
+```bash
+npx smoonb backup --skip-supabase-version-check
+npx smoonb restore --skip-supabase-version-check
+```
+
+> **Nota para usuários de Scoop (Windows):** o repositório do Scoop pode levar alguns dias para atualizar após um release. Use `--skip-supabase-version-check` até que o Scoop disponibilize a versão atualizada.
+
 ### Personal Access Token inválido ou ausente
 
 1. Verificar se `SUPABASE_ACCESS_TOKEN` está no `.env.local`

package/bin/smoonb.js

@@ -79,6 +79,10 @@ program
     const getT = global.smoonbI18n?.t || t;
     return getT('help.commands.backupDesc');
   })
+  .option('--skip-supabase-version-check', () => {
+    const getT = global.smoonbI18n?.t || t;
+    return getT('help.commands.skipSupabaseVersionCheck');
+  })
   .addHelpText('after', () => {
     const getT = global.smoonbI18n?.t || t;
     return `
@@ -86,6 +90,9 @@ ${chalk.yellow.bold(getT('help.commands.backupExamples'))}
   ${chalk.white(getT('help.commands.backupExample1'))}
   ${chalk.white(getT('help.commands.backupExample1Desc'))}
 
+  ${chalk.white(getT('help.commands.backupExample3'))}
+  ${chalk.white(getT('help.commands.backupExample3Desc'))}
+
 ${chalk.yellow.bold(getT('help.commands.backupFlow'))}
   ${getT('help.commands.backupFlow1')}
   ${getT('help.commands.backupFlow2')}
@@ -120,6 +127,10 @@ program
     const getT = global.smoonbI18n?.t || t;
     return getT('help.commands.restoreDesc');
   })
+  .option('--skip-supabase-version-check', () => {
+    const getT = global.smoonbI18n?.t || t;
+    return getT('help.commands.skipSupabaseVersionCheck');
+  })
   .addHelpText('after', () => {
     const getT = global.smoonbI18n?.t || t;
     return `
@@ -127,6 +138,9 @@ ${chalk.yellow.bold(getT('help.commands.restoreExamples'))}
   ${chalk.white(getT('help.commands.restoreExample1'))}
   ${chalk.white(getT('help.commands.restoreExample1Desc'))}
 
+  ${chalk.white(getT('help.commands.restoreExample4'))}
+  ${chalk.white(getT('help.commands.restoreExample4Desc'))}
+
 ${chalk.yellow.bold(getT('help.commands.restoreFlow'))}
   ${getT('help.commands.restoreFlow1')}
   ${getT('help.commands.restoreFlow2')}
@@ -144,7 +158,7 @@ ${chalk.yellow.bold(getT('help.commands.restoreFormats'))}
   ${getT('help.commands.restoreFormats2')}
 `;
   })
-  .action(() => commands.restore({}));
+  .action((options) => commands.restore(options));
 
 program
   .command('import')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoonb",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Complete Supabase backup and migration tool. https://www.smoonb.com/#price",
   "preferGlobal": false,
   "preventGlobalInstall": true,

package/src/commands/backup/index.js

@@ -51,7 +51,7 @@ module.exports = async (options) => {
     const licenseResult = await step00License({ envPath, command: 'backup' });
 
     // Executar validação Docker
-    await step01DockerValidation();
+    await step01DockerValidation({ skipSupabaseVersionCheck: !!(options && options.skipSupabaseVersionCheck) });
 
     // Consentimento para leitura e escrita do .env.local
     console.log(chalk.yellow(`\n⚠️  ${getT('consent.title')}`));

package/src/commands/backup/steps/01-docker-validation.js

@@ -6,17 +6,25 @@ const { t } = require('../../../i18n');
 /**
  * Etapa 0: Validação Docker
  * Deve ocorrer antes de tudo
+ * @param {object} [options]
+ * @param {boolean} [options.skipSupabaseVersionCheck=false]
  */
-module.exports = async () => {
+module.exports = async (options = {}) => {
   const getT = global.smoonbI18n?.t || t;
   console.log(chalk.blue(`\n🐳 ${getT('docker.validation.title')}`));
   console.log(chalk.cyan(`🔍 ${getT('docker.validation.checking')}`));
   
-  const backupCapability = await canPerformCompleteBackup();
+  const backupCapability = await canPerformCompleteBackup({
+    skipSupabaseVersionCheck: options.skipSupabaseVersionCheck || false
+  });
 
   if (!backupCapability.canBackupComplete) {
     showDockerMessagesAndExit(backupCapability.reason, backupCapability);
   }
+
+  if (backupCapability.supabaseVersionCheckSkipped) {
+    console.log(chalk.yellow(`⚠️  ${getT('supabase.cliVersionSkipWarning')}`));
+  }
   
   console.log(chalk.green(`✅ ${getT('docker.validation.detected')}`));
   console.log(chalk.white(`🐳 ${getT('docker.validation.version', { version: backupCapability.dockerStatus.version })}`));

package/src/commands/backup/steps/07-storage.js

@@ -7,9 +7,52 @@ const { ensureDir, writeJson } = require('../../../utils/fsx');
 const { confirm } = require('../../../utils/prompt');
 const { t } = require('../../../i18n');
 
+const TIMEOUT_LIST_MS = 30_000;       // 30s por chamada de listagem
+const TIMEOUT_DOWNLOAD_MS = 360_000;  // 2min por download de arquivo
+const MAX_RETRIES = 7;
+const RETRY_BASE_DELAY_MS = 2_000;    // backoff: 2s → 4s → 8s
+
+/**
+ * Executa uma promise com timeout. Lança Error se o tempo esgotar.
+ * @param {Promise} promise
+ * @param {number} ms
+ * @returns {Promise}
+ */
+function withTimeout(promise, ms) {
+  let id;
+  const timer = new Promise((_, reject) => {
+    id = setTimeout(() => reject(new Error(`Timeout (${ms / 1000}s)`)), ms);
+  });
+  return Promise.race([promise, timer]).finally(() => clearTimeout(id));
+}
+
+/**
+ * Executa fn() com retry automático e backoff exponencial.
+ * @param {Function} fn - Fábrica de Promise (chamada a cada tentativa)
+ * @param {number} maxAttempts
+ * @param {number} baseDelayMs
+ * @param {Function} [onRetry] - Callback(attempt, max, err, delayMs)
+ */
+async function withRetry(fn, maxAttempts = MAX_RETRIES, baseDelayMs = RETRY_BASE_DELAY_MS, onRetry) {
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxAttempts) {
+        const delay = baseDelayMs * Math.pow(2, attempt - 1);
+        if (onRetry) onRetry(attempt, maxAttempts, err, delay);
+        await new Promise(r => setTimeout(r, delay));
+      }
+    }
+  }
+  throw lastError;
+}
+
 /**
  * Etapa 6: Backup Storage via Supabase API
- * Agora faz backup completo: metadados + download de todos os arquivos + ZIP no padrão do Dashboard
+ * Backup completo: metadados + download de todos os arquivos + ZIP no padrão do Dashboard
  */
 module.exports = async ({ projectId, accessToken, backupDir, supabaseUrl, supabaseServiceKey }) => {
   try {
@@ -18,15 +61,14 @@ module.exports = async ({ projectId, accessToken, backupDir, supabaseUrl, supaba
     await ensureDir(storageDir);
 
     console.log(chalk.white(`   - ${getT('backup.steps.storage.listing')}`));
-    
-    // Usar fetch direto para Management API com Personal Access Token
+
     const storageResponse = await fetch(`https://api.supabase.com/v1/projects/${projectId}/storage/buckets`, {
-      headers: { 
+      headers: {
         'Authorization': `Bearer ${accessToken}`,
         'Content-Type': 'application/json'
       }
     });
-    
+
     if (!storageResponse.ok) {
       console.log(chalk.yellow(`     ⚠️ ${getT('backup.steps.storage.listBucketsError', { status: storageResponse.status, statusText: storageResponse.statusText })}`));
       return { success: false, buckets: [] };
@@ -44,20 +86,16 @@ module.exports = async ({ projectId, accessToken, backupDir, supabaseUrl, supaba
 
     console.log(chalk.white(`   - ${getT('backup.steps.storage.found', { count: buckets.length })}`));
 
-    // Validar credenciais do Supabase para download de arquivos
     if (!supabaseUrl || !supabaseServiceKey) {
       console.log(chalk.yellow(`   ⚠️  ${getT('backup.steps.storage.credentialsNotAvailable')}`));
       return await backupMetadataOnly(buckets, storageDir, projectId, accessToken);
     }
 
-    // Criar cliente Supabase para download de arquivos
     const supabase = createClient(supabaseUrl, supabaseServiceKey);
 
-    // Criar estrutura temporária para armazenar arquivos baixados
     const tempStorageDir = path.join(backupDir, 'storage_temp');
     await ensureDir(tempStorageDir);
-    
-    // Criar estrutura: storage_temp/project-id/bucket-name/arquivos...
+
     const projectStorageDir = path.join(tempStorageDir, projectId);
     await ensureDir(projectStorageDir);
 
@@ -67,10 +105,9 @@ module.exports = async ({ projectId, accessToken, backupDir, supabaseUrl, supaba
     for (const bucket of buckets || []) {
       try {
         console.log(chalk.white(`   - ${getT('backup.steps.storage.processing', { bucketName: bucket.name })}`));
-        
-        // Listar objetos do bucket via Management API com Personal Access Token
+
         const objectsResponse = await fetch(`https://api.supabase.com/v1/projects/${projectId}/storage/buckets/${bucket.name}/objects`, {
-          headers: { 
+          headers: {
             'Authorization': `Bearer ${accessToken}`,
             'Content-Type': 'application/json'
           }
@@ -90,51 +127,85 @@ module.exports = async ({ projectId, accessToken, backupDir, supabaseUrl, supaba
           objects: objects || []
         };
 
-        // Salvar informações do bucket
         const bucketPath = path.join(storageDir, `${bucket.name}.json`);
         await writeJson(bucketPath, bucketInfo);
 
-        // Baixar todos os arquivos do bucket
         const bucketDir = path.join(projectStorageDir, bucket.name);
         await ensureDir(bucketDir);
-        
-        // Listar todos os arquivos recursivamente usando Supabase client
+
+        // ── Listagem com progresso inline ──────────────────────────────
         console.log(chalk.white(`     - ${getT('backup.steps.storage.listingFiles', { bucketName: bucket.name })}`));
-        const allFiles = await listAllFilesRecursively(supabase, bucket.name, '');
-        
+        const counter = { total: 0 };
+        let allFiles = [];
+        let listingFailed = false;
+
+        try {
+          allFiles = await listAllFilesRecursively(supabase, bucket.name, '', counter, getT);
+        } catch (listErr) {
+          listingFailed = true;
+          console.log(chalk.yellow(`     ⚠️  ${getT('backup.steps.storage.listFailed', { bucketName: bucket.name, message: listErr.message })}`));
+        } finally {
+          // Encerra a linha de progresso (\r) iniciada por listAllFilesRecursively
+          process.stdout.write('\n');
+        }
+
+        if (!listingFailed) {
+          console.log(chalk.white(`     - ${getT('backup.steps.storage.totalFound', { count: allFiles.length })}`));
+        }
+
+        // ── Download com retry ──────────────────────────────────────────
         let filesDownloaded = 0;
+        let filesSkipped = 0;
+
         if (allFiles.length > 0) {
           console.log(chalk.white(`     - ${getT('backup.steps.storage.downloading', { count: allFiles.length, bucketName: bucket.name })}`));
-          
+
           for (const filePath of allFiles) {
             try {
-              // Baixar arquivo do Storage
-              const { data: fileData, error: downloadError } = await supabase.storage
-                .from(bucket.name)
-                .download(filePath);
+              let fileData = null;
+              let downloadError = null;
+
+              await withRetry(
+                async () => {
+                  const result = await withTimeout(
+                    supabase.storage.from(bucket.name).download(filePath),
+                    TIMEOUT_DOWNLOAD_MS
+                  );
+                  // Erros estruturais do Supabase (ex.: 404) não devem ser retentados
+                  if (result.error) {
+                    downloadError = result.error;
+                    fileData = null;
+                  } else {
+                    fileData = result.data;
+                    downloadError = null;
+                  }
+                },
+                MAX_RETRIES,
+                RETRY_BASE_DELAY_MS,
+                (attempt, max, err, delay) => {
+                  console.log(chalk.yellow(`       ⚠️  ${getT('backup.steps.storage.downloadRetry', { path: filePath, attempt, max, delay: delay / 1000 })}`));
+                }
+              );
 
               if (downloadError) {
+                filesSkipped++;
                 console.log(chalk.yellow(`       ⚠️  ${getT('backup.steps.storage.downloadError', { path: filePath, message: downloadError.message })}`));
                 continue;
               }
 
-              // Criar estrutura de pastas local se necessário
               const localFilePath = path.join(bucketDir, filePath);
-              const localFileDir = path.dirname(localFilePath);
-              await ensureDir(localFileDir);
+              await ensureDir(path.dirname(localFilePath));
 
-              // Salvar arquivo localmente
-              const arrayBuffer = await fileData.arrayBuffer();
-              const buffer = Buffer.from(arrayBuffer);
+              const buffer = Buffer.from(await fileData.arrayBuffer());
               await fs.writeFile(localFilePath, buffer);
               filesDownloaded++;
 
-              // Mostrar progresso a cada 10 arquivos ou se for o último
               if (filesDownloaded % 10 === 0 || filesDownloaded === allFiles.length) {
                 console.log(chalk.white(`       - ${getT('backup.steps.storage.downloaded', { current: filesDownloaded, total: allFiles.length })}`));
               }
             } catch (fileError) {
-              console.log(chalk.yellow(`       ⚠️  ${getT('backup.steps.storage.processFileError', { path: filePath, message: fileError.message })}`));
+              filesSkipped++;
+              console.log(chalk.yellow(`       ⚠️  ${getT('backup.steps.storage.downloadFailed', { path: filePath, message: fileError.message })}`));
             }
           }
         }
@@ -143,37 +214,36 @@ module.exports = async ({ projectId, accessToken, backupDir, supabaseUrl, supaba
         processedBuckets.push({
           name: bucket.name,
           objectCount: objects?.length || 0,
-          filesDownloaded: filesDownloaded,
+          filesDownloaded,
+          filesSkipped,
           totalFiles: allFiles.length
         });
 
-        console.log(chalk.green(`     ✅ ${getT('backup.steps.storage.bucketDone', { bucketName: bucket.name, downloaded: filesDownloaded, total: allFiles.length })}`));
+        if (filesSkipped > 0) {
+          console.log(chalk.yellow(`     ⚠️  ${getT('backup.steps.storage.bucketDoneWithSkips', { bucketName: bucket.name, downloaded: filesDownloaded, skipped: filesSkipped, total: allFiles.length })}`));
+        } else {
+          console.log(chalk.green(`     ✅ ${getT('backup.steps.storage.bucketDone', { bucketName: bucket.name, downloaded: filesDownloaded, total: allFiles.length })}`));
+        }
       } catch (error) {
         console.log(chalk.yellow(`     ⚠️ ${getT('backup.steps.storage.processBucketError', { bucketName: bucket.name, message: error.message })}`));
       }
     }
 
-    // Criar ZIP no padrão do Dashboard: {project-id}.storage.zip
+    // ── Criar ZIP no padrão do Dashboard ───────────────────────────────
     console.log(chalk.white(`\n   - ${getT('backup.steps.storage.creatingZip')}`));
     const zipFileName = `${projectId}.storage.zip`;
     const zipFilePath = path.join(backupDir, zipFileName);
-    
+
     const zip = new AdmZip();
-    
-    // Adicionar toda a estrutura de pastas ao ZIP
-    // Estrutura: project-id/bucket-name/arquivos...
     await addDirectoryToZip(zip, projectStorageDir, projectId);
-    
-    // Salvar ZIP
     zip.writeZip(zipFilePath);
     const zipStats = await fs.stat(zipFilePath);
     const zipSizeMB = (zipStats.size / (1024 * 1024)).toFixed(2);
-    
+
     console.log(chalk.green(`   ✅ ${getT('backup.steps.storage.zipCreated', { fileName: zipFileName, size: zipSizeMB })}`));
 
-    // Perguntar ao usuário se deseja limpar a estrutura temporária
     const shouldCleanup = await confirm(`   ${getT('backup.steps.storage.cleanup')}`, false);
-    
+
     if (shouldCleanup) {
       console.log(chalk.white(`   - ${getT('backup.steps.storage.cleanupRemoving')}`));
       try {
@@ -187,11 +257,11 @@ module.exports = async ({ projectId, accessToken, backupDir, supabaseUrl, supaba
     }
 
     console.log(chalk.green(`✅ ${getT('backup.steps.storage.done', { buckets: processedBuckets.length, files: totalFilesDownloaded })}`));
-    return { 
-      success: true, 
+    return {
+      success: true,
       buckets: processedBuckets,
       zipFile: zipFileName,
-      zipSizeMB: zipSizeMB,
+      zipSizeMB,
       totalFiles: totalFilesDownloaded,
       tempDirCleaned: shouldCleanup
     };
@@ -202,8 +272,10 @@ module.exports = async ({ projectId, accessToken, backupDir, supabaseUrl, supaba
   }
 };
 
+// ── Funções auxiliares ────────────────────────────────────────────────────────
+
 /**
- * Backup apenas de metadados (fallback quando não há credenciais do Supabase)
+ * Backup apenas de metadados (fallback sem credenciais Supabase)
  */
 async function backupMetadataOnly(buckets, storageDir, projectId, accessToken) {
   const processedBuckets = [];
@@ -211,9 +283,9 @@ async function backupMetadataOnly(buckets, storageDir, projectId, accessToken) {
   for (const bucket of buckets || []) {
     try {
       console.log(chalk.white(`   - Processando bucket: ${bucket.name}`));
-      
+
       const objectsResponse = await fetch(`https://api.supabase.com/v1/projects/${projectId}/storage/buckets/${bucket.name}/objects`, {
-        headers: { 
+        headers: {
           'Authorization': `Bearer ${accessToken}`,
           'Content-Type': 'application/json'
         }
@@ -236,11 +308,7 @@ async function backupMetadataOnly(buckets, storageDir, projectId, accessToken) {
       const bucketPath = path.join(storageDir, `${bucket.name}.json`);
       await writeJson(bucketPath, bucketInfo);
 
-      processedBuckets.push({
-        name: bucket.name,
-        objectCount: objects?.length || 0
-      });
-
+      processedBuckets.push({ name: bucket.name, objectCount: objects?.length || 0 });
       console.log(chalk.green(`     ✅ Bucket ${bucket.name}: ${objects?.length || 0} objetos`));
     } catch (error) {
       console.log(chalk.yellow(`     ⚠️ Erro ao processar bucket ${bucket.name}: ${error.message}`));
@@ -252,59 +320,97 @@ async function backupMetadataOnly(buckets, storageDir, projectId, accessToken) {
 }
 
 /**
- * Lista todos os arquivos recursivamente de um bucket do Storage
+ * Lista recursivamente todos os arquivos de um bucket com:
+ * - progresso inline via \r (pasta atual + total encontrado)
+ * - timeout por chamada (TIMEOUT_LIST_MS)
+ * - retry com backoff exponencial (MAX_RETRIES)
+ *
+ * O CALLER é responsável por emitir \n após o retorno para encerrar a linha \r.
+ *
+ * @param {object} supabase
+ * @param {string} bucketName
+ * @param {string} folderPath
+ * @param {{ total: number }} counter - Contador compartilhado entre chamadas recursivas
+ * @param {Function} getT - Função de tradução
+ * @returns {Promise<string[]>}
  */
-async function listAllFilesRecursively(supabase, bucketName, folderPath = '') {
+async function listAllFilesRecursively(supabase, bucketName, folderPath = '', counter = { total: 0 }, getT) {
   const allFiles = [];
-  const getT = global.smoonbI18n?.t || t;
-  
+  const label = folderPath ? `${bucketName}/${folderPath}` : `${bucketName}/`;
+  const displayLabel = label.length > 55 ? `...${label.slice(-52)}` : label;
+
+  // Progresso inline: mostra pasta atual + arquivos encontrados até agora
+  process.stdout.write(
+    chalk.gray(`\r       → ${getT('backup.steps.storage.scanningFolder', { path: displayLabel, count: counter.total })}          `)
+  );
+
+  let result;
   try {
-    // Listar arquivos e pastas no caminho atual
-    const { data: items, error } = await supabase.storage
-      .from(bucketName)
-      .list(folderPath, {
-        limit: 1000,
-        sortBy: { column: 'name', order: 'asc' }
-      });
+    result = await withRetry(
+      () => withTimeout(
+        supabase.storage.from(bucketName).list(folderPath, {
+          limit: 1000,
+          sortBy: { column: 'name', order: 'asc' }
+        }),
+        TIMEOUT_LIST_MS
+      ),
+      MAX_RETRIES,
+      RETRY_BASE_DELAY_MS,
+      (attempt, max, err, delay) => {
+        // Encerra linha \r antes de imprimir o aviso
+        process.stdout.write('\n');
+        console.log(chalk.yellow(`       ⚠️  ${getT('backup.steps.storage.listRetry', { path: displayLabel, attempt, max, delay: delay / 1000, message: err.message })}`));
+      }
+    );
+  } catch (err) {
+    // Esgotou as tentativas — propaga para o caller lidar
+    throw err;
+  }
 
-    if (error) {
-      console.log(chalk.yellow(`       ⚠️  ${getT('backup.steps.storage.listError', { path: folderPath || 'raiz', message: error.message })}`));
-      return allFiles;
-    }
+  const { data: items, error } = result;
 
-    if (!items || items.length === 0) {
-      return allFiles;
-    }
+  if (error) {
+    process.stdout.write('\n');
+    console.log(chalk.yellow(`       ⚠️  ${getT('backup.steps.storage.listError', { path: label, message: error.message })}`));
+    return allFiles;
+  }
 
-    for (const item of items) {
-      const itemPath = folderPath ? `${folderPath}/${item.name}` : item.name;
-      
-      if (item.id === null) {
-        // É uma pasta, listar recursivamente
-        const subFiles = await listAllFilesRecursively(supabase, bucketName, itemPath);
-        allFiles.push(...subFiles);
-      } else {
-        // É um arquivo
-        allFiles.push(itemPath);
-      }
+  if (!items || items.length === 0) {
+    return allFiles;
+  }
+
+  for (const item of items) {
+    const itemPath = folderPath ? `${folderPath}/${item.name}` : item.name;
+
+    if (item.id === null) {
+      // Pasta — listar recursivamente
+      const subFiles = await listAllFilesRecursively(supabase, bucketName, itemPath, counter, getT);
+      allFiles.push(...subFiles);
+    } else {
+      // Arquivo
+      allFiles.push(itemPath);
+      counter.total++;
+      // Atualizar display com novo total
+      const dl = label.length > 55 ? `...${label.slice(-52)}` : label;
+      process.stdout.write(
+        chalk.gray(`\r       → ${getT('backup.steps.storage.scanningFolder', { path: dl, count: counter.total })}          `)
+      );
     }
-  } catch (error) {
-    console.log(chalk.yellow(`       ⚠️  ${getT('backup.steps.storage.processError', { path: folderPath || 'raiz', message: error.message })}`));
   }
 
   return allFiles;
 }
 
 /**
- * Adiciona um diretório recursivamente ao ZIP mantendo a estrutura de pastas
+ * Adiciona diretório recursivamente ao ZIP mantendo estrutura de pastas
  */
 async function addDirectoryToZip(zip, dirPath, basePath = '') {
   const entries = await fs.readdir(dirPath, { withFileTypes: true });
-  
+
   for (const entry of entries) {
     const fullPath = path.join(dirPath, entry.name);
     const zipPath = basePath ? `${basePath}/${entry.name}` : entry.name;
-    
+
     if (entry.isDirectory()) {
       await addDirectoryToZip(zip, fullPath, zipPath);
     } else {
@@ -313,4 +419,3 @@ async function addDirectoryToZip(zip, dirPath, basePath = '') {
     }
   }
 }
-

package/src/commands/backup/utils.js

@@ -83,7 +83,7 @@ function showDockerMessagesAndExit(reason, data = {}) {
       break;
 
     case 'supabase_cli_outdated':
-      console.log(chalk.red(`❌ ${getT('supabase.cliOutdated', { version: data.supabaseCliVersion || '?', latest: data.supabaseCliLatest || '?' })}`));
+      console.log(chalk.red(`❌ ${getT('supabase.cliOutdated', { version: data.supabaseCliVersion || '?', minVersion: data.supabaseCliMinVersion || '?', latest: data.supabaseCliLatest || '?' })}`));
       console.log('');
       console.log(chalk.yellow(`📋 ${getT('supabase.cliUpdateInstructions')}`));
       console.log(chalk.cyan(`   ${getT('supabase.cliUpdateCommandExamples')}`));

package/src/commands/restore/index.js

@@ -25,7 +25,7 @@ const step07DatabaseSettings = require('./steps/07-database-settings');
 const step08RealtimeSettings = require('./steps/08-realtime-settings');
 const { sendTelemetry } = require('../../telemetry');
 
-module.exports = async () => {
+module.exports = async (options = {}) => {
   showBetaBanner();
   const restoreStartTime = Date.now();
   let telemetryEnabled = (process.env.SMOONB_TELEMETRY_ENABLED || 'true') !== 'false';
@@ -49,7 +49,7 @@ module.exports = async () => {
     await step00License({ envPath: envPathForLicense, command: 'restore' });
 
     // Executar validação Docker
-    await step01DockerValidation();
+    await step01DockerValidation({ skipSupabaseVersionCheck: !!(options && options.skipSupabaseVersionCheck) });
 
     // Consentimento para leitura e escrita do .env.local
     ui.warn(`\n⚠️  ${getT('consent.title')}`);

package/src/i18n/locales/en.json

@@ -72,8 +72,10 @@
   "supabase.installLink": "Installation: npm install -g supabase",
   "supabase.required": "Supabase CLI is required for full Supabase backup",
   "supabase.requiredComponents": "Supabase CLI is required for full Supabase backup\n   - PostgreSQL Database\n   - Edge Functions\n   - All components via Docker",
-  "supabase.cliUpdateRecommended": "Supabase CLI {version} detected. We recommend v2.72 or newer for new features and bug fixes: https://supabase.com/docs/guides/cli/getting-started#updating-the-supabase-cli",
-  "supabase.cliOutdated": "Supabase CLI {version} is not the latest ({latest}). Update to the latest version.",
+  "supabase.cliVersionPolicy": "Version policy: accepts any version up to 1 minor behind the latest (same major). Use --skip-supabase-version-check to bypass the check.",
+  "supabase.cliUpdateRecommended": "Supabase CLI {version} detected. We recommend always using the latest version for new features and bug fixes: https://supabase.com/docs/guides/cli/getting-started#updating-the-supabase-cli",
+  "supabase.cliOutdated": "Supabase CLI {version} is below the minimum accepted version ({minVersion}). Latest: {latest}. Update to at least version {minVersion}.",
+  "supabase.cliVersionSkipWarning": "Supabase CLI version check disabled (--skip-supabase-version-check). Proceeding without version check — user assumes the risk.",
   "supabase.cliUpdateInstructions": "Update the Supabase CLI and run smoonb again:",
   "supabase.cliUpdateCommandExamples": "Examples (depending on how you installed):",
   "supabase.cliUpdateCommandGlobal": "npm install -g supabase@latest   (global)",
@@ -166,6 +168,7 @@
   "help.tip5": "• Storage file format must be: *.storage.zip",
 
   "help.commands.backupDesc": "Create a full backup of your Supabase project using Supabase CLI",
+  "help.commands.skipSupabaseVersionCheck": "Skip the Supabase CLI version check (user assumes the risk)",
   "help.commands.backupSkipRealtime": "Skip interactive capture of Realtime Settings",
   "help.commands.backupPostgresMajor": "Postgres major version for dump (15, 17). Non-interactive; no menu.",
   "help.commands.backupExamples": "Examples:",
@@ -173,6 +176,8 @@
   "help.commands.backupExample1Desc": "# Complete interactive process",
   "help.commands.backupExample2": "npx smoonb backup --skip-realtime",
   "help.commands.backupExample2Desc": "# Skips Realtime Settings configuration",
+  "help.commands.backupExample3": "npx smoonb backup --skip-supabase-version-check",
+  "help.commands.backupExample3Desc": "# Skips Supabase CLI version check (use when your package manager lags behind, e.g. Scoop)",
   "help.commands.backupWhat": "What is captured:",
   "help.commands.backupWhat1": "• Database PostgreSQL (pg_dumpall + separate SQL)",
   "help.commands.backupWhat2": "• Database Extensions and Settings",
@@ -206,6 +211,8 @@
   "help.commands.restoreExample2Desc": "# Imports and restores backup file directly",
   "help.commands.restoreExample3": "npx smoonb restore --file \"backup.backup.gz\" --storage \"my-project.storage.zip\"",
   "help.commands.restoreExample3Desc": "# Imports and restores backup and storage together",
+  "help.commands.restoreExample4": "npx smoonb restore --skip-supabase-version-check",
+  "help.commands.restoreExample4Desc": "# Skips Supabase CLI version check (use when your package manager lags behind, e.g. Scoop)",
   "help.commands.restoreFlow": "Restore flow:",
   "help.commands.restoreFlow1": "1. Terms of use",
   "help.commands.restoreFlow2": "2. License validation (SMOONB_LICENSE_KEY)",
@@ -428,9 +435,16 @@
   "backup.steps.storage.found": "Found {count} buckets",
   "backup.steps.storage.processing": "Processing bucket: {bucketName}",
   "backup.steps.storage.listingFiles": "Listing files from bucket {bucketName}...",
+  "backup.steps.storage.scanningFolder": "Scanning {path} ({count} found)",
+  "backup.steps.storage.totalFound": "Total: {count} file(s) found",
+  "backup.steps.storage.listRetry": "Attempt {attempt}/{max} to list {path} failed ({message}). Retrying in {delay}s...",
+  "backup.steps.storage.listFailed": "Failed to list bucket {bucketName} after all attempts: {message}",
   "backup.steps.storage.downloading": "Downloading {count} file(s) from bucket {bucketName}...",
   "backup.steps.storage.downloaded": "Downloaded {current}/{total} file(s)...",
+  "backup.steps.storage.downloadRetry": "File {path}: attempt {attempt}/{max} failed. Retrying in {delay}s...",
+  "backup.steps.storage.downloadFailed": "File {path}: failed after all attempts: {message}",
   "backup.steps.storage.bucketDone": "Bucket {bucketName}: {downloaded}/{total} file(s) downloaded",
+  "backup.steps.storage.bucketDoneWithSkips": "Bucket {bucketName}: {downloaded}/{total} file(s) downloaded, {skipped} skipped",
   "backup.steps.storage.creatingZip": "Creating ZIP file in Dashboard format...",
   "backup.steps.storage.zipCreated": "ZIP file created: {fileName} ({size} MB)",
   "backup.steps.storage.cleanup": "Do you want to clean storage_temp after backup",

package/src/i18n/locales/pt-BR.json

@@ -72,8 +72,10 @@
   "supabase.installLink": "Instalação: npm install -g supabase",
   "supabase.required": "Supabase CLI é obrigatório para backup completo do Supabase",
   "supabase.requiredComponents": "Supabase CLI é obrigatório para backup completo do Supabase\n   - Database PostgreSQL\n   - Edge Functions\n   - Todos os componentes via Docker",
-  "supabase.cliUpdateRecommended": "Supabase CLI {version} detectado. Recomendamos v2.72 ou mais recente para novos recursos e correções: https://supabase.com/docs/guides/cli/getting-started#updating-the-supabase-cli",
-  "supabase.cliOutdated": "Supabase CLI {version} não é a versão mais recente ({latest}). Atualize para a última versão.",
+  "supabase.cliVersionPolicy": "Política de versão: aceita qualquer versão até 1 minor atrás da latest (mesma major). Use --skip-supabase-version-check para pular a checagem.",
+  "supabase.cliUpdateRecommended": "Supabase CLI {version} detectado. Recomendamos sempre usar a versão mais recente para obter novos recursos e correções: https://supabase.com/docs/guides/cli/getting-started#updating-the-supabase-cli",
+  "supabase.cliOutdated": "Supabase CLI {version} está abaixo da versão mínima aceita ({minVersion}). Versão latest: {latest}. Atualize para pelo menos a versão {minVersion}.",
+  "supabase.cliVersionSkipWarning": "Checagem de versão do Supabase CLI desabilitada (--skip-supabase-version-check). Prosseguindo sem verificar a versão — o usuário assume o risco.",
   "supabase.cliUpdateInstructions": "Atualize o Supabase CLI e execute o smoonb novamente:",
   "supabase.cliUpdateCommandExamples": "Exemplos (conforme a forma de instalação):",
   "supabase.cliUpdateCommandGlobal": "npm install -g supabase@latest   (global)",
@@ -166,6 +168,7 @@
   "help.tip5": "• O formato do arquivo de storage deve ser: *.storage.zip",
 
   "help.commands.backupDesc": "Fazer backup completo do projeto Supabase usando Supabase CLI",
+  "help.commands.skipSupabaseVersionCheck": "Pular checagem de versão do Supabase CLI (o usuário assume o risco)",
   "help.commands.backupSkipRealtime": "Pular captura interativa de Realtime Settings",
   "help.commands.backupPostgresMajor": "Versão major do Postgres para o dump (15, 17). Não interativo; sem menu.",
   "help.commands.backupExamples": "Exemplos:",
@@ -173,6 +176,8 @@
   "help.commands.backupExample1Desc": "# Processo interativo completo",
   "help.commands.backupExample2": "npx smoonb backup --skip-realtime",
   "help.commands.backupExample2Desc": "# Pula configuração de Realtime Settings",
+  "help.commands.backupExample3": "npx smoonb backup --skip-supabase-version-check",
+  "help.commands.backupExample3Desc": "# Pula checagem de versão do Supabase CLI (use quando seu gerenciador de pacotes instala com atraso, ex.: Scoop)",
   "help.commands.backupWhat": "O que é capturado:",
   "help.commands.backupWhat1": "• Database PostgreSQL (pg_dumpall + SQL separado)",
   "help.commands.backupWhat2": "• Database Extensions and Settings",
@@ -206,6 +211,8 @@
   "help.commands.restoreExample2Desc": "# Importa e restaura diretamente o arquivo de backup",
   "help.commands.restoreExample3": "npx smoonb restore --file \"backup.backup.gz\" --storage \"meu-projeto.storage.zip\"",
   "help.commands.restoreExample3Desc": "# Importa e restaura backup e storage juntos",
+  "help.commands.restoreExample4": "npx smoonb restore --skip-supabase-version-check",
+  "help.commands.restoreExample4Desc": "# Pula checagem de versão do Supabase CLI (use quando seu gerenciador de pacotes instala com atraso, ex.: Scoop)",
   "help.commands.restoreFlow": "Fluxo do restore:",
   "help.commands.restoreFlow1": "1. Termo de uso",
   "help.commands.restoreFlow2": "2. Validação de licença (SMOONB_LICENSE_KEY)",
@@ -428,9 +435,16 @@
   "backup.steps.storage.found": "Encontrados {count} buckets",
   "backup.steps.storage.processing": "Processando bucket: {bucketName}",
   "backup.steps.storage.listingFiles": "Listando arquivos do bucket {bucketName}...",
+  "backup.steps.storage.scanningFolder": "Escaneando {path} ({count} encontrado(s))",
+  "backup.steps.storage.totalFound": "Total: {count} arquivo(s) encontrado(s)",
+  "backup.steps.storage.listRetry": "Tentativa {attempt}/{max} ao listar {path} falhou ({message}). Retentando em {delay}s...",
+  "backup.steps.storage.listFailed": "Falha ao listar bucket {bucketName} após {max} tentativas: {message}",
   "backup.steps.storage.downloading": "Baixando {count} arquivo(s) do bucket {bucketName}...",
   "backup.steps.storage.downloaded": "Baixados {current}/{total} arquivo(s)...",
+  "backup.steps.storage.downloadRetry": "Arquivo {path}: tentativa {attempt}/{max} falhou. Retentando em {delay}s...",
+  "backup.steps.storage.downloadFailed": "Arquivo {path}: falhou após todas as tentativas: {message}",
   "backup.steps.storage.bucketDone": "Bucket {bucketName}: {downloaded}/{total} arquivo(s) baixado(s)",
+  "backup.steps.storage.bucketDoneWithSkips": "Bucket {bucketName}: {downloaded}/{total} arquivo(s) baixado(s), {skipped} pulado(s)",
   "backup.steps.storage.creatingZip": "Criando arquivo ZIP no padrão do Dashboard...",
   "backup.steps.storage.zipCreated": "Arquivo ZIP criado: {fileName} ({size} MB)",
   "backup.steps.storage.cleanup": "Deseja limpar storage_temp após o backup",

package/src/utils/docker.js

@@ -100,6 +100,21 @@ function compareSemver(a, b) {
   return 0;
 }
 
+/**
+ * Calcula a versão mínima aceita: no máximo 1 minor atrás da latest.
+ * Ex: latest "2.76.12" → "2.75.0"; latest "3.0.5" → "3.0.0"
+ * @param {string} latestVersion
+ * @returns {string|null}
+ */
+function getMinAcceptableVersion(latestVersion) {
+  if (!latestVersion) return null;
+  const parts = latestVersion.split('.').map(Number);
+  const major = parts[0] || 0;
+  const minor = parts[1] || 0;
+  const minMinor = Math.max(0, minor - 1);
+  return `${major}.${minMinor}.0`;
+}
+
 /**
  * Detecta Docker Desktop completo com versão
  * @returns {Promise<{installed: boolean, running: boolean, version: string}>}
@@ -159,9 +174,11 @@ async function detectDockerDependencies() {
 
 /**
  * Detecta se é possível fazer backup completo via Docker
+ * @param {object} [opts]
+ * @param {boolean} [opts.skipSupabaseVersionCheck=false] - Pular checagem de versão do Supabase CLI
  * @returns {Promise<{canBackupComplete: boolean, reason?: string, dockerStatus: any}>}
  */
-async function canPerformCompleteBackup() {
+async function canPerformCompleteBackup({ skipSupabaseVersionCheck = false } = {}) {
   const dockerStatus = await detectDockerDesktop();
   
   if (!dockerStatus.installed) {
@@ -189,6 +206,14 @@ async function canPerformCompleteBackup() {
     };
   }
 
+  if (skipSupabaseVersionCheck) {
+    return {
+      canBackupComplete: true,
+      supabaseVersionCheckSkipped: true,
+      dockerStatus
+    };
+  }
+
   const supabaseCliVersion = await getSupabaseCLIVersion();
   const latestResult = await getSupabaseCLILatestVersion();
   if (latestResult.error) {
@@ -200,12 +225,15 @@ async function canPerformCompleteBackup() {
       dockerStatus
     };
   }
-  if (supabaseCliVersion && latestResult.version && compareSemver(supabaseCliVersion, latestResult.version) < 0) {
+
+  const minVersion = getMinAcceptableVersion(latestResult.version);
+  if (supabaseCliVersion && minVersion && compareSemver(supabaseCliVersion, minVersion) < 0) {
     return {
       canBackupComplete: false,
       reason: 'supabase_cli_outdated',
       supabaseCliVersion,
       supabaseCliLatest: latestResult.version,
+      supabaseCliMinVersion: minVersion,
       dockerStatus
     };
   }
@@ -226,5 +254,6 @@ module.exports = {
   getSupabaseCLIVersion,
   getSupabaseCLILatestVersion,
   compareSemver,
+  getMinAcceptableVersion,
   canPerformCompleteBackup
 };