scp-next 1.0.19 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+- Added opt-in, repeatable `--post-upload-command` commands for CLI uploads and configured
+  upload jobs.
+- Added library `postUploadCommands`, `client.exec()`, `ExecResult`, and typed
+  `RemoteCommandError` APIs.
+- Kept remote command execution separate from SFTP, sequential, disabled for downloads and dry
+  runs, and fail-fast on non-zero exit codes.
+- Added bounded command output capture, CLI failure propagation, secret redaction, and mock-based
+  coverage for upload failure, ordering, command failure, dry-run, and connection cleanup.
+
 ## 1.0.19
 
 - Refined README structure for clearer installation, quick start, basic usage, advanced usage,
@@ -9,7 +20,7 @@
 - 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.
+- Moved release notes under `guides/release-notes/` for cleaner documentation organization.
 
 ## 1.0.14
 

package/README.md

@@ -19,25 +19,27 @@
 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/).
 
+## Features
+
+- Upload and download files or directories recursively.
+- CLI usage with clear `<source> <destination>` operands.
+- ESM `import` and CommonJS `require` support.
+- JSON configuration files, named profiles, and configured jobs.
+- Reusable transfer client.
+- Optional sequential remote commands after a successful upload.
+
 ## Contents
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Basic Usage](#basic-usage)
+- [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)
-
-## Features
-
-- Upload and download files or directories recursively.
-- CLI usage with clear `<source> <destination>` operands.
-- ESM `import` and CommonJS `require` support.
-- JSON configuration files, named profiles, and configured jobs.
-- Reusable transfer client.
+- [User Guides](#user-guides)
 
 ## Installation
 
@@ -99,7 +101,7 @@ await upload({
 });
 ```
 
-## Basic Usage
+## CLI Usage
 
 ### CLI Syntax
 
@@ -144,6 +146,21 @@ scp-next upload ./dist /var/www/example \
   --verbose
 ```
 
+Run commands after a successful upload:
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --recursive \
+  --post-upload-command "cd /var/www/example && npm install --omit=dev" \
+  --post-upload-command "pm2 reload example"
+```
+
+`--post-upload-command` is repeatable and upload-only. Commands run sequentially on the
+remote server with the SSH user's permissions. The first non-zero exit code stops the sequence
+and makes the CLI exit non-zero. A missing exit status is also treated as failure.
+
 Use an encrypted private key:
 
 ```bash
@@ -201,6 +218,7 @@ 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. |
+| `--post-upload-command <command>`     | Run a remote command after a successful upload. Repeatable.             |
 | `--timeout <milliseconds>`            | SSH connection ready timeout in milliseconds.                          |
 | `--verbose`                           | Print non-sensitive diagnostic details.                                |
 | `--quiet`                             | Disable progress and non-error output.                                 |
@@ -223,7 +241,11 @@ await upload({
   localPath: "./dist",
   remotePath: "/var/www/example",
   recursive: true,
-  overwrite: true
+  overwrite: true,
+  postUploadCommands: [
+    "cd /var/www/example && npm install --omit=dev",
+    "pm2 reload example"
+  ]
 });
 ```
 
@@ -262,6 +284,8 @@ const client = createClient({
 try {
   await client.connect();
   await client.upload("./dist", "/var/www/example", { recursive: true });
+  const result = await client.exec("pm2 reload example");
+  console.log(result.stdout);
   await client.download("/var/log/example.log", "./logs/example.log");
 } finally {
   await client.close();
@@ -292,26 +316,33 @@ 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.          |
+| 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.                |
+| `postUploadCommands` | upload         | Remote command strings run sequentially after success.       |
+| `onProgress`        | transfer        | Progress callback for file and directory transfers.          |
+
+`client.exec(command, options)` returns `ExecResult` with `stdout`, `stderr`, `exitCode`,
+and an optional signal. Its optional `timeout` is command-specific; `failOnStderr` can treat
+stderr output as failure even when the exit code is zero. `maxBuffer` limits combined captured
+output and defaults to 10 MiB. A timeout closes the SSH channel; whether the remote process is
+terminated depends on the SSH server.
 
 ## Advanced Usage
 
@@ -417,7 +448,11 @@ Jobs use `source` and `destination`; the `operation` determines which path is lo
       "source": "./dist",
       "destination": "/var/www/example",
       "recursive": true,
-      "overwrite": true
+      "overwrite": true,
+      "postUploadCommands": [
+        "cd /var/www/example && npm install --omit=dev",
+        "pm2 reload example"
+      ]
     },
     "download-logs": {
       "operation": "download",
@@ -532,7 +567,7 @@ Interactive terminals display concise progress. Progress is disabled with `--qui
 
 ### Dry Run
 
-`--dry-run` resolves configuration and validates local paths and transfer direction without connecting to the remote server or modifying local/remote files.
+`--dry-run` resolves configuration and validates local paths and transfer direction without connecting to the remote server, transferring files, or executing post-upload commands. Planned post-upload commands are shown with known and recognizable secret values redacted.
 
 ```text
 Dry run: upload
@@ -540,6 +575,10 @@ Source: ./dist
 Destination: your-username@your-host:/var/www/example
 Recursive: yes
 Overwrite: yes
+
+Post-upload commands:
+1. cd /var/www/example && npm install --omit=dev
+2. pm2 reload example
 ```
 
 ## Error Handling
@@ -552,6 +591,7 @@ Public typed errors:
 - `AuthenticationError`
 - `ConnectionError`
 - `TransferError`
+- `RemoteCommandError`
 - `FileSystemError`
 - `HostVerificationError`
 
@@ -581,7 +621,7 @@ try {
 Primary functions:
 
 ```ts
-upload(options: UploadOptions): Promise<void>
+upload(options: UploadOptions): Promise<ExecResult[]>
 download(options: DownloadOptions): Promise<void>
 createClient(options: ScpServerOptions): ScpNextClient
 copy(options: CopyOptions): Promise<void>
@@ -589,6 +629,18 @@ 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.
+`ScpNextClient.exec(command, options)` executes one command directly through SSH.
+
+Post-upload execution is disabled unless `postUploadCommands` is present. Commands are sent
+directly to the remote SSH server, never through a local shell, and never run for downloads or
+dry runs. Do not put passwords, tokens, or other secrets directly in command strings; command
+output may also contain application data. `scp-next` redacts known credentials and common secret
+assignment forms from CLI logs and errors.
+
+## User Guides
+
+- [English](https://github.com/chengchuu/scp-next/blob/main/guides/release-notes/introducing-scp-next-v1.0.19-en.md)
+- [简体中文](https://github.com/chengchuu/scp-next/blob/main/guides/release-notes/introducing-scp-next-v1.0.19-zh.md)
 
 ## Development
 
@@ -598,6 +650,8 @@ npm run typecheck
 npm run lint
 npm test
 npm run build
+npm run docs:links
+npm run docs:build
 npm pack --dry-run
 ```
 
@@ -605,7 +659,9 @@ npm pack --dry-run
 
 ## Publishing
 
-The published package includes `dist`, README, license, changelog, and docs. The CLI entry is `dist/cli/index.js` and contains a Node.js shebang.
+The published package includes `dist`, README, license, changelog, and handwritten guides. The CLI
+entry is `dist/cli/index.js` and contains a Node.js shebang. `npm run docs:build` generates the
+GitHub Pages artifact under `docs/`; do not edit or commit that output directly.
 
 ## Transfer Mechanism