proteworks 0.1.0__tar.gz

proteworks-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: proteworks
+Version: 0.1.0
+Summary: Sync files with Proteworks using file-browser paths.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# proteworks
+
+Command line client for pulling and pushing Proteworks files. The default API is production. Set `PROTEWORKS_API_URL` only when testing against staging or a local stack.
+
+```bash
+uv tool install proteworks
+proteworks login
+proteworks organization list
+proteworks organization set "My Org"
+proteworks pull '~/My Files/campaigns/run/' ./run
+proteworks push ./1UBQ.pdb '~/My Files/test/'
+proteworks push ./run '~/My Files/campaigns/run/'
+```
+
+Quote wildcards so the shell does not expand them. A trailing slash on a remote path means a folder. `proteworks --help` lists every command.
+
+Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs. The same URL is used in development and production.

proteworks-0.1.0/README.md

@@ -0,0 +1,17 @@
+# proteworks
+
+Command line client for pulling and pushing Proteworks files. The default API is production. Set `PROTEWORKS_API_URL` only when testing against staging or a local stack.
+
+```bash
+uv tool install proteworks
+proteworks login
+proteworks organization list
+proteworks organization set "My Org"
+proteworks pull '~/My Files/campaigns/run/' ./run
+proteworks push ./1UBQ.pdb '~/My Files/test/'
+proteworks push ./run '~/My Files/campaigns/run/'
+```
+
+Quote wildcards so the shell does not expand them. A trailing slash on a remote path means a folder. `proteworks --help` lists every command.
+
+Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs. The same URL is used in development and production.

proteworks-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "proteworks"
+version = "0.1.0"
+description = "Sync files with Proteworks using file-browser paths."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "keyring>=25",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+proteworks = "proteworks.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

proteworks-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

proteworks-0.1.0/src/proteworks/__init__.py

@@ -0,0 +1,3 @@
+"""Proteworks sync client."""
+
+__version__ = "0.1.0"

proteworks-0.1.0/src/proteworks/api.py

@@ -0,0 +1,180 @@
+"""Protein Studio HTTP API. Signed URLs are returned to callers and never logged."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+from urllib.parse import urlencode
+
+import httpx
+
+from proteworks.redact import redact
+
+
+class ApiError(Exception):
+    """Sanitized API failure. The message never includes a storage URL."""
+
+    def __init__(self, message: str, status_code: int):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def public_detail(response: httpx.Response) -> str:
+    """User-facing error from a JSON body, without echoing storage fields."""
+    try:
+        payload = response.json()
+    except Exception:
+        return f"Request failed ({response.status_code})"
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    if isinstance(detail, str) and detail.strip():
+        cleaned = redact(detail)
+        return cleaned if isinstance(cleaned, str) else "Request failed"
+    if response.status_code == 404:
+        return "File not found"
+    return f"Request failed ({response.status_code})"
+
+
+class ApiClient:
+    """Bearer-token client. Callers must not print values returned as URLs."""
+
+    def __init__(self, base_url: str, token: str, organization_id: Optional[str] = None, client: Optional[httpx.Client] = None):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.organization_id = organization_id
+        self._client = client or httpx.Client(timeout=120.0)
+        self._owns_client = client is None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.token}", "Accept": "application/json"}
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        json_body: Any = None,
+        data: Any = None,
+        extra_headers: Optional[dict] = None,
+    ) -> Any:
+        query = dict(params or {})
+        if self.organization_id and "organization_id" not in query and path != "/api/v1/organizations":
+            query["organization_id"] = self.organization_id
+        url = self.base_url + path
+        if query:
+            url = url + "?" + urlencode(query)
+        headers = self._headers()
+        if extra_headers:
+            headers.update(extra_headers)
+        response = self._client.request(method, url, headers=headers, json=json_body, data=data)
+        if response.status_code >= 400:
+            raise ApiError(public_detail(response), response.status_code)
+        if not response.content:
+            return None
+        return response.json()
+
+    def list_organizations(self) -> list[dict]:
+        payload = self.request("GET", "/api/v1/organizations", params={})
+        return list(payload or [])
+
+    def manifest(self, path: str, offset: int, limit: int = 500) -> dict:
+        return self.request(
+            "GET",
+            "/api/v1/sync/manifest",
+            params={"path": path, "offset": offset, "limit": limit},
+        )
+
+    def manifest_all(self, path: str) -> dict:
+        """Follow pages. Returns items plus root_folder_id from the first page."""
+        offset = 0
+        items: list[dict] = []
+        root_folder_id = None
+        total = None
+        while True:
+            page = self.manifest(path, offset)
+            root_folder_id = root_folder_id or page.get("root_folder_id")
+            batch = list(page.get("items") or [])
+            items.extend(batch)
+            total = int(page.get("total") or 0)
+            offset += len(batch)
+            if not batch or offset >= total:
+                break
+        return {"items": items, "total": total or 0, "root_folder_id": root_folder_id}
+
+    def content_urls(self, file_ids: list[str]) -> dict[str, dict]:
+        """Mint signed download URLs. Retries when the API asks the client to slow down."""
+        payload = self._request_with_backoff(
+            "POST",
+            "/api/v1/files/content-urls",
+            json_body={"file_ids": file_ids, "purpose": "download"},
+            extra_headers={"X-Proteworks-Client": "cli"},
+        )
+        return dict((payload or {}).get("urls") or {})
+
+    def _request_with_backoff(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        extra_headers: Optional[dict] = None,
+    ) -> Any:
+        delay_seconds = 1.0
+        for attempt in range(6):
+            try:
+                return self.request(method, path, json_body=json_body, extra_headers=extra_headers)
+            except ApiError as exc:
+                if exc.status_code != 429 or attempt == 5:
+                    raise
+                time.sleep(delay_seconds)
+                delay_seconds = min(delay_seconds * 2, 30.0)
+
+    def list_child_folders(self, parent_id: str) -> list[dict]:
+        payload = self.request("GET", "/api/v1/folders/", params={"parent_id": parent_id, "limit": 1000})
+        return list((payload or {}).get("folders") or [])
+
+    def create_folder(self, name: str, parent_id: str) -> dict:
+        return self.request(
+            "POST",
+            "/api/v1/folders/",
+            data={"name": name, "parent_id": parent_id},
+        )
+
+    def upload_init(self, filename: str, folder_id: str, size_bytes: int, content_type: str) -> dict:
+        return self.request(
+            "POST",
+            "/api/v1/files/upload-init",
+            json_body={
+                "filename": filename,
+                "folder_id": folder_id,
+                "content_type": content_type,
+                "size_bytes": size_bytes,
+                "skip_existing": False,
+            },
+        )
+
+    def upload_complete(self, session_id: str, size_bytes: int) -> dict:
+        return self.request(
+            "POST",
+            "/api/v1/files/upload-complete",
+            json_body={"session_id": session_id, "size_bytes": size_bytes},
+        )
+
+    def download_to(self, url: str, path) -> None:
+        """Stream bytes to a file. The URL is not logged."""
+        with self._client.stream("GET", url) as response:
+            response.raise_for_status()
+            with open(path, "wb") as handle:
+                for chunk in response.iter_bytes():
+                    handle.write(chunk)
+
+    def put_file(self, url: str, path, headers: Optional[dict] = None) -> None:
+        """Upload a file. The URL is not logged."""
+        with open(path, "rb") as handle:
+            response = self._client.put(url, content=handle, headers=headers or {})
+        if response.status_code >= 400:
+            raise ApiError(f"Upload to storage failed ({response.status_code})", response.status_code)

proteworks-0.1.0/src/proteworks/auth.py

@@ -0,0 +1,109 @@
+"""Auth0 loopback PKCE login. The access token is stored in the OS keychain."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+
+from proteworks.config import LOOPBACK_PORT, LOOPBACK_REDIRECT_PATH, Settings, TokenStore
+
+
+def pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+    return verifier, challenge
+
+
+def authorize_url(settings: Settings, redirect_uri: str, state: str, challenge: str) -> str:
+    query = urlencode(
+        {
+            "response_type": "code",
+            "client_id": settings.auth0_client_id,
+            "redirect_uri": redirect_uri,
+            "scope": "openid profile email",
+            "audience": settings.auth0_audience,
+            "state": state,
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+        }
+    )
+    return f"https://{settings.auth0_domain}/authorize?{query}"
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:  # noqa: N802 - stdlib handler name
+        parsed = urlparse(self.path)
+        if parsed.path != LOOPBACK_REDIRECT_PATH:
+            self.send_response(404)
+            self.end_headers()
+            return
+        params = parse_qs(parsed.query)
+        self.server.auth_code = params.get("code", [None])[0]  # type: ignore[attr-defined]
+        self.server.auth_state = params.get("state", [None])[0]  # type: ignore[attr-defined]
+        self.server.auth_error = params.get("error", [None])[0]  # type: ignore[attr-defined]
+        body = b"Signed in. You can close this window."
+        self.send_response(200)
+        self.send_header("Content-Type", "text/plain")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, fmt: str, *args) -> None:
+        """Do not log the authorization code."""
+        return
+
+
+def loopback_redirect_uri(port: int = LOOPBACK_PORT) -> str:
+    """Callback Auth0 must allow. The port is fixed so the URL does not change."""
+    return f"http://127.0.0.1:{port}{LOOPBACK_REDIRECT_PATH}"
+
+
+def login(settings: Settings, token_store: TokenStore, stderr) -> None:
+    """Open a browser, receive the loopback redirect, and save the access token."""
+    verifier, challenge = pkce_pair()
+    state = secrets.token_urlsafe(24)
+    try:
+        server = HTTPServer(("127.0.0.1", LOOPBACK_PORT), _CallbackHandler)
+    except OSError as exc:
+        raise SystemExit(
+            f"Port {LOOPBACK_PORT} is in use, so login cannot listen on {loopback_redirect_uri()}. ({exc})"
+        ) from exc
+    redirect_uri = loopback_redirect_uri()
+    url = authorize_url(settings, redirect_uri, state, challenge)
+    print(f"Auth0 must allow this callback URL: {redirect_uri}", file=stderr)
+    print("Opening a browser to sign in.", file=stderr)
+    opened = webbrowser.open(url)
+    if not opened:
+        print("Open this URL to sign in:", file=stderr)
+        print(url, file=stderr)
+    server.handle_request()
+    code = getattr(server, "auth_code", None)
+    returned_state = getattr(server, "auth_state", None)
+    error = getattr(server, "auth_error", None)
+    if error or not code or returned_state != state:
+        raise SystemExit("Login failed.")
+    token_response = httpx.post(
+        f"https://{settings.auth0_domain}/oauth/token",
+        json={
+            "grant_type": "authorization_code",
+            "client_id": settings.auth0_client_id,
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "code_verifier": verifier,
+        },
+        timeout=60.0,
+    )
+    if token_response.status_code >= 400:
+        raise SystemExit("Login failed.")
+    access_token = token_response.json().get("access_token")
+    if not access_token:
+        raise SystemExit("Login failed.")
+    token_store.set(access_token)
+    print("Signed in.", file=stderr)

proteworks-0.1.0/src/proteworks/cli.py

@@ -0,0 +1,176 @@
+"""proteworks command line. Help text comes from the registered subcommands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from proteworks.api import ApiClient
+from proteworks.auth import login
+from proteworks.config import ConfigStore, Settings, TokenStore, load_settings
+from proteworks.orgs import (
+    OrgSelectionError,
+    find_organization,
+    format_organization_line,
+    regular_organizations,
+    select_organization,
+)
+from proteworks.pull import pull_path
+from proteworks.push import push_directory
+from proteworks.redact import install_redacting_logs
+
+_PULL_EXAMPLES = """\
+examples:
+  proteworks pull '~/My Files/BoltzGenBinder.cif' .
+  proteworks pull '~/My Files/campaigns/' ./campaigns
+  proteworks pull '~/My Files/msa/*.cif' ./msa
+"""
+
+_PUSH_EXAMPLES = """\
+examples:
+  proteworks push ./1UBQ.pdb '~/My Files/test/'
+  proteworks push ./campaigns '~/My Files/campaigns/'
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the parser, then describe commands by walking what was registered."""
+    parser = argparse.ArgumentParser(
+        prog="proteworks",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("login", help="Sign in and save an access token in the OS keychain")
+
+    org = sub.add_parser("organization", help="List organizations or choose the active one")
+    org_sub = org.add_subparsers(dest="org_command", required=True)
+    org_sub.add_parser("list", help="Print each organization name")
+    set_parser = org_sub.add_parser("set", help="Save the active organization locally")
+    set_parser.add_argument("name", help="Organization name or id from organization list")
+
+    pull = sub.add_parser(
+        "pull",
+        help="Download a file, a folder/, or a quoted wildcard",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_PULL_EXAMPLES,
+    )
+    pull.add_argument("remote", help="File-browser path such as '~/My Files/campaigns/run/'. Quote wildcards.")
+    pull.add_argument("dest", help="Local file or directory")
+    pull.add_argument("--dry-run", action="store_true", help="Print the files that would be downloaded")
+
+    push = sub.add_parser(
+        "push",
+        help="Upload a local file or directory into a remote folder",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_PUSH_EXAMPLES,
+    )
+    push.add_argument("local_dir", help="Local file or directory to upload")
+    push.add_argument("remote", help="Remote folder path ending with /")
+    push.add_argument("--dry-run", action="store_true", help="Print the files that would be uploaded")
+
+    commands = "\n".join(f"  {line}" for line in _registered_commands(parser))
+    parser.description = (
+        f"Commands:\n{commands}\n\n"
+        "examples:\n"
+        "  proteworks pull '~/My Files/BoltzGenBinder.cif' .\n"
+        "  proteworks pull '~/My Files/campaigns/' ./campaigns\n"
+        "  proteworks pull '~/My Files/msa/*.cif' ./msa\n"
+        "  proteworks push ./1UBQ.pdb '~/My Files/test/'\n"
+        "  proteworks push ./campaigns '~/My Files/campaigns/'\n"
+    )
+    return parser
+
+
+def _registered_commands(parser: argparse.ArgumentParser) -> list[str]:
+    lines: list[str] = []
+    for action in parser._actions:
+        if not isinstance(action, argparse._SubParsersAction):
+            continue
+        for name, subparser in action.choices.items():
+            lines.append(name)
+            for subaction in subparser._actions:
+                if isinstance(subaction, argparse._SubParsersAction):
+                    for subname in subaction.choices:
+                        lines.append(f"{name} {subname}")
+    return lines
+
+
+def main(argv: list[str] | None = None, *, settings: Settings | None = None, token_store: TokenStore | None = None) -> int:
+    install_redacting_logs()
+    settings = settings or load_settings()
+    token_store = token_store or TokenStore()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if settings.api_url_overridden:
+        print(f"using {settings.api_url}", file=sys.stderr)
+    if args.command == "login":
+        login(settings, token_store, sys.stderr)
+        config = ConfigStore(settings.config_dir / "config.json")
+        data = config.read()
+        data["api_url"] = settings.api_url
+        config.write(data)
+        return 0
+    token = token_store.get()
+    if not token:
+        print("Run proteworks login.", file=sys.stderr)
+        return 2
+    config = ConfigStore(settings.config_dir / "config.json")
+    bound = config.bound_api_url()
+    if bound and bound.rstrip("/") != settings.api_url.rstrip("/"):
+        print("API URL changed. Run proteworks login again.", file=sys.stderr)
+        return 2
+    api = ApiClient(settings.api_url, token)
+    try:
+        if args.command == "organization" and args.org_command == "list":
+            return _organization_list(api, config, sys.stdout)
+        if args.command == "organization" and args.org_command == "set":
+            return _organization_set(api, config, settings, args.name, sys.stderr)
+        org = _require_organization(api, config, sys.stderr)
+        if org is None:
+            return 2
+        api.organization_id = org["id"]
+        if args.command == "pull":
+            return pull_path(api, args.remote, Path(args.dest), dry_run=args.dry_run, stderr=sys.stderr)
+        if args.command == "push":
+            return push_directory(api, Path(args.local_dir), args.remote, dry_run=args.dry_run, stderr=sys.stderr)
+        parser.print_help(sys.stderr)
+        return 2
+    finally:
+        api.close()
+
+
+def _organization_list(api: ApiClient, config: ConfigStore, stdout) -> int:
+    orgs = regular_organizations(api.list_organizations())
+    active = None
+    try:
+        active = select_organization(orgs, config.organization_id()).get("id")
+    except OrgSelectionError:
+        active = config.organization_id()
+    for org in orgs:
+        print(format_organization_line(org, active), file=stdout)
+    return 0
+
+
+def _organization_set(api: ApiClient, config: ConfigStore, settings: Settings, name: str, stderr) -> int:
+    try:
+        org = find_organization(api.list_organizations(), name)
+    except OrgSelectionError as exc:
+        print(str(exc), file=stderr)
+        return 2
+    config.set_organization(org["id"], settings.api_url)
+    print(f"Active organization: {org['name']}", file=stderr)
+    return 0
+
+
+def _require_organization(api: ApiClient, config: ConfigStore, stderr):
+    try:
+        return select_organization(api.list_organizations(), config.organization_id())
+    except OrgSelectionError as exc:
+        print(str(exc), file=stderr)
+        return None
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

proteworks-0.1.0/src/proteworks/config.py

@@ -0,0 +1,88 @@
+"""Local CLI config and production API defaults."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+PRODUCTION_API_URL = "https://api.studio.proteworks.com"
+PRODUCTION_AUTH0_DOMAIN = "proteworks-prod.us.auth0.com"
+PRODUCTION_AUTH0_CLIENT_ID = "wxtMn1fQ6hvAJopeNamTqugyLNbHUP2x"
+PRODUCTION_AUTH0_AUDIENCE = "https://proteworks-prod.us.auth0.com/api/v2/"
+LOOPBACK_REDIRECT_PATH = "/callback"
+LOOPBACK_PORT = 8765
+
+
+@dataclass
+class Settings:
+    api_url: str
+    api_url_overridden: bool
+    auth0_domain: str
+    auth0_client_id: str
+    auth0_audience: str
+    config_dir: Path
+
+
+def load_settings() -> Settings:
+    """Production is the default. PROTEWORKS_API_URL is only for staging or local tests."""
+    override = os.environ.get("PROTEWORKS_API_URL", "").strip()
+    api_url = override.rstrip("/") if override else PRODUCTION_API_URL
+    config_root = os.environ.get("PROTEWORKS_CONFIG_DIR", "").strip()
+    config_dir = Path(config_root) if config_root else Path.home() / ".config" / "proteworks"
+    return Settings(
+        api_url=api_url,
+        api_url_overridden=bool(override),
+        auth0_domain=os.environ.get("PROTEWORKS_AUTH0_DOMAIN", PRODUCTION_AUTH0_DOMAIN).strip(),
+        auth0_client_id=os.environ.get("PROTEWORKS_AUTH0_CLIENT_ID", PRODUCTION_AUTH0_CLIENT_ID).strip(),
+        auth0_audience=os.environ.get("PROTEWORKS_AUTH0_AUDIENCE", PRODUCTION_AUTH0_AUDIENCE).strip(),
+        config_dir=config_dir,
+    )
+
+
+class ConfigStore:
+    """Active organization for this API. The token itself stays in the keychain."""
+
+    def __init__(self, path: Path):
+        self.path = path
+
+    def read(self) -> dict:
+        if not self.path.exists():
+            return {}
+        return json.loads(self.path.read_text(encoding="utf-8"))
+
+    def write(self, data: dict) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+    def organization_id(self) -> Optional[str]:
+        value = self.read().get("organization_id")
+        return str(value) if value else None
+
+    def set_organization(self, organization_id: str, api_url: str) -> None:
+        data = self.read()
+        data["organization_id"] = organization_id
+        data["api_url"] = api_url
+        self.write(data)
+
+    def bound_api_url(self) -> Optional[str]:
+        value = self.read().get("api_url")
+        return str(value) if value else None
+
+
+class TokenStore:
+    """Access token in the OS keychain, never in the campaign folder."""
+
+    SERVICE = "proteworks"
+
+    def get(self) -> Optional[str]:
+        import keyring
+
+        return keyring.get_password(self.SERVICE, "access_token")
+
+    def set(self, token: str) -> None:
+        import keyring
+
+        keyring.set_password(self.SERVICE, "access_token", token)