feat(vscode): improved wing debugging and docs (breakpoints)

apps/vscode-wing/.projenrc.ts

@@ -97,6 +97,7 @@ vscodeIgnore.addPatterns(
 );
 
 const contributes: VSCodeExtensionContributions = {
+  breakpoints: [{ language: "wing" }],
   languages: [
     {
       id: "wing",

docs/docs/06-tools/03-debugging.md

@@ -0,0 +1,31 @@
+---
+title: Debugging
+id: Debugging
+description: Learn how to debug your Wing application
+keywords: [debugging, debug, test, vscode]
+---
+
+## Overview
+
+Internally Wing uses JavaScript to execute preflight and `inflight` code, so standard JavaScript debugging tools can be used to debug your Wing application. The best-supported debugger is the built-in VS Code one so this guide will focus on that. 
+
+### Local/Simulator Debugging
+
+To start, open your .w file in VS Code and set a breakpoint by clicking in the gutter to the left of the line number. Breakpoints can also be set in extern files. There are several ways to start the debugger, but let's use the "JavaScript Debug Terminal".
+Open the command palette and type "Debug: Open JavaScript Debug Terminal". This works for any wing commands like `wing test` and `wing it`, although keep in mind that `wing compile` will only debug preflight code.
+
+### Limitations
+
+- When using the Wing Console (`wing it`) and attempting to debug `inflight` code in a `test` or Function, the first execution of the test will not hit a breakpoint and will need to be run again
+- Caught/Unhandled will often not stop at expected places
+- `inflight` code by default has a timeout that continues during debugging, so if execution is paused for too long the program is terminate
+
+#### Non-VSCode Support
+
+The Wing CLI itself is a Node.js application, so you can use the `--inspect` flag to debug it and expose a debug server.
+
+```bash
+node --inspect $(which wing)
+```
+
+Note that `inflight` code will be executed among multiple child processes, so it's recommended to use a debugger than supports automatically attaching to child processes.

libs/wingsdk/src/shared/legacy-sandbox.ts

@@ -1,6 +1,4 @@
-import { mkdtemp, readFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
+import { readFile } from "node:fs/promises";
 import * as util from "node:util";
 import * as vm from "node:vm";
 import { createBundle } from "./bundling";
@@ -90,8 +88,7 @@ export class LegacySandbox {
 
   private async createBundle() {
     // load bundle into context on first run
-    const workdir = await mkdtemp(path.join(tmpdir(), "wing-bundles-"));
-    const bundle = createBundle(this.entrypoint, [], workdir);
+    const bundle = createBundle(this.entrypoint);
     this.entrypoint = bundle.entrypointPath;
 
     this.code = await readFile(this.entrypoint, "utf-8");

libs/wingsdk/src/shared/sandbox.ts

@@ -1,8 +1,6 @@
 import * as cp from "child_process";
 import { writeFileSync } from "fs";
-import { mkdtemp, readFile, stat } from "fs/promises";
-import { tmpdir } from "os";
-import path from "path";
+import { readFile, stat } from "fs/promises";
 import { Bundle, createBundle } from "./bundling";
 import { processStream } from "./stream-processor";
 
@@ -39,8 +37,6 @@ export class Sandbox {
     entrypoint: string,
     log?: (message: string) => void
   ): Promise<Bundle> {
-    const workdir = await mkdtemp(path.join(tmpdir(), "wing-bundles-"));
-
     let contents = (await readFile(entrypoint)).toString();
 
     // log a warning if contents includes __dirname or __filename
@@ -67,7 +63,7 @@ process.on("message", async (message) => {
 `;
     const wrappedPath = entrypoint.replace(/\.js$/, ".sandbox.js");
     writeFileSync(wrappedPath, contents); // async fsPromises.writeFile "flush" option is not available in Node 20
-    const bundle = createBundle(wrappedPath, [], workdir);
+    const bundle = createBundle(wrappedPath);
 
     if (process.env.DEBUG) {
       const fileStats = await stat(entrypoint);

libs/wingsdk/test/util.ts

@@ -130,6 +130,15 @@ export function directorySnapshot(initialRoot: string) {
       if (f === "node_modules") {
         continue;
       }
+      // skip sandbox entrypoints since they are mostly a duplicate of the original
+      if (f.endsWith(".sandbox.js")) {
+        continue;
+      }
+      // skip esbuild output
+      if (f.endsWith(".js.bundle")) {
+        continue;
+      }
+
       const relpath = join(subdir, f);
       const abspath = join(root, relpath);
       const key = prefix + relpath;
@@ -149,9 +158,6 @@ export function directorySnapshot(initialRoot: string) {
             break;
 
           case ".js":
-            if (f.endsWith(".sandbox.js")) {
-              continue;
-            }
             const code = readFileSync(abspath, "utf-8");
             snapshot[key] = sanitizeCode(code);
             break;