pushframe 5.1.6__tar.gz → 5.1.7__tar.gz

{pushframe-5.1.6 → pushframe-5.1.7}/CHANGELOG.md

@@ -12,6 +12,31 @@ every channel.
 `pushframe` is an unofficial community CLI for Aura Frames digital photo
 frames; it is not affiliated with Aura Frames Inc.
 
+## [5.1.7] - 2026-10-01
+
+### Fixed
+
+- **The live progress bar names the primitive that actually runs** (D-07,
+  venus 2026-10-01): the removal loop of `execute_plan` emitted a
+  hardcoded `delete` kind on every per-item progress callback, so a hide
+  run's bar read `delete ok <asset>` mid-run even though the final summary
+  correctly said `Hidden` — the wording contract held on plan headers and
+  summaries but not on the live stream. The bar now shows `hide ok` /
+  `delete ok` / `hard-delete ok` matching `removal_mode` (a parametrized
+  test pins one kind per mode).
+
+### Docs
+
+- `docs/CLI.md` aligned with the real CLI surface (full audit against
+  argparse + code): a new Google commands section (`google-link` incl.
+  the browser's auto-close on login detection, `google-album`,
+  `google-sync` with `--pair`/`--all`/`--scheduled` and its 0/1/2 exit
+  codes), the Contents index covering Pairs/Scheduling/Google, the
+  current root usage block (12 verbs), `sync`'s `--batch-size`/
+  `--chunk-delay`, the write-budget identity's env-then-stored-session
+  resolution (5.1.6), the Google-side environment variables, and the
+  removal-verb note on plan lines.
+
 ## [5.1.6] - 2026-09-30
 
 ### Fixed

{pushframe-5.1.6 → pushframe-5.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pushframe
-Version: 5.1.6
+Version: 5.1.7
 Summary: Unofficial community CLI for Aura Frames digital photo frames (sync a local folder or a Google Photos album; not affiliated with Aura Frames Inc.)
 Project-URL: Homepage, https://github.com/coredmp95/pushframe
 Project-URL: Repository, https://github.com/coredmp95/pushframe

{pushframe-5.1.6 → pushframe-5.1.7}/docs/CLI.md

@@ -13,12 +13,15 @@ talks to the frame over your local network — everything goes through your Aura
 
 - [Global usage](#global-usage)
 - [`doctor`](#doctor--can-this-machine-write-today)
+- [Pairs](#pairs--one-album--several-frames-and-back)
+- [Scheduling](#scheduling--systemd-user-timers-no-root)
 - [`config`](#config--set-up-credentials-and-settings-once)
 - [`status`](#status--check-credentials-and-list-frames)
 - [`inspect`](#inspect--look-at-one-frame)
 - [`sync`](#sync--make-a-frame-match-a-directory)
 - [`push`](#push--upload-only-never-removes)
 - [`reconcile`](#reconcile--account-for-stuck-placeholder-rows)
+- [Google commands (`google-link` / `google-album` / `google-sync`)](#google-commands)
 - [Choosing between `sync` and `push`](#choosing-between-sync-and-push)
 - [Environment variables](#environment-variables)
 - [Exit codes](#exit-codes)
@@ -43,11 +46,13 @@ settings stay (the next `pushframe config` proposes your email). Idempotent;
 token material is never printed.
 
 ```
-usage: pushframe [-h] [--version] [--debug] {status,inspect,sync,push} ...
+usage: pushframe [-h] [--version] [--debug]
+                 {status,logout,doctor,config,inspect,sync,push,reconcile,
+                  google-link,google-album,google-sync,schedule} ...
 
 options:
   -h, --help  show this help message and exit
-  --version   show the program version ("pushframe 5.0.0") and exit
+  --version   show the program version (e.g. "pushframe 5.1.6") and exit
   --debug     Show verbose loguru request/response logging on stderr
 ```
 
@@ -282,8 +287,10 @@ it is the value a command would actually use).
 
 ```
 usage: pushframe status [-h]
-```The first command to run. With env credentials it logs in fresh; with a
-stored token session it resumes it (no login call) and lists your frames.
+```
+
+The first command to run. With env credentials it logs in fresh; with a stored token session
+it resumes it (no login call) and lists your frames.
 Nothing is ever written except a session token: if the stored token is
 refused (HTTP 401), an interactive run offers ONE re-login right there and
 continues — a refused fresh login is never retried (that shape is the
@@ -349,7 +356,10 @@ than bugs in this client — see [Known issues](#known-issues):
 ## `sync` — make a frame match a directory
 
 ```
-usage: pushframe sync [-h] --frame FRAME [--apply] [--yes] [--delete | --hard-delete] dir
+usage: pushframe sync [-h] [--frame FRAME] [--apply] [--yes]
+                      [--delete | --hard-delete]
+                      [--batch-size BATCH_SIZE] [--chunk-delay CHUNK_DELAY]
+                      dir
 
 positional arguments:
   dir            Local directory to scan for photos
@@ -362,6 +372,8 @@ options:
                  (frame-scoped; the photo leaves this frame)
   --hard-delete  IRREVERSIBLY destroy gone-local photos instead of hiding them
                  (account-wide; requires typing the exact count to confirm)
+  --batch-size BATCH_SIZE  Assets per select_asset/batch_update call (default 50)
+  --chunk-delay CHUNK_DELAY  Seconds to pause between write chunks (default 5)
 ```
 
 `sync` makes the frame **match the directory**. Photos in the directory but not on the frame
@@ -390,6 +402,9 @@ Already hidden: 3 (no action needed)
 58 frame assets without a content hash (e.g. videos) left untouched
 ```
 
+(The removal line names the verb of the active mode — `To hide:` by
+default, `To delete:` / `To hard-delete:` with the corresponding flag.)
+
 Reading the plan:
 
 | Line | Meaning |
@@ -569,8 +584,12 @@ requests.
 ### Write budget and geo guard
 
 `push` and `sync --apply` both run a client-side token-bucket budget and a geo pre-flight
-check before any write, so the anti-abuse lockout is difficult to reach by accident. The
-budget is persisted between runs under `AURA_STATE_DIR`.
+check before any write, so the anti-abuse lockout is difficult to reach by accident.The budget is persisted between runs under `AURA_STATE_DIR` (default
+`~/.config/pushframe/`), keyed by a hash of the **account identity**: the
+`PUSHFRAME_EMAIL`/`AURA_EMAIL` override when set, otherwise the email of
+the stored session (the same env-then-config resolution auth uses —
+5.1.6). A run with no resolvable identity at all skips pacing with a
+named stderr line instead of crashing.
 
 | Flag | Effect |
 |---|---|
@@ -748,6 +767,71 @@ candidate list.
 (see [Write budget and geo guard](#write-budget-and-geo-guard)) and paces its requests the
 same way.
 
+## Google commands
+
+Three verbs mirror a Google Photos album onto a frame. The full narrative
+(with a verified end-to-end walkthrough, cache/manifest internals and
+SAFE-01..04 semantics) lives in [README.md](../README.md); this is the
+command-level reference.
+
+### `google-link` — link (or re-link) Google Photos
+
+One command for both linking and re-linking: opens a **visible** Chrome
+window (anti-bot posture — never headless) on a dedicated profile, waits
+for the login (auto-detect on auth cookies, 30 min timeout), then
+harvests the session cookies into the vault:
+
+```
+~/.config/pushframe/google-cookies.json   (0600, outside the repo)
+```
+
+The window closes by itself as soon as the login is detected — that is
+the auto-detect working, not a crash. On a headless server, connect with
+`ssh -X` so the window can open on your screen; the vault survives
+logouts and every other command is headless by nature. Profile
+precedence: `PUSHFRAME_PROBE_CHROME_PROFILE` > legacy
+`AURA_PROBE_CHROME_PROFILE` > built-in default (created on demand).
+
+### `google-album` — inspect a shared album
+
+```
+usage: pushframe google-album [-h] [--list] [target]
+```
+
+`--list` lists the account's shared albums (discovery aid). With a
+`target` (share URL, `AF1Qip…` id, or album-name substring — ambiguity
+prints a numbered list and exits 2), enumerates every item with its exact
+disk weight. Read-only.
+
+### `google-sync` — mirror an album onto a frame
+
+```
+usage: pushframe google-sync [-h] [--frame FRAME] [--all] [--pair PAIR]
+                             [--scheduled] [--apply] [--yes] [--debug]
+                             [--batch-size BATCH_SIZE]
+                             album
+```
+
+Dry-run by default. `--apply` runs one y/N (echoing the resolved frame's
+name and id) then mirrors: uploads, and removals as **hides only** —
+this verb has no delete tier (SAFE-03). An empty or truncated album
+listing aborts instead of planning (SAFE-01); a plan whose removals
+exceed the mass-hide threshold needs an explicit confirmation (SAFE-02;
+skip-and-log instead when `--scheduled`); videos are counted and skipped,
+never silently dropped. Prerequisites: the cookie vault (`google-link`,
+checked named before anything else) and an Aura session (same one-session
+path as every verb).
+
+Frame targeting: `--frame "Name"` for one album→frame pair, `--pair NAME`
+for a named pair from the config, or `--all` for every configured pair in
+sorted order with one shared write budget (a failing pair never blocks
+the others; exit 1 if any failed). Exit codes: `0` dry-run/aborted
+confirmation, `1` failure, `2` usage/ambiguity (album not found,
+no pairs configured…).
+
+A real steady-state run prints `Applied: N uploaded, K hidden, R re-shown`,
+then prunes the staging cache — only manifest-backed progress survives.
+
 ## Choosing between `sync` and `push`
 
 |  | `sync` | `push` |
@@ -796,6 +880,18 @@ to adopt one.
 | `AURA_DEVICE_IDENTIFIER` | `0000000000000000` |
 | `AURA_USER_AGENT` | `Aura/4.7.4271 (Android 36; Client)` |
 
+The client-identity defaults are the ones a fresh install ships with —
+`config set DEVICE_IDENTIFIER "$(uuidgen)"` (and optionally `USER_AGENT`)
+overwrites them in the config file, which is the documented posture above.
+
+**Optional — Google-side**
+
+| Variable | Purpose |
+|---|---|
+| `PUSHFRAME_PROBE_CHROME_PROFILE` | Dedicated Chrome profile dir for `google-link` (precedence over the legacy `AURA_PROBE_CHROME_PROFILE`, then the built-in default created on demand) |
+| `PUSHFRAME_GOOGLE_SYNC_REMOVAL_THRESHOLD` | SAFE-02 mass-hide threshold for `google-sync` (fraction of the frame's photos; see README) |
+| `PUSHFRAME_VAULT_PATH` | Override the Google cookie vault path (mainly for tests) |
+
 Booleans accept `1`, `true`, `yes`, `on` (case-insensitive); anything else is false.
 
 ## Exit codes

{pushframe-5.1.6 → pushframe-5.1.7}/pushframe/__init__.py

@@ -1,4 +1,4 @@
 # pushframe — unofficial community CLI for Aura Frames (not affiliated).
 # Version single source for the CLI surface (REL-02); pyproject keeps the
 # packaging metadata version and tests/test_version.py enforces lockstep.
-__version__ = "5.1.6"
+__version__ = "5.1.7"

{pushframe-5.1.6 → pushframe-5.1.7}/pushframe/sync.py

@@ -1112,6 +1112,13 @@ def execute_plan(plan: SyncPlan, aura, frame_id: str, *, s3_client, sqs_client,
         if budget is not None:
             budget.save()
 
+    # D-07 for the LIVE bar too (venus 2026-09-30): the per-item progress
+    # kind must name the primitive that actually runs — a hide run must
+    # never say 'delete ok' mid-bar. Mirrors cli.py's _REMOVAL_VERB_PRESENT
+    # (the report-side wording contract) and gsync's dry-run plan header.
+    removal_verb = {'hide': 'hide', 'delete': 'delete',
+                    'hard_delete': 'hard-delete'}[removal_mode]
+
     for chunk in _chunked(plan.to_delete, batch_size):
         interchunk_pause()
         if budget is not None:
@@ -1130,7 +1137,7 @@ def execute_plan(plan: SyncPlan, aura, frame_id: str, *, s3_client, sqs_client,
                 for asset in chunk:
                     result.delete_succeeded += 1
                     consecutive_failures = 0
-                    progress('delete', asset.id, True)
+                    progress(removal_verb, asset.id, True)
             except httpx.HTTPStatusError as e:
                 # Same rationale as the re-show loop above: this loop acts
                 # on server-assigned asset ids, hiding/removing an
@@ -1157,9 +1164,9 @@ def execute_plan(plan: SyncPlan, aura, frame_id: str, *, s3_client, sqs_client,
                         reason = ('HTTP 401 after a successful re-login -- classified as an '
                                   'anti-abuse trip, not authentication')
                         result.delete_failures.append((asset.id, reason))
-                        progress('delete', asset.id, False)
+                        progress(removal_verb, asset.id, False)
                         note_failure(reason)
-                        on_error('delete', asset.id, False, reason)
+                        on_error(removal_verb, asset.id, False, reason)
                     if budget is not None:
                         budget.save()
                     continue
@@ -1176,7 +1183,7 @@ def execute_plan(plan: SyncPlan, aura, frame_id: str, *, s3_client, sqs_client,
                     for asset in chunk:
                         result.delete_succeeded += 1
                         consecutive_failures = 0
-                        progress('delete', asset.id, True)
+                        progress(removal_verb, asset.id, True)
                 except (RateLimitError, ConsecutiveWriteFailureError):
                     raise
                 except Exception as resend_exc:
@@ -1184,9 +1191,9 @@ def execute_plan(plan: SyncPlan, aura, frame_id: str, *, s3_client, sqs_client,
                     for asset in chunk:
                         reason = f'HTTP 401 retry failed: {resend_exc}'
                         result.delete_failures.append((asset.id, reason))
-                        progress('delete', asset.id, False)
+                        progress(removal_verb, asset.id, False)
                         note_failure(str(resend_exc))
-                        on_error('delete', asset.id, False, str(resend_exc))
+                        on_error(removal_verb, asset.id, False, str(resend_exc))
         except RateLimitError:
             if budget is not None:
                 budget.reconcile_tripped(clock())
@@ -1204,9 +1211,9 @@ def execute_plan(plan: SyncPlan, aura, frame_id: str, *, s3_client, sqs_client,
             # (coarser than upload attribution, T-fyr-01).
             for asset in chunk:
                 result.delete_failures.append((asset.id, str(e)))
-                progress('delete', asset.id, False)
+                progress(removal_verb, asset.id, False)
                 note_failure(str(e))
-                on_error('delete', asset.id, False, str(e))
+                on_error(removal_verb, asset.id, False, str(e))
 
         if budget is not None:
             budget.save()

{pushframe-5.1.6 → pushframe-5.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pushframe"
-version = "5.1.6"
+version = "5.1.7"
 description = "Unofficial community CLI for Aura Frames digital photo frames (sync a local folder or a Google Photos album; not affiliated with Aura Frames Inc.)"
 readme = "README.md"
 requires-python = ">=3.14"

{pushframe-5.1.6 → pushframe-5.1.7}/tests/test_execute_plan.py

@@ -439,12 +439,12 @@ def test_execute_plan_reports_progress_per_item(tmp_path):
     succeeded_upload = [r for r in recorded if r[0] == 'upload' and r[2] is True]
     assert succeeded_upload == [('upload', path_b, True)]
 
-    delete_entries = [r for r in recorded if r[0] == 'delete']
-    assert delete_entries == [('delete', 'asset-good', True)]
+    delete_entries = [r for r in recorded if r[0] == 'hide']
+    assert delete_entries == [('hide', 'asset-good', True)]
 
-    # Every 'upload' entry appears before every 'delete' entry (D-09).
+    # Every 'upload' entry appears before every removal entry (D-09).
     upload_indices = [i for i, r in enumerate(recorded) if r[0] == 'upload']
-    delete_indices = [i for i, r in enumerate(recorded) if r[0] == 'delete']
+    delete_indices = [i for i, r in enumerate(recorded) if r[0] == 'hide']
     assert max(upload_indices) < min(delete_indices)
 
 
@@ -514,6 +514,25 @@ def _run(plan, aura, **kwargs):
                         sqs_client=_FakeSQSClient(), sleep=lambda *_: None, **kwargs)
 
 
+@pytest.mark.parametrize('removal_mode,expected_kind', [
+    ('hide', 'hide'), ('delete', 'delete'), ('hard_delete', 'hard-delete')])
+def test_removal_progress_kind_names_the_running_primitive(removal_mode, expected_kind):
+    """D-07 on the LIVE progress stream (venus 2026-09-30): a hide run's
+    per-item kind must never say 'delete' — the operator watching the bar
+    reads the primitive off it, and the report-side wording contract
+    (_REMOVAL_VERB_PRESENT) already forbids this drift on summaries."""
+    plan = SyncPlan(to_delete=[_asset('a1')])
+    aura = offline_aura(overrides=_default_overrides())
+    recorded: list = []
+
+    _run(plan, aura, removal_mode=removal_mode,
+         progress=lambda kind, identifier, ok: recorded.append((kind, identifier, ok)))
+
+    kinds = {kind for kind, _, _ in recorded}
+    assert kinds == {expected_kind}, \
+        f'{removal_mode} run emitted {kinds!r} — expected {expected_kind!r} only'
+
+
 def test_hide_mode_excludes_and_never_removes_or_deletes():
     """The default mode must reach ONLY the non-destructive primitive."""
     plan = SyncPlan(to_upload=[], to_delete=[_asset('a1'), _asset('a2')])

{pushframe-5.1.6 → pushframe-5.1.7}/tests/test_version.py

@@ -19,7 +19,7 @@ PYPROJECT = Path(__file__).resolve().parent.parent / "pyproject.toml"
 def test_version_is_first_distribution_release():
     """The current distribution release (moved off 0.1.0 at 5.0.0; page
     metadata fix shipped in 5.0.4)."""
-    assert __version__ == "5.1.6"
+    assert __version__ == "5.1.7"
 
 
 def test_version_matches_pyproject_single_source():

{pushframe-5.1.6 → pushframe-5.1.7}/uv.lock

@@ -432,7 +432,7 @@ wheels = [
 
 [[package]]
 name = "pushframe"
-version = "5.1.6"
+version = "5.1.7"
 source = { editable = "." }
 dependencies = [
     { name = "boto3" },