smoonb 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.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
+
+### 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
+
+---
+
 ## [1.0.0] - 2025-01-29
 
 ### Added
@@ -27,4 +52,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+[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

@@ -40,23 +40,26 @@ By continuing, you acknowledge and agree that Supa Moonbase (smoonb) is provided
 
 **⚠️ IMPORTANT: Install ONLY locally in the project!**
 
+**Install locally in the project:**
 ```bash
-# ✅ CORRECT - Install locally in the project
 npm install smoonb
+```
 
-# ✅ CORRECT - Use with npx
+**Use with npx:**
+```bash
 npx smoonb --help
+```
 
-# ❌ WRONG - DO NOT install globally
-npm install -g smoonb  # ← This will be blocked!
+**Do not install globally** (blocked):
+```bash
+npm install -g smoonb
 ```
 
 ### 🔄 Update to Latest Version
 
-To update smoonb to the latest available version:
+To update smoonb to the latest available version, run in the current project:
 
 ```bash
-# Update in current project
 npm install smoonb@latest
 ```
 
@@ -71,12 +74,10 @@ npm install smoonb@latest
 ## 📋 Prerequisites
 
 ### 1. Docker Desktop (REQUIRED)
-```bash
-# Install Docker Desktop
-# Windows/macOS: https://docs.docker.com/desktop/install/
-# Linux: https://docs.docker.com/engine/install/
 
-# Verify if it's running
+Install from [Docker Desktop](https://docs.docker.com/desktop/install/) (Windows/macOS) or [Docker Engine](https://docs.docker.com/engine/install/) (Linux). Then verify it is running:
+
+```bash
 docker --version
 docker ps
 ```
@@ -117,39 +118,26 @@ You need to obtain a Supabase personal access token to use the Management API:
 #### 1. Create or edit `.env.local` in the project root
 
 ```bash
-# Create .env.local file
 touch .env.local
 ```
 
 #### 2. Add required environment variables
 
 ```env
-# License (REQUIRED – from https://www.smoonb.com desktop app)
 SMOONB_LICENSE_KEY=[your-license-key]
-
-# Supabase URLs and Keys
 NEXT_PUBLIC_SUPABASE_URL=[your-supabase-url]
 NEXT_PUBLIC_SUPABASE_ANON_KEY=[your-anon-key]
 SUPABASE_SERVICE_ROLE_KEY=[your-service-role]
-
-# Database Connection
 SUPABASE_DB_URL=postgresql://postgres:[your-database-password]@db.[your-project-id].supabase.co:5432/postgres
-
-# Project Identification
 SUPABASE_PROJECT_ID=[your-project-id]
-
-# Personal Access Token (REQUIRED for Management API)
 SUPABASE_ACCESS_TOKEN=[your-access-token]
-
-# Postgres major version (REQUIRED for backup and restore). Check in Dashboard: Project Settings -> Infrastructure -> Service Versions (Postgres line).
 SUPABASE_POSTGRES_MAJOR=17
-
-# Optional
 SMOONB_TELEMETRY_ENABLED=true
-# Backup Directory (optional, default: ./backups)
 SMOONB_OUTPUT_DIR=./backups
 ```
 
+Required: `SMOONB_LICENSE_KEY` (from [smoonb.com](https://www.smoonb.com) desktop app), `SUPABASE_POSTGRES_MAJOR` (e.g. 17; see Dashboard → Project Settings → Infrastructure → Service Versions). Optional: `SMOONB_TELEMETRY_ENABLED`, `SMOONB_OUTPUT_DIR` (default `./backups`).
+
 #### 3. Interactive Mapping
 
 When running `backup` or `restore` for the first time, **smoonb** will:
@@ -179,69 +167,15 @@ Is this the correct value for the target project? (Y/n): Y
 
 Language is detected automatically in the following order of precedence:
 
-1. **CLI flag `--lang`** (highest priority)
-   ```bash
-   npx smoonb --lang pt-BR backup
-   npx smoonb --lang en restore
-   ```
-
-2. **Environment variable `SMOONB_LANG`**
-   ```bash
-   # Windows PowerShell
-   $env:SMOONB_LANG="pt-BR"
-   npx smoonb backup
-   
-   # Linux/macOS
-   export SMOONB_LANG=pt-BR
-   npx smoonb backup
-   ```
-
-3. **System locale** (LANG, LC_ALL, LC_MESSAGES)
-   ```bash
-   # smoonb automatically detects system locale
-   # Example: LANG=pt_BR.UTF-8 → pt-BR
-   # Example: LANG=en_US.UTF-8 → en
-   ```
-
-4. **Fallback to English (en)** if none of the above are detected
+1. **Environment variable `SMOONB_LANG`** (in `.env.local` or in the environment)
+2. **System locale** (LANG, LC_ALL, LC_MESSAGES). Example: `LANG=pt_BR.UTF-8` → pt-BR
+3. **Fallback to English (en)** if none of the above are detected
 
 ### Supported Languages and Aliases
 
-smoonb accepts the following language codes:
-
 - `en` or `en-US` → English
 - `pt-BR`, `pt_BR` or `pt` → Portuguese (Brazil)
 
-### Usage Examples
-
-**Force Portuguese:**
-```bash
-npx smoonb --lang pt-BR backup
-```
-
-**Force English:**
-```bash
-npx smoonb --lang en restore
-```
-
-**Use environment variable:**
-```bash
-# Windows PowerShell
-$env:SMOONB_LANG="pt-BR"
-npx smoonb check
-
-# Linux/macOS
-export SMOONB_LANG=en
-npx smoonb check
-```
-
-**Automatic system detection:**
-```bash
-# If system is configured with LANG=pt_BR.UTF-8
-# smoonb will automatically use Portuguese
-npx smoonb backup
-```
-
 ### Important Notes
 
 - **Machine outputs** (e.g., `--json` if implemented) are **not** translated; fields and keys remain in English
@@ -284,30 +218,31 @@ npx smoonb backup
    - 📁 9/10 - Supabase .temp Backup (if selected)
    - 📋 10/10 - Migrations Backup (if selected)
 
-**Result:**
+**Result:** A folder `backups/backup-YYYY-MM-DD-HH-MM-SS/` containing for example:
+
 ```
 backups/backup-2025-10-31-09-37-54/
-├── backup-manifest.json           # Manifest with metadata
-├── db_cluster-31-10-2025@09-38-57.backup.gz  # Full backup (Dashboard compatible)
-├── schema.sql                     # Database schema
-├── data.sql                       # Data
-├── roles.sql                      # PostgreSQL roles
-├── database-settings-*.json       # Extensions and settings
-├── auth-settings.json             # Auth configurations
-├── realtime-settings.json         # Realtime configurations
-├── storage/                       # Storage metadata
-│   └── [bucket-name].json         # Metadata for each bucket
-├── [project-id].storage.zip       # Full Storage backup (Dashboard format)
-├── storage_temp/                  # Temporary structure (optional, can be removed)
-│   └── [project-id]/              # Downloaded files structure
-│       └── [bucket-name]/        # Files for each bucket
-├── edge-functions/                # Downloaded Edge Functions
+├── backup-manifest.json
+├── db_cluster-31-10-2025@09-38-57.backup.gz
+├── schema.sql
+├── data.sql
+├── roles.sql
+├── database-settings-*.json
+├── auth-settings.json
+├── realtime-settings.json
+├── storage/
+│   └── [bucket-name].json
+├── [project-id].storage.zip
+├── storage_temp/
+│   └── [project-id]/
+│       └── [bucket-name]/
+├── edge-functions/
 │   └── [function-name]/
-├── supabase-temp/                 # Supabase CLI .temp files
-├── migrations/                    # All migrations
+├── supabase-temp/
+├── migrations/
 └── env/
-    ├── .env.local                 # .env.local backup
-    └── env-map.json               # Variable mapping
+    ├── .env.local
+    └── env-map.json
 ```
 
 ### Interactive Restoration
@@ -317,15 +252,6 @@ backups/backup-2025-10-31-09-37-54/
 npx smoonb restore
 ```
 
-**Import and restore directly from Dashboard:**
-```bash
-# Database only
-npx smoonb restore --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz"
-
-# Database and storage together
-npx smoonb restore --file "backup.backup.gz" --storage "my-project.storage.zip"
-```
-
 **Interactive restore flow:**
 
 1. **Terms of use** - Displays and requests acceptance of terms
@@ -334,9 +260,7 @@ npx smoonb restore --file "backup.backup.gz" --storage "my-project.storage.zip"
 4. **Consent** - Asks permission to read/write `.env.local`
 5. **Variable mapping** - Maps variables to target project (includes `SUPABASE_POSTGRES_MAJOR`)
 6. **.env.local backup** - Creates automatic backup
-7. **Backup selection** - Lists and allows choosing which backup to restore (skips if `--file` provided)
-   - If `--file` is provided: automatically imports and auto-selects the backup
-   - If `--storage` is provided along with `--file`: also imports the storage file
+7. **Backup selection** - Lists and allows choosing which backup to restore
 8. **Component selection** - Asks which components to restore:
    - 📊 Database (always available)
    - ⚡ Edge Functions (if available in backup)
@@ -359,12 +283,6 @@ npx smoonb restore --file "backup.backup.gz" --storage "my-project.storage.zip"
 - ✅ `.backup.gz` (compressed) - Automatically decompresses before restoring
 - ✅ `.backup` (uncompressed) - Restores directly
 
-**When to use `--file`:**
-- Automatically imports backup file before restoring
-- Eliminates backup selection step
-- If `--storage` provided, also imports storage file
-- Useful for restoring backups downloaded directly from Supabase Dashboard
-
 ### Import Backup from Supabase Dashboard
 
 If you downloaded a backup directly from the Supabase Dashboard (`.backup.gz` format), you can import it to the format expected by smoonb. The command also supports optionally importing storage files (`.storage.zip`).
@@ -389,52 +307,28 @@ npx smoonb import --file "backup.backup.gz" --storage "my-project.storage.zip"
 7. Makes backup ready to be found by `restore` command
 
 **Complete example - Database only (using import + restore):**
-```bash
-# 1. Download backup from Supabase Dashboard
-#    File: db_cluster-04-03-2024@14-16-59.backup.gz
 
-# 2. Import the file
-npx smoonb import --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz"
+1. Download backup from Supabase Dashboard (e.g. `db_cluster-04-03-2024@14-16-59.backup.gz`).
+2. Import the file, then restore:
 
-# 3. Restore the imported backup
+```bash
+npx smoonb import --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz"
 npx smoonb restore
-# The imported backup will appear in the list of available backups
 ```
 
-**Complete example - Database only (using restore directly):**
-```bash
-# 1. Download backup from Supabase Dashboard
-#    File: db_cluster-04-03-2024@14-16-59.backup.gz
-
-# 2. Import and restore directly (skips backup selection)
-npx smoonb restore --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz"
-```
+The imported backup will appear in the list of available backups.
 
 **Complete example - Database and Storage (using import + restore):**
-```bash
-# 1. Download backup and storage from Supabase Dashboard
-#    Files: 
-#    - db_cluster-04-03-2024@14-16-59.backup.gz
-#    - my-project.storage.zip
 
-# 2. Import both files
-npx smoonb import --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz" --storage "C:\Downloads\my-project.storage.zip"
+1. Download backup and storage from Supabase Dashboard (e.g. `db_cluster-04-03-2024@14-16-59.backup.gz` and `my-project.storage.zip`).
+2. Import both files, then restore:
 
-# 3. Restore the imported backup
+```bash
+npx smoonb import --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz" --storage "C:\Downloads\my-project.storage.zip"
 npx smoonb restore
-# The imported backup will appear in the list of available backups
 ```
 
-**Complete example - Database and Storage (using restore directly):**
-```bash
-# 1. Download backup and storage from Supabase Dashboard
-#    Files: 
-#    - db_cluster-04-03-2024@14-16-59.backup.gz
-#    - my-project.storage.zip
-
-# 2. Import and restore directly (skips backup selection)
-npx smoonb restore --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz" --storage "C:\Downloads\my-project.storage.zip"
-```
+The imported backup will appear in the list of available backups.
 
 **Important:**
 - Backup file is **required** and must be in Dashboard format: `db_cluster-DD-MM-YYYY@HH-MM-SS.backup.gz`
@@ -444,24 +338,7 @@ npx smoonb restore --file "C:\Downloads\db_cluster-04-03-2024@14-16-59.backup.gz
 - Path can be absolute or relative
 - Command will automatically create necessary folder structure
 
-**Difference between `import` and `restore --file`:**
-- `import`: Only imports the file and creates backup structure. You need to run `restore` afterwards.
-- `restore --file`: Automatically imports the file and starts the restoration process, skipping the backup selection step.
-
-### Post-Restore Verification
-
-```bash
-npx smoonb check
-```
-
-**Verifies:**
-- ✅ Database connection
-- ✅ Installed extensions
-- ✅ Created tables
-- ✅ RLS policies
-- ✅ Realtime publications
-- ✅ Storage buckets
-
+After running `import`, run `restore` to choose the imported backup from the list and restore it.
 
 ## 🔧 Available Commands
 
@@ -469,9 +346,7 @@ npx smoonb check
 |---------|-------------|
 | `npx smoonb backup` | Full interactive backup using Docker |
 | `npx smoonb restore` | Interactive restoration using psql (Docker) |
-| `npx smoonb restore --file <path> [--storage <path>]` | Import and restore directly .backup.gz file and optionally .storage.zip from Dashboard |
 | `npx smoonb import --file <path> [--storage <path>]` | Import .backup.gz file and optionally .storage.zip from Supabase Dashboard |
-| `npx smoonb check` | Post-restore integrity verification |
 
 ## 🏗️ Technical Architecture
 
@@ -482,39 +357,39 @@ The code has been refactored to a **modular architecture** with independent step
 #### Backup (`src/commands/backup/`)
 ```
 backup/
-├── index.js                    # Orquestrador principal
-├── utils.js                    # Utilitários específicos
+├── index.js
+├── utils.js
 └── steps/
-    ├── 00-license.js           # Validação de licença (SMOONB_LICENSE_KEY)
-    ├── 01-docker-validation.js # Validação Docker
-    ├── 02-database.js          # Backup via pg_dumpall
-    ├── 03-database-separated.js # SQL separado
-    ├── 04-database-settings.js # Extensões e settings
-    ├── 05-auth-settings.js     # Auth via API
-    ├── 06-realtime-settings.js # Realtime interativo
-    ├── 07-storage.js           # Storage via API
-    ├── 08-custom-roles.js      # Custom roles
-    ├── 09-edge-functions.js    # Edge Functions
-    ├── 10-supabase-temp.js     # Supabase .temp
-    └── 11-migrations.js        # Migrations
+    ├── 00-license.js
+    ├── 01-docker-validation.js
+    ├── 02-database.js
+    ├── 03-database-separated.js
+    ├── 04-database-settings.js
+    ├── 05-auth-settings.js
+    ├── 06-realtime-settings.js
+    ├── 07-storage.js
+    ├── 08-custom-roles.js
+    ├── 09-edge-functions.js
+    ├── 10-supabase-temp.js
+    └── 11-migrations.js
 ```
 
 #### Restore (`src/commands/restore/`)
 License validation (same as backup, `00-license.js` from backup steps) runs at start. Then:
 ```
 restore/
-├── index.js                    # Orquestrador principal
-├── utils.js                    # Utilitários específicos
+├── index.js
+├── utils.js
 └── steps/
-    ├── 00-backup-selection.js  # Seleção de backup
-    ├── 01-components-selection.js # Seleção de componentes
-    ├── 02-confirmation.js      # Confirmação (legacy)
-    ├── 03-database.js          # Restauração database
-    ├── 04-edge-functions.js    # Deploy Edge Functions
-    ├── 05-auth-settings.js     # Exibe Auth settings
-    ├── 06-storage.js           # Exibe Storage info
-    ├── 07-database-settings.js # Restaura settings
-    └── 08-realtime-settings.js # Exibe Realtime settings
+    ├── 00-backup-selection.js
+    ├── 01-components-selection.js
+    ├── 02-confirmation.js
+    ├── 03-database.js
+    ├── 04-edge-functions.js
+    ├── 05-auth-settings.js
+    ├── 06-storage.js
+    ├── 07-database-settings.js
+    └── 08-realtime-settings.js
 ```
 
 ### Backup Strategy
@@ -587,42 +462,26 @@ restore/
 
 ## 📊 Recommended Flow
 
-```bash
-# 1. Configure .env.local (first time)
-# Edit .env.local with your source project credentials
-
-# 2. Backup source project
-npx smoonb backup
-# - Maps variables interactively (first time)
-# - Selects components for backup
-# - Executes full backup
-
-# 3. Create new Supabase project
-# (via Dashboard or Supabase CLI)
-
-# 4. Edit .env.local with new project credentials
-# Update variables to point to target project
-
-# 5. Restore backup (interactive mode)
-npx smoonb restore
-# - Selects desired backup
-# - Selects components to restore
-# - Executes restoration
-
-# 6. Verify integrity
-npx smoonb check
-
-# 7. Apply manual configurations (if necessary)
-# - Auth Settings: Dashboard → Authentication → Settings
-# - Realtime: Dashboard → Database → Replication
-# Note: Storage is automatically restored from ZIP if available
-```
+1. **Configure `.env.local`** (first time) with your source project credentials.
+2. **Backup source project:**
+   ```bash
+   npx smoonb backup
+   ```
+   (Maps variables interactively on first run, selects components, executes full backup.)
+3. **Create new Supabase project** (via Dashboard or Supabase CLI).
+4. **Edit `.env.local`** with new project credentials (point variables to target project).
+5. **Restore backup** (interactive mode):
+   ```bash
+   npx smoonb restore
+   ```
+   (Select desired backup, select components, execute restoration.)
+6. **Apply manual configurations** if necessary: Auth Settings (Dashboard → Authentication → Settings), Realtime (Dashboard → Database → Replication). Storage is restored automatically from ZIP when available.
 
 ## 🎨 User Experience
 
 ### Multi-Language Interface
 
-All interactions are **automatically translated** based on system locale or `--lang` flag:
+All interactions are **automatically translated** based on system locale or `SMOONB_LANG`:
 - Clear and direct questions
 - Explanations before each process
 - Detailed summaries before confirming
@@ -645,18 +504,16 @@ All interactions are **automatically translated** based on system locale or `--l
 ## 🐛 Troubleshooting
 
 ### Docker not found or not running
+
+Verify Docker is installed and running:
+
 ```bash
-# Verify if Docker is installed
 docker --version
-
-# Verify if Docker Desktop is running
 docker ps
-
-# If not, start Docker Desktop
-# Windows/macOS: Open Docker Desktop application
-# Linux: sudo systemctl start docker
 ```
 
+If not, start Docker Desktop (Windows/macOS) or run `sudo systemctl start docker` (Linux).
+
 ### Supabase CLI not found
 ```bash
 npm install -g supabase