feat(unenv-preset): add support for native node:inspector module (#11733)

* feat(unenv-preset): add support for native node:inspector module

Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

* fix: require experimental flag for inspector module enablement

Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: petebacondarwin

.changeset/native-inspector-module.md

@@ -0,0 +1,23 @@
+---
+"@cloudflare/unenv-preset": minor
+---
+
+Add support for native `node:inspector` module when the `enable_nodejs_inspector_module` compatibility flag is enabled. This feature is currently experimental and requires both the `enable_nodejs_inspector_module` and `experimental` compatibility flags to be set.
+
+To enable the native inspector module, add the following to your `wrangler.jsonc`:
+
+```jsonc
+{
+	"compatibility_flags": ["experimental", "enable_nodejs_inspector_module"],
+}
+```
+
+Then you can import and use the inspector module in your Worker:
+
+```javascript
+import inspector from "node:inspector";
+
+// Access inspector APIs (note: workerd's implementation is a non-functional stub)
+inspector.url(); // returns undefined
+inspector.close(); // no-op
+```

packages/unenv-preset/src/preset.ts

@@ -79,6 +79,7 @@ export function getCloudflarePreset({
 	const wasiOverrides = getWasiOverrides(compat);
 	const consoleOverrides = getConsoleOverrides(compat);
 	const vmOverrides = getVmOverrides(compat);
+	const inspectorOverrides = getInspectorOverrides(compat);
 
 	// "dynamic" as they depend on the compatibility date and flags
 	const dynamicNativeModules = [
@@ -94,6 +95,7 @@ export function getCloudflarePreset({
 		...wasiOverrides.nativeModules,
 		...consoleOverrides.nativeModules,
 		...vmOverrides.nativeModules,
+		...inspectorOverrides.nativeModules,
 	];
 
 	// "dynamic" as they depend on the compatibility date and flags
@@ -110,6 +112,7 @@ export function getCloudflarePreset({
 		...wasiOverrides.hybridModules,
 		...consoleOverrides.hybridModules,
 		...vmOverrides.hybridModules,
+		...inspectorOverrides.hybridModules,
 	];
 
 	return {
@@ -596,3 +599,39 @@ function getVmOverrides({
 				hybridModules: [],
 			};
 }
+
+/**
+ * Returns the overrides for `node:inspector` (unenv or workerd)
+ *
+ * The native inspector implementation:
+ * - is experimental and has no default enable date
+ * - can be enabled with the "enable_nodejs_inspector_module" flag
+ * - can be disabled with the "disable_nodejs_inspector_module" flag
+ */
+function getInspectorOverrides({
+	compatibilityFlags,
+}: {
+	compatibilityDate: string;
+	compatibilityFlags: string[];
+}): { nativeModules: string[]; hybridModules: string[] } {
+	const disabledByFlag = compatibilityFlags.includes(
+		"disable_nodejs_inspector_module"
+	);
+
+	const enabledByFlag =
+		compatibilityFlags.includes("enable_nodejs_inspector_module") &&
+		compatibilityFlags.includes("experimental");
+
+	const enabled = enabledByFlag && !disabledByFlag;
+
+	// When enabled, use the native `inspector` module from workerd
+	return enabled
+		? {
+				nativeModules: ["inspector"],
+				hybridModules: [],
+			}
+		: {
+				nativeModules: [],
+				hybridModules: [],
+			};
+}

packages/wrangler/e2e/unenv-preset/preset.test.ts

@@ -410,6 +410,25 @@ const localTestConfigs: TestConfig[] = [
 			},
 		},
 	],
+	// node:inspector (experimental, no default enable date)
+	[
+		{
+			name: "inspector enabled by flag",
+			compatibilityDate: "2024-09-23",
+			compatibilityFlags: ["enable_nodejs_inspector_module", "experimental"],
+			expectRuntimeFlags: {
+				enable_nodejs_inspector_module: true,
+			},
+		},
+		{
+			name: "inspector disabled by flag",
+			compatibilityDate: "2024-09-23",
+			compatibilityFlags: ["disable_nodejs_inspector_module", "experimental"],
+			expectRuntimeFlags: {
+				enable_nodejs_inspector_module: false,
+			},
+		},
+	],
 ].flat() as TestConfig[];
 
 describe.each(localTestConfigs)(

packages/wrangler/e2e/unenv-preset/worker/index.ts

@@ -728,6 +728,30 @@ export const WorkerdTests: Record<string, () => void> = {
 			createScript: "function",
 		});
 	},
+
+	async testInspector() {
+		const inspector = await import("node:inspector");
+
+		assertTypeOfProperties(inspector, {
+			Session: "function",
+			close: "function",
+			console: "object",
+			open: "function",
+			url: "function",
+			waitForDebugger: "function",
+			Network: "object",
+		});
+
+		assertTypeOfProperties(inspector.default, {
+			Session: "function",
+			close: "function",
+			console: "object",
+			open: "function",
+			url: "function",
+			waitForDebugger: "function",
+			Network: "object",
+		});
+	},
 };
 
 /**