[upstream-sync] Python REST Client

[pr4bh4sh]

Origin-to-upstream tracking

• Plan: docs/superpowers/plans/2026-09-25-origin-to-upstream-sync.md
• Source: origin/main
• Target: canonical upstream/main
• Priority: P0
• Dependencies: Feature 1: REST API and JSON step protocol
• Scope rule: port origin behavior to upstream only; do not merge upstream changes back into origin.

Implementation spec

Goal and scope

Publish a supported Python package under client/python that wraps the REST API for pytest and Python automation users. It must cover session lifecycle, typed results, common flow steps, device queries, and an escape hatch for future server steps.

Current behaviour in upstream

upstream/main has no client/python package or Python client tests. Users must call the HTTP API manually or generate YAML.

Desired behaviour

MaestroClient supports context-manager use, explicit session creation/close, raw execute_step, and typed helpers for the origin-supported step families: app lifecycle, selectors/actions, text input, scrolling/gestures, assertions, screenshots, permissions, scripting, device controls, and browser/WebView controls. commands.py is the single JSON command-builder layer, while models.py converts server responses into typed Python objects. Failed non-optional steps raise StepError; optional failures return an ExecutionResult.

Parallel pytest fixtures start one server per worker, assign a distinct device/port, create per-worker output directories, and attach failure log tails and artifact summaries.

Required code changes

• Add client/python/pyproject.toml, package metadata, dependency declarations, and development tooling.
• Add client/python/maestro_runner/models.py, exceptions.py, commands.py, client.py, and __init__.py.
• Port the origin typed methods and the expanded gesture/media/device/browser/WebView bindings from commit 9448fa1.
• Add client/python/tests/conftest.py with server startup, device discovery, xdist worker isolation, cleanup, and artifact reporting.
• Add unit tests for models and command serialization; add device tests separately from unit tests.
• Add client/python/README.md and DEVELOPER.md with installation, server prerequisite, worker variables, and test commands.

Configuration / migration / data changes

• MAESTRO_SERVER_URL, MAESTRO_PLATFORM, MAESTRO_RUNNER_BIN, and MAESTRO_DEVICE_ID are supported.
• pytest-xdist is an optional development/test dependency, not a runtime requirement.
• No user data migration; sessions remain external to the Python process.

Testing strategy

• Unit: mocked HTTP tests for all command builders, response parsing, error mapping, optional failures, and context-manager cleanup.
• Integration: one real server/driver session per Android or iOS device; run a contact flow and animation wait flow.
• Parallel: run two workers against two devices and assert distinct ports, device serials, and output directories.

Rollout plan

Ship after Feature 1. Release the Python package as a development/client artifact first; no runner feature flag is needed. Publish examples and API reference before advertising it as stable.

Acceptance criteria

• The package installs from a clean checkout and passes lint/type/unit checks.
• Every public client method emits a valid JSON step accepted by the server.
• A failed non-optional command raises StepError; optional commands do not.
• close() and context-manager exit are idempotent and do not mask test failures.
• Two xdist workers can run against separate devices without port or server-session collisions.