vfs: refactor SEA VFS with initSeaVfs/getSeaVfs pattern

Separate initialization from retrieval for cleaner API:
- initSeaVfs(options): Initialize with custom options, throws if
  called twice (ERR_INVALID_STATE)
- getSeaVfs(): Get VFS instance, auto-initializes with defaults
  if not yet initialized

This is an internal-only API change; the public behavior remains
the same (SEA VFS auto-initializes at startup).

PR-URL: #61478

Author: mcollina

lib/internal/vfs/sea.js

@@ -4,13 +4,13 @@ const { isSea, getAssetKeys } = internalBinding('sea');
 const { kEmptyObject, getLazy } = require('internal/util');
 const {
   codes: {
-    ERR_INVALID_ARG_VALUE,
+    ERR_INVALID_STATE,
   },
 } = require('internal/errors');
 
 // Lazy-loaded VFS
 let cachedSeaVfs = null;
-let cachedSeaVfsPrefix = null;
+let initialized = false;
 
 // Lazy-load VirtualFileSystem and SEAProvider to avoid loading VFS code if not needed
 const lazyVirtualFileSystem = getLazy(
@@ -21,8 +21,9 @@ const lazySEAProvider = getLazy(
 );
 
 /**
- * Creates a VirtualFileSystem populated with SEA assets using the new Provider architecture.
+ * Creates a VirtualFileSystem populated with SEA assets using the Provider architecture.
  * Assets are mounted at the specified prefix (default: '/sea').
+ * This is an internal function - use initSeaVfs() or getSeaVfs() instead.
  * @param {object} [options] Configuration options
  * @param {string} [options.prefix] Mount point prefix for SEA assets
  * @param {boolean} [options.moduleHooks] Whether to enable require/import hooks
@@ -55,29 +56,39 @@ function createSeaVfs(options = kEmptyObject) {
 }
 
 /**
- * Gets or creates the default SEA VFS instance.
- * This is a singleton that is lazily created on first access.
- * @param {object} [options] Configuration options (only used on first call)
- * @returns {VirtualFileSystem|null} The VFS instance, or null if not running as SEA
- * @throws {ERR_INVALID_ARG_VALUE} If called with a different prefix than the first call
+ * Initializes the SEA VFS with custom options.
+ * Must be called before getSeaVfs() if custom options are needed.
+ * @param {object} [options] Configuration options
+ * @param {string} [options.prefix] Mount point prefix for SEA assets (default: '/sea')
+ * @param {boolean} [options.moduleHooks] Whether to enable require/import hooks (default: true)
+ * @returns {VirtualFileSystem|null} The VFS instance, or null if not running as SEA or no assets
+ * @throws {ERR_INVALID_STATE} If already initialized
  */
-function getSeaVfs(options) {
-  const prefix = options?.prefix ?? '/sea';
+function initSeaVfs(options = kEmptyObject) {
+  if (initialized) {
+    throw new ERR_INVALID_STATE('SEA VFS is already initialized');
+  }
 
-  if (cachedSeaVfs === null) {
-    cachedSeaVfs = createSeaVfs(options);
-    cachedSeaVfsPrefix = prefix;
-  } else if (prefix !== cachedSeaVfsPrefix) {
-    throw new ERR_INVALID_ARG_VALUE(
-      'options.prefix',
-      prefix,
-      `SEA VFS is already initialized with prefix '${cachedSeaVfsPrefix}'`,
-    );
+  initialized = true;
+  cachedSeaVfs = createSeaVfs(options);
+  return cachedSeaVfs;
+}
+
+/**
+ * Gets the SEA VFS instance.
+ * If not already initialized, auto-initializes with default options.
+ * @returns {VirtualFileSystem|null} The VFS instance, or null if not running as SEA or no assets
+ */
+function getSeaVfs() {
+  if (!initialized) {
+    initialized = true;
+    cachedSeaVfs = createSeaVfs();
   }
   return cachedSeaVfs;
 }
 
 module.exports = {
   createSeaVfs,
+  initSeaVfs,
   getSeaVfs,
 };