gflow-cli 0.21.0__tar.gz → 0.23.0__tar.gz

gflow_cli-0.23.0/.claude/commands/gflow/issue-assessment.md

@@ -0,0 +1,28 @@
+---
+description: >
+  Triage a gflow-cli GitHub issue: verify the reporter's claim against code,
+  tests, docs, KNOWN_ISSUES, and memory; classify it (CONFIRMED / NEEDS-E2E /
+  NEEDS-INFO / DUPLICATE / INVALID / WONTFIX); judge whether it is verifiable
+  end-to-end in the current environment; and draft a reporter-facing reply.
+  Read-only — changes nothing and posts nothing on its own.
+---
+
+# `/gflow:issue-assessment [issue number or URL]`
+
+**Read `skills/issue-assessment/SKILL.md` and follow its protocol now**, passing `$ARGUMENTS` as the issue to assess.
+
+> Do **not** call `Skill(skill="issue-assessment")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not Skill-tool-invocable (only `.claude/commands/gflow/*` are). Read the file directly instead.
+
+The skill at `skills/issue-assessment/SKILL.md` ingests the issue, verifies the
+claim (dispatching a search agent to keep context clean), assigns one verdict,
+applies the **e2e-gate** (never claim a fix is verified on an unverifiable
+surface), and emits a standard report artifact. On a `CONFIRMED` / `LIKELY-BUG`
+verdict with localized, verifiable scope it hands off to `issue-resolve`;
+otherwise it replies only.
+
+**Typical chain:**
+```
+/gflow:issue-assessment <N>   →  verdict + e2e-gate + reply artifact
+   ↓ (if scope clear & verifiable)
+issue-resolve <N>             →  worktree + TDD + draft PR for human review
+```

gflow_cli-0.23.0/.claude/commands/gflow/issue-resolve.md

@@ -0,0 +1,18 @@
+---
+description: >
+  Drive an assessed gflow-cli issue (verdict CONFIRMED-BUG or LIKELY-BUG, with
+  localized verifiable scope) to a fix: isolated worktree off develop, test-first
+  fix, /gflow:check, then a DRAFT PR for human review. Mutating and gated — runs
+  inside a strict action envelope (never merges, never spends credits, never
+  marks a PR ready, never claims an unverified fix verified).
+---
+
+# `/gflow:issue-resolve [issue number]`
+
+**Read `skills/issue-resolve/SKILL.md` and follow its protocol now**, passing `$ARGUMENTS` as the issue to resolve.
+
+> Do **not** call `Skill(skill="issue-resolve")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not Skill-tool-invocable (only `.claude/commands/gflow/*` are). Read the file directly instead.
+
+Preconditions (from `/gflow:issue-assessment`): verdict ∈ {`CONFIRMED-BUG`, `LIKELY-BUG`}, scope single-surface, and the fix is verifiable in this environment (or the gap is carried into the PR as "needs human e2e"). The skill isolates a `bugfix/` worktree off `develop`, gates high-stakes changes through `/gflow:predict` + `/gflow:scenario`, fixes test-first (Opus plans → Sonnet codes → Opus reviews for non-trivial work), runs `/gflow:check`, opens a **draft** PR with a Verification-status section, runs `/gflow:pr-council-review`, and **stops** for a human to promote and merge.
+
+**Chain:** `/gflow:issue-assessment <N>` → (if scope clear) `/gflow:issue-resolve <N>` → human promotes draft → human runs any headed/e2e check → merge.

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/.claude/commands/gflow/pr-council-review.md

@@ -8,4 +8,10 @@ description: Multi-dimensional LLM council review of an open PR. Five baseline d
 
 > Do **not** call `Skill(skill="pr-council-review")` — the repo's `skills/*/SKILL.md` files are plain Markdown, not registered as Skill-tool-invocable (only `.claude/commands/gflow/*` are). Invoking it errors with `Unknown skill: pr-council-review`. Read the file directly instead.
 
+**Required gate — SonarCloud must be green.** The council reviews the *diff*; it does
+not see SonarCloud's verdict. Before declaring the final verdict, run **`/gflow:sonar`**
+for this PR — the `SonarCloud analysis` gate must be green (zero new issues). A red gate
+is a blocking finding regardless of the council's own conclusions; report it with the
+exact failing conditions and do not call the PR merge-ready until it is green.
+
 Sibling: `/review` is the single-agent Claude-Code built-in (fast, one-pass). Use it for spot-checks; use this command for pre-merge multi-dim audits.

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/.claude/commands/gflow/release.md

@@ -198,8 +198,10 @@ gh pr create --base main --head chore/release-v<NEW_VERSION> \
   --title "chore(release): v<NEW_VERSION>"
 ```
 
-Wait for PR CI to go green (`gh pr checks <N> --watch`), then merge with a **merge
-commit** — never squash:
+Wait for PR CI to go green (`gh pr checks <N> --watch`). **The `SonarCloud analysis`
+check must be green (gate passed) — not just the test matrix.** If it is red or you
+want the verdict, run `/gflow:sonar <N>` and drive it to zero before merging. Then
+merge with a **merge commit** — never squash:
 
 ```bash
 gh pr merge <N> --merge --delete-branch

gflow_cli-0.23.0/.claude/commands/gflow/sonar.md

@@ -0,0 +1,82 @@
+---
+description: Check the SonarCloud quality gate for a PR (or the current branch) and drive it to zero. Reports GREEN, or the exact PR-scoped new issues/hotspots/coverage gaps to fix.
+---
+
+# `/gflow:sonar [PR#]` — SonarCloud quality gate
+
+The reusable Sonar primitive. `/gflow:check` is **local** and cannot see Sonar (it
+is server-side, post-push); `/gflow:pr-council-review` is an LLM diff review, not the
+gate verdict. This command answers one question: **is the SonarCloud gate green
+(zero new issues) for this PR, and if not, exactly what must be fixed?**
+
+`$ARGUMENTS` is the PR number. If empty, resolve it from the current branch
+(`gh pr view --json number -q .number`).
+
+Project: key `ffroliva_gflow-cli`, org `ffroliva-github` (see `sonar-project.properties`).
+The CI scan sets `sonar.qualitygate.wait=true`, so a **green `SonarCloud analysis`
+check means the gate genuinely passed** — but the gate **API is stale until that
+check finishes**, so always check the GitHub check FIRST.
+
+## Steps
+
+**1. Check the GitHub check first (never trust the gate API while it's pending).**
+
+```bash
+gh pr checks <N> --json name,state,bucket | \
+  jq -r '.[] | select(.name=="SonarCloud analysis") | "\(.bucket) \(.state)"'
+```
+
+- `pass` → **gate is GREEN / zero new issues. Done.** Report GREEN and stop.
+- `pending` → the SonarCloud job (~50s) runs *after* the ~3.5min test matrix; wait
+  (`gh pr checks <N> --watch`) before reading the API, or the API returns the
+  previous commit's verdict.
+- `fail` → continue to step 2 to enumerate the exact failing conditions.
+
+**2. Enumerate the failing conditions (PR-scoped — this is the #1 gotcha).**
+
+New-code issues live on the PR branch, NOT `main`. **Scope every call with
+`&pullRequest=<N>`** or the API reports 0 and you chase phantoms. Token is in
+`.env.local` as `SONAR_TOKEN` — read it inside a sandbox so it never lands in chat.
+`curl` may be blocked by the context-mode hook → use `ctx_execute` (javascript
+`fetch` with `Authorization: Basic base64(token+":")`).
+
+```bash
+# Which gate conditions are ERROR:
+GET /api/qualitygates/project_status?projectKey=ffroliva_gflow-cli&pullRequest=<N>
+# New issues (bugs/smells) with file:line + rule + creationDate:
+GET /api/issues/search?componentKeys=ffroliva_gflow-cli&pullRequest=<N>&resolved=false
+# Unreviewed security hotspots:
+GET /api/hotspots/search?projectKey=ffroliva_gflow-cli&pullRequest=<N>&status=TO_REVIEW
+```
+
+**3. Fix by condition — no gaming.**
+
+- **`new_coverage < 80%`** → add **real** unit tests for the uncovered new lines
+  (usually a new orchestration/`_run_*`/helper). There is NO mark-safe shortcut and
+  NEVER widen `sonar.coverage.exclusions` to dodge it.
+- **`new_code_smells` / `new_maintainability_rating` (e.g. S1192 duplicated literal,
+  S3776 cognitive complexity)** → fix at source. For a duplicated literal your diff
+  merely *touched*, collapse it to one module-scope alias so it falls under the
+  threshold (pyright/tests prove it's safe). For S7497, re-raise swallowed
+  `asyncio.CancelledError`.
+- **`new_security_hotspots_reviewed < 100%`** → only for a **genuine** false positive:
+  `POST /api/hotspots/change_status` form body
+  `hotspot=<key>&status=REVIEWED&resolution=SAFE&comment=<justification>` (204 = ok),
+  then **re-run the SonarCloud job** so it reposts the GitHub status
+  (`gh run rerun <run-id> --job <sonar-job-id>` — the coverage artifact is reused).
+  Never mark a real hotspot SAFE.
+
+**4. Push fixes, then re-verify from step 1** (the check must read `pass`).
+
+## Output
+
+- Verdict: **GREEN** (gate passed, zero new issues) or **RED** with the exact failing
+  conditions and a fix list (`file:line · rule · what to do`).
+- After any fix: re-confirm via step 1 — green check = gate passed.
+
+## See also
+
+- `docs/GITHUB.md` § SonarCloud Quality Gate — full policy + coverage-exclusion rationale.
+- `/gflow:check` — the local pre-commit gates (coverage floor pre-empts `new_coverage`).
+- Memory: [[sonarcloud-pr-issues-scope-s7497]], [[sonarcloud-new-code-gotchas]],
+  [[sonarcloud-hotspot-review-workflow]], [[sonarcloud-setup]].

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/.github/workflows/ci.yml

@@ -93,10 +93,13 @@ jobs:
     runs-on: ubuntu-latest
     needs: test   # wait for tests + coverage report
     # Forked pull_request runs do not receive repository secrets, so SONAR_TOKEN
-    # is empty there and the scanner fails before analysis. Keep SonarCloud on
-    # trusted pushes/internal PRs where the token is available.
+    # is empty there and the scanner fails before analysis. Dependabot-triggered
+    # runs are the same case: GitHub serves them the separate Dependabot secrets
+    # namespace, so SONAR_TOKEN is also empty even though the branch is in-repo.
+    # Keep SonarCloud on trusted pushes/internal PRs where the token is available.
     if: >
       always() &&
+      github.actor != 'dependabot[bot]' &&
       (
         github.event_name != 'pull_request' ||
         github.event.pull_request.head.repo.full_name == github.repository

gflow_cli-0.23.0/.github/workflows/main-base-guard.yml

@@ -0,0 +1,50 @@
+name: Guard main base
+
+# Blocks the divergence class that bit v0.21.0: a non-release branch merged
+# straight into `main` (PR #203 — base mistakenly set to `main`, then squashed),
+# which bypassed `develop` and skipped the `main -> develop` back-merge, leaving
+# `main` ahead of `develop` by an orphaned squash commit.
+#
+# Policy: only `chore/release-*` (cut by /gflow:release) or `hotfix/*` branches
+# may target `main`. Everything else must go through `develop` (the default /
+# integration branch). Dependabot and normal PRs already default to `develop`,
+# so this only catches a deliberate, mistaken `--base main`.
+#
+# The job runs on EVERY PR and passes trivially when the base is not `main`, so
+# it is safe to mark as a *required* status check on `main` without blocking
+# `develop` PRs (which would otherwise hang as "expected — waiting").
+
+on:
+  pull_request:
+    types: [opened, reopened, edited, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  guard:
+    name: Only release/hotfix branches may target main
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify base/head pairing
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: |
+          echo "PR head '$HEAD_REF' -> base '$BASE_REF'"
+          if [ "$BASE_REF" != "main" ]; then
+            echo "Base is '$BASE_REF' (not main) — nothing to enforce."
+            exit 0
+          fi
+          case "$HEAD_REF" in
+            chore/release-*|hotfix/*)
+              echo "OK: '$HEAD_REF' is allowed to target 'main'."
+              ;;
+            *)
+              echo "::error title=Wrong base branch::PR head '$HEAD_REF' must not target 'main'."
+              echo "Only 'chore/release-*' (via /gflow:release) or 'hotfix/*' branches may merge into 'main'."
+              echo "Feature, CI, fix, docs, and dependency work must target 'develop' (the integration branch)."
+              echo "Fix: re-target this PR to 'develop', or — if this really is a release — rename the branch to 'chore/release-vX.Y.Z'."
+              exit 1
+              ;;
+          esac

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/.gitignore

@@ -32,12 +32,15 @@ htmlcov/
 .DS_Store
 
 # Project-specific — secrets / session storage (NEVER commit)
-auth/                  # any project-local auth dir
-profile_*/             # Chromium persistent contexts (any name)
-*.cookies.json         # exported cookie jars
-storage_state.json     # Playwright storage_state output
-secrets.json           # generic secrets file
-.env                   # local env overrides (the .env.template IS committed)
+# NOTE: git does NOT support trailing inline comments in .gitignore — a `#` only
+# starts a comment at the START of a line. Keep each pattern on its own line so
+# the comment text isn't folded into the pattern (which silently un-ignores it).
+/auth/
+profile_*/
+*.cookies.json
+storage_state.json
+secrets.json
+.env
 .env.local
 .env.*.local
 
@@ -93,3 +96,6 @@ worktrees/
 # Understand Anything (local knowledge graph)
 .understand-anything/
 .worktrees
+
+# Subagent-driven-development scratch (ledger + task reports)
+.superpowers/

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/AGENTS.md

@@ -50,6 +50,7 @@ Or invoke the wrapper: `/gflow:check`.
 - Use `pytest -m "not live and not e2e and not smoke"` locally; full suite OOMs on small dev machines. Scope to changed dirs; trust CI for the full sweep.
 - TDD is non-negotiable. Coverage floor: 80% overall.
 - Documentation is a first-class deliverable. Every behavior, workflow, config, or operator-facing change must update the relevant docs or state why no docs changed in the PR/checklist. `scripts/ci/check_doc_links.py` is a merge gate.
+- **A PR is not done until its SonarCloud gate is green (zero new issues).** The six gates above are local/pre-commit; SonarCloud is server-side and runs in CI (`sonar.qualitygate.wait=true` → a red gate turns the `SonarCloud analysis` check red). Before calling a PR merge-ready, verify it with `/gflow:sonar <N>` (it is skipped on fork PRs — maintainer-checked there).
 - Live tests (`@pytest.mark.live`) opt in via `GFLOW_LIVE=1`. E2E tests require `GFLOW_CLI_E2E_PROFILE`.
 
 ## Code style
@@ -68,6 +69,15 @@ Or invoke the wrapper: `/gflow:check`.
 - Run `/gflow:check` (or the Impeccable Routine) before every commit.
 - All releases require a signed annotated tag (`git tag -s vX.Y.Z`); CI rejects unsigned tags.
 
+## Working discipline — verify before you act
+
+These rules exist because docs alone don't bind under momentum: a "check open PRs first" rule was already written and still got skipped, and a PR was merged without seeing an entangled open one. Follow them on every task.
+
+- **Check what's already in flight before coding a fix, opening a PR, or merging.** Run `gh pr list` and `git ls-remote` first — another open PR may already touch the same issue or files. Reconcile against it; don't re-derive "the only thing left" from a stale handoff. (A `PreToolUse` hook also surfaces same-issue open PRs at `gh pr create`/`merge` time, but treat that as a backstop, not a substitute for looking.)
+- **Truth is the CLI and running the code — not IDE/LSP "reminder" diagnostics.** Editor / `pyright`-in-worktree warnings go stale for an entire session and throw false positives (especially across multiple worktrees). Confirm with `ruff` / `pyright` / `pytest` from the terminal — or trust the worktree's own venv — never an IDE squiggle.
+- **Verify third-party runtime behavior empirically before wiring it in.** Don't assume how an external library, API, or browser actually behaves — exercise it once and observe, then build on the observed contract.
+- **If a claim can't be verified in the current environment, it's LIKELY — not CONFIRMED.** Keep the issue open, reference it with `Refs #N` (not `Closes #N`), and ship diagnostics rather than a blind fix. When you can't reproduce it, hand the fix to whoever can.
+
 ## Skills reference (cross-tool)
 
 The `skills/` directory ships installable agent skill docs in plain Markdown with YAML frontmatter. Any agent can consume them directly:

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/CHANGELOG.md

@@ -7,6 +7,106 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] — 2026-07-01
+
+### Added
+
+- **MCP generation is now functional (#228)**: the `gflow_generate_image` and
+  `gflow_generate_video` MCP tools — previously non-functional stubs — now enqueue onto
+  the FlowWorker queue and run end-to-end, with the background worker owning download and
+  history recording. The `tools` parameter (e.g. `creative-director`) is now applied to
+  expand the prompt before generation (it was previously accepted but never applied), and
+  reference images are supported across the image (`i2i`) and video (`i2v` / `r2v`) tools.
+
+### Fixed
+
+- **macOS generation 401 — resolved (#222, #230)**: Flow cookies are now read from the
+  full cookie jar filtered by domain instead of a path-`/` URL filter that silently
+  dropped the `/fx`-scoped `__Secure-next-auth.session-token`; and on macOS — where the
+  headed generation context can intermittently fail to decrypt the on-disk cookie store —
+  the session is seeded into the context from a snapshot captured pre-launch via the
+  working `--password-store=basic` reader. Verified end-to-end on macOS (Apple Silicon) by
+  the reporter. Thanks @gunalak.
+- **MCP video task safety (#228)**: `i2v` now requires `initial_frame` and `r2v` requires
+  `reference_images`, validated at the tool boundary with a clear error; a post-success
+  recording failure no longer flips a credit-spent video to `failed`; and any
+  non-`completed` task status is reported as a failure rather than a false success.
+- **Chrome channel on Chromium-only hosts**: `channel_for_profile()` now gates
+  Playwright's `channel="chrome"` on a new `_is_playwright_chrome_channel_available()`
+  check that probes only the exact Google-Chrome paths Playwright hardcodes, instead
+  of `is_chrome_available()` (which also accepts Chromium). On a host with only
+  Chromium installed, the CLI no longer requests `channel="chrome"` and fails with
+  `Chromium distribution 'chrome' is not found at /opt/google/chrome/chrome`; it falls
+  back to bundled Chromium and logs an actionable warning (#219).
+- **Text-to-image extra-image billing**: the generation-settings trigger selector now
+  requires `button[aria-haspopup='menu']` (aliased to `MODE_SWITCH_TRIGGER_SELECTORS`),
+  preventing a mis-click on an icon-only aspect thumbnail that skipped the count panel
+  and left Flow's own default count (typically 2) in effect — billing extra generations
+  while the CLI saved only one (#219).
+- **Extra-image observability**: `generate_image()` now logs a
+  `client.generate_image_extra_returned` warning when the transport returns more images
+  than the requested `count=1`, so silent over-generation is surfaced to the user (#219).
+- **macOS generation 401 — fail loud (#222)**: a `chrome`-strategy profile that is
+  silently downgraded to bundled Chromium at generation launch now raises instead of
+  running logged-out, so the macOS auth failure surfaces at its cause rather than as an
+  opaque later `401`.
+
+### Diagnostics
+
+- **Persistent-context cookie state (#222)**: generation launch now logs the resolved
+  `cookies_db_path` (`client.persistent_context_launch`) and the launched context's own
+  cookie state (`client.context_cookie_state`: `flow_session_cookie_present` / count /
+  expiry — **never values**, safe to paste publicly). This splits a cookie-**load**
+  failure (the macOS persistent context cannot decrypt the profile's cookies) from a
+  server-side rejection — the observability that localized the macOS `401` root cause,
+  now resolved (see the #222/#230 entry above).
+
+## [0.22.0] — 2026-06-28
+
+### Added
+
+- **Tools framework ("Creative Director")**: a TOML-defined prompt-tool system with
+  `creative-director` as the first built-in tool, exposed via two surfaces:
+  - **`gflow tools list/show/run`** — discover tools, inspect their styles, and run them
+    standalone (e.g. `gflow tools run creative-director "a cat" --style cinema --json`).
+  - **`-t` / `--tool` option** on every generation command — `image t2i` / `i2i` / `batch`,
+    `video t2v` / `i2v` / `r2v` / `chain` — apply one or more tools before generating
+    (e.g. `--tool creative-director:style=cinema`). Repeatable. On multi-prompt batches and
+    chains the tool is applied per prompt/link. Replaces the never-released `-e/--expand` flag.
+  - The `creative-director` tool rewrites a terse prompt into a vivid one using Google's
+    five-component formula (Subject + Action + Context/Location + Composition/Camera + Style)
+    via the public Gemini API. Requires `GFLOW_CLI_GEMINI_API_KEY`
+    ([get one](https://aistudio.google.com/apikey)); optional `GFLOW_CLI_GEMINI_MODEL`
+    (default `gemini-2.5-flash`). Domain-vocabulary modes (`--style cinema`, `portrait`,
+    `product`, etc.) inject specialized lens/lighting/colour vocabulary; styles are
+    **category-gated**, so image styles apply to image commands and video styles to video.
+  - Tool application is **never fatal** — missing key, rate limit, or any API/network fault
+    degrades gracefully to the original prompt.
+  - **History**: a generation rewritten by a tool records the user's original prompt in the
+    `prompt` column, the submitted expansion in `expanded_prompt`, and the applied tool
+    (`{name, version, model, params, config_hash}`) in `operations.metadata_json.tool` — all
+    honoring `GFLOW_CLI_HISTORY_PROMPTS=redacted` (the redacted form stores only
+    `{name, version, params_hash, config_hash}`).
+  - MCP parity: `gflow_list_tools` tool and a `tools` array parameter (`[{name, options}]`) on
+    `gflow_generate_image` / `gflow_generate_video`, validated and adapted to the CLI
+    `--tool` form.
+  - **"My Tools"**: drop your own tool TOMLs into `<GFLOW_CLI_HOME>/tools/*.toml` and they are
+    registered automatically — listed by `gflow tools list`, usable via `--tool`, and exposed over
+    MCP, just like built-ins. A user tool may override a built-in of the same name (logged via
+    `tool_user_override`); a malformed user TOML fails loud. See [docs/TOOLS.md](docs/TOOLS.md).
+  - The Gemini prompt expander gained an overall **wall-clock budget** (default ~60s per call)
+    on top of the lowered 20s per-attempt timeout, so sustained rate limiting can no longer
+    block a generation for the full retry schedule before falling back to the original prompt.
+
+### Deprecated
+
+- **`expand_prompt` MCP prompt**: superseded by the `creative-director` tool, which performs the
+  rewrite server-side (calls Gemini, strips banned keywords, supports domain styles, records
+  provenance). The prompt still works and now carries a `[DEPRECATED]` marker in its
+  client-visible description; it is slated for removal in a future major release. Use
+  `gflow tools run creative-director` / `--tool` (CLI) or `gflow_list_tools` + the `tools` array
+  param (MCP) instead.
+
 ## [0.21.0] — 2026-06-26
 
 ### Added
@@ -1582,7 +1682,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.21.0...HEAD
+[Unreleased]: https://github.com/ffroliva/gflow-cli/compare/v0.23.0...HEAD
+[0.23.0]: https://github.com/ffroliva/gflow-cli/compare/v0.22.0...v0.23.0
+[0.22.0]: https://github.com/ffroliva/gflow-cli/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/ffroliva/gflow-cli/compare/v0.20.1...v0.21.0
 [0.20.1]: https://github.com/ffroliva/gflow-cli/compare/v0.20.0...v0.20.1
 [0.20.0]: https://github.com/ffroliva/gflow-cli/compare/v0.19.0...v0.20.0

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/CONFIGURATION.md

@@ -9,6 +9,8 @@
 | `GFLOW_CLI_BROWSER` | `auto` | Browser mode. See **Browser mode** section below. |
 | `CHROME_BINARY` | (autodetect) | Override Chrome binary path. Falls back to platform-standard locations. |
 | `GFLOW_CLI_CONCURRENCY` | `4` | Maximum parallel API requests per batch. |
+| `GFLOW_CLI_GEMINI_API_KEY` | _(unset)_ | Public Gemini key enabling prompt expansion (`-e`/`--expand`). Unset = expansion is a graceful no-op. [Get one](https://aistudio.google.com/apikey). |
+| `GFLOW_CLI_GEMINI_MODEL` | `gemini-2.5-flash` | Gemini model used for prompt expansion. |
 | `GFLOW_LIVE` | _(unset)_ | Set to `1` to enable live-API test markers (`@pytest.mark.live`). |
 
 ---

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/CONTRIBUTING.md

@@ -102,6 +102,23 @@ pip install pre-commit && pre-commit install
 
 The `.pre-commit-config.yaml` already ships ruff and the hygiene gate.
 
+### SonarCloud quality gate
+
+On top of the six gates, CI runs a **SonarCloud** analysis whose quality gate must be
+**green** before a PR is merge-ready — the target is **zero new issues** on changed code
+(new bugs, vulnerabilities, and code smells = 0; coverage of new lines ≥ 80%; security
+hotspots reviewed = 100%). The local `--cov-fail-under=80` gate already pre-empts the
+coverage condition, so if your tests are green locally you have usually cleared the part
+of the gate you can run yourself.
+
+SonarCloud is **server-side and maintainer-run**: it needs a repo secret (`SONAR_TOKEN`)
+that, for security, GitHub does **not** share with pull requests from forks. So **on a
+fork PR the SonarCloud check is skipped** — you cannot run it, and that is expected. A
+maintainer checks the gate before merging (and, for fork PRs, may re-run the branch
+internally to produce an analysis). Don't worry if you see the SonarCloud check absent or
+skipped on your PR; focus on keeping the six local gates green and your diff free of new
+smells. Full policy: [`docs/GITHUB.md`](docs/GITHUB.md) § SonarCloud Quality Gate.
+
 ### Script output convention
 
 All runtime output — smoke runs, debug dumps, generated images — **must** go

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/GEMINI.md

@@ -25,7 +25,7 @@
 
 ## Active phase
 
-- **Decoupled Daemon/Worker Plan:** The blueprint for the headless SSE Daemon, SQLite generation queue, and Tauri/React editor is scheduled in [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-23-mcp-ui-worker-integration/PLAN.md) and [SCENARIO.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-23-mcp-ui-worker-integration/SCENARIO.md).
+- **Decoupled Daemon/Worker Plan:** The MCP→FlowWorker wiring shipped in v0.23.0 (PR #228). The remaining headless SSE Daemon + Tauri/React editor blueprint is scheduled in [gflow-studio-scaffold/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-gflow-studio-scaffold/PLAN.md) and [rest-api-layer/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-rest-api-layer/PLAN.md).
 - **Core Lesson (Retrospective):** Kept `gflow-cli` strictly headless (running Uvicorn and FastMCP over localhost HTTP/SSE). Bypassed browser context locks by serializing task writes in SQLite queue, allowing parallel client database reads via WAL mode.
 
 See [PLAN.md](PLAN.md) or type `gflow:status` for the current task. Type `gflow:plan <feature>` to create a new feature plan.

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/KNOWN_ISSUES.md

@@ -14,6 +14,28 @@ Living list of behaviour that's broken, surprising, or limited by design — alo
 
 ## Open
 
+### macOS: generation runs logged-out → HTTP 401, even with `--browser chrome`
+
+- **Status:** **RESOLVED in v0.23.0** ([#222](https://github.com/ffroliva/gflow-cli/issues/222),
+  fixed by [#230](https://github.com/ffroliva/gflow-cli/pull/230), @gunalak)
+- **Severity:** High · **Affected:** all `gflow` generation on **macOS** with a
+  `chrome`-strategy profile; Windows was unaffected
+
+On macOS, generation calls failed with **HTTP 401** (`AuthExpiredError` at
+`project.createProject`) on a profile that `gflow auth login` and verification
+accepted. Two corrections fixed it (verified end-to-end on macOS Apple Silicon):
+
+1. **Cookie-read bug (unconditional).** The Flow cookie snapshot read the jar via
+   `ctx.cookies(["https://labs.google"])`, whose path-`/` filter silently dropped
+   the `/fx`-scoped `__Secure-next-auth.session-token`. Now the full jar is read
+   and filtered by domain, so the session token is captured.
+2. **macOS headed-context decrypt (intermittent).** When the headed generation
+   context can't decrypt the on-disk store, the session is seeded from a snapshot
+   captured **pre-launch** via the working `--password-store=basic` reader. No-op on
+   Windows and on runs where the context decrypts natively.
+
+Evidence: [LIVE_VERIFICATION_v0.23.0](docs/LIVE_VERIFICATION_v0.23.0.md).
+
 ### Flow's new full-page media-library UI breaks entity attach (A/B rollout)
 
 - **Status:** **Open** — Flow-side staged rollout; tracked in

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gflow-cli
-Version: 0.21.0
+Version: 0.23.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,7 +58,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.18; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'
 Provides-Extra: gcs
 Requires-Dist: gcsfs>=2024.2.0; extra == 'gcs'
 Requires-Dist: universal-pathlib>=0.2.5; extra == 'gcs'
@@ -94,6 +94,7 @@ You pay for Google AI Ultra or Pro, you have Veo credits, and you run real batch
 
 - **Batch generation.** Loop prompts straight from the shell: `for p in $(cat prompts.txt); do gflow image t2i "$p"; done`. Image batching plus `gflow video t2v` / `i2v` / `r2v` all ship today.
 - **Consistent subjects.** `gflow character create` mints a Flow Character (face and body reference) so the same person appears from one generation to the next.
+- **Prompt tools.** `--tool creative-director` rewrites a terse prompt into a vivid one (Google's 5-component formula) before generating — on any command. Bring your own with [My Tools](docs/TOOLS.md).
 - **Pipelines.** Wire Veo into your content automation, AI-video stack, or batch experiments.
 - **Terminal-native.** After one `gflow auth login`, you stay in the shell. No clicking through dialogs.
 

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/PLAN.md

@@ -359,8 +359,14 @@ The video-generation feature has its own sub-phase plan (spike → Phase A → P
   - **Phase 4 (Task #6, 2026-05-26, branch `claude/next-quick-win-gBPqS`, PR #93):** `NEW_PROJECT_SELECTORS` expanded to all 14 locales (icon-first tier + 14-locale text tier); English-only ARIA fallbacks (`[aria-label*='New project']`, `[aria-label*='Project']`) removed. `SUBMIT_BUTTON_SELECTORS` drops its English-only `button[aria-label*="Create"]` entry — `arrow_forward` icon selectors cover it in all locales. Both tuples are now fully locale-invariant. Note: issue #24 was closed 2026-05-24 after Phases 1–3; Phase 4 is cosmetic tail work. `--lang=en-US` retained only to stabilise `IMAGE_MODEL_OPTION_SELECTORS` (product names like "Nano Banana 2" may be localised). Removing it requires converting the image model picker to a structural anchor — tracked as issue #94 (Phase 5 below). **R2V live e2e on non-EN not yet exercised** — still open.
   - **Phase 5 (2026-05-30, branch `claude/issue-94-staleness-check-MnsEY`, PR #127):** `IMAGE_MODEL_OPTION_SELECTORS` and `VIDEO_MODEL_OPTION_SELECTORS` converted from `dict[Model, str]` to `dict[Model, tuple[str, ...]]` (cascade discipline; Tier 1 structural slots reserved for future DOM-probe-confirmed anchors). `--lang=en-US` removed from Chromium launch args — locale controlled by `locale=locale_env` Playwright kwarg (persists across all navigations including `/project/<uuid>` deep-links) + `FLOW_URL`'s `?hl=en` on initial load. Branded model names confirmed locale-stable. Four new `TestSelectorLocaleInvariance` tests + four `TestSelectImageModel` runtime tests. **R2V live e2e on non-EN still pending (owner gate — requires authenticated non-EN Chrome profile).**
 - [ ] **Model Context Protocol (MCP) Server.** (Backlog) Expose core gflow-cli tools via MCP for language-agnostic agentic access. Planned in [PREDICT.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/PREDICT.md) / [SCENARIO.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/SCENARIO.md) / [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-mcp-server/PLAN.md).
-- [ ] **Prompt Expansion ("Creative Director" mode).** (Backlog) Add an option to expand prompts using Google's official 5-component formula via Gemini. Planned in [PREDICT.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-prompt-expansion/PREDICT.md) / [SCENARIO.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-prompt-expansion/SCENARIO.md) / [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-22-prompt-expansion/PLAN.md).
-- [ ] **Integrated Filmmaking Studio, Flow Worker & MCP SSE Service.** (Backlog) Port google-flow-worker, construct a local FastAPI/React filmmaking studio dashboard, and support HTTP/SSE MCP. Planned in [DESIGN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-23-mcp-ui-worker-integration/DESIGN.md) / [PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-23-mcp-ui-worker-integration/PLAN.md).
+- [x] **Tools framework + Prompt Expansion ("Creative Director") — shipped → develop (PRs #210 + #211, 2026-06-28).** Prompt expansion evolved from the never-released `-e`/`--expand` flag into a TOML-defined **Tools framework**: `creative-director` is the first built-in tool, invoked uniformly via `--tool/-t <name>[:k=v]` on every generation command (`image t2i`/`i2i`/`batch`, `video t2v`/`i2v`/`r2v`/`chain`) or standalone via `gflow tools list/show/run`. The tool rewrites a terse prompt via Gemini's 5-component formula (`src/gflow_cli/tools/`, stdlib-urllib expander, never-fatal: missing key / 429-backoff / network / empty-clean all fall back to the original), with 15 domain styles and deterministic banned-keyword stripping. `operations.expanded_prompt` records original + submitted expansion (withheld under `history_prompts=redacted`); `metadata_json.tool` records `{name, version, model, params, config_hash}` provenance (minimized in redacted mode). Reuses `GFLOW_CLI_GEMINI_API_KEY`; `GFLOW_CLI_GEMINI_MODEL` overrides. MCP parity: `gflow_list_tools` + a `tools` array param per AGENTS.md §61. Docs: [TOOLS.md](file:///C:/development/github/gflow-cli/docs/TOOLS.md) + [PROMPT_EXPANSION.md](file:///C:/development/github/gflow-cli/docs/PROMPT_EXPANSION.md). Memory `[[prompt-expansion-feature]]`.
+  - **PR #210 (framework):** `tools/` package (spec/loader/registry/runtime/expander/banned/invocation), `creative-director.toml`, `gflow tools list/show/run`, `--tool` on t2i/t2v (single-prompt guard kept), MCP `gflow_list_tools` + `tools` param.
+  - **PR #211 (broaden surface):** `original_prompt`/`tool` carried on the request DTOs (`GenerateImageRequest`/`GenerateVideoRequest`/`BatchPromptItem`/`ChainLinkSpec`); recorder reads `request.original_prompt` (kwarg retired); `metadata_json.tool` recording; `--tool` wired into i2i/batch/i2v/r2v/chain; single-prompt guard removed. Silent-misrecord hazard resolved by carrying `original_prompt` on the DTO rather than re-threading a kwarg through each recorder method.
+  - **Expander robustness — DONE 2026-06-28 (PR #214).** Per-attempt timeout lowered 30s→20s and an overall `max_total_seconds` wall-clock budget (default 60s) added to `tools/expander.py` — retries stop once the budget is spent and each attempt's timeout is clamped to the remaining budget, so sustained 429s can no longer block ~120s before fallback. `tenacity` (a dep) was evaluated and **rejected**: it is built around re-raising after retries whereas the expander must never raise (fall back to the original), and the per-attempt structlog + total-budget logic is clearer as a hand-rolled loop with injectable `transport`/`sleep`/`clock` seams.
+  - **`expand_prompt` reconcile — DONE 2026-06-28 (PR #215).** The legacy `mcp/prompts.py` `expand_prompt` MCP prompt is **deprecated** in favor of the `creative-director` tool (client-visible `[DEPRECATED]` marker; kept functional; removal slated for a future major). See [PROMPT_EXPANSION § Relationship to expand_prompt](file:///C:/development/github/gflow-cli/docs/PROMPT_EXPANSION.md).
+  - **My Tools — DONE 2026-06-28 (PR #216).** User-authored TOMLs in `<GFLOW_CLI_HOME>/tools/*.toml` are loaded into the registry (override-a-builtin-with-warning; malformed fails loud).
+  - **Backlog — deferred by design:** the S3 `Tool.apply(ctx)→outcome` dispatch framework. The research doc gates it on a *second, non-prompt* tool (e.g. Mockup) — building it now with a single prompt-only implementer is the documented "premature uniformity (guessed contract)" anti-pattern.
+- [ ] **Integrated Filmmaking Studio, Flow Worker & MCP SSE Service.** (Backlog) The MCP→FlowWorker wiring shipped in v0.23.0 (PR #228). Remaining: a local FastAPI/React filmmaking studio dashboard + HTTP/SSE MCP. Planned in [gflow-studio-scaffold/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-gflow-studio-scaffold/PLAN.md) and [rest-api-layer/PLAN.md](file:///C:/development/github/gflow-cli/docs/superpowers/plans/2026-06-24-rest-api-layer/PLAN.md).
 - [x] **Issue #92: Google account identity persistence shipped 2026-05-28 (PR #110).** After every `gflow auth login`, both auth strategies write the verified email to `$GFLOW_CLI_HOME/profile_<name>/.gflow_account`. `ProfileMeta.google_account` surfaces it; `gflow auth list` and `gflow auth list --json` display it. First-login auto-rename: when no `--profile` flag was given and the only profile is named `default`, it is renamed to the email local-part. `profile_store.rename_profile()` primitive added. Zero-credit smoke test (`tests/smoke/test_profile_account_smoke.py`) ships with backfill path for pre-existing profiles. LLM council (9-dim) run; all must-fix items applied before merge. See `KNOWN_ISSUES.md` § Resolved for full detail.
 - [x] **`/gflow:pr-council-review` slash command shipped 2026-05-26 (PR #97).** Multi-dimensional LLM council for open PRs (4 baseline + 8 adaptive dimensions, mandatory memory-slug binding, draft-PR guard, YELLOW escape valve, live-verify gate). Validated on PR #93; self-audited by 3-agent meta-council surfacing 13 must-fix items applied before merge. See memory `[[llm-council-code-review-pr93]]`.
   - **Phase A (Backlog — Portability):** extract command body into `skills/pr-council-review/SKILL.md` so Gemini CLI / Codex / Cursor / Aider can consume it. Keep `.claude/commands/gflow/pr-council-review.md` as a thin wrapper. Memory: `[[pr-council-review-portability-backlog]]`.

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/README.md

@@ -23,6 +23,7 @@ You pay for Google AI Ultra or Pro, you have Veo credits, and you run real batch
 
 - **Batch generation.** Loop prompts straight from the shell: `for p in $(cat prompts.txt); do gflow image t2i "$p"; done`. Image batching plus `gflow video t2v` / `i2v` / `r2v` all ship today.
 - **Consistent subjects.** `gflow character create` mints a Flow Character (face and body reference) so the same person appears from one generation to the next.
+- **Prompt tools.** `--tool creative-director` rewrites a terse prompt into a vivid one (Google's 5-component formula) before generating — on any command. Bring your own with [My Tools](docs/TOOLS.md).
 - **Pipelines.** Wire Veo into your content automation, AI-video stack, or batch experiments.
 - **Terminal-native.** After one `gflow auth login`, you stay in the shell. No clicking through dialogs.
 

{gflow_cli-0.21.0 → gflow_cli-0.23.0}/docs/CONFIGURATION.md

@@ -27,6 +27,9 @@ $env:GFLOW_CLI_HOME = "D:\gflow-cli"                                # PowerShell
 ```
 
 See [AUTHENTICATION § Session storage](AUTHENTICATION.md#session-storage) for the full layout.
+`$GFLOW_CLI_HOME` also holds `config.toml`, the SQLite catalog (`gflow.db`), and — if you
+create it — a `tools/` directory of user-authored "My Tools" TOMLs
+(`<GFLOW_CLI_HOME>/tools/*.toml`, auto-loaded; see [TOOLS.md § My Tools](TOOLS.md)).
 
 ### `GFLOW_CLI_PROFILE`
 
@@ -112,11 +115,26 @@ Deep setup, verification, and security notes live in
 
 ### `GFLOW_CLI_GEMINI_API_KEY`
 
-**What:** API key for the official Veo 3.1 SDK.
-**Required when:** `GFLOW_CLI_PROVIDER=official`.
+**What:** Public Gemini API key. Used by the **`creative-director`** prompt tool
+(`--tool creative-director` / `gflow tools run creative-director`, see
+[TOOLS.md](TOOLS.md) and [PROMPT_EXPANSION.md](PROMPT_EXPANSION.md)) and, in future, by the
+official Veo 3.1 SDK.
+**Required when:** you apply the `creative-director` tool (via `--tool` on any generation
+command, or `gflow tools run`), or `GFLOW_CLI_PROVIDER=official`.
 **Default:** unset
+**Behavior when unset:** the tool is a no-op — gflow logs an `INFO` notice and generates
+from your original prompt (it never fails the run). API errors (rate limit, network) fall
+back the same way after a short exponential-backoff retry, bounded by an overall ~60s
+wall-clock budget per call.
 **Get one:** <https://aistudio.google.com/apikey>
 
+### `GFLOW_CLI_GEMINI_MODEL`
+
+**What:** Gemini model used by the `creative-director` prompt tool.
+**Default:** `gemini-2.5-flash`
+**Note:** Override to select a newer Flash revision without upgrading gflow-cli, e.g.
+`GFLOW_CLI_GEMINI_MODEL=gemini-2.5-flash-lite`.
+
 ### `GFLOW_CLI_AUTH_LOGIN_TIMEOUT`
 
 **What:** Maximum time (seconds) that `gflow auth login` waits for the user to complete the Google sign-in flow in the browser.
@@ -179,6 +197,11 @@ Use this when you want the DB on a different volume, outside `GFLOW_CLI_HOME`, o
 
 **Default:** `store`
 
+**Tool provenance:** when a prompt tool (e.g. `creative-director`) rewrites a prompt, `store`
+mode also records the submitted `expanded_prompt` and a full `metadata_json.tool` descriptor;
+`redacted` withholds the expanded prompt and reduces the descriptor to
+`{name, version, params_hash, config_hash}`. See [PROMPT_EXPANSION.md](PROMPT_EXPANSION.md).
+
 ```bash
 GFLOW_CLI_HISTORY_PROMPTS=redacted gflow image t2i "confidential brief"
 ```