wondersearch-cli 0.1.0__py3-none-any.whl

wondersearch_cli/__init__.py

@@ -0,0 +1,5 @@
+"""WonderSearch command-line client."""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

wondersearch_cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+raise SystemExit(main())

wondersearch_cli/_messages.py

@@ -0,0 +1,102 @@
+"""Local error messages. Backend response messages are preserved verbatim."""
+
+MESSAGES = {
+    "unreadable_file": "Cannot read file or directory.",
+    "invalid_signin_callback": "Invalid sign-in callback. Return to your terminal.",
+    "api_url_must_be_a_string": "API URL must be a string.",
+    "api_url_must_be_an_https_origin_http": "API URL must be an HTTPS origin (HTTP is permitted only on loopback).",
+    "configuration_recovery_paths_must_not_contain_symlinks": "Configuration/recovery paths must not contain symlinks.",
+    "invalid_profile_name": "Invalid profile name.",
+    "configuration_profiles_must_be_an_object": "Configuration profiles must be an object.",
+    "profile_settings_must_contain_string_values": "Profile settings must contain string values.",
+    "private_configuration_recovery_file_must_have_mode_0600": "Private configuration/recovery file must have mode 0600.",
+    "set_only_one_of_wondersearch_api_key_and": "Set only one of WONDERSEARCH_API_KEY and WONDERSEARCH_ACCESS_TOKEN.",
+    "invalid_saved_credential_record_log_in_again": "Invalid saved credential record. Log in again.",
+    "log_in_or_provide_credentials_for_this_api": "Log in or provide credentials for this API origin.",
+    "cannot_read_private_configuration_recovery_file": "Cannot read private configuration/recovery file.",
+    "saved_credential_belongs_to_a_different_api_origin": "Saved credential belongs to a different API origin. Log in for this origin first.",
+    "unlock_or_configure_your_operating_system_credential_store": "Unlock or configure your operating system credential store, then run wondersearch login again. For automation, use WONDERSEARCH_API_KEY.",
+    "the_saved_session_is_invalid_run_wondersearch_login": "The saved session is invalid. Run wondersearch login again.",
+    "credential_paths_must_not_contain_symlinks": "Credential paths must not contain symlinks.",
+    "the_server_returned_an_invalid_sign_in_address": "The server returned an invalid sign-in address.",
+    "sign_in_timed_out_run_wondersearch_login_again": "Sign-in timed out. Run wondersearch login again.",
+    "sign_in_cancelled": "Sign-in cancelled.",
+    "your_session_has_expired_run_wondersearch_login_to": "Your session has expired. Run wondersearch login to sign in again.",
+    "browser_sign_in_is_unavailable_on_this_server": "Browser sign-in is unavailable on this server. Try again shortly, or use wondersearch login --api-key.",
+    "could_not_complete_sign_in_check_your_connection": "Could not complete sign-in. Check your connection and try again.",
+    "could_not_save_your_session_in_the_operating": "Could not save your session in the operating system credential store.",
+    "run_wondersearch_login_to_sign_in": "Run wondersearch login to sign in.",
+    "could_not_read_your_saved_session_unlock_your": "Could not read your saved session. Unlock your operating system credential store and try again.",
+    "the_session_was_revoked_but_local_cleanup_failed": "The session was revoked, but local cleanup failed. Unlock your credential store and run wondersearch logout again.",
+    "this_server_requires_a_different_cli_api_major": "This server requires a different CLI API major.",
+    "upgrade_wondersearch_cli_to_at_least_0": "Upgrade wondersearch-cli to at least {0}.",
+    "server_response_is_missing_required_fields_or_has": "Server response is missing required fields or has invalid field types.",
+    "operation_timed_out_accepted_server_work_continues": "Operation timed out; accepted server work continues.",
+    "expected_a_resource_uuid": "Expected a resource UUID.",
+    "complete_account_setup_in_the_console_first": "Complete account setup in the Console first.",
+    "sign_in_with_a_user_session_to_run": "Sign in with a user session to run this command. API keys cannot be used here.",
+    "api_request_failed": "API request failed.",
+    "unsafe_transfer_destination": "Unsafe transfer destination.",
+    "invalid_api_path": "Invalid API path.",
+    "server_returned_an_invalid_response": "Server returned an invalid response.",
+    "server_returned_invalid_pagination_data": "Server returned invalid pagination data.",
+    "repeated_pagination_cursor": "Repeated pagination cursor.",
+    "resource_is_missing_its_concurrency_etag": "Resource is missing its concurrency ETag.",
+    "server_returned_a_non_json_response": "Server returned a non-JSON response.",
+    "network_request_failed": "Network request failed.",
+    "processing_failed": "Processing failed.",
+    "replace_requires_exactly_one_file_and_no_recursive": "--replace requires exactly one file and no --recursive.",
+    "directories_require_recursive": "Directories require --recursive.",
+    "recovery_record_does_not_match_this_profile_origin": "Recovery record does not match this profile, origin, identity, workspace, and drive.",
+    "invalid_upload_recovery_record_restore_the_original_record": "Invalid upload recovery record. Restore the original record before resuming.",
+    "expected_a_supported_regular_file_of_1_through": "Expected a supported regular file of 1 through 1,000,000,000 bytes.",
+    "upload_bytes_are_incomplete_use_upload_resume_with": "Upload bytes are incomplete. Use upload resume with the original run ID.",
+    "source_changed_since_reservation_cannot_resume_this_upload": "Source changed since reservation; cannot resume this upload.",
+    "ambiguous_destination_folder": "Ambiguous destination folder: ",
+    "destination_folder_could_not_be_created_or_resolved": "Destination folder could not be created or resolved.",
+    "transfer_headers_must_be_strings": "Transfer headers must be strings.",
+    "unknown_transfer_transport": "Unknown transfer transport.",
+    "cannot_read_source_file": "Cannot read source file.",
+    "unsupported_command": "Unsupported command.",
+    "incorrect_number_of_command_arguments_see_help": "Incorrect number of command arguments. See --help.",
+    "use_either_a_positional_drive_or_drive_not": "Use either a positional drive or --drive, not both.",
+    "use_either_a_positional_workspace_or_workspace_not": "Use either a positional workspace or --workspace, not both.",
+    "deletion_revocation_requires_confirmation_use_yes_in_scripts": "Deletion/revocation requires confirmation; use --yes in scripts.",
+    "deletion_revocation_was_not_confirmed": "Deletion/revocation was not confirmed.",
+    "allowed_config_keys": "Allowed config keys: ",
+    "": ", ",
+    "provide_a_configuration_value": "Provide a configuration value.",
+    "list_limit_must_be_between_1_and_100": "List limit must be between 1 and 100.",
+    "search_timeout_must_be_between_1_and_20000": "Search timeout must be between 1 and 20000 milliseconds.",
+    "missing_command_argument_see_help": "Missing command argument. See --help.",
+    "processing_timeout_requires_wait": "--processing-timeout requires --wait.",
+    "dry_run_cannot_be_combined_with_wait": "--dry-run cannot be combined with --wait.",
+    "0_is_not_supported_for_this_command": "--{0} is not supported for this command.",
+    "select_an_organization_with_organization_or_config_set": "Select an organization with --organization or config set organization.",
+    "drive_is_not_accessible_in_the_selected_workspace": "Drive is not accessible in the selected workspace.",
+    "profile_names_must_contain_1_through_120_characters": "Profile names must contain 1 through 120 characters.",
+    "unknown_profile_create_it_with_login_profile_name": "Unknown profile. Create it with login --profile NAME or config set KEY VALUE --profile NAME.",
+    "waiting_interrupted_drive_0_continues_provisioning_check_it": "Waiting interrupted; drive {0} continues provisioning. Check it with drive get {1}.",
+    "idempotency_key_must_be_1_128_visible_ascii": "Idempotency key must be 1-128 visible ASCII characters.",
+    "input_ended_before_a_credential_was_provided": "Input ended before a credential was provided.",
+    "cannot_read_write_a_local_file_or_parse": "Cannot read/write a local file or parse its contents. Check paths, permissions, and encoding.",
+    "timeout_applies_only_to_browser_login": "--timeout applies only to browser login.",
+    "timeout_requires_wait": "--timeout requires --wait.",
+    "0_name_must_match_exactly_one_accessible_resource": "{0} name must match exactly one accessible resource; use its UUID.",
+    "this_api_key_is_scoped_to_a_different": "This API key is scoped to a different workspace.",
+    "drive_provisioning_failed": "Drive provisioning failed.",
+    "unknown_drive_provisioning_status": "Unknown drive provisioning status.",
+    "use_workspace_default_drive_get_or_set_drive": "Use workspace default-drive get or set <drive>.",
+    "use_upload_status_upload_id": "Use upload status <upload-id>.",
+    "use_upload_resume_run_id_wait": "Use upload resume <run-id> [--wait].",
+    "document_text_exceeds_2_000_000_bytes": "Document text exceeds 2,000,000 bytes.",
+    "timeouts_must_be_finite_and_positive": "Timeouts must be finite and positive.",
+    "select_a_workspace_with_workspace_or_workspace_use": "Select a workspace with --workspace or workspace use.",
+    "select_the_profile_for_this_api_origin_before": "Select the profile for this API origin before signing out.",
+    "choose_browser_sign_in_or_one_credential_type": "Choose browser sign-in or one credential type. Browser timeout must be at most 300 seconds.",
+    "provide_a_nonempty_credential_without_whitespace": "Provide a nonempty credential without whitespace.",
+}
+
+
+def local_message(code: str, *values: object) -> str:
+    return MESSAGES[code].format(*values)

wondersearch_cli/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

wondersearch_cli/api.py

@@ -0,0 +1,283 @@
+"""Bounded API calls and credential-isolated streaming transfers."""
+
+from ._messages import local_message
+
+import time
+import uuid
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+from ._version import __version__
+from .config import origin
+from .errors import CLIError, usage
+from .notices import notices
+
+
+def response_fields(value, **fields):
+    if not isinstance(value, dict) or any(
+        name not in value or not isinstance(value[name], expected)
+        for name, expected in fields.items()
+    ):
+        raise CLIError(
+            "invalid_response",
+            local_message("server_response_is_missing_required_fields_or_has"),
+            kind="transport",
+        )
+    return value
+
+
+def ident(value: str) -> str:
+    try:
+        return str(uuid.UUID(value))
+    except (ValueError, TypeError, AttributeError):
+        raise usage(local_message("expected_a_resource_uuid")) from None
+
+
+def segment(value: str) -> str:
+    return quote(value, safe="")
+
+
+def remaining(deadline: float) -> float:
+    value = deadline - time.monotonic()
+    if value <= 0:
+        raise CLIError(
+            "timeout",
+            local_message("operation_timed_out_accepted_server_work_continues"),
+            exit_code=3,
+        )
+    return value
+
+
+class API:
+    def __init__(self, base: str, token: str, kind: str, *, transport=None):
+        self.base, self.kind = origin(base), kind
+        self.headers = {
+            "Authorization": "Bearer " + token,
+            "User-Agent": f"wondersearch-cli/{__version__}",
+            "X-WonderSearch-CLI-Version": __version__,
+            "Accept-Encoding": "identity",
+        }
+        self.http = httpx.Client(
+            follow_redirects=False, transport=transport, trust_env=False
+        )
+        self.context: dict = {}
+        self.notices: list[dict] = []
+
+    def close(self):
+        self.http.close()
+
+    def discover(self):
+        self.context = self.request(
+            "GET", "/v1/sdk/context" if self.kind == "key" else "/v1/me"
+        )[0]
+        if self.kind == "key":
+            response_fields(self.context, workspace_id=str)
+        compatibility = self.context.get("compatibility")
+        self.notices = notices(
+            compatibility.get("cli") if isinstance(compatibility, dict) else None
+        )
+        if self.kind == "session" and not self.context.get("provisioned"):
+            raise CLIError(
+                "account_setup_required",
+                local_message("complete_account_setup_in_the_console_first"),
+            )
+        return self.context
+
+    def human(self):
+        if self.kind != "session":
+            raise CLIError(
+                "human_session_required",
+                local_message("sign_in_with_a_user_session_to_run"),
+            )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body=None,
+        *,
+        params=None,
+        headers=None,
+        key: str | None = None,
+        deadline: float | None = None,
+        file: Path | None = None,
+        external=False,
+        raw=False,
+    ):
+        deadline = deadline if deadline is not None else time.monotonic() + 60
+        if external:
+            p = urlsplit(path)
+            forbidden = {"authorization", "cookie", "host", "idempotency-key"}
+            if (
+                p.scheme != "https"
+                or not p.hostname
+                or p.username
+                or p.password
+                or p.fragment
+                or any(k.lower() in forbidden for k in headers or {})
+            ):
+                raise CLIError(
+                    "invalid_transfer", local_message("unsafe_transfer_destination")
+                )
+            url, merged = path, dict(headers or {})
+        else:
+            if not path.startswith("/v1/") or "?" in path or "#" in path:
+                raise usage(local_message("invalid_api_path"))
+            url, merged = self.base + path, {**self.headers, **(headers or {})}
+            if key:
+                merged["Idempotency-Key"] = key
+        safe = method == "GET" or bool(key) or external
+        for attempt in range(3):
+            try:
+
+                def chunks():
+                    assert file is not None
+                    with file.open("rb") as stream:
+                        while True:
+                            remaining(deadline)
+                            data = stream.read(65536)
+                            if not data:
+                                return
+                            yield data
+
+                # Construct directly, so response cookies can never leak across requests.
+                request = httpx.Request(
+                    method,
+                    url,
+                    params=params,
+                    headers=merged,
+                    content=chunks() if file else None,
+                    json=body if not file else None,
+                    extensions={
+                        "timeout": dict.fromkeys(
+                            ["connect", "read", "write", "pool"],
+                            min(60, remaining(deadline)),
+                        )
+                    },
+                )
+                response = self.http.send(request, follow_redirects=False)
+                remaining(deadline)
+            except httpx.TransportError:
+                if attempt == 2 or not safe:
+                    raise CLIError(
+                        "transport_error",
+                        local_message("network_request_failed"),
+                        kind="transport",
+                    ) from None
+                time.sleep(min(0.25 * 2**attempt, remaining(deadline)))
+                continue
+            if raw and response.is_success:
+                return response.content, dict(response.headers)
+            try:
+                data = response.json() if response.content and not external else {}
+            except ValueError:
+                raise CLIError(
+                    "invalid_response",
+                    local_message("server_returned_a_non_json_response"),
+                    kind="transport",
+                    status=response.status_code,
+                ) from None
+            if not isinstance(data, dict):
+                raise CLIError(
+                    "invalid_response",
+                    local_message("server_returned_an_invalid_response"),
+                    kind="transport",
+                )
+            if response.is_success:
+                return data, dict(response.headers)
+            error = data.get("error", {})
+            if not isinstance(error, dict):
+                error = {}
+            code = error.get(
+                "code", "transfer_failed" if external else "request_failed"
+            )
+            if (
+                safe
+                and attempt < 2
+                and code != "search_replay_unavailable"
+                and (
+                    response.status_code in {429, 502, 503, 504}
+                    or code in {"request_in_progress", "search_request_in_progress"}
+                )
+            ):
+                delay = 0.25 * 2**attempt
+                value = response.headers.get("retry-after")
+                if value:
+                    try:
+                        delay = float(value)
+                    except ValueError:
+                        try:
+                            delay = (
+                                parsedate_to_datetime(value)
+                                - datetime.now(timezone.utc)
+                            ).total_seconds()
+                        except (ValueError, TypeError, OverflowError):
+                            pass
+                time.sleep(min(max(0, delay), remaining(deadline)))
+                continue
+            raise CLIError(
+                str(code),
+                str(error.get("message") or local_message("api_request_failed")),
+                kind="api" if not external else "transport",
+                status=response.status_code,
+                request_id=error.get("request_id")
+                or response.headers.get("x-request-id"),
+                details=error.get("details"),
+            )
+        raise AssertionError("unreachable")
+
+    def pages(self, path: str, params=None, *, all_pages=False):
+        params = dict(params or {})
+        result = None
+        seen = set()
+        while True:
+            page, _ = self.request("GET", path, params=params)
+            response_fields(page, data=list)
+            if any(
+                not isinstance(row, dict) or not isinstance(row.get("id"), str)
+                for row in page["data"]
+            ) or (
+                page.get("next_cursor") is not None
+                and not isinstance(page["next_cursor"], str)
+            ):
+                raise CLIError(
+                    "invalid_response",
+                    local_message("server_returned_invalid_pagination_data"),
+                    kind="transport",
+                )
+            if result is None:
+                result = page
+            else:
+                result["data"].extend(page["data"])
+                result["next_cursor"] = page.get("next_cursor")
+            cursor = page.get("next_cursor")
+            if not all_pages or not cursor:
+                return result
+            if cursor in seen:
+                raise CLIError(
+                    "invalid_response",
+                    local_message("repeated_pagination_cursor"),
+                    kind="transport",
+                )
+            seen.add(cursor)
+            params["cursor"] = cursor
+
+    def mutate(self, method, path, body=None, *, versioned=False, key=None):
+        headers = {}
+        if versioned:
+            current, read_headers = self.request("GET", path)
+            tag = read_headers.get("etag")
+            if not tag:
+                raise CLIError(
+                    "invalid_response",
+                    local_message("resource_is_missing_its_concurrency_etag"),
+                    kind="transport",
+                )
+            headers["If-Match"] = tag
+        return self.request(
+            method, path, body, key=key or str(uuid.uuid4()), headers=headers
+        )[0]