diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 00000000000..27fa99cc057 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,35 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Rebuild and Debug Gateway", + "type": "node", + "request": "launch", + "preLaunchTask": "clean:dist", + "runtimeExecutable": "pnpm", + "args": ["run", "openclaw", "--", "gateway", "run"], + "env": { + "OUTPUT_SOURCE_MAPS": "1" + }, + "console": "integratedTerminal", + "skipFiles": ["/**", "node_modules/**"], + "outFiles": ["${workspaceFolder}/dist/**/*.js"], + "sourceMaps": true, + "smartStep": true, + "internalConsoleOptions": "openOnSessionStart" + }, + { + "name": "Debug Gateway", + "type": "node", + "request": "launch", + "program": "${workspaceFolder}/openclaw.mjs", + "args": ["gateway", "run"], + "console": "integratedTerminal", + "skipFiles": ["/**", "node_modules/**"], + "outFiles": ["${workspaceFolder}/dist/**/*.js"], + "sourceMaps": true, + "smartStep": true, + "internalConsoleOptions": "openOnSessionStart" + } + ] +} diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 00000000000..2eac84a7b7d --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,18 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "clean:dist", + "type": "shell", + "command": "pnpm clean:dist", + "group": "none", + "problemMatcher": [], + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared" + } + } + ] +} diff --git a/README.md b/README.md index b21b19108c4..20100912628 100644 --- a/README.md +++ b/README.md @@ -555,5 +555,5 @@ Thanks to all clawtributors: sktbrd larlyssa Mind-Dragon pcty-nextgen-service-account tmchow uli-will-code Marc Gratch JackyWay aaronveklabs CJWTRUST erik-agens odnxe T5-AndyML Josh Phillips mujiannan Marco Di Dionisio Randy Torres afern247 0oAstro alexanderatallah testingabc321 humanwritten aaronn Alphonse-arianee gtsifrikas hrdwdmrbl hugobarauna jiulingyun kitze loukotal - MSch odrobnik reeltimeapps rhjoh ronak-guliani snopoke + MSch odrobnik reeltimeapps rhjoh ronak-guliani snopoke SwissArmyBud

diff --git a/docs/help/debugging.md b/docs/help/debugging.md index 04fd150ef20..e68bb7fbf31 100644 --- a/docs/help/debugging.md +++ b/docs/help/debugging.md @@ -166,3 +166,35 @@ Default file: - Raw stream logs can include full prompts, tool output, and user data. - Keep logs local and delete them after debugging. - If you share logs, scrub secrets and PII first. + +## Debugging in VSCode + +Source maps are required to enable debugging in VSCode-based IDEs because many of the generated files end up with hashed names as part of the build process. The included `launch.json` configurations target the Gateway service, but can be adapted quickly for other purposes: + +1. **Rebuild and Debug Gateway** - Debugs the Gateway service after creating a new build +2. **Debug Gateway** - Debugs the Gateway service of a pre-existing build + +### Setup + +The default **Rebuild and Debug Gateway** configuration is batteries-included, it will automatically delete the `/dist` folder and rebuild the project with debugging enabled: + +1. Open the **Run and Debug** panel from the Activity Bar or press `Ctrl`+`Shift`+`D` +2. In the IDE, ensure **Rebuild and Debug Gateway** is selected in the configuration dropdown and then press the **Start Debugging** button + +Alternatively - if you prefer to manage the build and debug processes manually: + +1. Open a terminal and enable source maps: + - **Linux/macOS**: `export OUTPUT_SOURCE_MAPS=1` + - **Windows (PowerShell)**: `$env:OUTPUT_SOURCE_MAPS="1"` + - **Windows (CMD)**: `set OUTPUT_SOURCE_MAPS=1` +2. In the same terminal, rebuild the project: `pnpm clean:dist && pnpm build` +3. In the IDE, select the **Debug Gateway** option in the **Run and Debug** configuration dropdown and then press the **Start Debugging** button + +You can now set breakpoints in your TypeScript source files (`src/` directory) and the debugger will correctly map breakpoints to the compiled JavaScript via source maps. You'll be able to inspect variables, step through code, and examine call stacks as expected. + +### Notes + +- If using the **"Rebuild and Debug Gateway"** option, each time the debugger is launched it will completely delete the `/dist` folder and trigger the `run-node.mjs` script to rebuild the project +- If using the **"Debug Gateway"** option, debug sessions can be started and stopped at any time without affecting the `/dist` folder, but you must use a separate terminal process to both enable debugging and manage the build cycle +- Modify the `launch.json` settings for `args` to debug other sections of the project +- If you need to use the built OpenClaw CLI for other tasks (i.e. `dashboard --no-open` if your debug session spawns a new auth token), you can execute it in another terminal as `node ./openclaw.mjs` or create a shell alias like `alias openclaw-build="node $(pwd)/openclaw.mjs"` diff --git a/package.json b/package.json index 99529029aed..908b9682c91 100644 --- a/package.json +++ b/package.json @@ -456,6 +456,7 @@ "check:docs": "pnpm format:docs:check && pnpm lint:docs && pnpm docs:check-i18n-glossary && pnpm docs:check-links", "check:host-env-policy:swift": "node scripts/generate-host-env-security-policy-swift.mjs --check", "check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500", + "clean:dist": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"", "config:docs:check": "node --import tsx scripts/generate-config-doc-baseline.ts --check", "config:docs:gen": "node --import tsx scripts/generate-config-doc-baseline.ts --write", "deadcode:ci": "pnpm deadcode:report:ci:knip", diff --git a/tsdown.config.ts b/tsdown.config.ts index 304f781d91d..18e2fd5e616 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -24,6 +24,7 @@ type OnLogFunction = InputOptionsArg extends { onLog?: infer OnLog } ? NonNullab const env = { NODE_ENV: "production", }; +const OUTPUT_SOURCE_MAPS = process.env.OUTPUT_SOURCE_MAPS === "1"; const SUPPRESSED_EVAL_WARNING_PATHS = [ "@protobufjs/inquire/index.js", @@ -76,6 +77,7 @@ function nodeBuildConfig(config: UserConfig): UserConfig { env, fixedExtension: false, platform: "node", + sourcemap: OUTPUT_SOURCE_MAPS, inputOptions: buildInputOptions, }; }