Debugging instructions, replica WIT-DEBUG directory, StarlingMonkey debugger extension

.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "starlingmonkey",
+      "request": "launch",
+      "name": "StarlingMonkey",
+      "program": "${workspaceFolder}/dist/bundle.js",
+      "component": "${workspaceFolder}/dist/sample-wasi-http-js.wasm",
+      "stopOnEntry": true,
+      "preLaunchTask": "build debug component"
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,15 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "build debug component",
+      "type": "shell",
+      "command": "npm run build:debug",
+      "group": "build",
+      "presentation": {
+        "reveal": "always",
+        "panel": "new"
+      }
+    }
+  ]
+}

README.md

@@ -55,6 +55,24 @@ $ npm install
 $ npm run build
 $ wasmtime serve -S common dist/sample-wasi-http-js.wasm
 ```
+## Debugging in VSCode
+
+You can debug by installing the [StarlingMonkey debugger extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=BytecodeAlliance.starlingmonkey-debugger). [Componentize-js](https://github.com/bytecodealliance/componentize-js) is the compile tool that bundles the JavaScript application into a single .js file according to the `rollup.config.js` file, creates a WebAssembly module with the SpiderMonkey JavaScript engine, and then creates a component with both modules inside. For details, see the `build` and `build:debug` scripts in the `package.json` file in the root folder.
+
+> NOTE: At this time, the debug extension requires both a StarlingMonkey component with debugging enabled, using `componentize-js` and the `--enable-script-debugging` runtime argument flag. In addition, to attach the debugger to the SpiderMonkey debugging API inside the StarlingMonkey WebAssembly component, the following additional interfaces need to be built into the debug version of the component:
+
+```bash
+import wasi:cli/[email protected];
+import wasi:sockets/[email protected];
+import wasi:sockets/[email protected];
+import wasi:sockets/[email protected];
+import wasi:sockets/[email protected];
+```
+
+At the moment, the extension does not add these interfaces for you; to add these interfaces, a replica of the WIT directory with a modified `server.wit` file is included in the `wit-debug` directory. When you start the StarlingMonkey debugger by selecting the `Run` menu and then `Start Debugging` (or press `F5`), the `tasks.json` file executes `npm run build:debug`, which compiles the modified WIT file to build the debug version of the component automatically.
+
+Following a successful build, the StarlingMonkey debugger will launch `wasmtime` to serve the debug version of the component. Set a breakpoint on the JavaScript in the bundled version of your code, in dist/bundle.js, as that is the file that StarlingMonkey will be executing inside the component.
+
 
 ## See Also
 

package.json

@@ -13,6 +13,7 @@
   "scripts": {
     "bundle": "rollup -c",
     "build": "npm run bundle && componentize-js --aot --wit wit -o dist/$npm_package_name.wasm dist/bundle.js",
+    "build:debug": "npm run bundle && componentize-js --use-debug-build --runtime-args \"--enable-script-debugging\" --wit wit-debug -o dist/$npm_package_name.wasm dist/bundle.js",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css}\"",
     "format-ci": "prettier --check \"**/*.{js,jsx,ts,tsx,json,css}\"",
     "lint": "eslint src/**/*.js",

wit-debug/deps/wasi-cli-0.2.3/package.wit

@@ -0,0 +1,246 @@
+package wasi:[email protected];
+
+@since(version = 0.2.0)
+interface environment {
+  /// Get the POSIX-style environment variables.
+  ///
+  /// Each environment variable is provided as a pair of string variable names
+  /// and string value.
+  ///
+  /// Morally, these are a value import, but until value imports are available
+  /// in the component model, this import function should return the same
+  /// values each time it is called.
+  @since(version = 0.2.0)
+  get-environment: func() -> list<tuple<string, string>>;
+
+  /// Get the POSIX-style arguments to the program.
+  @since(version = 0.2.0)
+  get-arguments: func() -> list<string>;
+
+  /// Return a path that programs should use as their initial current working
+  /// directory, interpreting `.` as shorthand for this.
+  @since(version = 0.2.0)
+  initial-cwd: func() -> option<string>;
+}
+
+@since(version = 0.2.0)
+interface exit {
+  /// Exit the current instance and any linked instances.
+  @since(version = 0.2.0)
+  exit: func(status: result);
+}
+
+@since(version = 0.2.0)
+interface run {
+  /// Run the program.
+  @since(version = 0.2.0)
+  run: func() -> result;
+}
+
+@since(version = 0.2.0)
+interface stdin {
+  @since(version = 0.2.0)
+  use wasi:io/[email protected].{input-stream};
+
+  @since(version = 0.2.0)
+  get-stdin: func() -> input-stream;
+}
+
+@since(version = 0.2.0)
+interface stdout {
+  @since(version = 0.2.0)
+  use wasi:io/[email protected].{output-stream};
+
+  @since(version = 0.2.0)
+  get-stdout: func() -> output-stream;
+}
+
+@since(version = 0.2.0)
+interface stderr {
+  @since(version = 0.2.0)
+  use wasi:io/[email protected].{output-stream};
+
+  @since(version = 0.2.0)
+  get-stderr: func() -> output-stream;
+}
+
+/// Terminal input.
+///
+/// In the future, this may include functions for disabling echoing,
+/// disabling input buffering so that keyboard events are sent through
+/// immediately, querying supported features, and so on.
+@since(version = 0.2.0)
+interface terminal-input {
+  /// The input side of a terminal.
+  @since(version = 0.2.0)
+  resource terminal-input;
+}
+
+/// Terminal output.
+///
+/// In the future, this may include functions for querying the terminal
+/// size, being notified of terminal size changes, querying supported
+/// features, and so on.
+@since(version = 0.2.0)
+interface terminal-output {
+  /// The output side of a terminal.
+  @since(version = 0.2.0)
+  resource terminal-output;
+}
+
+/// An interface providing an optional `terminal-input` for stdin as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stdin {
+  @since(version = 0.2.0)
+  use terminal-input.{terminal-input};
+
+  /// If stdin is connected to a terminal, return a `terminal-input` handle
+  /// allowing further interaction with it.
+  @since(version = 0.2.0)
+  get-terminal-stdin: func() -> option<terminal-input>;
+}
+
+/// An interface providing an optional `terminal-output` for stdout as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stdout {
+  @since(version = 0.2.0)
+  use terminal-output.{terminal-output};
+
+  /// If stdout is connected to a terminal, return a `terminal-output` handle
+  /// allowing further interaction with it.
+  @since(version = 0.2.0)
+  get-terminal-stdout: func() -> option<terminal-output>;
+}
+
+/// An interface providing an optional `terminal-output` for stderr as a
+/// link-time authority.
+@since(version = 0.2.0)
+interface terminal-stderr {
+  @since(version = 0.2.0)
+  use terminal-output.{terminal-output};
+
+  /// If stderr is connected to a terminal, return a `terminal-output` handle
+  /// allowing further interaction with it.
+  @since(version = 0.2.0)
+  get-terminal-stderr: func() -> option<terminal-output>;
+}
+
+@since(version = 0.2.0)
+world imports {
+  @since(version = 0.2.0)
+  import environment;
+  @since(version = 0.2.0)
+  import exit;
+  @since(version = 0.2.0)
+  import wasi:io/[email protected];
+  @since(version = 0.2.0)
+  import wasi:io/[email protected];
+  @since(version = 0.2.0)
+  import wasi:io/[email protected];
+  @since(version = 0.2.0)
+  import stdin;
+  @since(version = 0.2.0)
+  import stdout;
+  @since(version = 0.2.0)
+  import stderr;
+  @since(version = 0.2.0)
+  import terminal-input;
+  @since(version = 0.2.0)
+  import terminal-output;
+  @since(version = 0.2.0)
+  import terminal-stdin;
+  @since(version = 0.2.0)
+  import terminal-stdout;
+  @since(version = 0.2.0)
+  import terminal-stderr;
+  @since(version = 0.2.0)
+  import wasi:clocks/[email protected];
+  @since(version = 0.2.0)
+  import wasi:clocks/[email protected];
+  @since(version = 0.2.0)
+  import wasi:filesystem/[email protected];
+  @since(version = 0.2.0)
+  import wasi:filesystem/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:random/[email protected];
+  @since(version = 0.2.0)
+  import wasi:random/[email protected];
+  @since(version = 0.2.0)
+  import wasi:random/[email protected];
+}
+@since(version = 0.2.0)
+world command {
+  @since(version = 0.2.0)
+  import environment;
+  @since(version = 0.2.0)
+  import exit;
+  @since(version = 0.2.0)
+  import wasi:io/[email protected];
+  @since(version = 0.2.0)
+  import wasi:io/[email protected];
+  @since(version = 0.2.0)
+  import wasi:io/[email protected];
+  @since(version = 0.2.0)
+  import stdin;
+  @since(version = 0.2.0)
+  import stdout;
+  @since(version = 0.2.0)
+  import stderr;
+  @since(version = 0.2.0)
+  import terminal-input;
+  @since(version = 0.2.0)
+  import terminal-output;
+  @since(version = 0.2.0)
+  import terminal-stdin;
+  @since(version = 0.2.0)
+  import terminal-stdout;
+  @since(version = 0.2.0)
+  import terminal-stderr;
+  @since(version = 0.2.0)
+  import wasi:clocks/[email protected];
+  @since(version = 0.2.0)
+  import wasi:clocks/[email protected];
+  @since(version = 0.2.0)
+  import wasi:filesystem/[email protected];
+  @since(version = 0.2.0)
+  import wasi:filesystem/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:sockets/[email protected];
+  @since(version = 0.2.0)
+  import wasi:random/[email protected];
+  @since(version = 0.2.0)
+  import wasi:random/[email protected];
+  @since(version = 0.2.0)
+  import wasi:random/[email protected];
+
+  @since(version = 0.2.0)
+  export run;
+}

wit-debug/deps/wasi-clocks-0.2.3/package.wit

@@ -0,0 +1,29 @@
+package wasi:[email protected];
+
+interface monotonic-clock {
+  use wasi:io/[email protected].{pollable};
+
+  type instant = u64;
+
+  type duration = u64;
+
+  now: func() -> instant;
+
+  resolution: func() -> duration;
+
+  subscribe-instant: func(when: instant) -> pollable;
+
+  subscribe-duration: func(when: duration) -> pollable;
+}
+
+interface wall-clock {
+  record datetime {
+    seconds: u64,
+    nanoseconds: u32,
+  }
+
+  now: func() -> datetime;
+
+  resolution: func() -> datetime;
+}
+