rdc-cli 0.5.4__tar.gz → 0.5.6__tar.gz

{rdc_cli-0.5.4 → rdc_cli-0.5.6}/.github/workflows/aur.yml

@@ -22,7 +22,7 @@ jobs:
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: KSXGitHub/github-actions-deploy-aur@2ac5a4c1d7035885d46b10e3193393be8460b6f1 # v4.1.1
+      - uses: KSXGitHub/github-actions-deploy-aur@da03e160361ce01bf087e790b6ffd196d7dccff7 # v4.1.3
         with:
           pkgname: rdc-cli-git
           pkgbuild: aur/PKGBUILD
@@ -69,7 +69,7 @@ jobs:
           sed -i "s/^pkgver=.*/pkgver=${VERSION}/" aur/stable/PKGBUILD
           sed -i "s/'PLACEHOLDER'/'${SHA256}'/" aur/stable/PKGBUILD
 
-      - uses: KSXGitHub/github-actions-deploy-aur@2ac5a4c1d7035885d46b10e3193393be8460b6f1 # v4.1.1
+      - uses: KSXGitHub/github-actions-deploy-aur@da03e160361ce01bf087e790b6ffd196d7dccff7 # v4.1.3
         with:
           pkgname: rdc-cli
           pkgbuild: aur/stable/PKGBUILD

{rdc_cli-0.5.4 → rdc_cli-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rdc-cli
-Version: 0.5.4
+Version: 0.5.6
 Summary: CLI for RenderDoc .rdc captures
 Author: Jim
 License-Expression: MIT

{rdc_cli-0.5.4 → rdc_cli-0.5.6}/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] [--timeout FLOAT]"
+          "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] [--gpu INDEX|NAME|DEVICEID]"
         },
         {
           "name": "close",
@@ -201,6 +201,12 @@
           "help": "Export buffer raw data.",
           "usage": "rdc buffer <ID> [-o PATH] [--raw]"
         },
+        {
+          "name": "cbuffer",
+          "id": "cbuffer",
+          "help": "Decode a constant buffer to JSON or export its raw bytes.",
+          "usage": "rdc cbuffer [EID] [--stage CHOICE] [--set INTEGER] [--binding INTEGER] [--json] [--raw] [-o PATH]"
+        },
         {
           "name": "rt",
           "id": "rt",

rdc_cli-0.5.6/openspec/changes/2026-06-04-open-gpu-override/proposal.md

@@ -0,0 +1,83 @@
+# Add `--gpu` override to `rdc open`
+
+## Problem
+
+When a capture is replayed, the daemon picks the replay GPU automatically via
+`_match_capture_gpu()`: it matches the capture's recorded device name (Vulkan)
+or adapter description / DeviceId (D3D12), and **falls back to vendor priority
+(nVidia > AMD > Intel)** when nothing matches.
+
+On a multi-GPU host that fallback is `filtered[0]` after a stable sort, i.e. the
+first-enumerated device of the highest-priority vendor — frequently the
+integrated GPU. There is no way for the user to override it:
+
+- `rdc open` exposes no GPU selection flag.
+- The fallback cannot be steered toward a discrete GPU, a specific device, or a
+  GPU whose name does not match the capture's recorded name (common when
+  replaying a capture taken on different hardware).
+
+This complements the recent multi-GPU auto-matching work (#225) by giving the
+analyst an explicit escape hatch when auto-selection picks the wrong device.
+
+Note: an explicit GPU choice does not make a capture portable across
+incompatible hardware (RADV descriptor layouts differ per GPU generation); it
+only controls *which* available GPU replay is attempted on.
+
+## Solution
+
+Add an optional `--gpu INDEX|NAME|DEVICEID` flag to `rdc open` that forces the
+replay GPU, overriding auto-selection.
+
+Resolution order against `cap.GetAvailableGPUs()`:
+
+1. **0-based index** — `--gpu 1` selects the second enumerated GPU.
+2. **device ID** — decimal or `0x` hex (`--gpu 0x747e`), matched against
+   `GPUDevice.deviceID`.
+3. **name substring** — case-insensitive (`--gpu "7800 XT"`).
+
+If the preference matches no available GPU, a warning is logged listing the
+available GPUs and replay falls back to the existing auto-selection (non-fatal).
+
+### Plumbing
+
+The flag threads CLI → daemon, reusing the existing daemon-arg channel:
+
+- `commands/session.py`: `--gpu` option on `open_cmd`; ignored (with a warning)
+  for `--connect` (an external daemon is already running). Passed to
+  `open_session` / `listen_open_session`.
+- `services/session_service.py`: `start_daemon(..., gpu=...)` appends
+  `--gpu <value>` to the daemon argv; `open_session` / `listen_open_session`
+  forward it.
+- `daemon_server.py`: `--gpu` arg → `DaemonState.gpu_pref`; `_match_capture_gpu`
+  gains a `pref` parameter that short-circuits to the resolved GPU before
+  auto-matching. Applied at both the local and remote replay call sites.
+
+Out of scope: changing the default auto-selection (vendor priority is unchanged).
+
+## Spec Delta
+
+The existing scenario "Multi-GPU capture replay" under **Requirement: Replay
+lifecycle** in `openspec/specs/daemon/spec.md` (added by #226, amended by #230)
+is amended so the user `--gpu` preference takes precedence over auto-selection:
+
+```diff
+ #### Scenario: Multi-GPU capture replay
+ - **WHEN** the capture was taken on a multi-GPU system
+ - **AND** multiple GPUs are available for replay
+-- **THEN** the daemon walks structured-data chunks whose name contains any of
++- **THEN** if the user passed `--gpu` (a 0-based index, a PCI device ID in
++  decimal or `0x` hex, or a case-insensitive name substring) that resolves to an
++  available GPU, that GPU is selected and structured-data inspection is skipped
++- **AND** otherwise the daemon walks structured-data chunks whose name contains any of
+   "Driver Initialisation Parameters", "DriverInit", "EnumAdapters", or
+   "CreateDXGIFactory"
+ ...
+ - **AND** if no structured-data match exists, Software/WARP adapters are excluded
+   and the highest-ranked discrete GPU is preferred (nVidia > AMD > Intel)
++- **AND** an unresolved `--gpu` preference logs a warning and falls back to the
++  auto-selection above
+ - **AND** a single available GPU is always returned directly without inspection
+```
+
+This delta has been applied to `openspec/specs/daemon/spec.md` as part of this
+change.

rdc_cli-0.5.6/openspec/changes/2026-06-04-open-gpu-override/tasks.md

@@ -0,0 +1,14 @@
+# Tasks: Add `--gpu` override to `rdc open`
+
+- [x] `daemon_server.py`: add `_resolve_gpu_pref()` (index / deviceID / name substring)
+- [x] `daemon_server.py`: add `pref` param to `_match_capture_gpu()`; short-circuit before auto-match, warn + fall back when no match
+- [x] `daemon_server.py`: `--gpu` arg, `DaemonState.gpu_pref`, pass `state.gpu_pref` at local + remote call sites
+- [x] `services/session_service.py`: `start_daemon(gpu=...)` appends `--gpu`; forward through `open_session` / `listen_open_session`
+- [x] `commands/session.py`: `--gpu` option on `open_cmd`; warn-and-ignore with `--connect`; pass to open paths
+- [x] `openspec/specs/daemon/spec.md`: apply Spec Delta to the "Multi-GPU capture replay" scenario (user `--gpu` precedence + unresolved fallback)
+- [x] Unit tests: `_resolve_gpu_pref` forms; `_match_capture_gpu` pref precedence + no-match fallback warning; `start_daemon` argv; CLI passthrough + `--connect` warning
+- [x] Update existing fakes broken by new signature/attr (`test_remote_replay_passes_sd` spy, sigterm-handler `mock_args`)
+- [x] `pixi run check` green (lint + typecheck + tests)
+- [ ] Fresh review of the diff
+- [ ] Open PR targeting `master`
+- [ ] Archive this OpenSpec folder after merge

rdc_cli-0.5.6/openspec/changes/2026-06-04-open-gpu-override/test-plan.md

@@ -0,0 +1,36 @@
+# Test Plan: `--gpu` override for `rdc open`
+
+## Unit (mocked — no GPU required)
+
+`tests/unit/test_daemon_server_unit.py` (`TestMatchCaptureGpu`):
+
+1. **Index** — `pref="1"` returns the second GPU.
+2. **Name substring** — `pref="7800 xt"` matches case-insensitively.
+3. **Device ID** — `pref="29822"` (decimal) and `pref="0x747e"` (hex) both match
+   `deviceID==29822`.
+4. **Precedence** — with a Vulkan `deviceName` chunk that would auto-match GPU B,
+   `pref="AMD"` still selects GPU A.
+5. **No match** — `pref="Matrox"` logs a `--gpu` warning and falls back to the
+   vendor-priority auto-selection.
+6. **`_resolve_gpu_pref`** — index / name / hex resolve; unknown and empty → None.
+
+`tests/unit/test_session_service.py`:
+
+7. `start_daemon(gpu="1")` puts `--gpu 1` in the daemon argv; default omits `--gpu`.
+
+`tests/unit/test_session_commands.py`:
+
+8. `rdc open CAP --gpu 1` forwards `gpu="1"` to `start_daemon`.
+9. `rdc open --connect host:port --token T --gpu 1` prints
+   `warning: --gpu is ignored with --connect`.
+
+Run: `pixi run test` (unit only; no GPU/e2e). Full gate: `pixi run check`.
+
+## Manual (requires a multi-GPU host + renderdoc)
+
+- `rdc open frame.rdc --gpu <discrete-name>` then `rdc status` / a replay query;
+  daemon log shows `replay GPU (user --gpu=...)`.
+- `rdc open frame.rdc --gpu nonsense` logs the no-match warning and still opens
+  via auto-selection.
+
+(Not run in CI: needs real hardware; out of scope for the unit suite.)

rdc_cli-0.5.6/openspec/changes/archive/2026-05-15-fix-225-d3d12-multi-gpu/proposal.md

@@ -0,0 +1,90 @@
+# Fix #225: D3D12 Multi-GPU Capture Replay
+
+## Summary
+
+Fix `_match_capture_gpu()` incorrectly returning the integrated GPU on multi-GPU
+systems when replaying D3D12 captures, causing an `E_INVALIDARG` heap failure on
+devices with insufficient VRAM.
+
+## Motivation
+
+`_match_capture_gpu()` only matches GPUs via the Vulkan `vkEnumeratePhysicalDevices`
+structured-data chunk. For D3D12 captures that chunk is absent, so the function
+falls through to `return gpus[0]`. On reporter's machine the GPU enumeration order
+was: AMD Radeon Graphics iGPU 2 GB, NVIDIA RTX 4500 Ada 24 GB, WARP. The iGPU was
+selected, D3D12 heap creation required more VRAM than available, and renderdoc
+returned `E_INVALIDARG`.
+
+The same fall-through also affects the remote-replay call site at line 368, which
+additionally never passes `sd` to the helper, so even the Vulkan path was silently
+bypassed on every remote replay.
+
+## Design
+
+### 1. D3D12 structured-data matching
+
+Walk the capture's structured data looking for chunks whose name contains
+`DriverInit`, `EnumAdapters`, or `CreateDXGIFactory`. Inside each matching chunk
+descend into child objects to find a child named `AdapterDesc` and within it a
+string field named `Description` or `DeviceName`. Perform a case-insensitive
+substring match of that string against `gpu.name`. Return the first GPU that
+matches.
+
+### 2. Vendor-preference fallback
+
+When no structured-data chunk produces a match, filter out Software/WARP adapters
+(`renderdoc.GPUVendor.Software`), then rank remaining GPUs by vendor:
+nVidia > AMD > Intel. Return the highest-ranked GPU, or the first non-Software GPU
+if no ranked match exists.
+
+### 3. Single-GPU short-circuit
+
+If `len(gpus) == 1` return that GPU immediately without inspecting structured data.
+
+### 4. Signature and call-site corrections
+
+Pass `rd` (the renderdoc module) into `_match_capture_gpu()` so that
+`GPUVendor` enum values are accessible without a module-level import assumption.
+Update the remote-replay call site (line 368) to pass `sd` in addition to `rd`,
+matching the local-replay call site.
+
+## Spec Delta
+
+A new scenario "Multi-GPU capture replay" should be appended under the existing
+**Requirement: Replay lifecycle** section in `openspec/specs/daemon/spec.md`:
+
+```
+#### Scenario: Multi-GPU capture replay
+- WHEN the capture was taken on a multi-GPU system
+- AND multiple GPUs are available for replay
+- THEN the daemon selects the GPU whose name matches structured-data adapter
+  metadata extracted from the capture
+- AND if no structured-data match exists, Software/WARP adapters are excluded
+  and the highest-ranked discrete GPU is preferred (nVidia > AMD > Intel)
+- AND a single available GPU is always returned directly without inspection
+```
+
+This proposal targets that scenario. The spec file itself is not modified here;
+the delta is applied in the implementing task (see `tasks.md`).
+
+## Files Changed
+
+- `src/rdc/daemon_server.py` — `_match_capture_gpu` body; call sites at lines 223
+  and 368
+- `tests/unit/test_daemon_server_unit.py` — new unit tests (see `test-plan.md`)
+
+## Risks
+
+- The exact D3D12 chunk name (`DriverInit` / `EnumAdapters` / `CreateDXGIFactory`)
+  has not been confirmed against a real renderdoc 1.42 D3D12 capture. The matching
+  uses substring search rather than exact equality as a defensive measure; a real
+  capture should be obtained from the issue reporter for verification before merge.
+- `renderdoc.GPUVendor.nVidia` uses a lower-case `n`. Attribute access should use
+  `getattr(rd.GPUVendor, "nVidia", 4)` with an integer fallback to avoid
+  `AttributeError` on builds where the spelling differs.
+- The Vulkan low-VRAM edge case (structured-data match returns a GPU that has less
+  VRAM than required) is not addressed here; the fix only corrects selection
+  behaviour and does not validate VRAM sufficiency.
+- Integration testing on Linux is not possible without Windows D3D12 multi-GPU
+  hardware. The unit tests use mocks. Full verification must be performed by the
+  issue reporter on their machine.

rdc_cli-0.5.6/openspec/changes/archive/2026-05-15-fix-225-d3d12-multi-gpu/tasks.md

@@ -0,0 +1,10 @@
+# Fix #225: Tasks
+
+- [ ] `daemon_server.py`: add D3D12 structured-data matching to `_match_capture_gpu` (walk `DriverInit`/`EnumAdapters`/`CreateDXGIFactory` chunks, match `AdapterDesc.Description`/`DeviceName` against `gpu.name`)
+- [ ] `daemon_server.py`: add vendor-preference fallback (drop Software/WARP, prefer nVidia > AMD > Intel via `getattr` on `rd.GPUVendor`)
+- [ ] `daemon_server.py`: add single-GPU short-circuit at top of `_match_capture_gpu`
+- [ ] `daemon_server.py`: add `rd` parameter to `_match_capture_gpu` signature; update both call sites (lines 223 and 368)
+- [ ] `daemon_server.py`: pass `sd` at the remote-replay call site (line 368)
+- [ ] `openspec/specs/daemon/spec.md`: append "Multi-GPU capture replay" scenario under **Requirement: Replay lifecycle**
+- [ ] `tests/unit/test_daemon_server_unit.py`: implement all 8 unit test cases from `test-plan.md`
+- [ ] `pixi run lint && pixi run test` passes

rdc_cli-0.5.6/openspec/changes/archive/2026-05-15-fix-225-d3d12-multi-gpu/test-plan.md

@@ -0,0 +1,33 @@
+# Fix #225: Test Plan
+
+## Unit tests — `tests/unit/test_daemon_server_unit.py`
+
+- [ ] `test_single_gpu_returns_it` — given `len(gpus) == 1` with any `sd` value
+  (including `None`), assert that GPU is returned without inspecting structured data
+
+- [ ] `test_vulkan_match_by_devicename` — regression guard for the existing Vulkan
+  path; mock structured data containing a `vkEnumeratePhysicalDevices` chunk with a
+  `DeviceName` field matching one of two GPU names; assert the matching GPU is
+  returned
+
+- [ ] `test_d3d12_match_via_driverinit_adapterdesc` — mock structured data with a
+  `DriverInit` chunk whose `AdapterDesc` child has a `Description` field matching
+  one GPU among three (iGPU, discrete, WARP); assert the discrete GPU is returned
+
+- [ ] `test_d3d12_fallback_skips_warp_prefers_nvidia` — no structured-data match;
+  three GPUs with vendors Software (WARP), AMD (iGPU), nVidia (discrete); assert
+  the nVidia GPU is returned
+
+- [ ] `test_d3d12_fallback_amd_over_intel` — no structured-data match; vendors
+  [Intel, AMD, Software]; assert the AMD GPU is returned
+
+- [ ] `test_no_structured_data_uses_fallback_not_gpu0` — `sd=None`; two GPUs in
+  order [AMD iGPU, NVIDIA discrete]; assert NVIDIA is returned, reproducing the
+  literal issue #225 scenario (iGPU was previously returned as `gpus[0]`)
+
+- [ ] `test_empty_gpu_list_returns_none` — `gpus=[]`; assert return value is `None`
+  (no exception raised)
+
+- [ ] `test_remote_replay_passes_sd` — mock the `_match_capture_gpu` call site at
+  the remote-replay path (line 368); assert it is invoked with a non-`None` `sd`
+  argument when structured data is available

rdc_cli-0.5.6/openspec/changes/archive/2026-05-15-issue-224-cbuffer-export/proposal.md

@@ -0,0 +1,95 @@
+# OpenSpec: issue-224-cbuffer-export
+
+## Summary
+
+Expose `rdc cbuffer` as a first-class CLI command with decoded JSON output and optional
+raw binary export (`--raw`).
+
+## Context and Motivation
+
+OpenSpec phase2-buffer-decode (archived 2026-02-19) originally planned three CLI commands:
+`rdc cbuffer`, `rdc vbuffer`, and `rdc ibuffer`. The daemon handler `cbuffer_decode` and its
+VFS route shipped in that phase. The CLI half — `rdc cbuffer` — was never implemented.
+This change completes that unshipped work.
+
+GitHub issue #224 (part 2) tracks the gap. Users who rely on `rdc buffer --raw` for raw bytes
+have no ergonomic path to decoded constant-buffer variables without constructing VFS paths
+manually.
+
+**Scope note:** The archived phase2-buffer-decode plan envisioned `rdc cbuffer` as a thin VFS
+`cat` wrapper; this change implements a richer direct command with decoded JSON output, a new
+`cbuffer_raw` handler, and a new VFS `leaf_bin` route — reviewers should not expect a pure VFS
+wrapper.
+
+## Design
+
+### New command: `rdc cbuffer`
+
+```
+rdc cbuffer [EID] --stage [vs|hs|ds|gs|ps|cs] --set N --binding N [--json] [--raw -o file.bin]
+```
+
+- `EID`: optional; resolved via `complete_eid` if omitted (matches existing `rdc buffer` pattern).
+- `--stage`: default `ps`.
+- `--set`: default `0`.
+- `--binding`: default `0`.
+- `--json`: emit decoded variables as JSON (default output mode).
+- `--raw -o file.bin`: export the raw constant-buffer bytes to a file.
+
+### Decoded path
+
+Calls the existing `cbuffer_decode` daemon handler unchanged.  Returns
+`{"eid", "set", "binding", "variables": [{name, type, value}, ...]}` and writes it via
+`write_json`.  No daemon changes required for this path.
+
+### Raw path
+
+Adds a new `cbuffer_raw` daemon handler in `handlers/buffer.py`.  The handler repeats the
+reflection lookup (`fixedBindSetOrSpace` / `fixedBindNumber`), obtains
+`GetConstantBlock(...).descriptor`, calls `controller.GetBufferData(resource, byteOffset,
+byteSize)`, writes the bytes to `state.temp_dir/cbuffer_<eid>_<set>_<binding>.bin`, and
+returns `{"path", "size"}`.
+
+The handler is exposed as a VFS `leaf_bin` route at
+`/draws/<eid>/cbuffer/<set>/<binding>/data` in `vfs/router.py`, mirroring the way `buf_raw`
+is wired at `/buffers/<id>/data`.  The CLI calls
+`_export_vfs_path(f"/draws/{eid}/cbuffer/{set}/{binding}/data", output, raw)` (from
+`commands/export.py`), which follows the same `vfs_ls` + `resolve_path` → `_deliver_binary`
+flow used by `rdc buffer --raw`.  `_deliver_binary` (vfs.py:216) is the final delivery
+step — it calls `call(match.handler, match.args)` through the VFS resolve layer; it is NOT
+a standalone "call handler, get path, write bytes" helper invoked directly.
+
+The `hasattr(pipe_state, "GetConstantBlock")` guard present in `cbuffer_decode` is preserved
+in `cbuffer_raw` for RenderDoc version drift safety.
+
+### New source file
+
+`src/rdc/commands/cbuffer.py` — registered in `src/rdc/cli.py` adjacent to `buffer_cmd`
+(~line 138).
+
+## Risks
+
+### Non-buffer-backed constant buffers
+
+`ConstantBlock.bufferBacked == False` for push constants (Vulkan) and D3D12 root constants.
+These have no backing buffer resource; `GetBufferData` would operate on a null resource.
+
+Defined behavior: `--raw` MUST return a JSON-RPC error with a descriptive message
+(e.g. `"cbuffer is not buffer-backed (push constant or root constant)"`) rather than crash
+or silently return zero bytes.  Decoded `--json` output is unaffected and continues to work
+via `GetCBufferVariableContents`.
+
+### D3D12 root constants / register spaces
+
+The `fixedBindSetOrSpace` / `fixedBindNumber` mapping for D3D12 root constants cannot be
+verified on this Linux development machine.  The Vulkan (vkcube) integration test exercises
+the buffer-backed path only.  Behavior on D3D12 root-constant captures is verified by
+reporter @Misaka-Mikoto-Tech on real D3D12 hardware after the PR ships.
+
+### `_extract_value` type coverage (optional improvement)
+
+The existing `_extract_value` helper (`buffer.py:163-173`) handles only `f32v` members;
+integer and unsigned-integer shader variables degrade silently.  `_flatten_shader_var`
+in `handlers/_helpers.py` already handles `u32v`/`s32v` and is used by `shader_constants`.
+Switching `cbuffer_decode` to use `_flatten_shader_var` is an optional polish step; it does
+not block this change but is tracked as a separate optional task.

rdc_cli-0.5.6/openspec/changes/archive/2026-05-15-issue-224-cbuffer-export/specs/daemon/spec.md

@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: Constant Buffer Raw Export
+The daemon SHALL expose a handler to export raw constant-buffer bytes to a temporary file.
+
+#### Scenario: Export buffer-backed constant buffer
+- **WHEN** client requests `cbuffer_raw` with `eid`, `set`, `binding`, and `stage`
+- **THEN** daemon resolves the constant block via `fixedBindSetOrSpace` / `fixedBindNumber`,
+  calls `GetBufferData(resource, byteOffset, byteSize)`, writes bytes to
+  `state.temp_dir/cbuffer_<eid>_<set>_<binding>.bin`, and returns `{"path", "size"}`.
+- **IF** `state.adapter` is None, return error -32002.
+- **IF** `eid` is not a valid draw event, return error.
+
+#### Scenario: Reject non-buffer-backed constant buffer
+- **WHEN** client requests `cbuffer_raw` and `ConstantBlock.bufferBacked == False`
+- **THEN** daemon returns a JSON-RPC error with a message indicating the cbuffer is not
+  buffer-backed (push constant or root constant) and does not write any file.
+
+#### Scenario: RenderDoc version guard
+- **WHEN** `GetConstantBlock` is not present on the pipeline state object
+- **THEN** daemon returns an error indicating the API is unavailable on this RenderDoc version.
+
+### Requirement: Constant Buffer CLI Command
+The CLI SHALL expose `rdc cbuffer` as a first-class command for decoded and raw export.
+
+#### Scenario: Decoded JSON output
+- **WHEN** user runs `rdc cbuffer [EID] --stage STAGE --set N --binding N`
+- **THEN** CLI calls `cbuffer_decode` handler and writes the JSON response to stdout.
+- **IF** `EID` is omitted, CLI resolves it via `complete_eid`.
+
+#### Scenario: Raw binary export
+- **WHEN** user runs `rdc cbuffer [EID] --raw -o FILE`
+- **THEN** CLI resolves the VFS path `/draws/<eid>/cbuffer/<set>/<binding>/data` via
+  `_export_vfs_path` (vfs_ls + resolve_path → _deliver_binary), exactly mirroring how
+  `rdc buffer --raw` uses `/buffers/<id>/data`, and writes bytes to `FILE`.
+- **IF** `-o` is not specified alongside `--raw`, CLI exits with a usage error.
+
+#### Scenario: No active session
+- **WHEN** user runs `rdc cbuffer` and no daemon session is active
+- **THEN** CLI exits with code 1 and prints an error message to stderr.

rdc_cli-0.5.6/openspec/changes/archive/2026-05-15-issue-224-cbuffer-export/tasks.md

@@ -0,0 +1,47 @@
+# Tasks: issue-224-cbuffer-export
+
+## Phase A: Mock API additions
+
+- [ ] Add `GetBufferData` stub to `mock_renderdoc.py` (anchor: ~line 1356 `GetConstantBlock`).
+  The happy-path test must give the mock `Descriptor` (returned via
+  `GetConstantBlock(...).descriptor`) a non-null `resource`, `byteOffset`, and `byteSize` —
+  these are the fields the raw-path handler keys off (`buffer.py:143-147`).
+- [ ] Add `bufferBacked=False` variant to the mock `ConstantBlock` for the push-constant
+  clean-error test; this stubs the reflection-level field used to reject non-buffer-backed
+  cbuffers before `GetBufferData` is called.
+
+## Phase B: `cbuffer_raw` daemon handler (tests first)
+
+- [ ] Extend `tests/unit/test_buffer_decode.py` with `cbuffer_raw` cases (happy path,
+  `bufferBacked=False` error, no-adapter guard)
+- [ ] Implement `cbuffer_raw` handler in `src/rdc/handlers/buffer.py` (~line 370,
+  adjacent to `HANDLERS` dict)
+- [ ] Register `cbuffer_raw` in `HANDLERS`
+- [ ] Add VFS `leaf_bin` route for `/draws/<eid>/cbuffer/<set>/<binding>/data` →
+  `cbuffer_raw` in `src/rdc/vfs/router.py`, mirroring
+  `/buffers/<id>/data` → `buf_raw` (router.py:184)
+- [ ] Verify handler unit tests pass
+
+## Phase C: `rdc cbuffer` CLI command (tests first)
+
+- [ ] Write `tests/unit/test_cbuffer_commands.py` (JSON mode, `--raw -o`, no-session error,
+  `complete_eid` fallback, `--raw` without `-o` usage error)
+- [ ] Implement `src/rdc/commands/cbuffer.py`; raw path calls
+  `_export_vfs_path(f"/draws/{eid}/cbuffer/{set}/{binding}/data", output, raw)` from
+  `commands/export.py` — no direct handler dispatch
+- [ ] Register `cbuffer_cmd` in `src/rdc/cli.py` (~line 138, adjacent to `buffer_cmd`)
+- [ ] Verify CLI unit tests pass
+
+## Phase D: Integration + verification
+
+- [ ] Extend `tests/integration/test_daemon_handlers_real.py` with `@pytest.mark.gpu`
+  tests for `cbuffer_raw` (Vulkan vkcube capture)
+- [ ] Run `pixi run lint && pixi run test` — all pass, coverage ≥ 80% for new paths
+- [ ] Run GPU integration tests against real capture — pass
+- [ ] Code review
+
+## Phase E: Optional polish (non-blocking)
+
+- [ ] Switch `cbuffer_decode` to use `_flatten_shader_var` from `handlers/_helpers.py`
+  instead of `_extract_value` to fix int/uint member degradation
+- [ ] Extend `test_buffer_decode.py` with int/uint value assertions

rdc_cli-0.5.6/openspec/changes/archive/2026-05-15-issue-224-cbuffer-export/test-plan.md

@@ -0,0 +1,78 @@
+# Test Plan: issue-224-cbuffer-export
+
+## Scope
+
+### In scope
+- New daemon handler `cbuffer_raw` (unit + integration)
+- New CLI command `rdc cbuffer` (unit: JSON mode, raw mode, error paths)
+- `bufferBacked == False` error path for `cbuffer_raw`
+- Optional: `_extract_value` int/uint coverage in `test_buffer_decode.py`
+
+### Out of scope
+- Existing `cbuffer_decode` handler correctness (covered by prior test suite)
+- `rdc vbuffer` / `rdc ibuffer` (separate issue)
+- D3D12 root-constant register-space mapping (cannot run on this Linux box; deferred to reporter verification)
+
+## Test Matrix
+
+| Layer | Test Type | File |
+|-------|-----------|------|
+| Unit | `cbuffer_raw` handler (mock) | `tests/unit/test_buffer_decode.py` (extend) |
+| Unit | `rdc cbuffer` CLI command | `tests/unit/test_cbuffer_commands.py` (new) |
+| Integration | real capture decoded + raw | `tests/integration/test_daemon_handlers_real.py` (extend) |
+
+## Cases
+
+### `cbuffer_raw` handler (extend `test_buffer_decode.py`)
+
+- **Happy path**: mock `GetConstantBlock` returns a buffer-backed descriptor (`bufferBacked=True`,
+  known `byteOffset`/`byteSize`); mock `GetBufferData` returns 16 known bytes.
+  Assert response contains `{"path": "...", "size": 16}` and the temp file exists with the
+  expected bytes.
+- **bufferBacked=False**: mock `GetConstantBlock` returns `bufferBacked=False`.
+  Assert the handler returns a JSON-RPC error (code -32602 or equivalent) with a message
+  containing `"not buffer-backed"`.  Assert no temp file is created.
+- **No adapter**: `state.adapter is None` → assert error -32002 (standard no-adapter guard).
+- **Missing eid**: invalid `eid` → assert error from `SetFrameEvent`.
+
+Mock anchor: `mock_renderdoc.py` `GetConstantBlock` (~line 1356), `GetBufferData`.
+
+### `rdc cbuffer` CLI command (new `test_cbuffer_commands.py`)
+
+Mirror structure of `tests/unit/test_mesh_commands.py` (monkeypatch `rdc.commands.cbuffer.call`).
+
+- **JSON mode (default)**: monkeypatch `call("cbuffer_decode", ...)` returns
+  `{"eid": 10, "set": 0, "binding": 0, "variables": [{"name": "mvp", "type": "mat4", "value": [...]}]}`.
+  Invoke `rdc cbuffer 10 --stage ps --set 0 --binding 0`.
+  Assert exit code 0, stdout is valid JSON matching the payload.
+- **`--json` explicit flag**: same as above with `--json` flag; assert identical output.
+- **`--raw -o file.bin`**: monkeypatch `call("cbuffer_raw", ...)` returns `{"path": "/tmp/cbuffer_10_0_0.bin", "size": 16}`;
+  monkeypatch binary delivery (`_deliver_binary` / `fetch_remote_file`).
+  Assert exit code 0, output file contains the expected bytes.
+- **No session**: `call` raises connection error → assert exit code 1, message on stderr.
+- **`--raw` without `-o`**: assert exit code non-zero with usage error on stderr.
+- **EID omitted**: monkeypatch `complete_eid` returns `42`; assert the handler is called with `eid=42`.
+
+### Integration (`test_daemon_handlers_real.py`, `@pytest.mark.gpu`)
+
+Extend analogous to `test_cbuffer_decode_returns_data` (~line 1965), using a vkcube/Vulkan
+capture with a known draw EID that has a buffer-backed cbuffer.
+
+- **`cbuffer_raw` returns file**: call `cbuffer_raw` with valid `eid`/`set`/`binding`.
+  Assert response contains `path` and `size > 0`; assert temp file exists and `size` matches
+  `os.path.getsize(path)`.
+- **`cbuffer_decode` + `cbuffer_raw` size agreement**: decoded `variables` total byte footprint
+  is consistent with the raw `size`.
+
+## Assertions (all tests)
+
+- Exit code 0 on success, non-zero on error.
+- JSON output: valid JSON, `variables` array present for decoded mode.
+- Raw output: file written at `-o` path, byte count matches `size` from handler.
+- Error messages go to stderr; stdout is empty on error.
+- `bufferBacked=False` produces an error message containing `"not buffer-backed"` (case-insensitive).
+
+## Coverage Gate
+
+CI enforces ≥ 80% line coverage for `src/rdc/commands/cbuffer.py` and the new
+`cbuffer_raw` code path in `src/rdc/handlers/buffer.py`.