webgpu-inspector-cli 0.1.0__tar.gz

webgpu_inspector_cli-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: webgpu-inspector-cli
+Version: 0.1.0
+Summary: CLI tool for WebGPU Inspector - debug WebGPU applications from the command line
+Author: Arvind Sekar
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: playwright>=1.40
+Requires-Dist: Pillow>=10.0
+Requires-Dist: prompt_toolkit>=3.0
+Dynamic: author
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

webgpu_inspector_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

webgpu_inspector_cli-0.1.0/setup.py

@@ -0,0 +1,24 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="webgpu-inspector-cli",
+    version="0.1.0",
+    description="CLI tool for WebGPU Inspector - debug WebGPU applications from the command line",
+    author="Arvind Sekar",
+    python_requires=">=3.10",
+    packages=find_packages(),
+    package_data={
+        "webgpu_inspector_cli": ["js/*.js", "skills/*.md"],
+    },
+    install_requires=[
+        "click>=8.0",
+        "playwright>=1.40",
+        "Pillow>=10.0",
+        "prompt_toolkit>=3.0",
+    ],
+    entry_points={
+        "console_scripts": [
+            "webgpu-inspector-cli=webgpu_inspector_cli.webgpu_inspector_cli:cli",
+        ],
+    },
+)

webgpu_inspector_cli-0.1.0/webgpu_inspector_cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI tool for WebGPU Inspector - debug WebGPU applications from the command line."""
+
+__version__ = "0.1.0"

webgpu_inspector_cli-0.1.0/webgpu_inspector_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m webgpu_inspector_cli"""
+
+from webgpu_inspector_cli.webgpu_inspector_cli import cli
+
+cli()

webgpu_inspector_cli-0.1.0/webgpu_inspector_cli/commands/browser.py

@@ -0,0 +1,106 @@
+"""Browser session management commands."""
+
+import json
+import click
+
+from webgpu_inspector_cli.core.bridge import get_bridge, require_bridge
+
+
+@click.group()
+def browser():
+    """Browser session management."""
+    pass
+
+
+@browser.command()
+@click.option("--url", required=True, help="URL to navigate to.")
+@click.option("--headless", is_flag=True, default=False, help="Run in headless mode.")
+@click.option("--gpu-backend", type=str, default=None, help="GPU backend (e.g., swiftshader).")
+@click.pass_context
+def launch(ctx, url, headless, gpu_backend):
+    """Launch browser, navigate to URL, and inject the WebGPU Inspector."""
+    bridge = get_bridge()
+    if bridge.is_connected:
+        click.echo("Browser session already active. Close it first with 'browser close'.")
+        return
+
+    bridge.launch(url, headless=headless, gpu_backend=gpu_backend)
+    info = bridge.get_browser_info()
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({
+            "status": "launched",
+            "url": info["url"],
+            "title": info["title"],
+            "gpu": info["gpu"],
+        }, indent=2))
+    else:
+        click.echo(f"Browser launched: {info['url']}")
+        click.echo(f"  Title: {info['title']}")
+        click.echo(f"  GPU: {info['gpu']}")
+        click.echo("Inspector injected and active.")
+
+
+@browser.command()
+@click.pass_context
+def close(ctx):
+    """Close the browser session."""
+    bridge = get_bridge()
+    if not bridge.is_connected:
+        click.echo("No active browser session.")
+        return
+    bridge.close()
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"status": "closed"}))
+    else:
+        click.echo("Browser session closed.")
+
+
+@browser.command()
+@click.option("--url", required=True, help="URL to navigate to.")
+@click.pass_context
+def navigate(ctx, url):
+    """Navigate to a new URL and re-inject the inspector."""
+    bridge = require_bridge()
+    bridge.navigate(url)
+    info = bridge.get_browser_info()
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({
+            "status": "navigated",
+            "url": info["url"],
+            "title": info["title"],
+        }, indent=2))
+    else:
+        click.echo(f"Navigated to: {info['url']}")
+        click.echo(f"  Title: {info['title']}")
+
+
+@browser.command()
+@click.option("--output", "-o", required=True, help="Output file path.")
+@click.option("--full-page", is_flag=True, default=False, help="Capture full scrollable page.")
+@click.pass_context
+def screenshot(ctx, output, full_page):
+    """Take a screenshot of the current page."""
+    bridge = require_bridge()
+    path = bridge.screenshot(output, full_page=full_page)
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"status": "saved", "path": path}))
+    else:
+        click.echo(f"Screenshot saved: {path}")
+
+
+@browser.command("status")
+@click.pass_context
+def browser_status(ctx):
+    """Show browser and GPU status information."""
+    bridge = require_bridge()
+    info = bridge.get_browser_info()
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps(info, indent=2))
+    else:
+        click.echo(f"URL: {info['url']}")
+        click.echo(f"Title: {info['title']}")
+        click.echo(f"GPU: {info['gpu']}")

webgpu_inspector_cli-0.1.0/webgpu_inspector_cli/commands/capture.py

@@ -0,0 +1,197 @@
+"""Frame capture and data inspection commands."""
+
+import base64
+import json
+import time
+import click
+
+from webgpu_inspector_cli.core.bridge import require_bridge
+
+
+@click.group()
+def capture():
+    """Frame capture and data inspection."""
+    pass
+
+
+@capture.command()
+@click.option("--timeout", type=float, default=30.0, help="Seconds to wait for capture.")
+@click.option("--poll-interval", type=float, default=0.5, help="Seconds between status polls.")
+@click.pass_context
+def frame(ctx, timeout, poll_interval):
+    """Capture the next frame's GPU commands."""
+    bridge = require_bridge()
+
+    # Trigger capture
+    bridge.query("requestCapture", {})
+
+    if not ctx.obj.get("json"):
+        click.echo("Capture requested, waiting for frame...")
+
+    # Poll for completion
+    start = time.time()
+    while time.time() - start < timeout:
+        status = bridge.query("getCaptureStatus")
+        if status == "complete":
+            break
+        time.sleep(poll_interval)
+    else:
+        msg = f"Capture timed out after {timeout}s"
+        if ctx.obj.get("json"):
+            click.echo(json.dumps({"status": "timeout", "error": msg}))
+        else:
+            click.echo(msg, err=True)
+        raise SystemExit(1)
+
+    results = bridge.query("getCapturedFrameResults")
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"status": "complete", "results": results}, indent=2))
+    else:
+        click.echo("Frame captured successfully.")
+        if results:
+            click.echo(f"  Frame: {results.get('frame', '?')}")
+            click.echo(f"  Commands: {results.get('count', '?')}")
+
+
+@capture.command()
+@click.option("--pass-index", type=int, default=None, help="Filter by render pass index.")
+@click.pass_context
+def commands(ctx, pass_index):
+    """List GPU commands from a captured frame."""
+    bridge = require_bridge()
+
+    status = bridge.query("getCaptureStatus")
+    if status != "complete":
+        click.echo("No captured frame. Run 'capture frame' first.", err=True)
+        raise SystemExit(1)
+
+    results = bridge.query("getCapturedFrameResults")
+    if not results:
+        click.echo("No capture data available.", err=True)
+        raise SystemExit(1)
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps(results, indent=2))
+    else:
+        batches = results.get("batches", [])
+        if not batches:
+            click.echo("No command batches in capture.")
+            return
+
+        for i, batch in enumerate(batches):
+            if pass_index is not None and i != pass_index:
+                continue
+            cmds = batch.get("commands", batch) if isinstance(batch, dict) else batch
+            click.echo(f"Batch {i}:")
+            if isinstance(cmds, list):
+                for cmd in cmds:
+                    if isinstance(cmd, dict):
+                        click.echo(f"  {cmd.get('method', cmd.get('name', str(cmd)))}")
+                    else:
+                        click.echo(f"  {cmd}")
+            else:
+                click.echo(f"  {cmds}")
+
+
+@capture.command()
+@click.option("--id", "tex_id", type=int, required=True, help="Texture object ID.")
+@click.option("--mip-level", type=int, default=0, help="Mip level to capture.")
+@click.option("--output", "-o", type=str, default=None, help="Save as PNG to path.")
+@click.option("--timeout", type=float, default=30.0, help="Seconds to wait for texture data.")
+@click.pass_context
+def texture(ctx, tex_id, mip_level, output, timeout):
+    """Read texture data from a live or captured texture."""
+    bridge = require_bridge()
+
+    # Request the texture data
+    bridge.query("requestTexture", tex_id, mip_level)
+
+    if not ctx.obj.get("json"):
+        click.echo(f"Requesting texture #{tex_id} mip {mip_level}...")
+
+    # Poll for data
+    start = time.time()
+    while time.time() - start < timeout:
+        data = bridge.query("getTextureData", tex_id)
+        if data and data.get("complete"):
+            break
+        time.sleep(0.5)
+    else:
+        msg = f"Texture data timed out after {timeout}s"
+        if ctx.obj.get("json"):
+            click.echo(json.dumps({"status": "timeout", "error": msg}))
+        else:
+            click.echo(msg, err=True)
+        raise SystemExit(1)
+
+    if output and data.get("data"):
+        # The data is base64 encoded - decode and save as raw or convert to PNG
+        try:
+            raw = base64.b64decode(data["data"].split(",")[-1] if "," in data["data"] else data["data"])
+            # Get texture info for dimensions
+            obj = bridge.query("getObject", tex_id)
+            desc = obj.get("descriptor", {}) if obj else {}
+            width = desc.get("size", {}).get("width", desc.get("size", [0])[0] if isinstance(desc.get("size"), list) else 0)
+            height = desc.get("size", {}).get("height", desc.get("size", [0, 0])[1] if isinstance(desc.get("size"), list) and len(desc.get("size", [])) > 1 else 0)
+
+            if output.endswith(".png") and width and height:
+                try:
+                    from PIL import Image
+                    img = Image.frombytes("RGBA", (width, height), raw)
+                    img.save(output)
+                except Exception:
+                    # Fallback: save raw bytes
+                    with open(output, "wb") as f:
+                        f.write(raw)
+            else:
+                with open(output, "wb") as f:
+                    f.write(raw)
+
+            if ctx.obj.get("json"):
+                click.echo(json.dumps({"status": "saved", "path": output, "size": len(raw)}))
+            else:
+                click.echo(f"Texture saved: {output} ({len(raw)} bytes)")
+        except Exception as e:
+            click.echo(f"Error saving texture: {e}", err=True)
+            raise SystemExit(1)
+    else:
+        if ctx.obj.get("json"):
+            click.echo(json.dumps({
+                "status": "complete",
+                "textureId": tex_id,
+                "mipLevel": mip_level,
+                "dataSize": len(data.get("data", "")) if data else 0,
+            }, indent=2))
+        else:
+            click.echo(f"Texture #{tex_id} data received ({data.get('totalChunks', 0)} chunks)")
+
+
+@capture.command()
+@click.option("--id", "buf_id", type=int, required=True, help="Buffer object ID.")
+@click.option("--offset", type=int, default=0, help="Byte offset into buffer.")
+@click.option("--size", "read_size", type=int, default=None, help="Number of bytes to read.")
+@click.option("--format", "fmt", type=click.Choice(["hex", "float32", "uint32", "raw"]),
+              default="hex", help="Display format.")
+@click.pass_context
+def buffer(ctx, buf_id, offset, read_size, fmt):
+    """Read buffer contents."""
+    bridge = require_bridge()
+    data = bridge.query("getBufferData", buf_id)
+
+    if not data:
+        click.echo(f"No buffer data for #{buf_id}. Capture a frame first.", err=True)
+        raise SystemExit(1)
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({
+            "bufferId": buf_id,
+            "offset": data.get("offset", 0),
+            "size": data.get("size", 0),
+            "data": data.get("data"),
+        }, indent=2))
+    else:
+        click.echo(f"Buffer #{buf_id}:")
+        click.echo(f"  Offset: {data.get('offset', 0)}")
+        click.echo(f"  Size: {data.get('size', 0)} bytes")
+        if data.get("data"):
+            click.echo(f"  Data (first 256 chars): {str(data['data'])[:256]}")

webgpu_inspector_cli-0.1.0/webgpu_inspector_cli/commands/errors.py

@@ -0,0 +1,82 @@
+"""Validation error tracking commands."""
+
+import json
+import time
+import click
+
+from webgpu_inspector_cli.core.bridge import require_bridge
+
+
+@click.group()
+def errors():
+    """Validation error tracking."""
+    pass
+
+
+@errors.command("list")
+@click.pass_context
+def list_errors(ctx):
+    """List all validation errors."""
+    bridge = require_bridge()
+    result = bridge.query("getErrors")
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"errors": result, "count": len(result)}, indent=2))
+    else:
+        if not result:
+            click.echo("No validation errors.")
+            return
+        for err in result:
+            click.echo(f"Error #{err['id']}:")
+            click.echo(f"  Message: {err['message']}")
+            if err.get("objectId"):
+                click.echo(f"  Object: #{err['objectId']}")
+            if err.get("stacktrace"):
+                click.echo("  Stacktrace:")
+                for line in err["stacktrace"].split("\n"):
+                    if line.strip():
+                        click.echo(f"    {line.strip()}")
+            click.echo()
+        click.echo(f"Total: {len(result)} errors")
+
+
+@errors.command()
+@click.option("--timeout", type=float, default=30.0, help="Seconds to watch for errors.")
+@click.option("--poll-interval", type=float, default=1.0, help="Seconds between polls.")
+@click.pass_context
+def watch(ctx, timeout, poll_interval):
+    """Watch for new validation errors in real-time."""
+    bridge = require_bridge()
+    seen_count = bridge.query("getErrorCount")
+    use_json = ctx.obj.get("json")
+
+    click.echo(f"Watching for errors (timeout: {timeout}s)..." if not use_json else "", nl=not use_json)
+
+    start = time.time()
+    while time.time() - start < timeout:
+        current_count = bridge.query("getErrorCount")
+        if current_count > seen_count:
+            all_errors = bridge.query("getErrors")
+            new_errors = all_errors[seen_count:]
+            for err in new_errors:
+                if use_json:
+                    click.echo(json.dumps(err))
+                else:
+                    click.echo(f"[{err['id']}] {err['message']}")
+            seen_count = current_count
+        time.sleep(poll_interval)
+
+    if not use_json:
+        click.echo(f"Watch ended. Total errors: {seen_count}")
+
+
+@errors.command()
+@click.pass_context
+def clear(ctx):
+    """Clear error history."""
+    bridge = require_bridge()
+    bridge.query("clearErrors")
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"status": "cleared"}))
+    else:
+        click.echo("Errors cleared.")

webgpu_inspector_cli-0.1.0/webgpu_inspector_cli/commands/objects.py

@@ -0,0 +1,129 @@
+"""GPU object inspection commands."""
+
+import json
+import click
+
+from webgpu_inspector_cli.core.bridge import require_bridge
+
+GPU_TYPES = [
+    "Adapter", "Device", "Buffer", "Texture", "TextureView", "Sampler",
+    "ShaderModule", "BindGroup", "BindGroupLayout", "PipelineLayout",
+    "RenderPipeline", "ComputePipeline", "RenderBundle",
+]
+
+
+def _format_bytes(n):
+    if n is None or n == 0:
+        return "0 B"
+    for unit in ("B", "KB", "MB", "GB"):
+        if abs(n) < 1024:
+            return f"{n:.1f} {unit}" if unit != "B" else f"{n} {unit}"
+        n /= 1024
+    return f"{n:.1f} TB"
+
+
+@click.group()
+def objects():
+    """GPU object inspection."""
+    pass
+
+
+@objects.command("list")
+@click.option("--type", "obj_type", type=click.Choice(GPU_TYPES, case_sensitive=False),
+              default=None, help="Filter by object type.")
+@click.pass_context
+def list_objects(ctx, obj_type):
+    """List all live GPU objects."""
+    bridge = require_bridge()
+    result = bridge.query("getObjects", obj_type)
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"objects": result, "count": len(result)}, indent=2))
+    else:
+        if not result:
+            click.echo("No GPU objects found.")
+            return
+        click.echo(f"{'ID':>6}  {'Type':<20}  {'Label':<30}  {'Size':>12}")
+        click.echo("-" * 72)
+        for obj in result:
+            size_str = ""
+            if obj.get("size"):
+                size_str = _format_bytes(obj["size"])
+            elif obj.get("gpuSize"):
+                size_str = _format_bytes(obj["gpuSize"])
+            label = obj.get("label") or ""
+            click.echo(f"{obj['id']:>6}  {obj['type']:<20}  {label:<30}  {size_str:>12}")
+        click.echo(f"\nTotal: {len(result)} objects")
+
+
+@objects.command()
+@click.option("--id", "obj_id", type=int, required=True, help="Object ID.")
+@click.pass_context
+def inspect(ctx, obj_id):
+    """Detailed view of a single GPU object."""
+    bridge = require_bridge()
+    obj = bridge.query("getObject", obj_id)
+
+    if obj is None:
+        click.echo(f"Object {obj_id} not found.", err=True)
+        raise SystemExit(1)
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps(obj, indent=2))
+    else:
+        click.echo(f"Object #{obj['id']} ({obj['type']})")
+        if obj.get("label"):
+            click.echo(f"  Label: {obj['label']}")
+        if obj.get("parent") is not None:
+            click.echo(f"  Parent: #{obj['parent']}")
+        if obj.get("pending"):
+            click.echo("  Status: pending (async)")
+        if obj.get("size"):
+            click.echo(f"  Size: {_format_bytes(obj['size'])}")
+        if obj.get("gpuSize"):
+            click.echo(f"  GPU Memory: {_format_bytes(obj['gpuSize'])}")
+        if obj.get("descriptor"):
+            click.echo("  Descriptor:")
+            desc_str = json.dumps(obj["descriptor"], indent=4)
+            for line in desc_str.split("\n"):
+                click.echo(f"    {line}")
+        if obj.get("stacktrace"):
+            click.echo("  Creation stacktrace:")
+            for line in obj["stacktrace"].split("\n"):
+                if line.strip():
+                    click.echo(f"    {line.strip()}")
+
+
+@objects.command()
+@click.option("--label", required=True, help="Label substring to search for.")
+@click.pass_context
+def search(ctx, label):
+    """Find objects by label."""
+    bridge = require_bridge()
+    all_objs = bridge.query("getObjects", None)
+    matched = [o for o in all_objs if o.get("label") and label.lower() in o["label"].lower()]
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"objects": matched, "count": len(matched)}, indent=2))
+    else:
+        if not matched:
+            click.echo(f"No objects matching '{label}'.")
+            return
+        for obj in matched:
+            click.echo(f"  #{obj['id']} {obj['type']}: {obj.get('label', '')}")
+        click.echo(f"\nFound: {len(matched)} objects")
+
+
+@objects.command()
+@click.pass_context
+def memory(ctx):
+    """Show GPU memory usage breakdown."""
+    bridge = require_bridge()
+    mem = bridge.query("getMemoryUsage")
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps(mem, indent=2))
+    else:
+        click.echo(f"Texture memory: {_format_bytes(mem['totalTextureMemory'])}")
+        click.echo(f"Buffer memory:  {_format_bytes(mem['totalBufferMemory'])}")
+        click.echo(f"Total:          {_format_bytes(mem['totalMemory'])}")

webgpu_inspector_cli-0.1.0/webgpu_inspector_cli/commands/shaders.py

@@ -0,0 +1,108 @@
+"""Shader module inspection commands."""
+
+import json
+import click
+
+from webgpu_inspector_cli.core.bridge import require_bridge
+from webgpu_inspector_cli.core.session import get_session
+
+
+@click.group()
+def shaders():
+    """Shader module inspection."""
+    pass
+
+
+@shaders.command("list")
+@click.pass_context
+def list_shaders(ctx):
+    """List all shader modules."""
+    bridge = require_bridge()
+    result = bridge.query("getObjects", "ShaderModule")
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"shaders": result, "count": len(result)}, indent=2))
+    else:
+        if not result:
+            click.echo("No shader modules found.")
+            return
+        click.echo(f"{'ID':>6}  {'Label':<30}  {'Size':>10}")
+        click.echo("-" * 50)
+        for obj in result:
+            label = obj.get("label") or ""
+            size = obj.get("size", 0)
+            click.echo(f"{obj['id']:>6}  {label:<30}  {size:>10} chars")
+        click.echo(f"\nTotal: {len(result)} shader modules")
+
+
+@shaders.command()
+@click.option("--id", "shader_id", type=int, required=True, help="Shader module ID.")
+@click.pass_context
+def view(ctx, shader_id):
+    """View WGSL source code of a shader module."""
+    bridge = require_bridge()
+    code = bridge.query("getShaderCode", shader_id)
+
+    if code is None:
+        click.echo(f"Shader #{shader_id} not found or has no code.", err=True)
+        raise SystemExit(1)
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"shaderId": shader_id, "code": code}, indent=2))
+    else:
+        click.echo(f"--- Shader #{shader_id} ---")
+        click.echo(code)
+        click.echo(f"--- End ({len(code)} chars) ---")
+
+
+@shaders.command("compile")
+@click.option("--id", "shader_id", type=int, required=True, help="Shader module ID.")
+@click.option("--file", "code_file", type=click.Path(exists=True), default=None,
+              help="Path to WGSL file.")
+@click.option("--code", "code_str", type=str, default=None,
+              help="WGSL code string (alternative to --file).")
+@click.pass_context
+def compile_shader(ctx, shader_id, code_file, code_str):
+    """Hot-replace shader code with new WGSL source."""
+    if not code_file and not code_str:
+        click.echo("Provide either --file or --code.", err=True)
+        raise SystemExit(1)
+
+    bridge = require_bridge()
+
+    # Save original for undo
+    session = get_session()
+    original = bridge.query("getShaderCode", shader_id)
+    if original:
+        session.push_shader_edit(shader_id, original)
+
+    if code_file:
+        with open(code_file) as f:
+            code = f.read()
+    else:
+        code = code_str
+
+    bridge.query("compileShader", shader_id, code)
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"status": "compiled", "shaderId": shader_id, "codeLength": len(code)}))
+    else:
+        click.echo(f"Shader #{shader_id} recompiled ({len(code)} chars)")
+
+
+@shaders.command("revert")
+@click.option("--id", "shader_id", type=int, required=True, help="Shader module ID.")
+@click.pass_context
+def revert_shader(ctx, shader_id):
+    """Revert shader to its original code."""
+    bridge = require_bridge()
+    bridge.query("revertShader", shader_id)
+
+    # Also clear session history for this shader
+    session = get_session()
+    session.clear_shader_edits(shader_id)
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps({"status": "reverted", "shaderId": shader_id}))
+    else:
+        click.echo(f"Shader #{shader_id} reverted to original.")