@xynogen/pix-ssh 0.5.1 → 0.5.5

package/README.md

@@ -49,16 +49,22 @@ Completed calls collapse after the configured Pix delay into a status row such a
 pi install npm:@xynogen/pix-ssh
 ```
 
-> Standalone/opt-in — **not** bundled by [`@xynogen/pix-core`](https://www.npmjs.com/package/@xynogen/pix-core). Remote execution over SSH is a networked, privileged capability, so you install it deliberately.
+> Standalone and opt-in. [`@xynogen/pix-core`](https://www.npmjs.com/package/@xynogen/pix-core) does not bundle it. Remote execution over SSH is a networked, privileged capability.
 
 ## Full distro
 
-Source: [github.com/xynogen/pix-mono](https://github.com/xynogen/pix-mono)
+This package is part of [Pix](https://github.com/xynogen/pix-mono). The installer sets up Pi and the full distro. See [Install](https://github.com/xynogen/pix-mono#install) for the notes for each OS.
 
 ```bash
+# Linux / macOS
 curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
 ```
 
+```powershell
+# Windows
+irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex
+```
+
 ## License
 
-MIT
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-ssh",
-	"version": "0.5.1",
+	"version": "0.5.5",
 	"description": "Pi tool — ssh_run: run remote commands over SSH with password/key auth and remote sudo",
 	"type": "module",
 	"main": "src/index.ts",
@@ -37,11 +37,11 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"typebox": "^1.1.38",
 		"@xynogen/pix-pretty": "^1.25.0",
-		"@xynogen/pix-runtime": "^0.8.0"
+		"@xynogen/pix-runtime": "^0.12.2"
 	},
 	"peerDependencies": {
+		"typebox": "*",
 		"@earendil-works/pi-coding-agent": "*",
 		"@earendil-works/pi-tui": "*"
 	}

package/src/index.ts

@@ -37,6 +37,7 @@ import {
 	dotJoin,
 	fillToolBackground,
 	frameToolResult,
+	getErrorMessage,
 	getTextContent,
 	hideCollapsedToolCall,
 	normalizeLineEndings,
@@ -49,6 +50,7 @@ import {
 } from "@xynogen/pix-pretty/utils";
 import { SPINNER } from "@xynogen/pix-pretty/widget-format";
 import { getUnattendedMode, withAgentBlock } from "@xynogen/pix-runtime";
+import { requireTool } from "@xynogen/pix-runtime/binaries";
 import { type CollapseState, tickCollapse } from "@xynogen/pix-runtime/collapse";
 import { Type } from "typebox";
 import {
@@ -351,6 +353,22 @@ function formatAliasList(aliases: HostAlias[]): string {
  * 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). */
+/**
+ * The pix-runtime lookup message for the first missing binary this action
+ * needs (ssh, plus scp for file transfers), or undefined when all resolve.
+ * sshpass is checked lazily: it only matters when a login password is used.
+ */
+export function missingSshTools(action: "command" | "file"): string | undefined {
+	for (const name of action === "file" ? ["ssh", "scp"] : ["ssh"]) {
+		try {
+			requireTool(name);
+		} catch (err) {
+			return getErrorMessage(err);
+		}
+	}
+	return undefined;
+}
+
 async function infoResult(host: string | undefined, sig?: AbortSignal) {
 	const details = { _type: "sshInfo" as const };
 	if (host?.trim()) {
@@ -358,7 +376,7 @@ async function infoResult(host: string | undefined, sig?: AbortSignal) {
 		try {
 			spec = parseHost(host);
 		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
+			const msg = getErrorMessage(err);
 			return {
 				content: [{ type: "text" as const, text: `ssh_run failed: ${msg}` }],
 				details,
@@ -379,6 +397,7 @@ async function infoResult(host: string | undefined, sig?: AbortSignal) {
 export default function (pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "ssh_run",
+		...({ exposure: "deferred" } as const),
 		label: "Run over SSH",
 		description:
 			"Run a command or transfer files/directories on a REMOTE host over SSH. " +
@@ -496,11 +515,25 @@ export default function (pi: ExtensionAPI): void {
 				};
 			}
 
+			// Fail up front with pix's install hint: the probes below treat a spawn
+			// error as "unreachable", which would hide a missing ssh/scp.
+			const missingTool = missingSshTools(action);
+			if (missingTool) {
+				return {
+					content: [{ type: "text", text: `ssh_run failed: ${missingTool}` }],
+					details: makeDetails(command, params.host, sudo, reason, {
+						outcome: "error",
+						errorKind: "execution",
+					}),
+					isError: true,
+				};
+			}
+
 			let spec: HostSpec;
 			try {
 				spec = parseHost(params.host);
 			} catch (err) {
-				const msg = err instanceof Error ? err.message : String(err);
+				const msg = getErrorMessage(err);
 				return {
 					content: [{ type: "text", text: `ssh_run failed: ${msg}` }],
 					details: makeDetails(command, params.host, sudo, reason, {
@@ -750,7 +783,7 @@ export default function (pi: ExtensionAPI): void {
 								...(sig ? { signal: sig } : {}),
 							});
 			} catch (err) {
-				const msg = err instanceof Error ? err.message : String(err);
+				const msg = getErrorMessage(err);
 				return {
 					content: [{ type: "text", text: `ssh_run failed: ${msg}` }],
 					details: makeDetails(

package/src/lib.ts

@@ -13,14 +13,21 @@
  *     entered once per session per host.
  */
 
-import { spawn } from "node:child_process";
+import type { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 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;
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { spawnTool } from "@xynogen/pix-runtime/exec";
+import { expandHome, homeDir, tempDir } from "@xynogen/pix-runtime/paths";
+
+// Pi's own tool-output limits (50KB / 2000 lines), so every tool caps the same way.
+export const MAX_OUTPUT_BYTES = DEFAULT_MAX_BYTES;
+export const MAX_OUTPUT_LINES = DEFAULT_MAX_LINES;
 
 /** Per-host approval TTL (ms) — mirrors sudo's PAM ticket window (~15 min). */
 export const APPROVAL_TTL_MS = 15 * 60_000;
@@ -144,7 +151,7 @@ export function resolveSshHost(spec: HostSpec, signal?: AbortSignal): Promise<Ho
 
 	return new Promise((resolve) => {
 		let stdout = "";
-		const proc = spawn("ssh", args, { stdio: ["ignore", "pipe", "ignore"] });
+		const proc = spawnTool("ssh", args, { stdio: ["ignore", "pipe", "ignore"] });
 		proc.stdout.on("data", (chunk: Buffer) => {
 			stdout += chunk.toString();
 		});
@@ -216,9 +223,7 @@ export function parseHostAliases(text: string): HostAlias[] {
 /** 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();
+	const p = expandHome(pattern);
 	return isAbsolute(p) ? p : resolvePath(baseDir, p);
 }
 
@@ -228,7 +233,7 @@ function expandConfigPath(pattern: string, baseDir: string): string {
  * (OpenSSH tolerates them). `seen` guards against Include cycles.
  */
 export function readSshConfigAliases(
-	path = join(homedir(), ".ssh", "config"),
+	path = join(homeDir(), ".ssh", "config"),
 	seen = new Set<string>(),
 ): HostAlias[] {
 	if (seen.has(path)) return [];
@@ -239,7 +244,7 @@ export function readSshConfigAliases(
 	} catch {
 		return [];
 	}
-	const baseDir = join(homedir(), ".ssh");
+	const baseDir = join(homeDir(), ".ssh");
 	const out: HostAlias[] = [];
 	for (const raw of text.split("\n")) {
 		const line = raw.replace(/#.*$/, "").trim();
@@ -280,7 +285,7 @@ export function resolveHostInfo(spec: HostSpec, signal?: AbortSignal): Promise<H
 	args.push(hostTarget(spec));
 	return new Promise((resolve) => {
 		let stdout = "";
-		const proc = spawn("ssh", args, { stdio: ["ignore", "pipe", "ignore"] });
+		const proc = spawnTool("ssh", args, { stdio: ["ignore", "pipe", "ignore"] });
 		proc.stdout.on("data", (c: Buffer) => {
 			stdout += c.toString();
 		});
@@ -300,7 +305,7 @@ export function hostTarget(spec: HostSpec): string {
 export function controlPathFor(spec: HostSpec): string {
 	const key = `${spec.user ?? ""}@${spec.host}:${spec.port ?? 22}`;
 	const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
-	return join(tmpdir(), `pix-ssh-${hash}.sock`);
+	return join(tempDir(), `pix-ssh-${hash}.sock`);
 }
 
 // ── ssh argv construction ────────────────────────────────────────────────────
@@ -405,17 +410,12 @@ export function truncate(
 	maxLines = MAX_OUTPUT_LINES,
 	maxBytes = MAX_OUTPUT_BYTES,
 ): { text: string; truncated: boolean } {
-	const lines = text.split("\n");
-	const byteLen = Buffer.byteLength(text, "utf8");
-	if (lines.length <= maxLines && byteLen <= maxBytes) {
-		return { text, truncated: false };
-	}
-	const kept = lines.slice(0, maxLines);
-	let result = kept.join("\n");
-	if (Buffer.byteLength(result, "utf8") > maxBytes) {
-		result = Buffer.from(result, "utf8").subarray(0, maxBytes).toString("utf8");
-	}
-	return { text: result, truncated: true };
+	const r = truncateHead(text, { maxLines, maxBytes });
+	if (!r.firstLineExceedsLimit) return { text: r.content, truncated: r.truncated };
+	// One line over the byte cap (minified JSON, a base64 blob): truncateHead keeps
+	// nothing. Keep its first maxBytes instead, cut on a UTF-8 boundary.
+	const head = Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+	return { text: head.replace(/\uFFFD$/, ""), truncated: true };
 }
 
 // ── Runners ──────────────────────────────────────────────────────────────────
@@ -440,7 +440,7 @@ export function probeKeyAuth(
 	const args = [...baseSshArgs(spec, controlPath), "-o", "BatchMode=yes", hostTarget(spec), "true"];
 	return new Promise((resolve) => {
 		let stderr = "";
-		const proc = spawn("ssh", args, { stdio: ["ignore", "ignore", "pipe"] });
+		const proc = spawnTool("ssh", args, { stdio: ["ignore", "ignore", "pipe"] });
 		proc.stderr.on("data", (c: Buffer) => {
 			stderr += c.toString();
 		});
@@ -488,7 +488,7 @@ export function probePasswordAuth(
 	];
 	return new Promise((resolve) => {
 		let stderr = "";
-		const proc = spawn("sshpass", args, {
+		const proc = spawnTool("sshpass", args, {
 			stdio: ["ignore", "ignore", "pipe"],
 			env: { ...process.env, SSHPASS: password },
 		});
@@ -525,7 +525,7 @@ export function probeSudoNoPassword(
 		"sudo -n true",
 	];
 	return new Promise((resolve) => {
-		const proc = spawn("ssh", args, { stdio: ["ignore", "ignore", "ignore"] });
+		const proc = spawnTool("ssh", args, { stdio: ["ignore", "ignore", "ignore"] });
 		proc.on("error", () => resolve(false));
 		proc.on("close", (code) => resolve(code === 0));
 		signal?.addEventListener("abort", () => proc.kill("SIGTERM"), { once: true });
@@ -569,29 +569,42 @@ export function runTransfer(
 	recursive: boolean,
 	opts: Pick<RunOptions, "controlPath" | "loginPassword" | "signal">,
 ): Promise<SshResult> {
-	const scpArgs = [
-		...baseScpArgs(spec, opts.controlPath, recursive),
-		"--",
-		...transferArgs(spec, direction, source, destination),
-	];
+	const endpoint = ["--", ...transferArgs(spec, direction, source, destination)];
 	const bin = opts.loginPassword ? "sshpass" : "scp";
-	const args = opts.loginPassword ? ["-e", "scp", ...scpArgs] : scpArgs;
+	// Same rule as runSsh: without a password in hand, force BatchMode so scp
+	// never opens its own /dev/tty prompt. sshpass path keeps prompts on.
+	const args = opts.loginPassword
+		? ["-e", "scp", ...baseScpArgs(spec, opts.controlPath, recursive), ...endpoint]
+		: [...baseScpArgs(spec, opts.controlPath, recursive), "-o", "BatchMode=yes", ...endpoint];
 	const env = opts.loginPassword ? { ...process.env, SSHPASS: opts.loginPassword } : process.env;
 	return spawnResult(bin, args, env, opts.signal);
 }
 
-export function runSsh(spec: HostSpec, command: string, opts: RunOptions): Promise<SshResult> {
+/**
+ * Build the ssh/sshpass argv for a run.
+ *
+ * Without a login password, force `BatchMode=yes` so ssh NEVER falls back to a
+ * `/dev/tty` password prompt (which leaks into the TUI). A run-time auth failure
+ * then returns a clean error the caller surfaces — all interactive password
+ * entry goes through the overlay + `sshpass`. With a password, BatchMode stays
+ * off so sshpass can answer ssh's own prompt.
+ */
+export function buildRunSshArgs(
+	spec: HostSpec,
+	command: string,
+	opts: Pick<RunOptions, "controlPath" | "loginPassword" | "sudo">,
+): { bin: string; args: string[] } {
 	const remote = remoteCommand(command, opts.sudo === true);
-	const sshArgs = [...baseSshArgs(spec, opts.controlPath), hostTarget(spec), remote];
-
-	let bin = "ssh";
-	let args = sshArgs;
-	let env = process.env;
+	const base = baseSshArgs(spec, opts.controlPath);
 	if (opts.loginPassword) {
-		bin = "sshpass";
-		args = ["-e", "ssh", ...sshArgs];
-		env = { ...process.env, SSHPASS: opts.loginPassword };
+		return { bin: "sshpass", args: ["-e", "ssh", ...base, hostTarget(spec), remote] };
 	}
+	return { bin: "ssh", args: [...base, "-o", "BatchMode=yes", hostTarget(spec), remote] };
+}
+
+export function runSsh(spec: HostSpec, command: string, opts: RunOptions): Promise<SshResult> {
+	const { bin, args } = buildRunSshArgs(spec, command, opts);
+	const env = opts.loginPassword ? { ...process.env, SSHPASS: opts.loginPassword } : process.env;
 
 	// Remote sudo reads its password from stdin (first line); anything else
 	// closes stdin so the remote command sees EOF.
@@ -608,7 +621,7 @@ function spawnResult(
 	stdin?: string,
 ): Promise<SshResult> {
 	return new Promise((resolve, reject) => {
-		const proc = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"], env });
+		const proc = spawnTool(bin, args, { stdio: ["pipe", "pipe", "pipe"], env });
 		let stdout = "";
 		let stderr = "";
 		proc.stdout.on("data", (c: Buffer) => {