gflow-cli 0.14.0__tar.gz → 0.15.0__tar.gz

{gflow_cli-0.14.0 → gflow_cli-0.15.0}/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] — 2026-06-09
+
+### Added
+
+- **`gflow image` can reference locked CHARACTER entities** for character-consistent
+  stills. New `--reference-entity <id>` (repeatable) + `--reference-entity-name` on
+  `image t2i` / `i2i`, plus `--project <id>` to generate in an EXISTING project (where
+  the entities live) instead of a throwaway scratch project. Entities attach through
+  the editor's **Personagens picker** and ride the submit as `referenceEntities`
+  (confirmed against the live API); `_build_batch_generate_images_body` serializes them
+  so non-UI/headless transports get parity too. Entities count toward the per-model
+  reference cap. `--project` / `--reference-entity` are single-prompt only; for a pure
+  character reference use `t2i` (`i2i` still needs a `--ref`). See `docs/USAGE.md` →
+  "Character-consistent images (entity references)".
+
+### Fixed
+
+- `--project` no longer overwrites an existing project's stored title/source in the
+  local history DB (the recorder preserves the curated title for non-created projects).
+
+### Security
+
+- `--project` / `--reference-entity` ids are validated at the CLI boundary
+  (`[A-Za-z0-9-]{1,128}`), closing an unvalidated `page.goto` navigation path
+  (`project_editor_url` lacked the allowlist its sibling routes enforce) and a
+  CSS-selector injection vector (`data-tile-id='fe_id_<id>'`). The request-body debug
+  logger elides large reference-field values so Flow-built image bytes can't leak into
+  logs.
+
+### Internal
+
+- Bump dev/CI `ruff` to `0.15.16` (both the `dev` extra and the `dependency-groups`
+  pin; supersedes Dependabot PR #165, which updated only the soft `>=` extra and not
+  the hard `==` group pin CI actually uses). `ruff check` / `format --check` clean.
+
 ## [0.14.0] — 2026-06-07
 
 ### Added
@@ -1434,7 +1469,8 @@ 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.14.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/ffroliva/gflow-cli/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/ffroliva/gflow-cli/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/ffroliva/gflow-cli/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/ffroliva/gflow-cli/compare/v0.11.0...v0.12.0

{gflow_cli-0.14.0 → gflow_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.14.0
+Version: 0.15.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
@@ -53,7 +53,7 @@ Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: pyright>=1.1.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.15.15; extra == 'dev'
+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'

{gflow_cli-0.14.0 → gflow_cli-0.15.0}/docs/PROJECT_STATUS.md

@@ -4,9 +4,9 @@
 
 ## Current release
 
-**v0.13.0 — alpha.** High-fidelity CLI hardening and term alignment. **`gflow video i2v`** now uses the canonical `--initial-frame` and `--end-frame` flags (matching Flow's UI labels), with robust Click greedy-fill protection and positional backward compatibility. **In-project governance** (ruff T20, materiality classification) is now active to harden the AI-driven development flow. This release also refactors the **`character_create` saga** for improved type safety and documentation. Live-verified end-to-end on 2026-06-04 with the new flags and interpolation paths.
+**v0.15.0 — alpha.** **Character-consistent images via entity references.** `gflow image t2i/i2i` can now reference locked Flow CHARACTER entities (`--reference-entity <id>`, repeatable) and generate in an existing project (`--project <id>`) where those entities live — entities attach through the editor's Personagens picker and ride the submit as `referenceEntities` (confirmed against the live API; the body builder serializes them for headless transports too). Live-verified 2026-06-08: a 3-frame Dragon-Hook smoke rendered drift-free with all three characters on-model. LLM-council-reviewed (security/correctness/dedup) before merge. Carries forward the v0.14.0 `gflow movie` line (multi-scene, character-consistent video).
 
-**Develop (unreleased, post-v0.13.0):** *(empty — develop is the staging branch for the next release).*
+**Develop (unreleased, post-v0.15.0):** *(empty — develop is the staging branch for the next release).*
 
 ## Milestone history
 
@@ -52,6 +52,8 @@
 | `gflow character rm` — free character deletion (#150) | ✅ done (v0.13.0) |
 | Align I2V CLI flags with Flow UI Labels (`--initial-frame`) (#122) | ✅ done (v0.13.0) |
 | In-project governance (ruff T20, materiality Classifier) | ✅ done (v0.13.0) |
+| `gflow movie` — multi-scene, character-consistent video from a TOML manifest (entity reuse, resumable, handoff manifest) | ✅ done (v0.14.0) |
+| `gflow image t2i/i2i` — reference locked CHARACTER entities (`--reference-entity`) + `--project` for character-consistent stills | ✅ done (v0.15.0) |
 | `gflow character` — reusable Flow Character entities (`create`/`list`/`show`/`voices`), persist-before-spend saga (#145) | ✅ done (v0.12.0) |
 | `gflow scene` — Add Clip / Scenes compose + credit-free server-side extended video (`runVideoFxConcatenation`) | ✅ done (v0.12.0) |
 | `gflow video chain` — last-frame I2V chaining from a JSONL manifest (`--dry-run`/`--max-links`/`--resume-from`) | ✅ done (v0.12.0) |

{gflow_cli-0.14.0 → gflow_cli-0.15.0}/docs/USAGE.md

@@ -131,6 +131,13 @@ Options:
                             Aspect ratio.                     [default: 9:16]
   -n, --count INTEGER       How many images to generate (1-4).  [default: 1]
   --out PATH                Output directory (see "Output paths" below).
+  --project ID              Generate in this EXISTING Flow project instead of a
+                            scratch project. Required to reference locked
+                            entities/assets in that project. Single-prompt only.
+  --reference-entity ID     Flow CHARACTER entity id to reference for character
+                            consistency (repeatable; must live in --project).
+                            Single-prompt only.
+  --reference-entity-name N Display name paired with --reference-entity.
   --profile NAME            Profile name (overrides default).
 ```
 
@@ -212,6 +219,10 @@ Options:
                             Aspect ratio.                     [default: 9:16]
   -n, --count INTEGER       How many images to generate (1-4).  [default: 1]
   --out PATH                Output directory (same semantics as t2i).
+  --project ID              Generate in this EXISTING Flow project (skip scratch).
+  --reference-entity ID     Flow CHARACTER entity id to reference (repeatable;
+                            must live in --project). Counts toward the ref cap.
+  --reference-entity-name N Display name paired with --reference-entity.
   --profile NAME            Profile name (overrides default).
 ```
 
@@ -248,6 +259,40 @@ A 2-image run produces files numbered `_1.png`, `_2.png`:
 ./variants/<media_name_b>_2.png
 ```
 
+## Character-consistent images (entity references)
+
+`--reference-entity` makes `image t2i`/`i2i` reference a locked Flow **CHARACTER
+entity** (minted via `gflow character create`) so the generated subject stays
+on-model across shots — no per-shot prompt wrangling or fragile image refs.
+
+How it works: entities are **project-scoped**, so you must generate **in the
+project that owns them** via `--project <id>` (this also means no throwaway
+scratch project is created). The CLI attaches each entity through the Flow editor's
+resource picker; the submit then carries `referenceEntities`, exactly like the
+video R2V path. Entities count toward the same per-model reference cap as `--ref`
+images. `--reference-entity` / `--project` are **single-prompt only**.
+
+For a *pure* character reference (no starting image) use `t2i` — `i2i` still
+requires at least one `--ref`.
+
+```bash
+# One locked character, consistent across runs (t2i = no image ref needed)
+gflow image t2i "Aria explores a neon market, full body" \
+  --project 7fa97443-… --reference-entity 8a77f8cb-… --reference-entity-name Aria \
+  --model nano2 --aspect 9:16 -n 3
+
+# Several characters in one scene (each --reference-entity repeatable)
+gflow image t2i "Aria and Drako meet at the gate" --project 7fa97443-… \
+  --reference-entity 8a77f8cb-… --reference-entity 4ed5cb7f-…
+
+# i2i: a starting image PLUS an entity for the character
+gflow image i2i "place this hero in a snowy pass" --ref hero.png \
+  --project 7fa97443-… --reference-entity 8a77f8cb-…
+```
+
+> Ids are validated at the CLI boundary (letters/digits/hyphens, ≤128 chars).
+> The entity must already exist in `--project` (see `gflow character create`).
+
 ## `gflow image batch`
 
 Generate multiple images from a single manifest file. The format is dispatched by file extension (`.json` or `.tsv`).

{gflow_cli-0.14.0 → gflow_cli-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gflow-cli"
-version = "0.14.0"
+version = "0.15.0"
 description = "Unofficial CLI for Google Flow — drive Veo image-to-video generations from the terminal."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -33,7 +33,7 @@ dependencies = [
 dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.23.0",
-    "ruff>=0.15.15",
+    "ruff>=0.15.16",
     "pyright>=1.1.0",
     # video-chain: the last-frame extractor (media.py) decodes with PyAV, and its
     # tests build synthetic mp4 fixtures with numpy. Declared here so the dev/CI
@@ -134,7 +134,7 @@ dev = [
     "pytest-asyncio>=1.3.0",
     "pytest-bdd>=8.1.0",
     "pytest-cov>=7.1.0",
-    "ruff==0.15.15",
+    "ruff==0.15.16",
 ]
 # Container-based integration tests — requires Docker daemon.
 # Install: uv sync --group containers

{gflow_cli-0.14.0 → gflow_cli-0.15.0}/src/gflow_cli/__init__.py

@@ -1,3 +1,3 @@
 """gflow-cli — unofficial CLI for Google Flow."""
 
-__version__ = "0.14.0"
+__version__ = "0.15.0"

{gflow_cli-0.14.0 → gflow_cli-0.15.0}/src/gflow_cli/api/image.py

@@ -229,6 +229,14 @@ class GenerateImageRequest:
     # dialog by the ui_automation transport (the REST uploadImage path 401s).
     # The common i2i case; `refs` (pre-uploaded UUIDs) would need library-select.
     ref_paths: tuple[Path, ...] = ()
+    # Flow CHARACTER entity ids to reference (project-scoped, attached via the
+    # Add-Media → Personagens picker by the ui_automation transport). Entities
+    # keep generated subjects consistent with a locked character. They count
+    # toward the same per-model reference cap as image refs.
+    reference_entities: tuple[str, ...] = ()
+    # Optional display names paired with reference_entities (used by the UI
+    # picker when an id-keyed tile can't be located by id alone).
+    reference_entity_names: tuple[str, ...] = ()
     recaptcha_token: str = ""  # populated by caller right before send; "" means unminted
     # number of images to generate (1–4); UI transport uses this to set Flow's count tab
     count: int = 1
@@ -240,10 +248,10 @@ class GenerateImageRequest:
         if not 1 <= self.count <= 4:
             msg = f"GenerateImageRequest.count must be 1–4, got {self.count}"
             raise ValueError(msg)
-        n_refs = len(self.refs) + len(self.ref_paths)
+        n_refs = len(self.refs) + len(self.ref_paths) + len(self.reference_entities)
         cap = reference_cap_for(self.model)
         if n_refs > cap:
-            msg = f"{self.model.value} allows at most {cap} reference image(s); got {n_refs}"
+            msg = f"{self.model.value} allows at most {cap} reference(s); got {n_refs}"
             raise ValueError(
                 msg,
             )
@@ -299,6 +307,14 @@ def _build_batch_generate_images_body(
         # Always present — empty list for T2I, populated for I2I.
         "imageInputs": [r.to_wire() for r in req.refs],
     }
+    # Character entity references. Shape confirmed by live capture (2026-06-08):
+    # the image submit carries `referenceEntities: [{"entityId": <id>}]`. Added
+    # only when present so plain t2i/i2i bodies stay byte-identical to the
+    # captured samples. The ui_automation transport attaches entities via the
+    # Personagens picker and lets Flow's JS build this; non-UI transports rely
+    # on this serialization.
+    if req.reference_entities:
+        request["referenceEntities"] = [{"entityId": e} for e in req.reference_entities]
     return {
         "clientContext": cc,
         "mediaGenerationContext": {"batchId": batch_id},

{gflow_cli-0.14.0 → gflow_cli-0.15.0}/src/gflow_cli/api/transports/ui_automation.py

@@ -31,6 +31,7 @@ from gflow_cli.api.transports._common import extract_project_id
 from gflow_cli.api.transports.ui_automation_video import (
     MODE_SWITCH_TRIGGER_SELECTORS,
     VideoGenerationMixin,
+    zip_entity_refs,
 )
 from gflow_cli.errors import (
     AuthExpiredError,
@@ -518,6 +519,70 @@ def _images_from_responses(
     return images, first_error_status, first_error_route
 
 
+_REF_VALUE_MAX_CHARS = 512
+
+
+def _elide_large_value(value: Any) -> Any:
+    """Return *value* verbatim when small, else a length-only redaction marker.
+
+    Guards the request-body logger against dumping large/secret payloads: if Flow
+    names an i2i image field `reference*`/`*entity*`, its base64 bytes would match
+    the reference-field filter and be logged in full. Small fields like
+    `referenceEntities` (a short list of `{entityId}`) pass through; anything
+    serializing beyond the cap is elided to a `<elided N chars>` marker.
+    """
+    try:
+        serialized = json.dumps(value, default=str)
+    except (TypeError, ValueError):
+        return f"<unserializable {type(value).__name__}>"
+    if len(serialized) > _REF_VALUE_MAX_CHARS:
+        return f"<elided {len(serialized)} chars>"
+    return value
+
+
+def _summarize_batch_request_body(post_data: str | None) -> dict[str, Any]:
+    """Compact, byte-safe summary of an outgoing ``batchGenerateImages`` body.
+
+    This is the make-or-break signal for the entity-reference spike: it reveals
+    whether Flow's image submit carries a ``referenceEntities`` field after we
+    attach a character via the picker — WITHOUT logging the full body (i2i
+    bodies embed base64 image bytes that would flood the log and leak content).
+
+    Returns a dict with ``present``, ``mentions_reference_entities`` (cheap
+    substring probe that survives non-JSON bodies), and — when the body parses —
+    the keys of ``requests[0]`` plus any reference/entity-related fields verbatim
+    (those are small id lists, safe to surface).
+    """
+    if not post_data:
+        return {"present": False}
+    summary: dict[str, Any] = {
+        "present": True,
+        "bytes": len(post_data),
+        "mentions_reference_entities": "referenceEntit" in post_data,
+    }
+    try:
+        parsed: object = json.loads(post_data)
+    except (ValueError, TypeError):
+        return summary
+    if not isinstance(parsed, dict):
+        return summary
+    parsed_dict = cast("dict[str, Any]", parsed)
+    reqs = parsed_dict.get("requests")
+    if isinstance(reqs, list) and reqs and isinstance(reqs[0], dict):
+        first = cast("dict[str, Any]", reqs[0])
+        summary["request0_keys"] = sorted(first.keys())
+        ref_bits = {
+            k: _elide_large_value(v)
+            for k, v in first.items()
+            if "reference" in k.lower() or "entity" in k.lower()
+        }
+        if ref_bits:
+            summary["reference_fields"] = ref_bits
+    else:
+        summary["top_keys"] = sorted(parsed_dict.keys())
+    return summary
+
+
 class UiAutomationTransport(VideoGenerationMixin):
     """D.2.4 — Playwright UI mimicry strategy.
 
@@ -1593,6 +1658,51 @@ class UiAutomationTransport(VideoGenerationMixin):
 
         return captured, detach
 
+    @staticmethod
+    def _attach_batch_request_logger(
+        page: Page,
+        *,
+        project_id: str | None = None,
+    ) -> Callable[[], None]:
+        """Register a ``page.on('request', ...)`` that logs a compact summary of
+        each outgoing ``batchGenerateImages`` body.
+
+        The summary (see :func:`_summarize_batch_request_body`) surfaces whether
+        the submit carries ``referenceEntities`` — the entity-reference spike's
+        make-or-break signal — without dumping i2i image bytes. Returns an
+        idempotent detach fn, torn down alongside the response listener.
+        """
+
+        def on_request(request_obj: Any) -> None:
+            if "batchGenerateImages" not in request_obj.url:
+                return
+            try:
+                post_data = request_obj.post_data
+            except Exception:
+                post_data = None
+            log.info(
+                "ui_automation.batch_request_body",
+                url=request_obj.url,
+                filter_project_id=project_id,
+                summary=_summarize_batch_request_body(post_data),
+            )
+
+        page.on("request", on_request)
+
+        _detached = False
+
+        def detach() -> None:
+            nonlocal _detached
+            if _detached:
+                return
+            _detached = True
+            try:
+                page.remove_listener("request", on_request)
+            except Exception:
+                pass
+
+        return detach
+
     @staticmethod
     async def _await_captured(
         captured: list[dict[str, Any]],
@@ -1814,6 +1924,18 @@ class UiAutomationTransport(VideoGenerationMixin):
         if request.ref_paths:
             await self._attach_references(page, list(request.ref_paths), out_dir=out_dir)
 
+        # Entity references: attach locked CHARACTER entities via the Personagens
+        # picker (inherited from the video transport). The entity must live in the
+        # project we generate in (pass --project / project_id). Flow's JS then
+        # includes them on the submit; the request logger below records whether the
+        # outgoing batchGenerateImages carries `referenceEntities` (spike signal).
+        if request.reference_entities:
+            await self._attach_character_entities(
+                page,
+                zip_entity_refs(request.reference_entities, request.reference_entity_names),
+                out_dir=out_dir,
+            )
+
         # Attach the response listener SYNCHRONOUSLY before any prompt
         # action. asyncio.create_task is unsafe here: it defers the listener
         # registration until the new task gets event-loop scheduling, which
@@ -1821,6 +1943,9 @@ class UiAutomationTransport(VideoGenerationMixin):
         # attach/await eliminates that race. Project-ID filter prevents stale
         # responses from previously-visited projects accumulating in the list.
         captured, detach = self._attach_batch_response_listener(page, project_id=nav_project_id)
+        # Also log the OUTGOING request body summary so the entity-reference spike
+        # can read whether the submit carries `referenceEntities`.
+        req_log_detach = self._attach_batch_request_logger(page, project_id=nav_project_id)
         # Record submit_time BEFORE the click so the post-submit-time filter
         # in _await_captured can distinguish this prompt's responses from any
         # stale entries that arrived between listener attach and the click.
@@ -1835,6 +1960,7 @@ class UiAutomationTransport(VideoGenerationMixin):
             )
         finally:
             detach()
+            req_log_detach()
 
         # Collect images from ALL captured responses (Flow makes one API call
         # per image when count > 1).

{gflow_cli-0.14.0 → gflow_cli-0.15.0}/src/gflow_cli/api/transports/ui_automation_video.py

@@ -318,6 +318,22 @@ VIDEO_SUBMODE_SELECTORS: dict[str, tuple[str, ...]] = {
     ),
 }
 
+
+def zip_entity_refs(
+    entity_ids: tuple[str, ...],
+    entity_names: tuple[str, ...],
+) -> list[tuple[str, str]]:
+    """Pair character entity ids with display names for the Personagens picker.
+
+    Tiles are addressed by id (``data-tile-id="fe_id_<id>"``); the name is only a
+    human label for logs/error screenshots. When fewer names than ids are given,
+    the id stands in as its own name so the pairing never drops an entity. Shared
+    by the image (`ui_automation`) and video (R2V) entity-attach paths.
+    """
+    names = list(entity_names)
+    return [(eid, names[i] if i < len(names) else eid) for i, eid in enumerate(entity_ids)]
+
+
 # The editor SPA's ready anchor — the Slate prompt textbox. The /project/ URL
 # nav fires before the UI mounts; this is the readiness gate (used by
 # _wait_video_editor_ready and asserted in its test).
@@ -1585,14 +1601,9 @@ class VideoGenerationMixin:
                 )
         elif request.mode is Mode.R2V:
             if request.reference_entities:
-                names = request.reference_entity_names or request.reference_entities
-                entities = [
-                    (entity_id, names[i] if i < len(names) else entity_id)
-                    for i, entity_id in enumerate(request.reference_entities)
-                ]
                 await VideoGenerationMixin._attach_character_entities(
                     page,
-                    entities,
+                    zip_entity_refs(request.reference_entities, request.reference_entity_names),
                     out_dir=out_dir,
                 )
             if request.reference_images: