google/lightflow

PyPI Upgrade Guard (pypi_upgrade_guard)

Executes the 3-stage dependency upgrade workflow with compensating rollback using examples/pypi_upgrade_guard/actions.py.

Workflow Stages & Rules

1. Stage 1 — Audit Pinned Packages (audit_pypi_versions):

   • Call actions.audit_pypi_versions(payload) with {"offline": True, "requirements_path": "<path>"}.

   • Returns (delta_dict, msg) where delta_dict contains {"pinned": dict, "upgrades": list, "upgrade_count": int, "summary": str, "source": str}.

   • Persist delta_dict under payload["outputs"]["audit_pypi_versions"] so audit_pypi_versions is never re-executed in later steps.

   • Example invocation:

     python3 -B -c "import json, sys; sys.path.insert(0, 'examples/pypi_upgrade_guard'); import actions; d, m = actions.audit_pypi_versions({'offline': True}); print(json.dumps({'delta': d, 'message': m}))"
     

2. Stage 2 — Human Approval Gate (approve_upgrades):

   • MANDATORY GATE: Stop after Stage 1 and present delta_dict["summary"] (upgrade_count packages) to the human operator.
   • Wait for their explicit approval ({"approved": True, "approved_by": "<user>", "smoke_test_cmd": "<cmd>"}). Never auto-approve.

3. Stage 3 — Apply Upgrades, Smoke-Test & Compensating Rollback (apply_and_smoke_test):

   • Condition: Run only after Stage 2 is approved. Do not call audit_pypi_versions again.
   • Construct payload with "requirements_path", "simulate_smoke_failure" (bool), "outputs": {"audit_pypi_versions": <delta_dict>, "approve_upgrades": {"approved": True}}.
   • Call actions.apply_and_smoke_test(payload) inside a try / except Exception: block:
     • If apply_and_smoke_test(payload) raises an exception, immediately call actions.restore_requirements_backup(payload) to restore requirements_path from requirements_path + ".bak" and remove .bak, then exit non-zero.
   • Failure Recovery: When recovering from a failed smoke test (e.g., with "simulate_smoke_failure": False), re-run only Stage 3 using the saved outputs.audit_pypi_versions dict without re-running Stage 1.