Dbg Dev

dbg Development

Internal skill for developing dbg itself.

Build & Test

pnpm run build         # build all packages (tsc per package)
pnpm test              # build + vitest
pnpm run ci            # full pipeline (lint + typecheck + build + test)
pnpm run lint          # biome lint
pnpm run format:check  # biome format check

Architecture

pnpm monorepo (pnpm-workspace.yaml). All packages under packages/.

@dbg/cli          CLI entry point, daemon, commands
  → @dbg/adapter-cdp   CDP websocket client + target discovery
  → @dbg/adapter-dap   DAP (Debug Adapter Protocol) client + transport
  → @dbg/query         SQL parser, filter engine, table registry
  → @dbg/store         SQLite-backed event store
  → @dbg/tables-core   Virtual tables: frames, vars, scripts, breakpoints, timeline, etc.
  → @dbg/tables-browser  Browser tables: network, dom, cookies, storage, coverage, etc.
  → @dbg/tables-native   Native debug tables: threads, registers, memory, disassembly, etc.
  → @dbg/types         Shared types (Session, Command, Response, protocol)

Request flow

CLI (packages/cli/src/cli.ts)
  → Unix socket → daemon (packages/cli/src/daemon.ts)
    → CDP client (packages/adapter-cdp/src/client.ts) → Chrome DevTools Protocol target
    or → DAP client (packages/adapter-dap/src/client.ts) → Debug Adapter Protocol target

Key Files

Environment Variables

Test Isolation

Tests use isolated socket and database paths to avoid interfering with production daemons:

• Integration tests set SOCKET_PATH = "/tmp/dbg-test.sock" and pass DBG_SOCK in all env objects
• Each test file uses its own DBG_EVENTS_DB path and cleans up after each test
• Never rely on default socket paths in tests
• fileParallelism: false in vitest config — tests share sockets and can't run in parallel
• Test fixtures in test/fixtures/*.js must preserve exact whitespace (line-number-dependent tests)
• Don't run biome on test/fixtures/*.js — it would break line numbers

Self-Debugging

dbg can debug its own daemon by running a second instance on a different socket.

Basic Pattern

# Terminal 1: Start the daemon you want to debug
DBG_SOCK=/tmp/dbg2.sock DBG_EVENTS_DB=/tmp/dbg2-events.db \
  node --inspect-brk=9230 packages/cli/dist/daemon.js

# Terminal 2: Use normal dbg to attach to it
dbg open 9230
dbg b daemon.ts:150
dbg c
dbg q "SELECT * FROM vars"    # see the target daemon's own variables
dbg q "SELECT * FROM frames"  # see its call stack

--inspect vs --inspect-brk

• --inspect-brk: Pauses on first line. Good for debugging startup. But the daemon can't serve its socket until you resume it — bootstrap problem.
• --inspect: Starts normally with debug port open. Daemon is functional immediately. Use breakpoints to catch specific execution points.

For daemon debugging, prefer --inspect-brk when investigating startup/initialization, and --inspect when debugging request handling.

Ouroboros Pattern

Two daemons debugging each other — proven working for testing debugger protocol handling:

# Daemon A on socket A, debug port 9230
DBG_SOCK=/tmp/dbg-a.sock DBG_EVENTS_DB=/tmp/dbg-a-events.db \
  node --inspect=9230 packages/cli/dist/daemon.js

# Daemon B on socket B, debug port 9231
DBG_SOCK=/tmp/dbg-b.sock DBG_EVENTS_DB=/tmp/dbg-b-events.db \
  node --inspect=9231 packages/cli/dist/daemon.js

# A debugs B
DBG_SOCK=/tmp/dbg-a.sock dbg open 9231

# B debugs A
DBG_SOCK=/tmp/dbg-b.sock dbg open 9230

# Now each can pause, step, and inspect the other
DBG_SOCK=/tmp/dbg-a.sock dbg pause     # A pauses B
DBG_SOCK=/tmp/dbg-a.sock dbg e "process.env.DBG_SOCK"  # → /tmp/dbg-b.sock

Deadlock avoidance: Don't pause both daemons simultaneously. If A is paused and B sends a CDP message requiring A to respond, B hangs. Keep at least one daemon running.

Eval Scope Gotcha

dbg e evaluates in the current call frame, not module scope:

• Paused in your code → local variables visible
• Paused in Node internals (e.g., processTimers after pause) → module-level variables not accessible
• Fix: Set a breakpoint in your actual code, continue to it, then evaluate

# Wrong: paused in Node internals
dbg e "myConfig"  # → ReferenceError

# Right: continue to your code first
dbg b daemon.ts:25
dbg c
dbg e "myConfig"  # → { port: 9222, ... }

Converted and distributed by TomeVault — claim your Tome and manage your conversions.