@linxin666/dsh-ssh 0.1.13 → 0.1.15

package/lib/index.js

@@ -1,9 +1,9 @@
 import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
-import { createServer } from "node:net";
 import { createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
 import { Client } from "ssh2";
 import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { createServer } from "node:net";
 import { unlink } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { WebSocket, WebSocketServer } from "ws";
@@ -1312,13 +1312,12 @@ function expandHome(path) {
 	return path;
 }
 //#endregion
-//#region src/engine.ts
+//#region src/engine/connection-pool.ts
 /**
-* The SSH engine: a per-alias persistent connection pool (ssh2) with
-* multi-hop jump support, command execution, PTY shells, SFTP transfers,
-* local port-forward tunnels and cluster execution — the DSH counterpart of
-* ssh-skill's daemon + scripts, living entirely in the host process.
+* Connection pool: per-alias persistent ssh2 connections with multi-hop jump
+* support, the acquire / dispose / sweep lifecycle, and the pooled exec path.
 */
+/** Default engine knobs (applied when an option is omitted). */
 const DEFAULTS = {
 	idleTimeoutMs: 30 * 6e4,
 	connectTimeoutMs: 15e3,
@@ -1342,7 +1341,7 @@ function buildConnectConfig(entry, sock) {
 	if (entry.auth.kind === "password") config.password = entry.auth.password;
 	else {
 		const keyPath = entry.auth.keyPath === void 0 ? void 0 : expandHome(entry.auth.keyPath);
-		if (keyPath === void 0 || !existsSync(keyPath)) throw new Error(`private key not found: '${entry.auth.keyPath ?? "(unset)"}'`);
+		if (keyPath === void 0 || !existsSync(keyPath)) throw new Error("private key not found: " + (entry.auth.keyPath ?? "(unset)"));
 		config.privateKey = readFileSync(keyPath, "utf8");
 		if (entry.auth.passphrase !== void 0 && entry.auth.passphrase !== "") config.passphrase = entry.auth.passphrase;
 	}
@@ -1385,6 +1384,283 @@ function appendOutput(target, chunk, maxBytes) {
 	}
 	target.text += chunk.toString("utf8");
 }
+/**
+* Build one full jump chain for an entry: hop clients connected through in
+* order, each forwarding a stream to the next destination, ending with the
+* target client. Shared by the pool and standalone shell sessions.
+*/
+async function connectChain(engine, entry) {
+	const hops = [];
+	let sock;
+	const chain = entry.proxyJump;
+	for (let index = 0; index < chain.length; index += 1) {
+		const hopAlias = chain[index];
+		const hop = engine.store.find(hopAlias);
+		if (hop === void 0) {
+			for (const client of hops) client.end();
+			throw new Error("proxyJump alias '" + hopAlias + "' not found — create it first");
+		}
+		const hopClient = await connectClient(buildConnectConfig(hop, sock));
+		hops.push(hopClient);
+		const next = index + 1 < chain.length ? engine.store.find(chain[index + 1]) : void 0;
+		const nextHost = next !== void 0 ? next.host : entry.host;
+		const nextPort = next !== void 0 ? next.port : entry.port;
+		sock = await new Promise((resolve, reject) => {
+			hopClient.forwardOut("127.0.0.1", 0, nextHost, nextPort, (error, stream) => {
+				if (error !== void 0) {
+					for (const client of hops) client.end();
+					reject(error);
+				} else resolve(stream);
+			});
+		});
+	}
+	try {
+		return {
+			client: await connectClient(buildConnectConfig(entry, sock)),
+			hops
+		};
+	} catch (error) {
+		for (const client of hops) client.end();
+		throw error;
+	}
+}
+/** Connect (or reuse) the pooled chain for one alias; pins nothing. */
+async function acquire(engine, alias) {
+	const pending = engine.acquireQueue.get(alias);
+	if (pending !== void 0) return pending;
+	const task = doAcquire(engine, alias);
+	engine.acquireQueue.set(alias, task);
+	try {
+		return await task;
+	} finally {
+		if (engine.acquireQueue.get(alias) === task) engine.acquireQueue.delete(alias);
+	}
+}
+async function doAcquire(engine, alias) {
+	const entry = engine.store.find(alias);
+	if (entry === void 0) throw new Error("alias '" + alias + "' not found — add it first");
+	const { client, hops } = await connectChain(engine, entry);
+	const record = {
+		client,
+		hops,
+		idleAt: Date.now(),
+		pinned: false,
+		broken: false,
+		inFlight: 0
+	};
+	client.on("error", () => {
+		record.broken = true;
+	});
+	client.on("close", () => {
+		record.broken = true;
+	});
+	engine.pool.set(alias, record);
+	return record;
+}
+/**
+* Tear down one alias's record. When `record` is given and no longer the
+* pooled record for the alias (a concurrent acquire replaced it), nothing
+* is torn down — the connection belongs to someone else now.
+*/
+function disposeRecord(engine, alias, record) {
+	const current = engine.pool.get(alias);
+	if (record !== void 0 && current !== record) return;
+	if (current === void 0) return;
+	engine.pool.delete(alias);
+	try {
+		current.client.end();
+	} catch {}
+	for (const hop of current.hops) try {
+		hop.end();
+	} catch {}
+}
+/** Close connections idle beyond the threshold (skips pinned and in-flight). */
+function sweepPool(engine) {
+	const cutoff = Date.now() - engine.opts.idleTimeoutMs;
+	for (const [alias, record] of engine.pool) if (!record.pinned && record.inFlight === 0 && record.idleAt < cutoff) disposeRecord(engine, alias, record);
+}
+/**
+* Run `fn` with a live client for `alias`, reconnecting (up to the
+* attempt budget) when the connection broke mid-flight.
+*/
+async function withClient(engine, alias, fn, attempts = 3) {
+	let lastError;
+	for (let attempt = 1; attempt <= attempts; attempt += 1) {
+		let record = engine.pool.get(alias);
+		if (record === void 0 || record.broken) {
+			if (record !== void 0) disposeRecord(engine, alias, record);
+			record = await acquire(engine, alias);
+		}
+		record.idleAt = Date.now();
+		record.inFlight += 1;
+		try {
+			const result = await fn(record.client);
+			record.idleAt = Date.now();
+			return result;
+		} finally {
+			record.inFlight -= 1;
+		}
+	}
+	throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+/** Run one command on `alias` (reusing the pooled connection). */
+async function execCommand(engine, alias, command, timeoutMs) {
+	const started = Date.now();
+	const budget = timeoutMs !== void 0 && timeoutMs > 0 ? timeoutMs : engine.opts.defaultExecTimeoutMs;
+	return withClient(engine, alias, async (client) => {
+		return await new Promise((resolve, reject) => {
+			client.exec(command, (error, stream) => {
+				if (error !== void 0) {
+					reject(error);
+					return;
+				}
+				const stdout = {
+					text: "",
+					truncated: false
+				};
+				const stderr = {
+					text: "",
+					truncated: false
+				};
+				let timedOut = false;
+				let settled = false;
+				const finish = () => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(timer);
+					resolve({
+						success: false,
+						exitCode: null,
+						timedOut,
+						stdout: stdout.text,
+						stderr: stderr.text,
+						durationMs: Date.now() - started,
+						error: timedOut ? "command timed out after " + budget + " ms" : void 0
+					});
+				};
+				const timer = setTimeout(() => {
+					timedOut = true;
+					try {
+						stream.signal("KILL");
+					} catch {}
+					try {
+						stream.close();
+					} catch {}
+					finish();
+				}, budget);
+				stream.on("data", (chunk) => appendOutput(stdout, chunk, engine.opts.maxOutputBytes));
+				stream.stderr.on("data", (chunk) => appendOutput(stderr, chunk, engine.opts.maxOutputBytes));
+				stream.on("close", (code) => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(timer);
+					resolve({
+						success: code === 0 && !timedOut,
+						exitCode: code,
+						timedOut,
+						stdout: stdout.text,
+						stderr: stderr.text,
+						durationMs: Date.now() - started
+					});
+				});
+				stream.on("error", (streamError) => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(timer);
+					reject(streamError);
+				});
+			});
+		});
+	});
+}
+//#endregion
+//#region src/engine/pty.ts
+/**
+* Open a PTY shell session for the web terminal (standalone connection).
+* The shell is a long-lived exclusive stream: it uses its own connection so
+* closing it can never tear down a pooled exec/tunnel sharing the alias.
+*/
+async function openShell(engine, alias, size) {
+	const entry = engine.store.find(alias);
+	if (entry === void 0) throw new Error("alias '" + alias + "' not found — add it first");
+	const { client, hops } = await connectChain(engine, entry);
+	return await new Promise((resolve, reject) => {
+		client.shell({
+			term: "xterm-256color",
+			cols: size.cols,
+			rows: size.rows
+		}, (error, stream) => {
+			if (error !== void 0) {
+				try {
+					client.end();
+				} catch {}
+				for (const hop of hops) try {
+					hop.end();
+				} catch {}
+				reject(error);
+				return;
+			}
+			let tornDown = false;
+			const teardown = () => {
+				if (tornDown) return;
+				tornDown = true;
+				try {
+					client.end();
+				} catch {}
+				for (const hop of hops) try {
+					hop.end();
+				} catch {}
+			};
+			const session = {
+				send: (data) => {
+					try {
+						stream.write(data);
+					} catch {}
+				},
+				resize: (cols, rows) => {
+					try {
+						stream.setWindow(rows, cols, rows, cols);
+					} catch {}
+				},
+				close: () => {
+					try {
+						stream.close();
+					} catch {}
+					teardown();
+				},
+				pause: () => {
+					try {
+						stream.pause();
+					} catch {}
+				},
+				resume: () => {
+					try {
+						stream.resume();
+					} catch {}
+				}
+			};
+			stream.on("data", (chunk) => {
+				session.onData?.(chunk);
+			});
+			stream.on("close", (code) => {
+				teardown();
+				session.onExit?.(code);
+			});
+			stream.on("error", (streamError) => {
+				teardown();
+				session.onExit?.(null, streamError instanceof Error ? streamError.message : String(streamError));
+			});
+			resolve(session);
+		});
+	});
+}
+//#endregion
+//#region src/engine/sftp.ts
+/**
+* SFTP transfers: upload (file or recursive tree), single-file download, and
+* remote directory listing. Every channel is opened once per operation and
+* released exactly once so sshd's MaxSessions cap is never exhausted.
+*/
 /** Walk a local directory, collecting relative paths of every file. */
 function walkLocalDir(root) {
 	const files = [];
@@ -1399,6 +1675,366 @@ function walkLocalDir(root) {
 	visit(root);
 	return files;
 }
+/** Upload one local file (or directory tree) to a remote path. */
+async function upload(engine, alias, localPath, remotePath, recursive, onProgress) {
+	if (!remotePath.startsWith("/")) throw new Error("remotePath must be an absolute path (got '" + remotePath + "')");
+	const local = resolve(localPath);
+	if (!existsSync(local)) throw new Error("local path not found: '" + localPath + "'");
+	return withClient(engine, alias, (client) => withSftp(client, async (sftp) => {
+		const stat = statSync(local);
+		let files;
+		if (stat.isDirectory()) {
+			if (!recursive) throw new Error("'" + localPath + "' is a directory — enable recursive upload");
+			files = walkLocalDir(local);
+			await ensureRemoteDir(sftp, remotePath);
+		} else {
+			files = [""];
+			await ensureRemoteDir(sftp, dirname(remotePath));
+		}
+		let bytes = 0;
+		for (const rel of files) {
+			const src = rel === "" ? local : join(local, rel);
+			const remoteRel = rel.split(/[\\/]/).join("/");
+			await fastPut(sftp, src, rel === "" ? remotePath : remotePath.replace(/\/$/, "") + "/" + remoteRel, engine.opts.sftpConcurrency, onProgress);
+			bytes += statSync(src).size;
+		}
+		return {
+			bytes,
+			files: files.length
+		};
+	}));
+}
+/** Download one remote file to a local path. */
+async function download(engine, alias, remotePath, localPath, onProgress) {
+	return withClient(engine, alias, (client) => withSftp(client, async (sftp) => {
+		if ((await new Promise((resolve, reject) => {
+			sftp.stat(remotePath, (error, stats) => error !== void 0 ? reject(error) : resolve(stats));
+		})).isDirectory()) throw new Error("'" + remotePath + "' is a directory — directory download is not supported yet (download individual files)");
+		const local = resolve(localPath);
+		if (!existsSync(dirname(local))) mkdirSync(dirname(local), { recursive: true });
+		await fastGet(sftp, remotePath, local, engine.opts.sftpConcurrency, onProgress);
+		return { bytes: statSync(local).size };
+	}));
+}
+/** List a remote directory (file browser). */
+async function ls(engine, alias, path) {
+	return withClient(engine, alias, (client) => withSftp(client, async (sftp) => {
+		return await new Promise((resolve, reject) => {
+			sftp.readdir(path, (error, list) => {
+				if (error !== void 0) {
+					reject(error);
+					return;
+				}
+				resolve(list.map((item) => ({
+					name: item.filename,
+					type: item.attrs.isDirectory() ? "dir" : item.attrs.isFile() ? "file" : "other",
+					size: item.attrs.size,
+					mtimeMs: item.attrs.mtime * 1e3,
+					mode: item.attrs.mode
+				})));
+			});
+		});
+	}));
+}
+/**
+* Open one SFTP channel, run the operation, and release the channel exactly
+* once when the operation settles (success or error). ssh2 keeps each
+* subsystem channel open until end(); without this, every transfer leaks a
+* channel until sshd's MaxSessions cap makes all later opens fail.
+*/
+async function withSftp(client, run) {
+	const sftp = await sftpChannel(client);
+	let ended = false;
+	const endOnce = () => {
+		if (ended) return;
+		ended = true;
+		try {
+			sftp.end();
+		} catch {}
+	};
+	sftp.once("close", endOnce);
+	try {
+		return await run(sftp);
+	} finally {
+		endOnce();
+	}
+}
+function sftpChannel(client) {
+	return new Promise((resolve, reject) => {
+		client.sftp((error, sftp) => error !== void 0 ? reject(error) : resolve(sftp));
+	});
+}
+/** Create a remote directory chain (stat-then-mkdir per segment). */
+function ensureRemoteDir(sftp, remote) {
+	return new Promise((resolve, reject) => {
+		const segments = remote.replace(/^\/+/, "").split("/").filter((segment) => segment !== "");
+		const walk = (index) => {
+			if (index >= segments.length) {
+				resolve();
+				return;
+			}
+			const current = "/" + segments.slice(0, index + 1).join("/");
+			sftp.stat(current, (statError) => {
+				if (statError === void 0) {
+					walk(index + 1);
+					return;
+				}
+				sftp.mkdir(current, (mkdirError) => {
+					if (mkdirError !== void 0) {
+						reject(mkdirError);
+						return;
+					}
+					walk(index + 1);
+				});
+			});
+		};
+		walk(0);
+	});
+}
+function fastPut(sftp, src, dst, concurrency, onProgress) {
+	return new Promise((resolve, reject) => {
+		let last = 0;
+		let lastEmit = 0;
+		const started = Date.now();
+		onProgress?.({
+			phase: "transferring",
+			file: dst,
+			transferred: 0,
+			total: statSync(src).size,
+			percent: 0
+		});
+		sftp.fastPut(src, dst, {
+			concurrency,
+			step: (transferred, _chunk, total) => {
+				const now = Date.now();
+				if (now - lastEmit < 100 && transferred < total) return;
+				lastEmit = now;
+				const elapsed = (now - started) / 1e3;
+				onProgress?.({
+					phase: "transferring",
+					file: dst,
+					transferred,
+					total,
+					percent: total > 0 ? Math.round(transferred / total * 1e3) / 10 : 0,
+					speedBps: elapsed > 0 ? Math.round((transferred - last) / elapsed) : void 0
+				});
+				last = transferred;
+			}
+		}, (error) => {
+			if (error !== void 0) {
+				onProgress?.({
+					phase: "error",
+					file: dst,
+					transferred: 0,
+					total: 0,
+					percent: 0,
+					error: String(error)
+				});
+				reject(error);
+			} else {
+				onProgress?.({
+					phase: "done",
+					file: dst,
+					transferred: statSync(src).size,
+					total: statSync(src).size,
+					percent: 100
+				});
+				resolve();
+			}
+		});
+	});
+}
+function fastGet(sftp, src, dst, concurrency, onProgress) {
+	return new Promise((resolve, reject) => {
+		let last = 0;
+		let lastEmit = 0;
+		const started = Date.now();
+		sftp.fastGet(src, dst, {
+			concurrency,
+			step: (transferred, _chunk, total) => {
+				const now = Date.now();
+				if (now - lastEmit < 100 && transferred < total) return;
+				lastEmit = now;
+				const elapsed = (now - started) / 1e3;
+				onProgress?.({
+					phase: "transferring",
+					file: src,
+					transferred,
+					total,
+					percent: total > 0 ? Math.round(transferred / total * 1e3) / 10 : 0,
+					speedBps: elapsed > 0 ? Math.round((transferred - last) / elapsed) : void 0
+				});
+				last = transferred;
+			}
+		}, (error) => {
+			if (error !== void 0) {
+				onProgress?.({
+					phase: "error",
+					file: src,
+					transferred: 0,
+					total: 0,
+					percent: 0,
+					error: String(error)
+				});
+				reject(error);
+			} else {
+				onProgress?.({
+					phase: "done",
+					file: src,
+					transferred: statSync(dst).size,
+					total: statSync(dst).size,
+					percent: 100
+				});
+				resolve();
+			}
+		});
+	});
+}
+//#endregion
+//#region src/engine/tunnel.ts
+/**
+* Local port-forward tunnels: one loopback-only listener per tunnel, pinned
+* to a pooled connection so an idle sweep never closes it, with per-tunnel
+* socket tracking and stop (single / alias-scoped / all).
+*/
+/** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
+async function startTunnel(engine, alias, options) {
+	if (!Number.isInteger(options.remotePort) || options.remotePort < 1 || options.remotePort > 65535) throw new Error("remotePort must be an integer in 1..65535");
+	if (options.localPort !== void 0 && (!Number.isInteger(options.localPort) || options.localPort < 1 || options.localPort > 65535)) throw new Error("localPort must be an integer in 1..65535");
+	if (engine.store.find(alias) === void 0) throw new Error("alias '" + alias + "' not found — add it first");
+	const remoteHost = options.remoteHost ?? "127.0.0.1";
+	const id = "tun-" + engine.nextTunnelId;
+	engine.nextTunnelId += 1;
+	const info = {
+		id,
+		alias,
+		localPort: 0,
+		remoteHost,
+		remotePort: options.remotePort,
+		state: "connecting",
+		startedAt: Date.now()
+	};
+	const record = await acquire(engine, alias);
+	const client = record.client;
+	const sockets = /* @__PURE__ */ new Set();
+	const server = createServer((socket) => {
+		sockets.add(socket);
+		socket.on("close", () => {
+			sockets.delete(socket);
+		});
+		client.forwardOut("127.0.0.1", 0, remoteHost, options.remotePort, (error, stream) => {
+			if (error !== void 0) {
+				socket.destroy();
+				return;
+			}
+			const destroy = () => {
+				try {
+					socket.destroy();
+				} catch {}
+				try {
+					stream.close();
+				} catch {}
+			};
+			stream.on("error", destroy);
+			socket.on("error", destroy);
+			stream.on("close", destroy);
+			socket.on("close", destroy);
+			stream.pipe(socket).pipe(stream);
+		});
+	});
+	try {
+		await new Promise((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(options.localPort ?? 0, "127.0.0.1", () => {
+				server.removeListener("error", reject);
+				resolve();
+			});
+		});
+	} catch (error) {
+		if (!record.pinned && record.inFlight === 0) disposeRecord(engine, alias, record);
+		throw error;
+	}
+	record.pinned = true;
+	const address = server.address();
+	info.localPort = typeof address === "object" && address !== null ? address.port : 0;
+	info.state = "forwarding";
+	engine.tunnels.set(id, {
+		info,
+		server,
+		alias,
+		sockets
+	});
+	return info;
+}
+/** All active tunnels. */
+function listTunnels(engine) {
+	return [...engine.tunnels.values()].map((tunnel) => ({ ...tunnel.info }));
+}
+/** Stop one tunnel (closes the listener, live sockets, and the pinned connection). */
+function stopTunnel(engine, id) {
+	const tunnel = engine.tunnels.get(id);
+	if (tunnel === void 0) return false;
+	engine.tunnels.delete(id);
+	try {
+		tunnel.server.close();
+	} catch {}
+	for (const socket of tunnel.sockets) try {
+		socket.destroy();
+	} catch {}
+	tunnel.sockets.clear();
+	disposeRecord(engine, tunnel.alias);
+	return true;
+}
+/** Stop all tunnels (optionally for one alias). */
+function stopAllTunnels(engine, alias) {
+	let count = 0;
+	for (const [id, tunnel] of [...engine.tunnels]) if (alias === void 0 || tunnel.alias === alias) {
+		stopTunnel(engine, id);
+		count += 1;
+	}
+	return count;
+}
+//#endregion
+//#region src/engine/cluster.ts
+/** Run one command against many hosts concurrently. */
+async function cluster(engine, options) {
+	let targets = engine.store.list();
+	if (options.aliases !== void 0 && options.aliases.length > 0) targets = targets.filter((entry) => options.aliases.includes(entry.alias));
+	if (options.environment !== void 0 && options.environment !== "") targets = targets.filter((entry) => entry.environment === options.environment);
+	if (options.tags !== void 0 && options.tags.length > 0) targets = targets.filter((entry) => options.tags.every((tag) => entry.tags.includes(tag)));
+	if (targets.length === 0) return [];
+	if (options.maxWorkers !== void 0 && (!Number.isInteger(options.maxWorkers) || options.maxWorkers < 1)) throw new Error("maxWorkers must be a positive integer");
+	const workers = Math.min(engine.opts.defaultMaxWorkers, options.maxWorkers ?? engine.opts.defaultMaxWorkers, targets.length);
+	const results = [];
+	const queue = [...targets];
+	const run = async () => {
+		while (queue.length > 0) {
+			const entry = queue.shift();
+			try {
+				const result = await execCommand(engine, entry.alias, options.command, options.timeoutMs);
+				results.push({
+					alias: entry.alias,
+					ok: result.success,
+					exitCode: result.exitCode,
+					timedOut: result.timedOut,
+					stdout: result.stdout,
+					stderr: result.stderr,
+					durationMs: result.durationMs
+				});
+			} catch (error) {
+				results.push({
+					alias: entry.alias,
+					ok: false,
+					error: error instanceof Error ? error.message : String(error)
+				});
+			}
+		}
+	};
+	await Promise.all(Array.from({ length: workers }, () => run()));
+	return results;
+}
+//#endregion
+//#region src/engine.ts
 /**
 * The engine. Owns the pool, tunnels, and all operations. One instance per
 * plugin apply; dispose() closes every connection.
@@ -1407,9 +2043,10 @@ var SshEngine = class {
 	store;
 	opts;
 	pool = /* @__PURE__ */ new Map();
+	acquireQueue = /* @__PURE__ */ new Map();
 	tunnels = /* @__PURE__ */ new Map();
-	sweepTimer;
 	nextTunnelId = 1;
+	sweepTimer;
 	/**
 	* @param store - the host config store.
 	* @param options - engine knobs (defaults applied).
@@ -1420,7 +2057,7 @@ var SshEngine = class {
 			...DEFAULTS,
 			...options
 		};
-		this.sweepTimer = setInterval(() => this.sweep(), Math.max(1e4, this.opts.idleTimeoutMs / 4));
+		this.sweepTimer = setInterval(() => sweepPool(this), Math.max(1e4, this.opts.idleTimeoutMs / 4));
 		this.sweepTimer.unref?.();
 	}
 	/** Secret-free host list (filtered by the optional query). */
@@ -1433,620 +2070,45 @@ var SshEngine = class {
 		const entry = this.store.find(alias);
 		return entry === void 0 ? void 0 : this.store.summarize(entry);
 	}
-	/**
-	* Run `fn` with a live client for `alias`, reconnecting (up to the
-	* attempt budget) when the connection broke mid-flight.
-	*/
-	async withClient(alias, fn, attempts = 3) {
-		let lastError;
-		for (let attempt = 1; attempt <= attempts; attempt += 1) {
-			let record = this.pool.get(alias);
-			if (record === void 0 || record.broken) {
-				if (record !== void 0) this.disposeRecord(alias, record);
-				record = await this.acquire(alias);
-			}
-			record.idleAt = Date.now();
-			record.inFlight += 1;
-			try {
-				const result = await fn(record.client);
-				record.idleAt = Date.now();
-				return result;
-			} finally {
-				record.inFlight -= 1;
-			}
-		}
-		throw lastError instanceof Error ? lastError : new Error(String(lastError));
-	}
-	/**
-	* Build one full jump chain for an entry: hop clients connected through in
-	* order, each forwarding a stream to the next destination, ending with the
-	* target client. Shared by the pool and standalone shell sessions.
-	*/
-	async connectChain(entry) {
-		const hops = [];
-		let sock;
-		const chain = entry.proxyJump;
-		for (let index = 0; index < chain.length; index += 1) {
-			const hopAlias = chain[index];
-			const hop = this.store.find(hopAlias);
-			if (hop === void 0) {
-				for (const client of hops) client.end();
-				throw new Error(`proxyJump alias '${hopAlias}' not found — create it first`);
-			}
-			const hopClient = await connectClient(buildConnectConfig(hop, sock));
-			hops.push(hopClient);
-			const next = index + 1 < chain.length ? this.store.find(chain[index + 1]) : void 0;
-			const nextHost = next !== void 0 ? next.host : entry.host;
-			const nextPort = next !== void 0 ? next.port : entry.port;
-			sock = await new Promise((resolve, reject) => {
-				hopClient.forwardOut("127.0.0.1", 0, nextHost, nextPort, (error, stream) => {
-					if (error !== void 0) {
-						for (const client of hops) client.end();
-						reject(error);
-					} else resolve(stream);
-				});
-			});
-		}
-		try {
-			return {
-				client: await connectClient(buildConnectConfig(entry, sock)),
-				hops
-			};
-		} catch (error) {
-			for (const client of hops) client.end();
-			throw error;
-		}
-	}
-	/** In-flight acquire promises, deduped per alias (concurrent first use). */
-	acquireQueue = /* @__PURE__ */ new Map();
-	/** Connect (or reuse) the pooled chain for one alias; pins nothing. */
-	async acquire(alias) {
-		const pending = this.acquireQueue.get(alias);
-		if (pending !== void 0) return pending;
-		const task = this.doAcquire(alias);
-		this.acquireQueue.set(alias, task);
-		try {
-			return await task;
-		} finally {
-			if (this.acquireQueue.get(alias) === task) this.acquireQueue.delete(alias);
-		}
-	}
-	async doAcquire(alias) {
-		const entry = this.store.find(alias);
-		if (entry === void 0) throw new Error(`alias '${alias}' not found — add it first`);
-		const { client, hops } = await this.connectChain(entry);
-		const record = {
-			client,
-			hops,
-			idleAt: Date.now(),
-			pinned: false,
-			broken: false,
-			inFlight: 0
-		};
-		client.on("error", () => {
-			record.broken = true;
-		});
-		client.on("close", () => {
-			record.broken = true;
-		});
-		this.pool.set(alias, record);
-		return record;
-	}
-	/**
-	* Tear down one alias's record. When `record` is given and no longer the
-	* pooled record for the alias (a concurrent acquire replaced it), nothing
-	* is torn down — the connection belongs to someone else now.
-	*/
-	disposeRecord(alias, record) {
-		const current = this.pool.get(alias);
-		if (record !== void 0 && current !== record) return;
-		if (current === void 0) return;
-		this.pool.delete(alias);
-		try {
-			current.client.end();
-		} catch {}
-		for (const hop of current.hops) try {
-			hop.end();
-		} catch {}
-	}
-	/** Close connections idle beyond the threshold (skips pinned and in-flight). */
-	sweep() {
-		const cutoff = Date.now() - this.opts.idleTimeoutMs;
-		for (const [alias, record] of this.pool) if (!record.pinned && record.inFlight === 0 && record.idleAt < cutoff) this.disposeRecord(alias, record);
-	}
 	/** Run one command on `alias` (reusing the pooled connection). */
 	async exec(alias, command, timeoutMs) {
-		const started = Date.now();
-		const budget = timeoutMs !== void 0 && timeoutMs > 0 ? timeoutMs : this.opts.defaultExecTimeoutMs;
-		return this.withClient(alias, async (client) => {
-			return await new Promise((resolve, reject) => {
-				client.exec(command, (error, stream) => {
-					if (error !== void 0) {
-						reject(error);
-						return;
-					}
-					const stdout = {
-						text: "",
-						truncated: false
-					};
-					const stderr = {
-						text: "",
-						truncated: false
-					};
-					let timedOut = false;
-					let settled = false;
-					const finish = () => {
-						if (settled) return;
-						settled = true;
-						clearTimeout(timer);
-						resolve({
-							success: false,
-							exitCode: null,
-							timedOut,
-							stdout: stdout.text,
-							stderr: stderr.text,
-							durationMs: Date.now() - started,
-							error: timedOut ? `command timed out after ${budget} ms` : void 0
-						});
-					};
-					const timer = setTimeout(() => {
-						timedOut = true;
-						try {
-							stream.signal("KILL");
-						} catch {}
-						try {
-							stream.close();
-						} catch {}
-						finish();
-					}, budget);
-					stream.on("data", (chunk) => appendOutput(stdout, chunk, this.opts.maxOutputBytes));
-					stream.stderr.on("data", (chunk) => appendOutput(stderr, chunk, this.opts.maxOutputBytes));
-					stream.on("close", (code) => {
-						if (settled) return;
-						settled = true;
-						clearTimeout(timer);
-						resolve({
-							success: code === 0 && !timedOut,
-							exitCode: code,
-							timedOut,
-							stdout: stdout.text,
-							stderr: stderr.text,
-							durationMs: Date.now() - started
-						});
-					});
-					stream.on("error", (streamError) => {
-						if (settled) return;
-						settled = true;
-						clearTimeout(timer);
-						reject(streamError);
-					});
-				});
-			});
-		});
+		return execCommand(this, alias, command, timeoutMs);
 	}
 	/** Run one command against many hosts concurrently. */
 	async cluster(options) {
-		let targets = this.store.list();
-		if (options.aliases !== void 0 && options.aliases.length > 0) targets = targets.filter((entry) => options.aliases.includes(entry.alias));
-		if (options.environment !== void 0 && options.environment !== "") targets = targets.filter((entry) => entry.environment === options.environment);
-		if (options.tags !== void 0 && options.tags.length > 0) targets = targets.filter((entry) => options.tags.every((tag) => entry.tags.includes(tag)));
-		if (targets.length === 0) return [];
-		if (options.maxWorkers !== void 0 && (!Number.isInteger(options.maxWorkers) || options.maxWorkers < 1)) throw new Error("maxWorkers must be a positive integer");
-		const workers = Math.min(this.opts.defaultMaxWorkers, options.maxWorkers ?? this.opts.defaultMaxWorkers, targets.length);
-		const results = [];
-		const queue = [...targets];
-		const run = async () => {
-			while (queue.length > 0) {
-				const entry = queue.shift();
-				try {
-					const result = await this.exec(entry.alias, options.command, options.timeoutMs);
-					results.push({
-						alias: entry.alias,
-						ok: result.success,
-						exitCode: result.exitCode,
-						timedOut: result.timedOut,
-						stdout: result.stdout,
-						stderr: result.stderr,
-						durationMs: result.durationMs
-					});
-				} catch (error) {
-					results.push({
-						alias: entry.alias,
-						ok: false,
-						error: error instanceof Error ? error.message : String(error)
-					});
-				}
-			}
-		};
-		await Promise.all(Array.from({ length: workers }, () => run()));
-		return results;
+		return cluster(this, options);
 	}
 	/** Open a PTY shell session for the web terminal (standalone connection). */
 	async openShell(alias, size) {
-		const entry = this.store.find(alias);
-		if (entry === void 0) throw new Error(`alias '${alias}' not found — add it first`);
-		const { client, hops } = await this.connectChain(entry);
-		return await new Promise((resolve, reject) => {
-			client.shell({
-				term: "xterm-256color",
-				cols: size.cols,
-				rows: size.rows
-			}, (error, stream) => {
-				if (error !== void 0) {
-					try {
-						client.end();
-					} catch {}
-					for (const hop of hops) try {
-						hop.end();
-					} catch {}
-					reject(error);
-					return;
-				}
-				let tornDown = false;
-				const teardown = () => {
-					if (tornDown) return;
-					tornDown = true;
-					try {
-						client.end();
-					} catch {}
-					for (const hop of hops) try {
-						hop.end();
-					} catch {}
-				};
-				const session = {
-					send: (data) => {
-						try {
-							stream.write(data);
-						} catch {}
-					},
-					resize: (cols, rows) => {
-						try {
-							stream.setWindow(rows, cols, rows, cols);
-						} catch {}
-					},
-					close: () => {
-						try {
-							stream.close();
-						} catch {}
-						teardown();
-					},
-					pause: () => {
-						try {
-							stream.pause();
-						} catch {}
-					},
-					resume: () => {
-						try {
-							stream.resume();
-						} catch {}
-					}
-				};
-				stream.on("data", (chunk) => {
-					session.onData?.(chunk);
-				});
-				stream.on("close", (code) => {
-					teardown();
-					session.onExit?.(code);
-				});
-				stream.on("error", (streamError) => {
-					teardown();
-					session.onExit?.(null, streamError instanceof Error ? streamError.message : String(streamError));
-				});
-				resolve(session);
-			});
-		});
+		return openShell(this, alias, size);
 	}
 	/** Upload one local file (or directory tree) to a remote path. */
 	async upload(alias, localPath, remotePath, recursive, onProgress) {
-		if (!remotePath.startsWith("/")) throw new Error(`remotePath must be an absolute path (got '${remotePath}')`);
-		const local = resolve(localPath);
-		if (!existsSync(local)) throw new Error(`local path not found: '${localPath}'`);
-		return this.withClient(alias, (client) => this.withSftp(client, async (sftp) => {
-			const stat = statSync(local);
-			let files;
-			if (stat.isDirectory()) {
-				if (!recursive) throw new Error(`'${localPath}' is a directory — enable recursive upload`);
-				files = walkLocalDir(local);
-				await this.ensureRemoteDir(sftp, remotePath);
-			} else {
-				files = [""];
-				await this.ensureRemoteDir(sftp, dirname(remotePath));
-			}
-			let bytes = 0;
-			for (const rel of files) {
-				const src = rel === "" ? local : join(local, rel);
-				const remoteRel = rel.split(/[\\/]/).join("/");
-				const dst = rel === "" ? remotePath : remotePath.replace(/\/$/, "") + "/" + remoteRel;
-				await this.fastPut(sftp, src, dst, onProgress);
-				bytes += statSync(src).size;
-			}
-			return {
-				bytes,
-				files: files.length
-			};
-		}));
+		return upload(this, alias, localPath, remotePath, recursive, onProgress);
 	}
 	/** Download one remote file to a local path. */
 	async download(alias, remotePath, localPath, onProgress) {
-		return this.withClient(alias, (client) => this.withSftp(client, async (sftp) => {
-			if ((await new Promise((resolve, reject) => {
-				sftp.stat(remotePath, (error, stats) => error !== void 0 ? reject(error) : resolve(stats));
-			})).isDirectory()) throw new Error(`'${remotePath}' is a directory — directory download is not supported yet (download individual files)`);
-			const local = resolve(localPath);
-			if (!existsSync(dirname(local))) mkdirSync(dirname(local), { recursive: true });
-			await this.fastGet(sftp, remotePath, local, onProgress);
-			return { bytes: statSync(local).size };
-		}));
+		return download(this, alias, remotePath, localPath, onProgress);
 	}
 	/** List a remote directory (file browser). */
 	async ls(alias, path) {
-		return this.withClient(alias, (client) => this.withSftp(client, async (sftp) => {
-			return await new Promise((resolve, reject) => {
-				sftp.readdir(path, (error, list) => {
-					if (error !== void 0) {
-						reject(error);
-						return;
-					}
-					resolve(list.map((item) => ({
-						name: item.filename,
-						type: item.attrs.isDirectory() ? "dir" : item.attrs.isFile() ? "file" : "other",
-						size: item.attrs.size,
-						mtimeMs: item.attrs.mtime * 1e3,
-						mode: item.attrs.mode
-					})));
-				});
-			});
-		}));
-	}
-	/**
-	* Open one SFTP channel, run the operation, and release the channel exactly
-	* once when the operation settles (success or error). ssh2 keeps each
-	* subsystem channel open until end(); without this, every transfer leaks a
-	* channel until sshd's MaxSessions cap makes all later opens fail.
-	*/
-	async withSftp(client, run) {
-		const sftp = await this.sftp(client);
-		let ended = false;
-		const endOnce = () => {
-			if (ended) return;
-			ended = true;
-			try {
-				sftp.end();
-			} catch {}
-		};
-		sftp.once("close", endOnce);
-		try {
-			return await run(sftp);
-		} finally {
-			endOnce();
-		}
-	}
-	sftp(client) {
-		return new Promise((resolve, reject) => {
-			client.sftp((error, sftp) => error !== void 0 ? reject(error) : resolve(sftp));
-		});
-	}
-	/** Create a remote directory chain (stat-then-mkdir per segment). */
-	ensureRemoteDir(sftp, remote) {
-		return new Promise((resolve, reject) => {
-			const segments = remote.replace(/^\/+/, "").split("/").filter((segment) => segment !== "");
-			const walk = (index) => {
-				if (index >= segments.length) {
-					resolve();
-					return;
-				}
-				const current = "/" + segments.slice(0, index + 1).join("/");
-				sftp.stat(current, (statError) => {
-					if (statError === void 0) {
-						walk(index + 1);
-						return;
-					}
-					sftp.mkdir(current, (mkdirError) => {
-						if (mkdirError !== void 0) {
-							reject(mkdirError);
-							return;
-						}
-						walk(index + 1);
-					});
-				});
-			};
-			walk(0);
-		});
-	}
-	fastPut(sftp, src, dst, onProgress) {
-		return new Promise((resolve, reject) => {
-			let last = 0;
-			let lastEmit = 0;
-			const started = Date.now();
-			onProgress?.({
-				phase: "transferring",
-				file: dst,
-				transferred: 0,
-				total: statSync(src).size,
-				percent: 0
-			});
-			sftp.fastPut(src, dst, {
-				concurrency: this.opts.sftpConcurrency,
-				step: (transferred, _chunk, total) => {
-					const now = Date.now();
-					if (now - lastEmit < 100 && transferred < total) return;
-					lastEmit = now;
-					const elapsed = (now - started) / 1e3;
-					onProgress?.({
-						phase: "transferring",
-						file: dst,
-						transferred,
-						total,
-						percent: total > 0 ? Math.round(transferred / total * 1e3) / 10 : 0,
-						speedBps: elapsed > 0 ? Math.round((transferred - last) / elapsed) : void 0
-					});
-					last = transferred;
-				}
-			}, (error) => {
-				if (error !== void 0) {
-					onProgress?.({
-						phase: "error",
-						file: dst,
-						transferred: 0,
-						total: 0,
-						percent: 0,
-						error: String(error)
-					});
-					reject(error);
-				} else {
-					onProgress?.({
-						phase: "done",
-						file: dst,
-						transferred: statSync(src).size,
-						total: statSync(src).size,
-						percent: 100
-					});
-					resolve();
-				}
-			});
-		});
-	}
-	fastGet(sftp, src, dst, onProgress) {
-		return new Promise((resolve, reject) => {
-			let last = 0;
-			let lastEmit = 0;
-			const started = Date.now();
-			sftp.fastGet(src, dst, {
-				concurrency: this.opts.sftpConcurrency,
-				step: (transferred, _chunk, total) => {
-					const now = Date.now();
-					if (now - lastEmit < 100 && transferred < total) return;
-					lastEmit = now;
-					const elapsed = (now - started) / 1e3;
-					onProgress?.({
-						phase: "transferring",
-						file: src,
-						transferred,
-						total,
-						percent: total > 0 ? Math.round(transferred / total * 1e3) / 10 : 0,
-						speedBps: elapsed > 0 ? Math.round((transferred - last) / elapsed) : void 0
-					});
-					last = transferred;
-				}
-			}, (error) => {
-				if (error !== void 0) {
-					onProgress?.({
-						phase: "error",
-						file: src,
-						transferred: 0,
-						total: 0,
-						percent: 0,
-						error: String(error)
-					});
-					reject(error);
-				} else {
-					onProgress?.({
-						phase: "done",
-						file: src,
-						transferred: statSync(dst).size,
-						total: statSync(dst).size,
-						percent: 100
-					});
-					resolve();
-				}
-			});
-		});
+		return ls(this, alias, path);
 	}
 	/** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
 	async startTunnel(alias, options) {
-		if (!Number.isInteger(options.remotePort) || options.remotePort < 1 || options.remotePort > 65535) throw new Error("remotePort must be an integer in 1..65535");
-		if (options.localPort !== void 0 && (!Number.isInteger(options.localPort) || options.localPort < 1 || options.localPort > 65535)) throw new Error("localPort must be an integer in 1..65535");
-		if (this.store.find(alias) === void 0) throw new Error(`alias '${alias}' not found — add it first`);
-		const remoteHost = options.remoteHost ?? "127.0.0.1";
-		const id = `tun-${this.nextTunnelId++}`;
-		const info = {
-			id,
-			alias,
-			localPort: 0,
-			remoteHost,
-			remotePort: options.remotePort,
-			state: "connecting",
-			startedAt: Date.now()
-		};
-		const record = await this.acquire(alias);
-		const client = record.client;
-		const sockets = /* @__PURE__ */ new Set();
-		const server = createServer((socket) => {
-			sockets.add(socket);
-			socket.on("close", () => {
-				sockets.delete(socket);
-			});
-			client.forwardOut("127.0.0.1", 0, remoteHost, options.remotePort, (error, stream) => {
-				if (error !== void 0) {
-					socket.destroy();
-					return;
-				}
-				const destroy = () => {
-					try {
-						socket.destroy();
-					} catch {}
-					try {
-						stream.close();
-					} catch {}
-				};
-				stream.on("error", destroy);
-				socket.on("error", destroy);
-				stream.on("close", destroy);
-				socket.on("close", destroy);
-				stream.pipe(socket).pipe(stream);
-			});
-		});
-		try {
-			await new Promise((resolve, reject) => {
-				server.once("error", reject);
-				server.listen(options.localPort ?? 0, "127.0.0.1", () => {
-					server.removeListener("error", reject);
-					resolve();
-				});
-			});
-		} catch (error) {
-			if (!record.pinned && record.inFlight === 0) this.disposeRecord(alias, record);
-			throw error;
-		}
-		record.pinned = true;
-		const address = server.address();
-		info.localPort = typeof address === "object" && address !== null ? address.port : 0;
-		info.state = "forwarding";
-		this.tunnels.set(id, {
-			info,
-			server,
-			alias,
-			sockets
-		});
-		return info;
+		return startTunnel(this, alias, options);
 	}
 	/** All active tunnels. */
 	listTunnels() {
-		return [...this.tunnels.values()].map((tunnel) => ({ ...tunnel.info }));
+		return listTunnels(this);
 	}
 	/** Stop one tunnel (closes the listener, live sockets, and the pinned connection). */
 	stopTunnel(id) {
-		const tunnel = this.tunnels.get(id);
-		if (tunnel === void 0) return false;
-		this.tunnels.delete(id);
-		try {
-			tunnel.server.close();
-		} catch {}
-		for (const socket of tunnel.sockets) try {
-			socket.destroy();
-		} catch {}
-		tunnel.sockets.clear();
-		this.disposeRecord(tunnel.alias);
-		return true;
+		return stopTunnel(this, id);
 	}
 	/** Stop all tunnels (optionally for one alias). */
 	stopAllTunnels(alias) {
-		let count = 0;
-		for (const [id, tunnel] of [...this.tunnels]) if (alias === void 0 || tunnel.alias === alias) {
-			this.stopTunnel(id);
-			count += 1;
-		}
-		return count;
+		return stopAllTunnels(this, alias);
 	}
 	/** Probe connectivity: connect, run `true`, close. */
 	async test(alias) {
@@ -2059,7 +2121,7 @@ var SshEngine = class {
 			} : {
 				ok: false,
 				latencyMs: result.durationMs,
-				error: `remote exit code ${result.exitCode}`
+				error: "remote exit code " + result.exitCode
 			};
 		} catch (error) {
 			return {
@@ -2072,8 +2134,8 @@ var SshEngine = class {
 	/** Close every pooled connection and tunnel. */
 	dispose() {
 		if (this.sweepTimer !== void 0) clearInterval(this.sweepTimer);
-		for (const id of [...this.tunnels.keys()]) this.stopTunnel(id);
-		for (const alias of [...this.pool.keys()]) this.disposeRecord(alias);
+		for (const id of [...this.tunnels.keys()]) stopTunnel(this, id);
+		for (const alias of [...this.pool.keys()]) disposeRecord(this, alias);
 	}
 };
 //#endregion