robotframework-velo-cli 0.1.7__py3-none-any.whl

robotframework_velo_cli-0.1.7.dist-info/METADATA

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: robotframework-velo-cli
+Version: 0.1.7
+Summary: Run Robot Framework test suites on the Velo cloud platform
+Author-email: Velo <support@velo.com>
+License: Copyright (c) 2026 Velo. All rights reserved.
+        
+        PROPRIETARY SOFTWARE LICENSE
+        
+        This software and its source code, documentation, and associated files
+        (collectively, the "Software") are the exclusive property of Velo and are
+        protected by copyright law and international treaties.
+        
+        GRANT OF LICENSE
+        
+        Velo grants you a limited, non-exclusive, non-transferable, non-sub licensable
+        license to use the Software solely for your internal business purposes,
+        strictly in accordance with any agreement entered into with Velo.
+        
+        RESTRICTIONS
+        
+        You may not, and you may not permit any third party to:
+        
+          1. Copy, modify, adapt, translate, or create derivative works of the Software;
+          2. Reverse engineer, disassemble, decompile, or otherwise attempt to derive
+             the source code of the Software;
+          3. Sell, sublicense, rent, lease, transfer, or otherwise make the Software
+             available to any third party;
+          4. Remove or alter any proprietary notices, labels, or marks on the Software;
+          5. Use the Software for any purpose other than as expressly permitted
+             under this license.
+        
+        NO WARRANTY
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
+        FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL VELO BE
+        LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF
+        THE SOFTWARE.
+        
+        TERMINATION
+        
+        This license is effective until terminated. It will terminate automatically
+        if you fail to comply with any of its terms. Upon termination, you must
+        immediately cease all use of the Software and destroy any copies in your
+        possession.
+        
+        GOVERNING LAW
+        
+        This license shall be governed by and construed in accordance with applicable
+        law. Any disputes arising under this license shall be subject to the exclusive
+        jurisdiction of the competent courts.
+        
+        For licensing inquiries, contact: legal@velo.com
+        
+Project-URL: Homepage, https://velo.com
+Project-URL: Bug Tracker, https://github.com/velo/robotframework-velo-cli/issues
+Keywords: robotframework,robot,testing,automation,velo,sap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Robot Framework
+Classifier: Framework :: Robot Framework :: Tool
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: robotframework>=6.0
+Requires-Dist: requests>=2.31
+Requires-Dist: pathspec>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# robotframework-velo-cli
+
+Run Robot Framework test suites on the Velo cloud platform — no SAP GUI setup required on your machine.
+
+---
+
+## Installation
+
+```bash
+pip install robotframework-velo-cli
+```
+
+> **Note:** This package intentionally installs a `robot` command that wraps and replaces the standard Robot Framework entry point. `robotframework` is a declared dependency and will be installed automatically. Because `robotframework-velo-cli` is installed after `robotframework`, its `robot` script takes precedence. When `VELO_REMOTE` is not set the wrapper passes all arguments through to Robot Framework unchanged — your existing workflow is unaffected.
+
+---
+
+## Quick start
+
+```bash
+# 1. Set your workspace credentials
+export VELO_API_KEY=<your-api-key>
+export VELO_API_BASE=http://<velo-api-host>:8000   # default: http://localhost:8000
+
+# 2. Run your tests remotely — same command you always use
+VELO_REMOTE=1 robot ./tests
+
+# 3. With tag filtering — all standard RF flags pass through unchanged
+VELO_REMOTE=1 robot --include smoke --exclude wip ./tests
+```
+
+---
+
+## Execution modes
+
+| Variable | Value | Behaviour |
+|---|---|---|
+| `VELO_REMOTE` | `0` (default) | Package is inert — `robot` runs locally as normal |
+| `VELO_REMOTE` | `1` | Suite is packaged, uploaded, and executed on the Velo platform |
+| `VELO_DEBUG` | `1` | Local debug: native SAP GUI for Windows, or Docker Java elsewhere |
+| `VELO_SAP_CLIENT` | `auto` | SAP backend: `auto`, `java`, or `windows` (see debug mode below) |
+
+---
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `VELO_API_KEY` | Yes (remote) | — | Workspace API key |
+| `VELO_API_BASE` | No | `http://localhost:8000` | Velo API base URL |
+| `VELO_REMOTE` | No | `0` | Set to `1` to enable remote execution |
+| `VELO_DEBUG` | No | `0` | Set to `1` for local debug (Windows native or Docker Java) |
+| `VELO_SAP_CLIENT` | No | `auto` | SAP client: `auto`, `java`, or `windows` |
+
+---
+
+## Remote execution flow
+
+When `VELO_REMOTE=1`, the following happens automatically:
+
+```
+1. Scan working directory and apply .veloignore rules
+2. Package directory into a .zip archive
+3. Upload archive to the Velo API
+4. Trigger a remote run (optionally with --include / --exclude tags)
+5. Stream Robot Framework log output to your terminal in real time
+6. On completion: download log.html + report.html to ./results/
+7. Exit with the standard RF exit code
+```
+
+The terminal experience is identical to a local RF run — log lines appear as tests execute, not buffered.
+
+---
+
+## What gets uploaded
+
+The entire current working directory is packaged into a `.zip` archive when you run `robot`. The archive is created from the directory you run the command in, preserving the full folder structure.
+
+**Typical archive contents:**
+
+```
+tests/
+    smoke/
+        login.robot
+    regression/
+        sales_order.robot
+resources/
+    keywords.robot
+variables/
+    common.py
+```
+
+Only files are included — empty directories are omitted. The archive is uploaded to the API, extracted into the execution container, and `robot` is run against the entire directory.
+
+---
+
+## .veloignore
+
+A `.veloignore` file in the project root controls which files are excluded from the uploaded archive. It uses the same syntax as `.gitignore` (glob patterns, `#` comments, negation with `!`).
+
+Place it at the root of your test project:
+
+```
+your-project/
+├── .veloignore       ← here
+├── tests/
+├── resources/
+└── ...
+```
+
+### Default exclusions
+
+When **no `.veloignore` file is present**, the following are excluded automatically:
+
+```
+.git
+__pycache__
+*.pyc
+*.pyo
+venv
+.venv
+node_modules
+.env
+.env.*
+results
+*.log
+```
+
+### Important: defaults are replaced, not merged
+
+If a `.veloignore` file exists, **it completely replaces the default list** — the defaults above are no longer applied. Include any defaults you still want in your `.veloignore`.
+
+### Example .veloignore
+
+```gitignore
+# Re-include sensible defaults
+.git
+__pycache__
+*.pyc
+venv
+.venv
+.env
+.env.*
+results
+*.log
+
+# Project-specific exclusions
+data/sensitive/
+config/secrets.yaml
+*.csv
+docs/
+```
+
+### Verifying exclusions
+
+After a run, inspect the uploaded archive on the API server:
+
+```bash
+unzip -l <storage_root>/suites/<suite_id>.zip
+```
+
+---
+
+## Artifacts
+
+When the run completes, the following are downloaded to your local `--outputdir` (default: `./results/`):
+
+| File | Description |
+|---|---|
+| `log.html` | Full Robot Framework execution log with keyword-level detail |
+| `report.html` | Test suite summary report |
+
+The video recording (`recording.mp4`) is stored on the server and accessible via the API at `GET /api/runs/{run_id}/artifacts/video`.
+
+---
+
+## Exit codes
+
+The package preserves standard RF exit codes so existing CI scripts and Makefiles work without modification:
+
+| Code | Meaning |
+|---|---|
+| `0` | All tests passed |
+| `1` | One or more tests failed |
+| `2` | Invalid RF options or arguments |
+| `3` | Test execution stopped by user |
+| `252` | Help or version info printed |
+| `253` | Platform error (upload failed, API unreachable, run did not start) |
+
+---
+
+## RF flag pass-through
+
+All standard `robot` flags are forwarded to the remote execution environment:
+
+| Flag | Behaviour |
+|---|---|
+| `--include TAG` / `--exclude TAG` | Passed to remote RF runner |
+| `--variable KEY:VALUE` | Passed to remote RF runner |
+| `--suite SUITE` | Passed to remote RF runner |
+| `--outputdir PATH` | Controls local download destination for results |
+| `--dryrun` | Executes locally — remote is not triggered |
+
+---
+
+## Development install (editable)
+
+```bash
+git clone <repo>
+cd velo
+pip install -e packages/robotframework-velo-cli
+```

robotframework_velo_cli-0.1.7.dist-info/RECORD

@@ -0,0 +1,15 @@
+robotframework_velo_cli-0.1.7.dist-info/licenses/LICENSE,sha256=Qx-di54idhaOnrKKU-L9H2p-8JwkT_G157WyhxR-SZg,1906
+velo/__init__.py,sha256=FOkEvPiy2cSVFxVUDAnajrFLEOWbkwHRcqn9ElxoGBk,177
+velo/cli.py,sha256=4XkgsHx5zP7VZBUGK42ZkgZsqwVjFwOXLfwmdFYNgls,720
+velo/constants.py,sha256=u9f5PRzF85ZG3dBTSdBj0sKHh9yrThOWqYxCo4S19T4,161
+velo/debug.py,sha256=vofojwNkS4qFGqp5rBAvEyrIxtYV74zhAO0EwdfA4xs,4176
+velo/ignore.py,sha256=FqUAkEMth2uxuvscUZhBn67MgFwysNSntXQrpLKU3BA,1042
+velo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+velo/runner.py,sha256=qe8f8pslPDHEwBz0v501X5HNAAZmgsXTLoqJWNgpC_A,4053
+velo/sap_client.py,sha256=aEOh43sK_aXvoCAHz-ygBn4zRpl9USGbS_Ex-qu4OFc,592
+velo/streamer.py,sha256=3sQG3mQswS9xSSWHKo2PgsBtOWcAZwNm7hPz19s5xIo,2083
+robotframework_velo_cli-0.1.7.dist-info/METADATA,sha256=DsFbPgdwP7yIWIG0sKl0_W0en-XxzCV4dwYibOi4-hg,9298
+robotframework_velo_cli-0.1.7.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+robotframework_velo_cli-0.1.7.dist-info/entry_points.txt,sha256=RhLfsXbSOVkzZJ82pF5BNCnUc7AaGjnI-Nt8TfF2v84,66
+robotframework_velo_cli-0.1.7.dist-info/top_level.txt,sha256=DvWsWbYteXtPv_CrlE7HAff1eE_Ayg1c3pLECTGAcQs,5
+robotframework_velo_cli-0.1.7.dist-info/RECORD,,

robotframework_velo_cli-0.1.7.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

robotframework_velo_cli-0.1.7.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+robot = velo.cli:main
+velo = velo.cli:velo_main

robotframework_velo_cli-0.1.7.dist-info/licenses/LICENSE

@@ -0,0 +1,49 @@
+Copyright (c) 2026 Velo. All rights reserved.
+
+PROPRIETARY SOFTWARE LICENSE
+
+This software and its source code, documentation, and associated files
+(collectively, the "Software") are the exclusive property of Velo and are
+protected by copyright law and international treaties.
+
+GRANT OF LICENSE
+
+Velo grants you a limited, non-exclusive, non-transferable, non-sub licensable
+license to use the Software solely for your internal business purposes,
+strictly in accordance with any agreement entered into with Velo.
+
+RESTRICTIONS
+
+You may not, and you may not permit any third party to:
+
+  1. Copy, modify, adapt, translate, or create derivative works of the Software;
+  2. Reverse engineer, disassemble, decompile, or otherwise attempt to derive
+     the source code of the Software;
+  3. Sell, sublicense, rent, lease, transfer, or otherwise make the Software
+     available to any third party;
+  4. Remove or alter any proprietary notices, labels, or marks on the Software;
+  5. Use the Software for any purpose other than as expressly permitted
+     under this license.
+
+NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL VELO BE
+LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF
+THE SOFTWARE.
+
+TERMINATION
+
+This license is effective until terminated. It will terminate automatically
+if you fail to comply with any of its terms. Upon termination, you must
+immediately cease all use of the Software and destroy any copies in your
+possession.
+
+GOVERNING LAW
+
+This license shall be governed by and construed in accordance with applicable
+law. Any disputes arising under this license shall be subject to the exclusive
+jurisdiction of the competent courts.
+
+For licensing inquiries, contact: legal@velo.com

robotframework_velo_cli-0.1.7.dist-info/top_level.txt

@@ -0,0 +1 @@
+velo

velo/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("robotframework-velo-cli")
+except PackageNotFoundError:
+    __version__ = "unknown"

velo/cli.py

@@ -0,0 +1,29 @@
+import os
+import sys
+
+
+def main() -> None:
+    """Shadows the system `robot` command. Gate 2 implementation pending."""
+    args = sys.argv[1:]
+
+    if os.getenv("VELO_REMOTE") == "1":
+        from velo.runner import run_remote
+
+        sys.exit(run_remote(args))
+
+    elif os.getenv("VELO_DEBUG") == "1":
+        from velo.debug import run_debug
+
+        sys.exit(run_debug(args))
+
+    else:
+        import subprocess
+
+        result = subprocess.run([sys.executable, "-m", "robot"] + args)
+        sys.exit(result.returncode)
+
+
+def velo_main() -> None:
+    """Entry point for `velo` CLI subcommands (e.g. velo agent start). Gate 2+."""
+    print("velo agent commands are not available in this build.")
+    sys.exit(1)

velo/constants.py

@@ -0,0 +1,6 @@
+RF_EXIT_ALL_PASS = 0
+RF_EXIT_TEST_FAILURE = 1
+RF_EXIT_INVALID_OPTIONS = 2
+RF_EXIT_STOPPED_BY_USER = 3
+RF_EXIT_HELP_OR_VERSION = 252
+RF_EXIT_PLATFORM_ERROR = 253

velo/debug.py

@@ -0,0 +1,143 @@
+"""VELO_DEBUG=1 — local debug router (native Windows or Docker Java)."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from velo.constants import RF_EXIT_PLATFORM_ERROR
+from velo.sap_client import resolve_sap_client
+
+DOCKER_DESKTOP_URL = "https://www.docker.com/products/docker-desktop"
+EXECUTION_IMAGE = os.getenv("VELO_EXECUTION_IMAGE", "velo-execution")
+
+
+def run_debug(rf_args: list[str]) -> int:
+    client = resolve_sap_client()
+    if client == "windows":
+        return _run_native_windows(rf_args)
+    return _run_docker_java(rf_args)
+
+
+def _run_native_windows(rf_args: list[str]) -> int:
+    if sys.platform != "win32":
+        print(
+            "[velo] VELO_DEBUG with SAP GUI for Windows requires a Windows host.",
+            file=sys.stderr,
+        )
+        return RF_EXIT_PLATFORM_ERROR
+
+    err = _check_windows_scripting()
+    if err:
+        print(f"[velo] {err}", file=sys.stderr)
+        return RF_EXIT_PLATFORM_ERROR
+
+    env = {**os.environ, "VELO_SAP_CLIENT": "windows"}
+    return subprocess.run([sys.executable, "-m", "robot", *rf_args], env=env).returncode
+
+
+def _check_windows_scripting() -> str | None:
+    try:
+        import win32com.client  # type: ignore[import-untyped]
+    except ImportError:
+        return (
+            "pywin32 is required for Windows SAP GUI debug runs. "
+            "Install with: pip install pywin32"
+        )
+
+    try:
+        sap_gui = win32com.client.GetObject("SAPGUI")
+        engine = sap_gui.GetScriptingEngine
+    except Exception:
+        return (
+            "SAP GUI for Windows is not available. Install SAP GUI, start a session, "
+            "and enable scripting in SAP GUI options."
+        )
+
+    if engine is None:
+        return (
+            "SAP GUI Scripting is disabled. Enable it in SAP GUI settings and verify "
+            "server parameter sapgui/user_scripting."
+        )
+    return None
+
+
+def _run_docker_java(rf_args: list[str]) -> int:
+    if shutil.which("docker") is None:
+        print(
+            "[velo] Docker is required for Java SAP GUI debug runs on this platform.",
+            file=sys.stderr,
+        )
+        print(f"[velo] Install Docker Desktop: {DOCKER_DESKTOP_URL}", file=sys.stderr)
+        return RF_EXIT_PLATFORM_ERROR
+
+    cwd = Path.cwd().resolve()
+    results_dir = _parse_outputdir(rf_args)
+    results_dir.mkdir(parents=True, exist_ok=True)
+
+    docker_cmd = [
+        "docker",
+        "run",
+        "--rm",
+        "-v",
+        f"{cwd}:/suite:ro",
+        "-v",
+        f"{results_dir}:/results",
+        "-e",
+        "VELO_SAP_CLIENT=java",
+        "-e",
+        "SUITE_DIR=/suite",
+        "-e",
+        "RESULTS_DIR=/results",
+        EXECUTION_IMAGE,
+    ]
+
+    include, exclude = _parse_tags(rf_args)
+    if include:
+        docker_cmd.extend(["-e", f"ROBOT_INCLUDE={include}"])
+    if exclude:
+        docker_cmd.extend(["-e", f"ROBOT_EXCLUDE={exclude}"])
+
+    print(f"[velo] Starting Docker debug run ({EXECUTION_IMAGE})…", flush=True)
+    return subprocess.run(docker_cmd).returncode
+
+
+def _parse_outputdir(rf_args: list[str]) -> Path:
+    outputdir = "./results"
+    args = list(rf_args)
+    idx = 0
+    while idx < len(args):
+        arg = args[idx]
+        if arg in ("--outputdir", "-d") and idx + 1 < len(args):
+            outputdir = args[idx + 1]
+            idx += 2
+            continue
+        if arg.startswith("--outputdir="):
+            outputdir = arg.split("=", 1)[1]
+        idx += 1
+    path = Path(outputdir)
+    if not path.is_absolute():
+        path = Path.cwd() / path
+    return path.resolve()
+
+
+def _parse_tags(rf_args: list[str]) -> tuple[str | None, str | None]:
+    include: str | None = None
+    exclude: str | None = None
+    args = list(rf_args)
+    idx = 0
+    while idx < len(args):
+        arg = args[idx]
+        if arg in ("--include", "-i") and idx + 1 < len(args):
+            include = args[idx + 1]
+            idx += 2
+            continue
+        if arg in ("--exclude", "-e") and idx + 1 < len(args):
+            exclude = args[idx + 1]
+            idx += 2
+            continue
+        idx += 1
+    return include, exclude

velo/ignore.py

@@ -0,0 +1,41 @@
+import zipfile
+from pathlib import Path
+from typing import Any
+
+import pathspec
+
+DEFAULT_IGNORE = [
+    ".git",
+    "__pycache__",
+    "*.pyc",
+    "*.pyo",
+    "venv",
+    ".venv",
+    "node_modules",
+    ".env",
+    ".env.*",
+    "results",
+    "*.log",
+]
+
+
+def load_ignore_spec(root: Path) -> pathspec.PathSpec[Any]:
+    veloignore = root / ".veloignore"
+    if veloignore.exists():
+        patterns = veloignore.read_text().splitlines()
+    else:
+        patterns = DEFAULT_IGNORE.copy()
+    return pathspec.PathSpec.from_lines("gitwildmatch", patterns)
+
+
+def build_archive(root: Path, output: Path) -> None:
+    """Package root into a zip archive at output, respecting .veloignore rules."""
+    spec = load_ignore_spec(root)
+    with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as zf:
+        for path in sorted(root.rglob("*")):
+            if not path.is_file():
+                continue
+            rel = path.relative_to(root)
+            if spec.match_file(str(rel)):
+                continue
+            zf.write(path, rel)

velo/runner.py

@@ -0,0 +1,124 @@
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+import requests
+
+from velo.constants import RF_EXIT_PLATFORM_ERROR
+from velo.ignore import build_archive
+from velo.streamer import stream_logs_to_terminal
+
+DEFAULT_API_BASE = "https://velo.aster.pro"
+
+
+def run_remote(rf_args: list[str]) -> int:
+    api_base = os.getenv("VELO_API_BASE", DEFAULT_API_BASE)
+    api_key = os.getenv("VELO_API_KEY", "")
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    root = Path.cwd()
+
+    # 1. Build archive respecting .veloignore
+    with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
+        archive_path = Path(tmp.name)
+    build_archive(root, archive_path)
+    size_kb = archive_path.stat().st_size // 1024
+    print(f"[velo] uploading suite ({size_kb} KB)...", flush=True)
+
+    # 2. Upload suite
+    try:
+        with open(archive_path, "rb") as f:
+            r = requests.post(
+                f"{api_base}/cli/api/suites",
+                files={"archive": (root.name + ".zip", f, "application/zip")},
+                headers=headers,
+            )
+        r.raise_for_status()
+    except Exception as exc:
+        print(f"[velo] suite upload failed: {exc}", file=sys.stderr, flush=True)
+        return RF_EXIT_PLATFORM_ERROR
+    finally:
+        archive_path.unlink(missing_ok=True)
+
+    suite_id = r.json()["suite_id"]
+
+    # 3. Parse RF flags for include/exclude tags and output dir
+    include = _extract_flag(rf_args, "--include")
+    exclude = _extract_flag(rf_args, "--exclude")
+    output_dir = _extract_flag(rf_args, "--outputdir") or "results"
+
+    # 4. Trigger run
+    try:
+        r = requests.post(
+            f"{api_base}/cli/api/runs",
+            json={"suite_id": suite_id, "include": include, "exclude": exclude},
+            headers=headers,
+        )
+        r.raise_for_status()
+    except Exception as exc:
+        print(f"[velo] run trigger failed: {exc}", file=sys.stderr, flush=True)
+        return RF_EXIT_PLATFORM_ERROR
+
+    run_id = r.json()["run_id"]
+    print(f"[velo] run started: {run_id}", flush=True)
+
+    # 5. Stream logs to terminal
+    stream_logs_to_terminal(run_id, api_base, api_key)
+
+    # 6. Poll for final status + exit code
+    try:
+        r = requests.get(f"{api_base}/cli/api/runs/{run_id}", headers=headers)
+        r.raise_for_status()
+        run = r.json()
+    except Exception as exc:
+        print(f"[velo] failed to fetch run result: {exc}", file=sys.stderr, flush=True)
+        return RF_EXIT_PLATFORM_ERROR
+
+    # 7. Download artifacts to local output directory
+    _download_artifacts(run_id, output_dir, api_base, api_key)
+
+    exit_code = run.get("exit_code")
+    if exit_code is None:
+        return RF_EXIT_PLATFORM_ERROR
+    return int(exit_code)
+
+
+def _extract_flag(args: list[str], flag: str) -> str | None:
+    """Return the value following `flag` in args, or None if not present."""
+    for i, arg in enumerate(args):
+        if arg == flag and i + 1 < len(args):
+            return args[i + 1]
+        if arg.startswith(f"{flag}="):
+            return arg.split("=", 1)[1]
+    return None
+
+
+def _download_artifacts(
+    run_id: str,
+    output_dir: str,
+    api_base: str,
+    api_key: str,
+) -> None:
+    """Download log.html and report.html into output_dir."""
+    dest = Path(output_dir)
+    dest.mkdir(parents=True, exist_ok=True)
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    artifacts = {
+        "log.html": f"{api_base}/cli/api/runs/{run_id}/artifacts/log",
+        "report.html": f"{api_base}/cli/api/runs/{run_id}/artifacts/report",
+    }
+
+    for filename, url in artifacts.items():
+        try:
+            r = requests.get(url, headers=headers, timeout=60)
+            r.raise_for_status()
+            (dest / filename).write_bytes(r.content)
+            print(f"[velo] downloaded {filename} → {dest / filename}", flush=True)
+        except Exception as exc:
+            print(
+                f"[velo] warning: could not download {filename}: {exc}",
+                file=sys.stderr,
+                flush=True,
+            )

velo/sap_client.py

@@ -0,0 +1,18 @@
+"""SAP client type resolution for VELO_DEBUG and local runs."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def resolve_sap_client(client: str | None = None) -> str:
+    """Return ``java`` or ``windows`` for the active SAP GUI backend."""
+    raw = (client or os.getenv("VELO_SAP_CLIENT") or "auto").strip().lower()
+    if raw not in ("auto", "java", "windows"):
+        raise ValueError(
+            f"Invalid VELO_SAP_CLIENT '{raw}'. Use auto, java, or windows."
+        )
+    if raw == "auto":
+        return "windows" if sys.platform == "win32" else "java"
+    return raw

velo/streamer.py

@@ -0,0 +1,63 @@
+import sys
+import time
+
+import requests
+
+
+def stream_logs_to_terminal(run_id: str, api_base: str, api_key: str) -> None:
+    """
+    Connect to the SSE log stream for a run and print lines to stdout as they arrive.
+    Reconnects up to 5 times with exponential backoff on connection errors,
+    but stops immediately if the run has already reached a terminal state.
+    """
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Accept": "text/event-stream",
+    }
+    retries = 0
+    max_retries = 5
+
+    while retries <= max_retries:
+        try:
+            with requests.get(
+                f"{api_base}/cli/api/runs/{run_id}/stream",
+                headers=headers,
+                stream=True,
+                timeout=300,
+            ) as resp:
+                resp.raise_for_status()
+                retries = 0
+                for raw in resp.iter_lines():
+                    if raw and raw.startswith(b"data: "):
+                        print(raw[6:].decode(), flush=True)
+            return  # stream closed cleanly — run ended
+        except Exception:
+            retries += 1
+            if retries > max_retries:
+                print("[velo] lost contact with platform", file=sys.stderr, flush=True)
+                return
+            if _run_is_terminal(run_id, api_base, api_key):
+                return
+            wait = 2**retries
+            print(
+                f"[velo] reconnecting to log stream... ({retries}/{max_retries})",
+                file=sys.stderr,
+                flush=True,
+            )
+            time.sleep(wait)
+
+
+def _run_is_terminal(run_id: str, api_base: str, api_key: str) -> bool:
+    """Return True if the run has already completed or failed."""
+    try:
+        r = requests.get(
+            f"{api_base}/cli/api/runs/{run_id}",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        if r.status_code == 200:
+            status = r.json().get("status", "")
+            return status in ("completed", "failed")
+    except Exception:
+        pass
+    return False