feat: Add CommandFailedException for COPY/MOVE and APPEND, exposing command name, status, server text, and parsed completion code.

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

lib/Client/CommandFailedException.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXM\ProviderImap\Client;
+
+/**
+ * A server-reported unsuccessful tagged command completion.
+ */
+final class CommandFailedException extends ImapException
+{
+    /**
+     * @param ?array{name:string, arguments:list<string>, text:string} $responseCode
+     */
+    public function __construct(
+        private readonly string $command,
+        private readonly string $status,
+        private readonly string $text,
+        private readonly ?array $responseCode = null,
+    ) {
+        parent::__construct($command . ' failed: ' . $text);
+    }
+
+    public function command(): string
+    {
+        return $this->command;
+    }
+
+    public function status(): string
+    {
+        return $this->status;
+    }
+
+    public function text(): string
+    {
+        return $this->text;
+    }
+
+    /**
+     * The code from the tagged completion, if present.
+     *
+     * @return ?array{name:string, arguments:list<string>, text:string}
+     */
+    public function responseCode(): ?array
+    {
+        return $this->responseCode;
+    }
+}