Polish extension add URL-install tests and docs

Author: Copilot

src/specify_cli/__init__.py

@@ -3649,10 +3649,10 @@ def extension_add(
                     from specify_cli.authentication.http import open_url as _open_url
 
                     with _open_url(from_url, timeout=60) as response:
-                        zip_data = response.read()
+                        zip_bytes = response.read()
 
                     # Install from downloaded ZIP
-                    manifest = manager.install_from_zip_bytes(zip_data, speckit_version, priority=priority)
+                    manifest = manager.install_from_zip_bytes(zip_bytes, speckit_version, priority=priority)
                 except urllib.error.URLError as e:
                     console.print(f"[red]Error:[/red] Failed to download from {from_url}: {e}")
                     raise typer.Exit(1)

src/specify_cli/extensions.py

@@ -1225,16 +1225,32 @@ def install_from_zip(
             ValidationError: If manifest is invalid or priority is invalid
             CompatibilityError: If extension is incompatible
         """
-        with zip_path.open("rb") as zip_file:
-            return self.install_from_zip_bytes(zip_file.read(), speckit_version, priority=priority)
+        try:
+            with zip_path.open("rb") as zip_file:
+                return self.install_from_zip_bytes(zip_file.read(), speckit_version, priority=priority)
+        except OSError as e:
+            raise ValidationError(f"Failed to read ZIP file {zip_path}: {e}") from e
 
     def install_from_zip_bytes(
         self,
         zip_bytes: bytes,
         speckit_version: str,
         priority: int = 10,
     ) -> ExtensionManifest:
-        """Install extension from ZIP bytes."""
+        """Install extension from ZIP bytes.
+
+        Args:
+            zip_bytes: ZIP archive content.
+            speckit_version: Current spec-kit version.
+            priority: Resolution priority (lower = higher precedence, default 10).
+
+        Returns:
+            Installed extension manifest.
+
+        Raises:
+            ValidationError: If manifest is invalid or priority is invalid.
+            CompatibilityError: If extension is incompatible.
+        """
         # Validate priority early
         if priority < 1:
             raise ValidationError("Priority must be a positive integer (1 or higher)")

tests/test_extensions.py

@@ -3510,28 +3510,28 @@ def test_add_from_url_installs_from_downloaded_bytes(self, tmp_path):
         zip_payload = b"fake-zip-bytes"
         install_args = {}
 
-        class _Resp:
+        class _MockHTTPResponse:
             def __enter__(self):
                 return self
 
-            def __exit__(self, *_args):
+            def __exit__(self, exc_type, exc_val, exc_tb):
                 return False
 
             def read(self):
                 return zip_payload
 
-        def _install_from_zip_bytes(self_obj, payload, _speckit_version, priority=10):
+        def _install_from_zip_bytes(_self, payload, _speckit_version, priority=10):
             install_args["payload"] = payload
             install_args["priority"] = priority
             return fake_manifest
 
         with patch.object(Path, "cwd", return_value=project_dir), \
-             patch("specify_cli.authentication.http.open_url", return_value=_Resp()), \
+             patch("specify_cli.authentication.http.open_url", return_value=_MockHTTPResponse()), \
              patch.object(ExtensionManager, "install_from_zip_bytes", _install_from_zip_bytes), \
              patch.object(ExtensionManager, "install_from_zip", side_effect=AssertionError("legacy path install should not be used")):
             result = runner.invoke(
                 app,
-                ["extension", "add", "../../evil", "--from", "https://example.com/ext.zip"],
+                ["extension", "add", "ignored-extension-name", "--from", "https://example.com/ext.zip"],
                 catch_exceptions=True,
             )