Merge branch 'master' of github.com:BANANASJIM/rdc-cli

Author: BANANASJIM

.github/workflows/ci.yml

@@ -56,7 +56,8 @@ jobs:
           enable-cache: true
       - run: uv python install 3.12
       - run: uv sync --extra dev
-      - run: uv run --with pip-audit pip-audit
+      # CVE-2026-4539: no fixed pygments release yet (last_affected=2.19.2); ignore until upstream ships a patch
+      - run: uv run --with pip-audit pip-audit --ignore-vuln CVE-2026-4539
 
   validate-aur:
     name: Validate AUR PKGBUILD

docs-astro/src/data/commands.json

@@ -9,7 +9,7 @@
           "name": "open",
           "id": "open",
           "help": "Create local default session and start daemon skeleton.",
-          "usage": "rdc open [CAPTURE] [--preload] [--proxy HOST[:PORT]|adb://SERIAL] [--android] [--serial TEXT] [--remote HOST[:PORT]] [--listen [ADDR]:PORT] [--connect HOST:PORT] [--token TEXT]"
+          "usage": "rdc open [CAPTURE] [--preload] [--proxy HOST[:PORT]|adb://SERIAL] [--android] [--serial TEXT] [--remote HOST[:PORT]] [--listen [ADDR]:PORT] [--connect HOST:PORT] [--token TEXT] [--timeout FLOAT]"
         },
         {
           "name": "close",
@@ -473,6 +473,24 @@
           "help": "Capture on a remote host and transfer to local.",
           "usage": "rdc remote capture <APP> -o <PATH> [--url TEXT] [--args TEXT] [--workdir TEXT] [--frame INTEGER] [--timeout FLOAT] [--api-validation] [--callstacks] [--hook-children] [--ref-all-resources] [--soft-memory-limit INTEGER] [--keep-remote] [--json]"
         },
+        {
+          "name": "remote setup",
+          "id": "remote-setup",
+          "help": "Verify a remote server is reachable, handshake, and save state.",
+          "usage": "rdc remote setup <URL> [--timeout FLOAT] [--json]"
+        },
+        {
+          "name": "remote status",
+          "id": "remote-status",
+          "help": "Show the currently saved remote server state.",
+          "usage": "rdc remote status [--json]"
+        },
+        {
+          "name": "remote disconnect",
+          "id": "remote-disconnect",
+          "help": "Delete the saved remote server state (local only).",
+          "usage": "rdc remote disconnect [--json]"
+        },
         {
           "name": "android setup",
           "id": "android-setup",

pixi.lock

@@ -31,6 +31,7 @@ cmake = ">=3.26,<4"
 [target.linux-64.dependencies]
 cmake = ">=3.26,<4"
 ninja = ">=1.11,<2"
+libxml2 = ">=2.12,<3"
 
 [feature.vulkan.target.osx-64.dependencies]
 libvulkan-headers = ">=1.3"

pixi.toml

@@ -69,6 +69,7 @@
         "Remote", "remote",
         "Connect to a remote RenderDoc server for remote capture and replay.",
         ["serve", "remote connect", "remote list", "remote capture",
+         "remote setup", "remote status", "remote disconnect",
          "android setup", "android stop", "android capture"],
     ),
     ("Utilities", "utilities", None, [

scripts/gen-commands.py

@@ -295,6 +295,10 @@ def _safe_extractall(zf: zipfile.ZipFile, dest: Path) -> None:
             sys.stderr.write(f"ERROR: zip-slip attempt detected: {member.filename}\n")
             raise SystemExit(1)
         zf.extract(member, dest)
+        # Restore Unix execute bits that zipfile.extract() drops.
+        unix_mode = member.external_attr >> 16
+        if unix_mode and (unix_mode & 0o111):
+            target.chmod(target.stat().st_mode | (unix_mode & 0o111))
 
 
 def download_swig(build_dir: Path) -> None:
@@ -377,6 +381,13 @@ def configure_build(
     cmd += CMAKE_COMMON_FLAGS
     cmd.append(f"-DRENDERDOC_SWIG_PACKAGE={swig_dir}")
 
+    # Use base_prefix Python so cmake finds python3.XX-config (venv lacks it)
+    base_python = Path(sys.base_prefix) / "bin" / Path(sys.executable).name
+    if base_python.exists():
+        cmd.append(f"-DPython3_EXECUTABLE={base_python}")
+    else:
+        _log(f"WARNING: base Python not found at {base_python}, cmake will auto-detect")
+
     env = dict(os.environ)
     if plat == "linux":
         _log("stripping LTO flags")
@@ -749,8 +760,10 @@ def main(argv: list[str] | None = None) -> None:
     args = parser.parse_args(argv)
 
     plat = _platform()
-    install_dir = Path(args.install_dir) if args.install_dir else default_install_dir()
-    build_dir = Path(args.build_dir) if args.build_dir else install_dir.parent / "renderdoc-build"
+    install_dir = Path(args.install_dir).resolve() if args.install_dir else default_install_dir()
+    build_dir = (
+        Path(args.build_dir).resolve() if args.build_dir else install_dir.parent / "renderdoc-build"
+    )
 
     if _artifacts_present(install_dir, plat):
         _log(f"renderdoc already exists at {install_dir}/")

src/rdc/_build_renderdoc.py

@@ -0,0 +1,46 @@
+"""Progress callback factory for RenderDoc long-running operations."""
+
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Callable
+
+import click
+
+
+def make_progress_cb(label: str, min_interval: float = 1.0) -> Callable[[float], None]:
+    """Return a callback suitable for RenderDoc ProgressCallback.
+
+    Writes to stderr. On tty: '\\r{label}: {pct:.0%}' in place, '\\n' at
+    completion. Non-tty: one line per call, throttled to min_interval seconds.
+    First call (progress=0.0001) and final call (progress>=1.0) always emit.
+    Clamps NaN/negative/inf to [0, 1].
+    """
+    last_echo: list[float] = [0.0]
+    first_seen: list[bool] = [False]
+
+    def _cb(progress: float) -> None:
+        if math.isnan(progress) or progress < 0:
+            progress = 0.0
+        elif math.isinf(progress) or progress > 1.0:
+            progress = 1.0
+
+        is_first = not first_seen[0]
+        is_done = progress >= 1.0
+        first_seen[0] = True
+
+        stderr = click.get_text_stream("stderr")
+        on_tty = stderr.isatty()
+
+        if on_tty:
+            end = "\n" if is_done else "\r"
+            click.echo(f"{label}: {progress:.0%}", nl=False, err=True)
+            click.echo(end, nl=False, err=True)
+        else:
+            now = time.monotonic()
+            if is_first or is_done or (now - last_echo[0] >= min_interval):
+                click.echo(f"{label}: {progress:.0%}", err=True)
+                last_echo[0] = now
+
+    return _cb

src/rdc/_progress.py

@@ -20,7 +20,11 @@ Check setup: `rdc doctor`.
 
 Follow this session lifecycle for any capture analysis task:
 
-1. **Open** a capture: `rdc open path/to/capture.rdc`
+1. **Open** a capture:
+   - Local: `rdc open path/to/capture.rdc`
+   - Remote replay (Proxy): `rdc open capture.rdc --proxy host:port`
+   - Split thin-client: `rdc open --connect host:port --token TOKEN`
+   - Android device: `rdc open capture.rdc --android [--serial SERIAL]`
 2. **Inspect** metadata: `rdc info`, `rdc stats`, `rdc events`
 3. **Navigate** the VFS: `rdc ls /`, `rdc ls /textures`, `rdc cat /pipelines/0`
 4. **Analyze** specifics: `rdc shaders`, `rdc pipeline`, `rdc resources`, `rdc bindings`
@@ -196,6 +200,54 @@ rdc shader-restore EID            # revert single shader
 rdc shader-restore-all            # revert all modifications
 ```
 
+## Remote Capture Workflow
+
+rdc-cli wraps `renderdoccmd remoteserver` to support PC-to-PC remote captures.
+
+- `rdc serve [--port PORT] [--allow-ips CIDR] [--no-exec] [--daemon]` — launch remoteserver on the target machine
+- `rdc remote connect <host:port>` — save remote connection state
+- `rdc remote list` — enumerate capturable apps on the remote
+- `rdc remote capture <app> -o frame.rdc [--args ...] [--frame N] [--keep-remote]` — inject, capture, and transfer back. `--keep-remote` skips the transfer and prints the remote path; replay it with `rdc open <path> --proxy host:port`. (The CLI's own `next:` hint currently still references the deprecated `--remote` alias for `--proxy`.)
+- `rdc open frame.rdc --proxy host:port` — remote-backed replay (daemon local, GPU remote)
+
+`remote_state.py` persists the last connected host so subsequent `rdc remote list` can omit `--url`.
+
+## Split Mode (thin client)
+
+Split mode decouples CLI and daemon — run the daemon where the GPU is and connect from a machine that doesn't need the renderdoc module. Useful when the analyst's laptop is macOS/Windows and the GPU is on a Linux server.
+
+- Server side: `rdc open capture.rdc --listen [ADDR[:PORT]]`
+  - Prints these four labeled lines to stdout (among other status output): `host: ADDR`, `port: PORT`, `token: TOKEN`, `connect with: rdc open --connect ADDR:PORT --token TOKEN`
+- Client side: `rdc open --connect HOST:PORT --token TOKEN`
+
+SSH tunnel tip (use the port from `--listen`, or `rdc serve`'s default `39920`): `ssh -L 39920:localhost:39920 user@server`, then connect to `localhost:39920`.
+
+Every normal command (`rdc draws`, `rdc rt`, ...) works transparently in Split mode. Binary exports use `file_read` RPC with raw binary frames — no base64 overhead.
+
+## Android Workflow
+
+- Prerequisite: the RenderDoc APK must already be installed on the host via `rdc setup-renderdoc --android` (upstream) or `--android --arm` (ARM PS fork for Mali). `rdc android setup` does not push the APK itself.
+- `rdc android setup [--serial SERIAL]` — starts remoteserver on the device via RenderDoc's Device Protocol API (`StartRemoteServer`), sets adb forward, saves remote state.
+- `rdc android capture <activity> [--serial SERIAL] [--timeout N] [--port PORT] [-o out.rdc]` — GPU debug layers based capture (works around EMUI/Mali injection limitations).
+- `rdc android stop [--serial SERIAL]` — stops the remoteserver and cleans state.
+- For remote replay: `rdc open frame.rdc --android [--serial SERIAL]` — this is the only form that rewrites the saved `adb://SERIAL` to the forwarded `localhost:PORT`. Passing `--proxy adb://SERIAL` directly bypasses the rewrite and is known to crash the daemon (see `session.py:_resolve_android_url`).
+
+Hardware matrix: Adreno is the happy path; Mali may need the ARM Performance Studio fork (see `rdc setup-renderdoc --android --arm`).
+
+## Troubleshooting
+
+Always run `rdc doctor` first. It reports status for renderdoc module, renderdoccmd, adb, Android APK, and platform-specific toolchains. Only the missing-renderdoc-module case emits a dedicated build-hint block; other checks surface inline hints in the detail column, so read each failing line rather than relying on a uniform next-step list.
+
+Common failure categories (conceptual, not literal error strings — map from the text the tool actually emits):
+
+- **network / connect failed** — remote host unreachable, firewall, wrong port. Verify `rdc serve` is running on the target.
+- **version mismatch** — host and target RenderDoc versions differ. Re-run `rdc setup-renderdoc` or `rdc setup-renderdoc --android` to align.
+- **inject failed / ident=0** — injection blocked (Android EMUI, macOS SIP, Windows privilege). Run `rdc doctor` and check the platform-specific detail.
+- **OpenCapture unsupported** — local GPU can't replay the capture's API surface; switch to `--proxy` or `--android` remote replay.
+- **not loaded / no session** — forgot `rdc open`; use `rdc status` to inspect.
+
+For long operations (large capture transfers, remote replay init), the CLI has limited progress feedback — this is a known UX gap, not a hang. Wait up to the `--timeout` value before concluding failure.
+
 ## Command Reference
 
 For the complete list of all commands with their arguments, options, types, and defaults, see [references/commands-quick-ref.md](references/commands-quick-ref.md).

src/rdc/_skills/SKILL.md

@@ -622,6 +622,7 @@ Create local default session and start daemon skeleton.
 | `--listen` | Listen on [ADDR]:PORT. Use :0 for auto-port on all interfaces. | text |  |
 | `--connect` | Connect to an already-running external daemon. | text |  |
 | `--token` | Authentication token (required with --connect). | text |  |
+| `--timeout` | Daemon startup timeout in seconds. | float |  |
 
 ## `rdc pass`
 
@@ -759,6 +760,16 @@ Connect to a remote RenderDoc server.
 |------|------|------|---------|
 | `--json` | Output as JSON. | flag |  |
 
+## `rdc remote disconnect`
+
+Delete the saved remote server state (local only).
+
+**Options:**
+
+| Flag | Help | Type | Default |
+|------|------|------|---------|
+| `--json` | Output as JSON. | flag |  |
+
 ## `rdc remote list`
 
 List capturable applications on a remote host.
@@ -770,6 +781,33 @@ List capturable applications on a remote host.
 | `--url` | Override saved remote (host:port). | text |  |
 | `--json` | Output as JSON. | flag |  |
 
+## `rdc remote setup`
+
+Verify a remote server is reachable, handshake, and save state.
+
+**Arguments:**
+
+| Name | Type | Required |
+|------|------|----------|
+| `url` | text | yes |
+
+**Options:**
+
+| Flag | Help | Type | Default |
+|------|------|------|---------|
+| `--timeout` | TCP probe timeout in seconds. | float | 10.0 |
+| `--json` | Output as JSON. | flag |  |
+
+## `rdc remote status`
+
+Show the currently saved remote server state.
+
+**Options:**
+
+| Flag | Help | Type | Default |
+|------|------|------|---------|
+| `--json` | Output as JSON. | flag |  |
+
 ## `rdc resource`
 
 Show details of a specific resource.

src/rdc/_skills/references/commands-quick-ref.md

@@ -10,6 +10,8 @@
 from pathlib import Path
 from typing import Any
 
+import click
+
 from rdc import _platform
 from rdc.discover import find_renderdoc
 
@@ -220,7 +222,9 @@ def run_target_control_loop(
     else:
         tc.TriggerCapture(1)
 
-    deadline = time.monotonic() + timeout
+    start = time.monotonic()
+    deadline = start + timeout
+    last_echo = start
     while time.monotonic() < deadline:
         if not tc.Connected():
             return CaptureResult(error="target disconnected")
@@ -239,6 +243,10 @@ def run_target_control_loop(
             )
         if msg_type == 1:
             return CaptureResult(error="target disconnected")
+        now = time.monotonic()
+        if now - last_echo >= 5.0:
+            click.echo(f"waiting for capture... ({int(now - start):d}s)", err=True)
+            last_echo = now
         time.sleep(0.01)
 
     return CaptureResult(error="timeout waiting for capture")