feat: expose inspect and format as the ns:util builtin module

Runtime-provided modules now resolve under the URL-style `ns:` scheme,
ahead of any filesystem or npm resolution, with `node:` compatibility
shims served from the same registry. v1 ships `ns:util` (inspect, format)
and a `node:util` shim that shares its members but is a distinct, frozen
module object.

format() is Node's util.format (%s %d %i %f %j %o %O %%, extras appended
space-separated), and console.* routes its arguments through it, so
`console.log("%d apples", 3)` works while unknown and dangling percent
signs stay verbatim.

Resolution is wired into the CommonJS require path, the ES module resolve
callback and the dynamic-import callback; ESM consumption is served by a
per-realm synthetic module. An unknown name in either scheme fails with
`No such built-in module: <specifier>`, which replaces the warn-and-export-
nothing polyfill previously handed to unshimmed `node:` imports. Bare
specifiers are untouched.

docs/ns-builtin-modules.md is the cross-runtime contract both runtimes
implement.

Author: edusperoni

NativeScript/runtime/Caches.h

@@ -155,6 +155,10 @@ class Caches {
   // console formatter (internal/inspect.js), initialized by Console::Init.
   std::unique_ptr<v8::Persistent<v8::Function>> InspectFunc =
       std::unique_ptr<v8::Persistent<v8::Function>>(nullptr);
+  // ns:util's format, used by console.* for %-substitution.
+  std::unique_ptr<v8::Persistent<v8::Function>> FormatFunc =
+      std::unique_ptr<v8::Persistent<v8::Function>>(nullptr);
+  bool FormatFuncUnavailable = false;
   std::unique_ptr<v8::Persistent<v8::Function>> InteropReferenceCtorFunc =
       std::unique_ptr<v8::Persistent<v8::Function>>(nullptr);
   std::unique_ptr<v8::Persistent<v8::Function>> PointerCtorFunc =
@@ -164,6 +168,16 @@ class Caches {
   std::unique_ptr<v8::Persistent<v8::Function>> UnmanagedTypeCtorFunc =
       std::unique_ptr<v8::Persistent<v8::Function>>(nullptr);
 
+  // `ns:`/`node:` builtin modules (NsBuiltinModules), keyed by specifier. Both
+  // are per isolate: a builtin module is a singleton per realm, so workers get
+  // their own exports objects and their own synthetic modules.
+  robin_hood::unordered_map<std::string,
+                            std::unique_ptr<v8::Persistent<v8::Object>>>
+      BuiltinModuleExports;
+  robin_hood::unordered_map<std::string,
+                            std::unique_ptr<v8::Persistent<v8::Module>>>
+      BuiltinModules;
+
   // Frozen intrinsics snapshot returned by internal/primordials.js, passed to
   // every builtin as its second fixed parameter (BuiltinLoader::RunBuiltin).
   // Per isolate, so workers snapshot their own realm's intrinsics.

NativeScript/runtime/Console.cpp

@@ -11,6 +11,7 @@
 #include "DataWrapper.h"
 #include "Helpers.h"
 #include "NativeScriptException.h"
+#include "NsBuiltinModules.h"
 #include "RuntimeConfig.h"
 // #include "v8-log-agent-impl.h"
 #include <sstream>
@@ -272,6 +273,30 @@ std::string Console::BuildStringFromArgs(
   Isolate* isolate = args.GetIsolate();
   Local<Context> context = isolate->GetCurrentContext();
   int argLen = args.Length();
+
+  // console.* follows Node: the arguments go through util.format, so the first
+  // one may carry %-substitutions and the rest are appended space-separated.
+  Local<v8::Function> format = argLen > startingIndex
+                                   ? NsBuiltinModules::GetFormatFunc(context)
+                                   : Local<v8::Function>();
+  if (!format.IsEmpty()) {
+    std::vector<Local<Value>> formatArgs;
+    formatArgs.reserve(argLen - startingIndex);
+    for (int i = startingIndex; i < argLen; i++) {
+      formatArgs.push_back(args[i]);
+    }
+    TryCatch tc(isolate);
+    Local<Value> result;
+    if (format
+            ->Call(context, v8::Undefined(isolate),
+                   static_cast<int>(formatArgs.size()), formatArgs.data())
+            .ToLocal(&result) &&
+        result->IsString()) {
+      return tns::ToString(isolate, result.As<v8::String>());
+    }
+  }
+
+  // ns:util unavailable or the formatter threw: per-argument rendering.
   std::stringstream ss;
 
   if (argLen > 0) {
@@ -327,6 +352,11 @@ static void GetNativeWrapperHintCallback(
 
 void Console::InitInspect(Local<Context> context) {
   Isolate* isolate = v8::Isolate::GetCurrent();
+  if (Caches::Get(isolate)->InspectFunc != nullptr) {
+    // inspect.js installs a non-configurable global.__inspect, so a second run
+    // in the same realm would throw.
+    return;
+  }
 
   Local<v8::Function> hintFunc;
   if (!v8::Function::New(context, GetNativeWrapperHintCallback)

NativeScript/runtime/Console.h

@@ -14,6 +14,9 @@ class Console {
   static void AttachInspectorClient(
       v8_inspector::JsV8InspectorClient* inspector);
   static void DetachInspectorClient();
+  // Builds this realm's inspect function (Caches::InspectFunc) if it isn't
+  // there yet. Public so ns:util can re-export the same instance.
+  static void InitInspect(v8::Local<v8::Context> context);
 
  private:
   using ConsoleAPIType = v8_inspector::ConsoleAPIType;
@@ -34,7 +37,6 @@ class Console {
   static v8::Local<v8::String> InspectValue(v8::Local<v8::Context> context,
                                             const v8::Local<v8::Value>& val,
                                             int depth = -1);
-  static void InitInspect(v8::Local<v8::Context> context);
   static ConsoleAPIType VerbosityToInspectorMethod(const std::string level);
 
   static void SendToDevToolsFrontEnd(

NativeScript/runtime/ModuleInternal.mm

@@ -11,6 +11,7 @@
 #include "Helpers.h"
 #include "ModuleInternalCallbacks.h"  // for ResolveModuleCallback
 #include "NativeScriptException.h"
+#include "NsBuiltinModules.h"
 #include "Runtime.h"  // for GetAppConfigValue
 #include "RuntimeConfig.h"
 
@@ -214,6 +215,25 @@ bool IsESModule(const std::string& path) {
 void ModuleInternal::RequireCallback(const FunctionCallbackInfo<Value>& info) {
   Isolate* isolate = info.GetIsolate();
 
+  // Builtin modules resolve before any path handling, so they can never be
+  // shadowed by a file or a package, and an unknown one fails as a missing
+  // builtin rather than as a missing file. Only prefixed specifiers get here:
+  // a bare `util` still resolves through npm.
+  if (info.Length() > 0 && info[0]->IsString()) {
+    std::string specifier = tns::ToString(isolate, info[0].As<v8::String>());
+    if (NsBuiltinModules::IsBuiltinScheme(specifier)) {
+      Local<Context> context = isolate->GetCurrentContext();
+      Local<Object> exports;
+      if (NsBuiltinModules::GetExports(context, specifier).ToLocal(&exports)) {
+        info.GetReturnValue().Set(exports);
+      } else if (!NsBuiltinModules::IsRegistered(specifier)) {
+        isolate->ThrowException(Exception::Error(
+            tns::ToV8String(isolate, NsBuiltinModules::NotFoundMessage(specifier))));
+      }
+      return;
+    }
+  }
+
   // Declare these outside try block so they're available in catch
   std::string moduleName;
   std::string callingModuleDirName;

NativeScript/runtime/ModuleInternalCallbacks.mm

@@ -16,6 +16,7 @@
 #include "Helpers.h"         // for tns::Exists
 #include "ModuleInternal.h"  // for LoadScript(...)
 #include "NativeScriptException.h"
+#include "NsBuiltinModules.h"
 #include "Runtime.h"  // for GetAppConfigValue
 #include "RuntimeConfig.h"
 
@@ -715,6 +716,20 @@ static bool IsDocumentsPath(const std::string& path) {
     return v8::MaybeLocal<v8::Module>();
   }
 
+  // Builtin modules resolve before any path handling. Unshimmed "node:" names
+  // fall through to the legacy node:url polyfill below.
+  if (NsBuiltinModules::IsRegistered(rawSpec) || NsBuiltinModules::IsNsScheme(rawSpec)) {
+    v8::Local<v8::Module> builtin;
+    if (NsBuiltinModules::GetModule(context, rawSpec).ToLocal(&builtin)) {
+      return v8::MaybeLocal<v8::Module>(builtin);
+    }
+    if (!NsBuiltinModules::IsRegistered(rawSpec)) {
+      isolate->ThrowException(v8::Exception::Error(
+          tns::ToV8String(isolate, NsBuiltinModules::NotFoundMessage(rawSpec))));
+    }
+    return v8::MaybeLocal<v8::Module>();
+  }
+
   std::string normalizedSpec = rawSpec;
 
   // Normalize malformed HTTP(S) schemes that sometimes appear as 'http:/host' (single slash)
@@ -1344,11 +1359,9 @@ static bool IsDocumentsPath(const std::string& path) {
                           "  return new URL('file://' + encoded);\n"
                           "}\n";
       } else {
-        // Generic polyfill for other Node.js built-in modules
-        polyfillContent = "// In-memory polyfill for node:" + builtinName + "\n" +
-                          "console.warn('Node.js built-in module \\'node:" + builtinName +
-                          "\\' is not fully supported in NativeScript');\n" +
-                          "export default {};\n";
+        isolate->ThrowException(v8::Exception::Error(
+            tns::ToV8String(isolate, NsBuiltinModules::NotFoundMessage(spec))));
+        return v8::MaybeLocal<v8::Module>();
       }
 
       v8::MaybeLocal<v8::Module> m =
@@ -1862,6 +1875,29 @@ static bool IsDocumentsPath(const std::string& path) {
   // Normalize spec: expand '@/'; only strip ?query/hash for non-HTTP specs so SFC HTTP keys keep
   // version tags
   std::string rawSpec = cSpec ? std::string(cSpec) : std::string();
+
+  // Builtin modules never reach the loader below; the namespace comes straight
+  // from the realm's synthetic module.
+  if (NsBuiltinModules::IsRegistered(rawSpec) || NsBuiltinModules::IsNsScheme(rawSpec)) {
+    v8::EscapableHandleScope builtinScope(isolate);
+    v8::Local<v8::Promise::Resolver> builtinResolver;
+    if (!v8::Promise::Resolver::New(context).ToLocal(&builtinResolver)) {
+      return v8::MaybeLocal<v8::Promise>();
+    }
+    v8::TryCatch tc(isolate);
+    v8::Local<v8::Module> builtin;
+    if (NsBuiltinModules::GetModule(context, rawSpec).ToLocal(&builtin)) {
+      builtinResolver->Resolve(context, builtin->GetModuleNamespace()).FromMaybe(false);
+    } else {
+      v8::Local<v8::Value> error = tc.HasCaught()
+                                       ? tc.Exception()
+                                       : v8::Exception::Error(tns::ToV8String(
+                                             isolate, NsBuiltinModules::NotFoundMessage(rawSpec)));
+      builtinResolver->Reject(context, error).FromMaybe(false);
+    }
+    return builtinScope.Escape(builtinResolver->GetPromise());
+  }
+
   std::string normalizedSpec = rawSpec;
   // remove query/hash ONLY for non-HTTP specs
   bool isHttpLike = (!normalizedSpec.empty() && (StartsWith(normalizedSpec, "http://") ||