typescript-virtual-container 1.5.11 → 1.6.0

package/dist/modules/VirtualNetworkManager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * VirtualNetworkManager — a configurable virtual network stack.
+ *
+ * Maintains a routing table, ARP cache, and interface list with simulated
+ * latency and packet loss. Used by the `ip`, `ping`, and `netstat` commands
+ * to produce dynamic, deterministic output instead of hardcoded strings.
+ */
+export interface VirtualInterface {
+    name: string;
+    type: "loopback" | "ether";
+    mac: string;
+    mtu: number;
+    state: "UP" | "DOWN";
+    ipv4: string;
+    ipv4Mask: number;
+    ipv6: string;
+}
+export interface VirtualRoute {
+    destination: string;
+    gateway: string;
+    netmask: string;
+    device: string;
+    flags: string;
+}
+export interface VirtualArpEntry {
+    ip: string;
+    mac: string;
+    device: string;
+    state: "REACHABLE" | "STALE" | "PERMANENT";
+}
+export declare class VirtualNetworkManager {
+    private interfaces;
+    private routes;
+    private arpCache;
+    getInterfaces(): VirtualInterface[];
+    getRoutes(): VirtualRoute[];
+    getArpCache(): VirtualArpEntry[];
+    addRoute(dest: string, gateway: string, netmask: string, device: string): void;
+    delRoute(dest: string): boolean;
+    setInterfaceState(name: string, state: "UP" | "DOWN"): boolean;
+    setInterfaceIp(name: string, ipv4: string, mask: number): boolean;
+    /** Ping simulation: returns latency in ms, or -1 if unreachable. */
+    ping(host: string): number;
+    /** Get formatted output for `ip addr`. */
+    formatIpAddr(): string;
+    /** Get formatted output for `ip route`. */
+    formatIpRoute(): string;
+    /** Get formatted output for `ip link`. */
+    formatIpLink(): string;
+    /** Get formatted output for `ip neigh`. */
+    formatIpNeigh(): string;
+    private _maskToCidr;
+    private _ipForDevice;
+}

package/dist/modules/VirtualNetworkManager.js

@@ -0,0 +1,144 @@
+/**
+ * VirtualNetworkManager — a configurable virtual network stack.
+ *
+ * Maintains a routing table, ARP cache, and interface list with simulated
+ * latency and packet loss. Used by the `ip`, `ping`, and `netstat` commands
+ * to produce dynamic, deterministic output instead of hardcoded strings.
+ */
+function randomMac() {
+    const hex = () => Math.floor(Math.random() * 256).toString(16).padStart(2, "0");
+    return `02:42:${hex()}:${hex()}:${hex()}:${hex()}`;
+}
+export class VirtualNetworkManager {
+    interfaces = [
+        {
+            name: "lo",
+            type: "loopback",
+            mac: "00:00:00:00:00:00",
+            mtu: 65536,
+            state: "UP",
+            ipv4: "127.0.0.1",
+            ipv4Mask: 8,
+            ipv6: "::1",
+        },
+        {
+            name: "eth0",
+            type: "ether",
+            mac: randomMac(),
+            mtu: 1500,
+            state: "UP",
+            ipv4: "10.0.0.2",
+            ipv4Mask: 24,
+            ipv6: "fe80::42:aff:fe00:2",
+        },
+    ];
+    routes = [
+        { destination: "default", gateway: "10.0.0.1", netmask: "0.0.0.0", device: "eth0", flags: "UG" },
+        { destination: "10.0.0.0", gateway: "0.0.0.0", netmask: "255.255.255.0", device: "eth0", flags: "U" },
+        { destination: "127.0.0.0", gateway: "0.0.0.0", netmask: "255.0.0.0", device: "lo", flags: "U" },
+    ];
+    arpCache = [
+        { ip: "10.0.0.1", mac: "02:42:0a:00:00:01", device: "eth0", state: "REACHABLE" },
+    ];
+    getInterfaces() {
+        return [...this.interfaces];
+    }
+    getRoutes() {
+        return [...this.routes];
+    }
+    getArpCache() {
+        return [...this.arpCache];
+    }
+    addRoute(dest, gateway, netmask, device) {
+        this.routes.push({ destination: dest, gateway, netmask, device, flags: "UG" });
+    }
+    delRoute(dest) {
+        const idx = this.routes.findIndex((r) => r.destination === dest);
+        if (idx === -1)
+            return false;
+        this.routes.splice(idx, 1);
+        return true;
+    }
+    setInterfaceState(name, state) {
+        const iface = this.interfaces.find((i) => i.name === name);
+        if (!iface)
+            return false;
+        iface.state = state;
+        return true;
+    }
+    setInterfaceIp(name, ipv4, mask) {
+        const iface = this.interfaces.find((i) => i.name === name);
+        if (!iface)
+            return false;
+        iface.ipv4 = ipv4;
+        iface.ipv4Mask = mask;
+        return true;
+    }
+    /** Ping simulation: returns latency in ms, or -1 if unreachable. */
+    ping(host) {
+        // Loopback always works
+        if (host === "127.0.0.1" || host === "localhost" || host === "::1") {
+            return 0.05 + Math.random() * 0.1;
+        }
+        // Check ARP cache / routing
+        const arp = this.arpCache.find((e) => e.ip === host);
+        if (arp && arp.state === "REACHABLE") {
+            return 0.5 + Math.random() * 2;
+        }
+        // Simulate random packet loss (5%)
+        if (Math.random() < 0.05)
+            return -1;
+        return 0.8 + Math.random() * 5;
+    }
+    /** Get formatted output for `ip addr`. */
+    formatIpAddr() {
+        const lines = [];
+        let idx = 1;
+        for (const iface of this.interfaces) {
+            const flags = iface.state === "UP"
+                ? (iface.type === "loopback" ? "LOOPBACK,UP,LOWER_UP" : "BROADCAST,MULTICAST,UP,LOWER_UP")
+                : "DOWN";
+            lines.push(`${idx}: ${iface.name}: <${flags}> mtu ${iface.mtu} qdisc mq state ${iface.state === "UP" ? "UNKNOWN" : "DOWN"} group default qlen 1000`);
+            lines.push(`    link/${iface.type === "loopback" ? "loopback" : "ether"} ${iface.mac} brd ff:ff:ff:ff:ff:ff`);
+            lines.push(`    inet ${iface.ipv4}/${iface.ipv4Mask} scope global ${iface.name}`);
+            lines.push(`       valid_lft forever preferred_lft forever`);
+            lines.push(`    inet6 ${iface.ipv6}/64 scope link`);
+            lines.push(`       valid_lft forever preferred_lft forever`);
+            idx++;
+        }
+        return lines.join("\n");
+    }
+    /** Get formatted output for `ip route`. */
+    formatIpRoute() {
+        return this.routes.map((r) => {
+            if (r.destination === "default") {
+                return `default via ${r.gateway} dev ${r.device}`;
+            }
+            return `${r.destination}/${this._maskToCidr(r.netmask)} dev ${r.device} proto kernel scope link src ${this._ipForDevice(r.device)}`;
+        }).join("\n");
+    }
+    /** Get formatted output for `ip link`. */
+    formatIpLink() {
+        const lines = [];
+        let idx = 1;
+        for (const iface of this.interfaces) {
+            const flags = iface.state === "UP"
+                ? (iface.type === "loopback" ? "LOOPBACK,UP,LOWER_UP" : "BROADCAST,MULTICAST,UP,LOWER_UP")
+                : "DOWN";
+            lines.push(`${idx}: ${iface.name}: <${flags}> mtu ${iface.mtu} qdisc mq state ${iface.state === "UP" ? "UNKNOWN" : "DOWN"} mode DEFAULT group default qlen 1000`);
+            lines.push(`    link/${iface.type === "loopback" ? "loopback" : "ether"} ${iface.mac} brd ff:ff:ff:ff:ff:ff`);
+            idx++;
+        }
+        return lines.join("\n");
+    }
+    /** Get formatted output for `ip neigh`. */
+    formatIpNeigh() {
+        return this.arpCache.map((e) => `${e.ip} dev ${e.device} lladdr ${e.mac} ${e.state}`).join("\n");
+    }
+    _maskToCidr(mask) {
+        return mask.split(".").reduce((acc, oct) => acc + (parseInt(oct, 10) ? parseInt(oct, 10).toString(2).split("1").length - 1 : 0), 0);
+    }
+    _ipForDevice(device) {
+        return this.interfaces.find((i) => i.name === device)?.ipv4 ?? "0.0.0.0";
+    }
+}

package/dist/modules/linuxRootfs.d.ts

@@ -20,6 +20,7 @@
 import VirtualFileSystem from "../VirtualFileSystem";
 import type { ShellProperties } from "../VirtualShell";
 import type { VirtualActiveSession, VirtualUserManager } from "../VirtualUserManager";
+import type { VirtualNetworkManager } from "./VirtualNetworkManager";
 /**
  * Sync `/etc/passwd`, `/etc/group`, and `/etc/shadow` from the
  * VirtualUserManager's current user list into the VFS.
@@ -32,7 +33,7 @@ export declare function syncEtcPasswd(vfs: VirtualFileSystem, users: VirtualUser
  *
  * Safe to call repeatedly — acts as a live kernel state snapshot.
  */
-export declare function refreshProc(vfs: VirtualFileSystem, props: ShellProperties, hostname: string, shellStartTime: number, sessions?: VirtualActiveSession[]): void;
+export declare function refreshProc(vfs: VirtualFileSystem, props: ShellProperties, hostname: string, shellStartTime: number, sessions?: VirtualActiveSession[], network?: VirtualNetworkManager): void;
 /**
  * Build or retrieve the static rootfs VFSB snapshot for the given
  * hostname + ShellProperties combination.
@@ -51,7 +52,7 @@ export declare function getStaticRootfsSnapshot(hostname: string, props: ShellPr
  * @param shellStartTime Unix ms of shell creation (for uptime).
  * @param sessions       Active sessions (for /proc/<pid> population).
  */
-export declare function bootstrapLinuxRootfs(vfs: VirtualFileSystem, users: VirtualUserManager, hostname: string, props: ShellProperties, shellStartTime: number, sessions?: VirtualActiveSession[]): void;
+export declare function bootstrapLinuxRootfs(vfs: VirtualFileSystem, users: VirtualUserManager, hostname: string, props: ShellProperties, shellStartTime: number, sessions?: VirtualActiveSession[], network?: VirtualNetworkManager): void;
 /**
  * Engine for runtimes that want periodic /proc refresh (e.g. web shell
  * with live `top`/`ps` output). Call `.boot()` once, then `.tick()` on
@@ -63,7 +64,7 @@ export declare function bootstrapLinuxRootfs(vfs: VirtualFileSystem, users: Virt
  * setInterval(() => engine.tick(shell.listActiveSessions()), 5000);
  * ```
  */
-export declare function createLinuxRootfsEngine(vfs: VirtualFileSystem, props: ShellProperties, hostname: string, startTime: number): {
+export declare function createLinuxRootfsEngine(vfs: VirtualFileSystem, props: ShellProperties, hostname: string, startTime: number, network?: VirtualNetworkManager): {
     boot(users: VirtualUserManager, sessions?: VirtualActiveSession[]): void;
     tick(sessions?: VirtualActiveSession[]): void;
 };

package/dist/modules/linuxRootfs.js

@@ -505,7 +505,7 @@ function bootProcLog(vfs, props) {
  *
  * Safe to call repeatedly — acts as a live kernel state snapshot.
  */
-export function refreshProc(vfs, props, hostname, shellStartTime, sessions = []) {
+export function refreshProc(vfs, props, hostname, shellStartTime, sessions = [], network) {
     ensureDir(vfs, "/proc");
     const uptimeSec = Math.floor((Date.now() - shellStartTime) / 1000);
     const idleSec = Math.floor(uptimeSec * 0.9);
@@ -589,6 +589,59 @@ export function refreshProc(vfs, props, hostname, shellStartTime, sessions = [])
     const load = (Math.random() * 0.3).toFixed(2);
     const numProcs = 1 + sessions.length;
     write(vfs, "/proc/loadavg", `${load} ${load} ${load} ${numProcs}/${numProcs} 1\n`);
+    // /proc/stat — CPU statistics
+    const cpuCount = os.cpus().length;
+    const userJiffies = Math.floor(uptimeSec * 100);
+    const niceJiffies = Math.floor(uptimeSec * 2);
+    const systemJiffies = Math.floor(uptimeSec * 30);
+    const idleJiffies = Math.floor(uptimeSec * 800);
+    const iowaitJiffies = Math.floor(uptimeSec * 5);
+    const irqJiffies = Math.floor(uptimeSec * 1);
+    const softirqJiffies = Math.floor(uptimeSec * 2);
+    const stealJiffies = Math.floor(uptimeSec * 0);
+    const totalJiffies = userJiffies + niceJiffies + systemJiffies + idleJiffies + iowaitJiffies + irqJiffies + softirqJiffies + stealJiffies;
+    const cpuStats = `cpu  ${userJiffies} ${niceJiffies} ${systemJiffies} ${idleJiffies} ${iowaitJiffies} ${irqJiffies} ${softirqJiffies} ${stealJiffies} 0 0\n`;
+    const perCpuStats = Array.from({ length: cpuCount }, (_, i) => `cpu${i} ${Math.floor(userJiffies / cpuCount)} ${Math.floor(niceJiffies / cpuCount)} ${Math.floor(systemJiffies / cpuCount)} ${Math.floor(idleJiffies / cpuCount)} ${Math.floor(iowaitJiffies / cpuCount)} ${Math.floor(irqJiffies / cpuCount)} ${Math.floor(softirqJiffies / cpuCount)} ${Math.floor(stealJiffies / cpuCount)} 0 0`).join("\n");
+    write(vfs, "/proc/stat", `${cpuStats}${perCpuStats}\nintr ${Math.floor(totalJiffies * 2)} 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\nctxt ${Math.floor(totalJiffies * 50)}\nbtime ${Math.floor(shellStartTime / 1000)}\nprocesses ${numProcs + 10}\nprocs_running 1\nprocs_blocked 0\n`);
+    // /proc/vmstat — virtual memory stats
+    const pgpgin = Math.floor(totalJiffies * 0.5);
+    const pgpgout = Math.floor(totalJiffies * 0.3);
+    const pswpin = 0;
+    const pswpout = 0;
+    const pgalloc = Math.floor(totalJiffies * 2);
+    const pgfault = pgalloc + Math.floor(totalJiffies * 0.5);
+    const pgmajfault = Math.floor(totalJiffies * 0.01);
+    write(vfs, "/proc/vmstat", `nr_free_pages ${Math.floor(freeMemKb / 4)}\nnr_zone_inactive_anon 0\nnr_zone_active_anon 0\nnr_zone_inactive_file ${Math.floor(cachedKb / 4)}\nnr_zone_active_file ${Math.floor(buffersKb / 4)}\nnr_zone_unevictable 0\nnr_zone_write_pending 0\nnr_mlock 0\nnr_page_table_pages ${pageTablesKb}\nnr_kernel_stack ${Math.floor(totalMemKb * 0.0005)}\nnr_bounce 0\nnr_zspages 0\nnr_free_cma 0\nnuma_hit ${Math.floor(totalJiffies * 3)}\nnuma_miss 0\nnuma_foreign 0\nnuma_interleave 0\nnuma_local ${Math.floor(totalJiffies * 3)}\nnuma_other 0\nnr_inactive_anon 0\nnr_active_anon 0\nnr_inactive_file ${Math.floor(cachedKb / 4)}\nnr_active_file ${Math.floor(buffersKb / 4)}\nnr_unevictable 0\nnr_slab_reclaimable ${Math.floor(slabKb * 0.6)}\nnr_slab_unreclaimable ${Math.floor(slabKb * 0.4)}\nnr_isolated_anon 0\nnr_isolated_file 0\nworkingset_nodes 0\nworkingset_refault 0\nworkingset_activate 0\nworkingset_restore 0\nworkingset_nodereclaim 0\nnr_anon_pages ${Math.floor(totalMemKb * 0.001)}\nnr_mapped ${Math.floor(cachedKb * 0.4)}\nnr_file_pages ${Math.floor(cachedKb * 0.8)}\nnr_dirty ${Math.floor(totalMemKb * 0.001)}\nnr_writeback 0\nnr_writeback_temp 0\nnr_shmem ${Math.floor(totalMemKb * 0.005)}\nnr_shmem_hugepages 0\nnr_shmem_pmdmapped 0\nnr_file_hugepages 0\nnr_file_pmdmapped 0\nnr_anon_transparent_hugepages 0\nnr_vmscan_write 0\nnr_vmscan_immediate_reclaim 0\nnr_dirtied ${Math.floor(totalJiffies * 2)}\nnr_written ${Math.floor(totalJiffies * 2)}\nnr_throttled_written 0\nnr_kernel_misc_reclaimable 0\nnr_reclaim_pages 0\nnr_zone_active_anon 0\nnr_zone_active_file ${Math.floor(buffersKb / 4)}\npgpgin ${pgpgin}\npgpgout ${pgpgout}\npswpin ${pswpin}\npswpout ${pswpout}\npgalloc_dma 0\npgalloc_dma32 ${Math.floor(pgalloc * 0.3)}\npgalloc_normal ${Math.floor(pgalloc * 0.7)}\npgalloc_movable 0\npgfree ${pgalloc}\npgactivate ${Math.floor(totalJiffies * 0.5)}\npgdeactivate 0\npgfault ${pgfault}\npgmajfault ${pgmajfault}\npglazyfree 0\npgrefill 0\npgsteal_kswapd 0\npgsteal_direct 0\npgscan_kswapd 0\npgscan_direct 0\npgskip_dma 0\npgskip_dma32 0\npgskip_normal 0\npgskip_movable 0\npgmigrate_success 0\npgmigrate_fail 0\ncompact_migrate_scanned 0\ncompact_free_scanned 0\ncompact_isolated 0\ncompact_stall 0\ncompact_fail 0\ncompact_success 0\nhtlb_buddy_alloc_success 0\nhtlb_buddy_alloc_fail 0\nunevictable_pgs_culled 0\nunevictable_pgs_scanned 0\nunevictable_pgs_rescued 0\nunevictable_pgs_mlocked 0\nunevictable_pgs_munlocked 0\nunevictable_pgs_cleared 0\nunevictable_pgs_stranded 0\nswap_ra 0\nswap_ra_hit 0\nnr_hugepages 0\nnr_hugepages_bootmem 0\n\n`);
+    // /proc/pressure — PSI (Pressure Stall Information)
+    ensureDir(vfs, "/proc/pressure");
+    const someAvg10 = (Math.random() * 0.3).toFixed(2);
+    const someAvg60 = (Math.random() * 0.2 + 0.1).toFixed(2);
+    const someAvg300 = (Math.random() * 0.1 + 0.05).toFixed(2);
+    const someTotal = Math.floor(totalJiffies * 10);
+    write(vfs, "/proc/pressure/cpu", `some avg10=${someAvg10} avg60=${someAvg60} avg300=${someAvg300} total=${someTotal}\n`);
+    write(vfs, "/proc/pressure/memory", `some avg10=${(Number(someAvg10) * 0.5).toFixed(2)} avg60=${(Number(someAvg60) * 0.3).toFixed(2)} avg300=${(Number(someAvg300) * 0.2).toFixed(2)} total=${Math.floor(someTotal * 0.3)}\n`);
+    write(vfs, "/proc/pressure/io", `some avg10=${(Number(someAvg10) * 0.7).toFixed(2)} avg60=${(Number(someAvg60) * 0.5).toFixed(2)} avg300=${(Number(someAvg300) * 0.3).toFixed(2)} total=${Math.floor(someTotal * 0.5)}\n`);
+    // /proc/modules
+    write(vfs, "/proc/modules", `${[
+        "virtio 163840 10 - Live 0x0000000000000000",
+        "virtio_ring 28672 10 virtio, Live 0x0000000000000000",
+        "virtio_blk 20480 10 - Live 0x0000000000000000",
+        "virtio_net 57344 10 - Live 0x0000000000000000",
+        "virtio_console 28672 10 - Live 0x0000000000000000",
+        "virtio_pci 24576 10 - Live 0x0000000000000000",
+        "virtio_pci_legacy_dev 12288 1 virtio_pci, Live 0x0000000000000000",
+        "virtio_pci_modern_dev 16384 1 virtio_pci, Live 0x0000000000000000",
+        "ext4 847872 10 - Live 0x0000000000000000",
+        "jbd2 131072 1 ext4, Live 0x0000000000000000",
+        "mbcache 16384 1 ext4, Live 0x0000000000000000",
+        "fuse 172032 10 - Live 0x0000000000000000",
+        "overlay 131072 10 - Live 0x0000000000000000",
+        "nf_tables 188416 10 - Live 0x0000000000000000",
+        "tun 49152 10 - Live 0x0000000000000000",
+        "bridge 286720 10 - Live 0x0000000000000000",
+        "dm_mod 155648 10 - Live 0x0000000000000000",
+        "crc32c_intel 24576 10 - Live 0x0000000000000000",
+    ].join("\n")}\n`);
     // /proc/cmdline — Firecracker boot args
     write(vfs, "/proc/cmdline", `console=ttyS0 reboot=k panic=1 nomodule random.trust_cpu=1 ipv6.disable=1 swiotlb=noforce rdinit=/process_api init_on_free=1 -- --firecracker-init --addr 0.0.0.0:2024 --max-ws-buffer-size 32768 --block-local-connections\n`);
     // /proc/filesystems — matching real container
@@ -651,26 +704,69 @@ export function refreshProc(vfs, props, hostname, shellStartTime, sessions = [])
     write(vfs, "/proc/mounts", mountsContent);
     ensureDir(vfs, "/proc/self");
     write(vfs, "/proc/self/mounts", mountsContent);
-    // /proc/net
+    // /proc/net — dynamic when network manager is available
     ensureDir(vfs, "/proc/net");
-    write(vfs, "/proc/net/dev", `${[
-        "Inter-|   Receive                                                |  Transmit",
-        " face |bytes    packets errs drop fifo frame compressed multicast|bytes    packets errs drop fifo colls carrier compressed",
-        "    lo:       0       0    0    0    0     0          0         0        0       0    0    0    0     0       0          0",
-        "  eth0:  128628    1230    0   19    0     0          0         0 52027469    2045    0    0    0     0       0          0",
-    ].join("\n")}\n`);
+    if (network) {
+        const ifaces = network.getInterfaces();
+        const routes = network.getRoutes();
+        const arpCache = network.getArpCache();
+        const ipToHex = (ip) => ip.split(".")
+            .reverse()
+            .map((n) => parseInt(n, 10).toString(16).padStart(2, "0"))
+            .join("")
+            .toUpperCase();
+        // /proc/net/dev
+        const devHeader = "Inter-|   Receive                                                |  Transmit\n face |bytes    packets errs drop fifo frame compressed multicast|bytes    packets errs drop fifo colls carrier compressed";
+        const devLines = ifaces.map((iface) => {
+            const name = iface.name.padStart(4);
+            if (iface.name === "lo") {
+                return `${name}:       0       0    0    0    0     0          0         0        0       0    0    0    0     0       0          0`;
+            }
+            const rxBytes = Math.floor(Math.random() * 200000);
+            const rxPkts = Math.floor(Math.random() * 2000);
+            const txBytes = Math.floor(Math.random() * 50000000);
+            const txPkts = Math.floor(Math.random() * 3000);
+            return `${name}: ${String(rxBytes).padStart(8)} ${String(rxPkts).padStart(7)}    0    0    0     0          0         0 ${String(txBytes).padStart(9)} ${String(txPkts).padStart(7)}    0    0    0     0       0          0`;
+        });
+        write(vfs, "/proc/net/dev", `${devHeader}\n${devLines.join("\n")}\n`);
+        // /proc/net/route
+        const routeLines = routes.map((r) => [
+            r.device,
+            ipToHex(r.destination === "default" ? "0.0.0.0" : r.destination),
+            ipToHex(r.gateway),
+            r.flags === "UG"
+                ? "0003"
+                : r.flags === "U"
+                    ? "0001"
+                    : "0000",
+            "0", "0", "100",
+            ipToHex(r.netmask),
+            "0", "0", "0",
+        ].join("\t"));
+        write(vfs, "/proc/net/route", `Iface\tDestination\tGateway\tFlags\tRefCnt\tUse\tMetric\tMask\t\tMTU\tWindow\tIRTT\n${routeLines.join("\n")}\n`);
+        // /proc/net/arp
+        const arpLines = arpCache.map((e) => `${e.ip.padEnd(15)} 0x1         0x2         ${e.mac.padEnd(17)}     *        ${e.device}`);
+        write(vfs, "/proc/net/arp", `IP address       HW type     Flags       HW address            Mask     Device\n${arpLines.join("\n")}\n`);
+    }
+    else {
+        write(vfs, "/proc/net/dev", "Inter-|   Receive                                                |  Transmit\n face |bytes    packets errs drop fifo frame compressed multicast|bytes    packets errs drop fifo colls carrier compressed\n    lo:       0       0    0    0    0     0          0         0        0       0    0    0    0     0       0          0\n  eth0:  128628    1230    0   19    0     0          0         0 52027469    2045    0    0    0     0       0          0\n");
+        write(vfs, "/proc/net/route", "Iface\tDestination\tGateway\tFlags\tRefCnt\tUse\tMetric\tMask\t\tMTU\tWindow\tIRTT\neth0\t00000000\t0101A8C0\t0003\t0\t0\t100\t00000000\t0\t0\t0\neth0\t0000A8C0\t00000000\t0001\t0\t0\t100\t00FFFFFF\t0\t0\t0\n");
+        write(vfs, "/proc/net/arp", "IP address       HW type     Flags       HW address            Mask     Device\n");
+    }
     write(vfs, "/proc/net/if_inet6", "");
-    write(vfs, "/proc/net/tcp", "  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode\n");
+    // /proc/net/tcp — fake listening sockets
+    const tcpListen = [
+        "   0: 00000000:0016 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 10000 1 0000000000000000 100 0 0 10 0",
+        "   1: 00000000:022D 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 10001 1 0000000000000000 100 0 0 10 0",
+        "   2: 00000000:0A8C 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 10002 1 0000000000000000 100 0 0 10 0",
+    ].join("\n");
+    write(vfs, "/proc/net/tcp", `  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode\n${tcpListen}\n`);
     write(vfs, "/proc/net/tcp6", "  sl  local_address                         remote_address                        st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode\n");
     write(vfs, "/proc/net/udp", "  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode\n");
-    write(vfs, "/proc/net/route", "Iface\tDestination\tGateway\tFlags\tRefCnt\tUse\tMetric\tMask\t\tMTU\tWindow\tIRTT\n" +
-        "eth0\t00000000\t0101A8C0\t0003\t0\t0\t100\t00000000\t0\t0\t0\n" +
-        "eth0\t0000A8C0\t00000000\t0001\t0\t0\t100\t00FFFFFF\t0\t0\t0\n");
-    write(vfs, "/proc/net/arp", "IP address       HW type     Flags       HW address            Mask     Device\n");
     write(vfs, "/proc/net/fib_trie", "Local:\n  +-- 0.0.0.0/0 3 0 5\n");
     write(vfs, "/proc/net/unix", "Num       RefCount Protocol Flags    Type St Inode Path\n" +
         "0000000000000000: 00000002 00000000 00010000 0001 01 10000 /run/dbus/system_bus_socket\n");
-    write(vfs, "/proc/net/sockstat", "sockets: used 8\nTCP: inuse 0 orphan 0 tw 0 alloc 0 mem 0\nUDP: inuse 0 mem 0\nUDPLITE: inuse 0\nRAW: inuse 0\nFRAG: inuse 0 memory 0\n");
+    write(vfs, "/proc/net/sockstat", "sockets: used 11\nTCP: inuse 3 orphan 0 tw 0 alloc 3 mem 1024\nUDP: inuse 0 mem 0\nUDPLITE: inuse 0\nRAW: inuse 0\nFRAG: inuse 0 memory 0\n");
     // /proc/partitions — virtio block devices
     write(vfs, "/proc/partitions", `${[
         "major minor  #blocks  name",
@@ -994,61 +1090,6 @@ function bootstrapUsr(vfs) {
         "hostname", "uname", "ps", "kill", "df", "du", "curl", "wget",
         "nano", "diff", "uniq", "xargs", "base64",
     ];
-    // From a real container
-    // const builtins = [
-    // 	// core
-    // 	"sh", "bash", "dash",
-    // 	"ls", "cat", "echo", "grep", "find", "sort",
-    // 	"head", "tail", "cut", "tr", "sed", "awk", "mawk", "gawk",
-    // 	"wc", "tee", "tar", "gzip", "gunzip", "bzip2", "xz",
-    // 	"touch", "mkdir", "rm", "mv", "cp", "ln", "pwd",
-    // 	"chmod", "chown", "chgrp", "env", "date", "sleep",
-    // 	"id", "whoami", "hostname", "uname", "ps", "kill",
-    // 	"df", "du", "dd", "stat", "file",
-    // 	// net
-    // 	"curl", "wget", "nc", "netcat", "ss", "ip",
-    // 	// editors
-    // 	"nano", "vi",
-    // 	// text
-    // 	"diff", "uniq", "xargs", "base64", "md5sum", "sha256sum",
-    // 	"strings", "hexdump", "od", "column", "fmt", "paste",
-    // 	"join", "comm", "split", "csplit", "fold", "expand",
-    // 	// archive
-    // 	"zip", "unzip",
-    // 	// process
-    // 	"top", "htop", "free", "uptime", "dmesg", "lsof",
-    // 	"strace", "ltrace", "pgrep", "pkill", "nohup", "nice",
-    // 	// fs
-    // 	"mount", "umount", "lsblk", "fdisk", "blkid", "e2fsck",
-    // 	// misc
-    // 	"bc", "expr", "seq", "yes", "true", "false", "test",
-    // 	"readlink", "realpath", "dirname", "basename", "mktemp",
-    // 	"install", "make",
-    // 	// dev tools
-    // 	"gcc", "gcc-13", "g++", "g++-13", "cpp", "as", "ld",
-    // 	"ar", "nm", "objdump", "objcopy", "strip", "size",
-    // 	"cc", "c++", "pkg-config",
-    // 	// package
-    // 	"apt", "apt-get", "apt-cache", "dpkg", "dpkg-query",
-    // 	"lsb_release", "add-apt-repository",
-    // 	// scripting
-    // 	"perl", "python3", "python3.12", "pipx",
-    // 	// node/npm
-    // 	"node", "npm", "npx",
-    // 	// java
-    // 	"java", "javac", "jar", "javadoc",
-    // 	// security
-    // 	"openssl", "gpg", "gpg2", "gpgv", "ssh", "ssh-keygen",
-    // 	"sudo", "su", "passwd", "adduser", "useradd",
-    // 	// misc system
-    // 	"systemctl", "journalctl", "loginctl",
-    // 	"timedatectl", "localectl",
-    // 	"lshw", "lscpu", "lsusb", "lspci",
-    // 	// text proc
-    // 	"jq", "xmllint", "pandoc",
-    // 	// multimedia
-    // 	"ffmpeg",
-    // ];
     for (const bin of builtins) {
         ensureFile(vfs, `/usr/bin/${bin}`, `#!/bin/sh\nexec builtin ${bin} "$@"\n`, 0o755);
     }
@@ -1547,7 +1588,7 @@ export function getStaticRootfsSnapshot(hostname, props) {
  * @param shellStartTime Unix ms of shell creation (for uptime).
  * @param sessions       Active sessions (for /proc/<pid> population).
  */
-export function bootstrapLinuxRootfs(vfs, users, hostname, props, shellStartTime, sessions = []) {
+export function bootstrapLinuxRootfs(vfs, users, hostname, props, shellStartTime, sessions = [], network) {
     const snapshot = getStaticRootfsSnapshot(hostname, props);
     const hasRestoredData = vfs.getMode() === "fs" && vfs.exists("/home");
     if (hasRestoredData) {
@@ -1557,7 +1598,7 @@ export function bootstrapLinuxRootfs(vfs, users, hostname, props, shellStartTime
         vfs.importRootTree(decodeVfs(snapshot));
     }
     bootstrapRoot(vfs);
-    refreshProc(vfs, props, hostname, shellStartTime, sessions);
+    refreshProc(vfs, props, hostname, shellStartTime, sessions, network);
     syncEtcPasswd(vfs, users);
 }
 // ─── optional live engine ─────────────────────────────────────────────────────
@@ -1572,13 +1613,13 @@ export function bootstrapLinuxRootfs(vfs, users, hostname, props, shellStartTime
  * setInterval(() => engine.tick(shell.listActiveSessions()), 5000);
  * ```
  */
-export function createLinuxRootfsEngine(vfs, props, hostname, startTime) {
+export function createLinuxRootfsEngine(vfs, props, hostname, startTime, network) {
     return {
         boot(users, sessions = []) {
-            bootstrapLinuxRootfs(vfs, users, hostname, props, startTime, sessions);
+            bootstrapLinuxRootfs(vfs, users, hostname, props, startTime, sessions, network);
         },
         tick(sessions = []) {
-            refreshProc(vfs, props, hostname, startTime, sessions);
+            refreshProc(vfs, props, hostname, startTime, sessions, network);
         },
     };
 }

package/dist/modules/neofetch.d.ts

@@ -1,4 +1,5 @@
 import type { ShellProperties } from "../VirtualShell";
+/** System info fields used to render neofetch output. */
 export interface NeofetchInfo {
     user: string;
     host: string;
@@ -15,4 +16,5 @@ export interface NeofetchInfo {
     memoryUsedMiB?: number;
     memoryTotalMiB?: number;
 }
+/** Builds the full neofetch ASCII art system-info string. */
 export declare function buildNeofetchOutput(info: NeofetchInfo): string;

package/dist/modules/neofetch.js

@@ -133,7 +133,7 @@ function countDpkgPackages() {
             const matches = data.match(/^Package:\s+/gm);
             return matches?.length ?? 0;
         }
-        catch { }
+        catch { /* dpkg status file may not exist */ }
     }
     return undefined;
 }
@@ -148,7 +148,7 @@ function countSnapPackages() {
             const count = entries.filter((entry) => entry.isDirectory()).length;
             return count;
         }
-        catch { }
+        catch { /* snap directory may not be readable */ }
     }
     return undefined;
 }
@@ -216,6 +216,7 @@ function resolveDefaults(info) {
         memoryTotalMiB: info.memoryTotalMiB ?? toMiB(totalMem),
     };
 }
+/** Builds the full neofetch ASCII art system-info string. */
 export function buildNeofetchOutput(info) {
     const fields = resolveDefaults(info);
     const uptime = formatUptime(fields.uptimeSeconds);

package/dist/modules/pacmanGame.d.ts

@@ -1,10 +1,12 @@
 import type { ShellStream } from "../types/streams";
 import type { TerminalSize } from "./shellRuntime";
+/** Configuration options for creating a PacmanGame instance. */
 export interface PacmanGameOptions {
     stream: ShellStream;
     terminalSize: TerminalSize;
     onExit: () => void;
 }
+/** Classic Pacman game that runs in the terminal with ANSI rendering. */
 export declare class PacmanGame {
     private stream;
     private onExit;

package/dist/modules/pacmanGame.js

@@ -92,6 +92,7 @@ const DR = [0, 1, 0, -1];
 const DC = [1, 0, -1, 0];
 const OPP = [2, 3, 0, 1];
 // ── PacmanGame ────────────────────────────────────────────────────────────────
+/** Classic Pacman game that runs in the terminal with ANSI rendering. */
 export class PacmanGame {
     stream;
     onExit;

package/dist/modules/shellInteractive.d.ts

@@ -1,5 +1,7 @@
 import { type ChildProcessWithoutNullStreams } from "node:child_process";
 import type { ShellStream } from "../types/streams";
 import { type TerminalSize } from "./shellRuntime";
+/** Spawns the nano editor as an interactive subprocess. */
 export declare function spawnNanoEditorProcess(tempPath: string, terminalSize: TerminalSize, stream: ShellStream): ChildProcessWithoutNullStreams;
+/** Spawns htop as an interactive subprocess, filtered to the given PIDs. */
 export declare function spawnHtopProcess(pidList: string, terminalSize: TerminalSize, stream: ShellStream): ChildProcessWithoutNullStreams;

package/dist/modules/shellInteractive.js

@@ -18,9 +18,11 @@ function spawnScriptProcess(command, terminalSize, stream) {
     });
     return proc;
 }
+/** Spawns the nano editor as an interactive subprocess. */
 export function spawnNanoEditorProcess(tempPath, terminalSize, stream) {
     return spawnScriptProcess(`nano -- ${shellQuote(tempPath)}`, terminalSize, stream);
 }
+/** Spawns htop as an interactive subprocess, filtered to the given PIDs. */
 export function spawnHtopProcess(pidList, terminalSize, stream) {
     return spawnScriptProcess(`htop -p ${shellQuote(pidList)}`, terminalSize, stream);
 }

package/dist/modules/shellRuntime.d.ts

@@ -1,10 +1,17 @@
+/** Terminal dimensions (columns × rows). */
 export interface TerminalSize {
     cols: number;
     rows: number;
 }
+/** Shell-escapes a string for safe use in a command line. */
 export declare function shellQuote(value: string): string;
+/** Converts line endings to CRLF for TTY output. */
 export declare function toTtyLines(text: string): string;
+/** Wraps a command to run with a specific terminal size via stty. */
 export declare function withTerminalSize(command: string, terminalSize: TerminalSize): string;
+/** Resolves a path relative to a base working directory. */
 export declare function resolvePath(base: string, inputPath: string): string;
+/** Recursively collects all child PIDs of a given parent process. */
 export declare function collectChildPids(parentPid: number): Promise<number[]>;
+/** Returns a comma-separated PID list visible in htop, or null if none. */
 export declare function getVisibleHtopPidList(rootPid?: number): Promise<string | null>;

package/dist/modules/shellRuntime.js

@@ -1,14 +1,17 @@
 import { readFile } from "node:fs/promises";
 import * as path from "node:path";
+/** Shell-escapes a string for safe use in a command line. */
 export function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+/** Converts line endings to CRLF for TTY output. */
 export function toTtyLines(text) {
     return text
         .replace(/\r\n/g, "\n")
         .replace(/\r/g, "\n")
         .replace(/\n/g, "\r\n");
 }
+/** Wraps a command to run with a specific terminal size via stty. */
 export function withTerminalSize(command, terminalSize) {
     const cols = Number.isFinite(terminalSize.cols) && terminalSize.cols > 0
         ? Math.floor(terminalSize.cols)
@@ -18,6 +21,7 @@ export function withTerminalSize(command, terminalSize) {
         : 24;
     return `stty cols ${cols} rows ${rows} 2>/dev/null; ${command}`;
 }
+/** Resolves a path relative to a base working directory. */
 export function resolvePath(base, inputPath) {
     if (!inputPath || inputPath.trim() === "" || inputPath === ".") {
         return base;
@@ -26,6 +30,7 @@ export function resolvePath(base, inputPath) {
         ? path.posix.normalize(inputPath)
         : path.posix.normalize(path.posix.join(base, inputPath));
 }
+/** Recursively collects all child PIDs of a given parent process. */
 export async function collectChildPids(parentPid) {
     try {
         const childrenRaw = await readFile(`/proc/${parentPid}/task/${parentPid}/children`, "utf8");
@@ -42,6 +47,7 @@ export async function collectChildPids(parentPid) {
         return [];
     }
 }
+/** Returns a comma-separated PID list visible in htop, or null if none. */
 export async function getVisibleHtopPidList(rootPid = process.pid) {
     const descendants = await collectChildPids(rootPid);
     const unique = Array.from(new Set(descendants)).sort((a, b) => a - b);

package/dist/modules/webTermRenderer.js

@@ -392,13 +392,6 @@ export class WebTermRenderer {
         return html;
     }
 }
-// const ANSI_NORMAL_TO_BRIGHT: Record<string, string> = {
-// 	"#000": "#555", "#c00": "#f55", "#0c0": "#5f5", "#cc0": "#ff5",
-// 	"#00c": "#55f", "#c0c": "#f5f", "#0cc": "#5ff", "#ccc": "#fff",
-// };
-// function boldBright(fg: string): string {
-// 	return ANSI_NORMAL_TO_BRIGHT[fg] ?? fg;
-// }
 function escHtml(ch) {
     if (ch === "&")
         return "&amp;";