vfs: add SEA (Single Executable Application) integration

Add support for accessing SEA embedded assets through the VFS:

- Add lib/internal/vfs/sea.js with createSeaVfs() and getSeaVfs() functions
- Add fs.getSeaVfs() to get a VFS populated with SEA assets
- Add fs.hasSeaAssets() to check if SEA assets are available
- SEA assets are mounted at /sea by default (configurable via prefix option)
- Document SEA integration in fs.md

This allows SEA applications to access embedded assets using standard fs
APIs instead of the lower-level sea.getAsset() API.

Author: mcollina

doc/api/fs.md

@@ -8695,6 +8695,85 @@ for await (const file of glob('/virtual/src/**/*.js')) {
 }
 ```
 
+### SEA (Single Executable Application) integration
+
+When running as a Single Executable Application, the VFS can automatically
+provide access to embedded assets through standard file system APIs.
+
+#### `fs.hasSeaAssets()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {boolean}
+
+Returns `true` if running as a SEA with embedded assets, `false` otherwise.
+
+```cjs
+const fs = require('node:fs');
+
+if (fs.hasSeaAssets()) {
+  console.log('Running as SEA with assets');
+}
+```
+
+#### `fs.getSeaVfs([options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `options` {Object}
+  * `prefix` {string} Mount point prefix for SEA assets. **Default:** `'/sea'`.
+  * `moduleHooks` {boolean} Whether to enable require/import hooks.
+    **Default:** `true`.
+* Returns: {VirtualFileSystem|null}
+
+Returns a VFS populated with all SEA embedded assets, mounted at the specified
+prefix. Returns `null` if not running as a SEA or if there are no assets.
+
+The VFS is a singleton - subsequent calls return the same instance (options
+are only used on the first call).
+
+```cjs
+const fs = require('node:fs');
+
+// In a SEA with an embedded 'config.json' asset:
+const seaVfs = fs.getSeaVfs();
+if (seaVfs) {
+  // Access embedded assets via standard fs APIs
+  const config = fs.readFileSync('/sea/config.json', 'utf8');
+  console.log(JSON.parse(config));
+
+  // Or require modules from embedded assets
+  const utils = require('/sea/utils.js');
+}
+```
+
+To use SEA assets, first configure them in your SEA configuration file:
+
+```json
+{
+  "main": "app.js",
+  "output": "app.blob",
+  "assets": {
+    "config.json": "path/to/config.json",
+    "utils.js": "path/to/utils.js"
+  }
+}
+```
+
+Then access them via the VFS:
+
+```cjs
+const fs = require('node:fs');
+const seaVfs = fs.getSeaVfs();
+
+// Assets are accessible at /sea/<asset-key>
+const config = fs.readFileSync('/sea/config.json', 'utf8');
+```
+
 ### Limitations
 
 The current VFS implementation has the following limitations:

lib/fs.js

@@ -3207,18 +3207,42 @@ function globSync(pattern, options) {
 }
 
 const lazyVfs = getLazy(() => require('internal/vfs/virtual_fs').VirtualFileSystem);
+const lazySeaVfs = getLazy(() => require('internal/vfs/sea'));
 
 /**
  * Creates a new virtual file system instance.
  * @param {object} [options] Configuration options
  * @param {boolean} [options.fallthrough=true] Whether to fall through to real fs on miss
+ * @param {boolean} [options.moduleHooks=true] Whether to enable require/import hooks
  * @returns {VirtualFileSystem}
  */
 function createVirtual(options) {
   const VirtualFileSystem = lazyVfs();
   return new VirtualFileSystem(options);
 }
 
+/**
+ * Gets the VFS containing SEA (Single Executable Application) assets.
+ * Returns null if not running as a SEA or if there are no assets.
+ * @param {object} [options] Configuration options
+ * @param {string} [options.prefix='/sea'] Mount point prefix for SEA assets
+ * @param {boolean} [options.moduleHooks=true] Whether to enable require/import hooks
+ * @returns {VirtualFileSystem|null}
+ */
+function getSeaVfs(options) {
+  const { getSeaVfs: getSeaVfsInternal } = lazySeaVfs();
+  return getSeaVfsInternal(options);
+}
+
+/**
+ * Checks if SEA assets are available.
+ * @returns {boolean}
+ */
+function hasSeaAssets() {
+  const { hasSeaAssets: hasSeaAssetsInternal } = lazySeaVfs();
+  return hasSeaAssetsInternal();
+}
+
 module.exports = fs = {
   appendFile,
   appendFileSync,
@@ -3237,6 +3261,8 @@ module.exports = fs = {
   createReadStream,
   createVirtual,
   createWriteStream,
+  getSeaVfs,
+  hasSeaAssets,
   exists,
   existsSync,
   fchown,

lib/internal/vfs/sea.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const {
+  StringPrototypeStartsWith,
+} = primordials;
+
+const { isSea, getAsset, getAssetKeys } = require('sea');
+
+// Lazy-loaded VFS
+let cachedSeaVfs = null;
+
+/**
+ * Creates a VirtualFileSystem populated with SEA assets.
+ * Assets are mounted at the specified prefix (default: '/sea').
+ * @param {object} [options] Configuration options
+ * @param {string} [options.prefix='/sea'] Mount point prefix for SEA assets
+ * @param {boolean} [options.moduleHooks=true] Whether to enable require/import hooks
+ * @returns {VirtualFileSystem|null} The VFS instance, or null if not running as SEA
+ */
+function createSeaVfs(options = {}) {
+  if (!isSea()) {
+    return null;
+  }
+
+  const { VirtualFileSystem } = require('internal/vfs/virtual_fs');
+  const prefix = options.prefix ?? '/sea';
+  const moduleHooks = options.moduleHooks !== false;
+
+  const vfs = new VirtualFileSystem({ moduleHooks });
+
+  // Get all asset keys and populate VFS
+  const keys = getAssetKeys();
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    // Get asset content as ArrayBuffer and convert to Buffer
+    const content = getAsset(key);
+    const buffer = Buffer.from(content);
+
+    // Determine the path - if key starts with /, use as-is, otherwise prepend /
+    const path = StringPrototypeStartsWith(key, '/') ? key : `/${key}`;
+    vfs.addFile(path, buffer);
+  }
+
+  // Mount at the specified prefix
+  vfs.mount(prefix);
+
+  return vfs;
+}
+
+/**
+ * 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
+ */
+function getSeaVfs(options) {
+  if (cachedSeaVfs === null) {
+    cachedSeaVfs = createSeaVfs(options);
+  }
+  return cachedSeaVfs;
+}
+
+/**
+ * Checks if SEA VFS is available (i.e., running as SEA with assets).
+ * @returns {boolean}
+ */
+function hasSeaAssets() {
+  if (!isSea()) {
+    return false;
+  }
+  const keys = getAssetKeys();
+  return keys.length > 0;
+}
+
+module.exports = {
+  createSeaVfs,
+  getSeaVfs,
+  hasSeaAssets,
+};

test/parallel/test-vfs-sea.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+
+// Test that SEA functions exist
+assert.strictEqual(typeof fs.getSeaVfs, 'function');
+assert.strictEqual(typeof fs.hasSeaAssets, 'function');
+
+// Test that SEA functions return appropriate values when not in SEA
+{
+  // hasSeaAssets should return false when not running as SEA
+  const hasAssets = fs.hasSeaAssets();
+  assert.strictEqual(hasAssets, false);
+
+  // getSeaVfs should return null when not running as SEA
+  const seaVfs = fs.getSeaVfs();
+  assert.strictEqual(seaVfs, null);
+}
+
+// Test with custom options (should still return null when not in SEA)
+{
+  const seaVfs = fs.getSeaVfs({ prefix: '/custom-sea', moduleHooks: false });
+  assert.strictEqual(seaVfs, null);
+}