scp-next 1.0.0

package/dist/cli/index.js

@@ -0,0 +1,1294 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command as Command4, CommanderError } from "commander";
+
+// src/client/client.ts
+import { access as access4, mkdir as mkdir2 } from "fs/promises";
+import path4 from "path";
+
+// src/client/transport.ts
+import { readFile as readFile2 } from "fs/promises";
+import SftpClient from "ssh2-sftp-client";
+
+// src/security/redact.ts
+var 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;
+function isSensitiveKey(key) {
+  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;
+}
+function formatErrorMessage(error) {
+  if (error instanceof Error) {
+    return String(redactSensitiveValues(error.message));
+  }
+  return String(redactSensitiveValues(error));
+}
+
+// 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" });
+  }
+};
+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")) {
+    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
+import { createHash } from "crypto";
+import { access as access2, readFile } from "fs/promises";
+
+// src/paths/local-path.ts
+import { constants } from "fs";
+import { access, mkdir, stat } from "fs/promises";
+import os from "os";
+import path from "path";
+function expandHome(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 path.isAbsolute(expanded) ? path.normalize(expanded) : path.resolve(baseDir, expanded);
+}
+async function assertLocalPathExists(inputPath) {
+  try {
+    await access(resolveLocalPath(inputPath), 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 = path.dirname(resolved);
+  if (createDirectories) {
+    await mkdir(parent, { recursive: true });
+    return;
+  }
+  try {
+    await access(parent, 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 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, "");
+}
+function isFingerprintMatch(actual, expected) {
+  return normalizeFingerprint(actual) === normalizeFingerprint(expected);
+}
+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) {
+    fingerprints.add(normalizeFingerprint(options.hostFingerprint));
+  }
+  try {
+    await access2(expandHome(knownHostsFile));
+    const content = await 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+/);
+      if (!hosts || !algorithm || !key || !hosts.split(",").includes(options.host)) {
+        continue;
+      }
+      const fingerprint = createHash("sha256").update(Buffer.from(key, "base64")).digest("base64").replace(/=+$/g, "");
+      fingerprints.add(fingerprint);
+    }
+  } 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."
+    );
+  }
+  return fingerprints;
+}
+function createHostVerifier(allowedFingerprints) {
+  return (hashedKey) => {
+    for (const expected of allowedFingerprints) {
+      if (isFingerprintMatch(hashedKey, expected)) {
+        return true;
+      }
+    }
+    return false;
+  };
+}
+
+// src/client/transport.ts
+function toRemoteFileInfo(info) {
+  return {
+    type: info.type,
+    name: info.name,
+    size: info.size
+  };
+}
+var Ssh2SftpTransport = class {
+  client;
+  constructor(name = "scp-next") {
+    this.client = new SftpClient(name);
+  }
+  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 readFile2(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;
+    }
+    if (options.timeout !== void 0) connectOptions.readyTimeout = options.timeout;
+    if (hostVerifier) {
+      connectOptions.hostHash = "sha256";
+      connectOptions.hostVerifier = hostVerifier;
+    }
+    try {
+      await this.client.connect(connectOptions);
+    } catch (error) {
+      const converted = toScpNextError(error);
+      if (converted instanceof HostVerificationError) {
+        throw converted;
+      }
+      throw new ConnectionError("Unable to connect to SSH server.", {
+        cause: error,
+        context: {
+          host: options.host,
+          port: options.port,
+          username: options.username
+        }
+      });
+    }
+  }
+  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}.`, {
+        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}.`, {
+        cause: error,
+        context: { remotePath, localPath }
+      });
+    }
+  }
+  transferOptions(onStep) {
+    if (!onStep) {
+      return void 0;
+    }
+    return {
+      step(transferredBytes, chunkBytes, totalBytes) {
+        onStep({ transferredBytes, chunkBytes, totalBytes });
+      }
+    };
+  }
+};
+
+// src/client/walk.ts
+import { readdir, stat as stat2 } from "fs/promises";
+import path3 from "path";
+
+// src/paths/remote-path.ts
+import path2 from "path";
+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 }
+    });
+  }
+}
+function normalizeRemotePath(inputPath) {
+  assertRemotePath(inputPath);
+  return path2.posix.normalize(inputPath.replace(/\\/g, "/"));
+}
+function remoteJoin(...parts) {
+  const joined = path2.posix.join(...parts);
+  assertRemotePath(joined);
+  return joined;
+}
+function remoteDirname(inputPath) {
+  assertRemotePath(inputPath);
+  return path2.posix.dirname(inputPath);
+}
+
+// src/client/walk.ts
+async function walkLocalFiles(rootPath) {
+  const resolvedRoot = resolveLocalPath(rootPath);
+  const stats = await stat2(resolvedRoot);
+  if (stats.isFile()) {
+    return [
+      {
+        absolutePath: resolvedRoot,
+        relativePath: path3.basename(resolvedRoot),
+        size: stats.size
+      }
+    ];
+  }
+  const files = [];
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolutePath = path3.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(absolutePath);
+      } else if (entry.isFile()) {
+        const entryStats = await stat2(absolutePath);
+        files.push({
+          absolutePath,
+          relativePath: path3.relative(resolvedRoot, absolutePath),
+          size: entryStats.size
+        });
+      }
+    }
+  }
+  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
+        });
+      }
+    }
+  }
+  await visit(rootPath, "", rootEntries);
+  return files;
+}
+
+// src/config/validation.ts
+import { access as access3 } from "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 }
+    });
+  }
+}
+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 }
+    });
+  }
+}
+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 access3(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);
+  }
+}
+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);
+  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));
+}
+function mergeOptions(serverOptions, transferOptions) {
+  return { ...serverOptions, ...transferOptions ?? {} };
+}
+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") {
+      await this.ensureRemoteParent(remotePath, options.createDirectories);
+      await this.assertRemoteOverwrite(remotePath, options.overwrite);
+      const totalBytes2 = void 0;
+      await this.transport.uploadFile(resolveLocalPath(options.localPath), remotePath, (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 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);
+    }
+    for (const file of files) {
+      const destinationFile = remoteJoin(remotePath, 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) => {
+        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 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 = resolveLocalPath(options.localPath);
+    await this.assertLocalOverwrite(localPath, options.overwrite);
+    if (options.createDirectories) {
+      await mkdir2(path4.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 = resolveLocalPath(options.localPath);
+    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) });
+    for (const file of files) {
+      const localFile = path4.join(localRoot, ...file.relativePath.split("/"));
+      await this.assertLocalOverwrite(localFile, options.overwrite);
+      await mkdir2(path4.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 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 assertRemoteOverwrite(remotePath, overwrite = false) {
+    if (overwrite) {
+      return;
+    }
+    const exists = await this.transport.exists(remotePath);
+    if (exists) {
+      throw new TransferError(`Remote destination already exists: ${remotePath}`, {
+        context: { remotePath }
+      });
+    }
+  }
+  async assertLocalOverwrite(localPath, overwrite = false) {
+    if (overwrite) {
+      return;
+    }
+    try {
+      await access4(localPath);
+      throw new TransferError(`Local destination already exists: ${localPath}`, {
+        context: { localPath }
+      });
+    } catch (error) {
+      if (error instanceof TransferError) {
+        throw error;
+      }
+    }
+  }
+};
+
+// 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();
+  }
+}
+
+// src/client/upload.ts
+async function upload(options) {
+  const client = new ScpNextClientImpl(options);
+  try {
+    await client.upload(options.localPath, options.remotePath, options);
+  } finally {
+    await client.close();
+  }
+}
+
+// src/cli/commands/download.ts
+import { Command } from "commander";
+
+// src/cli/operands.ts
+function usageFor(operation) {
+  return `scp-next ${operation} <source> <destination> [options]`;
+}
+function assertSourceDestination(operation, source, destination) {
+  if (!source) {
+    throw new ValidationError(`Missing source path.
+
+Usage:
+  ${usageFor(operation)}`);
+  }
+  if (!destination) {
+    throw new ValidationError(`Missing destination path.
+
+Usage:
+  ${usageFor(operation)}`);
+  }
+}
+
+// src/cli/commands/shared.ts
+import { Option } from "commander";
+
+// src/config/environment.ts
+function parseInteger(value, name) {
+  if (!value) {
+    return void 0;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${name} must be a number.`);
+  }
+  return parsed;
+}
+function readEnvironment(env = process.env) {
+  const result = {};
+  if (env.SCP_NEXT_HOST) result.host = env.SCP_NEXT_HOST;
+  if (env.SCP_NEXT_PORT) {
+    const port = parseInteger(env.SCP_NEXT_PORT, "SCP_NEXT_PORT");
+    if (port !== void 0) result.port = port;
+  }
+  if (env.SCP_NEXT_USERNAME) result.username = env.SCP_NEXT_USERNAME;
+  if (env.SCP_NEXT_PASSWORD) result.password = env.SCP_NEXT_PASSWORD;
+  if (env.SCP_NEXT_PRIVATE_KEY) result.privateKey = env.SCP_NEXT_PRIVATE_KEY;
+  if (env.SCP_NEXT_PRIVATE_KEY_FILE) result.privateKeyFile = env.SCP_NEXT_PRIVATE_KEY_FILE;
+  if (env.SCP_NEXT_PASSPHRASE) result.passphrase = env.SCP_NEXT_PASSPHRASE;
+  if (env.SCP_NEXT_TIMEOUT) {
+    const timeout = parseInteger(env.SCP_NEXT_TIMEOUT, "SCP_NEXT_TIMEOUT");
+    if (timeout !== void 0) result.timeout = timeout;
+  }
+  if (env.SCP_NEXT_PROFILE) result.profile = env.SCP_NEXT_PROFILE;
+  return result;
+}
+
+// src/config/load-config.ts
+import { access as access5, readFile as readFile3 } from "fs/promises";
+import path5 from "path";
+import { z } from "zod";
+var CONFIG_FILENAMES = ["scp-next.config.json", ".scp-nextrc", ".scp-nextrc.json"];
+var serverSchema = z.object({
+  host: z.string().optional(),
+  port: z.number().int().optional(),
+  username: z.string().optional(),
+  password: z.string().optional(),
+  privateKey: z.string().optional(),
+  privateKeyFile: z.string().optional(),
+  passphrase: z.string().optional(),
+  agent: z.string().optional(),
+  timeout: z.number().int().optional(),
+  hostFingerprint: z.string().optional(),
+  knownHostsFile: z.string().optional()
+});
+var transferSchema = z.object({
+  recursive: z.boolean().optional(),
+  overwrite: z.boolean().optional(),
+  createDirectories: z.boolean().optional(),
+  dryRun: z.boolean().optional(),
+  timeout: z.number().int().optional()
+});
+var jobSchema = transferSchema.extend({
+  operation: z.enum(["upload", "download"]),
+  profile: z.string().optional(),
+  source: z.string(),
+  destination: z.string()
+});
+var configSchema = serverSchema.extend({
+  defaultProfile: z.string().optional(),
+  server: serverSchema.optional(),
+  transfer: transferSchema.optional(),
+  profiles: z.record(serverSchema).optional(),
+  jobs: z.record(jobSchema).optional()
+}).passthrough();
+async function fileExists(filePath) {
+  try {
+    await access5(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findConfigFile(cwd = process.cwd()) {
+  for (const filename of CONFIG_FILENAMES) {
+    const candidate = path5.resolve(cwd, filename);
+    if (await fileExists(candidate)) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+async function loadConfig(explicitPath, cwd = process.cwd()) {
+  const configPath = explicitPath ? resolveLocalPath(explicitPath, cwd) : await findConfigFile(cwd);
+  if (!configPath) {
+    return { config: {}, directory: cwd };
+  }
+  let raw;
+  try {
+    raw = await readFile3(configPath, "utf8");
+  } catch (error) {
+    throw new ConfigurationError(`Unable to read configuration file: ${configPath}`, {
+      cause: error,
+      context: { path: configPath }
+    });
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const result = configSchema.safeParse(parsed);
+    if (!result.success) {
+      throw new ConfigurationError(`Invalid configuration file: ${result.error.message}`, {
+        context: { path: configPath }
+      });
+    }
+    return {
+      config: result.data,
+      path: configPath,
+      directory: path5.dirname(configPath)
+    };
+  } catch (error) {
+    if (error instanceof ConfigurationError) {
+      throw error;
+    }
+    throw new ConfigurationError(`Invalid JSON in configuration file: ${configPath}`, {
+      cause: error,
+      context: { path: configPath }
+    });
+  }
+}
+
+// src/config/resolve-config.ts
+import path6 from "path";
+
+// src/config/jobs.ts
+function selectJob(config, jobName) {
+  const job = config.jobs?.[jobName];
+  if (!job) {
+    throw new ConfigurationError(`Unknown job: ${jobName}`, {
+      context: { job: jobName }
+    });
+  }
+  return job;
+}
+
+// src/config/profiles.ts
+function selectProfile(config, profileName) {
+  if (!profileName) {
+    return void 0;
+  }
+  const profile = config.profiles?.[profileName];
+  if (!profile) {
+    throw new ConfigurationError(`Unknown profile: ${profileName}`, {
+      context: { profile: profileName }
+    });
+  }
+  return profile;
+}
+
+// src/config/resolve-config.ts
+var DEFAULT_TRANSFER = {
+  port: 22,
+  recursive: false,
+  overwrite: false,
+  createDirectories: false,
+  dryRun: false
+};
+function assignDefined(target, source) {
+  if (!source) {
+    return target;
+  }
+  for (const [key, value] of Object.entries(source)) {
+    if (value !== void 0) {
+      Object.assign(target, { [key]: value });
+    }
+  }
+  return target;
+}
+function rootServer(config) {
+  const result = {};
+  assignDefined(result, config.server);
+  assignDefined(result, {
+    host: config.host,
+    port: config.port,
+    username: config.username,
+    password: config.password,
+    privateKey: config.privateKey,
+    privateKeyFile: config.privateKeyFile,
+    passphrase: config.passphrase,
+    agent: config.agent,
+    timeout: config.timeout,
+    hostFingerprint: config.hostFingerprint,
+    knownHostsFile: config.knownHostsFile
+  });
+  return result;
+}
+function jobTransfer(job) {
+  const result = {};
+  if (!job) {
+    return result;
+  }
+  return assignDefined(result, {
+    recursive: job.recursive,
+    overwrite: job.overwrite,
+    createDirectories: job.createDirectories,
+    dryRun: job.dryRun,
+    timeout: job.timeout
+  });
+}
+function resolveConfigRelatedPaths(resolved, operation, configDirectory) {
+  const next = { ...resolved };
+  if (next.privateKeyFile && !next.privateKeyFile.startsWith("~")) {
+    next.privateKeyFile = path6.isAbsolute(next.privateKeyFile) ? next.privateKeyFile : resolveLocalPath(next.privateKeyFile, configDirectory);
+  }
+  if (next.knownHostsFile && !next.knownHostsFile.startsWith("~")) {
+    next.knownHostsFile = path6.isAbsolute(next.knownHostsFile) ? next.knownHostsFile : resolveLocalPath(next.knownHostsFile, configDirectory);
+  }
+  if (operation === "upload" && !next.source.startsWith("~")) {
+    next.source = path6.isAbsolute(next.source) ? next.source : resolveLocalPath(next.source, configDirectory);
+  }
+  if (operation === "download" && !next.destination.startsWith("~")) {
+    next.destination = path6.isAbsolute(next.destination) ? next.destination : resolveLocalPath(next.destination, configDirectory);
+  }
+  return next;
+}
+function resolveTransferConfig(input) {
+  const config = input.config ?? {};
+  const env = input.env ?? {};
+  const cli = input.cli ?? {};
+  const configDirectory = input.configDirectory ?? process.cwd();
+  const cwd = input.cwd ?? process.cwd();
+  const job = input.jobName ? selectJob(config, input.jobName) : void 0;
+  const operation = input.operation ?? job?.operation;
+  if (!operation) {
+    throw new Error("Transfer operation is required.");
+  }
+  const selectedProfileName = cli.profile ?? env.profile ?? job?.profile ?? config.defaultProfile;
+  const profile = selectProfile(config, selectedProfileName);
+  const resolved = {
+    ...DEFAULT_TRANSFER,
+    operation,
+    source: job?.source ?? "",
+    destination: job?.destination ?? ""
+  };
+  assignDefined(resolved, jobTransfer(job));
+  assignDefined(resolved, config.transfer);
+  assignDefined(resolved, rootServer(config));
+  assignDefined(resolved, profile);
+  assignDefined(resolved, {
+    host: env.host,
+    port: env.port,
+    username: env.username,
+    password: env.password,
+    privateKey: env.privateKey,
+    privateKeyFile: env.privateKeyFile,
+    passphrase: env.passphrase,
+    timeout: env.timeout
+  });
+  assignDefined(resolved, {
+    source: input.source,
+    destination: input.destination
+  });
+  assignDefined(resolved, cli);
+  if (selectedProfileName) {
+    resolved.profile = selectedProfileName;
+  }
+  const pathResolved = resolveConfigRelatedPaths(resolved, operation, configDirectory);
+  if (input.source && operation === "upload") {
+    pathResolved.source = resolveLocalPath(input.source, cwd);
+  }
+  if (input.destination && operation === "download") {
+    pathResolved.destination = resolveLocalPath(input.destination, cwd);
+  }
+  return pathResolved;
+}
+
+// src/cli/output.ts
+function writeDryRun(output, config) {
+  const destination = config.operation === "upload" ? `${config.username ?? "user"}@${config.host ?? "host"}:${config.destination}` : config.destination;
+  output.stdout.write(`Dry run: ${config.operation}
+`);
+  output.stdout.write(`Source: ${config.source}
+`);
+  output.stdout.write(`Destination: ${destination}
+`);
+  output.stdout.write(`Recursive: ${config.recursive ? "yes" : "no"}
+`);
+  output.stdout.write(`Overwrite: ${config.overwrite ? "yes" : "no"}
+`);
+}
+function createProgressReporter(output, quiet) {
+  if (quiet || !output.stderr.isTTY) {
+    return void 0;
+  }
+  return (progress) => {
+    const total = progress.totalBytes ? formatBytes(progress.totalBytes) : "?";
+    const transferred = formatBytes(progress.transferredBytes);
+    const percentage2 = progress.percentage === void 0 ? "" : ` (${progress.percentage}%)`;
+    const currentFile = progress.currentFile ? `: ${progress.currentFile}` : "";
+    output.stderr.write(`\r${progress.operation === "upload" ? "Uploading" : "Downloading"}${currentFile}
+`);
+    output.stderr.write(`${transferred} / ${total}${percentage2}
+`);
+  };
+}
+function verbosePlan(output, config) {
+  output.stderr.write(
+    `${JSON.stringify(
+      redactSensitiveValues({
+        operation: config.operation,
+        host: config.host,
+        port: config.port,
+        username: config.username,
+        source: config.source,
+        destination: config.destination,
+        recursive: config.recursive,
+        overwrite: config.overwrite,
+        createDirectories: config.createDirectories,
+        dryRun: config.dryRun
+      }),
+      null,
+      2
+    )}
+`
+  );
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes / 1024;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+  return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+// src/cli/commands/shared.ts
+function addTransferOptions(command) {
+  command.option("--host <host>", "SSH server host");
+  command.addOption(new Option("--port <port>", "SSH server port").argParser(parseInteger2));
+  command.option("--username <username>", "SSH username");
+  command.option("--password <password>", "SSH password (prefer environment variables or key files)");
+  command.option("--private-key <privateKey>", "Private-key content");
+  command.option("--private-key-file <privateKeyFile>", "Private-key file path");
+  command.option("--passphrase <passphrase>", "Private-key passphrase");
+  command.option("--config <path>", "Configuration file path");
+  command.option("--profile <name>", "Named server profile");
+  command.option("--recursive", "Transfer directories recursively");
+  command.option("--overwrite", "Overwrite existing destination files");
+  command.option("--create-directories", "Create missing destination directories");
+  command.option("--dry-run", "Resolve and validate without connecting or transferring");
+  command.addOption(new Option("--timeout <milliseconds>", "Connection/operation timeout").argParser(parseInteger2));
+  command.option("--verbose", "Print verbose diagnostic output");
+  command.option("--quiet", "Disable progress and non-error output");
+  return command;
+}
+function parseInteger2(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) {
+    throw new Error("Expected a number.");
+  }
+  return parsed;
+}
+function toCliOptions(options) {
+  return {
+    host: options.host,
+    port: options.port,
+    username: options.username,
+    password: options.password,
+    privateKey: options.privateKey,
+    privateKeyFile: options.privateKeyFile,
+    passphrase: options.passphrase,
+    profile: options.profile,
+    recursive: options.recursive,
+    overwrite: options.overwrite,
+    createDirectories: options.createDirectories,
+    dryRun: options.dryRun,
+    timeout: options.timeout
+  };
+}
+async function resolveForCli(input) {
+  const loaded = await loadConfig(input.options.config, input.cwd);
+  return resolveTransferConfig({
+    operation: input.operation,
+    source: input.source,
+    destination: input.destination,
+    jobName: input.jobName,
+    cli: toCliOptions(input.options),
+    env: readEnvironment(),
+    config: loaded.config,
+    configDirectory: loaded.directory,
+    cwd: input.cwd
+  });
+}
+async function executeResolvedTransfer(config, handlers, output, commandOptions) {
+  if (commandOptions.verbose) {
+    verbosePlan(output, config);
+  }
+  if (config.dryRun) {
+    if (!commandOptions.quiet) {
+      writeDryRun(output, config);
+    }
+    return;
+  }
+  const onProgress = createProgressReporter(output, commandOptions.quiet);
+  if (config.operation === "upload") {
+    const uploadOptions = {
+      ...config,
+      localPath: config.source,
+      remotePath: config.destination
+    };
+    if (onProgress) uploadOptions.onProgress = onProgress;
+    await handlers.upload(uploadOptions);
+    return;
+  }
+  const downloadOptions = {
+    ...config,
+    remotePath: config.source,
+    localPath: config.destination
+  };
+  if (onProgress) downloadOptions.onProgress = onProgress;
+  await handlers.download(downloadOptions);
+}
+
+// src/cli/commands/download.ts
+function createDownloadCommand(handlers, output, cwd) {
+  const command = new Command("download").description("Download a remote source path to a local destination path").usage("<source> <destination> [options]").argument("[source]", "Remote file or directory path").argument("[destination]", "Local file or directory").action(async (source, destination, options) => {
+    assertSourceDestination("download", source, destination);
+    const resolved = await resolveForCli({
+      operation: "download",
+      source,
+      destination,
+      options,
+      cwd
+    });
+    await executeResolvedTransfer(resolved, handlers, output, options);
+  });
+  addTransferOptions(command);
+  return command;
+}
+
+// src/cli/commands/run.ts
+import { Command as Command2 } from "commander";
+function createRunCommand(handlers, output, cwd) {
+  const command = new Command2("run").description("Run a configured transfer job").usage("<job> [source] [destination] [options]").argument("<job>", "Configured job name").argument("[source]", "Optional source override").argument("[destination]", "Optional destination override").action(
+    async (jobName, source, destination, options) => {
+      const resolved = await resolveForCli({
+        source,
+        destination,
+        jobName,
+        options,
+        cwd
+      });
+      await executeResolvedTransfer(resolved, handlers, output, options);
+    }
+  );
+  addTransferOptions(command);
+  return command;
+}
+
+// src/cli/commands/upload.ts
+import { Command as Command3 } from "commander";
+function createUploadCommand(handlers, output, cwd) {
+  const command = new Command3("upload").description("Upload a local source path to a remote destination path").usage("<source> <destination> [options]").argument("[source]", "Local file or directory").argument("[destination]", "Remote file or directory path").action(async (source, destination, options) => {
+    assertSourceDestination("upload", source, destination);
+    const resolved = await resolveForCli({
+      operation: "upload",
+      source,
+      destination,
+      options,
+      cwd
+    });
+    await executeResolvedTransfer(resolved, handlers, output, options);
+  });
+  addTransferOptions(command);
+  return command;
+}
+
+// src/cli/index.ts
+async function runCli(options = {}) {
+  const output = options.output ?? { stdout: process.stdout, stderr: process.stderr };
+  const cwd = options.cwd ?? process.cwd();
+  const handlers = options.handlers ?? { upload, download };
+  const program = new Command4();
+  program.name("scp-next").description("Secure file transfers over SSH using SFTP").version("0.1.0").showHelpAfterError().exitOverride();
+  program.addCommand(createUploadCommand(handlers, output, cwd));
+  program.addCommand(createDownloadCommand(handlers, output, cwd));
+  program.addCommand(createRunCommand(handlers, output, cwd));
+  try {
+    await program.parseAsync(options.argv ?? process.argv, { from: "node" });
+    return 0;
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      if (error.code === "commander.helpDisplayed" || error.code === "commander.version") {
+        return 0;
+      }
+      output.stderr.write(`${formatErrorMessage(error.message)}
+`);
+      return error.exitCode || 1;
+    }
+    const verbose = (options.argv ?? process.argv).includes("--verbose");
+    if (error instanceof ScpNextError) {
+      output.stderr.write(`Error: ${formatErrorMessage(error.message)}
+`);
+      if (verbose && error.cause instanceof Error) {
+        output.stderr.write(`${formatErrorMessage(error.cause.stack ?? error.cause.message)}
+`);
+      }
+      return 1;
+    }
+    output.stderr.write(`Error: ${formatErrorMessage(error)}
+`);
+    if (verbose && error instanceof Error && error.stack) {
+      output.stderr.write(`${formatErrorMessage(error.stack)}
+`);
+    }
+    return 1;
+  }
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  void runCli().then((exitCode) => {
+    process.exitCode = exitCode;
+  });
+}
+export {
+  runCli
+};
+//# sourceMappingURL=index.js.map