proteworks 0.1.0__py3-none-any.whl

proteworks/__init__.py

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

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/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/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/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)

proteworks/index.py

@@ -0,0 +1,95 @@
+"""Local sync index. Stores ids, logical paths, sizes, and hashes only."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+
+def index_path(dest_dir: Path) -> Path:
+    return dest_dir / ".proteworks" / "files.jsonl"
+
+
+def load_index(dest_dir: Path) -> dict[str, dict]:
+    path = index_path(dest_dir)
+    if not path.exists():
+        return {}
+    rows: dict[str, dict] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        row = json.loads(line)
+        rows[row["relative_path"]] = {
+            "file_id": row.get("file_id"),
+            "relative_path": row["relative_path"],
+            "size": row.get("size"),
+            "sha256": row.get("sha256"),
+        }
+    return rows
+
+
+def save_index(dest_dir: Path, rows: dict[str, dict]) -> None:
+    path = index_path(dest_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = []
+    for key in sorted(rows):
+        row = rows[key]
+        lines.append(
+            json.dumps(
+                {
+                    "file_id": row.get("file_id"),
+                    "relative_path": row["relative_path"],
+                    "size": row.get("size"),
+                    "sha256": row.get("sha256"),
+                },
+                separators=(",", ":"),
+            )
+        )
+    path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def sha256_bytes(payload: bytes) -> str:
+    return hashlib.sha256(payload).hexdigest()
+
+
+def local_relative(remote: str, relative_path: str) -> str:
+    """Path under the destination, relative to the requested remote prefix."""
+    prefix = remote.rstrip("/")
+    if relative_path == prefix:
+        return Path(relative_path).name
+    marker = prefix + "/"
+    if relative_path.startswith(marker):
+        return relative_path[len(marker) :]
+    stripped = relative_path[2:] if relative_path.startswith("~/") else relative_path
+    return stripped
+
+
+def destination_for(dest: Path, remote: str, relative_path: str, *, single_file: bool) -> Path:
+    """Place a downloaded file under dest without keeping the ~/ prefix."""
+    name = local_relative(remote, relative_path)
+    if single_file and not _dest_is_directory(dest):
+        return dest
+    return dest / name
+
+
+def _dest_is_directory(dest: Path) -> bool:
+    if str(dest) in {".", ""}:
+        return True
+    if dest.exists():
+        return dest.is_dir()
+    return str(dest).endswith("/")
+
+
+def index_dir_for(dest: Path, *, single_file: bool) -> Path:
+    if single_file and not _dest_is_directory(dest):
+        return dest.parent if dest.parent != Path("") else Path(".")
+    return dest

proteworks/orgs.py

@@ -0,0 +1,57 @@
+"""Organization list, selection, and the tutorial-aware default."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class OrgSelectionError(Exception):
+    """The user must pick an organization before pull or push."""
+
+
+def is_tutorial(org: dict) -> bool:
+    return bool(org.get("is_tutorial_organization") or org.get("is_tutorial_generation_organization"))
+
+
+def regular_organizations(orgs: list[dict]) -> list[dict]:
+    return [org for org in orgs if not is_tutorial(org)]
+
+
+def select_organization(orgs: list[dict], configured_id: Optional[str]) -> dict:
+    """
+    Use the saved organization when it is still a membership.
+
+    Otherwise prefer the only regular organization. Tutorial organizations are ignored.
+    """
+    regular = regular_organizations(orgs)
+    if configured_id:
+        for org in regular:
+            if org.get("id") == configured_id:
+                return org
+        if not any(org.get("id") == configured_id and is_tutorial(org) for org in orgs):
+            raise OrgSelectionError("Saved organization is not in your memberships. Run proteworks organization set.")
+    if len(regular) == 1:
+        return regular[0]
+    if len(regular) > 1:
+        raise OrgSelectionError("You belong to more than one organization. Run proteworks organization set.")
+    raise OrgSelectionError("You do not belong to an organization.")
+
+
+def find_organization(orgs: list[dict], name_or_id: str) -> dict:
+    """Match a name or id returned by organization list. Reject anything else."""
+    needle = name_or_id.strip()
+    orgs = regular_organizations(orgs)
+    by_id = [org for org in orgs if org.get("id") == needle]
+    if len(by_id) == 1:
+        return by_id[0]
+    by_name = [org for org in orgs if org.get("name") == needle]
+    if len(by_name) == 1:
+        return by_name[0]
+    if len(by_name) > 1:
+        raise OrgSelectionError("That name matches more than one organization. Set the organization id instead.")
+    raise OrgSelectionError("That organization was not returned by proteworks organization list.")
+
+
+def format_organization_line(org: dict, active_id: Optional[str]) -> str:
+    marker = "*" if org.get("id") == active_id else " "
+    return f"{marker} {org.get('name')}"

proteworks/pull.py

@@ -0,0 +1,145 @@
+"""Download a file, folder, or wildcard onto local disk."""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from threading import Lock
+
+from proteworks.api import ApiClient, ApiError
+from proteworks.index import (
+    destination_for,
+    index_dir_for,
+    load_index,
+    local_relative,
+    save_index,
+    sha256_file,
+)
+
+# One content-urls call can mint this many links. The API rejects a larger batch.
+_CONTENT_URL_BATCH = 100
+
+
+def pull_path(api: ApiClient, remote: str, dest: Path, *, dry_run: bool, stderr) -> int:
+    """Download readable files for a file-browser path. Returns a process status code."""
+    try:
+        page = api.manifest_all(remote)
+    except ApiError as exc:
+        print(str(exc), file=stderr)
+        return 1
+    items = list(page.get("items") or [])
+    single_file = len(items) == 1 and not remote.endswith("/") and "*" not in remote and "?" not in remote
+    print(f"{len(items)} file(s)", file=stderr)
+    if dry_run:
+        for item in items:
+            print(local_relative(remote, item["relative_path"]), file=stderr)
+        return 0
+    index_root = index_dir_for(dest, single_file=single_file)
+    if not single_file or dest.exists() and dest.is_dir() or str(dest) in {".", ""}:
+        dest.mkdir(parents=True, exist_ok=True)
+    index = load_index(index_root)
+    index_lock = Lock()
+    failures = 0
+    pending = []
+    for item in items:
+        if _already_local(dest, remote, item, single_file):
+            with index_lock:
+                index[item["relative_path"]] = _index_row(item)
+            print(f"skip {local_relative(remote, item['relative_path'])}", file=stderr)
+            continue
+        pending.append(item)
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        for start in range(0, len(pending), _CONTENT_URL_BATCH):
+            chunk = pending[start : start + _CONTENT_URL_BATCH]
+            try:
+                urls = api.content_urls([item["file_id"] for item in chunk])
+            except ApiError as exc:
+                for item in chunk:
+                    print(f"{local_relative(remote, item['relative_path'])}: {exc}", file=stderr)
+                failures += len(chunk)
+                continue
+            futures = [
+                pool.submit(
+                    _download_one,
+                    api,
+                    remote,
+                    dest,
+                    item,
+                    single_file,
+                    urls.get(item["file_id"]) or {},
+                    index,
+                    index_lock,
+                    stderr,
+                )
+                for item in chunk
+            ]
+            for future in as_completed(futures):
+                if not future.result():
+                    failures += 1
+    save_index(index_root, index)
+    return 1 if failures else 0
+
+
+def _already_local(dest: Path, remote: str, item: dict, single_file: bool) -> bool:
+    """True when dest already holds this file.
+
+    A stored checksum must match. Workflow outputs often have no checksum, so a
+    file of the same size is treated as the copy that was already downloaded.
+    """
+    target = destination_for(dest, remote, item["relative_path"], single_file=single_file)
+    if not target.is_file():
+        return False
+    expected = item.get("sha256")
+    if expected:
+        return sha256_file(target) == expected
+    size = item.get("size")
+    if size is None:
+        return False
+    return target.stat().st_size == int(size)
+
+
+def _download_one(
+    api: ApiClient,
+    remote: str,
+    dest: Path,
+    item: dict,
+    single_file: bool,
+    entry: dict,
+    index: dict,
+    index_lock: Lock,
+    stderr,
+) -> bool:
+    relative = item["relative_path"]
+    target = destination_for(dest, remote, relative, single_file=single_file)
+    expected = item.get("sha256")
+    signed = entry.get("url")
+    if not signed:
+        print(f"{local_relative(remote, relative)}: Could not get a download URL", file=stderr)
+        return False
+    target.parent.mkdir(parents=True, exist_ok=True)
+    partial = target.with_suffix(target.suffix + ".partial")
+    try:
+        api.download_to(signed, partial)
+        digest = sha256_file(partial)
+        if expected and digest != expected:
+            partial.unlink(missing_ok=True)
+            print(f"{local_relative(remote, relative)}: hash mismatch", file=stderr)
+            return False
+        partial.replace(target)
+    except Exception:
+        partial.unlink(missing_ok=True)
+        print(f"{local_relative(remote, relative)}: download failed", file=stderr)
+        return False
+    with index_lock:
+        index[relative] = _index_row(item)
+    print(f"download {local_relative(remote, relative)}", file=stderr)
+    return True
+
+
+def _index_row(item: dict) -> dict:
+    return {
+        "file_id": item.get("file_id"),
+        "relative_path": item["relative_path"],
+        "size": item.get("size"),
+        "sha256": item.get("sha256"),
+    }

proteworks/push.py

@@ -0,0 +1,118 @@
+"""Upload a local file or directory into a remote folder the caller may write."""
+
+from __future__ import annotations
+
+import mimetypes
+from pathlib import Path
+
+from proteworks.api import ApiClient, ApiError
+from proteworks.index import sha256_file
+
+
+def push_directory(api: ApiClient, local_dir: Path, remote: str, *, dry_run: bool, stderr) -> int:
+    """Upload files under local_dir. Skip a file when the remote hash already matches."""
+    if not remote.endswith("/"):
+        print("The remote path must be a folder ending with /.", file=stderr)
+        return 2
+    try:
+        files = _local_files(local_dir)
+    except ValueError as exc:
+        print(str(exc), file=stderr)
+        return 2
+    try:
+        page = api.manifest_all(remote)
+    except ApiError as exc:
+        print(str(exc), file=stderr)
+        return 1
+    root_id = page.get("root_folder_id")
+    if not root_id:
+        print("File not found", file=stderr)
+        return 1
+    remote_by_suffix = {}
+    prefix = remote.rstrip("/")
+    for item in page.get("items") or []:
+        relative = item.get("relative_path") or ""
+        if relative.startswith(prefix + "/"):
+            remote_by_suffix[relative[len(prefix) + 1 :]] = item
+    print(f"{len(files)} file(s)", file=stderr)
+    if dry_run:
+        for rel, _path in files:
+            print(rel.as_posix(), file=stderr)
+        return 0
+    folder_ids = {Path("."): root_id}
+    failures = 0
+    for rel, path in files:
+        try:
+            folder_id = _ensure_parent(api, folder_ids, rel.parent)
+            existing = remote_by_suffix.get(rel.as_posix())
+            digest = sha256_file(path)
+            if existing and existing.get("sha256") == digest:
+                print(f"skip {rel.as_posix()}", file=stderr)
+                continue
+            content_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
+            init = api.upload_init(path.name, folder_id, path.stat().st_size, content_type)
+            if not init.get("skipped"):
+                upload_url = init.get("upload_url")
+                if not upload_url:
+                    print(f"{rel.as_posix()}: upload failed", file=stderr)
+                    failures += 1
+                    continue
+                # The signed PUT requires the same Content-Type sent to upload-init.
+                headers = dict(init.get("upload_headers") or {})
+                headers.setdefault("Content-Type", content_type)
+                api.put_file(upload_url, path, headers)
+                api.upload_complete(init["session_id"], path.stat().st_size)
+            print(f"upload {rel.as_posix()}", file=stderr)
+        except ApiError as exc:
+            print(f"{rel.as_posix()}: {exc}", file=stderr)
+            failures += 1
+        except Exception:
+            print(f"{rel.as_posix()}: upload failed", file=stderr)
+            failures += 1
+    return 1 if failures else 0
+
+
+def _local_files(local_path: Path) -> list[tuple[Path, Path]]:
+    if local_path.is_file():
+        return [(Path(local_path.name), local_path)]
+    if not local_path.is_dir():
+        raise ValueError("The local path must be a file or directory.")
+    return _iter_local_files(local_path)
+
+
+def _iter_local_files(local_dir: Path) -> list[tuple[Path, Path]]:
+    found: list[tuple[Path, Path]] = []
+    for path in sorted(local_dir.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(local_dir)
+        if ".proteworks" in rel.parts:
+            continue
+        if any(part in {".", ".."} for part in rel.parts):
+            raise ValueError("A local path escapes the directory.")
+        resolved = path.resolve()
+        root = local_dir.resolve()
+        if root != resolved and root not in resolved.parents:
+            raise ValueError("A local path escapes the directory.")
+        found.append((rel, path))
+    return found
+
+
+def _ensure_parent(api: ApiClient, folder_ids: dict[Path, str], parent: Path) -> str:
+    if parent in folder_ids:
+        return folder_ids[parent]
+    ancestor = _ensure_parent(api, folder_ids, parent.parent)
+    name = parent.name
+    try:
+        created = api.create_folder(name, ancestor)
+        folder_id = created["id"]
+    except ApiError:
+        folder_id = None
+        for child in api.list_child_folders(ancestor):
+            if child.get("name") == name and child.get("id"):
+                folder_id = child["id"]
+                break
+        if not folder_id:
+            raise
+    folder_ids[parent] = folder_id
+    return folder_id

proteworks/redact.py

@@ -0,0 +1,47 @@
+"""Keep signed URLs and storage locations out of logs and saved state."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+_SECRET_KEYS = {"url", "upload_url", "cloud_storage_url", "upload_headers"}
+
+
+def redact(value: Any) -> Any:
+    """Return a copy with storage URLs and signed-URL fields removed."""
+    if isinstance(value, dict):
+        cleaned = {}
+        for key, item in value.items():
+            if key in _SECRET_KEYS:
+                cleaned[key] = "[redacted]"
+            else:
+                cleaned[key] = redact(item)
+        return cleaned
+    if isinstance(value, list):
+        return [redact(item) for item in value]
+    if isinstance(value, str):
+        lowered = value.lower()
+        if lowered.startswith("gs://") or "storage.googleapis.com" in lowered:
+            return "[redacted]"
+        return value
+    return value
+
+
+class RedactFilter(logging.Filter):
+    """Drop storage URLs from log records."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if isinstance(record.msg, str):
+            record.msg = str(redact(record.msg))
+        if record.args:
+            record.args = redact(record.args)
+        return True
+
+
+def install_redacting_logs() -> None:
+    """Attach the redaction filter to the root logger once."""
+    root = logging.getLogger()
+    if any(isinstance(item, RedactFilter) for item in root.filters):
+        return
+    root.addFilter(RedactFilter())

proteworks-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+proteworks/__init__.py,sha256=JJg1U5dSx0JnlDnpWAWbwU3p_t-bsrbmvJkhtYXEQts,53
+proteworks/api.py,sha256=KN7CC9yBl6q5UixWX6Dkux1dnnYROGX9X-IePeBwOKY,6740
+proteworks/auth.py,sha256=PHaRqFgA2WcahRryitePyg9Zv5uE9Qhr_MSfM6nTC2k,4177
+proteworks/cli.py,sha256=8oXiAcbygplAUQCLVKxy6BSHAV-37jycNilPwLFtQUQ,6840
+proteworks/config.py,sha256=uCYbrdOpCjKk0SjgezEj26UbHaSywQ86Y5AE5-reN1g,2908
+proteworks/index.py,sha256=Eudu50jWIZ1OYC91ge7_vZJQ-CDKR7Skkt1Mc-KSwIM,2935
+proteworks/orgs.py,sha256=Z09udOHkeSVmlFKsOxaDClz-mjR0CLoteSkcV57eJeg,2234
+proteworks/pull.py,sha256=posEsWWZJBqEXzvHMZRAIxJvYIEe7VJiWWSspFW33a4,5017
+proteworks/push.py,sha256=U1xWcZ3AGwB6ZS37TS1I5UjEZQeezXXHsniSa6VpYYk,4547
+proteworks/redact.py,sha256=cLV9XWXp5DcXEWFxgN7RCxCFXDbJjqwZQ_xHQkPlMfg,1456
+proteworks-0.1.0.dist-info/METADATA,sha256=LAgmThg9SLf8Te3UJT-AdJgwPtNQ4n0qfX1fxi5oz34,1065
+proteworks-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+proteworks-0.1.0.dist-info/entry_points.txt,sha256=Qq8OkFQyEVOqlq7aY89vbYcHrXGPtJqVn0kNx_fYf7s,51
+proteworks-0.1.0.dist-info/top_level.txt,sha256=yWHfkVzhk5jS18i2usGFecejonxm7wAvnAQjsUSB6wc,11
+proteworks-0.1.0.dist-info/RECORD,,

proteworks-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

proteworks-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+proteworks = proteworks.cli:main

proteworks-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+proteworks