scp-next 1.0.20 → 1.1.3

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

@@ -18,6 +18,9 @@
 `scp-next` is an SCP-style command-line tool and library for secure file transfers over SSH.
 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/).
+Use the [interactive examples](https://chengchuu.github.io/scp-next/examples/) to generate
+CLI and TypeScript transfer snippets, or browse the
+[API documentation](https://chengchuu.github.io/scp-next/api/).
 
 ## Features
 
@@ -26,6 +29,7 @@ Developer documentation is available at [GitHub Pages](https://chengchuu.github.
 - 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
 
@@ -145,6 +149,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
@@ -202,6 +221,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.                                 |
@@ -224,7 +244,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"
+  ]
 });
 ```
 
@@ -263,6 +287,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();
@@ -293,26 +319,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
 
@@ -418,7 +451,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",
@@ -533,7 +570,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
@@ -541,6 +578,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
@@ -553,6 +594,7 @@ Public typed errors:
 - `AuthenticationError`
 - `ConnectionError`
 - `TransferError`
+- `RemoteCommandError`
 - `FileSystemError`
 - `HostVerificationError`
 
@@ -582,7 +624,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>
@@ -590,11 +632,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/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)
+- [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
 
@@ -604,6 +653,8 @@ npm run typecheck
 npm run lint
 npm test
 npm run build
+npm run docs:links
+npm run docs
 npm pack --dry-run
 ```
 
@@ -611,7 +662,10 @@ 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` generates TypeDoc,
+builds the website and examples with Webpack, assembles the GitHub Pages artifact under `docs/`,
+and validates its SEO and PWA metadata. Do not edit or commit generated output directly.
 
 ## Transfer Mechanism