dbg

dbg デバッガー

dbg は、Node.js（V8/CDP）、Bun（WebKit/JSC）、Python（debugpy/DAP 経由）、Java（JDWP/DAP 経由）、およびネイティブコード（LLDB/DAP 経由の C/C++/Rust/Swift）に対応する CLI デバッガーです。すべてのエンティティに短い @refs を使用します。長い ID の代わりにこれらを使ってください。

対応ランタイム

ランタイム	言語	起動例
Node.js	JavaScript	dbg launch --brk node app.js
tsx / ts-node	TypeScript	dbg launch --brk tsx src/app.ts
Bun	JavaScript / TypeScript	dbg launch --brk bun app.ts
Bun 実行ファイル（bun build --compile）	JavaScript / TypeScript	dbg launch --brk ./my-cli --its-flags
debugpy	Python	dbg launch --brk python3 app.py（またはアタッチ。Python のセクションを参照）
LLDB	C / C++ / Rust / Swift	dbg launch --brk --runtime lldb ./program
JDWP	Java	dbg launch --brk --runtime java ./program

JS および Python ランタイムでは、Bun でコンパイルされた実行ファイルも含め、起動コマンドからランタイムが自動検出されます（それ以外の場合は --runtime bun を渡してください）。プログラム名以降のすべての引数は、変更されずにプログラムへ渡されます。ネイティブコードでは --runtime lldb を使ってください。Python では、TCP 経由で実行中の debugpy リスナーにアタッチすることもできます（--runtime python）。

基本的なデバッグの流れ

# 1. Launch with breakpoint at first line
dbg launch --brk node app.js
# Or: dbg launch --brk bun app.ts
# Or: dbg launch --brk python3 app.py
# Or: dbg launch --brk --runtime lldb ./my_program
# Or attach to a running process with the --inspect flag
dbg attach 9229

# 2. Set breakpoints at suspicious locations
dbg break src/handler.ts:42
dbg break src/utils.ts:15 --condition "count > 10"

# 3. Run to breakpoint (--wait blocks until it pauses or the program ends;
#    "Running (no pause within 30s)" means it ran out: dbg continue --wait 60 keeps waiting)
dbg continue --wait 30

# 4. Inspect state (shows location, source, locals, stack)
dbg state

# 5. Drill into values
dbg props @v1              # expand object
dbg props @v1 --depth 3   # expand nested 3 levels
dbg eval "x + 1"

# 6. Fix and verify (JS/TS only)
dbg set count 0            # change variable
dbg hotpatch src/utils.js  # live-edit (reads file from disk)
dbg continue               # verify fix

デバッグ戦略

バグの調査 — ブレークポイントで絞り込む

dbg launch --brk node app.js
dbg break src/api.ts:50                    # suspect line
dbg break src/api.ts:60 --condition "!user" # conditional
dbg continue
dbg vars                                    # check locals
dbg eval "JSON.stringify(req.body)"         # inspect deeply
dbg step over                               # advance one line
dbg state                                   # see new state

ネイティブコードのデバッグ（C/C++/Rust）

dbg launch --brk --runtime lldb ./my_program
dbg break main.c:42
dbg break-fn main                          # function breakpoint
dbg continue
dbg vars                                    # inspect locals
dbg eval "array[i]"                         # evaluate expression
dbg step into                               # step into function

Python のデバッグ（debugpy）

Python は debugpy DAP アダプターを使用します。接続方法は 2 つあります。

起動（python/python3 コマンドから自動検出）:

dbg launch --brk python3 app.py        # pauses at first line
dbg break app.py:42
dbg continue
dbg state                              # location + locals + stack
dbg eval "some_expr"                   # evaluate in the paused frame
dbg step over

アタッチ — デバッグ対象プロセス自身が debugpy リスナーを起動し、dbg が TCP 経由で接続します（間にアダプターは起動しません）。特定の方法でプロセスを 起動する必要がある場合（テストランナー、仮想環境、シークレットのラッパーなど）に便利です。

# 1. Start the program listening on a port. --wait-for-client blocks before
#    the first line runs, so you have time to attach and set breakpoints.
python3 -m debugpy --listen 5679 --wait-for-client app.py &

# 2. Attach. --runtime python (alias: debugpy) is REQUIRED for a bare port.
dbg attach 5679 --runtime python

# 3. Set breakpoints (use absolute paths), then drive execution.
dbg break /abs/path/app.py:42
dbg continue
dbg state

注意:

• --wait-for-client は最初の TCP 接続をクライアントとして扱います。準備状況を確認するためにポートへ接続しないでください。debugpy が stderr に起動バナーを出力したら、そのままアタッチしてください。
• ブレークポイントを設定する前に、短いスクリプトが実行を完了することがあります。アタッチ直後にブレークポイントを設定するか、長時間実行されるエントリーポイントにアタッチしてください。
• dbg set / dbg hotpatch は JS/TS 専用です。検査コマンド（break、continue、state、vars、eval、step、break-fn）はすべて Python でも動作します。

実行中のプロセス／テストプロセスへのアタッチ（Node/Bun）

# Start with inspector enabled
node --inspect app.js
# Or: bun --inspect app.ts
# Then attach
dbg attach 9229
dbg state

# Bun process or Bun-compiled binary: BUN_INSPECT opens the inspector, `?break=1`
# holds the process until dbg attaches, then pauses on its first statement.
BUN_INSPECT='ws://localhost:6499/app?break=1' ./my-bun-binary
dbg attach ws://localhost:6499/app        # runtime auto-detected
# Function breakpoint (JS/TS): a path from the global scope, an @ref, or --name <regex> (Bun)
dbg break-fn fetch --condition 'String(args[0]).includes("/v1/messages")'
dbg break-fn @v12                          # a function object you found in vars/props
dbg logpoint fn:service.ping '"ping", label'   # trace calls without pausing; dbg console
dbg continue                              # pauses on the call; `dbg stack` @f1 is the caller

ログポイントで実行フローを追跡する（一時停止なし）

dbg logpoint src/auth.ts:20 '"login attempt:", username'   # console.log's arguments
dbg logpoint src/auth.ts:45 '`auth result: ${result}`'
dbg continue
dbg console    # see logged output; logpoints never print into the program's own output

プログラム終了時の状態を調べる（JS）

dbg catch exit              # pause in the program's exit, state still alive
dbg continue --wait 60      # runs until it exits
dbg eval "code"             # the exit code; eval anything else that is still there
dbg continue                # let it exit

例外のデバッグ

dbg catch uncaught          # pause on uncaught exceptions
dbg continue                # runs until exception
dbg state                   # see where it threw
dbg eval "err.message"      # inspect the error
dbg stack                   # full call stack

TypeScript のソースマップ対応

dbg はソースマップを通じて .ts のパスを自動的に解決します。.ts のパスを指定してブレークポイントを設定すると、出力に .ts のソースが表示されます。必要に応じて --generated を使うと、コンパイル済みの .js を確認できます。

Ref システム

出力にはすべて短い ref が割り当てられます。どこでもこれらを使ってください。

• @v1..@vN — 変数: dbg props @v1、dbg set @v2 true
• @f0..@fN — スタックフレーム: dbg eval --frame @f1 "this"
• BP#1..N — ブレークポイント: dbg break-rm BP#1、dbg break-toggle BP#1
• LP#1..N — ログポイント: dbg break-rm LP#1

ref @v/@f は一時停止のたびにリセットされます。BP#/LP# は削除されるまで維持されます。

主なフラグ

• --json — すべてのコマンドで機械可読な JSON 出力を行います
• --session NAME — 特定のセッションを対象にします（既定値: "default"）
• --runtime NAME — デバッグアダプターを選択します（例: ネイティブコードの場合は lldb）
• --generated — ソースマップを無視し、コンパイル済み JS を表示します（state/source/stack で使用）

コマンドリファレンス

コマンドとオプションの詳細については、references/commands.md を参照してください。

ヒント

• ステップ実行後に dbg state を実行すると、場所・ソース・ローカル変数が常に表示されます。通常はこれだけで十分なコンテキストが得られます。
• dbg state -c はソースのみ、-v は変数のみ、-s はスタックのみを表示します。トークンを節約できます。
• 圧縮／バンドルされたコードの場合：dbg sourcemap <script> --pretty を実行すると、それ以降はスクリプトが整形された状態で表示されます（位置とブレークポイントも対応します）。dbg source --width 600 は一時停止した列の前後 600 文字を表示し、dbg search "text" --width 200 は各一致箇所の前後を表示します。
• dbg eval は await と --await に対応しています（JS/TS）。Promise が解決されるのはプログラムの実行中のみです。一時停止中はすでに解決済みの値が取得され、それ以外の場合は説明が表示されます。
• dbg eval <expr> --out file.txt は値全体を出力します（指定しない場合、出力は 80 文字で切り詰められます）。
• ES モジュールでは require は未定義です。代わりに process.getBuiltinModule("node:fs") を使用してください。
• dbg blackbox "node_modules/**" — 依存関係へのステップインをスキップします。
• dbg hotpatch file はディスク上のファイルを読み込みます。先にファイルを編集してから、ホットパッチを適用してください（JS/TS のみ）。
• dbg break-fn funcName — 関数ブレークポイント：DAP ランタイムではシンボルで指定します。JS ではパス（obj.method）、@ref、または --name <regex>（Bun）で指定します。--condition／--log は、一時停止した場所で関数自身のパラメーター、arguments、this を対象に実行されます。プロセス内で dbg がラップするネイティブ関数（Bun の fetch など）の場合は、args と this が対象です。設定時にパスが存在している必要があります。dbg stop を実行するとラッパーが削除されます。
• dbg eval は実行中のターゲットでも動作します（グローバルスコープ）。一時停止が必要なのは --frame のみです。
• Python：dbg launch --brk python3 app.py を実行するか、dbg attach <port> --runtime python で debugpy --listen <port> サーバーにアタッチします。
• 実行コマンド（continue、step、pause、run-to）はステータスを自動的に返します。
• dbg stop はデバッグ対象のプロセスとデーモンを終了します。