Module debug 

Opt-in diagnostic log for the adapter side, written to a file.

The driver has its own live log (TERMWRIGHT_DEBUG=1, stderr, see packages/driver/src/debug.ts). This is the other half: what the adapter inside the application decided, which is the half that goes missing when a conformance run reports skips and nobody can say why the app never attached.

Never stderr. The application under test owns the terminal; a stray line on stderr lands in the middle of a render and corrupts the very screen the driver is asserting on. So this log goes to a file the caller names, or nowhere.

Never fatal. Every failure here — an unwritable path, a full disk, a poisoned lock — leaves the application running and the log silently off.

Enable it with either variable:

TERMWRIGHT_DEBUG_FILE=/tmp/adapter.log     # preferred
TERMWRIGHT_DEBUG=/tmp/adapter.log          # path, not 1/true/all

The second form is deliberately restricted to values that are not the driver’s own switches: TERMWRIGHT_DEBUG=1 reaches the child process too, and if that turned this log on it would have to invent a destination for it.

Structs

DebugLog

Appends diagnostic lines to one file.

Enums

Category

Which part of the adapter a line is about, borrowed from the driver’s vocabulary so one reader greps both logs.

Constants

ENV_DEBUG

The driver’s switch, honoured here only when it carries a path.

ENV_DEBUG_FILE

Names the file this log is written to. Preferred over TERMWRIGHT_DEBUG because it cannot collide with the driver’s stderr switch.

Functions

debug_path

The file this process should log to, or None to stay silent.

describe_endpoint

How an endpoint reads in the log: its transport and its path.