scp-next 1.0.5 → 1.0.7

package/README.md

@@ -13,8 +13,7 @@
 [module-image]: https://img.shields.io/badge/module-ESM%20%2B%20CJS-blue
 
 `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.
+The package uses SFTP internally through `ssh2-sftp-client` instead of implementing SCP or SFTP protocols manually.
 
 ## Features
 
@@ -45,6 +44,9 @@ scp-next run <job> [source] [destination] [options]
 CLI commands use `<source> <destination>`. Programmatic upload and download APIs use
 `localPath` and `remotePath`.
 
+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.
+Use `--create-directories` when a destination directory may be missing.
+
 ## Upload Examples
 
 ```bash
@@ -66,9 +68,8 @@ scp-next upload ./dist /var/www/example \
   --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.
+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
 
@@ -248,8 +249,7 @@ Highest to lowest:
 6. Configured job values
 7. Internal defaults
 
-For `run`, job values are loaded first, then root configuration, selected profile,
-environment variables, explicit positional overrides, and CLI options.
+For `run`, job values are loaded first, then root configuration, selected profile, environment variables, explicit positional overrides, and CLI options.
 
 ## Library Usage
 
@@ -322,23 +322,17 @@ Supported methods:
 
 ## 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.
+`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.
+`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
 
-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`.
+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` 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 or modifying local/remote files.
 
 ```text
 Dry run: upload
@@ -361,8 +355,7 @@ Public typed errors:
 - `FileSystemError`
 - `HostVerificationError`
 
-Each error includes a stable `code`, readable `message`, optional `cause`, and redacted
-non-sensitive context.
+Each error includes a stable `code`, readable `message`, optional `cause`, and redacted non-sensitive context.
 
 ```ts
 import { AuthenticationError, upload } from "scp-next";
@@ -394,8 +387,8 @@ createClient(options: ScpServerOptions): ScpNextClient
 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.
+Upload and download APIs use explicit `localPath` and `remotePath` names.
+The optional generic `copy()` API accepts typed local/remote endpoint objects.
 
 ## Development
 
@@ -412,11 +405,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 docs. The CLI entry is `dist/cli/index.js` and contains a Node.js shebang.
 
 ## Transfer Mechanism
 
-Despite the package name, normal transfers use SFTP through `ssh2-sftp-client`, which is built
-on `ssh2`. This avoids remote shell execution for regular transfers and gives better support
-for progress reporting and recursive directory traversal than shelling out to an SCP command.
+Despite the package name, normal transfers use SFTP through `ssh2-sftp-client`, which is built on `ssh2`.
+This avoids remote shell execution for regular transfers and gives better support for progress reporting and recursive directory traversal than shelling out to an SCP command.

package/dist/cli/index.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from "url";
 import { Command as Command4, CommanderError } from "commander";
 
 // src/client/client.ts
-import { access as access4, mkdir as mkdir2 } from "fs/promises";
+import { access as access4, mkdir as mkdir2, stat as stat3 } from "fs/promises";
 import path4 from "path";
 
 // src/client/transport.ts
@@ -580,6 +580,38 @@ function percentage(transferredBytes, totalBytes) {
 function mergeOptions(serverOptions, transferOptions) {
   return { ...serverOptions, ...transferOptions ?? {} };
 }
+function hasTrailingPathSeparator(inputPath) {
+  return /[\\/]$/.test(inputPath);
+}
+function trimmedRemoteDirectory(remotePath) {
+  return remotePath.replace(/\/+$/g, "") || "/";
+}
+function remoteBasename(remotePath) {
+  return path4.posix.basename(trimmedRemoteDirectory(remotePath));
+}
+async function isExistingLocalDirectory(localPath) {
+  try {
+    return (await stat3(localPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function ensureLocalDirectory(localPath, createParents = false) {
+  try {
+    const stats = await stat3(localPath);
+    if (stats.isDirectory()) {
+      return;
+    }
+    throw new TransferError(`Local destination already exists and is not a directory: ${localPath}`, {
+      context: { localPath }
+    });
+  } catch (error) {
+    if (error instanceof TransferError) {
+      throw error;
+    }
+    await mkdir2(localPath, { recursive: createParents });
+  }
+}
 var ScpNextClientImpl = class {
   serverOptions;
   transport;
@@ -656,22 +688,15 @@ var ScpNextClientImpl = class {
     const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
     let completedBytes = 0;
     let completedFiles = 0;
-    const destinationExists = await this.transport.exists(remotePath);
-    if (destinationExists && destinationExists !== "d") {
-      throw new TransferError(`Remote destination already exists and is not a directory: ${remotePath}`, {
-        context: { remotePath }
-      });
-    }
-    if (!destinationExists) {
-      if (!options.createDirectories) {
-        throw new TransferError(`Remote destination directory does not exist: ${remotePath}`, {
-          context: { remotePath }
-        });
-      }
-      await this.transport.mkdir(remotePath, true);
-    }
+    const destinationRoot = await this.resolveRemoteDestinationForLocalDirectory(
+      options,
+      remotePath
+    );
     for (const file of files) {
-      const destinationFile = remoteJoin(remotePath, file.relativePath.split(path4.sep).join("/"));
+      const destinationFile = remoteJoin(
+        destinationRoot,
+        file.relativePath.split(path4.sep).join("/")
+      );
       await this.ensureRemoteParent(destinationFile, true);
       await this.assertRemoteOverwrite(destinationFile, options.overwrite);
       await this.transport.uploadFile(file.absolutePath, destinationFile, (step) => {
@@ -721,6 +746,39 @@ var ScpNextClientImpl = class {
     await this.assertRemoteOverwrite(destinationFile, options.overwrite);
     return destinationFile;
   }
+  async resolveRemoteDestinationForLocalDirectory(options, remotePath) {
+    const remoteKind = await this.transport.exists(remotePath);
+    const isDirectoryLikeDestination = remoteKind === "d" || remotePath.endsWith("/");
+    const localDirectoryName = path4.basename(resolveLocalPath(options.localPath));
+    if (remoteKind && remoteKind !== "d") {
+      throw new TransferError(`Remote destination already exists and is not a directory: ${remotePath}`, {
+        context: { remotePath }
+      });
+    }
+    if (isDirectoryLikeDestination) {
+      const remoteDirectory = trimmedRemoteDirectory(remotePath);
+      if (!remoteKind) {
+        if (!options.createDirectories) {
+          throw new TransferError(`Remote destination directory does not exist: ${remoteDirectory}`, {
+            context: { remotePath }
+          });
+        }
+        await this.transport.mkdir(remoteDirectory, true);
+      }
+      const destinationRoot = remoteJoin(remoteDirectory, localDirectoryName);
+      await this.ensureRemoteDirectory(destinationRoot);
+      return destinationRoot;
+    }
+    if (!remoteKind) {
+      if (!options.createDirectories) {
+        throw new TransferError(`Remote destination directory does not exist: ${remotePath}`, {
+          context: { remotePath }
+        });
+      }
+      await this.transport.mkdir(remotePath, true);
+    }
+    return remotePath;
+  }
   async downloadWithTransport(options) {
     const remotePath = normalizeRemotePath(options.remotePath);
     const remoteKind = await this.transport.exists(remotePath);
@@ -739,7 +797,7 @@ var ScpNextClientImpl = class {
     await this.downloadSingleFile(options, remotePath);
   }
   async downloadSingleFile(options, remotePath) {
-    const localPath = resolveLocalPath(options.localPath);
+    const localPath = await this.resolveLocalDestinationForRemoteFile(options, remotePath);
     await this.assertLocalOverwrite(localPath, options.overwrite);
     if (options.createDirectories) {
       await mkdir2(path4.dirname(localPath), { recursive: true });
@@ -758,12 +816,12 @@ var ScpNextClientImpl = class {
   }
   async downloadDirectory(options) {
     const remotePath = normalizeRemotePath(options.remotePath);
-    const localRoot = resolveLocalPath(options.localPath);
+    const localRoot = await this.resolveLocalDestinationForRemoteDirectory(options, remotePath);
     const files = await walkRemoteFiles(this.transport, remotePath);
     const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
     let completedBytes = 0;
     let completedFiles = 0;
-    await mkdir2(localRoot, { recursive: Boolean(options.createDirectories) });
+    await ensureLocalDirectory(localRoot, Boolean(options.createDirectories));
     for (const file of files) {
       const localFile = path4.join(localRoot, ...file.relativePath.split("/"));
       await this.assertLocalOverwrite(localFile, options.overwrite);
@@ -786,6 +844,38 @@ var ScpNextClientImpl = class {
       completedFiles += 1;
     }
   }
+  async resolveLocalDestinationForRemoteFile(options, remotePath) {
+    const localDestination = resolveLocalPath(options.localPath);
+    const isDirectoryLikeDestination = hasTrailingPathSeparator(options.localPath) || await isExistingLocalDirectory(localDestination);
+    if (!isDirectoryLikeDestination) {
+      return localDestination;
+    }
+    if (!await isExistingLocalDirectory(localDestination)) {
+      if (!options.createDirectories) {
+        throw new TransferError(`Local destination directory does not exist: ${localDestination}`, {
+          context: { localPath: options.localPath }
+        });
+      }
+      await mkdir2(localDestination, { recursive: true });
+    }
+    return path4.join(localDestination, remoteBasename(remotePath));
+  }
+  async resolveLocalDestinationForRemoteDirectory(options, remotePath) {
+    const localDestination = resolveLocalPath(options.localPath);
+    const isDirectoryLikeDestination = hasTrailingPathSeparator(options.localPath) || await isExistingLocalDirectory(localDestination);
+    if (!isDirectoryLikeDestination) {
+      return localDestination;
+    }
+    if (!await isExistingLocalDirectory(localDestination)) {
+      if (!options.createDirectories) {
+        throw new TransferError(`Local destination directory does not exist: ${localDestination}`, {
+          context: { localPath: options.localPath }
+        });
+      }
+      await mkdir2(localDestination, { recursive: true });
+    }
+    return path4.join(localDestination, remoteBasename(remotePath));
+  }
   async ensureRemoteParent(remotePath, createDirectories = false) {
     const parent = remoteDirname(remotePath);
     if (parent === "." || parent === "/") {
@@ -802,6 +892,17 @@ var ScpNextClientImpl = class {
       });
     }
   }
+  async ensureRemoteDirectory(remotePath) {
+    const exists = await this.transport.exists(remotePath);
+    if (exists && exists !== "d") {
+      throw new TransferError(`Remote destination already exists and is not a directory: ${remotePath}`, {
+        context: { remotePath }
+      });
+    }
+    if (!exists) {
+      await this.transport.mkdir(remotePath, true);
+    }
+  }
   async assertRemoteOverwrite(remotePath, overwrite = false) {
     if (overwrite) {
       return;