@volter/tabnode 0.5.4 → 0.5.5

package/dist/assets/{runtime-worker-DBtzjAkn.js → runtime-worker-iInsmIAS.js}

@@ -6641,6 +6641,14 @@ var asyncHooksShim$1 = /* @__PURE__ */ Object.freeze({
   executionAsyncResource,
   triggerAsyncId
 });
+function describedIdentity(identity) {
+  const { pid, ppid, argv, cwd, startedAt } = identity;
+  const described = { pid, ppid };
+  if (Array.isArray(argv) && argv.length <= 4096 && argv.every((arg) => typeof arg === "string")) described.argv = Object.freeze([...argv]);
+  if (typeof cwd === "string" && cwd.startsWith("/")) described.cwd = cwd;
+  if (typeof startedAt === "number" && Number.isFinite(startedAt)) described.startedAt = startedAt;
+  return Object.freeze(described);
+}
 function createProcessRegistryOwner() {
   let nextPid2 = 1e3 + Math.floor(Math.random() * 3e4);
   const live = /* @__PURE__ */ new Map();
@@ -6697,7 +6705,7 @@ function createProcessRegistryOwner() {
           if (identity.ppid !== 0 && !Array.from(runs2.values()).some((parent) => parent.pid === identity.ppid)) {
             throw new Error("Parent process is not owned by this realm.");
           }
-          const entry = Object.freeze({ pid: identity.pid, ppid: identity.ppid });
+          const entry = describedIdentity(identity);
           runs2.set(token, entry);
           live.set(entry.pid, entry);
           receivers.set(entry.pid, receiver);
@@ -6739,6 +6747,10 @@ function createProcessRegistryOwner() {
       };
       scopes.set(scope, { allocated, runs: runs2, active: active2 });
       return scope;
+    },
+    /** Every live process of the container, in pid order: what `/proc` lists. */
+    table() {
+      return [...live.values()].sort((a, b) => a.pid - b.pid);
     }
   };
 }
@@ -6779,8 +6791,8 @@ const pidsOfRuns = /* @__PURE__ */ new Map();
 function mintPid() {
   return processRegistry.allocate();
 }
-function setRunPid(token, pid, ppid) {
-  processRegistry.publish(token, { pid, ppid });
+function setRunPid(token, pid, ppid, started) {
+  processRegistry.publish(token, { pid, ppid, ...started, startedAt: Date.now() });
   pidsOfRuns.set(token, { pid, ppid });
 }
 function runPid(token) {
@@ -9657,7 +9669,7 @@ function createUtilBinding(require2) {
 const bufferModule = lazyModule("buffer");
 const Buffer$9 = lazyExport("buffer", "Buffer");
 function createNodeError$1(code2, syscall, path2) {
-  const known = ["EEXIST", "EINVAL", "EISDIR", "ENOENT", "ENOTDIR", "ENOTEMPTY", "ELOOP"];
+  const known = ["EEXIST", "EINVAL", "EISDIR", "ENOENT", "ENOTDIR", "ENOTEMPTY", "ELOOP", "EROFS"];
   if (known.includes(code2)) return createNodeError(code2, syscall, path2);
   return Object.assign(new Error(`${code2}: ${syscall} '${path2}'`), { code: code2, syscall, path: path2, errno: -9 });
 }
@@ -27571,14 +27583,16 @@ function createNodeError(code2, syscall, path2, message) {
     ENOTDIR: -20,
     EISDIR: -21,
     EEXIST: -17,
-    ENOTEMPTY: -39
+    ENOTEMPTY: -39,
+    EROFS: -30
   };
   const messages2 = {
     ENOENT: "no such file or directory",
     ENOTDIR: "not a directory",
     EISDIR: "is a directory",
     EEXIST: "file already exists",
-    ENOTEMPTY: "directory not empty"
+    ENOTEMPTY: "directory not empty",
+    EROFS: "read-only file system"
   };
   const err2 = new Error(
     `${code2}: ${messages2[code2]}, ${syscall} '${path2}'`
@@ -27637,6 +27651,7 @@ class VirtualFS {
     return { files };
   }
   serializeNode(path2, node, files) {
+    if (node.mount) return;
     if (node.type === "file") {
       let content = "";
       if (node.content && node.content.length > 0) {
@@ -27692,6 +27707,7 @@ class VirtualFS {
    */
   writeFileSyncInternal(path2, data2, emitEvent) {
     const normalized = this.normalizePath(path2);
+    this.assertWritable(normalized, "open");
     const parentPath = this.getParentPath(normalized);
     const basename = this.getBasename(normalized);
     if (!basename) {
@@ -27767,11 +27783,12 @@ class VirtualFS {
     if (depth > 40) throw createNodeError("ELOOP", "stat", path2);
     const segments = this.getPathSegments(path2);
     let current3 = this.root;
+    let mounted;
     for (let index2 = 0; index2 < segments.length; index2 += 1) {
-      if (current3.type !== "directory" || !current3.children) {
+      if (current3.type !== "directory" || !mounted && !current3.children) {
         return void 0;
       }
-      const child = current3.children.get(segments[index2]);
+      const child = mounted ? mounted.tree.node("/" + segments.slice(mounted.at + 1, index2 + 1).join("/")) : current3.children.get(segments[index2]);
       if (!child) {
         return void 0;
       }
@@ -27781,16 +27798,53 @@ class VirtualFS {
         const target = this.__substrateLinkTarget(linkPath, child.target);
         return this.__substrateNode(rest ? target + "/" + rest : target, follow, depth + 1);
       }
-      current3 = child;
+      if (!mounted && child.mount) {
+        mounted = { tree: child.mount, at: index2 };
+        current3 = child.mount.node("/") ?? child;
+      } else {
+        current3 = child;
+      }
     }
     return current3;
   }
+  /**
+   * Mount a read-only tree at a directory, as Linux mounts `/proc`: reads
+   * below it are the tree's answers, writes fail with `EROFS`, and a snapshot
+   * leaves it out. Answers the unmount.
+   */
+  mount(path2, tree2) {
+    var _a3;
+    const normalized = this.normalizePath(path2);
+    const basename = this.getBasename(normalized);
+    if (!basename) throw createNodeError("EINVAL", "mount", path2);
+    const parent = this.ensureDirectory(this.getParentPath(normalized));
+    const existing = parent.children.get(basename);
+    if (existing && (existing.type !== "directory" || existing.mount || ((_a3 = existing.children) == null ? void 0 : _a3.size))) {
+      throw createNodeError("EEXIST", "mount", path2);
+    }
+    const node = { type: "directory", children: /* @__PURE__ */ new Map(), mtime: Date.now(), mode: 365, mount: tree2 };
+    parent.children.set(basename, node);
+    return () => {
+      if (parent.children.get(basename) === node) parent.children.delete(basename);
+    };
+  }
+  /** A write at or below a mount point is refused, as a read-only filesystem refuses it. */
+  assertWritable(path2, syscall) {
+    var _a3;
+    let current3 = this.root;
+    for (const segment of this.getPathSegments(path2)) {
+      current3 = (_a3 = current3 == null ? void 0 : current3.children) == null ? void 0 : _a3.get(segment);
+      if (!current3) return;
+      if (current3.mount) throw createNodeError("EROFS", syscall, path2);
+    }
+  }
   /** A link's target as an absolute path: absolute as written, or relative to the link's directory. */
   __substrateLinkTarget(linkPath, target) {
     return this.normalizePath(target.startsWith("/") ? target : this.getParentPath(linkPath) + "/" + target);
   }
   symlinkSync(target, path2) {
     const normalized = this.normalizePath(path2);
+    this.assertWritable(normalized, "symlink");
     const parentPath = this.getParentPath(normalized);
     const basename = this.getBasename(normalized);
     const parent = this.getNode(parentPath);
@@ -27851,11 +27905,13 @@ class VirtualFS {
    * Get stats for path
    */
   chmodSync(path2, mode) {
+    this.assertWritable(path2, "chmod");
     const node = this.getNode(path2);
     if (!node) throw createNodeError("ENOENT", "chmod", path2);
     node.mode = mode & 4095;
   }
   utimesSync(path2, atime, mtime) {
+    this.assertWritable(path2, "utime");
     const node = this.getNode(path2);
     if (!node) throw createNodeError("ENOENT", "utimes", path2);
     node.atime = atime instanceof Date ? atime.getTime() : atime * 1e3;
@@ -27961,7 +28017,10 @@ class VirtualFS {
    * Create directory, optionally with recursive parent creation
    */
   mkdirSync(path2, options) {
+    var _a3;
     const normalized = this.normalizePath(path2);
+    if ((options == null ? void 0 : options.recursive) && ((_a3 = this.getNode(normalized)) == null ? void 0 : _a3.type) === "directory") return;
+    this.assertWritable(normalized, "mkdir");
     if (options == null ? void 0 : options.recursive) {
       this.ensureDirectory(normalized);
       return;
@@ -28006,6 +28065,7 @@ class VirtualFS {
    */
   unlinkSync(path2) {
     const normalized = this.normalizePath(path2);
+    this.assertWritable(normalized, "unlink");
     const parentPath = this.getParentPath(normalized);
     const basename = this.getBasename(normalized);
     const parent = this.getNode(parentPath);
@@ -28028,6 +28088,7 @@ class VirtualFS {
    */
   rmdirSync(path2) {
     const normalized = this.normalizePath(path2);
+    this.assertWritable(normalized, "rmdir");
     const parentPath = this.getParentPath(normalized);
     const basename = this.getBasename(normalized);
     if (!basename) {
@@ -28056,6 +28117,8 @@ class VirtualFS {
   renameSync(oldPath, newPath) {
     const normalizedOld = this.normalizePath(oldPath);
     const normalizedNew = this.normalizePath(newPath);
+    this.assertWritable(normalizedOld, "rename");
+    this.assertWritable(normalizedNew, "rename");
     const oldParentPath = this.getParentPath(normalizedOld);
     const oldBasename = this.getBasename(normalizedOld);
     const newParentPath = this.getParentPath(normalizedNew);
@@ -28154,10 +28217,12 @@ class VirtualFS {
     for (let hops = 0; hops <= 40; hops += 1) {
       const segments = resolved.split("/").filter(Boolean);
       let current3 = this.root;
+      let mounted;
       let linked = false;
       for (let index2 = 0; index2 < segments.length; index2 += 1) {
-        const child = current3 && current3.children ? current3.children.get(segments[index2]) : void 0;
+        const child = mounted ? mounted.tree.node("/" + segments.slice(mounted.at + 1, index2 + 1).join("/")) : current3 && current3.children ? current3.children.get(segments[index2]) : void 0;
         if (!child) throw createNodeError("ENOENT", "realpath", path2);
+        if (!mounted && child.mount) mounted = { tree: child.mount, at: index2 };
         if (child.type === "symlink") {
           const linkPath = "/" + segments.slice(0, index2 + 1).join("/");
           const rest = segments.slice(index2 + 1).join("/");
@@ -69753,7 +69818,7 @@ const _runStreams = /* @__PURE__ */ new Map();
 async function runHostedNode(host, launch) {
   var _a3;
   const { token, streams } = launch;
-  if (!runPid(token)) setRunPid(token, mintPid(), 0);
+  if (!runPid(token)) setRunPid(token, mintPid(), 0, { argv: ["node", ...launch.argv], cwd: launch.cwd });
   let input;
   try {
     (_a3 = streams == null ? void 0 : streams.signal) == null ? void 0 : _a3.throwIfAborted();
@@ -69989,7 +70054,7 @@ function initChildProcess(vfs2) {
       ...runPid(runToken) ? { pid: runPid(runToken).pid, ppid: runPid(runToken).ppid } : {}
     });
     const proc = runtime2.getProcess();
-    if (runToken !== null) setRunPid(runToken, proc.pid, proc.ppid);
+    if (runToken !== null) setRunPid(runToken, proc.pid, proc.ppid, { argv: ["node", ...args], cwd: ctx.cwd });
     const releaseRun = runToken === null ? null : __recordRun(runToken, {
       process: proc,
       stdout: appendStdout,
@@ -70715,7 +70780,12 @@ function startChildRun(request) {
   var _a3;
   const token = `child-${__nextChildRun++}`;
   const pid = mintPid();
-  setRunPid(token, pid, ((_a3 = runPid(__currentProcessToken() ?? __lastLaunchedToken)) == null ? void 0 : _a3.pid) ?? 0);
+  setRunPid(
+    token,
+    pid,
+    ((_a3 = runPid(__currentProcessToken() ?? __lastLaunchedToken)) == null ? void 0 : _a3.pid) ?? 0,
+    { argv: request.args.length ? request.args : [request.file], ...request.cwd ? { cwd: request.cwd } : {} }
+  );
   const controller = new AbortController();
   const pendingStdin = [];
   const admittedNode = nodeProcessHostInstalled();

package/dist/index.d.ts

@@ -9,7 +9,7 @@
  */
 export { restoreHostGlobals, guestRealmInstalled } from './host-globals';
 export { VirtualFS } from './virtual-fs';
-export type { FSNode, Stats, FSWatcher, WatchListener, WatchEventType } from './virtual-fs';
+export type { FSNode, MountedTree, Stats, FSWatcher, WatchListener, WatchEventType } from './virtual-fs';
 export { Runtime, execute } from './runtime';
 export type { Module, RuntimeOptions, RequireFunction } from './runtime';
 export { createRuntime, WorkerRuntime } from './create-runtime';
@@ -46,7 +46,7 @@ import { ServerBridge } from './server-bridge';
 import { type Socket as NetSocket } from './node-lib/net-module';
 import { runPid, processByPid } from './process-tokens';
 export { runPid, processByPid };
-export { createProcessRegistryScope, installProcessRegistry, ownerProcessRegistryScope } from './process-tokens';
+export { createProcessRegistryScope, installProcessRegistry, ownerProcessRegistryScope, ownerProcessTable } from './process-tokens';
 export { installNodeProcessHost, nodeProcessHostInstalled } from './node-process-host';
 export type { NodeProcessLaunch, NodeProcessHost } from './node-process-host';
 export type { ProcessIdentity, ProcessRegistry, ProcessRegistryScope, InitialProcessRegistration } from './process-registry';
@@ -112,6 +112,10 @@ export declare function createContainer(options?: ContainerOptions): {
     run: (command: string, options?: RunOptions) => Promise<RunResult>;
     pendingTimers: (token: string) => number;
     processPorts: (token: string) => number[];
+    /** The pid of the process listening on a port of this engine, where a guest process is: `/proc`'s socket owner. */
+    portPid: (port: number) => number | undefined;
+    /** Deliver a signal to the named run as another process's `kill(pid)` does; false when the run is gone. */
+    signalProcess: (token: string, signal: string) => boolean;
     stopProcess: (token: string) => boolean;
     /**
      * Input for one run's guest, by its process token; without a token, the most

package/dist/index.mjs

@@ -6350,6 +6350,14 @@ const asyncHooksShim$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.de
   executionAsyncResource,
   triggerAsyncId
 }, Symbol.toStringTag, { value: "Module" }));
+function describedIdentity(identity) {
+  const { pid, ppid, argv, cwd, startedAt } = identity;
+  const described = { pid, ppid };
+  if (Array.isArray(argv) && argv.length <= 4096 && argv.every((arg) => typeof arg === "string")) described.argv = Object.freeze([...argv]);
+  if (typeof cwd === "string" && cwd.startsWith("/")) described.cwd = cwd;
+  if (typeof startedAt === "number" && Number.isFinite(startedAt)) described.startedAt = startedAt;
+  return Object.freeze(described);
+}
 function createProcessRegistryOwner() {
   let nextPid2 = 1e3 + Math.floor(Math.random() * 3e4);
   const live = /* @__PURE__ */ new Map();
@@ -6406,7 +6414,7 @@ function createProcessRegistryOwner() {
           if (identity.ppid !== 0 && !Array.from(runs2.values()).some((parent) => parent.pid === identity.ppid)) {
             throw new Error("Parent process is not owned by this realm.");
           }
-          const entry = Object.freeze({ pid: identity.pid, ppid: identity.ppid });
+          const entry = describedIdentity(identity);
           runs2.set(token, entry);
           live.set(entry.pid, entry);
           receivers.set(entry.pid, receiver);
@@ -6448,6 +6456,10 @@ function createProcessRegistryOwner() {
       };
       scopes2.set(scope, { allocated: allocated2, runs: runs2, active: active2 });
       return scope;
+    },
+    /** Every live process of the container, in pid order: what `/proc` lists. */
+    table() {
+      return [...live.values()].sort((a, b) => a.pid - b.pid);
     }
   };
 }
@@ -6485,6 +6497,18 @@ function __stopOwnedProcess(token) {
   var _a2;
   (_a2 = runs.get(token)) == null ? void 0 : _a2.stopTimers();
 }
+function __signalOwnedProcess(token, signal) {
+  const run = runs.get(token);
+  if (!run) return false;
+  const guest = run.process;
+  try {
+    enterRun(token, () => guest.kill(guest.pid, signal));
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("Process exited with code")) return true;
+    return false;
+  }
+  return true;
+}
 const processRegistryOwner = createProcessRegistryOwner();
 let processRegistry = processRegistryOwner.createScope();
 let registryInstalled = false;
@@ -6494,6 +6518,10 @@ function createProcessRegistryScope() {
   if (registryInstalled) throw new Error("Only the container owner can create process registry scopes.");
   return processRegistryOwner.createScope();
 }
+function ownerProcessTable() {
+  if (registryInstalled) throw new Error("This realm is a process registry client, not the container owner.");
+  return processRegistryOwner.table();
+}
 function ownerProcessRegistryScope() {
   if (registryInstalled) throw new Error("This realm is a process registry client, not the container owner.");
   return processRegistry;
@@ -6513,9 +6541,9 @@ function mintPid() {
   registryUsed = true;
   return processRegistry.allocate();
 }
-function setRunPid(token, pid, ppid) {
+function setRunPid(token, pid, ppid, started2) {
   registryUsed = true;
-  processRegistry.publish(token, { pid, ppid });
+  processRegistry.publish(token, { pid, ppid, ...started2, startedAt: Date.now() });
   pidsOfRuns.set(token, { pid, ppid });
 }
 function runPid(token) {
@@ -9804,7 +9832,7 @@ function createUtilBinding(require2) {
 const bufferModule = lazyModule("buffer");
 const Buffer$9 = lazyExport("buffer", "Buffer");
 function createNodeError$1(code2, syscall, path2) {
-  const known = ["EEXIST", "EINVAL", "EISDIR", "ENOENT", "ENOTDIR", "ENOTEMPTY", "ELOOP"];
+  const known = ["EEXIST", "EINVAL", "EISDIR", "ENOENT", "ENOTDIR", "ENOTEMPTY", "ELOOP", "EROFS"];
   if (known.includes(code2)) return createNodeError(code2, syscall, path2);
   return Object.assign(new Error(`${code2}: ${syscall} '${path2}'`), { code: code2, syscall, path: path2, errno: -9 });
 }
@@ -17762,10 +17790,17 @@ var implementation$1 = function bind2(that) {
 var implementation = implementation$1;
 var functionBind = Function.prototype.bind || implementation;
 var functionCall = Function.prototype.call;
-var functionApply = Function.prototype.apply;
+var functionApply;
+var hasRequiredFunctionApply;
+function requireFunctionApply() {
+  if (hasRequiredFunctionApply) return functionApply;
+  hasRequiredFunctionApply = 1;
+  functionApply = Function.prototype.apply;
+  return functionApply;
+}
 var reflectApply = typeof Reflect !== "undefined" && Reflect && Reflect.apply;
 var bind$2 = functionBind;
-var $apply$1 = functionApply;
+var $apply$1 = requireFunctionApply();
 var $call$2 = functionCall;
 var $reflectApply = reflectApply;
 var actualApply = $reflectApply || bind$2.call($call$2, $apply$1);
@@ -17885,7 +17920,7 @@ var hasSymbols = requireHasSymbols()();
 var getProto = requireGetProto();
 var $ObjectGPO = requireObject_getPrototypeOf();
 var $ReflectGPO = requireReflect_getPrototypeOf();
-var $apply = functionApply;
+var $apply = requireFunctionApply();
 var $call = functionCall;
 var needsEval = {};
 var TypedArray = typeof Uint8Array === "undefined" || !getProto ? undefined$1 : getProto(Uint8Array);
@@ -18526,7 +18561,7 @@ function requireApplyBind() {
   if (hasRequiredApplyBind) return applyBind;
   hasRequiredApplyBind = 1;
   var bind3 = functionBind;
-  var $apply2 = functionApply;
+  var $apply2 = requireFunctionApply();
   var actualApply$1 = actualApply;
   applyBind = function applyBind2() {
     return actualApply$1(bind3, $apply2, arguments);
@@ -27737,14 +27772,16 @@ function createNodeError(code2, syscall, path2, message) {
     ENOTDIR: -20,
     EISDIR: -21,
     EEXIST: -17,
-    ENOTEMPTY: -39
+    ENOTEMPTY: -39,
+    EROFS: -30
   };
   const messages2 = {
     ENOENT: "no such file or directory",
     ENOTDIR: "not a directory",
     EISDIR: "is a directory",
     EEXIST: "file already exists",
-    ENOTEMPTY: "directory not empty"
+    ENOTEMPTY: "directory not empty",
+    EROFS: "read-only file system"
   };
   const err2 = new Error(
     `${code2}: ${messages2[code2]}, ${syscall} '${path2}'`
@@ -27803,6 +27840,7 @@ class VirtualFS {
     return { files };
   }
   serializeNode(path2, node, files) {
+    if (node.mount) return;
     if (node.type === "file") {
       let content = "";
       if (node.content && node.content.length > 0) {
@@ -27858,6 +27896,7 @@ class VirtualFS {
    */
   writeFileSyncInternal(path2, data2, emitEvent) {
     const normalized = this.normalizePath(path2);
+    this.assertWritable(normalized, "open");
     const parentPath = this.getParentPath(normalized);
     const basename2 = this.getBasename(normalized);
     if (!basename2) {
@@ -27933,11 +27972,12 @@ class VirtualFS {
     if (depth > 40) throw createNodeError("ELOOP", "stat", path2);
     const segments = this.getPathSegments(path2);
     let current3 = this.root;
+    let mounted;
     for (let index2 = 0; index2 < segments.length; index2 += 1) {
-      if (current3.type !== "directory" || !current3.children) {
+      if (current3.type !== "directory" || !mounted && !current3.children) {
         return void 0;
       }
-      const child = current3.children.get(segments[index2]);
+      const child = mounted ? mounted.tree.node("/" + segments.slice(mounted.at + 1, index2 + 1).join("/")) : current3.children.get(segments[index2]);
       if (!child) {
         return void 0;
       }
@@ -27947,16 +27987,53 @@ class VirtualFS {
         const target = this.__substrateLinkTarget(linkPath, child.target);
         return this.__substrateNode(rest ? target + "/" + rest : target, follow, depth + 1);
       }
-      current3 = child;
+      if (!mounted && child.mount) {
+        mounted = { tree: child.mount, at: index2 };
+        current3 = child.mount.node("/") ?? child;
+      } else {
+        current3 = child;
+      }
     }
     return current3;
   }
+  /**
+   * Mount a read-only tree at a directory, as Linux mounts `/proc`: reads
+   * below it are the tree's answers, writes fail with `EROFS`, and a snapshot
+   * leaves it out. Answers the unmount.
+   */
+  mount(path2, tree2) {
+    var _a2;
+    const normalized = this.normalizePath(path2);
+    const basename2 = this.getBasename(normalized);
+    if (!basename2) throw createNodeError("EINVAL", "mount", path2);
+    const parent = this.ensureDirectory(this.getParentPath(normalized));
+    const existing = parent.children.get(basename2);
+    if (existing && (existing.type !== "directory" || existing.mount || ((_a2 = existing.children) == null ? void 0 : _a2.size))) {
+      throw createNodeError("EEXIST", "mount", path2);
+    }
+    const node = { type: "directory", children: /* @__PURE__ */ new Map(), mtime: Date.now(), mode: 365, mount: tree2 };
+    parent.children.set(basename2, node);
+    return () => {
+      if (parent.children.get(basename2) === node) parent.children.delete(basename2);
+    };
+  }
+  /** A write at or below a mount point is refused, as a read-only filesystem refuses it. */
+  assertWritable(path2, syscall) {
+    var _a2;
+    let current3 = this.root;
+    for (const segment of this.getPathSegments(path2)) {
+      current3 = (_a2 = current3 == null ? void 0 : current3.children) == null ? void 0 : _a2.get(segment);
+      if (!current3) return;
+      if (current3.mount) throw createNodeError("EROFS", syscall, path2);
+    }
+  }
   /** A link's target as an absolute path: absolute as written, or relative to the link's directory. */
   __substrateLinkTarget(linkPath, target) {
     return this.normalizePath(target.startsWith("/") ? target : this.getParentPath(linkPath) + "/" + target);
   }
   symlinkSync(target, path2) {
     const normalized = this.normalizePath(path2);
+    this.assertWritable(normalized, "symlink");
     const parentPath = this.getParentPath(normalized);
     const basename2 = this.getBasename(normalized);
     const parent = this.getNode(parentPath);
@@ -28017,11 +28094,13 @@ class VirtualFS {
    * Get stats for path
    */
   chmodSync(path2, mode) {
+    this.assertWritable(path2, "chmod");
     const node = this.getNode(path2);
     if (!node) throw createNodeError("ENOENT", "chmod", path2);
     node.mode = mode & 4095;
   }
   utimesSync(path2, atime, mtime) {
+    this.assertWritable(path2, "utime");
     const node = this.getNode(path2);
     if (!node) throw createNodeError("ENOENT", "utimes", path2);
     node.atime = atime instanceof Date ? atime.getTime() : atime * 1e3;
@@ -28127,7 +28206,10 @@ class VirtualFS {
    * Create directory, optionally with recursive parent creation
    */
   mkdirSync(path2, options) {
+    var _a2;
     const normalized = this.normalizePath(path2);
+    if ((options == null ? void 0 : options.recursive) && ((_a2 = this.getNode(normalized)) == null ? void 0 : _a2.type) === "directory") return;
+    this.assertWritable(normalized, "mkdir");
     if (options == null ? void 0 : options.recursive) {
       this.ensureDirectory(normalized);
       return;
@@ -28172,6 +28254,7 @@ class VirtualFS {
    */
   unlinkSync(path2) {
     const normalized = this.normalizePath(path2);
+    this.assertWritable(normalized, "unlink");
     const parentPath = this.getParentPath(normalized);
     const basename2 = this.getBasename(normalized);
     const parent = this.getNode(parentPath);
@@ -28194,6 +28277,7 @@ class VirtualFS {
    */
   rmdirSync(path2) {
     const normalized = this.normalizePath(path2);
+    this.assertWritable(normalized, "rmdir");
     const parentPath = this.getParentPath(normalized);
     const basename2 = this.getBasename(normalized);
     if (!basename2) {
@@ -28222,6 +28306,8 @@ class VirtualFS {
   renameSync(oldPath, newPath) {
     const normalizedOld = this.normalizePath(oldPath);
     const normalizedNew = this.normalizePath(newPath);
+    this.assertWritable(normalizedOld, "rename");
+    this.assertWritable(normalizedNew, "rename");
     const oldParentPath = this.getParentPath(normalizedOld);
     const oldBasename = this.getBasename(normalizedOld);
     const newParentPath = this.getParentPath(normalizedNew);
@@ -28320,10 +28406,12 @@ class VirtualFS {
     for (let hops = 0; hops <= 40; hops += 1) {
       const segments = resolved.split("/").filter(Boolean);
       let current3 = this.root;
+      let mounted;
       let linked = false;
       for (let index2 = 0; index2 < segments.length; index2 += 1) {
-        const child = current3 && current3.children ? current3.children.get(segments[index2]) : void 0;
+        const child = mounted ? mounted.tree.node("/" + segments.slice(mounted.at + 1, index2 + 1).join("/")) : current3 && current3.children ? current3.children.get(segments[index2]) : void 0;
         if (!child) throw createNodeError("ENOENT", "realpath", path2);
+        if (!mounted && child.mount) mounted = { tree: child.mount, at: index2 };
         if (child.type === "symlink") {
           const linkPath = "/" + segments.slice(0, index2 + 1).join("/");
           const rest = segments.slice(index2 + 1).join("/");
@@ -29379,7 +29467,7 @@ const _runStreams = /* @__PURE__ */ new Map();
 async function runHostedNode(host2, launch) {
   var _a2;
   const { token, streams } = launch;
-  if (!runPid(token)) setRunPid(token, mintPid(), 0);
+  if (!runPid(token)) setRunPid(token, mintPid(), 0, { argv: ["node", ...launch.argv], cwd: launch.cwd });
   let input;
   try {
     (_a2 = streams == null ? void 0 : streams.signal) == null ? void 0 : _a2.throwIfAborted();
@@ -29638,7 +29726,7 @@ function initChildProcess(vfs2) {
       ...runPid(runToken) ? { pid: runPid(runToken).pid, ppid: runPid(runToken).ppid } : {}
     });
     const proc = runtime.getProcess();
-    if (runToken !== null) setRunPid(runToken, proc.pid, proc.ppid);
+    if (runToken !== null) setRunPid(runToken, proc.pid, proc.ppid, { argv: ["node", ...args], cwd: ctx.cwd });
     const releaseRun = runToken === null ? null : __recordRun(runToken, {
       process: proc,
       stdout: appendStdout,
@@ -30384,7 +30472,12 @@ function startChildRun(request) {
   var _a2;
   const token = `child-${__nextChildRun++}`;
   const pid = mintPid();
-  setRunPid(token, pid, ((_a2 = runPid(nodeProcessRealmToken() ?? __currentProcessToken() ?? __lastLaunchedToken)) == null ? void 0 : _a2.pid) ?? 0);
+  setRunPid(
+    token,
+    pid,
+    ((_a2 = runPid(nodeProcessRealmToken() ?? __currentProcessToken() ?? __lastLaunchedToken)) == null ? void 0 : _a2.pid) ?? 0,
+    { argv: request.args.length ? request.args : [request.file], ...request.cwd ? { cwd: request.cwd } : {} }
+  );
   const controller = new AbortController();
   const pendingStdin = [];
   const admittedNode = nodeProcessHostInstalled() && engineProgramFor(request.file, request.cwd) === "node";
@@ -35562,7 +35655,7 @@ class WorkerRuntime {
     this.worker = new Worker(
       new URL(
         /* @vite-ignore */
-        "/assets/runtime-worker-DBtzjAkn.js",
+        "/assets/runtime-worker-iInsmIAS.js",
         import.meta.url
       ),
       { type: "module" }
@@ -38278,6 +38371,16 @@ function createContainer(options) {
     },
     /** The ports the servers the named run opened are listening on. */
     processPorts: (token) => __ownedServerPorts(token),
+    portPid: (port) => {
+      var _a2;
+      const listener = listenerOnPort(port);
+      return listener ? (_a2 = runPid(ownerOf(listener))) == null ? void 0 : _a2.pid : void 0;
+    },
+    /**
+     * Deliver a signal to the named run as another process's `kill(pid)` does:
+     * the guest's listeners for it run, else its default action ends the run.
+     */
+    signalProcess: (token, signal) => __signalOwnedProcess(token, signal),
     /** End the named run: its timers stop and its servers are released. */
     stopProcess: (token) => {
       const known = __runFor(token) !== void 0 || __ownedServerPorts(token).length > 0;
@@ -38350,6 +38453,7 @@ export {
   nodeProcessHostInstalled,
   index as npm,
   ownerProcessRegistryScope,
+  ownerProcessTable,
   path,
   perfHooksShim as perf_hooks,
   processByPid,

package/dist/process-registry.d.ts

@@ -2,6 +2,12 @@
 export interface ProcessIdentity {
     readonly pid: number;
     readonly ppid: number;
+    /** What the process was started as, where its starter said: `/proc/<pid>/cmdline`. */
+    readonly argv?: readonly string[];
+    /** The directory it was started in: `/proc/<pid>/cwd`. */
+    readonly cwd?: string;
+    /** When it started, in milliseconds since the epoch. */
+    readonly startedAt?: number;
 }
 /** A run already admitted by the container owner into this realm's scope. */
 export interface InitialProcessRegistration {
@@ -36,4 +42,5 @@ export interface ProcessRegistryScope extends ProcessRegistry {
  */
 export declare function createProcessRegistryOwner(): {
     createScope(): ProcessRegistryScope;
+    table(): ProcessIdentity[];
 };

package/dist/process-tokens.d.ts

@@ -15,7 +15,7 @@
  * command gives its process has it removed.
  */
 import type { Process } from './shims/process';
-import { type ProcessRegistry, type ProcessRegistryScope, type InitialProcessRegistration } from './process-registry';
+import { type ProcessIdentity, type ProcessRegistry, type ProcessRegistryScope, type InitialProcessRegistration } from './process-registry';
 /** Whatever the embedding runtime uses to name one guest process. */
 export type ProcessToken = string;
 /** The environment variable a run's name travels in, from `exec` to `node`. */
@@ -64,8 +64,18 @@ export declare function __currentProcessToken(): ProcessToken | null;
  * half, `__releaseOwnedServers`, which calls this for the timers.
  */
 export declare function __stopOwnedProcess(token: ProcessToken): void;
+/**
+ * Another process's `kill(pid, signal)`, delivered to a named run's guest.
+ * On a machine the target's handlers run, or its default action ends it; the
+ * guest's own `process.kill(process.pid, signal)` is exactly that, so the
+ * signal is raised through it, as the run. False when the run is gone or the
+ * signal is not one Node names.
+ */
+export declare function __signalOwnedProcess(token: ProcessToken, signal: string): boolean;
 /** Each child realm gets its own registration authority in this container. */
 export declare function createProcessRegistryScope(): ProcessRegistryScope;
+/** Trusted container owner only: every live process of the container, from every realm. */
+export declare function ownerProcessTable(): ProcessIdentity[];
 /** Trusted container owner only; worker clients cannot expose their authority. */
 export declare function ownerProcessRegistryScope(): ProcessRegistryScope;
 /** Startup-only host seam; never swap identity authorities under live runs. */
@@ -73,7 +83,10 @@ export declare function installProcessRegistry(registry: ProcessRegistry, initia
 /** The next process number this engine hands out. */
 export declare function mintPid(): number;
 /** Record the numbers a named run was started with, for the run to read back. */
-export declare function setRunPid(token: ProcessToken, pid: number, ppid: number): void;
+export declare function setRunPid(token: ProcessToken, pid: number, ppid: number, started?: {
+    argv?: readonly string[];
+    cwd?: string;
+}): void;
 /** The numbers a named run was started with, where one was recorded. */
 export declare function runPid(token: ProcessToken | null | undefined): {
     pid: number;

package/dist/virtual-fs.d.ts

@@ -37,6 +37,22 @@ export interface FSNode {
      * apart). Absent until something sets it, which is the write time.
      */
     atime?: number;
+    /**
+     * A tree mounted here: the paths below this node are the tree's, answered
+     * when they are read, and never this filesystem's to write. Linux's
+     * `/proc` is one.
+     */
+    mount?: MountedTree;
+}
+/**
+ * A read-only tree another party answers, mounted at a directory: `node`
+ * returns what is at a path relative to the mount point (`/` is the mount
+ * point itself), computed when it is asked, or undefined where nothing is.
+ * A directory's `children` names what a listing shows; a link's `target` is
+ * followed as any link is.
+ */
+export interface MountedTree {
+    node(path: string): FSNode | undefined;
 }
 type VFSChangeListener = (path: string, content: string) => void;
 type VFSDeleteListener = (path: string) => void;
@@ -83,7 +99,7 @@ export interface NodeError extends Error {
     syscall: string;
     path?: string;
 }
-export declare function createNodeError(code: 'ENOENT' | 'ENOTDIR' | 'EISDIR' | 'EEXIST' | 'ENOTEMPTY' | 'ELOOP' | 'EINVAL', syscall: string, path: string, message?: string): NodeError;
+export declare function createNodeError(code: 'ENOENT' | 'ENOTDIR' | 'EISDIR' | 'EEXIST' | 'ENOTEMPTY' | 'ELOOP' | 'EINVAL' | 'EROFS', syscall: string, path: string, message?: string): NodeError;
 export declare class VirtualFS {
     private root;
     private encoder;
@@ -140,6 +156,14 @@ export declare class VirtualFS {
     getNode(path: string): FSNode | undefined;
     /** The node at a path, following every link on the way and, when `follow`, the last one too. */
     __substrateNode(path: string, follow: boolean, depth: number): FSNode | undefined;
+    /**
+     * Mount a read-only tree at a directory, as Linux mounts `/proc`: reads
+     * below it are the tree's answers, writes fail with `EROFS`, and a snapshot
+     * leaves it out. Answers the unmount.
+     */
+    mount(path: string, tree: MountedTree): () => void;
+    /** A write at or below a mount point is refused, as a read-only filesystem refuses it. */
+    private assertWritable;
     /** A link's target as an absolute path: absolute as written, or relative to the link's directory. */
     __substrateLinkTarget(linkPath: string, target: string): string;
     symlinkSync(target: string, path: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/tabnode",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Node's own library, in a browser tab.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -13,7 +13,7 @@
 // hands the host's own globals back. See `host-globals.ts`.
 export { restoreHostGlobals, guestRealmInstalled } from './host-globals';
 export { VirtualFS } from './virtual-fs';
-export type { FSNode, Stats, FSWatcher, WatchListener, WatchEventType } from './virtual-fs';
+export type { FSNode, MountedTree, Stats, FSWatcher, WatchListener, WatchEventType } from './virtual-fs';
 export { Runtime, execute } from './runtime';
 export type { Module, RuntimeOptions, RequireFunction } from './runtime';
 export { createRuntime, WorkerRuntime } from './create-runtime';
@@ -54,11 +54,12 @@ import { PackageManager } from './npm';
 import { ServerBridge, getServerBridge } from './server-bridge';
 import { runCommand, registerRunStreams, releaseRunStreams, sendStdin } from './shims/child_process';
 import { Server as NetServer, __releaseOwnedHandles, type Socket as NetSocket } from './node-lib/net-module';
-import { __adoptHandle, type OwnedHandle } from './node-lib/binding/handles';
+import { __adoptHandle, ownerOf, type OwnedHandle } from './node-lib/binding/handles';
+import { listenerOnPort } from './node-lib/binding/tcp_wrap';
 
-import { __currentProcessToken, __runFor, __stopOwnedProcess, runPid, processByPid } from './process-tokens';
+import { __currentProcessToken, __runFor, __signalOwnedProcess, __stopOwnedProcess, runPid, processByPid } from './process-tokens';
 export { runPid, processByPid };
-export { createProcessRegistryScope, installProcessRegistry, ownerProcessRegistryScope } from './process-tokens';
+export { createProcessRegistryScope, installProcessRegistry, ownerProcessRegistryScope, ownerProcessTable } from './process-tokens';
 export { installNodeProcessHost, nodeProcessHostInstalled } from './node-process-host';
 export type { NodeProcessLaunch, NodeProcessHost } from './node-process-host';
 export type { ProcessIdentity, ProcessRegistry, ProcessRegistryScope, InitialProcessRegistration } from './process-registry';
@@ -123,6 +124,10 @@ export function createContainer(options?: ContainerOptions): {
   run: (command: string, options?: RunOptions) => Promise<RunResult>;
   pendingTimers: (token: string) => number;
   processPorts: (token: string) => number[];
+  /** The pid of the process listening on a port of this engine, where a guest process is: `/proc`'s socket owner. */
+  portPid: (port: number) => number | undefined;
+  /** Deliver a signal to the named run as another process's `kill(pid)` does; false when the run is gone. */
+  signalProcess: (token: string, signal: string) => boolean;
   stopProcess: (token: string) => boolean;
   /**
    * Input for one run's guest, by its process token; without a token, the most
@@ -208,6 +213,15 @@ export function createContainer(options?: ContainerOptions): {
     pendingTimers: (token: string): number => __runFor(token)?.pendingTimers() ?? 0,
     /** The ports the servers the named run opened are listening on. */
     processPorts: (token: string): number[] => __ownedServerPorts(token),
+    portPid: (port: number): number | undefined => {
+      const listener = listenerOnPort(port);
+      return listener ? runPid(ownerOf(listener as unknown as OwnedHandle))?.pid : undefined;
+    },
+    /**
+     * Deliver a signal to the named run as another process's `kill(pid)` does:
+     * the guest's listeners for it run, else its default action ends the run.
+     */
+    signalProcess: (token: string, signal: string): boolean => __signalOwnedProcess(token, signal),
     /** End the named run: its timers stop and its servers are released. */
     stopProcess: (token: string): boolean => {
       const known = __runFor(token) !== undefined || __ownedServerPorts(token).length > 0;

package/src/node-lib/binding/fs.ts

@@ -40,7 +40,7 @@ import { errname } from './uv';
  * the same shape here rather than widened there.
  */
 function createNodeError(code: string, syscall: string, path: string): Error {
-  const known = ['EEXIST', 'EINVAL', 'EISDIR', 'ENOENT', 'ENOTDIR', 'ENOTEMPTY', 'ELOOP'];
+  const known = ['EEXIST', 'EINVAL', 'EISDIR', 'ENOENT', 'ENOTDIR', 'ENOTEMPTY', 'ELOOP', 'EROFS'];
   if (known.includes(code)) return vfsError(code as 'ENOENT', syscall, path);
   return Object.assign(new Error(`${code}: ${syscall} '${path}'`), { code, syscall, path, errno: -9 });
 }

package/src/process-registry.ts

@@ -2,6 +2,22 @@
 export interface ProcessIdentity {
   readonly pid: number;
   readonly ppid: number;
+  /** What the process was started as, where its starter said: `/proc/<pid>/cmdline`. */
+  readonly argv?: readonly string[];
+  /** The directory it was started in: `/proc/<pid>/cwd`. */
+  readonly cwd?: string;
+  /** When it started, in milliseconds since the epoch. */
+  readonly startedAt?: number;
+}
+
+/** The parts of an identity a starter may add, checked before they are kept. */
+function describedIdentity(identity: ProcessIdentity): ProcessIdentity {
+  const { pid, ppid, argv, cwd, startedAt } = identity;
+  const described: { pid: number; ppid: number; argv?: readonly string[]; cwd?: string; startedAt?: number } = { pid, ppid };
+  if (Array.isArray(argv) && argv.length <= 4096 && argv.every(arg => typeof arg === 'string')) described.argv = Object.freeze([...argv]);
+  if (typeof cwd === 'string' && cwd.startsWith('/')) described.cwd = cwd;
+  if (typeof startedAt === 'number' && Number.isFinite(startedAt)) described.startedAt = startedAt;
+  return Object.freeze(described);
 }
 
 /** A run already admitted by the container owner into this realm's scope. */
@@ -38,7 +54,7 @@ export interface ProcessRegistryScope extends ProcessRegistry {
  * so identical local run tokens cannot overwrite or release another realm's
  * process. Allocation alone does not announce a live process.
  */
-export function createProcessRegistryOwner(): { createScope(): ProcessRegistryScope } {
+export function createProcessRegistryOwner(): { createScope(): ProcessRegistryScope; table(): ProcessIdentity[] } {
   let nextPid = 1000 + Math.floor(Math.random() * 30000);
   const live = new Map<number, ProcessIdentity>();
   // Which realm's scope answers for each live pid, including after handoff.
@@ -104,7 +120,7 @@ export function createProcessRegistryOwner(): { createScope(): ProcessRegistrySc
           if (identity.ppid !== 0 && !Array.from(runs.values()).some(parent => parent.pid === identity.ppid)) {
             throw new Error('Parent process is not owned by this realm.');
           }
-          const entry = Object.freeze({ pid: identity.pid, ppid: identity.ppid });
+          const entry = describedIdentity(identity);
           runs.set(token, entry);
           live.set(entry.pid, entry);
           receivers.set(entry.pid, receiver);
@@ -140,5 +156,9 @@ export function createProcessRegistryOwner(): { createScope(): ProcessRegistrySc
       scopes.set(scope, { allocated, runs, active });
       return scope;
     },
+    /** Every live process of the container, in pid order: what `/proc` lists. */
+    table() {
+      return [...live.values()].sort((a, b) => a.pid - b.pid);
+    },
   };
 }

package/src/process-tokens.ts

@@ -17,7 +17,7 @@
 
 import type { Process } from './shims/process';
 import { AsyncLocalStorage } from './shims/async_hooks';
-import { createProcessRegistryOwner, type ProcessRegistry, type ProcessRegistryScope, type InitialProcessRegistration } from './process-registry';
+import { createProcessRegistryOwner, type ProcessIdentity, type ProcessRegistry, type ProcessRegistryScope, type InitialProcessRegistration } from './process-registry';
 
 /** Whatever the embedding runtime uses to name one guest process. */
 export type ProcessToken = string;
@@ -113,6 +113,27 @@ export function __stopOwnedProcess(token: ProcessToken): void {
   runs.get(token)?.stopTimers();
 }
 
+/**
+ * Another process's `kill(pid, signal)`, delivered to a named run's guest.
+ * On a machine the target's handlers run, or its default action ends it; the
+ * guest's own `process.kill(process.pid, signal)` is exactly that, so the
+ * signal is raised through it, as the run. False when the run is gone or the
+ * signal is not one Node names.
+ */
+export function __signalOwnedProcess(token: ProcessToken, signal: string): boolean {
+  const run = runs.get(token);
+  if (!run) return false;
+  const guest = run.process as unknown as { pid: number; kill(pid: number, signal: string): unknown };
+  try { enterRun(token, () => guest.kill(guest.pid, signal)); }
+  catch (error) {
+    // A default action ends the process by `exit`, which a synchronous guest
+    // frame reports by throwing; that is the signal delivered.
+    if (error instanceof Error && error.message.startsWith("Process exited with code")) return true;
+    return false;
+  }
+  return true;
+}
+
 /**
  * A process's own number.
  *
@@ -147,6 +168,12 @@ export function createProcessRegistryScope(): ProcessRegistryScope {
   return processRegistryOwner.createScope();
 }
 
+/** Trusted container owner only: every live process of the container, from every realm. */
+export function ownerProcessTable(): ProcessIdentity[] {
+  if (registryInstalled) throw new Error('This realm is a process registry client, not the container owner.');
+  return processRegistryOwner.table();
+}
+
 /** Trusted container owner only; worker clients cannot expose their authority. */
 export function ownerProcessRegistryScope(): ProcessRegistryScope {
   if (registryInstalled) throw new Error('This realm is a process registry client, not the container owner.');
@@ -177,9 +204,9 @@ export function mintPid(): number {
 }
 
 /** Record the numbers a named run was started with, for the run to read back. */
-export function setRunPid(token: ProcessToken, pid: number, ppid: number): void {
+export function setRunPid(token: ProcessToken, pid: number, ppid: number, started?: { argv?: readonly string[]; cwd?: string }): void {
   registryUsed = true;
-  processRegistry.publish(token, { pid, ppid });
+  processRegistry.publish(token, { pid, ppid, ...started, startedAt: Date.now() });
   pidsOfRuns.set(token, { pid, ppid });
 }
 

package/src/shims/child_process.ts

@@ -199,7 +199,7 @@ const _runStreams = new Map<ProcessToken, RunStreams>();
 /** Submit before returning to a spawning parent; completion remains async. */
 async function runHostedNode(host: NodeProcessHost, launch: Omit<NodeProcessLaunch, 'identity' | 'inherited' | 'stdinStream'>): Promise<CommandOutcome> {
   const { token, streams } = launch;
-  if (!runPid(token)) setRunPid(token, mintPid(), 0);
+  if (!runPid(token)) setRunPid(token, mintPid(), 0, { argv: ['node', ...launch.argv], cwd: launch.cwd });
   let input: ReturnType<typeof nodeProcessInput> | undefined;
   try {
     streams?.signal?.throwIfAborted();
@@ -578,7 +578,7 @@ export function initChildProcess(vfs: VirtualFS): void {
     // This run's numbers, recorded under its name: a child it spawns reads
     // them for its own `ppid`, and `process.kill(pid, 0)` asks this registry
     // whether a pid is a live process.
-    if (runToken !== null) setRunPid(runToken, proc.pid, proc.ppid);
+    if (runToken !== null) setRunPid(runToken, proc.pid, proc.ppid, { argv: ['node', ...args], cwd: ctx.cwd });
     const releaseRun = runToken === null ? null : __recordRun(runToken, {
       process: proc,
       stdout: appendStdout,
@@ -1680,7 +1680,8 @@ function startChildRun(request: RunRequest): StartedRun {
   const pid = mintPid();
   // In a process realm the admitted guest is always the spawning parent.
   // Async bookkeeping for a routed child must not make that child its parent.
-  setRunPid(token, pid, runPid(nodeProcessRealmToken() ?? __currentProcessToken() ?? __lastLaunchedToken)?.pid ?? 0);
+  setRunPid(token, pid, runPid(nodeProcessRealmToken() ?? __currentProcessToken() ?? __lastLaunchedToken)?.pid ?? 0,
+    { argv: request.args.length ? request.args : [request.file], ...(request.cwd ? { cwd: request.cwd } : {}) });
   const controller = new AbortController();
   const pendingStdin: Array<Uint8Array | null> = [];
   // A host terminal consumes input incrementally. The old string-only

package/src/virtual-fs.ts

@@ -44,6 +44,23 @@ export interface FSNode {
    * apart). Absent until something sets it, which is the write time.
    */
   atime?: number;
+  /**
+   * A tree mounted here: the paths below this node are the tree's, answered
+   * when they are read, and never this filesystem's to write. Linux's
+   * `/proc` is one.
+   */
+  mount?: MountedTree;
+}
+
+/**
+ * A read-only tree another party answers, mounted at a directory: `node`
+ * returns what is at a path relative to the mount point (`/` is the mount
+ * point itself), computed when it is asked, or undefined where nothing is.
+ * A directory's `children` names what a listing shows; a link's `target` is
+ * followed as any link is.
+ */
+export interface MountedTree {
+  node(path: string): FSNode | undefined;
 }
 
 // Identity belongs to the node, so writes and renames preserve it while an
@@ -116,7 +133,7 @@ export interface NodeError extends Error {
 }
 
 export function createNodeError(
-  code: 'ENOENT' | 'ENOTDIR' | 'EISDIR' | 'EEXIST' | 'ENOTEMPTY' | 'ELOOP' | 'EINVAL',
+  code: 'ENOENT' | 'ENOTDIR' | 'EISDIR' | 'EEXIST' | 'ENOTEMPTY' | 'ELOOP' | 'EINVAL' | 'EROFS',
   syscall: string,
   path: string,
   message?: string
@@ -127,6 +144,7 @@ export function createNodeError(
     EISDIR: -21,
     EEXIST: -17,
     ENOTEMPTY: -39,
+    EROFS: -30,
   };
 
   const messages: Record<string, string> = {
@@ -135,6 +153,7 @@ export function createNodeError(
     EISDIR: 'is a directory',
     EEXIST: 'file already exists',
     ENOTEMPTY: 'directory not empty',
+    EROFS: 'read-only file system',
   };
 
   const err = new Error(
@@ -216,6 +235,7 @@ export class VirtualFS {
   }
 
   private serializeNode(path: string, node: FSNode, files: VFSFileEntry[]): void {
+    if (node.mount) return; // a mounted tree is its answerer's, never the filesystem's contents
     if (node.type === 'file') {
       // Encode binary content as base64
       let content = '';
@@ -284,6 +304,7 @@ export class VirtualFS {
    */
   private writeFileSyncInternal(path: string, data: string | Uint8Array, emitEvent: boolean): void {
     const normalized = this.normalizePath(path);
+    this.assertWritable(normalized, 'open');
     const parentPath = this.getParentPath(normalized);
     const basename = this.getBasename(normalized);
 
@@ -377,11 +398,14 @@ export class VirtualFS {
     if (depth > 40) throw createNodeError('ELOOP', 'stat', path);
     const segments = this.getPathSegments(path);
     let current = this.root;
+    let mounted: { tree: MountedTree; at: number } | undefined;
     for (let index = 0; index < segments.length; index += 1) {
-      if (current.type !== 'directory' || !current.children) {
+      if (current.type !== 'directory' || (!mounted && !current.children)) {
         return undefined;
       }
-      const child = current.children.get(segments[index]);
+      const child = mounted
+        ? mounted.tree.node('/' + segments.slice(mounted.at + 1, index + 1).join('/'))
+        : current.children!.get(segments[index]);
       if (!child) {
         return undefined;
       }
@@ -391,16 +415,51 @@ export class VirtualFS {
         const target = this.__substrateLinkTarget(linkPath, child.target!);
         return this.__substrateNode(rest ? target + '/' + rest : target, follow, depth + 1);
       }
-      current = child;
+      if (!mounted && child.mount) {
+        mounted = { tree: child.mount, at: index };
+        current = child.mount.node('/') ?? child;
+      } else {
+        current = child;
+      }
     }
     return current;
   }
+
+  /**
+   * Mount a read-only tree at a directory, as Linux mounts `/proc`: reads
+   * below it are the tree's answers, writes fail with `EROFS`, and a snapshot
+   * leaves it out. Answers the unmount.
+   */
+  mount(path: string, tree: MountedTree): () => void {
+    const normalized = this.normalizePath(path);
+    const basename = this.getBasename(normalized);
+    if (!basename) throw createNodeError('EINVAL', 'mount', path);
+    const parent = this.ensureDirectory(this.getParentPath(normalized));
+    const existing = parent.children!.get(basename);
+    if (existing && (existing.type !== 'directory' || existing.mount || existing.children?.size)) {
+      throw createNodeError('EEXIST', 'mount', path);
+    }
+    const node: FSNode = { type: 'directory', children: new Map(), mtime: Date.now(), mode: 0o555, mount: tree };
+    parent.children!.set(basename, node);
+    return () => { if (parent.children!.get(basename) === node) parent.children!.delete(basename); };
+  }
+
+  /** A write at or below a mount point is refused, as a read-only filesystem refuses it. */
+  private assertWritable(path: string, syscall: string): void {
+    let current: FSNode | undefined = this.root;
+    for (const segment of this.getPathSegments(path)) {
+      current = current?.children?.get(segment);
+      if (!current) return;
+      if (current.mount) throw createNodeError('EROFS', syscall, path);
+    }
+  }
   /** A link's target as an absolute path: absolute as written, or relative to the link's directory. */
   __substrateLinkTarget(linkPath: string, target: string): string {
     return this.normalizePath(target.startsWith('/') ? target : this.getParentPath(linkPath) + '/' + target);
   }
   symlinkSync(target: string, path: string): void {
     const normalized = this.normalizePath(path);
+    this.assertWritable(normalized, 'symlink');
     const parentPath = this.getParentPath(normalized);
     const basename = this.getBasename(normalized);
     const parent = this.getNode(parentPath);
@@ -472,12 +531,14 @@ export class VirtualFS {
    * Get stats for path
    */
   chmodSync(path: string, mode: number): void {
+    this.assertWritable(path, 'chmod');
     const node = this.getNode(path);
     if (!node) throw createNodeError('ENOENT', 'chmod', path);
     node.mode = mode & 0o7777;
   }
 
   utimesSync(path: string, atime: number | Date, mtime: number | Date): void {
+    this.assertWritable(path, 'utime');
     const node = this.getNode(path);
     if (!node) throw createNodeError('ENOENT', 'utimes', path);
     node.atime = atime instanceof Date ? atime.getTime() : atime * 1000;
@@ -600,6 +661,9 @@ export class VirtualFS {
    */
   mkdirSync(path: string, options?: { recursive?: boolean }): void {
     const normalized = this.normalizePath(path);
+    // `mkdir -p` of a directory that is there, a mount point among them, is done
+    if (options?.recursive && this.getNode(normalized)?.type === 'directory') return;
+    this.assertWritable(normalized, 'mkdir');
 
     if (options?.recursive) {
       this.ensureDirectory(normalized);
@@ -657,6 +721,7 @@ export class VirtualFS {
    */
   unlinkSync(path: string): void {
     const normalized = this.normalizePath(path);
+    this.assertWritable(normalized, 'unlink');
     const parentPath = this.getParentPath(normalized);
     const basename = this.getBasename(normalized);
 
@@ -689,6 +754,7 @@ export class VirtualFS {
    */
   rmdirSync(path: string): void {
     const normalized = this.normalizePath(path);
+    this.assertWritable(normalized, 'rmdir');
     const parentPath = this.getParentPath(normalized);
     const basename = this.getBasename(normalized);
 
@@ -727,6 +793,8 @@ export class VirtualFS {
   renameSync(oldPath: string, newPath: string): void {
     const normalizedOld = this.normalizePath(oldPath);
     const normalizedNew = this.normalizePath(newPath);
+    this.assertWritable(normalizedOld, 'rename');
+    this.assertWritable(normalizedNew, 'rename');
 
     const oldParentPath = this.getParentPath(normalizedOld);
     const oldBasename = this.getBasename(normalizedOld);
@@ -846,10 +914,14 @@ export class VirtualFS {
     for (let hops = 0; hops <= 40; hops += 1) {
       const segments = resolved.split('/').filter(Boolean);
       let current: FSNode | undefined = this.root;
+      let mounted: { tree: MountedTree; at: number } | undefined;
       let linked = false;
       for (let index = 0; index < segments.length; index += 1) {
-        const child: FSNode | undefined = current && current.children ? current.children.get(segments[index]) : void 0;
+        const child: FSNode | undefined = mounted
+          ? mounted.tree.node('/' + segments.slice(mounted.at + 1, index + 1).join('/'))
+          : current && current.children ? current.children.get(segments[index]) : void 0;
         if (!child) throw createNodeError('ENOENT', 'realpath', path);
+        if (!mounted && child.mount) mounted = { tree: child.mount, at: index };
         if (child.type === 'symlink') {
           const linkPath = '/' + segments.slice(0, index + 1).join('/');
           const rest = segments.slice(index + 1).join('/');