typescript-virtual-container 1.4.2 → 1.4.4

package/.vscode/settings.json

@@ -14,5 +14,6 @@
         
         "LICENSE": true,
         "tsconfig.tsbuildinfo": true
-    }
+    },
+    "js/ts.tsdk.path": "node_modules/typescript/lib"
 }

package/README.md

@@ -24,6 +24,7 @@
   - [`VirtualSftpServer`](#virtualsftpserver)
   - [`VirtualShell`](#virtualshell)
   - [`VirtualFileSystem`](#virtualfilesystem)
+    - [Mount API](#mount-api)
   - [`VirtualUserManager`](#virtualusermanager)
   - [`VirtualPackageManager`](#virtualpackagemanager)
   - [Snapshot Diff Tooling](#snapshot-diff-tooling)
@@ -53,7 +54,7 @@
 | Mode | Entry point | Use case |
 |------|-------------|----------|
 | **SSH/SFTP server** | `VirtualSshServer` / `VirtualSftpServer` | Honeypots, remote testing, training environments |
-| **Web shell** | `builds/web.min.js` (browser bundle) | Embedded terminals, interactive tutorials, browser demos |
+| **Web shell** | `builds/web.min.js` / `builds/web-full-api.min.js` (ESM) | Embedded terminals, interactive tutorials, browser demos |
 | **Standalone CLI** | `builds/self-standalone.js` (single file) | Local shell, one-liner demos, no install required |
 
 All three modes share the same core: a pure in-memory VFS, a real shell interpreter, a virtual package manager, and a typed programmatic API.
@@ -111,24 +112,22 @@ await ssh.start();
 
 ### Web shell (browser)
 
-Three browser bundles are available — pick the one that fits your deployment:
+Two browser bundles are available:
 
-| Bundle | Format | Entry | Use case |
-|--------|--------|-------|----------|
-| `builds/web.min.js` | ESM | `createWebShell()` | Local dev, modern bundlers |
-| `builds/web-iife.min.js` | IIFE (`WebShellLib`) | `WebShellLib.createWebShell()` | Cloudflare, CDN, reverse proxies |
-| `builds/web-full-api.min.js` | ESM | `createVirtualShellShim()` | API surface close to `VirtualShell` |
+| Bundle | Format | Entry point | Use case |
+|--------|--------|-------------|----------|
+| `builds/web.min.js` | ESM | `createWebShell()` | Embedded terminals, modern bundlers |
+| `builds/web-full-api.min.js` | ESM | `createVirtualShellShim()` | Full `VirtualShell`-like API in the browser |
 
-All bundles persist the VFS in **IndexedDB** — state survives page reloads.
+Both bundles persist the VFS in **IndexedDB** — state survives page reloads.
 
 ```bash
-bun run web-build          # → builds/web.min.js + examples/web.min.js
-bun run web-build-iife     # → builds/web-iife.min.js
-bun run web-full-build     # → builds/web-full-api.min.js
-bun run build-all          # rebuild everything
+bun run web-build       # → builds/web.min.js + examples/web.min.js
+bun run web-full-build  # → builds/web-full-api.min.js
+bun run build-all       # rebuild everything
 ```
 
-**ESM (`web.min.js`)**
+**`web.min.js`** — lightweight shell with IndexedDB VFS:
 
 ```html
 <script type="module">
@@ -144,19 +143,7 @@ bun run build-all          # rebuild everything
 </script>
 ```
 
-**IIFE (`web-iife.min.js`)** — no `type="module"` needed, works through Cloudflare:
-
-```html
-<script src="./builds/web-iife.min.js"></script>
-<script>
-  const shell = WebShellLib.createWebShell("web-vm");
-  shell.ensureInitialized().then(() =>
-    shell.executeCommandLine("whoami").then(r => console.log(r.stdout))
-  );
-</script>
-```
-
-**Full API shim (`web-full-api.min.js`)** — mirrors the `VirtualShell` programmatic API:
+**`web-full-api.min.js`** — mirrors the `VirtualShell` programmatic API:
 
 ```html
 <script type="module">
@@ -165,8 +152,7 @@ bun run build-all          # rebuild everything
   const shell = createVirtualShellShim("web-vm");
   await shell.ensureInitialized();
   await shell.executeCommandLine("mkdir -p /app && echo hello > /app/file.txt");
-  const vfs = shell.getVfs();
-  console.log(vfs.readFile("/app/file.txt")); // hello
+  console.log(shell.getVfs().readFile("/app/file.txt")); // hello
 </script>
 ```
 
@@ -174,8 +160,7 @@ bun run build-all          # rebuild everything
 
 ```bash
 bun run example-serve
-# Open http://localhost:8787/index.html (ESM)
-# or   http://localhost:8787/index-cf.html (IIFE, Cloudflare-compatible)
+# Open http://localhost:8787/index.html
 ```
 
 ### Programmatic API
@@ -327,6 +312,9 @@ interface ShellProperties {
 | `writeFileAsUser(authUser, path, content)` | Write with quota enforcement. |
 | `refreshProcFs(): void` | Refresh all `/proc/*` files (uptime, meminfo, cpuinfo, per-pid). |
 | `refreshProcSessions(): void` | Lightweight refresh of `/proc/<pid>` and `/proc/self` only. |
+| `mount(vPath, hostPath, options?): void` | Mount a host directory into the VFS. See [Mount API](#mount-api). |
+| `unmount(vPath): void` | Remove a host directory mount. |
+| `getMounts()` | List all active mounts as `{ vPath, hostPath, readOnly }[]`. |
 | `syncPasswd(): void` | Sync `/etc/passwd`, `/etc/group`, `/etc/shadow` from user manager. |
 | `getVfs(): VirtualFileSystem \| null` | Access VFS instance. |
 | `getUsers(): VirtualUserManager \| null` | Access user manager. |
@@ -398,6 +386,40 @@ await vfs.flushMirror();   // save to disk
 
 **Events:** `file:write { path, size }`, `file:read { path, size }`, `dir:create { path, mode }`, `node:remove { path }`, `symlink:create { link, target }`, `snapshot:import`, `snapshot:restore { path }`, `mirror:flush { path? }`
 
+
+#### Mount API
+
+Mount a host directory inside the VM — all standard VFS operations (`readFile`, `writeFile`, `exists`, `stat`, `list`) are transparently delegated to the host filesystem.
+
+> **Node.js only.** In browser environments `mount()` is a silent no-op — the `vPath` remains an empty in-memory directory.
+
+```typescript
+// Read-only mount (default) — shell commands can read host files
+shell.mount("/workspace", "./my-project");
+
+// Read-write mount — shell commands can also write back to the host
+shell.mount("/data", "./data", { readOnly: false });
+
+// Unmount — delegation removed, vPath stays as an empty VFS directory
+shell.unmount("/workspace");
+
+// Introspect
+shell.getMounts();
+// → [{ vPath: "/workspace", hostPath: "/abs/path/my-project", readOnly: true }]
+```
+
+Direct VFS usage:
+
+```typescript
+shell.vfs.mount("/workspace", "./my-project");
+shell.vfs.unmount("/workspace");
+shell.vfs.getMounts();
+```
+
+**Events:** `mount { vPath, hostPath, readOnly }`, `unmount { vPath }`
+
+**Snapshot behaviour:** mounted files are **not** included in `toSnapshot()` — only the in-memory VFS tree is serialised. The mount configuration itself is also not persisted; restore it after each `fromSnapshot()` or `restoreMirror()`.
+
 #### VFSB Binary Format
 
 In `"fs"` mode, state is persisted as a compact binary file (`vfs-snapshot.vfsb`).
@@ -654,6 +676,17 @@ interface VirtualActiveSession {
   remoteAddress: string;
   startedAt: string; // ISO-8601
 }
+
+/** Returned by adduser, passwd, deluser — triggers interactive password prompt in the terminal. */
+interface PasswordChallenge {
+  preamble?: string;        // Lines printed before the first prompt
+  prompt: string;           // e.g. "New password: "
+  confirmPrompt?: string;   // Second prompt for confirmation
+  confirmText?: string;     // Destructive confirmation prompt (y/N)
+  action: "adduser" | "passwd" | "deluser" | "su";
+  targetUsername: string;
+  newUsername?: string;     // adduser only
+}
 ```
 
 ---
@@ -932,7 +965,7 @@ echo "Welcome back, root!"
 <details>
 <summary><strong>Built-in Commands (91)</strong></summary>
 
-Type `help` in the shell for a grouped, colorized listing. Type `help <command>` for detailed usage.
+Type `help` in the shell for a grouped, colorized listing. Type `help <command>` for detailed usage. Type `man <command>` for full manual pages — all 91 commands are documented.
 
 ### Navigation
 
@@ -1198,27 +1231,145 @@ On every `VirtualShell` init, a realistic Linux hierarchy is bootstrapped idempo
 
 ```
 /
-├── bin -> /usr/bin          (symlink, Debian-style)
-├── dev/                     null, zero, random, urandom, pts/, shm/
+├── bin -> usr/bin             (symlink, Debian-style)
+├── sbin -> usr/sbin           (symlink, Debian-style)
+├── lib/                       (ELF stub)
+├── lib/modules/
+├── lib/x86_64-linux-gnu/
+├── lib64 -> usr/lib64         (symlink, Debian-style)
+├── initrd.img -> boot/initrd.img-<kernel>
+├── initrd.img.old -> boot/initrd.img-<prev>
+├── vmlinuz -> boot/vmlinuz-<kernel>
+├── vmlinuz.old -> boot/vmlinuz-<prev>
+├── lost+found/                (mode 0o700, ext4 fsck dir)
+│
+├── boot/
+│   ├── grub/
+│   │   └── grub.cfg           virtual bootloader config
+│   ├── vmlinuz-<kernel>       kernel stub
+│   ├── initrd.img-<kernel>    initrd stub
+│   ├── System.map-<kernel>
+│   └── config-<kernel>
+│
+├── dev/
+│   ├── null / zero / full     (0o666)
+│   ├── random / urandom       (0o444)
+│   ├── mem                    (0o640)
+│   ├── console / tty / tty0 / tty1 / ttyS0
+│   ├── sda / sda1 / sda2      block device stubs
+│   ├── loop0-loop7 + loop-control
+│   ├── stdin / stdout / stderr
+│   ├── pts/
+│   └── shm/
+│
 ├── etc/
-│   ├── group                synced from VirtualUserManager
+│   ├── apt/sources.list + sources.list.d/
+│   ├── cron.d/
+│   ├── init.d/
+│   ├── ld.so.conf + ld.so.conf.d/x86_64-linux-gnu.conf
+│   ├── network/interfaces     lo + eth0 (DHCP)
+│   ├── pam.d/                 common-auth|account|password|session + sshd
+│   ├── security/limits.conf + access.conf
+│   ├── sudoers (0o440) + sudoers.d/
+│   ├── systemd/system/
+│   ├── debian_version         12.0
+│   ├── fstab                  UUID stubs + tmpfs entries
+│   ├── group                  synced from VirtualUserManager
+│   ├── hostname
+│   ├── hosts                  127.0.0.1 + ::1 + VM hostname
+│   ├── issue                  login banner
+│   ├── locale.conf            LANG=en_US.UTF-8
+│   ├── localtime / timezone   UTC
+│   ├── login.defs             UID_MIN=1000 SHA512
+│   ├── motd                   uses ShellProperties
+│   ├── os-release             NAME="Fortune GNU/Linux" + ShellProperties
+│   ├── passwd                 synced from VirtualUserManager
+│   ├── profile                PATH + PS1 defaults
+│   ├── resolv.conf            1.1.1.1 + 8.8.8.8
+│   ├── shadow                 (mode 0o640, fake hashes)
+│   └── shells                 /bin/sh /bin/bash /usr/bin/bash
+│
+├── home/
+├── media/
+├── mnt/
+├── opt/
+├── snap/bin/
+├── srv/
+│
+├── proc/                      kernel simulation engine (refreshed on demand)
+│   ├── boot/log + version     kernel boot sequence
+│   ├── net/dev + if_inet6 + tcp + tcp6
+│   ├── sys/kernel/            hostname, ostype, osrelease, pid_max,
+│   │                          threads-max, randomize_va_space, dmesg_restrict
+│   ├── sys/net/ipv4/ip_forward
+│   ├── sys/vm/swappiness + overcommit_memory
+│   ├── self/mounts            mirrors most recent session's /proc/<pid>/
+│   ├── 1/                     init (cmdline, comm, stat, status, environ, fd/, fdinfo/)
+│   ├── <pid>/                 one subtree per active session (TTY-derived PID)
+│   ├── cmdline                kernel boot args
+│   ├── cpuinfo                real host CPU passthrough
+│   ├── filesystems
 │   ├── hostname
-│   ├── hosts                127.0.0.1 localhost + VM hostname
-│   ├── os-release           NAME="Fortune GNU/Linux" + ShellProperties
-│   ├── passwd               synced from VirtualUserManager
-│   ├── resolv.conf          1.1.1.1 + 8.8.8.8
-│   └── shadow               (mode 0o640)
-├── proc/
-│   ├── 1/                   init process (cmdline, status, comm, environ, fd/)
-│   ├── <pid>/               one entry per active session (pts/* TTY)
-│   ├── self/                mirrors most recent session's /proc/<pid>/
-│   ├── cpuinfo              real host CPU info
-│   ├── meminfo              real host memory
-│   └── ...
-├── sys/devices/virtual/dmi/id/
-├── tmp/                     (mode 0o1777 sticky)
-├── usr/bin/                 stubs for all built-in commands
-└── var/lib/dpkg/status      managed by VirtualPackageManager
+│   ├── loadavg                computed dynamically
+│   ├── meminfo                real host memory (Total/Free/Available/Buffers/Cached/Swap)
+│   ├── mounts
+│   ├── partitions
+│   ├── swaps
+│   ├── uptime                 computed from shellStartTime
+│   └── version                Linux <kernel> (fortune@build)
+│
+├── root/                      (mode 0o700)
+│   ├── .bashrc                colored PS1, PATH, ll/la aliases
+│   └── .profile
+│
+├── run/                       (systemd tmpfs runtime)
+│   ├── lock/
+│   ├── systemd/
+│   ├── user/
+│   └── utmp
+│
+├── sys/                       sysfs graph — deterministic, seeded from hostname (fnv1a)
+│   ├── class/net/
+│   ├── devices/virtual/dmi/id/
+│   │   ├── bios_vendor / bios_version / bios_date
+│   │   ├── sys_vendor / product_name / product_family / product_version
+│   │   ├── product_uuid / product_serial
+│   │   ├── chassis_type / chassis_vendor / chassis_version
+│   │   ├── board_name
+│   │   └── modalias
+│   └── kernel/
+│       ├── hostname
+│       ├── osrelease
+│       └── ostype
+│
+├── tmp/                       (mode 0o1777, sticky)
+│
+├── usr/
+│   ├── bin/                   stubs for all built-in commands (exec builtin <name>)
+│   ├── sbin/
+│   ├── lib/ + lib64/
+│   ├── local/bin|lib|share/
+│   └── share/doc|man/man1/
+│
+└── var/
+    ├── cache/apt/archives/
+    ├── lib/
+    │   ├── apt/lists/
+    │   ├── misc/
+    │   └── dpkg/
+    │       ├── available
+    │       ├── info/
+    │       └── status          managed by VirtualPackageManager
+    ├── log/
+    │   ├── apt/history.log + term.log
+    │   ├── auth.log
+    │   ├── dpkg.log
+    │   ├── kern.log
+    │   └── syslog
+    ├── mail/
+    ├── run -> /run             (legacy symlink)
+    ├── spool/cron/
+    └── tmp/
 ```
 
 ```typescript
@@ -1440,13 +1591,17 @@ Open:
 - [x] Pure in-memory VFS · symlinks · binary snapshot format (VFSB, ~27% smaller than JSON+base64)
 - [x] Linux rootfs on boot — `/etc`, `/proc`, `/sys`, `/dev`, `/usr`, `/var`
 - [x] Virtual package manager — `apt`/`dpkg`, 25 packages, VFS file writes
-- [x] 91 built-in commands across 9 categories
-- [x] Real shell interpreter — `if`/`for`/`while`/`case`/functions, `$(cmd)`, `$((expr))`, `${#VAR}`, single-quote isolation
+- [x] 92 built-in commands across 9 categories (`seq` added)
+- [x] Real shell interpreter — `if`/`for`/`while`/`case`/functions, `$(cmd)`, `$((expr))`, `${#VAR}`, `{a,b,c}` brace expansion, `{1..N}` ranges, `2>/dev/null` stderr redirect, `2>&1`, `(( x++ ))`
 - [x] `curl`/`wget` as pure `fetch()` · VFS PATH resolution · `/sbin` root-only
 - [x] `/proc/self` and `/proc/<pid>` per-session entries
 - [x] Snapshot diff tooling — `diffSnapshots`, `formatDiff`, `assertDiff`
 - [x] `node`/`python3`/`npm`/`npx` — package-gated virtual REPL stubs
-- [x] Web shell bundle (`web.min.js`) — fully browser-native with IndexedDB VFS
-- [x] Self-standalone CLI (`self-standalone.js`) — single-file interactive shell, no install
+- [x] Web shell bundles (`web.min.js`, `web-full-api.min.js`) — fully browser-native with IndexedDB VFS
+- [x] Self-standalone CLI (`self-standalone.js`) — single-file interactive shell, per-user history, tab completion
+- [x] 120+ `man` pages — all built-in commands documented via `man <cmd>`
+- [x] Shared `tokenize.ts` — unified tokenizer for shell parser and runtime (eliminates duplication)
+- [x] `PasswordChallenge` type — generic interactive password flow for `adduser`, `passwd`, `deluser`
+- [x] `VirtualFileSystem.mount(vPath, hostPath, { readOnly })` — bind-mount host directories into the VM; read-only by default; browser-safe (silent no-op)
 
 </details>

package/benchmark-results.txt

@@ -1,40 +1,40 @@
 Benchmarking VirtualShell concurrency:
 
 Running 1 shells...
-  Initialized 1 shells in 89ms, RSS 85 MB
-  Executed shell commands in 9ms, RSS now 86 MB (+1 MB)
+  Initialized 1 shells in 55ms, RSS 96 MB
+  Executed shell commands in 5ms, RSS now 97 MB (+0 MB)
 
 Running 2 shells...
-  Initialized 2 shells in 19ms, RSS 89 MB
-  Executed shell commands in 1ms, RSS now 89 MB (+0 MB)
+  Initialized 2 shells in 7ms, RSS 99 MB
+  Executed shell commands in 1ms, RSS now 99 MB (+0 MB)
 
 Running 5 shells...
-  Initialized 5 shells in 21ms, RSS 93 MB
-  Executed shell commands in 1ms, RSS now 93 MB (+0 MB)
+  Initialized 5 shells in 18ms, RSS 108 MB
+  Executed shell commands in 1ms, RSS now 109 MB (+1 MB)
 
 Running 10 shells...
-  Initialized 10 shells in 40ms, RSS 102 MB
-  Executed shell commands in 6ms, RSS now 103 MB (+1 MB)
+  Initialized 10 shells in 33ms, RSS 122 MB
+  Executed shell commands in 2ms, RSS now 122 MB (+0 MB)
 
 Running 20 shells...
-  Initialized 20 shells in 72ms, RSS 116 MB
-  Executed shell commands in 4ms, RSS now 117 MB (+1 MB)
+  Initialized 20 shells in 64ms, RSS 147 MB
+  Executed shell commands in 4ms, RSS now 148 MB (+1 MB)
 
 Running 50 shells...
-  Initialized 50 shells in 140ms, RSS 142 MB
-  Executed shell commands in 8ms, RSS now 142 MB (+0 MB)
+  Initialized 50 shells in 127ms, RSS 157 MB
+  Executed shell commands in 5ms, RSS now 158 MB (+0 MB)
 
 Running 100 shells...
-  Initialized 100 shells in 315ms, RSS 160 MB
-  Executed shell commands in 18ms, RSS now 160 MB (+0 MB)
+  Initialized 100 shells in 256ms, RSS 185 MB
+  Executed shell commands in 9ms, RSS now 186 MB (+0 MB)
 
 Summary:
 
 count   init_ms cmd_ms  init_rss        final_rss       delta_rss
-1       89      9       85 MB           86 MB           1 MB
-2       19      1       89 MB           89 MB           0 MB
-5       21      1       93 MB           93 MB           0 MB
-10      40      6       102 MB          103 MB          1 MB
-20      72      4       116 MB          117 MB          1 MB
-50      140     8       142 MB          142 MB          0 MB
-100     315     18      160 MB          160 MB          0 MB
+1       55      5       96 MB           97 MB           0 MB
+2       7       1       99 MB           99 MB           0 MB
+5       18      1       108 MB          109 MB          1 MB
+10      33      2       122 MB          122 MB          0 MB
+20      64      4       147 MB          148 MB          1 MB
+50      127     5       157 MB          158 MB          0 MB
+100     256     9       185 MB          186 MB          0 MB