fix(deps): declare colorama on Windows so a clean install can run (#846)

CHANGELOG.md

@@ -9,6 +9,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **A clean Windows install could not run a single command.** `configure_logging`
+  renders TEXT logs with `structlog.dev.ConsoleRenderer(colors=True)`, and structlog's
+  Windows `_init_terminal` raises `SystemError` outright when `colorama` is missing —
+  but `colorama` was never declared, and nothing in the runtime closure supplies it
+  (structlog keeps it an optional extra; rich ships its own Windows console handling).
+  Because the call sits in the Click *group* callback it runs before any subcommand
+  body, so every interactive command on a fresh Windows install aborted with a
+  traceback that named structlog and never gflow — the failure read as a broken
+  install rather than an incomplete one, and it made the README's Windows quick-start
+  fail as written. Piping stderr happened to escape it, since `AUTO` then resolves to
+  the JSON renderer, which is why non-interactive use and CI never saw it.
+
+  The only `colorama` edge in `uv.lock` came from **pytest**, a dev dependency — so
+  every developer machine had it transitively and no gate could see the gap.
+  `colorama` is now a declared `sys_platform == "win32"` runtime dependency, and
+  `tests/test_observability.py` fails if it is dropped again. Reproduced and verified
+  on a clean Python 3.13 venv: the same `gflow doctor` invocation that raised
+  `SystemError` before now runs to completion, on both the CLI and the MCP stdio
+  server. ([#846](https://github.com/ffroliva/gflow-cli/issues/846))
 - **The address scan in the migrated-host session probe was quadratic.** It reads a
   1.28 MB `myaccount.google.com` response, and `[\w.+-]+@…` retries from every start
   position and rescans its run before failing to find an `@` — so an unbroken run of

pyproject.toml

@@ -77,6 +77,18 @@ dependencies = [
     "pydantic-settings>=2.5.0",
     "platformdirs>=4.0.0",
     "structlog>=24.0.0",
+    # Windows-only, and NOT optional there: observability.py renders TEXT logs
+    # with `structlog.dev.ConsoleRenderer(colors=True)`, whose Windows
+    # `_init_terminal` raises SystemError outright when colorama is missing.
+    # That runs in the Click group callback, so a clean Windows install aborted
+    # EVERY interactive command before any subcommand body (#846, 0.76.0) with
+    # a traceback that named structlog and never gflow. Nothing in the runtime
+    # closure supplies it — structlog keeps colorama an optional extra and rich
+    # ships its own Windows console handling — and the only colorama edge in
+    # uv.lock comes from pytest, a DEV dependency, which is why every developer
+    # machine hid this. Dropping this line re-breaks Windows out of the box;
+    # tests/test_observability.py guards it.
+    'colorama>=0.4.6; sys_platform == "win32"',
     "tenacity>=8.2",
     "browser-cookie3>=0.20.1",
     # MCP server + daemon layer (gflow serve / gflow mcp).

tests/test_observability.py

@@ -4,11 +4,14 @@
 
 import hashlib
 import json
+import tomllib
 from io import StringIO
+from pathlib import Path
 from unittest.mock import patch
 
 import pytest
 import structlog
+from packaging.requirements import Requirement
 
 from gflow_cli.config import LogFormat
 from gflow_cli.errors import AuthExpiredError, ContentPolicyError, WireFormatError
@@ -18,6 +21,8 @@
     emit_unhandled_event,
 )
 
+_ROOT = Path(__file__).resolve().parents[1]
+
 
 @pytest.fixture(autouse=True)
 def _reset_structlog():
@@ -182,3 +187,33 @@ def test_correlation_id_bound_at_boundary_appears_in_events():
     log.info("any_event")
     assert cap.entries[0]["correlation_id"] == "zzz-111"
     assert cap.entries[0]["cli_version"] == "0.4.0a1"
+
+
+def test_colorama_is_a_declared_windows_runtime_dependency() -> None:
+    """`ConsoleRenderer(colors=True)` makes colorama mandatory on Windows (#846).
+
+    `configure_logging` builds `structlog.dev.ConsoleRenderer(colors=True)` for
+    every TEXT render, and structlog's Windows `_init_terminal` raises
+    `SystemError` outright when colorama is absent. Because that call lives in
+    the Click *group* callback it runs before any subcommand body, so a clean
+    Windows install with no colorama aborts every interactive command — the
+    install looks broken rather than incomplete, and the error names structlog,
+    never gflow.
+
+    Nothing in the runtime closure supplies it: structlog treats colorama as an
+    optional extra and rich implements its own Windows console handling. The
+    only edge to colorama in `uv.lock` comes from **pytest**, a dev dependency,
+    which is exactly why this survived every developer machine and shipped to
+    users in 0.76.0.
+    """
+    data = tomllib.loads((_ROOT / "pyproject.toml").read_text(encoding="utf-8"))
+    deps: list[str] = data["project"]["dependencies"]
+    colorama = next((Requirement(raw) for raw in deps if Requirement(raw).name == "colorama"), None)
+    assert colorama is not None, (
+        "colorama is not declared in [project.dependencies]; a clean Windows "
+        "install then dies with SystemError before any subcommand runs (#846)"
+    )
+    assert colorama.marker is not None and colorama.marker.evaluate({"sys_platform": "win32"}), (
+        f"colorama's marker {str(colorama.marker)!r} excludes win32, which is "
+        "the only platform that needs it"
+    )