Celest Debug Adapter

celest-dap 1.1.3 is the stdio Debug Adapter Protocol server for native Celest programs. It consumes Runtime inspection protocol schema 4; it does not parse Celest source or dereference arbitrary process addresses itself.

Running

From this repository:

npm install
node src/main.js

After installing or unpacking the npm package, a DAP client launches celest-dap and communicates with standard DAP Content-Length framing over stdin/stdout. The VS Code extension bundles the same adapter, so VS Code users do not need a separate global installation.

Launch

A launch request requires an absolute executable path:

{
  "type": "celest",
  "request": "launch",
  "name": "Launch Celest",
  "program": "D:/project/build/windows-x64/app.exe",
  "args": [],
  "cwd": "D:/project",
  "env": {}
}

The adapter creates per-session inspection, control, breakpoint and memory endpoints, passes them to the child through environment variables, captures stdout/stderr and validates the Runtime process/session identity. program must already be compiled with the current Runtime inspection support. Restart terminates and relaunches only launch sessions.

Attach

Direct attach is endpoint-based. The request must provide processId plus absolute inspectionFile, controlFile, breakpointFile, memoryRequestFile and memoryResponseFile paths created for that Runtime session; runtimeSessionIdentity can additionally pin the expected session. The adapter rejects process or session identity mismatches. A PID by itself is not sufficient for the standalone adapter.

Capabilities

• Continue, Pause, Step Over, Step Into, Step Out, terminate and launch-session restart;
• source, conditional, hit-count, log, Function, instruction and write data breakpoints;
• threads and delayed/paged stack traces;
• Arguments, Locals, Globals, this and Closure Captures scopes;
• nested Object/Function/dynamic value expansion;
• read-only identifier/member/index-path evaluate for hover/watch;
• setVariable for exact-width unsigned integers or 0x-prefixed bytes;
• exception information and Runtime-gated memory read/write.

Source breakpoints bind to source revision, code identity and Function generation. Instruction breakpoints bind only to exact Runtime checkpoints. Data breakpoints bind allocation identity, address and length and currently support writes only.

Variable, frame and memory references include Runtime session, thread and stop epoch; they expire immediately after resume. Invalid, released, moved or unchecked dynamic identities never receive a trusted memory reference. Memory access is available only when the Runtime session advertises that capability and the target thread is stopped.

Arbitrary side-effecting expression evaluation and disassembly are not implemented. Evaluate resolves only existing variable/property/index paths. setVariable does not evaluate Celest expressions and rejects width mismatch or values larger than 1024 bytes.

Build, test and publish

npm test
powershell -File deploy.ps1

deploy.ps1 runs tests, packs the npm archive into %USERPROFILE%\.celest\npm, performs interactive npm authentication when needed and publishes. The adapter itself is JavaScript; the debug target supplies the native Runtime protocol.

Tests cover fragmented UTF-8 DAP framing, inspection schema/session sequencing, reference expiry, invalid dynamic values, a real compiled Runtime session, async logical stacks and stepping, nested Object literals and transitive closure captures.