1 files changed, 111 insertions, 0 deletions
diff --git a/packages/ssh/src/errors.ts b/packages/ssh/src/errors.ts
new file mode 100644
index 0000000..fab9d32
--- /dev/null
+++ b/packages/ssh/src/errors.ts
@@ -0,0 +1,111 @@
+/**
+ * Error mapping — translate ssh2/SFTP errors onto node:fs-style errors.
+ *
+ * The bundled tools (`read_file`/`write_file`/`edit_file`) branch on
+ * `(err as NodeJS.ErrnoException).code` (e.g. `"ENOENT"`). SFTP/ssh2 errors do
+ * NOT carry that shape, so the `SshExecBackend` routes every throw through this
+ * mapping first. Pure: input → output, no I/O, zero mocks (plan §4.3).
+ *
+ * ssh2 SFTP status codes (RFC 4254 §9.1) → node:fs errno mapping, mirroring how
+ * OpenSSH's own sftp client and node:fs classify the same conditions. Only the
+ * cases the tools actually react to are mapped; everything else becomes
+ * `EIO`-ish (a generic I/O error) so the tool's generic catch still works.
+ */
+
+/** A node:fs-style error carrying a `.code` errno string. */
+export interface FsError extends Error {
+	readonly code: string;
+}
+
+/** Build a node:fs-style error with a `.code`. Pure. */
+export function fsError(code: string, message: string): FsError {
+	const err = new Error(message) as FsError;
+	(err as { code: string }).code = code;
+	return err;
+}
+
+/**
+ * Map a numeric SFTP status code (SSH_FXP_*) onto a node:fs errno string.
+ * Returns `undefined` when the code has no meaningful errno analog (caller
+ * falls back to a generic I/O error). Pure.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc4254#section-9.1
+ */
+export function sftpStatusToErrno(status: number): string | undefined {
+	// SSH_FX_NO_SUCH_FILE (3) → ENOENT — the common case (missing path).
+	if (status === 3) return "ENOENT";
+	// SSH_FX_PERMISSION_DENIED (4) → EACCES — read/parse this path.
+	if (status === 4) return "EACCES";
+	// SSH_FX_FILE_ALREADY_EXISTS (11) → EEXIST.
+	if (status === 11) return "EEXIST";
+	// SSH_FX_NOT_A_DIRECTORY (20) → ENOTDIR.
+	if (status === 20) return "ENOTDIR";
+	return undefined;
+}
+
+/**
+ * Normalize a ssh2/SFTP error into a node:fs-style `FsError`. Inspects the
+ * ssh2 error's `code` (an SSH_FXP_* status string like `"SFTP_NO_SUCH_FILE"`
+ * or a numeric `.code`/`.desc`) and maps it. Anything unrecognized → `EIO`.
+ *
+ * ssh2 surfaces SFTP failures two ways depending on the operation:
+ *  - callback `err` whose `.code` is an `"SFTP_*"` status string, OR a numeric
+ *    code on the error object;
+ *  - `sftp.exists(cb)` which gives no error — handled separately by the caller.
+ *
+ * Pure: takes the thrown value, returns an `FsError`. Never throws.
+ */
+export function mapSshError(err: unknown, context: string): FsError {
+	const message = err instanceof Error ? err.message : String(err);
+
+	// ssh2 SFTP errors often carry a `.code` that is an SSH_FXP_* string.
+	const code = (err as { code?: unknown } | null)?.code;
+	if (typeof code === "string") {
+		const mapped = sshCodeStringToErrno(code);
+		if (mapped !== undefined) return fsError(mapped, `${context}: ${message}`);
+		// ssh2 also surfaces raw numeric SFTP status on `.code`.
+	}
+	if (typeof code === "number") {
+		const mapped = sftpStatusToErrno(code);
+		if (mapped !== undefined) return fsError(mapped, `${context}: ${message}`);
+	}
+
+	// Some ssh2 errors embed the SFTP status code as `.desc`/message text; sniff
+	// the human-readable text for the common markers as a last resort.
+	if (message.includes("No such file") || message.includes("ENOENT")) {
+		return fsError("ENOENT", `${context}: ${message}`);
+	}
+	if (message.includes("Permission denied") || message.includes("EACCES")) {
+		return fsError("EACCES", `${context}: ${message}`);
+	}
+	if (message.includes("not a directory") || message.includes("ENOTDIR")) {
+		return fsError("ENOTDIR", `${context}: ${message}`);
+	}
+
+	// Host-key / connect failures are surfaced as ECONNREFUSED-ish so the tool's
+	// generic error path still renders them clearly. Default: generic I/O error.
+	if (message.includes("HOST KEY CHANGED") || message.includes("host key")) {
+		return fsError("EHOSTUNREACH", `${context}: ${message}`);
+	}
+	return fsError("EIO", `${context}: ${message}`);
+}
+
+/**
+ * Map an ssh2 `"SFTP_*"` status-code string (e.g. `"SFTP_STATUS_NO_SUCH_FILE"`,
+ * `"NO_SUCH_FILE"`) onto a node:fs errno. ssh2's exact string spelling varies
+ * across versions, so match case-insensitively on the stable fragment.
+ * Returns `undefined` when no analog. Pure.
+ */
+function sshCodeStringToErrno(code: string): string | undefined {
+	const c = code.toUpperCase();
+	if (c.includes("NO_SUCH_FILE")) return "ENOENT";
+	if (c.includes("PERMISSION_DENIED")) return "EACCES";
+	if (
+		c.includes("FILE_ALREADY_EXISTS") ||
+		(c.includes("FAILURE") === false && c.includes("EXIST"))
+	) {
+		return "EEXIST";
+	}
+	if (c.includes("NOT_A_DIRECTORY")) return "ENOTDIR";
+	return undefined;
+}