scp-next 1.0.18 → 1.0.20

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.0.19
+
+- Refined README structure for clearer installation, quick start, basic usage, advanced usage,
+  library options, and configuration guidance.
+- Improved password-first examples while keeping security warnings and safer authentication
+  recommendations visible.
+- Clarified SSH agent usage, `SSH_AUTH_SOCK`, timeout behavior, and configuration-file
+  recommendations.
+- Expanded GitHub Pages documentation with CLI, library, and configuration options.
+- Moved release notes under `docs/release-notes/` for cleaner documentation organization.
+
 ## 1.0.14
 
 - Production-ready `scp-next` TypeScript CLI and library.

package/README.md

@@ -19,14 +19,6 @@
 It uses SFTP internally through `ssh2-sftp-client` instead of implementing SCP or SFTP protocols manually.
 Developer documentation is available at [GitHub Pages](https://chengchuu.github.io/scp-next/).
 
-## Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Basic Usage](#basic-usage)
-- [Library Usage](#library-usage)
-- [Advanced Usage](#advanced-usage)
-
 ## Features
 
 - Upload and download files or directories recursively.
@@ -35,6 +27,19 @@ Developer documentation is available at [GitHub Pages](https://chengchuu.github.
 - JSON configuration files, named profiles, and configured jobs.
 - Reusable transfer client.
 
+## Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [CLI Usage](#cli-usage)
+  - [CLI Options](#cli-options)
+- [Library Usage](#library-usage)
+  - [Library Options](#library-options)
+- [Advanced Usage](#advanced-usage)
+  - [Configuration File Options](#configuration-file-options)
+  - [Environment Variables](#environment-variables)
+- [User Guides](#user-guides)
+
 ## Installation
 
 CLI:
@@ -77,7 +82,7 @@ Downloading: /var/log/example.log 1.0 MB / 1.0 MB (100%)
 ```
 
 Password arguments are convenient, but they may be exposed through shell history and process listings.
-Prefer `SCP_NEXT_PASSWORD`, SSH agents, or protected private-key files for shared or production environments.
+Prefer `SCP_NEXT_PASSWORD` environment variable in shared or production environments. For key authentication, use a protected private-key file.
 
 Use the library:
 
@@ -95,7 +100,7 @@ await upload({
 });
 ```
 
-## Basic Usage
+## CLI Usage
 
 ### CLI Syntax
 
@@ -186,7 +191,7 @@ scp-next run download-logs --config ./scp-next.config.json
 | `--host <host>`                       | SSH server host.                                                       |
 | `--port <port>`                       | SSH server port. Defaults to `22`.                                     |
 | `--username <username>`               | SSH username.                                                          |
-| `--password <password>`               | SSH password. Prefer environment variables, SSH agents, or key files.  |
+| `--password <password>`               | SSH password.                                                          |
 | `--private-key <privateKey>`          | Private-key content. Redacted from logs and errors.                    |
 | `--private-key-file <privateKeyFile>` | Private-key file path. Supports `~` expansion.                         |
 | `--passphrase <passphrase>`           | Passphrase for an encrypted private key.                               |
@@ -197,12 +202,14 @@ scp-next run download-logs --config ./scp-next.config.json
 | `--create-directories`                | Create missing destination directories. Enabled by default.            |
 | `--no-create-directories`             | Disable automatic destination directory creation.                      |
 | `--dry-run`                           | Resolve and validate the operation without connecting or transferring. |
-| `--timeout <milliseconds>`            | Connection and operation timeout in milliseconds.                      |
+| `--timeout <milliseconds>`            | SSH connection ready timeout in milliseconds.                          |
 | `--verbose`                           | Print non-sensitive diagnostic details.                                |
 | `--quiet`                             | Disable progress and non-error output.                                 |
 | `--help`                              | Show command help.                                                     |
 | `--version`                           | Show the package version.                                              |
 
+`--timeout` maps to the SSH `readyTimeout`, so it controls how long to wait for the connection handshake. It does not currently limit per-file or total transfer duration.
+
 ## Library Usage
 
 ### ESM Upload
@@ -284,6 +291,29 @@ await upload({
 });
 ```
 
+### Library Options
+
+| Field               | Used by         | Description                                                  |
+| ------------------- | --------------- | ------------------------------------------------------------ |
+| `host`              | server          | SSH server host.                                             |
+| `port`              | server          | SSH server port. Defaults to `22`.                           |
+| `username`          | server          | SSH username.                                                |
+| `password`          | server          | SSH password.                                                |
+| `privateKey`        | server          | Private-key content as a string or Buffer.                   |
+| `privateKeyFile`    | server          | Private-key file path.                                       |
+| `passphrase`        | server          | Passphrase for an encrypted private key.                     |
+| `agent`             | server          | SSH agent socket path.                                       |
+| `hostFingerprint`   | server          | Expected server host-key SHA-256 fingerprint.                |
+| `knownHostsFile`    | server          | Known-hosts file for host verification.                      |
+| `localPath`         | upload/download | Local source for upload or local destination for download.   |
+| `remotePath`        | upload/download | Remote destination for upload or remote source for download. |
+| `recursive`         | transfer        | Transfer directories recursively. Defaults to `false`.       |
+| `overwrite`         | transfer        | Allow replacing existing files.                              |
+| `createDirectories` | transfer        | Create missing destination directories. Defaults to `true`.  |
+| `dryRun`            | transfer        | Validate and plan without modifying local or remote files.   |
+| `timeout`           | server/transfer | SSH connection ready timeout in milliseconds.                |
+| `onProgress`        | transfer        | Progress callback for file and directory transfers.          |
+
 ## Advanced Usage
 
 ### Configuration Files
@@ -329,15 +359,15 @@ Example:
 
 Do not commit configuration files containing real passwords. Prefer `SCP_NEXT_PASSWORD` or another protected secret source for shared repositories and deployment environments.
 
-Configuration file options:
+### Configuration File Options
 
-| Key              | Description                                                         |
-| ---------------- | ------------------------------------------------------------------- |
-| `server`         | SSH connection options such as `host`, `port`, and `username`.      |
-| `transfer`       | Transfer defaults such as `recursive`, `overwrite`, and `timeout`.  |
-| `defaultProfile` | Profile name used when `--profile` or `SCP_NEXT_PROFILE` is absent. |
-| `profiles`       | Named server connection profiles.                                   |
-| `jobs`           | Reusable upload or download jobs for `scp-next run <job>`.          |
+| Key              | Description                                                          |
+| ---------------- | -------------------------------------------------------------------- |
+| `server`         | SSH connection options such as `host`, `port`, and `username`.       |
+| `transfer`       | Transfer defaults such as `recursive`, `overwrite`, and directories. |
+| `defaultProfile` | Profile name used when `--profile` or `SCP_NEXT_PROFILE` is absent.  |
+| `profiles`       | Named server connection profiles.                                    |
+| `jobs`           | Reusable upload or download jobs for `scp-next run <job>`.           |
 
 Root-level server options such as `host`, `username`, `privateKeyFile`, `knownHostsFile`,
 and `hostFingerprint` are also supported for simple configuration files, but `server` keeps connection values grouped and easier to read.
@@ -420,6 +450,7 @@ SCP_NEXT_PRIVATE_KEY_FILE
 SCP_NEXT_PASSPHRASE
 SCP_NEXT_TIMEOUT
 SCP_NEXT_PROFILE
+SSH_AUTH_SOCK
 ```
 
 Bash:
@@ -464,6 +495,32 @@ Supported methods:
 - Private-key passphrase
 - SSH agent authentication through `agent` or `SSH_AUTH_SOCK`
 
+SSH agent CLI example:
+
+```bash
+ssh-add ~/.ssh/id_ed25519
+
+export SCP_NEXT_HOST="your-host"
+export SCP_NEXT_USERNAME="your-username"
+
+scp-next upload ./dist /var/www/example --recursive
+```
+
+Library example:
+
+```ts
+import { upload } from "scp-next";
+
+await upload({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  agent: process.env.SSH_AUTH_SOCK,
+  localPath: "./dist",
+  remotePath: "/var/www/example",
+  recursive: true
+});
+```
+
 ### Host Verification
 
 `hostFingerprint` compares the server host key SHA-256 fingerprint. `knownHostsFile` supports plain OpenSSH `known_hosts` entries for exact host names. When neither is supplied, `scp-next` reads `~/.ssh/known_hosts`. Hashed host names and every OpenSSH marker variant are not currently parsed.
@@ -534,6 +591,11 @@ copy(options: CopyOptions): Promise<void>
 Upload and download APIs use explicit `localPath` and `remotePath` names.
 The optional generic `copy()` API accepts typed local/remote endpoint objects.
 
+## User Guides
+
+- [English](https://github.com/chengchuu/scp-next/blob/main/docs/release-notes/introducing-scp-next-v1.0.19-en.md)
+- [简体中文](https://github.com/chengchuu/scp-next/blob/main/docs/release-notes/introducing-scp-next-v1.0.19-zh.md)
+
 ## Development
 
 ```bash

package/docs/release-notes/introducing-scp-next-v1.0.14.md

@@ -0,0 +1,183 @@
+# Introducing scp-next v1.0.14
+
+`scp-next` is an SCP-style CLI and TypeScript library for secure file transfers over SSH.
+It keeps familiar `upload <source> <destination>` and `download <source> <destination>`
+commands while using SFTP internally through `ssh2-sftp-client`.
+
+Version 1.0.14 focuses on production polish: clearer documentation, safer daily defaults,
+better path behavior, and a cleaner project footprint.
+
+## Highlights
+
+- Upload and download files or directories recursively.
+- Use the CLI with clear `<source> <destination>` operands.
+- Use the library from ESM `import` or CommonJS `require`.
+- Configure transfers with JSON files, named profiles, jobs, and environment variables.
+- Reuse a transfer client across multiple operations.
+- Create missing destination directories by default.
+- Disable destination directory creation with `--no-create-directories`.
+- Preview operations with `--dry-run`.
+- Keep secrets redacted from logs and errors.
+
+## Install
+
+CLI:
+
+```bash
+npm install --global scp-next
+```
+
+Library:
+
+```bash
+npm install scp-next
+```
+
+## Quick Start
+
+Upload with password authentication:
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive
+```
+
+Password arguments are convenient, but they may be exposed through shell history and process
+listings. Prefer environment variables, SSH agents, or protected private-key files for shared
+or production environments.
+
+Download with password authentication:
+
+```bash
+scp-next download /var/log/example.log ./logs/example.log \
+  --host your-host \
+  --username your-username \
+  --password your-password
+```
+
+## Library Usage
+
+ESM upload:
+
+```ts
+import { upload } from "scp-next";
+
+await upload({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  password: process.env.SCP_NEXT_PASSWORD,
+  localPath: "./dist",
+  remotePath: "/var/www/example",
+  recursive: true,
+  overwrite: true
+});
+```
+
+Reusable client:
+
+```ts
+import { createClient } from "scp-next";
+
+const client = createClient({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  password: process.env.SCP_NEXT_PASSWORD
+});
+
+try {
+  await client.connect();
+  await client.upload("./dist", "/var/www/example", { recursive: true });
+  await client.download("/var/log/example.log", "./logs/example.log");
+} finally {
+  await client.close();
+}
+```
+
+## Configuration Files
+
+The CLI searches for:
+
+```text
+scp-next.config.json
+.scp-nextrc
+.scp-nextrc.json
+```
+
+You can also pass an explicit path:
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --config ./scp-next.config.json \
+  --profile production
+```
+
+Example:
+
+```json
+{
+  "profiles": {
+    "production": {
+      "host": "your-host",
+      "username": "your-username",
+      "privateKeyFile": "~/.ssh/id_ed25519"
+    }
+  },
+  "jobs": {
+    "deploy": {
+      "operation": "upload",
+      "profile": "production",
+      "source": "./dist",
+      "destination": "/var/www/example",
+      "recursive": true,
+      "overwrite": true
+    }
+  }
+}
+```
+
+Run the configured job:
+
+```bash
+scp-next run deploy
+```
+
+## What's New in v1.0.14
+
+- Added GitHub Pages developer documentation.
+- Expanded README sections for quick start, basic usage, library usage, and advanced usage.
+- Added complete CLI, library, and configuration option references to the docs site.
+- Improved SCP-style destination behavior for file and directory transfers.
+- Made missing destination directory creation the default behavior.
+- Added `--no-create-directories` as the explicit opt-out.
+- Improved host verification guidance and typical-fix messaging.
+- Improved Git Bash remote path restoration for Windows users.
+- Reduced noisy duplicate progress output.
+- Removed unused legacy tooling and Docker configuration files.
+
+## Security Notes
+
+`scp-next` is designed for security-conscious transfer workflows:
+
+- Normal transfers use SFTP and do not execute remote shell commands.
+- Passwords, passphrases, private-key contents, and tokens are redacted from logs and errors.
+- Host verification uses `hostFingerprint`, `knownHostsFile`, or `~/.ssh/known_hosts`.
+- Local paths use OS-aware path behavior, while remote paths preserve POSIX `/` separators.
+- Credentials are never persisted automatically.
+
+## Transfer Terminology
+
+The CLI uses standard `<source> <destination>` order:
+
+```text
+Operation  Source  Destination
+Upload     Local   Remote
+Download   Remote  Local
+```
+
+The TypeScript API uses `localPath` and `remotePath` so application code stays explicit.
+
+`scp-next` v1.0.14 is ready for command-line transfers, deployment scripts, and Node.js
+applications that need SSH file transfer without custom protocol implementation.

package/docs/release-notes/introducing-scp-next-v1.0.19-en.md

@@ -0,0 +1,347 @@
+# Introducing scp-next v1.0.19: An SSH File Transfer Tool for Node.js Developers
+
+![scp-next](http://blog.mazey.net/wp-content/uploads/2026/07/scp-next-SF-s7x3.jpg)
+
+Learn how to install `scp-next` from npm, use the CLI for uploads and downloads, configure reusable jobs, handle credentials safely, call the library API, and onboard a new engineer quickly.
+
+- [Introduction](#introduction)
+- [Who Should Use It](#who-should-use-it)
+- [Installation](#installation)
+- [Understand Transfer Direction First](#understand-transfer-direction-first)
+- [CLI Quick Start](#cli-quick-start)
+- [Recommended Credential Patterns](#recommended-credential-patterns)
+- [Common CLI Options](#common-cli-options)
+- [Configuration Files](#configuration-files)
+- [Library API Usage](#library-api-usage)
+- [Host Verification](#host-verification)
+- [New Engineer Checklist](#new-engineer-checklist)
+
+## Introduction
+
+`scp-next` is an SCP-style npm package. It provides both a command-line tool and a library for secure file transfers over SSH. Although the package name includes SCP, normal transfers use SFTP internally through `ssh2-sftp-client`, so regular transfers do not execute remote shell commands.
+
+## Who Should Use It
+
+Use `scp-next` when you need file transfers in deployment scripts, CI workflows, or Node.js applications. Common use cases include:
+
+- Uploading local build output to a server.
+- Downloading logs or generated artifacts from a server.
+- Managing different server environments with configuration files.
+- Reusing one transfer client across multiple operations in application code.
+
+`scp-next` requires Node.js 18.18.0 or later.
+
+## Installation
+
+Install it globally when you want to call the `scp-next` command directly.
+
+```bash
+npm install --global scp-next
+```
+
+Install it as a project dependency when you want to import the API from Node.js code.
+
+```bash
+npm install scp-next
+```
+
+If a project only needs the CLI in scripts, you can also install it locally and call it with `npx scp-next` or through npm scripts.
+
+## Understand Transfer Direction First
+
+The CLI always uses two positional operands: `<source> <destination>`.
+
+```text
+scp-next upload <source> <destination> [options]
+scp-next download <source> <destination> [options]
+scp-next run <job> [source] [destination] [options]
+```
+
+The direction rules are:
+
+| Operation | Source | Destination |
+| --------- | ------ | ----------- |
+| Upload    | Local  | Remote      |
+| Download  | Remote | Local       |
+
+The programmatic API does not use `<source>` and `<destination>`. Upload and download options use `localPath` and `remotePath`, which keeps local and remote paths explicit in application code.
+
+## CLI Quick Start
+
+Upload a local directory to a remote server.
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive
+```
+
+Download a remote file to a local path.
+
+```bash
+scp-next download /var/log/example.log ./logs/example.log \
+  --host your-host \
+  --username your-username \
+  --password your-password
+```
+
+If the destination directory does not exist, `scp-next` creates it by default. This matches familiar `cp` and `scp` behavior for day-to-day use. Use `--no-create-directories` to disable automatic destination directory creation.
+
+Preview an upload plan without connecting to the server.
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive \
+  --dry-run
+```
+
+`--dry-run` resolves configuration and validates local paths. It does not connect to the remote server, and it does not modify local or remote files.
+
+## Recommended Credential Patterns
+
+Password arguments are convenient for local trials.
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive
+```
+
+For shared or production environments, prefer environment variables. This lowers the risk of exposing passwords through shell history or process listings.
+
+```bash
+export SCP_NEXT_HOST="your-host"
+export SCP_NEXT_USERNAME="your-username"
+export SCP_NEXT_PASSWORD="your-password"
+
+scp-next upload ./dist /var/www/example --recursive
+```
+
+You can also use a protected private-key file.
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --private-key-file ~/.ssh/id_ed25519 \
+  --recursive
+```
+
+If your environment already uses SSH agent authentication, add the key first and let `scp-next` use `SSH_AUTH_SOCK`.
+
+```bash
+ssh-add ~/.ssh/id_ed25519
+
+export SCP_NEXT_HOST="your-host"
+export SCP_NEXT_USERNAME="your-username"
+
+scp-next upload ./dist /var/www/example --recursive
+```
+
+## Common CLI Options
+
+| Option                                | Description                                                            |
+| ------------------------------------- | ---------------------------------------------------------------------- |
+| `--host <host>`                       | SSH server host.                                                       |
+| `--port <port>`                       | SSH server port. Defaults to `22`.                                     |
+| `--username <username>`               | SSH username.                                                          |
+| `--password <password>`               | SSH password.                                                          |
+| `--private-key-file <privateKeyFile>` | Private-key file path. Supports `~` expansion.                         |
+| `--passphrase <passphrase>`           | Passphrase for an encrypted private key.                               |
+| `--config <path>`                     | Explicit configuration file path.                                      |
+| `--profile <name>`                    | Named server profile from the configuration file.                      |
+| `--recursive`                         | Transfer directories recursively. Defaults to `false`.                 |
+| `--overwrite`                         | Allow replacing existing destination files.                            |
+| `--create-directories`                | Create missing destination directories. Enabled by default.            |
+| `--no-create-directories`             | Disable automatic destination directory creation.                      |
+| `--dry-run`                           | Resolve and validate the operation without connecting or transferring. |
+| `--timeout <milliseconds>`            | SSH connection ready timeout in milliseconds.                          |
+| `--quiet`                             | Disable progress and non-error output.                                 |
+| `--verbose`                           | Print non-sensitive diagnostic details.                                |
+
+`--timeout` maps to the SSH `readyTimeout`. It controls how long to wait for the connection handshake, not the duration of each file transfer or the whole transfer run.
+
+## Configuration Files
+
+The CLI automatically searches for these configuration files.
+
+```text
+scp-next.config.json
+.scp-nextrc
+.scp-nextrc.json
+```
+
+You can also pass an explicit path.
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --config ./scp-next.config.json \
+  --profile production
+```
+
+The example below defines a server profile and two reusable jobs.
+
+```json
+{
+  "profiles": {
+    "production": {
+      "host": "your-host",
+      "username": "your-username",
+      "privateKeyFile": "~/.ssh/id_ed25519"
+    }
+  },
+  "jobs": {
+    "deploy": {
+      "operation": "upload",
+      "profile": "production",
+      "source": "./dist",
+      "destination": "/var/www/example",
+      "recursive": true,
+      "overwrite": true
+    },
+    "download-logs": {
+      "operation": "download",
+      "profile": "production",
+      "source": "/var/log/example",
+      "destination": "./logs",
+      "recursive": true
+    }
+  }
+}
+```
+
+Run the configured upload job.
+
+```bash
+scp-next run deploy
+```
+
+Run the configured download job.
+
+```bash
+scp-next run download-logs
+```
+
+The `run` command also supports temporary path overrides.
+
+```bash
+scp-next run deploy ./dist-canary /var/www/canary
+```
+
+Configuration precedence, from highest to lowest, is:
+
+1. Explicit CLI options
+2. Positional CLI operands
+3. Environment variables
+4. Selected configuration profile
+5. Root-level configuration values
+6. Configured job values
+7. Internal defaults
+
+Do not commit configuration files that contain real passwords to public repositories. For shared repositories and deployment environments, prefer `SCP_NEXT_PASSWORD`, SSH agent authentication, or protected key files.
+
+## Library API Usage
+
+ESM projects can import `upload` directly.
+
+```ts
+import { upload } from "scp-next";
+
+await upload({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  password: process.env.SCP_NEXT_PASSWORD,
+  localPath: "./dist",
+  remotePath: "/var/www/example",
+  recursive: true,
+  overwrite: true
+});
+```
+
+CommonJS projects can use `require`.
+
+```js
+const { download } = require("scp-next");
+
+async function main() {
+  await download({
+    host: process.env.SCP_NEXT_HOST,
+    username: process.env.SCP_NEXT_USERNAME,
+    password: process.env.SCP_NEXT_PASSWORD,
+    remotePath: "/var/log/example.log",
+    localPath: "./logs/example.log"
+  });
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});
+```
+
+Create a reusable client when you need multiple operations in one connection lifecycle.
+
+```ts
+import { createClient } from "scp-next";
+
+const client = createClient({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  password: process.env.SCP_NEXT_PASSWORD
+});
+
+try {
+  await client.connect();
+  await client.upload("./dist", "/var/www/example", { recursive: true });
+  await client.download("/var/log/example.log", "./logs/example.log");
+} finally {
+  await client.close();
+}
+```
+
+Primary exports include:
+
+```ts
+upload(options: UploadOptions): Promise<void>;
+download(options: DownloadOptions): Promise<void>;
+createClient(options: ScpServerOptions): ScpNextClient;
+copy(options: CopyOptions): Promise<void>;
+```
+
+Public errors include stable `code` values, readable `message` values, and redacted non-sensitive context. Common error types include `ConfigurationError`, `AuthenticationError`, `ConnectionError`, `TransferError`, and `HostVerificationError`.
+
+## Host Verification
+
+`scp-next` supports host verification with `hostFingerprint` or `knownHostsFile`. When neither is supplied, it reads `~/.ssh/known_hosts`.
+
+For CI or deployment environments without an available known-hosts file, configure `hostFingerprint`. If `scp-next` cannot establish host verification, it fails closed.
+
+## New Engineer Checklist
+
+Use this order when onboarding a project that already uses `scp-next`.
+
+1. Confirm that Node.js is 18.18.0 or later.
+2. Install the CLI with `npm install --global scp-next`.
+3. Run `scp-next upload ... --dry-run` to validate options and paths.
+4. Move server details into environment variables or a configuration file.
+5. Use `scp-next run <job>` for recurring upload or download workflows.
+6. Use `upload`, `download`, or `createClient` from Node.js code when the project needs library integration.
+
+After these pieces are clear, `scp-next` is ready for deployment scripts, log downloads, and Node.js file transfer workflows.
+
+**Copyright Notice**
+
+This is an original article. The author reserves all rights. Please keep the full content when reposting, and include a hyperlink to the author.
+
+Author: [Cheng](https://github.com/chengchuu)
+
+<!-- ID: introducing-scp-next-v1.0.19-en -->
+
+(End)

package/docs/release-notes/introducing-scp-next-v1.0.19-zh.md

@@ -0,0 +1,324 @@
+# scp-next v1.0.19 项目介绍: 面向 Node.js 开发者的 SSH 文件传输工具
+
+![scp-next](http://blog.mazey.net/wp-content/uploads/2026/07/scp-next-SF-s7x3.jpg)
+
+介绍 scp-next v1.0.19 的 npm 安装、CLI 上传下载、配置文件、凭据安全、库 API 和新人使用流程。
+
+- [前言](#前言)
+- [适合谁使用](#适合谁使用)
+- [安装方式](#安装方式)
+- [先理解传输方向](#先理解传输方向)
+- [命令行快速开始](#命令行快速开始)
+- [推荐的凭据写法](#推荐的凭据写法)
+- [常用命令选项](#常用命令选项)
+- [配置文件用法](#配置文件用法)
+- [库 API 用法](#库-api-用法)
+- [主机验证](#主机验证)
+- [新人接手清单](#新人接手清单)
+
+## 前言
+
+`scp-next` 是一个 SCP 风格的 npm 包。他同时提供命令行工具和库，用于通过 SSH 安全传输文件。虽然包名包含 SCP，实际使用 SFTP，不会为普通传输执行远程 Shell 命令。
+
+## 适合谁使用
+
+如果你需要在部署脚本、CI 流程或 Node.js 应用中传输文件，`scp-next` 可以减少重复封装。常见场景如下:
+
+- 将本地构建产物上传到服务器。
+- 从服务器下载日志或产物。
+- 用配置文件管理不同服务器环境。
+- 在应用代码中复用同一个传输客户端。
+
+## 安装方式
+
+全局安装后，可以直接使用 `scp-next` 命令。
+
+```bash
+npm install --global scp-next
+```
+
+作为项目依赖安装后，可以在 Node.js 代码中导入 API。
+
+```bash
+npm install scp-next
+```
+
+如果一个项目只在脚本里调用命令行工具，也可以把他安装到项目依赖中，再通过 `npx scp-next` 或 npm scripts 调用。
+
+## 先理解传输方向
+
+命令行统一使用 `<source> <destination>` 两个位置参数。
+
+```plain
+scp-next upload <source> <destination> [options]
+scp-next download <source> <destination> [options]
+scp-next run <job> [source] [destination] [options]
+```
+
+方向规则如下:
+
+| Operation | Source | Destination |
+| --------- | ------ | ----------- |
+| Upload    | Local  | Remote      |
+| Download  | Remote | Local       |
+
+## 命令行快速开始
+
+上传本地目录到远程服务器。
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive
+```
+
+下载远程文件到本地目录。如果目标目录不存在，`scp-next` 默认会创建目录。这符合日常 `cp` 和 `scp` 风格的使用习惯。可以用 `--no-create-directories` 关闭该行为。
+
+```bash
+scp-next download /var/log/example.log ./logs/example.log \
+  --host your-host \
+  --username your-username \
+  --password your-password
+```
+
+先预览上传计划，而不连接服务器。`--dry-run` 会解析配置并检查本地路径。他不会连接远程服务器，也不会修改本地或远程文件。
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive \
+  --dry-run
+```
+
+## 推荐的凭据写法
+
+命令行密码参数适合本地快速试用。
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive
+```
+
+共享环境和生产环境建议使用环境变量。这样可以降低密码进入 Shell 历史记录或进程列表的风险。
+
+```bash
+export SCP_NEXT_HOST="your-host"
+export SCP_NEXT_USERNAME="your-username"
+export SCP_NEXT_PASSWORD="your-password"
+
+scp-next upload ./dist /var/www/example --recursive
+```
+
+也可以使用受保护的私钥文件。
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --private-key-file ~/.ssh/id_ed25519 \
+  --recursive
+```
+
+## 常用命令选项
+
+| 选项                                  | 作用                            |
+| ------------------------------------- | ------------------------------- |
+| `--host <host>`                       | SSH 服务器地址。                |
+| `--port <port>`                       | SSH 服务器端口，默认值为 `22`。 |
+| `--username <username>`               | SSH 用户名。                    |
+| `--password <password>`               | SSH 密码。                      |
+| `--private-key-file <privateKeyFile>` | 私钥文件路径，支持 `~`。        |
+| `--passphrase <passphrase>`           | 加密私钥的口令。                |
+| `--config <path>`                     | 指定配置文件路径。              |
+| `--profile <name>`                    | 选择配置文件中的服务器配置。    |
+| `--recursive`                         | 递归传输目录，默认关闭。        |
+| `--overwrite`                         | 允许覆盖已有目标文件。          |
+| `--create-directories`                | 创建缺失的目标目录，默认开启。  |
+| `--no-create-directories`             | 关闭目标目录自动创建。          |
+| `--dry-run`                           | 只解析和验证，不执行传输。      |
+| `--timeout <milliseconds>`            | SSH 握手超时时间，单位为毫秒。  |
+| `--quiet`                             | 关闭进度和非错误输出。          |
+| `--verbose`                           | 输出不含敏感信息的诊断内容。    |
+
+## 配置文件用法
+
+CLI 会自动查找以下配置文件。
+
+```plain
+scp-next.config.json
+.scp-nextrc
+.scp-nextrc.json
+```
+
+也可以显式指定路径。
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --config ./scp-next.config.json \
+  --profile production
+```
+
+下面是一个包含服务器配置和任务的示例。
+
+```json
+{
+  "profiles": {
+    "production": {
+      "host": "your-host",
+      "username": "your-username",
+      "privateKeyFile": "~/.ssh/id_ed25519"
+    }
+  },
+  "jobs": {
+    "deploy": {
+      "operation": "upload",
+      "profile": "production",
+      "source": "./dist",
+      "destination": "/var/www/example",
+      "recursive": true,
+      "overwrite": true
+    },
+    "download-logs": {
+      "operation": "download",
+      "profile": "production",
+      "source": "/var/log/example",
+      "destination": "./logs",
+      "recursive": true
+    }
+  }
+}
+```
+
+运行配置好的上传任务。
+
+```bash
+scp-next run deploy
+```
+
+运行配置好的下载任务。
+
+```bash
+scp-next run download-logs
+```
+
+`run` 命令也支持临时覆盖路径。
+
+```bash
+scp-next run deploy ./dist-canary /var/www/canary
+```
+
+配置优先级从高到低如下。
+
+1. 显式 CLI 选项
+2. 位置参数
+3. 环境变量
+4. 选中的配置 profile
+5. 根级配置值
+6. 配置的 job 值
+7. 内部默认值
+
+不要把包含真实密码的配置文件提交到 Public 仓库。共享仓库和部署环境应优先使用 `SCP_NEXT_PASSWORD` 或受保护的密钥文件。
+
+## 库 API 用法
+
+ESM 项目可以直接导入 `upload`。
+
+```ts
+import { upload } from "scp-next";
+
+await upload({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  password: process.env.SCP_NEXT_PASSWORD,
+  localPath: "./dist",
+  remotePath: "/var/www/example",
+  recursive: true,
+  overwrite: true
+});
+```
+
+CommonJS 项目可以使用 `require`。
+
+```js
+const { download } = require("scp-next");
+
+async function main() {
+  await download({
+    host: process.env.SCP_NEXT_HOST,
+    username: process.env.SCP_NEXT_USERNAME,
+    password: process.env.SCP_NEXT_PASSWORD,
+    remotePath: "/var/log/example.log",
+    localPath: "./logs/example.log"
+  });
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});
+```
+
+如果一次连接内要执行多个操作，可以创建可复用客户端。
+
+```ts
+import { createClient } from "scp-next";
+
+const client = createClient({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  password: process.env.SCP_NEXT_PASSWORD
+});
+
+try {
+  await client.connect();
+  await client.upload("./dist", "/var/www/example", { recursive: true });
+  await client.download("/var/log/example.log", "./logs/example.log");
+} finally {
+  await client.close();
+}
+```
+
+主要导出如下。
+
+```ts
+upload(options);
+download(options);
+createClient(options);
+copy(options);
+```
+
+错误类型包含稳定的 `code`、可读的 `message` 和经过脱敏的上下文。常见错误包括 `ConfigurationError`、`AuthenticationError`、`ConnectionError`、`TransferError` 和 `HostVerificationError`。
+
+## 主机验证
+
+`scp-next` 支持通过 `hostFingerprint` 或 `knownHostsFile` 验证主机。如果没有显式配置，他会读取 `~/.ssh/known_hosts`。
+
+在 CI 或部署环境中，如果没有可用的 known-hosts 文件，建议配置 `hostFingerprint`。如果无法建立主机验证，`scp-next` 会失败退出。
+
+## 新人接手清单
+
+接手项目时，可以按以下顺序验证。
+
+1. 确认 Node.js 版本不低于 18.18.0。
+2. 使用 `npm install --global scp-next` 安装 CLI。
+3. 用 `scp-next upload ... --dry-run` 验证参数和路径。
+
+掌握这几项后，就可以把 `scp-next` 用于日常部署脚本、日志下载任务和 Node.js 文件传输流程。
+
+**版权声明**
+
+本文为原创文章，作者保留版权。转载请保留本文完整内容，并以超链接形式注明作者及原文出处。
+
+作者: [除除](https://github.com/chengchuu)
+原文: <https://blog.mazey.net/6454.html>
+
+<!-- ID: introducing-scp-next-v1.0.19-zh -->
+
+(完)

package/docs/release-notes/introducing-scp-next-v1.0.2.md

@@ -0,0 +1,186 @@
+# Introducing scp-next v1.0.2
+
+`scp-next` is an SCP-style command-line tool and TypeScript library for secure file transfers
+over SSH. It keeps the familiar upload/download workflow while using SFTP internally through
+`ssh2-sftp-client`, avoiding custom protocol code and normal remote shell execution.
+
+## Why scp-next
+
+File transfer tools often start simple and become harder to manage once deployments need
+profiles, dry runs, recursive directories, secret handling, and reusable application code.
+`scp-next` is built for that middle ground: easy to run from a terminal, but structured enough
+to use safely in scripts, CI, and Node.js applications.
+
+## Highlights
+
+- Upload and download files or directories recursively.
+- Use clear CLI operands: `<source> <destination>`.
+- Import the library from ESM or CommonJS projects.
+- Configure servers with JSON files, named profiles, jobs, or environment variables.
+- Preview operations with dry-run mode before connecting.
+- Track transfer progress when supported by the SFTP client.
+- Control overwrites, timeouts, and destination directory creation.
+- Redact passwords, passphrases, and private-key contents from logs and errors.
+- Reuse a transfer client across multiple upload and download operations.
+
+## Install
+
+Global CLI installation:
+
+```bash
+npm install --global scp-next
+```
+
+Library installation:
+
+```bash
+npm install scp-next
+```
+
+## CLI Usage
+
+Uploads treat `source` as local and `destination` as remote:
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host example.com \
+  --username deploy \
+  --private-key-file ~/.ssh/id_ed25519 \
+  --recursive \
+  --create-directories
+```
+
+Downloads treat `source` as remote and `destination` as local:
+
+```bash
+scp-next download /var/log/example.log ./logs/example.log \
+  --host example.com \
+  --username deploy \
+  --private-key-file ~/.ssh/id_ed25519 \
+  --create-directories
+```
+
+Run a configured job:
+
+```bash
+scp-next run deploy
+```
+
+## Library Usage
+
+ESM:
+
+```ts
+import { upload } from "scp-next";
+
+await upload({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  privateKeyFile: process.env.SCP_NEXT_PRIVATE_KEY_FILE,
+  localPath: "./dist",
+  remotePath: "/var/www/example",
+  recursive: true,
+  overwrite: true
+});
+```
+
+CommonJS:
+
+```js
+const { download } = require("scp-next");
+
+await download({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  privateKeyFile: process.env.SCP_NEXT_PRIVATE_KEY_FILE,
+  remotePath: "/var/log/example.log",
+  localPath: "./logs/example.log"
+});
+```
+
+Reusable client:
+
+```ts
+import { createClient } from "scp-next";
+
+const client = createClient({
+  host: process.env.SCP_NEXT_HOST,
+  username: process.env.SCP_NEXT_USERNAME,
+  privateKeyFile: process.env.SCP_NEXT_PRIVATE_KEY_FILE
+});
+
+try {
+  await client.connect();
+  await client.upload("./dist", "/var/www/example", { recursive: true });
+  await client.download("/var/log/example.log", "./logs/example.log");
+} finally {
+  await client.close();
+}
+```
+
+## Configuration
+
+`scp-next` supports `scp-next.config.json`, `.scp-nextrc`, `.scp-nextrc.json`, or an explicit
+`--config` path.
+
+```json
+{
+  "profiles": {
+    "production": {
+      "host": "production.example.com",
+      "username": "deploy",
+      "privateKeyFile": "~/.ssh/id_ed25519"
+    }
+  },
+  "jobs": {
+    "deploy": {
+      "operation": "upload",
+      "profile": "production",
+      "source": "./dist",
+      "destination": "/var/www/example",
+      "recursive": true,
+      "overwrite": true,
+      "createDirectories": true
+    }
+  }
+}
+```
+
+## Security Notes
+
+`scp-next` is designed to make safer defaults and patterns easy:
+
+- Prefer environment variables, SSH agents, or protected private-key files over CLI password
+  arguments.
+- Passwords, passphrases, and private-key contents are redacted from logs and error context.
+- Host verification uses `hostFingerprint`, `knownHostsFile`, or `~/.ssh/known_hosts`.
+- Remote paths are handled with POSIX rules, while local paths use the current operating
+  system's path behavior.
+- Normal transfers use SFTP and do not execute remote shell commands.
+
+## Transfer Terminology
+
+The CLI uses the standard `<source> <destination>` order:
+
+```text
+Operation  Source  Destination
+Upload     Local   Remote
+Download   Remote  Local
+```
+
+The TypeScript API uses explicit `localPath` and `remotePath` names for upload and download
+calls, so application code does not need to infer path locality from transfer direction.
+
+## What's Included in v1.0.2
+
+- CLI commands for upload, download, and configured jobs.
+- ESM, CommonJS, and TypeScript declaration outputs.
+- Recursive directory transfers.
+- Dry-run support.
+- Configuration files, profiles, jobs, and environment variables.
+- Typed errors and validation for common configuration, filesystem, connection, and transfer
+  failures.
+- Mockable transport architecture for tests and future integration coverage.
+
+`scp-next` v1.0.2 is ready for CLI workflows, deployment scripts, and Node.js applications that
+need secure SSH file transfers without hand-rolled protocol logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scp-next",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "A SCP CLI and library for secure SSH file transfers using SFTP.",
   "type": "module",
   "main": "./dist/index.cjs",