### Clone and Install Repository

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Initial steps to clone the repository and install necessary dependencies.

```bash
git clone https://github.com/Innovate-group/tiendanubecli.git
cd tiendanubecli
```

```bash
npm install
```

--------------------------------

### Initialize Tienda Nube CLI Setup

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Run the interactive setup wizard to configure FTP credentials and create the .env configuration file and local theme directory.

```bash
# Run the interactive setup
tiendanube init

# The wizard prompts for:
# - FTP Host (default: ftp.tiendanube.com)
# - FTP Username
# - FTP Password
# - FTP Port (default: 21)
# - FTP Base Path (default: /)
# - Connection Timeout (default: 30000ms)
# - Debug mode (true/false)

# After successful setup, the following files are created:
# .env - FTP configuration
# theme/ - Local theme directory

# Example .env file created:
# FTP_HOST=ftp.tiendanube.com
# FTP_USER=mystore123
# FTP_PASSWORD=secretpassword
# FTP_PORT=21
# FTP_SECURE=true
# FTP_BASE_PATH=/
# FTP_TIMEOUT=30000
# DEBUG=false
```

--------------------------------

### Initialize Configuration

Source: https://github.com/innovate-group/tiendanubecli/blob/main/README.md

Run the interactive setup wizard to configure FTP credentials and create a .env file.

```bash
tiendanube init
```

--------------------------------

### Install the CLI

Source: https://github.com/innovate-group/tiendanubecli/blob/main/README.md

Commands to install the package globally or as a development dependency.

```bash
npm install -g tiendanubecli
```

```bash
npm install --save-dev tiendanubecli
```

--------------------------------

### Tienda Nube CLI - Initialization

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

The `tiendanube init` command runs an interactive setup wizard to configure FTP credentials, validate the connection, and create the `.env` configuration file and local `theme/` directory.

```APIDOC
## tiendanube init

### Description
Interactive setup wizard that prompts for FTP credentials, validates the connection, and creates a `.env` configuration file. It also creates the local `theme/` directory if it doesn't exist.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### CLI Arguments
- `tiendanube init`: Runs the interactive setup wizard.

### Prompts
- **FTP Host** (string) - Optional - Default: `ftp.tiendanube.com`
- **FTP Username** (string) - Required
- **FTP Password** (string) - Required
- **FTP Port** (integer) - Optional - Default: `21`
- **FTP Base Path** (string) - Optional - Default: `/`
- **Connection Timeout** (integer) - Optional - Default: `30000ms`
- **Debug mode** (boolean) - Optional - Default: `false`

### Output Files
- `.env`: FTP configuration file.
- `theme/`: Local theme directory.

### Example .env file created
```
FTP_HOST=ftp.tiendanube.com
FTP_USER=mystore123
FTP_PASSWORD=secretpassword
FTP_PORT=21
FTP_SECURE=true
FTP_BASE_PATH=/
FTP_TIMEOUT=30000
DEBUG=false
```
```

--------------------------------

### GitHub Actions for Deployment

Source: https://github.com/innovate-group/tiendanubecli/blob/main/ROADMAP.md

Example GitHub Actions workflows for automating deployments to test and production environments based on branch pushes.

```yaml
# .github/workflows/deploy-test.yml
name: Deploy to Test Environment
on:
  push:
    branches: [ develop, feature/* ]
```

```yaml
# .github/workflows/deploy-prod.yml
name: Deploy to Production
on:
  push:
    branches: [ main ]
```

--------------------------------

### CLI Usage Commands

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Commands for interacting with the Tienda Nube CLI after installation.

```bash
# Interactive setup (creates .env file)
tiendanube init

# Start file monitoring and auto-sync to FTP
tiendanube watch

# Download entire theme from FTP server to local ./theme folder
tiendanube download

# Upload entire local theme to FTP server
tiendanube push

# Download a specific file from FTP server
tiendanube download-file <remote-path>

# Validate configuration files
tiendanube check

# Show help
tiendanube --help

# Show version
tiendanube --version
```

--------------------------------

### Configure CLI using .env file

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

The CLI reads configuration from a .env file in the project root. This file allows setting FTP connection details, timeouts, and debug logging. Use 'tiendanube init' for interactive setup or create the file manually.

```bash
# .env file configuration

# Required: FTP server hostname
FTP_HOST=ftp.tiendanube.com

# Required: FTP username
FTP_USER=mystore123

# Required: FTP password
FTP_PASSWORD=secretpassword

# Optional: FTP port (default: 21)
FTP_PORT=21

# Optional: Use secure FTPS connection (default: false)
FTP_SECURE=true

# Optional: Remote base path (default: /)
FTP_BASE_PATH=/

# Optional: Connection timeout in milliseconds (default: 30000)
FTP_TIMEOUT=30000

# Optional: Enable verbose debug logging (default: false)
DEBUG=true
```

--------------------------------

### Enable Debug Mode

Source: https://github.com/innovate-group/tiendanubecli/blob/main/README.md

Enable verbose logging for detailed FTP protocol logs to help identify connection issues. This can be set in the .env file or during `tiendanube init` setup.

```env
DEBUG=true
```

--------------------------------

### Start Tienda Nube CLI Watch Mode

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Initiates the file watcher to monitor the local theme directory and automatically synchronize changes to the FTP server. Uses debouncing and prioritization for efficient updates.

```bash
# Start watching for file changes
tiendanube watch

# Output:
# === 🔄 FTP SYNCHRONIZATION SYSTEM ===
# Monitoring changes in: /path/to/project/theme
# Changes will be automatically synchronized with FTP
# 🛑 Press Ctrl+C to stop.

# When files change:
# 📝 [ADDED] Local file: templates/product.tpl
# ✅ File uploaded: /templates/product.tpl

# 🔄 [CHANGE] File modified: static/css/main.css
# ✅ File uploaded: /static/css/main.css

# ❌ [DELETED] File deleted: snipplets/old-component.tpl
# ✅ File deleted: /snipplets/old-component.tpl

# 📁 [FOLDER ADDED] New folder: static/images/new
# ✅ Directory created: /static/images/new

# Queue statistics (shown periodically):
# 📤 Queue: 2 processing, 5 pending | Total: 47 completed, 0 failed

# Graceful shutdown with Ctrl+C:
# 🛑 Closing application...
# Draining 3 remaining tasks...
# ✅ System stopped successfully
```

--------------------------------

### Tienda Nube CLI - Watch Mode

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

The `tiendanube watch` command starts a file watcher that monitors the `theme/` folder for changes and automatically synchronizes them to the FTP server. It supports debouncing, prioritization, and graceful shutdown.

```APIDOC
## tiendanube watch

### Description
Starts the file watcher that monitors the `theme/` folder and automatically synchronizes changes to the FTP server. Uses debouncing to batch rapid file changes and prioritizes config files over static assets.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### CLI Arguments
- `tiendanube watch`: Starts the file synchronization watcher.

### Example Usage
```bash
tiendanube watch
```

### Output Example
```
=== 🔄 FTP SYNCHRONIZATION SYSTEM ===
Monitoring changes in: /path/to/project/theme
Changes will be automatically synchronized with FTP
🛑 Press Ctrl+C to stop.

When files change:
📝 [ADDED] Local file: templates/product.tpl
✅ File uploaded: /templates/product.tpl

🔄 [CHANGE] File modified: static/css/main.css
✅ File uploaded: /static/css/main.css

❌ [DELETED] File deleted: snipplets/old-component.tpl
✅ File deleted: /snipplets/old-component.tpl

📁 [FOLDER ADDED] New folder: static/images/new
✅ Directory created: /static/images/new

Queue statistics (shown periodically):
📤 Queue: 2 processing, 5 pending | Total: 47 completed, 0 failed

Graceful shutdown with Ctrl+C:
🛑 Closing application...
Draining 3 remaining tasks...
✅ System stopped successfully
```
```

--------------------------------

### CLI Help and Version

Source: https://github.com/innovate-group/tiendanubecli/blob/main/README.md

Display help information or the current version of the CLI.

```bash
tiendanube --help
```

```bash
tiendanube --version
```

--------------------------------

### Configure Test and Production Environments

Source: https://github.com/innovate-group/tiendanubecli/blob/main/ROADMAP.md

Use these commands to initialize and manage separate FTP configurations for testing and production environments.

```bash
tiendanube init --env test     # Configure test environment
tiendanube init --env prod     # Configure production environment
```

```bash
tiendanube download --from test    # Download from Test
tiendanube push --to prod          # Upload to Production
```

```bash
tiendanube sync test prod          # Sync Test → Production
```

--------------------------------

### Configure Environment and Build

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Commands to set up environment variables, compile TypeScript, and link the CLI locally.

```bash
cp .env.example .env
```

```bash
npm run build
```

```bash
npm link
```

--------------------------------

### Migrate FTP Client Usage

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Compare legacy direct client creation with the modern FtpService approach.

```javascript
const client = await createFtpClient();
await client.uploadFrom(local, remote);
client.close();
```

```javascript
const ftpService = new FtpService();
await ftpService.uploadFile(local, remote);
// Connection stays open automatically
```

--------------------------------

### Sync and Watch Files

Source: https://github.com/innovate-group/tiendanubecli/blob/main/README.md

Commands to monitor local changes or push the entire local theme to the server.

```bash
tiendanube watch
```

```bash
tiendanube push
```

--------------------------------

### Run Tests

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Command to execute the test suite.

```bash
npm test
```

--------------------------------

### Proposed Modular Configuration Structure

Source: https://github.com/innovate-group/tiendanubecli/blob/main/ROADMAP.md

A suggested directory structure for splitting the main `settings.txt` file into modular configuration files for better organization and reusability.

```directory
config/
├── sections/
│   ├── header.txt          # Header configuration
│   ├── footer.txt          # Footer configuration
│   ├── colors.txt          # Color scheme
│   ├── typography.txt      # Font configuration
│   └── products.txt        # Product configuration
├── compiled/
│   └── settings.txt        # Final compiled file
└── defaults.txt            # Default values
```

--------------------------------

### Release Process Commands

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Commands for versioning, testing, committing, and publishing the package.

```bash
npm version patch|minor|major
```

```bash
npm test
npm run lint
```

```bash
git add package.json CHANGELOG.md
git commit -m "chore: bump version to X.Y.Z"
```

```bash
git tag -a vX.Y.Z -m "Release vX.Y.Z"
```

```bash
git push origin main --tags
```

```bash
npm login
```

```bash
npm publish
```

```bash
npm view tiendanubecli
```

--------------------------------

### Download Theme Files

Source: https://github.com/innovate-group/tiendanubecli/blob/main/README.md

Download the entire theme or a specific file from the FTP server.

```bash
tiendanube download
```

```bash
tiendanube download-file config/settings.txt
tiendanube download-file templates/product.tpl
```

--------------------------------

### Download Entire Theme from FTP

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Downloads the complete theme from the FTP server to the local `theme/` directory, recreating the directory structure. Useful for backing up or migrating themes.

```bash
# Download entire theme from FTP
tiendanube download

# Output:
# === 📥 FTP DOWNLOAD SYSTEM ===
# 📥 Starting complete FTP download...
# 🔸 Source: ftp.tiendanube.com:21/
# 🔸 Destination: /path/to/project/theme
# ✅ Access confirmed. 15 items found.
# 📂 Processing directory: config
# ⏳ Downloading: /config/settings.txt
# ✅ File downloaded: config/settings.txt
# ⏳ Downloading: /config/defaults.txt
# ✅ File downloaded: config/defaults.txt
# 📂 Processing directory: templates
# ⏳ Downloading: /templates/home.tpl
# ✅ File downloaded: templates/home.tpl
# ...
# ✅ Complete download finished
# 📂 Files downloaded to: /path/to/project/theme
# ✅ Operation completed
```

--------------------------------

### Upload Entire Local Theme to FTP

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Uploads the entire local theme directory to the FTP server. It performs checksum comparisons to avoid uploading unchanged files, optimizing the process.

```bash
# Upload entire local theme to FTP
tiendanube push

# Output:
# === 📤 FTP UPLOAD SYSTEM ===
# 📤 Starting complete FTP upload...
# 🔸 Source: /path/to/project/theme
# 🔸 Destination: ftp.tiendanube.com:21/
# ✅ Local directory verified. 15 items found.
# ✅ Remote directory verified: /
# 📁 Exploring local directory: /path/to/project/theme
# ✅ Found 15 items in /path/to/project/theme
# 📂 Processing directory: config
# ⏳ Uploading: /config/settings.txt
# ✅ File uploaded: /config/settings.txt
# ⏳ Uploading: /config/defaults.txt
# ⏭️  Skipped (unchanged): /config/defaults.txt
# ...
# ✅ Complete upload finished
# 📂 Files uploaded from: /path/to/project/theme
# ✅ Operation completed
```

--------------------------------

### Reuse FTP Connection with Manager

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Demonstrates the recommended pattern for using the FTP connection manager to reuse an active connection across multiple operations, reducing overhead. Avoid creating new connections for each operation.

```javascript
// DO: Reuse connection through manager
const client = await ftpConnectionManager.getConnection();
await client.uploadFrom(local, remote);
// Connection stays open for next operation

// DON'T: Create new connections for each operation (old pattern)
const client = new Client();
await client.access({...});
await client.uploadFrom(local, remote);
client.close(); // Wasteful!
```

--------------------------------

### Tienda Nube CLI - Download Theme

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

The `tiendanube download` command downloads the entire theme from the FTP server to the local `theme/` folder, recursively creating the necessary directory structure.

```APIDOC
## tiendanube download

### Description
Downloads the entire theme from the FTP server to the local `theme/` folder. Recursively downloads all files and directories, creating the local directory structure as needed.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### CLI Arguments
- `tiendanube download`: Initiates a full theme download from the FTP server.

### Example Usage
```bash
tiendanube download
```

### Output Example
```
=== 📥 FTP DOWNLOAD SYSTEM ===
📥 Starting complete FTP download...
🔸 Source: ftp.tiendanube.com:21/
🔸 Destination: /path/to/project/theme
✅ Access confirmed. 15 items found.
📂 Processing directory: config
⏳ Downloading: /config/settings.txt
✅ File downloaded: config/settings.txt
⏳ Downloading: /config/defaults.txt
✅ File downloaded: config/defaults.txt
📂 Processing directory: templates
⏳ Downloading: /templates/home.tpl
✅ File downloaded: templates/home.tpl
...
✅ Complete download finished
📂 Files downloaded to: /path/to/project/theme
✅ Operation completed
```
```

--------------------------------

### FTP Full Theme Download/Upload

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Recursively downloads or uploads the entire theme directory.

```APIDOC
## GET /downloadAll / POST /uploadAll

### Description
Recursively downloads or uploads the entire theme directory.

### Method
GET (downloadAll), POST (uploadAll)

### Endpoint
/downloadAll, /uploadAll

### Parameters
#### Path Parameters
- **remoteBasePath** (string) - Required - The base path on the FTP server.
- **localBasePath** (string) - Required - The base path on the local filesystem.

### Request Example
```json
// Download All
{
  "remoteBasePath": "/",
  "localBasePath": "/path/to/project/theme"
}

// Upload All
{
  "localBasePath": "/path/to/project/theme",
  "remoteBasePath": "/"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the operation completed.

#### Response Example
```json
{
  "message": "Theme downloaded successfully."
}
```

#### Error Handling
- CONNECTION_ERROR
- PERMISSION_DENIED
```

--------------------------------

### Standard Theme Directory Layout

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

The theme directory structure follows specific conventions for configuration, layouts, templates, snipplets, and static assets.

```bash
theme/
├── config/              # Theme configuration files
│   ├── settings.txt     # Theme settings definitions
│   ├── defaults.txt     # Default values for settings
│   ├── sections.txt     # Product page sections
│   ├── translations.txt # Multi-language translations
│   ├── variants.txt     # Product variant options
│   └── data.json        # Theme metadata and preview config
│
├── layouts/             # Page layouts (wrappers)
│   └── layout.tpl       # Main layout template
│
├── templates/           # Page templates
│   ├── home.tpl         # Homepage
│   ├── product.tpl      # Product detail page
│   ├── category.tpl     # Category listing
│   ├── cart.tpl         # Shopping cart
│   └── checkout.tpl     # Checkout page
│
├── snipplets/           # Reusable template components
│   ├── header.tpl       # Header component
│   ├── footer.tpl       # Footer component
│   └── product-card.tpl # Product card component
│
└── static/              # Static assets
    ├── css/             # Stylesheets
    │   └── main.css
    ├── js/              # JavaScript files
    │   └── main.js
    └── images/          # Image assets
        └── logo.png
```

--------------------------------

### Tienda Nube CLI - Push Theme

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

The `tiendanube push` command uploads the entire local theme to the FTP server. It recursively uploads files and directories, using checksum comparison to skip unchanged files.

```APIDOC
## tiendanube push

### Description
Uploads the entire local theme to the FTP server. Recursively uploads all files and directories, with checksum comparison to skip unchanged files.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### CLI Arguments
- `tiendanube push`: Initiates a full theme upload from the local directory to the FTP server.

### Example Usage
```bash
tiendanube push
```

### Output Example
```
=== 📤 FTP UPLOAD SYSTEM ===
📤 Starting complete FTP upload...
🔸 Source: /path/to/project/theme
🔸 Destination: ftp.tiendanube.com:21/
✅ Local directory verified. 15 items found.
✅ Remote directory verified: /
📁 Exploring local directory: /path/to/project/theme
✅ Found 15 items in /path/to/project/theme
📂 Processing directory: config
⏳ Uploading: /config/settings.txt
✅ File uploaded: /config/settings.txt
⏳ Uploading: /config/defaults.txt
⏭️  Skipped (unchanged): /config/defaults.txt
...
✅ Complete upload finished
📂 Files uploaded from: /path/to/project/theme
✅ Operation completed
```
```

--------------------------------

### FTP Configuration Options

Source: https://github.com/innovate-group/tiendanubecli/blob/main/README.md

Set FTP connection details and debug mode in a .env file. Ensure sensitive information like passwords is not committed to version control.

```env
FTP_HOST=your-ftp-host.com
FTP_USER=your-username
FTP_PASSWORD=your-password
FTP_PORT=21
FTP_SECURE=false
FTP_BASE_PATH=/
FTP_TIMEOUT=30000
DEBUG=false
```

--------------------------------

### Create and Remove Directories on FTP Server

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Creates or removes directories on the FTP server. No specific error handling is shown, but it's recommended to implement try-catch blocks.

```typescript
import { FtpService } from "./lib/ftp/service.js";

const ftpService = new FtpService();

// Create a new directory
await ftpService.createDirectory("/static/images/banners");
// Output: ✅ Directory created: /static/images/banners

// Remove an empty directory
await ftpService.removeDirectory("/static/images/old");
// Output: ✅ Directory deleted: /static/images/old
```

--------------------------------

### TypeScript Build Commands

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Available npm scripts for building and developing the TypeScript codebase.

```bash
# Build TypeScript to JavaScript (output in dist/)
npm run build

# Build and watch for changes (auto-rebuild)
npm run build:watch

# Development mode with tsx (no build needed)
npm run dev

# Prepare for npm publish (runs build automatically)
npm run prepublishOnly
```

--------------------------------

### Linting and Formatting Commands

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Commands to run ESLint for code linting and Prettier for code formatting. Use `lint:fix` to automatically resolve linting issues.

```bash
# Lint code with ESLint
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code with Prettier
npm run format
```

--------------------------------

### Validate Configuration

Source: https://github.com/innovate-group/tiendanubecli/blob/main/README.md

Run validation checks on theme configuration files for compliance with platform requirements.

```bash
tiendanube check
```

--------------------------------

### Testing Commands

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Commands for running tests, including watch mode and coverage reports.

```bash
# Run all tests (uses Jest with ES modules)
npm test

# Run tests in watch mode for development
npm run test:watch

# Generate test coverage report
npm run test:coverage
```

--------------------------------

### Download file from nested directory

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Use the 'download-file' command to retrieve specific files from a nested directory within your theme.

```bash
tiendanube download-file static/css/main.css
```

--------------------------------

### Recursively Download or Upload Theme Directory

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Recursively downloads or uploads the entire theme directory between the local filesystem and the FTP server. Requires proper error handling.

```typescript
import { FtpService } from "./lib/ftp/service.js";

const ftpService = new FtpService();

// Download entire theme
try {
  await ftpService.downloadAll(
    "/",                              // remoteBasePath
    "/path/to/project/theme"          // localBasePath
  );
  // Recursively downloads all files and directories
} catch (error) {
  console.error("Download failed:", error.message);
}

// Upload entire theme
try {
  await ftpService.uploadAll(
    "/path/to/project/theme",         // localBasePath
    "/"                               // remoteBasePath
  );
  // Recursively uploads all files and directories
} catch (error) {
  console.error("Upload failed:", error.message);
}

// Always shutdown when done
await ftpService.shutdown();
```

--------------------------------

### Tienda Nube CLI - Download File

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

The `tiendanube download-file` command downloads a specific file from the FTP server to its corresponding local path within the `theme/` folder.

```APIDOC
## tiendanube download-file

### Description
Downloads a specific file from the FTP server to the corresponding local path in the `theme/` folder.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### CLI Arguments
- `tiendanube download-file <ftp_file_path>`: Downloads a single file from the specified FTP path.
  - **ftp_file_path** (string) - Required - The path to the file on the FTP server.

### Example Usage
```bash
# Download a specific configuration file
tiendanube download-file config/settings.txt

# Download a template file
tiendanube download-file templates/product.tpl
```

### Output Example
```
=== 📥 FTP FILE DOWNLOAD SYSTEM ===
ℹ️  FTP file: /config/settings.txt
ℹ️  Local destination: /path/to/project/theme/config/settings.txt
✅ File downloaded: theme/config/settings.txt
✅ Operation completed
```
```

--------------------------------

### Theme Configuration Checker

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Validates theme configuration files against Tienda Nube requirements. Returns detailed validation results with errors and warnings.

```APIDOC
## check

### Description
Validates theme configuration files against Tienda Nube requirements. Returns detailed validation results with errors and warnings.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
None

### Request Example
```typescript
import { ConfigChecker, ValidationResults } from "./lib/validators/config-checker.js";

const checker = new ConfigChecker();

// Run validation on theme directory
const results: ValidationResults = await checker.check("./theme");

console.log("Success:", results.success);
console.log("Errors:", results.summary.totalErrors);
console.log("Warnings:", results.summary.totalWarnings);

// Process individual errors
results.errors.forEach(error => {
  console.log(`❌ ${error.file}`);
  if (error.line) console.log(`   Line ${error.line}`);
  console.log(`   ${error.message}`);
});

// Process warnings
results.warnings.forEach(warning => {
  console.log(`⚠️  ${warning.file}: ${warning.message}`);
});
```

### Response
#### Success Response (200)
- **results** (ValidationResults) - Object containing validation success status, errors, warnings, and summary.

#### Response Example
```json
{
  "success": false,
  "errors": [
    {
      "file": "settings.txt",
      "line": 15,
      "column": undefined,
      "message": "CRITICAL: Indentation must use tabs, not spaces.",
      "severity": "error"
    }
  ],
  "warnings": [
    {
      "file": "translations.txt",
      "message": "Missing translations for language: es_mx",
      "severity": "warning"
    }
  ],
  "summary": { "totalErrors": 1, "totalWarnings": 1 }
}
```
```

--------------------------------

### Twig Development Commands

Source: https://github.com/innovate-group/tiendanubecli/blob/main/ROADMAP.md

CLI commands for validating, linting, and optimizing Twig templates within the Tienda Nube environment.

```bash
tiendanube twig check           # Validate all templates
tiendanube twig lint            # Best practices linting
tiendanube twig variables       # List available variables
tiendanube twig optimize        # Optimization suggestions
```

--------------------------------

### Theme Directory Structure

Source: https://github.com/innovate-group/tiendanubecli/blob/main/README.md

The standard Tienda Nube / Nuvemshop theme directory includes configuration, layouts, templates, snippets, and static assets.

```tree
theme/
├── config/          # Theme configuration (settings.txt, data.json)
├── layouts/         # Page layouts (.tpl files)
├── templates/       # Page templates (home.tpl, product.tpl, cart.tpl, etc.)
├── snipplets/       # Reusable template components
└── static/          # Static assets
    ├── css/         # Stylesheets
    ├── js/          # JavaScript files
    └── images/      # Image assets
```

--------------------------------

### Run CLI with Node Inspector

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Use the Node inspector to debug the CLI process.

```bash
# Run with Node inspector
node --inspect bin/cli.js watch

# Or use VS Code launch configuration
```

--------------------------------

### Legacy npm Scripts

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Alternative npm scripts for performing common FTP operations.

```bash
# Start file monitoring and auto-sync to FTP (default mode)
npm start

# Download entire theme from FTP server to local ./theme folder
npm run download

# Upload entire local theme to FTP server
npm run push

# Download a specific file from FTP server
npm run download:file <remote-path>
```

--------------------------------

### Validate theme configuration files

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

The 'check' command validates theme configuration files in the 'config/' folder for Tienda Nube-specific requirements. It checks for indentation, duplicate fields, cross-reference validation, and JSON syntax. It provides detailed error and warning messages.

```bash
# Validate configuration files
tiendanube check
```

```bash
# Output for valid configuration:
# ============================================================
# Configuration Check Results
# ============================================================
# ✅ All configuration files are valid!

# Output with errors:
# ============================================================
# Configuration Check Results
# ============================================================
# 
# ❌ Errors (3):
# 
# 1. settings.txt
#    Line 15
#    CRITICAL: Indentation must use tabs, not spaces. Tienda Nube requires tab indentation.
# 
# 2. sections.txt
#    Line 8
#    Duplicate name field: "header_color" already exists in settings.txt at line 12
# 
# 3. settings.txt
#    Line 23
#    Name field "footer_text" has no corresponding value in defaults.txt
# 
# ⚠️  Warnings (2):
# 
# 1. translations.txt
#    Missing translations for language: es_mx
# 
# 2. defaults.txt
#    Default value "unused_setting" is not used in any configuration file
# 
# ============================================================
# Summary: 3 errors, 2 warnings
# ============================================================
# ❌ Configuration check failed. Please fix the errors above.

# Exit codes:
# 0 - All checks passed
# 1 - Errors found
```

--------------------------------

### Download File from FTP Server

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Downloads a file from the FTP server to the local filesystem. Automatically creates local directories as needed. Handles connection and permission errors.

```typescript
import { FtpService } from "./lib/ftp/service.js";

const ftpService = new FtpService();

// Download a single file
try {
  await ftpService.downloadFile(
    "/config/settings.txt",                           // remoteFilePath
    "/path/to/project/theme/config/settings.txt"      // localFilePath
  );
  // Output: ✅ File downloaded: theme/config/settings.txt
} catch (error) {
  console.error("Download failed:", error.message);
}
```

--------------------------------

### runConfigCheck (Standalone)

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Convenience function that runs validation and prints formatted results to console.

```APIDOC
## runConfigCheck

### Description
Convenience function that runs validation and prints formatted results to console.

### Method
Not applicable (CLI command)

### Endpoint
Not applicable (CLI command)

### Parameters
None

### Request Example
```typescript
import { runConfigCheck } from "./lib/validators/config-checker.js";

// Run check and get boolean result
const success = await runConfigCheck("./theme");

if (success) {
  console.log("All configuration files are valid!");
  process.exit(0);
} else {
  console.log("Configuration errors found.");
  process.exit(1);
}
```

### Response
#### Success Response (200)
- **success** (boolean) - True if all configuration files are valid, false otherwise.

#### Response Example
```
All configuration files are valid!
```
(or)
```
Configuration errors found.
```
```

--------------------------------

### Download Specific File from FTP

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Downloads a single specified file from the FTP server to its corresponding location within the local `theme/` directory. Useful for targeted updates or retrieval.

```bash
# Download a specific configuration file
tiendanube download-file config/settings.txt

# Output:
# === 📥 FTP FILE DOWNLOAD SYSTEM ===
# ℹ️  FTP file: /config/settings.txt
# ℹ️  Local destination: /path/to/project/theme/config/settings.txt
# ✅ File downloaded: theme/config/settings.txt
# ✅ Operation completed

# Download a template file
tiendanube download-file templates/product.tpl
```

--------------------------------

### Convert Paths with PathUtils

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Utility class for converting between local filesystem paths and remote FTP paths, including cross-platform normalization.

```typescript
import { PathUtils } from "./lib/utils/path-utils.js";

const pathUtils = new PathUtils(
  "/path/to/project/theme",  // themeFolderPath
  "/"                        // ftpBasePath
);

// Get relative path from theme folder
const relative = pathUtils.getRelativePath("/path/to/project/theme/templates/product.tpl");
// Result: "templates/product.tpl"

// Convert local path to remote FTP path
const remotePath = pathUtils.getRemotePath("/path/to/project/theme/templates/product.tpl");
// Result: "/templates/product.tpl"

// Convert remote path to local path
const localPath = pathUtils.getLocalPath("/templates/product.tpl");
// Result: "/path/to/project/theme/templates/product.tpl"

// Normalize remote path with FTP base
const normalized = pathUtils.normalizeRemotePath("config/settings.txt");
// Result: "/config/settings.txt"

// Convert Windows paths to POSIX for FTP
const posixPath = pathUtils.toPosix("templates\\partials\\header.tpl");
// Result: "templates/partials/header.tpl"
```

--------------------------------

### Access Configuration Settings

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Access centralized settings from the .env file using the typed config object.

```javascript
config.ftp;        // FTP connection settings
config.local;      // Local paths (theme folder)
config.watcher;    // File watcher settings
config.connection; // Connection pooling settings
config.debug;      // Debug mode flag
```

--------------------------------

### Upload File to FTP Server

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Uploads a local file to the FTP server. Supports checksum comparison to skip unchanged files and automatic directory creation. Handles file not found, connection, and permission errors.

```typescript
import { FtpService } from "./lib/ftp/service.js";

const ftpService = new FtpService();

// Upload a single file
try {
  await ftpService.uploadFile(
    "/path/to/project/theme/templates/product.tpl",  // localPath
    "/templates/product.tpl"                          // remotePath
  );
  // Output: ✅ File uploaded: /templates/product.tpl
} catch (error) {
  // Handles: FILE_NOT_FOUND, CONNECTION_ERROR, PERMISSION_DENIED
  console.error("Upload failed:", error.message);
}

// With checksum caching (skips unchanged files)
await ftpService.uploadFile(
  "/path/to/project/theme/static/css/main.css",
  "/static/css/main.css"
);
// Output if unchanged: ⏭️  Skipped (unchanged): /static/css/main.css
// Output if changed:   ✅ File uploaded: /static/css/main.css
```

--------------------------------

### FTP Directory Operations

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Creates or removes directories on the FTP server.

```APIDOC
## POST /createDirectory / DELETE /removeDirectory

### Description
Creates or removes directories on the FTP server.

### Method
POST (createDirectory), DELETE (removeDirectory)

### Endpoint
/createDirectory, /removeDirectory

### Parameters
#### Path Parameters
- **remotePath** (string) - Required - The path of the directory to create or remove on the FTP server.

### Request Example
```json
{
  "remotePath": "/static/images/banners" 
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the directory was created or removed.

#### Response Example
```json
{
  "message": "✅ Directory created: /static/images/banners"
}
```

#### Error Handling
- CONNECTION_ERROR
- PERMISSION_DENIED
```

--------------------------------

### FTP File Download

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Downloads a file from the FTP server to the local filesystem. Automatically creates local directories as needed.

```APIDOC
## GET /downloadFile

### Description
Downloads a file from the FTP server to the local filesystem. Automatically creates local directories as needed.

### Method
GET

### Endpoint
/downloadFile

### Parameters
#### Path Parameters
- **remoteFilePath** (string) - Required - The path of the file on the FTP server.
- **localFilePath** (string) - Required - The destination path on the local filesystem.

### Request Example
```json
{
  "remoteFilePath": "/config/settings.txt",
  "localFilePath": "/path/to/project/theme/config/settings.txt"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the file was downloaded.

#### Response Example
```json
{
  "message": "✅ File downloaded: theme/config/settings.txt"
}
```

#### Error Handling
- CONNECTION_ERROR
- PERMISSION_DENIED
```

--------------------------------

### Validate Theme Configuration

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Validates theme configuration files against Tienda Nube requirements and processes validation results.

```typescript
import { ConfigChecker, ValidationResults } from "./lib/validators/config-checker.js";

const checker = new ConfigChecker();

// Run validation on theme directory
const results: ValidationResults = await checker.check("./theme");

console.log("Success:", results.success);
console.log("Errors:", results.summary.totalErrors);
console.log("Warnings:", results.summary.totalWarnings);

// Process individual errors
results.errors.forEach(error => {
  console.log(`❌ ${error.file}`);
  if (error.line) console.log(`   Line ${error.line}`);
  console.log(`   ${error.message}`);
});

// Process warnings
results.warnings.forEach(warning => {
  console.log(`⚠️  ${warning.file}: ${warning.message}`);
});
```

--------------------------------

### Implement Structured Logging

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Use the Logger class to provide consistent, categorized log output across components.

```javascript
const logger = new Logger("ComponentName");
logger.success("Operation completed");
logger.error("Operation failed", errorDetails);
logger.info("Processing...");
logger.debug("Debug info"); // Only when DEBUG=true
```

--------------------------------

### Theme Directory Structure

Source: https://github.com/innovate-group/tiendanubecli/blob/main/DEVELOPMENT.md

Standard directory layout for Tienda Nube themes.

```text
theme/
├── config/          # Theme configuration files
│   ├── settings.txt # Main theme settings (JSON array)
│   └── data.json    # Theme data (JSON object)
├── layouts/         # Page layout templates (.tpl files)
├── templates/       # Page-specific templates
│   ├── home.tpl
│   ├── product.tpl
│   ├── cart.tpl
│   └── ...
├── snipplets/       # Reusable template components
└── static/          # Static assets
    ├── css/         # Stylesheets (SCSS templates)
    ├── js/          # JavaScript files
    └── images/      # Image assets
```

--------------------------------

### FTP File Upload

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Uploads a local file to the FTP server. Supports checksum comparison to skip unchanged files and automatic directory creation.

```APIDOC
## POST /uploadFile

### Description
Uploads a local file to the FTP server. Supports checksum comparison to skip unchanged files and automatic directory creation.

### Method
POST

### Endpoint
/uploadFile

### Parameters
#### Path Parameters
- **localPath** (string) - Required - The local path of the file to upload.
- **remotePath** (string) - Required - The destination path on the FTP server.

### Request Example
```json
{
  "localPath": "/path/to/project/theme/templates/product.tpl",
  "remotePath": "/templates/product.tpl"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the file was uploaded or skipped.

#### Response Example
```json
{
  "message": "✅ File uploaded: /templates/product.tpl"
}
```

#### Error Handling
- FILE_NOT_FOUND
- CONNECTION_ERROR
- PERMISSION_DENIED
```

--------------------------------

### Run Standalone Configuration Check

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Convenience function to run validation and output results to the console with process exit codes.

```typescript
import { runConfigCheck } from "./lib/validators/config-checker.js";

// Run check and get boolean result
const success = await runConfigCheck("./theme");

if (success) {
  console.log("All configuration files are valid!");
  process.exit(0);
} else {
  console.log("Configuration errors found.");
  process.exit(1);
}
```

--------------------------------

### PathUtils API

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Utility class for converting between local filesystem paths and remote FTP paths. Handles cross-platform path separators automatically.

```APIDOC
## PathUtils API

### Description
Utility class for converting between local filesystem paths and remote FTP paths. Handles cross-platform path separators automatically.

### Method
Not applicable (Class instantiation)

### Endpoint
Not applicable (Class instantiation)

### Parameters
#### Constructor Parameters
- **themeFolderPath** (string) - Required - The base path to the theme folder.
- **ftpBasePath** (string) - Required - The base path on the FTP server.

### Methods
#### getRelativePath
- **Description**: Gets the relative path of a file from the theme folder.
- **Parameters**:
  - **localFilePath** (string) - Required - The absolute local path to the file.
- **Returns**: string - The relative path from the theme folder.

#### getRemotePath
- **Description**: Converts a local path to a remote FTP path.
- **Parameters**:
  - **localFilePath** (string) - Required - The absolute local path to the file.
- **Returns**: string - The corresponding remote FTP path.

#### getLocalPath
- **Description**: Converts a remote FTP path to a local path.
- **Parameters**:
  - **remoteFilePath** (string) - Required - The remote FTP path.
- **Returns**: string - The corresponding local path.

#### normalizeRemotePath
- **Description**: Normalizes a remote path, ensuring it starts with the FTP base path.
- **Parameters**:
  - **remotePath** (string) - Required - The remote path to normalize.
- **Returns**: string - The normalized remote path.

#### toPosix
- **Description**: Converts a Windows-style path to a POSIX-style path.
- **Parameters**:
  - **windowsPath** (string) - Required - The Windows-style path.
- **Returns**: string - The POSIX-style path.

### Request Example
```typescript
import { PathUtils } from "./lib/utils/path-utils.js";

const pathUtils = new PathUtils(
  "/path/to/project/theme",  // themeFolderPath
  "/"
); // ftpBasePath

// Get relative path from theme folder
const relative = pathUtils.getRelativePath("/path/to/project/theme/templates/product.tpl");
// Result: "templates/product.tpl"

// Convert local path to remote FTP path
const remotePath = pathUtils.getRemotePath("/path/to/project/theme/templates/product.tpl");
// Result: "/templates/product.tpl"

// Convert remote path to local path
const localPath = pathUtils.getLocalPath("/templates/product.tpl");
// Result: "/path/to/project/theme/templates/product.tpl"

// Normalize remote path with FTP base
const normalized = pathUtils.normalizeRemotePath("config/settings.txt");
// Result: "/config/settings.txt"

// Convert Windows paths to POSIX for FTP
const posixPath = pathUtils.toPosix("templates\\partials\\header.tpl");
// Result: "templates/partials/header.tpl"
```

### Response
#### Success Response (200)
- **Methods return**: string - The result of the path conversion or normalization.

#### Response Example
```json
{
  "relative": "templates/product.tpl",
  "remotePath": "/templates/product.tpl",
  "localPath": "/path/to/project/theme/templates/product.tpl",
  "normalized": "/config/settings.txt",
  "posixPath": "templates/partials/header.tpl"
}
```
```

--------------------------------

### FTP Directory Listing

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Lists contents of a remote directory, returning file information.

```APIDOC
## GET /listDirectory

### Description
Lists contents of a remote directory, returning file information.

### Method
GET

### Endpoint
/listDirectory

### Parameters
#### Path Parameters
- **remotePath** (string) - Required - The path of the directory to list on the FTP server.

### Request Example
```json
{
  "remotePath": "/templates"
}
```

### Response
#### Success Response (200)
- **items** (array) - An array of FileInfo objects, each containing details about a file or directory.
  - **name** (string) - The name of the file or directory.
  - **size** (number) - The size of the file in bytes (0 for directories).
  - **type** (number) - Type indicator (e.g., 2 for directory, other for file).

#### Response Example
```json
{
  "items": [
    { "name": "home.tpl", "size": 2456, "type": 1 },
    { "name": "product.tpl", "size": 5678, "type": 1 },
    { "name": "cart.tpl", "size": 3421, "type": 1 },
    { "name": "partials", "size": 0, "type": 2 }
  ]
}
```

#### Error Handling
- CONNECTION_ERROR
- PERMISSION_DENIED
```

--------------------------------

### Manage Upload Queue

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Handles file synchronization with debouncing, parallel processing, and priority-based task management.

```typescript
import { UploadQueue, QueueStats } from "./lib/core/upload-queue.js";
import { FtpService } from "./lib/ftp/service.js";

const ftpService = new FtpService();
const queue = new UploadQueue(ftpService, {
  debounceTime: 500,      // Wait 500ms before processing
  maxConcurrent: 3,       // Process up to 3 files in parallel
  showProgress: true,     // Show periodic progress updates
  progressInterval: 5000, // Update every 5 seconds
  maxRetries: 3           // Retry failed tasks 3 times
});

// Start the queue processor
queue.start();

// Add tasks to the queue (automatically prioritized)
queue.add(
  "/path/to/project/theme/config/settings.txt",  // filePath
  "/config/settings.txt",                         // remotePath
  "upload"                                        // operation: upload|delete|createDir|deleteDir
);
// Config files get "high" priority

queue.add(
  "/path/to/project/theme/templates/product.tpl",
  "/templates/product.tpl",
  "upload"
);
// Template files get "normal" priority

queue.add(
  "/path/to/project/theme/static/images/banner.jpg",
  "/static/images/banner.jpg",
  "upload"
);
// Image files get "low" priority

// Get queue statistics
const stats: QueueStats = queue.getStats();
console.log(`Pending: ${stats.pending}`);
console.log(`Processing: ${stats.processing}`);
console.log(`Completed: ${stats.completed}`);
console.log(`Failed: ${stats.failed}`);

// Stop queue and drain remaining tasks
await queue.stop();
// Output: Queue stopped. Final stats: 3 completed, 0 failed
```

--------------------------------

### List Contents of Remote Directory

Source: https://context7.com/innovate-group/tiendanubecli/llms.txt

Lists the contents of a remote directory on the FTP server, returning file information including type, name, and size. Requires importing FileInfo.

```typescript
import { FtpService } from "./lib/ftp/service.js";
import { FileInfo } from "basic-ftp";

const ftpService = new FtpService();

// List remote directory contents
const items: FileInfo[] = await ftpService.listDirectory("/templates");

items.forEach(item => {
  console.log(`${item.type === 2 ? "📁" : "📄"} ${item.name} (${item.size} bytes)`);
});

// Example output:
// 📄 home.tpl (2456 bytes)
// 📄 product.tpl (5678 bytes)
// 📄 cart.tpl (3421 bytes)
// 📁 partials (0 bytes)
```