pushframe 5.0.0__py3-none-any.whl

pushframe/client.py

@@ -0,0 +1,267 @@
+import copy
+from collections import deque
+from typing import Optional, Deque
+
+import httpx
+from httpx import Response, Timeout
+from loguru import logger
+
+AURA_API_BASE_URL = 'https://api.pushd.com'
+AURA_API_VERSION = 'v5'
+USER_AGENT = 'Aura/4.7.790 (Android 30; Client)'
+
+# Keys whose values are secrets and must never reach the on-disk logs (D-07).
+_REDACT_KEYS = {'password', 'auth_token', 'x-token-auth'}
+_REDACTED = '***REDACTED***'
+
+# Status codes that mean "the server is throttling / has locked out this
+# account" rather than a per-request client error. 429 is the standard
+# Too Many Requests; 475 is Pushd's non-standard code observed during the
+# select-asset-401-unauthorized debug session — returned with valid
+# credentials once the account's write burst tripped the anti-abuse layer,
+# and it escalates to reject login too. Both are treated as a single
+# back-off-and-stop signal (see RateLimitError) so a tripped batch aborts
+# with one clear message instead of N misleading per-item 401s.
+_RATE_LIMIT_STATUS_CODES = {429, 475}
+
+
+class AuraError(Exception):
+    """Package-wide exception root for pushframe's own control-flow types
+    (MOD-03/D-20). This is a MARKER base, not a codebase-wide taxonomy --
+    most of this codebase still raises bare ``RuntimeError``/``ValueError``
+    deliberately (MOD-03 scopes typed-exception conversion to the write
+    path only, "where it pays", not a full rewrite).
+
+    Catching ``AuraError`` broadly is deliberately discouraged and, inside
+    `pushframe/sync.py`, actively prohibited: `execute_plan`'s write-loop
+    except-ladder depends on `RateLimitError` and
+    `ConsecutiveWriteFailureError` each being matched by their OWN specific
+    branch before any broader handler could see them. An `except AuraError`
+    introduced there would silently swallow both and break that ordering.
+    """
+    pass
+
+
+class AuthenticationError(AuraError):
+    """Raised by `execute_plan`'s write-chunk 401 retry (REL-01/REL-04,
+    D-01/D-02) when a write returns HTTP 401, a re-login is attempted to
+    discriminate a genuine authentication failure from an anti-abuse trip,
+    and that re-login itself raises.
+
+    This is a HARD STOP, never a transient/retryable condition: two write
+    401s in a row would be ambiguous on their own, but a re-login that
+    *itself* fails means the credentials are bad or revoked. The write is
+    never retried and the failure is never re-labelled transient.
+
+    Carries `underlying` -- the exception the re-login raised (or `None`)
+    -- for callers/logs. The message names the failure class and
+    `type(underlying).__name__` ONLY; it must never interpolate a response
+    body, an auth token, or the password (T-11-02).
+    """
+
+    def __init__(self, underlying: Exception | None = None):
+        self.underlying = underlying
+        underlying_name = type(underlying).__name__ if underlying is not None else 'unknown error'
+        super().__init__(
+            f'Re-login failed after a write returned HTTP 401 -- treating this as a '
+            f'genuine authentication failure (bad or revoked credentials), not a '
+            f'transient/retryable anti-abuse trip. Underlying: {underlying_name}.'
+        )
+
+
+class WriteEndpointError(AuraError):
+    """The write-path form of an Aura error-envelope response (MOD-03/D-20):
+    the call reached the server, the server answered HTTP 200, and the body
+    carried an `error` key -- distinct from a network/HTTP-status failure.
+
+    Converted from exactly two bare `RuntimeError`s in
+    `pushframe/api/assetApi.py` (`batch_update`, `delete_asset`). Every
+    other write-endpoint error envelope (`select_asset`/`exclude_asset`/
+    `remove_asset` in `pushframe/api/frameApi.py`) and every read-path
+    raise is deliberately left as `RuntimeError` this phase -- D-20 scopes
+    conversion narrowly so a phase about the write path's *trustworthiness*
+    does not also become the widest-blast-radius rewrite of its *type
+    surface*.
+    """
+    pass
+
+
+class RateLimitError(AuraError):
+    """Raised when the Aura/Pushd API signals rate-limiting or an account
+    lockout (HTTP 429 or the custom 475).
+
+    Carries the offending ``status_code`` and, when the server provided a
+    ``Retry-After`` header, ``retry_after`` (an int number of seconds when
+    the header was numeric, otherwise the raw header string — e.g. an
+    HTTP-date). Distinct from ``httpx.HTTPStatusError`` so callers can
+    abort a whole batch and surface a single "back off" message rather than
+    treating it as one of many per-item failures.
+    """
+
+    def __init__(self, status_code: int, retry_after=None, server_message: str | None = None):
+        self.status_code = status_code
+        self.retry_after = retry_after
+        self.server_message = server_message
+
+        detail = (
+            f' Retry after {retry_after}s.'
+            if isinstance(retry_after, int)
+            else (f' Retry-After: {retry_after}.' if retry_after else '')
+        )
+        server = f' Server said: {server_message}.' if server_message else ''
+        super().__init__(
+            f'Aura API is rate-limiting or has locked out this account '
+            f'(HTTP {status_code}). Stop and back off before retrying; '
+            f'continued calls may extend the lockout.{detail}{server}'
+        )
+
+
+def _parse_retry_after(raw: str | None):
+    """Parse a ``Retry-After`` header value.
+
+    Returns an ``int`` when the header is a plain number of seconds, the
+    stripped raw string when it is an HTTP-date (or otherwise non-numeric),
+    or ``None`` when the header is absent. Stdlib only — no date parsing is
+    attempted; a non-numeric value is surfaced verbatim for the human.
+    """
+    if raw is None:
+        return None
+    raw = raw.strip()
+    if not raw:
+        return None
+    return int(raw) if raw.isdigit() else raw
+
+
+def _redact(value):
+    """Return a deep copy of a dict/list with secret-bearing keys masked.
+
+    Recurses into nested dicts (e.g. the ``user`` sub-dict of the login payload)
+    and lists so a secret can never leak from a deeper level. Non-container
+    values are returned unchanged. Stdlib only.
+    """
+    if isinstance(value, dict):
+        return {
+            k: (_REDACTED if k in _REDACT_KEYS else _redact(v))
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [_redact(item) for item in value]
+    return copy.copy(value)
+
+
+# Use something similar to:
+# https://github.com/sudoguy/tiktokpy/blob/master/tiktokpy/client/__init__.py
+# https://github.com/mkb79/Audible/tree/master/src/audible
+# https://github.com/ssut/py-googletrans/blob/master/googletrans/client.py
+
+
+# TODO: This should be reworked to be async, particularly for mass uploads/clones.
+
+class Client:
+
+    def __init__(self, history_len: int = 30, transport: httpx.BaseTransport | None = None,
+                 base_url: str | None = None):
+        # TEST-01 candidate #4 (Phase 19): base_url is injectable for offline
+        # tests; None keeps the historical composition byte-identical.
+        resolved_base_url = base_url or f'{AURA_API_BASE_URL}/{AURA_API_VERSION}'
+        self.http2_client = httpx.Client(http2=True, base_url=resolved_base_url, headers={
+            'accept-language': 'en-US',
+            'cache-control': 'no-cache',
+            'user-agent': USER_AGENT,
+            'content-type': 'application/json; charset=utf-8',
+        }, timeout=Timeout(timeout=20.0), transport=transport)
+
+        self.history: Deque[Response] = deque(maxlen=history_len)
+
+    def get(self, url, query_params: Optional[dict] = None, headers: Optional[dict] = None):
+        query_params = {k: v for k, v in query_params.items() if v is not None} if query_params else None
+        logger.info(f'GET request to {url}', query_params=query_params, headers=headers)
+        response = self.http2_client.get(url=url, params=query_params, headers=headers)
+
+        self.history.append(response)
+        self._raise_if_rate_limited(response)
+        response.raise_for_status()
+        logger.debug(f'Response ({response.status_code}), body: {_redact(response.json())}')
+
+        self._set_cookies(response)
+
+        return response.json()
+
+    def post(self, url, data: dict = None, query_params: Optional[dict] = None, headers: Optional[dict] = None):
+        logger.info(f'POST request to {url}', data=_redact(data), query_params=query_params, headers=headers)
+        response = self.http2_client.post(url=url, json=data, headers=headers, params=query_params)
+
+        self.history.append(response)
+        self._raise_if_rate_limited(response)
+        response.raise_for_status()
+        logger.debug(f'Response ({response.status_code}), body: {_redact(response.json())}')
+
+        self._set_cookies(response)
+
+        return response.json()
+
+    def delete(self, url, query_params: Optional[dict] = None, headers: Optional[dict] = None):
+        logger.info(f'DELETE request to {url}', query_params=query_params, headers=headers)
+        response = self.http2_client.delete(url=url, headers=headers, params=query_params)
+
+        self.history.append(response)
+        self._raise_if_rate_limited(response)
+        response.raise_for_status()
+        logger.debug(f'Response ({response.status_code}), body: {_redact(response.json())}')
+
+        self._set_cookies(response)
+
+        return response.json()
+
+    def put(self, url, data: dict = None, query_params: Optional[dict] = None, headers: Optional[dict] = None):
+        logger.info(f'PUT request to {url}', data=_redact(data), query_params=query_params, headers=headers)
+        response = self.http2_client.put(url=url, json=data, headers=headers, params=query_params)
+
+        self.history.append(response)
+        self._raise_if_rate_limited(response)
+        response.raise_for_status()
+        logger.debug(f'Response ({response.status_code}), body: {_redact(response.json())}')
+
+        self._set_cookies(response)
+
+        return response.json()
+
+    def _raise_if_rate_limited(self, response: httpx.Response) -> None:
+        """Convert a rate-limit / lockout response (HTTP 429 or 475) into a
+        `RateLimitError` before the generic `raise_for_status()` runs.
+
+        Runs on every request method (read and write) so a throttle that
+        first appears on a GET is classified just as clearly as one on a
+        write. Reads the server's ``message`` body field (best-effort) and
+        the ``Retry-After`` header so the raised error can tell the caller
+        how long to wait.
+        """
+        if response.status_code not in _RATE_LIMIT_STATUS_CODES:
+            return
+
+        retry_after = _parse_retry_after(response.headers.get('retry-after'))
+        server_message = None
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                server_message = body.get('message')
+        except Exception:
+            # A rate-limit response with a non-JSON body must still raise a
+            # clean RateLimitError, never a JSON-decode error.
+            server_message = None
+
+        logger.warning(
+            f'Rate-limited/locked-out response (HTTP {response.status_code}) '
+            f'from {response.request.url}; aborting.'
+        )
+        raise RateLimitError(response.status_code, retry_after, server_message)
+
+    def add_default_headers(self, headers: dict) -> None:
+        self.http2_client.headers.update(headers)
+
+    def _set_cookies(self, response: httpx.Response) -> None:
+        if len(response.cookies):
+            logger.debug(f'Response Cookies: {response.cookies}')
+
+        for cookie_name, cookie_data in response.cookies.items():
+            self.http2_client.cookies.set(cookie_name, cookie_data)

pushframe/exif.py

@@ -0,0 +1,147 @@
+from datetime import datetime
+from geopy import Nominatim
+import io
+import piexif
+import piexif.helper
+from fractions import Fraction
+import json
+import time
+from loguru import logger
+
+from pushframe.models.asset import Asset
+
+
+# Most of the exif writing is from:
+# https://gitlab.com/searchwing/development/payloads/ros-generic/-/blob/master/searchwing_common_py/scripts/ImageSaverNode.py
+
+def build_gps_ifd(location_dms: tuple[any, any]):
+    if not location_dms:
+        return {}
+
+    return {
+        piexif.GPSIFD.GPSVersionID: (2, 3, 0, 0),
+        piexif.GPSIFD.GPSLatitudeRef: location_dms[0][3],
+        piexif.GPSIFD.GPSLatitude: location_dms[0][:-1],
+        piexif.GPSIFD.GPSLongitudeRef: location_dms[1][3],
+        piexif.GPSIFD.GPSLongitude: location_dms[1][:-1],
+        piexif.GPSIFD.GPSAltitudeRef: 0,
+        piexif.GPSIFD.GPSAltitude: (0, 1),
+        piexif.GPSIFD.GPSStatus: b'A'
+    }
+
+
+class ExifWriter:
+    geolocator = Nominatim(user_agent="pushframe-python-client/1.0")
+    cache = {}
+
+    # TODO: LRU Cache would be nice but probably over-engineered
+    def _lookup_gps(self, location_name: str):
+        location_dms = self.cache.get(location_name)
+        if location_dms:
+            return location_dms
+
+        try:
+            location = self.geolocator.geocode(location_name)
+        except Exception:
+            # GPS is conditional (D-09): a geocode failure is tolerable — log
+            # and skip GPS rather than failing the whole download.
+            logger.info(f'Failed to read GPS data for {location_name}')
+            return None
+
+        if not location:
+            return None
+
+        longitude_dms = convert_to_rational_dms(to_deg(location.longitude, is_longitude=True))
+        latitude_dms = convert_to_rational_dms(to_deg(location.latitude, is_longitude=False))
+
+        self.cache[location_name] = (longitude_dms, latitude_dms)
+        return longitude_dms, latitude_dms
+
+    def write_exif(self, image, asset: Asset, thumbnail=None, set_gps_ifd=True):
+        taken_datetime = asset.taken_at_dt.strftime('%Y:%m:%d %H:%M:%S').encode()
+
+        exif_dict = {
+            "Exif": {
+                piexif.ExifIFD.DateTimeOriginal: taken_datetime,
+                piexif.ExifIFD.DateTimeDigitized: taken_datetime,
+                piexif.ExifIFD.OffsetTime: b'-05:00',
+                piexif.ExifIFD.OffsetTimeOriginal: b'-05:00',
+
+            },
+            '0th': {
+                piexif.ImageIFD.DateTime: taken_datetime,
+                piexif.ImageIFD.Artist: asset.user.name if asset.user else None
+            }
+        }
+
+        if set_gps_ifd:
+            location_dms = self._lookup_gps(asset.location_name)
+            exif_dict['GPS'] = build_gps_ifd(location_dms)
+
+        if thumbnail:
+            exif_dict['thumbnail'] = thumbnail
+            exif_dict['1st'] = {piexif.ImageIFD.Make: u"Canon",
+                                piexif.ImageIFD.XResolution: (40, 1),
+                                piexif.ImageIFD.YResolution: (40, 1),
+                                piexif.ImageIFD.Software: u"piexif"
+                                }
+        new_imag = io.BytesIO()
+        exif_bytes = piexif.dump(exif_dict)
+
+        try:
+            piexif.insert(exif_bytes, image, new_imag)
+        except Exception:
+            # A corrupt/non-JPEG body must fail loudly (D-11): re-raise instead
+            # of returning an empty BytesIO that would be saved as a 0-byte file.
+            logger.error('Failed to write EXIF to image.')
+            raise
+        return new_imag
+
+
+def change_to_rational(number):
+    f = Fraction(str(number))
+    return f.numerator, f.denominator
+
+
+def convert_to_rational_dms(dms: tuple[int, int, float, str]):
+    return change_to_rational(dms[0]), change_to_rational(dms[1]), change_to_rational(dms[2]), dms[3]
+
+
+def clone_exif(original_path, clone_path):
+    piexif.transplant(original_path, clone_path)
+
+
+def get_readable_exif(image_path):
+    exif_dict = piexif.load(image_path)
+    readable_dict = {}
+    for ifd in exif_dict:
+        readable_dict[ifd] = {}
+        if not exif_dict[ifd]:
+            continue
+        for tag in exif_dict[ifd]:
+            if ifd != 'thumbnail':
+                readable_dict[ifd][piexif.TAGS[ifd][tag]["name"]] = exif_dict[ifd][tag]
+            else:
+                readable_dict[ifd][tag] = exif_dict[ifd][tag]
+    return readable_dict
+
+def to_deg(value, is_longitude):
+    # convert decimal coordinates into degrees, minutes and seconds tuple
+    # Keyword arguments:
+    #   value is float gps-value,
+    #   loc is direction list ["S", "N"] or ["W", "E"]
+    # return: tuple like (25, 13, 48.343 ,'N')
+    loc = ["W", "E"] if is_longitude else ["S", "N"]
+
+    if value < 0:
+        loc_value = loc[0]
+    elif value > 0:
+        loc_value = loc[1]
+    else:
+        loc_value = ""
+    abs_value = abs(value)
+    deg = int(abs_value)
+    t1 = (abs_value - deg) * 60
+    min = int(t1)
+    sec = round((t1 - min) * 60, 5)
+    return deg, min, sec, loc_value

pushframe/export.py

@@ -0,0 +1,53 @@
+import os
+import shutil
+from datetime import datetime
+from io import BytesIO
+from loguru import logger
+from PIL import Image, UnidentifiedImageError
+import httpx
+
+from pushframe.exif import ExifWriter
+from pushframe.models.asset import Asset
+from pushframe.utils import settings
+
+
+def _get_path_safe_datetime(date_str: datetime):
+    return date_str.strftime('%Y%m%dT%H%M%S')
+
+
+def get_thumbnail(asset: Asset, original_image: BytesIO = None):
+    """
+    Aura thumbnails can be saved incorrectly, we can generate our own if we have the original image.
+    TODO: We could also check the other fields on `Asset` to see if there are smaller images instead of using PIL.
+    """
+    thumbnail_response = httpx.get(asset.thumbnail_url)
+    thumbnail_bytes = BytesIO(thumbnail_response.content)
+    try:
+        with Image.open(thumbnail_bytes) as http_thumbnail:
+            http_thumbnail.verify()
+    except UnidentifiedImageError:
+        if not original_image:
+            return None
+
+        with Image.open(original_image) as pil_image:
+            out_bytes = BytesIO()
+            pil_image.thumbnail((100, 100))
+            pil_image.save(out_bytes, 'jpeg')
+            return out_bytes.getvalue()
+
+    return thumbnail_bytes.getvalue()
+
+
+def get_image_from_asset(asset: Asset, path: str, exif_writer: ExifWriter = None, ignore_cache=False):
+    new_filename = os.path.join(path, f'{_get_path_safe_datetime(asset.taken_at_dt)}-{asset.file_name}')
+    if (os.path.isfile(new_filename) and not ignore_cache):
+        with open(new_filename, 'rb') as in_file:
+            return in_file.read()
+    original_image_bytes = httpx.get(f'{settings.IMAGE_PROXY_BASE_URL}/{asset.user_id}/{asset.file_name}').content
+
+    thumbnail = get_thumbnail(asset, BytesIO(original_image_bytes)) if exif_writer else None
+    image = exif_writer.write_exif(original_image_bytes, asset, thumbnail)
+
+    with open(new_filename, 'wb') as out:
+        shutil.copyfileobj(image, out)
+    return original_image_bytes

pushframe/google/__init__.py

@@ -0,0 +1,43 @@
+"""Google Photos integration package (phase 17 — LGS-02..05, TEST-02).
+
+The phase-16-proven mechanics, migrated from the `probes/` instruments into
+production shape:
+
+- `GoogleSession` (`client`) — full-cookie-jar httpx client over
+  photos.google.com, built from the 0600 cookie vault (`vault`, denylist
+  boundary carried over verbatim), with the harvesting browser's UA;
+- parsers (`parsers`) — share-page ds:1 and snAcKc RPC payloads (shared §1b
+  item shape), batchexecute envelope splitting, fail-loud everywhere;
+- enumeration (`enumerate`) — the snAcKc continuation loop (300/page, AH_
+  token swap, clean exhaustion) and the disk-weight measurer (1-byte Range
+  GETs → Content-Range totals);
+- redaction (`redaction`) — every printable URL goes through the helpers.
+
+Everything Google-facing is offline-tested through injected transports
+(TEST-02): zero live network in the test suite.
+"""
+from pushframe.google.client import GoogleSession, GoogleSessionError
+from pushframe.google.parsers import (
+    BatchexecuteEntry,
+    ProbeParseError,
+    SnackcPage,
+    parse_af_initdata,
+    parse_batchexecute,
+    parse_snackc_payload,
+)
+from pushframe.google.redaction import redact_link, redact_tokens
+from pushframe.google.vault import CookieVaultError
+
+__all__ = [
+    "GoogleSession",
+    "GoogleSessionError",
+    "CookieVaultError",
+    "ProbeParseError",
+    "SnackcPage",
+    "BatchexecuteEntry",
+    "parse_af_initdata",
+    "parse_snackc_payload",
+    "parse_batchexecute",
+    "redact_link",
+    "redact_tokens",
+]

pushframe/google/bootstrap.py

@@ -0,0 +1,134 @@
+"""Interactive Google bootstrap: dedicated-profile browser harvest.
+
+Migrated from probes/browser_bootstrap.py's `_bootstrap` (phase 16,
+live-proven). The CLI's `google-link` drives it through a `bootstrap_fn`
+seam so offline tests inject a fake and never launch a browser (TEST-02).
+
+Posture carried over (T-16-06): the DAILY-DRIVER profile is structurally
+unreachable — the dedicated profile directory must be named by
+`AURA_PROBE_CHROME_PROFILE` before any browser exists; unset/empty fails
+loud with the exact remedy. Playwright is imported lazily INSIDE
+`run_bootstrap` only — importing this module never requires playwright
+(BROWSER-AUTOMATION §4.2 isolation rule).
+
+Output discipline (T-16-07): identity signals only — cookie NAMES and
+counts, never values; the vault path is printed, never its contents.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import time
+from pathlib import Path
+
+from pushframe.google import vault
+from pushframe.google.client import PHOTOS_HOME
+
+PROFILE_ENV_VAR = "PUSHFRAME_PROBE_CHROME_PROFILE"
+# IDN-04: the AURA_* spelling stays readable for one release of grace.
+_LEGACY_PROFILE_ENV_VAR = "AURA_PROBE_CHROME_PROFILE"
+
+_AUTO_WAIT_SECONDS = 30 * 60  # the operator may log in much later
+
+# Identity-signal cookie names (names only, never values).
+_AUTH_MARKER_NAMES = ("SID", "SAPISID", "__Secure-1PSID", "__Secure-3PSID",
+                      "LSID", "__Secure-1PAPISID", "__Secure-3PAPISID")
+
+# Login-completion markers for auto-detect.
+_AUTH_COMPLETION_MARKERS = {"SAPISID", "__Secure-1PAPISID", "__Secure-3PAPISID"}
+
+
+class BootstrapError(RuntimeError):
+    """Bootstrap prerequisites missing or the login never completed."""
+
+
+def _require_profile() -> Path:
+    """Resolve the dedicated profile directory; fail loud when unset (T-16-06)."""
+    profile = os.environ.get(PROFILE_ENV_VAR, "").strip()
+    if not profile:
+        profile = os.environ.get(_LEGACY_PROFILE_ENV_VAR, "").strip()
+    if not profile:
+        raise BootstrapError(
+            f"{PROFILE_ENV_VAR} is unset — the daily-driver profile is "
+            f"structurally unreachable; point the env var at a dedicated "
+            f"profile directory (e.g. ~/.config/pushframe/chrome-profile) "
+            f"and re-run (T-16-06)"
+        )
+    path = Path(profile).expanduser().resolve()
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def run_bootstrap(*, auto: bool = False) -> dict:
+    """Open the dedicated-profile browser, harvest cookies, save the vault.
+
+    auto=True polls the context for completed Google auth (SAPISID-family
+    cookies) instead of waiting for an Enter in the terminal — for runs
+    launched from a non-interactive shell. Returns an identity summary dict:
+    {vault_path, cookie_count, auth_markers} — never cookie values.
+    """
+    profile_dir = _require_profile()
+    from playwright.sync_api import sync_playwright  # lazy, in-function import ONLY
+
+    print(f"dedicated profile: {profile_dir}")
+    print("opening browser — log into Google in the window.")
+    # Anti-bot-detection posture (BROWSER-AUTOMATION §2): channel="chrome"
+    # uses the REAL installed Google Chrome when present (Google's risk
+    # engine already treats it as an ordinary browser); otherwise bundled
+    # Chromium with automation switches masked so navigator.webdriver stays
+    # false.
+    has_chrome = shutil.which("google-chrome") is not None
+    launch_kwargs = dict(user_data_dir=str(profile_dir), headless=False,
+                         args=["--disable-blink-features=AutomationControlled"])
+    if has_chrome:
+        launch_kwargs["channel"] = "chrome"
+        print("browser: system Google Chrome (channel=chrome)")
+    else:
+        launch_kwargs["ignore_default_args"] = ["--enable-automation"]
+        print("browser: bundled Chromium (automation switches masked)")
+    with sync_playwright() as p:
+        context = p.chromium.launch_persistent_context(**launch_kwargs)
+        page = context.pages[0] if context.pages else context.new_page()
+        page.goto(PHOTOS_HOME, wait_until="domcontentloaded")
+        if auto:
+            print(f"waiting for login to complete (auto-detect, "
+                  f"{_AUTO_WAIT_SECONDS // 60} min timeout)…", flush=True)
+            deadline = time.monotonic() + _AUTO_WAIT_SECONDS
+            auth_names: set[str] = set()
+            while time.monotonic() < deadline:
+                cookies = context.cookies()
+                auth_names = {c["name"] for c in cookies
+                              if c["name"] in _AUTH_COMPLETION_MARKERS}
+                if auth_names:
+                    break
+                time.sleep(2)
+            if not auth_names:
+                context.close()
+                raise BootstrapError(
+                    "no auth cookies detected within the wait window — was the "
+                    "login completed in the opened window?"
+                )
+            print(f"login detected via {sorted(auth_names)} — harvesting", flush=True)
+            cookies = context.cookies()
+            context.close()
+        else:
+            input("…press Enter here AFTER logging in on the opened window> ")
+            cookies = context.cookies()
+            context.close()
+
+    if not any(c["name"] in ("SID", "SAPISID", "__Secure-1PSID") for c in cookies):
+        raise BootstrapError(
+            "no Google session cookies found after login — was the login "
+            "completed in the opened window?"
+        )
+
+    vault_path = vault.save(cookies)
+    markers = sorted({c["name"] for c in cookies if c["name"] in _AUTH_MARKER_NAMES})
+    return {"vault_path": vault_path, "cookie_count": len(cookies),
+            "auth_markers": markers}
+
+
+def default_bootstrap(*, auto: bool = True) -> dict:
+    """The CLI's default `bootstrap_fn`: interactive harvest with auto-detect
+    (the non-interactive-friendly posture the phase-16 probe settled on)."""
+    return run_bootstrap(auto=auto)