npm package: @baconshot/deploy-sftp
Description: Deploy files to FTP or SFTP servers with support for directory cleaning and multiple protocols
Author: Mehrzad Beiknejad
Latest version: 1.0.7

# @baconshot/deploy-sftp

A flexible Node.js package for deploying files to FTP or SFTP servers with support for both protocols, optional directory cleaning, and comprehensive error handling.

## Features

- 🚀 Support for both FTP and SFTP protocols
- 🧹 Optional remote directory cleaning before upload
- 📁 Recursive directory upload
- ⚙️ Configurable via environment variables
- 📦 TypeScript support with full type definitions
- 🔒 Secure password authentication
- 🎯 CLI tool and Node.js module

## Installation

```bash
npm install @baconshot/deploy-sftp
```

## Usage

### As a CLI Tool

Add to your `package.json`:

```json
{
  "scripts": {
    "deploy:sftp": "npm run build && deploy-sftp"
  }
}
```

Set up a `.env` file in your project root:

```env
FTP_PROTOCOL=sftp
FTP_HOST=your-server.com
FTP_PORT=22
FTP_USER=your-username
FTP_PASSWORD=your-password
FTP_REMOTE_DIR=/path/to/remote/dir/
FTP_LOCAL_DIR=dist
FTP_SECURE=false
FTP_CLEAN=false
FTP_CLEAN_SAFE_DEPTH=3
```

Environment variables:

| Variable               | Required | Default                  | Description                                                       |
| ---------------------- | -------- | ------------------------ | ----------------------------------------------------------------- |
| `FTP_PROTOCOL`         | No       | `sftp`                   | Protocol: `sftp` or `ftp`                                         |
| `FTP_HOST`             | Yes      | -                        | Server hostname                                                   |
| `FTP_USER`             | Yes      | -                        | Username                                                          |
| `FTP_PASSWORD`         | Yes      | -                        | Password                                                          |
| `FTP_PORT`             | No       | `22` (SFTP) / `21` (FTP) | Server port                                                       |
| `FTP_REMOTE_DIR`       | Yes      | -                        | Remote directory path                                             |
| `FTP_LOCAL_DIR`        | No       | `dist`                   | Local directory to upload                                         |
| `FTP_SECURE`           | No       | `false`                  | Use FTPS only when `FTP_PROTOCOL=ftp` (ignored for `sftp`)        |
| `FTP_CLEAN`            | No       | `false`                  | Clean remote directory before upload (requires a safe path depth) |
| `FTP_CLEAN_SAFE_DEPTH` | No       | `3`                      | Minimum remote path segments required before cleaning is allowed  |

Then run:

```bash
npm run deploy:sftp
```

### FTP vs FTPS vs SFTP

If you are unsure which one to use, this is the quick version:

- `SFTP`: Uses SSH. This is usually the modern default and the safest first choice.
- `FTP`: Plain FTP (no encryption). Only use if your host specifically requires it.
- `FTPS`: FTP + TLS encryption. In this package, FTPS is enabled by setting `FTP_PROTOCOL=ftp` and `FTP_SECURE=true`.

Important: `SFTP` and `FTPS` are different protocols.

- SFTP runs over SSH (commonly port `22`)
- FTPS runs over FTP with TLS (commonly port `21`)

How to configure:

- SFTP (recommended): set `FTP_PROTOCOL=sftp` and keep `FTP_SECURE=false` (ignored for SFTP)
- FTP (unencrypted): set `FTP_PROTOCOL=ftp` and `FTP_SECURE=false`
- FTPS (encrypted FTP): set `FTP_PROTOCOL=ftp` and `FTP_SECURE=true`

### As a Node.js Module

```typescript
import { deploy } from "@baconshot/deploy-sftp";

const result = await deploy({
  protocol: "sftp", // or 'ftp'
  host: "your-server.com",
  user: "username",
  password: "password",
  remoteDir: "/path/to/remote/dir/",
  localDir: "dist",
  secure: false,
  cleanBeforeUpload: false,
  cleanSafeDepth: 3,
  verbose: true,
});

if (result.success) {
  console.log(`Uploaded ${result.uploadedFiles} files`);
} else {
  console.error(result.message);
}
```

### Configuration Object

```typescript
interface DeployConfig {
  protocol?: "ftp" | "sftp"; // Default: 'sftp'
  host: string; // Required
  user: string; // Required
  password: string; // Required
  port?: number; // Optional, defaults based on protocol
  remoteDir: string; // Required
  localDir?: string; // Default: 'dist'
  secure?: boolean; // Default: false
  cleanBeforeUpload?: boolean; // Default: false
  cleanSafeDepth?: number; // Default: 3
  verbose?: boolean; // Default: true
}
```

## Security Notes

⚠️ **Never commit `.env` files to version control.** Add `.env` to your `.gitignore`.

When `FTP_CLEAN=true`, the package refuses to clean unsafe broad targets.

By default, the minimum required depth is `3` path segments.
Set `FTP_CLEAN_SAFE_DEPTH` to override this.

- Allowed example: `/utilities/todo-2023`
- Rejected examples: `/`, `/public`, `.` and paths containing `..`

This safety check helps avoid accidental deletion of top-level remote directories.

For CI/CD environments, inject environment variables securely through your platform's secret management.

## Supported Node Versions

Node.js 18 or higher

## License

MIT