retrace-dap

Go debug adapter for Retrace recordings. This project owns the DAP server that launches and controls Python replay subprocesses.

The Python runtime (retracesoftware) performs deterministic replay; retrace-dap translates editor/debugger requests into the Retrace control protocol and drives replay from the outside.

What this repo contains

• cmd/replay/ — CLI entrypoint (replay binary)
• replay/ — DAP proxy, control protocol client, recording index/extract, workspace generation, and replay launch plumbing

Build

go build -o replay ./cmd/replay

Python Wheel

This repository publishes the PyPI package retracesoftware-dap. The package contains a tiny Python wrapper plus a platform-specific Go replay binary built from cmd/replay.

python -m pip install --upgrade pip build setuptools wheel setuptools_scm
python -m build --wheel --outdir dist
python -m pip install dist/retracesoftware_dap-*.whl
python -c "from retrace_dap import binary_path; print(binary_path())"
retrace-dap --help

The installed Python package exposes:

• retrace_dap.binary_path() — returns the packaged replay/DAP binary path.
• retrace-dap — console script that execs the packaged binary.
• retrace-ai-driver — AI orchestration driver that talks to the replay DAP adapter and a hosted AI service.

RETRACE_REPLAY_BIN remains the local-development escape hatch. If it points at an executable replay binary, binary_path() returns that path instead of the packaged wheel binary.

Release To PyPI

PyPI Trusted Publishing must be configured for:

PyPI project: retracesoftware-dap
GitHub owner: retracesoftware
GitHub repository: retrace-dap
Workflow name: Build & Release
Workflow file: release.yml
Environment: leave blank unless the release workflow is changed to use one

The release workflow builds platform wheels for Linux and macOS, smoke-tests the installed wheel, uploads wheels to a GitHub Release, then publishes the same wheels to PyPI.

Manual release from main:

gh workflow run release.yml \
  -R retracesoftware/retrace-dap \
  --ref main \
  -f version=0.2.14

The workflow creates and pushes tag v0.2.14; tags can also trigger releases directly.

Common commands

# Process tree for a recording (VS Code sidebar)
replay --recording trace.retrace --index

# Extract pidfiles
replay --recording trace.retrace --extract

# Generate VS Code workspace
replay --recording trace.retrace --workspace

# DAP adapter (stdin/stdout)
replay --recording trace.retrace --dap [--pid N]

Test

go test ./...

Dev container

Open this repository in a Dev Container (VS Code / Cursor: Dev Containers: Reopen in Container). The container installs Go 1.25, builds bin/replay, and installs the retracesoftware Python package so integration tests can launch replay sessions.

go test ./...
go build -o bin/replay ./cmd/replay

Relationship to retracesoftware

This repo was split from retracesoftware/retracesoftware/go/. Python replay behavior lives in the main Retrace package (control_runtime.py, install/, proxy/, stream/). Changes that affect stop semantics, cursor navigation, or control-protocol payloads usually need coordinated updates in both repos.

The main retracesoftware package should depend on this package so:

python -m pip install retracesoftware

also installs retracesoftware-dap, and the retracesoftware.replay wrapper can discover the packaged replay/DAP binary through retrace_dap.binary_path().

Environment

Python replay discovery from tooling still uses RETRACE_REPLAY_BIN pointing at the built replay binary from this project.