Added NodeJS inspector

Author: Segfaultd

code/framework/CMakeLists.txt

@@ -205,6 +205,9 @@ macro(link_shared_deps target_name)
     endif()
 endmacro()
 
+# Node.js inspector support for script debugging (auto-enabled for Debug builds)
+option(FW_NODE_INSPECTOR "Enable Node.js inspector for script debugging" OFF)
+
 # FrameworkNodeEngine - Object library for node_engine.cpp
 # This is separate because it needs NODE_WANT_INTERNALS and libuv headers which
 # cause Windows SDK errno conflicts (EINVAL/ERANGE undefined) when applied to PCH.
@@ -235,6 +238,10 @@ target_compile_definitions(FrameworkNodeEngine PRIVATE NODE_WANT_INTERNALS=1)
 target_compile_definitions(FrameworkNodeEngine PRIVATE MG_ENABLE_LOG=0)
 target_compile_features(FrameworkNodeEngine PRIVATE cxx_std_20)
 
+# Node.js inspector: enabled via explicit option OR Debug builds
+target_compile_definitions(FrameworkNodeEngine PRIVATE
+    $<$<OR:$<BOOL:${FW_NODE_INSPECTOR}>,$<CONFIG:Debug>>:FW_NODE_INSPECTOR>)
+
 # Link the solutions based on the platform
 link_shared_deps(Framework)
 target_link_libraries(Framework v8 v8pp libnode)
@@ -245,10 +252,14 @@ target_sources(Framework PRIVATE $<TARGET_OBJECTS:FrameworkNodeEngine>)
 if(WIN32)
     link_shared_deps(FrameworkClient)
     target_link_libraries(FrameworkClient v8 v8pp libnode)
+    target_compile_definitions(FrameworkClient PRIVATE
+        $<$<OR:$<BOOL:${FW_NODE_INSPECTOR}>,$<CONFIG:Debug>>:FW_NODE_INSPECTOR>)
 endif()
 
 link_shared_deps(FrameworkServer)
 target_link_libraries(FrameworkServer v8 v8pp MafiaHubServices libsig libnode)
+target_compile_definitions(FrameworkServer PRIVATE
+    $<$<OR:$<BOOL:${FW_NODE_INSPECTOR}>,$<CONFIG:Debug>>:FW_NODE_INSPECTOR>)
 
 # FrameworkServer-specific includes
 target_include_directories(FrameworkServer PRIVATE

code/framework/src/integrations/client/scripting/module.cpp

@@ -19,6 +19,10 @@ namespace Framework::Integrations::Client::Scripting {
         Framework::Scripting::NodeEngineOptions options;
         options.sandboxed = true;
         options.processName = "mafiahub-client";
+#ifdef FW_NODE_INSPECTOR
+        options.enableInspector = true;
+        options.inspectorPort = 9230;
+#endif
         _nodeEngine = std::make_unique<Framework::Scripting::NodeEngine>(options);
     }
 

code/framework/src/integrations/server/scripting/module.cpp

@@ -17,6 +17,10 @@ namespace Framework::Integrations::Server::Scripting {
         Framework::Scripting::NodeEngineOptions options;
         options.sandboxed = false;
         options.processName = "mafiahub-server";
+#ifdef FW_NODE_INSPECTOR
+        options.enableInspector = true;
+        options.inspectorPort = 9229;
+#endif
         _nodeEngine = std::make_unique<Framework::Scripting::NodeEngine>(options);
     }
 

code/framework/src/scripting/node_engine.cpp

@@ -1,6 +1,8 @@
 #include "node_engine.h"
 #include "builtins/messages.h"
 
+#include <spdlog/spdlog.h>
+
 #include <filesystem>
 #include <fstream>
 #include <sstream>
@@ -143,6 +145,14 @@ namespace Framework::Scripting {
         // Build args from options
         std::vector<std::string> nodeArgs = {_options.processName};
 
+#ifdef FW_NODE_INSPECTOR
+        if (_options.enableInspector) {
+            std::string flag = _options.inspectorWaitForDebugger ? "--inspect-brk=" : "--inspect=";
+            flag += _options.inspectorHost + ":" + std::to_string(_options.inspectorPort);
+            nodeArgs.push_back(flag);
+        }
+#endif
+
         // Initialize Node.js with flags to control V8 platform ourselves
         // Using initializer_list syntax as shown in Node.js docs
         _initResult = node::InitializeOncePerProcess(
@@ -168,6 +178,13 @@ namespace Framework::Scripting {
         v8::V8::Initialize();
 
         _platformInitialized = true;
+
+#ifdef FW_NODE_INSPECTOR
+        if (_options.enableInspector) {
+            spdlog::info("Node.js inspector listening on {}:{}", _options.inspectorHost, _options.inspectorPort);
+        }
+#endif
+
         return true;
     }
 
@@ -358,8 +375,6 @@ namespace Framework::Scripting {
         // Other dangerous modules
         'vm', 'node:vm',
         'v8', 'node:v8',
-        'inspector', 'node:inspector',
-        'inspector/promises', 'node:inspector/promises',
         'trace_events', 'node:trace_events',
         'perf_hooks', 'node:perf_hooks',
         'async_hooks', 'node:async_hooks',
@@ -490,14 +505,31 @@ namespace Framework::Scripting {
     // This is also set at the C++ level but we reinforce it here
     // Note: This would require context-level settings which we do in C++
 
+    // Block inspector module unless explicitly enabled for debugging
+    if (!globalThis.__INSPECTOR_ENABLED__) {
+        blockedModules.add('inspector');
+        blockedModules.add('node:inspector');
+        blockedModules.add('inspector/promises');
+        blockedModules.add('node:inspector/promises');
+    }
+
     // Mark sandbox as applied
     globalThis.__SANDBOX_APPLIED__ = true;
 })();
 )JS";
 
-        v8::TryCatch tryCatch(_isolate);
         v8::Local<v8::Context> context = _setup->context();
 
+        // Set inspector flag before sandbox code runs so it can conditionally
+        // allow the inspector module for debugging
+        if (_options.enableInspector) {
+            v8::Local<v8::String> key =
+                v8::String::NewFromUtf8(_isolate, "__INSPECTOR_ENABLED__").ToLocalChecked();
+            context->Global()->Set(context, key, v8::Boolean::New(_isolate, true)).Check();
+        }
+
+        v8::TryCatch tryCatch(_isolate);
+
         v8::Local<v8::String> source =
             v8::String::NewFromUtf8(_isolate, sandboxCode).ToLocalChecked();
         v8::ScriptOrigin origin(

code/framework/src/scripting/node_engine.h

@@ -39,6 +39,27 @@ namespace Framework::Scripting {
          * Process name shown in Node.js (argv[0]).
          */
         std::string processName = "mafiahub";
+
+        /**
+         * Enable the Node.js inspector agent for debugging.
+         * Only effective when compiled with FW_NODE_INSPECTOR define.
+         */
+        bool enableInspector = false;
+
+        /**
+         * Port for the inspector agent to listen on.
+         */
+        int inspectorPort = 9229;
+
+        /**
+         * Host for the inspector agent to bind to.
+         */
+        std::string inspectorHost = "127.0.0.1";
+
+        /**
+         * If true, pause execution at start until a debugger connects.
+         */
+        bool inspectorWaitForDebugger = false;
     };
 
     /**