scp-next 1.0.20 → 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

@@ -26,6 +26,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 +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
@@ -202,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.                                 |
@@ -224,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"
+  ]
 });
 ```
 
@@ -263,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();
@@ -312,8 +335,15 @@ await upload({
 | `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
 
 ### Configuration Files
@@ -418,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",
@@ -533,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
@@ -541,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
@@ -553,6 +591,7 @@ Public typed errors:
 - `AuthenticationError`
 - `ConnectionError`
 - `TransferError`
+- `RemoteCommandError`
 - `FileSystemError`
 - `HostVerificationError`
 
@@ -582,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>
@@ -590,11 +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/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 +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
 ```
 
@@ -611,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