scp-next 1.0.12 → 1.0.13

package/README.md

@@ -16,8 +16,7 @@
 [docs-url]: https://chengchuu.github.io/scp-next/
 
 `scp-next` is an SCP-style command-line tool and library for secure file transfers over SSH.
-The package uses SFTP internally through `ssh2-sftp-client` instead of implementing SCP or SFTP protocols manually.
-
+It uses SFTP internally through `ssh2-sftp-client` instead of implementing SCP or SFTP protocols manually.
 Developer documentation is available at <https://chengchuu.github.io/scp-next/>.
 
 ## Features
@@ -26,19 +25,62 @@ Developer documentation is available at <https://chengchuu.github.io/scp-next/>.
 - CLI usage with clear `<source> <destination>` operands.
 - ESM `import` and CommonJS `require` support.
 - JSON configuration files, named profiles, and configured jobs.
-- Environment-variable-based credentials.
-- Dry-run mode, progress callbacks, timeouts, overwrite control, and destination directory creation.
-- Secret redaction for passwords, passphrases, and private-key contents.
 - Reusable transfer client.
 
 ## Installation
 
+CLI:
+
 ```bash
 npm install --global scp-next
+```
+
+Library:
+
+```bash
 npm install scp-next
 ```
 
-## CLI Syntax
+## Quick Start
+
+Upload with password authentication:
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive
+```
+
+Download with private-key authentication:
+
+```bash
+scp-next download /var/log/example.log ./logs/example.log \
+  --host your-host \
+  --username your-username \
+  --private-key-file ~/.ssh/id_ed25519
+```
+
+Use the library:
+
+```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
+});
+```
+
+## Basic Usage
+
+### CLI Syntax
 
 ```text
 scp-next upload <source> <destination> [options]
@@ -49,41 +91,33 @@ scp-next run <job> [source] [destination] [options]
 CLI commands use `<source> <destination>`. Programmatic upload and download APIs use
 `localPath` and `remotePath`.
 
+| Operation | Source | Destination |
+| --------- | ------ | ----------- |
+| Upload    | Local  | Remote      |
+| Download  | Remote | Local       |
+
 Destination paths follow familiar `cp`/`scp` behavior. If the destination exists as a directory or ends with a path separator, `scp-next` places the source inside that directory using the source basename. Missing destination directories are created by default.
 
-## Upload Examples
+### Upload Examples
 
 ```bash
 scp-next upload ./dist /var/www/example \
-  --host example.com \
-  --username deploy \
+  --host your-host \
+  --username your-username \
   --private-key-file ~/.ssh/id_ed25519 \
   --recursive
 ```
 
-Password authentication:
-
-```bash
-scp-next upload ./dist /var/www/example \
-  --host example.com \
-  --username deploy \
-  --password "your-password" \
-  --recursive
-```
-
-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.
-
-## Download Examples
+### Download Examples
 
 ```bash
 scp-next download /var/log/example.log ./logs/example.log \
-  --host example.com \
-  --username deploy \
+  --host your-host \
+  --username your-username \
   --private-key-file ~/.ssh/id_ed25519
 ```
 
-## CLI Options
+### CLI Options
 
 | Option                                | Description                                                            |
 | ------------------------------------- | ---------------------------------------------------------------------- |
@@ -107,7 +141,68 @@ scp-next download /var/log/example.log ./logs/example.log \
 | `--help`                              | Show command help.                                                     |
 | `--version`                           | Show the package version.                                              |
 
-## Configuration Files
+## Library Usage
+
+### ESM Upload
+
+```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 Download
+
+```js
+const { download } = require("scp-next");
+
+async function main() {
+  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"
+  });
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});
+```
+
+### 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();
+}
+```
+
+## Advanced Usage
+
+### Configuration Files
 
 `scp-next` searches for these files in the current directory:
 
@@ -128,9 +223,9 @@ Example:
 ```json
 {
   "server": {
-    "host": "example.com",
+    "host": "your-host",
     "port": 22,
-    "username": "deploy",
+    "username": "your-username",
     "privateKeyFile": "~/.ssh/id_ed25519"
   },
   "transfer": {
@@ -142,22 +237,22 @@ Example:
 }
 ```
 
-## Named Profiles
+### Named Profiles
 
 ```json
 {
   "defaultProfile": "production",
   "profiles": {
     "production": {
-      "host": "production.example.com",
+      "host": "your-host-a",
       "port": 22,
-      "username": "deploy",
+      "username": "your-username-a",
       "privateKeyFile": "~/.ssh/id_ed25519"
     },
     "staging": {
-      "host": "staging.example.com",
+      "host": "your-host-b",
       "port": 22,
-      "username": "deploy",
+      "username": "your-username-b",
       "privateKeyFile": "~/.ssh/id_ed25519"
     }
   }
@@ -168,7 +263,7 @@ Example:
 scp-next upload ./dist /var/www/example --profile production
 ```
 
-## Configured Jobs
+### Configured Jobs
 
 Jobs use `source` and `destination`; the `operation` determines which path is local or remote.
 
@@ -176,8 +271,8 @@ Jobs use `source` and `destination`; the `operation` determines which path is lo
 {
   "profiles": {
     "production": {
-      "host": "production.example.com",
-      "username": "deploy",
+      "host": "your-host",
+      "username": "your-username",
       "privateKeyFile": "~/.ssh/id_ed25519"
     }
   },
@@ -208,7 +303,7 @@ scp-next run download-logs
 
 `scp-next run <job> [source] [destination]` permits explicit path overrides.
 
-## Environment Variables
+### Environment Variables
 
 ```text
 SCP_NEXT_HOST
@@ -225,8 +320,8 @@ SCP_NEXT_PROFILE
 Bash:
 
 ```bash
-export SCP_NEXT_HOST="example.com"
-export SCP_NEXT_USERNAME="deploy"
+export SCP_NEXT_HOST="your-host"
+export SCP_NEXT_USERNAME="your-username"
 export SCP_NEXT_PRIVATE_KEY_FILE="$HOME/.ssh/id_ed25519"
 scp-next upload ./dist /var/www/example --recursive
 ```
@@ -234,13 +329,13 @@ scp-next upload ./dist /var/www/example --recursive
 PowerShell:
 
 ```powershell
-$env:SCP_NEXT_HOST = "example.com"
-$env:SCP_NEXT_USERNAME = "deploy"
+$env:SCP_NEXT_HOST = "your-host"
+$env:SCP_NEXT_USERNAME = "your-username"
 $env:SCP_NEXT_PRIVATE_KEY_FILE = "$HOME\.ssh\id_ed25519"
 scp-next upload .\dist /var/www/example --recursive
 ```
 
-## Configuration Precedence
+### Configuration Precedence
 
 Highest to lowest:
 
@@ -254,66 +349,7 @@ Highest to lowest:
 
 For `run`, job values are loaded first, then root configuration, selected profile, environment variables, explicit positional overrides, and CLI options.
 
-## Library Usage
-
-ESM upload:
-
-```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 download:
-
-```js
-const { download } = require("scp-next");
-
-async function main() {
-  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"
-  });
-}
-
-main().catch((error) => {
-  console.error(error.message);
-  process.exitCode = 1;
-});
-```
-
-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();
-}
-```
-
-## Authentication
+### Authentication
 
 Supported methods:
 
@@ -323,24 +359,24 @@ Supported methods:
 - Private-key passphrase
 - SSH agent authentication through `agent` or `SSH_AUTH_SOCK`
 
-## Host Verification
+### 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.
 
 `scp-next` fails closed if it cannot establish a host verifier. Use `hostFingerprint` for CI or deployments where a known-hosts file is not available.
 
-## Progress Reporting
+### Progress Reporting
 
 Interactive terminals display concise progress. Progress is disabled with `--quiet` or when stderr is not a TTY, which keeps CI logs readable. Library users can pass `onProgress`.
 
-## Dry Run
+### Dry Run
 
 `--dry-run` resolves configuration and validates local paths and transfer direction without connecting to the remote server or modifying local/remote files.
 
 ```text
 Dry run: upload
 Source: ./dist
-Destination: deploy@example.com:/var/www/example
+Destination: your-username@your-host:/var/www/example
 Recursive: yes
 Overwrite: yes
 ```

package/dist/cli/index.js

@@ -919,9 +919,12 @@ var ScpNextClientImpl = class {
     }
     const exists = await this.transport.exists(remotePath);
     if (exists) {
-      throw new TransferError(`Remote destination already exists: ${remotePath}`, {
-        context: { remotePath }
-      });
+      throw new TransferError(
+        `Remote destination already exists: ${remotePath}. Use --overwrite to overwrite it.`,
+        {
+          context: { remotePath }
+        }
+      );
     }
   }
   async assertLocalOverwrite(localPath, overwrite = false) {
@@ -1279,15 +1282,36 @@ function createProgressReporter(output, quiet) {
   if (quiet || !output.stderr.isTTY) {
     return void 0;
   }
+  const minimumUpdateIntervalMs = 500;
+  let lastLineLength = 0;
+  let lastPercentage;
+  let lastWriteAt = 0;
+  let completed = false;
   return (progress) => {
+    if (completed) {
+      return;
+    }
+    const now = Date.now();
+    const totalBytes = progress.totalBytes;
+    const isComplete = progress.percentage === 100 || totalBytes !== void 0 && totalBytes > 0 && progress.transferredBytes >= totalBytes;
+    const percentageChanged = progress.percentage !== void 0 && progress.percentage !== lastPercentage;
+    if (!isComplete && !percentageChanged && lastWriteAt !== 0 && now - lastWriteAt < minimumUpdateIntervalMs) {
+      return;
+    }
     const total = progress.totalBytes ? formatBytes(progress.totalBytes) : "?";
     const transferred = formatBytes(progress.transferredBytes);
     const percentage2 = progress.percentage === void 0 ? "" : ` (${progress.percentage}%)`;
     const currentFile = progress.currentFile ? `: ${progress.currentFile}` : "";
-    output.stderr.write(`\r${progress.operation === "upload" ? "Uploading" : "Downloading"}${currentFile}
-`);
-    output.stderr.write(`${transferred} / ${total}${percentage2}
-`);
+    const line = `${progress.operation === "upload" ? "Uploading" : "Downloading"}${currentFile} ${transferred} / ${total}${percentage2}`;
+    const padding = " ".repeat(Math.max(0, lastLineLength - line.length));
+    output.stderr.write(`\r${line}${padding}`);
+    lastLineLength = line.length;
+    lastPercentage = progress.percentage;
+    lastWriteAt = now;
+    if (isComplete) {
+      output.stderr.write("\n");
+      completed = true;
+    }
   };
 }
 function verbosePlan(output, config) {