Centralize file-open error message formatting

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

CONTRIBUTING.md

@@ -133,6 +133,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_extension_request_internal_reuse.py` (extension request-helper internal reuse of shared model request helpers),
   - `tests/test_extension_route_constants_usage.py` (extension manager route-constant usage enforcement),
   - `tests/test_extract_payload_helper_usage.py` (extract start-payload helper usage enforcement),
+  - `tests/test_file_open_error_helper_usage.py` (shared file-open error-message helper usage enforcement),
   - `tests/test_file_path_display_helper_import_boundary.py` (shared file-path display helper import boundary enforcement),
   - `tests/test_file_path_display_helper_usage.py` (shared file-path display helper usage enforcement),
   - `tests/test_guardrail_ast_utils.py` (shared AST guard utility contract),

hyperbrowser/client/file_utils.py

@@ -7,6 +7,7 @@
 from hyperbrowser.type_utils import is_plain_int, is_plain_string
 
 _MAX_FILE_PATH_DISPLAY_LENGTH = 200
+_DEFAULT_OPEN_ERROR_MESSAGE_PREFIX = "Failed to open file at path"
 
 
 def format_file_path_for_error(
@@ -43,6 +44,23 @@ def format_file_path_for_error(
     return f"{sanitized_path[:truncated_length]}..."
 
 
+def build_open_file_error_message(file_path: object, *, prefix: str) -> str:
+    normalized_prefix = prefix
+    if not is_plain_string(normalized_prefix):
+        normalized_prefix = _DEFAULT_OPEN_ERROR_MESSAGE_PREFIX
+    else:
+        try:
+            stripped_prefix = normalized_prefix.strip()
+        except Exception:
+            stripped_prefix = _DEFAULT_OPEN_ERROR_MESSAGE_PREFIX
+        if not is_plain_string(stripped_prefix) or not stripped_prefix:
+            normalized_prefix = _DEFAULT_OPEN_ERROR_MESSAGE_PREFIX
+        else:
+            normalized_prefix = stripped_prefix
+    file_path_display = format_file_path_for_error(file_path)
+    return f"{normalized_prefix}: {file_path_display}"
+
+
 def _normalize_file_path_text(file_path: Union[str, PathLike[str]]) -> str:
     try:
         normalized_path = os.fspath(file_path)

hyperbrowser/client/managers/async_manager/extension.py

@@ -1,6 +1,6 @@
 from typing import List
 
-from ...file_utils import open_binary_file
+from ...file_utils import build_open_file_error_message, open_binary_file
 from ..extension_create_utils import normalize_extension_create_input
 from ..extension_operation_metadata import EXTENSION_OPERATION_METADATA
 from ..extension_request_utils import (
@@ -27,7 +27,10 @@ async def create(self, params: CreateExtensionParams) -> ExtensionResponse:
 
         with open_binary_file(
             file_path,
-            open_error_message=f"Failed to open extension file at path: {file_path}",
+            open_error_message=build_open_file_error_message(
+                file_path,
+                prefix="Failed to open extension file at path",
+            ),
         ) as extension_file:
             return await create_extension_resource_async(
                 client=self._client,

hyperbrowser/client/managers/session_upload_utils.py

@@ -7,6 +7,7 @@
 from hyperbrowser.type_utils import is_plain_string, is_string_subclass_instance
 
 from ..file_utils import (
+    build_open_file_error_message,
     ensure_existing_file_path,
     format_file_path_for_error,
     open_binary_file,
@@ -72,7 +73,10 @@ def open_upload_files_from_input(
     if file_path is not None:
         with open_binary_file(
             file_path,
-            open_error_message=f"Failed to open upload file at path: {file_path}",
+            open_error_message=build_open_file_error_message(
+                file_path,
+                prefix="Failed to open upload file at path",
+            ),
         ) as opened_file:
             yield {"file": opened_file}
         return

hyperbrowser/client/managers/sync_manager/extension.py

@@ -1,6 +1,6 @@
 from typing import List
 
-from ...file_utils import open_binary_file
+from ...file_utils import build_open_file_error_message, open_binary_file
 from ..extension_create_utils import normalize_extension_create_input
 from ..extension_operation_metadata import EXTENSION_OPERATION_METADATA
 from ..extension_request_utils import (
@@ -27,7 +27,10 @@ def create(self, params: CreateExtensionParams) -> ExtensionResponse:
 
         with open_binary_file(
             file_path,
-            open_error_message=f"Failed to open extension file at path: {file_path}",
+            open_error_message=build_open_file_error_message(
+                file_path,
+                prefix="Failed to open extension file at path",
+            ),
         ) as extension_file:
             return create_extension_resource(
                 client=self._client,

tests/test_architecture_marker_usage.py

@@ -50,6 +50,7 @@
     "tests/test_model_request_wrapper_internal_reuse.py",
     "tests/test_tool_mapping_reader_usage.py",
     "tests/test_display_helper_usage.py",
+    "tests/test_file_open_error_helper_usage.py",
     "tests/test_file_path_display_helper_import_boundary.py",
     "tests/test_file_path_display_helper_usage.py",
     "tests/test_binary_file_open_helper_usage.py",

tests/test_file_open_error_helper_usage.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+OPEN_ERROR_HELPER_MODULES = (
+    "hyperbrowser/client/managers/session_upload_utils.py",
+    "hyperbrowser/client/managers/sync_manager/extension.py",
+    "hyperbrowser/client/managers/async_manager/extension.py",
+)
+
+
+def test_file_open_error_messages_use_shared_helper():
+    for module_path in OPEN_ERROR_HELPER_MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "build_open_file_error_message(" in module_text
+        assert "open_error_message=f\"" not in module_text

tests/test_file_utils.py

@@ -4,6 +4,7 @@
 
 import hyperbrowser.client.file_utils as file_utils
 from hyperbrowser.client.file_utils import (
+    build_open_file_error_message,
     ensure_existing_file_path,
     format_file_path_for_error,
     open_binary_file,
@@ -321,6 +322,33 @@ def __fspath__(self) -> str:
     assert format_file_path_for_error(_PathLike()) == "/tmp/path-value"
 
 
+def test_build_open_file_error_message_uses_prefix_and_sanitized_path():
+    message = build_open_file_error_message(
+        "bad\tpath.txt",
+        prefix="Failed to open upload file at path",
+    )
+
+    assert message == "Failed to open upload file at path: bad?path.txt"
+
+
+def test_build_open_file_error_message_uses_default_prefix_for_non_string():
+    message = build_open_file_error_message(
+        "/tmp/path.txt",
+        prefix=123,  # type: ignore[arg-type]
+    )
+
+    assert message == "Failed to open file at path: /tmp/path.txt"
+
+
+def test_build_open_file_error_message_uses_default_prefix_for_blank_string():
+    message = build_open_file_error_message(
+        "/tmp/path.txt",
+        prefix="   ",
+    )
+
+    assert message == "Failed to open file at path: /tmp/path.txt"
+
+
 def test_ensure_existing_file_path_wraps_invalid_path_os_errors(monkeypatch):
     def raising_exists(path: str) -> bool:
         raise OSError("invalid path")