Debug Adapter (DAP)

lash provides script debugging via two mechanisms: CLI debug flags for simple logging, and a full Debug Adapter Protocol (DAP) implementation for IDE integration.

CLI Debug Flags

`--log-verbose`

Logs script comments and command executions to stderr:

lash script.lash --log-verbose

Event	Format
Comment	`[debug] # comment text`
Pipeline	`[exec] program args \| program args`

Pipeline commands are logged after variable expansion.

`--log-variables`

Logs variable mutations to stderr. Accepts an optional comma-separated name filter:

lash script.lash --log-variables          # all variable changes
lash script.lash --log-variables x,y      # only x and y

Event	Format
Declaration	`[var] let name = value`
Assignment	`[var] name = value`
Drop	`[var] drop name`

Combining Flags

Flags may be combined. All debug output goes to stderr.

lash script.lash --log-verbose --log-variables x,count

Debug Adapter Protocol

A standalone lash-debug binary speaks the Debug Adapter Protocol over stdin/stdout, enabling VS Code (or any DAP client) to set breakpoints, step through code, and inspect variables.

Architecture: Lives in backend/debug/. Depends on backend/, lang/, runtime/. Does not import frontend/ or plugins/.

Debug Hook

An onBeforeStatement callback in ExecCallbacks. When set, called before each statement. Returns FlowSignal.none to continue or FlowSignal.break_ to pause.

Execution Model

MVP uses single-threaded with nested event loop: when a breakpoint hits, onBeforeStatement enters a nested DAP request loop until continue/step.

DAP Requests

Request	Description
`initialize`	Capabilities exchange.
`launch`	Start script. Params: `program`, `args`, `stopOnEntry`, `cwd`.
`disconnect`	Clean shutdown.
`configurationDone`	Start execution.
`setBreakpoints`	Set breakpoints for a source file.
`setExceptionBreakpoints`	Accept but ignore (no exception hierarchy).
`threads`	Single thread.
`stackTrace`	Current call stack when paused.
`scopes`	Scope chain for a stack frame.
`variables`	Variables in a scope.
`continue`	Resume execution.
`next`	Step over.
`stepIn`	Step into.
`stepOut`	Step out.

DAP Events

Event	When
`initialized`	After `initialize` response.
`stopped`	Breakpoint hit, step completed.
`terminated`	Script finished.
`output`	Script produced stdout/stderr.
`thread`	Thread started (once, `threadId: 1`).

Variable Inspection

When paused, the debugger exposes the scope chain for each stack frame. Structured values (lists, objects) get their own variable references for drill-down inspection.

VS Code Extension

A minimal extension at editors/vscode/ registers the “lash” debug type using DebugAdapterExecutable to spawn lash-debug directly.