Metadata-Version: 2.4
Name: retracesoftware-dap
Version: 0.2.14
Summary: Retrace DAP debug adapter and replay tooling
Author-email: Retrace Software <info@retracesoftware.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/retracesoftware/retrace-dap
Project-URL: Repository, https://github.com/retracesoftware/retrace-dap
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Go
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# retrace-dap

Go debug adapter for [Retrace](https://github.com/retracesoftware/retracesoftware)
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

```bash
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`.

```bash
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_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:

```text
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`:

```bash
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

```bash
# 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

```bash
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.

```bash
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:

```bash
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.
