gflow-cli 0.17.0__tar.gz → 0.19.0__tar.gz

{gflow_cli-0.17.0 → gflow_cli-0.19.0}/.env.template

@@ -106,6 +106,15 @@
 # visible window). The session is still reused from the persistent profile.
 # GFLOW_CLI_HEADLESS=true
 
+# Browser automation engine — playwright (default) | patchright
+# patchright is an OPT-IN, drop-in patched Playwright (Chromium) that avoids the
+# Runtime.enable CDP leak for stronger reCAPTCHA-Enterprise evasion on the HEADED
+# path. It is NOT a headless unlock. Requires a separate install:
+#   pip install patchright        (or: pip install 'gflow-cli[patchright]')
+# When using system Chrome (channel=chrome, the gflow default) you do NOT need
+# `patchright install chromium`. Unset to revert to the default playwright engine.
+# GFLOW_CLI_BROWSER_ENGINE=playwright
+
 # BCP-47 locale tag passed to Playwright's launch `locale=` parameter
 # (controls Accept-Language only — Chrome's UI language is forced to
 # en-US via the `--lang=en-US` launch arg regardless of this setting, so

{gflow_cli-0.17.0 → gflow_cli-0.19.0}/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.0] — 2026-06-12
+
+### Added
+
+- **Opt-in Patchright browser engine** via `GFLOW_CLI_BROWSER_ENGINE=patchright`
+  (default `playwright`, unchanged). Patchright is a drop-in patched Playwright
+  (Chromium) that runs page evaluations in an isolated execution context to
+  avoid the `Runtime.enable` CDP leak, for stronger reCAPTCHA-Enterprise evasion
+  on the **headed** path. It is **not** a headless unlock and must be installed
+  separately: `pip install 'gflow-cli[patchright]'`. The default engine is
+  byte-identical to before. `gflow auth status` now reports the active engine.
+- `BrowserEngineUnavailableError` (exit code 24): selecting `patchright` without
+  the package installed now fails with a clear `pip install patchright`
+  remediation hint instead of a raw `ImportError` hashed to a generic exit 1.
+
+### Fixed
+
+- An invalid `GFLOW_CLI_*` enum value (e.g. a typo'd `GFLOW_CLI_BROWSER_ENGINE`,
+  `GFLOW_CLI_PROVIDER`, or `GFLOW_CLI_LOG_LEVEL`) now fails with a clean
+  configuration error and **exit code 11** naming the offending variable, instead
+  of leaking a raw pydantic `ValidationError` traceback and exiting 1.
+
+## [0.18.0] — 2026-06-12
+
+### Added
+
+- `UiSelectorDriftError` (exit code 23): UI-automation selector-probe failures — e.g. the
+  mode-switch `crop_*` trigger missing from the Flow editor (issue #183) — now raise a typed
+  error carrying the probe name, the debug-screenshot path, and a remediation hint, instead
+  of an opaque "Unexpected error" (exit 1) whose message was hashed away in logs. Converted
+  probes: mode-switch trigger, Image/Video mode tabs, and video sub-mode tabs, in both the
+  image and video transports.
+
+### Fixed
+
+- `gflow image` commands (`t2i` / `i2i` / `upscale` / `upload`) now plumb their output
+  directory into the API client, so debug screenshots are actually captured on
+  UI-automation failures. Previously the transport's screenshot directory was never set on
+  the image path and drift errors reported `Screenshot: None` even with `--verbose`.
+
 ## [0.17.0] — 2026-06-12
 
 ### Added
@@ -1509,7 +1549,9 @@ shell-script template that branches on these codes.
 
 First skeleton. Not functional end-to-end yet.
 
-[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.17.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.19.0...HEAD
+[0.19.0]: https://github.com/ffroliva/gflow-cli/compare/v0.18.0...v0.19.0
+[0.18.0]: https://github.com/ffroliva/gflow-cli/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/ffroliva/gflow-cli/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/ffroliva/gflow-cli/compare/v0.15.1...v0.16.0
 [0.15.1]: https://github.com/ffroliva/gflow-cli/compare/v0.15.0...v0.15.1

{gflow_cli-0.17.0 → gflow_cli-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.17.0
+Version: 0.19.0
 Summary: Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal.
 Project-URL: Homepage, https://github.com/ffroliva/gflow-cli
 Project-URL: Issues, https://github.com/ffroliva/gflow-cli/issues
@@ -58,6 +58,8 @@ Requires-Dist: ruff>=0.15.16; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'
+Provides-Extra: patchright
+Requires-Dist: patchright==1.60.1; extra == 'patchright'
 Provides-Extra: s3
 Requires-Dist: s3fs>=2024.2.0; extra == 's3'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 's3'

{gflow_cli-0.17.0 → gflow_cli-0.19.0}/docs/CONFIGURATION.md

@@ -190,6 +190,16 @@ GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 **Default:** `true`
 **When to flip to `false`:** if reCAPTCHA Enterprise refuses to mint tokens (Google's bot-detection sometimes refuses headless Chromium but accepts a visible window). Set to `false` and re-run; the browser will appear during generation but the session is still reused from the persistent profile.
 
+### `GFLOW_CLI_BROWSER_ENGINE`
+
+**What:** Selects the browser-automation engine backing the Playwright API.
+**Values:** `playwright` | `patchright`
+**Default:** `playwright`
+**What `patchright` is:** an opt-in, drop-in patched Playwright (Chromium) that runs page evaluations in an isolated execution context to avoid the `Runtime.enable` CDP leak, for stronger reCAPTCHA-Enterprise evasion on the **headed** path. It is **not** a headless unlock — Google still detects headless Chromium regardless of engine.
+**Install:** `pip install 'gflow-cli[patchright]'` (or `pip install patchright`). Selecting `patchright` without it installed fails fast with exit code 24 and a pip remediation hint. When using system Chrome (the gflow default, `channel=chrome`) you do **not** need `patchright install chromium`.
+**Reverting:** unset the variable (or set `playwright`) — the default path is byte-identical to a build without this feature, with no profile migration.
+**Security note:** the `patchright` extra ships a *patched Chromium driver* that handles your live Google session cookies; it is exact-pinned and treated as a security-review-required dependency. See [SECURITY.md § Dependencies](SECURITY.md).
+
 ### `GFLOW_CLI_LOCALE`
 
 **What:** BCP-47 locale tag passed to Playwright's `launch_persistent_context(locale=...)` — controls the `Accept-Language` HTTP header only.

{gflow_cli-0.17.0 → gflow_cli-0.19.0}/docs/INDEX.md

@@ -111,7 +111,7 @@ Slash commands for Claude Code, stored in `.claude/commands/gflow/`. All prefixe
 **"A gflow command hangs / fails — where do I start?"** → [DEBUGGING § Quick reference](DEBUGGING.md#quick-reference)
 **"Flow's UI broke a selector — how do I diagnose it?"** → [DEBUGGING § Inspecting Flow's live UI](DEBUGGING.md#inspecting-flows-live-ui)
 **"What does each `ui_automation.*` log event mean?"** → [DEBUGGING § Listener & HTTP-layer debugging](DEBUGGING.md#listener--http-layer-debugging)
-**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.17.0](LIVE_VERIFICATION_v0.17.0.md) (#168 cookie verification live e2e_auth; #177 exit-7 hint recorded not-triggerable, credit-free). v0.14.0 / v0.15.0 / v0.15.1 shipped without a dedicated doc (CI + the v0.13.0 baseline). Prior: [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
+**"What was actually live-verified for the latest release?"** → latest: [LIVE_VERIFICATION_v0.19.0](LIVE_VERIFICATION_v0.19.0.md) (opt-in patchright engine: credit-free `image t2i` end-to-end under `GFLOW_CLI_BROWSER_ENGINE=patchright`, 5-layer ledger + missing-dep/invalid-enum/default-path checks; 403→200 premise documented as pending a hot profile). v0.14.0 / v0.15.0 / v0.15.1 shipped without a dedicated doc (CI + the v0.13.0 baseline). Prior: [v0.18.0](LIVE_VERIFICATION_v0.18.0.md) · [v0.17.0](LIVE_VERIFICATION_v0.17.0.md) · [v0.16.0](LIVE_VERIFICATION_v0.16.0.md) · [v0.13.0](LIVE_VERIFICATION_v0.13.0.md) · [v0.12.0](LIVE_VERIFICATION_v0.12.0.md) · [v0.11.0](LIVE_VERIFICATION_v0.11.0.md) · [v0.10.0](LIVE_VERIFICATION_v0.10.0.md) · [v0.9.1](LIVE_VERIFICATION_v0.9.1.md) · [v0.9.0](LIVE_VERIFICATION_v0.9.0.md) · [v0.8.1](LIVE_VERIFICATION_v0.8.1.md) · [v0.7.0](LIVE_VERIFICATION_v0.7.0.md)
 **"Where is the reverse-engineered wire protocol for a feature?"** → the `*_RECON.md` design docs: [CHARACTER_RECON](CHARACTER_RECON.md) (Flow character entity protocol), [IMAGE_UPSCALE_RECON](IMAGE_UPSCALE_RECON.md) (`/v1/flow/upsampleImage` wire). Naming convention: one `<FEATURE>_RECON.md` per reverse-engineered surface, kept as the durable spec after the feature ships.
 **"What was live-verified for the data layer (PR #58)?"** → [LIVE_VERIFICATION_data_layer](LIVE_VERIFICATION_data_layer.md) — 1 Imagen + 1 Veo credit on denon82, 6-layer ledger (file + magic + Pillow + DB rows + CLI round-trip + structlog)
 **"What was live-verified for the video-download feature (#29)?"** → [LIVE_VERIFICATION_video_download](LIVE_VERIFICATION_video_download.md)

gflow_cli-0.19.0/docs/LIVE_VERIFICATION_v0.18.0.md

@@ -0,0 +1,72 @@
+# Live verification — v0.18.0
+
+> Evidence record for the v0.18.0 release. v0.18.0 ships one feature — typed
+> `UiSelectorDriftError` (exit code 23) for UI-automation selector-probe failures
+> (issue #183, PR #184) — and one fix: the `gflow image` command family now wires
+> its output directory into the API client so debug screenshots are actually
+> captured on UI-automation failures.
+
+## Summary
+
+- **Verified by:** ffroliva (Claude Code)
+- **Date:** 2026-06-12 (live runs on the PR #184 head `45ae442`, merged unchanged
+  into `develop @ 9f1d80b`)
+- **gflow-cli version:** 0.18.0 (pre-tag verification)
+- **Status:** 🟢 Green — both the failure path (drift simulation) and the happy
+  path live-verified, **credit-free** (image generation spends no Veo credits)
+
+## 1. Pre-tag gates
+
+- `ruff check src tests` — clean; `ruff format --check` — 220 files formatted
+- `pyright src` — 0 errors (7 pre-existing `browser_cookie3` resolution errors in
+  the local env only, untouched `auth/cookies.py`; CI green)
+- Scoped pytest (errors + transports + cli surfaces) — 475 passed, 1 skipped
+- PR #184 CI — 7/7 checks green on `45ae442` (test matrix 3.11/3.12/3.13,
+  gitleaks, SonarCloud)
+
+## 2. Failure path — live drift simulation (the issue-#183 condition)
+
+`MODE_SWITCH_TRIGGER_SELECTORS` was patched (in both transport module namespaces)
+to a guaranteed-miss selector, reproducing exactly the reporter's DOM condition —
+the crop_* mode-switch trigger absent from the Flow editor. The real CLI t2i path
+was then run against live Flow (profile `denon82`, project created, $0 credits —
+the failure fires before any generation).
+
+| Ledger layer | Evidence |
+|---|---|
+| Exit code | **23** (`UiSelectorDriftError` via `EXIT_CODE_MAP`) |
+| File count | 1 — `debug_no_mode_trigger.png` written to the `--out` dir |
+| Magic bytes | `\x89PNG\r\n\x1a\n` ✅ (valid PNG) |
+| Dimensions | 1280×720 (Pillow) |
+| structlog invariants | `selector_miss` ×1 (bogus selector) → `selector_probe_failed` → `error_raised` with full RFC 9457 problem payload; **zero** `error_unhandled` / `message_hash` events |
+| User-visible artifact | `Flow UI selector drift: probe=mode_switch_trigger: no matching element found on the Flow editor. Screenshot: <out-dir>/debug_no_mode_trigger.png` + remediation hint (no `--verbose` claim, PII warning present) |
+
+This is the user-facing contract the release exists for: the issue-#183 reporter
+saw `Unexpected error` (exit 1) with the real message hashed away; on v0.18.0 the
+same condition produces an actionable, screenshot-carrying exit-23 error.
+
+## 3. Happy path — mode-switch unregressed
+
+`gflow --verbose image t2i "<prompt>" --profile denon82 --aspect 9:16 --out <dir>`
+against live Flow:
+
+| Ledger layer | Evidence |
+|---|---|
+| Exit code | 0 |
+| File count | 1 (`ec262f4c-….jpg`) |
+| Magic bytes | `\xff\xd8\xff` ✅ (valid JPEG) |
+| Dimensions | 768×1376 (portrait — matches `--aspect 9:16`) |
+| structlog invariants | `image_mode_entered` fired (mode-switch dropdown found and used); no `UiSelectorDriftError` in the run |
+| User gallery | image present in the Flow project gallery (denon82) |
+
+## 4. Not verified this cycle (recorded, not omitted)
+
+- **The drift error on a genuinely affected account:** the issue-#183 reporter's
+  account is in the (suspected) issue-#174 new-UI A/B cohort; both maintainer
+  accounts probed as the old dialog UI on 2026-06-12, so the organic condition is
+  not reproducible on our side. The simulation in § 2 exercises the identical
+  code path (selector cascade miss → typed raise → CLI boundary → exit 23).
+  Reporter confirmation is requested on #183.
+- **`cli_character.py` screenshot wiring:** intentionally out of scope for this
+  release (tracked as a follow-up); its drift errors correctly omit the
+  `Screenshot:` clause.

gflow_cli-0.19.0/docs/LIVE_VERIFICATION_v0.19.0.md

@@ -0,0 +1,60 @@
+# Live Verification — v0.19.0
+
+Feature under test: **opt-in Patchright browser engine** (`GFLOW_CLI_BROWSER_ENGINE=patchright`).
+Verified 2026-06-12 against live Google Flow on a real authenticated profile. Image
+generation is credit-free, so the end-to-end run cost **$0**.
+
+## Layer 1 — file count
+
+One image produced by `gflow image t2i` through the integrated patchright path:
+
+```
+scripts/dev/_spike_out/patch_verify/images/2026-06-12/6cb21d9e-e4f9-40ba-897c-eb25c6333892_1.jpg
+```
+
+(written to a throwaway `GFLOW_CLI_OUTPUT_DIR`, since cleaned up).
+
+## Layer 2 — magic bytes
+
+`b[:3] == FF D8 FF` → **valid JPEG**. Size 723,911 bytes.
+
+## Layer 3 — dimensions / shape
+
+Pillow: `format=JPEG dims=(768, 1376)` → correct **9:16** portrait (the default aspect).
+
+## Layer 4 — structlog invariants
+
+From the live run (`correlation_id=40877345-0af4-472f-966a-94f88112f0d9`):
+
+- `browser.engine_selected engine=patchright` — the **settings resolver** selected
+  patchright (the real wired path, not a test monkeypatch).
+- `ui_automation.batch_request_body` — prompt submitted (`bytes=5054`).
+- `ui_automation.batch_response_seen status=200` and
+  `ui_automation.batch_response_captured status=200` — `batchGenerateImages`
+  returned 200 and the response body parsed under patchright.
+
+## Layer 5 — user-confirmable artifact
+
+A studio-lit image of "a small green cactus in a terracotta pot" — visually
+inspectable, matches the prompt.
+
+## Supporting checks (same release)
+
+| Check | Evidence | Result |
+|---|---|---|
+| Default path byte-identical | client-level `navigator.webdriver` read through real `FlowApiClient`: `playwright → None` (masked), `patchright → False` (both non-bot) | ✅ default still stealthed |
+| Missing-dependency UX | `GFLOW_CLI_BROWSER_ENGINE=patchright` with patchright uninstalled → `image t2i` | ✅ **exit 24**, `BrowserEngineUnavailableError` + `pip install patchright` hint, no traceback, no browser launched |
+| Invalid enum setting | `GFLOW_CLI_BROWSER_ENGINE=patchwright` (and `GFLOW_CLI_PROVIDER=bogus`) | ✅ **exit 11**, clean "Configuration error" naming the variable, no raw pydantic traceback |
+| reCAPTCHA mint under patchright | `TokenMinter.mint` with `isolated_context=False` | ✅ returns a real token (the predicted isolated-world break, fixed) |
+| Retry across engine boundary | patchright's distinct `TimeoutError` through the real retry policy | ✅ retried (unit test) |
+
+## Premise still pending (documented, not a blocker)
+
+The *value* premise — does patchright reduce real 403s vs Playwright — could **not**
+be measured this cycle: the documented hot profile (`denon82`) had cooled, so plain
+Playwright also returned 200 (no 403 to flip). A faithful 403 cannot be emulated
+locally (a route-injected 403 is engine-blind; inflating real WAF heat risks the
+account). The feature ships as a **proven non-breaking, opt-in escape-hatch** with
+the default unchanged. Re-fire trigger: the instant any profile actually 403s, run
+`scripts/dev/spike_patchright.py --profile <hot> --engines playwright,patchright`
+to capture the `WAF_403 → OK_200` differential.

{gflow_cli-0.17.0 → gflow_cli-0.19.0}/docs/SECURITY.md

@@ -201,6 +201,26 @@ Audited with `pip-audit` in CI on every push. Major dependency surface:
 
 No transitive dep with known CVEs at the time of v0.1.0 scaffold.
 
+### Optional `patchright` engine — elevated supply-chain trust
+
+The `gflow-cli[patchright]` extra (opt-in via `GFLOW_CLI_BROWSER_ENGINE=patchright`)
+installs **Patchright**, a single-maintainer package that ships a **patched
+Chromium driver**. Because that driver *is* the browser process that loads your
+real Google session — it has direct access to session cookies, the OAuth Bearer
+token, and SAPISID — it carries a higher blast radius than an ordinary Python
+dependency: a compromised release could exfiltrate the full Google session.
+
+Controls:
+
+- **Optional-only** — never in the base `dependencies`; the default install pulls
+  neither the package nor its driver.
+- **Exact-pinned** (`patchright==1.60.1`) so a release cannot silently move the
+  browser binary underneath you.
+- **Security-review-required on bump** — a Patchright version change is treated
+  like a browser-binary change, NOT a routine dependabot auto-merge.
+- Default engine is `playwright` (Microsoft, security-reviewed); patchright is an
+  experiment you opt into per the trade-off above.
+
 ## Reporting
 
 | Issue type | How |

{gflow_cli-0.17.0 → gflow_cli-0.19.0}/docs/USAGE.md

@@ -1022,9 +1022,16 @@ shell scripts can branch on the failure mode without parsing stderr.
 | `12` | `AuthLoginTimeoutError` | Browser sign-in was not completed in time       | Re-run login or raise `GFLOW_CLI_AUTH_LOGIN_TIMEOUT`       |
 | `13` | `SecurityError`       | Unsafe local profile or secret handling blocked   | Follow the error's safety guidance                         |
 | `14` | `AuthBrowserRejectedError` | Google rejected the login browser             | `gflow auth login --browser chrome`                        |
+| `15` | `BrowserSessionClosedError` | The automation browser window was closed mid-operation | Re-run; keep the browser window open until the command finishes |
 | `16` | `DataStoreError`      | Local database cannot be opened, a migration failed, or the DB schema is newer than the installed gflow-cli | See below                                  |
 | `17` | `ModelModeIncompatibilityError` | The chosen video model can't do the requested mode (e.g. `--model omni-flash` with an `i2v` start/end frame — issue #125) | Use `--model veo-lite` (or veo-fast / veo-quality / veo-lite-lp) for `i2v` |
 | `18` | `VideoModelSelectionError` | gflow could not select the requested video model in Flow's editor for an `i2v` run (model-picker option not found) | Usually transient — retry; if it persists, Flow's model-picker UI changed (report referencing #125) |
+| `19` | `SceneConcatError`    | Server-side scene render/concat failed (`gflow scene --output`) | Retry; the recorded compose survives, so re-render is safe |
+| `20` | `FrameExtractionError` | Could not extract the last frame for a video chain link | Check the source video downloaded intact; retry the link  |
+| `21` | `ChainPartialError`   | A video chain stopped mid-way; earlier links completed | Resume from the last completed link shown in the error     |
+| `22` | `UpscaleUnavailableError` | 4K upscale is gated to Flow **Ultra** accounts (HTTP 403) | Use `--scale 2k`, or upgrade the Flow plan                |
+| `23` | `UiSelectorDriftError` | A Flow editor control could not be located — Google changed the frontend (issue #183) | Update gflow-cli; file a bug with the probe name + debug screenshot from the error message |
+| `24` | `BrowserEngineUnavailableError` | `GFLOW_CLI_BROWSER_ENGINE=patchright` but the engine is not installed | `pip install 'gflow-cli[patchright]'`, or unset `GFLOW_CLI_BROWSER_ENGINE` |
 | `130`| SIGINT                | User-interrupted (Ctrl-C)                        | —                                                          |
 
 **Exit code 16 — data store / migration error.** Fires when:

{gflow_cli-0.17.0 → gflow_cli-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.17.0"
+version = "0.19.0"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -58,6 +58,15 @@ s3 = [
 chain = [
     "av>=12",
 ]
+# Patchright engine extra — opt-in, drop-in patched Playwright (Chromium) that
+# avoids the Runtime.enable CDP leak on the headed path. Selected via
+# GFLOW_CLI_BROWSER_ENGINE=patchright. Ships a PATCHED Chromium driver that
+# handles live Google session cookies/Bearer/SAPISID, so it is EXACT-pinned and
+# treated as a security-review-required bump (NOT a dependabot auto-merge) —
+# see SECURITY.md. Not a headless unlock.
+patchright = [
+    "patchright==1.60.1",
+]
 
 [project.scripts]
 gflow = "gflow_cli.cli:main"