@xynogen/pix-ssh 0.3.4 → 0.4.0

package/README.md

@@ -14,7 +14,14 @@ Registers the `ssh_run` tool — run a command through the configured SSH shell
 
 Output is truncated to 50 KB / 2000 lines. Non-interactive (RPC/JSON) mode blocks the tool immediately.
 
-**Parameters:** `host` as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`), `command`, optional `sudo` (run through POSIX `sudo` as root), optional `reason`.
+**Parameters:** `action` (`"command"` default · `"file"` · `"info"`), `host` as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`), `command`, optional `sudo` (run through POSIX `sudo` as root), optional `reason`.
+
+### `action: "info"` — SSH config, no connection
+
+Lets the agent discover hosts without reading `~/.ssh/config` itself. Read-only: no connection, no approval dialog, no password.
+
+- **No `host`** → lists configured host aliases from `~/.ssh/config` and every file it pulls in via `Include` (glob + relative paths resolved OpenSSH-style, cycle-guarded). Wildcard-only patterns (`Host *`) are skipped. Each row shows `alias → user@hostname:port` plus `via <ProxyJump>` when set.
+- **With `host`** → runs `ssh -G <host>` and reports the effective `HostName`/`User`/`Port`/`ProxyJump`/`IdentityFile` for that target (alias resolution, `Match`, and `Include` all handled by OpenSSH). No packets are sent to the remote.
 
 ### Authentication
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-ssh",
-	"version": "0.3.4",
+	"version": "0.4.0",
 	"description": "Pi tool — ssh_run: run remote commands over SSH with password/key auth and remote sudo",
 	"type": "module",
 	"main": "src/index.ts",

package/src/index.ts

@@ -56,6 +56,8 @@ import {
 	controlPathFor,
 	detectSshFailure,
 	detectSudoFailure,
+	type HostAlias,
+	type HostInfo,
 	type HostSpec,
 	hostApproved,
 	hostTarget,
@@ -63,6 +65,8 @@ import {
 	MAX_OUTPUT_LINES,
 	parseHost,
 	probeKeyAuth,
+	readSshConfigAliases,
+	resolveHostInfo,
 	resolveSshHost,
 	runSsh,
 	runTransfer,
@@ -122,23 +126,19 @@ export interface SshResultDetails {
 	_render?: string;
 }
 
-type SshParams =
-	| {
-			action?: "command";
-			host: string;
-			command: string;
-			sudo?: boolean;
-			reason?: string;
-	  }
-	| {
-			action: "file";
-			host: string;
-			direction: TransferDirection;
-			source: string;
-			destination: string;
-			recursive?: boolean;
-			reason?: string;
-	  };
+// Flat shape mirroring the single Type.Object schema. Conditional fields are
+// optional here and validated at runtime by normalizeOperation.
+type SshParams = {
+	action?: "command" | "file" | "info";
+	host?: string;
+	command?: string;
+	sudo?: boolean;
+	direction?: TransferDirection;
+	source?: string;
+	destination?: string;
+	recursive?: boolean;
+	reason?: string;
+};
 
 interface SshOperation {
 	action: "command" | "file";
@@ -153,11 +153,11 @@ interface SshOperation {
 
 function normalizeOperation(params: SshParams): SshOperation {
 	if (params.action === "file") {
-		const source = params.source.trim();
-		const destination = params.destination.trim();
+		const source = (params.source ?? "").trim();
+		const destination = (params.destination ?? "").trim();
 		return {
 			action: "file",
-			command: `${params.direction} ${source || "(empty source)"} → ${destination || "(empty destination)"}`,
+			command: `${params.direction ?? ""} ${source || "(empty source)"} → ${destination || "(empty destination)"}`,
 			sudo: false,
 			reason: params.reason,
 			direction: params.direction,
@@ -168,7 +168,7 @@ function normalizeOperation(params: SshParams): SshOperation {
 	}
 	return {
 		action: "command",
-		command: params.command,
+		command: params.command ?? "",
 		sudo: params.sudo === true,
 		reason: params.reason,
 		source: "",
@@ -293,6 +293,67 @@ function cancelResult(
 	};
 }
 
+function formatHostInfo(host: string, info: HostInfo): string {
+	const rows = [
+		["HostName", info.hostname],
+		["User", info.user],
+		["Port", info.port],
+		["ProxyJump", info.proxyJump && info.proxyJump !== "none" ? info.proxyJump : undefined],
+		["IdentityFile", info.identityFile],
+	].filter((r): r is [string, string] => Boolean(r[1]));
+	if (rows.length === 0) return `No SSH config found for ${host}.`;
+	return [`Effective SSH config for ${host}:`, ...rows.map(([k, v]) => `  ${k} ${v}`)].join("\n");
+}
+
+function formatAliasList(aliases: HostAlias[]): string {
+	if (aliases.length === 0) {
+		return "No SSH host aliases found in ~/.ssh/config.";
+	}
+	// De-dupe by alias, first block wins (OpenSSH semantics).
+	const seen = new Set<string>();
+	const lines: string[] = [];
+	for (const a of aliases) {
+		if (seen.has(a.alias)) continue;
+		seen.add(a.alias);
+		let target = "";
+		if (a.hostname) {
+			const userPart = a.user ? `${a.user}@` : "";
+			const portPart = a.port ? `:${a.port}` : "";
+			target = `${userPart}${a.hostname}${portPart}`;
+		}
+		const via = a.proxyJump && a.proxyJump !== "none" ? ` via ${a.proxyJump}` : "";
+		lines.push(`  ${a.alias}${target ? ` → ${target}` : ""}${via}`);
+	}
+	return [`SSH host aliases (${lines.length}):`, ...lines].join("\n");
+}
+
+/** Build the info-action result: per-host effective config when `host` is
+ * given, otherwise the alias inventory from ~/.ssh/config. Read-only.
+ * Details carry `_type: "sshInfo"` so renderResult falls to its generic
+ * plain-text branch (no collapse, no exit-code framing). */
+async function infoResult(host: string | undefined, sig?: AbortSignal) {
+	const details = { _type: "sshInfo" as const };
+	if (host?.trim()) {
+		let spec: HostSpec;
+		try {
+			spec = parseHost(host);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return {
+				content: [{ type: "text" as const, text: `ssh_run failed: ${msg}` }],
+				details,
+				isError: true,
+			};
+		}
+		const text = formatHostInfo(hostTarget(spec), await resolveHostInfo(spec, sig));
+		return { content: [{ type: "text" as const, text }], details };
+	}
+	return {
+		content: [{ type: "text" as const, text: formatAliasList(readSshConfigAliases()) }],
+		details,
+	};
+}
+
 // ── Extension entry point ─────────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI): void {
@@ -300,67 +361,95 @@ export default function (pi: ExtensionAPI): void {
 		name: "ssh_run",
 		label: "Run over SSH",
 		description:
-			"Run a command or transfer files/directories through SSH. Commands may optionally use POSIX sudo. " +
-			"Basic cmd/PowerShell/pwsh commands may work, but Windows shells are best-effort: shell selection, " +
-			"quoting, PowerShell error/stream/encoding semantics, interactive prompts, and Windows " +
-			"administrator/UAC elevation are not supported. Back away and tell the user when correctness " +
-			"depends on one of those limits. Handles connection and password entry through a permission dialog. " +
-			"A configured approval window or YOLO mode may auto-approve non-privileged commands when no password is missing. " +
-			"SSH auth tries key/agent first, then prompts for a login password if needed. " +
-			"Set `sudo: true` to run the command as root on the remote machine (prompts for the " +
-			'remote sudo password). For transfer, set `action: "file"`, `direction`, `source`, ' +
-			"`destination`, and optional `recursive`. Transfers may overwrite the destination. Always provide a clear `reason`.",
-		promptSnippet: "Run a remote command or transfer files over SSH",
+			"Run a command or transfer files/directories on a REMOTE host over SSH. " +
+			"For the LOCAL machine use `bash` (or `sudo_run` for local root) instead — do not use ssh_run for local work. " +
+			"Requires a `host`. Windows/PowerShell shells are best-effort (elevation and PowerShell stream/encoding semantics unsupported). " +
+			"Set `sudo: true` to run the command as root on the remote machine. " +
+			'For transfer, set `action: "file"`, `direction`, `source`, `destination`, and optional `recursive` — ' +
+			"transfers may overwrite the destination. " +
+			'To discover hosts without reading `~/.ssh/config`, use `action: "info"` — omit `host` to list configured aliases, or pass a `host` to get its effective config (no connection). ' +
+			"Always provide a clear `reason`.",
+		promptSnippet: "Run a remote command, transfer files, or read SSH config over SSH",
 		promptGuidelines: [
-			'ssh_run: `host` as `[user@]host[:port]`; `sudo` covers POSIX sudo only. For transfer use `action: "file"` with `direction: "upload"|"download"`, `source`, `destination`, optional `recursive` (may overwrite). Always set `reason`.',
+			'ssh_run: REMOTE host only — use `bash`/`sudo_run` for the local machine. `host` as `[user@]host[:port]`; `sudo` covers remote POSIX sudo only. For transfer use `action: "file"` with `direction: "upload"|"download"`, `source`, `destination`, optional `recursive` (may overwrite). Use `action: "info"` (no `host` = list aliases, with `host` = its effective config) instead of reading `~/.ssh/config` yourself. Always set `reason`.',
 		],
 
 		renderShell: "self",
 
-		parameters: Type.Union([
-			Type.Object({
-				action: Type.Optional(Type.Literal("command")),
-				host: Type.String({
-					description: "Remote target as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`).",
+		// Single Type.Object (root `type: "object"`) rather than Type.Union — a union
+		// serializes to `anyOf` with no root type, which strict OpenAI-compatible
+		// providers (e.g. DeepSeek) reject with `type: null`. Conditional fields are
+		// optional and normalized/validated at runtime via normalizeOperation.
+		parameters: Type.Object({
+			action: Type.Optional(
+				Type.Union([Type.Literal("command"), Type.Literal("file"), Type.Literal("info")], {
+					description:
+						'"command" (default) runs a remote command; "file" transfers a file/directory; "info" reports SSH config (no connection) — list configured host aliases, or resolve one host\'s effective config when `host` is given.',
 				}),
-				command: Type.String({
-					description: "Command sent to the remote host's configured SSH shell.",
+			),
+			host: Type.Optional(
+				Type.String({
+					description:
+						"Remote target as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`). Required for command/file; for info, omit to list all aliases or set it to resolve one host.",
 				}),
-				sudo: Type.Optional(
-					Type.Boolean({
-						description: "Run the command as root on the remote host via sudo. Default false.",
-					}),
-				),
-				reason: Type.Optional(
-					Type.String({
-						description: "Short plain-English explanation of intent, shown to the user.",
-					}),
-				),
-			}),
-			Type.Object({
-				action: Type.Literal("file"),
-				host: Type.String({
-					description: "Remote target as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`).",
+			),
+			command: Type.Optional(
+				Type.String({
+					description:
+						'Command sent to the remote host\'s configured SSH shell. Required when action is "command".',
 				}),
-				direction: Type.Union([Type.Literal("upload"), Type.Literal("download")]),
-				source: Type.String({
-					description: "Source path. Local for upload; remote for download.",
+			),
+			sudo: Type.Optional(
+				Type.Boolean({
+					description:
+						"Run the command as root on the remote host via sudo. Default false. Command action only.",
 				}),
-				destination: Type.String({
-					description: "Destination path. Remote for upload; local for download.",
+			),
+			direction: Type.Optional(
+				Type.Union([Type.Literal("upload"), Type.Literal("download")], {
+					description: 'Transfer direction. Required when action is "file".',
 				}),
-				recursive: Type.Optional(
-					Type.Boolean({ description: "Copy a directory recursively. Default false." }),
-				),
-				reason: Type.Optional(
-					Type.String({
-						description: "Short plain-English explanation of intent, shown to the user.",
-					}),
-				),
-			}),
-		]),
+			),
+			source: Type.Optional(
+				Type.String({
+					description:
+						'Source path (local for upload, remote for download). Required when action is "file".',
+				}),
+			),
+			destination: Type.Optional(
+				Type.String({
+					description:
+						'Destination path (remote for upload, local for download). Required when action is "file".',
+				}),
+			),
+			recursive: Type.Optional(
+				Type.Boolean({
+					description: "Copy a directory recursively. Default false. File action only.",
+				}),
+			),
+			reason: Type.Optional(
+				Type.String({
+					description: "Short plain-English explanation of intent, shown to the user.",
+				}),
+			),
+		}),
 
 		async execute(_toolCallId, params, sig, onUpdate, ctx) {
+			// info: read-only SSH config report (no connection, no approval).
+			if (params.action === "info") {
+				return infoResult(params.host, sig);
+			}
+
+			if (!params.host?.trim()) {
+				return {
+					content: [{ type: "text", text: "ssh_run failed: host is required" }],
+					details: makeDetails("", "", false, params.reason, {
+						outcome: "error",
+						errorKind: "execution",
+					}),
+					isError: true,
+				};
+			}
 			const operation = normalizeOperation(params);
 			const { action, command, destination, direction, reason, recursive, source, sudo } =
 				operation;
@@ -376,6 +465,17 @@ export default function (pi: ExtensionAPI): void {
 				};
 			}
 
+			if (action === "command" && !command.trim()) {
+				return {
+					content: [{ type: "text", text: "ssh_run failed: command is required" }],
+					details: makeDetails(command, params.host, sudo, reason, {
+						outcome: "error",
+						errorKind: "execution",
+					}),
+					isError: true,
+				};
+			}
+
 			let spec: HostSpec;
 			try {
 				spec = parseHost(params.host);
@@ -713,9 +813,17 @@ export default function (pi: ExtensionAPI): void {
 			)
 				return text;
 
+			const host = safeOneLine(args.host ?? "");
+			if (args.action === "info") {
+				text.setText(
+					fillToolBackground(
+						`${theme.fg("toolTitle", theme.bold("ssh info"))} ${theme.fg("dim", host || "list aliases")}`,
+					),
+				);
+				return text;
+			}
 			const operation = normalizeOperation(args);
 			const command = safeOneLine(operation.command) || "(empty command)";
-			const host = safeOneLine(args.host);
 			const prefix = operation.sudo ? "sudo " : "";
 			text.setText(
 				fillToolBackground(

package/src/lib.ts

@@ -15,8 +15,9 @@
 
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { globSync, readFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, resolve as resolvePath } from "node:path";
 
 export const MAX_OUTPUT_BYTES = 50 * 1024;
 export const MAX_OUTPUT_LINES = 2000;
@@ -153,6 +154,142 @@ export function resolveSshHost(spec: HostSpec, signal?: AbortSignal): Promise<Ho
 	});
 }
 
+// ── Host inventory (info action) ─────────────────────────────────────────────
+
+export interface HostAlias {
+	alias: string;
+	hostname?: string;
+	user?: string;
+	port?: string;
+	proxyJump?: string;
+	identityFile?: string;
+}
+
+export interface HostInfo {
+	hostname?: string;
+	user?: string;
+	port?: string;
+	proxyJump?: string;
+	identityFile?: string;
+}
+
+/** Fields we surface from an ssh config Host block or `ssh -G` output. */
+const INFO_KEYS: Record<string, keyof HostInfo> = {
+	hostname: "hostname",
+	user: "user",
+	port: "port",
+	proxyjump: "proxyJump",
+	identityfile: "identityFile",
+};
+
+/**
+ * Parse `Host` blocks out of an ssh_config text. Returns one entry per alias
+ * token (a single `Host a b` line yields two aliases). Wildcard-only patterns
+ * (`*`, `?`, `!`) are skipped since they aren't connectable targets. Keys are
+ * matched case-insensitively; the first value for a key within a block wins
+ * (OpenSSH "first obtained value" semantics).
+ */
+export function parseHostAliases(text: string): HostAlias[] {
+	const out: HostAlias[] = [];
+	let current: HostAlias[] = [];
+	for (const raw of text.split("\n")) {
+		const line = raw.replace(/#.*$/, "").trim();
+		if (!line) continue;
+		const [keyRaw, ...rest] = line.split(/\s+/);
+		const key = (keyRaw ?? "").toLowerCase();
+		const value = rest.join(" ");
+		if (key === "host") {
+			current = rest.filter((p) => !/[*?!]/.test(p)).map((alias) => ({ alias }));
+			out.push(...current);
+		} else if (current.length > 0) {
+			const field = INFO_KEYS[key];
+			if (field && value) {
+				for (const entry of current) {
+					if (entry[field] === undefined) entry[field] = value;
+				}
+			}
+		}
+	}
+	return out;
+}
+
+/** Expand a Path with a leading `~` and resolve relative Includes against
+ * the containing config's directory (OpenSSH semantics). */
+function expandConfigPath(pattern: string, baseDir: string): string {
+	let p = pattern;
+	if (p.startsWith("~/")) p = join(homedir(), p.slice(2));
+	else if (p === "~") p = homedir();
+	return isAbsolute(p) ? p : resolvePath(baseDir, p);
+}
+
+/**
+ * Read an ssh_config file and every file it pulls in via `Include`, returning
+ * the concatenated Host aliases. Missing files and glob misses are ignored
+ * (OpenSSH tolerates them). `seen` guards against Include cycles.
+ */
+export function readSshConfigAliases(
+	path = join(homedir(), ".ssh", "config"),
+	seen = new Set<string>(),
+): HostAlias[] {
+	if (seen.has(path)) return [];
+	seen.add(path);
+	let text: string;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch {
+		return [];
+	}
+	const baseDir = join(homedir(), ".ssh");
+	const out: HostAlias[] = [];
+	for (const raw of text.split("\n")) {
+		const line = raw.replace(/#.*$/, "").trim();
+		const [keyRaw, ...rest] = line.split(/\s+/);
+		if ((keyRaw ?? "").toLowerCase() === "include") {
+			for (const pattern of rest) {
+				const expanded = expandConfigPath(pattern, baseDir);
+				let matches: string[] = [];
+				try {
+					matches = globSync(expanded);
+				} catch {
+					matches = [];
+				}
+				for (const file of matches.sort()) out.push(...readSshConfigAliases(file, seen));
+			}
+		}
+	}
+	out.push(...parseHostAliases(text));
+	return out;
+}
+
+/** Full effective config for one host via `ssh -G` (no connection made). */
+export function parseHostInfo(output: string): HostInfo {
+	const info: HostInfo = {};
+	for (const line of output.split("\n")) {
+		const [keyRaw, ...rest] = line.trim().split(/\s+/);
+		const field = INFO_KEYS[(keyRaw ?? "").toLowerCase()];
+		const value = rest.join(" ");
+		if (field && value && info[field] === undefined) info[field] = value;
+	}
+	return info;
+}
+
+/** Run `ssh -G <host>` and return its effective config. Never connects. */
+export function resolveHostInfo(spec: HostSpec, signal?: AbortSignal): Promise<HostInfo> {
+	const args = ["-G"];
+	if (spec.port !== undefined) args.push("-p", String(spec.port));
+	args.push(hostTarget(spec));
+	return new Promise((resolve) => {
+		let stdout = "";
+		const proc = spawn("ssh", args, { stdio: ["ignore", "pipe", "ignore"] });
+		proc.stdout.on("data", (c: Buffer) => {
+			stdout += c.toString();
+		});
+		proc.on("error", () => resolve({}));
+		proc.on("close", (code) => resolve(code === 0 ? parseHostInfo(stdout) : {}));
+		signal?.addEventListener("abort", () => proc.kill("SIGTERM"), { once: true });
+	});
+}
+
 /** Canonical `[user@]host` target string for ssh argv. */
 export function hostTarget(spec: HostSpec): string {
 	return spec.user ? `${spec.user}@${spec.host}` : spec.host;