@linxin666/dsh-ssh 0.3.19 → 0.3.21

package/lib/index.js

@@ -1,8 +1,10 @@
-import { closeSync, createReadStream, createWriteStream, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, createReadStream, createWriteStream, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { Client } from "ssh2";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { isAbsolute as isAbsolute$1, join as join$1 } from "node:path/posix";
+import { spawn } from "node:child_process";
+import { Duplex } from "node:stream";
 import { createServer } from "node:net";
 import { unlink } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
@@ -1058,6 +1060,136 @@ function dshHome() {
 	return resolveDshHome();
 }
 //#endregion
+//#region src/ssh-config.ts
+/**
+* Minimal `~/.ssh/config` reader for the one-shot host import: Host blocks with
+* `Include` expansion and explicit skip reasons. Values stay raw strings; the
+* store maps them onto a HostPayload.
+*
+* Deliberate simplifications (documented in the package README):
+*   - `Match` blocks are skipped — their options are conditional and must never
+*     merge into the Host block above them.
+*   - A multi-pattern `Host a b` line only exposes its first pattern.
+*   - Include pathnames accept `~`, globs, and several whitespace-separated
+*     pathnames, but not environment variables, `%` tokens, or quoting.
+*   - Relative Include pathnames resolve against the directory of the config
+*     file the import started from (OpenSSH: `~/.ssh` for a user config).
+*   - A file that already contributed lines is never read twice, which doubles
+*     as the Include cycle guard.
+*/
+/** Include recursion guard: a cycle or a runaway chain stops here. */
+const MAX_INCLUDE_DEPTH = 16;
+/** The only line shape ssh_config knows: `Keyword value...` (case-insensitive). */
+const LINE_RE = /^([A-Za-z0-9_-]+)\s+(.+)$/;
+/** Expand a leading `~` the way OpenSSH does for user configuration files. */
+function expandTilde(path) {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+	return path;
+}
+/** Turn one glob segment into a matcher (`*` and `?` only). */
+function segmentMatcher(segment) {
+	const escaped = segment.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	return new RegExp("^" + escaped.replace(/\*/g, ".*").replace(/\?/g, ".") + "$");
+}
+/**
+* Expand a segment list against the filesystem. Wildcards match whole segments
+* only; matches are sorted so a glob import stays deterministic.
+*/
+function globSegments(prefix, segments) {
+	const [head, ...rest] = segments;
+	if (head === void 0) return [prefix];
+	if (!/[*?]/.test(head)) return globSegments(join(prefix, head), rest);
+	let names;
+	try {
+		names = readdirSync(prefix);
+	} catch {
+		return [];
+	}
+	const matcher = segmentMatcher(head);
+	return names.filter((name) => matcher.test(name)).sort().flatMap((name) => globSegments(join(prefix, name), rest));
+}
+/** Resolve one Include pathname into the existing regular files it names. */
+function resolveInclude(spec, baseDir) {
+	const expanded = expandTilde(spec);
+	const full = isAbsolute(expanded) ? expanded : join(baseDir, expanded);
+	if (!/[*?]/.test(full)) return existsSync(full) ? [full] : [];
+	const root = /^([A-Za-z]:[\\/]|[\\/])/.exec(full)?.[1] ?? "";
+	const segments = full.slice(root.length).split(/[\\/]+/).filter((part) => part !== "");
+	return globSegments(root === "" ? "." : root, segments).filter((path) => {
+		try {
+			return statSync(path).isFile();
+		} catch {
+			return false;
+		}
+	});
+}
+/** Read one file into lines, splicing every `Include` in place. */
+function readLines(file, baseDir, visited, depth) {
+	if (depth > MAX_INCLUDE_DEPTH) return [];
+	let key;
+	try {
+		key = realpathSync(file);
+	} catch {
+		return [];
+	}
+	if (visited.has(key)) return [];
+	visited.add(key);
+	let text;
+	try {
+		text = readFileSync(key, "utf8");
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const raw of text.split(/\r?\n/)) {
+		const match = LINE_RE.exec(raw.trim());
+		if (match === null || match[1].toLowerCase() !== "include") {
+			out.push(raw);
+			continue;
+		}
+		for (const spec of match[2].trim().split(/\s+/).filter((part) => part !== "")) for (const included of resolveInclude(spec, baseDir)) out.push(...readLines(included, baseDir, visited, depth + 1));
+	}
+	return out;
+}
+/**
+* Parse one ssh_config file (Include expanded) into Host blocks plus the
+* `Match` blocks that were deliberately skipped.
+*/
+function readSshConfigBlocks(configPath) {
+	const blocks = [];
+	const skipped = [];
+	const lines = readLines(configPath, dirname(configPath), /* @__PURE__ */ new Set(), 0);
+	let current;
+	for (const raw of lines) {
+		const match = LINE_RE.exec(raw.trim());
+		if (match === null) continue;
+		const key = match[1].toLowerCase();
+		const value = match[2].trim();
+		if (key === "host") {
+			current = {
+				pattern: value,
+				props: {}
+			};
+			blocks.push(current);
+			continue;
+		}
+		if (key === "match") {
+			skipped.push({
+				name: "Match " + value,
+				reason: "match"
+			});
+			current = void 0;
+			continue;
+		}
+		if (current !== void 0) current.props[key] = value;
+	}
+	return {
+		blocks,
+		skipped
+	};
+}
+//#endregion
 //#region src/store.ts
 /**
 * Host config store: one JSON file (`$DSH_HOME/dsh-ssh.json`, defaulting
@@ -1093,6 +1225,10 @@ function validateHostPayload(payload) {
 	}
 	if (p.port !== void 0 && (typeof p.port !== "number" || !Number.isInteger(p.port) || p.port < 1 || p.port > 65535)) return "port must be an integer in 1..65535";
 	if (p.proxyJump !== void 0 && (!Array.isArray(p.proxyJump) || p.proxyJump.some((x) => typeof x !== "string" || x === ""))) return "proxyJump must be an array of alias strings";
+	if (p.proxyCommand !== void 0 && typeof p.proxyCommand !== "string") return "proxyCommand must be a string when provided";
+	const proxyCommand = typeof p.proxyCommand === "string" ? normalizeProxyCommand(p.proxyCommand) : void 0;
+	const proxyJump = Array.isArray(p.proxyJump) ? p.proxyJump : [];
+	if (proxyCommand !== void 0 && proxyJump.length > 0) return "proxyCommand and proxyJump cannot be combined — pick one transport per host";
 	if (p.tags !== void 0 && (!Array.isArray(p.tags) || p.tags.some((x) => typeof x !== "string"))) return "tags must be an array of strings";
 }
 /** Alias grammar: letters/digits plus dots, hyphens, underscores (IP/domain aliases included). */
@@ -1138,6 +1274,7 @@ var HostStore = class {
 			auth: entry.auth.kind,
 			keyReady,
 			proxyJump: [...entry.proxyJump],
+			...entry.proxyCommand !== void 0 ? { proxyCommand: entry.proxyCommand } : {},
 			...entry.description !== void 0 ? { description: entry.description } : {},
 			...entry.environment !== void 0 ? { environment: entry.environment } : {},
 			tags: [...entry.tags],
@@ -1171,6 +1308,7 @@ var HostStore = class {
 				agentPath: payload.auth.kind === "agent" ? normalizeAgentPath(payload.auth.agentPath) : void 0
 			},
 			proxyJump: [...payload.proxyJump ?? []],
+			proxyCommand: normalizeProxyCommand(payload.proxyCommand),
 			description: payload.description?.trim() || void 0,
 			environment: payload.environment?.trim() || void 0,
 			tags: [...payload.tags ?? []].map((tag) => tag.trim()).filter((tag) => tag !== ""),
@@ -1191,6 +1329,9 @@ var HostStore = class {
 		if (patch.user !== void 0 && (typeof patch.user !== "string" || patch.user.trim() === "")) throw new Error("user is required");
 		if (patch.port !== void 0 && (typeof patch.port !== "number" || !Number.isInteger(patch.port) || patch.port < 1 || patch.port > 65535)) throw new Error("port must be an integer in 1..65535");
 		if (patch.proxyJump !== void 0 && (!Array.isArray(patch.proxyJump) || patch.proxyJump.some((x) => typeof x !== "string" || x === ""))) throw new Error("proxyJump must be an array of alias strings");
+		if (patch.proxyCommand !== void 0 && typeof patch.proxyCommand !== "string") throw new Error("proxyCommand must be a string when provided");
+		const mergedProxyCommand = patch.proxyCommand !== void 0 ? normalizeProxyCommand(patch.proxyCommand) : entry.proxyCommand;
+		if (mergedProxyCommand !== void 0 && (patch.proxyJump ?? entry.proxyJump).length > 0) throw new Error("proxyCommand and proxyJump cannot be combined — pick one transport per host");
 		if (patch.tags !== void 0 && (!Array.isArray(patch.tags) || patch.tags.some((x) => typeof x !== "string"))) throw new Error("tags must be an array of strings");
 		if (patch.host !== void 0) entry.host = patch.host.trim();
 		if (patch.port !== void 0) entry.port = patch.port;
@@ -1211,6 +1352,7 @@ var HostStore = class {
 			};
 		}
 		if (patch.proxyJump !== void 0) entry.proxyJump = [...patch.proxyJump];
+		if (patch.proxyCommand !== void 0) entry.proxyCommand = mergedProxyCommand;
 		if (patch.description !== void 0) entry.description = patch.description.trim() || void 0;
 		if (patch.environment !== void 0) entry.environment = patch.environment.trim() || void 0;
 		if (patch.tags !== void 0) entry.tags = [...patch.tags].map((tag) => tag.trim()).filter((tag) => tag !== "");
@@ -1229,62 +1371,46 @@ var HostStore = class {
 	}
 	/**
 	* Import hosts from `~/.ssh/config`: Host blocks with a single non-wildcard
-	* pattern and a HostName become entries (key auth via IdentityFile, jump
-	* hosts via ProxyJump). Existing aliases are skipped.
+	* pattern become entries (a missing HostName falls back to the pattern
+	* itself; key auth via IdentityFile; jump hosts via ProxyJump; ProxyCommand
+	* kept verbatim). `Include` files are expanded, and `Match` blocks,
+	* wildcard patterns, and aliases that already exist are skipped with a
+	* reason instead of silently disappearing.
 	* @returns import statistics.
 	*/
 	importFromSshConfig() {
-		this.skippedNames = /* @__PURE__ */ new Set();
+		this.skippedBlocks = [];
 		const configPath = this.sshConfigOverride ?? sshConfigPath();
 		if (!existsSync(configPath)) return {
 			parsed: 0,
 			added: 0,
 			skipped: 0,
-			skippedNames: []
+			skippedBlocks: []
 		};
-		const lines = readFileSync(configPath, "utf8").split(/\r?\n/);
-		const blocks = [];
-		let current;
-		const skip = (name, seen) => {
-			if (name !== "" && !seen.has(name)) {
-				seen.add(name);
-				this.skippedNames.add(name);
-			}
+		const { blocks, skipped } = readSshConfigBlocks(configPath);
+		this.skippedBlocks = [...skipped];
+		const skip = (name, reason) => {
+			if (name === "") return;
+			if (this.skippedBlocks.some((block) => block.name === name)) return;
+			this.skippedBlocks.push({
+				name,
+				reason
+			});
 		};
-		for (const raw of lines) {
-			const line = raw.trim();
-			if (line === "" || line.startsWith("#")) continue;
-			const match = /^([A-Za-z0-9_\-]+)\s+(.+)$/.exec(line);
-			if (match === null) continue;
-			const key = match[1].toLowerCase();
-			const value = match[2].trim();
-			if (key === "host") {
-				current = {
-					pattern: value,
-					props: {}
-				};
-				blocks.push(current);
-			} else if (current !== void 0) current.props[key] = value;
-		}
 		let added = 0;
 		for (const block of blocks) {
 			const pattern = block.pattern.split(/\s+/)[0];
 			if (pattern.includes("*") || pattern.includes("?")) {
-				skip(pattern, this.skippedNames);
-				continue;
-			}
-			const hostName = block.props.hostname;
-			if (hostName === void 0 || hostName === "") {
-				skip(pattern, this.skippedNames);
+				skip(pattern, "wildcard");
 				continue;
 			}
 			if (this.list().some((entry) => entry.alias === pattern)) {
-				skip(pattern, this.skippedNames);
+				skip(pattern, "existing");
 				continue;
 			}
 			const payload = {
 				alias: pattern,
-				host: hostName,
+				host: block.props.hostname !== void 0 && block.props.hostname !== "" ? block.props.hostname : pattern,
 				port: block.props.port !== void 0 ? Number.parseInt(block.props.port, 10) : 22,
 				user: block.props.user ?? process.env.USER ?? "root",
 				auth: {
@@ -1294,6 +1420,7 @@ var HostStore = class {
 					agentPath: block.props.identityagent !== void 0 && block.props.identityagent.toLowerCase() !== "none" ? normalizeAgentPath(block.props.identityagent) : void 0
 				},
 				proxyJump: block.props.proxyjump !== void 0 ? block.props.proxyjump.split(",").map((hop) => hop.trim()).filter((hop) => hop !== "") : [],
+				proxyCommand: block.props.proxycommand,
 				description: block.props.description,
 				environment: block.props.environment,
 				tags: (block.props.tags ?? "").split(",").map((tag) => tag.trim()).filter((tag) => tag !== ""),
@@ -1303,17 +1430,17 @@ var HostStore = class {
 				this.create(payload);
 				added += 1;
 			} catch {
-				skip(pattern, this.skippedNames);
+				skip(pattern, "invalid");
 			}
 		}
 		return {
 			parsed: blocks.length,
 			added,
-			skipped: this.skippedNames.size,
-			skippedNames: [...this.skippedNames]
+			skipped: this.skippedBlocks.length,
+			skippedBlocks: [...this.skippedBlocks]
 		};
 	}
-	skippedNames = /* @__PURE__ */ new Set();
+	skippedBlocks = [];
 	/**
 	* Last parsed store keyed by file identity. list/find ride every acquire
 	* and GUI refresh; re-reading and re-parsing the whole file each call is
@@ -1377,6 +1504,16 @@ function normalizeAgentPath(agentPath) {
 	}
 	return expandHome(trimmed);
 }
+/**
+* Normalize a ProxyCommand for storage: trim, and treat an empty value or
+* OpenSSH's `none` keyword as "no proxy command" (an explicit clear).
+*/
+function normalizeProxyCommand(raw) {
+	const trimmed = raw?.trim();
+	if (trimmed === void 0 || trimmed === "") return void 0;
+	if (trimmed.toLowerCase() === "none") return void 0;
+	return trimmed;
+}
 /** Expand a leading `~` in a filesystem path. */
 function expandHome(path) {
 	if (path === "~") return homedir();
@@ -1384,6 +1521,207 @@ function expandHome(path) {
 	return path;
 }
 //#endregion
+//#region src/engine/proxy-command.ts
+/**
+* OpenSSH-compatible ProxyCommand transport: run the command with the user's
+* shell and expose its stdio as a Duplex that ssh2 accepts as `sock`.
+*
+* The command comes verbatim from the user's own 0600 store file and runs with
+* the DSH host process's privileges — the same trust the `ssh(1)` client gives
+* the identical line in `~/.ssh/config`.
+*/
+/** How long a killed proxy command may linger before SIGKILL (ms). */
+const KILL_GRACE_MS = 2e3;
+/** Expand the OpenSSH ProxyCommand tokens; unknown %X sequences stay verbatim. */
+function expandProxyTokens(command, target) {
+	return command.replace(/%[hprn%]/g, (token) => {
+		switch (token) {
+			case "%h": return target.host;
+			case "%p": return String(target.port);
+			case "%r": return target.user;
+			case "%n": return target.alias;
+			default: return "%";
+		}
+	});
+}
+/**
+* The shell OpenSSH itself would use on this platform: the user's shell with
+* `-c` on POSIX, cmd.exe on Windows (where the whole command must stay one
+* verbatim argument, exactly as Node's own `shell: true` does it).
+*/
+function spawnSpec(command) {
+	if (process.platform === "win32") return {
+		file: process.env.ComSpec ?? "cmd.exe",
+		args: [
+			"/d",
+			"/s",
+			"/c",
+			"\"" + command + "\""
+		],
+		windowsVerbatimArguments: true
+	};
+	return {
+		file: process.env.SHELL ?? "/bin/sh",
+		args: ["-c", command]
+	};
+}
+/**
+* Start one ProxyCommand and bridge its stdio into a Duplex.
+*
+* Failure modes are reported through the stream: a spawn error, or an exit
+* before the SSH handshake finished, destroys it with the exit status and the
+* tail of the command's stderr instead of letting ssh2 wait for its own
+* `readyTimeout`.
+*/
+function startProxyCommand(rawCommand, target) {
+	const spec = spawnSpec(expandProxyTokens(rawCommand, target));
+	const child = spawn(spec.file, spec.args, {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true,
+		...spec.windowsVerbatimArguments === true ? { windowsVerbatimArguments: true } : {},
+		...process.platform === "win32" ? {} : { detached: true }
+	});
+	let stderr = "";
+	child.stderr?.on("data", (chunk) => {
+		stderr = (stderr + chunk.toString("utf8")).slice(-4096);
+	});
+	let killed = false;
+	const kill = () => {
+		if (killed) return;
+		killed = true;
+		const pid = child.pid;
+		const group = process.platform !== "win32" && pid !== void 0;
+		try {
+			if (group) process.kill(-pid, "SIGTERM");
+			else child.kill();
+		} catch {}
+		setTimeout(() => {
+			try {
+				if (group) process.kill(-pid, "SIGKILL");
+				else child.kill("SIGKILL");
+			} catch {}
+		}, KILL_GRACE_MS).unref();
+	};
+	function formatExitError(code, signal, stderrDetail) {
+		const status = signal !== null ? "signal " + signal : "code " + String(code ?? "unknown");
+		const detail = stderrDetail.trim();
+		return /* @__PURE__ */ new Error("ProxyCommand exited (" + status + ")" + (detail === "" ? "" : ": " + detail));
+	}
+	const stream = new Duplex({
+		read() {
+			child.stdout?.resume();
+		},
+		write(chunk, _encoding, callback) {
+			const stdin = child.stdin;
+			if (stream.destroyed || stdin === null || stdin.destroyed) {
+				callback(/* @__PURE__ */ new Error("ProxyCommand stdin is already closed"));
+				return;
+			}
+			stdin.write(chunk, (err) => {
+				if (!err) {
+					callback();
+					return;
+				}
+				if (child.exitCode !== null && child.exitCode !== 0 || child.signalCode !== null) {
+					const exitErr = formatExitError(child.exitCode, child.signalCode, stderr);
+					fail(exitErr);
+					callback(exitErr);
+					return;
+				}
+				let resolved = false;
+				const onExit = (code, signal) => {
+					if (resolved) return;
+					resolved = true;
+					clearTimeout(timer);
+					const exitErr = code !== null && code !== 0 || signal !== null ? formatExitError(code, signal, stderr) : /* @__PURE__ */ new Error("ProxyCommand transport write failed: " + err.message);
+					fail(exitErr);
+					callback(exitErr);
+				};
+				const timer = setTimeout(() => {
+					if (resolved) return;
+					resolved = true;
+					child.removeListener("exit", onExit);
+					const transportErr = /* @__PURE__ */ new Error("ProxyCommand transport write failed: " + err.message);
+					fail(transportErr);
+					callback(transportErr);
+				}, 200);
+				timer.unref();
+				child.once("exit", onExit);
+			});
+		},
+		final(callback) {
+			const stdin = child.stdin;
+			if (stdin === null || stdin.destroyed) {
+				callback();
+				return;
+			}
+			stdin.end((err) => {
+				if (err) callback(/* @__PURE__ */ new Error("ProxyCommand transport close failed: " + err.message));
+				else callback();
+			});
+		},
+		destroy(error, callback) {
+			kill();
+			callback(error);
+		}
+	});
+	stream.on("error", () => {});
+	let failed = false;
+	const fail = (error) => {
+		if (failed || stream.destroyed) return;
+		failed = true;
+		stream.destroy(error);
+	};
+	let stdoutEnded = false;
+	let exited = false;
+	const finishIfClean = () => {
+		if (exited && stdoutEnded && !failed && !stream.destroyed) stream.push(null);
+	};
+	child.stdout?.on("data", (chunk) => {
+		if (stream.push(chunk) === false) child.stdout?.pause();
+	});
+	child.stdout?.on("end", () => {
+		stdoutEnded = true;
+		finishIfClean();
+	});
+	child.stdout?.on("error", (error) => {
+		fail(/* @__PURE__ */ new Error("ProxyCommand stdout error: " + error.message));
+	});
+	child.stdin?.on("error", (error) => {
+		if (child.exitCode !== null && child.exitCode !== 0 || child.signalCode !== null) {
+			fail(formatExitError(child.exitCode, child.signalCode, stderr));
+			return;
+		}
+		const timer = setTimeout(() => {
+			fail(/* @__PURE__ */ new Error("ProxyCommand transport error: " + error.message));
+		}, 200);
+		timer.unref();
+		child.once("exit", (code, signal) => {
+			clearTimeout(timer);
+			if (code !== null && code !== 0 || signal !== null) fail(formatExitError(code, signal, stderr));
+		});
+	});
+	child.on("error", (error) => {
+		fail(/* @__PURE__ */ new Error("ProxyCommand could not start: " + error.message));
+	});
+	child.on("exit", (code, signal) => {
+		exited = true;
+		if (code !== null && code !== 0 || signal !== null) {
+			fail(formatExitError(code, signal, stderr));
+			return;
+		}
+		finishIfClean();
+	});
+	return {
+		stream,
+		child
+	};
+}
+//#endregion
 //#region src/engine/connection-pool.ts
 /**
 * Connection pool: per-alias persistent ssh2 connections with multi-hop jump
@@ -1440,6 +1778,10 @@ function connectClient(config, onKeyboardInteractive) {
 		const fail = (error) => {
 			if (settled) return;
 			settled = true;
+			const sock = config.sock;
+			if (sock !== void 0 && typeof sock.destroy === "function") try {
+				sock.destroy();
+			} catch {}
 			try {
 				client.destroy();
 			} catch {}
@@ -1484,34 +1826,127 @@ function appendOutput(target, chunk, maxBytes) {
 	}
 	target.text += chunk.toString("utf8");
 }
+/** The ProxyCommand token source for one entry. */
+function proxyTargetOf(entry) {
+	return {
+		host: entry.host,
+		port: entry.port,
+		user: entry.user,
+		alias: entry.alias
+	};
+}
+/**
+* Parse an OpenSSH jump hop written as an address: `[user@]host[:port]`
+* (an IPv6 literal must be bracketed). Returns undefined when the value is not
+* an address at all.
+*/
+function parseJumpSpec(spec) {
+	const trimmed = spec.trim();
+	if (trimmed === "") return void 0;
+	const at = trimmed.lastIndexOf("@");
+	const user = at >= 0 ? trimmed.slice(0, at) : void 0;
+	const rest = at >= 0 ? trimmed.slice(at + 1) : trimmed;
+	if (rest === "") return void 0;
+	let host = rest;
+	let portText;
+	if (rest.startsWith("[")) {
+		const end = rest.indexOf("]");
+		if (end < 0) return void 0;
+		host = rest.slice(1, end);
+		const tail = rest.slice(end + 1);
+		if (tail.startsWith(":")) portText = tail.slice(1);
+		else if (tail !== "") return void 0;
+	} else {
+		const colon = rest.indexOf(":");
+		if (colon >= 0) {
+			host = rest.slice(0, colon);
+			portText = rest.slice(colon + 1);
+		}
+	}
+	if (host === "") return void 0;
+	let port;
+	if (portText !== void 0) {
+		port = Number(portText);
+		if (!Number.isInteger(port) || port < 1 || port > 65535) return void 0;
+	}
+	return {
+		host,
+		...port !== void 0 ? { port } : {},
+		...user !== void 0 && user !== "" ? { user } : {}
+	};
+}
+/**
+* Resolve one ProxyJump spec: an alias configured in this plugin wins, and any
+* other value is read as an OpenSSH address whose credentials come from the
+* target entry (an ad-hoc hop has no stored auth of its own).
+*/
+function resolveHop(engine, entry, spec) {
+	const configured = engine.store.find(spec);
+	if (configured !== void 0) return configured;
+	const parsed = parseJumpSpec(spec);
+	if (parsed === void 0) throw new Error("proxyJump '" + spec + "' is neither a configured alias nor a [user@]host[:port] address");
+	const now = Date.now();
+	return {
+		alias: spec,
+		host: parsed.host,
+		port: parsed.port ?? 22,
+		user: parsed.user ?? process.env.USER ?? entry.user,
+		auth: entry.auth,
+		proxyJump: [],
+		tags: [],
+		createdAt: now,
+		updatedAt: now
+	};
+}
 /**
 * 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.
+*
+* A ProxyCommand is the transport that reaches its own host, so the entry's
+* own command seeds the chain when there is no jump chain, and the first hop's
+* command is used when the hop carries one.
 */
 async function connectChain(engine, entry, onKeyboardInteractive) {
 	const hops = [];
-	let sock;
 	const chain = entry.proxyJump;
+	if (chain.length > 0 && entry.proxyCommand !== void 0) throw new Error("entry '" + entry.alias + "' declares both proxyCommand and proxyJump — pick one transport per host");
+	/** Transports this call started; destroyed on every failure path. */
+	const transports = [];
+	const startTransport = (owner) => {
+		const { stream } = startProxyCommand(owner.proxyCommand, proxyTargetOf(owner));
+		transports.push(stream);
+		return stream;
+	};
+	let sock = entry.proxyCommand !== void 0 ? startTransport(entry) : void 0;
 	try {
 		for (let index = 0; index < chain.length; index += 1) {
-			const hopAlias = chain[index];
-			const hop = engine.store.find(hopAlias);
-			if (hop === void 0) throw new Error("proxyJump alias '" + hopAlias + "' not found — create it first");
-			const hopClient = await connectClient(buildConnectConfig(hop, sock, engine.opts), onKeyboardInteractive);
+			const spec = chain[index];
+			const hop = resolveHop(engine, entry, spec);
+			if (index > 0 && hop.proxyCommand !== void 0) throw new Error("proxyJump hop '" + spec + "' declares a proxyCommand, which is only supported on the first hop");
+			const hopSock = index === 0 && hop.proxyCommand !== void 0 ? startTransport(hop) : sock;
+			let hopClient;
+			try {
+				hopClient = await connectClient(buildConnectConfig(hop, hopSock, engine.opts), onKeyboardInteractive);
+			} catch (error) {
+				throw new Error("proxyJump hop '" + spec + "' (" + hop.user + "@" + hop.host + ":" + hop.port + "): " + (error instanceof Error ? error.message : String(error)));
+			}
 			hops.push(hopClient);
-			const next = index + 1 < chain.length ? engine.store.find(chain[index + 1]) : void 0;
+			const next = index + 1 < chain.length ? resolveHop(engine, entry, 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) reject(error);
+					if (error !== void 0) reject(/* @__PURE__ */ new Error("proxyJump hop '" + spec + "' could not forward to " + nextHost + ":" + nextPort + ": " + error.message));
 					else resolve(stream);
 				});
 			});
 		}
 	} catch (error) {
 		for (const client of hops) client.end();
+		for (const stream of transports) try {
+			stream.destroy();
+		} catch {}
 		throw error;
 	}
 	let target;
@@ -1523,6 +1958,9 @@ async function connectChain(engine, entry, onKeyboardInteractive) {
 		};
 	} catch (error) {
 		for (const client of hops) client.end();
+		for (const stream of transports) try {
+			stream.destroy();
+		} catch {}
 		if (target !== void 0) try {
 			target.destroy();
 		} catch {}
@@ -2469,7 +2907,8 @@ function makeRoutes(deps) {
 								"port",
 								"user",
 								"auth",
-								"proxyJump"
+								"proxyJump",
+								"proxyCommand"
 							].some((key) => patch[key] !== void 0)) engine.dropAlias(alias);
 							writeJson(res, 200, { host: store.summarize(entry) });
 						} catch (error) {
@@ -2949,18 +3388,27 @@ function text(value) {
 		text: value
 	}];
 }
+/** Project one summary onto the agent-facing row shape. */
+function toAgentHostRow(host) {
+	const { proxyCommand, ...rest } = host;
+	return {
+		...rest,
+		proxyCommandConfigured: proxyCommand !== void 0
+	};
+}
 /** Host table render shared by list surfaces. */
 function renderHosts(hosts) {
 	if (hosts.length === 0) return "no hosts configured";
 	return [
-		"alias | host | port | user | auth | environment | tags | description",
-		"--- | --- | --- | --- | --- | --- | --- | ---",
+		"alias | host | port | user | auth | proxy | environment | tags | description",
+		"--- | --- | --- | --- | --- | --- | --- | --- | ---",
 		...hosts.map((host) => [
 			host.alias,
 			host.host,
 			String(host.port),
 			host.user,
 			host.auth,
+			host.proxyJump.length > 0 ? "jump:" + host.proxyJump.join(",") : host.proxyCommandConfigured ? "proxy-command" : "-",
 			host.environment ?? "-",
 			host.tags.length > 0 ? host.tags.join(",") : "-",
 			host.description ?? ""
@@ -3043,6 +3491,10 @@ function sshListTool(engine) {
 								items: { type: "string" },
 								required: true
 							},
+							proxyCommandConfigured: {
+								type: "boolean",
+								required: true
+							},
 							description: { type: "string" },
 							environment: { type: "string" },
 							tags: {
@@ -3066,7 +3518,7 @@ function sshListTool(engine) {
 			render: (_args, value) => text(renderHosts(value.hosts ?? []))
 		},
 		async execute(args) {
-			return { hosts: engine.list(args.query) };
+			return { hosts: engine.list(args.query).map(toAgentHostRow) };
 		}
 	});
 }
@@ -3582,7 +4034,7 @@ const DEFAULT_ANNOUNCE = false;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 150;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const SSH_GUIDANCE = "本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 $DSH_HOME/dsh-ssh.json（默认 ~/.dsh）（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 按 aliases/environment/tags 至少一种非空 selector 筛选后集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
+const SSH_GUIDANCE = "本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 $DSH_HOME/dsh-ssh.json（默认 ~/.dsh）（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 按 aliases/environment/tags 至少一种非空 selector 筛选后集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥、ProxyJump 跳板机（别名或 [user@]host[:port] 地址）与 OpenSSH 语义的 ProxyCommand（跳过堡垒机客户端场景，只能由用户在 GUI 配置，agent 不可写）；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
 /**
 * Mount the SSH engine, routes, tools, and announcement.
 * @param ctx - host plugin context carrying webServer/tools/systemPrompt.