scp-next 1.0.20 → 1.1.3

package/dist/index.cjs

@@ -1,1046 +1,1322 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+'use strict';
 
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  AuthenticationError: () => AuthenticationError,
-  ConfigurationError: () => ConfigurationError,
-  ConnectionError: () => ConnectionError,
-  FileSystemError: () => FileSystemError,
-  HostVerificationError: () => HostVerificationError,
-  ScpNextClientImpl: () => ScpNextClientImpl,
-  ScpNextError: () => ScpNextError,
-  TransferError: () => TransferError,
-  ValidationError: () => ValidationError,
-  copy: () => copy,
-  createClient: () => createClient,
-  download: () => download,
-  toScpNextError: () => toScpNextError,
-  upload: () => upload
-});
-module.exports = __toCommonJS(src_exports);
+var promises = require('node:fs/promises');
+var path = require('node:path');
+var SftpClient = require('ssh2-sftp-client');
+var node_crypto = require('node:crypto');
+var node_fs = require('node:fs');
+var os = require('node:os');
+var ssh2 = require('ssh2');
 
-// src/client/client.ts
-var import_promises6 = require("fs/promises");
-var import_node_path4 = __toESM(require("path"), 1);
-
-// src/client/transport.ts
-var import_promises3 = require("fs/promises");
-var import_ssh2_sftp_client = __toESM(require("ssh2-sftp-client"), 1);
-
-// src/security/redact.ts
-var SENSITIVE_KEYS = [
-  "password",
-  "passphrase",
-  "privatekey",
-  "privatekeyfile",
-  "token",
-  "authorization",
-  "credential",
-  "secret"
+const SENSITIVE_KEYS = [
+    "password",
+    "passphrase",
+    "privatekey",
+    "privatekeyfile",
+    "token",
+    "authorization",
+    "credential",
+    "secret"
 ];
-var PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+const PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+const SECRET_OPTION_PATTERN = /(--(?:password|passphrase|token|secret|authorization|credential)(?:=|\s+))(?:"[^"]*"|'[^']*'|\S+)/gi;
+const SECRET_ASSIGNMENT_PATTERN = /(\b(?:password|passphrase|token|secret|authorization|credential)[A-Z0-9_-]*\s*=\s*)(?:"[^"]*"|'[^']*'|[^\s&]+)/gi;
 function isSensitiveKey(key) {
-  const normalized = key.replace(/[-_\s]/g, "").toLowerCase();
-  return SENSITIVE_KEYS.some((sensitive) => normalized.includes(sensitive));
+    const normalized = key.replace(/[-_\s]/g, "").toLowerCase();
+    return SENSITIVE_KEYS.some((sensitive) => normalized.includes(sensitive));
 }
 function redactSensitiveValues(value) {
-  if (typeof value === "string") {
-    return value.replace(PRIVATE_KEY_PATTERN, "[REDACTED]");
-  }
-  if (Array.isArray(value)) {
-    const redacted = value.map((item) => redactSensitiveValues(item));
-    return redacted;
-  }
-  if (value && typeof value === "object") {
-    const redacted = {};
-    for (const [key, nestedValue] of Object.entries(value)) {
-      redacted[key] = isSensitiveKey(key) ? "[REDACTED]" : redactSensitiveValues(nestedValue);
-    }
-    return redacted;
-  }
-  return value;
+    if (typeof value === "string") {
+        return value.replace(PRIVATE_KEY_PATTERN, "[REDACTED]");
+    }
+    if (Array.isArray(value)) {
+        const redacted = value.map((item) => redactSensitiveValues(item));
+        return redacted;
+    }
+    if (value && typeof value === "object") {
+        const redacted = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            redacted[key] = isSensitiveKey(key) ? "[REDACTED]" : redactSensitiveValues(nestedValue);
+        }
+        return redacted;
+    }
+    return value;
 }
 function formatErrorMessage(error) {
-  if (error instanceof Error) {
-    return String(redactSensitiveValues(error.message));
-  }
-  return String(redactSensitiveValues(error));
+    if (error instanceof Error) {
+        return redactKnownSensitiveValues(error.message, {});
+    }
+    return redactKnownSensitiveValues(String(error), {});
+}
+function redactKnownSensitiveValues(text, source) {
+    const sensitiveValues = collectSensitiveValues(source);
+    const redactedKnownValues = sensitiveValues.reduce((redacted, value) => redacted.split(value).join("[REDACTED]"), String(redactSensitiveValues(text)));
+    return redactedKnownValues
+        .replace(SECRET_OPTION_PATTERN, "$1[REDACTED]")
+        .replace(SECRET_ASSIGNMENT_PATTERN, "$1[REDACTED]");
+}
+function collectSensitiveValues(value, key = "") {
+    if (isSensitiveKey(key)) {
+        if (typeof value === "string" && value) {
+            return [value];
+        }
+        if (Buffer.isBuffer(value) && value.length > 0) {
+            return [value.toString("utf8")];
+        }
+        return [];
+    }
+    if (!value || typeof value !== "object") {
+        return [];
+    }
+    return Object.entries(value).flatMap(([nestedKey, nestedValue]) => collectSensitiveValues(nestedValue, nestedKey));
 }
 
-// src/errors/index.ts
-var ScpNextError = class extends Error {
-  code;
-  context;
-  constructor(message, options = {}) {
-    super(message, { cause: options.cause });
-    this.name = new.target.name;
-    this.code = options.code ?? "SCP_NEXT_ERROR";
-    this.context = redactSensitiveValues(options.context ?? {});
-  }
-};
-var ConfigurationError = class extends ScpNextError {
-  constructor(message, options = {}) {
-    super(message, { ...options, code: "SCP_NEXT_CONFIGURATION_ERROR" });
-  }
-};
-var ValidationError = class extends ScpNextError {
-  constructor(message, options = {}) {
-    super(message, { ...options, code: "SCP_NEXT_VALIDATION_ERROR" });
-  }
-};
-var AuthenticationError = class extends ScpNextError {
-  constructor(message, options = {}) {
-    super(message, { ...options, code: "SCP_NEXT_AUTHENTICATION_ERROR" });
-  }
-};
-var ConnectionError = class extends ScpNextError {
-  constructor(message, options = {}) {
-    super(message, { ...options, code: "SCP_NEXT_CONNECTION_ERROR" });
-  }
-};
-var TransferError = class extends ScpNextError {
-  constructor(message, options = {}) {
-    super(message, { ...options, code: "SCP_NEXT_TRANSFER_ERROR" });
-  }
-};
-var FileSystemError = class extends ScpNextError {
-  constructor(message, options = {}) {
-    super(message, { ...options, code: "SCP_NEXT_FILESYSTEM_ERROR" });
-  }
-};
-var HostVerificationError = class extends ScpNextError {
-  constructor(message, options = {}) {
-    super(message, { ...options, code: "SCP_NEXT_HOST_VERIFICATION_ERROR" });
-  }
-};
+class ScpNextError extends Error {
+    code;
+    context;
+    constructor(message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = new.target.name;
+        this.code = options.code ?? "SCP_NEXT_ERROR";
+        this.context = redactSensitiveValues(options.context ?? {});
+    }
+}
+class ConfigurationError extends ScpNextError {
+    constructor(message, options = {}) {
+        super(message, { ...options, code: "SCP_NEXT_CONFIGURATION_ERROR" });
+    }
+}
+class ValidationError extends ScpNextError {
+    constructor(message, options = {}) {
+        super(message, { ...options, code: "SCP_NEXT_VALIDATION_ERROR" });
+    }
+}
+class AuthenticationError extends ScpNextError {
+    constructor(message, options = {}) {
+        super(message, { ...options, code: "SCP_NEXT_AUTHENTICATION_ERROR" });
+    }
+}
+class ConnectionError extends ScpNextError {
+    constructor(message, options = {}) {
+        super(message, { ...options, code: "SCP_NEXT_CONNECTION_ERROR" });
+    }
+}
+class TransferError extends ScpNextError {
+    constructor(message, options = {}) {
+        super(message, { ...options, code: "SCP_NEXT_TRANSFER_ERROR" });
+    }
+}
+class RemoteCommandError extends ScpNextError {
+    exitCode;
+    signal;
+    stdout;
+    stderr;
+    constructor(message, options) {
+        super(message, {
+            code: "SCP_NEXT_REMOTE_COMMAND_ERROR",
+            ...(options.cause !== undefined ? { cause: options.cause } : {}),
+            ...(options.context !== undefined ? { context: options.context } : {})
+        });
+        this.exitCode = options.exitCode;
+        this.signal = options.signal;
+        this.stdout = options.stdout ?? "";
+        this.stderr = options.stderr ?? "";
+    }
+}
+class FileSystemError extends ScpNextError {
+    constructor(message, options = {}) {
+        super(message, { ...options, code: "SCP_NEXT_FILESYSTEM_ERROR" });
+    }
+}
+class HostVerificationError extends ScpNextError {
+    constructor(message, options = {}) {
+        super(message, { ...options, code: "SCP_NEXT_HOST_VERIFICATION_ERROR" });
+    }
+}
 function toScpNextError(error) {
-  if (error instanceof ScpNextError) {
-    return error;
-  }
-  const message = error instanceof Error ? error.message : "Unexpected scp-next error.";
-  const lowerMessage = message.toLowerCase();
-  if (lowerMessage.includes("authentication") || lowerMessage.includes("permission denied")) {
-    return new AuthenticationError("SSH authentication failed.", { cause: error });
-  }
-  if (lowerMessage.includes("host verification") || lowerMessage.includes("host key") || lowerMessage.includes("fingerprint") || lowerMessage.includes("host") && lowerMessage.includes("denied")) {
-    return new HostVerificationError("SSH host verification failed.", { cause: error });
-  }
-  if (lowerMessage.includes("timed out") || lowerMessage.includes("connection") || lowerMessage.includes("econn")) {
-    return new ConnectionError("SSH connection failed.", { cause: error });
-  }
-  return new TransferError(String(redactSensitiveValues(message)), { cause: error });
+    if (error instanceof ScpNextError) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : "Unexpected scp-next error.";
+    const lowerMessage = message.toLowerCase();
+    if (lowerMessage.includes("authentication") || lowerMessage.includes("permission denied")) {
+        return new AuthenticationError("SSH authentication failed.", { cause: error });
+    }
+    if (lowerMessage.includes("host verification") ||
+        lowerMessage.includes("host key") ||
+        lowerMessage.includes("fingerprint") ||
+        (lowerMessage.includes("host") && lowerMessage.includes("denied"))) {
+        return new HostVerificationError("SSH host verification failed.", { cause: error });
+    }
+    if (lowerMessage.includes("timed out") ||
+        lowerMessage.includes("connection") ||
+        lowerMessage.includes("econn")) {
+        return new ConnectionError("SSH connection failed.", { cause: error });
+    }
+    return new TransferError(String(redactSensitiveValues(message)), { cause: error });
 }
 
-// src/security/host-verification.ts
-var import_node_crypto = require("crypto");
-var import_promises2 = require("fs/promises");
-
-// src/paths/local-path.ts
-var import_node_fs = require("fs");
-var import_promises = require("fs/promises");
-var import_node_os = __toESM(require("os"), 1);
-var import_node_path = __toESM(require("path"), 1);
 function expandHome(inputPath) {
-  if (inputPath === "~") {
-    return import_node_os.default.homedir();
-  }
-  if (inputPath.startsWith(`~${import_node_path.default.sep}`) || inputPath.startsWith("~/")) {
-    return import_node_path.default.join(import_node_os.default.homedir(), inputPath.slice(2));
-  }
-  return inputPath;
+    if (inputPath === "~") {
+        return os.homedir();
+    }
+    if (inputPath.startsWith(`~${path.sep}`) || inputPath.startsWith("~/")) {
+        return path.join(os.homedir(), inputPath.slice(2));
+    }
+    return inputPath;
 }
 function resolveLocalPath(inputPath, baseDir = process.cwd()) {
-  const expanded = expandHome(inputPath);
-  return import_node_path.default.isAbsolute(expanded) ? import_node_path.default.normalize(expanded) : import_node_path.default.resolve(baseDir, expanded);
+    const expanded = expandHome(inputPath);
+    return path.isAbsolute(expanded) ? path.normalize(expanded) : path.resolve(baseDir, expanded);
 }
 async function assertLocalPathExists(inputPath) {
-  try {
-    await (0, import_promises.access)(resolveLocalPath(inputPath), import_node_fs.constants.F_OK);
-  } catch (error) {
-    throw new FileSystemError(`Local path does not exist: ${inputPath}`, {
-      cause: error,
-      context: { path: inputPath }
-    });
-  }
+    try {
+        await promises.access(resolveLocalPath(inputPath), node_fs.constants.F_OK);
+    }
+    catch (error) {
+        throw new FileSystemError(`Local path does not exist: ${inputPath}`, {
+            cause: error,
+            context: { path: inputPath }
+        });
+    }
 }
 async function assertDownloadDestination(inputPath, createDirectories = false) {
-  const resolved = resolveLocalPath(inputPath);
-  const parent = import_node_path.default.dirname(resolved);
-  if (createDirectories) {
-    await (0, import_promises.mkdir)(parent, { recursive: true });
-    return;
-  }
-  try {
-    await (0, import_promises.access)(parent, import_node_fs.constants.W_OK);
-  } catch (error) {
-    throw new FileSystemError(`Local destination parent does not exist or is not writable: ${parent}`, {
-      cause: error,
-      context: { path: inputPath }
-    });
-  }
+    const resolved = resolveLocalPath(inputPath);
+    const parent = path.dirname(resolved);
+    if (createDirectories) {
+        await promises.mkdir(parent, { recursive: true });
+        return;
+    }
+    try {
+        await promises.access(parent, node_fs.constants.W_OK);
+    }
+    catch (error) {
+        throw new FileSystemError(`Local destination parent does not exist or is not writable: ${parent}`, {
+            cause: error,
+            context: { path: inputPath }
+        });
+    }
 }
 async function getLocalPathKind(inputPath) {
-  const stats = await (0, import_promises.stat)(resolveLocalPath(inputPath));
-  if (stats.isDirectory()) {
-    return "directory";
-  }
-  if (stats.isFile()) {
-    return "file";
-  }
-  throw new ValidationError(`Local path must be a file or directory: ${inputPath}`, {
-    context: { path: inputPath }
-  });
+    const stats = await promises.stat(resolveLocalPath(inputPath));
+    if (stats.isDirectory()) {
+        return "directory";
+    }
+    if (stats.isFile()) {
+        return "file";
+    }
+    throw new ValidationError(`Local path must be a file or directory: ${inputPath}`, {
+        context: { path: inputPath }
+    });
 }
 
-// src/security/host-verification.ts
 function normalizeFingerprint(fingerprint) {
-  return fingerprint.trim().replace(/^SHA256:/i, "").replace(/^sha256:/i, "").replace(/=+$/g, "");
+    return fingerprint
+        .trim()
+        .replace(/^SHA256:/i, "")
+        .replace(/^sha256:/i, "")
+        .replace(/=+$/g, "");
 }
 function isHexFingerprint(fingerprint) {
-  return /^[0-9a-f]+$/i.test(fingerprint);
+    return /^[0-9a-f]+$/i.test(fingerprint);
 }
 function fingerprintCandidates(fingerprint) {
-  const normalized = normalizeFingerprint(fingerprint);
-  const candidates = /* @__PURE__ */ new Set([normalized]);
-  if (isHexFingerprint(normalized)) {
-    candidates.add(normalized.toLowerCase());
-  } else {
-    try {
-      candidates.add(Buffer.from(normalized, "base64").toString("hex"));
-    } catch {
+    const normalized = normalizeFingerprint(fingerprint);
+    const candidates = new Set([normalized]);
+    if (isHexFingerprint(normalized)) {
+        candidates.add(normalized.toLowerCase());
     }
-  }
-  return [...candidates];
+    else {
+        try {
+            candidates.add(Buffer.from(normalized, "base64").toString("hex"));
+        }
+        catch {
+            // Keep the original normalized value when it is not valid base64.
+        }
+    }
+    return [...candidates];
 }
 function isFingerprintMatch(actual, expected) {
-  const normalizedActual = normalizeFingerprint(actual);
-  const normalizedExpected = normalizeFingerprint(expected);
-  if (normalizedActual === normalizedExpected) {
-    return true;
-  }
-  return isHexFingerprint(normalizedActual) && isHexFingerprint(normalizedExpected) && normalizedActual.toLowerCase() === normalizedExpected.toLowerCase();
+    const normalizedActual = normalizeFingerprint(actual);
+    const normalizedExpected = normalizeFingerprint(expected);
+    if (normalizedActual === normalizedExpected) {
+        return true;
+    }
+    return (isHexFingerprint(normalizedActual) &&
+        isHexFingerprint(normalizedExpected) &&
+        normalizedActual.toLowerCase() === normalizedExpected.toLowerCase());
 }
 function hostVerificationHint(host) {
-  return [
-    "",
-    "Typical fix:",
-    `  ssh ${host}`,
-    "",
-    "If you trust the host key, accept it and retry the scp-next command.",
-    "Alternatively configure hostFingerprint or knownHostsFile explicitly."
-  ].join("\n");
+    return [
+        "",
+        "Typical fix:",
+        `  ssh ${host}`,
+        "",
+        "If you trust the host key, accept it and retry the scp-next command.",
+        "Alternatively configure hostFingerprint or knownHostsFile explicitly."
+    ].join("\n");
 }
 async function resolveAllowedFingerprints(options) {
-  const fingerprints = /* @__PURE__ */ new Set();
-  const knownHostsFile = options.knownHostsFile ?? "~/.ssh/known_hosts";
-  if (!options.host) {
-    throw new HostVerificationError("A host is required for SSH host verification.");
-  }
-  if (options.hostFingerprint) {
-    for (const fingerprint of fingerprintCandidates(options.hostFingerprint)) {
-      fingerprints.add(fingerprint);
-    }
-  }
-  try {
-    await (0, import_promises2.access)(expandHome(knownHostsFile));
-    const content = await (0, import_promises2.readFile)(expandHome(knownHostsFile), "utf8");
-    for (const line of content.split(/\r?\n/)) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("@")) {
-        continue;
-      }
-      const [hosts, algorithm, key] = trimmed.split(/\s+/);
-      const hostPatterns = hosts?.split(",") ?? [];
-      const portHost = options.port ? `[${options.host}]:${options.port}` : void 0;
-      const matchesHost = hostPatterns.includes(options.host) || Boolean(portHost && hostPatterns.includes(portHost));
-      if (!hosts || !algorithm || !key || !matchesHost) {
-        continue;
-      }
-      const keyBuffer = Buffer.from(key, "base64");
-      fingerprints.add((0, import_node_crypto.createHash)("sha256").update(keyBuffer).digest("base64").replace(/=+$/g, ""));
-      fingerprints.add((0, import_node_crypto.createHash)("sha256").update(keyBuffer).digest("hex"));
-    }
-  } catch (error) {
-    if (options.knownHostsFile || !options.hostFingerprint) {
-      throw new HostVerificationError(
-        "SSH host verification requires hostFingerprint or an accessible knownHostsFile.",
-        { cause: error, context: { knownHostsFile } }
-      );
-    }
-  }
-  if (fingerprints.size === 0) {
-    throw new HostVerificationError(
-      `SSH host verification failed before connecting: no matching host fingerprint was configured.${hostVerificationHint(
-        options.host
-      )}`
-    );
-  }
-  return fingerprints;
+    const fingerprints = new Set();
+    const knownHostsFile = options.knownHostsFile ?? "~/.ssh/known_hosts";
+    if (!options.host) {
+        throw new HostVerificationError("A host is required for SSH host verification.");
+    }
+    if (options.hostFingerprint) {
+        for (const fingerprint of fingerprintCandidates(options.hostFingerprint)) {
+            fingerprints.add(fingerprint);
+        }
+    }
+    try {
+        await promises.access(expandHome(knownHostsFile));
+        const content = await promises.readFile(expandHome(knownHostsFile), "utf8");
+        for (const line of content.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("@")) {
+                continue;
+            }
+            const [hosts, algorithm, key] = trimmed.split(/\s+/);
+            const hostPatterns = hosts?.split(",") ?? [];
+            const portHost = options.port ? `[${options.host}]:${options.port}` : undefined;
+            const matchesHost = hostPatterns.includes(options.host) || Boolean(portHost && hostPatterns.includes(portHost));
+            if (!hosts || !algorithm || !key || !matchesHost) {
+                continue;
+            }
+            const keyBuffer = Buffer.from(key, "base64");
+            fingerprints.add(node_crypto.createHash("sha256").update(keyBuffer).digest("base64").replace(/=+$/g, ""));
+            fingerprints.add(node_crypto.createHash("sha256").update(keyBuffer).digest("hex"));
+        }
+    }
+    catch (error) {
+        if (options.knownHostsFile || !options.hostFingerprint) {
+            throw new HostVerificationError("SSH host verification requires hostFingerprint or an accessible knownHostsFile.", { cause: error, context: { knownHostsFile } });
+        }
+    }
+    if (fingerprints.size === 0) {
+        throw new HostVerificationError(`SSH host verification failed before connecting: no matching host fingerprint was configured.${hostVerificationHint(options.host)}`);
+    }
+    return fingerprints;
 }
 function createHostVerifier(allowedFingerprints) {
-  return (hashedKey) => {
-    for (const expected of allowedFingerprints) {
-      if (isFingerprintMatch(hashedKey, expected)) {
-        return true;
-      }
+    return (hashedKey) => {
+        for (const expected of allowedFingerprints) {
+            if (isFingerprintMatch(hashedKey, expected)) {
+                return true;
+            }
+        }
+        return false;
+    };
+}
+
+async function createSshConnectOptions(options) {
+    const connectOptions = {};
+    if (options.host !== undefined)
+        connectOptions.host = options.host;
+    if (options.port !== undefined)
+        connectOptions.port = options.port;
+    if (options.username !== undefined)
+        connectOptions.username = options.username;
+    if (options.password !== undefined)
+        connectOptions.password = options.password;
+    if (options.privateKey !== undefined) {
+        connectOptions.privateKey = options.privateKey;
     }
-    return false;
-  };
+    else if (options.privateKeyFile) {
+        connectOptions.privateKey = await promises.readFile(expandHome(options.privateKeyFile), "utf8");
+    }
+    if (options.passphrase !== undefined)
+        connectOptions.passphrase = options.passphrase;
+    const agent = options.agent ?? process.env.SSH_AUTH_SOCK;
+    if (agent !== undefined)
+        connectOptions.agent = agent;
+    if (options.timeout !== undefined)
+        connectOptions.readyTimeout = options.timeout;
+    const allowedFingerprints = await resolveAllowedFingerprints(options);
+    const hostVerifier = createHostVerifier(allowedFingerprints);
+    if (hostVerifier) {
+        connectOptions.hostHash = "sha256";
+        connectOptions.hostVerifier = hostVerifier;
+    }
+    return connectOptions;
 }
 
-// src/client/transport.ts
 function toRemoteFileInfo(info) {
-  return {
-    type: info.type,
-    name: info.name,
-    size: info.size
-  };
+    return {
+        type: info.type,
+        name: info.name,
+        size: info.size
+    };
 }
-var Ssh2SftpTransport = class {
-  client;
-  constructor(name = "scp-next") {
-    this.client = new import_ssh2_sftp_client.default(name, {
-      error: () => void 0,
-      end: () => void 0,
-      close: () => void 0
-    });
-  }
-  async connect(options) {
-    const allowedFingerprints = await resolveAllowedFingerprints(options);
-    const hostVerifier = createHostVerifier(allowedFingerprints);
-    const connectOptions = {};
-    if (options.host !== void 0) connectOptions.host = options.host;
-    if (options.port !== void 0) connectOptions.port = options.port;
-    if (options.username !== void 0) connectOptions.username = options.username;
-    if (options.password !== void 0) connectOptions.password = options.password;
-    if (options.privateKey !== void 0) {
-      connectOptions.privateKey = options.privateKey;
-    } else if (options.privateKeyFile) {
-      connectOptions.privateKey = await (0, import_promises3.readFile)(expandHome(options.privateKeyFile), "utf8");
-    }
-    if (options.passphrase !== void 0) connectOptions.passphrase = options.passphrase;
-    const agent = options.agent ?? process.env.SSH_AUTH_SOCK;
-    if (agent !== void 0) {
-      connectOptions.agent = agent;
+class Ssh2SftpTransport {
+    client;
+    constructor(name = "scp-next") {
+        this.client = new SftpClient(name, {
+            error: () => undefined,
+            end: () => undefined,
+            close: () => undefined
+        });
     }
-    if (options.timeout !== void 0) connectOptions.readyTimeout = options.timeout;
-    if (hostVerifier) {
-      connectOptions.hostHash = "sha256";
-      connectOptions.hostVerifier = hostVerifier;
+    async connect(options) {
+        const connectOptions = await createSshConnectOptions(options);
+        try {
+            await this.client.connect(connectOptions);
+        }
+        catch (error) {
+            const converted = toScpNextError(error);
+            if (converted instanceof HostVerificationError) {
+                throw new HostVerificationError(`SSH host verification failed during connection: ${formatErrorMessage(error)}.${hostVerificationTroubleshooting(options.host)}`, { cause: error, context: connectionContext(options) });
+            }
+            if (isLikelyHostVerificationFailure(error)) {
+                throw new HostVerificationError(`SSH host verification failed during connection.${hostVerificationTroubleshooting(options.host)}`, { cause: error, context: connectionContext(options) });
+            }
+            throw new ConnectionError(`Unable to connect to SSH server: ${formatErrorMessage(error)}`, {
+                cause: error,
+                context: connectionContext(options)
+            });
+        }
     }
-    try {
-      await this.client.connect(connectOptions);
-    } catch (error) {
-      const converted = toScpNextError(error);
-      if (converted instanceof HostVerificationError) {
-        throw new HostVerificationError(
-          `SSH host verification failed during connection: ${formatErrorMessage(
-            error
-          )}.${hostVerificationTroubleshooting(options.host)}`,
-          { cause: error, context: connectionContext(options) }
-        );
-      }
-      if (isLikelyHostVerificationFailure(error)) {
-        throw new HostVerificationError(
-          `SSH host verification failed during connection.${hostVerificationTroubleshooting(
-            options.host
-          )}`,
-          { cause: error, context: connectionContext(options) }
-        );
-      }
-      throw new ConnectionError(`Unable to connect to SSH server: ${formatErrorMessage(error)}`, {
-        cause: error,
-        context: connectionContext(options)
-      });
-    }
-  }
-  async close() {
-    await this.client.end();
-  }
-  async exists(remotePath) {
-    return this.client.exists(remotePath);
-  }
-  async mkdir(remotePath, recursive = true) {
-    await this.client.mkdir(remotePath, recursive);
-  }
-  async list(remotePath) {
-    const files = await this.client.list(remotePath);
-    return files.map(toRemoteFileInfo);
-  }
-  async uploadFile(localPath, remotePath, onStep) {
-    try {
-      await this.client.fastPut(localPath, remotePath, this.transferOptions(onStep));
-    } catch (error) {
-      throw new TransferError(`Upload failed for ${localPath}: ${formatErrorMessage(error)}`, {
-        cause: error,
-        context: { localPath, remotePath }
-      });
-    }
-  }
-  async downloadFile(remotePath, localPath, onStep) {
-    try {
-      await this.client.fastGet(remotePath, localPath, this.transferOptions(onStep));
-    } catch (error) {
-      throw new TransferError(`Download failed for ${remotePath}: ${formatErrorMessage(error)}`, {
-        cause: error,
-        context: { remotePath, localPath }
-      });
-    }
-  }
-  transferOptions(onStep) {
-    if (!onStep) {
-      return void 0;
+    async close() {
+        await this.client.end();
+    }
+    async exists(remotePath) {
+        return this.client.exists(remotePath);
     }
+    async mkdir(remotePath, recursive = true) {
+        await this.client.mkdir(remotePath, recursive);
+    }
+    async list(remotePath) {
+        const files = await this.client.list(remotePath);
+        return files.map(toRemoteFileInfo);
+    }
+    async uploadFile(localPath, remotePath, onStep) {
+        try {
+            await this.client.fastPut(localPath, remotePath, this.transferOptions(onStep));
+        }
+        catch (error) {
+            throw new TransferError(`Upload failed for ${localPath}: ${formatErrorMessage(error)}`, {
+                cause: error,
+                context: { localPath, remotePath }
+            });
+        }
+    }
+    async downloadFile(remotePath, localPath, onStep) {
+        try {
+            await this.client.fastGet(remotePath, localPath, this.transferOptions(onStep));
+        }
+        catch (error) {
+            throw new TransferError(`Download failed for ${remotePath}: ${formatErrorMessage(error)}`, {
+                cause: error,
+                context: { remotePath, localPath }
+            });
+        }
+    }
+    transferOptions(onStep) {
+        if (!onStep) {
+            return undefined;
+        }
+        return {
+            step(transferredBytes, chunkBytes, totalBytes) {
+                onStep({ transferredBytes, chunkBytes, totalBytes });
+            }
+        };
+    }
+}
+function connectionContext(options) {
     return {
-      step(transferredBytes, chunkBytes, totalBytes) {
-        onStep({ transferredBytes, chunkBytes, totalBytes });
-      }
+        host: options.host,
+        port: options.port,
+        username: options.username
     };
-  }
-};
-function connectionContext(options) {
-  return {
-    host: options.host,
-    port: options.port,
-    username: options.username
-  };
 }
 function isLikelyHostVerificationFailure(error) {
-  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
-  return message.includes("host") && (message.includes("verif") || message.includes("fingerprint") || message.includes("host key") || message.includes("key mismatch") || message.includes("denied"));
+    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    return (message.includes("host") &&
+        (message.includes("verif") ||
+            message.includes("fingerprint") ||
+            message.includes("host key") ||
+            message.includes("key mismatch") ||
+            message.includes("denied")));
 }
 function hostVerificationTroubleshooting(host) {
-  const displayHost = host ?? "<host>";
-  return [
-    "",
-    "",
-    "Typical fix:",
-    `  ssh ${displayHost}`,
-    "",
-    "If plain ssh works but scp-next fails, check that the host entry is available in",
-    "`~/.ssh/known_hosts` for the same host and port used by scp-next. For non-default ports,",
-    "OpenSSH usually stores entries as `[host]:port`.",
-    "You can also configure hostFingerprint or knownHostsFile explicitly."
-  ].join("\n");
+    const displayHost = host ?? "<host>";
+    return [
+        "",
+        "",
+        "Typical fix:",
+        `  ssh ${displayHost}`,
+        "",
+        "If plain ssh works but scp-next fails, check that the host entry is available in",
+        "`~/.ssh/known_hosts` for the same host and port used by scp-next. For non-default ports,",
+        "OpenSSH usually stores entries as `[host]:port`.",
+        "You can also configure hostFingerprint or knownHostsFile explicitly."
+    ].join("\n");
 }
 
-// src/client/walk.ts
-var import_promises4 = require("fs/promises");
-var import_node_path3 = __toESM(require("path"), 1);
+class SshCommandExecutor {
+    client;
+    connected = false;
+    closed = true;
+    constructor(client = new ssh2.Client()) {
+        this.client = client;
+        this.client.on("error", () => {
+            this.connected = false;
+        });
+        this.client.on("close", () => {
+            this.connected = false;
+            this.closed = true;
+        });
+    }
+    async connect(options) {
+        const connectOptions = await createSshConnectOptions(options);
+        this.closed = false;
+        await new Promise((resolve, reject) => {
+            const onReady = () => {
+                cleanup();
+                this.connected = true;
+                resolve();
+            };
+            const onError = (error) => {
+                cleanup();
+                this.connected = false;
+                this.closed = true;
+                try {
+                    this.client.end();
+                }
+                catch {
+                    // The failed connection may not have a writable socket.
+                }
+                const converted = toScpNextError(error);
+                if (converted instanceof HostVerificationError) {
+                    reject(converted);
+                    return;
+                }
+                reject(new ConnectionError(`Unable to connect command executor to SSH server: ${formatErrorMessage(error)}`, {
+                    cause: error,
+                    context: {
+                        host: options.host,
+                        port: options.port,
+                        username: options.username
+                    }
+                }));
+            };
+            const onClose = () => {
+                cleanup();
+                reject(new ConnectionError("SSH connection closed before it was ready."));
+            };
+            const cleanup = () => {
+                this.client.off("ready", onReady);
+                this.client.off("error", onError);
+                this.client.off("close", onClose);
+            };
+            this.client.once("ready", onReady);
+            this.client.once("error", onError);
+            this.client.once("close", onClose);
+            try {
+                this.client.connect(connectOptions);
+            }
+            catch (error) {
+                cleanup();
+                this.closed = true;
+                reject(new ConnectionError(`Unable to start SSH connection: ${formatErrorMessage(error)}`));
+            }
+        });
+    }
+    async exec(command, options = {}) {
+        if (!this.connected) {
+            throw new ConnectionError("Command executor is not connected.");
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                this.client.exec(command, (error, stream) => {
+                    if (error) {
+                        reject(new RemoteCommandError("Unable to start remote command.", {
+                            exitCode: null
+                        }));
+                        return;
+                    }
+                    collectCommandResult(command, stream, options, resolve, reject);
+                });
+            }
+            catch (error) {
+                reject(new ConnectionError(`Unable to start remote command: ${formatErrorMessage(error)}`));
+            }
+        });
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.connected = false;
+        await new Promise((resolve) => {
+            this.client.once("close", resolve);
+            this.client.end();
+        });
+    }
+}
+function collectCommandResult(command, stream, options, resolve, reject) {
+    let stdout = "";
+    let stderr = "";
+    let outputBytes = 0;
+    let settled = false;
+    const maxBuffer = options.maxBuffer ?? 10 * 1024 * 1024;
+    const cleanup = () => {
+        if (timer)
+            clearTimeout(timer);
+        stream.off("data", onStdoutData);
+        stream.stderr.off("data", onStderrData);
+        stream.off("close", onClose);
+        stream.off("error", onStreamError);
+        stream.stderr.off("error", onStreamError);
+    };
+    const fail = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        try {
+            stream.close();
+        }
+        catch {
+            // The connection may already be closed.
+        }
+        reject(error);
+    };
+    const appendOutput = (target, chunk) => {
+        outputBytes += Buffer.byteLength(chunk);
+        if (outputBytes > maxBuffer) {
+            fail(new RemoteCommandError(`Remote command output exceeded maxBuffer of ${maxBuffer} bytes.`, {
+                exitCode: null,
+                stdout,
+                stderr
+            }));
+            return;
+        }
+        if (target === "stdout")
+            stdout += chunk;
+        else
+            stderr += chunk;
+    };
+    const onStreamError = () => {
+        fail(new RemoteCommandError("Remote command stream failed.", {
+            exitCode: null,
+            stdout,
+            stderr
+        }));
+    };
+    const onStdoutData = (chunk) => {
+        appendOutput("stdout", chunk);
+    };
+    const onStderrData = (chunk) => {
+        appendOutput("stderr", chunk);
+    };
+    const onClose = (exitCode, signal) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        resolve({
+            command,
+            stdout,
+            stderr,
+            exitCode: typeof exitCode === "number" ? exitCode : null,
+            ...(signal ? { signal } : {})
+        });
+    };
+    const timer = options.timeout === undefined
+        ? undefined
+        : setTimeout(() => {
+            fail(new RemoteCommandError(`Remote command timed out after ${options.timeout} ms.`, {
+                exitCode: null,
+                stdout,
+                stderr
+            }));
+        }, options.timeout);
+    stream.setEncoding("utf8");
+    stream.stderr.setEncoding("utf8");
+    stream.on("data", onStdoutData);
+    stream.stderr.on("data", onStderrData);
+    stream.once("error", onStreamError);
+    stream.stderr.once("error", onStreamError);
+    stream.once("close", onClose);
+}
 
-// src/paths/remote-path.ts
-var import_node_path2 = __toESM(require("path"), 1);
 function assertRemotePath(inputPath, label = "remote path") {
-  if (!inputPath || inputPath.trim().length === 0) {
-    throw new ValidationError(`Invalid ${label}: remote paths must not be empty.`, {
-      context: { path: inputPath }
-    });
-  }
+    if (!inputPath || inputPath.trim().length === 0) {
+        throw new ValidationError(`Invalid ${label}: remote paths must not be empty.`, {
+            context: { path: inputPath }
+        });
+    }
 }
 function normalizeRemotePath(inputPath) {
-  assertRemotePath(inputPath);
-  return import_node_path2.default.posix.normalize(inputPath.replace(/\\/g, "/"));
+    assertRemotePath(inputPath);
+    return path.posix.normalize(inputPath.replace(/\\/g, "/"));
 }
 function remoteJoin(...parts) {
-  const joined = import_node_path2.default.posix.join(...parts);
-  assertRemotePath(joined);
-  return joined;
+    const joined = path.posix.join(...parts);
+    assertRemotePath(joined);
+    return joined;
 }
 function remoteDirname(inputPath) {
-  assertRemotePath(inputPath);
-  return import_node_path2.default.posix.dirname(inputPath);
+    assertRemotePath(inputPath);
+    return path.posix.dirname(inputPath);
 }
 
-// src/client/walk.ts
 async function walkLocalFiles(rootPath) {
-  const resolvedRoot = resolveLocalPath(rootPath);
-  const stats = await (0, import_promises4.stat)(resolvedRoot);
-  if (stats.isFile()) {
-    return [
-      {
-        absolutePath: resolvedRoot,
-        relativePath: import_node_path3.default.basename(resolvedRoot),
-        size: stats.size
-      }
-    ];
-  }
-  const files = [];
-  async function visit(directory) {
-    const entries = await (0, import_promises4.readdir)(directory, { withFileTypes: true });
-    for (const entry of entries) {
-      const absolutePath = import_node_path3.default.join(directory, entry.name);
-      if (entry.isDirectory()) {
-        await visit(absolutePath);
-      } else if (entry.isFile()) {
-        const entryStats = await (0, import_promises4.stat)(absolutePath);
-        files.push({
-          absolutePath,
-          relativePath: import_node_path3.default.relative(resolvedRoot, absolutePath),
-          size: entryStats.size
-        });
-      }
+    const resolvedRoot = resolveLocalPath(rootPath);
+    const stats = await promises.stat(resolvedRoot);
+    if (stats.isFile()) {
+        return [
+            {
+                absolutePath: resolvedRoot,
+                relativePath: path.basename(resolvedRoot),
+                size: stats.size
+            }
+        ];
+    }
+    const files = [];
+    async function visit(directory) {
+        const entries = await promises.readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            const absolutePath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await visit(absolutePath);
+            }
+            else if (entry.isFile()) {
+                const entryStats = await promises.stat(absolutePath);
+                files.push({
+                    absolutePath,
+                    relativePath: path.relative(resolvedRoot, absolutePath),
+                    size: entryStats.size
+                });
+            }
+        }
     }
-  }
-  await visit(resolvedRoot);
-  return files;
+    await visit(resolvedRoot);
+    return files;
 }
 async function walkRemoteFiles(transport, rootPath) {
-  const rootEntries = await transport.list(rootPath);
-  const files = [];
-  async function visit(directory, relativeBase, entries) {
-    for (const entry of entries) {
-      const fullPath = remoteJoin(directory, entry.name);
-      const relativePath = relativeBase ? remoteJoin(relativeBase, entry.name) : entry.name;
-      if (entry.type === "d") {
-        await visit(fullPath, relativePath, await transport.list(fullPath));
-      } else if (entry.type === "-") {
-        files.push({
-          remotePath: fullPath,
-          relativePath,
-          size: entry.size
-        });
-      }
+    const rootEntries = await transport.list(rootPath);
+    const files = [];
+    async function visit(directory, relativeBase, entries) {
+        for (const entry of entries) {
+            const fullPath = remoteJoin(directory, entry.name);
+            const relativePath = relativeBase ? remoteJoin(relativeBase, entry.name) : entry.name;
+            if (entry.type === "d") {
+                await visit(fullPath, relativePath, await transport.list(fullPath));
+            }
+            else if (entry.type === "-") {
+                files.push({
+                    remotePath: fullPath,
+                    relativePath,
+                    size: entry.size
+                });
+            }
+        }
+    }
+    await visit(rootPath, "", rootEntries);
+    return files;
+}
+
+function isPostUploadCommands(value) {
+    return (Array.isArray(value) &&
+        value.every((command) => typeof command === "string" && command.trim().length > 0));
+}
+function getPostUploadCommands(source) {
+    const commands = readPostUploadCommands(source);
+    if (commands === undefined) {
+        return undefined;
+    }
+    if (!isPostUploadCommands(commands)) {
+        throw new ValidationError("postUploadCommands must be an array of non-empty command strings.");
+    }
+    return commands;
+}
+function readPostUploadCommands(source) {
+    if (typeof source !== "object" || source === null) {
+        return undefined;
     }
-  }
-  await visit(rootPath, "", rootEntries);
-  return files;
+    return source
+        .postUploadCommands;
 }
 
-// src/config/validation.ts
-var import_promises5 = require("fs/promises");
 function validatePort(port) {
-  if (port === void 0) {
-    return;
-  }
-  if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new ValidationError("Port must be an integer between 1 and 65535.", {
-      context: { port }
-    });
-  }
+    if (port === undefined) {
+        return;
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new ValidationError("Port must be an integer between 1 and 65535.", {
+            context: { port }
+        });
+    }
 }
 function validateTimeout(timeout) {
-  if (timeout === void 0) {
-    return;
-  }
-  if (!Number.isFinite(timeout) || timeout <= 0) {
-    throw new ValidationError("Timeout must be a positive number.", {
-      context: { timeout }
-    });
-  }
+    if (timeout === undefined) {
+        return;
+    }
+    if (!Number.isFinite(timeout) || timeout <= 0) {
+        throw new ValidationError("Timeout must be a positive number.", {
+            context: { timeout }
+        });
+    }
 }
 async function validateServerOptions(options) {
-  if (!options.host) {
-    throw new ValidationError("Host is required.");
-  }
-  if (!options.username) {
-    throw new ValidationError("Username is required.");
-  }
-  validatePort(options.port);
-  validateTimeout(options.timeout);
-  if (options.privateKeyFile) {
-    try {
-      await (0, import_promises5.access)(resolveLocalPath(options.privateKeyFile));
-    } catch (error) {
-      throw new ValidationError(`Private key file does not exist: ${options.privateKeyFile}`, {
-        cause: error,
-        context: { privateKeyFile: options.privateKeyFile }
-      });
-    }
-  }
-  const hasAuthentication = Boolean(options.password) || Boolean(options.privateKey) || Boolean(options.privateKeyFile) || Boolean(options.agent) || Boolean(process.env.SSH_AUTH_SOCK);
-  if (!hasAuthentication) {
-    throw new ValidationError(
-      "Authentication is required. Provide a password, private key, private key file, or SSH agent."
-    );
-  }
+    if (!options.host) {
+        throw new ValidationError("Host is required.");
+    }
+    if (!options.username) {
+        throw new ValidationError("Username is required.");
+    }
+    validatePort(options.port);
+    validateTimeout(options.timeout);
+    if (options.privateKeyFile) {
+        try {
+            await promises.access(resolveLocalPath(options.privateKeyFile));
+        }
+        catch (error) {
+            throw new ValidationError(`Private key file does not exist: ${options.privateKeyFile}`, {
+                cause: error,
+                context: { privateKeyFile: options.privateKeyFile }
+            });
+        }
+    }
+    const hasAuthentication = Boolean(options.password) ||
+        Boolean(options.privateKey) ||
+        Boolean(options.privateKeyFile) ||
+        Boolean(options.agent) ||
+        Boolean(process.env.SSH_AUTH_SOCK);
+    if (!hasAuthentication) {
+        throw new ValidationError("Authentication is required. Provide a password, private key, private key file, or SSH agent.");
+    }
 }
 async function validateUploadOptions(options) {
-  if (!options.localPath) {
-    throw new ValidationError("Missing localPath.");
-  }
-  if (!options.remotePath) {
-    throw new ValidationError("Missing remotePath.");
-  }
-  assertRemotePath(options.remotePath, "remotePath");
-  validateTimeout(options.timeout);
-  await assertLocalPathExists(options.localPath);
-  if (!options.dryRun) {
-    await validateServerOptions(options);
-  }
+    if (!options.localPath) {
+        throw new ValidationError("Missing localPath.");
+    }
+    if (!options.remotePath) {
+        throw new ValidationError("Missing remotePath.");
+    }
+    assertRemotePath(options.remotePath, "remotePath");
+    validateTimeout(options.timeout);
+    getPostUploadCommands(options);
+    await assertLocalPathExists(options.localPath);
+    if (!options.dryRun) {
+        await validateServerOptions(options);
+    }
 }
 async function validateDownloadOptions(options) {
-  if (!options.remotePath) {
-    throw new ValidationError("Missing remotePath.");
-  }
-  if (!options.localPath) {
-    throw new ValidationError("Missing localPath.");
-  }
-  assertRemotePath(options.remotePath, "remotePath");
-  validateTimeout(options.timeout);
-  await assertDownloadDestination(options.localPath, options.createDirectories ?? true);
-  if (!options.dryRun) {
-    await validateServerOptions(options);
-  }
+    if (!options.remotePath) {
+        throw new ValidationError("Missing remotePath.");
+    }
+    if (!options.localPath) {
+        throw new ValidationError("Missing localPath.");
+    }
+    assertRemotePath(options.remotePath, "remotePath");
+    validateTimeout(options.timeout);
+    if (getPostUploadCommands(options)?.length) {
+        throw new ValidationError("Post-upload commands are not supported for downloads.");
+    }
+    await assertDownloadDestination(options.localPath, options.createDirectories ?? true);
+    if (!options.dryRun) {
+        await validateServerOptions(options);
+    }
 }
 
-// src/client/client.ts
 function percentage(transferredBytes, totalBytes) {
-  if (!totalBytes || totalBytes <= 0) {
-    return void 0;
-  }
-  return Math.min(100, Math.round(transferredBytes / totalBytes * 100));
+    if (!totalBytes || totalBytes <= 0) {
+        return undefined;
+    }
+    return Math.min(100, Math.round((transferredBytes / totalBytes) * 100));
 }
 function mergeOptions(serverOptions, transferOptions) {
-  return { ...serverOptions, ...transferOptions ?? {} };
+    return { ...serverOptions, ...(transferOptions ?? {}) };
 }
 function shouldCreateDirectories(options) {
-  return options.createDirectories ?? true;
+    return options.createDirectories ?? true;
 }
 function hasTrailingPathSeparator(inputPath) {
-  return /[\\/]$/.test(inputPath);
+    return /[\\/]$/.test(inputPath);
 }
 function trimmedRemoteDirectory(remotePath) {
-  return remotePath.replace(/\/+$/g, "") || "/";
+    return remotePath.replace(/\/+$/g, "") || "/";
 }
 function remoteBasename(remotePath) {
-  return import_node_path4.default.posix.basename(trimmedRemoteDirectory(remotePath));
+    return path.posix.basename(trimmedRemoteDirectory(remotePath));
 }
 async function isExistingLocalDirectory(localPath) {
-  try {
-    return (await (0, import_promises6.stat)(localPath)).isDirectory();
-  } catch {
-    return false;
-  }
+    try {
+        return (await promises.stat(localPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
 }
 async function ensureLocalDirectory(localPath, createParents = false) {
-  try {
-    const stats = await (0, import_promises6.stat)(localPath);
-    if (stats.isDirectory()) {
-      return;
+    try {
+        const stats = await promises.stat(localPath);
+        if (stats.isDirectory()) {
+            return;
+        }
+        throw new TransferError(`Local destination already exists and is not a directory: ${localPath}`, {
+            context: { localPath }
+        });
     }
-    throw new TransferError(`Local destination already exists and is not a directory: ${localPath}`, {
-      context: { localPath }
-    });
-  } catch (error) {
-    if (error instanceof TransferError) {
-      throw error;
+    catch (error) {
+        if (error instanceof TransferError) {
+            throw error;
+        }
+        await promises.mkdir(localPath, { recursive: createParents });
     }
-    await (0, import_promises6.mkdir)(localPath, { recursive: createParents });
-  }
 }
-var ScpNextClientImpl = class {
-  serverOptions;
-  transport;
-  connected = false;
-  constructor(serverOptions, dependencies = {}) {
-    this.serverOptions = serverOptions;
-    this.transport = dependencies.transport ?? new Ssh2SftpTransport();
-  }
-  async connect() {
-    await validateServerOptions(this.serverOptions);
-    await this.transport.connect(this.serverOptions);
-    this.connected = true;
-  }
-  async upload(localPath, remotePath, options = {}) {
-    const uploadOptions = {
-      ...mergeOptions(this.serverOptions, options),
-      localPath,
-      remotePath
-    };
-    await validateUploadOptions(uploadOptions);
-    if (options.dryRun) {
-      return;
-    }
-    await this.ensureConnected();
-    await this.uploadWithTransport(uploadOptions);
-  }
-  async download(remotePath, localPath, options = {}) {
-    const downloadOptions = {
-      ...mergeOptions(this.serverOptions, options),
-      remotePath,
-      localPath
-    };
-    await validateDownloadOptions(downloadOptions);
-    if (options.dryRun) {
-      return;
-    }
-    await this.ensureConnected();
-    await this.downloadWithTransport(downloadOptions);
-  }
-  async close() {
-    if (this.connected) {
-      await this.transport.close();
-      this.connected = false;
-    }
-  }
-  async ensureConnected() {
-    if (!this.connected) {
-      await this.connect();
-    }
-  }
-  async uploadWithTransport(options) {
-    const localKind = await getLocalPathKind(options.localPath);
-    const remotePath = normalizeRemotePath(options.remotePath);
-    if (localKind === "directory" && !options.recursive) {
-      throw new ValidationError("Uploading a directory requires recursive mode.");
-    }
-    if (localKind === "file") {
-      const destinationFile = await this.resolveRemoteDestinationForLocalFile(options, remotePath);
-      const totalBytes2 = void 0;
-      await this.transport.uploadFile(resolveLocalPath(options.localPath), destinationFile, (step) => {
-        options.onProgress?.({
-          operation: "upload",
-          source: options.localPath,
-          destination: options.remotePath,
-          transferredBytes: step.transferredBytes,
-          totalBytes: step.totalBytes || totalBytes2,
-          percentage: percentage(step.transferredBytes, step.totalBytes),
-          currentFile: options.localPath
-        });
-      });
-      return;
-    }
-    const files = await walkLocalFiles(options.localPath);
-    const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
-    let completedBytes = 0;
-    let completedFiles = 0;
-    const destinationRoot = await this.resolveRemoteDestinationForLocalDirectory(
-      options,
-      remotePath
-    );
-    for (const file of files) {
-      const destinationFile = remoteJoin(
-        destinationRoot,
-        file.relativePath.split(import_node_path4.default.sep).join("/")
-      );
-      await this.ensureRemoteParent(destinationFile, true);
-      await this.assertRemoteOverwrite(destinationFile, options.overwrite);
-      await this.transport.uploadFile(file.absolutePath, destinationFile, (step) => {
-        const transferredBytes = completedBytes + step.transferredBytes;
-        options.onProgress?.({
-          operation: "upload",
-          source: options.localPath,
-          destination: options.remotePath,
-          transferredBytes,
-          totalBytes,
-          percentage: percentage(transferredBytes, totalBytes),
-          currentFile: file.relativePath,
-          completedFiles,
-          totalFiles: files.length
-        });
-      });
-      completedBytes += file.size;
-      completedFiles += 1;
-    }
-  }
-  async resolveRemoteDestinationForLocalFile(options, remotePath) {
-    const remoteKind = await this.transport.exists(remotePath);
-    const isDirectoryLikeDestination = remoteKind === "d" || remotePath.endsWith("/");
-    if (!isDirectoryLikeDestination) {
-      await this.ensureRemoteParent(remotePath, shouldCreateDirectories(options));
-      await this.assertRemoteOverwrite(remotePath, options.overwrite);
-      return remotePath;
-    }
-    if (remoteKind && remoteKind !== "d") {
-      throw new TransferError(`Remote destination already exists and is not a directory: ${remotePath}`, {
-        context: { remotePath }
-      });
-    }
-    const remoteDirectory = remotePath.replace(/\/+$/g, "") || "/";
-    if (!remoteKind) {
-      if (!shouldCreateDirectories(options)) {
-        throw new TransferError(`Remote destination directory does not exist: ${remoteDirectory}`, {
-          context: { remotePath }
-        });
-      }
-      await this.transport.mkdir(remoteDirectory, true);
-    }
-    const destinationFile = remoteJoin(
-      remoteDirectory,
-      import_node_path4.default.basename(resolveLocalPath(options.localPath))
-    );
-    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 = import_node_path4.default.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 (!shouldCreateDirectories(options)) {
-          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 (!shouldCreateDirectories(options)) {
-        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);
-    if (!remoteKind) {
-      throw new TransferError(`Remote path does not exist: ${options.remotePath}`, {
-        context: { remotePath: options.remotePath }
-      });
-    }
-    if (remoteKind === "d") {
-      if (!options.recursive) {
-        throw new ValidationError("Downloading a directory requires recursive mode.");
-      }
-      await this.downloadDirectory(options);
-      return;
-    }
-    await this.downloadSingleFile(options, remotePath);
-  }
-  async downloadSingleFile(options, remotePath) {
-    const localPath = await this.resolveLocalDestinationForRemoteFile(options, remotePath);
-    await this.assertLocalOverwrite(localPath, options.overwrite);
-    if (shouldCreateDirectories(options)) {
-      await (0, import_promises6.mkdir)(import_node_path4.default.dirname(localPath), { recursive: true });
-    }
-    await this.transport.downloadFile(remotePath, localPath, (step) => {
-      options.onProgress?.({
-        operation: "download",
-        source: options.remotePath,
-        destination: options.localPath,
-        transferredBytes: step.transferredBytes,
-        totalBytes: step.totalBytes,
-        percentage: percentage(step.transferredBytes, step.totalBytes),
-        currentFile: options.remotePath
-      });
-    });
-  }
-  async downloadDirectory(options) {
-    const remotePath = normalizeRemotePath(options.remotePath);
-    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 ensureLocalDirectory(localRoot, shouldCreateDirectories(options));
-    for (const file of files) {
-      const localFile = import_node_path4.default.join(localRoot, ...file.relativePath.split("/"));
-      await this.assertLocalOverwrite(localFile, options.overwrite);
-      await (0, import_promises6.mkdir)(import_node_path4.default.dirname(localFile), { recursive: true });
-      await this.transport.downloadFile(file.remotePath, localFile, (step) => {
-        const transferredBytes = completedBytes + step.transferredBytes;
-        options.onProgress?.({
-          operation: "download",
-          source: options.remotePath,
-          destination: options.localPath,
-          transferredBytes,
-          totalBytes,
-          percentage: percentage(transferredBytes, totalBytes),
-          currentFile: file.relativePath,
-          completedFiles,
-          totalFiles: files.length
-        });
-      });
-      completedBytes += file.size;
-      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 (!shouldCreateDirectories(options)) {
-        throw new TransferError(`Local destination directory does not exist: ${localDestination}`, {
-          context: { localPath: options.localPath }
-        });
-      }
-      await (0, import_promises6.mkdir)(localDestination, { recursive: true });
-    }
-    return import_node_path4.default.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 (!shouldCreateDirectories(options)) {
-        throw new TransferError(`Local destination directory does not exist: ${localDestination}`, {
-          context: { localPath: options.localPath }
+class ScpNextClientImpl {
+    serverOptions;
+    transport;
+    commandExecutor;
+    connected = false;
+    commandExecutorConnected = false;
+    constructor(serverOptions, dependencies = {}) {
+        this.serverOptions = serverOptions;
+        this.transport = dependencies.transport ?? new Ssh2SftpTransport();
+        this.commandExecutor = dependencies.commandExecutor ?? new SshCommandExecutor();
+    }
+    async connect() {
+        await validateServerOptions(this.serverOptions);
+        await this.transport.connect(this.serverOptions);
+        this.connected = true;
+    }
+    async upload(localPath, remotePath, options = {}) {
+        const uploadOptions = {
+            ...mergeOptions(this.serverOptions, options),
+            localPath,
+            remotePath
+        };
+        await validateUploadOptions(uploadOptions);
+        if (options.dryRun) {
+            return [];
+        }
+        await this.ensureConnected();
+        await this.uploadWithTransport(uploadOptions);
+        const results = [];
+        for (const command of getPostUploadCommands(options) ?? []) {
+            results.push(await this.exec(command));
+        }
+        return results;
+    }
+    async download(remotePath, localPath, options = {}) {
+        const downloadOptions = {
+            ...mergeOptions(this.serverOptions, options),
+            remotePath,
+            localPath
+        };
+        await validateDownloadOptions(downloadOptions);
+        if (options.dryRun) {
+            return;
+        }
+        await this.ensureConnected();
+        await this.downloadWithTransport(downloadOptions);
+    }
+    async exec(command, options = {}) {
+        if (typeof command !== "string" || !command.trim()) {
+            throw new ValidationError("Remote command must not be empty.");
+        }
+        if (options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout <= 0)) {
+            throw new ValidationError("Command timeout must be a positive number.");
+        }
+        if (options.maxBuffer !== undefined &&
+            (!Number.isInteger(options.maxBuffer) || options.maxBuffer <= 0)) {
+            throw new ValidationError("Command maxBuffer must be a positive integer.");
+        }
+        if (options.failOnStderr !== undefined &&
+            typeof options.failOnStderr !== "boolean") {
+            throw new ValidationError("Command failOnStderr must be a boolean.");
+        }
+        await this.ensureCommandExecutorConnected();
+        let result;
+        try {
+            result = await this.commandExecutor.exec(command, options);
+        }
+        catch (error) {
+            if (error instanceof RemoteCommandError) {
+                throw new RemoteCommandError(error.message, {
+                    exitCode: error.exitCode,
+                    signal: error.signal,
+                    stdout: redactKnownSensitiveValues(error.stdout, this.serverOptions),
+                    stderr: redactKnownSensitiveValues(error.stderr, this.serverOptions)
+                });
+            }
+            throw error;
+        }
+        if (result.exitCode !== 0 || (options.failOnStderr && result.stderr.length > 0)) {
+            const reason = result.exitCode === null
+                ? "Remote command ended without an exit code."
+                : result.exitCode !== 0
+                    ? `Remote command failed with exit code ${String(result.exitCode)}.`
+                    : "Remote command wrote to stderr.";
+            throw new RemoteCommandError(reason, {
+                exitCode: result.exitCode,
+                signal: result.signal,
+                stdout: redactKnownSensitiveValues(result.stdout, this.serverOptions),
+                stderr: redactKnownSensitiveValues(result.stderr, this.serverOptions)
+            });
+        }
+        return result;
+    }
+    async close() {
+        const closures = [];
+        if (this.connected)
+            closures.push(this.transport.close());
+        if (this.commandExecutorConnected)
+            closures.push(this.commandExecutor.close());
+        const results = await Promise.allSettled(closures);
+        this.connected = false;
+        this.commandExecutorConnected = false;
+        const failure = results.find((result) => result.status === "rejected");
+        if (failure) {
+            throw failure.reason;
+        }
+    }
+    async ensureConnected() {
+        if (!this.connected) {
+            await this.connect();
+        }
+    }
+    async ensureCommandExecutorConnected() {
+        if (!this.commandExecutorConnected) {
+            await validateServerOptions(this.serverOptions);
+            await this.commandExecutor.connect(this.serverOptions);
+            this.commandExecutorConnected = true;
+        }
+    }
+    async uploadWithTransport(options) {
+        const localKind = await getLocalPathKind(options.localPath);
+        const remotePath = normalizeRemotePath(options.remotePath);
+        if (localKind === "directory" && !options.recursive) {
+            throw new ValidationError("Uploading a directory requires recursive mode.");
+        }
+        if (localKind === "file") {
+            const destinationFile = await this.resolveRemoteDestinationForLocalFile(options, remotePath);
+            const totalBytes = undefined;
+            await this.transport.uploadFile(resolveLocalPath(options.localPath), destinationFile, (step) => {
+                options.onProgress?.({
+                    operation: "upload",
+                    source: options.localPath,
+                    destination: options.remotePath,
+                    transferredBytes: step.transferredBytes,
+                    totalBytes: step.totalBytes || totalBytes,
+                    percentage: percentage(step.transferredBytes, step.totalBytes),
+                    currentFile: options.localPath
+                });
+            });
+            return;
+        }
+        const files = await walkLocalFiles(options.localPath);
+        const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
+        let completedBytes = 0;
+        let completedFiles = 0;
+        const destinationRoot = await this.resolveRemoteDestinationForLocalDirectory(options, remotePath);
+        for (const file of files) {
+            const destinationFile = remoteJoin(destinationRoot, file.relativePath.split(path.sep).join("/"));
+            await this.ensureRemoteParent(destinationFile, true);
+            await this.assertRemoteOverwrite(destinationFile, options.overwrite);
+            await this.transport.uploadFile(file.absolutePath, destinationFile, (step) => {
+                const transferredBytes = completedBytes + step.transferredBytes;
+                options.onProgress?.({
+                    operation: "upload",
+                    source: options.localPath,
+                    destination: options.remotePath,
+                    transferredBytes,
+                    totalBytes,
+                    percentage: percentage(transferredBytes, totalBytes),
+                    currentFile: file.relativePath,
+                    completedFiles,
+                    totalFiles: files.length
+                });
+            });
+            completedBytes += file.size;
+            completedFiles += 1;
+        }
+    }
+    async resolveRemoteDestinationForLocalFile(options, remotePath) {
+        const remoteKind = await this.transport.exists(remotePath);
+        const isDirectoryLikeDestination = remoteKind === "d" || remotePath.endsWith("/");
+        if (!isDirectoryLikeDestination) {
+            await this.ensureRemoteParent(remotePath, shouldCreateDirectories(options));
+            await this.assertRemoteOverwrite(remotePath, options.overwrite);
+            return remotePath;
+        }
+        if (remoteKind && remoteKind !== "d") {
+            throw new TransferError(`Remote destination already exists and is not a directory: ${remotePath}`, {
+                context: { remotePath }
+            });
+        }
+        const remoteDirectory = remotePath.replace(/\/+$/g, "") || "/";
+        if (!remoteKind) {
+            if (!shouldCreateDirectories(options)) {
+                throw new TransferError(`Remote destination directory does not exist: ${remoteDirectory}`, {
+                    context: { remotePath }
+                });
+            }
+            await this.transport.mkdir(remoteDirectory, true);
+        }
+        const destinationFile = remoteJoin(remoteDirectory, path.basename(resolveLocalPath(options.localPath)));
+        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 = path.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 (!shouldCreateDirectories(options)) {
+                    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 (!shouldCreateDirectories(options)) {
+                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);
+        if (!remoteKind) {
+            throw new TransferError(`Remote path does not exist: ${options.remotePath}`, {
+                context: { remotePath: options.remotePath }
+            });
+        }
+        if (remoteKind === "d") {
+            if (!options.recursive) {
+                throw new ValidationError("Downloading a directory requires recursive mode.");
+            }
+            await this.downloadDirectory(options);
+            return;
+        }
+        await this.downloadSingleFile(options, remotePath);
+    }
+    async downloadSingleFile(options, remotePath) {
+        const localPath = await this.resolveLocalDestinationForRemoteFile(options, remotePath);
+        await this.assertLocalOverwrite(localPath, options.overwrite);
+        if (shouldCreateDirectories(options)) {
+            await promises.mkdir(path.dirname(localPath), { recursive: true });
+        }
+        await this.transport.downloadFile(remotePath, localPath, (step) => {
+            options.onProgress?.({
+                operation: "download",
+                source: options.remotePath,
+                destination: options.localPath,
+                transferredBytes: step.transferredBytes,
+                totalBytes: step.totalBytes,
+                percentage: percentage(step.transferredBytes, step.totalBytes),
+                currentFile: options.remotePath
+            });
         });
-      }
-      await (0, import_promises6.mkdir)(localDestination, { recursive: true });
     }
-    return import_node_path4.default.join(localDestination, remoteBasename(remotePath));
-  }
-  async ensureRemoteParent(remotePath, createDirectories = false) {
-    const parent = remoteDirname(remotePath);
-    if (parent === "." || parent === "/") {
-      return;
+    async downloadDirectory(options) {
+        const remotePath = normalizeRemotePath(options.remotePath);
+        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 ensureLocalDirectory(localRoot, shouldCreateDirectories(options));
+        for (const file of files) {
+            const localFile = path.join(localRoot, ...file.relativePath.split("/"));
+            await this.assertLocalOverwrite(localFile, options.overwrite);
+            await promises.mkdir(path.dirname(localFile), { recursive: true });
+            await this.transport.downloadFile(file.remotePath, localFile, (step) => {
+                const transferredBytes = completedBytes + step.transferredBytes;
+                options.onProgress?.({
+                    operation: "download",
+                    source: options.remotePath,
+                    destination: options.localPath,
+                    transferredBytes,
+                    totalBytes,
+                    percentage: percentage(transferredBytes, totalBytes),
+                    currentFile: file.relativePath,
+                    completedFiles,
+                    totalFiles: files.length
+                });
+            });
+            completedBytes += file.size;
+            completedFiles += 1;
+        }
     }
-    if (createDirectories) {
-      await this.transport.mkdir(parent, true);
-      return;
-    }
-    const exists = await this.transport.exists(parent);
-    if (exists !== "d") {
-      throw new TransferError(`Remote destination parent does not exist: ${parent}`, {
-        context: { remotePath }
-      });
-    }
-  }
-  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;
-    }
-    const exists = await this.transport.exists(remotePath);
-    if (exists) {
-      throw new TransferError(
-        `Remote destination already exists: ${remotePath}. Use --overwrite to overwrite it.`,
-        {
-          context: { remotePath }
-        }
-      );
-    }
-  }
-  async assertLocalOverwrite(localPath, overwrite = false) {
-    if (overwrite) {
-      return;
+    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 (!shouldCreateDirectories(options)) {
+                throw new TransferError(`Local destination directory does not exist: ${localDestination}`, {
+                    context: { localPath: options.localPath }
+                });
+            }
+            await promises.mkdir(localDestination, { recursive: true });
+        }
+        return path.join(localDestination, remoteBasename(remotePath));
     }
-    try {
-      await (0, import_promises6.access)(localPath);
-      throw new TransferError(`Local destination already exists: ${localPath}`, {
-        context: { localPath }
-      });
-    } catch (error) {
-      if (error instanceof TransferError) {
-        throw error;
-      }
+    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 (!shouldCreateDirectories(options)) {
+                throw new TransferError(`Local destination directory does not exist: ${localDestination}`, {
+                    context: { localPath: options.localPath }
+                });
+            }
+            await promises.mkdir(localDestination, { recursive: true });
+        }
+        return path.join(localDestination, remoteBasename(remotePath));
+    }
+    async ensureRemoteParent(remotePath, createDirectories = false) {
+        const parent = remoteDirname(remotePath);
+        if (parent === "." || parent === "/") {
+            return;
+        }
+        if (createDirectories) {
+            await this.transport.mkdir(parent, true);
+            return;
+        }
+        const exists = await this.transport.exists(parent);
+        if (exists !== "d") {
+            throw new TransferError(`Remote destination parent does not exist: ${parent}`, {
+                context: { remotePath }
+            });
+        }
     }
-  }
-};
+    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;
+        }
+        const exists = await this.transport.exists(remotePath);
+        if (exists) {
+            throw new TransferError(`Remote destination already exists: ${remotePath}. Use --overwrite to overwrite it.`, {
+                context: { remotePath }
+            });
+        }
+    }
+    async assertLocalOverwrite(localPath, overwrite = false) {
+        if (overwrite) {
+            return;
+        }
+        try {
+            await promises.access(localPath);
+            throw new TransferError(`Local destination already exists: ${localPath}`, {
+                context: { localPath }
+            });
+        }
+        catch (error) {
+            if (error instanceof TransferError) {
+                throw error;
+            }
+        }
+    }
+}
 function createClient(options) {
-  return new ScpNextClientImpl(options);
+    return new ScpNextClientImpl(options);
 }
 
-// src/client/upload.ts
 async function upload(options) {
-  const client = new ScpNextClientImpl(options);
-  try {
-    await client.upload(options.localPath, options.remotePath, options);
-  } finally {
+    const client = new ScpNextClientImpl(options);
+    let result;
+    try {
+        result = await client.upload(options.localPath, options.remotePath, options);
+    }
+    catch (error) {
+        try {
+            await client.close();
+        }
+        catch {
+            // Preserve the upload or command failure as the primary error.
+        }
+        throw error;
+    }
     await client.close();
-  }
+    return result;
 }
 
-// src/client/download.ts
 async function download(options) {
-  const client = new ScpNextClientImpl(options);
-  try {
-    await client.download(options.remotePath, options.localPath, options);
-  } finally {
-    await client.close();
-  }
+    const client = new ScpNextClientImpl(options);
+    try {
+        await client.download(options.remotePath, options.localPath, options);
+    }
+    finally {
+        await client.close();
+    }
 }
 
-// src/client/copy.ts
 async function copy(options) {
-  if (options.source.type === "local" && options.destination.type === "remote") {
-    await upload({
-      ...options,
-      localPath: options.source.path,
-      remotePath: options.destination.path
-    });
-    return;
-  }
-  if (options.source.type === "remote" && options.destination.type === "local") {
-    await download({
-      ...options,
-      remotePath: options.source.path,
-      localPath: options.destination.path
+    if (options.source.type === "local" && options.destination.type === "remote") {
+        await upload({
+            ...options,
+            localPath: options.source.path,
+            remotePath: options.destination.path
+        });
+        return;
+    }
+    if (options.source.type === "remote" && options.destination.type === "local") {
+        await download({
+            ...options,
+            remotePath: options.source.path,
+            localPath: options.destination.path
+        });
+        return;
+    }
+    throw new ValidationError("copy() supports only local-to-remote or remote-to-local transfers.", {
+        context: {
+            sourceType: options.source.type,
+            destinationType: options.destination.type
+        }
     });
-    return;
-  }
-  throw new ValidationError("copy() supports only local-to-remote or remote-to-local transfers.", {
-    context: {
-      sourceType: options.source.type,
-      destinationType: options.destination.type
-    }
-  });
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  AuthenticationError,
-  ConfigurationError,
-  ConnectionError,
-  FileSystemError,
-  HostVerificationError,
-  ScpNextClientImpl,
-  ScpNextError,
-  TransferError,
-  ValidationError,
-  copy,
-  createClient,
-  download,
-  toScpNextError,
-  upload
-});
-//# sourceMappingURL=index.cjs.map
+
+exports.AuthenticationError = AuthenticationError;
+exports.ConfigurationError = ConfigurationError;
+exports.ConnectionError = ConnectionError;
+exports.FileSystemError = FileSystemError;
+exports.HostVerificationError = HostVerificationError;
+exports.RemoteCommandError = RemoteCommandError;
+exports.ScpNextClientImpl = ScpNextClientImpl;
+exports.ScpNextError = ScpNextError;
+exports.TransferError = TransferError;
+exports.ValidationError = ValidationError;
+exports.copy = copy;
+exports.createClient = createClient;
+exports.download = download;
+exports.toScpNextError = toScpNextError;
+exports.upload = upload;
+//# sourceMappingURL=index.cjs.map