/**
 * 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;
}
