@xynogen/pix-ssh 0.2.6 → 0.3.0

package/README.md

@@ -7,7 +7,12 @@ Pi tool — `ssh_run`: run a command through a remote host's configured SSH shel
 
 ## What it does
 
-Registers the `ssh_run` tool, which executes a command through the configured SSH shell on a remote machine behind a permission dialog (the shared overlay from `@xynogen/pix-pretty`, the same one pix-sudo uses). Initial and privileged calls require Allow/Deny approval in the UI, with a 60-second auto-deny timeout. Non-privileged calls may be auto-approved during the 15-minute per-host approval window or in YOLO mode when no password is missing; each host-window auto-approval emits a notification. Output is truncated to 50 KB / 2000 lines. In non-interactive (RPC/JSON) mode the tool is blocked immediately.
+Registers the `ssh_run` tool — run a command through the configured SSH shell on a remote machine, behind the same permission dialog pix-sudo uses (shared overlay from `@xynogen/pix-pretty`).
+
+- **Initial + privileged calls** → Allow/Deny approval, 60-second auto-deny timeout.
+- **Non-privileged calls** → may auto-approve during the 15-minute per-host window, or in YOLO mode when no password is missing; each auto-approval emits a notification.
+
+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`.
 
@@ -37,6 +42,8 @@ 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.
+
 ## Full distro
 
 Source: [github.com/xynogen/pix-mono](https://github.com/xynogen/pix-mono)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-ssh",
-	"version": "0.2.6",
+	"version": "0.3.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

@@ -1,9 +1,9 @@
 /**
  * pix-ssh — Pi extension
  *
- * Registers an `ssh_run` tool: run a shell command on a remote host over SSH,
- * optionally as root (remote sudo). One overlay handles confirm + any needed
- * password entry, mirroring pix-sudo.
+ * Registers an `ssh_run` tool: run a command or transfer files/directories over
+ * SSH. Commands may optionally run as root through remote sudo. One overlay
+ * handles confirmation and any needed password entry, mirroring pix-sudo.
  *
  * Auth:
  *   - SSH: key/agent/existing-master first (BatchMode probe). If that fails,
@@ -20,7 +20,7 @@
  *
  * Security notes:
  *   - Passwords never leave JS memory; never written to disk; never in argv.
- *   - Every command still requires explicit per-call confirmation in the UI.
+ *   - File transfers are warning-level and show their overwrite risk in the UI.
  *   - No UI (RPC / JSON mode) = blocked immediately.
  *   - Output truncated to 50 KB / 2000 lines.
  */
@@ -44,6 +44,7 @@ import {
 	sectionRule,
 	termW,
 } from "@xynogen/pix-pretty/utils";
+import { SPINNER } from "@xynogen/pix-pretty/widget-format";
 import { getUnattendedMode, withAgentBlock } from "@xynogen/pix-runtime";
 import { type CollapseState, tickCollapse } from "@xynogen/pix-runtime/collapse";
 import { Type } from "typebox";
@@ -62,11 +63,15 @@ import {
 	probeKeyAuth,
 	resolveSshHost,
 	runSsh,
+	runTransfer,
+	type TransferDirection,
+	transferApprovalDecision,
 	truncate,
 } from "./lib.ts";
 
 const PROMPT_TIMEOUT_MS = 60_000;
 const MAX_PASSWORD_ATTEMPTS = 3;
+const SPINNER_INTERVAL_MS = 120;
 
 // In-memory per-host credential cache (session-scoped, never persisted).
 // Key = canonical "user@host:port". Cleared on process exit.
@@ -115,6 +120,78 @@ 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;
+	  };
+
+interface SshOperation {
+	action: "command" | "file";
+	command: string;
+	sudo: boolean;
+	reason?: string;
+	direction?: TransferDirection;
+	source: string;
+	destination: string;
+	recursive: boolean;
+}
+
+function normalizeOperation(params: SshParams): SshOperation {
+	if (params.action === "file") {
+		const source = params.source.trim();
+		const destination = params.destination.trim();
+		return {
+			action: "file",
+			command: `${params.direction} ${source || "(empty source)"} → ${destination || "(empty destination)"}`,
+			sudo: false,
+			reason: params.reason,
+			direction: params.direction,
+			source,
+			destination,
+			recursive: params.recursive === true,
+		};
+	}
+	return {
+		action: "command",
+		command: params.command,
+		sudo: params.sudo === true,
+		reason: params.reason,
+		source: "",
+		destination: "",
+		recursive: false,
+	};
+}
+
+function approvalBody(operation: SshOperation, host: string, port?: number): string[] {
+	const { action, command, destination, direction, reason, recursive, source, sudo } = operation;
+	return [
+		reason?.trim() ? `Intent: ${reason.trim()}` : "No reason provided by AI",
+		`Host: ${host}${port ? ` (port ${port})` : ""}`,
+		...(action === "command"
+			? [`Command: ${sudo ? "sudo " : ""}${command}`]
+			: [
+					`Direction: ${direction === "download" ? "Download" : "Upload"}`,
+					`From: ${source}`,
+					`To: ${destination}`,
+					`Mode: ${recursive ? "Recursive copy" : "Single item"}`,
+					"Warning: existing destination may be overwritten",
+				]),
+	];
+}
+
 function safeOneLine(value: string): string {
 	return value
 		.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ")
@@ -151,12 +228,15 @@ function updatePresentation(
 	sudo: boolean,
 	reason: string | undefined,
 	outcome: "awaiting-approval" | "running",
+	message?: string,
 ): void {
 	onUpdate?.({
 		content: [
 			{
 				type: "text",
-				text: outcome === "awaiting-approval" ? "Awaiting approval…" : `Running on ${host}…`,
+				text:
+					message ??
+					(outcome === "awaiting-approval" ? "Awaiting approval…" : `Running on ${host}…`),
 			},
 		],
 		details: makeDetails(command, host, sudo, reason, { outcome }),
@@ -218,7 +298,7 @@ export default function (pi: ExtensionAPI): void {
 		name: "ssh_run",
 		label: "Run over SSH",
 		description:
-			"Run a command through the remote host's configured SSH shell, optionally through POSIX sudo. " +
+			"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 " +
@@ -226,40 +306,80 @@ export default function (pi: ExtensionAPI): void {
 			"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). Always provide a clear `reason`.",
-		promptSnippet: "Run a remote SSH command (Windows shells best-effort; POSIX sudo only)",
+			'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",
 		promptGuidelines: [
-			"ssh_run sends commands to the remote host's configured SSH shell. Basic cmd, PowerShell, or " +
+			"ssh_run sends commands or transfers files/directories over SSH. Basic cmd, PowerShell, or " +
 				"pwsh commands may work, but treat Windows shells as best-effort. Back away and tell the user " +
 				"when correctness depends on explicit shell selection, complex quoting, PowerShell error/stream/encoding " +
 				"semantics, interactive prompts, or Windows administrator/UAC elevation. `sudo` covers POSIX sudo " +
-				"only. Provide `host` as `[user@]host[:port]` and always explain the intent in `reason`.",
+				'only. Provide `host` as `[user@]host[:port]`. For file transfer, use `action: "file"`, ' +
+				'`direction: "upload" | "download"`, `source`, `destination`, and optional `recursive`. ' +
+				"Transfers may overwrite the destination and are warning-level: AFK/YOLO auto-approve when " +
+				"no login password is missing. Always explain the intent in `reason`.",
 		],
 
 		renderShell: "self",
 
-		parameters: Type.Object({
-			host: Type.String({
-				description: "Remote target as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`).",
-			}),
-			command: Type.String({
-				description: "Command sent to the remote host's configured SSH shell.",
+		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`).",
+				}),
+				command: Type.String({
+					description: "Command sent to the remote host's configured SSH shell.",
+				}),
+				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.",
+					}),
+				),
 			}),
-			sudo: Type.Optional(
-				Type.Boolean({
-					description: "Run the command as root on the remote host via sudo. Default false.",
+			Type.Object({
+				action: Type.Literal("file"),
+				host: Type.String({
+					description: "Remote target as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`).",
+				}),
+				direction: Type.Union([Type.Literal("upload"), Type.Literal("download")]),
+				source: Type.String({
+					description: "Source path. Local for upload; remote for download.",
 				}),
-			),
-			reason: Type.Optional(
-				Type.String({
-					description: "Short plain-English explanation of intent, shown to the user.",
+				destination: Type.String({
+					description: "Destination path. Remote for upload; local for download.",
 				}),
-			),
-		}),
+				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.",
+					}),
+				),
+			}),
+		]),
 
 		async execute(_toolCallId, params, sig, onUpdate, ctx) {
-			const { command, reason } = params;
-			const sudo = params.sudo === true;
+			const operation = normalizeOperation(params);
+			const { action, command, destination, direction, reason, recursive, source, sudo } =
+				operation;
+
+			if (action === "file" && (!source || !destination)) {
+				return {
+					content: [{ type: "text", text: "ssh_run failed: source and destination are required" }],
+					details: makeDetails(command, params.host, false, reason, {
+						outcome: "error",
+						errorKind: "execution",
+					}),
+					isError: true,
+				};
+			}
 
 			let spec: HostSpec;
 			try {
@@ -287,7 +407,7 @@ export default function (pi: ExtensionAPI): void {
 
 			const mode = getUnattendedMode(pi.events);
 			const yolo = mode === "yolo";
-			if (mode === "afk") {
+			if (action === "command" && mode === "afk") {
 				return {
 					content: [{ type: "text", text: "ssh_run denied immediately — AFK mode is active." }],
 					details: makeDetails(command, host, sudo, reason, {
@@ -327,12 +447,26 @@ export default function (pi: ExtensionAPI): void {
 				...(needLogin ? (["login"] as const) : []),
 				...(needSudo ? (["sudo"] as const) : []),
 			];
+			const transferDecision =
+				action === "file" ? transferApprovalDecision(mode, needLogin) : "ask";
+			if (transferDecision === "deny") {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "ssh_run file transfer denied — unattended mode cannot enter a missing SSH login password.",
+						},
+					],
+					details: makeDetails(command, host, false, reason, {
+						outcome: "denied",
+						cancellationKind: "denied",
+					}),
+				};
+			}
 
 			const body = [
-				reason?.trim() ? `Intent: ${reason.trim()}` : "No reason provided by AI",
-				`Host: ${host}${spec.port ? ` (port ${spec.port})` : ""}`,
-				`Command: ${sudo ? "sudo " : ""}${command}`,
-				...(keyOk && !creds.loginPassword ? ["(key-based auth — no login password needed)"] : []),
+				...approvalBody(operation, host, spec.port),
+				...(keyOk && !creds.loginPassword ? ["Auth: SSH key (no password)"] : []),
 			];
 
 			const collected: { login?: string; sudo?: string } = {};
@@ -345,29 +479,49 @@ export default function (pi: ExtensionAPI): void {
 			// the confirm overlay entirely (visible notify below). Privileged commands
 			// (sudo:true, or a sudo/su/doas/pkexec token in the command text) are never
 			// auto-approved — they always re-confirm.
-			const privileged = sudo || commandEscalatesPrivilege(command);
+			const privileged = action === "command" && (sudo || commandEscalatesPrivilege(command));
 			const alreadyApproved =
-				!privileged && hostApproved(approvedHosts, key) && promptFor.length === 0;
+				action === "command" &&
+				!privileged &&
+				hostApproved(approvedHosts, key) &&
+				promptFor.length === 0;
 			if (alreadyApproved) {
 				ctx.ui.notify(`🔐 ssh_run auto-approved — ${host} allowed this session`, "warning");
+			} else if (transferDecision === "allow") {
+				ctx.ui.notify(
+					`⚠ ssh_run file transfer auto-approved — ${mode.toUpperCase()} warning policy`,
+					"warning",
+				);
 			}
 
 			const runOverlay = (): Promise<OverlayResult> =>
 				withAgentBlock(pi.events, "ssh_run", "SSH approval required", async () => {
-					if ((yolo || alreadyApproved) && promptFor.length === 0) {
+					if ((transferDecision === "allow" || yolo || alreadyApproved) && promptFor.length === 0) {
 						return { action: "approved", password: "" } as OverlayResult;
 					}
 					// Confirm-only when no password is missing.
 					if (promptFor.length === 0) {
 						return showOverlay(ctx.ui, {
 							mode: "confirm",
-							title: "🔐 SSH COMMAND REQUEST",
+							title:
+								action === "file"
+									? `⚠ SSH ${direction === "download" ? "DOWNLOAD" : "UPLOAD"}`
+									: "🔐 SSH COMMAND REQUEST",
 							body,
-							accent: sudo ? "error" : "accent",
+							accent: sudo ? "error" : action === "file" ? "warning" : "accent",
 							timeoutMs: PROMPT_TIMEOUT_MS,
 							choices: [
-								{ value: "yes", label: "Allow", description: "Run the command" },
-								{ value: "no", label: "Deny", description: "Block the command" },
+								{
+									value: "yes",
+									label: "Allow",
+									description:
+										action === "file" ? "Copy to destination (may overwrite)" : "Run the command",
+								},
+								{
+									value: "no",
+									label: "Deny",
+									description: action === "file" ? "Cancel transfer" : "Block the command",
+								},
 							],
 						});
 					}
@@ -377,9 +531,12 @@ export default function (pi: ExtensionAPI): void {
 						const label = stage === "login" ? "SSH login password" : "Remote sudo password";
 						last = await showOverlay(ctx.ui, {
 							mode: "sudo",
-							title: "🔐 SSH COMMAND REQUEST",
+							title:
+								action === "file"
+									? `⚠ SSH ${direction === "download" ? "DOWNLOAD" : "UPLOAD"}`
+									: "🔐 SSH COMMAND REQUEST",
 							body: [...body, `Enter: ${label}`],
-							accent: sudo ? "error" : "accent",
+							accent: sudo ? "error" : action === "file" ? "warning" : "accent",
 							timeoutMs: PROMPT_TIMEOUT_MS,
 							maxPasswordAttempts: MAX_PASSWORD_ATTEMPTS,
 							passwordLabel: `${label}:`,
@@ -410,8 +567,9 @@ export default function (pi: ExtensionAPI): void {
 				return r;
 			}
 
-			// Remember this host's approval until the TTL lapses (refreshed each call).
-			approvedHosts.set(key, Date.now() + APPROVAL_TTL_MS);
+			// File transfers remain warning-level: normal mode asks every time,
+			// AFK denies above, and YOLO may approve when no password is missing.
+			if (action === "command") approvedHosts.set(key, Date.now() + APPROVAL_TTL_MS);
 
 			// Persist newly-entered passwords in the session cache.
 			const loginPassword = creds.loginPassword ?? collected.login;
@@ -421,17 +579,47 @@ export default function (pi: ExtensionAPI): void {
 				...(sudoPassword ? { sudoPassword } : {}),
 			});
 
-			updatePresentation(onUpdate, command, host, sudo, reason, "running");
+			let spinnerFrame = 0;
+			const updateTransferPresentation = () => {
+				const verb = direction === "download" ? "Downloading from" : "Uploading to";
+				updatePresentation(
+					onUpdate,
+					command,
+					host,
+					sudo,
+					reason,
+					"running",
+					`${SPINNER[spinnerFrame] ?? ""} ${verb} ${host}…`,
+				);
+			};
+			if (action === "file") updateTransferPresentation();
+			else updatePresentation(onUpdate, command, host, sudo, reason, "running");
+			// ponytail: spinner shows liveness only; SCP has no stable byte-progress API.
+			// Use an SFTP client with byte callbacks if percentage progress is needed.
+			const spinnerTimer =
+				action === "file" && onUpdate
+					? setInterval(() => {
+							spinnerFrame = (spinnerFrame + 1) % SPINNER.length;
+							updateTransferPresentation();
+						}, SPINNER_INTERVAL_MS)
+					: undefined;
 
 			let result: { stdout: string; stderr: string; code: number } | undefined;
 			try {
-				result = await runSsh(spec, command, {
-					controlPath,
-					...(loginPassword ? { loginPassword } : {}),
-					sudo,
-					...(sudo ? { sudoPassword: sudoPassword ?? "" } : {}),
-					...(sig ? { signal: sig } : {}),
-				});
+				result =
+					action === "file"
+						? await runTransfer(spec, direction ?? "upload", source, destination, recursive, {
+								controlPath,
+								...(loginPassword ? { loginPassword } : {}),
+								...(sig ? { signal: sig } : {}),
+							})
+						: await runSsh(spec, command, {
+								controlPath,
+								...(loginPassword ? { loginPassword } : {}),
+								sudo,
+								...(sudo ? { sudoPassword: sudoPassword ?? "" } : {}),
+								...(sig ? { signal: sig } : {}),
+							});
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
 				return {
@@ -447,6 +635,8 @@ export default function (pi: ExtensionAPI): void {
 					),
 					isError: sig?.aborted !== true,
 				};
+			} finally {
+				if (spinnerTimer) clearInterval(spinnerTimer);
 			}
 
 			if (!result) {
@@ -518,11 +708,7 @@ export default function (pi: ExtensionAPI): void {
 			};
 		},
 
-		renderCall: ((
-			args: { command: string; host: string; sudo?: boolean; reason?: string },
-			theme: ThemeLike,
-			renderCtx: RenderContextLike,
-		) => {
+		renderCall: ((args: SshParams, theme: ThemeLike, renderCtx: RenderContextLike) => {
 			resolveBaseBackground(theme);
 			const text = renderCtx.lastComponent ?? new Text("", 0, 0);
 			if (
@@ -532,12 +718,13 @@ export default function (pi: ExtensionAPI): void {
 			)
 				return text;
 
-			const command = safeOneLine(args.command) || "(empty command)";
+			const operation = normalizeOperation(args);
+			const command = safeOneLine(operation.command) || "(empty command)";
 			const host = safeOneLine(args.host);
-			const prefix = args.sudo ? "sudo " : "";
+			const prefix = operation.sudo ? "sudo " : "";
 			text.setText(
 				fillToolBackground(
-					`${theme.fg("toolTitle", theme.bold("ssh"))} ${theme.fg("dim", host)} ${theme.fg("muted", prefix + command)}`,
+					`${theme.fg("toolTitle", theme.bold(operation.action === "file" ? "ssh file" : "ssh"))} ${theme.fg("dim", host)} ${theme.fg("muted", prefix + command)}`,
 				),
 			);
 			return text;

package/src/lib.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import {
+	baseScpArgs,
 	baseSshArgs,
 	commandEscalatesPrivilege,
 	controlPathFor,
@@ -12,7 +13,10 @@ import {
 	parseHost,
 	parseSshConfig,
 	remoteCommand,
+	remoteTransferPath,
 	shellQuote,
+	transferApprovalDecision,
+	transferArgs,
 	truncate,
 } from "./lib.ts";
 
@@ -94,6 +98,53 @@ describe("baseSshArgs", () => {
 	});
 });
 
+describe("transfer unattended approval", () => {
+	it("treats transfer as warning-level in AFK and YOLO", () => {
+		expect(transferApprovalDecision("off", false)).toBe("ask");
+		expect(transferApprovalDecision("afk", false)).toBe("allow");
+		expect(transferApprovalDecision("yolo", false)).toBe("allow");
+	});
+
+	it("denies unattended transfer when a login password is missing", () => {
+		expect(transferApprovalDecision("afk", true)).toBe("deny");
+		expect(transferApprovalDecision("yolo", true)).toBe("deny");
+	});
+});
+
+describe("SCP transfer arguments", () => {
+	it("builds upload and download endpoints", () => {
+		const spec = { user: "deploy", host: "example.com", port: 2222 };
+		expect(remoteTransferPath(spec, "/srv/app file")).toBe("deploy@example.com:/srv/app file");
+		expect(transferArgs(spec, "upload", "./build", "/srv/app")).toEqual([
+			"./build",
+			"deploy@example.com:/srv/app",
+		]);
+		expect(transferArgs(spec, "download", "/var/log/app.log", "./app.log")).toEqual([
+			"deploy@example.com:/var/log/app.log",
+			"./app.log",
+		]);
+		expect(baseScpArgs(spec, "/tmp/control.sock", true)).toEqual([
+			"-o",
+			"ControlMaster=auto",
+			"-o",
+			"ControlPath=/tmp/control.sock",
+			"-o",
+			"ControlPersist=120",
+			"-o",
+			"ConnectTimeout=10",
+			"-o",
+			"StrictHostKeyChecking=accept-new",
+			"-P",
+			"2222",
+			"-r",
+		]);
+	});
+
+	it("brackets IPv6 hosts for SCP remote-path syntax", () => {
+		expect(remoteTransferPath({ user: "root", host: "::1" }, "/tmp/x")).toBe("root@[::1]:/tmp/x");
+	});
+});
+
 describe("remoteCommand + shellQuote", () => {
 	it("returns the command unchanged without sudo", () => {
 		expect(remoteCommand("whoami", false)).toBe("whoami");

package/src/lib.ts

@@ -65,6 +65,18 @@ export interface SshResult {
 	code: number;
 }
 
+export type TransferDirection = "upload" | "download";
+export type UnattendedMode = "off" | "afk" | "yolo";
+
+/** Warning-level transfer policy. Password prompts cannot run unattended. */
+export function transferApprovalDecision(
+	mode: UnattendedMode,
+	loginPasswordMissing: boolean,
+): "ask" | "allow" | "deny" {
+	if (mode === "off") return "ask";
+	return loginPasswordMissing ? "deny" : "allow";
+}
+
 // ── Host parsing ─────────────────────────────────────────────────────────────
 
 /** Parse `[user@]host[:port]` into parts. Throws on empty host. */
@@ -158,7 +170,7 @@ export function controlPathFor(spec: HostSpec): string {
 
 /** Base ssh options shared by every invocation: multiplexing + timeouts +
  * non-interactive prompts (BatchMode is toggled by the caller). */
-export function baseSshArgs(spec: HostSpec, controlPath: string): string[] {
+function connectionArgs(spec: HostSpec, controlPath: string, portFlag: "-p" | "-P"): string[] {
 	const args = [
 		"-o",
 		"ControlMaster=auto",
@@ -171,10 +183,36 @@ export function baseSshArgs(spec: HostSpec, controlPath: string): string[] {
 		"-o",
 		"StrictHostKeyChecking=accept-new",
 	];
-	if (spec.port !== undefined) args.push("-p", String(spec.port));
+	if (spec.port !== undefined) args.push(portFlag, String(spec.port));
 	return args;
 }
 
+export function baseSshArgs(spec: HostSpec, controlPath: string): string[] {
+	return connectionArgs(spec, controlPath, "-p");
+}
+
+/** SCP shares SSH connection options but uses uppercase `-P` for its port. */
+export function baseScpArgs(spec: HostSpec, controlPath: string, recursive: boolean): string[] {
+	return [...connectionArgs(spec, controlPath, "-P"), ...(recursive ? ["-r"] : [])];
+}
+
+/** Format SCP's remote endpoint, bracketing IPv6 literals. */
+export function remoteTransferPath(spec: HostSpec, path: string): string {
+	const host = spec.host.includes(":") ? `[${spec.host}]` : spec.host;
+	return `${spec.user ? `${spec.user}@` : ""}${host}:${path}`;
+}
+
+export function transferArgs(
+	spec: HostSpec,
+	direction: TransferDirection,
+	source: string,
+	destination: string,
+): string[] {
+	return direction === "upload"
+		? [source, remoteTransferPath(spec, destination)]
+		: [remoteTransferPath(spec, source), destination];
+}
+
 /** Wrap a command for optional remote sudo. `sudo -S -p ''` reads the sudo
  * password from stdin with no prompt echo; the command runs under `sh -c`. */
 export function remoteCommand(command: string, sudo: boolean): string {
@@ -238,7 +276,7 @@ export function truncate(
 	const kept = lines.slice(0, maxLines);
 	let result = kept.join("\n");
 	if (Buffer.byteLength(result, "utf8") > maxBytes) {
-		result = Buffer.from(result, "utf8").slice(0, maxBytes).toString("utf8");
+		result = Buffer.from(result, "utf8").subarray(0, maxBytes).toString("utf8");
 	}
 	return { text: result, truncated: true };
 }
@@ -308,6 +346,25 @@ export interface RunOptions {
  * in `sshpass -e` (password via env, not argv). When `sudo` is set, the command
  * is wrapped in `sudo -S` and `sudoPassword` is written to the remote stdin.
  */
+export function runTransfer(
+	spec: HostSpec,
+	direction: TransferDirection,
+	source: string,
+	destination: string,
+	recursive: boolean,
+	opts: Pick<RunOptions, "controlPath" | "loginPassword" | "signal">,
+): Promise<SshResult> {
+	const scpArgs = [
+		...baseScpArgs(spec, opts.controlPath, recursive),
+		"--",
+		...transferArgs(spec, direction, source, destination),
+	];
+	const bin = opts.loginPassword ? "sshpass" : "scp";
+	const args = opts.loginPassword ? ["-e", "scp", ...scpArgs] : scpArgs;
+	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> {
 	const remote = remoteCommand(command, opts.sudo === true);
 	const sshArgs = [...baseSshArgs(spec, opts.controlPath), hostTarget(spec), remote];
@@ -321,30 +378,36 @@ export function runSsh(spec: HostSpec, command: string, opts: RunOptions): Promi
 		env = { ...process.env, SSHPASS: opts.loginPassword };
 	}
 
+	// Remote sudo reads its password from stdin (first line); anything else
+	// closes stdin so the remote command sees EOF.
+	const stdin = opts.sudo && opts.sudoPassword !== undefined ? `${opts.sudoPassword}\n` : undefined;
+	return spawnResult(bin, args, env, opts.signal, opts.sudo ? filterSudoPrompt : undefined, stdin);
+}
+
+function spawnResult(
+	bin: string,
+	args: string[],
+	env: NodeJS.ProcessEnv,
+	sig?: AbortSignal,
+	filterStderr?: (value: string) => string,
+	stdin?: string,
+): Promise<SshResult> {
 	return new Promise((resolve, reject) => {
 		const proc = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"], env });
 		let stdout = "";
 		let stderr = "";
-
 		proc.stdout.on("data", (c: Buffer) => {
 			stdout += c.toString();
 		});
 		proc.stderr.on("data", (c: Buffer) => {
-			const filtered = opts.sudo ? filterSudoPrompt(c.toString()) : c.toString();
-			if (filtered) stderr += filtered;
+			const value = filterStderr ? filterStderr(c.toString()) : c.toString();
+			if (value) stderr += value;
 		});
-
 		proc.on("error", reject);
 		proc.on("close", (code) => resolve({ stdout, stderr, code: code ?? 1 }));
-
-		// Remote sudo reads its password from stdin (first line); anything else
-		// closes stdin so the remote command sees EOF.
-		if (opts.sudo && opts.sudoPassword !== undefined) {
-			proc.stdin.write(`${opts.sudoPassword}\n`);
-		}
+		if (stdin) proc.stdin.write(stdin);
 		proc.stdin.end();
-
-		signal(opts.signal, proc, reject);
+		signal(sig, proc, reject);
 	});
 }