Debugger (DAP)

bin/penelope-dap speaks the standard Debug Adapter Protocol over stdio. Any DAP-compatible editor (VSCode, Neovim's nvim-dap) can drive a Penelope debugging session.

What works

• Launch — open a .pen file and start execution
• Source-line breakpoints — mapped to opcode IPs via the compiler's sourceMap
• Continue — runs until next breakpoint or program end
• Step in / over / out — single-step execution
• Restart — re-load and re-run the program
• Stack trace — single thread; shows the suspended IP's source line + parent call frames
• Scopes — Locals (visible bindings via parent chain) + Value Stack
• Variables — current frame's bindings, pretty-printed
• Terminate / disconnect — clean exit

What does not work yet

• Conditional / log breakpoints
• Exception breakpoints
• repl evaluation at a breakpoint
• Reverse / time-travel debugging

VSCode

Install the extension in dev mode (see vscode-extension/README). Open a .pen file → Run and Debug → "Launch Penelope file".

{
  "type": "penelope",
  "request": "launch",
  "name": "Launch Penelope file",
  "program": "${workspaceFolder}/${file}"
}

Neovim (nvim-dap)

local dap = require('dap')
dap.adapters.penelope = {
  type = 'executable',
  command = 'bin/penelope-dap',
  args = {},
}
dap.configurations.penelope = {
  {
    type = 'penelope',
    request = 'launch',
    name = 'Launch Penelope file',
    program = '${workspaceFolder}/${relativeFile}',
  },
}

Protocol details

The adapter understands these DAP requests: initialize, launch, setBreakpoints, configurationDone, continue, next, stepIn, stepOut, restart, threads, stackTrace, scopes, variables, terminate, disconnect. Emits events: initialized, stopped (reasons: entry, breakpoint, step, pause), output, terminated.

The wire format is identical to LSP — Content-Length-framed JSON-RPC over stdio.