pushframe 5.1.7__tar.gz → 5.1.8__tar.gz

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

@@ -12,12 +12,62 @@ every channel.
 `pushframe` is an unofficial community CLI for Aura Frames digital photo
 frames; it is not affiliated with Aura Frames Inc.
 
+## [5.1.8] - 2026-10-01
+
+### Changed
+
+- **Documentation restructured around users, not development history.** The
+  README is now a user guide (highlight → install → connect → everyday use →
+  safety model → troubleshooting) and no longer carries the device-flow
+  transcripts, the write-path research narrative or the open
+  reverse-engineering questions; those moved to a new
+  [`docs/INTERNALS.md`](docs/INTERNALS.md) ("how it works" for curious
+  readers). docs/CLI.md's reconcile evidence story is condensed to what a
+  user needs. No behavior change.
+
+### Added
+
+- **Every failed command now points at the documentation from the terminal**:
+  any non-zero exit prints one footer with the URLs of docs/ERRORS.md (every
+  error message explained) and docs/CLI.md (full command reference). It never
+  appears on success — a dry run or an aborted confirmation stays output-only.
+- `docs/ERRORS.md`: every error message explained by symptom, meaning and
+  remedy (login/session, the refused-write 401 family, resolution ambiguity,
+  the Google safety gates, pacing/budget, scheduling) — the user's map from
+  "what does this message mean" to "what do I do".
+- `docs/DEVELOPING.md`: the contributor guide — project layout, environment,
+  conventions (plain-language user text, offline-test contract, changelog
+  discipline), the verified-increment working method, and the release
+  process (one tag → PyPI + APT + GitHub Releases).
+- `docs/INTERNALS.md`: how pushframe works internally — the
+  reverse-engineered cloud API, the Google mirror engine (cache, manifest,
+  safety gates), the anti-abuse findings, the device flows (documented from
+  code, not verified) and the open questions.
+
+### Changed (docs)
+
+- The README's requirements and install sections no longer assume a
+  uv/Python setup: prerequisites are just the two accounts, the install
+  channels are ordered by simplicity (APT repository first — no Python
+  required, then the one-off .deb, then `uv tool install`/pipx, then from
+  source), and each channel states exactly what it needs.
+- `pushframe schedule --help` now answers "what gets scheduled": the timer
+  runs a `google-sync` of the Google album onto the frame (`--pair NAME` →
+  `google-sync "<album>" --frame "<frame>" --apply --yes --scheduled`),
+  with the `--album/--frame`, `--sync-dir` (local-directory sync) and
+  `--at "OnCalendar"` alternatives plus copy-pasteable examples.
+  docs/CLI.md and the README spell out the same.
+- Internal task codes (SAFE-xx, phase N, plan 11-xx, D-xx, MTF/TMR/PRF/SEC,
+  UAT) removed from all user-facing documentation AND from the CLI's own
+  output (`--help` strings, the mass-hide confirmation and the scheduled
+  skip message now speak plain language); two tests pinning the old
+  strings updated.
+
 ## [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
+- **The live progress bar names the primitive that actually runs** (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
@@ -43,11 +93,11 @@ frames; it is not affiliated with Aura Frames Inc.
 
 - **`google-sync --apply` (and `sync --apply` / `push --apply` /
   `reconcile --remove`) no longer crash building the write budget on a
-  token-session host** (venus, 2026-09-30, debug session
+  token-session host** (observed in production, 2026-09-30, debug session
   gsync-apply-budget-none-crash): the budget's account email was read
   from the ENVIRONMENT only while auth resolves env-then-stored-session
   — the config/env duality was broken at exactly that layer. With a
-  stored token session and no env vars (venus's intended posture), the
+  stored token session and no env vars (that install's intended posture), the
   run authenticated fine, printed the plan, took the operator's `y`
   confirmation, then died on `email.encode()` inside the budget state
   filename. The identity now resolves through ONE helper
@@ -64,7 +114,7 @@ frames; it is not affiliated with Aura Frames Inc.
 
 ### Removed
 
-- The phase-24 sweep's `gsync_no_creds` case: with the vault gate standing
+- The preflight sweep's `gsync_no_creds` case: with the vault gate standing
   BEFORE the Aura gate by design, a form-valid fake vault pushed the run
   past the gate onto the REAL Google network with a bogus cookie (the
   5.1.2 network guard covers pushd, not google.com). The Aura-side
@@ -75,13 +125,13 @@ frames; it is not affiliated with Aura Frames Inc.
 ### Fixed
 
 - **`google-sync` no longer claims "no Google session vault" on a healthy
-  vault** (venus, 2026-09-30): the vault preflight probed the default path
+  vault** (observed in production, 2026-09-30): the vault preflight probed the default path
   WITHOUT `expanduser()` — a literal `~` path never exists, so the check
   fired on every machine whose vault was perfectly healthy (a
   `google-link` seconds earlier had saved it) — and its shape check
   demanded a JSON object while the vault is a JSON list of cookie
-  records, so even the right path would have failed. Two stacked
-  phase-24 bugs, masked until now because CI has no vault either and the
+  records, so even the right path would have failed.  Two stacked
+  session-layer bugs, masked until now because CI has no vault either and the
   scheduled `--pair` branch skips this block entirely. One tell was in
   every transcript: `google-link` prints "existing Google session found"
   only when a vault READ succeeds. The preflight now expands the default
@@ -95,10 +145,10 @@ frames; it is not affiliated with Aura Frames Inc.
 ### Added
 
 - **One-shot TTY token refresh on every frames-reading verb** — `status`,
-  `inspect`, `sync`, `push` and `google-sync` (venus, 2026-09-30): when
+  `inspect`, `sync`, `push` and `google-sync` (observed in production, 2026-09-30): when
   the stored token is refused (401) and stdin is a terminal, the command
   offers ONE re-login right there — the new token is persisted and the
-  same run continues (venus proved a fresh login reads green while the
+  same run continues (production proved a fresh login reads green while the
   stored token was dead). All five verbs share one gate
   (`session.frames_read_with_refresh`), so the behavior, the failure
   shapes and the guardrails are byte-identical everywhere. Guardrails:
@@ -113,14 +163,14 @@ frames; it is not affiliated with Aura Frames Inc.
 ### Fixed
 
 - **`pushframe status` no longer tracebacks on a refused frames read**
-  (venus, debug session status-crash-401-trip): a 401 with the trip's
+  (observed in production, debug session status-crash-401-trip): a 401 with the trip's
   `logout:true` body prints a named diagnosis — the remedy is
   `pushframe config` (refresh the stored token; a fresh login read frames
   fine minutes later, so on a READ that body means a dead token first),
   with the 24h-silence protocol reserved for the case where the same
   body recurs on a genuinely fresh login. A 475/429 on the read prints a
   named WAIT (never a re-login suggestion). Every shape exits 1 named —
-  the PRF-02 no-traceback contract now holds on the token path's first
+  the no-traceback contract now holds on the token path's first
   authenticated call.
 
 ## [5.1.3] — 2026-09-30
@@ -128,7 +178,7 @@ frames; it is not affiliated with Aura Frames Inc.
 ### Fixed
 
 - **`pushframe config` — Enter now keeps the stored email, as the banner
-  always promised** (venus, 5.1.2): an empty answer on a configured
+  always promised** (observed on 5.1.2): an empty answer on a configured
   install aborted with "no email given — aborting" instead of keeping
   it. With a stored token, Enter-Enter now finishes the wizard with ZERO
   API calls (the anti-abuse rule: no gratuitous login); typing a new
@@ -166,8 +216,8 @@ frames; it is not affiliated with Aura Frames Inc.
 
 - **The `tests` workflow is green again** (red on master since v5.1.0 —
   not a 5.1.1 regression): the 9 offline tests of the 401-retry and
-  write-throttling suites relied on the pre-phase-24 re-login default
-  (`aura.login`); phase 24 made the default token-aware, which fails
+  write-throttling suites relied on the old unconditional re-login default
+  (`aura.login`); the token-first session work made the default token-aware, which fails
   named off-TTY without env credentials — exactly the CI case. A local
   `.env` with real credentials masked it locally. All 9 `execute_plan`
   call sites now pin `relogin=aura.login`; zero product code changed.
@@ -176,7 +226,7 @@ frames; it is not affiliated with Aura Frames Inc.
 
 ### Changed
 
-- **Credible client identity** (venus 2026-09-30 anti-abuse lesson): the
+- **Credible client identity** (production 2026-09-30 anti-abuse lesson): the
   user agent is now a setting — `USER_AGENT` (env `PUSHFRAME_USER_AGENT`,
   or `pushframe config set USER_AGENT …`) — whose default tracks a
   current Play build (`Aura/4.7.4271 (Android 36; Client)`) instead of
@@ -196,48 +246,48 @@ frames; it is not affiliated with Aura Frames Inc.
 
 ## [5.1.0] — 2026-09-29
 
-### Added (phase 25: Multi-frame & Scheduling)
+### Added
 
-- **Named pairs** (MTF-01): `pushframe config pair add/remove/list` —
-  `pairs` in config.json is a named dict (`{"cadre-venus": {"album": …,
+- **Named pairs**: `pushframe config pair add/remove/list` —
+  `pairs` in config.json is a named dict (`{"family": {"album": …,
   "frame": …}}`); duplicates and unknown names fail named.
-- **`google-sync --pair <name>` / `--all`** (MTF-02/03): per-pair state
+- **`google-sync --pair <name>` / `--all`**: per-pair state
   (manifest `~/.config/pushframe/pairs/<name>/`, cache
   `~/.local/state/pushframe/pairs/<name>/cache/`); `--all` runs every pair
-  in sorted order with ONE shared write budget (account-level SAFE-02);
+  in sorted order with ONE shared write budget (the mass-hide guard applies account-wide);
   a failing pair is reported and never blocks the others; exit 1 if any
   failed.
-- **`pushframe schedule add/list/remove`** (TMR-01..03): systemd USER
+- **`pushframe schedule add/list/remove`**: systemd USER
   timers (no root) — `pushframe-<job>.service/.timer`, oneshot,
   `Restart=no` (the next tick is the retry), `RandomizedDelaySec`, per-job
   log at `~/.local/state/pushframe/<job>.log`. ExecStart is fully
-  non-interactive (token session); **`--scheduled` flips SAFE-02 to
-  skip-and-log** (a timed run never mass-hides silently and never fails
+  non-interactive (token session); **`--scheduled` flips the mass-hide
+  threshold to skip-and-log** (a timed run never mass-hides silently and never fails
   the unit over a safety decision). Preflight names the systemd user
   session requirement with the `loginctl enable-linger` remedy
   (documented; never executed by the tool).
 
 ## [5.0.7] — 2026-09-29
 
-### Added (phase 24: Token-First Sessions & Preflight Sweep)
+### Added (Token-First Sessions & Preflight Sweep)
 
-- **One session path for every command** (SEC-01/02): `inspect`,
+- **One session path for every command**: `inspect`,
   `reconcile`, `sync`, `push` and `google-sync` now run from the stored
   token session (0600) with no password and no login call; env vars stay
   the override; a terminal session gets ONE password prompt whose token is
-  persisted (SEC-01: the password is never written anywhere — file-content
+  persisted (the password is never written anywhere — file-content
   tested); non-interactive runs without credentials fail named.
-- **Token expiry** (D-01): a 401 while resuming the stored session prompts
+- **Token expiry**: a 401 while resuming the stored session prompts
   once in a terminal (new token persisted, command continues) and raises
   `SessionExpiredError` with the remedy in scheduled runs. `execute_plan`'s
   401-retry relogin is token-aware (it previously assumed a password).
-- **`pushframe logout`** (SEC-03, D-02): deletes the stored token (and only
+- **`pushframe logout`**: deletes the stored token (and only
   the token) — email and settings survive, mode stays 0600, idempotent.
-- **Preflights** (PRF-01, D-03): `google-sync` checks the vault up front
+- **Preflights**: `google-sync` checks the vault up front
   (remedy: `google-link` + the headless ssh -X recipe); `sync`/`push` fail
   named on a nonexistent source directory BEFORE any network call (an
   empty directory remains a friendly "nothing to do").
-- **The traceback-free sweep** (PRF-02): a parametrized test over the
+- **The traceback-free sweep**: a parametrized test over the
   failure-mode inventory proves every foreseeable mode ends named, with a
   remedy, and never a traceback.
 
@@ -248,7 +298,7 @@ frames; it is not affiliated with Aura Frames Inc.
   owned by the session path.
 
 ## [5.0.6] — 2026-09-29
-- **`pushframe doctor`** — the field write-probe the venus regressions
+- **`pushframe doctor`** — the field write-probe the production regressions
   demanded: one 4×4 test image through the REAL write path (S3 +
   select_asset + batch_update), verify + cleanup, then a GO/NO-GO verdict
   with the 401 body classified. `--no-write` for reads-only. Closes the
@@ -259,7 +309,7 @@ frames; it is not affiliated with Aura Frames Inc.
 
 ### Added
 
-- **`pushframe config`** (v5.1, phase 23): interactive wizard that asks for
+- **`pushframe config`** (v5.1): interactive wizard that asks for
   the email + password (hidden input), **verifies the login against the real
   Aura API before writing anything**, and stores email + session token —
   never the password — in `~/.config/pushframe/config.json` (0600, atomic
@@ -274,7 +324,7 @@ frames; it is not affiliated with Aura Frames Inc.
 
 ### Fixed
 
-- **`google-sync`/`sync`/`push` apply feedback was opaque** (venus
+- **`google-sync`/`sync`/`push` apply feedback was opaque** (a production
   regression): the progress bar sat silent for minutes at a time — budget
   waits and inter-chunk cooldowns never reached the bar — and failures
   showed a bare `upload FAIL` with no cause. The bar now shows a live
@@ -289,14 +339,14 @@ frames; it is not affiliated with Aura Frames Inc.
 - The abort message on the 5-consecutive-failures breaker now states what
   to expect: confirmed items ARE on the frame, the next run recognizes
   them and will not upload them twice, wait ~30 min before retrying.
-- **Scoped-trip honesty** (second venus regression): `pushframe status`
+- **Scoped-trip honesty** (second production regression): `pushframe status`
   staying green does NOT mean writes will work — the anti-abuse trip can
   be scoped to the assets surface (write endpoints AND the
   `asset_for_local_identifier` verify-probe read) while login/frames keep
   answering. The abort message no longer suggests status as an all-clear;
   it prescribes 60+ min from the abort and a single, solitary retry call.
 - **"Request Unauthenticated" + logout:true identified as the trip's
-  disguise** (fourth venus regression, decisive capture): the body arrived
+  disguise** (fourth production regression, decisive capture): the body arrived
   on a FRESH token immediately after a successful re-login, one item after
   a doctor probe had WRITTEN fine — so Pushd's "Request Unauthenticated"
   here means "we refuse your writes (trip)", not "your token is bad". The
@@ -315,7 +365,7 @@ frames; it is not affiliated with Aura Frames Inc.
   Forwarded only when supplied — the historical default (50) otherwise
   rules. The anti-trip drill (doctor → wait → batch-size) is documented in
   docs/CLI.md.
-- **401 bodies are captured and classified** (third venus regression): an
+- **401 bodies are captured and classified** (third production regression): an
   HTTP 401 exception now carries the server's response body (redacted
   through the same filter as request logs, truncated to 300 chars, also
   debug-logged) — so per-item failure reasons, verify-probe errors and the
@@ -452,7 +502,7 @@ Milestone summary — see `.planning/MILESTONES.md` for the full retros.
   `google-link` (dedicated Chrome profile, cookie vault `0600`),
   `google-album` (full walk, exact byte counts), `google-sync`
   (hide-by-default mirror semantics, pruned cache + persistent manifest,
-  SAFE-01..04 guards); live UAT two-run proof (upload run → zero-upload
+  mirror safety gates); live two-run proof (upload run → zero-upload
   steady state); debt closeout (AWS config out of code, single logger
   per process, transport seam).
 - **v3.0 — direct transport rewrite**: `Client` over `httpx` (HTTP/2),