gflow-cli 0.8.1__tar.gz → 0.9.1__tar.gz

{gflow_cli-0.8.1 → gflow_cli-0.9.1}/.claude/commands/gflow/check.md

@@ -32,7 +32,7 @@ uv run pyright src
 **4. Tests + coverage** (report only)
 
 ```bash
-uv run pytest -q --cov=gflow_cli --cov-fail-under=80
+uv run python -m pytest -q --cov=gflow_cli --cov-fail-under=80
 ```
 
 ## Output
@@ -46,3 +46,7 @@ uv run pytest -q --cov=gflow_cli --cov-fail-under=80
 
 Ruff fix and format may rewrite multiple files. Always `git diff` before staging.
 Pyright errors and test failures require manual intervention — do not attempt silent workarounds.
+If the coverage run crashes the current MCP/sandbox session with `Connection closed`, re-run the
+same marker-filtered suite in smaller chunks without coverage and rely on CI for the coverage XML.
+Project pytest defaults already exclude `e2e` and `live`; those markers are explicit,
+credit-spending gates and must be requested with a separate `-m e2e` / `-m live` command.

gflow_cli-0.9.1/.claude/commands/gflow/pr-council-review.md

@@ -0,0 +1,265 @@
+---
+description: Multi-dimensional LLM council review of an open PR. Adaptive dimensions per PR surface (data / transports / CLI / docs / auth). Baseline always includes correctness, code quality, security, and tests. With no argument, lists open PRs ranked by review priority.
+---
+
+# `/gflow:pr-council-review [PR#]` — PR Council Review Gate
+
+Council-driven PR review. Dispatches **4 baseline + N adaptive** parallel reviewers, each scoped to one dimension, then synthesizes a single consensus verdict. Validated on PR #93 (2026-05-26) — see memory `llm-council-code-review-pr93`.
+
+**Two modes:**
+1. **No argument** → list open PRs ranked by review priority; user picks.
+2. **`PR#` argument** → run the full council on that PR.
+
+Treat **YELLOW as soft block** (per memory `llm-council-data-layer-fixes`).
+
+---
+
+## 0 · Pre-flight
+
+**All four checks are mandatory. Any failure halts before Phase 1/2.**
+
+1. **`gh` authenticated** — run `gh auth status`. Non-zero exit → stop with: *"`gh` is not authenticated. Run `gh auth login` and re-invoke."* Do NOT proceed to dispatch agents that would all fail opaquely.
+2. **Inside the repo** — assert `AGENTS.md` AND `CLAUDE.md` exist in the working directory.
+3. **Resolve the argument:**
+   - **Empty** → jump to **Phase 1 (Prioritize)**.
+   - **PR number** → validate it with `gh pr view <N> --json number`. If error → stop with the error verbatim. Do NOT silently fall back to Phase 1.
+4. **Draft check** (PR# mode only) — if `gh pr view <N> --json isDraft` returns `true`, surface a banner citing memory `draft-pr-merge-trap`: *"PR #N is DRAFT. Reviewing is fine, but do NOT merge a draft (the merge API can close it + delete the head ref). Run `gh pr ready N` first if you intend to merge. Continue review? (yes/no)"*. Ask the user before dispatching.
+
+---
+
+## 1 · Prioritize (no-argument mode)
+
+Run once, list open PRs in recommended order, then stop and ask the user which to review.
+
+```bash
+gh pr list --state open --json number,title,author,isDraft,headRefName,updatedAt,additions,deletions,labels,reviewDecision,statusCheckRollup
+```
+
+**Empty-list short-circuit:** if the result is `[]`, print *"No open PRs to review."* and exit. Do NOT render an empty table or fall through to Phase 2.
+
+Rank with these heuristics (highest priority first):
+
+| Signal | Weight | Why |
+|---|---|---|
+| `isDraft == false` AND CI all-green | +3 | Ready to merge once approved — highest ROI |
+| Touched path includes `src/gflow_cli/api/transports/` | +2 | UI-automation is the highest-risk surface (memory `pr-must-verify-on-affected-surface`) |
+| Touched path includes `src/gflow_cli/auth/` or `recaptcha` | +2 | Auth changes need security-deep-dive |
+| Touched path includes `src/gflow_cli/data/` | +2 | Migration safety + #86 hygiene history |
+| Older than 7 days (stale risk) | +1 | Conflict risk grows with age |
+| `additions + deletions <= 300` | +1 | Small PRs ship faster |
+| Label contains `release-blocker`, `security`, `hotfix` | +5 | Anything labelled urgent jumps the queue |
+| `isDraft == true` AND CI red | −2 | Author still iterating; review wastes their time |
+
+Present a numbered table:
+
+```
+| Rank | PR# | Title | Ready? | CI | Surface | Why prioritized |
+|------|-----|-------|--------|----|---------| ---------------|
+| 1 | #71 | feat(image): native count selector …  | ✅ | green | transports | Ready + transports surface + small (220 LOC) |
+| 2 | …
+```
+
+Then **stop and ask** the user to pick a PR number. Do NOT auto-start a review on Rank 1 — *recommend*, do not *pre-select*. The user MUST type the PR number they want reviewed.
+
+---
+
+## 2 · Gather context (PR# mode)
+
+Pull in parallel. Use `ctx_batch_execute` to avoid context-window flood.
+
+**Commands** (label → cmd):
+- `PR_META` → `gh pr view <N> --json title,body,author,baseRefName,headRefName,state,isDraft,additions,deletions,changedFiles,labels,files,statusCheckRollup`
+- `PR_DIFF` → `gh pr diff <N>`
+- `PR_CHECKS` → `gh pr checks <N>`
+- `TOUCHED_PATHS` → `gh pr view <N> --json files --jq '.files[].path' | sort -u`
+- `RECENT_COMMITS` → `gh pr view <N> --json commits --jq '.commits[-5:] | .[] | "\(.oid[:7]) \(.messageHeadline)"'`
+
+**Reference files** (Read inline; small enough to load):
+- `CLAUDE.md` — Claude-Code-specific protocol
+- `AGENTS.md` — universal agent rules
+- `docs/INDEX.md` — docs routing
+- `~/.claude/projects/C--development-github-gflow-cli/memory/MEMORY.md` — memory index
+
+**Memory traversal:** For each `TOUCHED_PATH`, glob memory for related entries:
+- `transports/` (image OR video) → `[[pr-must-verify-on-affected-surface]]`, `[[flow-locale-leak-icon-ligatures]]`, `[[playwright-click-no-downstream-event-signature]]`, `[[rest-transports-drop-ui-fields]]`, `[[image-video-mode-switch-symmetry]]`, `[[video-generation-spec]]`, `[[image-generation-401-next]]`
+- `data/` → `[[data-layer-overview]]`, `[[data-layer-test-pollution-trap]]`, `[[data-layer-v0.9.0-bugs]]`, `[[exit-code-16-data-store]]`, `[[on-started-callback-recorder-safety]]`
+- `auth/` → `[[real-browser-auth-mandatory]]`, `[[release-signing]]`
+- `cli` → `[[release-back-merge-gap-recovery]]`, `[[wheel-build-sanity-gate]]`
+- `tests/` (any) → `[[bdd-stubs-mirror-runtime-signatures]]`, `[[background-e2e-pytest-pattern]]`, `[[full-test-suite-ooms]]`, `[[stale-test-discovery]]`, `[[structlog-cache-logger-off-for-tests]]`
+- `tests/features/` (BDD) → also `[[bdd-stubs-mirror-runtime-signatures]]` (silent TypeError trap)
+- `scripts/` (dev / CI / release helpers) → `[[wheel-build-sanity-gate]]`, `[[release-back-merge-gap-recovery]]`
+- `.planning/`, `docs/superpowers/` (process artifacts) → `[[release-spec-plan-memory-consolidation]]`
+- `docs/`, `*.md` → `[[readme-hybrid-router-pattern]]`, `[[llm-council-doc-review-v0.9.0]]`, `[[agents-md-vs-llms-txt]]`, `[[pypi-readme-staleness-fix]]`
+- `pyproject.toml`, `.github/` → `[[release-spec-plan-memory-consolidation]]`, `[[pr-hygiene-revert-and-multi-commit]]`, `[[draft-pr-merge-trap]]`, `[[pypi-rejected-filename-reusable]]`
+
+---
+
+## 3 · Detect adaptive dimensions
+
+The **baseline** 4 dimensions run for every PR. **Adaptive** dimensions activate only when the touched paths or labels match. Build the council roster before dispatching.
+
+| Dimension | Always? | Activates when… |
+|---|---|---|
+| **D1 — Correctness & completeness** | ✅ baseline | always |
+| **D2 — Code quality & best practices** | ✅ baseline | always |
+| **D3 — Security** | ✅ baseline | always |
+| **D4 — Tests & coverage** | ✅ baseline | always |
+| **D5 — UI / live-verification** | adaptive | any path under `src/gflow_cli/api/transports/` or `tests/e2e/` |
+| **D6 — Data-migration safety** | adaptive | any path under `src/gflow_cli/data/` or `*.sql` |
+| **D7 — CLI UX & help-text consistency** | adaptive | any path matching `src/gflow_cli/cli*.py` or `src/gflow_cli/commands/` |
+| **D8 — Docs cross-reference & drift** | adaptive | ≥2 of these touched: `README.md`, `docs/**`, `CHANGELOG.md`, `AGENTS.md`, `CLAUDE.md`, `PLAN.md` |
+| **D9 — Auth / reCAPTCHA / Chrome-profile** | adaptive | any path under `src/gflow_cli/auth/` or label `security` |
+| **D10 — Release-gate compliance** | adaptive | `pyproject.toml`, `src/gflow_cli/__init__.py`, `.github/workflows/`, or `release/*` branch |
+| **D11 — BDD step-stub signatures** | adaptive | any path under `tests/features/` (silent TypeError trap, memory `bdd-stubs-mirror-runtime-signatures`) |
+| **D12 — Dev / release scripts** | adaptive | any path under `scripts/` |
+
+**Baseline floor is non-negotiable.** D1–D4 ALWAYS run, even on docs-only PRs. The user spec explicitly required quality / security / best-practices / tests as a floor — do not skip.
+
+**Docs-only PRs** (defined as: 100% of touched paths match `*.md`, `docs/**`, `CHANGELOG.md`, `README.md`, `LICENSE`, `AUTHORS`) → D4 reframes from "test code coverage" to "docs-verification" (broken cross-references, dead links, code examples that don't run). The dimension still runs; only its lens shifts.
+
+---
+
+## 4 · Dispatch the council
+
+Use `superpowers:dispatching-parallel-agents`. Send **all** agents in one message — they must run concurrently. Each agent must:
+
+- Get the PR number, base branch, and head branch.
+- Be told its dimension AND told what NOT to duplicate (the other dimensions' scope).
+- Use `ctx_execute` for large outputs (diff, file reads) — never flood the context.
+- Output a structured report: **Verdict (GREEN / YELLOW / RED)**, **Must-fix** (numbered, file:line refs), **Nice-to-have** (numbered), **Confirmed-good/safe/correct** (1-line bullets).
+- Be word-limited to **under 500 words** so the synthesizer doesn't drown.
+
+**Per-dimension prompt skeleton** (fill in `<…>`):
+
+```
+You are one of <N> parallel reviewers on a council reviewing PR #<N> of `gflow-cli` at C:\development\github\gflow-cli.
+
+Your dimension is **<DIMENSION NAME>**. Other agents handle <other dimensions> — do NOT duplicate their work.
+
+Get the diff with `gh pr diff <N>` via ctx_execute. If `additions + deletions > 5000`, do NOT pull the full diff at once — instead enumerate touched files with `gh pr view <N> --json files --jq '.files[].path'`, then read per-directory with `gh pr diff <N> -- <path>` to keep each call under 2k lines. Read the unchanged surrounding code with Read for any file you flag.
+
+Assess specifically:
+1. <dimension-specific question 1, with code citation hooks>
+2. <…>
+3. <…>
+
+**Mandatory memory you MUST consult and cite if relevant** (from the Dimension → Slugs table below): <fixed slug list for this dimension>.
+
+Output a structured report under 500 words:
+- Verdict: GREEN / YELLOW / RED
+- Must-fix (numbered, file:line refs)
+- Nice-to-have (numbered)
+- Confirmed-<good/safe/correct> (1-line bullets)
+
+Be skeptical. Cite file paths and line numbers. **If you have nothing to flag in your dimension, say so explicitly and state GREEN with a one-line justification — do NOT manufacture findings to look thorough.**
+```
+
+**Dimension → mandatory slugs table** (always pass these in the prompt, regardless of which paths the PR touches — they encode the recurring traps for that dimension):
+
+| Dim | Mandatory memory slugs |
+|---|---|
+| D1 | `[[pr-must-verify-on-affected-surface]]` |
+| D2 | (none mandatory; consult surrounding code style) |
+| D3 | `[[real-browser-auth-mandatory]]`, `[[release-signing]]` |
+| D4 | `[[pr-must-verify-on-affected-surface]]`, `[[full-test-suite-ooms]]`, `[[stale-test-discovery]]`, `[[structlog-cache-logger-off-for-tests]]` |
+| D5 | `[[flow-locale-leak-icon-ligatures]]`, `[[playwright-click-no-downstream-event-signature]]`, `[[rest-transports-drop-ui-fields]]`, `[[image-video-mode-switch-symmetry]]`, `[[verification-ledger-5-layer]]` |
+| D6 | `[[on-started-callback-recorder-safety]]`, `[[data-layer-test-pollution-trap]]`, `[[exit-code-16-data-store]]`, `[[data-layer-v0.9.0-bugs]]` |
+| D7 | (none mandatory) |
+| D8 | `[[readme-hybrid-router-pattern]]`, `[[agents-md-vs-llms-txt]]`, `[[pypi-readme-staleness-fix]]`, `[[llm-council-doc-review-v0.9.0]]` |
+| D9 | `[[real-browser-auth-mandatory]]` |
+| D10 | `[[release-back-merge-gap-recovery]]`, `[[wheel-build-sanity-gate]]`, `[[pypi-rejected-filename-reusable]]`, `[[draft-pr-merge-trap]]` |
+| D11 | `[[bdd-stubs-mirror-runtime-signatures]]` |
+| D12 | `[[wheel-build-sanity-gate]]` |
+
+**Per-dimension specifics** (concrete checks each agent must perform):
+
+- **D1 Correctness & completeness:**
+  - Does the fix address the *root cause* or only the symptom? Cite the function being changed.
+  - Are edge cases handled? Spot-check 2 boundary conditions.
+  - Does the CHANGELOG entry match what shipped? Quote both.
+  - **PR-body compliance:** does the PR body's description match the diff? Are the PR body's test-plan checkboxes (the `- [ ]` / `- [x]` markers) accurate? If any unchecked box represents work the PR claims to deliver, flag it. If the PR claims `Closes #N` for an issue whose acceptance criteria are not met by the diff, flag it.
+- **D2 Code quality:** Style consistency with surrounding code? Comments explain WHY not WHAT (per `CLAUDE.md`)? Any abstraction that doesn't earn its keep? SRP intact? Type annotations on every new signature?
+- **D3 Security:** Injection vectors? Env-var trust boundary? Shell interpolation (`subprocess`, `shell=True`)? Path traversal? Secret-shaped literals? `--no-verify` or signature-bypass in commits?
+- **D4 Tests:**
+  - **Mandatory affected-surface check** (cardinal rule, memory `pr-must-verify-on-affected-surface`): identify the runtime surface the fix touches (T2V / I2V / R2V / data / CLI / auth / etc.). If the test suite does not exercise that exact surface (e.g. a fix for `_attach_frame` with only T2V tests), this is **automatically YELLOW**. Cite the test `file:line` that proves coverage of the affected surface — or state explicitly that no such test exists.
+  - Test pyramid placement (unit vs integration vs e2e)?
+  - Do tests verify *behavior* or just shape (static strings, mocked returns)?
+  - Coverage delta meaningful, or dead-coverage (counts new constants without exercising them)?
+- **D5 UI/live-verify:** Will this selector match real Flow DOM on non-EN locales? Is there runtime evidence beyond static-string invariants? Has the PR author pasted live-verify evidence (file count + magic bytes + Pillow dims + structlog events such as `new_project_clicked` / `submit_clicked` / `frame_attached` / `image_mode_entered` / `count_setter_completed` / `reference_attached`) in the PR body or a comment? **Absent live-verify on a UI-automation PR is YELLOW per memory `pr-must-verify-on-affected-surface`.**
+- **D6 Data-migration & on_started safety:**
+  - **Mandatory on_started callback check** (memory `on-started-callback-recorder-safety`): grep the diff for `VideoStartedCallback` / `on_started` / any new callback invoked inside a transport during a paid Flow generation. Verify each callsite is wrapped in `try/except DataStoreError` (and ideally a broad guard). **A bare callback in a paid-generation path is automatically RED** — uncaught exceptions abort paid generation.
+  - Schema-compat with existing rows? Migration script idempotent?
+  - `DataStoreError` vs `DataMigrationError` vs `DataIntegrityError` semantics correct? Pre-Flow failures vs post-success-warn-and-return-0 per memory `exit-code-16-data-store`?
+- **D7 CLI UX:** Help text matches behavior? Flag names follow `--kebab-case`? Does the new flag appear in `--help` golden-snapshot tests? Examples in docstring runnable?
+- **D8 Docs drift:** Cross-references mutually consistent (CLAUDE.md / AGENTS.md / docs/INDEX.md / README.md / PLAN.md)? Code examples actually run? Version strings consistent across files?
+- **D9 Auth:** Chrome-strategy profile required (memory `real-browser-auth-mandatory`)? Profile-dir SecurityError boundary intact (`outside of GFLOW_CLI_HOME`)? No new secret-shaped strings?
+- **D10 Release-gate:**
+  - **Quote the version string** from `pyproject.toml` AND from `src/gflow_cli/__init__.py` and confirm they match exactly. If only one was bumped → RED.
+  - Verify `CHANGELOG.md` `[Unreleased]` was emptied and a new version section added — cite the line range.
+  - Wheel build clean (`uv build` + ZIP-dupe check per memory `wheel-build-sanity-gate`)?
+  - Back-merge gap from prior releases addressed (memory `release-back-merge-gap-recovery`)?
+- **D11 BDD step-stub signatures:** any new `_run_*` kwarg or runtime signature change requires mirroring in `tests/features/_fake_*` stubs — silent `TypeError` trap. Cite each fake stub touched (or assert no signature change occurred).
+- **D12 Dev/release scripts:** any new script must run cleanly on Windows (memory `windows-dev-quirks`); release scripts must include the wheel-build sanity gate.
+
+---
+
+## 5 · Synthesize the verdict
+
+After all agents return:
+
+1. **Tally verdicts:** count GREEN / YELLOW / RED per dimension.
+2. **Handle missing agents:** if any dimension failed to return (timeout, dispatch error), mark it `UNKNOWN` and downgrade the consensus by one step (GREEN → YELLOW, YELLOW → YELLOW, RED stays RED). Never wait indefinitely. Surface which dimension is missing so the user can re-dispatch if they want.
+3. **Consensus rule:**
+   - Any RED → **RED** (block merge).
+   - Any YELLOW → **YELLOW** (soft block — must address before merge, per memory `llm-council-data-layer-fixes`).
+   - All GREEN → **GREEN** (mergeable).
+4. **Deduplicate must-fix AND confirmed-good items:** if two dimensions flag the same issue (or confirm the same positive), list it once and credit both.
+5. **Live-verify gate** (D5 fired + PR body has unchecked live-verify boxes): emit an explicit `AskUserQuestion` with three options — (a) *Run now (estimate: ~1 Flow image credit per locale)*, (b) *Block merge — add to PR body as required reviewer action*, (c) *Skip and accept the risk*. Cite memory `verification-ledger-5-layer` in the question body so the user is reminded that file count alone is not proof. Do NOT spend credits without an explicit affirmative click.
+6. **YELLOW escape valve:** when reporting in Phase 6, the `AskUserQuestion` MUST include a *"Dismiss YELLOW with justification (logged)"* option so the user is never trapped without a path forward. Dismissal requires a one-line reason that gets appended to the PR body or comment, so the override is auditable.
+
+---
+
+## 6 · Report
+
+Output to the user, in this exact shape:
+
+```
+# PR #<N> — Council Review Verdict
+
+## Consensus: <emoji> <GREEN | YELLOW | RED>
+
+| Dimension | Verdict | Headline |
+|---|---|---|
+| <D1> | … | <one-line summary> |
+| <D2> | … | … |
+…
+
+## Must-fix (<N>)
+1. **<short title>** — `<file>:<line>`. <description>. <which dimension flagged>.
+2. …
+
+## Nice-to-have (<N>)
+1. …
+
+## Confirmed-good (high-confidence positives)
+- …
+
+## How to proceed
+<AskUserQuestion: which must-fixes to apply now, whether to run live-verify, etc.>
+```
+
+Always end with an `AskUserQuestion` so the user can drive next steps (apply fixes, post evidence, dismiss findings).
+
+---
+
+## 7 · Provenance & extensions
+
+> **Provenance:** the council protocol below was validated on PR #93 (locale selectors + DB isolation, merged 2026-05-26). The audit found an unanchored regex + a silent-test-pyramid gap that 152 passing unit tests missed. Then a meta-council audited *this* command itself, surfacing 13 must-fix items now applied. See memory `[[llm-council-code-review-pr93]]`.
+
+- Council baseline = 4 dimensions (D1–D4) always run. Adaptive ceiling = D5–D12 (currently). Going beyond ~12 dimensions adds noise faster than signal — split into two reviews instead.
+- Each agent currently uses `general-purpose`. If a future dedicated `code-reviewer` subagent ships, swap it in.
+- If a PR touches paths that don't match any adaptive dimension, document the gap and add a new dimension here (D13+).
+- The command is **stateless** — concurrent invocations on different PR numbers don't share data, so two instances can run in parallel without interference.
+- **Idempotence:** running the same council on the same PR SHA should produce comparable verdicts on different days. If verdicts drift, the cause is usually (a) memory grew new precedents, or (b) the mandatory-slug table here needs an update. Drift is informational, not a defect.
+- No destructive git/gh actions are taken by this command. Reviews are read-only. The user always drives apply-fix / push / merge through subsequent commands.
+- **Sibling commands.** `/review` is the single-agent Claude-Code built-in (one-pass code review, fast and cheap) — use it for spot-checks, draft iteration, or when the council is overkill. `/gflow:pr-council-review` is the multi-agent council version — use it before merge, on high-risk surfaces (auth, transports, data, release-gate), or whenever a single-agent pass would miss the cross-dimension defects the council is designed to catch.

{gflow_cli-0.8.1 → gflow_cli-0.9.1}/.env.template

@@ -77,3 +77,12 @@
 # (Google's bot-detection sometimes refuses headless Chromium but accepts a
 # visible window). The session is still reused from the persistent profile.
 # GFLOW_CLI_HEADLESS=true
+
+# 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
+# Flow stays on /fx/tools/flow/ instead of /fx/<locale>/). Default:
+# `en-US`. Override to capture locale-invariant DOM via
+# scripts/dev/capture_locale_invariants.py or to live-verify a non-EN
+# language end-to-end (see KNOWN_ISSUES § issue #24).
+# GFLOW_CLI_LOCALE=en-US

{gflow_cli-0.8.1 → gflow_cli-0.9.1}/.github/workflows/ci.yml

@@ -54,14 +54,10 @@ jobs:
         run: uv run pyright src
 
       - name: Test (smoke only) + coverage
-        # e2e tests (tests/e2e/) require a logged-in Chromium profile
-        # and live Flow auth — never runnable in CI. They self-mark with
-        # `pytestmark = pytest.mark.e2e` (file-level) and are opt-in via
-        # `-m e2e` per their module docstring. `live` marker is reserved for
-        # `GFLOW_LIVE=1` tests that hit the real Flow API. Both are excluded
-        # from the default smoke run; `tests/smoke/test_real_flow.py` already
-        # self-skips via `pytest.mark.skipif(GFLOW_E2E != "1")`.
-        run: uv run python -m pytest -q -m "not e2e and not live" --cov=gflow_cli --cov-report=xml
+        # e2e/live tests require a logged-in Chromium profile and may spend
+        # Flow credits. pyproject.toml excludes both markers by default; CI
+        # intentionally relies on that default smoke set.
+        run: uv run python -m pytest -q --cov=gflow_cli --cov-report=xml
 
       # Upload coverage XML so the sonar job can consume it
       - name: Upload coverage report

{gflow_cli-0.8.1 → gflow_cli-0.9.1}/.gitignore

@@ -18,6 +18,7 @@ env/
 pytest-of-*/
 .coverage
 .coverage.*
+coverage.xml
 htmlcov/
 .tox/
 .mypy_cache/
@@ -78,3 +79,5 @@ samples/captured/flow_outgoing_*.json
 
 worktrees/
 
+# E2E test logs (live Flow runs — may contain account/profile names)
+.planning/e2e-logs/

{gflow_cli-0.8.1 → gflow_cli-0.9.1}/AGENTS.md

@@ -8,7 +8,7 @@ Supported tools that auto-discover this file: Cursor, Codex, Aider, Gemini CLI,
 
 - Unofficial Python CLI for [Google Flow](https://labs.google/fx/tools/flow) — drives Veo (image-to-video, text-to-video) and Imagen (text-to-image) generations from the terminal by reverse-engineering Flow's private REST API at `aisandbox-pa.googleapis.com`.
 - Python 3.11+ · `uv`-managed · `hatchling` builds · Playwright Chromium transport · `pyright` strict · `ruff` · `pytest`.
-- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_image.py`, `cli_run.py`, `cli_video.py`, `config.py`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
+- Single-package modular monolith. Top-level modules under `src/gflow_cli/`: `api/`, `auth/`, `browser_manager.py`, `cli.py`, `_cli_helpers.py`, `cli_data.py`, `cli_image.py`, `cli_run.py`, `cli_video.py`, `config.py`, `data/`, `errors.py`, `exceptions.py`, `image_batch.py`, `manifest.py`, `observability.py`, `paths.py`, `profile_store.py`.
 - Requires a Google AI Ultra or Pro subscription with Flow access. All generations bill against the user's own Google account.
 
 ## Headed-browser dependency (architectural reality)
@@ -53,7 +53,7 @@ Or invoke the wrapper: `/gflow:check`.
 
 - Type hints everywhere; `pyright` strict on `src/gflow_cli`.
 - Structured logging only (`structlog`) — **never** raw `print()` or `import logging` in `src/`.
-- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–15). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
+- Errors as RFC 9457 Problem Details with stable per-class exit codes (3–16, where 16 is the `DataStoreError` family from `gflow_cli.data`). See `src/gflow_cli/errors.py::EXIT_CODE_MAP` for the complete mapping.
 - 100-char line length, `ruff` configured. Imports sorted by `ruff` (isort rules).
 
 ## PR instructions

{gflow_cli-0.8.1 → gflow_cli-0.9.1}/CHANGELOG.md

@@ -7,6 +7,214 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.1] — 2026-05-27
+
+> **Locale and catalog patch release.** Hardens the headed-browser UI
+> automation path for localized Flow profiles, fixes I2V start/end-frame
+> attachment on non-English Chrome/Flow sessions, and repairs first-run catalog
+> edge cases found after v0.9.0.
+
+### Changed
+
+- `NEW_PROJECT_SELECTORS` now covers all 14 supported locales (EN / PT / ES /
+  FR / DE / IT / NL / JA / ZH / KO / PL / RU / TR / ID) and leads with
+  locale-stable icon selectors (`add_2` Material Symbols ligature on
+  `<button>` and on `[role='button']` ARIA-role variants, plus an anchored
+  `^\+\s+\S+$` regex for `+ <word>` host elements). English-only
+  `[aria-label*='New project']` and `[aria-label*='Project']` ARIA fallbacks
+  removed.
+  `SUBMIT_BUTTON_SELECTORS` drops its English-only
+  `button[aria-label*="Create"]` fallback — the preceding `arrow_forward` icon
+  entries already cover this button in every locale. Both selector tuples are
+  now fully locale-invariant for non-English Chrome profiles. The `--lang=en-US`
+  Chromium launch arg is retained only to stabilise `IMAGE_MODEL_OPTION_SELECTORS`
+  (English product names); its removal is tracked as issue #24 Phase 5 (#94).
+
+### Fixed
+
+- Bare `pytest` no longer collects live/e2e tests by default. The project-wide
+  pytest `addopts` now excludes `e2e` and `live` unless callers explicitly pass
+  a different `-m` expression, and `tests/smoke/test_real_flow.py` is marked
+  with both markers so marker-filtered local and CI runs cannot accidentally
+  launch a real Flow browser session.
+- Browser-manager PID tests no longer call the real `os.kill` while pretending
+  to be on POSIX from a Windows runner. The POSIX liveness branches are now
+  tested with mocked `os.kill`, avoiding hard interpreter/session exits during
+  local test runs.
+
+- Running the pytest suite no longer writes fixture rows into the developer's
+  production `gflow.db` catalog. A new autouse `_isolate_settings` fixture in
+  `tests/conftest.py` redirects `GFLOW_CLI_HOME` and `GFLOW_CLI_DB_PATH` to
+  per-test `tmp_path` dirs and clears the `get_settings()` `lru_cache` before
+  and after every test, preventing the cached singleton from ever resolving to
+  a `platformdirs` production path. Closes
+  [#86](https://github.com/ffroliva/gflow-cli/issues/86).
+
+- `gflow video i2v` no longer silently breaks on non-English Chrome profiles.
+  PR #70's structural-first `_attach_frame` cascade matched **zero** real
+  slots — its anchor selector assumed the `swap_horiz` icon used class
+  `google-symbols` (it uses `material-icons`) and the slots were `<button>`
+  (they're `<div type="button">`). Production I2V therefore relied on the
+  English-text fallback, which silently misses on any non-EN profile (pt-BR
+  shows `Inicial`/`Final`, DE shows `Anfang`/`Ende`, etc.). Replaced
+  `FRAME_SLOTS_STRUCT` with the locale-free pattern
+  `div[type='button'][aria-haspopup='dialog']` and added a `.first`-of-remaining
+  fallback for the End-frame case (after Start is attached, only one slot
+  matches and the prior `.nth(slot_index)` went out-of-bounds). Live-verified
+  with `tests/e2e/test_transports_e2e.py::test_e2e_i2v_start_end_frame_attach`
+  on `ffroliva` + `GFLOW_CLI_LOCALE=de-DE` (Chrome rendered pt-BR; both
+  non-EN). Closes [#63](https://github.com/ffroliva/gflow-cli/issues/63).
+
+### Changed
+
+- `gflow data media <id>` now searches across **all** profiles by default,
+  matching the cross-profile default of `gflow data list`. Pass
+  `--profile NAME` to disambiguate the rare case where the same Flow
+  media ID exists under multiple profiles (the command refuses to
+  guess and prints the list of candidate profiles, each annotated with
+  its `kind`). Closes
+  [#87](https://github.com/ffroliva/gflow-cli/issues/87).
+
+### Fixed
+
+- `gflow data list` no longer crashes with `no such table: assets` on a
+  missing or freshly-created catalog DB. The query path now routes through
+  `DataStore.open`, which applies schema migrations on first connect —
+  first-time users and anyone recovering from a wiped DB get an empty
+  table and exit 0 instead of a `DataStoreError`. Closes
+  [#88](https://github.com/ffroliva/gflow-cli/issues/88).
+- `gflow auth list` no longer crashes with `UnicodeEncodeError` on Windows
+  consoles whose code page cannot encode the default-profile marker `●`
+  (cp1252 in PowerShell / cmd by default). The renderer now picks a glyph
+  safe for the active `sys.stdout.encoding` — `●` on UTF-8, ASCII `*` on
+  cp1252 / ascii / latin-1 / unknown. Closes [#82](https://github.com/ffroliva/gflow-cli/issues/82).
+
+### Documentation
+
+- `PLAN.md` refreshed to reflect develop state through v0.9.0 — marks Phase 6
+  (data layer) shipped via PR #58 + #78 + #81, Phase 7 Issue #24 Phase 2
+  shipped via PR #70, Phase B I2V/R2V shipped via PR #48, and resolves the
+  duplicate Phase 7 numbering (pluggable storage renumbered to Phase 8).
+
+## [0.9.0] — 2026-05-25
+
+> **Maturity & Visibility release.** Surfaces the SQLite catalog (PR #52/#58)
+> via a read-only `gflow data list {projects,images,videos,profiles}` CLI,
+> publishes `ROADMAP.md`, and ships the locale-agnostic media-dialog
+> selectors that unblock non-English Chrome profiles. Plus the previously-
+> unreleased video model picker, i2v/r2v, and the I2I ref-attach + model-
+> select fixes. Sponsorship wiring will land in a follow-up patch release
+> once GitHub Sponsors / Buy Me a Coffee accounts are fully provisioned.
+
+### Added
+
+- `gflow data list {projects,images,videos,profiles}` — read-only catalog
+  query CLI over the local SQLite data layer. Flags: `--limit` (1..1000,
+  default 20), `--offset` (≥0, default 0), `--profile NAME`, `--json`.
+  Rich table on TTY, JSONL on pipe or `--json`. Default sort: newest first.
+  `DataStoreError` family maps to exit code 16. See
+  [`docs/DATA_LAYER.md § Querying the data layer`](docs/DATA_LAYER.md#querying-the-data-layer).
+- `ROADMAP.md` at repo root — themed milestones from v0.9 through v1.0 (no
+  dates).
+- `gflow video t2v` model picker: `--model` (`omni-flash` | `veo-lite` |
+  `veo-fast` | `veo-quality` | `veo-lite-lp`), `--duration` (`4`/`6`/`8`, plus
+  `10` for `omni-flash` only), and `--count` (1–4). Driven via the editor's
+  generation-settings panel; live-verified against a Pro/Ultra profile.
+- `gflow video i2v <image> "<prompt>"` — image-to-video with a start frame and
+  an optional `--end-image` (interpolation). Fires
+  `batchAsyncGenerateVideoStartImage` / `…StartAndEndImage`.
+- `gflow video r2v "<prompt>" --ref <img> [--ref …]` — reference-to-video
+  (Flow "ingredients"). Model-aware reference cap (omni_flash ≤7, veo_3_1_* ≤3)
+  enforced in the request DTO; the transport stops gracefully if Flow hides the
+  add-media button at the cap. Fires `batchAsyncGenerateVideoReferenceImages`.
+- `GFLOW_CLI_LOCALE` env var — overrides Playwright's launch `locale=` parameter
+  (default: `en-US`). Controls `Accept-Language` only; Chrome's UI language is
+  still forced to en-US via `--lang=en-US`. Prep for issue #24 (locale-agnostic
+  selectors); live-verified end-to-end with `GFLOW_CLI_LOCALE=pt-BR` against a
+  Pro/Ultra account. See `docs/CONFIGURATION.md § GFLOW_CLI_LOCALE`.
+- **Local data layer** — `gflow-cli` now keeps a SQLite catalog of every new
+  image, batch, and video operation under `$GFLOW_CLI_DB_PATH` (default:
+  `~/.local/share/gflow-cli/data.db`). Records profile, project, asset
+  (model / aspect / dimensions / Flow media ID), operation provenance
+  (mode / prompt / model / timing / error), input↔output links, and
+  downloaded local files. New `gflow data media <id>` command resolves a
+  Flow media ID to its origin. `DataRepository` exposes seed-image resolvers
+  (`resolve_seed_image_by_path` / `resolve_seed_image` /
+  `resolve_latest_image`) — foundation for the upcoming I2V seed-reuse
+  path. Pre-Flow store failures exit `16` (`DataStoreError` /
+  `DataMigrationError` / `DataIntegrityError`); post-success store
+  failures warn and exit `0` (Flow already charged the credits). See
+  [`docs/DATA_LAYER.md`](docs/DATA_LAYER.md). (PR #58, stacked on #52.)
+
+### Changed
+
+- `MAX_REFERENCE_IMAGES` (in `api/video.py`) now tracks the `omni_flash`
+  ceiling of **7** (was **3**). The tighter per-model cap (`veo_3_1_* ≤ 3`) is
+  still enforced in `GenerateVideoRequest.__post_init__` when the model is
+  known; the constant is only the absolute upper bound. Anyone pinning to the
+  old value of 3 should re-check against the per-model caps.
+
+### Fixed
+
+- `FlowApiClient.__aenter__` now tears down a partially-launched browser if any
+  step after the Playwright driver starts raises (e.g. the persistent-context
+  launch, the bootstrap navigation, or `transport.setup`). Python does not call
+  `__aexit__` when `__aenter__` raises, so an unguarded failure orphaned the
+  chrome process, which then held the profile's user-data-dir lock — the next
+  run could not acquire it and spiralled into rapid `about:blank` tabs +
+  `TargetClosedError`. Context close + driver stop are now shared by
+  `__aenter__`'s guard and `__aexit__` via `_close_browser_resources`.
+- `gflow image i2i --ref <local-file>` now binds the reference through the
+  editor's media dialog instead of the REST `uploadImage` endpoint (which 401s —
+  same root as #15/#39). Local-path refs ride a new `GenerateImageRequest.ref_paths`
+  field and are attached via the inherited R2V `_attach_references` (the image-mode
+  add-media dialog is the same `add_2` surface). Bare-UUID `--ref` still flows
+  through `refs` unchanged. Re-introduces #50 (reverted in #57 for the account/
+  locale variant tracked in #56); the media-dialog selectors are now
+  locale-agnostic (see the next entry).
+- The media-dialog upload selectors are now **locale-agnostic** (issue #56/#24).
+  `UPLOAD_MEDIA_BUTTON` matched localized text (`has-text('Upload media')`), so on
+  a non-English Chrome profile (Flow follows the *Chrome profile* language, which
+  the `--lang=en-US` arg cannot override) the click missed and the file chooser
+  never opened — a silent ~34s hang. It now anchors on the locale-free `upload`
+  icon ligature (`:text-is('upload')`, exact, so it doesn't grab the `Uploads`
+  tab), with the original English-text selector kept as a graceful **fallback
+  tier** (matches if Google ever changes the icon but keeps the English label);
+  'Add to Prompt' (which has no icon) is selected structurally as the only
+  iconless button in the open dialog. If neither tier opens a chooser,
+  `_upload_via_open_dialog` raises a clear error + writes a screenshot (no silent
+  hang) and points the operator at the Chrome-profile-language workaround. Fixes
+  I2I/I2V/R2V upload alike.
+- `gflow image t2i/i2i --model` now actually selects the requested model. It was
+  a no-op under `ui_automation` (the wire field was set but the model picker was
+  never clicked, so Flow used its UI default). Adds `_select_image_model`.
+- Video selector mismatches: the output-count selector `[id*=-trigger-1]`
+  collided with the `-trigger-10` duration tab; the aspect selector matched a
+  non-existent `aria-controls*=9_16`; the video-mode tab match was ambiguous.
+  All now use exact `[id$=-trigger-X]` suffixes + aria-label text.
+
+### Build
+
+- **Wheel build no longer emits duplicate ZIP entries.** An earlier attempt at
+  tagging v0.9.0 was rejected by PyPI with HTTP 400 ("Duplicate filename in
+  local headers") because `pyproject.toml` had
+  `[tool.hatch.build.targets.wheel.force-include]` and
+  `[tool.hatch.build.targets.sdist.force-include]` blocks pointing at
+  `src/gflow_cli/data/migrations`, on top of the already-comprehensive
+  `packages = ["src/gflow_cli"]` directive — hatchling included the
+  migrations directory twice (both `__init__.py` and `0001_initial.sql`). The
+  force-include blocks have been removed; hatchling's default package
+  inclusion already covers `.sql` files inside the package tree. (PR #74.)
+
+### Notes
+
+- I2V/R2V image inputs bind through the editor's media dialog (frame slot /
+  add-media → "Upload media" → file chooser → "Add to Prompt"). `set_input_files`
+  on the generic hidden input only adds to the library and Flow then ignores the
+  image (plain Text route). The editor is forced to English via the
+  `--lang=en-US` Chromium launch arg because the slot/dialog labels are localized
+  with no locale-free anchor.
+
 ## [0.8.1] — 2026-05-23
 
 ### Documentation
@@ -826,7 +1034,10 @@ 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.8.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.9.1...HEAD
+[0.9.1]: https://github.com/ffroliva/gflow-cli/compare/v0.9.0...v0.9.1
+[0.9.0]: https://github.com/ffroliva/gflow-cli/compare/v0.8.1...v0.9.0
+[0.8.1]: https://github.com/ffroliva/gflow-cli/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/ffroliva/gflow-cli/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/ffroliva/gflow-cli/compare/v0.6.0a6...v0.7.0
 [0.6.0a6]: https://github.com/ffroliva/gflow-cli/compare/v0.6.0a5...v0.6.0a6