From 968bfd2d192ae393790bb2413354b1d556b2f24b Mon Sep 17 00:00:00 2001 From: Andrew Porter Date: Sat, 14 Mar 2026 16:07:57 -0700 Subject: [PATCH] (pr feedback): use process env variable, be more explicit about cleanup, update docs --- .vscode/launch.json | 31 +++++++++++++++++-------------- .vscode/tasks.json | 2 +- docs/help/debugging.md | 36 +++++++++++++++++------------------- package.json | 1 + tsdown.config.ts | 2 +- 5 files changed, 37 insertions(+), 35 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 41d4639c349..27fa99cc057 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -1,6 +1,23 @@ { "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", @@ -13,20 +30,6 @@ "sourceMaps": true, "smartStep": true, "internalConsoleOptions": "openOnSessionStart" - }, - { - "name": "Rebuild and Debug Gateway", - "type": "node", - "request": "launch", - "preLaunchTask": "clean:dist", - "runtimeExecutable": "pnpm", - "args": ["run", "openclaw", "--", "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 index a081a09b354..3318e75656b 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -4,7 +4,7 @@ { "label": "clean:dist", "type": "shell", - "command": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"", + "command": "pnpm clean:dist", "group": "none", "presentation": { "echo": true, diff --git a/docs/help/debugging.md b/docs/help/debugging.md index 8a7a118ef59..25afc1c442c 100644 --- a/docs/help/debugging.md +++ b/docs/help/debugging.md @@ -163,31 +163,29 @@ Default file: ## Debugging in VSCode -### Overview +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: -The OpenClaw project uses `tsdown` to bundle TypeScript code into JavaScript for distribution. 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 scoped builds. Generating source maps is a single change before build time and 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 -#### Included Configurations +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. **Debug Gateway** - Debugs the Gateway service of a pre-existing build -2. **Rebuild and Debug Gateway** - Debugs the Gateway service after creating a new build +1. Open the **Run and Debug** panel from the Activity Bar or press `Ctrl`+`Shift`+`D` +2. Ensure **Rebuild and Debug Gateway** is selected in the configuration dropdown, then press the **Start Debugging** button -#### Using the Debugger +Alternatively - if you prefer to manage the build and debug processes manually: -1. Enable debugging support in the `tsdown` configuration and rebuild: - - Set `OUTPUT_SOURCE_MAPS` to `true` in `tsdown.config.ts` - - Run `node -e "require('fs').rmSync('dist', {recursive: true, force: true})" && pnpm build` to rebuild the project -2. Open the `Run and Debug` panel from the Activity Bar or press `Ctrl`+`Shift`+`D` -3. Select one of the debug configurations from the dropdown -4. Press the "Start Debugging" button next to the dropdown or press `F5` -5. Set breakpoints in your TypeScript source files (under `src/` directory) - - The debugger will correctly map breakpoints to the compiled JavaScript via source maps - - You'll be able to inspect variables, step through code, etc. +1. Open a terminal and enable source maps: `export OUTPUT_SOURCE_MAPS=1` +2. In the same terminal, rebuld the project: `pnpm clean:dist && pnpm build` +3. Select the **Debug Gateway** option in the **Run and Debug** configuration dropdown, then press the **Start Debugging** button -#### Additional Notes +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. -- If using the "Rebuild and Debug Gateway" option, restarting the debugger will completely delete the `/dist` folder, causing the `run-node.mjs` script to rebuild the project -- Change 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 run it in another shell as `node ./openclaw.mjs` or a shell alias like `alias openclaw-build="node $(pwd)/openclaw.mjs"` +### 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 6cde8d84431..17338d4209a 100644 --- a/package.json +++ b/package.json @@ -233,6 +233,7 @@ "check:docs": "pnpm format:docs:check && pnpm lint:docs && 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})\"", "deadcode:ci": "pnpm deadcode:report:ci:knip", "deadcode:knip": "pnpm dlx knip --config knip.config.ts --isolate-workspaces --production --no-progress --reporter compact --files --dependencies", "deadcode:report": "pnpm deadcode:knip; pnpm deadcode:ts-prune; pnpm deadcode:ts-unused", diff --git a/tsdown.config.ts b/tsdown.config.ts index 6a2caa0cbda..4a92fa05483 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -3,7 +3,7 @@ import { defineConfig } from "tsdown"; const env = { NODE_ENV: "production", }; -const OUTPUT_SOURCE_MAPS = false; +const OUTPUT_SOURCE_MAPS = process.env.OUTPUT_SOURCE_MAPS === "1"; function buildInputOptions(options: { onLog?: unknown; [key: string]: unknown }) { if (process.env.OPENCLAW_BUILD_VERBOSE === "1") {